@oscharko-dev/keiko-quality-intelligence 0.2.0

package/dist/domain/figma/screenIrTestBaseline.js

@@ -0,0 +1,326 @@
+// Deterministic structural test baseline from a Screen-IR (Epic #750, Issue #754).
+//
+// Pure domain: a Screen-IR (#752) is reduced by structural rules to a reproducible, citation-ready
+// list of test items — every input field → presence + validation tests; every control (button/link)
+// → action + expected-result tests; every screen → a render/navigation test; every state/variant
+// → a state test. No IO, no model, no network: the same IR yields a byte-identical baseline so the
+// QI source ships a usable baseline with NO model available.
+//
+// Generic by construction: the rules read only the IR's structural shape (interactionHint, node
+// type, text, and a generic `state`/`variant` naming convention shared across design tools). No
+// rule, threshold, name, or template is tuned to a specific board.
+//
+// Additive seam: `deriveScreenTestBaseline` accepts optional `extraItems`, so sibling derivations
+// (navigation/flow #811, a11y #812) can contribute extra per-screen test items WITHOUT changing the
+// baseline shape. Vision-derived semantics are layered separately (see visionAugmentation.ts) and
+// never replace these structural items.
+const INTERACTION_HINTS = new Set([
+    "button",
+    "input",
+    "link",
+    "text",
+    "image",
+    "container",
+]);
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+// Parse the optional bounding box from the serialised `irJson` (used by the a11y focus-order and
+// target-size derivation, #812). A malformed or partial box is dropped rather than crashing.
+function parseBoundingBox(value) {
+    if (!isObject(value))
+        return undefined;
+    const { x, y, width, height } = value;
+    if (!isFiniteNumber(x) ||
+        !isFiniteNumber(y) ||
+        !isFiniteNumber(width) ||
+        !isFiniteNumber(height)) {
+        return undefined;
+    }
+    return { x, y, width, height };
+}
+function parseImageFills(value) {
+    if (!Array.isArray(value))
+        return [];
+    const refs = [];
+    for (const entry of value) {
+        if (isObject(entry) && isString(entry.imageRef))
+            refs.push({ imageRef: entry.imageRef });
+    }
+    return refs;
+}
+// Subtrees deeper than this are truncated during parse so a chain-like persisted irJson cannot cause
+// a RangeError. Shared constant — see prune.ts for rationale. Must stay in sync with every walk.
+const MAX_TREE_DEPTH = 512;
+// The total accepted node count for one screen is bounded so a pathologically WIDE persisted irJson
+// (flat siblings, not deep nesting — invisible to MAX_TREE_DEPTH) cannot materialise unbounded
+// memory/time during parse and every derivation that walks the resulting tree. The cap is set well
+// above the per-screen node ceiling the governed Figma pipeline enforces before a snapshot is ever
+// written (the connector rejects oversized scopes/screens upstream), so every real board parses fully
+// and byte-identically; only an out-of-band, oversized irJson (e.g. a direct write into the evidence
+// dir) is truncated. Breadth is bounded the same way depth is — silently, at the read boundary.
+export const MAX_IR_NODES_PER_SCREEN = 20_000;
+// Parse a node's children list, dropping any malformed child rather than failing the whole node.
+// depth bounds recursion at MAX_TREE_DEPTH; budget bounds the total accepted node count — once it is
+// exhausted no further siblings are parsed, so a flat-wide children array degrades to a truncated
+// (still well-formed) subtree rather than an unbounded allocation.
+function parseIrChildren(value, depth, budget) {
+    if (depth > MAX_TREE_DEPTH)
+        return [];
+    if (!Array.isArray(value))
+        return [];
+    const children = [];
+    for (const child of value) {
+        if (budget.remaining <= 0)
+            break;
+        const parsed = parseIrNodeAt(child, depth, budget);
+        if (parsed !== undefined)
+            children.push(parsed);
+    }
+    return children;
+}
+// The optional, additive node fields (text, bounding box, a11y colours #812, layout fidelity).
+// Each is present only when well-typed; a malformed value is dropped so a corrupt node degrades
+// rather than crashing.
+function parseOptionalNodeFields(value) {
+    const boundingBox = parseBoundingBox(value.boundingBox);
+    const layout = parseIrLayout(value.layout);
+    const sizing = parseIrSizing(value.sizing);
+    const typography = parseIrTypography(value.typography);
+    const cornerRadius = isFiniteNumber(value.cornerRadius) ? value.cornerRadius : undefined;
+    return {
+        ...(isString(value.text) ? { text: value.text } : {}),
+        ...(boundingBox !== undefined ? { boundingBox } : {}),
+        ...(isString(value.textColor) ? { textColor: value.textColor } : {}),
+        ...(isString(value.backgroundColor) ? { backgroundColor: value.backgroundColor } : {}),
+        ...(layout !== undefined ? { layout } : {}),
+        ...(sizing !== undefined ? { sizing } : {}),
+        ...(cornerRadius !== undefined ? { cornerRadius } : {}),
+        ...(typography !== undefined ? { typography } : {}),
+    };
+}
+const LAYOUT_MODES = new Set(["row", "column"]);
+const ALIGN_VALUES = new Set(["start", "center", "end", "space-between"]);
+const SIZING_VALUES = new Set(["fixed", "hug", "fill"]);
+const parseAlign = (value) => isString(value) && ALIGN_VALUES.has(value) ? value : undefined;
+// Re-hydrate the layout-fidelity fields persisted in irJson (codegen path). Persisted snapshots
+// from before these fields existed simply omit them — every branch is total and optional.
+function parseIrLayout(value) {
+    if (!isObject(value) || !isString(value.mode) || !LAYOUT_MODES.has(value.mode))
+        return undefined;
+    const padding = parsePadding(value.padding);
+    const itemSpacing = isFiniteNumber(value.itemSpacing) ? value.itemSpacing : undefined;
+    const primaryAlign = parseAlign(value.primaryAlign);
+    const counterAlign = parseAlign(value.counterAlign);
+    return {
+        mode: value.mode,
+        ...(itemSpacing !== undefined ? { itemSpacing } : {}),
+        ...(padding !== undefined ? { padding } : {}),
+        ...(primaryAlign !== undefined ? { primaryAlign } : {}),
+        ...(counterAlign !== undefined ? { counterAlign } : {}),
+    };
+}
+function parsePadding(value) {
+    if (!Array.isArray(value) || value.length !== 4)
+        return undefined;
+    return value.every(isFiniteNumber)
+        ? value
+        : undefined;
+}
+const parseSizingValue = (value) => isString(value) && SIZING_VALUES.has(value) ? value : undefined;
+function parseIrSizing(value) {
+    if (!isObject(value))
+        return undefined;
+    const horizontal = parseSizingValue(value.horizontal);
+    const vertical = parseSizingValue(value.vertical);
+    if (horizontal === undefined && vertical === undefined)
+        return undefined;
+    return {
+        ...(horizontal !== undefined ? { horizontal } : {}),
+        ...(vertical !== undefined ? { vertical } : {}),
+    };
+}
+function parseIrTypography(value) {
+    if (!isObject(value))
+        return undefined;
+    const { fontFamily, fontSize, fontWeight, lineHeight } = value;
+    if (!isString(fontFamily) || !isFiniteNumber(fontSize) || !isFiniteNumber(fontWeight)) {
+        return undefined;
+    }
+    return {
+        fontFamily,
+        fontSize,
+        fontWeight,
+        ...(isFiniteNumber(lineHeight) ? { lineHeight } : {}),
+    };
+}
+// Total, defensive IR-node parser: an opaque serialised node (from the snapshot's `irJson`) is
+// accepted only when its required structural fields are present and well-typed; anything malformed
+// yields `undefined` so a corrupt screen degrades to "no items" rather than crashing the run.
+// depth bounds recursion at MAX_TREE_DEPTH; budget bounds the total accepted node count. A node is
+// counted against the budget only once it is accepted, so malformed nodes are free.
+function parseIrNodeAt(value, depth, budget) {
+    if (!isObject(value))
+        return undefined;
+    const { id, name, type, interactionHint } = value;
+    if (!isString(id) || !isString(name) || !isString(type))
+        return undefined;
+    if (!isString(interactionHint) || !INTERACTION_HINTS.has(interactionHint))
+        return undefined;
+    budget.remaining -= 1;
+    return {
+        id,
+        name,
+        type,
+        interactionHint: interactionHint,
+        ...parseOptionalNodeFields(value),
+        imageFills: parseImageFills(value.imageFills),
+        children: parseIrChildren(value.children, depth + 1, budget),
+    };
+}
+function parseIrNode(value) {
+    return parseIrNodeAt(value, 0, { remaining: MAX_IR_NODES_PER_SCREEN });
+}
+/**
+ * Total, defensive Screen-IR parser for the snapshot's opaque `irJson`. Returns `undefined` for a
+ * missing or malformed value (no `root`, malformed node tree) so the caller can skip an unparseable
+ * screen without crashing. A valid IR is returned verbatim through the typed shape.
+ */
+export function parseScreenIr(value) {
+    if (!isObject(value) || !isString(value.id) || !isString(value.name))
+        return undefined;
+    const root = parseIrNode(value.root);
+    if (root === undefined)
+        return undefined;
+    return { id: value.id, name: value.name, root };
+}
+// A generic state/variant naming convention shared across design tools: a node whose name carries an
+// explicit `state=` / `variant=` property segment, or a slash-delimited property. NOT tuned to any
+// board's vocabulary — it matches the structural property syntax, never specific state names.
+const STATE_PROPERTY = /(?:^|[,\s])(?:state|variant)\s*=\s*([^,]+)/iu;
+function stateLabel(name) {
+    const match = STATE_PROPERTY.exec(name);
+    const captured = match?.[1]?.trim();
+    return captured !== undefined && captured.length > 0 ? captured : undefined;
+}
+function shortHash(input) {
+    // Deterministic non-cryptographic id suffix (FNV-1a) — stable across runs, no IO, no import.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16).padStart(8, "0");
+}
+function itemId(screenId, category, nodeId, ordinal) {
+    return `fst-${shortHash(`${screenId}|${category}|${nodeId}|${String(ordinal)}`)}`;
+}
+function fieldItems(node, ctx) {
+    const label = node.text !== undefined && node.text.length > 0 ? node.text : node.name;
+    const base = { screenId: ctx.screenId, screenName: ctx.screenName, sourceNodeId: node.id };
+    return [
+        {
+            ...base,
+            id: itemId(ctx.screenId, "field-presence", node.id, 0),
+            category: "field-presence",
+            title: `Field "${label}" is present and editable on screen "${ctx.screenName}"`,
+        },
+        {
+            ...base,
+            id: itemId(ctx.screenId, "field-validation", node.id, 0),
+            category: "field-validation",
+            title: `Field "${label}" rejects empty / malformed input on screen "${ctx.screenName}"`,
+        },
+    ];
+}
+function controlItems(node, ctx) {
+    const label = node.text !== undefined && node.text.length > 0 ? node.text : node.name;
+    const verb = node.interactionHint === "link" ? "Following" : "Activating";
+    return [
+        {
+            screenId: ctx.screenId,
+            screenName: ctx.screenName,
+            sourceNodeId: node.id,
+            id: itemId(ctx.screenId, "control-action", node.id, 0),
+            category: "control-action",
+            title: `${verb} "${label}" produces its expected result on screen "${ctx.screenName}"`,
+        },
+    ];
+}
+function stateItem(node, ctx, label) {
+    return {
+        screenId: ctx.screenId,
+        screenName: ctx.screenName,
+        sourceNodeId: node.id,
+        id: itemId(ctx.screenId, "state", node.id, 0),
+        category: "state",
+        title: `Element "${node.name}" renders correctly in state "${label}" on screen "${ctx.screenName}"`,
+    };
+}
+function collectNodeItemsAt(node, ctx, out, depth) {
+    if (depth > MAX_TREE_DEPTH)
+        return;
+    if (node.interactionHint === "input")
+        out.push(...fieldItems(node, ctx));
+    if (node.interactionHint === "button" || node.interactionHint === "link") {
+        out.push(...controlItems(node, ctx));
+    }
+    const state = stateLabel(node.name);
+    if (state !== undefined)
+        out.push(stateItem(node, ctx, state));
+    for (const child of node.children)
+        collectNodeItemsAt(child, ctx, out, depth + 1);
+}
+function collectNodeItems(node, ctx, out) {
+    collectNodeItemsAt(node, ctx, out, 0);
+}
+function screenRenderItem(ctx) {
+    return {
+        screenId: ctx.screenId,
+        screenName: ctx.screenName,
+        id: itemId(ctx.screenId, "screen-render", ctx.screenId, 0),
+        category: "screen-render",
+        title: `Screen "${ctx.screenName}" renders correctly`,
+    };
+}
+/**
+ * Derive the deterministic structural baseline for one screen. The screen-render item comes first,
+ * then field / control / state items in stable depth-first node order. `extraItems` is the additive
+ * seam (#811 navigation, #812 a11y): a sibling derivation may contribute already-built test items
+ * for this screen without changing the baseline shape. The result is reproducible for a given IR.
+ */
+export function deriveScreenTestBaseline(screen, extraItems = []) {
+    const ctx = { screenId: screen.id, screenName: screen.name };
+    const items = [screenRenderItem(ctx)];
+    collectNodeItems(screen.root, ctx, items);
+    items.push(...extraItems);
+    return { screenId: screen.id, screenName: screen.name, items };
+}
+/**
+ * Render the structural baseline as citation-ready canonical text carrying per-screen provenance.
+ * The text is deterministic (no timestamps, stable order) and is what the QI ingestion turns into a
+ * content-bearing atom. Vision-derived hints, when present, are appended SEPARATELY by the caller
+ * (visionAugmentation.ts) and never replace these lines.
+ */
+/**
+ * Stable marker line introducing the structural baseline inside a Figma screen atom's canonical text.
+ * Exported so the deterministic test-design model (`testDesignModel.ts`) can recognise a Figma screen
+ * atom and emit a clean, screen-scoped structural candidate instead of the generic prose-requirement
+ * template (which produces an atom-id/hash-laden stub for a structural baseline). Intentionally NOT
+ * re-exported from the figma barrel (`domain/figma/index.ts`), so it stays off the package surface.
+ */
+export const STRUCTURAL_BASELINE_MARKER = "Structural test baseline (deterministic, derived from Screen-IR):";
+export function renderBaselineText(baseline) {
+    const header = `Screen: ${baseline.screenName} [${baseline.screenId}]`;
+    const lines = baseline.items.map((item) => {
+        const nodeRef = item.sourceNodeId !== undefined ? ` [node:${item.sourceNodeId}]` : "";
+        return `- (${item.category}) ${item.title}${nodeRef}`;
+    });
+    return [header, STRUCTURAL_BASELINE_MARKER, ...lines].join("\n");
+}

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

