@issuegraph/editor 0.10.0 → 0.23.0

package/dist/workspace/mount.js

@@ -49,7 +49,7 @@ import { edgeIdentity } from '@issuegraph/core';
 import { nextDocument } from '@issuegraph/store';
 import { navigate, renderViewer, resolveTheme, } from '@issuegraph/viewer';
 import { CONTROL_ATTRIBUTES } from "../a11y/baseline.js";
-import { isChoosingKind } from "../create/draft.js";
+import { isChoosingKind, isDraftLive } from "../create/draft.js";
 import { KIND_KEYS, keyIntent } from "../create/keys.js";
 import { pickerPlacement } from "../create/placement.js";
 import { firstPassIntent } from "../firstpass/keys.js";
@@ -61,7 +61,8 @@ 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, editCarrier, railRowAt, railSlackFor, railWindowTarget, reconcileHost, reduceHost, targetMatches, } from "./host.js";
+import { renderWorkspaceSkeleton } from "./skeleton.js";
+import { INITIAL_HOST_STATE, editCarrier, narrowOverlayOpen, 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";
@@ -74,8 +75,31 @@ const CHOOSER_SIZE = { width: 280, height: 220 };
 /** The drag threshold, in CSS pixels: a press that moves less is a click. */
 const DRAG_THRESHOLD = 6;
 const KEY_ATTRIBUTE = 'data-ig-key';
+/**
+ * §17c's change region, which is the one node this surface carries ACROSS a
+ * redraw rather than replacing.
+ *
+ * Matched on the role as well as the class: the class is a styling hook, and
+ * what has to be preserved is the live region specifically.
+ */
+const LIVE_REGION = '.ig-change-line[role="status"]';
 const GROUP_ATTRIBUTE = 'data-ig-group';
 const COMMAND_ATTRIBUTE = 'data-ig-command';
+/**
+ * How many surfaces this module has mounted, so each gets an id nothing else
+ * on the page carries.
+ *
+ * MODULE STATE, DELIBERATELY, and it is the smallest honest way to do this. The
+ * renderer is pure and must stay so — `scale/render.ts`'s `searchSpec` records
+ * what a fixed id costs when a host draws two documents side by side — and the
+ * value has to be stable across every redraw of the SAME mount, so it cannot be
+ * derived per render. A counter in the module that does the mounting satisfies
+ * both: one value per `mountWorkspace` call, fixed for that surface's life.
+ *
+ * Not a random value: a deterministic sequence keeps the markup reproducible
+ * for anything that snapshots it.
+ */
+let surfaces = 0;
 /**
  * Which subject a command acts on, when one command names several.
  *
@@ -123,9 +147,21 @@ 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. */
+/** The three 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' });
+/** A control whose activation the BROWSER performs. See {@link isNavigating}. */
+const REFUSED_NAVIGATION = Object.freeze({ kind: 'refused', reason: 'navigation' });
+/**
+ * Whether this control is a link the browser will follow by itself.
+ *
+ * THE `href` IS PART OF THE TEST. A bare `<a>` with no `href` is not a link —
+ * it has no activation behaviour of its own — so one carrying a command is an
+ * ordinary control and must still be dispatched.
+ */
+function isNavigating(node) {
+    return node?.tagName.toLowerCase() === 'a' && node.getAttribute('href') !== null;
+}
 function isInput(node) {
     return node !== null && node !== undefined && node.tagName === 'INPUT';
 }
@@ -176,6 +212,10 @@ export function mountWorkspace(element, options) {
     const doc = element.ownerDocument;
     const { store } = options;
     let current = options;
+    // ONE PER MOUNT, FIXED FOR ITS LIFE. See `surfaces` for why it is taken here
+    // rather than per render.
+    surfaces += 1;
+    const surfaceId = `w${String(surfaces)}`;
     const styles = doc.createElement('style');
     const surface = doc.createElement('div');
     surface.className = 'ig-mount';
@@ -188,6 +228,21 @@ 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;
+    /**
+     * Set when a command opened the isolated list, cleared by the redraw that
+     * reveals it.
+     *
+     * THE LIST IS NOT WHERE ITS CONTROL IS, and that is what makes this
+     * necessary rather than tidy. §17a puts the count and the toggle at the foot
+     * of the ORDER RAIL; the list itself is drawn by the ladder in the CANVAS,
+     * because the rail is virtualized on a fixed row pitch (`railRowAt`,
+     * `railSpacer`) and content of arbitrary height inside that scroll track
+     * makes every offset beneath it name the wrong row. So pressing the toggle
+     * flips a control in one zone and grows a list in another, below whatever
+     * that zone was already scrolled to — and the reader is told the list is open
+     * while seeing nothing change.
+     */
+    let revealIsolated = false;
     // 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.
@@ -508,6 +563,12 @@ export function mountWorkspace(element, options) {
     const dispatch = (command) => {
         if (destroyed)
             return;
+        // ON THE COMMAND, NOT ON THE RESULTING STATE. `open-isolated` is what the
+        // reader just asked for; `scale.isolatedOpen` is also true on every redraw
+        // that follows for any other reason, and revealing it again there would
+        // yank the canvas back under a reader who had scrolled away.
+        if (command.kind === 'control' && command.name === 'open-isolated')
+            revealIsolated = true;
         applyResult(reduceHost(state, command, landed()));
     };
     const zone = (name) => surface.querySelector(`.ig-zone[data-zone="${name}"]`);
@@ -872,15 +933,19 @@ export function mountWorkspace(element, options) {
     const sceneFor = (zoneName) => {
         if (drawn === null)
             return null;
+        // `frame: false` MIRRORS WHAT IS DRAWN. These rebuild a scene to answer a
+        // navigation question, and a scene built from different options than the
+        // markup is a second opinion about the surface. See `SceneOptions.frame`.
         if (zoneName === 'rail')
-            return renderViewer(drawn.rail.document, { projection: 'linear', theme: theme() }).scene;
+            return renderViewer(drawn.rail.document, { projection: 'linear', theme: theme(), frame: false, dockLegend: true })
+                .scene;
         if (zoneName !== 'canvas')
             return null;
         if (current.canvas === 'tree')
-            return renderViewer(withoutChrome(drawn.viewer), { projection: 'tree', theme: theme(), chrome: false }).scene;
+            return renderViewer(withoutChrome(drawn.viewer), { projection: 'tree', theme: theme(), chrome: false, frame: false, dockLegend: true }).scene;
         const ladder = scaleLadder(drawn.viewer, state.scale);
         return ladder.tier === 'direct'
-            ? renderViewer(ladder.canvas, { projection: 'graph', theme: theme(), chrome: false }).scene
+            ? renderViewer(ladder.canvas, { projection: 'graph', theme: theme(), chrome: false, frame: false, dockLegend: true }).scene
             : null;
     };
     /** The row or node that owns keyboard focus, if focus is on one at all. */
@@ -889,10 +954,65 @@ export function mountWorkspace(element, options) {
         const keyed = isElement(active) ? active.closest(`[${KEY_ATTRIBUTE}]`) : null;
         return keyed !== null && surface.contains(keyed) ? keyed.getAttribute(KEY_ATTRIBUTE) : null;
     };
+    /**
+     * The subject `+ add` publishes, when that control itself owns focus.
+     *
+     * THE SECOND SOURCE FOR `KeyboardContext.focused`, and it exists because the
+     * first one cannot answer here: `focusedKey` reads the rail's roving tab stop,
+     * and a focused button has no keyed ancestor — every command control this
+     * package draws sits in chrome beside the keyed rows rather than inside one.
+     * So `R` on `+ add` reached a `relate` arm whose subject was `null`, which
+     * answers `none` ("nothing focused is nothing to relate FROM"). `#173`.
+     *
+     * IT READS THE CONTROL'S OWN ATTRIBUTE, NOT THE SELECTION, for the reason
+     * `reduceHost`'s `add` arm already reads it: `inspectorView` canonicalizes a
+     * selection naming a together unit's member onto the slot's LEAD, and the
+     * panel is worded from that, so the control publishes the canonical subject
+     * and the selection is only a fallback for a control that names none. Taking
+     * the selection here would begin the keyboard's draft from a different issue
+     * than the pointer's, on one screen, from one control.
+     *
+     * NARROWED TO THE `add` COMMAND, and that is a correctness bound rather than
+     * tidiness: {@link TARGET_ATTRIBUTE} is carried by the row remove control
+     * (an edge id), by a recovery card (a mutation id) and by a hold's subject
+     * button. Reading it off whichever control happens to hold focus would hand
+     * `relate` an edge id as an issue ref.
+     */
+    const focusedAddSubject = () => {
+        const active = doc.activeElement;
+        if (!isElement(active) || !surface.contains(active))
+            return null;
+        if (active.getAttribute(COMMAND_ATTRIBUTE) !== 'add')
+            return null;
+        return active.getAttribute(TARGET_ATTRIBUTE);
+    };
     const render = () => {
         if (destroyed)
             return;
         const snapshot = store.getSnapshot();
+        // THE FIRST READ IS IN FLIGHT, SO THERE IS NOTHING TO SAY YET. Drawn over
+        // the store's empty document, the workspace announced an empty backlog —
+        // "no relationships yet", no rows — about issues nobody had read. The
+        // placeholder holds the three zones' shape instead, and the first render
+        // after the load replaces it.
+        //
+        // `hydrating` ONLY, NEVER `idle`. A store nobody has asked to load is not
+        // loading, and a host that fills its store another way (or a test that
+        // never hydrates) must still get the document it has. A REHYDRATE is not
+        // this state either: the store keeps its last good document and stays
+        // `ready`, so a refresh never blanks the surface.
+        if (snapshot.status === 'hydrating') {
+            const skeleton = renderWorkspaceSkeleton({
+                label: current.words.loading,
+                theme: current.theme === undefined ? undefined : theme(),
+                themeSelector: current.themeSelector,
+            });
+            const skeletonSheet = [skeleton.styles, mountStylesheet].join('\n');
+            if (styles.textContent !== skeletonSheet)
+                styles.textContent = skeletonSheet;
+            surface.innerHTML = skeleton.markup;
+            return;
+        }
         const document_ = landed();
         // 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:
@@ -1089,11 +1209,43 @@ export function mountWorkspace(element, options) {
         }
         const result = renderWorkspace(viewer, {
             words: current.words,
+            // §17c's CAUSE AND EFFECT, STRAIGHT OFF THE SNAPSHOT. The store is the
+            // single source of truth for both — `lastChange` persists until the next
+            // edit or an explicit dismissal, and `dismissChange()` is already the
+            // only thing besides the next edit that clears it — so nothing about
+            // "has this been dismissed" is held out here. A second copy of that is
+            // exactly the drift the command grammar exists to avoid.
+            //
+            // `orderStatus` is the SAME value stamped on `surface` below. They cannot
+            // disagree because they are one read of one snapshot, and each is for a
+            // different reader: the attribute on `surface` is the host's, on the
+            // element the host holds; the option is the stylesheet's, on the root the
+            // renderer owns, so an unmounted rendering greys the held rail too.
+            change: snapshot.lastChange ?? null,
+            orderStatus: snapshot.order.status,
             selection: state.selection,
             scale: state.scale,
             rail: { start: state.railStart, count: railCount() },
+            // §16f's open rows. Host state, because the viewer is re-rendered from
+            // scratch and cannot keep any of its own.
+            expanded: state.expanded,
+            // UNIQUE TO THIS MOUNT, so §17a's rail footer can name the isolated list
+            // the canvas draws without two mounted workspaces on one page naming the
+            // same element. See `WorkspaceOptions.surfaceId`; the counter is why a
+            // second mount gets a second value.
+            surfaceId,
             audit,
             auditFiltered: state.auditFiltered,
+            // §17k's two reader decisions. Host state, for the reason the filter
+            // beside it is: the renderer keeps nothing across a redraw, and a strip
+            // that reopened itself on every landed write would be unusable.
+            canvasOpen: state.canvasOpen,
+            inspectorDismissed: state.inspectorDismissed,
+            // §17d's overlay. Host state, for the same reason the filter beside it
+            // is: the renderer keeps nothing across a redraw.
+            auditOpen: state.auditOpen,
+            issueUrl: current.issueUrl,
+            railDensity: current.railDensity,
             theme: resolved,
             themeSelector: current.themeSelector,
             // THE WRITE STATES ONLY. The workspace holds the one selection, and the
@@ -1121,9 +1273,23 @@ export function mountWorkspace(element, options) {
         if (styles.textContent !== sheet)
             styles.textContent = sheet;
         // What the reader was doing survives the redraw: the rail's scroll offset,
-        // and the caret in whichever search box they were typing into.
+        // the audit panel's, and the caret in whichever search box they were typing
+        // into.
         const railBefore = zone('rail');
         const scrollTop = railBefore?.scrollTop ?? 0;
+        // THE AUDIT SCROLLS TOO, SINCE IT TOOK A SHARE OF ITS COLUMN. Before it had
+        // a bound it grew to its content and only the ZONE scrolled, so there was no
+        // second offset to keep. Now a long audit is read inside its own scroller,
+        // and every store update and unrelated command runs this redraw — so without
+        // this a reader deep in the findings is returned to the first one by
+        // something they did somewhere else entirely.
+        //
+        // THE REGION, NOT THE PANEL. #177 put the bound on `.ig-audit-panel`, and
+        // §17d's second surface moved it up to the region holding both — so reading
+        // the panel's offset now reads a number that is always zero, and restoring
+        // it is a no-op a reader feels as the audit jumping back on every redraw.
+        const auditBefore = surface.querySelector('.ig-audit-overlay');
+        const auditScrollTop = auditBefore?.scrollTop ?? 0;
         const active = doc.activeElement;
         const activeInput = isElement(active) && isInput(active) && surface.contains(active) ? active : null;
         const activeCommand = activeInput?.getAttribute(COMMAND_ATTRIBUTE) ?? null;
@@ -1146,13 +1312,60 @@ export function mountWorkspace(element, options) {
         // redraw that destroyed the focused control and of a reader who simply is
         // not here.
         const heldFocus = isElement(active) && surface.contains(active);
+        // AND WHETHER IT WAS ONE OF THE AUDIT'S OWN TAB STOPS, which are the stops
+        // on this surface no token can name. Neither has a keyed ancestor or a
+        // command attribute, so `focusedKey()` and `commandFocusToken()` both answer
+        // nothing for them — and the last-resort arm below fires on exactly that,
+        // sending a reader who was reading a long audit to the first rail row, in
+        // another zone.
+        //
+        // TWO OF THEM SINCE §17d GAINED ITS SECOND SURFACE, and the refused block is
+        // the one that needs this MOST: both of its controls are conditional, so a
+        // block whose refusals all name unloaded issues has no focusable descendant
+        // at all and the section itself is the only stop a reader can hold.
+        //
+        // A CLASS RATHER THAN THE NODE THE OFFSET CAME FROM. That identity test was
+        // right while the scrolling element and the tab stop were one element; they
+        // are not any more — the region scrolls and its members carry the stops —
+        // so the answer has to name which stop, and it is restored by the same name.
+        const AUDIT_STOPS = ['.ig-audit-refused', '.ig-audit-panel'];
+        const auditStop = isElement(active)
+            ? (AUDIT_STOPS.find((one) => active.matches(one)) ?? null)
+            : null;
         // 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.
         const focusedZone = isElement(active) ? (active.closest('.ig-zone')?.getAttribute('data-zone') ?? null) : null;
         drawn = { viewer, rail: result.view.rail };
+        // THE LIVE REGION HAS TO SURVIVE THE REDRAW, or it announces nothing.
+        //
+        // `summarySpec` mounts §17c's `role="status"` region ALWAYS and leaves it
+        // EMPTY until there is something to say, precisely because a status node
+        // that is created already carrying its text is not reliably announced —
+        // the region has to exist first and then have its contents change. This
+        // function replaces the whole subtree on every redraw, so rendering that
+        // region into the markup and stopping there would destroy it and insert a
+        // new, already-populated one every time: the affordance present, correct
+        // in the markup, and inert. Worse than absent, because it looks done.
+        //
+        // So the ELEMENT is carried across: re-attached still holding the previous
+        // summary, and only then given the new one. The insertion says nothing and
+        // the mutation is what announces, which is the sequence the region was
+        // designed around.
+        const liveBefore = surface.querySelector(LIVE_REGION);
         // Package-rendered markup, escaped by the package.
         surface.innerHTML = result.markup;
+        const liveAfter = surface.querySelector(LIVE_REGION);
+        if (liveBefore !== null && liveAfter !== null) {
+            const next = liveAfter.innerHTML;
+            liveAfter.replaceWith(liveBefore);
+            // GUARDED, so a redraw that did not touch the summary is not a change to
+            // announce. Every keystroke in the ladder's search box redraws this
+            // surface, and re-assigning identical content would re-announce the last
+            // edit's result on each one.
+            if (liveBefore.innerHTML !== next)
+                liveBefore.innerHTML = next;
+        }
         // THE ORDER'S STATUS, PUBLISHED AS DATA. A write in flight holds the order
         // — it does not move until the edit lands — and a host that wants to say
         // so has nowhere to read it once the snapshot is consumed here. The
@@ -1169,13 +1382,79 @@ 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.
+                // §17f'S ROW SURVIVES THIS ASSIGNMENT, AND ITS CAPTION DOES NOT.
+                // `innerHTML` replaces every child, and `renderWorkspace` puts the
+                // toolbar in this zone as its FIRST child — so the row, the pill
+                // included, was silently deleted the moment a reader switched to the
+                // tree. The pill is a property of the SURFACE, and a mounted surface is
+                // exactly where a host is told to supply it, so losing it here took the
+                // control away in the one state it is documented to exist in.
+                //
+                // THE CAPTION IS DIFFERENT, and is dropped on purpose rather than by
+                // accident. It states what the LADDER's canvas draws — one connected
+                // component out of the whole backlog — and this branch does not draw the
+                // ladder's canvas: it draws `viewer`, the whole document, as a tree. So
+                // "6 out of 312 drawn here" is simply false over a tree of 312, on the
+                // same rule that keeps the caption off the refusing tiers.
+                const toolbar = canvas.querySelector('.ig-canvas-toolbar');
+                toolbar?.querySelector('.ig-canvas-caption')?.remove();
+                // THE ISOLATED BLOCK SURVIVES THIS ASSIGNMENT TOO, and for a sharper
+                // reason than the row above. §17a moves the isolated CONTROL to the
+                // foot of the order rail, which this branch does not touch — so the
+                // control survives the switch to the tree whatever happens here, while
+                // the list it opens is drawn in THIS zone and would not. The reader
+                // presses it, the label turns to "hide" and `aria-expanded` to `true`,
+                // and nothing appears: a control that reports a state the surface is
+                // not in.
+                //
+                // WORSE THAN WHAT IT REPLACED, WHICH IS WHY IT IS FIXED HERE RATHER
+                // THAN NOTED. Before that move the chip lived in this zone beside its
+                // list, so the tree deleted BOTH and the affordance was merely absent —
+                // wrong, but not lying. Keeping the list is what makes the control it
+                // is now separated from honest.
+                //
+                // UNCONDITIONAL, unlike the toolbar's `childElementCount` guard. This
+                // element is not assembled from optional parts: `isolatedSpec` returns
+                // null rather than an empty husk, so anything found here has content.
+                const isolated = canvas.querySelector('.ig-ladder-isolated');
                 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,
+                    // THE WORKSPACE RULES ITS OWN ZONES OFF, so the viewer draws no
+                    // frame of its own here: the rail track carries `border-right`, the
+                    // canvas toolbar carries `border-bottom`, and a second edge one
+                    // pixel away reads as a doubled hairline. See `SceneOptions.frame`.
+                    frame: false,
+                    // §16b's KEY, KEPT IN VIEW. It explains every line and station on this
+                    // zone, and below a scroll it was the one thing a reader had to leave the
+                    // reading to reach. See `SceneOptions.dockLegend`.
+                    dockLegend: true,
                 }).markup;
+                // Re-inserted rather than re-rendered: the row is already assembled,
+                // and rebuilding it here would be a second place that decides what it
+                // says.
+                //
+                // ONLY IF IT STILL HAS CONTENT, which is `canvasToolbar`'s own rule —
+                // "nothing to say, no row" — and removing the caption above is exactly
+                // what can empty it. A host that words the caption and not the pill
+                // gets a caption-only row on the direct tier, and prepending its
+                // emptied husk here left a sticky padded band with a border and no
+                // content over the tree. Reading the element rather than re-deriving
+                // the condition keeps the rule in one place.
+                // THE TREE ALWAYS DRAWS A KEY, WHATEVER THE GRAPH'S TIER SAID. render.ts
+                // set `data-canvas-legend` from the scale ladder, which is a fact about
+                // the GRAPH — and this branch has just replaced the graph with a
+                // projection that has no budget and no refusal. Left as it was, a tree
+                // over a backlog past the node budget reported no key in this zone and
+                // the rail drew a second one beside the one on screen.
+                surface.firstElementChild?.setAttribute('data-canvas-legend', 'drawn');
+                if (isolated !== null)
+                    canvas.append(isolated);
+                if (toolbar !== null && toolbar.childElementCount > 0)
+                    canvas.prepend(toolbar);
                 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) ?? '');
@@ -1203,6 +1482,27 @@ export function mountWorkspace(element, options) {
         const rail = zone('rail');
         if (rail !== null)
             rail.scrollTop = scrollTop;
+        // AFTER the subtree is in place, because it measures what was just drawn.
+        dockRailLegend();
+        // RE-QUERIED, NEVER REUSED: `surface.innerHTML` above replaced the subtree,
+        // so the element captured from is gone. A region that shrank clamps this on
+        // assignment, and one the redraw removed — the audit going clean — is
+        // simply absent, which is why nothing is restored rather than zeroed.
+        const auditRegion = surface.querySelector('.ig-audit-overlay');
+        if (auditRegion !== null)
+            auditRegion.scrollTop = auditScrollTop;
+        // THE LIST THE READER JUST OPENED IS BROUGHT INTO VIEW. See
+        // `revealIsolated` for why the control and the list are in different zones.
+        // `block: 'nearest'` so a list already visible is not scrolled at all, and
+        // guarded on the method because the same guard is used for the rail's own
+        // jumps — this module renders into whatever document a host hands it.
+        if (revealIsolated) {
+            revealIsolated = false;
+            const list = surface.querySelector('.ig-isolated-list');
+            if (list !== null && typeof list.scrollIntoView === 'function') {
+                list.scrollIntoView({ block: 'nearest' });
+            }
+        }
         // FOCUS SURVIVES THE REDRAW, and it moves to the target search when that
         // step opens. The keyboard path is R -> kind -> search -> Enter, and every
         // step redraws: without this, R destroyed the focused row, the next press
@@ -1231,6 +1531,21 @@ export function mountWorkspace(element, options) {
             // irreversible answer under the reader's next Space.
             (again ?? overlay).focus({ preventScroll: true });
         }
+        else if (auditStop !== null && surface.querySelector(auditStop) !== null) {
+            // THE READER WAS IN THE AUDIT, SO THEY STAY THERE — and on the same one of
+            // its two surfaces, which is why the stop is restored by the name it was
+            // captured under rather than by whichever the redraw drew first.
+            //
+            // Beside the offset restored above rather than instead of it: the offset
+            // says where the region is scrolled to and this says who is reading it,
+            // and a redraw that kept one without the other still moves the reader out
+            // of the zone.
+            //
+            // `preventScroll`, because the offset was already put back — focusing
+            // normally would scroll the column to bring the element into view and
+            // undo it.
+            surface.querySelector(auditStop)?.focus({ preventScroll: true });
+        }
         else if (activeCommand !== null) {
             const again = surface.querySelector(`input[${COMMAND_ATTRIBUTE}="${activeCommand}"]`);
             if (again !== null) {
@@ -1482,6 +1797,22 @@ export function mountWorkspace(element, options) {
             const name = control.getAttribute(COMMAND_ATTRIBUTE) ?? '';
             if (isInput(control))
                 return REFUSED_INPUT; // the `input` listener owns these
+            // AND THE BROWSER OWNS A LINK, which is the same refusal one element over.
+            // §17d's `Open in GitHub` is an ANCHOR — it leaves the document, and a
+            // control that navigates away must not announce itself as a button — and
+            // it carries a command name only so `a11y/baseline.ts` can see it: that
+            // artifact records a control through the attribute channels it knows, and
+            // an anchor bearing nothing but `href` is invisible to it.
+            //
+            // DISPATCHING IT WOULD BE A REDRAW UNDER THE READER'S OWN CLICK. The
+            // reducer has no arm for the name, so the command comes back unclaimed —
+            // but `applyResult` still schedules, and the redraw replaces the surface's
+            // markup, detaching the anchor mid-activation. An `<a>` is exempt from the
+            // "cannot navigate" connectedness check so the navigation still happens,
+            // which is precisely why this would have gone unnoticed: a full re-render
+            // per click, paid for a command nothing handles.
+            if (isNavigating(control))
+                return REFUSED_NAVIGATION;
             // 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
@@ -1532,6 +1863,13 @@ export function mountWorkspace(element, options) {
         if (target.closest('[data-ig-audit-filter]') !== null) {
             return { kind: 'dispatch', command: { kind: 'control', name: 'audit-filter' } };
         }
+        // §17d's HEADER COUNT. Checked AFTER the filter, and the order is not
+        // arbitrary: the filter chip lives inside the panel the count opens, so a
+        // click on it is inside neither the other's subtree today — but if the two
+        // ever nest, the inner control is the one the reader aimed at.
+        if (target.closest('[data-ig-audit-panel]') !== null) {
+            return { kind: 'dispatch', command: { kind: 'control', name: 'audit-panel' } };
+        }
         return null;
     };
     const onClick = (event) => {
@@ -1584,6 +1922,49 @@ export function mountWorkspace(element, options) {
     const onCompositionEnd = (event) => {
         readInput(event);
     };
+    /**
+     * Move the rail's docked legend clear of this zone's own footer.
+     *
+     * TWO THINGS ARE PINNED TO ONE EDGE, AND ONLY THIS PACKAGE KNOWS BOTH. The
+     * viewer docks its legend against the bottom of whatever scrollport it was
+     * given (`SceneOptions.dockLegend`), with `bottom: 0` as the default; this
+     * zone already holds `.ig-rail-footer` there. Left at the default the two
+     * stack in the same place, and the footer — later in the subtree and carrying
+     * its own layer — paints over the bottom of the key. The viewer cannot fix
+     * that: it has never been told the footer exists.
+     *
+     * MEASURED, NOT DERIVED FROM THE TOKENS. The footer is one line of type at a
+     * known size inside known padding, so its height looks like something the
+     * stylesheet could state — and then the rail narrows, `5 with no
+     * relationships` and its control wrap to two lines, and the written-down
+     * number is quietly wrong by a line. The same argument `onScroll` makes about
+     * the header it measures rather than derives.
+     *
+     * ON EVERY REDRAW AND ON EVERY RESIZE, because the wrap depends on the width
+     * and a resize alone redraws nothing. The observer is guarded on the
+     * constructor rather than assumed: this module renders into whatever document
+     * a host hands it, and a host rendering server-side or in a minimal DOM has
+     * no need of the correction — the default is simply left in place.
+     */
+    const dockRailLegend = () => {
+        const rail = zone('rail');
+        const legend = rail?.querySelector('.ig-viewer > .ig-legend');
+        if (rail === null || legend == null)
+            return;
+        const footer = rail.querySelector('.ig-rail-footer');
+        // RE-OBSERVED EVERY REDRAW, because `surface.innerHTML` replaced the zone and
+        // the element the last call watched is gone. `disconnect` first so the
+        // observer never accumulates dead targets.
+        if (railResize !== null) {
+            railResize.disconnect();
+            railResize.observe(rail);
+        }
+        const clearance = footer === null ? 0 : Math.ceil(footer.getBoundingClientRect().height);
+        // AN INLINE STYLE, because it is a measurement rather than a rule: it is
+        // true of this rail at this width and of nothing else, which is exactly what
+        // a stylesheet cannot say.
+        legend.style.bottom = `${String(clearance)}px`;
+    };
     const onScroll = (event) => {
         const rail = zone('rail');
         if (rail === null || event.target !== rail)
@@ -1621,14 +2002,23 @@ export function mountWorkspace(element, options) {
      * `elsewhere` as "everything that is not our own search box", and a button is
      * that. The target search keeps its two bindings.
      *
-     * ## The kind chooser is the ONE button group that is not `elsewhere`
+     * ## The TWO controls that are not `elsewhere`, and the test they pass
      *
-     * The rule above is right for every control it names and wrong for this one,
+     * The rule above is right for every control it names and wrong for these two,
      * 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.
+     * delete button share no vocabulary with the key map, while these two ARE the
+     * key map rendered. The kind chooser's digits are `KIND_KEYS`, the same table
+     * `keyIntent` resolves the press against, and `+ add` draws `RELATE_KEY`
+     * itself as its hint. A control whose labels tell the reader to press `2`
+     * cannot be a control the reader's `2` is refused by, and `#173` is the same
+     * sentence about `R`: the hint named a key the reader genuinely has, at the
+     * one focus position where it was inert.
+     *
+     * THE TEST IS "DOES THIS CONTROL DRAW A KEY THIS MAP READS", and it is what
+     * stops the list growing on taste. It admits exactly two controls today; a
+     * host's own widget, a filter, a remove button and every control that draws
+     * no key stay `elsewhere`. `create/keys.ts` carries the matching half — the
+     * new state admits the ONE binding it renders and no other.
      *
      * ## Asked of the DRAFT, not of where focus happens to be
      *
@@ -1646,6 +2036,25 @@ export function mountWorkspace(element, options) {
      * digits would still have died while the change typechecked and its own table
      * test passed.
      *
+     * ## `add-control` reads focus, and that is not a relapse
+     *
+     * `#173`'s arm asks where focus is, which is the shape this section rejects —
+     * so it has to survive the argument rather than repeat what it rejected, and
+     * the difference is WHICH FACT IS MISSING. At the kind step the fact is the
+     * DRAFT: a source with no kind IS the reader at that step, wherever a restore
+     * put them, so reading focus there answers a question the draft had already
+     * answered better. At the begin step there is no draft yet — beginning one is
+     * the act — and the fact is the SUBJECT to begin from. The control publishes
+     * it on `data-ig-target`, so what this arm reads is a control's own claim
+     * about what it is for, and focus is what says the reader is standing on it.
+     *
+     * The `#150` failure mode is therefore absent by construction: it was focus
+     * MOVING AWAY from the control the draft belonged to, and the arm here has no
+     * "away" — it answers about the control still holding focus, and once the
+     * draft begins the panel replaces this control with the kind list, at which
+     * point the draft is the fact again and `kind-chooser` answers. That ordering
+     * is written below rather than left to be inferred.
+     *
      * ## `canvas` is asked FIRST, and that ordering is the safety property
      *
      * The only answers that move are ones that read `elsewhere` today — where
@@ -1657,6 +2066,52 @@ export function mountWorkspace(element, options) {
      * list sits in an inspector that carries no key — so it answers null from
      * inside either one however this is ordered.
      */
+    /**
+     * Whether Escape has nothing of the CREATE PATH's to cancel.
+     *
+     * ONE PREDICATE FOR WHAT WAS TWO. §17d's overlay and §17k's transients both
+     * take Escape, and both must yield to a live draft — a reader mid-relationship
+     * means "not this edge", not "close the panel behind it". Written out at each
+     * site, that rule is one a later edit can move at one of them.
+     *
+     * FIVE FIELDS, NOT THREE. `isDraftLive` answers for the draft itself, and the
+     * target search and the drop point are the create path's too: a reader who
+     * typed into the target box with no draft open still has something for Escape
+     * to clear, and taking the press for a panel would leave their query sitting
+     * there. `cancel` clears all five, which is why all five are asked.
+     */
+    /**
+     * Whether §17k's lifted inspector is actually ON SCREEN.
+     *
+     * `narrowOverlayOpen` answers about STATE, and state is not visibility here:
+     * the panel is lifted between `1120` and `1359` and is an ordinary column
+     * either side of that, so at the wide layout a selection makes the reducer's
+     * predicate true with nothing overlaid for Escape to dismiss. The press was
+     * being spent on a change the reader could not see.
+     *
+     * THE STYLESHEET KNOWS AND THE DOM SHOWS ITS ANSWER, which is why this is a
+     * measurement rather than a width. The lifted panel is placed in the CANVAS's
+     * grid area, so it overlaps the canvas's box; as a column it sits beside it
+     * and cannot. That is the same fact the sheet encodes, read back rather than
+     * re-derived — and it is not the window, which §17k rules out.
+     *
+     * A SURFACE WITH NO LAYOUT CANNOT ANSWER, and says so by yielding to the
+     * state. Every box is zero-sized before layout, and under `node --test` there
+     * is no layout at all; a strict reading would disable the key there and take
+     * a tested behaviour away from every consumer that renders without a browser.
+     */
+    const inspectorIsLifted = () => {
+        const inspector = surface.querySelector('.ig-zone[data-zone="inspector"]');
+        const canvas = surface.querySelector('.ig-zone[data-zone="canvas"]');
+        if (inspector === null || canvas === null)
+            return false;
+        const panel = inspector.getBoundingClientRect();
+        const zone = canvas.getBoundingClientRect();
+        if (panel.width === 0 && zone.width === 0)
+            return true;
+        return panel.left < zone.right && panel.right > zone.left;
+    };
+    const nothingToCancel = () => !isDraftLive(state.draft) && state.targetQuery === '' && state.drop === null;
     const interaction = () => {
         const active = doc.activeElement;
         if (isElement(active) && isInput(active) && active.getAttribute(COMMAND_ATTRIBUTE) === 'target-query') {
@@ -1680,7 +2135,14 @@ export function mountWorkspace(element, options) {
         // change's to settle.
         if (isInput(active))
             return 'elsewhere';
-        return isChoosingKind(state.draft) ? 'kind-chooser' : 'elsewhere';
+        // THE DRAFT IS ASKED BEFORE THE CONTROL, so the section above stays true of
+        // the state it was written for. The two cannot both be live in practice —
+        // `createStep` withholds `+ add` for the whole of the kind step — but a rule
+        // that depends on another module's rendering condition is one that changes
+        // silently the day that condition does.
+        if (isChoosingKind(state.draft))
+            return 'kind-chooser';
+        return focusedAddSubject() === null ? 'elsewhere' : 'add-control';
     };
     /**
      * The rail's window edge, decided BEFORE the viewer is asked.
@@ -1776,6 +2238,26 @@ export function mountWorkspace(element, options) {
             focusIn(zoneName, result.command.key);
             return true;
         }
+        // §16f's `→ expands provenance` on a list row. The viewer cannot expand
+        // anything itself, so it publishes `expand:<key>` and this is where the
+        // host takes it — split into the name/target shape every other control
+        // here already uses, rather than teaching the reducer a second spelling.
+        //
+        // THE COLON IS LOAD-BEARING. `expand` with no key is §16a's panel-size
+        // control and means something else entirely; only the qualified form is a
+        // row. A press that names no key is handed back rather than swallowed.
+        if (result.command.kind === 'command') {
+            const [name, ...rest] = result.command.command.split(':');
+            // REJOINED, NOT `rest[0]`. A qualified key is `owner/repo#12`, which
+            // carries no colon today — but the split is over the whole command and
+            // taking only the first segment would silently truncate any key that
+            // ever does.
+            const row = rest.join(':');
+            if ((name === 'expand' || name === 'collapse') && row !== '') {
+                dispatch({ kind: 'control', name, target: row });
+                return true;
+            }
+        }
         return false;
     };
     /**
@@ -1889,11 +2371,89 @@ export function mountWorkspace(element, options) {
             // The FOCUSED row, not the selection: on a fresh page a row can own
             // focus while nothing is selected, and after focus moves on, a stale
             // selection must not become the source of a keyboard-started draft.
-            focused: focusedKey(),
+            // AND `+ add`'S OWN SUBJECT WHERE THERE IS NO ROW, which is still that
+            // rule rather than an exception to it — the fallback is a control's
+            // published claim about what it acts on, not the selection this line
+            // refuses. It moves nothing that worked: the second term is consulted
+            // only where the first is `null`, and where it answers, `interaction()`
+            // answers `add-control`, which admits `relate` alone.
+            // AND IT DOES NOT OPEN THE NAVIGATION ARM BELOW, which is the one place a
+            // wider `focused` could have leaked. That arm is guarded on this field,
+            // but `navigateFocus` re-derives the key from a `[data-ig-key]` ANCESTOR
+            // and answers `false` without one — and no command control has one, since
+            // every one this package draws sits in chrome beside the keyed rows. So
+            // the guard now admits a press the arm still declines, rather than
+            // stepping the rail from a focused button.
+            focused: focusedKey() ?? focusedAddSubject(),
             match,
             selectedEdge: selectedEdgeId(state.selection),
             interaction: interaction(),
         };
+        // §17k'S TRANSIENT SURFACES ARE DISMISSED ON ESCAPE — the ruling's own
+        // words for the lifted inspector, and the strip takes the same key because
+        // a canvas opened over the inspector is the same kind of thing.
+        //
+        // BEFORE `keyIntent`, AND THE OBVIOUS PLACEMENT IS THE WRONG ONE. Putting
+        // it after reads as the safe order — let the create loop have the press
+        // first — and it makes this arm DEAD. `create/keys.ts` binds `escape` to
+        // `cancel` with the comment "ALWAYS AVAILABLE", and `reaches` admits it
+        // whenever the interaction is `canvas`, which `interaction()` answers for
+        // any focused `[data-ig-key]`. So with focus on a rail row — where it sits
+        // after almost every click on this surface — `keyIntent` claims Escape for
+        // a draft that does not exist and returns, and nothing below it is reached.
+        // MEASURED IN A BROWSER, not reasoned about: the panel stayed open, and the
+        // `dataInspector` attribute stayed `lifted` across the press.
+        //
+        // THE DRAFT STILL WINS, WHICH IS WHAT THE OTHER ORDER WAS FOR. A reader
+        // mid-relationship pressing Escape means "not this edge", not "close the
+        // panel behind it" — so the guard is `nothingToCancel`, which asks about
+        // the create path rather than about the position in this function. An idle
+        // one is the only state `keyIntent` would have spent the press on, and
+        // cancelling an idle draft is a no-op.
+        //
+        // GUARDED ALSO ON `narrowOverlayOpen`, WHICH IS THE REDUCER'S OWN PREDICATE
+        // rather than a second reading of the same two fields, so the two cannot
+        // drift apart — `reduceHost` answers `unclaimed` for exactly the same case.
+        //
+        // WHAT THAT DOES NOT DO IS LET THE PRESS THROUGH. A press this arm declines
+        // falls to `keyIntent`, which binds Escape to a cancel that is "ALWAYS
+        // AVAILABLE" and cancels it there — so on a focused rail row Escape is
+        // consumed by this surface whether or not anything was dismissed. That
+        // predates this branch and is not changed here; it is written down because
+        // the obvious reading of `unclaimed` is that the key reaches the host, and
+        // on this surface it does not.
+        //
+        // THE REDUCER CANNOT ASK WHICH OF THE TWO THE READER CAN SEE, and it must
+        // not: the width is the stylesheet's to know, per §17k's note that a
+        // package reading the window cannot be dropped into someone else's page.
+        // So it closes both and the sheet draws whichever was on screen.
+        //
+        // THE SHELL CAN ASK, THOUGH, AND HAS TO. An earlier revision left the guard
+        // at the reducer's predicate alone and accepted "a press spent invisibly at
+        // the wide layout" as a cost. It is not a cost worth taking: a key consumed
+        // for a surface nobody can see is indistinguishable from a broken key. See
+        // `inspectorIsLifted`, which reads the sheet's own answer off the DOM
+        // rather than re-deriving it from a width.
+        //
+        // TWO TRANSIENTS SHARE THIS KEY NOW, AND §17d'S GOES FIRST. The audit
+        // overlay is the one the reader pressed a control to open, and it is drawn
+        // at EVERY width; §17k's lifted inspector is opened implicitly by a
+        // selection and exists only between `1120` and `1359`. So a press with the
+        // audit panel up closes the audit panel, at any width — without this order
+        // a reader at the wide layout, where nothing of §17k's is drawn, would
+        // press Escape and watch the panel stay put.
+        if (event.key === 'Escape' && nothingToCancel()) {
+            if (state.auditOpen) {
+                event.preventDefault();
+                dispatch({ kind: 'control', name: 'audit-close' });
+                return;
+            }
+            if (narrowOverlayOpen(state) && (state.canvasOpen || inspectorIsLifted())) {
+                event.preventDefault();
+                dispatch({ kind: 'control', name: 'narrow-dismiss' });
+                return;
+            }
+        }
         const intent = keyIntent(event, context);
         if (intent.kind !== 'none') {
             event.preventDefault();
@@ -1913,11 +2473,13 @@ export function mountWorkspace(element, options) {
         // 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
+        // neither an input, nor the kind step, nor `+ add`, 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
+        // again. On `+ add` it answers `add-control`, which admits `RELATE_KEY`
+        // alone (`#173`) and neither of these two, so this arm still owns them
+        // there. 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
@@ -2001,8 +2563,18 @@ export function mountWorkspace(element, options) {
         // 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.
+        //
+        // EXCEPT A NAVIGATION REFUSAL, WHICH MEANS THE OPPOSITE. `input` and `inert`
+        // say "this press does nothing, and nothing else wants it"; `navigation`
+        // says the BROWSER performs this control's activation, so there is something
+        // else waiting for the key and cancelling is how it never arrives. An
+        // anchor's `Enter` activation is a DEFAULT ACTION — cancel the keydown and
+        // no click is synthesized and the link never opens, which would leave §17d's
+        // outward link working for a pointer and dead for a keyboard. The click path
+        // still refuses to DISPATCH it; the two answers differ because the acts do.
         if (answer.kind === 'refused') {
-            event.preventDefault();
+            if (answer.reason !== 'navigation')
+                event.preventDefault();
             return;
         }
         // DISPATCH FIRST, THEN DECIDE WHETHER THE PRESS WAS OURS TO KEEP — and that
@@ -2146,10 +2718,23 @@ export function mountWorkspace(element, options) {
     element.addEventListener('lostpointercapture', onPointerCancel);
     doc.addEventListener('pointerup', onDocumentPointerUp);
     doc.addEventListener('pointercancel', onDocumentPointerUp);
+    /**
+     * The rail's own width, watched only so the docked legend's clearance stays
+     * true. See `dockRailLegend` for why a resize and not just a redraw.
+     *
+     * THE ELEMENT, NOT THE WINDOW. A package that reads the window cannot be
+     * dropped into someone else's page — the same rule §17j states about the
+     * density crossover and the workspace's own container query rests on. The
+     * rail can narrow because the host resized, because a sibling grew, or
+     * because a container query re-tracked the grid, and only the box itself sees
+     * all three.
+     */
+    const railResize = typeof ResizeObserver === 'function' ? new ResizeObserver(() => { dockRailLegend(); }) : null;
     const unsubscribe = store.subscribe(schedule);
     /** Every listener off and every node this mount built removed. Shared by `destroy` and a failed first render. */
     const teardown = () => {
         unsubscribe();
+        railResize?.disconnect();
         element.removeEventListener('click', onClick);
         element.removeEventListener('input', onInput);
         element.removeEventListener('compositionend', onCompositionEnd);