@invarn/cibuild 2.1.0 → 2.1.1

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/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"}

package/dist/src/yaml/steps/ui-fidelity-preview-android.js

@@ -24,6 +24,7 @@ import { homedir, tmpdir } from 'node:os';
 import { basename, join, resolve } from 'node:path';
 import { parseScale, DEFAULT_SCALE } from './ui-fidelity-render.js';
 import { DEFAULT_GRADLE_TASK, PACKAGE_ARCHIVE_BASENAME, generateAndroidRenderScript, isValidGradleTask, } from './ui-fidelity-render-android.js';
+import { buildPreviewScreenResult } from './ui-fidelity-preview.js';
 /**
  * Build error returned when the local Android toolchain is absent, so the caller
  * can fall back to a remote run instead of a confusing build failure. Generic
@@ -233,15 +234,7 @@ export function renderUiFidelityPreviewAndroid(options) {
             (detail ? `:\n${detail}` : ''));
     }
     const raw = JSON.parse(readFileSync(resultPath, 'utf-8'));
-    const screens = (raw.screens || []).map((s) => ({
-        screen: s.screen,
-        status: s.status,
-        error: s.error ?? null,
-        referenceImagePath: absOrNull(artifactsDir, s.reference_image_path),
-        renderedImagePath: absOrNull(artifactsDir, s.rendered_image_path),
-        alignedImagePath: absOrNull(artifactsDir, s.aligned_image_path),
-        dimensions: s.dimensions ?? null,
-    }));
+    const screens = (raw.screens || []).map((s) => buildPreviewScreenResult(s, artifactsDir));
     const buildError = raw.error ?? null;
     const ok = buildError === null && screens.length > 0 && screens.every((s) => s.status === 'rendered');
     return { packageSource: 'inputs', buildError, screens, artifactsDir, ok };

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

@@ -73,6 +73,12 @@ export interface UiFidelityPreviewScreenResult {
     /** Absolute path to the reference-aligned image, or null. */
     alignedImagePath: string | null;
     dimensions: UiFidelityPreviewDimensions | null;
