@issuegraph/editor 0.1.0

package/dist/workspace/rail.js

@@ -0,0 +1,216 @@
+/**
+ * The order rail: always present, always complete, and virtualised.
+ *
+ * ## The asymmetry with the canvas is the design, not an inconsistency
+ *
+ * §17f gives the two centre zones opposite obligations. The canvas answers
+ * "what surrounds this issue" and REFUSES above its budget — that is #10343's
+ * scale ladder, and it is correct. The rail answers "what gets worked next" for
+ * the whole backlog and must NEVER refuse. Assembling them must not average the
+ * two: a rail that paginates has stopped answering its question, and a canvas
+ * that tries to keep up with the rail has stopped honouring its budget.
+ *
+ * So virtualisation here is a requirement rather than an optimisation, and it
+ * is the resolution of what reads at first like a contradiction — "complete"
+ * and "windowed" at once.
+ *
+ * **The MODEL is complete; the WINDOW is bounded.** Every slot the host handed
+ * over is held, and {@link RailWindow.addressOf} answers for every rank in the
+ * order whether or not it is drawn. What is bounded is only how many rows are
+ * rendered at a time. Nothing is dropped, nothing is refused, and a host that
+ * scrolls asks for a different window over the same complete model.
+ *
+ * That is what "every rank is addressable" means, and it is the property the
+ * acceptance suite drives at 312 rows.
+ *
+ * ## `addressOf` is a closure over a private index
+ *
+ * The same shape — and the same reasoning — as `AuditOverlay.rowFor`. Handing
+ * out the index itself would let a JavaScript consumer mutate it, after which
+ * the lookups and `total` would disagree about what the order contains, which
+ * is the inconsistency this value exists to prevent. A closure cannot be
+ * reached at all, and still answers in constant time.
+ *
+ * ## What gets windowed
+ *
+ * Slots are sliced, and the issues and edges are cut down to exactly what the
+ * drawn rows need — a drawn slot's members, an exclusion's key, and the
+ * endpoints of any edge a drawn row owes a badge for.
+ *
+ * KEEPING THE WHOLE ISSUE LIST WAS THE OBVIOUS THING AND IT WAS WRONG. See the
+ * note at the filter itself for what it cost: the linear projection renders a
+ * count of the keys that appear in no slot and on no edge, so every edgeless
+ * issue outside the window was reported to the reader as isolated — the rail
+ * describing the reader's scroll position as though it were the document.
+ *
+ * `together-with` keeps its own rule, and it is layer 1's rather than a choice
+ * made here: that edge draws as an ENCLOSURE around one slot's members, so the
+ * viewer drops — and reports — any whose members no longer share a drawn slot.
+ * Those edges are left out of the windowed document and counted on
+ * {@link RailWindow.undrawn} instead, so the fact is reported as a property of
+ * the WINDOW rather than leaking out as a document defect.
+ */
+import { edgeIdentity } from '@issuegraph/core';
+import { normalizeDocument } from '@issuegraph/viewer';
+/**
+ * How many rows a window holds when the host does not say.
+ *
+ * A round number rather than a measured one: this package has no mount and
+ * therefore no viewport to measure, so any default here is a guess. It is
+ * published so a host can see what it is overriding, and generous enough that
+ * a first paint fills an ordinary screen.
+ */
+export const RAIL_WINDOW = 50;
+/**
+ * A finite integer, or the fallback.
+ *
+ * `NaN` is the one input that survives a clamp: `Math.max(0, Math.min(NaN, n))`
+ * is `NaN`, so it would flow into `slice` — which yields an empty window — and
+ * into `before`/`after`, which would then not sum to `total`. That is the rail
+ * silently reporting an order it cannot account for, on the zone whose whole
+ * contract is that it accounts for everything. `Infinity` clamps correctly and
+ * is admitted; only a non-number is replaced.
+ */
+function finite(value, fallback) {
+    const asked = value ?? fallback;
+    return Number.isNaN(asked) ? fallback : Math.trunc(asked);
+}
+/** Clamp a window onto an order of `total` slots. */
+function clampWindow(total, options) {
+    // Fractions and negatives are clamped rather than refused: this reads a
+    // scroll position, and a host computing one from a measured height will hand
+    // over a float sooner or later. Refusing would take the rail down over a
+    // rounding error, which is the one thing it may never do.
+    const count = Math.max(0, Math.min(finite(options.count, RAIL_WINDOW), total));
+    const start = Math.max(0, Math.min(finite(options.start, 0), total - count));
+    return { start, count };
+}
+/**
+ * Window an order without narrowing it.
+ *
+ * Pure, and total over any document: there is no input that makes this throw or
+ * refuse, because the rail is the zone that is not allowed to.
+ */
+export function railWindow(raw, options = {}) {
+    // IT NORMALIZES ITS OWN INPUT, like `inspectorView` and `renderWorkspace`.
+    // Every exported function in this module that takes a `ViewerDocument` now
+    // does, and that is the point: the reasoning was applied to one sibling and
+    // not the other, which left two public helpers with different contracts for
+    // the same argument.
+    //
+    // Slicing RAW slots is scroll-dependent on a malformed document. Layer 1
+    // keeps the FIRST placement of a key and drops the later one, so a duplicate
+    // straddling the window boundary became the valid placement whenever its
+    // earlier copy fell outside the slice — the visible order changing with the
+    // reader's position. `renderWorkspace` normalizing first fixed that for the
+    // workspace path and for nothing else; a direct caller of this still saw it.
+    //
+    // Idempotent, so the workspace normalizing first costs a pass and changes
+    // nothing. `total` therefore counts the slots the rail can actually show,
+    // which is the number a caller is asking about.
+    const input = normalizeDocument(raw).document;
+    const slots = input.order.slots;
+    const total = slots.length;
+    const { start, count } = clampWindow(total, options);
+    const rows = slots.slice(start, start + count);
+    // BUILT OVER EVERY SLOT, not the window. These are the indexes behind the two
+    // lookups, and narrowing them to the window is exactly the completeness bug
+    // this module exists to avoid.
+    const byRank = new Map();
+    const offsetByKey = new Map();
+    for (const [offset, slot] of slots.entries()) {
+        if (slot.rank !== null)
+            byRank.set(slot.rank, slot);
+        // FIRST WINS, matching `normalizeDocument`'s own rule for a key placed
+        // twice: it keeps the earlier slot and drops the later placement. A last-
+        // wins index here would send a host scrolling to a row the viewer never
+        // drew.
+        for (const member of slot.members)
+            if (!offsetByKey.has(member))
+                offsetByKey.set(member, offset);
+    }
+    // Which leads are drawn, so the `together-with` rule below can ask whether a
+    // unit survived the window.
+    const drawnLead = new Map();
+    for (const slot of rows)
+        for (const member of slot.members)
+            drawnLead.set(member, slot.lead);
+    // EVERY KEY THAT RENDERS A ROW, WHICH IS NOT THE SAME AS EVERY SLOT MEMBER.
+    // Exclusions are carried whole, and layer 1 draws each one as a footer row
+    // that calls `edgeBadges` for its own key — so an excluded row owes badges
+    // exactly like a slot does. Built from the slots alone, an excluded issue
+    // related only to an out-of-window slot lost its badge as the reader
+    // scrolled, on a row that never left the screen.
+    const drawnMember = new Set([
+        ...rows.flatMap((slot) => slot.members),
+        ...input.order.excluded.map((exclusion) => exclusion.key),
+    ]);
+    // AN EDGE IS KEPT WHEN A DRAWN ROW OWES A BADGE FOR IT — one endpoint on
+    // screen is enough, because that row draws the badge and the other end is
+    // named as text. `together-with` keeps its own rule: layer 1 draws it as an
+    // ENCLOSURE around one slot's members, so an edge whose members no longer
+    // share a drawn slot has nothing to draw it, and the viewer would report that
+    // as a document defect rather than as a fact about the window.
+    const drawable = (edge) => edge.field === 'together-with'
+        ? drawnLead.get(edge.from) !== undefined && drawnLead.get(edge.from) === drawnLead.get(edge.to)
+        : drawnMember.has(edge.from) || drawnMember.has(edge.to);
+    const edges = input.edges.filter(drawable);
+    // ISSUES ARE WINDOWED TOO, AND AN EARLIER VERSION OF THIS GOT IT WRONG in a
+    // way worth recording, because the reasoning that produced it was nearly
+    // right. It kept the WHOLE issue list, justified on the grounds that
+    // `normalizeDocument` reports a slot member that is not an issue and never
+    // the reverse — which is true, and is about DIAGNOSTICS. It is not about what
+    // gets DRAWN: the linear projection also renders a footer counting the keys
+    // that appear "in no slot and on no edge", so every edgeless issue outside
+    // the window was reported to the reader as an isolated issue. Windowing made
+    // the rail state a falsehood about the document, quietly, with no diagnostic
+    // anywhere — a justification that covered the surface it named and not the
+    // one that mattered.
+    //
+    // So the set is exactly what the drawn rows need, and nothing beyond it:
+    //
+    //   - a member of a drawn slot, or
+    //   - an exclusion's key, since an exclusion is a position too and the viewer
+    //     drops one whose key it cannot find, or
+    //   - an endpoint of a kept edge, so a badge pointing out of the window still
+    //     resolves rather than being dropped with a diagnostic.
+    //
+    // Every issue that survives is therefore placed, excluded, or on an edge —
+    // so windowing adds nothing to `isolated` and the footer goes back to
+    // describing the document rather than the scroll position.
+    const keep = new Set([
+        ...drawnMember,
+        ...input.order.excluded.map((exclusion) => exclusion.key),
+        ...edges.flatMap((edge) => [edge.from, edge.to]),
+    ]);
+    // EXCLUSIONS ARE CARRIED WHOLE, and that is a stated bound rather than an
+    // oversight. An excluded issue is one the order deliberately never works, so
+    // it holds no rank — and the window slices the SEQUENCE, which exclusions are
+    // not part of. Windowing them would need a second window with its own
+    // coordinate, for a population that is duplicates and is small by
+    // construction. A host that needs them bounded filters before calling.
+    const document = {
+        issues: input.issues.filter((issue) => keep.has(issue.key)),
+        edges,
+        order: { slots: rows, excluded: input.order.excluded },
+    };
+    // BY IDENTITY, so a document carrying the same connector twice reports one
+    // drop rather than two — and counted over the edges that did NOT survive,
+    // which is one pass rather than two set builds and a subtraction.
+    const undrawn = new Set(input.edges
+        .filter((edge) => edge.field === 'together-with' && !drawable(edge))
+        .map((edge) => edgeIdentity(edge.field, edge.from, edge.to))).size;
+    return {
+        total,
+        start,
+        count: rows.length,
+        before: start,
+        after: total - start - rows.length,
+        rows,
+        document,
+        undrawn,
+        addressOf: (rank) => byRank.get(rank),
+        offsetOf: (key) => offsetByKey.get(key),
+    };
+}
+//# sourceMappingURL=rail.js.map

