@invarn/cibuild 2.0.9 → 2.1.1

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

@@ -189,8 +189,13 @@ describe('renderUiFidelityPreviewAndroid — missing local toolchain', () => {
     test('reports a clear toolchain-missing build error instead of crashing', () => {
         const savedHome = process.env.ANDROID_HOME;
         const savedRoot = process.env.ANDROID_SDK_ROOT;
+        const savedUserHome = process.env.HOME;
         delete process.env.ANDROID_HOME;
         delete process.env.ANDROID_SDK_ROOT;
+        // Point HOME at an empty dir so the default-location auto-detect
+        // (~/Library/Android/sdk, ~/Android/Sdk) finds nothing — otherwise a dev
+        // machine with the SDK installed would resolve one and this guard wouldn't fire.
+        process.env.HOME = tempDir('ui-fidelity-android-emptyhome-');
         try {
             const result = renderUiFidelityPreviewAndroid({
                 packagePath: gradleProject(),
@@ -211,6 +216,52 @@ describe('renderUiFidelityPreviewAndroid — missing local toolchain', () => {
                 delete process.env.ANDROID_SDK_ROOT;
             else
                 process.env.ANDROID_SDK_ROOT = savedRoot;
+            if (savedUserHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = savedUserHome;
+        }
+    });
+    test('auto-detects the SDK at the default install location when ANDROID_HOME is unset', () => {
+        const savedHome = process.env.ANDROID_HOME;
+        const savedRoot = process.env.ANDROID_SDK_ROOT;
+        const savedUserHome = process.env.HOME;
+        const savedScreens = process.env.FAKE_ROBORAZZI_SCREENS;
+        delete process.env.ANDROID_HOME;
+        delete process.env.ANDROID_SDK_ROOT;
+        // A clean HOME with an SDK at the macOS default location, but no ANDROID_HOME.
+        const fakeHome = tempDir('ui-fidelity-android-home-');
+        mkdirSync(join(fakeHome, 'Library', 'Android', 'sdk'), { recursive: true });
+        process.env.HOME = fakeHome;
+        process.env.FAKE_ROBORAZZI_SCREENS = 'XProof';
+        try {
+            const result = renderUiFidelityPreviewAndroid({
+                packagePath: gradleProject(),
+                screens: [{ screen: 'XProof', reference: writeReference() }],
+                toolchainPath: fakeToolchain(),
+            });
+            // Auto-detected the SDK and rendered, rather than bailing with TOOLCHAIN_MISSING.
+            expect(result.buildError).toBeNull();
+            expect(result.ok).toBe(true);
+            expect(result.screens[0]?.status).toBe('rendered');
+        }
+        finally {
+            if (savedHome === undefined)
+                delete process.env.ANDROID_HOME;
+            else
+                process.env.ANDROID_HOME = savedHome;
+            if (savedRoot === undefined)
+                delete process.env.ANDROID_SDK_ROOT;
+            else
+                process.env.ANDROID_SDK_ROOT = savedRoot;
+            if (savedUserHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = savedUserHome;
+            if (savedScreens === undefined)
+                delete process.env.FAKE_ROBORAZZI_SCREENS;
+            else
+                process.env.FAKE_ROBORAZZI_SCREENS = savedScreens;
         }
     });
 });
@@ -218,7 +269,8 @@ describe('renderUiFidelityPreviewAndroid — missing local toolchain', () => {
 // toolchain and asserts a non-blank paired render at the expected size. Requires
 // the Android toolchain (JDK + SDK) and warm Roborazzi caches; gated behind
 // CIBUILD_UI_FIDELITY_REAL_ANDROID=1 (the Android analog of the iOS real-Swift
-// gate). It needs ANDROID_HOME set on the dev machine.
+// gate). ANDROID_HOME need not be exported — a standard SDK install at the
+// default location (~/Library/Android/sdk etc.) is auto-detected.
 describe('renderUiFidelityPreviewAndroid — real toolchain', () => {
     const realAndroidTest = process.env.CIBUILD_UI_FIDELITY_REAL_ANDROID === '1' ? test : test.skip;
     // A real, decodable 1x1 PNG so the trim helper's reference load/align succeeds.

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

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).
@@ -136,6 +145,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);
@@ -549,6 +606,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 {
@@ -600,7 +669,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',

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

@@ -286,6 +286,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.0.9",
+  "version": "2.1.1",
   "description": "CI Build CLI — local pipeline orchestration and validation",
   "type": "module",
   "main": "dist/cli.cjs",