+    /**
+     * Advisory warning (never a failure) when the rendered aspect ratio diverges
+     * sharply from the reference's — the early signal that several states were
+     * stacked into one composable. Null when in tolerance or not comparable.
+     */
+    aspectWarning: string | null;
 }
 export interface UiFidelityPreviewResult {
     /** Always "inputs": the preview mirrors a shipped-package remote run. */
@@ -89,6 +95,26 @@ export interface UiFidelityPreviewResult {
     /** True only when every screen rendered and there was no build error. */
     ok: boolean;
 }
+/** Shape of the protocol-result.json the render script writes. */
+/** One screen as the render script writes it into protocol-result.json. */
+export interface RawPreviewScreen {
+    screen: string;
+    status: string;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    reference_image_path: string | null;
+    rendered_image_path: string | null;
+    aligned_image_path?: string | null;
+    dimensions?: UiFidelityPreviewDimensions | null;
+}
+/**
+ * Map one raw render-script screen to a preview result, resolving image paths
+ * and attaching the aspect-ratio warning. Shared by the iOS and Android preview
+ * engines so the two paths produce identical result shapes and warnings.
+ */
+export declare function buildPreviewScreenResult(raw: RawPreviewScreen, artifactsDir: string): UiFidelityPreviewScreenResult;
 /**
  * Render the requested screens locally and return the produced image paths and
  * dimensions. Throws only on caller errors (bad options) or when the render

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

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-preview.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAwBH,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;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,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,aAAa,EAAE,QAAQ,CAAC;IACxB,oEAAoE;IACpE,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,wDAAwD;IACxD,OAAO,EAAE,6BAA6B,EAAE,CAAC;IACzC,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,EAAE,EAAE,OAAO,CAAC;CACb;AAkCD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAoIzB"}
+{"version":3,"file":"ui-fidelity-preview.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA4BH,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;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,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,2BAA2B,GAAG,IAAI,CAAC;IAC/C;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,aAAa,EAAE,QAAQ,CAAC;IACxB,oEAAoE;IACpE,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,wDAAwD;IACxD,OAAO,EAAE,6BAA6B,EAAE,CAAC;IACzC,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,EAAE,EAAE,OAAO,CAAC;CACb;AAED,kEAAkE;AAClE,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,UAAU,CAAC,EAAE,2BAA2B,GAAG,IAAI,CAAC;CACjD;AAuBD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,gBAAgB,EACrB,YAAY,EAAE,MAAM,GACnB,6BAA6B,CAgB/B;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CA8HzB"}

package/dist/src/yaml/steps/ui-fidelity-preview.js

@@ -20,6 +20,7 @@ import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, statSyn
 import { tmpdir } from 'node:os';
 import { basename, join, resolve } from 'node:path';
 import { DEFAULT_RENDER_SIZE, DEFAULT_SCALE, generateRenderScript, parseRenderSize, parseScale, } from './ui-fidelity-render.js';
+import { evaluateAspectRatio, formatAspectRatioWarning, } from './fidelity-aspect-guard.js';
 function runTar(args, pathPrepend) {
     const env = pathPrepend
         ? { ...process.env, PATH: pathPrepend + ':' + (process.env.PATH ?? '') }
@@ -34,6 +35,25 @@ function runTar(args, pathPrepend) {
 function absOrNull(artifactsDir, relative) {
     return typeof relative === 'string' && relative !== '' ? resolve(artifactsDir, relative) : null;
 }
+/**
+ * Map one raw render-script screen to a preview result, resolving image paths
+ * and attaching the aspect-ratio warning. Shared by the iOS and Android preview
+ * engines so the two paths produce identical result shapes and warnings.
+ */
+export function buildPreviewScreenResult(raw, artifactsDir) {
+    const dimensions = raw.dimensions ?? null;
+    const aspect = evaluateAspectRatio(dimensions?.rendered_px ?? null, dimensions?.reference_px ?? null);
+    return {
+        screen: raw.screen,
+        status: raw.status,
+        error: raw.error ?? null,
+        referenceImagePath: absOrNull(artifactsDir, raw.reference_image_path),
+        renderedImagePath: absOrNull(artifactsDir, raw.rendered_image_path),
+        alignedImagePath: absOrNull(artifactsDir, raw.aligned_image_path),
+        dimensions,
+        aspectWarning: formatAspectRatioWarning(raw.screen, aspect),
+    };
+}
 /**
  * Render the requested screens locally and return the produced image paths and
  * dimensions. Throws only on caller errors (bad options) or when the render
@@ -136,15 +156,7 @@ export function renderUiFidelityPreview(options) {
             (detail ? `:\n${detail}` : ''));
     }
     const raw = JSON.parse(readFileSync(resultPath, 'utf-8'));
-    const screens = (raw.screens || []).map((s) => ({
-        screen: s.screen,
-        status: s.status,
-        error: s.error ?? null,
-        referenceImagePath: absOrNull(artifactsDir, s.reference_image_path),
-        renderedImagePath: absOrNull(artifactsDir, s.rendered_image_path),
-        alignedImagePath: absOrNull(artifactsDir, s.aligned_image_path),
-        dimensions: s.dimensions ?? null,
-    }));
+    const screens = (raw.screens || []).map((s) => buildPreviewScreenResult(s, artifactsDir));
     const buildError = raw.error ?? null;
     const ok = buildError === null && screens.length > 0 && screens.every((s) => s.status === 'rendered');
     return { packageSource: 'inputs', buildError, screens, artifactsDir, ok };

package/dist/src/yaml/steps/ui-fidelity-preview.test.js

@@ -12,7 +12,7 @@ import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { renderUiFidelityPreview } from './ui-fidelity-preview.js';
+import { renderUiFidelityPreview, buildPreviewScreenResult, } from './ui-fidelity-preview.js';
 const FIXTURE_PACKAGE = resolve(dirname(fileURLToPath(import.meta.url)), '../../../test/fixtures/ui-fidelity-package');
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 // A real, decodable 1x1 transparent PNG, used as the reference for the
@@ -100,6 +100,36 @@ describe('renderUiFidelityPreview — option validation', () => {
         })).toThrow(/reference for HomeView not found/);
     });
 });
+describe('buildPreviewScreenResult — aspect-ratio warning wiring', () => {
+    function rawScreen(rendered, reference) {
+        return {
+            screen: 'PromoBanner',
+            status: 'rendered',
+            error: null,
+            reference_image_path: 'references/PromoBanner.png',
+            rendered_image_path: 'rendered/PromoBanner.png',
+            aligned_image_path: 'aligned/PromoBanner.png',
+            dimensions: {
+                rendered_px: rendered,
+                logical_pt: [rendered[0] / 2, rendered[1] / 2],
+                reference_px: reference,
+            },
+        };
+    }
+    test('attaches a warning when a stacked render diverges from its reference', () => {
+        const result = buildPreviewScreenResult(rawScreen([880, 400], [952, 200]), '/tmp/art');
+        expect(result.aspectWarning).toMatch(/divergence/);
+        expect(result.aspectWarning).toContain('PromoBanner');
+    });
+    test('leaves no warning when the render matches the reference aspect ratio', () => {
+        const result = buildPreviewScreenResult(rawScreen([720, 1280], [360, 640]), '/tmp/art');
+        expect(result.aspectWarning).toBeNull();
+    });
+    test('leaves no warning when there is no reference to compare', () => {
+        const result = buildPreviewScreenResult(rawScreen([720, 1280], null), '/tmp/art');
+        expect(result.aspectWarning).toBeNull();
+    });
+});
 describe('renderUiFidelityPreview — fake toolchain', () => {
     test('archives the package, renders in inputs mode, and returns image paths + dims', () => {
         const result = renderUiFidelityPreview({

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

@@ -9,6 +9,15 @@
  *   1. Reads `.ci/inputs/params.json`
  *      ({ "screens": { "<ScreenName>": "<referenceFileBasename>" } });
  *      reference images live at `.ci/inputs/<basename>`.
+ *      Optional reference-provenance sidecar (manifest-driven multi-state path):
+ *      `"render_locale": "<locale>"` plus
+ *      `"provenance": { "<ScreenName>": { figmaNode, locale, resolved, exportedAt } }`.
+ *      When `render_locale` is present, each screen's reference is gated on its
+ *      provenance METADATA (never pixels/OCR): absent, unprovenanced,
+ *      `resolved == false`, or `locale != render_locale` → status
+ *      `unverifiable` for that screen, so a rotten reference fails loud instead
+ *      of yielding a confident-but-false PASS. Content differences (copy,
+ *      geometry) are NOT gated here — they stay soft, judged findings.
  *   2. Extracts and validates the shipped Gradle project shipped as
  *      `.ci/inputs/package.tar.gz` (single project root carrying a settings
  *      script, bounded extracted size, safe member paths).

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

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAIpE,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAqnBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAUrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,OAAO,EAAE,6BAA6B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAepB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CAgBpB"}
+{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAIpE,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAmsBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAUrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,OAAO,EAAE,6BAA6B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAepB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CAgBpB"}