@issuegraph/editor 0.4.0 → 0.22.1

package/dist/workspace/render.d.ts

@@ -9,7 +9,7 @@
  * |-----------|-------------------------------------------------------|
  * | header    | `auditOverlay` + `renderAuditHeader`                   |
  * | rail      | `renderViewer(…, { projection: 'linear' })`, windowed  |
- * | canvas    | `renderScaleLadder`                                    |
+ * | canvas    | `canvasToolbar` + `renderScaleLadder`                  |
  * | inspector | `inspectorView`, rendered here                         |
  *
  * ## The audit left-bar is applied to the rail's SPEC, never to its markup
@@ -49,17 +49,83 @@
  * `styles.ts` writes structure against its custom properties.
  */
 import { type Theme, type ViewerDocument } from '@issuegraph/viewer';
-import type { ProjectedEdge } from '@issuegraph/store';
+import type { EdgeId, InvalidCode, MutationId, OrderChange, OrderStatus, ProjectedEdge } from '@issuegraph/store';
 import type { AuditInput } from '../audit/findings.ts';
+import { type AuditWords } from '../audit/panel.ts';
+import { type EncodingRefusedBlockOptions } from '../audit/refused.ts';
+import { type CreateDraft } from '../create/draft.ts';
+import type { Point } from '../create/placement.ts';
+import type { ChangeWords } from '../reevaluate/words.ts';
 import { type AuditOverlay } from '../audit/surface.ts';
 import { type ScaleState } from '../scale/commands.ts';
 import { type InspectorView } from './inspector.ts';
 import { type RailWindow, type RailWindowOptions } from './rail.ts';
