@issuegraph/editor 0.4.0 → 0.10.0

package/dist/workspace/mount.js

@@ -46,17 +46,24 @@
  * document rather than on a window.
  */
 import { edgeIdentity } from '@issuegraph/core';
+import { nextDocument } from '@issuegraph/store';
 import { navigate, renderViewer, resolveTheme, } from '@issuegraph/viewer';
-import { keyIntent } from "../create/keys.js";
+import { CONTROL_ATTRIBUTES } from "../a11y/baseline.js";
+import { isChoosingKind } from "../create/draft.js";
+import { KIND_KEYS, keyIntent } from "../create/keys.js";
 import { pickerPlacement } from "../create/placement.js";
+import { firstPassIntent } from "../firstpass/keys.js";
+import { ANSWER_ATTRIBUTE, renderFirstPass } from "../firstpass/render.js";
+import { firstPassStylesheet } from "../firstpass/styles.js";
 import { STATE_ATTRIBUTE, overlayFor } from "../overlay/grammar.js";
 import { overlaysFor } from "../overlay/projected.js";
 import { renderPicker } from "../picker/render.js";
 import { pickerStylesheet } from "../picker/styles.js";
 import { scaleLadder } from "../scale/ladder.js";
 import { mountStylesheet } from "./chrome.js";
-import { INITIAL_HOST_STATE, KINDS, railRowAt, railSlackFor, railWindowTarget, reconcileHost, reduceHost, targetMatches, } from "./host.js";
-import { renderWorkspace } from "./render.js";
+import { INITIAL_HOST_STATE, editCarrier, railRowAt, railSlackFor, railWindowTarget, reconcileHost, reduceHost, targetMatches, } from "./host.js";
+import { conflictDiff } from "./recovery.js";
+import { renderWorkspace, } from "./render.js";
 import { selectedEdgeId, selectedKey } from "./selection.js";
 /** What the canvas zone draws: the editor's scale ladder, or the viewer's tree projection. */
 export const CANVAS_MODES = Object.freeze(['neighbourhood', 'tree']);
@@ -69,6 +76,40 @@ const DRAG_THRESHOLD = 6;
 const KEY_ATTRIBUTE = 'data-ig-key';
 const GROUP_ATTRIBUTE = 'data-ig-group';
 const COMMAND_ATTRIBUTE = 'data-ig-command';
+/**
+ * Which subject a command acts on, when one command names several.
+ *
+ * Named here because this file now READS it in two places rather than one —
+ * `controlAnswer` turns it into the dispatch's `target`, and the focus token
+ * below uses it to tell one `select-edge` from the next. A third bare literal for an
+ * attribute the renderer writes on every relationship row and every recovery
+ * button is how a typo becomes a control that silently stops matching.
+ */
+const TARGET_ATTRIBUTE = 'data-ig-target';
+/**
+ * Commands that name ONE control in two states.
+ *
+ * The isolated-issues chip redraws the SAME button with its command flipped
+ * (`scale/render.ts`), so a focus token comparing the raw command rejects the
+ * replacement and sends the reader to the rail — and that control, like the
+ * conflict disclosure, is one you press a second time to undo. It is this
+ * pull request's own defect wearing a different attribute value, which is
+ * why it is worth a table rather than a special case: the next toggle gets
+ * one line here instead of a new bug.
+ *
+ * A TABLE, NOT A PREFIX RULE. `open-` / `close-` looks like a pattern and is
+ * not one — `first-pass` and `first-pass-close` are two different controls in
+ * two different places, and a rule that folded them would restore focus onto
+ * the wrong one.
+ */
+const TOGGLE_IDENTITY = Object.freeze({
+    'open-isolated': 'isolated',
+    'close-isolated': 'isolated',
+});
+/** What a control is, rather than which of its states is showing. */
+function controlIdentity(control) {
+    return TOGGLE_IDENTITY[control] ?? control;
+}
 /**
  * An element, recognised by what it can do.
  *
@@ -82,6 +123,9 @@ function isElement(target) {
 function isFocusable(node) {
     return node !== null && node !== undefined && 'focus' in node;
 }
+/** The two refusals, allocated once: they carry no per-press data. */
+const REFUSED_INPUT = Object.freeze({ kind: 'refused', reason: 'input' });
+const REFUSED_INERT = Object.freeze({ kind: 'refused', reason: 'inert' });
 function isInput(node) {
     return node !== null && node !== undefined && node.tagName === 'INPUT';
 }
