@invarn/cibuild 2.1.0 → 2.1.2

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;AAKpE,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;AA4uBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAWrF;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"}

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

@@ -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).
@@ -41,6 +50,7 @@
 import { BaseStepExecutor } from './base.js';
 import { parseScale, DEFAULT_SCALE } from './ui-fidelity-render.js';
 import { RENDER_SCRIPT_TRIM_STAGE } from './render-post-processor.js';
+import { RENDER_SCRIPT_FACTS_STAGE } from './structural-facts.js';
 /**
  * Default Roborazzi record task. Run from the project root so Gradle resolves
  * it in whichever subproject declares it.
@@ -136,6 +146,54 @@ function setError(entry, code, message) {
   entry.error = { code: code, message: sanitizeMessage(message) };
 }
 
+// A reference the gate cannot honestly judge: a hard, mechanical metadata
+// verdict (never pixels/OCR). Distinct status so a rotten reference fails loud
+// instead of producing a confident-but-false PASS.
+function setUnverifiable(entry, code, message) {
+  entry.status = 'unverifiable';
+  entry.error = { code: code, message: sanitizeMessage(message) };
+}
+
+// Inlined twin of src/yaml/steps/fidelity-reference-provenance.ts (this script
+// ships self-contained and cannot import it). The render-step integration tests
+// exercise BOTH against the same fixtures so they cannot silently drift. Returns
+// a { code, message } fault, or null when the reference is verifiable.
+function provenanceFault(screen, provenance, renderLocale, referenceExists) {
+  var hasProvenance =
+    provenance != null &&
+    typeof provenance === 'object' &&
+    typeof provenance.locale === 'string' &&
+    typeof provenance.resolved === 'boolean';
+  if (!hasProvenance) {
+    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;
+}
+
 function outputTail(result) {
   var combined = ((result.stdout || '') + '\n' + (result.stderr || '')).trim();
   if (combined.length > 2000) combined = '...' + combined.slice(-2000);
@@ -404,6 +462,21 @@ function roborazziPngMatches(basename, screen) {
   return method === screen || method === 'render' + screen;
 }
 
+// The structural-pass layout dump (Signal A) is emitted next to the PNG in a
+// roborazzi output dir, but Roborazzi controls the PNG's golden filename and
+// ignores explicit capture names, so the dump can't reliably share the PNG's
+// stem. Match it the same collision-safe way as the PNG instead — by the final
+// dot-delimited segment of "<...>.layout.json" — so the emitter can write a
+// simple "<Screen>.layout.json" regardless of the PNG's golden name.
+function roborazziLayoutMatches(basename, screen) {
+  var suffix = '.layout.json';
+  if (basename.slice(-suffix.length) !== suffix) return false;
+  var stem = basename.slice(0, -suffix.length);
+  var lastDot = stem.lastIndexOf('.');
+  var seg = lastDot === -1 ? stem : stem.slice(lastDot + 1);
+  return seg === screen || seg === 'render' + screen;
+}
+
 // Roborazzi writes PNGs to <module>/build/outputs/roborazzi/. Collect every
 // such directory in the project so a screen's PNG can be located regardless of
 // which module rendered it.
@@ -504,6 +577,28 @@ function renderScreens(renderable, projectRoot) {
       entry.error = null;
       log('rendered ' + entry.screen + ' -> ' + relative);
       trimRenderedImage(entry, outputPath, workDir);
+      // Signal A: the render emits a per-node layout dump into a roborazzi
+      // output dir (named "<Screen>.layout.json" or "...render<Screen>.layout.json").
+      // Locate it the same way as the PNG and derive structural facts; absent or
+      // malformed is a clean no-op.
+      var layoutSource = null;
+      for (var li = 0; li < roborazziDirs.length && layoutSource === null; li++) {
+        var lnames;
+        try {
+          lnames = fs.readdirSync(roborazziDirs[li]);
+        } catch (lReadError) {
+          lnames = [];
+        }
+        for (var lj = 0; lj < lnames.length; lj++) {
+          if (roborazziLayoutMatches(lnames[lj], entry.screen)) {
+            layoutSource = path.join(roborazziDirs[li], lnames[lj]);
+            break;
+          }
+        }
+      }
+      if (layoutSource !== null) {
+        deriveAndWriteFacts(entry, layoutSource);
+      }
     });
   } finally {
     if (process.env.UI_FIDELITY_KEEP_HARNESS) {
@@ -549,6 +644,18 @@ function main() {
     return 1;
   }
 
+  // Reference-provenance sidecar. Enforcement is ON only when the run declares
+  // its render locale (the manifest-driven multi-state path always does);
+  // legacy single-reference runs without it keep their existing behaviour.
+  var renderLocale =
+    typeof params.render_locale === 'string' && params.render_locale !== ''
+      ? params.render_locale
+      : null;
+  var provenanceMap =
+    params.provenance && typeof params.provenance === 'object' && !Array.isArray(params.provenance)
+      ? params.provenance
+      : {};
+
   var screens = Object.keys(params.screens);
   currentEntries = screens.map(function (screen) {
     return {
@@ -559,6 +666,8 @@ function main() {
       rendered_image_path: null,
       aligned_image_path: null,
       dimensions: null,
+      layout_path: null,
+      facts_path: null,
     };
   });
   log('screens: ' + (screens.join(', ') || '(none)'));
@@ -566,6 +675,8 @@ function main() {
   fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'rendered'), { recursive: true });
   fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'references'), { recursive: true });
   fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'aligned'), { recursive: true });
+  fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'layout'), { recursive: true });
+  fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'facts'), { recursive: true });
 
   // 2. Per-screen validation + reference copies. Each screen gets its OWN copy
   //    named by screen, even when two screens share a reference basename.
@@ -600,7 +711,25 @@ function main() {
     } catch (statError) {
       sourceStat = null;
     }
-    if (!sourceStat || !sourceStat.isFile()) {
+    var referenceExists = !!(sourceStat && sourceStat.isFile());
+
+    if (renderLocale) {
+      // Provenance enforcement: a reference that is absent, unprovenanced,
+      // unresolved, or in the wrong locale is UNVERIFIABLE (hard, loud) — not a
+      // render_failed and never a silent PASS.
+      var fault = provenanceFault(
+        entry.screen,
+        provenanceMap[entry.screen],
+        renderLocale,
+        referenceExists
+      );
+      if (fault) {
+        setUnverifiable(entry, fault.code, fault.message);
+        return;
+      }
+    } else if (!referenceExists) {
+      // Legacy (no render locale declared): an absent reference stays a
+      // render_failed REFERENCE_MISSING, exactly as before.
       setError(
         entry,
         'REFERENCE_MISSING',
@@ -696,6 +825,7 @@ export function generateAndroidRenderScript(config) {
         'var RENDERER = ' + JSON.stringify(ANDROID_RENDERER) + ';',
         'var PACKAGE_ARCHIVE_NAME = ' + JSON.stringify(PACKAGE_ARCHIVE_BASENAME) + ';',
         RENDER_SCRIPT_TRIM_STAGE,
+        RENDER_SCRIPT_FACTS_STAGE,
         ANDROID_RENDER_SCRIPT_MAIN,
     ].join('\n');
 }

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

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { chmodSync, cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import { gzipSync } from 'node:zlib';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -39,6 +39,16 @@ const FAKE_GRADLEW_LINES = [
     '  [ -z "$s" ] && continue',
     "  printf '\\x89PNG\\r\\n\\x1a\\n' > \"$out/$s.png\"",
     '  printf \'roborazzi:%s\' "$s" >> "$out/$s.png"',
+    // When FAKE_ROBORAZZI_LAYOUT is set, also emit the layout-dump sidecar next
+    // to the PNG (matching basename, .layout.json) — a clipping card with an
+    // overflowing tag, so the deriver yields one clipped-by-parent fact.
+    '  if [ -n "$FAKE_ROBORAZZI_LAYOUT" ]; then',
+    // Layout sidecar basename: flat "<screen>.layout.json" by default, or an
+    // explicit golden-style dotted name via FAKE_ROBORAZZI_LAYOUT_NAME to prove
+    // the consumer finds it by dot-segment match, decoupled from the PNG stem.
+    '    lname="${FAKE_ROBORAZZI_LAYOUT_NAME:-$s.layout.json}"',
+    `    printf '%s' '{"canvas":{"left":0,"top":0,"right":200,"bottom":400},"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}]}' > "$out/$lname"`,
+    '  fi',
     'done',
     'exit 0',
 ];
@@ -275,6 +285,67 @@ describe('android render runtime — render + trim (happy path)', () => {
         // The rendered file holds the trim helper's output, not the raw render.
         expect(readFileSync(artifact(project, 'ui-fidelity/rendered/XProof.png'), 'utf-8')).toContain('trimmed:XProof.png');
     });
+    test('derives structural facts from the layout dump and records layout_path + facts_path', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        stageArchive(project, gradleProjectEntries());
+        const run = runScript(project, await buildScript(), {
+            FAKE_ROBORAZZI_SCREENS: 'XProof',
+            FAKE_ROBORAZZI_LAYOUT: '1',
+        });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.layout_path).toBe('ui-fidelity/layout/XProof.json');
+        expect(screen?.facts_path).toBe('ui-fidelity/facts/XProof.json');
+        // The layout dump is copied verbatim as a build artifact.
+        expect(existsSync(artifact(project, 'ui-fidelity/layout/XProof.json'))).toBe(true);
+        // The facts artifact surfaces the bottom clip the eye would miss.
+        const facts = JSON.parse(readFileSync(artifact(project, 'ui-fidelity/facts/XProof.json'), 'utf-8'));
+        expect(facts).toEqual({
+            screen: 'XProof',
+            facts: [
+                {
+                    kind: 'clipped_by_parent',
+                    nodeId: 'tag',
+                    clipperId: 'card',
+                    edges: ['bottom'],
+                    clippedPx: { bottom: 24 },
+                },
+            ],
+        });
+    });
+    test('finds the layout dump by dot-segment match even when its name differs from the PNG stem', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        stageArchive(project, gradleProjectEntries());
+        // Golden-style dotted layout name (as real Roborazzi would name a sidecar),
+        // distinct from the flat PNG the fake writes — the consumer must still find it.
+        const run = runScript(project, await buildScript(), {
+            FAKE_ROBORAZZI_SCREENS: 'XProof',
+            FAKE_ROBORAZZI_LAYOUT: '1',
+            FAKE_ROBORAZZI_LAYOUT_NAME: 'com.example.XProofTest.renderXProof.layout.json',
+        });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.facts_path).toBe('ui-fidelity/facts/XProof.json');
+        const facts = JSON.parse(readFileSync(artifact(project, 'ui-fidelity/facts/XProof.json'), 'utf-8'));
+        expect(facts.facts).toHaveLength(1);
+        expect(facts.facts[0].kind).toBe('clipped_by_parent');
+    });
+    test('degrades cleanly when no layout dump is emitted (no facts, render still succeeds)', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        stageArchive(project, gradleProjectEntries());
+        // No FAKE_ROBORAZZI_LAYOUT → the render emits a PNG but no sidecar.
+        const run = runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.layout_path ?? null).toBeNull();
+        expect(screen?.facts_path ?? null).toBeNull();
+        expect(existsSync(artifact(project, 'ui-fidelity/facts/XProof.json'))).toBe(false);
+    });
     test('renders multiple screens independently in one Gradle run', async () => {
         const project = makeProject({ screens: { XProof: 'x.png', YProof: 'y.png' } });
         writeReference(project, 'x.png');
@@ -286,6 +357,104 @@ describe('android render runtime — render + trim (happy path)', () => {
         expect(doc.screens.map((s) => s.status)).toEqual(['rendered', 'rendered']);
     });
 });
+describe('android render runtime — reference provenance (UNVERIFIABLE)', () => {
+    const GOOD_PROV = {
+        figmaNode: '12:345',
+        locale: 'en',
+        resolved: true,
+        exportedAt: '2026-06-18T10:00:00Z',
+    };
+    // Stage a valid project so per-build archive validation passes and the only
+    // signal under test is the per-screen provenance verdict.
+    function provProject(params) {
+        const project = makeProject(params);
+        stageArchive(project, gradleProjectEntries());
+        return project;
+    }
+    test('a reference with no provenance is unverifiable', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            render_locale: 'en',
+            provenance: {},
+        });
+        writeReference(project, 'x.png');
+        runScript(project, await buildScript());
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('unverifiable');
+        expect(screen?.error?.code).toBe('NO_PROVENANCE');
+    });
+    test('a placeholder reference (resolved=false) is unverifiable', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            render_locale: 'en',
+            provenance: { XProof: { ...GOOD_PROV, resolved: false } },
+        });
+        writeReference(project, 'x.png');
+        runScript(project, await buildScript());
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('unverifiable');
+        expect(screen?.error?.code).toBe('UNRESOLVED_REFERENCE');
+    });
+    test('an Italian reference against an English render is unverifiable', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            render_locale: 'en',
+            provenance: { XProof: { ...GOOD_PROV, locale: 'it' } },
+        });
+        writeReference(project, 'x.png');
+        runScript(project, await buildScript());
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('unverifiable');
+        expect(screen?.error?.code).toBe('LOCALE_MISMATCH');
+    });
+    test('an absent reference with good provenance is unverifiable', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            render_locale: 'en',
+            provenance: { XProof: GOOD_PROV },
+        });
+        // No writeReference — the file is absent.
+        runScript(project, await buildScript());
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('unverifiable');
+        expect(screen?.error?.code).toBe('REFERENCE_ABSENT');
+    });
+    test('a good provenanced reference renders normally (a content diff is left to the judge)', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png' },
+            render_locale: 'en',
+            provenance: { XProof: GOOD_PROV },
+        });
+        writeReference(project, 'x.png');
+        const run = runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.error).toBeNull();
+    });
+    test('independent verdicts: a sibling stays rendered while one state is unverifiable', async () => {
+        const project = provProject({
+            screens: { XProof: 'x.png', YProof: 'y.png' },
+            render_locale: 'en',
+            provenance: { XProof: GOOD_PROV, YProof: { ...GOOD_PROV, resolved: false } },
+        });
+        writeReference(project, 'x.png');
+        writeReference(project, 'y.png');
+        runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        const doc = readResult(project);
+        expect(doc.screens.find((s) => s.screen === 'XProof')?.status).toBe('rendered');
+        const y = doc.screens.find((s) => s.screen === 'YProof');
+        expect(y?.status).toBe('unverifiable');
+        expect(y?.error?.code).toBe('UNRESOLVED_REFERENCE');
+    });
+    test('without a render_locale, provenance is not enforced (legacy behaviour)', async () => {
+        const project = provProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+    });
+});
 describe('android render runtime — error isolation', () => {
     function twoScreenProject() {
         const project = makeProject({ screens: { XProof: 'x.png', YProof: 'y.png' } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invarn/cibuild",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "CI Build CLI — local pipeline orchestration and validation",
   "type": "module",
   "main": "dist/cli.cjs",