+import { type ConflictDiff } from './recovery.ts';
 import { type WorkspaceSelection } from './selection.ts';
 /** The four fixed positions. A closed union, which is what keeps `zone` safe. */
 export declare const ZONES: readonly ["header", "rail", "canvas", "inspector"];
 export type Zone = (typeof ZONES)[number];
 export interface WorkspaceWords {
+    /**
+     * §17c's vocabulary — the change summary's facets, its dismiss control and
+     * its direction words.
+     *
+     * OPTIONAL, AND ITS ABSENCE DRAWS NOTHING rather than drawing a default.
+     * `ChangeWords` states the doctrine and this obeys it exactly: the store
+     * ships the change as COUNTS so a host writes the sentence in its own
+     * language, and a default supplied here would take that choice back one layer
+     * down. So a host that has not supplied these gets no summary and no chips —
+     * not an English summary it cannot translate.
+     *
+     * It is the one shape that also keeps this a non-breaking addition: every
+     * host built against 0.12 renders exactly as it did.
+     */
+    readonly change?: ChangeWords | undefined;
+    /**
+     * Reads the freshness stamp in §17a's header — the frame's `as of 14:32 ↻`,
+     * minus the clock.
+     *
+     * THE NUMBER IS APPENDED, NOT INTERPOLATED, exactly as {@link whyRank}'s is
+     * and for the reason stated there: a `{n}` template makes every host
+     * reimplement the substitution, which is how a package that refuses to invent
+     * English ships a tiny template language instead. `Freshness.asOf` and
+     * `Freshness.age` are the host's own strings and are printed verbatim.
+     *
+     * THE STALE FLAG CARRIES NO WORD, unlike layer 1's stamp, which appends a
+     * literal ` · stale`. §17a's stamp is `as of 14:32 ↻` and says nothing more,
+     * so staleness rides on `data-stale` for the stylesheet to treat. A word here
+     * would be a fourth thing to translate for a state the frame draws silently.
+     */
+    readonly asOf: string;
+    /**
+     * The noun after the backlog's total — frame 17a's `312 open`.
+     *
+     * IT WORDS `Adoption.counts.total`, WHICH IS NOT `OrderCounts`. Two different
+     * pairs reach this surface and only one of them is §17a's header content: the
+     * adoption pair says how much of the backlog is encoded, and the order pair
+     * (`ranked` / `readyNow` / `held`) says how the order splits. The second stays
+     * in the rail, where it belongs to the order it describes.
+     */
+    readonly open: string;
+    /**
+     * The noun after the encoded count — frame 17a's `64 encoded`, wording
+     * `Adoption.counts.declaring`.
+     *
+     * SEPARATE FROM {@link open} RATHER THAN ONE PHRASE, because the two numbers
+     * are the package's and the two nouns are the host's; a single string would
+     * have to carry both figures and would be a template again.
+     */
+    readonly encoded: string;
+    /**
+     * The panel's own heading — frame 17a's `INSPECTOR`.
+     *
+     * UNCONDITIONAL, and that is what it is for: the zone used to begin with
+     * whatever the selection happened to resolve to, so a reader who had selected
+     * nothing met a bare sentence in an unnamed column. The caps are the
+     * stylesheet's, as they already are for `WHY RANK` and `RELATIONSHIPS`, so
+     * the word supplied here reads as a word.
+     */
+    readonly inspector: string;
     /** Shown in the inspector when nothing is selected. */
     readonly nothingSelected: string;
     /**
@@ -72,8 +138,532 @@ export interface WorkspaceWords {
      * command it publishes is `clear`, and that is the whole of its behaviour.
      */
     readonly clearSelection: string;
+    /**
+     * §17k's strip control while the canvas is collapsed — "open the canvas".
+     *
+     * REQUIRED, UNLIKE {@link CanvasWords}, AND THAT IS THE WHOLE REASON IT IS
+     * NOT IN IT. The canvas caption is optional because a surface without it
+     * still draws every fact; this control is the only way back out of §17k's
+     * strip, and a host that omitted it would ship a layout with a zone the
+     * reader cannot reach below `1120`. An unreachable zone is not a degraded
+     * caption.
+     *
+     * IT NAMES THE ZONE, NOT A DIRECTION. The strip is drawn at the canvas's own
+     * track, so "open" and "show" both read as acting on what is beside the word;
+     * the fixture and the demo both say which zone out loud, because a strip four
+     * characters wide, turned on its side, carries no other label.
+     */
+    readonly showCanvas: string;
+    /**
+     * The same control while the canvas is open.
+     *
+     * ITS OWN MEMBER RATHER THAN REUSING {@link showCanvas}, on
+     * {@link RailWords.hide}'s reasoning exactly: the control carries
+     * `aria-expanded`, which flips, and a label that did not flip with it would
+     * tell a screen-reader user the canvas is open and offer to open it in one
+     * breath.
+     */
+    readonly hideCanvas: string;
     /** Names the relationships list. */
     readonly relationships: string;
+    /**
+     * §17a's `WHY RANK n` heading, without the number.
+     *
+     * THE NUMBER IS APPENDED, NOT INTERPOLATED INTO A HOST TEMPLATE. A rank is
+     * the one part of this heading the package knows and the host does not, and
+     * a `{n}` placeholder would make every host reimplement the substitution —
+     * which is how a package that refuses to invent English ends up shipping a
+     * tiny template language instead.
+     */
+    readonly whyRank: string;
+    /**
+     * The same heading for a HELD slot, which has no rank to name.
+     *
+     * A held slot's rank is `null` by construction (`@issuegraph/derive` assigns
+     * `ready ? (rank += 1) : null`), so "why rank —" would be a heading about a
+     * position that does not exist. The design's own §16d ruling is the same one:
+     * a held unit prints the em dash rather than a number.
+     */
+    readonly whyHeld: string;
+    /**
+     * What the rail says when the audit filter is on and NOTHING matched it:
+     * §17's *"No flagged rows match."*
+     *
+     * A SEPARATE STRING FROM EVERY OTHER EMPTY SENTENCE, because it is about a
+     * different world. The others say the order is short; this one says the order
+     * is intact and the view is narrow.
+     */
+    readonly filteredEmpty: string;
+    /**
+     * The count that makes the sentence above unmisreadable: *"8 issues are
+     * ranked"*.
+     *
+     * A FUNCTION, WHICH IS THE ONE PLACE THIS FILE TAKES ONE, and the reason is
+     * the reason `whyRank` refuses to: there the number is APPENDED to a fixed
+     * phrase and a host can write the phrase; here the number sits INSIDE the
+     * sentence and its grammar moves with it — *"1 issue is ranked"* against
+     * *"8 issues are ranked"*. A fixed string plus a number cannot say both, and
+     * a `{n}` placeholder would make every host implement the substitution. So
+     * the host is handed the count and writes its own sentence, in its own
+     * language, with its own plural rule.
+     */
+    readonly filteredDenominator: (ranked: number) => string;
+    /** The way back out, which §17d requires be one click: *"clear the filter"*. */
+    readonly filteredClear: string;
+    /**
+     * What the rail says while the filter is on AND some rows still match.
+     *
+     * A SECOND HEADLINE RATHER THAN A REUSE OF `filteredEmpty`, because they are
+     * opposite statements: that one says nothing matched, this one says the list
+     * is narrowed. Saying "no flagged rows match" above three flagged rows is the
+     * false statement §2 wrote its ruling about.
+     */
+    readonly filteredActive: string;
+    /**
+     * Joins the rest of a together unit: §17a ends *"then worked with #514 as one
+     * unit"*, and this is that phrase minus the members, which the package names.
+     */
+    readonly workedAsOneUnit: string;
+    /**
+     * Stated when the subject has no relationships at all.
+     *
+     * A STATED EMPTY IS NOT THE SAME AS AN ABSENT LIST. The panel used to draw
+     * the `RELATIONSHIPS` heading and then nothing under it, which reads as a
+     * list that failed to load rather than as an issue that is genuinely
+     * unrelated to everything — and "this issue is connected to nothing" is one
+     * of the more actionable things a grooming surface can say.
+     */
+    readonly noRelationships: string;
+    /**
+     * The control that begins a relationship from the selected issue — frame
+     * 17a's `+ add`, publishing `add`.
+     *
+     * MOVED HERE FROM `MountWords`, where it was while the mount drew the button.
+     * `renderWorkspace` is the published surface and the panel is now what draws
+     * it, so a host rendering the markup without mounting gets the control rather
+     * than a panel that can only be read. `MountWords` extends this, so the mount
+     * still reads the same field and no host supplies two.
+     */
+    readonly addRelationship: string;
+    /**
+     * §17a's `ADD RELATIONSHIP` heading, over the numbered kinds.
+     *
+     * NOT {@link WorkspaceWords.addRelationship}, AND THE FRAME IS WHY. That
+     * field is the CONTROL's label — frame 17a writes it `+ add`, on the
+     * relationships header row — and this is the HEADING over the five numbered
+     * choices, which the frame writes in full. They are two strings in the frame
+     * and reusing one for both would put a control's label where a section name
+     * belongs, in a panel whose other two headings are already section names.
+     *
+     * REQUIRED, on the same rule the three header nouns took. An optional field
+     * would draw the heading only for a host that opted in, leaving every other
+     * host with the frame's two moved placements and not its third — a panel that
+     * half-applies the pass this exists to complete. The usual argument for
+     * optional, that a host built against the previous version renders
+     * byte-identically, has nothing to preserve here: this release moves `+ add`
+     * and the kind digits for every host regardless of what it passes.
+     */
+    readonly addRelationshipHeading: string;
+    /**
+     * The control that abandons a draft — frame 17b's escape hatch beside the
+     * numbered kind list, publishing `cancel`.
+     *
+     * MOVED HERE FROM `MountWords` WITH THE STEP IT BELONGS TO. The kind list and
+     * the control that withdraws from it are one affordance; leaving the cancel
+     * in host chrome while the list moved into the package would have split a
+     * control group across two layers, and a draft the reader cannot abandon with
+     * a pointer is the failure `create/keys.ts` names for the keyboard. The
+     * mount's target-search step still reads this field, through the extension.
+     */
+    readonly cancel: string;
+    /**
+     * Names the issue a live draft was begun from, when that is not the panel's
+     * subject — "relating from", read before the reference the package supplies.
+     *
+     * IT EXISTS BECAUSE THE TWO CAN DIVERGE AND THE DRAFT MUST STILL BE
+     * CANCELLABLE. See {@link createStep}: a draft begun by `R` on a together
+     * unit's non-lead member, or one outlived by a change of selection, leaves
+     * the kind step live under a panel headed by a different issue. The step is
+     * drawn anyway — it carries the only pointer cancel there is — so it has to
+     * say whose it is, and the package invents that phrase no more readily than
+     * it invents {@link WorkspaceWords.workedAsOneUnit}. The REFERENCE is the
+     * package's, appended as its own element, so a host writes a phrase and never
+     * a template.
+     */
+    readonly relatingFrom: string;
+    /**
+     * The accessible name of a row's remove control — the `✕` in frame 17a's
+     * right-hand slot.
+     *
+     * ROW-INDEPENDENT WORDING. Which relationship it removes is in the markup
+     * (`data-ig-target`) and in the row the button sits on, not in this string, so
+     * a host writing "remove #488" here would be wrong on every other row.
+     *
+     * DISTINCT FROM `MountWords.deleteRelationship`, which names a different
+     * control: that is the mount's labelled button for the one SELECTED edge, and
+     * this is a glyph button repeated once per row. A glyph carries no name of its
+     * own — see {@link relationshipSpec} — so the two cannot share one string
+     * without one of them reading wrongly.
+     */
+    readonly remove: string;
+    /**
+     * The right-hand marker on an incoming row — frame 17a's `inbound`.
+     *
+     * IT IS A STATED FACT, NOT A MISSING CONTROL. An inbound edge's field lives in
+     * the OTHER issue's body, so this panel's subject cannot declare it away; the
+     * slot says which relationship this is rather than leaving a gap where the
+     * other rows have a `✕`.
+     */
+    readonly inbound: string;
+    /**
+     * The control that reverses a directed relationship — frame 17b's `⇅ flip`.
+     *
+     * MOVED HERE FROM `PickerWords` WITH THE CONTROL ITSELF, on the same rule
+     * that brought `addRelationship` and `cancel` down from `MountWords`: the
+     * surface that draws a control owns the word for it, so a host rendering the
+     * markup without mounting gets the affordance rather than a panel it can only
+     * read. §17b calls direction “the single most common encoding mistake”, which
+     * made this the worst control to have reachable from one rendering path only.
+     *
+     * IT IS NOT #144's MOVE, AND THE DIFFERENCE IS VISIBLE TO EVERY HOST.
+     * `addRelationship` travelled between two interfaces in one `extends` chain,
+     * so `words.addRelationship` read the same before and after. `MountWords`
+     * holds the picker's vocabulary in a NESTED field, so this word's path
+     * changed: `words.picker.flip` became `words.flip`.
+     *
+     * ROW-INDEPENDENT WORDING, exactly as {@link WorkspaceWords.remove} is. Which
+     * relationship it reverses is the selected row it sits in, never this string.
+     */
+    readonly flip: string;
+    /**
+     * Why the store refused an edit, keyed by its code.
+     *
+     * TOTAL OVER `InvalidCode`, so a code the store adds is a compile error in
+     * every host rather than a capsule that renders blank on the one refusal
+     * nobody anticipated. The store's own `InvalidReason.message` is deliberately
+     * not used: it is one sentence in one language chosen by the layer that
+     * detected the refusal, and `overlay/grammar.ts` already records that an
+     * invalid edge's sentence is the host's, keyed off the code.
+     */
+    readonly refusals: Readonly<Record<InvalidCode, string>>;
+    /**
+     * §17b's recovery cards, in the host's own words.
+     *
+     * `retry` AND `retryOnLatest` ARE TWO WORDS BECAUSE THEY ARE TWO CALLS. §17b
+     * names the failed affordance "retry" and the conflict affordance "retry on
+     * latest", and they reach `store.retry` and `store.retryOnLatest`
+     * respectively — the second of which re-reads and ADOPTS the upstream
+     * document as the new base before re-dispatching. One string for both would
+     * make one card lie about what pressing it does, and it would be the card
+     * whose consequence most needs stating.
+     */
+    readonly recovery: RecoveryWords;
+    /**
+     * §17d's findings panel, in the host's own words.
+     *
+     * NESTED, like `recovery` and `refusals` beside it, because it is a record
+     * over a closed class table rather than a loose string — flattening four
+     * chips and four titles into this interface would put eight members here
+     * whose relationship to each other is only legible from their names.
+     */
+    readonly audit: AuditWords;
+    /**
+     * The canvas toolbar's words — frame 17a's caption over the graph.
+     *
+     * OPTIONAL, AND ITS ABSENCE DRAWS NO TOOLBAR, on `change`'s reasoning
+     * exactly: a required member here would break every host built against the
+     * current version, and a default supplied here would be this package writing
+     * an English caption for a host that may not speak English. So a host that
+     * has not worded the row gets the canvas it already had.
+     */
+    readonly canvas?: CanvasWords | undefined;
+    /**
+     * The order rail's footer — frame 17a's `248 with no relationships · show`.
+     *
+     * OPTIONAL, AND ITS ABSENCE DRAWS NO FOOTER, on `canvas`'s reasoning exactly:
+     * a required member here would break every host built against the current
+     * version, and a default supplied here would be this package writing English
+     * for a host that may not speak it.
+     *
+     * IT IS ALSO THE ONE WORDS MEMBER WHOSE PRESENCE MOVES SOMETHING IN ANOTHER
+     * ZONE, and that is worth stating where a host reads it. Supplying this draws
+     * the count and its control at the foot of the rail and turns the canvas
+     * ladder's own chip off, so the surface offers one control rather than two.
+     * The list the control opens is drawn in the CANVAS either way — the rail is
+     * virtualized and cannot hold it; `railFooter` records the arithmetic. The
+     * `isolatedChip` argument at the ladder call records why the two conditions
+     * are safely the same.
+     */
+    readonly rail?: RailWords | undefined;
+}
+/**
+ * Frame 17a's canvas toolbar reads `focus: #512 · 1 hop · 6 of 312 shown`, and
+ * every word in it is the host's.
+ *
+ * NUMBERS ARE APPENDED, NEVER INTERPOLATED, which is why this is four words
+ * rather than one sentence with two `{n}` holes in it. {@link
+ * WorkspaceWords.whyRank} states the doctrine and the reason: a template makes
+ * every host reimplement the substitution. The row is assembled as spans —
+ * `<focus> <key> · <n> <of> <total> <shown>` — so a host whose language orders
+ * those differently is no worse off than it is with `whyRank`, and no host has
+ * to parse a format string.
+ *
+ * THE DOCTRINE IS THIS INTERFACE'S, NOT THE WHOLE PACKAGE'S, and saying
+ * otherwise would be refuted by the markup directly beneath this row. The scale
+ * module writes English with numbers in it — the refusal sentence
+ * (`scale/ladder.ts`), the isolated chip's label, and a literal button label in
+ * `scale/render.ts`. That is a pre-existing inconsistency; the row follows
+ * `WorkspaceWords`' rule because the row is composed in the workspace, and it
+ * neither resolves nor extends the other one.
+ *
+ * THE FRAME'S `1 hop` IS NOT HERE, and its absence is a decision rather than an
+ * omission. `scaleLadder` narrows the canvas to a whole CONNECTED COMPONENT,
+ * not to an n-hop ball around the focus: there is no hop radius in
+ * `ScaleState`, in `ScaleLadder`, or in the viewer's graph projection, and a
+ * component can be ten hops deep. Printing `1 hop` would state a bound the
+ * canvas does not honour — the same defect as a rank the rail is not sure of —
+ * so the row prints what the ladder computed and nothing else.
+ */
+export interface CanvasWords {
+    /**
+     * Leads the focus clause — the frame's `focus:`, minus the colon, which is
+     * punctuation this package draws rather than a word a host translates.
+     */
+    readonly focus: string;
+    /**
+     * Sits between the two counts: the frame's `6 OF 312`.
+     *
+     * ITS OWN MEMBER RATHER THAN PART OF `shown`, because the two numbers
+     * straddle it. Folding it into either neighbour would put a number in the
+     * middle of a host's string, which is the interpolation this interface's
+     * whole shape exists to avoid.
+     */
+    readonly of: string;
+    /** Trails the counts — the frame's `6 of 312 SHOWN`. */
+    readonly shown: string;
+    /**
+     * The trailing pill — the frame's `edit mode`.
+     *
+     * A STATE, NOT A CONTROL. The workspace is the editing surface and there is
+     * no read-only workspace to toggle into, so this names what the reader is
+     * looking at rather than offering to change it. It is drawn as text, never as
+     * a button, because a pill that looked pressable and did nothing is the dead
+     * control `headerControls` refuses to draw.
+     *
+     * OPTIONAL AND SEPARATELY SO, on `headerControls`' own reasoning rather than
+     * on this group's. `renderWorkspace` returns markup, and markup can be served
+     * without `mountWorkspace` — nothing on such a surface is editable, so a pill
+     * asserting that it is would be a claim the render layer cannot honour. The
+     * host knows which it built, so the host says: supply this only where the
+     * surface was mounted. Absent, the caption still draws and the pill does not.
+     */
+    readonly editMode?: string | undefined;
+}
+/**
+ * Frame 17a's rail footer reads `248 with no relationships · show`, and every
+ * word in it is the host's.
+ *
+ * NUMBERS ARE APPENDED, NEVER INTERPOLATED — {@link CanvasWords} states the
+ * doctrine and {@link WorkspaceWords.whyRank} the reason. The row is assembled
+ * as spans, `<count> <isolated>`, so a host is never handed a format string.
+ *
+ * `IsolatedChip.label` IS NOT REUSED, and the reason is the one `CanvasWords`
+ * already records: the scale module writes English with numbers in it, that is
+ * a pre-existing inconsistency, and a row composed in the workspace follows the
+ * workspace's rule rather than inheriting it. Reusing the label here would have
+ * been the cheaper line and would have imported the defect.
+ */
+export interface RailWords {
+    /** Trails the count — the frame's `248 WITH NO RELATIONSHIPS`. */
+    readonly isolated: string;
+    /** The toggle while the list is closed — the frame's `show`. */
+    readonly show: string;
+    /**
+     * The toggle while the list is open.
+     *
+     * ITS OWN MEMBER RATHER THAN REUSING `show`. The control carries
+     * `aria-expanded`, which flips; a label that did not flip with it would tell
+     * a screen-reader user the list is open and offer to open it in one breath.
+     */
+    readonly hide: string;
+}
+export interface RecoveryWords {
+    /** Names the state on a failed card. */
+    readonly failed: string;
+    /** Names the state on a conflicted card. */
+    readonly conflict: string;
+    readonly viewDiff: string;
+    /** `failed` → `store.retry`. */
+    readonly retry: string;
+    /** `conflict` → `store.retryOnLatest`, which adopts upstream as the new base. */
+    readonly retryOnLatest: string;
+    readonly discardMine: string;
+    /** Heads the edges the held document has and the reader's does not. */
+    readonly upstreamOnly: string;
+    /** Heads the reader's own unlanded edit, where it ADDS a relationship. */
+    readonly mineOnly: string;
+    /** Heads the reader's own unlanded edit, where it REMOVES one. */
+    readonly mineRemoved: string;
+    /** Heads relationships both sides hold pointing opposite ways. */
+    readonly carrierReversed: string;
+    /** Heads the issues the two documents disagree about. */
+    readonly issuesChanged: string;
+    /** Shown when the diff has nothing to show on THIS panel. */
+    readonly diffEmpty: string;
+    /**
+     * Why a `retry on latest` could not even read.
+     *
+     * The store's refresh is half of one operation: when it fails the record is
+     * restored verbatim and nothing is dispatched, so without this the button
+     * reads as dead on exactly the failure the store went to trouble to make
+     * observable.
+     */
+    readonly retryFailed: string;
+    /**
+     * Heads the region for recoveries with no panel to sit on.
+     *
+     * See {@link WorkspaceRecovery.carrier}: a write about issues this backlog
+     * does not hold has no panel, and dropping it would leave the reader's work
+     * unrecoverable.
+     */
+    readonly unplaced: string;
+}
+/**
+ * One unsettled write the reader can still act on: §17b's `failed` and
+ * `conflict`.
+ *
+ * NARROW FOR THE REASON {@link WorkspaceRefusal} IS, and shaped the same way.
+ * The whole write ledger is the larger surface this deliberately is not: a
+ * `WriteRecord` carries a `Mutation` and, on a conflict, an entire second
+ * `GraphDocument`, none of which a renderer can draw. What a card needs is the
+ * state, the reason or the difference, and which panel states it.
+ *
+ * A UNION, BECAUSE THE TWO STATES CARRY DIFFERENT FACTS. `WriteRecord` is
+ * already a union on this exact line. Two optionals would admit a conflict with
+ * no diff and a failure with one, and the renderer would need a runtime guard
+ * for a case the type can refuse outright.
+ *
+ * NO `phantom` EQUIVALENT, and the absence is deliberate rather than an
+ * oversight. {@link WorkspaceRefusal.phantom} exists because a refusal either
+ * JOINS a relationship row or REPLACES it, and getting that wrong deletes a
+ * removable relationship from the panel. A recovery card is its own element in
+ * its own region and replaces nothing, so the question does not arise.
+ */
+export type WorkspaceRecovery = {
+    readonly kind: 'failed';
+    readonly mutationId: MutationId;
+    readonly edgeId: EdgeId;
+    readonly carrier: string | null;
+    /**
+     * The adapter's own sentence, verbatim.
+     *
+     * NOT KEYED OFF A CODE, and the asymmetry with {@link
+     * WorkspaceWords.refusals} is the argument. The store's refusal codes are
+     * a CLOSED set the store owns, so a host can be made total over them. An
+     * adapter's failure is an open one — a status, a rate limit, a network
+     * message — and there is no code to key on, so the sentence travels.
+     */
+    readonly reason: string;
+} | {
+    readonly kind: 'conflict';
+    readonly mutationId: MutationId;
+    readonly edgeId: EdgeId;
+    readonly carrier: string | null;
+    /** Both sides, held apart. See `recovery.ts`. */
+    readonly diff: ConflictDiff;
+    /**
+     * Why the last refresh could not read, or `null`.
+     *
+     * A `retry on latest` whose READ fails restores the record exactly as it
+     * was and dispatches nothing — the conflict keeps its held document so it
+     * can still be compared against. Without this the card re-renders
+     * identically and the button reads as dead.
+     */
+    readonly refreshError: string | null;
+};
+/**
+ * One refused edit, as the panel needs it: which edge, and why.
+ *
+ * NARROW ON PURPOSE, AND THE NARROWNESS IS THE ARGUMENT. `WorkspaceOptions.projected`
+ * already carries every edge's states, and `invalid` is among them — but a
+ * state says an edge was refused and never says why, because the code lives on
+ * `WriteRecord.reason`, which reaches no renderer. The alternative was to hand
+ * the panel the whole write ledger, which is the input #137's conflict cards
+ * need and is a much larger surface: both versions of a conflicted body, the
+ * upstream document, the retry and discard affordances. This is one code per
+ * edge id, derivable in a shell from what the store already publishes, and
+ * nothing here is blocked on that larger shape.
+ */
+export interface WorkspaceRefusal {
+    readonly edgeId: EdgeId;
+    readonly code: InvalidCode;
+    /**
+     * The issue whose panel states this refusal.
+     *
+     * THE EDIT'S OWN SUBJECT, DECIDED BY WHOEVER MADE THE EDIT. This panel used
+     * to work it out for itself, by asking whether the refused edge's identity
+     * named the issue on show — a derivation entirely separate from the one that
+     * produced the subject, and free to disagree with it. It did, three times
+     * over: an unfiltered orphan branch drew every refusal on every panel; a
+     * retype whose projection hid the edge the panel was filtered to left the
+     * panel with no subject and the reason nowhere; and a draft begun from a
+     * together-unit partner produced an edge naming the partner while
+     * `inspectorView` had canonicalized the panel onto the slot's lead, so
+     * nothing matched. None of the three is a question this renderer can answer
+     * from an identity, because none of them is about the identity.
+     *
+     * A MOUNT KNOWS IT WITHOUT GUESSING, BECAUSE IT WROTE IT DOWN. `editCarrier`
+     * in `host.ts` answers it — for a create from a draft, for a retype or flip
+     * whose produced identity differs from the one the reader named, and for a
+     * delete — and `mountWorkspace` asks it as the edit goes OUT, while the
+     * document still holds the relationship, then keeps the answer against the
+     * write. It cannot be asked again afterwards: by the time a refusal comes
+     * back a sibling write may have removed the edge, and an identity records
+     * which two issues a relationship was between and never which of them
+     * declared it. A host rendering without `mountWorkspace` states the same fact
+     * the same way: whichever issue's panel it wants the refusal read on, decided
+     * when it made the edit.
+     *
+     * NOT DERIVABLE FROM {@link WorkspaceRefusal.edgeId}, which is why it is a
+     * second field rather than a lookup. `unknown-issue` names an issue the
+     * document does not hold; `unknown-edge` names an edge it does not hold; and
+     * a together unit's panel is headed by a key the edge may never mention.
+     */
+    readonly carrier: string;
+    /**
+     * Whether the edge this refusal marks exists only because the refusal does.
+     *
+     * NOT EVERY REFUSAL IS ABOUT AN EDIT THAT LEFT NO TRACE, and reading them as
+     * if they were deleted a relationship the reader still has. Three of the
+     * store's codes mark an edge that is already LANDED — measured against the
+     * store rather than reasoned from the code list: `duplicate-edge` (a create
+     * of a relationship that exists; `project` folds the phantom onto the real
+     * edge), and `unchanged-kind` and `symmetric-edge` (a retype or flip whose
+     * result has the identity it started from, so `edgeChangeFor` marks the
+     * original rather than swapping it). `cardinality` looks like a fourth and is
+     * not: through a create it marks the edge it would have made, and through a
+     * retype it marks the edge it would have BECOME — a phantom either way, with
+     * the original hidden — which is exactly why this is asked of the document
+     * rather than keyed off a list of codes. With the capsule REPLACING the row
+     * for all of them, telling a reader "this relationship is already declared"
+     * removed the declared relationship's row from the panel, remove control
+     * included — so the one message they were given was contradicted by the list
+     * beside it, and nothing on the surface could undo the edge they had just
+     * been told about.
+     *
+     * TRUE MEANS THE ROW IS THE REFUSAL. A refused CREATE of a genuinely new
+     * relationship draws as a capsule in the row it would have been: there is no
+     * relationship to operate, and a `select-edge` and a `✕` on it would offer to
+     * remove something that was never added. False means the relationship is
+     * real, so the row stands and the reason is attached to it.
+     *
+     * REQUIRED, BECAUSE NEITHER DEFAULT IS SAFE. Defaulted to `true` the panel
+     * eats real rows; defaulted to `false` it draws a live remove control for an
+     * edge the document does not have. A host derives it in one line — the
+     * refused id is in `snapshot.landed` or it is not — and the store's own
+     * projection is where both halves already come from.
+     */
+    readonly phantom: boolean;
 }
 export interface WorkspaceOptions {
     /**
@@ -81,11 +671,43 @@ export interface WorkspaceOptions {
      * not invent an English sentence, and a default would be one.
      */
     readonly words: WorkspaceWords;
+    /**
+     * The store's `lastChange` — what the last landed edit did to the order.
+     *
+     * ABSENT MEANS NO EDIT HAS LANDED TO REPORT, which is not the same as an edit
+     * that landed and moved nothing. The second is a `change` whose summary is
+     * `unchanged`, and §17c draws it in the summary's own place because "landed
+     * and moved nothing" is the finding an owner auditing an encoding most needs.
+     */
+    readonly change?: OrderChange | null | undefined;
+    /**
+     * The store's `order.status`. `held` labels the rail and greys it one step.
+     *
+     * THE RANKS DRAWN ARE STILL THE ONES THE CALLER VOUCHED FOR. This says the
+     * order is being re-evaluated; it does not re-rank anything, and nothing in
+     * this render moves a row because a write is in flight. §122's rule —
+     * optimistic rendering yes, optimistic re-ORDERING no — is held by there
+     * being no code path here that reorders at all.
+     */
+    readonly orderStatus?: OrderStatus | undefined;
     readonly selection?: WorkspaceSelection | undefined;
     /** The ladder's reader position — search, focus, opened isolates. */
     readonly scale?: ScaleState | undefined;
     /** Which slice of the order the rail draws. See {@link railWindow}. */
     readonly rail?: RailWindowOptions | undefined;
+    /**
+     * The rail rows whose provenance is open, by lead key.
+     *
+     * §16f's `→ expands provenance` names a per-row state, and the VIEWER CANNOT
+     * HOLD ONE: it is a pure renderer, re-run from scratch on every change. So
+     * the host owns the set and hands it back in, exactly as `selection` is.
+     *
+     * ONLY THE RAIL READS IT. The canvas draws stations rather than rows and has
+     * no provenance to open, and §17j already shows provenance inline on the wide
+     * panel — where the expand affordance would be a control for something
+     * already visible.
+     */
+    readonly expanded?: readonly string[] | undefined;
     /**
      * The audit's input, when the host has one.
      *
@@ -108,6 +730,73 @@ export interface WorkspaceOptions {
      * Ignored with no audit, because there is nothing to filter by.
      */
     readonly auditFiltered?: boolean | undefined;
+    /**
+     * Whether §17d's audit overlay is open.
+     *
+     * SEPARATE FROM `auditFiltered`, and they used to be one thing. The header
+     * count was the filter toggle; `RULINGS.md` §3 makes it this overlay's anchor
+     * and moves the filter into the panel head, so the two states are now two
+     * questions: which rows the rail shows, and whether the panel is on screen.
+     *
+     * Ignored with no audit, because there is no panel to open.
+     */
+    readonly auditOpen?: boolean | undefined;
+    /**
+     * Whether §17k's collapsed canvas has been opened — `HostState.canvasOpen`.
+     *
+     * PUBLISHED AS AN ATTRIBUTE ON THE SURFACE ROOT, and read only by the
+     * stylesheet's narrow block. Nothing here decides whether the canvas IS a
+     * strip: that is a question about the box the surface was given, the
+     * container query is the only party that can answer it, and §17k's
+     * implementation note is explicit that the package must not ask the window
+     * instead. So this says what the reader asked for and the sheet says whether
+     * it is currently drawn.
+     *
+     * Absent means shut, which is §17k's resting state for the strip.
+     */
+    readonly canvasOpen?: boolean | undefined;
+    /**
+     * Whether the reader has dismissed §17k's lifted inspector —
+     * `HostState.inspectorDismissed`.
+     *
+     * COMBINED WITH THE SELECTION, NEVER READ ALONE. §17k opens the lifted panel
+     * "by selection", so the attribute this becomes is `lifted` only when
+     * something is selected AND the reader has not pressed Escape since. A render
+     * with nothing selected draws the panel dismissed however this is set, which
+     * is what keeps an empty "nothing selected" card from floating over the
+     * canvas at the middle width.
+     *
+     * Ignored at the two other widths, where the inspector is a zone.
+     */
+    readonly inspectorDismissed?: boolean | undefined;
+    /**
+     * Take over §17j's rail density, instead of letting the rail's own box decide.
+     *
+     * FORWARDED, NOT INVENTED. `@issuegraph/viewer` owns the rule and the
+     * default: the rail reads its density off the column it was given, and the
+     * crossover it uses — `430px` — is that package's default rather than a
+     * figure Design published. This exists so a consumer of the EDITOR can reach
+     * the same escape hatch without rendering the rail themselves.
+     *
+     * THE WORKSPACE ITSELF NEEDS IT FOR NOTHING. §17k holds the rail at one
+     * measure now — 390 at every width, which is the rule §17k states outright —
+     * so this surface never crosses the threshold and never has an opinion. It is
+     * threaded for the host's sake, and absent it changes nothing.
+     */
+    readonly railDensity?: 'dense' | 'wide' | undefined;
+    /**
+     * Where an issue lives in the host's own world, for §17d's refused block.
+     *
+     * THE HOST'S ANSWER BECAUSE IT IS THE ONLY PARTY THAT HAS ONE. A store ref is
+     * opaque in here and this package holds no repository identity, so a URL is
+     * supplied rather than derived. Absent, `null`, or a scheme the viewer's
+     * allowlist refuses all mean the same thing — no link is drawn. See
+     * {@link EncodingRefusedBlockOptions.issueUrl}, which owns that rule and the
+     * reason an `href` cannot be trusted to escaping alone.
+     *
+     * Ignored with no audit, because a refusal arrives on the audit's input.
+     */
+    readonly issueUrl?: EncodingRefusedBlockOptions['issueUrl'];
     readonly theme?: Theme | undefined;
     /** The selector the theme's custom properties are written onto. */
     readonly themeSelector?: string | undefined;
@@ -115,8 +804,96 @@ export interface WorkspaceOptions {
      * The store's projection, for the canvas to draw each edge's write states.
      * See `ScaleLadderOptions.projected`; the workspace forwards it and reads
      * none of it, because the rail and the inspector draw no line to overlay.
+     *
+     * AND IT IS NOT WHERE THE INSPECTOR'S REFUSALS COME FROM, which is worth
+     * saying here because it is the obvious place to look. A `ProjectedEdge`
+     * carries `states` and `writes` — so it says an edge is `invalid` and never
+     * says why. The code is on the write record, and the panel takes it through
+     * {@link WorkspaceOptions.refusals}.
      */
     readonly projected?: readonly ProjectedEdge[] | undefined;
+    /**
+     * The create draft in flight, so the panel can draw the step the reader is on.
+     *
+     * §17b's inspector path is `+ add` → kind → target, and `create/draft.ts`
+     * makes `begin` RESET the kind and the target on purpose. An always-visible
+     * kind list would therefore let a reader fill a slot that the next `+ add`
+     * silently discards, so the list is drawn only while a draft is live —
+     * which the panel cannot know without being told.
+     *
+     * Absent means idle, which is the state a host that has no create path is in.
+     */
+    readonly draft?: CreateDraft | undefined;
+    /**
+     * Where a canvas drop landed, or `null`. Read for its NULLNESS alone.
+     *
+     * THE PANEL SUPPRESSES ITS KIND LIST WHILE A DROP IS LIVE, which is the
+     * invariant that keeps the two choosers mutually exclusive. A drag that ends
+     * on the canvas opens a chooser AT THE DROP POINT; a panel list drawn at the
+     * same moment would be a second copy of the same step, one under the
+     * reader's pointer and one in the column beside it, both writing to the one
+     * draft. The shell held that rule alone while it drew both, and it cannot
+     * hold it any more now that one of them is package markup.
+     *
+     * The host's own value is forwarded rather than a boolean derived from it:
+     * a `dropInFlight: boolean` would be a second spelling of a fact the shell
+     * already holds, free to disagree with it on the render where it matters.
+     */
+    readonly drop?: Point | null | undefined;
+    /**
+     * The edits the store refused, so the panel can say so where the reader made
+     * them. See {@link WorkspaceRefusal}.
+     *
+     * IN THE ORDER THE STORE RECORDED THEM, and that is part of the contract
+     * rather than an accident of how a caller happened to build it. One row
+     * states one reason, so two refusals naming one edge collapse to the LAST —
+     * the one the reader just caused, rather than the one they have read and
+     * moved past. A caller assembling this from two passes and concatenating
+     * them loses that chronology at the join; `mountWorkspace` walks
+     * `snapshot.writes` once for exactly this reason.
+     *
+     * ABSENT MEANS "NOTHING REFUSED", which is unlike {@link WorkspaceOptions.audit}
+     * and is safe for the reason that one is not: a refusal is a fact the store
+     * produces, so a host with no refusals to report and a host that never asked
+     * are in the same position — there is nothing to draw either way. An audit
+     * count is a NUMBER, and inventing a zero for one nobody computed is the
+     * distinction that option exists to keep.
+     */
+    readonly refusals?: readonly WorkspaceRefusal[] | undefined;
+    /**
+     * The failed and conflicted writes the reader can still act on.
+     *
+     * OPTIONAL, on the same reasoning as {@link WorkspaceOptions.refusals}: an
+     * unsettled write is a fact the store produces, so "none" and "never asked"
+     * leave the panel with the same nothing to draw.
+     */
+    readonly recoveries?: readonly WorkspaceRecovery[] | undefined;
+    /**
+     * Which conflict has its difference open, if any.
+     *
+     * ONE AT A TIME, because the region is inside a panel rather than a dialog.
+     * The shell holds it for the reason `auditFiltered` is held: the card
+     * publishes a toggle, so something has to carry its state or every render
+     * answers "closed" and the control cannot complete what it advertises.
+     */
+    readonly diffOpen?: MutationId | null | undefined;
+    /**
+     * A value unique to this surface, used to bind §17a's rail footer to the
+     * isolated list the canvas draws.
+     *
+     * SUPPLIED BY WHOEVER KNOWS THE PAGE. The footer's toggle and the list are in
+     * different zones, so the toggle names the list with `aria-controls` — and an
+     * id invented in here would be emitted twice by a host rendering two
+     * workspaces, leaving the second toggle pointing at the first surface's list.
+     * `scale/render.ts`'s `searchSpec` records the same hazard for its own label.
+     *
+     * ABSENT, NO ASSOCIATION IS DRAWN, and that is the honest default rather than
+     * a degraded one: `mountWorkspace` mints a value per mount, and markup served
+     * WITHOUT a mount is not operable anyway — the same argument
+     * `CanvasWords.editMode` is optional under. A toggle nobody can press needs no
+     * `aria-controls`.
+     */
+    readonly surfaceId?: string | undefined;
 }
 export interface WorkspaceView {
     readonly selection: WorkspaceSelection;