@issuegraph/viewer 0.1.0

package/dist/document.d.ts

@@ -0,0 +1,190 @@
+/**
+ * The viewer's input: one normalised document, and nothing else.
+ *
+ * THIS IS A PLAIN, JSON-SAFE SHAPE ON PURPOSE. `@issuegraph/derive` describes
+ * its own return value as "an in-process value, not a payload" — it carries a
+ * live closure and two `Map`s, so it cannot cross a serialization boundary. A
+ * viewer that took it directly would be unusable from a server-rendered host, a
+ * worker, or anything that receives its data over a wire, and it would couple
+ * the innermost rendering layer to a package it is not allowed to need.
+ *
+ * So the shape here is a PROJECTION of that value rather than the value: a host
+ * that uses `deriveIssueOrder` maps it across in a few lines, and a host that
+ * ranks its backlog some other way supplies the same fields from its own
+ * source. The viewer derives no order, resolves no reference, and reads no
+ * tracker — everything it draws was given to it.
+ *
+ * `normalizeDocument` is the one entry point. It never throws: a document
+ * assembled by hand is untrusted input, not a contract, and a renderer that
+ * dies on a dangling edge is worse than one that draws what it can and says
+ * what it dropped.
+ */
+import { type EdgeField } from '@issuegraph/core';
+/**
+ * How an issue's rank came about, in the three forms the format and a host's
+ * own configuration can produce. The viewer FORMATS provenance; it never
+ * decides it — which is why every arm carries its own text rather than a code
+ * the viewer would have to interpret.
+ */
+export type RankProvenance = 
+/** A host ordering query matched this issue. `label` is the query as written. */
+{
+    readonly kind: 'matched-query';
+    readonly index: number;
+    readonly label: string;
+}
+/** No query matched; the issue sits in its declared priority tier. */
+ | {
+    readonly kind: 'declared-tier';
+    readonly priority: number;
+}
+/**
+ * Effective priority promoted it. `notation` is the spec's own `P3 -> 0`
+ * form and `promotedBy` names the open dependents the urgency arrived
+ * through — both supplied, because the viewer cannot recompute either.
+ */
+ | {
+    readonly kind: 'promotion';
+    readonly notation: string;
+    readonly promotedBy: readonly string[];
+};
+/** Where a hold came from. The two families never share a treatment. */
+export type HoldFamily = 
+/**
+ * The graph itself holds it — a `blocked-by` that is still open, or a
+ * serialize component someone else is in. These render INLINE at the rank
+ * the work would have taken, because "why isn't my P1 running" has to be
+ * answerable in place.
+ */
+'graph'
+/**
+ * The runner or the tracker holds it — claimed, parked, an external gate.
+ * These are not facts about the work, so they earn no rank slot and collapse
+ * into a footer group.
+ */
+ | 'tracker';
+/** One reason a slot is held, and which family it belongs to. */
+export interface ViewerHold {
+    readonly family: HoldFamily;
+    /** Human-readable, host-authored. The viewer renders it verbatim. */
+    readonly reason: string;
+}
+/** One issue the document knows about. */
+export interface ViewerIssue {
+    /** The model's node key: `"12"`, or `"owner/repo#12"` when qualified. */
+    readonly key: string;
+    /** Rendered as the row's leading text. Escaped at render; never parsed. */
+    readonly title: string;
+    /**
+     * The deep-link target for the `owner/repo#N` chip. OPTIONAL BY DESIGN: the
+     * viewer renders no link it was not given, because inventing one means
+     * knowing a tracker's URL shape, which is precisely the knowledge this layer
+     * must not carry.
+     */
+    readonly url?: string | undefined;
+    readonly open: boolean;
+    /** Declared priority, as the host resolved it. */
+    readonly priority: number;
+    /** Absent when the host has no provenance to state. */
+    readonly provenance?: RankProvenance | undefined;
+}
+/** One relationship, exactly as the format declares it. */
+export interface ViewerEdge {
+    readonly field: EdgeField;
+    readonly from: string;
+    readonly to: string;
+}
+/**
+ * One position in the order. A together unit is ONE slot with several members,
+ * not one slot per member — the same rule `@issuegraph/derive` applies, carried
+ * across so the two cannot disagree about what a position is.
+ */
+export interface ViewerSlot {
+    /**
+     * The 1-based rank, or `null` when the slot is held. A held slot renders `—`
+     * rather than a number: it has no position in the sequence, and printing one
+     * would claim work is queued that nothing can start.
+     */
+    readonly rank: number | null;
+    /** The member that placed the slot — the detail surface's subject. */
+    readonly lead: string;
+    /** Every member, in the order the host supplied. */
+    readonly members: readonly string[];
+    readonly ready: boolean;
+    /** Empty when ready. Each entry names one failed readiness condition. */
+    readonly holds: readonly ViewerHold[];
+    /**
+     * The rank this slot becomes ready after, when the host knows it. Drives the
+     * hollow readiness station; `null` renders a filled one when ready and a
+     * dashed one when held.
+     */
+    readonly readyAfterRank?: number | null | undefined;
+}
+/** An issue the order deliberately never works. */
+export interface ViewerExclusion {
+    readonly key: string;
+    /** The issue this one defers to. */
+    readonly canonical: string;
+    readonly reason: 'duplicate-of';
+}
+/** The order, as the host derived it. */
+export interface ViewerOrder {
+    /**
+     * Every slot in derivation order. A HELD slot keeps its position — it is
+     * never moved to the end — so its rank column reads `—` exactly where the
+     * work would have sat.
+     */
+    readonly slots: readonly ViewerSlot[];
+    readonly excluded: readonly ViewerExclusion[];
+}
+/** Everything the viewer draws. */
+export interface ViewerDocument {
+    readonly issues: readonly ViewerIssue[];
+    readonly edges: readonly ViewerEdge[];
+    readonly order: ViewerOrder;
+}
+/**
+ * A normalised document plus an index over it. The index exists so no
+ * projection re-scans the issue list per row, and so every projection resolves
+ * a key the same way.
+ */
+export interface NormalizedDocument {
+    readonly issues: readonly ViewerIssue[];
+    readonly edges: readonly ViewerEdge[];
+    readonly order: ViewerOrder;
+    /** Key -> issue. Every edge and slot member below is present here. */
+    readonly byKey: ReadonlyMap<string, ViewerIssue>;
+    /** Key -> the edges touching it, in document order. */
+    readonly edgesOf: ReadonlyMap<string, readonly ViewerEdge[]>;
+    /** Keys that appear in no slot and on no edge. */
+    readonly isolated: readonly string[];
+    /**
+     * Key -> the `decomposed-from` origin it declares that this document does not
+     * carry.
+     *
+     * KEPT RATHER THAN DROPPED WITH THE EDGE. The edge itself cannot be drawn —
+     * a node outside the set has no bounds — but the tree projection has to be
+     * able to say "this is a root because its origin is not here" instead of
+     * "this is a root". An absence rendered as a value licenses a false
+     * conclusion, and the false conclusion here is that an issue has no
+     * provenance when in fact its provenance was not supplied.
+     */
+    readonly outOfSetOrigins: ReadonlyMap<string, string>;
+}
+export interface NormalizeResult {
+    readonly document: NormalizedDocument;
+    /**
+     * What was dropped and why. A host surfaces these; the viewer does not draw
+     * them, because a diagnostic is a fact about the DATA and this layer renders
+     * the work order.
+     */
+    readonly diagnostics: readonly string[];
+}
+/**
+ * Read a document into the shape every projection consumes.
+ *
+ * Deterministic and total: the same input always produces the same output, and
+ * no input produces a throw. Call it once per render and pass the result down.
+ */
+export declare function normalizeDocument(input: ViewerDocument): NormalizeResult;
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/document.js

