@oscharko-dev/keiko-quality-intelligence 0.2.0

package/dist/domain/figma/htmlCssAdapter.js

@@ -0,0 +1,452 @@
+// Framework-agnostic HTML/CSS CodeTargetAdapter — the first-slice code target (Epic #750, Issue #755).
+//
+// Renders the target-neutral emission plan (emissionPlan.ts) to clean, semantic HTML plus a CSS
+// custom-property stylesheet built from the design tokens (#752). No framework, router, or component
+// library: each element role maps to a semantic HTML tag, each design token to a CSS variable, and
+// each screen's routing hints (#811) to a `<nav>` of plain anchors carrying the trigger as a data
+// attribute. The adapter consumes token VARIABLES — it never re-derives or hard-codes raw values
+// beyond emitting the token table itself.
+//
+// Output is a reviewable proposal (an ordered file list): `index.html` (links every screen),
+// `tokens.css` (the `:root` custom-property table), and one `screens/<id>.html` per screen. Pure: no
+// IO, no model, no clock — a given plan yields a byte-identical artifact. All text and attribute values
+// are HTML-escaped so the reviewable artifact cannot inject markup, and unsafe Unicode format chars
+// (bidi-override / zero-width / C0-C1 / DEL) are stripped from every emitted string before escaping —
+// these are not HTML metacharacters and would otherwise survive into the artifact, enabling
+// Trojan-source spoofing and zero-width-split secrets that evade redaction (same invariant the QI atom
+// path enforces). The TAB/LF/CR trio and all ordinary text survive, so clean boards are unchanged.
+//
+// CSS value handling: fontFamily tokens are emitted as quoted strings with embedded double-quotes
+// escaped and control/injection characters ('{', '}', ';', '</', '*/', newlines) stripped, so a
+// hostile font name cannot break out of the custom-property declaration. Color tokens are validated
+// against /^#[0-9a-fA-F]{3,8}$/ and numeric tokens as finite numbers; invalid values are dropped
+// rather than emitted.
+//
+// Screen file names: Figma ids may contain ':' (Windows-invalid) and ';' (URI scheme risk in hrefs).
+// Stored evidence can also be tampered with, so screen ids are normalized to one safe POSIX path
+// segment ([A-Za-z0-9_-]) before they become CodeFile.path / href material. Collisions after
+// substitution are resolved by a numeric suffix. All relative hrefs inside screen HTML are prefixed
+// with './' so they are relative to the screens/ directory, not ambiguous URI-scheme fragments. The
+// raw screen id is preserved in the data-screen-id attribute.
+//
+// Layout / sizing / cornerRadius / typography (from IrNode, threaded through EmissionElement):
+// For nodes with auto-layout, a deterministic CSS class is emitted (name = "n-" + sanitized node id)
+// carrying display:flex, flex-direction, gap, padding, and border-radius. TEXT nodes with typography
+// matching a tokens.css entry reference var(--font-N). fill-sized nodes emit flex:1 / width:100% on
+// the relevant axis; hug is the default (no output).
+//
+// What IS reproduced: auto-layout direction, gap, padding, border-radius, font (via token var or
+// inline).
+// What is NOT reproduced: absolute positioning, constraints, effects (shadows/blur), image fills
+// beyond refs, grid layout, overflow, z-ordering, component variants.
+import { stripUnsafeFormatChars } from "../assertions.js";
+const ADAPTER_NAME = "html-css";
+const INDENT = "  ";
+const HTML_ESCAPES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+// Strip unsafe Unicode format chars (bidi-override / zero-width / C0-C1 / DEL) BEFORE HTML-escaping.
+// These are NOT HTML metacharacters, so escaping alone passes them verbatim into the reviewable
+// artifact — enabling Trojan-source spoofing and zero-width-split secrets that evade redaction. This
+// mirrors the QI atom-text invariant (stripUnsafeFormatChars). Clean text is unchanged — the TAB/LF/CR
+// trio and all ordinary/accented/CJK/emoji code points survive — so deterministic output stays
+// byte-identical for non-hostile boards.
+const escapeHtml = (value) => stripUnsafeFormatChars(value).replace(/[&<>"']/gu, (char) => HTML_ESCAPES[char] ?? char);
+const indent = (depth) => INDENT.repeat(depth);
+// ─── Fix #7: safe screen file names ──────────────────────────────────────────
+//
+// Figma ids contain ':' (invalid on Windows file paths) and INSTANCE ids contain ';' which is parsed
+// as a URI scheme separator in sibling hrefs (e.g. "I123:456;789:12.html" → opaque URI). A tampered
+// stored snapshot could also contain slashes, backslashes, or other path metacharacters. Normalize to
+// a single artifact-relative filename segment. Ids are unique before substitution so collisions are
+// rare, but a numeric suffix is appended defensively.
+const SAFE_SCREEN_FILE_RE = /[^A-Za-z0-9_-]/gu;
+function sanitizeScreenFileName(screenId) {
+    const cleaned = stripUnsafeFormatChars(screenId)
+        .replace(SAFE_SCREEN_FILE_RE, "-")
+        .replace(/-+/gu, "-")
+        .replace(/^-|-$/gu, "");
+    return cleaned.length > 0 ? cleaned : "screen";
+}
+function buildSafeNameIndex(screens) {
+    const seen = new Map();
+    const result = new Map();
+    for (const screen of screens) {
+        const base = sanitizeScreenFileName(screen.screenId);
+        const count = seen.get(base) ?? 0;
+        seen.set(base, count + 1);
+        result.set(screen.screenId, count === 0 ? base : `${base}-${String(count)}`);
+    }
+    return result;
+}
+// ─── Fix #8: CSS value sanitization ──────────────────────────────────────────
+//
+// fontFamily is emitted as a CSS quoted string. Embedded double-quotes are escaped as \\22 (the
+// CSS hex escape for ") and injection sequences ('{', '}', ';', '</', '*/', newlines, control
+// chars) are stripped, so a hostile font name cannot break out of the declaration.
+// Unicode escapes for control characters (U+0000-U+001F) and DEL (U+007F) avoid the no-control-regex
+// lint rule while matching the same character set at runtime.
+// eslint-disable-next-line no-control-regex
+const CSS_INJECTION_RE = /[{};]|<\/|\*\/|[\u0000-\u001f\u007f]/gu;
+const safeFontFamily = (family) => {
+    // Strip unsafe Unicode format chars first — bidi/zero-width/C1 are NOT covered by CSS_INJECTION_RE
+    // (which only strips C0/DEL + structural injection sequences) — then escape embedded quotes. Same
+    // egress invariant as escapeHtml: these chars would otherwise survive into the quoted CSS string.
+    const cleaned = stripUnsafeFormatChars(family)
+        .replace(CSS_INJECTION_RE, "")
+        .replace(/"/gu, "\\22 ");
+    return `"${cleaned}"`;
+};
+// Valid CSS hex color: 3, 4, 6, or 8 hex digits.
+const HEX_COLOR_RE = /^#[0-9a-fA-F]{3,8}$/u;
+const isSafeColor = (value) => HEX_COLOR_RE.test(value);
+// ─── Map a target-neutral element role to a semantic HTML tag ─────────────────
+// Containers become <section>; everything else is the closest semantic element.
+const TAG_BY_ROLE = {
+    button: "button",
+    input: "input",
+    link: "a",
+    text: "p",
+    image: "img",
+    container: "section",
+};
+// Roles that render as void (self-closing) elements with no children/text.
+const VOID_ROLES = new Set(["input", "image"]);
+const colorVar = (index) => `--color-${String(index + 1)}`;
+const spaceVar = (index) => `--space-${String(index + 1)}`;
+const radiusVar = (index) => `--radius-${String(index + 1)}`;
+const fontVar = (index) => `--font-${String(index + 1)}`;
+// Typography key used to match per-node typography against the global token table.
+const typographyKey = (t) => `${t.fontFamily}|${String(t.fontSize)}|${String(t.fontWeight)}|${String(t.lineHeight ?? "")}`;
+const typographyTokenKey = (t) => `${t.fontFamily}|${String(t.fontSize)}|${String(t.fontWeight)}|${String(t.lineHeight)}`;
+const buildTokenLookups = (tokens) => {
+    const colorMap = new Map();
+    tokens.colors.forEach((token, i) => {
+        colorMap.set(token.value, colorVar(i));
+    });
+    const fontMap = new Map();
+    tokens.typography.forEach((token, i) => {
+        fontMap.set(typographyTokenKey(token), fontVar(i));
+    });
+    const spaceMap = new Map();
+    tokens.spacing.forEach((token, i) => {
+        spaceMap.set(token.value, spaceVar(i));
+    });
+    const radiusMap = new Map();
+    tokens.radius.forEach((token, i) => {
+        radiusMap.set(token.value, radiusVar(i));
+    });
+    return { colorVar: colorMap, fontVar: fontMap, spaceVar: spaceMap, radiusVar: radiusMap };
+};
+// ─── Per-node CSS class generation ───────────────────────────────────────────
+//
+// A deterministic class name is derived from the node id by replacing non-alphanumeric characters
+// with "-" and prefixing "n-". When two raw ids sanitize to the same slug, append a stable raw-id
+// hash to the later class so distinct Figma nodes cannot alias onto one CSS selector.
+const sanitizeIdForClass = (id) => id.replace(/[^a-zA-Z0-9]/gu, "-");
+const classHash = (id) => {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < id.length; i += 1) {
+        hash ^= id.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(36);
+};
+const nodeClassBase = (id) => `n-${sanitizeIdForClass(id) || "node"}`;
+const nodeClass = (id, ctx) => {
+    const existing = ctx.classMap.get(id);
+    if (existing !== undefined)
+        return existing;
+    const base = nodeClassBase(id);
+    const owner = ctx.usedClasses.get(base);
+    const cls = owner === undefined || owner === id ? base : `${base}-${classHash(id)}`;
+    ctx.usedClasses.set(cls, id);
+    ctx.classMap.set(id, cls);
+    return cls;
+};
+const ALIGN_CSS = {
+    start: "flex-start",
+    center: "center",
+    end: "flex-end",
+    "space-between": "space-between",
+};
+// Resolve a numeric spacing or radius value to a CSS token var or an inline px literal.
+const spaceValue = (value, lookups) => {
+    const varName = lookups.spaceVar.get(value);
+    return varName !== undefined ? `var(${varName})` : `${String(value)}px`;
+};
+const radiusValue = (value, lookups) => {
+    const varName = lookups.radiusVar.get(value);
+    return varName !== undefined ? `var(${varName})` : `${String(value)}px`;
+};
+// Build CSS declarations for a layout node. Returns undefined when nothing would be emitted.
+const layoutDeclarations = (layout, lookups) => {
+    const decls = ["display: flex;", `flex-direction: ${layout.mode};`];
+    if (layout.itemSpacing !== undefined && Number.isFinite(layout.itemSpacing)) {
+        decls.push(`gap: ${spaceValue(layout.itemSpacing, lookups)};`);
+    }
+    if (layout.padding !== undefined) {
+        const [top, right, bottom, left] = layout.padding;
+        const t = spaceValue(top, lookups);
+        const r = spaceValue(right, lookups);
+        const b = spaceValue(bottom, lookups);
+        const l = spaceValue(left, lookups);
+        decls.push(`padding: ${t} ${r} ${b} ${l};`);
+    }
+    if (layout.primaryAlign !== undefined) {
+        decls.push(`justify-content: ${ALIGN_CSS[layout.primaryAlign]};`);
+    }
+    if (layout.counterAlign !== undefined) {
+        decls.push(`align-items: ${ALIGN_CSS[layout.counterAlign]};`);
+    }
+    return decls;
+};
+// Build CSS declarations for sizing (fill = flex:1, hug = nothing [default], fixed = nothing here).
+const sizingDeclarations = (sizing) => {
+    const decls = [];
+    if (sizing.horizontal === "fill")
+        decls.push("width: 100%;");
+    if (sizing.vertical === "fill")
+        decls.push("flex: 1;");
+    return decls;
+};
+// Build CSS declarations for typography. Prefer token var when matched; inline otherwise.
+const typographyDeclarations = (typo, lookups) => {
+    const fontVarName = lookups.fontVar.get(typographyKey(typo));
+    if (fontVarName !== undefined) {
+        return [`font: var(${fontVarName});`];
+    }
+    // Inline fallback: validate each value before emitting.
+    const decls = [];
+    if (Number.isFinite(typo.fontWeight))
+        decls.push(`font-weight: ${String(typo.fontWeight)};`);
+    if (Number.isFinite(typo.fontSize))
+        decls.push(`font-size: ${String(typo.fontSize)}px;`);
+    if (typo.lineHeight !== undefined && Number.isFinite(typo.lineHeight)) {
+        decls.push(`line-height: ${String(typo.lineHeight)}px;`);
+    }
+    if (typo.fontFamily.length > 0)
+        decls.push(`font-family: ${safeFontFamily(typo.fontFamily)};`);
+    return decls;
+};
+// Walk the element tree, collect CSS rules, populate classMap.
+const collectStyles = (element, ctx) => {
+    const decls = [
+        ...(element.layout !== undefined ? layoutDeclarations(element.layout, ctx.lookups) : []),
+        ...(element.sizing !== undefined ? sizingDeclarations(element.sizing) : []),
+        ...(element.cornerRadius !== undefined && Number.isFinite(element.cornerRadius)
+            ? [`border-radius: ${radiusValue(element.cornerRadius, ctx.lookups)};`]
+            : []),
+        ...(element.typography !== undefined
+            ? typographyDeclarations(element.typography, ctx.lookups)
+            : []),
+    ];
+    if (decls.length > 0) {
+        const cls = nodeClass(element.id, ctx);
+        ctx.rules.push(`.${cls} {`);
+        for (const decl of decls)
+            ctx.rules.push(`  ${decl}`);
+        ctx.rules.push("}");
+    }
+    // renderElement discards the children of void-role elements (image/input), so collecting their
+    // styles would emit orphaned CSS rules referencing classes that appear on no rendered element.
+    // Skip the recursion for void roles to keep the stylesheet aligned with the emitted HTML.
+    if (!VOID_ROLES.has(element.role)) {
+        for (const child of element.children)
+            collectStyles(child, ctx);
+    }
+};
+// ─── HTML element rendering ───────────────────────────────────────────────────
+// Fix #6: additionally emit data-node-id so the element's IR origin is traceable in the HTML output.
+// True when this element renders any visible text — its own text or a descendant TEXT node's text.
+// A button/link is usually a container whose visible label lives in a child TEXT node, so checking
+// only the element's OWN `text` misses it (WCAG 4.1.2 / 2.5.3).
+const hasRenderedText = (element) => element.text !== undefined || element.children.some(hasRenderedText);
+function elementAttributes(element, classMap) {
+    const parts = [
+        `data-role="${escapeHtml(element.role)}"`,
+        `data-name="${escapeHtml(element.displayName)}"`,
+        `data-node-id="${escapeHtml(element.id)}"`,
+    ];
+    const cls = classMap.get(element.id);
+    if (cls !== undefined)
+        parts.push(`class="${escapeHtml(cls)}"`);
+    if (element.role === "link")
+        parts.push('href="#"');
+    if (element.role === "input")
+        parts.push(`aria-label="${escapeHtml(element.displayName)}"`);
+    if (element.role === "image")
+        parts.push(`alt="${escapeHtml(element.displayName)}"`);
+    // A button/link with NO visible text (icon-only) gets no accessible name from its content; fall
+    // back to the structural display name so the artifact stays screen-reader navigable (WCAG 4.1.2).
+    // But when it DOES render visible text (own or in a child TEXT node), adding aria-label would
+    // OVERRIDE that visible label for assistive tech (and break label-in-name, WCAG 2.5.3) — so skip it.
+    if ((element.role === "button" || element.role === "link") && !hasRenderedText(element)) {
+        parts.push(`aria-label="${escapeHtml(element.displayName)}"`);
+    }
+    return parts.join(" ");
+}
+function renderElement(element, depth, classMap) {
+    const tag = TAG_BY_ROLE[element.role];
+    const attributes = elementAttributes(element, classMap);
+    if (VOID_ROLES.has(element.role)) {
+        return [`${indent(depth)}<${tag} ${attributes} />`];
+    }
+    const lines = [`${indent(depth)}<${tag} ${attributes}>`];
+    if (element.text !== undefined)
+        lines.push(`${indent(depth + 1)}${escapeHtml(element.text)}`);
+    for (const child of element.children)
+        lines.push(...renderElement(child, depth + 1, classMap));
+    lines.push(`${indent(depth)}</${tag}>`);
+    return lines;
+}
+// Fix #7: hrefs use the sanitized name and are prefixed with './' so they resolve relative to the
+// screens/ directory and cannot be misinterpreted as URI schemes.
+function renderNav(navTargets, safeNames, depth) {
+    if (navTargets.length === 0)
+        return [];
+    const lines = [`${indent(depth)}<nav aria-label="Screen navigation">`];
+    for (const target of navTargets) {
+        const safeName = safeNames.get(target.toScreenId) ?? sanitizeScreenFileName(target.toScreenId);
+        const href = `./${escapeHtml(safeName)}.html`;
+        const trigger = escapeHtml(target.trigger);
+        const label = escapeHtml(target.toScreenName);
+        lines.push(`${indent(depth + 1)}<a href="${href}" data-trigger="${trigger}">${label}</a>`);
+    }
+    lines.push(`${indent(depth)}</nav>`);
+    return lines;
+}
+// Fix #7: screen file uses safe name; raw id is preserved in data-screen-id for traceability.
+function renderScreenHtml(screen, safeNames, lookups) {
+    // Collect per-node styles first so classMap is populated before HTML rendering.
+    const ctx = {
+        lookups,
+        classMap: new Map(),
+        usedClasses: new Map(),
+        rules: [],
+    };
+    collectStyles(screen.root, ctx);
+    const styleBlock = ctx.rules.length > 0
+        ? [
+            `${indent(2)}<style>`,
+            ...ctx.rules.map((line) => `${indent(2)}${line}`),
+            `${indent(2)}</style>`,
+        ]
+        : [];
+    const title = escapeHtml(screen.screenName);
+    const body = [
+        ...renderNav(screen.navTargets, safeNames, 3),
+        `${indent(3)}<main data-screen-id="${escapeHtml(screen.screenId)}">`,
+        ...renderElement(screen.root, 4, ctx.classMap),
+        `${indent(3)}</main>`,
+    ];
+    return [
+        "<!doctype html>",
+        '<html>',
+        `${indent(1)}<head>`,
+        `${indent(2)}<meta charset="utf-8" />`,
+        `${indent(2)}<title>${title}</title>`,
+        `${indent(2)}<link rel="stylesheet" href="../tokens.css" />`,
+        ...styleBlock,
+        `${indent(1)}</head>`,
+        `${indent(1)}<body>`,
+        ...body,
+        `${indent(1)}</body>`,
+        "</html>",
+        "",
+    ].join("\n");
+}
+// Fix #7: index links use safe names for the href path but display the human-readable screen name.
+function renderIndexHtml(screens, safeNames) {
+    const links = screens.map((screen) => {
+        const safeName = safeNames.get(screen.screenId) ?? sanitizeScreenFileName(screen.screenId);
+        return (`${indent(3)}<li><a href="screens/${escapeHtml(safeName)}.html">` +
+            `${escapeHtml(screen.screenName)}</a></li>`);
+    });
+    return [
+        "<!doctype html>",
+        '<html>',
+        `${indent(1)}<head>`,
+        `${indent(2)}<meta charset="utf-8" />`,
+        `${indent(2)}<title>Screens</title>`,
+        `${indent(2)}<link rel="stylesheet" href="tokens.css" />`,
+        `${indent(1)}</head>`,
+        `${indent(1)}<body>`,
+        `${indent(2)}<nav aria-label="All screens">`,
+        `${indent(3)}<ul>`,
+        ...links,
+        `${indent(3)}</ul>`,
+        `${indent(2)}</nav>`,
+        `${indent(1)}</body>`,
+        "</html>",
+        "",
+    ].join("\n");
+}
+// Fix #8: validate color before emit; drop invalid tokens rather than emitting them.
+const colorLine = (token, index) => isSafeColor(token.value) ? `${indent(1)}${colorVar(index)}: ${token.value};` : undefined;
+const spaceLine = (token, index) => Number.isFinite(token.value)
+    ? `${indent(1)}${spaceVar(index)}: ${String(token.value)}px;`
+    : undefined;
+const radiusLine = (token, index) => Number.isFinite(token.value)
+    ? `${indent(1)}${radiusVar(index)}: ${String(token.value)}px;`
+    : undefined;
+// Fix #8: fontFamily is sanitized via safeFontFamily (quoted + injection chars stripped).
+// Weight, size, lineHeight are validated as finite numbers before emit.
+const fontLine = (token, index) => {
+    if (!Number.isFinite(token.fontWeight) ||
+        !Number.isFinite(token.fontSize) ||
+        !Number.isFinite(token.lineHeight)) {
+        return undefined;
+    }
+    return (`${indent(1)}${fontVar(index)}: ${String(token.fontWeight)} ${String(token.fontSize)}px/` +
+        `${String(token.lineHeight)}px ${safeFontFamily(token.fontFamily)};`);
+};
+function renderTokensCss(tokens) {
+    const lines = [
+        ...tokens.colors.map(colorLine).filter((l) => l !== undefined),
+        ...tokens.spacing.map(spaceLine).filter((l) => l !== undefined),
+        ...tokens.radius.map(radiusLine).filter((l) => l !== undefined),
+        ...tokens.typography.map(fontLine).filter((l) => l !== undefined),
+    ];
+    return [
+        "/* Design tokens (deterministic, from the Figma Snapshot Screen-IR). */",
+        ":root {",
+        ...lines,
+        "}",
+        "",
+    ].join("\n");
+}
+function emitHtmlCss(plan) {
+    const safeNames = buildSafeNameIndex(plan.screens);
+    const lookups = buildTokenLookups(plan.tokens);
+    const files = [
+        { path: "index.html", contents: renderIndexHtml(plan.screens, safeNames) },
+        { path: "tokens.css", contents: renderTokensCss(plan.tokens) },
+        ...plan.screens.map((screen) => {
+            const safeName = safeNames.get(screen.screenId) ?? sanitizeScreenFileName(screen.screenId);
+            return {
+                path: `screens/${safeName}.html`,
+                contents: renderScreenHtml(screen, safeNames, lookups),
+            };
+        }),
+    ];
+    return { adapterName: ADAPTER_NAME, files };
+}
+/**
+ * The framework-agnostic HTML/CSS adapter — the only adapter shipped in the first slice. Renders the
+ * target-neutral plan to semantic HTML per screen, a `tokens.css` custom-property table, and an
+ * `index.html`. Pure and deterministic: a given plan yields a byte-identical artifact.
+ *
+ * Layout fidelity: nodes with auto-layout emit display:flex + direction + gap + padding + radius in a
+ * per-screen `<style>` block; TEXT nodes with matching typography tokens emit var(--font-N); fill-sized
+ * nodes emit flex:1 / width:100%. Absolute positioning, constraints, effects, and image content are
+ * not reproduced.
+ */
+export const htmlCssAdapter = {
+    name: ADAPTER_NAME,
+    emit: emitHtmlCss,
+};

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

@@ -0,0 +1,19 @@
+export { cleanScopedNodesToScreenIr } from "./cleanToScreenIr.js";
+export { parseDesignTokens } from "./tokens.js";
+export { parseScreenIr, deriveScreenTestBaseline, renderBaselineText, } from "./screenIrTestBaseline.js";
+export type { ScreenTestBaseline, StructuralTestCategory, StructuralTestItem, StructuralTestOutcome, } from "./screenIrTestBaseline.js";
+export { mergeVisionHints } from "./visionAugmentation.js";
+export type { VisionMergeResult } from "./visionAugmentation.js";
+export { deriveNavGraph, deriveNavFlows, deriveRoutingHints, deriveNavTestItemsByScreen, } from "./navGraph.js";
+export type { NavEdge, NavFlow, NavGraph, NavNode, RoutingHint, UnresolvedLink, } from "./navGraph.js";
+export { buildEmissionPlan } from "./emissionPlan.js";
+export type { CodeEmissionPlan, EmissionElement, EmissionInput, EmissionNavTarget, EmissionRole, ScreenEmission, } from "./emissionPlan.js";
+export { emitCode } from "./codeTargetAdapter.js";
+export type { CodeArtifact, CodeFile, CodeTargetAdapter } from "./codeTargetAdapter.js";
+export { applyNaming } from "./semanticNaming.js";
+export type { SemanticNamingProvider, SemanticNamingRequest } from "./semanticNaming.js";
+export { htmlCssAdapter } from "./htmlCssAdapter.js";
+export { deriveA11yTestItemsByScreen, relativeLuminance, contrastRatio, meetsContrastAa, } from "./a11yBaseline.js";
+export type { FigmaSourceNode } from "./sourceNode.js";
+export type { AlignItems, BoundingBox, ColorToken, DesignTokens, ImageFillRef, InteractionHint, InterScreenLink, IrLayout, IrNode, IrSizing, IrTypography, LayoutMode, LayoutSizing, RadiusToken, ReductionReport, ScreenIr, ScreenIrResult, SpacingToken, TypographyToken, } from "./irTypes.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAGlE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAIhD,OAAO,EACL,aAAa,EACb,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAKjE,OAAO,EACL,cAAc,EACd,cAAc,EACd,kBAAkB,EAClB,0BAA0B,GAC3B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,OAAO,EACP,OAAO,EACP,QAAQ,EACR,OAAO,EACP,WAAW,EACX,cAAc,GACf,MAAM,eAAe,CAAC;AAMvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,cAAc,GACf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,YAAY,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAExF,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,YAAY,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEzF,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,EACL,2BAA2B,EAC3B,iBAAiB,EACjB,aAAa,EACb,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,YAAY,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,eAAe,EACf,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,WAAW,EACX,eAAe,EACf,QAAQ,EACR,cAAc,EACd,YAAY,EACZ,eAAe,GAChB,MAAM,cAAc,CAAC"}

package/dist/domain/figma/index.js

@@ -0,0 +1,31 @@
+// Public barrel for the Quality Intelligence Figma Screen-IR sub-namespace (Epic #750, Issue #752).
+//
+// Pure-domain cleaner: raw scoped Figma node tree → lean per-screen IR + deduped design tokens +
+// raw inter-screen links + reduction report. No IO, no network, no model. Downstream stages import
+// these types: #753 (snapshot evidence), #754 (QI source), #811 (nav graph, from `links`), #812
+// (a11y), #755 (codegen, from `tokens`).
+export { cleanScopedNodesToScreenIr } from "./cleanToScreenIr.js";
+// Tolerant re-hydration of the persisted, opaque design-tokens artifact (#752) for design-to-code
+// (#755), which reads the STORED snapshot. Total + defensive; same shape as `extractDesignTokens`.
+export { parseDesignTokens } from "./tokens.js";
+// Structural test-baseline derivation + the defensive Screen-IR parser for the snapshot's opaque
+// `irJson` (Issue #754). Deterministic, model-free: same IR → byte-identical baseline.
+export { parseScreenIr, deriveScreenTestBaseline, renderBaselineText, } from "./screenIrTestBaseline.js";
+// Vision merge that structurally enforces "vision augments, never overrides the IR" (Issue #754).
+export { mergeVisionHints } from "./visionAugmentation.js";
+// Deterministic navigation/flow graph + routing hints + per-screen nav test items (Issue #811).
+// Pure, model-free: derived from the IR's inter-screen links; composes into the QI run additively
+// through `deriveScreenTestBaseline`'s `extraItems` seam.
+export { deriveNavGraph, deriveNavFlows, deriveRoutingHints, deriveNavTestItemsByScreen, } from "./navGraph.js";
+// Deterministic design-to-code emission: target-neutral plan + pluggable CodeTargetAdapter seam +
+// the framework-agnostic HTML/CSS adapter + the model-only-for-naming port (Issue #755). Pure,
+// model-free: the structural emission is fully deterministic; the naming port only renames elements
+// and never changes structure. Consumes design tokens (#752) and routing hints (#811).
+export { buildEmissionPlan } from "./emissionPlan.js";
+export { emitCode } from "./codeTargetAdapter.js";
+export { applyNaming } from "./semanticNaming.js";
+export { htmlCssAdapter } from "./htmlCssAdapter.js";
+// Deterministic accessibility baseline + WCAG contrast math (Issue #812). Pure, model-free: derived
+// from the Screen-IR's colour/box fields; composes into the QI run additively through
+// `deriveScreenTestBaseline`'s `extraItems` seam, ALONGSIDE the navigation items above.
+export { deriveA11yTestItemsByScreen, relativeLuminance, contrastRatio, meetsContrastAa, } from "./a11yBaseline.js";

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

@@ -0,0 +1,156 @@
+/** A best-effort structural/role hint for a kept node. Never load-bearing downstream. */
+export type InteractionHint = "button" | "input" | "link" | "text" | "image" | "container";
+export interface BoundingBox {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A reference to an image fill on a node (the imageRef the provider assigns to the fill). */
+export interface ImageFillRef {
+    readonly imageRef: string;
+}
+/** Auto-layout direction for a flex container. */
+export type LayoutMode = "row" | "column";
+/** Simplified alignment shorthand for a flex axis. */
+export type AlignItems = "start" | "center" | "end" | "space-between";
+/**
+ * Auto-layout properties for a FRAME/COMPONENT/INSTANCE that has `layoutMode` set. Optional and
+ * additive: absent when the node has no auto-layout. NEVER folded into the snapshot integrity hash
+ * (#753/#735) — it is codegen metadata, not structural drift identity.
+ */
+export interface IrLayout {
+    /** Flex direction derived from Figma `layoutMode` (HORIZONTAL → row, VERTICAL → column). */
+    readonly mode: LayoutMode;
+    /** Gap between children, from `itemSpacing`. */
+    readonly itemSpacing?: number;
+    /** Padding: [top, right, bottom, left]. Absent when all four are zero/absent. */
+    readonly padding?: readonly [number, number, number, number];
+    /** Primary-axis alignment (Figma `primaryAxisAlignItems`). */
+    readonly primaryAlign?: AlignItems;
+    /** Cross-axis alignment (Figma `counterAxisAlignItems`). */
+    readonly counterAlign?: AlignItems;
+}
+/** Whether a dimension is fixed, fills available space, or hugs content. */
+export type LayoutSizing = "fixed" | "hug" | "fill";
+/**
+ * Per-axis sizing mode (Figma `layoutSizingHorizontal` / `layoutSizingVertical`). Optional and
+ * additive; absent when the node has no auto-layout parent or when sizing is not explicitly set.
+ * Hash-neutral like {@link IrLayout}.
+ */
+export interface IrSizing {
+    readonly horizontal?: LayoutSizing;
+    readonly vertical?: LayoutSizing;
+}
+/**
+ * Per-TEXT-node typography properties, only present on TEXT nodes. Matches what `tokens.ts`
+ * already extracts globally (fontFamily, fontSize, fontWeight, lineHeight). Optional and additive;
+ * absent for non-TEXT nodes or when the `style` block is missing. Hash-neutral like
+ * {@link IrLayout}.
+ */
+export interface IrTypography {
+    readonly fontFamily: string;
+    readonly fontSize: number;
+    readonly fontWeight: number;
+    readonly lineHeight?: number;
+}
+/** A kept node in a screen's normalized structural tree. */
+export interface IrNode {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    readonly interactionHint: InteractionHint;
+    readonly text?: string;
+    readonly boundingBox?: BoundingBox;
+    /**
+     * The node's solid text-fill colour as normalized `#RRGGBB[AA]`, for a TEXT node (Issue #812).
+     * Optional and additive: absent when the node carries no solid text fill. NEVER folded into the
+     * snapshot integrity hash (#753/#735) — it is a11y-derivation metadata, not structural identity.
+     */
+    readonly textColor?: string;
+    /**
+     * The node's solid background-fill colour as normalized `#RRGGBB[AA]` (Issue #812). Used as the
+     * nearest-ancestor background when computing deterministic text-vs-background contrast. Optional,
+     * additive, and hash-neutral like {@link IrNode.textColor}.
+     */
+    readonly backgroundColor?: string;
+    /**
+     * Auto-layout properties (direction, gap, padding, alignment). Optional and additive: absent when
+     * the node has no auto-layout. Hash-neutral — codegen metadata, not structural drift identity.
+     */
+    readonly layout?: IrLayout;
+    /**
+     * Per-axis sizing mode. Optional and additive: absent when no sizing context exists.
+     * Hash-neutral like {@link IrNode.layout}.
+     */
+    readonly sizing?: IrSizing;
+    /**
+     * Corner radius in pixels. Optional and additive: absent when zero or absent from source.
+     * Hash-neutral like {@link IrNode.layout}.
+     */
+    readonly cornerRadius?: number;
+    /**
+     * Per-TEXT typography (fontFamily, fontSize, fontWeight, optional lineHeight). Optional and
+     * additive: absent for non-TEXT nodes or when the style block is missing. Hash-neutral like
+     * {@link IrNode.layout}.
+     */
+    readonly typography?: IrTypography;
+    readonly imageFills: readonly ImageFillRef[];
+    readonly children: readonly IrNode[];
+}
+export interface ScreenIr {
+    readonly id: string;
+    readonly name: string;
+    readonly root: IrNode;
+}
+export interface ColorToken {
+    readonly id: string;
+    readonly kind: "color";
+    readonly value: string;
+}
+export interface TypographyToken {
+    readonly id: string;
+    readonly kind: "typography";
+    readonly fontFamily: string;
+    readonly fontSize: number;
+    readonly fontWeight: number;
+    readonly lineHeight: number;
+}
+export interface SpacingToken {
+    readonly id: string;
+    readonly kind: "spacing";
+    readonly value: number;
+}
+export interface RadiusToken {
+    readonly id: string;
+    readonly kind: "radius";
+    readonly value: number;
+}
+/** Deduped, stable-ordered design tokens — emitted as part of and alongside the IR (for #755). */
+export interface DesignTokens {
+    readonly colors: readonly ColorToken[];
+    readonly typography: readonly TypographyToken[];
+    readonly spacing: readonly SpacingToken[];
+    readonly radius: readonly RadiusToken[];
+}
+/** A raw inter-screen transition. The flow graph is derived downstream (#811); we carry the link. */
+export interface InterScreenLink {
+    readonly sourceNodeId: string;
+    readonly trigger: string;
+    readonly targetNodeId: string;
+}
+/** How much of the raw subtree was dropped. `removedRatio` is rounded deterministically. */
+export interface ReductionReport {
+    readonly inputNodeCount: number;
+    readonly keptNodeCount: number;
+    readonly removedNodeCount: number;
+    readonly removedRatio: number;
+}
+/** The full per-board result of cleaning a scoped Figma node subtree. */
+export interface ScreenIrResult {
+    readonly screens: readonly ScreenIr[];
+    readonly tokens: DesignTokens;
+    readonly links: readonly InterScreenLink[];
+    readonly reduction: ReductionReport;
+}
+//# sourceMappingURL=irTypes.d.ts.map