@beehexa/hexasync-template-model 2608.20.18 → 2608.20.32

package/dist/flowRender.js

@@ -0,0 +1,316 @@
+/**
+ * Mermaid and Markdown emission — the primitives both flow packages render through (Story 4.3).
+ *
+ * ### Why this is in `model` rather than a package of its own
+ *
+ * `PACKAGE-CONTRACT.md` §5 says the renderers are *"exported from both flow packages over the shared model"*, and
+ * AD-21 forbids those two packages importing each other — so the shared half cannot live in either. A package of its
+ * own would make both flow packages depend on it, contradicting Story 4.1 Task 1's *"zero runtime dependencies beyond
+ * `hexasync-template-model`"*.
+ *
+ * It belongs here on its own merits: `renderedNodeId` — the `:` → `__` projection every diagram id goes through — is
+ * already in this package and is already half a renderer. The address algebra and the emission algebra are one
+ * subject.
+ *
+ * ### What each rule below cost to learn
+ *
+ * **1. Every subgraph emits its OWN direction.** Mermaid ignores the parent chart's direction inside a subgraph, so a
+ * `TD` chart with `LR` stages needs the statement repeated per subgraph. (`PACKAGE-CONTRACT.md` §5 rule 1.)
+ *
+ * **2. Styling is PER ELEMENT — `style` and `linkStyle`, not `class`/`classDef`.** dashboard's own comment is the
+ * evidence: *"`classDef` did NOT reliably apply to node shapes in v11 — edges highlighted but nodes/diamonds did
+ * not."* A class-based overlay silently highlights the arrows and leaves the boxes plain.
+ *
+ * **3. …with ONE exception, and it is not a contradiction.** The VS Code extension uses `classDef` successfully — for
+ * `stroke-width` only, never a fill — precisely so the **webview's stylesheet** can colour it from theme variables. A
+ * literal colour would be wrong in one of light or dark. So: per-element `style` for anything carrying a COLOUR (which
+ * the caller supplies), `classDef` for a shape hint a stylesheet should own. Both are offered; neither is guessed.
+ *
+ * **4. A `classDef` inside a `subgraph` is a PARSE ERROR in mermaid 11**, which is why class declarations are hoisted
+ * to the end of the chart rather than emitted beside the nodes they name.
+ *
+ * **5. A colour is VALIDATED, and an unusable one drops the highlight rather than the chart.** Measured with the real
+ * mermaid 11 parser: `#hex` and a bare identifier (`red`) parse; `rgba(…)`, `rgb(…)`, `hsl(…)` and `var(--x)` are
+ * **parse errors** in `style` and `linkStyle` alike. dashboard's comment — ported here verbatim at first — said such
+ * colours *"fall back to a stroke-only highlight"*, and that was false in both directions: a named colour never broke
+ * anything, and an `rgba` did not degrade, it destroyed the diagram. A fill tint still needs exactly `#rrggbb`,
+ * because the tint is 8-digit-hex alpha and has nothing to append to otherwise.
+ *
+ * **6. The same `(model, opts)` always produces the same string.** No clock, no randomness, no ambient state — the
+ * golden-diagram suite depends on it (AD-29), which is also why the overlay is an ARGUMENT and never state.
+ */
+import { renderedNodeId } from './nodeAddress.js';
+/**
+ * Words mermaid's flowchart grammar owns. A node id or class name spelled as one is a parse error.
+ *
+ * Verified against mermaid 11 by the Story 4.3 review: `end`, `graph`, `subgraph`, `style` and `class` each break the
+ * parse, while `direction`, `o`, `x` and `0` do not — so this is the measured set rather than a cautious guess.
+ */
+const MERMAID_RESERVED = new Set([
+    'end',
+    'graph',
+    'subgraph',
+    'style',
+    'class',
+    'classdef',
+    'linkstyle',
+    'click',
+    'flowchart',
+]);
+/** Mermaid's own spelling: a chart is `TD`, a subgraph is `TB`. */
+const subgraphDirection = (direction) => direction === 'TD' ? 'TB' : 'LR';
+/**
+ * A label, safe inside `["…"]`.
+ *
+ * ⚠️ Escaping lives HERE, and Story 4.2's review is why it is written down: the frontend port moved escaping out of
+ * the model layer without recording that it had moved, and **4 real labels carry a raw newline**
+ * (`ShoplinePublicApp.yaml`). A renderer that forgets breaks a real connector's diagram.
+ *
+ * The `&` replacement comes FIRST, or the entities the later rules produce would themselves be re-escaped.
+ */
+export function escapeLabel(value) {
+    return value
+        .replace(/[\r\n]+/g, ' ')
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .trim();
+}
+/**
+ * A label guaranteed non-empty — because an empty one is a **mermaid parse error that kills the whole diagram**.
+ *
+ * ⛔ Story 4.3 review, CRITICAL-1, found with the real mermaid 11 parser. `escapeLabel` ends in `.trim()`, so a label
+ * that is non-empty in the model can become `''`, and `["${''}"]` is rejected outright: *"Expecting …, got
+ * 'STADIUMEND'"*. Not one blank node — **no chart at all**.
+ *
+ * Four reachable inputs, each verified end to end through the real builders: `if: ""` on an IF step (the route graph
+ * maps it to the label `''`, since only `null`/`undefined` become `'?'`), `next: '   '`, `next: '\n'`, and a SWITCH
+ * whose case key is `' '`. One keystroke of YAML.
+ *
+ * A regression relative to the authorities rather than a ported flaw: neither dashboard's nor the CLI's `escapeLabel`
+ * trims, so neither can manufacture an empty label.
+ */
+function safeLabel(value, fallback) {
+    const escaped = escapeLabel(value);
+    if (escaped !== '')
+        return escaped;
+    // The fallback is escaped too, and if THAT is empty the node still needs something a reader can see.
+    const escapedFallback = escapeLabel(fallback);
+    return escapedFallback === '' ? '?' : escapedFallback;
+}
+/**
+ * A colour mermaid's grammar accepts in a `style` / `linkStyle` declaration.
+ *
+ * ⛔ Story 4.3 review, CRITICAL-2. Rule 5 below used to claim a non-hex colour *"falls back to a stroke-only
+ * highlight, which is still clearly visible"*. Measured against the real parser, that is false in **both**
+ * directions: a bare identifier like `red` parses fine (so withholding its fill achieved nothing), while
+ * `rgba(255,0,0,.5)`, `rgb(…)`, `hsl(…)` and `var(--x)` are **parse errors** — in `style` AND in `linkStyle`, which
+ * had no guard at all. So the documented safety net did not exist, and the chart died instead of degrading.
+ *
+ * It matters more here than in the Vue caller it was ported from: this is a published library whose contract invites
+ * the caller to supply a colour, and a theme token (`var(--vscode-focusBorder)`, an `rgba` from a palette) is the most
+ * likely thing a webview or dashboard reaches for.
+ *
+ * So an unusable colour drops the whole highlight rather than emitting a declaration that cannot parse.
+ */
+function usableColor(color) {
+    if (color === undefined)
+        return undefined;
+    const trimmed = color.trim();
+    // `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, or a bare identifier — the two forms the grammar takes.
+    return /^#[0-9a-fA-F]{3,8}$/.test(trimmed) ||
+        /^[A-Za-z][A-Za-z0-9-]*$/.test(trimmed)
+        ? trimmed
+        : undefined;
+}
+/** One node line, shaped by what the node is. */
+function nodeLine(node) {
+    const id = renderedNodeId(node.address);
+    // The address is the fallback: never empty, and it names the node a reader can look up.
+    const label = safeLabel(node.label, node.address);
+    if (node.decides === true)
+        return `    ${id}{"${label}"}`;
+    if (node.terminal === true)
+        return `    ${id}(["${label}"])`;
+    return `    ${id}["${label}"]`;
+}
+function edgeLine(edge) {
+    const from = renderedNodeId(edge.from);
+    const to = renderedNodeId(edge.to);
+    /**
+     * Emptiness is tested on the ESCAPED value, not the raw one (CRITICAL-1).
+     *
+     * The guard used to read the raw label and then emit the escaped one, so `label: '   '` took the labelled branch and
+     * emitted `-->|""|` — a parse error. An unlabelled arrow is the right answer for a label that escapes to nothing.
+     */
+    const label = edge.label === undefined ? '' : escapeLabel(edge.label);
+    return label === ''
+        ? `    ${from} --> ${to}`
+        : `    ${from} -->|"${label}"| ${to}`;
+}
+/**
+ * A per-element node style: a strong border, plus a fill tint only when the colour admits one.
+ *
+ * The fill is 8-digit-hex alpha, so it needs exactly 6 hex digits to append to — which is the REAL reason a named
+ * colour gets no fill. (Rule 5's comma story is true of `rgba(…)` and was never true of `red`; the caller's colour is
+ * validated by `usableColor` before it reaches here, so the comma case can no longer arrive at all.)
+ */
+function nodeStyle(address, color) {
+    const fill = /^#[0-9a-fA-F]{6}$/.test(color) ? `,fill:${color}24` : '';
+    return `  style ${renderedNodeId(address)} stroke:${color},stroke-width:3px${fill}`;
+}
+/**
+ * The diagram.
+ *
+ * Deterministic for a given `(groups, edges, opts)`: every list is emitted in the order given, duplicates are
+ * collapsed by first appearance, and nothing consults the clock or the environment.
+ */
+export function renderMermaid(groups, edges, opts = {}) {
+    const direction = opts.direction ?? 'TD';
+    const multiStage = opts.multiStage ?? groups.length > 1;
+    const lines = [`flowchart ${direction}`];
+    /**
+     * Nothing to draw ⇒ SAY SO (Story 4.3 review, MED-1 / MEDIUM-3).
+     *
+     * A bare `flowchart TD` parses and renders a blank box, and a titled Markdown section wrapping one is
+     * indistinguishable from a failure. Measured against `epic-4-ground-truth.md`: the shipped renderer had invented a
+     * fourth answer where the note says one of three must be chosen.
+     */
+    if (groups.every((group) => group.nodes.length === 0)) {
+        return [
+            ...lines,
+            `    empty["${safeLabel(opts.emptyLabel ?? 'No steps', 'No steps')}"]`,
+        ].join('\n');
+    }
+    const emitted = new Set();
+    const push = (line) => {
+        if (emitted.has(line))
+            return;
+        emitted.add(line);
+        lines.push(line);
+    };
+    const drawn = new Set();
+    for (const group of groups) {
+        if (multiStage && group.title !== undefined) {
+            lines.push(`  subgraph ${renderedNodeId(group.key)}["${escapeLabel(group.title)}"]`);
+            // Rule 1: its OWN direction, because the parent's is ignored inside a subgraph.
+            lines.push(`    direction ${subgraphDirection(direction)}`);
+        }
+        for (const node of group.nodes) {
+            push(nodeLine(node));
+            drawn.add(node.address);
+        }
+        if (multiStage && group.title !== undefined)
+            lines.push('  end');
+    }
+    for (const edge of edges) {
+        // An edge naming a node no group drew would render mermaid's own placeholder box, silently inventing a node.
+        if (!drawn.has(edge.from) || !drawn.has(edge.to))
+            continue;
+        push(edgeLine(edge));
+    }
+    /**
+     * The overlay — per element, and AFTER the nodes so a style statement always names something already drawn.
+     *
+     * `errored` is applied second deliberately: a node that both ran and failed should read as failed.
+     */
+    /**
+     * Class declarations come BEFORE the overlay (Story 4.3 review, MED-4).
+     *
+     * The commit claimed *"a chart rendered with an overlay still begins with the chart rendered without one"* — true
+     * only while `shapeClasses` was absent, because the class block was emitted after the overlay and so shifted when an
+     * overlay appeared. Classes first makes the overlay genuinely the last thing in the file, so the additive property
+     * holds for every combination rather than the subset the tests happened to cover.
+     *
+     * Still hoisted out of every subgraph, which is what rule 4 is about, and still declared once per class name.
+     */
+    for (const shapeClass of opts.shapeClasses ?? []) {
+        const members = shapeClass.addresses.filter((a) => drawn.has(a));
+        if (members.length === 0)
+            continue;
+        /**
+         * The class NAME reaches mermaid verbatim, so a space or a RESERVED WORD is a parse error (review LOW). Refused
+         * rather than emitted, because one bad class name would cost the whole chart rather than one style.
+         *
+         * `end` is the one a caller would plausibly reach for — a terminal-node class — and it is exactly the word that
+         * closes a subgraph.
+         */
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(shapeClass.name) ||
+            MERMAID_RESERVED.has(shapeClass.name.toLowerCase())) {
+            continue;
+        }
+        push(`  classDef ${shapeClass.name} ${shapeClass.declaration}`);
+        push(`  class ${members.map((a) => renderedNodeId(a)).join(',')} ${shapeClass.name}`);
+    }
+    const overlay = opts.overlay;
+    if (overlay) {
+        const traversedColor = usableColor(overlay.colors?.traversed);
+        const erroredColor = usableColor(overlay.colors?.errored);
+        if (traversedColor !== undefined) {
+            for (const address of overlay.traversed ?? []) {
+                if (drawn.has(address))
+                    push(nodeStyle(address, traversedColor));
+            }
+        }
+        if (erroredColor !== undefined) {
+            for (const address of overlay.errored ?? []) {
+                if (drawn.has(address))
+                    push(nodeStyle(address, erroredColor));
+            }
+        }
+        /**
+         * Edges are styled by INDEX (`linkStyle 3 …`), which is why the index has to be the one mermaid will assign — the
+         * position of the edge among those actually emitted, not among those the model holds.
+         */
+        const highlight = new Set([
+            ...(overlay.traversed ?? []),
+            ...(overlay.errored ?? []),
+        ]);
+        const drawnEdges = edges.filter((e) => drawn.has(e.from) && drawn.has(e.to));
+        const seenEdge = new Set();
+        let index = -1;
+        for (const edge of drawnEdges) {
+            const key = edgeLine(edge);
+            if (seenEdge.has(key))
+                continue;
+            seenEdge.add(key);
+            index += 1;
+            if (!highlight.has(edge.from) || !highlight.has(edge.to))
+                continue;
+            const color = (overlay.errored ?? []).includes(edge.to) ||
+                (overlay.errored ?? []).includes(edge.from)
+                ? erroredColor
+                : traversedColor;
+            if (color !== undefined) {
+                push(`  linkStyle ${index} stroke:${color},stroke-width:3px`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * A titled section with a fenced diagram, and nothing else (rule 3).
+ *
+ * What the composition report embeds and what an MCP resource serves — the same string, because two surfaces
+ * describing one flow disagreeing is the defect this epic exists to remove.
+ */
+export function renderMarkdown(title, groups, edges, opts = {}) {
+    return [
+        /**
+         * The title is COLLAPSED, not HTML-escaped (Story 4.3 review, MEDIUM-4).
+         *
+         * A newline would end the heading and turn the diagram into body text, so collapsing is required. Entity-escaping
+         * is not: §5 says this string is what an MCP resource and the composition report both serve, and served as text
+         * `Orders &amp; Returns` reads as visible noise. Only an HTML consumer would decode it, and a heading is not a
+         * mermaid label.
+         */
+        `### ${title.replace(/[\r\n]+/g, ' ').trim()}`,
+        '',
+        '```mermaid',
+        renderMermaid(groups, edges, opts),
+        '```',
+        '',
+    ].join('\n');
+}
+//# sourceMappingURL=flowRender.js.map

package/dist/flowRender.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { normalizeUri, joinUri, dirnameUri, basenameUri, resolveUri, relativeUri, isAbsoluteUri, isInsideUri, } from './uriPath.js';
+export { normalizeComponentKey } from './componentKey.js';
+export { ADDRESS_SEPARATOR, RENDERED_SEPARATOR, keySegment, identitySegment, entrySegment, nodeAddress, renderedNodeId, addressSegments, addressMatches, addressForRenderedId, type AddressSegment, } from './nodeAddress.js';
+/**
+ * A token rename applied to an inherited component (`replacements` on an external).
+ *
+ * Moved here from `apps/cli/src/helpers/@types` in Story 1.2: it is part of the composer's
+ * domain vocabulary, and leaving it in the binary would have made every relocated core module
+ * depend on the app — the exact direction AD-3 forbids.
+ */
+export interface IExternalReplacement {
+    fromKey: string;
+    toKey: string;
+    value: string | number | null;
+}
+export { COMPOSE_CONTRACT_VERSION, compareComposeContract, type ContractComparison, } from './contract.js';
+export { classifyTemplating, hasComposeTimeTemplating, composeTimeKeys, type TemplatingLayer, type RuntimeReference, type TemplateOccurrence, } from './templating.js';
+/**
+ * Which properties name another component (Phase 2 Story 1.2).
+ *
+ * Lives in `template-model` rather than in the index because reference kinds are domain VOCABULARY,
+ * not index machinery: the validation rules need them as much as the graph does, and a registry
+ * reachable from only one of the two surfaces is how a rule gets wired into the CLI and forgotten in
+ * the editor (FR-54, counter-metric C3). `template-model` is the base package both already depend on.
+ */
+export * from './references.js';
+export * from './connectorSupport.js';
+export { renderMermaid as renderFlowMermaid, renderMarkdown as renderFlowMarkdown, escapeLabel, type RenderNode, type RenderEdge, type RenderGroup, type RenderOptions, type RenderOverlay, type FlowDirection, } from './flowRender.js';
+export { composeNodeLabel, glyphOfStepType, familyOfStepType, } from './stepGlyph.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,YAAY,EACZ,OAAO,EACP,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAI1D,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACd,oBAAoB,EACpB,KAAK,cAAc,GACpB,MAAM,kBAAkB,CAAC;AAE1B;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AACH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,uBAAuB,CAAC;AAItC,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,cAAc,IAAI,kBAAkB,EACpC,WAAW,EACX,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,28 @@
+// Domain types for HexaSync templates, and the URI path algebra the whole system shares.
+//
+// The algebra lives in core because AD-18 requires ONE canonical identity: if each adapter
+// canonicalized paths its own way, the Node host and the web host could disagree about whether
+// two references point at the same file, and cycle detection and diamond dedupe would silently
+// differ between them.
+export { normalizeUri, joinUri, dirnameUri, basenameUri, resolveUri, relativeUri, isAbsoluteUri, isInsideUri, } from './uriPath.js';
+export { normalizeComponentKey } from './componentKey.js';
+// AD-33 — a node is addressed by its path. One scheme for the diagram click target, the provenance anchor and an
+// MCP citation, which is why it is here and not in a flow package.
+export { ADDRESS_SEPARATOR, RENDERED_SEPARATOR, keySegment, identitySegment, entrySegment, nodeAddress, renderedNodeId, addressSegments, addressMatches, addressForRenderedId, } from './nodeAddress.js';
+export { COMPOSE_CONTRACT_VERSION, compareComposeContract, } from './contract.js';
+export { classifyTemplating, hasComposeTimeTemplating, composeTimeKeys, } from './templating.js';
+/**
+ * Which properties name another component (Phase 2 Story 1.2).
+ *
+ * Lives in `template-model` rather than in the index because reference kinds are domain VOCABULARY,
+ * not index machinery: the validation rules need them as much as the graph does, and a registry
+ * reachable from only one of the two surfaces is how a rule gets wired into the CLI and forgotten in
+ * the editor (FR-54, counter-metric C3). `template-model` is the base package both already depend on.
+ */
+export * from './references.js';
+export * from './connectorSupport.js';
+// Story 4.3 — the emission algebra, beside the address algebra it shares a subject with. Both flow packages render
+// through these, which is how "one renderer set" holds without them importing each other (AD-21).
+export { renderMermaid as renderFlowMermaid, renderMarkdown as renderFlowMarkdown, escapeLabel, } from './flowRender.js';
+export { composeNodeLabel, glyphOfStepType, familyOfStepType, } from './stepGlyph.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,EAAE;AACF,2FAA2F;AAC3F,+FAA+F;AAC/F,+FAA+F;AAC/F,uBAAuB;AACvB,OAAO,EACL,YAAY,EACZ,OAAO,EACP,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,aAAa,EACb,WAAW,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAE1D,iHAAiH;AACjH,mEAAmE;AACnE,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,UAAU,EACV,eAAe,EACf,YAAY,EACZ,WAAW,EACX,cAAc,EACd,eAAe,EACf,cAAc,EACd,oBAAoB,GAErB,MAAM,kBAAkB,CAAC;AAe1B,OAAO,EACL,wBAAwB,EACxB,sBAAsB,GAEvB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,eAAe,GAIhB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;GAOG;AACH,cAAc,iBAAiB,CAAC;AAEhC,cAAc,uBAAuB,CAAC;AAEtC,mHAAmH;AACnH,kGAAkG;AAClG,OAAO,EACL,aAAa,IAAI,iBAAiB,EAClC,cAAc,IAAI,kBAAkB,EACpC,WAAW,GAOZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,gBAAgB,CAAC"}

package/dist/nodeAddress.d.ts

@@ -0,0 +1,105 @@
+/** The separator between address segments. Measured absent from all 2,144+ authored keys. */
+export declare const ADDRESS_SEPARATOR = ":";
+/** What a `:` becomes when rendered into a mermaid id, which admits only `[A-Za-z0-9_]`. */
+export declare const RENDERED_SEPARATOR = "__";
+/**
+ * One step along a path.
+ *
+ * `kind` is what makes the segment self-describing, which is why an address can be read by a human and matched by a
+ * machine without a side map — the thing dashboard's word-boundary regex and the extension's `MermaidFlow.steps`
+ * payload both existed to supply.
+ */
+export type AddressSegment = 
+/** A document key at that level: `pullers`, `pullSteps`, `metrics`, `next`, `if`. */
+{
+    readonly kind: 'key';
+    readonly name: string;
+}
+/** A component carrying an `id` (AD-33 rule 2) → `id_<value>`. */
+ | {
+    readonly kind: 'id';
+    readonly value: string;
+}
+/** A component with no `id` but a `key` (rule 3) → `key_<value>`. */
+ | {
+    readonly kind: 'componentKey';
+    readonly value: string;
+}
+/** A dictionary tail, named by the bare dictionary key (rule 5). */
+ | {
+    readonly kind: 'entry';
+    readonly value: string;
+};
+/** A key segment — `pullers`, `pullSteps`, `next`, `if`. */
+export declare const keySegment: (name: string) => AddressSegment;
+/**
+ * An identity segment, from a component's raw `id` or `key` value.
+ *
+ * ### `id_` carries the AUTHORED value, tokens and all
+ *
+ * Jazz's own example is `pullers:id_**LightspeedXSeriesPullerId**`, not the composed GUID. An address describes the
+ * **source**, and the authored form is identical across environments where a resolved GUID is not. It renders as
+ * `id___LightspeedXSeriesPullerId__`, which is ugly and harmless: nothing parses a rendered id for navigation,
+ * because the node index carries file, location and source text.
+ *
+ * Returns `undefined` for an absent identity, and for a value whose `!` marks it **removed** — a node the composer
+ * deletes has no address in the composed document, and minting one would be a citation to something that is not
+ * there.
+ */
+export declare function identitySegment(raw: unknown, which: 'id' | 'key'): AddressSegment | undefined;
+/** A dictionary tail, e.g. a metric facet's key. */
+export declare function entrySegment(raw: unknown): AddressSegment | undefined;
+/**
+ * The canonical address for a path.
+ *
+ * `undefined` segments are dropped rather than rendered as blanks, so a caller can pass
+ * `identitySegment(step.key, 'key')` without first checking it — a step with no key still gets the address of the
+ * stage that holds it, which is a true statement about a lesser-known node rather than an address with a hole in it.
+ *
+ * A segment whose TEXT is empty is dropped for the same reason, and this is the structural home of that rule (Story
+ * 4.6 review, LOW-1). `identitySegment` already refuses an empty id, but `keySegment('')` is a defined segment holding
+ * no text, so an empty `collection` or an empty base string produced `:creationSteps:key_FORM` — an address whose
+ * separator claims a level that was never there. That was first patched at one call site in `frontend-flow`; the class
+ * belongs here, where every caller gets it. Whitespace counts as empty: a segment of spaces is not a level either.
+ */
+export declare function nodeAddress(segments: readonly (AddressSegment | undefined)[]): string;
+/**
+ * The rendered form for a mermaid node id.
+ *
+ * Two steps, in this order: `:` → `__`, then sanitise anything still outside `[A-Za-z0-9_]`. Sanitising first would
+ * turn a stray character into `_` and make it indistinguishable from a separator.
+ */
+export declare function renderedNodeId(address: string): string;
+/** The segments of a canonical address, as text. */
+export declare function addressSegments(address: string): readonly string[];
+/**
+ * Does `address` name this node, or one inside it?
+ *
+ * **Whole-segment**, which is what makes AD-33's prefix-capture fix structural rather than a rule. The corpus has
+ * **924 pairs** of unique step keys where one prefixes another, and fixture 01 contains one directly:
+ * `SAVE_SALES_RETURN` and `SAVE_SALES_RETURN_DETAILS`, both named in one Scriban expression. As segments they are
+ * simply different, so `includes()`-style capture cannot happen — no word-boundary regex, no side payload map.
+ */
+export declare function addressMatches(address: string, candidate: string): boolean;
+/**
+ * The address, among those a caller already knows, that a rendered mermaid id refers to.
+ *
+ * ### There is deliberately NO reverse function, and the first draft of this module had one
+ *
+ * `addressOfRenderedId` looked reasonable and was unsound. It reversed `__` → `:` and accepted the result if it
+ * re-rendered to the same id — but that check proves round-trip *consistency*, not *uniqueness*, and the projection
+ * is genuinely many-to-one once sanitisation is involved. Its own test caught it: both
+ *
+ * ```
+ * pullers:id_**XPullerId**:pullSteps:key_GET_ORDERS:next:if     ← the real address
+ * pullers:id:_XPullerId::pullSteps:key_GET_ORDERS:next:if       ← a different node entirely
+ * ```
+ *
+ * render to `pullers__id___XPullerId____pullSteps__key_GET_ORDERS__next__if`. So it would have returned the second
+ * for a click on the first: precisely the wrong-node navigation its own docblock claimed to prevent.
+ *
+ * The direction that IS sound is forward-only, and it is all a consumer needs — Story 4.1 AC-4 puts the address on
+ * every node in the index, so a click handler always has the candidates in hand and never has to invert anything.
+ */
+export declare function addressForRenderedId(rendered: string, known: readonly string[]): string | undefined;
+//# sourceMappingURL=nodeAddress.d.ts.map

package/dist/nodeAddress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodeAddress.d.ts","sourceRoot":"","sources":["../src/nodeAddress.ts"],"names":[],"mappings":"AAuCA,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,4FAA4F;AAC5F,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;;;GAMG;AACH,MAAM,MAAM,cAAc;AACxB,qFAAqF;AACnF;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACjD,kEAAkE;GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACjD,qEAAqE;GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAC3D,oEAAoE;GAClE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,4DAA4D;AAC5D,eAAO,MAAM,UAAU,SAAU,MAAM,KAAG,cAGxC,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,IAAI,GAAG,KAAK,GAClB,cAAc,GAAG,SAAS,CAQ5B;AAED,oDAAoD;AACpD,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAMrE;AAiCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,SAAS,CAAC,cAAc,GAAG,SAAS,CAAC,EAAE,GAChD,MAAM,CAMR;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAElE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAY1E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,MAAM,GAAG,SAAS,CAMpB"}