@@ -0,0 +1,24 @@
+import type { CodeEmissionPlan, EmissionElement } from "./emissionPlan.js";
+/** A request for semantic names: each element's id, role, and current structural default name. */
+export interface SemanticNamingRequest {
+    readonly elements: readonly {
+        readonly id: string;
+        readonly role: EmissionElement["role"];
+        readonly structuralName: string;
+    }[];
+}
+/**
+ * The naming port: given the structural elements, return a map (or record) from element id to a
+ * proposed semantic display name. The server backs this with a capability-routed model; tests back it
+ * with a plain function. Returning nothing for an id leaves its structural default untouched.
+ */
+export type SemanticNamingProvider = (request: SemanticNamingRequest) => ReadonlyMap<string, string> | Readonly<Record<string, string>>;
+/**
+ * Apply a semantic-naming provider to a plan, overriding ONLY element display names. The element
+ * tree, roles, text, tokens, and navigation are preserved byte-for-byte; only `displayName` fields
+ * may change, and only for elements the provider names with a non-empty string. With no usable name
+ * for an element (or a missing provider entry), the structural default stands. Deterministic and
+ * side-effect-free.
+ */
+export declare function applyNaming(plan: CodeEmissionPlan, provider: SemanticNamingProvider): CodeEmissionPlan;
+//# sourceMappingURL=semanticNaming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"semanticNaming.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/semanticNaming.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAkB,MAAM,mBAAmB,CAAC;AAE3F,kGAAkG;AAClG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;QACvC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,EAAE,CAAC;CACL;AAED;;;;GAIG;AACH,MAAM,MAAM,sBAAsB,GAAG,CACnC,OAAO,EAAE,qBAAqB,KAC3B,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAyDpE;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,EAAE,sBAAsB,GAC/B,gBAAgB,CAIlB"}

