@invarn/cibuild 2.1.0 → 2.1.2

package/dist/src/yaml/steps/fidelity-aspect-guard.js

@@ -0,0 +1,72 @@
+/**
+ * Fidelity aspect-ratio guard.
+ *
+ * One named composable per state is the authoring norm; the failure this
+ * catches is the opposite — several states stacked into one composable, which
+ * renders far taller (or wider) than the single-state reference it is paired
+ * against. That shows up as a sharp divergence between the rendered and
+ * reference aspect ratios, well before a human reads the diff.
+ *
+ * The guard is a pure comparison over the dimensions the render already
+ * reports (`rendered_px`, `reference_px`). It emits a WARNING when the
+ * divergence exceeds a documented fold factor — it never fails the render, and
+ * it stays silent when there is no reference to compare against.
+ */
+/**
+ * Fold factor beyond which a rendered/reference aspect-ratio divergence is
+ * worth a warning. A faithful single-state wrapper sits near 1.0; trim and
+ * reference alignment nudge it a few percent; a re-stacked 2-up wrapper roughly
+ * doubles one dimension and lands near 2.0. 1.5 catches the stack while
+ * tolerating the wobble.
+ */
+export const ASPECT_RATIO_WARN_FACTOR = 1.5;
+function isPositiveSize(size) {
+    return (Array.isArray(size) &&
+        size.length === 2 &&
+        Number.isFinite(size[0]) &&
+        Number.isFinite(size[1]) &&
+        size[0] > 0 &&
+        size[1] > 0);
+}
+/**
+ * Compares a rendered size against its reference size. Returns a
+ * non-warning, non-comparable result when either size is missing or
+ * non-positive — the guard only speaks when it has two real frames to compare.
+ */
+export function evaluateAspectRatio(renderedPx, referencePx, factor = ASPECT_RATIO_WARN_FACTOR) {
+    if (!isPositiveSize(renderedPx) || !isPositiveSize(referencePx)) {
+        return {
+            comparable: false,
+            renderedAspect: null,
+            referenceAspect: null,
+            divergence: null,
+            warn: false,
+        };
+    }
+    const renderedAspect = renderedPx[0] / renderedPx[1];
+    const referenceAspect = referencePx[0] / referencePx[1];
+    const divergence = Math.max(renderedAspect / referenceAspect, referenceAspect / renderedAspect);
+    return {
+        comparable: true,
+        renderedAspect,
+        referenceAspect,
+        divergence,
+        warn: divergence > factor,
+    };
+}
+/**
+ * Human/agent-readable warning line for a divergent screen, or null when the
+ * screen does not warrant one. The caller decides where to surface it (preview
+ * result, preflight output) — it is advisory, never a failure.
+ */
+export function formatAspectRatioWarning(screen, check) {
+    if (!check.warn || check.divergence === null)
+        return null;
+    const r = check.renderedAspect?.toFixed(2);
+    const ref = check.referenceAspect?.toFixed(2);
+    return (`Screen "${screen}" renders at aspect ratio ${r}:1 but its reference is ` +
+        `${ref}:1 (${check.divergence.toFixed(1)}× divergence). This often means ` +
+        `multiple states were stacked into one composable — author one named ` +
+        `composable per state instead.`);
+}
+//# sourceMappingURL=fidelity-aspect-guard.js.map

package/dist/src/yaml/steps/fidelity-aspect-guard.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Unit tests for the fidelity aspect-ratio guard.
+ *
+ * A wrapper that stacks several states into one composable renders far taller
+ * (or wider) than its single-state reference, so its aspect ratio diverges
+ * sharply from the reference's. The guard is the early warning for that
+ * re-stacking: it compares the rendered vs reference aspect ratios and flags a
+ * divergence beyond a documented fold factor — a WARNING, never a failure.
+ */
+export {};
+//# sourceMappingURL=fidelity-aspect-guard.test.d.ts.map

package/dist/src/yaml/steps/fidelity-aspect-guard.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-aspect-guard.test.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-aspect-guard.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/src/yaml/steps/fidelity-aspect-guard.test.js

