@issuegraph/viewer 0.2.0 → 0.5.0

package/dist/parts.js

@@ -7,9 +7,54 @@
  * is held", and a change to the grammar lands in every projection at once.
  */
 import { edgeIdentity } from '@issuegraph/core';
-import { element } from "./element.js";
+import { element, svg } from "./element.js";
 import { GROUP_ATTRIBUTE } from "./scene.js";
-import { EDGE_ORDER, treatmentFor } from "./vocabulary.js";
+import { EDGE_ORDER, dashArrayFor, labelFrom, treatmentFor } from "./vocabulary.js";
+/**
+ * The attribute a control the viewer publishes but does not wire carries. The
+ * same one `@issuegraph/editor` reads for its own controls, so a host that
+ * already listens for the editor's commands hears this one through the same
+ * listener.
+ */
+export const COMMAND_ATTRIBUTE = 'data-ig-command';
+/**
+ * A mark for the eye and for nothing else.
+ *
+ * FOUR CHANNELS SEPARATE A RELATIONSHIP AND ONLY ONE OF THEM IS AUDIBLE. The
+ * glyph is `aria-hidden` because `⊘` announces as whatever a given screen
+ * reader's character table calls it — "circle with slash", or nothing at all —
+ * which is a description of the mark rather than of the relationship. Whatever
+ * carries the NAME has to be something else: the word beside it, or an
+ * `aria-label` on the control the mark sits inside.
+ *
+ * IT IS ITS OWN FUNCTION BECAUSE THE PAIRING IS NOT ITS ONLY CONSUMER. A word
+ * beside the glyph is the common shape and {@link glyphAndLabel} is it, but a
+ * glyph-only control — §17a's `✕` in a relationship row's slot, whose name is
+ * on the button — genuinely needs the hidden mark with no visible word. Given
+ * only the pairing, that call site writes the class and the `aria-hidden` out
+ * by hand, which is the copy the pairing exists to prevent wearing a different
+ * shape. Two published pieces, one rule.
+ */
+export function hiddenGlyph(glyph) {
+    return element('span', { class: 'ig-glyph', 'aria-hidden': 'true' }, [glyph]);
+}
+/**
+ * A badge's inner pair — the glyph a reader can see and the word a reader can
+ * hear.
+ *
+ * THE WORD IS THE ACCESSIBLE NAME, and it is the vocabulary's own. The mark
+ * beside it is {@link hiddenGlyph}, so the `aria-hidden` that makes this pair
+ * work at all is written in one place for every surface that draws one.
+ *
+ * EXPORTED FOR THE EDITOR, which draws the same pair in §17a's inspector rows
+ * and its numbered kind list. A second spelling of the pairing there would be
+ * free to drop the `aria-hidden` — the failure it exists to prevent — and would
+ * put the same relationship on screen in two shapes one zone apart from the
+ * §16 badge this already draws.
+ */
+export function glyphAndLabel(glyph, label) {
+    return [hiddenGlyph(glyph), element('span', {}, [label])];
+}
 /**
  * Filled = ready now. Hollow = ready once a named rank lands. Dashed = held.
  *
@@ -55,34 +100,126 @@ export function identity(issue) {
     ]);
 }
 /**
- * The provenance line, in the three forms the design fixes: a matched ordering
- * query, the declared tier, and an effective-priority promotion that names the
- * dependent the urgency arrived through.
+ * The provenance SENTENCE, without the line it normally sits on.
+ *
+ * ONE WORDING, TWO PLACEMENTS. §16 hangs this sentence off a turnstile as a
+ * subordinate rail line; §17a's inspector needs the same sentence inside its
+ * own "why rank" paragraph, where a `↳` would be rail furniture imported into
+ * a panel. So the wording lives here and the furniture lives in
+ * {@link provenanceLine}, which is the only difference between the two.
+ *
+ * IT IS ON THE PUBLIC SURFACE FOR THE EDITOR, and that is the whole reason it
+ * exists separately. Layer 2 composing this is layer 2 reading layer 1's
+ * wording; layer 2 switching on `RankProvenance` itself would be a second
+ * wording of one fact, free to drift from the rail's. The seam permits adding
+ * to this layer's surface — what it forbids is reaching past it.
+ *
+ * NO TURNSTILE HERE, DELIBERATELY. `provenanceLine` adds it. A caller that
+ * wants the §16 line calls that; a caller that wants the sentence calls this.
  */