package/dist/workspace/rail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rail.js","sourceRoot":"","sources":["../../src/workspace/rail.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC;AAwD9B;;;;;;;;;GASG;AACH,SAAS,MAAM,CAAC,KAAyB,EAAE,QAAgB;IACzD,MAAM,KAAK,GAAG,KAAK,IAAI,QAAQ,CAAC;IAChC,OAAO,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AAC5D,CAAC;AAED,qDAAqD;AACrD,SAAS,WAAW,CAAC,KAAa,EAAE,OAA0B;IAC5D,wEAAwE;IACxE,6EAA6E;IAC7E,yEAAyE;IACzE,0DAA0D;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IAC7E,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CACxB,GAAmB,EACnB,UAA6B,EAAE;IAE/B,2EAA2E;IAC3E,2EAA2E;IAC3E,4EAA4E;IAC5E,4EAA4E;IAC5E,qBAAqB;IACrB,EAAE;IACF,yEAAyE;IACzE,6EAA6E;IAC7E,yEAAyE;IACzE,4EAA4E;IAC5E,4EAA4E;IAC5E,6EAA6E;IAC7E,EAAE;IACF,0EAA0E;IAC1E,0EAA0E;IAC1E,gDAAgD;IAChD,MAAM,KAAK,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC9C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;IAChC,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;IAE/C,8EAA8E;IAC9E,4EAA4E;IAC5E,+BAA+B;IAC/B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC7C,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC9C,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC7C,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpD,uEAAuE;QACvE,0EAA0E;QAC1E,wEAAwE;QACxE,QAAQ;QACR,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO;YAAE,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC;gBAAE,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnG,CAAC;IAED,6EAA6E;IAC7E,4BAA4B;IAC5B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,IAAI;QAAE,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO;YAAE,SAAS,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IAE7F,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,0EAA0E;IAC1E,qEAAqE;IACrE,iDAAiD;IACjD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC;QAC1B,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC;QACvC,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC;KAC1D,CAAC,CAAC;IAEH,yEAAyE;IACzE,0EAA0E;IAC1E,4EAA4E;IAC5E,0EAA0E;IAC1E,8EAA8E;IAC9E,+DAA+D;IAC/D,MAAM,QAAQ,GAAG,CAAC,IAAqC,EAAW,EAAE,CAClE,IAAI,CAAC,KAAK,KAAK,eAAe;QAC5B,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/F,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAE7D,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAE3C,4EAA4E;IAC5E,yEAAyE;IACzE,qEAAqE;IACrE,2EAA2E;IAC3E,8EAA8E;IAC9E,4EAA4E;IAC5E,2EAA2E;IAC3E,6EAA6E;IAC7E,6EAA6E;IAC7E,2EAA2E;IAC3E,qBAAqB;IACrB,EAAE;IACF,yEAAyE;IACzE,EAAE;IACF,mCAAmC;IACnC,8EAA8E;IAC9E,6CAA6C;IAC7C,8EAA8E;IAC9E,4DAA4D;IAC5D,EAAE;IACF,2EAA2E;IAC3E,sEAAsE;IACtE,2DAA2D;IAC3D,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC;QACnB,GAAG,WAAW;QACd,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC;QACzD,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;KACjD,CAAC,CAAC;IAEH,0EAA0E;IAC1E,6EAA6E;IAC7E,8EAA8E;IAC9E,sEAAsE;IACtE,kEAAkE;IAClE,uEAAuE;IACvE,MAAM,QAAQ,GAAmB;QAC/B,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3D,KAAK;QACL,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE;KACvD,CAAC;IAEF,2EAA2E;IAC3E,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,OAAO,GAAG,IAAI,GAAG,CACrB,KAAK,CAAC,KAAK;SACR,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,KAAK,eAAe,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;SACnE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAC/D,CAAC,IAAI,CAAC;IAEP,OAAO;QACL,KAAK;QACL,KAAK;QACL,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,MAAM,EAAE,KAAK;QACb,KAAK,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,MAAM;QAClC,IAAI;QACJ,QAAQ;QACR,OAAO;QACP,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QACrC,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC;KACxC,CAAC;AACJ,CAAC"}

