@oscharko-dev/keiko-quality-intelligence 0.2.0

package/dist/domain/figma/irTypes.d.ts.map

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

package/dist/domain/figma/irTypes.js

@@ -0,0 +1,8 @@
+// Screen-IR, design-token, and inter-screen-link types (Epic #750, Issue #752).
+//
+// The IR is the lean structural ground truth a scoped Figma board reduces to: per-screen kept-node
+// trees plus deduped design tokens and the raw inter-screen transitions. These types are the
+// import surface for downstream stages — #753 (snapshot evidence), #754 (QI source), #811 (nav
+// graph, from `links`), #812 (a11y), #755 (codegen, from `tokens`). All emitted collections are
+// stable-ordered; the structure carries no timestamps so the same input yields a byte-identical IR.
+export {};

package/dist/domain/figma/links.d.ts

@@ -0,0 +1,6 @@
+import { type FigmaSourceNode } from "./sourceNode.js";
+import type { InterScreenLink } from "./irTypes.js";
+import type { PrunedNode } from "./prune.js";
+/** Extract stable-ordered, deduped raw inter-screen links from the pruned tree + raw flow entries. */
+export declare const extractInterScreenLinks: (rawRoot: FigmaSourceNode, screens: readonly PrunedNode[]) => readonly InterScreenLink[];
+//# sourceMappingURL=links.d.ts.map

package/dist/domain/figma/links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/links.ts"],"names":[],"mappings":"AAcA,OAAO,EAAyC,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAC9F,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAqF7C,sGAAsG;AACtG,eAAO,MAAM,uBAAuB,GAClC,SAAS,eAAe,EACxB,SAAS,SAAS,UAAU,EAAE,KAC7B,SAAS,eAAe,EAS1B,CAAC"}

package/dist/domain/figma/links.js

