@issuegraph/editor 0.1.0

package/dist/overlay/grammar.d.ts

@@ -0,0 +1,259 @@
+/**
+ * The edge mutation-state grammar, as data.
+ *
+ * `@issuegraph/store` already ships the state MODEL — `EDGE_STATES`,
+ * `edgeStateOf`, `project` and a `ProjectedEdge` that carries a *list* of
+ * states. What was missing is the grammar that draws them, and this is it.
+ *
+ * ## Overlay, not variant — and why that is a property of this table
+ *
+ * The design's §17b: *"An edge keeps its type identity (dash + terminal + glyph
+ * + hue) and gains a state OVERLAY, so a pending `blocked-by` is still
+ * recognisably `blocked-by` and combinations need no new symbols."*
+ *
+ * Five states and five relationships would be twenty-five hand-drawn cases if a
+ * state were a variant of an edge. It is not one here: the viewer's
+ * `treatmentFor` supplies the kind on four channels, and this table supplies
+ * the state on channels of its own, so a `selected` `pending-write`
+ * `blocked-by` composes from three independent sources rather than being a
+ * twenty-sixth entry somewhere. That is the same construction `vocabulary.ts`
+ * uses for `EDGE_TREATMENTS`, and it is what AGENTS.md's branching-boundary
+ * rule asks for: the treatments are a table keyed on state, never a switch.
+ *
+ * It is declared `satisfies Record<EdgeState, OverlayTreatment>` so a sixth
+ * state added to the store fails the BUILD here, rather than rendering as an
+ * untreated line nobody notices.
+ *
+ * ## Two channels, and the reason they cannot be one
+ *
+ * `selected` is *"the only state that is not about a write"*, and it is drawn
+ * as a halo — a mark beside the line rather than a change to it. Every other
+ * state paints the line itself. Those are different channels, so a selected
+ * pending edge shows both and neither has to win.
+ *
+ * The write states DO compete for the one line, which is why {@link
+ * OverlayTreatment.precedence} exists. Two unsettled edits can mark one edge —
+ * `project` accumulates a state per record — so "which treatment does the line
+ * take" is a real question with a real answer, and the answer is declared as a
+ * number in the table instead of being decided by a comparison written out in
+ * code. A reader can see the whole ordering at once, and adding a state means
+ * choosing its rank rather than finding the branch that ranks things.
+ *
+ * ## What this module will not do
+ *
+ * - **It never re-evaluates the order.** `pending-write` is an optimistic
+ *   *draw*; the order does not move until the write lands. Nothing here imports
+ *   a deriver, and nothing here can.
+ * - **It never invents state.** `invalid` carries the store's `InvalidCode` and
+ *   nothing else — the sentence beside the ghost is the host's, keyed off the
+ *   code, for the same reason `change.ts` ships counts rather than prose.
+ * - **It never replaces a terminal.** The four redundant channels have to
+ *   survive every overlay, so the mark vocabulary below has no member that
+ *   occupies the terminal's place. `failed` ADDS a ✕ beside the type's own
+ *   marker rather than standing in for it.
+ */
+import { type EdgeId, type EdgeState, type ProjectedEdge } from '@issuegraph/store';
+/**
+ * What a state does to the edge's own stroke.
+ *
+ * `halo` is the odd one and is deliberately in the same vocabulary: it is a
+ * second stroke drawn behind the line, so naming it here keeps "what happens to
+ * the line" answerable from one field.
+ *
+ * `doubled` is drawn by the COMPOSER, not by `attachEdgeOverlays`. A second
+ * version has to sit beside the line, and "beside" is the path's perpendicular
+ * — geometry this layer does not have. So it is declared here and carried by
+ * the `second-version` mark, and `grammar.test.ts` holds the two together so
+ * the field cannot become a claim nothing renders.
+ */
+export type OverlayStroke = 'none' | 'halo' | 'ghost' | 'doubled';
+/** A dash the overlay lays over the edge, on top of the kind's own pattern. */
+export type OverlayDash = 'marching' | 'dotted';
+/**
+ * A mark the overlay adds. Every one is ADDITIVE — see the module note.
+ *
+ * `node-chip` sits on both endpoints rather than on the line, which is what
+ * §17b specifies: a write is about the pair, and a chip on the line alone is
+ * unreadable once the line is short.
+ */
+export type OverlayMark = 'node-chip' | 'terminal-cross' | 'inline-reason' | 'second-version';
+/**
+ * What a host may offer for a state.
+ *
+ * There is deliberately no `merge`. §17b is explicit that a conflict offers
+ * view-diff, retry-on-latest and discard-mine and **never** auto-merges, so the
+ * absence is encoded in the vocabulary rather than left to a reviewer to
+ * notice: a merge affordance cannot be spelled, not merely should not be.
+ */
+export type OverlayAffordance = 'retry' | 'discard-mine' | 'view-diff';
+export interface OverlayTreatment {
+    readonly stroke: OverlayStroke;
+    /** The dash laid over the kind's own, or `null` when the state adds none. */
+    readonly dash: OverlayDash | null;
+    /**
+     * The opacity the state draws the edge at, or `null` at full strength.
+     *
+     * A number rather than a token because it is not a colour: opacity is
+     * structural, and a host retheming the palette does not re-decide how ghostly
+     * a refused edge is.
+     */
+    readonly opacity: number | null;
+    /**
+     * The custom property carrying this state's hue, or `null` when it adds none.
+     * Never a literal colour, and never an `--ig-edge-*` token: those name what an
+     * edge IS, and spending one here would make a host retheming a relationship
+     * silently recolour a state.
+     */
+    readonly hueToken: string | null;
+    readonly marks: readonly OverlayMark[];
+    readonly affordances: readonly OverlayAffordance[];
+    /**
+     * Which treatment the LINE takes when several write states mark one edge.
+     * Higher wins. `selected` sits on its own channel and is given `0` because it
+     * never competes — see the module note.
+     */
+    readonly precedence: number;
+    /** Announced to a screen reader. The one place this package names a state. */
+    readonly label: string;
+}
+/**
+ * The five states, drawn.
+ *
+ * The precedence order reads: a conflict outranks a rejection outranks a
+ * refusal outranks an edit still in flight. It is severity order, and it is
+ * also *settledness* order — the further a write got from succeeding, the more
+ * the line should say so.
+ */
+export declare const OVERLAY_TREATMENTS: Readonly<{
+    readonly selected: {
+        readonly stroke: "halo";
+        readonly dash: null;
+        readonly opacity: null;
+        readonly hueToken: "--ig-focus";
+        readonly marks: readonly [];
+        readonly affordances: readonly [];
+        readonly precedence: 0;
+        readonly label: "selected";
+    };
+    readonly 'pending-write': {
+        readonly stroke: "none";
+        readonly dash: "marching";
+        readonly opacity: 0.7;
+        readonly hueToken: null;
+        readonly marks: readonly ["node-chip"];
+        readonly affordances: readonly [];
+        readonly precedence: 1;
+        readonly label: "writing";
+    };
+    readonly invalid: {
+        readonly stroke: "ghost";
+        readonly dash: "dotted";
+        readonly opacity: 0.5;
+        readonly hueToken: "--ig-state-invalid";
+        readonly marks: readonly ["inline-reason"];
+        readonly affordances: readonly ["discard-mine"];
+        readonly precedence: 2;
+        readonly label: "invalid";
+    };
+    readonly failed: {
+        readonly stroke: "ghost";
+        readonly dash: null;
+        readonly opacity: 0.5;
+        readonly hueToken: "--ig-state-failed";
+        readonly marks: readonly ["terminal-cross"];
+        readonly affordances: readonly ["retry", "discard-mine"];
+        readonly precedence: 3;
+        readonly label: "failed";
+    };
+    readonly conflict: {
+        readonly stroke: "doubled";
+        readonly dash: null;
+        readonly opacity: null;
+        readonly hueToken: "--ig-state-conflict";
+        readonly marks: readonly ["second-version"];
+        readonly affordances: readonly ["view-diff", "retry", "discard-mine"];
+        readonly precedence: 4;
+        readonly label: "conflict";
+    };
+}>;
+/**
+ * The alpha the selection halo is drawn at.
+ *
+ * IT LIVES HERE, BESIDE THE TABLE, AND NOT IN THE STYLESHEET — which is where
+ * it started, and that is the whole reason it is worth a named export.
+ *
+ * `styles.ts` already carried the rule that a state's opacity belongs to this
+ * table because a second copy would drift. The halo broke that rule quietly: it
+ * is not a state opacity, so it was written as a CSS declaration instead, and
+ * `grammar.test.ts`'s composited-contrast check reads this table — so the one
+ * alpha the check could not see was the one that failed. At 0.35 the halo
+ * measured about 2.0:1 on the dark surfaces and 1.75:1 on the light ones, under
+ * the 3:1 non-text bar, while every assertion stayed green.
+ *
+ * 0.75 clears the bar on both documented themes with margin. The halo is the
+ * selection cue; if it is not legible, selection is not visible.
+ */
+export declare const HALO_OPACITY = 0.75;
+/**
+ * Every (token, alpha) pair this package composites, as data.
+ *
+ * The contrast claim is about what LANDS on the surface, so it has to range
+ * over the alphas actually applied — and an alpha that is not in this list is
+ * one the check cannot see. Deriving the list rather than writing it by hand is
+ * what stops a third opacity appearing somewhere and going unmeasured.
+ */
+export declare function compositedHues(): readonly {
+    token: string;
+    alpha: number;
+}[];
+/** The treatment for a state. Total over the store's state set. */
+export declare function treatmentForState(state: EdgeState): OverlayTreatment;
+/** The attribute an overlaid edge announces its states on. */
+export declare const STATE_ATTRIBUTE = "data-ig-state";
+/**
+ * One edge's overlay: every state it carries, resolved into what to draw.
+ *
+ * The states are kept alongside the resolution rather than thrown away, because
+ * a host writing an accessible name needs all of them — "selected, writing" —
+ * while the line can only be drawn one way.
+ */
+export interface EdgeOverlay {
+    readonly edgeId: EdgeId;
+    /** Every state, in `EDGE_STATES` order. Empty for an edge with no overlay. */
+    readonly states: readonly EdgeState[];
+    /**
+     * The treatment the LINE takes — the highest-precedence write state, or
+     * `null` when the edge carries none. `selected` is not a candidate here.
+     */
+    readonly line: OverlayTreatment | null;
+    /** Whether the selection halo is drawn. Orthogonal to {@link line}. */
+    readonly halo: boolean;
+    /** Every mark owed, in state order, de-duplicated. */
+    readonly marks: readonly OverlayMark[];
+    /** Every affordance offered, in state order, de-duplicated. Never a merge. */
+    readonly affordances: readonly OverlayAffordance[];
+    /** The value for {@link STATE_ATTRIBUTE}: the states, space separated. */
+    readonly attribute: string | null;
+}
+/**
+ * Fold an edge's states into one overlay.
+ *
+ * `ProjectedEdge.states` already arrives in `EDGE_STATES` order — `project`
+ * canonicalises it so two projections of the same state compare equal — and
+ * this preserves that order rather than re-sorting, so a host memoising on the
+ * attribute string is not defeated by a second ordering rule appearing here.
+ */
+export declare function overlayFor(edge: ProjectedEdge): EdgeOverlay;
+/**
+ * The accessible name for an overlaid edge, given the viewer's own name for it.
+ *
+ * The kind's sentence leads and the states follow, because the relationship is
+ * what the edge IS and the state is what is happening to it. A reader who stops
+ * after the first clause still has the fact.
+ *
+ * This is the ONLY English this module produces, and it is state names rather
+ * than a reason: an `invalid` edge's sentence is the host's, keyed off the
+ * store's `InvalidCode`.
+ */
+export declare function overlayLabel(base: string, overlay: EdgeOverlay): string;
+//# sourceMappingURL=grammar.d.ts.map