-export function provenanceLine(provenance) {
+export function provenanceClause(provenance) {
     if (provenance === undefined)
         return null;
     switch (provenance.kind) {
         case 'matched-query':
-            return element('p', { class: 'ig-provenance' }, [
+            return element('span', {}, [
                 `matched ordered query ${String(provenance.index)} · `,
                 element('span', { class: 'ig-id' }, [provenance.label]),
             ]);
         case 'declared-tier':
-            return element('p', { class: 'ig-provenance' }, [
-                `priority tier P${String(provenance.priority)}`,
+            // NEUTRAL, AND THAT IS THE POINT. This arm means only that no ordering
+            // query matched and the issue stayed in its tier — it does NOT mean the
+            // priority was absent. §16a's own row happens to be one where it was, and
+            // borrowing that row's sentence made the panel tell every reader that an
+            // explicitly-declared P0 had no declared priority. A panel whose job is
+            // explaining the order cannot invent the reason.
+            return element('span', {}, [
+                'no ordered query matched — ranked in tier ',
+                element('span', { class: 'ig-id' }, [`P${String(provenance.priority)}`]),
             ]);
         case 'promotion': {
             const via = provenance.promotedBy.length === 0
-                ? ''
-                : ` · inherited from ${provenance.promotedBy.join(', ')}`;
-            return element('p', { class: 'ig-provenance' }, [
+                ? null
+                : element('span', {}, [
+                    ' — inherited from ',
+                    element('span', { class: 'ig-id' }, [provenance.promotedBy.join(', ')]),
+                    ', which it blocks',
+                ]);
+            return element('span', {}, [
+                'effective priority ',
                 element('span', { class: 'ig-id' }, [provenance.notation]),
-                `${via}`,
+                via,
             ]);
         }
     }
 }
+/**
+ * The provenance line, in the three forms the design fixes: a matched ordering
+ * query, the declared tier, and an effective-priority promotion that names the
+ * dependent the urgency arrived through.
+ *
+ * The wording is {@link provenanceClause}'s; this adds only §16's turnstile and
+ * the paragraph it hangs on, so the rail and the inspector cannot come to
+ * disagree about how one fact reads.
+ */
+export function provenanceLine(provenance) {
+    const clause = provenanceClause(provenance);
+    if (clause === null)
+        return null;
+    return element('p', { class: 'ig-provenance' }, [turn(), clause]);
+}
+/**
+ * The turnstile every explanation line hangs off.
+ *
+ * §16a puts one in front of the provenance sentence, the hold sentence and the
+ * caveat note alike, and it is what makes those lines read as subordinate to
+ * the row above WITHOUT dimming them. The line that shipped was muted instead,
+ * which files the panel's own reason for existing — why is this here — under
+ * decoration.
+ */
+function turn() {
+    return element('span', { class: 'ig-turn', 'aria-hidden': 'true' }, ['↳']);
+}
+/**
+ * The priority chip a row wears on its badge row, derived from the same
+ * provenance the sentence beneath it explains.
+ *
+ * ONE FACT, TWO READS, and the frame draws both on purpose: the chip is what a
+ * reader scanning a column of rows sees, and the sentence is what they read
+ * when the chip surprises them. A promotion is the one chip the design accents,
+ * because a low tier pulled to the top because it blocks a high one is the most
+ * interesting thing the panel can say.
+ */
+export function priorityBadge(provenance) {
+    if (provenance === undefined)
+        return null;
+    switch (provenance.kind) {
+        case 'matched-query':
+            return element('span', { class: 'ig-badge', 'data-priority': 'query' }, [provenance.label]);
+        case 'declared-tier':
+            // `· tier`, NOT `· default`. The chip says which tier ranked the row; it
+            // cannot say the tier was a default, because this arm does not know that.
+            return element('span', { class: 'ig-badge', 'data-priority': 'tier' }, [
+                `P${String(provenance.priority)} · tier`,
+            ]);
+        case 'promotion':
+            return element('span', { class: 'ig-badge', 'data-priority': 'promoted' }, [
+                provenance.notation,
+            ]);
+    }
+}
+/**
+ * The evidence chip: `✓ verified`, or nothing.
+ *
+ * ABSENT READS `asserted`, which §16d states in those words, so an absent field
+ * draws no chip rather than a muted one — a panel that prints "asserted" on
+ * every row has spent a chip slot on the default.
+ */
+export function evidenceBadge(issue) {
+    if (issue?.evidence !== 'verified')
+        return null;
+    return element('span', { class: 'ig-badge', 'data-evidence': 'verified', title: 'evidence: verified' }, glyphAndLabel('✓', 'verified'));
+}
 /**
  * One hold, rendered with the family it belongs to visible in the markup — and
  * its cause and subject beside it when the host supplied them, so a host reads
@@ -90,12 +227,485 @@ export function provenanceLine(provenance) {
  * when absent: `data-code=""` would claim a cause the host did not state.
  */
 export function holdLine(hold) {
+    // THE LABEL IS THE TRACKER ARM'S ALONE, and the union is what lets this read
+    // it without asking: a graph hold has no `label` to read. Drawn INSIDE the
+    // paragraph, so a labelled hold is still one row child and the slot grid's
+    // column rule holds without a second placement.
+    const label = hold.family === 'tracker' && hold.label !== undefined && hold.label !== ''
+        ? element('span', { class: 'ig-badge', 'data-hold': hold.label }, [hold.label])
+        : null;
     return element('p', {
         class: 'ig-hold',
         'data-family': hold.family,
         'data-code': hold.code,
         'data-subject': hold.subject,
-    }, [hold.reason]);
+    }, [turn(), label, element('span', {}, [hold.reason])]);
+}
+/**
+ * The runner's own words for the holds a footer collects — `claimed · parked` —
+ * so the footer title can name them the way the design does. Empty when no
+ * hold carries a label, which keeps the title exactly as it was before labels
+ * existed.
+ */
+export function footerLabels(slots) {
+    const labels = [];
+    for (const slot of slots) {
+        for (const hold of slot.holds) {
+            if (hold.family !== 'tracker' || hold.label === undefined || hold.label === '')
+                continue;
+            if (!labels.includes(hold.label))
+                labels.push(hold.label);
+        }
+    }
+    return labels.join(' · ');
+}
+/**
+ * The projection toggle and the size affordance — controls the viewer PUBLISHES
+ * and does not wire, exactly like the refresh button beside them.
+ *
+ * THE VIEWER CANNOT SWITCH ITS OWN PROJECTION. It is a pure renderer: the host
+ * re-renders it with a different option, which is the same shape `refresh`
+ * already has. So the toggle is drawn here — §16a and §16b both draw it, and a
+ * panel whose two views are its whole point cannot leave the way between them
+ * to the host's imagination — and the command travels on the attribute the host
+ * is already listening to.
+ */
+function headerControls(controls) {
+    // A CONTROL NOBODY WIRED IS WORSE THAN NO CONTROL. This package cannot switch
+    // its own projection, so the host says whether it will — and until it does,
+    // the button is not drawn rather than drawn dead.
+    if (controls === undefined || !controls.switchable)
+        return null;
+    const toggle = (projection, glyph, label) => element('button', {
+        class: 'ig-toggle-option',
+        type: 'button',
+        'aria-pressed': controls.projection === projection ? 'true' : 'false',
+        [COMMAND_ATTRIBUTE]: `projection:${projection}`,
+    }, [element('span', { class: 'ig-glyph', 'aria-hidden': 'true' }, [glyph]), label]);
+    return element('span', { class: 'ig-toggle', role: 'group', 'aria-label': 'projection' }, [
+        toggle('linear', '☰', 'List'),
+        toggle('graph', '⛓', 'Graph'),
+    ]);
+}
+/**
+ * The expand / collapse affordance the graph's two sizes need.
+ *
+ * GATED THE SAME WAY THE TOGGLE IS, and for the same reason: `expand` and
+ * `collapse` are published commands this package cannot perform on itself, so a
+ * host that has not wired them would be given a button that does nothing.
+ */
+function sizeControl(controls) {
+    if (controls === undefined || !controls.switchable || controls.compact === undefined)
+        return null;
+    // ITS OWN CLASS, NOT THE REFRESH BUTTON'S. They look alike and they are not
+    // the same thing: refresh is drawn only when a host supplied a word for it,
+    // and this is drawn whenever the graph is, so sharing a class made a document
+    // with no host facts render `ig-refresh` and broke the pure-graph promise.
+    return element('button', {
+        class: 'ig-size',
+        type: 'button',
+        [COMMAND_ATTRIBUTE]: controls.compact ? 'expand' : 'collapse',
+    }, [controls.compact ? '⤢ Expand' : '⤡ Collapse']);
+}
+export function hostHeader(document, controls) {
+    const { concurrencyCap, counts, freshness, adoption } = document.host;
+    // THREE CHIPS, NOT ONE SENTENCE, and the middle one carries the accent. §16a
+    // outlines each tally separately and tints only "how many could run right
+    // now, against the cap" — the number an operator acts on — so the panel
+    // spends its accent once instead of on a line of muted prose in which every
+    // figure looks equally worth reading. The cap rides on that chip because the
+    // comparison is the point: four ready against a cap of two says something
+    // neither number says alone.
+    const chips = [];
+    if (counts !== undefined) {
+        chips.push(element('span', { class: 'ig-count-chip', 'data-count': 'ranked' }, [
+            `${String(counts.ranked)} ranked`,
+        ]), element('span', { class: 'ig-count-chip', 'data-count': 'ready' }, [
+            concurrencyCap === undefined
+                ? `${String(counts.readyNow)} ready now`
+                : `${String(counts.readyNow)} ready now · cap ${String(concurrencyCap)}`,
+        ]), element('span', { class: 'ig-count-chip', 'data-count': 'held' }, [
+            `${String(counts.held)} held`,
+        ]));
+    }
+    else if (concurrencyCap !== undefined) {
+        chips.push(element('span', { class: 'ig-count-chip', 'data-count': 'ready' }, [
+            `cap ${String(concurrencyCap)}`,
+        ]));
+    }
+    // §16h'S ONE AMBIGUITY WORTH REMOVING, stated once and here. "No edges shown"
+    // and "no edges declared" look identical on a panel, and only the host can
+    // tell them apart — it holds the whole backlog, while this document may be a
+    // window onto it. So the number is supplied like every other count, and the
+    // header prints it beside them rather than inventing a second place for it.
+    if (adoption?.counts !== undefined) {
+        chips.push(element('span', { class: 'ig-count-chip', 'data-count': 'adoption' }, [
+            `${String(adoption.counts.declaring)} of ${String(adoption.counts.total)} declare relationships`,
+        ]));
+    }
+    const summary = chips.length === 0
+        ? null
+        : element('p', { class: 'ig-counts', 'aria-label': 'order summary' }, chips);
+    const stamp = freshness === undefined
+        ? null
+        : element('p', { class: 'ig-freshness', 'data-stale': freshness.stale === true ? 'true' : 'false' }, [
+            element('span', {}, [
+                'as of ',
+                element('span', { class: 'ig-id' }, [freshness.asOf]),
+                freshness.age === undefined || freshness.age === '' ? null : ` · ${freshness.age}`,
+                freshness.stale === true ? ' · stale' : null,
+            ]),
+            // A CONTROL THE VIEWER PUBLISHES AND DOES NOT WIRE. Refreshing a mirror
+            // is fetching, which this layer never does; the host that can listens
+            // for the command. A real button rather than a styled span, so the
+            // mount's own click and Enter handling leave it alone the way they
+            // leave a deep link alone.
+            freshness.refresh === undefined || freshness.refresh === ''
+                ? null
+                : element('button', { class: 'ig-refresh', type: 'button', [COMMAND_ATTRIBUTE]: 'refresh' }, [freshness.refresh]),
+        ]);
+    const toggle = headerControls(controls);
+    const size = sizeControl(controls);
+    if (summary === null && stamp === null && toggle === null)
+        return null;
+    // THE PANEL'S OWN NAME IS PART OF THE HEADER BAR. §16a leads with it, and it
+    // is what tells a reader that the rows beneath are a PREVIEW of an order
+    // rather than the tracker's own list.
+    return element('header', { class: 'ig-header' }, [
+        element('div', { class: 'ig-header-top' }, [
+            element('span', { class: 'ig-header-lead' }, [
+                element('span', { class: 'ig-header-label' }, ['Order preview']),
+                toggle,
+            ]),
+            element('span', { class: 'ig-header-lead' }, [stamp, size]),
+        ]),
+        summary,
+    ]);
+}
+/**
+ * The kind of condition the host stated, or nothing.
+ *
+ * Exported so each projection root can put it on the panel element as
+ * `data-ig-condition` and let the STYLESHEET decide what a condition looks
+ * like. `renderAttrs` omits a `null` attribute, so a host that stated none
+ * emits exactly the markup it emitted before this existed — which is what keeps
+ * the pure-graph promise a promise rather than an aspiration.
+ */
+export function conditionKind(document, chrome) {
+    // GATED LIKE THE NOTICE, because it is the same fact wearing a different
+    // channel: the stylesheet reads this attribute to outline the panel, so a
+    // chrome-less render kept the gold outline with nothing anywhere in it saying
+    // what the gold meant. An unexplained treatment is worse than none.
+    if (chrome === false)
+        return null;
+    return document.host.condition?.kind ?? null;
+}
+/**
+ * Whether the host has said why this panel is short, so no projection may say
+ * why itself.
+ *
+ * NOT CHROME, AND THIS IS THE DISTINCTION THE TWO HELPERS EXIST TO KEEP. What
+ * to DRAW is a rendering question, and a host composing two views of one
+ * document wants the notice and its outline once — that is `conditionKind`.
+ * What is TRUE is not: a chrome-less canvas beside an explained rail is still a
+ * view of a document whose emptiness the host has accounted for, and its own
+ * derived sentence is not a fallback explanation but a false one. The graph's
+ * reads "no issue in this document declares a relationship", which under a
+ * stated `error` is a claim about something else entirely, contradicting the
+ * panel beside it. Drawing nothing there is right; explaining it wrongly is not.
+ */
+export function statesItsOwnCause(document) {
+    return document.host.condition !== undefined;
+}
+/**
+ * One interpreter for the three arms.
+ *
+ * AN EXHAUSTIVE SWITCH, which is the whole of the branching this feature adds.
+ * The arms carry different field names, so a lookup table would have to reach
+ * them through an index the union does not offer — and the compiler proving a
+ * new arm was not forgotten is worth more here than the table's shape.
+ *
+ * THE COMMANDS ARE NAMESPACED. `data-ig-command` is one namespace shared with
+ * `@issuegraph/editor` and with whatever a host publishes beside it, and the
+ * bare word `retry` already means "retry that write" to the editor's own
+ * reducer. A control that looks wired and does something else is worse than
+ * the control this package refuses to draw at all.
+ */
+function noticeParts(condition) {
+    switch (condition.kind) {
+        case 'importing':
+            return { headline: condition.headline, body: [condition.caution], progress: condition.progress };
+        case 'empty':
+            return {
+                headline: condition.headline,
+                body: [condition.reason, condition.assurance],
+                ...(condition.action === undefined
+                    ? {}
+                    : {
+                        control: {
+                            label: condition.action.label,
+                            command: 'review-pick-order',
+                            ...(condition.action.href === undefined ? {} : { href: condition.action.href }),
+                        },
+                    }),
+            };
+        case 'error':
+            return {
+                headline: condition.headline,
+                body: [condition.assurance],
+                ...(condition.retry === undefined || condition.retry.trim() === ''
+                    ? {}
+                    : { control: { label: condition.retry, command: 'retry:index' } }),
+            };
+    }
+}
+/**
+ * The panel-level notice: what the host says is true of the whole panel.
+ *
+ * CHROME, like the header beside it, and it takes the flag rather than leaving
+ * each projection to apply it: the rule is that a host composing two views of
+ * one document owns ONE notice for the same reason it owns one header, and a
+ * rule restated at three call sites is three places to forget it. The same
+ * argument that gave `hostHeader` its gate gives this one its parameter.
+ *
+ * `role="status"` SITS ON THE TEXT, NOT THE CONTAINER. A polite live region
+ * holding an interactive control re-announces the button every time the host
+ * re-renders, which turns a reassurance into a nag.
+ *
+ * A CONTROL IS DRAWN ONLY FOR A HOST THAT NAMED ONE, exactly as the refresh
+ * button beside the stamp is. An `href` makes it a link instead of a command —
+ * some hosts route rather than act — and the scheme was already refused or
+ * kept by `normalizeDocument`, so nothing is checked a second time here.
+ */
+export function conditionNotice(document, chrome) {
+    const condition = document.host.condition;
+    if (chrome === false || condition === undefined)
+        return null;
+    const parts = noticeParts(condition);
+    const control = parts.control === undefined
+        ? null
+        : parts.control.href === undefined
+            ? element('button', { class: 'ig-notice-action', type: 'button', [COMMAND_ATTRIBUTE]: parts.control.command }, [parts.control.label])
+            : element('a', 
+            // `rel="noreferrer"`, THE SAME ANSWER `identity` GIVES. This is the
+            // package's other rendering of a host-supplied URL, and two answers
+            // to one question is the drift the shared scheme check exists to
+            // avoid — applied to the attribute set as well as to the check.
+            { class: 'ig-notice-action', href: parts.control.href, rel: 'noreferrer' }, [parts.control.label]);
+    return element('aside', { class: 'ig-notice', 'data-ig-condition': condition.kind }, [
+        element('div', { class: 'ig-notice-text', role: 'status' }, [
+            element('p', { class: 'ig-notice-head' }, condition.glyph === undefined || condition.glyph === ''
+                ? [condition.headline]
+                : glyphAndLabel(condition.glyph, condition.headline)),
+            ...parts.body.map((line) => element('p', { class: 'ig-notice-body' }, [line])),
+            parts.progress === undefined ? null : element('p', { class: 'ig-notice-progress' }, [parts.progress]),
+        ]),
+        control,
+    ]);
+}
+/**
+ * §16h's one quiet line: why this panel shows no relationships at all.
+ *
+ * THE SENTENCE IS THE HOST'S, and it has to be: the cause names a host's own
+ * configuration, and a package that has never heard of a pick order cannot
+ * write it. The line, the link and the dismiss control are this package's.
+ *
+ * THE VIEWER NEVER HIDES ITS OWN LINE. Dismiss is published like every other
+ * command; the host re-renders without the note. A package that removed the
+ * element itself would be holding state, which is the one thing this layer
+ * promises it does not do.
+ */
+export function adoptionNote(document, chrome) {
+    const note = document.host.adoption?.note;
+    if (chrome === false || note === undefined)
+        return null;
+    return element('p', { class: 'ig-adoption' }, [
+        // THE SENTENCE STAYS PLAIN. Its link is a short label beside it, not the
+        // whole line wearing an underline — this is the one piece of commentary on
+        // a panel the design asks to read complete and calm.
+        element('span', { class: 'ig-adoption-text' }, [note.text]),
+        note.link === undefined
+            ? null
+            : element('a', { class: 'ig-adoption-link', href: note.link.href, rel: 'noreferrer' }, [note.link.text]),
+        note.dismiss === undefined || note.dismiss.trim() === ''
+            ? null
+            : element('button', {
+                class: 'ig-adoption-dismiss',
+                type: 'button',
+                'aria-label': note.dismiss,
+                [COMMAND_ATTRIBUTE]: 'dismiss:adoption',
+            }, [note.dismiss]),
+    ]);
+}
+/**
+ * The NOW rows: what the runner is working this moment, drawn above the order.
+ *
+ * A POINTER IDENTITY, NEVER A FOCUS ONE. The running issue may also hold a slot
+ * — a claimed row in the footer, say — and exactly one element per key carries
+ * `data-ig-key` or `focus()` lands on whichever the renderer emitted first. So
+ * the row announces itself through {@link GROUP_ATTRIBUTE}, the way an
+ * enclosure does: clickable and hoverable, resolving to the issue through the
+ * document, and absent from the focus index. The title and identity are the
+ * ISSUE'S, looked up here; only the phase and the elapsed time are the host's
+ * words, because only the host has the clock.
+ */
+export function nowRows(document) {
+    if (document.host.running.length === 0)
+        return null;
+    return element('ol', { class: 'ig-now', 'aria-label': 'working now' }, document.host.running.map((job) => {
+        // Present by construction: `normalizeHost` dropped any job the document
+        // does not carry. The fallback keeps this total rather than trusting it.
+        const issue = document.byKey.get(job.key);
+        return element('li', {
+            class: 'ig-now-row',
+            [GROUP_ATTRIBUTE]: job.key,
+            // The list already announces "working now"; the row says what and how long.
+            'aria-label': `${issue?.title ?? job.key} — ${job.phase} · ${job.elapsed}`,
+        }, [
+            element('span', { class: 'ig-now-mark', 'aria-hidden': 'true' }, ['now']),
+            // THE SAME TWO-LINE HEAD EVERY ROW HAS. The band that shipped put the
+            // title, the identity and the phase on one line at three different
+            // ends of it, so the row being worked read as less structured than
+            // the queued rows beneath it — the opposite of what the frame does.
+            element('div', { class: 'ig-row-head' }, [
+                element('span', { class: 'ig-title' }, [issue?.title ?? job.key]),
+                element('span', { class: 'ig-id' }, [
+                    issue === undefined ? job.key : identity(issue),
+                    ` · ${job.phase} · ${job.elapsed}`,
+                ]),
+            ]),
+            element('span', { class: 'ig-now-phase' }, [
+                element('span', { class: 'ig-now-pulse', 'aria-hidden': 'true' }),
+                'working',
+            ]),
+        ]);
+    }));
+}
+/**
+ * A together unit's members, one line each.
+ *
+ * THE UNIT IS THE ONE PLACE THE DESIGN DRAWS AN ENCLOSURE, and it draws it to
+ * say that two distinct issues are one unit of work. Joining their titles with
+ * a separator — which is what shipped — says the opposite: a reader sees one
+ * issue with an unusually long name, and the second issue's own identity and
+ * tier vanish. Returns `null` for a single-member slot, so an ordinary row is
+ * unchanged by construction.
+ */
+export function unitBlock(document, slot) {
+    if (slot.members.length < 2)
+        return null;
+    return element('ul', { class: 'ig-unit', 'aria-label': `one unit of ${String(slot.members.length)} issues` }, slot.members.map((member) => {
+        const issue = document.byKey.get(member);
+        // THROUGH `identity`, WHICH IS WHERE THE DEEP LINK LIVES. Printing the key
+        // as plain text took the chip away from the lead — which had one before
+        // this row shape existed — and gave the partners none either, so a unit
+        // was the one row in the panel from which no issue could be opened at
+        // all. §16e calls that chip "the only external link", so losing it on a
+        // unit loses the only way out of it.
+        return element('li', { class: 'ig-unit-member' }, [
+            element('span', { class: 'ig-title' }, [issue?.title ?? member]),
+            issue === undefined
+                ? element('span', { class: 'ig-id' }, [member])
+                : element('span', { class: 'ig-id' }, [
+                    identity(issue),
+                    ` · P${String(issue.priority)}`,
+                ]),
+        ]);
+    }));
+}
+/** The unit's own pill, above the enclosure: what it is, and how many. */
+export function unitMark(slot) {
+    if (slot.members.length < 2)
+        return null;
+    return element('div', { class: 'ig-unit-mark' }, [
+        element('span', { class: 'ig-unit-pill' }, [
+            `⧉ one unit · ${String(slot.members.length)} issues`,
+        ]),
+        element('span', { class: 'ig-unit-note' }, ['worked together']),
+    ]);
+}
+/**
+ * The two caveats a host can put on a row, each ONE row child so the slot grid
+ * places it like provenance.
+ *
+ * `preview-only`: the host's engine could not evaluate a pick-order query, and
+ * the note says what it fell back to. `signals disagree`: two ordering signals
+ * named different priorities, the host chose one, and the design's rule is
+ * that the loser stays visible — struck through, never hidden — because a panel
+ * whose job is explaining the order cannot silently pick a winner.
+ */
+export function caveatLines(issue) {
+    if (issue === undefined)
+        return [];
+    const lines = [];
+    if (issue.previewOnly !== undefined) {
+        lines.push(element('p', { class: 'ig-caveat', 'data-caveat': 'preview-only' }, [
+            turn(),
+            element('span', {}, [issue.previewOnly.note]),
+        ]));
+    }
+    if (issue.disagreement !== undefined) {
+        const { used, ignored } = issue.disagreement;
+        lines.push(element('p', { class: 'ig-caveat', 'data-caveat': 'disagree' }, [
+            turn(),
+            element('span', {}, [
+                `ranked by ${used} · ${ignored.carrier} declares `,
+                element('s', { class: 'ig-strike' }, [ignored.value]),
+            ]),
+        ]));
+    }
+    return lines;
+}
+/**
+ * The caveat CHIPS, which sit on the badge row rather than in front of the note.
+ *
+ * §16a treats a caveat exactly like a relationship: a chip a scanner sees, and
+ * a sentence a reader reads. Leaving the chip inline in the sentence made the
+ * badge row incomplete and the sentence lumpy — the chip is a fact ABOUT the
+ * row, not the first two words of an explanation.
+ */
+export function caveatBadges(issue) {
+    if (issue === undefined)
+        return [];
+    const chips = [];
+    if (issue.previewOnly !== undefined) {
+        chips.push(element('span', { class: 'ig-badge', 'data-caveat': 'preview-only' }, glyphAndLabel('◐', 'preview-only')));
+    }
+    if (issue.disagreement !== undefined) {
+        chips.push(element('span', { class: 'ig-badge', 'data-caveat': 'disagree' }, glyphAndLabel('◆', 'signals disagree')));
+    }
+    return chips;
+}
+/**
+ * The `⊘ not ready` chip a graph-held row wears.
+ *
+ * The frame puts it on the badge row beside the tier, so "held" is legible in
+ * the same scan as "P1" rather than only from the hatched ground or the
+ * sentence underneath.
+ */
+export function notReadyBadge(slot) {
+    if (slot.ready)
+        return null;
+    if (!slot.holds.some((hold) => hold.family === 'graph'))
+        return null;
+    return element('span', { class: 'ig-badge', 'data-not-ready': 'true' }, glyphAndLabel('⊘', 'not ready'));
+}
+/**
+ * The caveats as one sentence, for a row that has no room for a block — the
+ * graph rail positions its rows onto layout boxes, so it carries text on the
+ * label and the tooltip instead (the same choice it makes for holds).
+ */
+export function caveatText(issue) {
+    if (issue === undefined)
+        return '';
+    const parts = [];
+    if (issue.previewOnly !== undefined)
+        parts.push(`preview-only: ${issue.previewOnly.note}`);
+    if (issue.disagreement !== undefined) {
+        const { used, ignored } = issue.disagreement;
+        parts.push(`signals disagree: ranked by ${used}, ${ignored.carrier} declares ${ignored.value}`);
+    }
+    return parts.join(' · ');
 }
 /**
  * A badge naming one relationship, on all four channels at once.
@@ -125,18 +735,22 @@ export function holdLine(hold) {
  * `keyAt` walks target-upward. That is the intended half of "an edge is pointable
  * in every projection", and it is what the canvas already does for an arc.
  */
-function edgeBadge(field, edgeId, detail) {
+function edgeBadge(field, edgeId, label, other) {
     const treatment = treatmentFor(field);
     return element('span', {
         class: 'ig-badge',
         'data-edge': field,
         [GROUP_ATTRIBUTE]: edgeId,
-        title: `${treatment.label} ${detail}`,
-        'aria-label': `${treatment.label} ${detail}`,
-    }, [
-        element('span', { class: 'ig-glyph', 'aria-hidden': 'true' }, [treatment.glyph]),
-        element('span', {}, [detail]),
-    ]);
+        title: `${label} ${other}`,
+        'aria-label': `${label} ${other}`,
+    }, 
+    // WORDED, NOT GLYPH-AND-NUMBER. `⊘ 512` asks a reader to hold a five-glyph
+    // legend in their head while scanning a column of rows; `⊘ blocked by #512`
+    // does not, and §16a and §16b both draw the word. The glyph stays — it is
+    // one of the four channels the colour-blind-safety claim rests on — and the
+    // label it now shows is the same string the accessible name already used,
+    // so what is announced and what is drawn cannot drift.
+    glyphAndLabel(treatment.glyph, `${label} ${other}`));
 }
 /**
  * How many relationship badges one row draws before the rest collapse into a
@@ -194,6 +808,18 @@ function overflowBadge(omitted) {
  * key — a single-key row is unchanged by construction.
  */
 export function edgeBadges(document, keys) {
+    const badges = edgeBadgeList(document, keys);
+    return badges.length === 0 ? null : element('span', { class: 'ig-badges' }, badges);
+}
+/**
+ * The same badges, unwrapped, for a row that builds ONE badge row out of
+ * several sources — a priority chip, an evidence chip, a caveat chip and the
+ * relationships — which is what §16a draws. Returning the wrapper to such a
+ * caller left it either nesting one flex row inside another or reaching into
+ * the spec's children, and the second is how markup and its published
+ * behaviour drift.
+ */
+export function edgeBadgeList(document, keys) {
     const mine = new Set(keys);
     const badges = [];
     // COUNTED PAST THE BUDGET, NOT BUILT. The walk still visits every edge so
@@ -237,30 +863,273 @@ export function edgeBadges(document, keys) {
                 // is announced as one relationship rather than as two directions.
                 const outgoing = mine.has(edge.from);
                 const other = outgoing ? edge.to : edge.from;
-                const detail = treatment.symmetric || outgoing ? other : `${other} (incoming)`;
-                badges.push(edgeBadge(field, edgeId, detail));
+                // THE VOCABULARY WORDS IT, not this loop. `labelFrom` is the one
+                // construction of "which verb, read from which end", and §17a's
+                // inspector row draws the same edge from it one zone away.
+                const label = labelFrom(treatment, outgoing);
+                badges.push(edgeBadge(field, edgeId, label, other));
             }
         }
     }
-    if (badges.length === 0)
-        return null;
     if (omitted > 0)
         badges.push(overflowBadge(omitted));
-    return element('span', { class: 'ig-badges' }, badges);
+    return badges;
+}
+/**
+ * The VISIBLE TEXT of every chip a row's badge row draws, in order.
+ *
+ * EXPORTED FOR THE LAYOUT, which has to know how tall a card is before anything
+ * is rendered and cannot measure the DOM — this package is pure and its
+ * coordinates have to be the same on a server with no fonts as in a browser
+ * with them. Deriving the strings here rather than re-deriving them there is
+ * what keeps the reserved height and the drawn height about the same thing: a
+ * badge whose wording changes moves the geometry with it.
+ */
+export function badgeTexts(document, slot, issue, keys) {
+    // THROUGH `textOf` FOR EVERY CHIP, so the GLYPH is measured with the label it
+    // sits beside. Two of these were written out by hand and lost their glyph —
+    // `✓ verified` measured as `verified`, `⊘ not ready` as `not ready` — which
+    // under-measured exactly the chips a held row carries, and near a row
+    // boundary the browser wrapped one this packer had kept on the previous row.
+    // The builders are the one source; nothing here restates what they draw.
+    const chips = [
+        priorityBadge(issue?.provenance),
+        evidenceBadge(issue),
+        slot === undefined ? null : notReadyBadge(slot),
+        ...caveatBadges(issue),
+        ...edgeBadgeList(document, keys),
+    ];
+    return chips.filter((chip) => chip !== null).map(textOf);
+}
+/** Every string inside one spec, concatenated — what a reader sees on it. */
+function textOf(spec) {
+    let text = '';
+    for (const child of spec.children ?? []) {
+        if (child === null || child === undefined)
+            continue;
+        text += typeof child === 'string' ? child : textOf(child);
+    }
+    return text;
+}
+/**
+ * Everything one canvas card draws, in the order it draws it.
+ *
+ * `onSpine` decides the notes and nothing else: a spine card keeps its hold on
+ * a chip and a tooltip, because the list beside it prints the sentence, while a
+ * gutter card is the only mark the projection makes for its issue and §16b
+ * prints "open · not eligible" on it in as many words.
+ */
+export function cardBlocks(document, key, members, onSpine, now) {
+    const slot = document.order.slots.find((candidate) => candidate.lead === key);
+    const issue = document.byKey.get(key);
+    const blocks = [];
+    if (now) {
+        const job = document.host.running.find((candidate) => members.includes(candidate.key));
+        blocks.push({
+            kind: 'banner',
+            mark: 'now',
+            note: job === undefined ? '' : `${job.phase} · ${job.elapsed}`,
+        });
+    }
+    if (members.length > 1 && slot !== undefined) {
+        blocks.push({
+            kind: 'banner',
+            mark: `⧉ one unit · ${String(members.length)} issues`,
+            note: 'worked together',
+        });
+        blocks.push({ kind: 'unit', members });
+    }
+    else {
+        blocks.push({ kind: 'head', key });
+    }
+    const texts = badgeTexts(document, slot, issue, members);
+    if (texts.length > 0)
+        blocks.push({ kind: 'badges', texts });
+    if (!onSpine) {
+        for (const text of noteText(document, key))
+            blocks.push({ kind: 'note', text });
+    }
+    return blocks;
+}
+/**
+ * The sentences a card off the spine prints: why it is held, and what it
+ * duplicates.
+ *
+ * Lives here rather than in the layout for the reason {@link cardBlocks} gives:
+ * one description, two readers.
+ */
+export function noteText(document, key) {
+    const lines = [];
+    for (const slot of document.order.slots) {
+        if (slot.lead !== key)
+            continue;
+        for (const hold of slot.holds)
+            lines.push(hold.reason);
+    }
+    for (const exclusion of document.order.excluded) {
+        // THE BADGE ALREADY NAMES THE CANONICAL, so the sentence says only what the
+        // badge cannot: that this issue is never worked at all.
+        if (exclusion.key === key)
+            lines.push('never worked — the canonical is worked instead');
+    }
+    return lines;
+}
+/**
+ * The text runs one block puts on the card, each of which the layout wraps and
+ * counts as one or more lines.
+ *
+ * A `head` is a title AND an identity, and a `unit` is that pair per member —
+ * so the count is per RUN rather than per block, which is what lets the layout
+ * charge a wrapped title what it costs.
+ */
+export function cardText(document, block) {
+    switch (block.kind) {
+        case 'banner':
+            return [`${block.mark} ${block.note}`];
+        case 'head': {
+            const issue = document.byKey.get(block.key);
+            return [issue?.title ?? block.key, block.key];
+        }
+        case 'unit':
+            return block.members.flatMap((member) => [
+                document.byKey.get(member)?.title ?? member,
+                member,
+            ]);
+        case 'badges':
+            return block.texts;
+        case 'note':
+            return [block.text];
+    }
 }
-/** The legend. Rendered once per scene so the grammar is readable cold. */
+/**
+ * The legend: a footer bar under the drawing it explains.
+ *
+ * IT DRAWS THE LINE, NOT A CHIP OF IT. The claim this package makes about
+ * colour-blind safety is that each relationship is separable by dash pattern,
+ * terminal marker and glyph as well as hue — and a legend of five outlined
+ * chips shows none of the first two, so a reader meeting a dotted arc has
+ * nothing to match it against. Each sample is the same stroke and the same
+ * dash array the canvas uses, taken from `vocabulary.ts` rather than restated,
+ * and the terminal is the marker that edge actually ends in.
+ *
+ * THE READINESS KEY RIDES ALONG. The station fill is the parallelism channel —
+ * filled, hollow, dashed — and it is the one part of the grammar the edge table
+ * cannot explain, so §16b keys it at the far end of the same bar.
+ */
 export function legend() {
     return element('fieldset', { class: 'ig-legend' }, [
         element('legend', { class: 'ig-legend-caption' }, ['relationships']),
         ...EDGE_ORDER.map((field) => {
             const treatment = treatmentFor(field);
-            return element('span', { class: 'ig-badge', 'data-edge': field }, [
-                element('span', { class: 'ig-glyph', 'aria-hidden': 'true' }, [treatment.glyph]),
-                element('span', {}, [treatment.label]),
+            return element('span', { class: 'ig-legend-item' }, [
+                legendSample(field),
+                // THE PAIRING, NOT A COPY OF IT. This spelled the glyph span and the
+                // word out by hand — the same two elements `glyphAndLabel` returns,
+                // free to lose the `aria-hidden` that makes the mark silent, in the
+                // file whose own header calls that the failure the shared pairing
+                // exists to prevent.
+                ...glyphAndLabel(treatment.glyph, treatment.label),
             ]);
         }),
+        element('span', { class: 'ig-legend-keys' }, [
+            ...STATION_KEYS.map(([fill, label]) => element('span', { class: 'ig-legend-item' }, [station(fill), element('span', {}, [label])])),
+        ]),
     ]);
 }
+const STATION_KEYS = Object.freeze([
+    ['filled', 'ready now'],
+    ['hollow', 'ready after'],
+    ['dashed', 'held'],
+]);
+/** The width and height of one drawn legend sample, in CSS pixels. */
+const SAMPLE_WIDTH = 34;
+const SAMPLE_HEIGHT = 10;
+/**
+ * One relationship, drawn the way the canvas draws it.
+ *
+ * `together-with` is an enclosure rather than a line, so its sample is the
+ * rounded outline the canvas puts around a unit — drawing it as a line would
+ * be the legend teaching a shape the picture never uses.
+ */
+function legendSample(field) {
+    const treatment = treatmentFor(field);
+    const dash = dashArrayFor(treatment.dash);
+    const box = { width: String(SAMPLE_WIDTH), height: String(SAMPLE_HEIGHT), 'aria-hidden': 'true' };
+    const mid = SAMPLE_HEIGHT / 2;
+    // BUILT IN THE SVG NAMESPACE, and `element` does not put it there. That works
+    // by accident through `renderViewer`, whose output a host parses as HTML —
+    // but `mountViewer` materializes the same spec with `createElement`, which
+    // builds an HTML `<svg>` and HTML `<line>` children that draw nothing at all.
+    // So a mounted viewer showed five blank boxes where the legend's samples are,
+    // which is the whole of what the samples were added for.
+    if (treatment.dash === 'enclosure') {
+        return svg('svg', box, [
+            svg('rect', {
+                class: 'ig-enclosure',
+                'data-edge': field,
+                x: '1',
+                y: '1',
+                width: String(SAMPLE_WIDTH - 2),
+                height: String(SAMPLE_HEIGHT - 2),
+                rx: '3',
+            }),
+        ]);
+    }
+    const lines = treatment.dash === 'double'
+        ? [
+            lineSample(field, 1, SAMPLE_WIDTH, mid - 2, dash),
+            lineSample(field, 1, SAMPLE_WIDTH, mid + 2, dash),
+        ]
+        : [lineSample(field, 1, SAMPLE_WIDTH - 7, mid, dash)];
+    return svg('svg', box, [...lines, terminalSample(field, treatment.terminal, mid)]);
+}
+function lineSample(field, x1, x2, y, dash) {
+    return svg('line', {
+        class: 'ig-edge',
+        'data-edge': field,
+        x1: String(x1),
+        y1: String(y),
+        x2: String(x2),
+        y2: String(y),
+        ...(dash === null ? {} : { 'stroke-dasharray': dash }),
+    });
+}
+/** The sample's pointed end, in the shape the vocabulary names for that edge. */
+function terminalSample(field, terminal, y) {
+    const tip = SAMPLE_WIDTH;
+    switch (terminal) {
+        case 'arrow':
+            return svg('path', {
+                class: 'ig-terminal',
+                'data-edge': field,
+                fill: 'currentColor',
+                d: `M${String(tip - 7)},${String(y - 3)} L${String(tip)},${String(y)} L${String(tip - 7)},${String(y + 3)} z`,
+            });
+        case 'hollow-circle':
+            return svg('circle', {
+                class: 'ig-terminal',
+                'data-edge': field,
+                fill: 'none',
+                stroke: 'currentColor',
+                cx: String(tip - 3),
+                cy: String(y),
+                r: '3',
+            });
+        case 'tee':
+            return svg('line', {
+                class: 'ig-terminal',
+                'data-edge': field,
+                stroke: 'currentColor',
+                x1: String(tip - 2),
+                y1: String(y - 4),
+                x2: String(tip - 2),
+                y2: String(y + 4),
+            });
+        case 'none':
+        case 'enclosure':
+            return null;
+    }
+}
 /**
  * Every key a projection draws under some OTHER key's station, mapped to it.
  *