@@ -0,0 +1,102 @@
+// Raw inter-screen link extraction (Epic #750, Issue #752).
+//
+// Captures the raw prototype transitions; the navigation/flow graph itself is derived downstream
+// (#811). Three structural sources, read generically:
+//   1. `interactions[].actions[]` — the CURRENT Figma prototype field. Each action with a
+//      destination node id yields `{ sourceNodeId, trigger, targetNodeId }`; trigger comes from the
+//      interaction's `trigger.type`.
+//   2. `reactions[].action` — the LEGACY field, tolerated for older payloads, same projection.
+//   3. CANVAS `flowStartingPoints[]` + `prototypeStartNodeID` — flow entry points, emitted as
+//      `{ sourceNodeId: <canvasId>, trigger: "FLOW_START", targetNodeId }`.
+//
+// Links come from the pruned tree (hidden/dropped nodes emit nothing) plus the raw root for flow
+// entry points. The output is sorted by a stable structural key so order never depends on traversal.
+import { asNode, nodeId, readArray, readString } from "./sourceNode.js";
+const FLOW_START = "FLOW_START";
+const UNKNOWN_TRIGGER = "UNKNOWN";
+// Shared constant — see prune.ts for rationale. Must stay in sync with every other recursive walk.
+const MAX_TREE_DEPTH = 512;
+const EXTERNAL_LINK_TARGET = /^(?:[a-z][a-z0-9+.-]*:\/\/|mailto:|tel:|data:|javascript:)/iu;
+const isExternalLinkTarget = (targetNodeId) => targetNodeId.startsWith("url:") || EXTERNAL_LINK_TARGET.test(targetNodeId);
+const readDestination = (action) => {
+    const direct = readString(action.destinationId);
+    if (direct !== undefined)
+        return isExternalLinkTarget(direct) ? undefined : direct;
+    const nav = asNode(action.navigation);
+    if (nav !== undefined) {
+        const nested = readString(nav.destinationId);
+        return nested !== undefined && !isExternalLinkTarget(nested) ? nested : undefined;
+    }
+    return undefined;
+};
+const triggerType = (entry) => {
+    const trigger = asNode(entry.trigger);
+    return (trigger !== undefined ? readString(trigger.type) : undefined) ?? UNKNOWN_TRIGGER;
+};
+const collectFromActions = (sourceNodeId, trigger, actions, out) => {
+    for (const action of actions) {
+        const record = asNode(action);
+        if (record === undefined)
+            continue;
+        const targetNodeId = readDestination(record);
+        if (targetNodeId !== undefined)
+            out.push({ sourceNodeId, trigger, targetNodeId });
+    }
+};
+const collectInteractions = (node, out) => {
+    const sourceNodeId = nodeId(node);
+    for (const entry of readArray(node.interactions)) {
+        const record = asNode(entry);
+        if (record === undefined)
+            continue;
+        collectFromActions(sourceNodeId, triggerType(record), readArray(record.actions), out);
+    }
+    for (const entry of readArray(node.reactions)) {
+        const record = asNode(entry);
+        if (record === undefined)
+            continue;
+        const action = asNode(record.action);
+        if (action === undefined)
+            continue;
+        collectFromActions(sourceNodeId, triggerType(record), [action], out);
+    }
+};
+function visitAt(pruned, out, depth) {
+    if (depth > MAX_TREE_DEPTH)
+        return;
+    collectInteractions(pruned.source, out);
+    for (const child of pruned.children)
+        visitAt(child, out, depth + 1);
+}
+const visit = (pruned, out) => {
+    visitAt(pruned, out, 0);
+};
+const collectFlowEntries = (root, out) => {
+    const sourceNodeId = nodeId(root);
+    for (const point of readArray(root.flowStartingPoints)) {
+        const record = asNode(point);
+        const target = record !== undefined ? readString(record.nodeId) : undefined;
+        if (target !== undefined)
+            out.push({ sourceNodeId, trigger: FLOW_START, targetNodeId: target });
+    }
+    const start = readString(root.prototypeStartNodeID);
+    if (start !== undefined)
+        out.push({ sourceNodeId, trigger: FLOW_START, targetNodeId: start });
+};
+// Injective dedup/sort key: JSON.stringify of the field tuple escapes every character (NUL,
+// backslash, quote, ...), so two distinct links can never collide into one key, which would
+// silently drop a transition feeding the downstream navigation graph (#811). Deterministic and
+// stable-ordered, preserving the byte-identical IR contract for every input.
+const linkKey = (link) => JSON.stringify([link.sourceNodeId, link.trigger, link.targetNodeId]);
+/** Extract stable-ordered, deduped raw inter-screen links from the pruned tree + raw flow entries. */
+export const extractInterScreenLinks = (rawRoot, screens) => {
+    const collected = [];
+    collectFlowEntries(rawRoot, collected);
+    for (const screen of screens)
+        visit(screen, collected);
+    const byKey = new Map();
+    for (const link of collected)
+        byKey.set(linkKey(link), link);
+    const byCode = (x, y) => (x < y ? -1 : x > y ? 1 : 0);
+    return [...byKey.values()].sort((a, b) => byCode(linkKey(a), linkKey(b)));
+};

package/dist/domain/figma/navGraph.d.ts