package/dist/workspace/render.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The three-zone workspace: the package's top-level surface.
+ *
+ * Rail on the left, canvas in the centre, inspector on the right, with the
+ * ambient audit count in the header. Every zone is COMPOSED from the leaf that
+ * already owns it — this file assembles, it does not re-derive.
+ *
+ * | zone      | comes from                                            |
+ * |-----------|-------------------------------------------------------|
+ * | header    | `auditOverlay` + `renderAuditHeader`                   |
+ * | rail      | `renderViewer(…, { projection: 'linear' })`, windowed  |
+ * | canvas    | `renderScaleLadder`                                    |
+ * | inspector | `inspectorView`, rendered here                         |
+ *
+ * ## The audit left-bar is applied to the rail's SPEC, never to its markup
+ *
+ * The rail's rows are layer 1's, and this package's standing rule is that
+ * nothing splices a rendered string — that is the hand-rolled escaping surface
+ * the spec grammar exists to remove, and `reevaluate/render.ts` records the
+ * same decision when it nests `scene.root` rather than concatenating chips into
+ * the rail.
+ *
+ * `scene.root` is DATA, and `KEY_ATTRIBUTE` is published, so {@link markRail}
+ * walks the spec tree and adds `data-ig-audit` to the keyed rows. That is a
+ * pure transform over a public value rather than a reach past a surface, and it
+ * means no attribute in this file is ever escaped by anything but `renderMarkup`.
+ *
+ * ## A row's severity is the heaviest across its MEMBERS
+ *
+ * A `together-with` unit is one row and several refs, and a finding can name a
+ * member that does not lead. Read off the lead alone, an affected unit renders
+ * clean — which is the audit failing silently on exactly the rows where an
+ * encoding error is hardest to see.
+ *
+ * ## The zone frames, and the one place a tag is written here
+ *
+ * Two of the four zones hand back a STRING rather than a spec — the ladder's
+ * chrome and the audit header — so the frames are assembled by concatenation,
+ * as `renderScaleLadder` already assembles its own canvas and chrome. What
+ * makes that safe is not care: {@link ZONES} is a closed union of literals, so
+ * no caller value can reach an attribute here at all, and `zones.test.ts` pins
+ * it. Everything with a dynamic value in it goes through `renderMarkup`.
+ *
+ * ## Dark only
+ *
+ * The pass-2 brief carries "light + dark" over from pass 1; light was cut after
+ * that pass, and dark-only is the decision rather than an omission. There is no
+ * forked token set here and no second palette: the theme is the viewer's, and
+ * `styles.ts` writes structure against its custom properties.
+ */
+import { type Theme, type ViewerDocument } from '@issuegraph/viewer';
+import type { AuditInput } from '../audit/findings.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 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 {
+    /** Shown in the inspector when nothing is selected. */
+    readonly nothingSelected: string;
+    /**
+     * The control that returns to nothing selected.
+     *
+     * NAMED FOR WHAT IT DOES, after a round of review found the previous name
+     * inviting a host to write the wrong sentence: called `clearFilter`, it read
+     * as "widen the list back", and the fixture here duly labelled it "show every
+     * relationship" — a button that emptied the panel it promised to fill. The
+     * command it publishes is `clear`, and that is the whole of its behaviour.
+     */
+    readonly clearSelection: string;
+    /** Names the relationships list. */
+    readonly relationships: string;
+}
+export interface WorkspaceOptions {
+    /**
+     * The words. Required, for the reason `ChangeWords` gives: this package does
+     * not invent an English sentence, and a default would be one.
+     */
+    readonly words: WorkspaceWords;
+    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 audit's input, when the host has one.
+     *
+     * ABSENT MEANS "NOT RUN", NOT "CLEAN", and the two render differently: with
+     * no input the header is left out entirely rather than drawn at zero, because
+     * a zero the reader can trust and a zero nobody computed are different facts.
+     */
+    readonly audit?: AuditInput | undefined;
+    /**
+     * Whether the audit filter is narrowing the rail to affected rows.
+     *
+     * THE HEADER PUBLISHES THE TOGGLE, SO SOMETHING HAS TO HOLD ITS STATE.
+     * `renderAuditHeader` draws a `button` with `aria-pressed`, and without this
+     * option every render answered `false` and left the rail unnarrowed — a
+     * control that could not complete the action it advertised, which is the
+     * finding the scale ladder already records paying for once. The ladder's note
+     * is also the resolution: layer 2 CAN narrow, and the assembling surface is
+     * the layer that holds the state to narrow with.
+     *
+     * Ignored with no audit, because there is nothing to filter by.
+     */
+    readonly auditFiltered?: boolean | undefined;
+    readonly theme?: Theme | undefined;
+    /** The selector the theme's custom properties are written onto. */
+    readonly themeSelector?: string | undefined;
+}
+export interface WorkspaceView {
+    readonly selection: WorkspaceSelection;
+    readonly rail: RailWindow;
+    readonly inspector: InspectorView;
+    /** `null` when no audit input was supplied — see {@link WorkspaceOptions.audit}. */
+    readonly audit: AuditOverlay | null;
+    /**
+     * Whether the rail was narrowed to affected rows.
+     *
+     * DERIVED, not echoed: it is `auditFiltered` AND an audit to filter by, so a
+     * caller reading this is reading what actually happened rather than what was
+     * asked for.
+     */
+    readonly auditFiltered: boolean;
+}
+export interface WorkspaceResult {
+    readonly view: WorkspaceView;
+    /** The whole surface: the four zones inside one root. */
+    readonly markup: string;
+    /** Every stylesheet this surface needs, in install order. */
+    readonly styles: string;
+    readonly diagnostics: readonly string[];
+}
+/** Render one document at one reader position, as the whole workspace. */
+export declare function renderWorkspace(input: ViewerDocument, options: WorkspaceOptions): WorkspaceResult;
+//# sourceMappingURL=render.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/workspace/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAIL,KAAK,KAAK,EACV,KAAK,cAAc,EASpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,UAAU,EAAiB,MAAM,sBAAsB,CAAC;AAGtE,OAAO,EAEL,KAAK,YAAY,EAKlB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,UAAU,EAAuB,MAAM,sBAAsB,CAAC;AAI5E,OAAO,EAA8B,KAAK,aAAa,EAAiB,MAAM,gBAAgB,CAAC;AAC/F,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAc,MAAM,WAAW,CAAC;AAChF,OAAO,EACL,KAAK,kBAAkB,EAIxB,MAAM,gBAAgB,CAAC;AAGxB,iFAAiF;AACjF,eAAO,MAAM,KAAK,oDAAoE,CAAC;AAEvF,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,oCAAoC;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACpD,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IAC9C;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACxC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,mEAAmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AA4MD,0EAA0E;AAC1E,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,gBAAgB,GACxB,eAAe,CA6JjB"}