@@ -0,0 +1,308 @@
+/**
+ * The viewer's input: one normalised document, and nothing else.
+ *
+ * THIS IS A PLAIN, JSON-SAFE SHAPE ON PURPOSE. `@issuegraph/derive` describes
+ * its own return value as "an in-process value, not a payload" — it carries a
+ * live closure and two `Map`s, so it cannot cross a serialization boundary. A
+ * viewer that took it directly would be unusable from a server-rendered host, a
+ * worker, or anything that receives its data over a wire, and it would couple
+ * the innermost rendering layer to a package it is not allowed to need.
+ *
+ * So the shape here is a PROJECTION of that value rather than the value: a host
+ * that uses `deriveIssueOrder` maps it across in a few lines, and a host that
+ * ranks its backlog some other way supplies the same fields from its own
+ * source. The viewer derives no order, resolves no reference, and reads no
+ * tracker — everything it draws was given to it.
+ *
+ * `normalizeDocument` is the one entry point. It never throws: a document
+ * assembled by hand is untrusted input, not a contract, and a renderer that
+ * dies on a dangling edge is worse than one that draws what it can and says
+ * what it dropped.
+ */
+import { EDGE_CARDINALITY, isEdgeField, isSymmetricEdgeField, } from '@issuegraph/core';
+/**
+ * The schemes a deep link may carry.
+ *
+ * A DOCUMENT IS UNTRUSTED INPUT — this module says so at the top, and a `url`
+ * is the one field that becomes an executable surface when it reaches the DOM.
+ * `javascript:` and `data:` hrefs run in the host's origin, so escaping the
+ * attribute is not enough: the value has to be refused. An ALLOWLIST rather
+ * than a denylist, because the scheme space is open and a miss here publishes
+ * exactly the bug the check exists to stop.
+ *
+ * A relative URL is allowed: it cannot name a scheme, and a host embedding the
+ * viewer under its own routes has a legitimate reason to pass one.
+ */
+const LINKABLE_SCHEMES = new Set(['http:', 'https:', 'mailto:']);
+function isLinkable(url) {
+    // CANONICALIZE THE WAY A URL PARSER DOES, THEN READ THE SCHEME. Reading the
+    // raw string is not enough: the URL parser REMOVES every ASCII tab, newline
+    // and carriage return from ANYWHERE in the input before it reads anything,
+    // and then strips leading C0 controls and spaces. So `java<TAB>script:alert(1)`
+    // reaches the browser as `javascript:` while a raw scan finds no scheme at
+    // all, reads the value as relative, and links it.
+    //
+    // The test therefore has to canonicalize first. Stripping only the leading
+    // controls — which is what this did — left the whole embedded-control class
+    // open, which is the same fail-open the allowlist exists to close.
+    const canonical = url.replace(/[\t\n\r]/g, '').replace(/^[\x00-\x20]+/, '');
+    // A scheme is `ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ) ":"` (RFC 3986 3.1).
+    // No match means the value is relative, which carries no scheme to abuse.
+    const scheme = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(canonical);
+    if (scheme === null)
+        return true;
+    return LINKABLE_SCHEMES.has(`${scheme[1].toLowerCase()}:`);
+}
+function indexIssues(issues, diagnostics) {
+    const byKey = new Map();
+    const kept = [];
+    for (const issue of issues) {
+        if (issue.key === '') {
+            diagnostics.push('issue with an empty key dropped');
+            continue;
+        }
+        if (byKey.has(issue.key)) {
+            diagnostics.push(`duplicate issue key ${issue.key}: the first occurrence is kept`);
+            continue;
+        }
+        let kept_issue = issue;
+        if (issue.url !== undefined && issue.url !== '' && !isLinkable(issue.url)) {
+            diagnostics.push(`${issue.key} declares a url whose scheme the viewer will not link; the deep link was dropped`);
+            const { url: _dropped, ...rest } = issue;
+            kept_issue = rest;
+        }
+        byKey.set(issue.key, kept_issue);
+        kept.push(kept_issue);
+    }
+    return { kept, byKey };
+}
+/**
+ * An edge survives only when the format recognises its field AND both ends are
+ * issues this document carries.
+ *
+ * DROPPING A DANGLING EDGE IS THE POINT, not a shortcut. Every projection
+ * derives an endpoint from a node's computed bounds, and a node that does not
+ * exist has none — so an edge kept here would either be drawn at coordinates
+ * nobody computed or crash the layout. Dropping it and SAYING SO leaves the
+ * absence visible to the host, which is the only party that can resolve it.
+ */
+function indexEdges(edges, byKey, slotOf, diagnostics) {
+    const kept = [];
+    const edgesOf = new Map();
+    const outOfSetOrigins = new Map();
+    // SINGLE-CARDINALITY IS ASKED OF THE FORMAT, NOT LISTED HERE. `EDGE_CARDINALITY`
+    // names four single-reference fields and this guard used to enforce exactly
+    // one of them, so a document declaring two `duplicate-of` (or `serialize-with`,
+    // or `together-with`) edges from one issue kept both: two badges for one
+    // relationship and two graph paths, where the format promises one fact and
+    // this reader promises a diagnostic. Reading the constant means the fifth
+    // single field, whenever the spec adds one, is covered the day it lands.
+    // THE RULE BELONGS HERE, where the edges are read — not later, per projection.
+    // A second origin that resolved while the first did not left the tree nesting
+    // an issue under one parent while printing that it came from another, with
+    // neither the diagnostic nor the first-origin rule the projection promises.
+    // First declared wins, whether or not it resolves.
+    // KEYED ON (from, field), WHICH IS WHAT MAKES IT SAFE FOR THE SYMMETRIC FIELDS.
+    // `A together-with B` and `B together-with A` are one undirected fact written
+    // the way the format asks, and each endpoint declared ONCE — so keying on the
+    // endpoint PAIR would reject the reverse declaration as a repeat, and keying on
+    // the target would reject a legitimate three-member group in which B and C both
+    // point at A. Each issue gets one declaration; who points at it is not its
+    // budget to spend.
+    const claimed = new Set();
+    // Every edge's identity, symmetric or directed — see the branch below for what
+    // each key collapses.
+    const edgeSeen = new Set();
+    for (const edge of edges) {
+        if (!isEdgeField(edge.field)) {
+            diagnostics.push(`edge ${edge.from} -> ${edge.to} names an unknown field and was dropped`);
+            continue;
+        }
+        // BEFORE THE SYMMETRIC DEDUPE BELOW, AND THAT ORDER IS THE CORRECTNESS. The
+        // dedupe drops a symmetric edge's reverse declaration as a repeat of one
+        // fact — so counted after it, `B together-with A` would spend nothing, and a
+        // `B together-with C` arriving later would read as B's first declaration
+        // when it is really its second. Counting first means every declaration an
+        // author WROTE is counted, whatever the reader later collapses or drops.
+        if (EDGE_CARDINALITY[edge.field] === 'single') {
+            const claim = `${edge.field}\u0000${edge.from}`;
+            if (claimed.has(claim)) {
+                diagnostics.push(`${edge.from} declares more than one ${edge.field}; the format allows one, so only the first is kept and ${edge.to} was dropped`);
+                continue;
+            }
+            claimed.add(claim);
+        }
+        const missing = !byKey.has(edge.from) ? edge.from : !byKey.has(edge.to) ? edge.to : null;
+        if (missing !== null) {
+            // The edge cannot be drawn, but a missing PROVENANCE origin is worth
+            // remembering: the tree projection has to distinguish "no origin" from
+            // "an origin this document was not given".
+            if (edge.field === 'decomposed-from' && missing === edge.to && byKey.has(edge.from)) {
+                if (!outOfSetOrigins.has(edge.from))
+                    outOfSetOrigins.set(edge.from, edge.to);
+            }
+            diagnostics.push(`${edge.field} edge ${edge.from} -> ${edge.to} names ${missing}, which this document does not carry, and was dropped`);
+            continue;
+        }
+        if (edge.from === edge.to) {
+            diagnostics.push(`${edge.field} self-edge on ${edge.from} was dropped`);
+            continue;
+        }
+        // A `together-with` THE ORDER DOES NOT GROUP CANNOT BE DRAWN AT ALL. It is
+        // rendered as an enclosure around one slot's members rather than as an arc,
+        // and the enclosures come from the slot table — so an edge whose endpoints
+        // sit in different slots, or in none, produced no mark anywhere while still
+        // counting toward the relationship total the legend reports. Measured: a
+        // document with one such edge said "2 relationships" and drew one.
+        // DROPPED AND REPORTED RATHER THAN DRAWN SOME OTHER WAY. The alternative is a
+        // fallback connector, which invents a second visual form for one relationship
+        // and leaves the reader to reconcile them. The input is inconsistent — an
+        // author declared a grouping the order does not carry — and saying so is what
+        // this reader does with every other undrawable edge above.
+        // THE COUNT IS WHY IT MATTERS: it is taken from the kept edges, so dropping
+        // here makes the total the legend prints match what the canvas contains.
+        if (edge.field === 'together-with') {
+            const home = slotOf.get(edge.from);
+            if (home === undefined || home !== slotOf.get(edge.to)) {
+                diagnostics.push(`together-with edge ${edge.from} -> ${edge.to} is not carried by any one order slot, so nothing could draw it, and it was dropped`);
+                continue;
+            }
+        }
+        // A SYMMETRIC FIELD IS ONE UNDIRECTED FACT, so both endpoints declaring it
+        // is the NORMAL way to write it down, not a malformed document — and the
+        // reader that keeps both renders the one relationship twice: two badges,
+        // two paths, and a component edge count nobody can reconcile with what is
+        // drawn. Canonicalizing the pair collapses the reverse declaration AND a
+        // repeat of the same direction, because the identity of an undirected edge
+        // is its endpoint SET.
+        // NO DIAGNOSTIC. Unlike the drops above, nothing here is wrong with the
+        // document: `A serialize-with B` plus `B serialize-with A` is exactly what
+        // the format asks an author to write, so reporting it would train readers
+        // to ignore the diagnostics that do mean something.
+        // ONE FACT IS DRAWN ONCE, WHICHEVER DIRECTION THE FIELD HAS. The symmetric
+        // arm canonicalizes the endpoint PAIR, because `A serialize-with B` and
+        // `B serialize-with A` are one undirected fact. A DIRECTED field has no such
+        // equivalence — `A blocked-by B` and `B blocked-by A` are two different
+        // claims — but an EXACT repeat of one of them is still one relationship
+        // written twice, and this reader kept both: two identical paths, two badges,
+        // and a blocking count in the refusal summary inflated past what the canvas
+        // contains. Measured: `A blocked-by B` listed twice survived as two edges.
+        // THE KEY IS WHAT DIFFERS, not the rule. Symmetric collapses the reverse;
+        // directed keeps it and collapses only the exact triple — so the distinct
+        // `B -> A` edge is preserved, which is the half that must not be lost.
+        // NO DIAGNOSTIC, for the reason the symmetric arm already gives: a repeat is
+        // the format's normal redundancy rather than a malformed document, and
+        // reporting it would train readers to ignore the drops that do mean
+        // something.
+        const identity = isSymmetricEdgeField(edge.field)
+            ? edge.from < edge.to
+                ? `${edge.field}\u0000${edge.from}\u0000${edge.to}`
+                : `${edge.field}\u0000${edge.to}\u0000${edge.from}`
+            : `${edge.field}\u0000${edge.from}\u0000${edge.to}`;
+        if (edgeSeen.has(identity))
+            continue;
+        edgeSeen.add(identity);
+        kept.push(edge);
+        for (const end of [edge.from, edge.to]) {
+            const existing = edgesOf.get(end);
+            if (existing === undefined)
+                edgesOf.set(end, [edge]);
+            else
+                existing.push(edge);
+        }
+    }
+    return { kept, edgesOf, outOfSetOrigins };
+}
+/**
+ * A slot survives only when at least one member is an issue the document
+ * carries; unknown members are dropped from it, with a diagnostic each.
+ */
+function normalizeSlots(slots, byKey, diagnostics) {
+    const kept = [];
+    // ONE ISSUE HOLDS ONE PLACE IN THE ORDER. A hand-built document can name the
+    // same issue in two slots, and keeping both publishes the key twice: two rows
+    // render `tabindex="0"` for one focused key, while `indexOf` and the mount
+    // index can only ever address the first — so roving focus breaks and the
+    // later row is unreachable. The first placement wins, as everywhere else here.
+    const placed = new Set();
+    for (const slot of slots) {
+        const members = slot.members.filter((member) => {
+            if (!byKey.has(member)) {
+                diagnostics.push(`slot member ${member} is not an issue in this document and was dropped`);
+                return false;
+            }
+            if (placed.has(member)) {
+                diagnostics.push(`${member} is already placed in an earlier slot; the later placement was dropped`);
+                return false;
+            }
+            placed.add(member);
+            return true;
+        });
+        if (members.length === 0) {
+            diagnostics.push(`slot led by ${slot.lead} has no known member and was dropped`);
+            continue;
+        }
+        const lead = members.includes(slot.lead) ? slot.lead : members[0];
+        if (lead !== slot.lead) {
+            diagnostics.push(`slot lead ${slot.lead} is not among its members; ${lead} leads instead`);
+        }
+        kept.push(Object.freeze({ ...slot, lead, members: Object.freeze(members) }));
+    }
+    return { kept, placed };
+}
+/**
+ * Read a document into the shape every projection consumes.
+ *
+ * Deterministic and total: the same input always produces the same output, and
+ * no input produces a throw. Call it once per render and pass the result down.
+ */
+export function normalizeDocument(input) {
+    const diagnostics = [];
+    const { kept: issues, byKey } = indexIssues(input.issues, diagnostics);
+    // SLOTS BEFORE EDGES, because one edge rule needs to know them. `together-with`
+    // is drawn as an ENCLOSURE around a slot's members rather than as an arc, so an
+    // edge whose endpoints are not in one slot has nothing to draw it — and
+    // `indexEdges` is where an undrawable edge is dropped and reported. Nothing in
+    // `normalizeSlots` reads the edges, so the two are free to swap.
+    const { kept: slots, placed } = normalizeSlots(input.order.slots, byKey, diagnostics);
+    // WHICH SLOT OWNS EACH KEY, which is the whole question the rule asks.
+    const slotOf = new Map();
+    for (const slot of slots)
+        for (const member of slot.members)
+            slotOf.set(member, slot.lead);
+    const { kept: edges, edgesOf, outOfSetOrigins } = indexEdges(input.edges, byKey, slotOf, diagnostics);
+    // AN EXCLUSION IS A POSITION TOO. The rule is one issue, one position — and
+    // it has to cover this field as well as the slots, because the projections
+    // publish both into one focus order. A key in a slot AND in `excluded`, or
+    // twice in `excluded`, rendered two keyed rows: `ArrowDown` from the first
+    // resolved to the same key and returned `none`, so nothing after it was
+    // reachable.
+    const excluded = input.order.excluded.filter((exclusion) => {
+        if (!byKey.has(exclusion.key)) {
+            diagnostics.push(`excluded ${exclusion.key} is not an issue in this document and was dropped`);
+            return false;
+        }
+        if (placed.has(exclusion.key)) {
+            diagnostics.push(`${exclusion.key} already holds a position in the order; the exclusion was dropped`);
+            return false;
+        }
+        placed.add(exclusion.key);
+        return true;
+    });
+    const isolated = issues
+        .filter((issue) => !placed.has(issue.key) && (edgesOf.get(issue.key) ?? []).length === 0)
+        .map((issue) => issue.key);
+    return Object.freeze({
+        document: Object.freeze({
+            issues: Object.freeze(issues),
+            edges: Object.freeze(edges),
+            order: Object.freeze({ slots: Object.freeze(slots), excluded: Object.freeze(excluded) }),
+            byKey,
+            edgesOf,
+            isolated: Object.freeze(isolated),
+            outOfSetOrigins,
+        }),
+        diagnostics: Object.freeze(diagnostics),
+    });
+}
+//# sourceMappingURL=document.js.map