@@ -0,0 +1,74 @@
+import type { ScreenIrResult } from "./irTypes.js";
+import type { StructuralTestItem } from "./screenIrTestBaseline.js";
+/** A graph node: one screen. */
+export interface NavNode {
+    readonly screenId: string;
+    readonly screenName: string;
+}
+/** A resolved transition between two screens (both endpoints own a screen). */
+export interface NavEdge {
+    readonly fromScreenId: string;
+    readonly trigger: string;
+    readonly toScreenId: string;
+    readonly sourceNodeId: string;
+    readonly targetNodeId: string;
+}
+/** A raw link whose target node id resolves to no screen — an edge that leaves the known screens. */
+export interface UnresolvedLink {
+    readonly sourceNodeId: string;
+    readonly trigger: string;
+    readonly targetNodeId: string;
+}
+/** The deterministic navigation graph plus reachability analysis. */
+export interface NavGraph {
+    readonly nodes: readonly NavNode[];
+    readonly edges: readonly NavEdge[];
+    readonly unresolvedLinks: readonly UnresolvedLink[];
+    /** Screens that are flow entry points (or the synthetic first-screen entry when none exist). */
+    readonly entryScreenIds: readonly string[];
+    /** Reachable-by-no-edge-or-entry screens, stable-sorted. */
+    readonly unreachableScreenIds: readonly string[];
+    /** Reachable screens with no outgoing edge, stable-sorted. */
+    readonly deadEndScreenIds: readonly string[];
+}
+/** A bounded, acyclic multi-step path through the graph. */
+export interface NavFlow {
+    readonly screenIds: readonly string[];
+}
+/** A framework-agnostic routing hint: one screen and its outgoing transitions. */
+export interface RoutingHint {
+    readonly screenId: string;
+    readonly transitions: readonly {
+        readonly trigger: string;
+        readonly toScreenId: string;
+    }[];
+}
+/**
+ * Derive the deterministic navigation graph from a Screen-IR result. When the IR carries no
+ * flow-entry link, the first screen in stable id order is used as the synthetic entry so reachability
+ * is still well-defined. The result is byte-identical for a given input.
+ */
+export declare function deriveNavGraph(ir: ScreenIrResult): NavGraph;
+/**
+ * Derive bounded, acyclic multi-step flow paths from the graph's entry screens. `maxDepth` caps the
+ * number of screens per path (default {@link DEFAULT_MAX_FLOW_DEPTH}); the per-path visited set makes
+ * every path acyclic, so a cycle or self-loop never yields an unbounded path set. Total flows are
+ * capped at {@link MAX_NAV_FLOWS} so a dense fully-connected graph cannot exhaust memory. Stable-sorted.
+ */
+export declare function deriveNavFlows(graph: NavGraph, maxDepth?: number): readonly NavFlow[];
+/**
+ * Framework-agnostic routing hints for design-to-code (#755): every screen mapped to its outgoing
+ * transitions (`trigger` + `toScreenId`). No router, path, or framework vocabulary — a neutral
+ * structure the target adapter shapes into its own routing. Stable-sorted per screen and transition.
+ */
+export declare function deriveRoutingHints(graph: NavGraph): readonly RoutingHint[];
+/**
+ * Derive per-screen navigation/flow/coverage test items, keyed by the screen they are attributed to.
+ * Reuses #754's StructuralTestItem shape so the items compose additively through
+ * `deriveScreenTestBaseline(screen, extraItems)`. Every edge → a navigation item on its source
+ * screen; every multi-step flow → a flow item on its entry screen; every unreachable/dead-end screen
+ * → a coverage-notice item. When flow enumeration is truncated by MAX_NAV_FLOWS, one additional
+ * coverage-notice records the omission. Deterministic: items are emitted in the graph's stable order.
+ */
+export declare function deriveNavTestItemsByScreen(graph: NavGraph, maxFlowDepth?: number): ReadonlyMap<string, readonly StructuralTestItem[]>;
+//# sourceMappingURL=navGraph.d.ts.map

package/dist/domain/figma/navGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navGraph.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/navGraph.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAqC,cAAc,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AASpE,gCAAgC;AAChC,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,qGAAqG;AACrG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,SAAS,cAAc,EAAE,CAAC;IACpD,gGAAgG;IAChG,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,4DAA4D;IAC5D,QAAQ,CAAC,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;IACjD,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,4DAA4D;AAC5D,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,kFAAkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5F;AA6GD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,GAAG,QAAQ,CA0B3D;AA6DD;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,EACf,QAAQ,GAAE,MAA+B,GACxC,SAAS,OAAO,EAAE,CAWpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,WAAW,EAAE,CAU1E;AA+ED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,QAAQ,EACf,YAAY,GAAE,MAA+B,GAC5C,WAAW,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC,CAYpD"}

package/dist/domain/figma/navGraph.js