@@ -101,11 +145,26 @@ function withKey(scope, key) {
  * canvas renders the whole document and so drew a second header and a second
  * refresh control in the same workspace. One place strips it for both.
  */
-function withoutHost(document) {
+/**
+ * The host facts a SECONDARY view keeps: what is true, never what is drawn.
+ *
+ * The rail owns this workspace's one header, NOW row and freshness stamp, and
+ * carrying them onto a second view would draw them twice — that is why the
+ * facts are stripped here at all, and it stays true.
+ *
+ * THE CONDITION IS NOT ONE OF THEM. It is the host's account of WHY the panel
+ * is short, and the viewer uses it to refuse to invent a different account:
+ * without it, a canvas beside an explained rail falls back to "no issue in this
+ * document declares a relationship", which under a stated `error` is a claim
+ * about something else and contradicts the rail. It draws nothing on its own
+ * under `chrome: false`, so keeping it costs no chrome — it only stops a second
+ * view explaining the same emptiness a different, false way.
+ */
+function withoutChrome(document) {
     if (document.host === undefined)
         return document;
-    const { host: _host, ...rest } = document;
-    return rest;
+    const { host, ...rest } = document;
+    return host.condition === undefined ? rest : { ...rest, host: { condition: host.condition } };
 }
 /**
  * Mount the workspace into an element.
@@ -129,10 +188,95 @@ export function mountWorkspace(element, options) {
     let drawn = null;
     // A rail row to focus once the window has been re-cut around it.
     let pendingFocus = null;
+    // The keys currently holding a control they activated. See `onKeydown`'s first
+    // arm for why this is a fact about the PRESS and not a question asked of
+    // whatever holds focus by the time the repeats arrive.
+    //
+    // A SET RATHER THAN THE LATEST KEY. Two can be down at once — hold `Space` on
+    // one control and press `Enter` on another — and a scalar answers that by
+    // forgetting the first, so its repeats stop being recognised as its own and go
+    // wherever focus has since moved. That is not a case to guard; it is a case
+    // the representation should not be able to express, which is what this is.
+    const activating = new Set();
     let pressed = null;
     // Whether the last render drew the target search, so focus moves into it on
     // the render that OPENS it and not on every render while it stays open.
     let searchWasOpen = false;
+    // The phase the last render drew, so the overlay is entered once rather than
+    // on every redraw, and left exactly once.
+    let firstPassWas = 'closed';
+    // Where focus was when the overlay went up, so it can be given back when the
+    // overlay comes down. `mount.ts` already learned this lesson on the create
+    // flow: a surface removed with focus inside it leaves `activeElement` on the
+    // body, and the keydown listener is on the element — so the whole workspace
+    // goes keyboard-dead until the reader clicks something.
+    let focusBeforeFirstPass = null;
+    /** The scanner the live lifecycle belongs to, so a swap can end it. */
+    let firstPassSource = options.firstPass?.source ?? null;
+    /**
+     * Which write each applied candidate created.
+     *
+     * THE ONLY HANDLE THAT IDENTIFIES A WRITE, and it exists nowhere else: the
+     * `MutationId` is minted by `store.propose` and seen only here, while the
+     * create's own `kind`/`from`/`to` does NOT identify it — `candidates.ts` mints
+     * a distinct id per finding precisely so two detectors proposing the same pair
+     * stay two questions, and an older failed write can carry the same triple. An
+     * earlier revision matched structurally and could have discarded the wrong
+     * record. Cleared when the queue closes.
+     */
+    const appliedWrites = new Map();
+    /**
+     * The issue each unsettled write is about, answered once and then remembered.
+     *
+     * THE ANSWER GOES STALE, WHICH IS WHY IT IS KEPT RATHER THAN RE-ASKED. A
+     * refusal reaches the panel through the ledger, long after the act that
+     * caused it, and `editCarrier` reads the LANDED document — so between the two
+     * moments a sibling write can land and take the relationship away, leaving
+     * that call with nothing but the edge's identity. An identity records which
+     * two issues a relationship was between, and for a SYMMETRIC field it does not
+     * record which of them declared it: `edgeIdentity` sorts those endpoints, so
+     * the declaring end is not in the string at all. Re-asking therefore answered a
+     * different issue from the one the edit went out under, for exactly the pairs
+     * whose stored `from` sorted after their `to` — and `renderWorkspace` draws a
+     * refusal only on the panel it names, so it was drawn where the reader was
+     * not. Asked once, there is nothing for a second answer to disagree with.
+     *
+     * TWO WAYS IN, AND THE EARLIER ONE WINS. `reduceHost` decides the carrier as
+     * it emits the edit — before `store.propose` is even called, from the
+     * document as it stood when the reader acted — and `perform` records it under
+     * the identity the store mints. A write this mount did not emit (a host
+     * proposing on the same store) has no such moment, so it is answered the first
+     * time this render sees it in the ledger, which is the earliest moment there
+     * is. Neither is ever recomputed.
+     *
+     * ITS LIFETIME IS THE LEDGER'S, exactly. A record that lands is REMOVED from
+     * `snapshot.writes` — that is the store's own contract — and a refused or
+     * failed one stays until the reader discards it, which is precisely as long as
+     * it can still be drawn. So the map is pruned to the ledger's own keys on
+     * every render and needs no rule of its own. Clearing it beside
+     * `appliedWrites` was the alternative and is wrong in both directions: those
+     * clears are the first pass's lifecycle, not the write ledger's, so a queue
+     * that closes over a still-refused write would forget where to state it, and
+     * a write settling with no queue in sight would never be forgotten at all.
+     */
+    const writeCarriers = new Map();
+    /**
+     * The conflict whose `retry on latest` is the last one the reader pressed.
+     *
+     * WITHOUT IT, `hydrationError` IS THE WRONG FACT TO DRAW. The store sets that
+     * field from ANY failed read — a host's own `refresh()`, a background
+     * rehydrate, a failed first load — and attributes it to no mutation. Painted
+     * on every conflict card it says "could not read the newest version" on cards
+     * whose button nobody pressed, and on all of them at once when two conflicts
+     * stand. The card's claim is about a control the reader operated, so the
+     * shell records which control that was; the store cannot answer it.
+     *
+     * CLEARED WHEN THE READ SUCCEEDS, which the ledger cannot express: a resolve
+     * that reads fine and is then refused leaves an `invalid` record and no
+     * hydration error, and a stale flag here would keep explaining a failure that
+     * did not happen.
+     */
+    let refreshFailedFor = null;
     const railCount = () => current.railCount ?? MOUNT_RAIL_COUNT;
     const theme = () => resolveTheme(current.theme);
     const el = (tag, attributes = {}, children = []) => {
@@ -165,7 +309,10 @@ export function mountWorkspace(element, options) {
     const perform = (effect) => {
         switch (effect.kind) {
             case 'propose':
-                void store.propose(effect.proposal);
+                // THE CARRIER IS RECORDED, NOT RE-DERIVED. See `writeCarriers`: the
+                // reducer decided it from the document the reader acted on, and the
+                // `MutationId` that binds the two exists only here.
+                writeCarriers.set(store.propose(effect.proposal).mutationId, effect.carrier);
                 return;
             case 'retry': {
                 // A conflict retries against the LATEST document. The store owns that
@@ -173,6 +320,10 @@ export function mountWorkspace(element, options) {
                 // operation, so there is nothing for the mount to sequence.
                 const record = store.getSnapshot().writes.find((each) => each.mutationId === effect.mutationId);
                 if (record?.state === 'conflict') {
+                    // WHOSE READ THIS IS, recorded as the press happens. See
+                    // `refreshFailedFor`: after the fact there is nothing that ties the
+                    // store's hydration error to the edit it was read for.
+                    refreshFailedFor = effect.mutationId;
                     void store.retryOnLatest(effect.mutationId);
                 }
                 else {
@@ -186,30 +337,199 @@ export function mountWorkspace(element, options) {
             case 'dismiss-change':
                 store.dismissChange();
                 return;
+            case 'find-candidates': {
+                const option = current.firstPass;
+                // UNREACHABLE WITHOUT A BUNDLE, because the command is withheld at the
+                // listener — but written as a guard rather than an assertion, because
+                // `update()` can take the bundle away between the click and this call.
+                if (option === undefined) {
+                    // CLOSED, NOT FAILED. `failed` is a state this surface DRAWS, in the
+                    // host's own words — and with no bundle there are no words and no
+                    // overlay, so a failed phase here is an invisible one that blocks the
+                    // workspace's keyboard with no control to close it. The DOM guard
+                    // withholds this command, but `handle.dispatch` is public and reaches
+                    // the reducer directly, so the shell answers for that route too.
+                    dispatch({ kind: 'first-pass', command: { kind: 'close' } });
+                    return;
+                }
+                // THE OPEN IS REAL, SO THE DRAFT GOES NOW. Only the shell knows a scan
+                // will actually run — the reducer cannot tell this open from one about
+                // to be refused for want of a source, and clearing on both destroyed a
+                // draft for a queue that never appeared. Both routes into the queue, the
+                // attribute and `handle.dispatch`, arrive here.
+                dispatch({ kind: 'control', name: 'cancel' });
+                const { scan } = effect;
+                // STARTED FROM A CALLBACK, so a host whose `findCandidates` throws
+                // BEFORE returning its promise — reading its own state, building a
+                // request — reaches the same failed scan as one whose promise rejects.
+                // Called directly, that throw escapes the `.catch` entirely and unwinds
+                // through the click handler, leaving the phase `scanning` for good.
+                void Promise.resolve()
+                    .then(() => option.source.findCandidates())
+                    .then((candidates) => {
+                    dispatch({ kind: 'first-pass', command: { kind: 'candidates', scan, candidates } });
+                })
+                    .catch(() => {
+                    // THE REASON IS THE HOST'S AND IS NOT READ. A failed scan is a phase
+                    // this surface draws in the host's own words; adopting the rejection
+                    // value would be this package writing a sentence about someone
+                    // else's tracker.
+                    dispatch({ kind: 'first-pass', command: { kind: 'scan-failed', scan } });
+                });
+                return;
+            }
+            case 'first-pass-apply': {
+                // THIS CANDIDATE'S WRITE MAY ALREADY BE OUT THERE. `⌫` on an answer whose
+                // create is still `pending` steps the queue back but takes nothing away,
+                // because `discardMine` declines a pending record — so answering `Y`
+                // again would propose the SAME create a second time, and when the first
+                // lands the second turns `invalid` and shows the reader an error about a
+                // relationship that now exists. One consent, one write: the handle is
+                // kept and nothing new is proposed.
+                if (pendingWriteFor(effect.candidateId) !== undefined)
+                    return;
+                // AND THE RELATIONSHIP ITSELF MAY ALREADY BE THERE. The check above is
+                // per candidate, and a candidate is not a relationship: two findings
+                // with different ids may propose the same pair (`candidates.ts` keeps
+                // them apart on purpose), and a close-and-reopen starts a fresh queue
+                // over a document the earlier answer has since written to. Either way
+                // the store refuses the second create as a duplicate — correctly — and
+                // the reader is left an `invalid` record about a relationship that
+                // exists.
+                // LANDED OR ON ITS WAY, AND NOTHING ELSE. Asked of the two records that
+                // answer it directly: `landed` says the relationship is there, and a
+                // `pending-write` state says one is being created right now. An edge
+                // whose only write FAILED is precisely NOT there, so a second consent is
+                // free to try again.
+                // ASKED OF `landed`, NOT INFERRED FROM "no unsettled write". An earlier
+                // revision read a landed edge as one with an empty `writes` — which a
+                // landed edge carrying any settled overlay, a failed DELETE among them,
+                // is not. It then proposed a create for a relationship that was still
+                // there, and the store recorded the invalid duplicate.
+                const { proposal } = effect;
+                if (proposal.op === 'create') {
+                    const id = edgeIdentity(proposal.kind, proposal.from, proposal.to);
+                    const snapshot = store.getSnapshot();
+                    // ASKED OF THE STORE'S OWN RULE, not enumerated here. `nextDocument`
+                    // is the store's answer to "what would this edit produce if it landed
+                    // exactly as proposed", and it answers for every operation the store
+                    // has: a create adds the edge, a delete removes it, and a retype or a
+                    // flip replaces it with a different identity — which removes the one
+                    // the reader is being asked about just as surely as a delete does.
+                    // FOUR EARLIER VERSIONS RECONSTRUCTED THAT ANSWER and each was wrong
+                    // in a way only the store's internals reveal — a failed write still
+                    // projects, a landed edge can carry a settled overlay, a pending
+                    // delete is marked `pending-write` too, and a retype removes an edge
+                    // without being a delete. Every one of them suppressed a consent that
+                    // then wrote nothing, showed nothing, and was already decided. So the
+                    // enumeration is the store's, and a fifth operation is covered the day
+                    // the store learns about one. See autnmy/issuegraph#142.
+                    const landedNow = { issues: snapshot.issues, edges: snapshot.landed };
+                    const isThere = (document___) => document___.edges.some((edge) => edge.id === id);
+                    const already = isThere(landedNow);
+                    let coming = false;
+                    let going = false;
+                    for (const write of snapshot.writes) {
+                        if (write.state !== 'pending')
+                            continue;
+                        const after = isThere(nextDocument(landedNow, write.mutation));
+                        if (after && !already)
+                            coming = true;
+                        if (!after && already)
+                            going = true;
+                    }
+                    // THERE, AND NOT ON ITS WAY OUT. A landed edge under a pending edit
+                    // that would remove it is a relationship the reader may be about to
+                    // lose, so their consent goes to the store and is adjudicated there —
+                    // visible either way, which is the difference this guard exists to
+                    // preserve.
+                    if ((already && !going) || coming)
+                        return;
+                }
+                const handle = store.propose(effect.proposal);
+                appliedWrites.set(effect.candidateId, handle.mutationId);
+                // AND THE SAME RECORDING AS THE PLAIN ROUTE, because this is the same
+                // kind of event: a write going out with a panel it belongs to. The
+                // effect carries one now — it used to be built without going through
+                // the reducer's emit funnel at all, so a refused first-pass answer had
+                // no panel to be stated on.
+                writeCarriers.set(handle.mutationId, effect.carrier);
+                return;
+            }
+            case 'first-pass-withdraw': {
+                // THE STORE'S OWN UNDO, AND NOTHING ELSE. `discardMine` is the whole of
+                // what a host may take back: it declines a `pending` record itself, and
+                // a create that LANDED has no record left at all — so in practice the
+                // withdrawable set is `invalid`, `failed` and `conflict`, and the
+                // reader's `⌫` on anything else steps the queue back and leaves the
+                // write alone.
+                // THAT REFUSAL IS NOT RESTATED HERE. An earlier revision guarded on
+                // `state !== 'pending'` before calling, which is a second copy of a rule
+                // the store already enforces — and a mutation test proved it: removing
+                // the guard changed no observable behaviour, because `discardMine` was
+                // refusing anyway. What is NOT done here is the thing that would be
+                // wrong: proposing a compensating `delete`, which is the second
+                // retraction path `firstpass/queue.ts` refuses in terms — "free to
+                // disagree with [the store] about what undoing a create means."
+                // BY THE WRITE'S OWN IDENTITY. See `appliedWrites`: a structural match on
+                // the create's fields cannot tell this answer's write from another
+                // candidate proposing the same pair, or from an older failed one.
+                const mutationId = appliedWrites.get(effect.candidateId);
+                if (mutationId === undefined)
+                    return;
+                store.discardMine(mutationId);
+                // THE HANDLE OUTLIVES A REFUSED DISCARD. `discardMine` leaves a `pending`
+                // record exactly where it was, so forgetting the id here would lose the
+                // only thing that can find that write again — see the apply arm.
+                if (!recordedWriteFor(effect.candidateId)) {
+                    appliedWrites.delete(effect.candidateId);
+                }
+                return;
+            }
         }
     };
-    const dispatch = (command) => {
-        if (destroyed)
-            return;
-        const result = reduceHost(state, command, landed());
+    /**
+     * Take a reduction: keep its state, perform its effects, draw.
+     *
+     * SPLIT FROM `dispatch` SO ONE CALLER CAN LOOK BEFORE IT LEAPS. The keyboard
+     * arm has to know whether this reducer owns a command BEFORE it does anything
+     * at all, and `schedule()` is not nothing: it redraws, which replaces
+     * `surface.innerHTML` and with it the very button the reader is holding. A
+     * `<button>`'s `Space` activation lands on KEYUP, so destroying it first takes
+     * the host's own control off the keyboard just as surely as cancelling the
+     * press did. `reduceHost` is pure, so asking costs nothing and answers safely.
+     */
+    const applyResult = (result) => {
         state = result.state;
         for (const effect of result.effects)
             perform(effect);
         schedule();
     };
+    const dispatch = (command) => {
+        if (destroyed)
+            return;
+        applyResult(reduceHost(state, command, landed()));
+    };
     const zone = (name) => surface.querySelector(`.ig-zone[data-zone="${name}"]`);
     const pitch = () => theme().metrics['--ig-row-height'] + theme().metrics['--ig-space-tight'];
     const kindChooser = (source, target) => {
         const { words } = current;
         const chooser = el('div', { class: 'ig-chrome-chooser', role: 'group', 'aria-label': words.picker.heading });
         chooser.append(el('p', { class: 'ig-chrome-sentence' }, [`#${source} … ${target === null ? words.chooseKind : `#${target}`}`]));
+        // THE DIGITS ARE THE KEYBOARD'S OWN, READ OFF `KIND_KEYS`. They used to be
+        // computed here as `index + 1` over a `KINDS` alias in `host.ts` — a second
+        // construction of `create/keys.ts`'s table: the two agreed only because
+        // both walked `EDGE_FIELDS`, and nothing pinned them, so a chooser could
+        // have told the reader to press a key the key map resolved to a different
+        // kind. That alias is gone with its last caller, so this is now the only
+        // numbering in the package.
         const list = el('div', { class: 'ig-chrome-kinds' });
-        KINDS.forEach((kind, index) => {
-            list.append(button(`${String(index + 1)} ${words.picker.kinds[kind]}`, 'kind', {
-                'data-ig-value': kind,
-                'data-edge': kind,
+        for (const entry of KIND_KEYS) {
+            list.append(button(`${entry.key} ${words.picker.kinds[entry.edgeKind]}`, 'kind', {
+                'data-ig-value': entry.edgeKind,
+                'data-edge': entry.edgeKind,
             }));
-        });
+        }
         chooser.append(list, button(words.cancel, 'cancel', { class: 'ig-chrome-button ig-chrome-quiet' }));
         return chooser;
     };
@@ -232,7 +552,7 @@ export function mountWorkspace(element, options) {
             for (const match of matches) {
                 list.append(el('li', {}, [
                     button(`#${match.ref} ${match.title}`, 'target', {
-                        'data-ig-target': match.ref,
+                        [TARGET_ATTRIBUTE]: match.ref,
                         class: 'ig-chrome-button ig-chrome-match',
                     }),
                 ]));
@@ -247,24 +567,31 @@ export function mountWorkspace(element, options) {
         const { words } = current;
         const panel = el('div', { class: 'ig-chrome', 'data-chrome': 'inspector' });
         const edgeId = selectedEdgeId(state.selection);
-        const issue = selectedKey(state.selection);
         const { draft } = state;
+        // WHAT IS LEFT HERE IS WHAT NEEDS A DOM. `+ add`, the numbered kind list
+        // and §17b's flip are `renderWorkspace`'s now — the flip because the
+        // statement it reverses is the selected relationship's ROW, and a picker
+        // composed into this same panel drew a second statement and a second flip
+        // one element from the first. What is left below draws one control, not two.
+        // The older half of this note stands: `+ add` and the numbered kind list
+        // are `renderWorkspace`'s now — they are markup, and a host rendering the
+        // package without mounting had a panel it could only read. The retype
+        // picker and the target search stay: the first is another package's
+        // renderer composed as markup, and the second is a live input over
+        // `state.targetQuery` with a caret to preserve, which a markup-only
+        // renderer cannot be.
+        //
+        // THE CHAIN'S EXCLUSIVITY IS NOW SPLIT ACROSS TWO LAYERS, and that is why
+        // `renderWorkspace` is told about the draft and the drop: it re-states the
+        // same guards for the steps it draws, rather than the two surfaces each
+        // drawing whatever they can see.
         if (edgeId !== null) {
             const picker = el('div', { class: 'ig-chrome-picker' });
             // Package-rendered markup, escaped by the package.
             picker.innerHTML = renderPicker(document, edgeId, { words: words.picker, theme: theme() }).markup;
             panel.append(picker, button(words.deleteRelationship, 'delete', { class: 'ig-chrome-button ig-chrome-danger' }));
         }
-        else if (draft.source === null) {
-            if (issue !== null)
-                panel.append(button(words.addRelationship, 'add'));
-        }
-        else if (draft.kind === null) {
-            // Placed at the drop point when a canvas drag got here; inline otherwise.
-            if (state.drop === null)
-                panel.append(kindChooser(draft.source, draft.target));
-        }
-        else if (draft.target === null) {
+        else if (draft.source !== null && draft.kind !== null && draft.target === null) {
             panel.append(targetSearch(document, draft.source, draft.kind));
         }
         if (words.keys !== undefined)
@@ -288,6 +615,225 @@ export function mountWorkspace(element, options) {
         chooser.style.top = `${String(placed.y)}px`;
         return chooser;
     };
+    /**
+     * The first-pass surface, when one is up.
+     *
+     * A TAKEOVER RATHER THAN A FOURTH ZONE: `ZONES` is a closed union the
+     * workspace's grid is laid out from, and §17e's queue occupies the surface
+     * rather than a column. It is built and appended the way the floating chooser
+     * is — after `surface.innerHTML`, inside the workspace root, which is the box
+     * `chrome.ts` positions against and the element a host's theme is scoped to.
+     *
+     * ## It is a modal, and says so
+     *
+     * The rail and the canvas are still in the DOM underneath, still focusable and
+     * still in the accessibility tree. Without `aria-modal` and `inert` on the
+     * zones, one Tab lands the reader on a row they cannot see, where every key is
+     * inert because the queue owns the keyboard — and a screen reader reads the
+     * whole covered workspace as though nothing were over it.
+     *
+     * ## `aria-live`, because focus deliberately does not move
+     *
+     * Answering swaps the question in place while focus stays on this wrapper, so
+     * without a live region a reader answering sixty questions at speed hears
+     * nothing after the first. Focus stays here rather than moving onto a control
+     * because the first control is `apply` — the one irreversible answer — and a
+     * `Space` on a focus move nobody made is precisely the un-consented apply
+     * §17e forbids.
+     */
+    const firstPassOverlay = () => {
+        const option = current.firstPass;
+        const { phase } = state.firstPass;
+        if (option === undefined || phase.kind === 'closed')
+            return null;
+        const wrapper = el('div', {
+            class: 'ig-firstpass-overlay',
+            role: 'dialog',
+            'aria-modal': 'true',
+            // THE DIALOG IS NAMED, not just its child. `renderFirstPass` puts the
+            // host's label on the `<section>` it draws, which names that landmark and
+            // says nothing about its dialog ancestor — so assistive technology met an
+            // unnamed modal. The same word, on the element that is the modal.
+            'aria-label': option.words.label,
+            'aria-live': 'polite',
+            'data-ig-firstpass': phase.kind,
+            tabindex: '-1',
+        });
+        if (phase.kind === 'open') {
+            const panel = el('div', { class: 'ig-firstpass-panel' });
+            // Package-rendered markup, escaped by the package — the file's standing
+            // idiom, the same one the inspector's picker uses.
+            panel.innerHTML = renderFirstPass(phase.queue, { words: option.words, theme: theme() }).markup;
+            wrapper.append(panel);
+        }
+        else {
+            // THE HOST'S SENTENCE, PLACED. A scan that is out and a scan that failed
+            // are different facts and get different words; neither is worded here.
+            wrapper.append(el('p', { class: 'ig-firstpass-note' }, [
+                phase.kind === 'scanning' ? option.scanning : option.scanFailed,
+            ]));
+        }
+        wrapper.append(button(option.exit, 'first-pass-close', { class: 'ig-chrome-button ig-chrome-quiet' }));
+        return wrapper;
+    };
+    /**
+     * This candidate's write, if one is still IN FLIGHT.
+     *
+     * `pending` and nothing else, because the question it answers is "is this
+     * create already on its way?" — and a record that has FAILED is not on its way
+     * and never landed, so the relationship it stood for does not exist. Reading
+     * "a record exists" as "a write is out there" suppressed the reader's second
+     * consent after a failure: nothing was proposed, and the queue nevertheless
+     * marked the candidate decided, so a relationship they believed they had
+     * recorded was silently absent and never asked about again.
+     */
+    const pendingWriteFor = (candidateId) => {
+        const mutationId = appliedWrites.get(candidateId);
+        if (mutationId === undefined)
+            return undefined;
+        return store
+            .getSnapshot()
+            .writes.some((write) => write.mutationId === mutationId && write.state === 'pending')
+            ? mutationId
+            : undefined;
+    };
+    /** Whether the store still holds a record for this candidate's write, in any state. */
+    const recordedWriteFor = (candidateId) => {
+        const mutationId = appliedWrites.get(candidateId);
+        return (mutationId !== undefined &&
+            store.getSnapshot().writes.some((write) => write.mutationId === mutationId));
+    };
+    /**
+     * Which control inside the overlay owns focus, as a SELECTOR a redraw can find
+     * again — or `''` for the wrapper itself, or `null` when focus is elsewhere.
+     *
+     * A selector rather than the node, because the node does not survive the
+     * redraw: `surface.innerHTML` is reassigned and the overlay is rebuilt, so
+     * what has to be carried across is a way to name the control, not a reference
+     * to the one that was destroyed.
+     */
+    const overlayFocusToken = () => {
+        const active = doc.activeElement;
+        if (!isElement(active))
+            return null;
+        const overlay = active.closest('.ig-firstpass-overlay');
+        if (overlay === null || !surface.contains(overlay))
+            return null;
+        const answer = active.getAttribute(ANSWER_ATTRIBUTE);
+        if (answer !== null)
+            return `[${ANSWER_ATTRIBUTE}="${answer}"]`;
+        const command = active.getAttribute(COMMAND_ATTRIBUTE);
+        if (command !== null)
+            return `[${COMMAND_ATTRIBUTE}="${command}"]`;
+        return '';
+    };
+    /**
+     * The command control that owns focus, as facts a redraw can match again.
+     *
+     * `overlayFocusToken` above answers the same question for the first-pass
+     * overlay and only for it, so every command control OUTSIDE that overlay had
+     * no restore path at all: the arms below cover the overlay, an `input`'s
+     * caret, the target search on the render that opens it, and a pending rail
+     * jump — and then fall through to restoring by RAIL ROW, which needs a
+     * `[data-ig-key]` ancestor. An inspector button has none, so focus fell to
+     * the body. The keydown listener is on the mount's element, so that killed
+     * the whole keyboard loop until the reader clicked something else.
+     *
+     * FACTS, NOT A SELECTOR STRING. `overlayFocusToken` interpolates its value
+     * into `[attr="value"]`, which is safe only because `data-ig-answer` and the
+     * overlay's own commands come from closed sets. A general token carries
+     * {@link TARGET_ATTRIBUTE} — edge identities and issue keys straight out of
+     * a host's tracker — and a `"` in one would break the selector or match the
+     * wrong control. Comparing attribute values during a walk removes the class
+     * instead of escaping it.
+     *
+     * THE ZONE IS PART OF THE IDENTITY. One command name is published by many
+     * controls — every relationship row carries `select-edge` — and an issue is
+     * commonly drawn in the rail and again on the canvas, so a token without its
+     * zone would restore focus to a namesake in a zone the reader was not in.
+     */
+    const commandFocusToken = () => {
+        const active = doc.activeElement;
+        if (!isElement(active) || !surface.contains(active))
+            return null;
+        // ALL THREE CHANNELS, because the defect is not the command channel's. The
+        // audit header's toggle publishes on `data-ig-audit-filter` alone and the
+        // first pass's answers on `data-ig-answer` — `controlAnswer` resolves each
+        // in its own branch — so a token reading only `data-ig-command` left the audit
+        // toggle dropping focus to the body exactly as before. #149 says "any
+        // command control", and this is the list that makes that true.
+        for (const channel of CONTROL_ATTRIBUTES) {
+            const control = active.getAttribute(channel);
+            if (control === null)
+                continue;
+            const partial = {
+                channel,
+                zone: active.closest('.ig-zone')?.getAttribute('data-zone') ?? null,
+                control,
+                target: active.getAttribute(TARGET_ATTRIBUTE),
+                // THE SAME TWO SPELLINGS `controlAnswer` READS, and in its order: the picker
+                // publishes its kind as `data-ig-kind`, the mount's own chrome as
+                // `data-ig-value`.
+                value: active.getAttribute('data-ig-value') ?? active.getAttribute('data-ig-kind'),
+            };
+            // `findIndex` RATHER THAN `indexOf`, because `active` is narrowed to
+            // `Element` and the siblings are `HTMLElement`. Identity comparison is
+            // the same question either way, and the alternative — widening the list
+            // or asserting the narrower type — would be a cast this repository bans.
+            const ordinal = siblingsOf(partial).findIndex((node) => node === active);
+            // A CONTROL THAT DOES NOT FIND ITSELF is one this scope cannot name, so
+            // there is no token to carry. `indexOf` answering -1 would otherwise
+            // become an ordinal that matches nothing on the way back.
+            return ordinal < 0 ? null : { ...partial, ordinal };
+        }
+        return null;
+    };
+    /**
+     * Every control this token could name, in document order.
+     *
+     * THE ATTRIBUTE NAME IS A CONSTANT AND THE VALUES ARE COMPARED, so nothing a
+     * host's tracker can spell reaches a selector. See the token above.
+     *
+     * Shared by the token and the restore so the ordinal means the same thing on
+     * both sides: a list computed two ways is a list that can disagree with
+     * itself, and the ordinal would then point at a different control than the
+     * one it was counted against.
+     */
+    const siblingsOf = (token) => {
+        const scope = token.zone === null ? surface : (zone(token.zone) ?? surface);
+        return [...scope.querySelectorAll(`[${token.channel}]`)].filter((node) => {
+            const control = node.getAttribute(token.channel);
+            // BY IDENTITY, so a toggle that redraws itself with the other command is
+            // still the control the reader was on. See {@link TOGGLE_IDENTITY}.
+            if (control === null || controlIdentity(control) !== controlIdentity(token.control))
+                return false;
+            if (node.getAttribute(TARGET_ATTRIBUTE) !== token.target)
+                return false;
+            const value = node.getAttribute('data-ig-value') ?? node.getAttribute('data-ig-kind');
+            if (value !== token.value)
+                return false;
+            // A ZONELESS TOKEN MUST NOT MATCH A ZONED CONTROL. The floating chooser
+            // and the first-pass overlay are appended OUTSIDE the four zones, so
+            // their tokens carry `zone: null` and scope to the whole surface — and
+            // without this the chooser's `cancel` restored onto the inspector's.
+            // The two directions are asymmetric on purpose: a zoned token is already
+            // confined by `scope`.
+            return !(token.zone === null && node.closest('.ig-zone') !== null);
+        });
+    };
+    /** Give focus back to the control a {@link CommandFocus} names. `false` when it is gone. */
+    const refocusCommand = (token) => {
+        const siblings = siblingsOf(token);
+        // THE SAME ONE, THEN THE FIRST. A list that shrank under the reader — a
+        // match that stopped matching, a capsule that collapsed — has no nth
+        // member, and landing on the first sibling keeps the keyboard alive where
+        // returning `false` would drop to the rail.
+        const again = siblings[token.ordinal] ?? siblings[0];
+        if (again === undefined)
+            return false;
+        again.focus({ preventScroll: true });
+        return true;
+    };
     /** Focus the element carrying `key`, inside one zone when named, without scrolling the page. */
     const focusIn = (zoneName, key) => {
         const scope = zoneName === null ? surface : (zone(zoneName) ?? surface);
@@ -331,9 +877,11 @@ export function mountWorkspace(element, options) {
         if (zoneName !== 'canvas')
             return null;
         if (current.canvas === 'tree')
-            return renderViewer(withoutHost(drawn.viewer), { projection: 'tree', theme: theme() }).scene;
+            return renderViewer(withoutChrome(drawn.viewer), { projection: 'tree', theme: theme(), chrome: false }).scene;
         const ladder = scaleLadder(drawn.viewer, state.scale);
-        return ladder.tier === 'direct' ? renderViewer(ladder.canvas, { projection: 'graph', theme: theme() }).scene : null;
+        return ladder.tier === 'direct'
+            ? renderViewer(ladder.canvas, { projection: 'graph', theme: theme(), chrome: false }).scene
+            : null;
     };
     /** The row or node that owns keyboard focus, if focus is on one at all. */
     const focusedKey = () => {
@@ -346,8 +894,16 @@ export function mountWorkspace(element, options) {
             return;
         const snapshot = store.getSnapshot();
         const document_ = landed();
-        // A landed write can retire what the state names; agree with the document first.
-        state = reconcileHost(state, document_);
+        // WHAT THE STORE IS NOT SHOWING, computed before the reconcile rather than
+        // beside the edges below, because the reconcile is the first reader of it:
+        // an unsettled retype or flip hides the edge it replaces, and the landed
+        // document the reconcile is otherwise handed still carries it. Both halves
+        // of "the reader can no longer see this" reach `reconcileHost` together.
+        const shown = new Set(snapshot.projected.map((edge) => edge.id));
+        const hidden = new Set(snapshot.landed.map((edge) => edge.id).filter((id) => !shown.has(id)));
+        // A landed write can retire what the state names, and an unsettled one can
+        // hide it; agree with what is on show first.
+        state = reconcileHost(state, document_, hidden);
         const projected = current.project(snapshot);
         // WHAT TO DRAW IS THE STORE'S PROJECTION, by the store's own contract:
         // `projected` is "landed plus every unsettled edit, each carrying its
@@ -362,8 +918,6 @@ export function mountWorkspace(element, options) {
         // projection hides the old one until the write settles; the host's
         // document still carries it, so without this the old line and the new
         // dashed one were drawn together for the life of the write.
-        const shown = new Set(snapshot.projected.map((edge) => edge.id));
-        const hidden = new Set(snapshot.landed.map((edge) => edge.id).filter((id) => !shown.has(id)));
         const kept = projected.viewer.edges.filter((edge) => !hidden.has(edgeIdentity(edge.field, edge.from, edge.to)));
         const drawn_ = new Set(kept.map((edge) => edgeIdentity(edge.field, edge.from, edge.to)));
         const unsettled = snapshot.projected
@@ -379,6 +933,160 @@ export function mountWorkspace(element, options) {
         // through `store.select()` would draw a second halo the inspector does not
         // reflect, so it is stripped before the projection reaches a canvas.
         const writeStates = snapshot.projected.map((edge) => edge.states.includes('selected') ? { ...edge, states: edge.states.filter((state) => state !== 'selected') } : edge);
+        // THE WRITE LEDGER, TURNED INTO WHAT THE PANEL DRAWS — in ONE pass, in the
+        // ledger's own order.
+        //
+        // IT WAS TWO PASSES AND A CONCATENATION: one walk over the projection for
+        // the refusals it had an edge for, then one over the ledger for the ones it
+        // did not, appended after. Both halves were right and the JOIN was not.
+        // The renderer collapses repeated edges last-wins, so the array's order is
+        // the chronology — and appending every stranded record after every
+        // projected one is not the order the reader made them in. An older
+        // `unknown-edge` naming an edge a later refused create then projects
+        // reported the older reason. There is nothing to get wrong now: the ledger
+        // is walked once, and its order is the order.
+        //
+        // WHICH EDGE A REFUSAL MARKS IS THE PROJECTION'S OWN ANSWER.
+        // `ProjectedEdge.writes` is its record of which mutations it is speaking
+        // for, and `validity.ts` has already decided which edge each one marks — a
+        // create marks the edge it would have made, a retype the one it would have
+        // become. Rebuilding that here would be a second answer, free to disagree
+        // with the line the canvas draws the ghost on; asked of the projection, the
+        // record that produced one edge cannot also be counted against another,
+        // which is the double-draw this join used to be able to produce.
+        const markedBy = new Map(snapshot.projected.flatMap((edge) => edge.writes.map((write) => [write, edge.id])));
+        // WHETHER THE MARKED EDGE IS REAL. Three codes refuse an edit ABOUT a
+        // landed relationship — `duplicate-edge`, `unchanged-kind`,
+        // `symmetric-edge` — and the panel keeps the row for those rather than
+        // replacing it with a capsule; see `WorkspaceRefusal.phantom`.
+        //
+        // ASKED OF `landed`, NEVER OF THE CODE. A list of codes here would be a
+        // second copy of `validity.ts`'s decision about which edge each refusal
+        // marks, and it would already be wrong: `cardinality` reads like a fourth
+        // member of that set and marks a PHANTOM through both of its routes. This
+        // is the store's own answer to "what does the document actually carry".
+        const landedIds = new Set(snapshot.landed.map((edge) => edge.id));
+        const landedNow = { issues: snapshot.issues, edges: snapshot.landed };
+        // THE CARRIER MAP, BROUGHT LEVEL WITH THE LEDGER. See `writeCarriers` for
+        // why the answer is kept rather than re-asked, and why the ledger's own
+        // membership is the whole of its lifetime.
+        const ledger = new Set(snapshot.writes.map((record) => record.mutationId));
+        // CLEARED WHEN THE RECORD GOES, AND NOT BEFORE.
+        //
+        // Clearing it on `hydrationError === undefined` as well was the obvious
+        // rule and it was WRONG BY ONE RENDER: `retryOnLatest` reserves its record
+        // synchronously and publishes, so the very next render happens BEFORE the
+        // read has had a chance to fail — the error is still undefined, the flag
+        // was dropped, and when the failure did arrive there was nothing left to
+        // attribute it to. The card then stayed silent on exactly the failure this
+        // field exists to explain. Measured: the pin below went red.
+        //
+        // So the flag's lifetime is the RECORD's, and whether there is anything to
+        // draw is asked of the snapshot at draw time instead.
+        if (refreshFailedFor !== null && !ledger.has(refreshFailedFor)) {
+            refreshFailedFor = null;
+        }
+        for (const mutationId of writeCarriers.keys()) {
+            if (!ledger.has(mutationId))
+                writeCarriers.delete(mutationId);
+        }
+        for (const record of snapshot.writes) {
+            // FIRST SIGHT IS THE EARLIEST MOMENT THERE IS for a write this mount did
+            // not emit. Its own edits are already recorded by `perform`, from the
+            // document the reader acted on, so this fills in only what a host
+            // proposed on the same store — and never a second time.
+            if (!writeCarriers.has(record.mutationId)) {
+                writeCarriers.set(record.mutationId, editCarrier(landedNow, record.mutation));
+            }
+        }
+        const refusals = snapshot.writes.flatMap((record) => {
+            if (record.state !== 'invalid')
+                return [];
+            // WHOSE PANEL STATES IT, READ BACK RATHER THAN WORKED OUT. The panel used
+            // to derive this from the refused edge's endpoints, against a subject it
+            // had derived by an unrelated rule; then `editCarrier` was called here
+            // instead, which is one rule but still asked at the wrong TIME — a
+            // sibling write can remove the relationship between the act and the
+            // refusal, and what is left says which end declared it only for the
+            // directed fields — `edgeIdentity` sorts the symmetric ones. The answer
+            // was taken when the edit was made; this only looks it up. The two loops
+            // above run over this same `snapshot.writes`, so the key is always
+            // present, and `null` means the document held neither end — there is no
+            // panel a reader could be standing on to read it.
+            const carrier = writeCarriers.get(record.mutationId) ?? null;
+            if (carrier === null)
+                return [];
+            // THE PROJECTION'S EDGE, AND THE EDIT'S OWN AS THE FALLBACK. A refusal
+            // the projection has nothing to hang on is the whole `unknown-edge`
+            // class — a retype, flip or delete of an edge the document no longer
+            // carries produces `{ hidden: [], drawn: [], marked: [] }` — and the
+            // mutation names the edge it was about, so that id is what the capsule
+            // is keyed on.
+            const edgeId = markedBy.get(record.mutationId) ??
+                (record.mutation.op === 'create'
+                    ? edgeIdentity(record.mutation.kind, record.mutation.from, record.mutation.to)
+                    : record.mutation.edgeId);
+            return [{ edgeId, code: record.reason.code, carrier, phantom: !landedIds.has(edgeId) }];
+        });
+        // §17b's RECOVERY CARDS, BUILT FROM THE SAME LEDGER PASS AS THE REFUSALS.
+        // One walk of `snapshot.writes` keeps the chronology the panel relies on,
+        // and reuses the `edgeId` and `carrier` answers already worked out above
+        // rather than asking either question a second time.
+        //
+        // THE CARRIER IS CARRIED EVEN WHEN IT IS `null`, and that is the one place
+        // this deliberately parts company with the refusal derivation above, which
+        // drops those. A refusal dropped costs the reader a sentence. A RECOVERY
+        // dropped costs them the only retry and discard they have, on a write that
+        // is still theirs to resolve — so it travels, and the panel draws it in the
+        // unplaced region instead of nowhere.
+        // ANNOTATED RATHER THAN INFERRED. `flatMap` takes its element type from the
+        // first arm it sees, which here is the `failed` one — so an unannotated
+        // callback types the whole list as failures and rejects the conflict arm
+        // for want of a `reason`. The repair this repository bans is a cast; the
+        // repair it wants is saying what the function returns.
+        const recoveries = snapshot.writes.flatMap((record) => {
+            if (record.state !== 'failed' && record.state !== 'conflict')
+                return [];
+            const carrier = writeCarriers.get(record.mutationId) ?? null;
+            const edgeId = markedBy.get(record.mutationId) ??
+                (record.mutation.op === 'create'
+                    ? edgeIdentity(record.mutation.kind, record.mutation.from, record.mutation.to)
+                    : record.mutation.edgeId);
+            if (record.state === 'failed') {
+                return [{ kind: 'failed', mutationId: record.mutationId, edgeId, carrier, reason: record.reason }];
+            }
+            return [
+                {
+                    kind: 'conflict',
+                    mutationId: record.mutationId,
+                    edgeId,
+                    carrier,
+                    // AGAINST `landedNow`, WHICH CANNOT HOLD THE EDIT — that is the
+                    // point. `conflictDiff` reconstructs the reader's own side from the
+                    // mutation, so the card is guaranteed to name the relationship it is
+                    // about rather than depending on a document that by contract omits it.
+                    diff: conflictDiff(landedNow, record.upstream, record.mutation),
+                    // THE READ'S OWN FAILURE, WHICH IS NOT THE RECORD'S. A `retry on
+                    // latest` whose refresh fails restores this record verbatim and
+                    // dispatches nothing; the reason lands on the snapshot instead. Read
+                    // from there, the card can say why the button appeared to do nothing.
+                    // ONLY ON THE CARD WHOSE READ FAILED. Both halves are required: a
+                    // hydration error with no press behind it belongs to no card, and a
+                    // press whose read succeeded leaves no error to draw.
+                    refreshError: refreshFailedFor === record.mutationId ? (snapshot.hydrationError ?? null) : null,
+                },
+            ];
+        });
+        // ITS LIFETIME IS THE CONFLICT'S, NOT THE LEDGER'S, and the distinction is
+        // load-bearing: `retryOnLatest` reserves its record as `pending`
+        // synchronously, and a resolve whose re-check refuses leaves it `invalid`.
+        // In both the record is still in the ledger and its held document is gone,
+        // so "still in the ledger" would leave a difference region open over
+        // nothing. Asked of the state, it closes on every route out of `conflict`.
+        if (state.diffOpen !== null &&
+            !snapshot.writes.some((record) => record.mutationId === state.diffOpen && record.state === 'conflict')) {
+            state = { ...state, diffOpen: null };
+        }
         const result = renderWorkspace(viewer, {
             words: current.words,
             selection: state.selection,
@@ -393,8 +1101,23 @@ export function mountWorkspace(element, options) {
             // through `store.select()` would draw a second halo the inspector does
             // not reflect, so it is stripped before the projection reaches the canvas.
             projected: writeStates,
+            // THE SAME TWO VALUES THE CHROME BELOW READS. The create path's steps are
+            // split across the two surfaces now, so both have to be told which step is
+            // live — and a drop in flight suppresses the panel's list for the reason
+            // `WorkspaceOptions.drop` records: the floating chooser is already open
+            // at the pointer, and two choosers writing to one draft is what the
+            // shell's own `if (state.drop === null)` was preventing while it drew
+            // both of them.
+            draft: state.draft,
+            drop: state.drop,
+            refusals,
+            recoveries,
+            diffOpen: state.diffOpen,
         });
-        const sheet = [result.styles, pickerStylesheet, mountStylesheet].join('\n');
+        // THE FIRST PASS'S OWN SHEET, IMPORTED — not `renderFirstPass(...).styles`,
+        // which carries a second copy of the theme block written just above it. The
+        // picker is installed the same way and for the same reason.
+        const sheet = [result.styles, pickerStylesheet, firstPassStylesheet, mountStylesheet].join('\n');
         if (styles.textContent !== sheet)
             styles.textContent = sheet;
         // What the reader was doing survives the redraw: the rail's scroll offset,
@@ -410,6 +1133,19 @@ export function mountWorkspace(element, options) {
             ? { start: activeInput.selectionStart, end: activeInput.selectionEnd, direction: activeInput.selectionDirection }
             : null;
         const focused = focusedKey();
+        const overlayToken = overlayFocusToken();
+        // CAPTURED BEFORE THE REDRAW, like every other fact here: the node itself
+        // does not survive `surface.innerHTML`, so what crosses is a way to name
+        // the control rather than a reference to the one about to be destroyed.
+        const commandToken = commandFocusToken();
+        // WAS THE FOCUS OURS TO RESTORE? A reader whose focus is on the host's own
+        // chrome must not have it dragged into the workspace by a redraw the
+        // workspace happened to do — the search arm below already records paying
+        // for that once. The last-resort arm needs this because it fires on
+        // "nothing inside the surface holds focus", which is equally true of a
+        // redraw that destroyed the focused control and of a reader who simply is
+        // not here.
+        const heldFocus = isElement(active) && surface.contains(active);
         // The ZONE too: an issue is commonly drawn in the rail and on the canvas,
         // and restoring "the first element with this key" would move focus from
         // a canvas node into the rail on every redraw.
@@ -433,7 +1169,13 @@ export function mountWorkspace(element, options) {
                 // as data, the same `data-ig-state` the ladder's line carries, so a
                 // pending edge is not drawn as a settled one and a host styles or reads
                 // it the same way in both modes. The merge is the ladder's own.
-                canvas.innerHTML = renderViewer(withoutHost(viewer), { projection: 'tree', theme: resolved, selected: selectedKey(state.selection) }).markup;
+                canvas.innerHTML = renderViewer(withoutChrome(viewer), {
+                    projection: 'tree',
+                    theme: resolved,
+                    selected: selectedKey(state.selection),
+                    // The rail beside this canvas draws the panel's one header.
+                    chrome: false,
+                }).markup;
                 const states = new Map(overlaysFor(viewer.edges, writeStates, selectedEdgeId(state.selection)).map((edge) => [edge.id, overlayFor(edge).attribute]));
                 for (const badge of canvas.querySelectorAll(`[${GROUP_ATTRIBUTE}]`)) {
                     const attribute = states.get(badge.getAttribute(GROUP_ATTRIBUTE) ?? '');
@@ -449,6 +1191,15 @@ export function mountWorkspace(element, options) {
         const floating = floatingChooser();
         if (floating !== null)
             (surface.firstElementChild ?? surface).append(floating);
+        const overlay = firstPassOverlay();
+        if (overlay !== null) {
+            (surface.firstElementChild ?? surface).append(overlay);
+            // THE ZONES GO INERT UNDER IT. Set here rather than in the stylesheet
+            // because it is a behaviour — focus and hit-testing — not a look, and the
+            // markup is rebuilt every render so it cannot be left behind on close.
+            for (const covered of surface.querySelectorAll('.ig-zone'))
+                covered.setAttribute('inert', '');
+        }
         const rail = zone('rail');
         if (rail !== null)
             rail.scrollTop = scrollTop;
@@ -463,7 +1214,24 @@ export function mountWorkspace(element, options) {
                 return;
             focusIn(within, key);
         };
-        if (activeCommand !== null) {
+        if (overlay !== null) {
+            // FOCUS IS TAKEN BACK ON EVERY RENDER WHILE THE OVERLAY IS UP, not only on
+            // the one that opens it. Every answer dispatches, every dispatch redraws,
+            // and the redraw destroys the element focus was on — so a once-only rule
+            // gave the reader exactly one keystroke before `activeElement` fell to the
+            // body, `interaction` read `elsewhere` and every later key returned
+            // `none`. This is the same arm the target search already earns below.
+            if (firstPassWas === 'closed')
+                focusBeforeFirstPass = focused;
+            const again = overlayToken === null || overlayToken === ''
+                ? null
+                : overlay.querySelector(overlayToken);
+            // THE WRAPPER IS THE FALLBACK, INCLUDING ON THE RENDER THAT OPENS IT. The
+            // first control is `apply`, and landing focus there would put the one
+            // irreversible answer under the reader's next Space.
+            (again ?? overlay).focus({ preventScroll: true });
+        }
+        else if (activeCommand !== null) {
             const again = surface.querySelector(`input[${COMMAND_ATTRIBUTE}="${activeCommand}"]`);
             if (again !== null) {
                 again.focus();
@@ -516,32 +1284,267 @@ export function mountWorkspace(element, options) {
             }
         }
         else {
-            focusRow(focused);
+            // THE COMMAND CONTROL, WHERE THE RAIL CANNOT ANSWER. Strictly additive:
+            // it is reached only when `focusedKey()` found nothing, which is exactly
+            // the case `focusRow(null)` returned from without moving focus at all —
+            // so no control that has a keyed ancestor changes behaviour, and the
+            // rail's roving tab stop is untouched.
+            //
+            // The control can legitimately be gone: the edit it named landed, the
+            // relationship it belonged to was deleted, the recovery card it sat in
+            // resolved. `refocusCommand` says so rather than guessing, and the rail
+            // fallback below is then the same one that ran before.
+            const restored = focused === null && commandToken !== null && refocusCommand(commandToken);
+            if (!restored)
+                focusRow(focused);
+            // A LAST RESORT, because half of these controls RESOLVE THEMSELVES. A
+            // picker option closes the picker; `retry`, `discard`, `cancel` and
+            // `dismiss-change` each remove the card they sit in — so `refocusCommand`
+            // correctly answers "gone", `focusRow(null)` moves nothing, and the
+            // keyboard loop died anyway. That is the whole-loop half of the defect,
+            // and leaving it would have fixed the disclosure while every one-shot
+            // control kept failing the same way.
+            //
+            // The first drawn row, on the same reasoning the first-pass close arm
+            // gives for returning to §17a's entry: somewhere inside the surface that
+            // reaches the listener beats the body, and the rail is the zone the
+            // reader can navigate out of.
+            // THE TEST IS "INSIDE THE SURFACE", NOT "FOCUSABLE". `isFocusable` asks
+            // whether a node has `focus`, and `<body>` does — so it answers true for
+            // exactly the state this arm exists to repair. What the keydown listener
+            // needs is a focus owner it can receive an event from.
+            const adrift = !isElement(doc.activeElement) || !surface.contains(doc.activeElement);
+            if (!restored && focused === null && heldFocus && adrift) {
+                // THROUGH `focusIn`, NOT `focus()`. The rail renders one row at
+                // `tabindex="0"` and the rest at `-1`, and focusing a row directly
+                // leaves the STOP on whichever row had it — so Tab out and back
+                // returns to a different row than the one the reader is on.
+                // `focusIn` moves the stop with the focus, which is why every other
+                // row-focus path in this file goes through it.
+                const first = zone('rail')?.querySelector(`[${KEY_ATTRIBUTE}][tabindex]`);
+                const key = first?.getAttribute(KEY_ATTRIBUTE);
+                if (key !== null && key !== undefined)
+                    focusIn('rail', key);
+            }
+            // AND A RESORT THAT CANNOT ITSELF FAIL. The rail is not always there to
+            // fall back to: with the audit filter on and nothing flagged it draws no
+            // rows at all, while the inspector stays perfectly usable — so pressing a
+            // self-removing control there left focus on the body and killed the
+            // keyboard loop exactly as before. A fallback with a precondition is not
+            // a last resort.
+            //
+            // The surface itself always exists, and the keydown listener is on it, so
+            // focus landing here is by definition focus the loop can hear. `tabindex`
+            // is -1: this is somewhere to PUT focus, never a stop Tab should find.
+            if (heldFocus &&
+                (!isElement(doc.activeElement) || !surface.contains(doc.activeElement))) {
+                // A CONTROL, BEFORE THE SURFACE ITSELF. Most of these do not merely
+                // vanish — they REPLACE themselves with the step they opened, and `add`
+                // becoming the kind list is the ordinary case. Landing on the bare
+                // surface there put the press back in reach of the listener and no
+                // further: `interaction()` answers `canvas` only for a focused ROW, so
+                // on the surface every create binding — the kind digits, Escape —
+                // returns `none`. Reachable and inoperable is not the loop this is about.
+                //
+                // THE ZONE THE READER WAS IN FIRST, then anywhere. Which control
+                // replaced which is not knowable from here — the chooser is sometimes
+                // floating and sometimes the inspector's own list — so this asks the
+                // weaker, answerable question: what can the reader act on, nearest to
+                // where they were.
+                const zoneName = commandToken?.zone ?? null;
+                const near = zoneName === null ? null : zone(zoneName);
+                const opened = near?.querySelector(`[${COMMAND_ATTRIBUTE}]`) ??
+                    surface.querySelector(`[${COMMAND_ATTRIBUTE}]`);
+                if (opened !== null) {
+                    opened.focus({ preventScroll: true });
+                }
+                else {
+                    // AND THE SURFACE LAST, which is the resort that cannot itself fail.
+                    // It leaves the reader without a binding to press, but it keeps the
+                    // listener reachable so Tab moves them somewhere useful — strictly
+                    // better than the body, which reaches nothing at all.
+                    surface.setAttribute('tabindex', '-1');
+                    surface.focus({ preventScroll: true });
+                }
+            }
+        }
+        // THE KEYBOARD IS GIVEN BACK. The overlay is removed with focus inside it,
+        // so without this `activeElement` is the body — and the keydown listener is
+        // on the mount's element, so no press reaches it and the whole workspace is
+        // dead until the reader clicks. Restores what held focus when it opened.
+        if (overlay === null && firstPassWas !== 'closed') {
+            const back = focusBeforeFirstPass;
+            focusBeforeFirstPass = null;
+            appliedWrites.clear();
+            if (back !== null) {
+                focusIn(null, back);
+            }
+            else {
+                // NOTHING KEYED HELD FOCUS, WHICH IS THE ORDINARY CASE. §17a's entry is
+                // a button and carries no `data-ig-key`, so a reader who tabbed to it
+                // and pressed it leaves nothing for `focusIn` to find — and focus on
+                // the document body reaches no listener at all, because the keydown
+                // listener is on the mount's element. The entry is the control they
+                // came in through, so it is where they come back to.
+                // ONE RECORDED ANSWER, NOT TWO: an earlier revision also recorded WHICH
+                // control held focus, which a mutation test showed could never differ —
+                // the queue opens from this one control and no other.
+                // THE ENTRY CAN BE GONE BY NOW, THOUGH. Whether a backlog has a first
+                // pass to run is the host's answer and the host may change it: the
+                // sandbox draws the entry only while its detector finds candidates, so
+                // a completed queue whose writes land removes the very control this
+                // would return to. So the order of resort ends inside the ORDER, which
+                // is the one part of the workspace that is always there.
+                const back_ = surface.querySelector(`[${COMMAND_ATTRIBUTE}="first-pass"]`) ??
+                    surface.querySelector(`[${KEY_ATTRIBUTE}][tabindex]`);
+                back_?.focus({ preventScroll: true });
+            }
         }
+        firstPassWas = state.firstPass.phase.kind;
         searchWasOpen = search !== null;
     };
-    // --- listeners ---
-    const onClick = (event) => {
-        const target = isElement(event.target) ? event.target : null;
-        if (target === null)
+    /**
+     * Take the option's scanner, and end the lifecycle the old one was scanning for.
+     *
+     * Two failures, one rule. Removing the bundle stops the overlay being drawn
+     * while the phase stays open — and the phase is what hands every key to a
+     * queue that is no longer on screen, with no control left to close it.
+     * REPLACING the source is worse than it looks: the old scan's promise still
+     * resolves under the current generation, so the queue would be drawn in the
+     * new bundle's words and populated by the superseded scanner, and a `Y` there
+     * writes a relationship the configured source never proposed.
+     *
+     * RESET RATHER THAN CLOSE, and the difference is the decided set: a
+     * `CandidateId` is the HOST's and opaque, so one scanner's ids say nothing
+     * about another's — carried across, a collision silently drops the new
+     * detector's question, and a question nobody was asked is indistinguishable
+     * from one already answered.
+     *
+     * CALLED FROM `update()`, AT THE MOMENT THE OPTION CHANGES, not from the
+     * render that observes it later. Renders are coalesced on a microtask, so a
+     * host that calls `update()` and then dispatches an `open` in the same task
+     * had its brand-new lifecycle reset by a render still holding the previous
+     * scanner — and the new scan's answer then arrived on a closed phase and was
+     * dropped, so that supported sequence never opened a queue at all.
+     *
+     * Keyed on the SOURCE rather than the bundle, because a host that rebuilds an
+     * equivalent options object every render has changed nothing.
+     */
+    const adoptSource = () => {
+        const source = current.firstPass?.source ?? null;
+        if (source === firstPassSource)
             return;
+        firstPassSource = source;
+        if (state.firstPass.phase.kind !== 'closed' || state.firstPass.decided.length > 0) {
+            dispatch({ kind: 'first-pass', command: { kind: 'reset' } });
+        }
+        appliedWrites.clear();
+    };
+    // --- listeners ---
+    /**
+     * What a control press means, resolved once for both listeners.
+     *
+     * ONE CONSTRUCTION, TWO CALLERS. A pointer press and a key press perform the
+     * same act, and until `#158` only the pointer could perform it — so the
+     * keyboard's half was written as a second reading of the same attributes,
+     * free to disagree with this one about which act a press is. Extracting the
+     * answer is what makes "the click path and the key path do the same thing" a
+     * fact rather than a claim two code paths happen to agree on today.
+     *
+     * WHY A REFUSAL IS A STATE AND NOT A `null`. The two callers want opposite
+     * things from a control that declines, so collapsing the two would be wrong
+     * for one of them whichever way it collapsed:
+     *
+     * - `onClick` must STOP on a refusal. Fall through and a press on an inert
+     *   `First pass →` reaches the identity branch below and selects whatever row
+     *   or group happens to sit under it — an act the reader never asked for.
+     * - `onKeydown` must hand an `input` refusal BACK to the platform and hold an
+     *   `inert` one. Hence the reason travels with the refusal: see the arm's own
+     *   comment for the space character that is lost when it does not.
+     *
+     * The alternative considered and rejected: `HostCommand | null` plus an
+     * `isControl(target)` predicate for the callers to gate on. The predicate has
+     * to re-walk these same three `closest` calls, which is a second construction
+     * of the very thing this function exists to make singular.
+     *
+     * THREE `closest` WALKS RATHER THAN ONE COMBINED SELECTOR, on purpose. A
+     * single `closest('[a],[b],[c]')` answers with the NEAREST of the three,
+     * which is not the same question: these channels are asked in a fixed
+     * priority — a command wins over an answer, an answer over the audit filter —
+     * and where two nest, the combined selector would answer with the inner one
+     * whatever the priority says. The saving is two ancestor walks on a press,
+     * which is a human keystroke rather than a loop, and the risk is changing
+     * which act a press performs.
+     */
+    const controlAnswer = (target) => {
         const control = target.closest(`[${COMMAND_ATTRIBUTE}]`);
         if (control !== null && surface.contains(control)) {
             const name = control.getAttribute(COMMAND_ATTRIBUTE) ?? '';
             if (isInput(control))
-                return; // the `input` listener owns these
-            dispatch({
-                kind: 'control',
-                name,
-                target: control.getAttribute('data-ig-target') ?? undefined,
-                // The picker publishes its kind as `data-ig-kind`; the mount's chrome
-                // publishes `data-ig-value`. One command channel, two spellings.
-                value: control.getAttribute('data-ig-value') ?? control.getAttribute('data-ig-kind') ?? undefined,
-            });
-            return;
+                return REFUSED_INPUT; // the `input` listener owns these
+            // THE ENTRY IS INERT WITHOUT A BUNDLE, and it is withheld HERE rather
+            // than in the reducer. `renderWorkspace` draws §17a's `First pass →`
+            // inside this surface, so a host cannot intercept it from outside; and
+            // the reducer's `first-pass` arm would move to `scanning` with no source
+            // to call and no way back. See `MountWorkspaceOptions.firstPass`.
+            if (name === 'first-pass' && current.firstPass === undefined)
+                return REFUSED_INERT;
+            return {
+                kind: 'dispatch',
+                command: {
+                    kind: 'control',
+                    name,
+                    target: control.getAttribute(TARGET_ATTRIBUTE) ?? undefined,
+                    // The picker publishes its kind as `data-ig-kind`; the mount's chrome
+                    // publishes `data-ig-value`. One command channel, two spellings.
+                    value: control.getAttribute('data-ig-value') ?? control.getAttribute('data-ig-kind') ?? undefined,
+                },
+            };
+        }
+        // AN ANSWER IS ITS OWN ATTRIBUTE, so it falls through the command branch
+        // above and is read here — before the identity branch in `onClick`, which
+        // would otherwise answer a click inside the overlay with whatever key or
+        // group is underneath it.
+        //
+        // REACHED BY THE POINTER ONLY, and deliberately. `onKeydown` returns while
+        // the first-pass phase is open, and this attribute is published only by the
+        // overlay that is drawn while it is open — so the key arm can never see one.
+        // The overlay's own `y`/`n`/`s` map owns those presses, which makes this
+        // half a designed vocabulary rather than a gap.
+        //
+        // WHAT IS A GAP, said plainly because the first draft of this note got it
+        // wrong: the same early return also hides `first-pass-close`, and THAT is a
+        // `data-ig-command` control — the very channel `#158` is about, not one
+        // over. Whether it is activated from `firstPassKeydown` or from a binding in
+        // `firstpass/keys.ts` is a decision about who owns the queue's keyboard, so
+        // it is filed as `#161` rather than settled from inside this function.
+        const answered = target.closest(`[${ANSWER_ATTRIBUTE}]`);
+        if (answered !== null && surface.contains(answered)) {
+            return {
+                kind: 'dispatch',
+                command: {
+                    kind: 'control',
+                    name: 'first-pass-answer',
+                    value: answered.getAttribute(ANSWER_ATTRIBUTE) ?? undefined,
+                },
+            };
         }
         if (target.closest('[data-ig-audit-filter]') !== null) {
-            dispatch({ kind: 'control', name: 'audit-filter' });
+            return { kind: 'dispatch', command: { kind: 'control', name: 'audit-filter' } };
+        }
+        return null;
+    };
+    const onClick = (event) => {
+        const target = isElement(event.target) ? event.target : null;
+        if (target === null)
+            return;
+        const answer = controlAnswer(target);
+        if (answer !== null) {
+            // A REFUSAL STILL STOPS THE CLICK, which is what the three `return`s this
+            // branch replaced did. See {@link controlAnswer} for why falling through
+            // would select something underneath the control instead.
+            if (answer.kind === 'dispatch')
+                dispatch(answer.command);
             return;
         }
         // THE NEARER IDENTITY WINS. A relationship badge inside a row carries
@@ -616,15 +1619,68 @@ export function mountWorkspace(element, options) {
      * filter or the delete button is a control with its own Enter and Space, and
      * a Backspace there must not delete the selected edge; the key map names
      * `elsewhere` as "everything that is not our own search box", and a button is
-     * that. The target search keeps its two bindings, and everything else is
-     * someone else's key.
+     * that. The target search keeps its two bindings.
+     *
+     * ## The kind chooser is the ONE button group that is not `elsewhere`
+     *
+     * The rule above is right for every control it names and wrong for this one,
+     * and the difference is namable rather than a taste: the audit filter and the
+     * delete button share no vocabulary with the key map, while the chooser IS the
+     * key map rendered — its digits are `KIND_KEYS`, the same table `keyIntent`
+     * resolves the press against. A group whose labels tell the reader to press
+     * `2` cannot be a group the reader's `2` is refused by.
+     *
+     * ## Asked of the DRAFT, not of where focus happens to be
+     *
+     * `#152`, and the reason three consecutive rounds of `#150` each fixed a real
+     * bug and surfaced the next one: every one of them moved focus somewhere else,
+     * and this predicate never read the draft, so the next place focus landed
+     * classified `elsewhere` again. Focus is not the fact. A draft with a source
+     * and no kind IS the reader being at the kind step, wherever the mount's
+     * restore happened to put them — and it puts them on the inspector's `clear`,
+     * because the last-resort arm takes the zone's FIRST command control and
+     * `clear` is drawn above the kind list.
+     *
+     * A CONJUNCT ON THE CHOOSER'S OWN MARKUP WAS TRIED ON PAPER AND WOULD HAVE
+     * SHIPPED THE BUG: `closest('<the chooser>')` is false from `clear`, so the
+     * digits would still have died while the change typechecked and its own table
+     * test passed.
+     *
+     * ## `canvas` is asked FIRST, and that ordering is the safety property
+     *
+     * The only answers that move are ones that read `elsewhere` today — where
+     * nothing reaches, so nothing can regress. A reader who leaves the chooser
+     * open and tabs back to a row keeps the whole canvas vocabulary exactly as
+     * before. Note that the order is NOT needed to keep a chooser out of `canvas`:
+     * `focusedKey` walks DOM ancestry, the floating chooser is appended to the
+     * workspace root beside the zones rather than inside the canvas, and the panel
+     * list sits in an inspector that carries no key — so it answers null from
+     * inside either one however this is ordered.
      */
     const interaction = () => {
         const active = doc.activeElement;
         if (isElement(active) && isInput(active) && active.getAttribute(COMMAND_ATTRIBUTE) === 'target-query') {
             return 'target-search';
         }
-        return focusedKey() !== null ? 'canvas' : 'elsewhere';
+        if (focusedKey() !== null)
+            return 'canvas';
+        // A FOCUSED TEXT BOX IS NEVER THE CHOOSER, whatever the draft is doing.
+        // `scale/render.ts` draws the search-to-focus input, and it stays usable
+        // while a draft is open — so without this a reader who clicked it and typed
+        // `1` would have the digit taken from their query and spent on a
+        // relationship kind, `preventDefault()` included. That is the failure
+        // `create/keys.ts` withholds the digits from `target-search` to avoid, and
+        // this arm would have reintroduced it one control over.
+        //
+        // NARROWING THE NEW ARM ONLY, deliberately: an input that is not the target
+        // search already read `elsewhere` before this predicate existed, so this
+        // hands those presses back exactly as they were rather than reclassifying
+        // anything that works today. A focused input INSIDE a keyed node still
+        // answers `canvas` above, which is a pre-existing question and not this
+        // change's to settle.
+        if (isInput(active))
+            return 'elsewhere';
+        return isChoosingKind(state.draft) ? 'kind-chooser' : 'elsewhere';
     };
     /**
      * The rail's window edge, decided BEFORE the viewer is asked.
@@ -722,7 +1778,111 @@ export function mountWorkspace(element, options) {
         }
         return false;
     };
+    /**
+     * The queue's keys, while the queue is up.
+     *
+     * Returns whether the press was consumed. The queue OWNS the keyboard while it
+     * is drawn — the create map and the viewer's navigation are not consulted,
+     * because every one of their targets is behind an inert overlay — but a press
+     * it does not recognise is handed back rather than swallowed, which is the
+     * contract `firstpass/keys.ts` states in terms: `none` exists "so the host does
+     * not `preventDefault()` a key it did not consume".
+     */
+    const firstPassKeydown = (event) => {
+        const { phase } = state.firstPass;
+        if (phase.kind === 'closed')
+            return false;
+        // ESCAPE IS THE MOUNT'S OWN, and it has to be: `firstpass/keys.ts` binds
+        // `y`/`n`/`s` and both spellings of the delete key and nothing else, and its
+        // own tests pin `Escape` to `none`. The exit CONTROL is the mount's, so the
+        // exit KEY is too — without it §17e's "exit anytime" is reachable only with
+        // a pointer, on the one surface that advertises a pointer-free loop.
+        if (event.key === 'Escape') {
+            dispatch({ kind: 'first-pass', command: { kind: 'close' } });
+            return true;
+        }
+        // TAB STAYS INSIDE. `inert` covers the workspace's own zones and nothing
+        // else, so a mount sitting beside other page chrome let Tab — and Shift-Tab
+        // from the wrapper focus lands on — walk straight out of a dialog that
+        // asserts `aria-modal`. The keydown listener is on the mount's element, so
+        // once focus is outside, `Y`/`N`/`S` and Escape all stop working while the
+        // overlay is still up: a keyboard reader stranded with no way back.
+        if (event.key === 'Tab') {
+            const overlay = surface.querySelector('.ig-firstpass-overlay');
+            if (overlay === null)
+                return false;
+            const stops = [...overlay.querySelectorAll('button, [tabindex]:not([tabindex="-1"])')];
+            const first = stops[0];
+            const last = stops[stops.length - 1];
+            if (first === undefined || last === undefined)
+                return false;
+            const active = doc.activeElement;
+            const at = isElement(active) ? stops.indexOf(active) : -1;
+            // WRAPPING AT BOTH ENDS, and treating "focus is on the wrapper" as before
+            // the first stop — which is where it sits on open and after every answer.
+            const next = event.shiftKey ? (at <= 0 ? last : stops[at - 1]) : at === stops.length - 1 ? first : stops[at + 1];
+            (next ?? first).focus({ preventScroll: true });
+            return true;
+        }
+        if (phase.kind !== 'open')
+            return false;
+        const progress = phase.queue;
+        const context = {
+            // `queue` WHENEVER THE OVERLAY HOLDS FOCUS. The surface has no text input
+            // of its own, so the only question is whether the reader is inside it.
+            interaction: isElement(doc.activeElement) &&
+                doc.activeElement.closest('.ig-firstpass-overlay') !== null &&
+                !isInput(doc.activeElement)
+                ? 'queue'
+                : 'elsewhere',
+            hasCandidate: progress.cursor < progress.candidates.length,
+            canUndo: progress.answers.length > 0,
+        };
+        const intent = firstPassIntent(event, context);
+        if (intent.kind === 'none')
+            return false;
+        dispatch({ kind: 'first-pass', command: { kind: 'queue', command: intent.command } });
+        return true;
+    };
     const onKeydown = (event) => {
+        // A HELD KEY BELONGS TO THE CONTROL IT ACTIVATED, wherever focus went next.
+        //
+        // The arm below already refuses to dispatch twice for one held key, and that
+        // is not enough, because ACTIVATING A CONTROL OFTEN MOVES FOCUS: pressing a
+        // kind option redraws and focuses `target-query`, and a self-removing
+        // control falls back to a rail row. So the repeats of that same press arrive
+        // at a DIFFERENT element, where the arm's question — "is what holds focus
+        // now a control?" — answers about the wrong thing entirely. Held `Space` on
+        // a kind option would type spaces into the query the reader has not started;
+        // held `Space` on `add` would walk the rail. Each is the platform doing
+        // exactly the right thing with a press this package took halfway.
+        //
+        // Recorded as a FACT ABOUT THE PRESS rather than re-derived from focus,
+        // which is the same shape as the rest of this file's fixes for this class:
+        // where focus is is not what the question was about. It ends at `keyup`, and
+        // a fresh non-repeat press of the same key clears it too — so a `keyup` lost
+        // to a window blur costs one held key rather than every later one.
+        if (event.repeat && activating.has(event.key)) {
+            event.preventDefault();
+            return;
+        }
+        // A FRESH PRESS ENDS ONLY ITS OWN KEY'S RECORD, and with a set that falls
+        // out rather than being arranged: every key's record is its own, so no other
+        // key's press can reach it. A reader holding `Space` on a control and
+        // touching `Shift` used to have the whole record dropped, and the next
+        // `Space` repeat landed wherever the activation had sent focus.
+        if (!event.repeat)
+            activating.delete(event.key);
+        if (firstPassKeydown(event)) {
+            event.preventDefault();
+            return;
+        }
+        // THE QUEUE STILL OWNS THE SURFACE even for a key it did not consume: every
+        // target the create map and the viewer's navigation could reach is behind
+        // the overlay and inert, so consulting them would act on something the
+        // reader cannot see.
+        if (state.firstPass.phase.kind !== 'closed')
+            return;
         const document_ = landed();
         const match = targetMatches(document_.issues, state.targetQuery, state.draft.source)[0]?.ref ?? null;
         const context = {
@@ -740,8 +1900,152 @@ export function mountWorkspace(element, options) {
             dispatch({ kind: 'intent', intent });
             return;
         }
-        if (context.focused !== null && navigateFocus(event))
+        if (context.focused !== null && navigateFocus(event)) {
+            event.preventDefault();
+            return;
+        }
+        // --- activating a control from the keyboard ---
+        //
+        // ## Why this is last, and why that is the safety property
+        //
+        // The same argument `interaction()` makes for its own ordering: the only
+        // answers that move are ones nothing reaches today, so nothing can regress.
+        // Two facts make it true here rather than merely plausible.
+        //
+        // `interaction()` answers `elsewhere` for a focused command control that is
+        // neither an input nor the kind step, so `keyIntent` returns `none` for
+        // every key there. At the KIND STEP it answers `kind-chooser` — the
+        // predicate is asked of the DRAFT, not of where focus is — and there
+        // `enter` does not survive and `' '` is unbound, so `keyIntent` is silent
+        // again. So this arm does claim `Enter` and `Space` on the inspector's
+        // `clear`, which is where the mount's focus restore lands after `begin`.
+        // That is a control doing what a control does, and it is new behaviour on
+        // a step the create loop passes through every time — said out loud because
+        // it is the one place this arm changes an interaction that already worked.
+        //
+        // And `navigateFocus` is gated on a focused `[data-ig-key]` ancestor, which
+        // no control has: every command control this package draws sits in chrome —
+        // the inspector, the header, the ladder's refusal list and search — beside
+        // the keyed rows rather than inside one.
+        //
+        // ## Why cancelling is mandatory here, not tidy
+        //
+        // On a real `<button>` the browser's ACTIVATION BEHAVIOUR is this keydown's
+        // default action, and `onClick` sees the click it synthesises. Cancelling
+        // the press is therefore what stops this arm and the browser from both
+        // dispatching — the double fire that was, correctly, the reason this was
+        // never built. Every path below that resolves a control reaches
+        // `preventDefault()` for that reason first and the page's scroll second.
+        //
+        // ## …and why an `input` refusal is handed back anyway
+        //
+        // Both search boxes are `<input>` elements carrying `data-ig-command` — the
+        // chrome's `target-query` and the ladder's `search`. `' '` is unbound in
+        // `create/keys.ts` and neither input has a keyed ancestor, so a space
+        // pressed in either arrives HERE. Cancel it and the reader cannot type a
+        // space into the target query, which is step three of the very
+        // `R → digit → search → ⏎` loop this arm exists to complete. The `input`
+        // listener and the platform's text editing own those characters.
+        //
+        // An `inert` refusal keeps the press for the OTHER two reasons this block
+        // gives: `Space` would scroll the page, and this package has answered. It is
+        // NOT that handing it back would let a native button activate the entry —
+        // that was the first draft of this comment and it is false, because the
+        // click a handed-back press synthesizes reaches `onClick`, which asks the
+        // same `controlAnswer` and gets the same refusal. Recorded wrong-then-right
+        // because the argument, not the behaviour, is what the next reader inherits.
+        //
+        // `' '` is the modern `KeyboardEvent.key` value for the space bar; legacy
+        // `'Spacebar'` is not bound. `viewer/navigation.ts` is the package's one
+        // other key reader that binds it and spells it the same way. (`create/keys.ts`
+        // is NOT a precedent either way: it binds no space key, and lowercases the
+        // names it does bind.)
+        if (event.key !== 'Enter' && event.key !== ' ')
+            return;
+        // TWO OF THE REFUSALS `create/keys.ts` ARGUES FOR ITS OWN BINDINGS, and for
+        // the same reasons — a chord is the platform's shortcut, and `Enter` while
+        // an input method is composing confirms its candidate. Read off the event
+        // rather than imported: those predicates are that module's private
+        // business, and this is the shell's half. Its third, `repeat`, is answered
+        // below rather than here, and the difference is not cosmetic — see there.
+        if (event.ctrlKey || event.metaKey || event.altKey)
+            return;
+        if (event.isComposing)
+            return;
+        // THE FOCUSED ELEMENT. `onClick` reads `event.target` because a click's
+        // target IS where the pointer landed; a keydown's target is the focused
+        // element only under the browser's own dispatch, so a press delegated from a
+        // container would name the container instead. `interaction()` and
+        // `navigateFocus` both read `activeElement` for that reason, and an arm in
+        // the same handler answering a different question would be the outlier.
+        const active = doc.activeElement;
+        if (!isElement(active))
+            return;
+        const answer = controlAnswer(active);
+        if (answer === null)
+            return;
+        if (answer.kind === 'refused' && answer.reason === 'input')
+            return;
+        // A REPEAT IS SWALLOWED, NOT HANDED BACK, and it has to be resolved first to
+        // know that it is ours to swallow. Handing it back looked like the modest
+        // choice and is the one that breaks: `Space` activates a `<button>` on
+        // KEYUP, so a held `Space` whose first keydown this arm cancels and whose
+        // second it releases lets the platform mark the button active — and the
+        // keyup then synthesizes a click that dispatches the act a SECOND time. One
+        // held key, two edits; on a toggle the two cancel and the control reads
+        // dead. So the reader holding a key is one decision, which is what
+        // `create/keys.ts` says a repeat is, and cancelling is how it stays one.
+        // (`Enter` repeats natively either way; only `Space` carries the asymmetry,
+        // and a rule that split them would be a rule about keyboards rather than
+        // about acts.)
+        // A REFUSAL IS THIS PACKAGE'S OWN ANSWER, so it keeps the press: `Space`
+        // would otherwise scroll the page under a reader who has just pressed
+        // something, and there is nothing else waiting for this key.
+        if (answer.kind === 'refused') {
             event.preventDefault();
+            return;
+        }
+        // DISPATCH FIRST, THEN DECIDE WHETHER THE PRESS WAS OURS TO KEEP — and that
+        // order is the whole of this arm's remaining subtlety.
+        //
+        // `data-ig-command` IS A SHARED NAMESPACE. `reduceHost`'s `default` arm says
+        // so in terms: a host's own chrome publishes on the same attribute, and
+        // layer 1 already does — the freshness `refresh`, `retry:index`,
+        // `review-pick-order`, `dismiss:adoption` are all drawn inside this surface
+        // and all answered by the host's own `click` listener, never by this
+        // reducer. Cancelling their keydown would suppress the native click that
+        // listener is waiting for, and every one of those controls would stop
+        // answering the keyboard — a regression this arm introduced and could not
+        // see, because from out here a command the reducer ignored and one it
+        // handled without changing anything look identical. So the reducer is asked.
+        //
+        // Unclaimed means HANDS OFF, ALL THE WAY OFF — and "all the way" is the
+        // part that needed a second try. Not cancelling is not enough: dispatching
+        // an unclaimed command still ends in `schedule()`, and the redraw replaces
+        // `surface.innerHTML` — including the button the reader is holding. Since
+        // `Space` activates a `<button>` on KEYUP, destroying it before then loses
+        // the activation just as completely as cancelling the press would. So the
+        // reduction is computed, read, and only THEN applied. No `preventDefault`,
+        // no redraw, no `activating`: the platform's own activation is that
+        // control's route, repeats and all, exactly as before this arm existed.
+        if (destroyed)
+            return;
+        const result = reduceHost(state, answer.command, landed());
+        if (!result.claimed)
+            return;
+        applyResult(result);
+        event.preventDefault();
+        // THE PRESS IS NOW RECORDED AS OURS, so its repeats are swallowed at the top
+        // of this handler wherever the dispatch has since sent focus. Added beside
+        // any other key already held rather than replacing it.
+        activating.add(event.key);
+    };
+    // THE HELD KEY IS LET GO. Registered beside the keydown listener rather than on
+    // the document, so a mount that is torn down takes it with it — and a `keyup`
+    // that never arrives because focus left the window is survivable, which is why
+    // `onKeydown` clears the flag on a fresh press too.
+    const onKeyup = (event) => {
+        activating.delete(event.key);
     };
     const onPointerDown = (event) => {
         // ONE PRIMARY MAIN-BUTTON PRESS AT A TIME. A second pointer during a drag
@@ -834,6 +2138,7 @@ export function mountWorkspace(element, options) {
     element.addEventListener('compositionend', onCompositionEnd);
     element.addEventListener('scroll', onScroll, true);
     element.addEventListener('keydown', onKeydown);
+    element.addEventListener('keyup', onKeyup);
     element.addEventListener('pointerdown', onPointerDown);
     element.addEventListener('pointermove', onPointerMove);
     element.addEventListener('pointerup', onPointerUp);
@@ -850,6 +2155,7 @@ export function mountWorkspace(element, options) {
         element.removeEventListener('compositionend', onCompositionEnd);
         element.removeEventListener('scroll', onScroll, true);
         element.removeEventListener('keydown', onKeydown);
+        element.removeEventListener('keyup', onKeyup);
         element.removeEventListener('pointerdown', onPointerDown);
         element.removeEventListener('pointermove', onPointerMove);
         element.removeEventListener('pointerup', onPointerUp);
@@ -890,8 +2196,10 @@ export function mountWorkspace(element, options) {
         update(next) {
             if (destroyed)
                 return;
-            if (next !== undefined)
+            if (next !== undefined) {
                 current = { ...current, ...next, store };
+                adoptSource();
+            }
             schedule();
         },
         dispatch,