@oscharko-dev/keiko-quality-intelligence 0.2.0

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

@@ -0,0 +1,31 @@
+import { type FigmaSourceNode } from "./sourceNode.js";
+/**
+ * Whether a Figma paint contributes a visible colour. Figma omits `visible` when a paint is shown, so
+ * only an explicit `visible:false` hides it (mirrors {@link isHidden} for nodes). A paint-level
+ * `opacity <= 0` or a SOLID `color.a <= 0` is fully transparent and likewise contributes no visible colour.
+ * Used so neither the reported text/background colour (#812) nor an extracted colour token (#752) is
+ * ever taken from a paint that does not render.
+ */
+export declare const isVisiblePaint: (paint: Record<string, unknown>) => boolean;
+/** Project a Figma paint's `color` ({r,g,b,a} in 0..1) to normalized `#RRGGBB[AA]` (alpha < 1 only). */
+export declare const paintColorToHex: (paint: Record<string, unknown>) => string | undefined;
+/**
+ * The first VISIBLE SOLID paint's normalized hex from a node's paint array (`fills`/`strokes`), if
+ * any. Hidden (`visible:false`) and fully-transparent paints are skipped so the reported colour is
+ * one that actually renders; an empty/absent paint array yields `undefined` (resolved downstream as a
+ * coverage notice, never a fabricated colour).
+ */
+export declare const firstSolidPaintHex: (node: FigmaSourceNode, key: string) => string | undefined;
+/** Parsed sRGB channels in the 0..255 range. */
+export interface Rgb {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+}
+export interface Rgba extends Rgb {
+    /** Alpha in the 0..1 range. */
+    readonly a: number;
+}
+export declare const parseHexRgba: (hex: string) => Rgba | undefined;
+export declare const parseHexRgb: (hex: string) => Rgb | undefined;
+//# sourceMappingURL=color.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/color.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAkC,KAAK,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAOvF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,OAU/D,CAAC;AAEF,wGAAwG;AACxG,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,MAAM,GAAG,SAYzE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,eAAe,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,SAWhF,CAAC;AAEF,gDAAgD;AAChD,MAAM,WAAW,GAAG;IAClB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,IAAK,SAAQ,GAAG;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAID,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,IAAI,GAAG,SAOjD,CAAC;AAGF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,GAAG,GAAG,SAK/C,CAAC"}

package/dist/domain/figma/color.js