@@ -0,0 +1,315 @@
+// Deterministic screen navigation/flow graph from a Screen-IR (Epic #750, Issue #811).
+//
+// Pure domain: a Screen-IR (#752) carries `screens` (per-screen kept-node trees) and the raw
+// inter-screen `links` (prototype transitions `{ sourceNodeId, trigger, targetNodeId }`). This
+// module reduces them, with NO model and NO IO, to:
+//   • a navigation GRAPH — nodes = screens, edges = transitions whose source AND target node ids
+//     each resolve to an owning screen; links whose target resolves to no screen are recorded as
+//     `unresolvedLinks` (an "edge outside any screen"); flow-entry links (a canvas source outside
+//     any screen) mark `entryScreenIds` without an edge;
+//   • reachability — `entryScreenIds`, `unreachableScreenIds`, `deadEndScreenIds`;
+//   • framework-agnostic ROUTING HINTS (screen → outgoing transitions) for design-to-code (#755),
+//     with no router/framework vocabulary;
+//   • per-screen navigation/flow/coverage TEST ITEMS reusing #754's StructuralTestItem shape, so
+//     they compose into the figma-snapshot QI run additively through `deriveScreenTestBaseline`'s
+//     `extraItems` seam.
+//
+// Generic by construction: rules read only structural shape (which node ids own which screen, which
+// trigger reaches which screen). No screen name, layout, mask style, or copy is special-cased.
+// Deterministic: every emitted collection is stable-sorted and carries no timestamp, so the same IR
+// yields a byte-identical result. Flow derivation is bounded (max depth + acyclic visited set) so a
+// cycle or self-loop never produces an unbounded path set. Total flow count is also bounded by
+// MAX_NAV_FLOWS so a dense fully-connected graph cannot exhaust memory during QI ingestion.
+const FLOW_START_TRIGGER = "FLOW_START";
+const DEFAULT_MAX_FLOW_DEPTH = 6;
+// Total cap on enumerated flows: a fully-connected 12-screen graph at depth 6 yields 773,784+ paths
+// and hangs/OOMs QI ingestion. The cap preserves the deterministic prefix (derivation order is
+// already stable) and appends one coverage-notice when truncated. Mirrors MAX_A11Y_ITEMS_PER_SCREEN.
+const MAX_NAV_FLOWS = 500;
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+// Build a nodeId → screenId index by walking every screen's IR tree once. A node id that appears in
+// more than one screen (malformed input) keeps its first (stable-order) owner.
+function buildNodeOwnership(screens) {
+    const owner = new Map();
+    const visit = (node, screenId) => {
+        if (!owner.has(node.id))
+            owner.set(node.id, screenId);
+        for (const child of node.children)
+            visit(child, screenId);
+    };
+    for (const screen of [...screens].sort((a, b) => byString(a.id, b.id))) {
+        visit(screen.root, screen.id);
+    }
+    return owner;
+}
+// Injective composite key over a field tuple. The previous NUL-delimited join was non-injective:
+// a value carrying the separator byte could shift a field boundary so two distinct tuples collapse
+// to one key — the exact defect #752 fixed in links.ts linkKey, and a Figma node id or trigger from
+// an (untrusted) snapshot is not guaranteed separator-free. JSON.stringify escapes the quote,
+// backslash, and control bytes, so the encoding is total and unambiguous for any input. Used for
+// de-duplication, identity hashing, and stable total ordering so every emitted collection stays
+// byte-identical for a given input.
+const compositeKey = (...parts) => JSON.stringify(parts);
+const edgeKey = (e) => compositeKey(e.fromScreenId, e.trigger, e.toScreenId, e.sourceNodeId, e.targetNodeId);
+const flowKey = (screenIds) => compositeKey(...screenIds);
+// Classify each raw link against the node-ownership index. A target that owns a screen and a source
+// that owns a screen yields an edge; a FLOW_START whose target owns a screen marks an entry; any
+// link whose target owns no screen is unresolved (an edge that leaves the known screens).
+function classifyLinks(links, owner) {
+    const edges = new Map();
+    const unresolved = [];
+    const entries = new Set();
+    for (const link of links) {
+        const toScreenId = owner.get(link.targetNodeId);
+        if (toScreenId === undefined) {
+            unresolved.push({ ...link });
+            continue;
+        }
+        const fromScreenId = owner.get(link.sourceNodeId);
+        if (fromScreenId === undefined) {
+            if (link.trigger === FLOW_START_TRIGGER)
+                entries.add(toScreenId);
+            continue;
+        }
+        const edge = {
+            fromScreenId,
+            trigger: link.trigger,
+            toScreenId,
+            sourceNodeId: link.sourceNodeId,
+            targetNodeId: link.targetNodeId,
+        };
+        edges.set(edgeKey(edge), edge);
+    }
+    return {
+        edges: [...edges.values()].sort((a, b) => byString(edgeKey(a), edgeKey(b))),
+        // Total order: targetNodeId alone is not injective across unresolved links sharing a target, so
+        // input order would leak into the output and break the byte-identical guarantee (DET1). The
+        // full tuple key restores a deterministic total order under ties.
+        unresolved: [...unresolved].sort((a, b) => byString(compositeKey(a.targetNodeId, a.trigger, a.sourceNodeId), compositeKey(b.targetNodeId, b.trigger, b.sourceNodeId))),
+        entryScreenIds: [...entries].sort(byString),
+    };
+}
+// Reachable set by BFS from the entry screens over the directed edges.
+function reachableFrom(entryScreenIds, edges) {
+    const adjacency = new Map();
+    for (const edge of edges) {
+        const list = adjacency.get(edge.fromScreenId) ?? [];
+        list.push(edge.toScreenId);
+        adjacency.set(edge.fromScreenId, list);
+    }
+    const reached = new Set(entryScreenIds);
+    const queue = [...entryScreenIds];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            continue;
+        for (const next of adjacency.get(current) ?? []) {
+            if (!reached.has(next)) {
+                reached.add(next);
+                queue.push(next);
+            }
+        }
+    }
+    return reached;
+}
+/**
+ * Derive the deterministic navigation graph from a Screen-IR result. When the IR carries no
+ * flow-entry link, the first screen in stable id order is used as the synthetic entry so reachability
+ * is still well-defined. The result is byte-identical for a given input.
+ */
+export function deriveNavGraph(ir) {
+    const nodes = [...ir.screens]
+        .map((s) => ({ screenId: s.id, screenName: s.name }))
+        .sort((a, b) => byString(a.screenId, b.screenId));
+    const owner = buildNodeOwnership(ir.screens);
+    const { edges, unresolved, entryScreenIds } = classifyLinks(ir.links, owner);
+    const effectiveEntries = entryScreenIds.length > 0
+        ? entryScreenIds
+        : nodes.length > 0 && nodes[0] !== undefined
+            ? [nodes[0].screenId]
+            : [];
+    const reached = reachableFrom(effectiveEntries, edges);
+    const withOutgoing = new Set(edges.map((e) => e.fromScreenId));
+    return {
+        nodes,
+        edges,
+        unresolvedLinks: unresolved,
+        entryScreenIds: effectiveEntries,
+        unreachableScreenIds: nodes.map((n) => n.screenId).filter((id) => !reached.has(id)),
+        deadEndScreenIds: nodes
+            .map((n) => n.screenId)
+            .filter((id) => reached.has(id) && !withOutgoing.has(id)),
+    };
+}
+// Depth-first enumeration of acyclic paths from one entry, bounded by maxDepth, the visited set, and
+// the shared counter so dense graphs cannot exhaust memory or hang QI ingestion. Each path of length
+// ≥ 2 is a flow; the single-screen entry path is not emitted. Paths are in deterministic edge order.
+function walkFlows(start, adjacency, maxDepth, cap, counter, out) {
+    const recurse = (path) => {
+        if (counter.count >= cap)
+            return;
+        if (path.length >= 2) {
+            out.push([...path]);
+            counter.count += 1;
+        }
+        if (path.length >= maxDepth)
+            return;
+        const last = path[path.length - 1];
+        if (last === undefined)
+            return;
+        for (const next of adjacency.get(last) ?? []) {
+            if (counter.count >= cap)
+                return;
+            if (!path.includes(next))
+                recurse([...path, next]);
+        }
+    };
+    recurse([start]);
+}
+// Build the adjacency map once; edges are already stable-sorted so adjacency lists are deterministic.
+// Parallel edges (distinct prototype reactions from the same screen to the same target — two buttons,
+// or the same button with two triggers, both reaching A → B) must NOT push duplicate target entries:
+// walkFlows would traverse the identical sub-path once per duplicate, inflating the shared flow
+// counter past the number of DISTINCT flows. Because deriveNavTestItemsByScreen decides whether to
+// emit the truncation notice from the post-dedup flows.length, an inflated counter can hit
+// MAX_NAV_FLOWS and truncate enumeration while flows.length stays below the cap — silently dropping
+// flows with NO coverage-notice (CORR1). Navigation adjacency is a reachability relation, so a
+// per-source target set is the correct model and keeps the counter equal to the distinct-flow count.
+// First-occurrence order is preserved (edges are stable-sorted) so the derivation stays byte-identical.
+function buildAdjacency(edges) {
+    const adj = new Map();
+    const seen = new Map();
+    for (const edge of edges) {
+        const list = adj.get(edge.fromScreenId) ?? [];
+        const seenTargets = seen.get(edge.fromScreenId) ?? new Set();
+        if (seenTargets.has(edge.toScreenId))
+            continue;
+        list.push(edge.toScreenId);
+        seenTargets.add(edge.toScreenId);
+        adj.set(edge.fromScreenId, list);
+        seen.set(edge.fromScreenId, seenTargets);
+    }
+    return adj;
+}
+/**
+ * Derive bounded, acyclic multi-step flow paths from the graph's entry screens. `maxDepth` caps the
+ * number of screens per path (default {@link DEFAULT_MAX_FLOW_DEPTH}); the per-path visited set makes
+ * every path acyclic, so a cycle or self-loop never yields an unbounded path set. Total flows are
+ * capped at {@link MAX_NAV_FLOWS} so a dense fully-connected graph cannot exhaust memory. Stable-sorted.
+ */
+export function deriveNavFlows(graph, maxDepth = DEFAULT_MAX_FLOW_DEPTH) {
+    const adjacency = buildAdjacency(graph.edges);
+    const collected = [];
+    const counter = { count: 0 };
+    for (const entry of graph.entryScreenIds) {
+        if (counter.count >= MAX_NAV_FLOWS)
+            break;
+        walkFlows(entry, adjacency, maxDepth, MAX_NAV_FLOWS, counter, collected);
+    }
+    const byKey = new Map();
+    for (const screenIds of collected)
+        byKey.set(flowKey(screenIds), { screenIds });
+    return [...byKey.values()].sort((a, b) => byString(flowKey(a.screenIds), flowKey(b.screenIds)));
+}
+/**
+ * Framework-agnostic routing hints for design-to-code (#755): every screen mapped to its outgoing
+ * transitions (`trigger` + `toScreenId`). No router, path, or framework vocabulary — a neutral
+ * structure the target adapter shapes into its own routing. Stable-sorted per screen and transition.
+ */
+export function deriveRoutingHints(graph) {
+    return graph.nodes.map((node) => ({
+        screenId: node.screenId,
+        transitions: graph.edges
+            .filter((e) => e.fromScreenId === node.screenId)
+            .map((e) => ({ trigger: e.trigger, toScreenId: e.toScreenId }))
+            .sort((a, b) => byString(compositeKey(a.trigger, a.toScreenId), compositeKey(b.trigger, b.toScreenId))),
+    }));
+}
+const screenNameOf = (graph, screenId) => graph.nodes.find((n) => n.screenId === screenId)?.screenName ?? screenId;
+function navItemId(prefix, key) {
+    // Deterministic non-cryptographic id (FNV-1a) — stable across runs, no IO. Mirrors #754's scheme.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < key.length; i += 1) {
+        hash ^= key.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return `${prefix}-${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function navigationItem(graph, edge) {
+    const from = screenNameOf(graph, edge.fromScreenId);
+    const to = screenNameOf(graph, edge.toScreenId);
+    return {
+        id: navItemId("fnav", edgeKey(edge)),
+        category: "navigation",
+        screenId: edge.fromScreenId,
+        screenName: from,
+        sourceNodeId: edge.sourceNodeId,
+        title: `From screen "${from}", trigger "${edge.trigger}" reaches screen "${to}"`,
+    };
+}
+function flowItem(graph, flow) {
+    const entry = flow.screenIds[0] ?? "";
+    const names = flow.screenIds.map((id) => `"${screenNameOf(graph, id)}"`).join(" → ");
+    return {
+        id: navItemId("fflow", flowKey(flow.screenIds)),
+        category: "flow",
+        screenId: entry,
+        screenName: screenNameOf(graph, entry),
+        title: `Flow ${names} completes end to end`,
+    };
+}
+function coverageItem(graph, screenId, kind) {
+    const name = screenNameOf(graph, screenId);
+    const title = kind === "unreachable"
+        ? `Screen "${name}" is unreachable: no navigation reaches it`
+        : `Screen "${name}" is a dead end: no navigation leaves it`;
+    return {
+        id: navItemId("fcov", compositeKey(kind, screenId)),
+        category: "coverage-notice",
+        screenId,
+        screenName: name,
+        title,
+    };
+}
+// Emitted as a coverage-notice when flow enumeration was truncated by MAX_NAV_FLOWS. Attributed to
+// the synthetic entry screen (stable: first entry id) so it appears in a well-defined byScreen slot.
+function flowCapNoticeItem(graph, totalEnumerated) {
+    const entryId = graph.entryScreenIds[0] ?? graph.nodes[0]?.screenId ?? "";
+    const name = screenNameOf(graph, entryId);
+    return {
+        id: navItemId("fnavcap", compositeKey("cap", entryId)),
+        category: "coverage-notice",
+        screenId: entryId,
+        screenName: name,
+        title: `Flow enumeration was truncated at ${String(MAX_NAV_FLOWS)} paths (${String(totalEnumerated)} emitted); denser graphs may have additional flows`,
+    };
+}
+function pushItem(byScreen, item) {
+    const list = byScreen.get(item.screenId) ?? [];
+    list.push(item);
+    byScreen.set(item.screenId, list);
+}
+/**
+ * Derive per-screen navigation/flow/coverage test items, keyed by the screen they are attributed to.
+ * Reuses #754's StructuralTestItem shape so the items compose additively through
+ * `deriveScreenTestBaseline(screen, extraItems)`. Every edge → a navigation item on its source
+ * screen; every multi-step flow → a flow item on its entry screen; every unreachable/dead-end screen
+ * → a coverage-notice item. When flow enumeration is truncated by MAX_NAV_FLOWS, one additional
+ * coverage-notice records the omission. Deterministic: items are emitted in the graph's stable order.
+ */
+export function deriveNavTestItemsByScreen(graph, maxFlowDepth = DEFAULT_MAX_FLOW_DEPTH) {
+    const byScreen = new Map();
+    for (const edge of graph.edges)
+        pushItem(byScreen, navigationItem(graph, edge));
+    const flows = deriveNavFlows(graph, maxFlowDepth);
+    for (const flow of flows)
+        pushItem(byScreen, flowItem(graph, flow));
+    if (flows.length >= MAX_NAV_FLOWS) {
+        pushItem(byScreen, flowCapNoticeItem(graph, flows.length));
+    }
+    for (const id of graph.unreachableScreenIds)
+        pushItem(byScreen, coverageItem(graph, id, "unreachable"));
+    for (const id of graph.deadEndScreenIds)
+        pushItem(byScreen, coverageItem(graph, id, "dead end"));
+    return byScreen;
+}

package/dist/domain/figma/normalize.d.ts

@@ -0,0 +1,7 @@
+import type { IrNode } from "./irTypes.js";
+import type { PrunedNode } from "./prune.js";
+/** Normalize a pruned screen root into its IR node tree. Child order follows source order. */
+export declare const normalizeScreenRoot: (pruned: PrunedNode) => IrNode;
+/** Count the IR nodes in a normalized tree, used for the reduction ratio. */
+export declare const countIrNodes: (node: IrNode) => number;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/domain/figma/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/normalize.ts"],"names":[],"mappings":"AAsCA,OAAO,KAAK,EAMV,MAAM,EAKP,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAiO7C,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,GAAI,QAAQ,UAAU,KAAG,MAAgC,CAAC;AAO1F,6EAA6E;AAC7E,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAAiC,CAAC"}