Adom Hydrogen (platform base)

@@ -1,52 +0,0 @@-----name: hd-editor-state-description: The Editor State Machine (ESM) — HOW to know the true state of the VS Code editor and the Claude Code conversations inside Hydrogen Desktop, and the HARD typing invariants. Use BEFORE typing into a Claude conversation, driving setup-step threads, diagnosing "state unknown", empty split panels, tab spam, prompts landing in the wrong conversation, or any Claude tab/webview confusion. Trigger words — editor state, /editor/state, claude tab state, conversation state, which tab is active, empty editor group, split panel, double-type, typed into two boxes, prompt in wrong conversation, census, safe to type, stray text, disk verified, msg_count wrong, workbench unknown.------# hd-editor-state — the Editor State Machine--ONE authoritative read: `GET /editor/state` on HD's control API. Everything below is what it-returns and the rules for acting on it. Full design: docs/EDITOR-STATE-MACHINE.md (hd repo).--## The layered truth (never blend layers)--| Layer | Question | Source | Trust |-|---|---|---|---|-| L0 `lifecycle` | starting / editor-up / ready | port probes (7380, :8821, CDP) | absolute |-| L1 `layout`+`conversations` | groups, widths, empty panels, tab census, focused tab | workbench DOM + tab bar | high (VS Code chrome is stable) |-| L2 `extension` | what commands can I invoke | the extension's contributed-command registry + fingerprint | absolute (it IS the API) |-| L3 `conversations_disk` | turns, first prompt, generating, delivered | the jsonl transcripts | absolute — works for DISPOSED background tabs |-| L4 `census` | compose boxes + submit buttons visible NOW | DOM probes across ALL contexts | only under the invariants below |--## The HARD invariants (John 2026-07-17 — non-negotiable)--1. **Never type unless `census.safe_to_type == true`** (exactly 1 visible input across ALL-   webview contexts — not just the focused one).-2. **Freshness oracle is the TITLE**: `title == 'Untitled'` = never submitted. NEVER use-   `msg_count` for freshness — it counts welcome-screen DOM nodes (reads 5 on a pristine tab).-3. **After a submit, run the stray-text audit**: `POST /editor/audit-prompt {prefix}` must-   return `contexts_containing: 0`. 1+ = the prompt is ALSO sitting in another conversation's-   box (double-type) — clear it, fail loudly, never ignore.-4. **Delivery is proven on DISK, not in the DOM**: the prompt must be the first user turn of-   exactly ONE `~/.claude/projects/*/*.jsonl`. 0 = not delivered; 2+ = double-send.-5. **Background tabs are unreadable** (VS Code disposes their webviews): `loaded:false`,-   null ctx/compose. To read one, activate it first (`/claude/tabs/activate {index:<ordinal>}`-   — by ORDINAL, never by label: every Claude tab is labeled 'Claude Code').-6. **`normalize_needed: true` → `POST /editor/normalize`** before showing the user anything-   (an empty split group steals 50% of their editor; populated 2-group layouts are preserved).-7. **Prefer registered commands over DOM clicks**: `extension.commands` lists them-   (claude-vscode.newConversation, .focus, .editor.open, ...). Run via the in-distro-   `:8821/command` API. Commands survive extension updates; selectors don't.-8. **Extension drift**: `extension.fingerprint` changes when Claude Code updates — re-verify-   your assumptions (anchors, commands) before trusting flows after a fingerprint change.--## Quick recipes--- Am I safe to type? `GET /editor/state` → `census.safe_to_type`.-- Did my prompt double-type? `POST /editor/audit-prompt {"prefix":"<first words>"}` → want 0 after submit.-- Which conversation is generating? `conversations_disk[*].generating` (disk truth, any tab).-- Fix a half-width Claude tab / dead empty panel? `POST /editor/normalize`.-- Bars: `layout.bars` reports activity / primary sidebar / secondary (auxiliary) bar / bottom-  panel visibility. A Claude conversation living in the SECONDARY bar is a second compose box-  (census=2). Close bars deterministically: `POST /editor/bars {"primary":"close","secondary":"close"}`-  (read -> toggle-on-mismatch -> verify; never a blind toggle).