package/dist/overlay/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/overlay/grammar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAe,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEjG;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAElE,+EAA+E;AAC/E,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,gBAAgB,GAAG,eAAe,GAAG,gBAAgB,CAAC;AAE9F;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,cAAc,GAAG,WAAW,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyD0B,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAa5E;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,GAAG,gBAAgB,CAEpE;AAED,8DAA8D;AAC9D,eAAO,MAAM,eAAe,kBAAkB,CAAC;AAE/C;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACvC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACnD,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,WAAW,CA6B3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAGvE"}

package/dist/overlay/grammar.js

@@ -0,0 +1,223 @@
+/**
+ * The edge mutation-state grammar, as data.
+ *
+ * `@issuegraph/store` already ships the state MODEL — `EDGE_STATES`,
+ * `edgeStateOf`, `project` and a `ProjectedEdge` that carries a *list* of
+ * states. What was missing is the grammar that draws them, and this is it.
+ *
+ * ## Overlay, not variant — and why that is a property of this table
+ *
+ * The design's §17b: *"An edge keeps its type identity (dash + terminal + glyph
+ * + hue) and gains a state OVERLAY, so a pending `blocked-by` is still
+ * recognisably `blocked-by` and combinations need no new symbols."*
+ *
+ * Five states and five relationships would be twenty-five hand-drawn cases if a
+ * state were a variant of an edge. It is not one here: the viewer's
+ * `treatmentFor` supplies the kind on four channels, and this table supplies
+ * the state on channels of its own, so a `selected` `pending-write`
+ * `blocked-by` composes from three independent sources rather than being a
+ * twenty-sixth entry somewhere. That is the same construction `vocabulary.ts`
+ * uses for `EDGE_TREATMENTS`, and it is what AGENTS.md's branching-boundary
+ * rule asks for: the treatments are a table keyed on state, never a switch.
+ *
+ * It is declared `satisfies Record<EdgeState, OverlayTreatment>` so a sixth
+ * state added to the store fails the BUILD here, rather than rendering as an
+ * untreated line nobody notices.
+ *
+ * ## Two channels, and the reason they cannot be one
+ *
+ * `selected` is *"the only state that is not about a write"*, and it is drawn
+ * as a halo — a mark beside the line rather than a change to it. Every other
+ * state paints the line itself. Those are different channels, so a selected
+ * pending edge shows both and neither has to win.
+ *
+ * The write states DO compete for the one line, which is why {@link
+ * OverlayTreatment.precedence} exists. Two unsettled edits can mark one edge —
+ * `project` accumulates a state per record — so "which treatment does the line
+ * take" is a real question with a real answer, and the answer is declared as a
+ * number in the table instead of being decided by a comparison written out in
+ * code. A reader can see the whole ordering at once, and adding a state means
+ * choosing its rank rather than finding the branch that ranks things.
+ *
+ * ## What this module will not do
+ *
+ * - **It never re-evaluates the order.** `pending-write` is an optimistic
+ *   *draw*; the order does not move until the write lands. Nothing here imports
+ *   a deriver, and nothing here can.
+ * - **It never invents state.** `invalid` carries the store's `InvalidCode` and
+ *   nothing else — the sentence beside the ghost is the host's, keyed off the
+ *   code, for the same reason `change.ts` ships counts rather than prose.
+ * - **It never replaces a terminal.** The four redundant channels have to
+ *   survive every overlay, so the mark vocabulary below has no member that
+ *   occupies the terminal's place. `failed` ADDS a ✕ beside the type's own
+ *   marker rather than standing in for it.
+ */
+import { EDGE_STATES } from '@issuegraph/store';
+/**
+ * The five states, drawn.
+ *
+ * The precedence order reads: a conflict outranks a rejection outranks a
+ * refusal outranks an edit still in flight. It is severity order, and it is
+ * also *settledness* order — the further a write got from succeeding, the more
+ * the line should say so.
+ */
+export const OVERLAY_TREATMENTS = Object.freeze({
+    selected: {
+        stroke: 'halo',
+        dash: null,
+        opacity: null,
+        hueToken: '--ig-focus',
+        marks: [],
+        affordances: [],
+        precedence: 0,
+        label: 'selected',
+    },
+    'pending-write': {
+        stroke: 'none',
+        dash: 'marching',
+        // §17b's number. The edge stays legible — this is an optimistic draw of
+        // something that is probably about to be true, not a warning.
+        opacity: 0.7,
+        hueToken: null,
+        marks: ['node-chip'],
+        affordances: [],
+        precedence: 1,
+        label: 'writing',
+    },
+    invalid: {
+        stroke: 'ghost',
+        dash: 'dotted',
+        opacity: 0.5,
+        hueToken: '--ig-state-invalid',
+        marks: ['inline-reason'],
+        // Nothing to retry: the edit was refused before any write was attempted, so
+        // the same edit refuses again. The user changes it or discards it.
+        affordances: ['discard-mine'],
+        precedence: 2,
+        label: 'invalid',
+    },
+    failed: {
+        stroke: 'ghost',
+        dash: null,
+        opacity: 0.5,
+        hueToken: '--ig-state-failed',
+        marks: ['terminal-cross'],
+        affordances: ['retry', 'discard-mine'],
+        precedence: 3,
+        label: 'failed',
+    },
+    conflict: {
+        stroke: 'doubled',
+        dash: null,
+        opacity: null,
+        hueToken: '--ig-state-conflict',
+        // Both versions are held and drawn. The store keeps the upstream document
+        // on the record precisely so this can show one beside the other.
+        marks: ['second-version'],
+        affordances: ['view-diff', 'retry', 'discard-mine'],
+        precedence: 4,
+        label: 'conflict',
+    },
+});
+/**
+ * The alpha the selection halo is drawn at.
+ *
+ * IT LIVES HERE, BESIDE THE TABLE, AND NOT IN THE STYLESHEET — which is where
+ * it started, and that is the whole reason it is worth a named export.
+ *
+ * `styles.ts` already carried the rule that a state's opacity belongs to this
+ * table because a second copy would drift. The halo broke that rule quietly: it
+ * is not a state opacity, so it was written as a CSS declaration instead, and
+ * `grammar.test.ts`'s composited-contrast check reads this table — so the one
+ * alpha the check could not see was the one that failed. At 0.35 the halo
+ * measured about 2.0:1 on the dark surfaces and 1.75:1 on the light ones, under
+ * the 3:1 non-text bar, while every assertion stayed green.
+ *
+ * 0.75 clears the bar on both documented themes with margin. The halo is the
+ * selection cue; if it is not legible, selection is not visible.
+ */
+export const HALO_OPACITY = 0.75;
+/**
+ * Every (token, alpha) pair this package composites, as data.
+ *
+ * The contrast claim is about what LANDS on the surface, so it has to range
+ * over the alphas actually applied — and an alpha that is not in this list is
+ * one the check cannot see. Deriving the list rather than writing it by hand is
+ * what stops a third opacity appearing somewhere and going unmeasured.
+ */
+export function compositedHues() {
+    const pairs = [];
+    for (const state of EDGE_STATES) {
+        const { hueToken, opacity } = treatmentForState(state);
+        if (hueToken === null)
+            continue;
+        // The halo is drawn as its own element at its own alpha; every other state
+        // paints the edge, which carries the treatment's opacity.
+        pairs.push({
+            token: hueToken,
+            alpha: state === 'selected' ? HALO_OPACITY : (opacity ?? 1),
+        });
+    }
+    return pairs;
+}
+/** The treatment for a state. Total over the store's state set. */
+export function treatmentForState(state) {
+    return OVERLAY_TREATMENTS[state];
+}
+/** The attribute an overlaid edge announces its states on. */
+export const STATE_ATTRIBUTE = 'data-ig-state';
+/**
+ * Fold an edge's states into one overlay.
+ *
+ * `ProjectedEdge.states` already arrives in `EDGE_STATES` order — `project`
+ * canonicalises it so two projections of the same state compare equal — and
+ * this preserves that order rather than re-sorting, so a host memoising on the
+ * attribute string is not defeated by a second ordering rule appearing here.
+ */
+export function overlayFor(edge) {
+    const states = EDGE_STATES.filter((state) => edge.states.includes(state));
+    let line = null;
+    const marks = [];
+    const affordances = [];
+    for (const state of states) {
+        const treatment = treatmentForState(state);
+        // The halo is a channel of its own, so `selected` contributes no line
+        // treatment and cannot lose to — or beat — a write state.
+        if (state !== 'selected' && (line === null || treatment.precedence > line.precedence)) {
+            line = treatment;
+        }
+        for (const mark of treatment.marks)
+            if (!marks.includes(mark))
+                marks.push(mark);
+        for (const offer of treatment.affordances) {
+            if (!affordances.includes(offer))
+                affordances.push(offer);
+        }
+    }
+    return {
+        edgeId: edge.id,
+        states,
+        line,
+        halo: states.includes('selected'),
+        marks,
+        affordances,
+        attribute: states.length === 0 ? null : states.join(' '),
+    };
+}
+/**
+ * The accessible name for an overlaid edge, given the viewer's own name for it.
+ *
+ * The kind's sentence leads and the states follow, because the relationship is
+ * what the edge IS and the state is what is happening to it. A reader who stops
+ * after the first clause still has the fact.
+ *
+ * This is the ONLY English this module produces, and it is state names rather
+ * than a reason: an `invalid` edge's sentence is the host's, keyed off the
+ * store's `InvalidCode`.
+ */
+export function overlayLabel(base, overlay) {
+    if (overlay.states.length === 0)
+        return base;
+    return `${base} — ${overlay.states.map((state) => treatmentForState(state).label).join(', ')}`;
+}
+//# sourceMappingURL=grammar.js.map