package/dist/domain/figma/semanticNaming.js

@@ -0,0 +1,67 @@
+// Model-only-for-naming port for design-to-code emission (Epic #750, Issue #755).
+//
+// The deterministic emitter (emissionPlan.ts) already produces a complete, usable plan with
+// structural default names and NO model. This module is the strictly-additive seam by which a
+// capability-routed model may supply BETTER semantic display names — and nothing else. The override
+// is enforced STRUCTURALLY: `applyNaming` only ever replaces an element's `displayName`; it cannot
+// add, remove, reorder, or re-parent an element, change a role, change text, or change navigation.
+// There is no code path by which a model name reaches structure. An absent provider, an unknown id,
+// or an empty/whitespace name leaves the structural default in place — so naming degrades gracefully
+// to the deterministic baseline. The provider is injected (a port), so no model id is hard-coded
+// here; the server tier resolves the model by capability (#810) and backs this port.
+function collectRequestElements(element, out) {
+    out.push({ id: element.id, role: element.role, structuralName: element.displayName });
+    for (const child of element.children)
+        collectRequestElements(child, out);
+}
+function buildRequest(plan) {
+    const elements = [];
+    for (const screen of plan.screens)
+        collectRequestElements(screen.root, elements);
+    return { elements };
+}
+// Project the provider result to id/value pairs, accepting either a Map or a plain record.
+function namingEntries(result) {
+    if (result instanceof Map) {
+        const map = result;
+        return [...map.entries()];
+    }
+    return Object.entries(result);
+}
+// Normalise the provider result to a lookup. A non-string or empty/whitespace value is dropped so a
+// garbage model output never overrides a structural default — it simply contributes nothing.
+function toNameLookup(result) {
+    const lookup = new Map();
+    for (const [id, value] of namingEntries(result)) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed.length > 0)
+            lookup.set(id, trimmed);
+    }
+    return lookup;
+}
+function renameElement(element, names) {
+    const override = names.get(element.id);
+    return {
+        ...element,
+        ...(override !== undefined ? { displayName: override } : {}),
+        children: element.children.map((child) => renameElement(child, names)),
+    };
+}
+function renameScreen(screen, names) {
+    return { ...screen, root: renameElement(screen.root, names) };
+}
+/**
+ * Apply a semantic-naming provider to a plan, overriding ONLY element display names. The element
+ * tree, roles, text, tokens, and navigation are preserved byte-for-byte; only `displayName` fields
+ * may change, and only for elements the provider names with a non-empty string. With no usable name
+ * for an element (or a missing provider entry), the structural default stands. Deterministic and
+ * side-effect-free.
+ */
+export function applyNaming(plan, provider) {
+    const names = toNameLookup(provider(buildRequest(plan)));
+    if (names.size === 0)
+        return plan;
+    return { ...plan, screens: plan.screens.map((screen) => renameScreen(screen, names)) };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * The subset of a raw Figma node the cleaner reads. Open-ended (`[key: string]: unknown`) because
+ * the provider payload carries many fields we ignore; readers narrow before use.
+ */
+export interface FigmaSourceNode {
+    readonly id?: unknown;
+    readonly name?: unknown;
+    readonly type?: unknown;
+    readonly visible?: unknown;
+    readonly children?: unknown;
+    readonly [key: string]: unknown;
+}
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const asNode: (value: unknown) => FigmaSourceNode | undefined;
+export declare const readString: (value: unknown) => string | undefined;
+export declare const readNumber: (value: unknown) => number | undefined;
+export declare const readArray: (value: unknown) => readonly unknown[];
+/** Figma omits `visible` when a node is shown; only an explicit `false` hides it. */
+export declare const isHidden: (node: FigmaSourceNode) => boolean;
+export declare const nodeId: (node: FigmaSourceNode) => string;
+export declare const nodeName: (node: FigmaSourceNode) => string;
+export declare const nodeType: (node: FigmaSourceNode) => string;
+export declare const childNodes: (node: FigmaSourceNode) => readonly FigmaSourceNode[];
+//# sourceMappingURL=sourceNode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sourceNode.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/sourceNode.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,eAAO,MAAM,QAAQ,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CACH,CAAC;AAEvE,eAAO,MAAM,MAAM,GAAI,OAAO,OAAO,KAAG,eAAe,GAAG,SACrB,CAAC;AAEtC,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SACN,CAAC;AAEhD,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SACoB,CAAC;AAE1E,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,SAAS,OAAO,EACxB,CAAC;AAEpC,qFAAqF;AACrF,eAAO,MAAM,QAAQ,GAAI,MAAM,eAAe,KAAG,OAAiC,CAAC;AAEnF,eAAO,MAAM,MAAM,GAAI,MAAM,eAAe,KAAG,MAAmC,CAAC;AAEnF,eAAO,MAAM,QAAQ,GAAI,MAAM,eAAe,KAAG,MAAqC,CAAC;AAEvF,eAAO,MAAM,QAAQ,GAAI,MAAM,eAAe,KAAG,MAAqC,CAAC;AAEvF,eAAO,MAAM,UAAU,GAAI,MAAM,eAAe,KAAG,SAAS,eAAe,EAO1E,CAAC"}

package/dist/domain/figma/sourceNode.js

@@ -0,0 +1,26 @@
+// Minimal, untyped-tolerant input model for the raw scoped Figma node subtree (Epic #750, Issue #752).
+//
+// The cleaner consumes the raw Figma `document` node tree returned by the server-side connector
+// (#751). That JSON is provider-shaped and only partially typed, so this module models the few
+// fields the IR needs and exposes narrowing readers over `unknown` — never `any`. Direction is
+// clean: this package depends on nothing from keiko-server; the readers tolerate absent/malformed
+// fields so a single bad node never aborts the transform.
+export const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+export const asNode = (value) => isRecord(value) ? value : undefined;
+export const readString = (value) => typeof value === "string" ? value : undefined;
+export const readNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+export const readArray = (value) => Array.isArray(value) ? value : [];
+/** Figma omits `visible` when a node is shown; only an explicit `false` hides it. */
+export const isHidden = (node) => node.visible === false;
+export const nodeId = (node) => readString(node.id) ?? "";
+export const nodeName = (node) => readString(node.name) ?? "";
+export const nodeType = (node) => readString(node.type) ?? "";
+export const childNodes = (node) => {
+    const out = [];
+    for (const child of readArray(node.children)) {
+        const record = asNode(child);
+        if (record !== undefined)
+            out.push(record);
+    }
+    return out;
+};

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

@@ -0,0 +1,11 @@
+import type { DesignTokens } from "./irTypes.js";
+import type { PrunedNode } from "./prune.js";
+/** Extract deduped, stable-ordered design tokens from the pruned screen roots. */
+export declare const extractDesignTokens: (screens: readonly PrunedNode[]) => DesignTokens;
+/**
+ * Re-hydrate a {@link DesignTokens} value from the opaque, serialised tokens artifact persisted in a
+ * Figma Snapshot (#753). Total + defensive: a non-object or any malformed family degrades to an empty
+ * list so design-to-code (#755) never crashes on an old or partial snapshot. Stable shape, no IO.
+ */
+export declare const parseDesignTokens: (value: unknown) => DesignTokens;
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/tokens.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAEV,YAAY,EAIb,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAoF7C,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,GAAI,SAAS,SAAS,UAAU,EAAE,KAAG,YAiBpE,CAAC;AA0DF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,YAQlD,CAAC"}

package/dist/domain/figma/tokens.js

@@ -0,0 +1,148 @@
+// Deterministic design-token extraction (Epic #750, Issue #752).
+//
+// Walks the kept (pruned) node trees and projects four token families out of structural fields:
+//   color       — solid `fills`/`strokes` → normalized #RRGGBB / #RRGGBBAA (alpha only when < 1).
+//   typography  — TEXT `style` → family|size|weight|lineHeight.
+//   spacing     — auto-layout `itemSpacing` + paddingTop/Right/Bottom/Left → distinct numbers.
+//   radius      — `cornerRadius` → distinct numbers.
+//
+// Token identity is the canonical value (content-free): same value → one token, regardless of how
+// many nodes carry it or in what order. Every family is sorted by its canonical key before emit, so
+// output never depends on traversal or map-insertion order.
+import { asNode, nodeType, readArray, readNumber, readString, } from "./sourceNode.js";
+import { isVisiblePaint, paintColorToHex } from "./color.js";
+const collectPaintColors = (node, key, out) => {
+    for (const paint of readArray(node[key])) {
+        const record = asNode(paint);
+        if (record === undefined || readString(record.type) !== "SOLID")
+            continue;
+        if (!isVisiblePaint(record))
+            continue;
+        const hex = paintColorToHex(record);
+        if (hex !== undefined)
+            out.add(hex);
+    }
+};
+const collectTypography = (node, out) => {
+    if (nodeType(node) !== "TEXT")
+        return;
+    const style = asNode(node.style);
+    if (style === undefined)
+        return;
+    const fontFamily = readString(style.fontFamily);
+    const fontSize = readNumber(style.fontSize);
+    const fontWeight = readNumber(style.fontWeight);
+    const lineHeight = readNumber(style.lineHeightPx);
+    if (fontFamily === undefined ||
+        fontSize === undefined ||
+        fontWeight === undefined ||
+        lineHeight === undefined) {
+        return;
+    }
+    const id = `typography:${fontFamily}|${String(fontSize)}|${String(fontWeight)}|${String(lineHeight)}`;
+    out.set(id, { id, kind: "typography", fontFamily, fontSize, fontWeight, lineHeight });
+};
+const SPACING_KEYS = ["itemSpacing", "paddingTop", "paddingRight", "paddingBottom", "paddingLeft"];
+const collectSpacing = (node, out) => {
+    for (const key of SPACING_KEYS) {
+        const value = readNumber(node[key]);
+        if (value !== undefined && value > 0)
+            out.add(value);
+    }
+};
+const collectRadius = (node, out) => {
+    const value = readNumber(node.cornerRadius);
+    if (value !== undefined && value > 0)
+        out.add(value);
+};
+// Shared constant — see prune.ts for rationale. Must stay in sync with every other recursive walk.
+const MAX_TREE_DEPTH = 512;
+function visitAt(pruned, acc, depth) {
+    if (depth > MAX_TREE_DEPTH)
+        return;
+    const node = pruned.source;
+    collectPaintColors(node, "fills", acc.colors);
+    collectPaintColors(node, "strokes", acc.colors);
+    collectTypography(node, acc.typography);
+    collectSpacing(node, acc.spacing);
+    collectRadius(node, acc.radius);
+    for (const child of pruned.children)
+        visitAt(child, acc, depth + 1);
+}
+const visit = (pruned, acc) => {
+    visitAt(pruned, acc, 0);
+};
+const toColorTokens = (values) => [...values].sort().map((value) => ({ id: `color:${value}`, kind: "color", value }));
+const toSpacingTokens = (values) => [...values]
+    .sort((a, b) => a - b)
+    .map((value) => ({ id: `spacing:${String(value)}`, kind: "spacing", value }));
+const toRadiusTokens = (values) => [...values]
+    .sort((a, b) => a - b)
+    .map((value) => ({ id: `radius:${String(value)}`, kind: "radius", value }));
+/** Extract deduped, stable-ordered design tokens from the pruned screen roots. */
+export const extractDesignTokens = (screens) => {
+    const acc = {
+        colors: new Set(),
+        typography: new Map(),
+        spacing: new Set(),
+        radius: new Set(),
+    };
+    for (const screen of screens)
+        visit(screen, acc);
+    return {
+        colors: toColorTokens(acc.colors),
+        typography: [...acc.typography.values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0),
+        spacing: toSpacingTokens(acc.spacing),
+        radius: toRadiusTokens(acc.radius),
+    };
+};
+// ─── Tolerant parse of a persisted/serialised design-tokens artifact (#752 → #755) ──────
+//
+// The snapshot persists the tokens artifact as an opaque JSON value (like the screen IR). Design-to-
+// code (#755) reads the STORED snapshot, so it must re-hydrate the typed shape defensively: a missing
+// or malformed family yields an empty list (codegen emits a smaller token table) rather than crashing.
+const EMPTY_DESIGN_TOKENS = { colors: [], typography: [], spacing: [], radius: [] };
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isString = (value) => typeof value === "string";
+const isFiniteNumber = (value) => typeof value === "number" && Number.isFinite(value);
+const parseColorRows = (value) => (Array.isArray(value) ? value : []).flatMap((entry) => isRecord(entry) && isString(entry.value)
+    ? [{ id: `color:${entry.value}`, kind: "color", value: entry.value }]
+    : []);
+const parseTypographyRows = (value) => (Array.isArray(value) ? value : []).flatMap((entry) => {
+    if (!isRecord(entry) ||
+        !isString(entry.fontFamily) ||
+        !isFiniteNumber(entry.fontSize) ||
+        !isFiniteNumber(entry.fontWeight) ||
+        !isFiniteNumber(entry.lineHeight)) {
+        return [];
+    }
+    const id = `typography:${entry.fontFamily}|${String(entry.fontSize)}|${String(entry.fontWeight)}|${String(entry.lineHeight)}`;
+    return [
+        {
+            id,
+            kind: "typography",
+            fontFamily: entry.fontFamily,
+            fontSize: entry.fontSize,
+            fontWeight: entry.fontWeight,
+            lineHeight: entry.lineHeight,
+        },
+    ];
+});
+const parseScalarRows = (value, kind) => (Array.isArray(value) ? value : []).flatMap((entry) => isRecord(entry) && isFiniteNumber(entry.value)
+    ? [{ id: `${kind}:${String(entry.value)}`, kind, value: entry.value }]
+    : []);
+/**
+ * Re-hydrate a {@link DesignTokens} value from the opaque, serialised tokens artifact persisted in a
+ * Figma Snapshot (#753). Total + defensive: a non-object or any malformed family degrades to an empty
+ * list so design-to-code (#755) never crashes on an old or partial snapshot. Stable shape, no IO.
+ */
+export const parseDesignTokens = (value) => {
+    if (!isRecord(value))
+        return EMPTY_DESIGN_TOKENS;
+    return {
+        colors: parseColorRows(value.colors),
+        typography: parseTypographyRows(value.typography),
+        spacing: parseScalarRows(value.spacing, "spacing"),
+        radius: parseScalarRows(value.radius, "radius"),
+    };
+};

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

@@ -0,0 +1,14 @@
+export interface VisionMergeResult {
+    /** Baseline text with the additive vision section appended; equals `baselineText` when no hints. */
+    readonly text: string;
+    /** How many vision hints survived sanitisation and were appended. */
+    readonly augmentedCount: number;
+}
+/**
+ * Merge vision hints into the deterministic baseline text WITHOUT overriding it. The baseline text is
+ * always the prefix of the result; hints (if any survive sanitisation) follow under a labelled
+ * section. When no hint survives, the result text is identical to `baselineText`, so the structural
+ * baseline always ships and the vision contribution is provably additive.
+ */
+export declare function mergeVisionHints(baselineText: string, hints: readonly string[]): VisionMergeResult;
+//# sourceMappingURL=visionAugmentation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"visionAugmentation.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/visionAugmentation.ts"],"names":[],"mappings":"AAmCA,MAAM,WAAW,iBAAiB;IAChC,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,iBAAiB,CAOnB"}