@oscharko-dev/keiko-quality-intelligence 0.2.0

package/dist/domain/coverageRelevance.js

@@ -0,0 +1,155 @@
+// Quality Intelligence coverage relevance (Epic #270, Issue #272).
+//
+// Builds a deterministic `QualityIntelligenceCoverageMap` linking each
+// evidence atom to the candidates derived from it, scoring each mapping
+// with a simple structural confidence in [0, 1]. NO model judges — model-
+// based coverage scoring lives in #279.
+//
+// Structurally inspired by
+// Test Intelligence reference (TI) packages/core-engine/src/coverage-relevance.ts
+// (`isCoverageRelevantElementLike`, `normalizeCoverageText`) — but the TI
+// reference scores UI element coverage; our Keiko port scores atom-to-
+// candidate provenance coverage.
+import { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+// ─── Coverage classification ────────────────────────────────────────────────────
+/** Thresholds for atom coverage classification. */
+export const COVERAGE_THRESHOLD_COVERED = 0.7;
+export const COVERAGE_THRESHOLD_WEAKLY_COVERED = 0.3;
+/**
+ * Classify a single atom given its coverage-map mapping (undefined when the atom has
+ * no mapping entry — i.e. no candidate cited it at all).
+ */
+export function classifyAtomCoverage(atom, mapping) {
+    if (mapping === undefined || mapping.confidence < COVERAGE_THRESHOLD_WEAKLY_COVERED) {
+        return {
+            atomId: atom.id,
+            status: "uncovered",
+            confidence: mapping?.confidence ?? 0,
+            coveringCandidateIds: Object.freeze([]),
+        };
+    }
+    const status = mapping.confidence >= COVERAGE_THRESHOLD_COVERED ? "covered" : "weakly-covered";
+    return {
+        atomId: atom.id,
+        status,
+        confidence: mapping.confidence,
+        coveringCandidateIds: mapping.candidateIds,
+    };
+}
+/**
+ * Classify every atom in `atoms` against the supplied coverage map. Atoms with no
+ * mapping are classified as "uncovered". The result is sorted by atomId ascending.
+ */
+export function buildAtomCoverageStatuses(atoms, coverageMap) {
+    const byAtomId = new Map();
+    for (const mapping of coverageMap.mappings) {
+        byAtomId.set(String(mapping.atomId), mapping);
+    }
+    const statuses = atoms.map((atom) => classifyAtomCoverage(atom, byAtomId.get(String(atom.id))));
+    statuses.sort((a, b) => String(a.atomId) < String(b.atomId) ? -1 : String(a.atomId) > String(b.atomId) ? 1 : 0);
+    return Object.freeze(statuses);
+}
+/**
+ * Returns the percentage of atoms classified as "covered" out of all atoms. Returns
+ * 0 when the array is empty (deterministic, no division by zero).
+ */
+export function runCoveragePercentage(statuses) {
+    if (statuses.length === 0)
+        return 0;
+    const covered = statuses.filter((s) => s.status === "covered").length;
+    return (covered / statuses.length) * 100;
+}
+const compareString = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+/**
+ * A citing test counts as a *focused* cover of an atom when it derives from at most this many
+ * atoms — i.e. the test is reasonably specific to the requirement rather than a sprawling
+ * integration test that incidentally touches it. An atom whose only covering tests are all
+ * broader than this is classified "weakly-covered" (covered only incidentally).
+ *
+ * Conservative for regulated use: a dedicated test (focus 1) always yields "covered"; coverage
+ * is NEVER diluted by the total run size (see the regression test for the historical bug where
+ * `citedCount / candidates.length` reported a perfectly-covered run as 0%).
+ */
+export const FOCUS_COVERED_MAX = 3;
+const clamp01 = (value, max) => Math.max(0, Math.min(max, value));
+/**
+ * Deterministic, run-size-INDEPENDENT structural confidence in [0, 1] that an atom is covered.
+ *
+ * Inputs are atom-local: `citerCount` is the number of candidates that DIRECTLY derive from the
+ * atom, and `bestFocus` is the smallest `derivedFromAtomIds` length among those citers (1 = a test
+ * dedicated to this atom alone). Confidence is monotonic non-decreasing in `citerCount` so more
+ * tracing tests never lowers confidence.
+ *
+ *   - no citers              -> 0           (uncovered)
+ *   - >=1 focused citer      -> [0.7, 1.0]  (covered; threshold COVERAGE_THRESHOLD_COVERED)
+ *   - only broad citers      -> [0.3, 0.7)  (weakly-covered; incidental coverage only)
+ */
+export const coverageConfidence = (citerCount, bestFocus) => {
+    if (citerCount <= 0)
+        return 0;
+    const focused = Math.max(1, bestFocus) <= FOCUS_COVERED_MAX;
+    const saturation = 1 - 1 / (1 + citerCount); // 0.5, 0.667, 0.75, ... (in [0.5, 1))
+    return focused
+        ? clamp01(COVERAGE_THRESHOLD_COVERED + 0.3 * saturation, 1) // 0.85, 0.90, 0.925, ...
+        : clamp01(COVERAGE_THRESHOLD_WEAKLY_COVERED + 0.4 * saturation, 0.699); // 0.5, 0.567, ...
+};
+const deriveCoverageMapIdString = (runId, atomHashes, candidateIds) => {
+    const payload = [
+        "v1",
+        String(runId),
+        [...atomHashes].sort().join(""),
+        [...candidateIds].sort().join(""),
+    ].join("");
+    return `qi-coverage-${sha256Hex(payload).slice(0, 32)}`;
+};
+/**
+ * Build a coverage map for the supplied run. The returned map is validated
+ * against `assertCoverageMapInvariant` before being returned — callers can
+ * trust every confidence value lies in [0, 1] and every mapping cites at
+ * least one candidate.
+ *
+ * Atoms whose structural score is 0 (no candidate cites them and no step
+ * mentions them) are omitted from the returned mappings — including a zero-
+ * confidence mapping would violate the contract invariant (every mapping
+ * must cite at least one candidate).
+ */
+export const buildCoverageMap = (input) => {
+    const { runId, atoms, candidates } = input;
+    const sortedAtoms = [...atoms].sort((left, right) => compareString(left.canonicalHashSha256Hex, right.canonicalHashSha256Hex));
+    const mappings = [];
+    for (const atom of sortedAtoms) {
+        const candidateIds = [];
+        // Track the most-focused citing test (smallest derivedFromAtomIds) so an atom covered only by
+        // sprawling tests is classified weakly-covered, while a dedicated test yields "covered". The
+        // confidence is atom-local — it does NOT depend on how many candidates the run produced.
+        let bestFocus = Number.POSITIVE_INFINITY;
+        for (const candidate of candidates) {
+            if (candidate.derivedFromAtomIds.includes(atom.id)) {
+                candidateIds.push(candidate.id);
+                bestFocus = Math.min(bestFocus, candidate.derivedFromAtomIds.length);
+            }
+        }
+        if (candidateIds.length === 0) {
+            continue;
+        }
+        const confidence = coverageConfidence(candidateIds.length, bestFocus);
+        if (confidence <= 0) {
+            continue;
+        }
+        mappings.push(Object.freeze({
+            atomId: atom.id,
+            candidateIds: Object.freeze([...candidateIds].sort(compareString)),
+            coverageKind: "derived",
+            confidence,
+        }));
+    }
+    const idString = deriveCoverageMapIdString(runId, sortedAtoms.map((atom) => atom.canonicalHashSha256Hex), candidates.map((candidate) => candidate.id));
+    const map = Object.freeze({
+        id: QualityIntelligence.asQualityIntelligenceCoverageMapId(idString),
+        runId,
+        mappings: Object.freeze(mappings),
+    });
+    QualityIntelligence.assertCoverageMapInvariant(map);
+    return map;
+};

package/dist/domain/deduplication.d.ts

@@ -0,0 +1,17 @@
+import type { QualityIntelligence } from "@oscharko-dev/keiko-contracts";
+/**
+ * Compute the canonical equivalence signature for a candidate. Exported so
+ * callers (validators, audit-summary builders) can inspect what makes two
+ * candidates collide without re-implementing the rule.
+ *
+ * @returns Lower-case hex sha256 of the canonical projection.
+ */
+export declare const computeCandidateEquivalenceSignature: (candidate: QualityIntelligence.QualityIntelligenceTestCaseCandidate) => string;
+/**
+ * Returns the deduplicated subset of `candidates`. Order is the original
+ * input order with duplicates removed (the lexicographically-smallest `id`
+ * within each equivalence class is the survivor). Empty input returns the
+ * empty array.
+ */
+export declare const deduplicateCandidates: (candidates: readonly QualityIntelligence.QualityIntelligenceTestCaseCandidate[]) => readonly QualityIntelligence.QualityIntelligenceTestCaseCandidate[];
+//# sourceMappingURL=deduplication.d.ts.map

package/dist/domain/deduplication.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deduplication.d.ts","sourceRoot":"","sources":["../../src/domain/deduplication.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAgCzE;;;;;;GAMG;AACH,eAAO,MAAM,oCAAoC,GAC/C,WAAW,mBAAmB,CAAC,oCAAoC,KAClE,MAWF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,YAAY,SAAS,mBAAmB,CAAC,oCAAoC,EAAE,KAC9E,SAAS,mBAAmB,CAAC,oCAAoC,EAkCnE,CAAC"}

package/dist/domain/deduplication.js

@@ -0,0 +1,95 @@
+// Quality Intelligence deduplication (Epic #270, Issue #272).
+//
+// Given a list of `QualityIntelligenceTestCaseCandidate` records, returns the
+// deduplicated subset using deterministic equivalence: two candidates are
+// considered equivalent iff their canonical equivalence signature collides.
+// The signature is computed from
+//   * the NFKC-normalised + lower-cased + whitespace-collapsed title
+//   * the canonicalised precondition sequence (each entry normalised the same way)
+//   * the canonicalised step sequence (each step normalised the same way)
+//   * the canonicalised expected-result sequence
+//   * the priority and risk-class fields
+//
+// NO embeddings, NO model judges — model-assisted dedup lives in #279.
+//
+// When two candidates are equivalent we keep the one with the lexicographic-
+// ally smallest `id` so the function is order-independent.
+//
+// Structurally inspired by
+// Test Intelligence reference (TI) packages/core-engine/src/test-case-dedupe.ts
+// (`detectTestCaseDuplicatesExtended`), but stripped of the embedding cosine
+// path that issue #279 owns; the deterministic canonical-signature path is
+// what we port here.
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+import { normaliseCandidateText } from "./assertions.js";
+const collapseWhitespace = (value) => value.replace(/\s+/gu, " ").trim();
+// Use normaliseCandidateText (NFKC + bidi/zero-width strip + trim) so that two candidates
+// differing only by injected bidi or zero-width spoofing chars produce the same signature.
+const canonicaliseLine = (value) => collapseWhitespace(normaliseCandidateText(value).toLowerCase());
+const canonicaliseSequence = (values) => {
+    const out = [];
+    for (const value of values) {
+        const canonical = canonicaliseLine(value);
+        if (canonical.length === 0) {
+            continue;
+        }
+        out.push(canonical);
+    }
+    return out;
+};
+const compareString = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+const compareCandidateById = (left, right) => compareString(String(left.id), String(right.id));
+/**
+ * Compute the canonical equivalence signature for a candidate. Exported so
+ * callers (validators, audit-summary builders) can inspect what makes two
+ * candidates collide without re-implementing the rule.
+ *
+ * @returns Lower-case hex sha256 of the canonical projection.
+ */
+export const computeCandidateEquivalenceSignature = (candidate) => {
+    const projection = JSON.stringify({
+        v: "1",
+        title: canonicaliseLine(candidate.title),
+        preconditions: canonicaliseSequence(candidate.preconditions),
+        steps: canonicaliseSequence(candidate.steps),
+        expectedResults: canonicaliseSequence(candidate.expectedResults),
+        priority: candidate.priority,
+        riskClass: candidate.riskClass,
+    });
+    return sha256Hex(projection);
+};
+/**
+ * Returns the deduplicated subset of `candidates`. Order is the original
+ * input order with duplicates removed (the lexicographically-smallest `id`
+ * within each equivalence class is the survivor). Empty input returns the
+ * empty array.
+ */
+export const deduplicateCandidates = (candidates) => {
+    if (candidates.length === 0) {
+        return Object.freeze([]);
+    }
+    const survivorBySignature = new Map();
+    for (const candidate of candidates) {
+        const signature = computeCandidateEquivalenceSignature(candidate);
+        const incumbent = survivorBySignature.get(signature);
+        if (incumbent === undefined) {
+            survivorBySignature.set(signature, candidate);
+            continue;
+        }
+        if (compareCandidateById(candidate, incumbent) < 0) {
+            survivorBySignature.set(signature, candidate);
+        }
+    }
+    const survivorIds = new Set();
+    for (const survivor of survivorBySignature.values()) {
+        survivorIds.add(String(survivor.id));
+    }
+    const out = [];
+    for (const candidate of candidates) {
+        if (survivorIds.has(String(candidate.id))) {
+            out.push(candidate);
+            survivorIds.delete(String(candidate.id));
+        }
+    }
+    return Object.freeze(out);
+};

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

@@ -0,0 +1,17 @@
+import { type Rgb } from "./color.js";
+import type { ScreenIr } from "./irTypes.js";
+import type { StructuralTestItem } from "./screenIrTestBaseline.js";
+/** WCAG relative luminance of an sRGB colour: 0 for black, 1 for white. */
+export declare const relativeLuminance: (rgb: Rgb) => number;
+/** WCAG contrast ratio (L_lighter + 0.05) / (L_darker + 0.05); symmetric, 1..21. */
+export declare const contrastRatio: (a: Rgb, b: Rgb) => number;
+/** Whether a ratio meets the WCAG AA threshold (3.0 for large text, else the stricter 4.5). */
+export declare const meetsContrastAa: (ratio: number, isLargeText: boolean) => boolean;
+/**
+ * Derive the deterministic a11y test items per screen, keyed by the screen they are attributed to.
+ * Reuses #754's StructuralTestItem shape so the items compose additively through
+ * `deriveScreenTestBaseline(screen, extraItems)`, ALONGSIDE #811's navigation items. Model-free and
+ * reproducible: the same IR yields a byte-identical map.
+ */
+export declare function deriveA11yTestItemsByScreen(screens: readonly ScreenIr[]): ReadonlyMap<string, readonly StructuralTestItem[]>;
+//# sourceMappingURL=a11yBaseline.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"a11yBaseline.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/a11yBaseline.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAgB,KAAK,GAAG,EAAa,MAAM,YAAY,CAAC;AAC/D,OAAO,KAAK,EAAuB,QAAQ,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AA0BpE,2EAA2E;AAC3E,eAAO,MAAM,iBAAiB,GAAI,KAAK,GAAG,KAAG,MAGX,CAAC;AAEnC,oFAAoF;AACpF,eAAO,MAAM,aAAa,GAAI,GAAG,GAAG,EAAE,GAAG,GAAG,KAAG,MAM9C,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,EAAE,aAAa,OAAO,KAAG,OACvB,CAAC;AA+PhD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,SAAS,QAAQ,EAAE,GAC3B,WAAW,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC,CAUpD"}

package/dist/domain/figma/a11yBaseline.js

@@ -0,0 +1,218 @@
+// Deterministic accessibility (a11y) baseline from a Screen-IR (Epic #750, Issue #812).
+//
+// Pure domain: a Screen-IR (#752) — per-screen kept-node trees plus the additive `textColor` /
+// `backgroundColor` / `boundingBox` fields — is reduced, with NO model and NO IO, to per-screen a11y
+// test items reusing #754's `StructuralTestItem` shape so they compose into the figma-snapshot QI run
+// additively through `deriveScreenTestBaseline`'s `extraItems` seam (ALONGSIDE #811's nav items):
+//   • accessible-name presence — an interactive node (button/input/link) with neither visible text
+//     nor a descriptive name → a "needs an accessible name" item;
+//   • colour-contrast — every TEXT node with a resolvable text colour and a nearest-ancestor
+//     background colour → an exact WCAG relative-luminance contrast item (meets / below AA), with
+//     the stricter AA-normal 4.5 threshold used when "large text" cannot be determined from the IR;
+//     an uncomputable pairing (missing/malformed colour) → a coverage-notice item, never a crash;
+//   • focus / reading order — ≥ 2 interactive nodes with bounding boxes → one reading-order item
+//     (top-to-bottom, then left-to-right);
+//   • minimum target size — an interactive node whose bounding box is smaller than 24×24 (WCAG 2.2
+//     AA 2.5.8) → a target-size item;
+//   • image-fill alt-text — a node carrying image fills → an alt-text expectation item.
+//
+// Generic by construction: every rule reads only structural shape (interactionHint, text, colour,
+// box) — no screen name, layout, mask style, or copy is special-cased. Deterministic: items are
+// emitted in a stable depth-first / stable-sorted order and carry no timestamp, so the same IR yields
+// a byte-identical result. The baseline is model-free and stands alone; vision augmentation (#810) is
+// layered separately and never replaces these items.
+import { parseHexRgba } from "./color.js";
+const MIN_TARGET_SIZE = 24;
+const AA_NORMAL = 4.5;
+const AA_LARGE = 3.0;
+const LARGE_TEXT_MIN_PX = 24;
+const LARGE_BOLD_TEXT_MIN_PX = 18.6667;
+const LARGE_TEXT_MIN_WEIGHT = 700;
+// Generous per-screen item cap so a pathologically dense real screen (thousands of TEXT nodes →
+// thousands of contrast checks) cannot make the a11y baseline unbounded in memory/output. Small
+// fixtures stay far below it, so it is invisible except on huge boards. Deterministic: the first
+// `MAX_A11Y_ITEMS_PER_SCREEN` items (stable order) are kept and a single coverage notice records the
+// remainder, so the same IR yields the same truncated set every run.
+const MAX_A11Y_ITEMS_PER_SCREEN = 800;
+const INTERACTIVE = new Set(["button", "input", "link"]);
+// ─── WCAG relative luminance + contrast ratio (exact, model-free) ─────────────────
+// sRGB → linear-light channel (WCAG 2.x): c/12.92 below the knee, else ((c+0.055)/1.055)^2.4.
+const linearizeChannel = (channel255) => {
+    const c = channel255 / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+/** WCAG relative luminance of an sRGB colour: 0 for black, 1 for white. */
+export const relativeLuminance = (rgb) => 0.2126 * linearizeChannel(rgb.r) +
+    0.7152 * linearizeChannel(rgb.g) +
+    0.0722 * linearizeChannel(rgb.b);
+/** WCAG contrast ratio (L_lighter + 0.05) / (L_darker + 0.05); symmetric, 1..21. */
+export const contrastRatio = (a, b) => {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+};
+/** Whether a ratio meets the WCAG AA threshold (3.0 for large text, else the stricter 4.5). */
+export const meetsContrastAa = (ratio, isLargeText) => ratio >= (isLargeText ? AA_LARGE : AA_NORMAL);
+function a11yItemId(prefix, key) {
+    // Deterministic non-cryptographic id (FNV-1a) — stable across runs, no IO. Mirrors #754/#811.
+    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")}`;
+}
+const a11yItem = (ctx, nodeId, kind, title, outcome) => ({
+    id: a11yItemId("fa11y", `${ctx.screenId}|${kind}|${nodeId}`),
+    category: "a11y",
+    ...(outcome !== undefined ? { outcome } : {}),
+    screenId: ctx.screenId,
+    screenName: ctx.screenName,
+    sourceNodeId: nodeId,
+    title,
+});
+const noticeItem = (ctx, nodeId, kind, title) => ({
+    id: a11yItemId("fa11ycov", `${ctx.screenId}|${kind}|${nodeId}`),
+    category: "coverage-notice",
+    screenId: ctx.screenId,
+    screenName: ctx.screenName,
+    sourceNodeId: nodeId,
+    title,
+});
+// ─── Per-rule derivation ───────────────────────────────────────────────────────────
+const nodeLabel = (node) => node.text !== undefined && node.text.length > 0 ? node.text : node.name;
+const GENERIC_LAYER_NAME = /^(?:frame|rectangle|group|button|instance|component|text|vector|ellipse|line|image|icon)(?:\s+\d+)?$/iu;
+// A node's name is descriptive only when it is neither an opaque Figma node id nor a generic default
+// layer name. This stays structural: it rejects provider-default vocabulary, not board-specific copy.
+const hasDescriptiveName = (node) => {
+    const trimmed = node.name.trim();
+    return (trimmed.length > 0 && !/^[0-9]+:[0-9]+$/u.test(trimmed) && !GENERIC_LAYER_NAME.test(trimmed));
+};
+const hasAccessibleName = (node) => (node.text !== undefined && node.text.trim().length > 0) || hasDescriptiveName(node);
+const isLargeText = (node) => {
+    const typography = node.typography;
+    if (typography === undefined)
+        return false;
+    if (typography.fontSize >= LARGE_TEXT_MIN_PX)
+        return true;
+    return (typography.fontSize >= LARGE_BOLD_TEXT_MIN_PX && typography.fontWeight >= LARGE_TEXT_MIN_WEIGHT);
+};
+const compositeChannel = (foreground, background, alpha) => Math.round(foreground * alpha + background * (1 - alpha));
+const compositeOver = (foreground, background) => {
+    if (foreground.a >= 1)
+        return { r: foreground.r, g: foreground.g, b: foreground.b };
+    return {
+        r: compositeChannel(foreground.r, background.r, foreground.a),
+        g: compositeChannel(foreground.g, background.g, foreground.a),
+        b: compositeChannel(foreground.b, background.b, foreground.a),
+    };
+};
+const resolveBackground = (backgroundColor, inheritedBackground) => {
+    if (backgroundColor === undefined)
+        return inheritedBackground;
+    const ownBackground = parseHexRgba(backgroundColor);
+    if (ownBackground === undefined)
+        return undefined;
+    if (inheritedBackground === undefined && ownBackground.a < 1)
+        return undefined;
+    return compositeOver(ownBackground, inheritedBackground ?? { r: 255, g: 255, b: 255 });
+};
+const contrastItem = (ctx, node, background) => {
+    const fg = node.textColor === undefined ? undefined : parseHexRgba(node.textColor);
+    const bg = background;
+    if (fg === undefined || bg === undefined) {
+        return noticeItem(ctx, node.id, "contrast", `Text "${nodeLabel(node)}" needs a verifiable colour contrast: text/background colour could not be resolved from the design tokens`);
+    }
+    const renderedFg = compositeOver(fg, bg);
+    const ratio = contrastRatio(renderedFg, bg);
+    const rounded = Math.round(ratio * 100) / 100;
+    const largeText = isLargeText(node);
+    const threshold = largeText ? AA_LARGE : AA_NORMAL;
+    const label = largeText ? "WCAG AA large text" : "WCAG AA";
+    const passes = meetsContrastAa(ratio, largeText);
+    const verdict = passes
+        ? `meets ${label} (${String(rounded)}:1 ≥ ${String(threshold)}:1)`
+        : `is below ${label} (${String(rounded)}:1 < ${String(threshold)}:1)`;
+    return a11yItem(ctx, node.id, "contrast", `Text "${nodeLabel(node)}" colour contrast ${verdict}`, passes ? "pass" : "fail");
+};
+const isTooSmall = (box) => box.width < MIN_TARGET_SIZE || box.height < MIN_TARGET_SIZE;
+const byReadingOrder = (a, b) => a.box.y !== b.box.y ? a.box.y - b.box.y : a.box.x - b.box.x;
+// Each rule returns its item (or undefined when the node is out of scope), keeping `visit` flat so
+// its cyclomatic complexity stays within budget. Rules read only structural shape — never copy.
+const nameRule = (ctx, node) => INTERACTIVE.has(node.interactionHint) && !hasAccessibleName(node)
+    ? a11yItem(ctx, node.id, "name", `Interactive "${node.name}" needs an accessible name`, "fail")
+    : undefined;
+const contrastRule = (ctx, node, background) => node.interactionHint === "text" && node.text !== undefined && node.text.trim().length > 0
+    ? contrastItem(ctx, node, background)
+    : undefined;
+const layoutCoverageRule = (ctx, node) => INTERACTIVE.has(node.interactionHint) && node.boundingBox === undefined
+    ? noticeItem(ctx, node.id, "bounds", `Control "${nodeLabel(node)}" needs verifiable layout bounds: target size and focus order could not be resolved from the Screen-IR`)
+    : undefined;
+const targetSizeRule = (ctx, node) => INTERACTIVE.has(node.interactionHint) &&
+    node.boundingBox !== undefined &&
+    isTooSmall(node.boundingBox)
+    ? a11yItem(ctx, node.id, "target", `Control "${nodeLabel(node)}" does not meet the 24×24 minimum target size`, "fail")
+    : undefined;
+const altTextRule = (ctx, node) => node.imageFills.length > 0
+    ? a11yItem(ctx, node.id, "alt", `Image "${node.name}" needs descriptive alt text verification`, "expectation")
+    : undefined;
+// Shared constant — see prune.ts for rationale. Must stay in sync with every other recursive walk.
+const MAX_TREE_DEPTH = 512;
+function visitAt(node, ctx, inheritedBackground, acc, depth) {
+    if (depth > MAX_TREE_DEPTH)
+        return;
+    const background = resolveBackground(node.backgroundColor, inheritedBackground);
+    for (const item of [
+        nameRule(ctx, node),
+        contrastRule(ctx, node, background),
+        layoutCoverageRule(ctx, node),
+        targetSizeRule(ctx, node),
+        altTextRule(ctx, node),
+    ]) {
+        if (item !== undefined)
+            acc.items.push(item);
+    }
+    if (INTERACTIVE.has(node.interactionHint) && node.boundingBox !== undefined) {
+        acc.focusables.push({ nodeId: node.id, label: nodeLabel(node), box: node.boundingBox });
+    }
+    for (const child of node.children)
+        visitAt(child, ctx, background, acc, depth + 1);
+}
+function visit(node, ctx, inheritedBackground, acc) {
+    visitAt(node, ctx, inheritedBackground, acc, 0);
+}
+const focusOrderItem = (ctx, focusables) => {
+    const ordered = [...focusables].sort(byReadingOrder);
+    const sequence = ordered.map((f) => `"${f.label}"`).join(" → ");
+    return a11yItem(ctx, ordered[0]?.nodeId ?? "", "focus-order", `Focus order follows the visual reading order: ${sequence}`, "expectation");
+};
+/**
+ * Derive the deterministic a11y test items per screen, keyed by the screen they are attributed to.
+ * Reuses #754's StructuralTestItem shape so the items compose additively through
+ * `deriveScreenTestBaseline(screen, extraItems)`, ALONGSIDE #811's navigation items. Model-free and
+ * reproducible: the same IR yields a byte-identical map.
+ */
+export function deriveA11yTestItemsByScreen(screens) {
+    const byScreen = new Map();
+    for (const screen of screens) {
+        const ctx = { screenId: screen.id, screenName: screen.name };
+        const acc = { items: [], focusables: [] };
+        visit(screen.root, ctx, undefined, acc);
+        if (acc.focusables.length >= 2)
+            acc.items.push(focusOrderItem(ctx, acc.focusables));
+        byScreen.set(screen.id, capItems(ctx, acc.items));
+    }
+    return byScreen;
+}
+// Deterministically bound a screen's a11y items: keep the first MAX (stable order), and when more
+// were derived, append ONE coverage notice recording how many were omitted (never a silent cut).
+function capItems(ctx, items) {
+    if (items.length <= MAX_A11Y_ITEMS_PER_SCREEN)
+        return items;
+    const omitted = items.length - MAX_A11Y_ITEMS_PER_SCREEN;
+    const kept = items.slice(0, MAX_A11Y_ITEMS_PER_SCREEN);
+    kept.push(noticeItem(ctx, ctx.screenId, "a11y-cap", `Screen "${ctx.screenName}" has more accessibility checks than the per-screen baseline shows: ${String(omitted)} additional checks were omitted to keep the baseline bounded`));
+    return kept;
+}

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

@@ -0,0 +1,3 @@
+import type { ScreenIrResult } from "./irTypes.js";
+export declare const cleanScopedNodesToScreenIr: (rawRoot: unknown) => ScreenIrResult;
+//# sourceMappingURL=cleanToScreenIr.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cleanToScreenIr.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/cleanToScreenIr.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAA6B,cAAc,EAAE,MAAM,cAAc,CAAC;AA6B9E,eAAO,MAAM,0BAA0B,GAAI,SAAS,OAAO,KAAG,cA4B7D,CAAC"}

package/dist/domain/figma/cleanToScreenIr.js

@@ -0,0 +1,62 @@
+// Figma node tree → lean per-screen IR orchestrator (Epic #750, Issue #752).
+//
+// Pure, deterministic, no IO/network/model. Takes the raw scoped Figma `document` node tree
+// (the connector output of #751) and produces the Screen-IR result: per-screen kept-node trees,
+// deduped design tokens, raw inter-screen links, and a reduction report. Every emitted collection
+// is sorted by a stable structural key, and the result carries no timestamp, so the same input
+// yields a byte-identical IR. A malformed input (non-object) degrades to an empty result.
+import { asNode } from "./sourceNode.js";
+import { countSourceNodes, pruneNode } from "./prune.js";
+import { detectScreens } from "./screenDetect.js";
+import { countIrNodes, normalizeScreenRoot } from "./normalize.js";
+import { extractDesignTokens } from "./tokens.js";
+import { extractInterScreenLinks } from "./links.js";
+const RATIO_PRECISION = 6;
+const EMPTY_TOKENS = { colors: [], typography: [], spacing: [], radius: [] };
+const roundRatio = (removed, input) => {
+    if (input <= 0)
+        return 0;
+    const factor = 10 ** RATIO_PRECISION;
+    return Math.round((removed / input) * factor) / factor;
+};
+const buildReduction = (inputNodeCount, keptNodeCount) => {
+    const removedNodeCount = Math.max(0, inputNodeCount - keptNodeCount);
+    return {
+        inputNodeCount,
+        keptNodeCount,
+        removedNodeCount,
+        removedRatio: roundRatio(removedNodeCount, inputNodeCount),
+    };
+};
+const emptyResult = (inputNodeCount) => ({
+    screens: [],
+    tokens: EMPTY_TOKENS,
+    links: [],
+    reduction: buildReduction(inputNodeCount, 0),
+});
+export const cleanScopedNodesToScreenIr = (rawRoot) => {
+    const root = asNode(rawRoot);
+    if (root === undefined)
+        return emptyResult(0);
+    const inputNodeCount = countSourceNodes(root);
+    const pruned = pruneNode(root);
+    if (pruned === undefined)
+        return emptyResult(inputNodeCount);
+    const screenRoots = detectScreens(pruned);
+    const screens = screenRoots
+        .map((screenRoot) => {
+        const ir = normalizeScreenRoot(screenRoot);
+        return { id: ir.id, name: ir.name, root: ir };
+    })
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    // keptNodeCount counts only IR nodes under detected screens, so surviving scope containers
+    // (CANVAS/SECTION) that are not themselves screens count toward removal. removedRatio is therefore
+    // the fraction of raw input nodes not retained in any screen IR, not the fraction the pruner dropped.
+    const keptNodeCount = screens.reduce((sum, screen) => sum + countIrNodes(screen.root), 0);
+    return {
+        screens,
+        tokens: extractDesignTokens(screenRoots),
+        links: extractInterScreenLinks(root, screenRoots),
+        reduction: buildReduction(inputNodeCount, keptNodeCount),
+    };
+};

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

@@ -0,0 +1,30 @@
+import { type SemanticNamingProvider } from "./semanticNaming.js";
+import { type CodeEmissionPlan, type EmissionInput } from "./emissionPlan.js";
+/** A single proposed file in the reviewable code artifact. Path is artifact-relative, POSIX-style. */
+export interface CodeFile {
+    readonly path: string;
+    readonly contents: string;
+}
+/** The reviewable output of a code-emission pass: the producing adapter plus its ordered files. */
+export interface CodeArtifact {
+    readonly adapterName: string;
+    readonly files: readonly CodeFile[];
+}
+/**
+ * The pluggable code-target seam. An adapter is a pure function from the target-neutral plan to a
+ * concrete code artifact. `name` records which target produced an artifact. Additive: future targets
+ * implement this interface without changing the emitter.
+ */
+export interface CodeTargetAdapter {
+    readonly name: string;
+    readonly emit: (plan: CodeEmissionPlan) => CodeArtifact;
+}
+/**
+ * Emit reviewable code for a set of screens through the selected adapter. Builds the deterministic,
+ * target-neutral plan, applies the optional semantic-naming port (which may rename elements but never
+ * change structure), and renders through the adapter. With no naming provider the structural default
+ * names are used, so emission is fully deterministic and model-independent. The result is a proposal,
+ * not an applied change.
+ */
+export declare function emitCode(input: EmissionInput, adapter: CodeTargetAdapter, naming?: SemanticNamingProvider): CodeArtifact;
+//# sourceMappingURL=codeTargetAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codeTargetAdapter.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/codeTargetAdapter.ts"],"names":[],"mappings":"AAcA,OAAO,EAAe,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC/E,OAAO,EAAqB,KAAK,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEjG,sGAAsG;AACtG,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,mGAAmG;AACnG,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,YAAY,CAAC;CACzD;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,iBAAiB,EAC1B,MAAM,CAAC,EAAE,sBAAsB,GAC9B,YAAY,CAId"}

package/dist/domain/figma/codeTargetAdapter.js

@@ -0,0 +1,27 @@
+// The pluggable CodeTargetAdapter seam for design-to-code emission (Epic #750, Issue #755).
+//
+// All code emission goes through a single seam: the workflow builds a target-NEUTRAL emission plan
+// (emissionPlan.ts) from the Screen-IR + tokens + routing hints, optionally enriches element names
+// via the injected naming port (semanticNaming.ts), and hands the plan to a `CodeTargetAdapter` which
+// renders it to a concrete `CodeArtifact`. The first slice ships exactly one adapter (the
+// framework-agnostic HTML/CSS adapter). A future MUI / component-library adapter is purely additive:
+// it implements this same interface and is selected at the call site — the emitter, plan, and naming
+// port do not change. No framework is hard-coded into the emitter.
+//
+// The artifact is a REVIEWABLE proposal (an ordered list of files), never auto-applied: this module
+// has no filesystem, network, or model access — the model only reaches naming, through the injected
+// provider. Deterministic: a given input + adapter yields a byte-identical artifact.
+import { applyNaming } from "./semanticNaming.js";
+import { buildEmissionPlan } from "./emissionPlan.js";
+/**
+ * Emit reviewable code for a set of screens through the selected adapter. Builds the deterministic,
+ * target-neutral plan, applies the optional semantic-naming port (which may rename elements but never
+ * change structure), and renders through the adapter. With no naming provider the structural default
+ * names are used, so emission is fully deterministic and model-independent. The result is a proposal,
+ * not an applied change.
+ */
+export function emitCode(input, adapter, naming) {
+    const base = buildEmissionPlan(input);
+    const plan = naming !== undefined ? applyNaming(base, naming) : base;
+    return adapter.emit(plan);
+}