package/dist/overlay/grammar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.js","sourceRoot":"","sources":["../../src/overlay/grammar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,WAAW,EAAmD,MAAM,mBAAmB,CAAC;AAsEjG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9C,QAAQ,EAAE;QACR,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,YAAY;QACtB,KAAK,EAAE,EAAE;QACT,WAAW,EAAE,EAAE;QACf,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,UAAU;KAClB;IACD,eAAe,EAAE;QACf,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,UAAU;QAChB,wEAAwE;QACxE,8DAA8D;QAC9D,OAAO,EAAE,GAAG;QACZ,QAAQ,EAAE,IAAI;QACd,KAAK,EAAE,CAAC,WAAW,CAAC;QACpB,WAAW,EAAE,EAAE;QACf,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,SAAS;KACjB;IACD,OAAO,EAAE;QACP,MAAM,EAAE,OAAO;QACf,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,GAAG;QACZ,QAAQ,EAAE,oBAAoB;QAC9B,KAAK,EAAE,CAAC,eAAe,CAAC;QACxB,4EAA4E;QAC5E,mEAAmE;QACnE,WAAW,EAAE,CAAC,cAAc,CAAC;QAC7B,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,SAAS;KACjB;IACD,MAAM,EAAE;QACN,MAAM,EAAE,OAAO;QACf,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,GAAG;QACZ,QAAQ,EAAE,mBAAmB;QAC7B,KAAK,EAAE,CAAC,gBAAgB,CAAC;QACzB,WAAW,EAAE,CAAC,OAAO,EAAE,cAAc,CAAC;QACtC,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,QAAQ;KAChB;IACD,QAAQ,EAAE;QACR,MAAM,EAAE,SAAS;QACjB,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,IAAI;QACb,QAAQ,EAAE,qBAAqB;QAC/B,0EAA0E;QAC1E,iEAAiE;QACjE,KAAK,EAAE,CAAC,gBAAgB,CAAC;QACzB,WAAW,EAAE,CAAC,WAAW,EAAE,OAAO,EAAE,cAAc,CAAC;QACnD,UAAU,EAAE,CAAC;QACb,KAAK,EAAE,UAAU;KAClB;CACqD,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAC;AAEjC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,KAAK,GAAuC,EAAE,CAAC;IACrD,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,QAAQ,KAAK,IAAI;YAAE,SAAS;QAChC,2EAA2E;QAC3E,0DAA0D;QAC1D,KAAK,CAAC,IAAI,CAAC;YACT,KAAK,EAAE,QAAQ;YACf,KAAK,EAAE,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC;SAC5D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,iBAAiB,CAAC,KAAgB;IAChD,OAAO,kBAAkB,CAAC,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAAG,eAAe,CAAC;AA4B/C;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,IAAmB;IAC5C,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAE1E,IAAI,IAAI,GAA4B,IAAI,CAAC;IACzC,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,MAAM,WAAW,GAAwB,EAAE,CAAC;IAE5C,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC3C,sEAAsE;QACtE,0DAA0D;QAC1D,IAAI,KAAK,KAAK,UAAU,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACtF,IAAI,GAAG,SAAS,CAAC;QACnB,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK;YAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChF,KAAK,MAAM,KAAK,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;YAC1C,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,EAAE;QACf,MAAM;QACN,IAAI;QACJ,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC;QACjC,KAAK;QACL,WAAW;QACX,SAAS,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC;KACzD,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY,EAAE,OAAoB;IAC7D,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7C,OAAO,GAAG,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACjG,CAAC"}