@@ -0,0 +1,99 @@
+// Deterministic colour helpers shared across token extraction (#752) and a11y contrast (#812).
+//
+// One canonical projection of a Figma SOLID paint to a normalized `#RRGGBB[AA]` hex string, plus the
+// inverse parse used by the WCAG contrast math. Pure and content-free: the same paint always yields
+// the same hex, and the same hex always parses to the same channels. No IO, no model.
+//
+// Empirical note (#838, verified content-free against real enterprise boards): a real Figma TEXT
+// node carries its colour as an INLINE SOLID paint in its own `fills` array for the overwhelming
+// majority of nodes (82–99% across the sampled boards). The earlier hypothesis that colour lives in
+// a `fillStyleId` / `styles.fill` style reference did NOT hold — fill-style-referenced text still
+// inlines the resolved SOLID paint, so `fills` is the single source of truth and no style-table
+// resolution is needed. The residual nodes carry an EMPTY `fills:[]` (a typography-only `styles.text`
+// reference, no own paint); those are genuinely unresolvable and correctly degrade to an a11y
+// coverage notice rather than a fabricated colour. The historical "0 textColor on real boards"
+// symptom was caused by the depth-fetch gap (#837), not by where the colour lives: the text-bearing
+// nodes simply never survived into the IR. The one real robustness gap here is paint VISIBILITY —
+// an explicitly hidden or fully-transparent paint must never become the reported colour.
+import { asNode, readNumber, readString } from "./sourceNode.js";
+const channel = (value) => Math.round(Math.min(1, Math.max(0, value)) * 255)
+    .toString(16)
+    .padStart(2, "0");
+/**
+ * Whether a Figma paint contributes a visible colour. Figma omits `visible` when a paint is shown, so
+ * only an explicit `visible:false` hides it (mirrors {@link isHidden} for nodes). A paint-level
+ * `opacity <= 0` or a SOLID `color.a <= 0` is fully transparent and likewise contributes no visible colour.
+ * Used so neither the reported text/background colour (#812) nor an extracted colour token (#752) is
+ * ever taken from a paint that does not render.
+ */
+export const isVisiblePaint = (paint) => {
+    if (paint.visible === false)
+        return false;
+    const opacity = readNumber(paint.opacity);
+    if (opacity !== undefined && opacity <= 0)
+        return false;
+    const color = asNode(paint.color);
+    if (color !== undefined) {
+        const alpha = readNumber(color.a);
+        if (alpha !== undefined && alpha <= 0)
+            return false;
+    }
+    return true;
+};
+/** Project a Figma paint's `color` ({r,g,b,a} in 0..1) to normalized `#RRGGBB[AA]` (alpha < 1 only). */
+export const paintColorToHex = (paint) => {
+    const color = asNode(paint.color);
+    if (color === undefined)
+        return undefined;
+    const r = readNumber(color.r);
+    const g = readNumber(color.g);
+    const b = readNumber(color.b);
+    if (r === undefined || g === undefined || b === undefined)
+        return undefined;
+    const colorAlpha = readNumber(color.a) ?? 1;
+    const paintOpacity = readNumber(paint.opacity) ?? 1;
+    const a = Math.min(1, Math.max(0, colorAlpha)) * Math.min(1, Math.max(0, paintOpacity));
+    const base = `#${channel(r)}${channel(g)}${channel(b)}`;
+    return a < 1 ? `${base}${channel(a)}` : base;
+};
+/**
+ * The first VISIBLE SOLID paint's normalized hex from a node's paint array (`fills`/`strokes`), if
+ * any. Hidden (`visible:false`) and fully-transparent paints are skipped so the reported colour is
+ * one that actually renders; an empty/absent paint array yields `undefined` (resolved downstream as a
+ * coverage notice, never a fabricated colour).
+ */
+export const firstSolidPaintHex = (node, key) => {
+    const paints = node[key];
+    if (!Array.isArray(paints))
+        return undefined;
+    for (const paint of paints) {
+        const record = asNode(paint);
+        if (record === undefined || readString(record.type) !== "SOLID")
+            continue;
+        if (!isVisiblePaint(record))
+            continue;
+        const hex = paintColorToHex(record);
+        if (hex !== undefined)
+            return hex;
+    }
+    return undefined;
+};
+// Parse `#RRGGBB[AA]` into rendered colour channels. Returns undefined for a malformed value so the
+// caller emits a coverage notice rather than crashing.
+export const parseHexRgba = (hex) => {
+    if (!/^#[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/u.test(hex))
+        return undefined;
+    const r = Number.parseInt(hex.slice(1, 3), 16);
+    const g = Number.parseInt(hex.slice(3, 5), 16);
+    const b = Number.parseInt(hex.slice(5, 7), 16);
+    const a = hex.length === 9 ? Number.parseInt(hex.slice(7, 9), 16) / 255 : 1;
+    return { r, g, b, a };
+};
+// Legacy RGB parser for callers that intentionally want the opaque leading colour.
+export const parseHexRgb = (hex) => {
+    const parsed = parseHexRgba(hex);
+    if (parsed === undefined)
+        return undefined;
+    const { r, g, b } = parsed;
+    return { r, g, b };
+};

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

@@ -0,0 +1,56 @@
+import type { DesignTokens, IrLayout, IrSizing, IrTypography, InteractionHint, ScreenIr } from "./irTypes.js";
+import type { RoutingHint } from "./navGraph.js";
+/** The target-neutral role of an element — mirrors the IR `interactionHint`; no framework tag. */
+export type EmissionRole = InteractionHint;
+/** A target-neutral element in a screen's emission tree. `displayName` is a structural default. */
+export interface EmissionElement {
+    readonly id: string;
+    readonly role: EmissionRole;
+    /** Semantic display name — a structural default here; the naming port may override it (never structure). */
+    readonly displayName: string;
+    readonly text?: string;
+    /** Auto-layout properties threaded from the IR node; absent when the node has no auto-layout. */
+    readonly layout?: IrLayout;
+    /** Per-axis sizing mode threaded from the IR node; absent when not set. */
+    readonly sizing?: IrSizing;
+    /**
+     * Corner radius in pixels threaded verbatim from the IR node; absent when the IR omits it. The IR
+     * cleaner (normalize) already drops a zero radius upstream, so this is never 0 in practice.
+     */
+    readonly cornerRadius?: number;
+    /** Per-TEXT typography threaded from the IR node; absent for non-TEXT nodes. */
+    readonly typography?: IrTypography;
+    readonly children: readonly EmissionElement[];
+}
+/** A resolved outgoing navigation target for a screen, derived from the routing hints (#811). */
+export interface EmissionNavTarget {
+    readonly trigger: string;
+    readonly toScreenId: string;
+    readonly toScreenName: string;
+}
+/** One screen reduced to its emission tree plus its outgoing navigation targets. */
+export interface ScreenEmission {
+    readonly screenId: string;
+    readonly screenName: string;
+    readonly root: EmissionElement;
+    readonly navTargets: readonly EmissionNavTarget[];
+}
+/** The full target-neutral emission plan an adapter renders to a concrete code target. */
+export interface CodeEmissionPlan {
+    readonly screens: readonly ScreenEmission[];
+    readonly tokens: DesignTokens;
+}
+/** The inputs to a code-emission pass: the screens, their tokens, and their routing hints. */
+export interface EmissionInput {
+    readonly screens: readonly ScreenIr[];
+    readonly tokens: DesignTokens;
+    readonly hints: readonly RoutingHint[];
+}
+/**
+ * Build the target-neutral emission plan from the Screen-IR, design tokens, and routing hints. Pure,
+ * deterministic, model-free: preserves the IR's child order, carries the tokens through verbatim, and
+ * attaches each screen's resolved outgoing navigation targets. The same input yields a byte-identical
+ * plan, so the emitted code is reproducible.
+ */
+export declare function buildEmissionPlan(input: EmissionInput): CodeEmissionPlan;
+//# sourceMappingURL=emissionPlan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emissionPlan.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/emissionPlan.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,YAAY,EACZ,QAAQ,EAER,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,QAAQ,EACT,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,kGAAkG;AAClG,MAAM,MAAM,YAAY,GAAG,eAAe,CAAC;AAE3C,mGAAmG;AACnG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,4GAA4G;IAC5G,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iGAAiG;IACjG,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;CAC/C;AAED,iGAAiG;AACjG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACnD;AAED,0FAA0F;AAC1F,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAyDD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,gBAAgB,CAYxE"}

package/dist/domain/figma/emissionPlan.js

@@ -0,0 +1,87 @@
+// Target-neutral design-to-code emission plan (Epic #750, Issue #755).
+//
+// Pure domain: a Screen-IR (#752) + deduped design tokens (#752) + framework-agnostic routing hints
+// (#811) are reduced — with NO model and NO IO — to a single, target-NEUTRAL emission plan: a
+// per-screen element tree (role + structural default name + text + child order preserved), each
+// screen's outgoing navigation targets, and the design-token set carried through verbatim for the
+// adapter to theme. A concrete `CodeTargetAdapter` renders this plan; the plan itself encodes no
+// framework, tag, or router vocabulary, so future adapters (MUI, a component library) plug in WITHOUT
+// changing this module.
+//
+// Generic by construction: the only structural signal read is `interactionHint` (a #752 role hint)
+// and the node's own `name`/`text`. No screen name, mask style, or copy is special-cased.
+// Deterministic: the plan carries no timestamp and preserves the IR's stable order, so the same
+// input yields a byte-identical plan (and thus byte-identical emitted code).
+//
+// Layout / sizing / cornerRadius / typography fields from the IR are threaded through unchanged so
+// that concrete adapters (htmlCssAdapter) can emit visual-fidelity CSS without re-reading the IR.
+// They are carried verbatim and never reinterpreted here.
+// A structural default display name: the node's own name when non-empty, else a role-based fallback.
+// Never empty, never model-invented — so emission always has a usable name with no model present.
+function structuralDisplayName(node) {
+    const trimmed = node.name.trim();
+    if (trimmed.length > 0)
+        return trimmed;
+    const text = node.text?.trim();
+    if (text !== undefined && text.length > 0)
+        return text;
+    return node.interactionHint;
+}
+// Screen names are evidence text too; a tampered/partial record can carry blank names. Keep the
+// first-slice artifact reviewable and navigable without model help by falling back to the screen id.
+function structuralScreenName(screen) {
+    const trimmed = screen.name.trim();
+    if (trimmed.length > 0)
+        return trimmed;
+    const id = screen.id.trim();
+    return id.length > 0 ? id : "Screen";
+}
+function toElement(node) {
+    const text = node.text?.trim();
+    return {
+        id: node.id,
+        role: node.interactionHint,
+        displayName: structuralDisplayName(node),
+        ...(text !== undefined && text.length > 0 ? { text } : {}),
+        ...(node.layout !== undefined ? { layout: node.layout } : {}),
+        ...(node.sizing !== undefined ? { sizing: node.sizing } : {}),
+        ...(node.cornerRadius !== undefined ? { cornerRadius: node.cornerRadius } : {}),
+        ...(node.typography !== undefined ? { typography: node.typography } : {}),
+        children: node.children.map(toElement),
+    };
+}
+// Resolve a screen's outgoing nav targets from the routing hints, mapping each hint's `toScreenId`
+// to a screen name. A hint targeting an unknown screen falls back to the id as its display name.
+function navTargetsFor(screenId, hints, nameByScreenId) {
+    const hint = hints.find((h) => h.screenId === screenId);
+    if (hint === undefined)
+        return [];
+    return hint.transitions.map((transition) => {
+        const fallbackName = transition.toScreenId.trim();
+        return {
+            trigger: transition.trigger,
+            toScreenId: transition.toScreenId,
+            toScreenName: nameByScreenId.get(transition.toScreenId) ??
+                (fallbackName.length > 0 ? fallbackName : "Screen"),
+        };
+    });
+}
+/**
+ * Build the target-neutral emission plan from the Screen-IR, design tokens, and routing hints. Pure,
+ * deterministic, model-free: preserves the IR's child order, carries the tokens through verbatim, and
+ * attaches each screen's resolved outgoing navigation targets. The same input yields a byte-identical
+ * plan, so the emitted code is reproducible.
+ */
+export function buildEmissionPlan(input) {
+    const nameByScreenId = new Map(input.screens.map((s) => [s.id, structuralScreenName(s)]));
+    const screens = input.screens.map((screen) => {
+        const screenName = structuralScreenName(screen);
+        return {
+            screenId: screen.id,
+            screenName,
+            root: toElement(screen.root),
+            navTargets: navTargetsFor(screen.id, input.hints, nameByScreenId),
+        };
+    });
+    return { screens, tokens: input.tokens };
+}

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

@@ -0,0 +1,13 @@
+import type { CodeTargetAdapter } from "./codeTargetAdapter.js";
+/**
+ * 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 declare const htmlCssAdapter: CodeTargetAdapter;
+//# sourceMappingURL=htmlCssAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"htmlCssAdapter.d.ts","sourceRoot":"","sources":["../../../src/domain/figma/htmlCssAdapter.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAA0B,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAqfxF;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,EAAE,iBAG5B,CAAC"}