@@ -0,0 +1,50 @@
+/**
+ * Unit tests for the fidelity aspect-ratio guard.
+ *
+ * A wrapper that stacks several states into one composable renders far taller
+ * (or wider) than its single-state reference, so its aspect ratio diverges
+ * sharply from the reference's. The guard is the early warning for that
+ * re-stacking: it compares the rendered vs reference aspect ratios and flags a
+ * divergence beyond a documented fold factor — a WARNING, never a failure.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { evaluateAspectRatio, ASPECT_RATIO_WARN_FACTOR, } from './fidelity-aspect-guard.js';
+describe('evaluateAspectRatio', () => {
+    test('does not warn when rendered and reference aspect ratios match', () => {
+        // A faithful single-state banner: same proportions as its reference.
+        const check = evaluateAspectRatio([720, 1280], [360, 640]);
+        expect(check.comparable).toBe(true);
+        expect(check.warn).toBe(false);
+        expect(check.divergence).toBeCloseTo(1, 5);
+    });
+    test('warns when a stacked render is far off the reference aspect ratio', () => {
+        // The canonical miss: two banner states stacked in one Column render at
+        // ~2.2:1, judged against a single-state ~4.76:1 reference.
+        const rendered = [880, 400]; // 2.2:1
+        const reference = [952, 200]; // 4.76:1
+        const check = evaluateAspectRatio(rendered, reference);
+        expect(check.comparable).toBe(true);
+        expect(check.warn).toBe(true);
+        expect(check.divergence).toBeCloseTo(4.76 / 2.2, 1);
+    });
+    test('tolerates a small alignment/trim wobble within the fold factor', () => {
+        // Trim + reference alignment can nudge dimensions a few percent; that must
+        // not trip the warning.
+        const check = evaluateAspectRatio([726, 1280], [360, 640]);
+        expect(check.warn).toBe(false);
+    });
+    test('is not comparable when there is no reference', () => {
+        const check = evaluateAspectRatio([720, 1280], null);
+        expect(check.comparable).toBe(false);
+        expect(check.warn).toBe(false);
+    });
+    test('is not comparable when a dimension is zero or negative', () => {
+        expect(evaluateAspectRatio([720, 0], [360, 640]).comparable).toBe(false);
+        expect(evaluateAspectRatio([720, 1280], [0, 640]).comparable).toBe(false);
+    });
+    test('exposes a sane default fold factor', () => {
+        expect(ASPECT_RATIO_WARN_FACTOR).toBeGreaterThan(1);
+        expect(ASPECT_RATIO_WARN_FACTOR).toBeLessThan(2);
+    });
+});
+//# sourceMappingURL=fidelity-aspect-guard.test.js.map

package/dist/src/yaml/steps/fidelity-reference-provenance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG the gate cannot read, so reference validity
+ * is asserted at export time as provenance metadata (`figmaNode`, `locale`,
+ * `resolved`, `exportedAt`) and the gate checks that METADATA — never the
+ * pixels, never via OCR. A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in a locale other than the
+ * render's is UNVERIFIABLE: a hard, mechanical verdict that fails loud instead
+ * of producing a confident-but-false PASS, and that kills the ad-hoc-Figma-fetch
+ * root cause (an ad-hoc fetch has no provenance, so it is Unverifiable).
+ *
+ * Content differences (copy wording, geometry) are deliberately NOT evaluated
+ * here — those are soft, judged findings that legitimately drift between
+ * reference-export and gate-run.
+ *
+ * This module is the authoritative spec for the check. The Android render
+ * runtime inlines an equivalent JS implementation (it ships as a self-contained
+ * script string and cannot import this module); the render-step integration
+ * tests exercise that inlined copy end-to-end against the same fixtures, so the
+ * two cannot silently drift.
+ */
+/** Export-time provenance as it travels in the run-input sidecar. */
+export interface ReferenceProvenanceMeta {
+    figmaNode?: string;
+    locale?: string;
+    resolved?: boolean;
+    exportedAt?: string;
+}
+/** A reason a reference cannot be honestly judged. */
+export interface ProvenanceFault {
+    /** Stable machine code (NO_PROVENANCE / UNRESOLVED_REFERENCE / …). */
+    code: string;
+    /** Human/agent-readable reason, naming the screen. */
+    message: string;
+}
+/** The per-state status string written to protocol-result.json. */
+export declare const UNVERIFIABLE_STATUS = "unverifiable";
+/**
+ * Returns the reason a reference is UNVERIFIABLE, or null when it is verifiable.
+ * Checks metadata then existence; order is irrelevant for single-fault inputs
+ * but deterministic when several faults coincide.
+ */
+export declare function provenanceFault(screen: string, provenance: ReferenceProvenanceMeta | null | undefined, renderLocale: string, referenceExists: boolean): ProvenanceFault | null;
+//# sourceMappingURL=fidelity-reference-provenance.d.ts.map