package/dist/overlay/render.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The overlay grammar, attached to a viewer scene.
+ *
+ * ## The constraint this module is shaped by
+ *
+ * Layer 2 does not know where an edge is. `index.ts` records the `together-with`
+ * connector as *the one declared crossing* precisely because "only the layer
+ * that computes the layout knows where its endpoints are", and that argument
+ * binds anything that needs a position — an arrowhead, a chip on a node, a
+ * sentence beside a line.
+ *
+ * So this module draws every treatment that can be stated WITHOUT a position,
+ * and declares the rest as marks for whoever owns the layout.
+ *
+ * ## The line, and it was drawn by evidence rather than by taste
+ *
+ * **An overlay that REUSES the path's own position can be drawn here. One that
+ * needs a NEW position cannot.**
+ *
+ * A halo is the path again, stroked wider. A marching or dotted ghost is the
+ * path again, patterned differently. Neither moves, so neither needs to know
+ * where the path goes, and cloning a solved `d` is enough.
+ *
+ * A conflict's second version is the case that looks identical and is not: it
+ * has to sit BESIDE the line, and "beside" is the path's perpendicular — which
+ * cannot be recovered from a `d` this layer does not interpret. Four review
+ * rounds each found a different way that goes wrong: three strokes where a pair
+ * was promised, a companion hidden underneath its twin, a companion that had
+ * lost the relationship's own double-line shape, and finally a vertical offset
+ * sliding ALONG a `together-with` connector that happens to run vertically —
+ * `connectorPath` emits exactly that whenever the two boxes are equal width.
+ *
+ * Each fix was correct and the next round found the next property, because the
+ * missing thing was never a property: it was the geometry. So the companion is
+ * no longer drawn here at all. It travels as the `second-version` mark, placed
+ * by the layer that computed the layout — the same treatment `node-chip`,
+ * `terminal-cross` and `inline-reason` already get, and the same argument
+ * `index.ts` makes for the `together-with` connector living in the viewer.
+ *
+ * What is left genuinely cannot be drawn here: `node-chip` sits on two nodes,
+ * `terminal-cross` and `inline-reason` need the line's end, and
+ * `second-version` needs its perpendicular. Those travel as
+ * {@link EdgeOverlay.marks} for the composer to place, declared rather than
+ * half-drawn here.
+ *
+ * ## How an edge is recognised
+ *
+ * Viewer edge paths publish no per-edge identity — only the `together-with`
+ * connector carries one — so an edge is matched by the accessible name the
+ * viewer gives it: `${from} ${treatment.label} ${to}`.
+ *
+ * The label is read from the viewer's OWN `treatmentFor`, never from a copy, so
+ * a renamed relationship moves both sides at once. What stays local is the
+ * SHAPE of that sentence, and a shape cannot be imported — so `render.test.ts`
+ * pins it with a positive control that attaches to a real rendered scene. If
+ * the viewer restyles its label, that control goes red rather than the overlays
+ * silently ceasing to attach, which is the failure mode worth buying a test.
+ *
+ * Publishing an identity on edge paths would be better and is deliberately NOT
+ * done here: `keyAt` reads `GROUP_ATTRIBUTE` as POINTER identity, so adding one
+ * would change what a click on an edge means. That belongs to the leaf that
+ * owns edge selection, not to a grammar.
+ *
+ * ## Attach to a freshly rendered scene, never to your own output
+ *
+ * The consequence of matching on the accessible name is that overlaying REWRITES
+ * that name — the states are announced there — so an overlaid edge no longer
+ * matches. A host renders a new scene on every state change and attaches to
+ * that, which is the intended shape and is why this is a boundary rather than a
+ * defect.
+ *
+ * Attaching to an already-overlaid scene is out of contract. It fails SAFELY
+ * rather than silently: nothing matches, the scene keeps the overlays it
+ * already had, and every edge is reported in {@link AttachResult.unattached}.
+ * `render.test.ts` pins that, so the behaviour is a decision rather than an
+ * accident. What it must never do is double the announcement, and it does not.
+ *
+ * ## No timer
+ *
+ * The marching dash is a CSS animation, which is what §17b asks for. The rule
+ * is that nothing changes STATE on its own — no `setTimeout`, no `setInterval`,
+ * no self-dismissal. A chip persists until the write settles, and a settled
+ * failure persists until the user acts on it.
+ */
+import type { ProjectedEdge } from '@issuegraph/store';
+import { type ElementSpec, type Scene, type Theme } from '@issuegraph/viewer';
+import { type EdgeOverlay } from './grammar.ts';
+/** The class every mark this module adds carries, so a host can find them. */
+export declare const OVERLAY_CLASS = "ig-overlay";
+export interface OverlayOptions {
+    readonly theme?: Theme | undefined;
+}
+export interface AttachResult {
+    readonly scene: Scene;
+    /**
+     * Every overlay applied, keyed by edge. Marks this module could not place —
+     * the ones needing a position — travel here for the composer that owns the
+     * layout.
+     */
+    readonly overlays: readonly EdgeOverlay[];
+    /** Overlays whose edge the scene does not draw. Never silently dropped. */
+    readonly unattached: readonly EdgeOverlay[];
+}
+/**
+ * Overlay a scene's edges with the states their projection carries.
+ *
+ * Takes `ProjectedEdge`s rather than resolved overlays because an edge's kind
+ * and endpoints are what identify it in the scene, and asking a caller to hand
+ * those over separately is asking it to keep two things in step.
+ */
+export declare function attachEdgeOverlays(scene: Scene, edges: readonly ProjectedEdge[], options?: OverlayOptions): AttachResult;
+/**
+ * The `writing…`, `retry` and reason marks, as controls a host can dispatch.
+ *
+ * Positioned by whoever calls it — see the module note. It renders the control,
+ * publishing what it does as data on `data-ig-overlay`, the same contract
+ * `scale/render.ts` established: layer 2 publishes the control, and the mount
+ * that owns the state wires it.
+ *
+ * The reason mark carries the store's `InvalidCode` and NO sentence. A host
+ * keys its own message off the code, for the same reason `change.ts` ships
+ * counts rather than prose.
+ */
+export declare function renderOverlayMark(overlay: EdgeOverlay, mark: EdgeOverlay['marks'][number], reasonCode?: string): ElementSpec;
+//# sourceMappingURL=render.d.ts.map

package/dist/overlay/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/overlay/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmFG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,KAAK,EAEV,KAAK,KAAK,EAIX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,KAAK,WAAW,EAGjB,MAAM,cAAc,CAAC;AAEtB,8EAA8E;AAC9E,eAAO,MAAM,aAAa,eAAe,CAAC;AAsB1C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,SAAS,WAAW,EAAE,CAAC;CAC7C;AAqRD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,SAAS,aAAa,EAAE,EAC/B,OAAO,GAAE,cAAmB,GAC3B,YAAY,CAyCd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,EAClC,UAAU,CAAC,EAAE,MAAM,GAClB,WAAW,CAuDb"}