package/dist/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}

package/dist/element.d.ts

@@ -0,0 +1,95 @@
+/**
+ * One description of rendered structure, and the two renderers that consume it.
+ *
+ * A projection returns an {@link ElementSpec} tree. {@link renderMarkup} turns
+ * it into a string — server rendering, and every test in this package that
+ * asserts what is drawn. {@link materialize} builds the same tree out of real
+ * nodes for {@link ../mount.ts mountViewer}.
+ *
+ * THE POINT IS THAT THEY CANNOT DISAGREE. The obvious alternative — build
+ * markup, then set `innerHTML` — makes the string path and the node path one
+ * implementation but leaves the package unable to render without a parser; the
+ * other obvious alternative, writing the DOM path separately, makes them two
+ * implementations that drift. One spec with two total walks over it is the only
+ * arrangement where a test on the markup is evidence about the nodes.
+ *
+ * Nothing here reaches a global. {@link materialize} takes the document it
+ * builds into, which is what keeps this module importable on a runtime that has
+ * no DOM at all.
+ */
+/** Attribute values a spec may carry. `false`, `null` and `undefined` omit it. */
+export type AttrValue = string | number | boolean | null | undefined;
+export interface ElementSpec {
+    readonly tag: string;
+    /** `svg` puts this element and its subtree in the SVG namespace. */
+    readonly ns?: 'svg' | undefined;
+    readonly attrs?: Readonly<Record<string, AttrValue>> | undefined;
+    readonly children?: readonly SpecChild[] | undefined;
+}
+export type SpecChild = ElementSpec | string;
+export declare const SVG_NAMESPACE = "http://www.w3.org/2000/svg";
+/**
+ * Render a spec tree to markup.
+ *
+ * Pure and deterministic: attribute order follows the spec's own key order, so
+ * the same tree always produces the same bytes. That is what makes a
+ * two-themes-one-markup assertion possible.
+ *
+ * ITERATIVE, LIKE EVERY OTHER WALK IN THIS PACKAGE. A recursive renderer costs
+ * one call frame per level of nesting, and the tree projection's depth is the
+ * host's `decomposed-from` chain — which nothing bounds. `renderViewer`
+ * documents itself as TOTAL, so a document that makes it throw falsifies the
+ * claim whatever the depth was. This was the third stack-depth finding on this
+ * package; making the traversal iterative removes the class rather than
+ * capping the input, which would have invented a product rule the design does
+ * not have.
+ */
+export declare function renderMarkup(spec: ElementSpec, inheritedNs?: 'svg' | undefined): string;
+/**
+ * The slice of `Document` this package builds with.
+ *
+ * Declared structurally rather than as `Document` so a host can pass any
+ * implementation that answers these five calls — and so this module stays
+ * honest about how little of the DOM it actually needs.
+ */
+export interface SpecDocument {
+    createElement(tag: string): SpecElement;
+    createElementNS(namespace: string, tag: string): SpecElement;
+    createTextNode(text: string): SpecNode;
+}
+export interface SpecNode {
+    readonly nodeType?: number;
+}
+export interface SpecElement extends SpecNode {
+    setAttribute(name: string, value: string): void;
+    appendChild(child: SpecNode): void;
+    /**
+     * Optional because building a tree never needs it — only the shell's roving
+     * tab stop does, and an implementation that cannot move focus should be able
+     * to say so by omitting it rather than by throwing.
+     */
+    focus?(): void;
+}
+export interface MaterializeOptions {
+    readonly ns?: 'svg' | undefined;
+    /**
+     * Called for every element as it is built. `mount` uses it to index the
+     * elements carrying a key, which is cheaper and less brittle than walking the
+     * finished tree back down — and it keeps this module to ONE traversal, so the
+     * markup and the node paths cannot diverge in how they descend.
+     */
+    readonly onElement?: ((spec: ElementSpec, element: SpecElement) => void) | undefined;
+}
+/**
+ * Build a spec tree as nodes in the supplied document.
+ *
+ * Attributes follow `renderMarkup`'s rules exactly — same omissions, same
+ * number coercion, same bare-attribute handling for `true` — because the two
+ * walks are only useful as one grammar.
+ */
+export declare function materialize(doc: SpecDocument, spec: ElementSpec, options?: MaterializeOptions): SpecElement;
+/** A spec, with `undefined` children dropped — the common conditional-child case. */
+export declare function element(tag: string, attrs: Readonly<Record<string, AttrValue>>, children?: readonly (SpecChild | null | undefined | false)[]): ElementSpec;
+/** The same, in the SVG namespace. */
+export declare function svg(tag: string, attrs: Readonly<Record<string, AttrValue>>, children?: readonly (SpecChild | null | undefined | false)[]): ElementSpec;
+//# sourceMappingURL=element.d.ts.map

package/dist/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../src/element.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,kFAAkF;AAClF,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAErE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,CAAC;CACtD;AAED,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,MAAM,CAAC;AAE7C,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAiD1D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,CAyCvF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;IACxC,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7D,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;CACxC;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CACtF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAwDb;AAED,qFAAqF;AACrF,wBAAgB,OAAO,CACrB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EAC1C,QAAQ,GAAE,SAAS,CAAC,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,EAAO,GAC/D,WAAW,CAQb;AAED,sCAAsC;AACtC,wBAAgB,GAAG,CACjB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,EAC1C,QAAQ,GAAE,SAAS,CAAC,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,CAAC,EAAO,GAC/D,WAAW,CAEb"}