package/dist/src/yaml/steps/fidelity-reference-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-reference-provenance.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-reference-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAgBlD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,EACtD,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,OAAO,GACvB,eAAe,GAAG,IAAI,CAgCxB"}

package/dist/src/yaml/steps/fidelity-reference-provenance.js

@@ -0,0 +1,69 @@
+/**
+ * Reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG the gate cannot read, so reference validity
+ * is asserted at export time as provenance metadata (`figmaNode`, `locale`,
+ * `resolved`, `exportedAt`) and the gate checks that METADATA — never the
+ * pixels, never via OCR. A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in a locale other than the
+ * render's is UNVERIFIABLE: a hard, mechanical verdict that fails loud instead
+ * of producing a confident-but-false PASS, and that kills the ad-hoc-Figma-fetch
+ * root cause (an ad-hoc fetch has no provenance, so it is Unverifiable).
+ *
+ * Content differences (copy wording, geometry) are deliberately NOT evaluated
+ * here — those are soft, judged findings that legitimately drift between
+ * reference-export and gate-run.
+ *
+ * This module is the authoritative spec for the check. The Android render
+ * runtime inlines an equivalent JS implementation (it ships as a self-contained
+ * script string and cannot import this module); the render-step integration
+ * tests exercise that inlined copy end-to-end against the same fixtures, so the
+ * two cannot silently drift.
+ */
+/** The per-state status string written to protocol-result.json. */
+export const UNVERIFIABLE_STATUS = 'unverifiable';
+function hasProvenance(p) {
+    // Provenance is only "present" when the fields the gate reasons over are
+    // there. A partial object (e.g. a hand-dropped `{ figmaNode }`) is treated as
+    // no provenance — verifiable is earned only through the full export path.
+    return (p != null &&
+        typeof p === 'object' &&
+        typeof p.locale === 'string' &&
+        typeof p.resolved === 'boolean');
+}
+/**
+ * Returns the reason a reference is UNVERIFIABLE, or null when it is verifiable.
+ * Checks metadata then existence; order is irrelevant for single-fault inputs
+ * but deterministic when several faults coincide.
+ */
+export function provenanceFault(screen, provenance, renderLocale, referenceExists) {
+    if (!hasProvenance(provenance)) {
+        return {
+            code: 'NO_PROVENANCE',
+            message: `reference for ${screen} has no export provenance; a reference is ` +
+                `verifiable only when exported through the deterministic path`,
+        };
+    }
+    if (provenance.resolved === false) {
+        return {
+            code: 'UNRESOLVED_REFERENCE',
+            message: `reference for ${screen} still has unresolved copy placeholders ` +
+                `(resolved=false) — export it with the copy filled in`,
+        };
+    }
+    if (provenance.locale !== renderLocale) {
+        return {
+            code: 'LOCALE_MISMATCH',
+            message: `reference for ${screen} is locale "${provenance.locale}" but the ` +
+                `render locale is "${renderLocale}"`,
+        };
+    }
+    if (!referenceExists) {
+        return {
+            code: 'REFERENCE_ABSENT',
+            message: `reference image for ${screen} is absent`,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=fidelity-reference-provenance.js.map

package/dist/src/yaml/steps/fidelity-reference-provenance.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Unit tests for the reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG; the gate cannot read its text. So validity
+ * is asserted at export time as provenance metadata, and the gate checks the
+ * METADATA, never the pixels (no OCR). A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in the wrong locale is
+ * UNVERIFIABLE — a loud, mechanical verdict, not a confident-but-false PASS.
+ *
+ * Content differences (copy wording, geometry) are NOT checked here — those are
+ * soft, judged findings that legitimately drift between export and run.
+ */
+export {};
+//# sourceMappingURL=fidelity-reference-provenance.test.d.ts.map

package/dist/src/yaml/steps/fidelity-reference-provenance.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-reference-provenance.test.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-reference-provenance.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/dist/src/yaml/steps/fidelity-reference-provenance.test.js

@@ -0,0 +1,54 @@
+/**
+ * Unit tests for the reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG; the gate cannot read its text. So validity
+ * is asserted at export time as provenance metadata, and the gate checks the
+ * METADATA, never the pixels (no OCR). A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in the wrong locale is
+ * UNVERIFIABLE — a loud, mechanical verdict, not a confident-but-false PASS.
+ *
+ * Content differences (copy wording, geometry) are NOT checked here — those are
+ * soft, judged findings that legitimately drift between export and run.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { provenanceFault, UNVERIFIABLE_STATUS, } from './fidelity-reference-provenance.js';
+const GOOD = {
+    figmaNode: '12:345',
+    locale: 'en',
+    resolved: true,
+    exportedAt: '2026-06-18T10:00:00Z',
+};
+describe('provenanceFault', () => {
+    test('a present, provenanced, resolved, locale-matching reference is verifiable', () => {
+        expect(provenanceFault('Guest', GOOD, 'en', true)).toBeNull();
+    });
+    test('an absent reference is UNVERIFIABLE (REFERENCE_ABSENT)', () => {
+        const fault = provenanceFault('Guest', GOOD, 'en', false);
+        expect(fault?.code).toBe('REFERENCE_ABSENT');
+    });
+    test('a reference with no provenance is UNVERIFIABLE (NO_PROVENANCE)', () => {
+        expect(provenanceFault('Guest', null, 'en', true)?.code).toBe('NO_PROVENANCE');
+        expect(provenanceFault('Guest', undefined, 'en', true)?.code).toBe('NO_PROVENANCE');
+    });
+    test('incomplete provenance (missing locale/resolved) is UNVERIFIABLE (NO_PROVENANCE)', () => {
+        expect(provenanceFault('Guest', { figmaNode: 'x', exportedAt: 'y' }, 'en', true)?.code).toBe('NO_PROVENANCE');
+    });
+    test('a placeholder reference (resolved=false) is UNVERIFIABLE (UNRESOLVED_REFERENCE)', () => {
+        const fault = provenanceFault('Guest', { ...GOOD, resolved: false }, 'en', true);
+        expect(fault?.code).toBe('UNRESOLVED_REFERENCE');
+    });
+    test('a wrong-locale reference is UNVERIFIABLE (LOCALE_MISMATCH)', () => {
+        // Italian reference vs an English render.
+        const fault = provenanceFault('Guest', { ...GOOD, locale: 'it' }, 'en', true);
+        expect(fault?.code).toBe('LOCALE_MISMATCH');
+    });
+    test('every fault carries the screen name and a human reason', () => {
+        const fault = provenanceFault('LoggedIn', { ...GOOD, resolved: false }, 'en', true);
+        expect(fault?.message).toContain('LoggedIn');
+        expect(fault?.message.length).toBeGreaterThan(10);
+    });
+    test('exposes the unverifiable status string the result document uses', () => {
+        expect(UNVERIFIABLE_STATUS).toBe('unverifiable');
+    });
+});
+//# sourceMappingURL=fidelity-reference-provenance.test.js.map

package/dist/src/yaml/steps/structural-facts.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Structural-facts deriver — Signal A of the UI-fidelity structural pass.
+ *
+ * Pure and platform-agnostic: it takes a per-node layout dump (bounds in px,
+ * parent, clip flag) emitted alongside the render and derives intent-agnostic
+ * geometric facts the fidelity judge should check instead of discovering them
+ * by eye:
+ *
+ *   - `overflow`          — a node extends past its parent's box (parent does
+ *                           NOT clip, so the excess is visibly sticking out).
+ *   - `clipped_by_parent` — a node extends past a CLIPPING parent's box, so the
+ *                           excess is cut away (the motivating euro-coin case).
+ *   - `off_screen`        — a node extends past the root canvas.
+ *   - `overlap`           — two siblings overlap by a significant area.
+ *
+ * The deriver does NOT judge or score; it reports facts. The verdict stays the
+ * agent's. This is the brain of Signal A; the render-side emission + facts
+ * artifact wiring live in the render step (a separate slice).
+ */
+export interface LayoutBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface LayoutNode {
+    /** Stable id/label for the node within one dump. */
+    id: string;
+    /** Root-space bounds in px. */
+    bounds: LayoutBounds;
+    /** Parent node id, or null for a root node. */
+    parentId: string | null;
+    /** Whether this node clips its children to its bounds. */
+    clipsChildren: boolean;
+}
+export interface LayoutDump {
+    /** The captured canvas / root bounds in px. */
+    canvas: LayoutBounds;
+    nodes: LayoutNode[];
+}
+export type Edge = 'left' | 'top' | 'right' | 'bottom';
+export type StructuralFact = {
+    kind: 'overflow';
+    nodeId: string;
+    parentId: string;
+    edges: Edge[];
+    overflowPx: Partial<Record<Edge, number>>;
+} | {
+    kind: 'clipped_by_parent';
+    nodeId: string;
+    clipperId: string;
+    edges: Edge[];
+    clippedPx: Partial<Record<Edge, number>>;
+} | {
+    kind: 'off_screen';
+    nodeId: string;
+    edges: Edge[];
+    offscreenPx: Partial<Record<Edge, number>>;
+} | {
+    kind: 'overlap';
+    nodeIds: [string, string];
+    overlapPx: {
+        width: number;
+        height: number;
+    };
+    ratio: number;
+};
+export interface DeriveStructuralFactsOptions {
+    /** Edge excesses / overlaps at or below this many px are ignored, so that
+     *  exact-touching layout edges don't read as overflow or overlap. */
+    tolerancePx?: number;
+    /** Minimum (intersection area / smaller node area) for an overlap to be
+     *  reported as significant. */
+    overlapMinRatio?: number;
+}
+export declare function deriveStructuralFacts(dump: LayoutDump, options?: DeriveStructuralFactsOptions): StructuralFact[];
+/**
+ * Render-side embedded form of the deriver.
+ *
+ * The Android render runs as a single self-contained generated script (see
+ * `generateAndroidRenderScript`), so render-side pure logic is embedded as a
+ * JS-source string and concatenated in — exactly like `RENDER_SCRIPT_TRIM_STAGE`.
+ * The typed `deriveStructuralFacts` above stays the canonical, tested spec; the
+ * `parity` test asserts this embedded port produces identical facts on shared
+ * fixtures so the two cannot drift.
+ *
+ * `deriveStructuralFacts` here is pure; `deriveAndWriteFacts` references runtime
+ * globals (`fs`, `path`, `artifactsDir`, `log`) defined in the main script and
+ * is only invoked from there — harmless to define in the eval sandbox.
+ */
+export declare const RENDER_SCRIPT_FACTS_STAGE: string;
+/**
+ * Evaluates the embedded facts stage and returns its pure `deriveStructuralFacts`,
+ * so the parity test exercises exactly the code that ships in the runtime script
+ * (mirrors `getPostProcessorInternals`). `deriveAndWriteFacts` references runtime
+ * globals only when called, so defining it in the sandbox is harmless.
+ */
+export declare function getStructuralFactsStageInternals(): {
+    deriveStructuralFacts: (dump: LayoutDump, options?: DeriveStructuralFactsOptions) => StructuralFact[];
+};
+//# sourceMappingURL=structural-facts.d.ts.map

package/dist/src/yaml/steps/structural-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-facts.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/structural-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0DAA0D;IAC1D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEvD,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3C,GACD;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1C,GACD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5C,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,4BAA4B;IAC3C;yEACqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;mCAC+B;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoCD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,4BAAiC,GACzC,cAAc,EAAE,CA2ElB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAuHvC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gCAAgC,IAAI;IAClD,qBAAqB,EAAE,CACrB,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,4BAA4B,KACnC,cAAc,EAAE,CAAC;CACvB,CAWA"}

package/dist/src/yaml/steps/structural-facts.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure unit tests for the structural-facts deriver (UI-fidelity structural
+ * pass, Signal A). Fixture-driven, no toolchain — the deriver turns a
+ * per-node layout dump into intent-agnostic geometric facts the fidelity
+ * judge checks instead of eyeballing.
+ *
+ * The canonical regression fixture is the motivating miss: a card clips an
+ * overflowing voucher tag; the deriver must surface the bottom clip as a
+ * fact so it is never again skipped by eye.
+ */
+export {};
+//# sourceMappingURL=structural-facts.test.d.ts.map

package/dist/src/yaml/steps/structural-facts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-facts.test.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/structural-facts.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/src/yaml/steps/structural-facts.test.js

@@ -0,0 +1,174 @@
+/**
+ * Pure unit tests for the structural-facts deriver (UI-fidelity structural
+ * pass, Signal A). Fixture-driven, no toolchain — the deriver turns a
+ * per-node layout dump into intent-agnostic geometric facts the fidelity
+ * judge checks instead of eyeballing.
+ *
+ * The canonical regression fixture is the motivating miss: a card clips an
+ * overflowing voucher tag; the deriver must surface the bottom clip as a
+ * fact so it is never again skipped by eye.
+ */
+import { deriveStructuralFacts, getStructuralFactsStageInternals, } from './structural-facts.js';
+// 200x400 canvas in px for all fixtures unless noted.
+const CANVAS = { left: 0, top: 0, right: 200, bottom: 400 };
+describe('deriveStructuralFacts — containment', () => {
+    test('a fully-contained child produces no clip/overflow fact', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'card', bounds: { left: 20, top: 20, right: 180, bottom: 200 }, parentId: null, clipsChildren: true },
+                { id: 'label', bounds: { left: 30, top: 30, right: 170, bottom: 60 }, parentId: 'card', clipsChildren: false },
+            ],
+        };
+        expect(deriveStructuralFacts(dump)).toEqual([]);
+    });
+});
+describe('deriveStructuralFacts — overflow vs clip', () => {
+    test('child overflowing a NON-clipping parent is reported as overflow, not clipped', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'row', bounds: { left: 20, top: 20, right: 180, bottom: 100 }, parentId: null, clipsChildren: false },
+                // sticks out 15px past the row's right edge
+                { id: 'chip', bounds: { left: 150, top: 30, right: 195, bottom: 80 }, parentId: 'row', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        expect(facts).toHaveLength(1);
+        expect(facts[0]).toMatchObject({
+            kind: 'overflow',
+            nodeId: 'chip',
+            parentId: 'row',
+            edges: ['right'],
+            overflowPx: { right: 15 },
+        });
+    });
+    test('child overflowing a CLIPPING parent is reported as clipped-by-parent with the clipped extent', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'card', bounds: { left: 20, top: 20, right: 180, bottom: 200 }, parentId: null, clipsChildren: true },
+                // overflows the card's bottom by 24px → that extent is clipped away
+                { id: 'tag', bounds: { left: 60, top: 150, right: 140, bottom: 224 }, parentId: 'card', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        expect(facts).toHaveLength(1);
+        expect(facts[0]).toMatchObject({
+            kind: 'clipped_by_parent',
+            nodeId: 'tag',
+            clipperId: 'card',
+            edges: ['bottom'],
+            clippedPx: { bottom: 24 },
+        });
+    });
+});
+describe('deriveStructuralFacts — off-screen', () => {
+    test('a node extending past the canvas is reported off-screen on those edges', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                // bottom edge 30px below the canvas
+                { id: 'sheet', bounds: { left: 0, top: 360, right: 200, bottom: 430 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        const offscreen = facts.filter((f) => f.kind === 'off_screen');
+        expect(offscreen).toHaveLength(1);
+        expect(offscreen[0]).toMatchObject({
+            kind: 'off_screen',
+            nodeId: 'sheet',
+            edges: ['bottom'],
+            offscreenPx: { bottom: 30 },
+        });
+    });
+});
+describe('deriveStructuralFacts — overlap', () => {
+    test('two significantly overlapping siblings are reported as an overlap', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'a', bounds: { left: 20, top: 20, right: 120, bottom: 120 }, parentId: 'root', clipsChildren: false },
+                { id: 'b', bounds: { left: 80, top: 60, right: 180, bottom: 160 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        const overlap = deriveStructuralFacts(dump).filter((f) => f.kind === 'overlap');
+        expect(overlap).toHaveLength(1);
+        expect(overlap[0]).toMatchObject({ kind: 'overlap', nodeIds: ['a', 'b'] });
+    });
+    test('barely-touching siblings within tolerance are not an overlap', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'a', bounds: { left: 20, top: 20, right: 100, bottom: 100 }, parentId: 'root', clipsChildren: false },
+                { id: 'b', bounds: { left: 100, top: 20, right: 180, bottom: 100 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        expect(deriveStructuralFacts(dump).filter((f) => f.kind === 'overlap')).toEqual([]);
+    });
+});
+describe('embedded render-side stage parity', () => {
+    // The render script ships a JS-source port of the deriver. It must produce
+    // byte-identical facts to the canonical typed module, or render-side facts
+    // would silently diverge from what the tests guarantee.
+    const { deriveStructuralFacts: embedded } = getStructuralFactsStageInternals();
+    const fixtures = {
+        clip: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'card', bounds: { left: 20, top: 20, right: 180, bottom: 200 }, parentId: null, clipsChildren: true },
+                { id: 'tag', bounds: { left: 60, top: 150, right: 140, bottom: 224 }, parentId: 'card', clipsChildren: false },
+            ],
+        },
+        overflow: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'row', bounds: { left: 20, top: 20, right: 180, bottom: 100 }, parentId: null, clipsChildren: false },
+                { id: 'chip', bounds: { left: 150, top: 30, right: 195, bottom: 80 }, parentId: 'row', clipsChildren: false },
+            ],
+        },
+        overlap: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'a', bounds: { left: 20, top: 20, right: 120, bottom: 120 }, parentId: 'root', clipsChildren: false },
+                { id: 'b', bounds: { left: 80, top: 60, right: 180, bottom: 160 }, parentId: 'root', clipsChildren: false },
+            ],
+        },
+    };
+    for (const [name, dump] of Object.entries(fixtures)) {
+        test(`embedded port matches the module for the ${name} fixture`, () => {
+            expect(embedded(dump)).toEqual(deriveStructuralFacts(dump));
+        });
+    }
+});
+describe('deriveStructuralFacts — motivating regression (voucher tag bottom-clip)', () => {
+    // The render-side layout dump for the HubPromoBanner-style case: a card
+    // clips children, and the voucher tag (with its euro coin) overflows the
+    // card's bottom. The deriver MUST surface the bottom clip so the verdict
+    // can compare its extent to the design and never miss it by eye again.
+    test('reports the voucher tag as clipped by the card at the bottom, with the clipped px', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 360, bottom: 720 },
+            nodes: [
+                { id: 'HubPromoBanner', bounds: { left: 16, top: 100, right: 344, bottom: 262 }, parentId: null, clipsChildren: true },
+                { id: 'promoText', bounds: { left: 32, top: 116, right: 240, bottom: 180 }, parentId: 'HubPromoBanner', clipsChildren: false },
+                // voucher tag overflows the card bottom (262) down to 280 → 18px clipped
+                { id: 'voucherTag', bounds: { left: 250, top: 210, right: 330, bottom: 280 }, parentId: 'HubPromoBanner', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        const clip = facts.find((f) => f.kind === 'clipped_by_parent' && f.nodeId === 'voucherTag');
+        expect(clip).toMatchObject({
+            kind: 'clipped_by_parent',
+            nodeId: 'voucherTag',
+            clipperId: 'HubPromoBanner',
+            edges: ['bottom'],
+            clippedPx: { bottom: 18 },
+        });
+    });
+});
+//# sourceMappingURL=structural-facts.test.js.map

package/dist/src/yaml/steps/ui-fidelity-preview-android.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-preview-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsBH,OAAO,KAAK,EAEV,uBAAuB,EACvB,uBAAuB,EAExB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAkBD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAqErE;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,uBAAuB,CA6KzB"}
+{"version":3,"file":"ui-fidelity-preview-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuBH,OAAO,KAAK,EAEV,uBAAuB,EACvB,uBAAuB,EAGxB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,+BAA+B;IAC9C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAQD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAqErE;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,uBAAuB,CAuKzB"}