@beehexa/hexasync-template-frontend-flow 2608.20.18 → 2608.20.31

package/dist/render.js

@@ -0,0 +1,73 @@
+/**
+ * `renderMermaid` / `renderMarkdown` for a frontend workflow — Story 4.3, `PACKAGE-CONTRACT.md` §5.
+ *
+ * Thin, for the same reason as its worker twin: the emission rules live in `hexasync-template-model`, which is the one
+ * package both may import (AD-21). This file says what a FRONTEND node looks like — and the differences from the worker
+ * side are real, not incidental.
+ */
+import { renderFlowMermaid, composeNodeLabel, renderFlowMarkdown, } from '@beehexa/hexasync-template-model';
+/**
+ * A node's label.
+ *
+ * ⚠️ A step reads as its **name** where it has one, falling back to its key — the CLI baseline draws
+ * `SHOW_CREATE_PROFILE_ERROR["Couldn't Start Profile Creation"]`, and dropping `name` was Story 4.2's L1 finding. The
+ * worker side has no equivalent: a worker step's identity in that corpus IS its key.
+ */
+function labelOf(node) {
+    // COMPOSED, not a fallback chain (2026-08-20). This was
+    // `node.label ?? node.name ?? node.stepKey ?? node.address`, so a step with a name drew its name and
+    // dropped the key and the type — both already on the node. A reader beside the YAML could not tell which
+    // `key:` a box was, and `next:`/`outputs:` reference steps BY KEY. One composer for both runtimes, in
+    // `template-model`, so the two diagrams cannot start labelling differently.
+    return composeNodeLabel(node);
+}
+function groupOf(one) {
+    return {
+        key: one.address,
+        title: one.title,
+        nodes: one.nodes.map((node) => ({
+            address: node.address,
+            label: labelOf(node),
+            decides: node.decides,
+            // START and END are stadiums, as both baselines draw them; an unresolved target is a plain box there, matching
+            // the reference, which ids it with the same shape as a real step.
+            terminal: node.junction === 'start' || node.junction === 'end',
+        })),
+    };
+}
+/** ONE workflow, which is what a diagram shows — a document with five of them is five diagrams, not one. */
+export function renderMermaid(one, opts = {}) {
+    // A single workflow is a flat chart by default: its own title is the chart's, and a lone subgraph adds a box around
+    // everything for nothing.
+    return renderFlowMermaid([groupOf(one)], one.edges, {
+        multiStage: false,
+        ...opts,
+    });
+}
+/** Markdown for one workflow — `(flow, opts)`, the same shape as the worker twin (review MEDIUM-1). */
+export function renderMarkdown(one, opts = {}) {
+    return renderFlowMarkdown(opts.title ?? one.title, [groupOf(one)], one.edges, {
+        multiStage: false,
+        ...opts,
+    });
+}
+/**
+ * Every workflow a document declares, each its own titled section.
+ *
+ * A connector definition carries up to five, and `epic-4-ground-truth.md` records that no shipped surface draws any of
+ * them — so a document-level entry point is what makes the set usable rather than a per-workflow call a consumer has
+ * to discover.
+ */
+export function renderDocumentMarkdown(flow, opts = {}) {
+    /**
+     * A document with NO workflows says so (review MEDIUM-3).
+     *
+     * It returned `''`, so a caller could not tell "this connector declares no workflows" from "the renderer returned
+     * nothing" — the same failure the empty-diagram placeholder exists to prevent, one level up.
+     */
+    if (flow.workflows.length === 0) {
+        return `### ${opts.title ?? 'Workflows'}\n\nThis document declares no frontend workflows.\n`;
+    }
+    return flow.workflows.map((one) => renderMarkdown(one, opts)).join('\n');
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GAGnB,MAAM,kCAAkC,CAAC;AAG1C;;;;;;GAMG;AACH,SAAS,OAAO,CAAC,IAA2C;IAC1D,wDAAwD;IACxD,qGAAqG;IACrG,yGAAyG;IACzG,sGAAsG;IACtG,4EAA4E;IAC5E,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,OAAO,CAAC,GAAyB;IACxC,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,OAAO;QAChB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC;YACpB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,+GAA+G;YAC/G,kEAAkE;YAClE,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,IAAI,CAAC,QAAQ,KAAK,KAAK;SAC/D,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,4GAA4G;AAC5G,MAAM,UAAU,aAAa,CAC3B,GAAyB,EACzB,IAAI,GAAkB,EAAE;IAExB,oHAAoH;IACpH,0BAA0B;IAC1B,OAAO,iBAAiB,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,EAAE;QAClD,UAAU,EAAE,KAAK;QACjB,GAAG,IAAI;KACR,CAAC,CAAC;AACL,CAAC;AAED,uGAAuG;AACvG,MAAM,UAAU,cAAc,CAC5B,GAAyB,EACzB,IAAI,GAAgD,EAAE;IAEtD,OAAO,kBAAkB,CACvB,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC,KAAK,EACvB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,EACd,GAAG,CAAC,KAAK,EACT;QACE,UAAU,EAAE,KAAK;QACjB,GAAG,IAAI;KACR,CACF,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,IAAkB,EAClB,IAAI,GAAgD,EAAE;IAEtD;;;;;OAKG;IACH,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,OAAO,OAAO,IAAI,CAAC,KAAK,IAAI,WAAW,qDAAqD,CAAC;IAC/F,CAAC;IACD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC3E,CAAC"}

package/dist/routes.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Where a frontend step goes next — Story 4.2 AC-2 and AC-3.
+ *
+ * Ported from `dashboard-v2/src/pages/__dev/lib/connectorWorkflowMermaid.ts`, which is a complete and working
+ * implementation; the port's job is to keep its semantics and drop its positional ids.
+ *
+ * ### AC-2: both spellings — on a `next` OBJECT only, which is where the reference aliases
+ *
+ * ⛔ **CORRECTED by the Story 4.2 review.** The first version applied the alias to an `IF` step's `metadata` as well,
+ * and that was an **invention**: dashboard reads `step.metadata.then` / `.else` *literally* (`addStepEdges`), and its
+ * `branchValue` is used only inside `addNextCondition` — i.e. only for a nested branch object under `next`. The CLI
+ * aliases the same single place. So `{ type: 'IF', metadata: { success: 'A', failed: 'B' } }` drew YES/NO edges here
+ * and **nothing at all** in either reference.
+ *
+ * That is precisely the failure the package split exists to prevent, committed by the package that exists to prevent
+ * it: accepting a document shape the runtime rejects. Measured: `success`/`failed` occur in **8 real `next` objects
+ * and 0 real `metadata` blocks**, so the alias was tested only on the surface where it does not belong, while the one
+ * place it genuinely applies had no test.
+ *
+ * Where it DOES apply, `hasOwnProperty` before falling back is load-bearing: `then: null` is a
+ * **declared-but-empty** arm (the frontend's way of saying "this branch ends") and is distinct from an absent `then`
+ * that should defer to `success`. Truthiness collapses the two and silently takes the wrong arm — which is what
+ * AC-2's *"does not silently lose half its edges"* is about.
+ *
+ * ### AC-3: `onCancelled` is not a route out of the happy path
+ *
+ * It is the cancel route for a pause-for-input step (`FORM`, `*_CHOICE_FORM`) and is emitted for ANY step that
+ * declares one, alongside whatever `next` says — the reference's comment records why: otherwise the cancel branch and
+ * its downstream navigation steps *"aren't left orphaned in the diagram"*.
+ *
+ * ### Expressions are NOT resolved — and the reason first given for that was false
+ *
+ * ⚠️ The original note claimed *"the frontend runtime has no such form"*. It has: **23 real `next` values** are Liquid
+ * templates, across `installStandaloneCallbackSteps` in LightspeedXSeries, SapoOmniV3PublicApp, ShopifyPublicApp,
+ * ShoplinePublicApp, TikTokShopGatewayV3 and Zalo — e.g.
+ * `{% assign codeSize = ... %}{% if codeSize > 0 %}CHECK_PROFILE_STATUS{% else %}GET_SETUP_INSTRUCTIONS{% endif %}`.
+ *
+ * Both the reference and this model render each as ONE unresolved node labelled with the whole template, so ~23
+ * genuinely reachable routes are undrawn on both sides. That is faithful, and it is a real gap.
+ *
+ * It is not closed here because the worker machinery does not transfer: the worker resolves `"QUOTED"` keys in a
+ * Scriban expression, whereas these name steps **bare** inside Liquid tags. Resolving them needs its own reader and
+ * its own decision about what to draw when a branch is undecidable statically. Deferred, with the premise corrected
+ * so nobody re-derives the false one.
+ */
+/** A frontend step as routing needs to see it. */
+export interface FrontendStep {
+    readonly key: string;
+    /** A step key, a `{ then|success, else|failed }` branch, or `null`/absent for the end of the workflow. */
+    readonly next?: unknown;
+    /** `IF`, `SWITCH`, `FORM`, … Compared case-insensitively. */
+    readonly type?: string;
+    /** Where an `IF`/`SWITCH` declares its branches — `metadata`, not `data`. */
+    readonly metadata?: unknown;
+    /** The cancel route. */
+    readonly onCancelled?: unknown;
+    /**
+     * ⛔ `errorHandlers` is NOT here, and that absence is a decision — see the note below on dead properties.
+     *
+     * 3 real steps declare one (Zalo, TikTokShopGatewayV3, LightspeedXSeries) and NO implementation reads it:
+     * not the dashboard engine, not `core.api`, not the CLI, not the shipped schemas. Drawing its arms would
+     * invent routes the runtime never takes, which is what NFR-1 forbids and what this module's own note
+     * records having got wrong once before.
+     */
+    /**
+     * An ENTRY point. `true` or the STRING `'true'` — the reference's `isTruthyFlag` accepts both, and 3 real
+     * declarations use the string form.
+     */
+    readonly root?: unknown;
+}
+/** What a synthesised node is. */
+export type JunctionKind = 'if' | 'unknown' | 'end' | 'start'
+/**
+ * A `next:` that is a TEMPLATE rather than a step key — drawn as a diamond (2026-08-20).
+ *
+ * Its own kind rather than reusing `'if'`, because the two are different facts about the document: an `'if'`
+ * junction comes from an authored `then`/`else` branch, and this comes from a template whose branches the
+ * reader can see but a static view cannot resolve. Both DECIDE, so both draw as a diamond — see
+ * `flow.ts`'s `decides`. The kind is what lets a consumer tell them apart without parsing the label.
+ */
+ | 'expression';
+/** A node the document does not declare. `path` is relative to the owning step. */
+export interface Junction {
+    readonly path: readonly string[];
+    readonly kind: JunctionKind;
+    readonly label: string;
+    readonly owner: string;
+}
+export type EdgeEnd = {
+    readonly kind: 'step';
+    readonly key: string;
+} | {
+    readonly kind: 'junction';
+    readonly owner: string;
+    readonly path: readonly string[];
+};
+export interface GraphEdge {
+    readonly from: EdgeEnd;
+    readonly to: EdgeEnd;
+    readonly label?: string;
+}
+export interface FrontendRouteGraph {
+    readonly junctions: readonly Junction[];
+    readonly edges: readonly GraphEdge[];
+}
+/**
+ * A branch arm, by either spelling.
+ *
+ * `hasOwnProperty` on the primary before falling back — see the module note. Returns a sentinel-free result: the
+ * caller cannot distinguish "absent" from "declared null" from the value alone, so both are returned as-is and the
+ * caller treats `null` as an end.
+ */
+export declare function branchArm(branch: Record<string, unknown>, primary: 'then' | 'else', alternate: 'success' | 'failed'): unknown;
+export declare function frontendRouteGraph(steps: readonly FrontendStep[], 
+/** Drawn inside the START terminal. The workflow's title, where the caller has one. */
+startLabel?: string): FrontendRouteGraph;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,0GAA0G;IAC1G,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,wBAAwB;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,kCAAkC;AAClC,MAAM,MAAM,YAAY,GACpB,IAAI,GACJ,SAAS,GACT,KAAK,GACL,OAAO;AACT;;;;;;;GAOG;GACD,YAAY,CAAC;AAEjB,mFAAmF;AACnF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,CAAC;AAEN,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAuCD;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,SAAS,EAAE,SAAS,GAAG,QAAQ,GAC9B,OAAO,CAIT;AAYD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,YAAY,EAAE;AAC9B,uFAAuF;AACvF,UAAU,SAAU,GACnB,kBAAkB,CAkSpB"}

package/dist/routes.js

@@ -0,0 +1,355 @@
+/**
+ * Where a frontend step goes next — Story 4.2 AC-2 and AC-3.
+ *
+ * Ported from `dashboard-v2/src/pages/__dev/lib/connectorWorkflowMermaid.ts`, which is a complete and working
+ * implementation; the port's job is to keep its semantics and drop its positional ids.
+ *
+ * ### AC-2: both spellings — on a `next` OBJECT only, which is where the reference aliases
+ *
+ * ⛔ **CORRECTED by the Story 4.2 review.** The first version applied the alias to an `IF` step's `metadata` as well,
+ * and that was an **invention**: dashboard reads `step.metadata.then` / `.else` *literally* (`addStepEdges`), and its
+ * `branchValue` is used only inside `addNextCondition` — i.e. only for a nested branch object under `next`. The CLI
+ * aliases the same single place. So `{ type: 'IF', metadata: { success: 'A', failed: 'B' } }` drew YES/NO edges here
+ * and **nothing at all** in either reference.
+ *
+ * That is precisely the failure the package split exists to prevent, committed by the package that exists to prevent
+ * it: accepting a document shape the runtime rejects. Measured: `success`/`failed` occur in **8 real `next` objects
+ * and 0 real `metadata` blocks**, so the alias was tested only on the surface where it does not belong, while the one
+ * place it genuinely applies had no test.
+ *
+ * Where it DOES apply, `hasOwnProperty` before falling back is load-bearing: `then: null` is a
+ * **declared-but-empty** arm (the frontend's way of saying "this branch ends") and is distinct from an absent `then`
+ * that should defer to `success`. Truthiness collapses the two and silently takes the wrong arm — which is what
+ * AC-2's *"does not silently lose half its edges"* is about.
+ *
+ * ### AC-3: `onCancelled` is not a route out of the happy path
+ *
+ * It is the cancel route for a pause-for-input step (`FORM`, `*_CHOICE_FORM`) and is emitted for ANY step that
+ * declares one, alongside whatever `next` says — the reference's comment records why: otherwise the cancel branch and
+ * its downstream navigation steps *"aren't left orphaned in the diagram"*.
+ *
+ * ### Expressions are NOT resolved — and the reason first given for that was false
+ *
+ * ⚠️ The original note claimed *"the frontend runtime has no such form"*. It has: **23 real `next` values** are Liquid
+ * templates, across `installStandaloneCallbackSteps` in LightspeedXSeries, SapoOmniV3PublicApp, ShopifyPublicApp,
+ * ShoplinePublicApp, TikTokShopGatewayV3 and Zalo — e.g.
+ * `{% assign codeSize = ... %}{% if codeSize > 0 %}CHECK_PROFILE_STATUS{% else %}GET_SETUP_INSTRUCTIONS{% endif %}`.
+ *
+ * Both the reference and this model render each as ONE unresolved node labelled with the whole template, so ~23
+ * genuinely reachable routes are undrawn on both sides. That is faithful, and it is a real gap.
+ *
+ * It is not closed here because the worker machinery does not transfer: the worker resolves `"QUOTED"` keys in a
+ * Scriban expression, whereas these name steps **bare** inside Liquid tags. Resolving them needs its own reader and
+ * its own decision about what to draw when a branch is undecidable statically. Deferred, with the premise corrected
+ * so nobody re-derives the false one.
+ */
+import { looksLikeTemplate, templateTargets } from './liquid.js';
+const stepEnd = (key) => ({ kind: 'step', key });
+/**
+ * A short, stable digest of an unresolved target — used as its ADDRESS segment instead of the target text.
+ *
+ * ⛔ Story 4.4 review. The segment used to be the raw target, and `renderedNodeId` sanitises everything outside
+ * `[A-Za-z0-9_]` to `_` — so two Liquid templates differing only in punctuation collapsed onto one mermaid id.
+ * Reproduced: `{% if x == 1 %}TARGET{% endif %}` and `{% if x != 1 %}TARGET{% endif %}` produce ONE node, which takes
+ * the second label and inherits both incoming edges as a false join, while `addressForRenderedId` then declines so the
+ * click resolves to nothing. It also produced 221-character ids carrying whole templates.
+ *
+ * A digest, not a counter: it is derived from the CONTENT, so it is stable under any insertion or reorder — which is
+ * what AD-33 actually requires — and two routes naming the same target still converge on one node, which is the
+ * behaviour the references have. The reader loses nothing: the junction's LABEL still carries the target verbatim.
+ *
+ * FNV-1a, because `node:crypto` is a host module this core package may not touch (AD-3).
+ */
+function targetDigest(target) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < target.length; index += 1) {
+        hash ^= target.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(16).padStart(8, '0');
+}
+/**
+ * The owner of a junction that belongs to the WORKFLOW rather than to one step — an unresolved target, which every
+ * route naming it shares. Not a valid step key, so it cannot collide with one.
+ */
+const WORKFLOW_OWNED = '';
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/**
+ * A branch arm, by either spelling.
+ *
+ * `hasOwnProperty` on the primary before falling back — see the module note. Returns a sentinel-free result: the
+ * caller cannot distinguish "absent" from "declared null" from the value alone, so both are returned as-is and the
+ * caller treats `null` as an end.
+ */
+export function branchArm(branch, primary, alternate) {
+    return Object.prototype.hasOwnProperty.call(branch, primary)
+        ? branch[primary]
+        : branch[alternate];
+}
+/**
+ * Every junction and edge for ONE workflow's steps.
+ *
+ * Iterative, never recursive — a branch arm can itself be a branch, without bound, and a document is untrusted input.
+ */
+/** `true` or the string `'true'` — the reference's `isTruthyFlag`, which 3 real declarations depend on. */
+function isTruthyFlag(value) {
+    return value === true || String(value).trim().toLowerCase() === 'true';
+}
+export function frontendRouteGraph(steps, 
+/** Drawn inside the START terminal. The workflow's title, where the caller has one. */
+startLabel = 'START') {
+    const known = new Set(steps.map((s) => String(s.key)));
+    const junctions = [];
+    const edges = [];
+    const seen = new Set();
+    const junction = (owner, path, kind, label) => {
+        /**
+         * `JSON.stringify`, not a space join (Story 4.2 review, MEDIUM-1).
+         *
+         * A SWITCH case label may contain spaces, and `['metadata','cases','q','if','then','unknown']` and
+         * `['metadata','cases','q if then','unknown']` joined to the SAME string — so one junction was never created and
+         * an edge resolved to the other one. The `q` diamond's YES arm pointed at the wrong box. 0 corpus labels contain a
+         * space, which is why this is a structural guard rather than a live fix.
+         */
+        const id = JSON.stringify([owner, ...path]);
+        if (!seen.has(id)) {
+            seen.add(id);
+            junctions.push({ owner, path, kind, label });
+        }
+        return { kind: 'junction', owner, path };
+    };
+    /**
+     * The ENTRY points, and an arrow into each — Story 4.2 review, HIGH-1 / H4.
+     *
+     * ⛔ The first version dropped `root` entirely: no field, no node, no edge. Measured: **84** `root: true` in the
+     * corpus, **3** of them written as the STRING `'true'`, and **two workflows declare TWO roots** —
+     * `GoogleSheets.yaml` and `Hubspot.yaml` `authorizationCallbackSteps` each mark a second, genuine direct-entry step
+     * for the OAuth callback.
+     *
+     * Not deferrable to the renderer: with no `root` bit in the model a renderer can only guess "the first step", which
+     * is wrong for those two and for the four workflows whose root is not first. The fact is unrecoverable downstream.
+     *
+     * Fallback to the first step, as the reference does — a workflow with no `root` still has an entry.
+     */
+    const roots = steps.filter((step) => isTruthyFlag(step.root));
+    const entries = roots.length > 0 ? roots : steps.slice(0, 1);
+    if (entries.length > 0) {
+        const start = junction(WORKFLOW_OWNED, ['start'], 'start', startLabel);
+        for (const entry of entries) {
+            edges.push({ from: start, to: stepEnd(String(entry.key)) });
+        }
+    }
+    for (const raw of steps) {
+        const owner = String(raw.key);
+        const type = String(raw.type ?? '').toUpperCase();
+        const metadata = isRecord(raw.metadata) ? raw.metadata : undefined;
+        /**
+         * Branch objects already entered on THIS step's walk — the cycle guard.
+         *
+         * ⛔ Without it a cyclic branch does not loop, it **kills the process**: exit 134, `FATAL ERROR: heap out of
+         * memory`, in seconds. The path grows two segments per iteration and the junction id is keyed by that path, so it
+         * never repeats and both lists grow without bound. Reachable from YAML with the parser the CLI already uses:
+         *
+         * ```yaml
+         * next: &loop
+         *   if: "x"
+         *   then: *loop
+         * ```
+         *
+         * The module note argued *"iterative, never recursive — a document is untrusted input"*, which was right and
+         * removed the only bound that existed: the reference recurses and throws a **catchable** `RangeError`. An
+         * uncatchable V8 fatal is strictly worse, and this package is bundled into the VS Code extension host.
+         *
+         * Identity, not depth: the same object reached twice is the cycle, however long the path. The sibling worker
+         * package had the identical defect and is fixed the same way.
+         */
+        const entered = new WeakSet();
+        /** Work list: where the arrow leaves, the route value, the path that reaches it, the label. */
+        const pending = [];
+        // ── AC-3: the cancel route, independent of the happy path and emitted first so it reads as a side exit ──
+        if (typeof raw.onCancelled === 'string' && raw.onCancelled.trim() !== '') {
+            pending.push({
+                from: stepEnd(owner),
+                value: raw.onCancelled.trim(),
+                path: ['onCancelled'],
+                label: 'Cancel',
+            });
+        }
+        if (type === 'IF' && metadata) {
+            /**
+             * `metadata.then` / `.else`, read LITERALLY — no alias. See the module note: aliasing here was an invention that
+             * accepted a shape both references reject. `metadata`, not `data`, is the frontend vocabulary; the alias is a
+             * property of a `next` OBJECT, and only there.
+             */
+            pending.push({
+                from: stepEnd(owner),
+                value: metadata.then,
+                path: ['metadata', 'then'],
+                label: 'YES',
+            });
+            pending.push({
+                from: stepEnd(owner),
+                value: metadata.else,
+                path: ['metadata', 'else'],
+                label: 'NO',
+            });
+        }
+        else if (type === 'SWITCH' && metadata) {
+            /**
+             * A frontend SWITCH reads `metadata.cases` — a RECORD of label → target — plus an optional `metadata.default`.
+             * The worker's SWITCH branches on its `data` KEYS instead. Two runtimes, two shapes.
+             */
+            if (isRecord(metadata.cases)) {
+                for (const [label, target] of Object.entries(metadata.cases)) {
+                    pending.push({
+                        from: stepEnd(owner),
+                        value: target,
+                        path: ['metadata', 'cases', label],
+                        label,
+                    });
+                }
+            }
+            if (typeof metadata.default === 'string') {
+                pending.push({
+                    from: stepEnd(owner),
+                    value: metadata.default,
+                    path: ['metadata', 'default'],
+                    label: 'default',
+                });
+            }
+        }
+        else if (typeof raw.next === 'string' || isRecord(raw.next)) {
+            pending.push({ from: stepEnd(owner), value: raw.next, path: ['next'] });
+        }
+        else {
+            /**
+             * No usable `next` ⇒ the workflow ENDS here, drawn as a terminal.
+             *
+             * The worker model has no equivalent: a worker step with no `next` simply has no outgoing edge. The frontend
+             * reference draws `END` explicitly, and it is worth keeping — an onboarding workflow that stops is a fact the
+             * reader wants stated, not inferred from an absence of arrows.
+             */
+            const end = junction(owner, ['next', 'end'], 'end', 'END');
+            edges.push({ from: stepEnd(owner), to: end });
+        }
+        while (pending.length > 0) {
+            const { from, value, path, label } = pending.shift();
+            const labelled = label !== undefined ? { label } : {};
+            if (typeof value === 'string' && value.trim() !== '') {
+                const target = value.trim();
+                if (known.has(target)) {
+                    edges.push({ from, to: stepEnd(target), ...labelled });
+                    continue;
+                }
+                /**
+                 * A TEMPLATE names its targets, so it is a DIAMOND with one arrow per target (2026-08-20).
+                 *
+                 * Reported: *"this is actually kind of liquid syntax which has `{% … %}` inside it, this must works
+                 * similar to how scriban syntax works. and the `next` MUST ALWAYS be a diamond if it is not a step
+                 * key … currently the node is not connected to the next which is not correct."*
+                 *
+                 * Right on both counts, and the gap was already written down in this module's own note — 20 real
+                 * `next` templates across six connectors drew as one unresolved BOX with no outgoing edges, so every
+                 * route they name was undrawn. `liquid.ts` reads the targets; this draws them.
+                 *
+                 * Owned by the STEP, not the workflow, and NOT converged by target text — unlike the ghost below. A
+                 * decision belongs to the step that makes it, so two steps carrying the same template get a diamond
+                 * each. That is the worker's shape for the same situation (`routeGraph.ts`, the `expression` branch)
+                 * and the reason this is `[...path, 'expression']` there too.
+                 *
+                 * The arrows are UNLABELLED, exactly as the worker draws them: which branch it takes is a run-time
+                 * fact, and labelling one `YES` would assert an order the template does not promise.
+                 *
+                 * A template that resolves NOTHING still draws its diamond. It is a decision either way, and a
+                 * diamond with no exits says "the flow branches here and I cannot tell where it goes" — which is
+                 * true, and is what the reader asked for over a box that says nothing at all.
+                 */
+                if (looksLikeTemplate(target)) {
+                    const point = junction(owner, [...path, 'expression'], 'expression', target);
+                    edges.push({ from, to: point, ...labelled });
+                    for (const reachable of templateTargets(target)) {
+                        if (known.has(reachable))
+                            edges.push({ from: point, to: stepEnd(reachable) });
+                    }
+                    continue;
+                }
+                /**
+                 * An unresolved target is a NODE, and routes naming the SAME target CONVERGE on it.
+                 *
+                 * ⚠️ The first version gave each route its own node, so two steps routing to `GONE` drew two boxes labelled
+                 * `GONE` where both references draw one with two incoming arrows (the reference ids the ghost by target, not
+                 * by route). Convergence restored — but keyed on the target TEXT rather than the reference's
+                 * `mermaidId(target)`, which also fixes a reference bug: two different Liquid expressions differing only in
+                 * punctuation collapse onto one node there, and a ghost target `A-B` hijacks a real step keyed `A_B`.
+                 *
+                 * Owned by the WORKFLOW rather than a step, since that is what "the same target" means.
+                 */
+                edges.push({
+                    from,
+                    // Digest, not the raw target — see `targetDigest`. Convergence is preserved: one target, one node.
+                    to: junction(WORKFLOW_OWNED, ['unknown', targetDigest(target)], 'unknown', target),
+                    ...labelled,
+                });
+                continue;
+            }
+            if (isRecord(value)) {
+                if (entered.has(value)) {
+                    const point = junction(owner, [...path, 'cycle'], 'unknown', 'cycle: this branch refers to itself');
+                    edges.push({ from, to: point, ...labelled });
+                    continue;
+                }
+                entered.add(value);
+                /**
+                 * A nested condition, labelled with its CONDITION where the document gives one.
+                 *
+                 * ⚠️ The first version labelled every one of these the literal `"IF"`, on the stated grounds that *"the
+                 * frontend branch object carries no `if` field to draw"*. False: **all 61** real `next` branch objects in the
+                 * corpus carry an `if:` holding the Liquid condition. The reference does label them `"IF"`, so this is an
+                 * *"accept the change"* against the baseline rather than a bug fix — and the change is worth making, because
+                 * the worker twin already carries its condition text and a diagram that says `IF` three times tells a reader
+                 * nothing about which branch is which.
+                 */
+                const condition = value.if;
+                const label = typeof condition === 'string' && condition.trim() !== ''
+                    ? condition.trim()
+                    : 'IF';
+                const point = junction(owner, [...path, 'if'], 'if', label);
+                edges.push({ from, to: point, ...labelled });
+                pending.push({
+                    from: point,
+                    value: branchArm(value, 'then', 'success'),
+                    path: [...path, 'if', 'then'],
+                    label: 'YES',
+                });
+                pending.push({
+                    from: point,
+                    value: branchArm(value, 'else', 'failed'),
+                    path: [...path, 'if', 'else'],
+                    label: 'NO',
+                });
+                continue;
+            }
+            if (value === null) {
+                /**
+                 * A DECLARED end — `then: null` says this arm stops.
+                 *
+                 * ONE end per owning step, not one per arm (review M3): `{ then: null, else: null }` drew two, where the
+                 * reference collapses them to a single unlabelled terminal. The label is dropped for the same reason — a
+                 * terminal reached by both arms cannot honestly carry either arm's label.
+                 */
+                const end = junction(owner, ['next', 'end'], 'end', 'END');
+                edges.push({ from, to: end });
+                continue;
+            }
+            /**
+             * Anything else — `undefined`, a number, an array — yields nothing, matching the reference exactly.
+             *
+             * ⚠️ Recorded rather than improved: an arm the document wrote as `then: 42` disappears silently here. Changing
+             * it would change the shipped diagram, which is Story 4.4's golden-suite decision to make deliberately, not a
+             * port's to make in passing.
+             */
+        }
+    }
+    return { junctions, edges };
+}
+//# sourceMappingURL=routes.js.map

package/dist/routes.js.map

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

package/dist/workflows.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The frontend workflows, and their titles — Story 4.2 AC-1.
+ *
+ * ### A separate package, deliberately (AD-21)
+ *
+ * A frontend step is never resolved with the worker vocabulary, and this is where that becomes structural rather than
+ * a convention. The two runtimes genuinely differ, in four ways measured off the reference implementation
+ * (`dashboard-v2/src/pages/__dev/lib/connectorWorkflowMermaid.ts`):
+ *
+ * | | worker | frontend |
+ * | --- | --- | --- |
+ * | branch arms | `then` / `else` | `then` **or** `success` / `else` **or** `failed` |
+ * | `IF` reads | `data` | `metadata` |
+ * | `SWITCH` reads | `data`'s KEYS | `metadata.cases` (a record) + `metadata.default` |
+ * | extra route | `onError` | `onCancelled`, labelled `Cancel` |
+ *
+ * Two more the worker side has no equivalent for: an explicit **`END`** terminal when a step declares no `next`, and
+ * no expression handling at all — a frontend `next` is a key, a branch object, or nothing.
+ *
+ * ⛔ **So the two packages must NOT share a branch reader.** The temptation to unify them is the thing to resist:
+ * teaching the worker model about `success`/`failed` would make it accept documents the worker runtime rejects, which
+ * is exactly the invention NFR-1 forbids.
+ */
+/** The five workflows a CONNECTOR DEFINITION may declare, in the order the reference implementation lists them. */
+export declare const CONNECTOR_WORKFLOW_KEYS: readonly ['appRegistrationSteps', 'authorizationSteps', 'authorizationCallbackSteps', 'installStandaloneCallbackSteps', 'setupSteps'];
+/** The one a TEMPLATE declares. Separate because it lives on a different document. */
+export declare const TEMPLATE_WORKFLOW_KEYS: readonly ['creationSteps'];
+export type ConnectorWorkflowKey = (typeof CONNECTOR_WORKFLOW_KEYS)[number];
+export type TemplateWorkflowKey = (typeof TEMPLATE_WORKFLOW_KEYS)[number];
+export type FrontendWorkflowKey = ConnectorWorkflowKey | TemplateWorkflowKey;
+export declare const FRONTEND_WORKFLOW_KEYS: readonly FrontendWorkflowKey[];
+/**
+ * A human title per workflow — AC-1's *"drawn with its own title"*.
+ *
+ * ⚠️ **PRESERVED from the recorded baseline** (Story 4.2 review, M2). The first version renamed five of the six —
+ * `App Registration` → `App registration`, `Profile Setup` → `Setup`, `Profile Creation` → `Creation` and so on — on
+ * the reasoning that the word *Steps* is noise and sentence case reads better. Two things were wrong with that: the
+ * baseline README records these titles as rendered output, so changing them needs an adopt/preserve/accept verdict per
+ * `golden-flows/README.md`, and nothing was asserting them — **setting all six to the same string left all 27 tests
+ * green**, because only `authorizationSteps` (the one title that happened not to change) was compared exactly.
+ *
+ * PRESERVE is the verdict: these are the titles two shipped surfaces already draw, and the case argument is a
+ * preference, not a defect. Each is now asserted exactly.
+ */
+export declare const FRONTEND_WORKFLOW_TITLES: Readonly<Record<FrontendWorkflowKey, string>>;
+/** Where a workflow may be declared. Reported on every node so a consumer can tell the two documents apart. */
+export type FrontendSurface = 'connector' | 'template';
+export declare function surfaceOf(key: FrontendWorkflowKey): FrontendSurface;
+/**
+ * The workflows a document actually declares, in the order above.
+ *
+ * Non-empty, for the same reason the worker package requires it: a declared-but-empty workflow is a fact about the
+ * document, not a diagram a reader can be sent to. (The worker side shipped the looser rule and the review measured
+ * 4,519 corpus occurrences of an arrow into nothing.)
+ */
+export declare function workflowsPresent(document: Record<string, unknown>, 
+/**
+ * How many of an array's items are actually DRAWABLE. Injected so this module stays free of step semantics while
+ * still measuring the right thing.
+ */
+drawableCount?: (items: readonly unknown[]) => number): readonly FrontendWorkflowKey[];
+//# sourceMappingURL=workflows.d.ts.map

package/dist/workflows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,mHAAmH;AACnH,eAAO,MAAM,uBAAuB,YAClC,sBAAsB,EACtB,oBAAoB,EACpB,4BAA4B,EAC5B,gCAAgC,EAChC,YAAY,CACJ,CAAC;AAEX,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,YAAI,eAAe,CAAU,CAAC;AAEjE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC5E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,GAAG,mBAAmB,CAAC;AAE7E,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EAGhE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAC7C,MAAM,CAAC,mBAAmB,EAAE,MAAM,CAAC,CAQpC,CAAC;AAEF,+GAA+G;AAC/G,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,UAAU,CAAC;AAEvD,wBAAgB,SAAS,CAAC,GAAG,EAAE,mBAAmB,GAAG,eAAe,CAInE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;AACjC;;;GAGG;AACH,aAAa,GAAE,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,KAAK,MAChC,GACb,SAAS,mBAAmB,EAAE,CAKhC"}