@invarn/cibuild 2.2.6 → 2.2.8

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

@@ -51,11 +51,27 @@ 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, RENDER_SCRIPT_GEOMETRY_STAGE } from './structural-facts.js';
+import { RENDER_SCRIPT_SOURCE_DIGEST_STAGE } from '../fidelity-input-digest.js';
 /**
  * Default Roborazzi record task. Run from the project root so Gradle resolves
  * it in whichever subproject declares it.
  */
 export const DEFAULT_GRADLE_TASK = 'recordRoborazziDebug';
+/** Valid values for the package_source input. */
+export const PACKAGE_SOURCES = ['repo', 'inputs'];
+/**
+ * Default package source: the Gradle project ships as package.tar.gz in the
+ * run-inputs directory (the agent-upload path). "repo" instead renders the
+ * committed project at package_path, for a triggered (agent-less) run.
+ */
+export const DEFAULT_PACKAGE_SOURCE = 'inputs';
+/** Valid values for the reference_source input. */
+export const REFERENCE_SOURCES = ['repo', 'inputs'];
+/**
+ * Default reference source: references arrive as run inputs (a plain basename
+ * under `.ci/inputs`), matching the agent-upload path.
+ */
+export const DEFAULT_REFERENCE_SOURCE = 'inputs';
 /** Basename of the shipped Gradle-project archive inside the run-inputs dir. */
 export const PACKAGE_ARCHIVE_BASENAME = 'package.tar.gz';
 /** Renderer identifier recorded in protocol-result.json. */
@@ -532,6 +548,14 @@ function findRoborazziDirs(root) {
 // screen — the analog of the iOS probe gate). A screen whose PNG is absent
 // after a successful build is RENDER_FAILED on its own.
 function renderScreens(renderable, projectRoot) {
+  // Snapshot the package's input files BEFORE the build runs, so the digest is
+  // over the pristine committed source and never perturbed by build outputs.
+  var packageFiles = __fidCollectPackageFiles(projectRoot);
+  // A package is safely cacheable only when it is hermetic — no Gradle script
+  // reaches outside its own root. Then the package IS its whole dependency
+  // closure, so the content key cannot miss an external change. A non-hermetic
+  // package emits no digest, so a later dispatch never skips it.
+  var packageHermetic = __fidIsHermetic(packageFiles);
   var gradle = runGradle(projectRoot, CONFIG.gradleTask);
   if (gradle.status !== 0) {
     var detail = outputTail(gradle);
@@ -591,6 +615,20 @@ function renderScreens(renderable, projectRoot) {
       entry.rendered_image_path = relative;
       entry.status = 'rendered';
       entry.error = null;
+      // Content key over the package source + this screen's reference: lets a
+      // consumer skip a re-render whose inputs are unchanged. Emitted only for a
+      // hermetic package; otherwise omitted so no stale verdict can be replayed.
+      if (packageHermetic) {
+        var referenceBytes = null;
+        try {
+          if (entry.reference_image_path) {
+            referenceBytes = fs.readFileSync(path.resolve(artifactsDir, entry.reference_image_path));
+          }
+        } catch (digestReferenceError) {
+          referenceBytes = null;
+        }
+        entry.source_digest = __fidSourceDigest(packageFiles, referenceBytes);
+      }
       log('rendered ' + entry.screen + ' -> ' + relative);
       trimRenderedImage(entry, outputPath, workDir);
       // Signal A: the render emits a per-node layout dump into a roborazzi
@@ -863,11 +901,122 @@ try {
 }
 process.exit(exitCode);
 `;
+/**
+ * Replaces exactly one occurrence of `anchor` in `source`. Throws when the
+ * anchor is missing or ambiguous, so any drift between the default runtime text
+ * and a *_source variant fails loudly at module load.
+ */
+function replaceOnce(source, anchor, replacement) {
+    const first = source.indexOf(anchor);
+    if (first === -1 || source.indexOf(anchor, first + anchor.length) !== -1) {
+        throw new Error('ui-fidelity-render-android: expected exactly one occurrence of anchor: ' + anchor);
+    }
+    return source.slice(0, first) + replacement + source.slice(first + anchor.length);
+}
+/**
+ * Builds the runtime main for package_source "repo" by patching the default
+ * (inputs) runtime text: the result document records package_source "repo", and
+ * the project is resolved from the committed checkout at package_path instead of
+ * being extracted from a shipped tarball. ANDROID_RENDER_SCRIPT_MAIN itself is
+ * never modified, so omitting package_source keeps the generated script
+ * byte-identical to the default. Mirrors the iOS package_source patch.
+ */
+function buildAndroidPackageRepoMain(base) {
+    let main = base;
+    // The result document advertises the repo package source.
+    main = replaceOnce(main, "package_source: 'inputs',", "package_source: 'repo',");
+    // Render directly from the committed project at package_path; no archive
+    // extract/validate. A missing or non-Gradle directory is a clean per-build
+    // error (the same exit-on-buildError path the inputs archive validation uses).
+    main = replaceOnce(main, '  // 3. Extract + validate the shipped Gradle project, then render the\n' +
+        '  //    renderable screens. The project stage runs even when no screen is\n' +
+        '  //    renderable, so packaging mistakes are always reported.\n' +
+        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
+        '  try {\n' +
+        '    var projectRoot = prepareShippedProject();\n' +
+        '    if (projectRoot !== null) {\n' +
+        '      if (renderable.length > 0) {\n' +
+        '        renderScreens(renderable, projectRoot);\n' +
+        '      } else if (currentEntries.length > 0) {\n' +
+        "        log('no renderable screens, skipping render');\n" +
+        '      }\n' +
+        '    }\n' +
+        '  } finally {\n' +
+        '    cleanupShippedProject();\n' +
+        '  }', '  // 3. Resolve the committed Gradle project at package_path and render the\n' +
+        '  //    renderable screens directly from the checkout (no archive extract).\n' +
+        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
+        '  var projectRoot = path.resolve(CONFIG.packagePath);\n' +
+        '  registerPathReplacement(\n' +
+        '    projectRoot,\n' +
+        "    path.isAbsolute(CONFIG.packagePath) ? '<package_path>' : CONFIG.packagePath\n" +
+        '  );\n' +
+        '  if (!fs.existsSync(projectRoot)) {\n' +
+        "    setBuildError('ANDROID_PROJECT_MISSING', 'package_path does not exist: ' + projectRoot);\n" +
+        '  } else if (!hasSettings(projectRoot)) {\n' +
+        '    setBuildError(\n' +
+        "      'ANDROID_PROJECT_ROOT_MISSING',\n" +
+        "      'no settings.gradle(.kts) at the top of package_path: ' + projectRoot\n" +
+        '    );\n' +
+        '  } else if (renderable.length > 0) {\n' +
+        '    renderScreens(renderable, projectRoot);\n' +
+        '  } else if (currentEntries.length > 0) {\n' +
+        "    log('no renderable screens, skipping render');\n" +
+        '  }');
+    return main;
+}
+const ANDROID_RENDER_SCRIPT_MAIN_REPO = buildAndroidPackageRepoMain(ANDROID_RENDER_SCRIPT_MAIN);
+/**
+ * Patches the reference-sourcing block to read each screen's reference from a
+ * repo-relative path (resolved against the checkout) instead of a plain basename
+ * under `.ci/inputs/`. Mirrors the iOS reference_source: repo patch. The
+ * downstream stat/copy/provenance logic is unchanged; only how `source` is
+ * computed differs, so a triggered (agent-less) run can point at a committed
+ * reference that lives in the cloned repo.
+ */
+function buildAndroidReferenceRepoMain(base) {
+    return replaceOnce(base, 'var basename = params.screens[entry.screen];\n' +
+        '    if (\n' +
+        "      typeof basename !== 'string' || basename === '' ||\n" +
+        "      basename === '.' || basename === '..' ||\n" +
+        '      basename !== path.basename(basename)\n' +
+        '    ) {\n' +
+        '      setError(\n' +
+        '        entry,\n' +
+        "        'REFERENCE_MISSING',\n" +
+        "        'reference for ' + entry.screen + ' must be a plain file basename inside ' +\n" +
+        "          inputsDir + ', got: ' + JSON.stringify(basename)\n" +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    var source = path.join(inputsDir, basename);', 'var refPath = params.screens[entry.screen];\n' +
+        "    if (typeof refPath !== 'string' || refPath === '') {\n" +
+        '      setError(\n' +
+        '        entry,\n' +
+        "        'REFERENCE_MISSING',\n" +
+        "        'reference for ' + entry.screen + ' must be a non-empty repo-relative path, got: ' +\n" +
+        '          JSON.stringify(refPath)\n' +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    var source = path.resolve(refPath);');
+}
 /**
  * Generates the self-contained runtime node script for the step. Pure function
  * of its config — exported so tests can execute the script directly.
+ *
+ * When config.referenceSource is absent the reference block is byte-identical
+ * to the default (JSON.stringify drops the undefined key, and the unpatched
+ * runtime is used).
  */
 export function generateAndroidRenderScript(config) {
+    let main = config.packageSource === 'repo' ? ANDROID_RENDER_SCRIPT_MAIN_REPO : ANDROID_RENDER_SCRIPT_MAIN;
+    // Reference-from-repo is an independent dimension layered on top of whichever
+    // package base applies. Absent → byte-identical reference block (default
+    // basename behaviour).
+    if (config.referenceSource === 'repo') {
+        main = buildAndroidReferenceRepoMain(main);
+    }
     return [
         "'use strict';",
         '// ui-fidelity-render-android runtime script (generated by cibuild at YAML conversion time)',
@@ -877,7 +1026,8 @@ export function generateAndroidRenderScript(config) {
         RENDER_SCRIPT_TRIM_STAGE,
         RENDER_SCRIPT_FACTS_STAGE,
         RENDER_SCRIPT_GEOMETRY_STAGE,
-        ANDROID_RENDER_SCRIPT_MAIN,
+        RENDER_SCRIPT_SOURCE_DIGEST_STAGE,
+        main,
     ].join('\n');
 }
 /**
@@ -899,7 +1049,51 @@ export class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
             throw new Error(`Invalid gradle_task '${gradleTask}' for step '${stepName}': ` +
                 'expected a Gradle task path (letters, digits, and : - _)');
         }
+        // package_source: validate when provided, but only record (and patch the
+        // script for) the non-default "repo" so omitting it — or setting the default
+        // "inputs" — keeps the default archive-extract script byte-identical. In
+        // repo mode package_path is required (the committed project to render).
+        const rawPackageSource = this.getInput(inputs, 'package_source', undefined);
+        let packageSource;
+        if (rawPackageSource !== undefined) {
+            const value = String(rawPackageSource);
+            if (!PACKAGE_SOURCES.includes(value)) {
+                throw new Error(`Invalid package_source '${value}' for step '${stepName}': ` +
+                    `expected one of: ${PACKAGE_SOURCES.join(', ')}`);
+            }
+            if (value === 'repo') {
+                packageSource = 'repo';
+            }
+        }
+        let packagePath;
+        if (packageSource === 'repo') {
+            packagePath = String(this.getRequiredInput(inputs, 'package_path', stepName));
+        }
+        // reference_source: validate when provided, but only record (and patch the
+        // script for) the non-default "repo" so omitting it — or setting the default
+        // "inputs" — keeps the default basename reference block intact.
+        const rawReferenceSource = this.getInput(inputs, 'reference_source', undefined);
+        let referenceSource;
+        if (rawReferenceSource !== undefined) {
+            const value = String(rawReferenceSource);
+            if (!REFERENCE_SOURCES.includes(value)) {
+                throw new Error(`Invalid reference_source '${value}' for step '${stepName}': ` +
+                    `expected one of: ${REFERENCE_SOURCES.join(', ')}`);
+            }
+            if (value === 'repo') {
+                referenceSource = 'repo';
+            }
+        }
         const config = { scale, gradleTask };
+        if (packageSource !== undefined) {
+            config.packageSource = packageSource;
+        }
+        if (packagePath !== undefined) {
+            config.packagePath = packagePath;
+        }
+        if (referenceSource !== undefined) {
+            config.referenceSource = referenceSource;
+        }
         const script = generateAndroidRenderScript(config);
         return this.createNodeStep(script, stepName);
     }

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

@@ -4,7 +4,10 @@ import { gzipSync } from 'node:zlib';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { ANDROID_RENDERER, UiFidelityRenderAndroidStepExecutor, } from './ui-fidelity-render-android.js';
+import { ANDROID_RENDERER, DEFAULT_GRADLE_TASK, UiFidelityRenderAndroidStepExecutor, } from './ui-fidelity-render-android.js';
+import { DEFAULT_SCALE } from './ui-fidelity-render.js';
+import { clearRegistry, getStepMetadata, hasStep } from './registry.js';
+import { initializeStepRegistry } from './index.js';
 import { testConfig } from './test-config.js';
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const tempDirs = [];
@@ -166,6 +169,48 @@ function runScript(project, script, env = {}) {
 function readResult(project) {
     return JSON.parse(readFileSync(join(project.dir, '.ci', 'artifacts', 'protocol-result.json'), 'utf-8'));
 }
+describe('registry integration', () => {
+    test('ui-fidelity-render-android is registered with its input schema', () => {
+        clearRegistry();
+        initializeStepRegistry();
+        expect(hasStep('ui-fidelity-render-android')).toBe(true);
+        const metadata = getStepMetadata('ui-fidelity-render-android');
+        expect(metadata?.platform).toBe('android');
+        const inputs = metadata?.inputs ?? {};
+        expect(Object.keys(inputs).sort()).toEqual([
+            'gradle_task',
+            'package_path',
+            'package_source',
+            'reference_source',
+            'scale',
+        ]);
+        expect(inputs.package_source.required).toBe(false);
+        expect(inputs.package_source.default).toBe('inputs');
+        expect(inputs.reference_source.required).toBe(false);
+        expect(inputs.reference_source.default).toBe('inputs');
+        // package_path is enforced by the executor only in repo mode; the default
+        // (inputs) config is valid without it, so it is not unconditionally required.
+        expect(inputs.package_path.required).toBe(false);
+        expect(inputs.scale.required).toBe(false);
+        expect(inputs.scale.default).toBe(DEFAULT_SCALE);
+        expect(inputs.gradle_task.required).toBe(false);
+        expect(inputs.gradle_task.default).toBe(DEFAULT_GRADLE_TASK);
+    });
+});
+describe('default byte compatibility', () => {
+    // Snapshot of the script generated for the default inputs (no package_source,
+    // no reference_source), captured from the executor with everything else at its
+    // default. Omitting both *_source inputs must keep the generated script
+    // byte-identical to this snapshot, so existing protocols are provably
+    // untouched. Update the snapshot only for a deliberate, reviewed change to the
+    // default runtime.
+    const DEFAULT_SCRIPT_SNAPSHOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../../test/fixtures/ui-fidelity-render-android-v1-script.txt');
+    test('omitting package_source and reference_source generates a byte-identical script', async () => {
+        const executor = new UiFidelityRenderAndroidStepExecutor();
+        const step = await executor.execute({}, {}, testConfig);
+        expect(step.script).toBe(readFileSync(DEFAULT_SCRIPT_SNAPSHOT, 'utf-8'));
+    });
+});
 describe('UiFidelityRenderAndroidStepExecutor', () => {
     test('returns a node StepDef named ui-fidelity-render-android', async () => {
         const executor = new UiFidelityRenderAndroidStepExecutor();
@@ -315,6 +360,34 @@ describe('android render runtime — render + trim (happy path)', () => {
             ],
         });
     });
+    test('emits a source_digest content key on a rendered screen entry', 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',
+        });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.source_digest).toMatch(/^[0-9a-f]{64}$/);
+    });
+    test('omits source_digest for a non-hermetic package (Gradle script escapes the root)', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        // A settings script that pulls in a sibling build via a parent path — the
+        // package is no longer its own dependency closure, so it must not be
+        // cacheable: it still renders, but emits no content key.
+        const entries = gradleProjectEntries().map((e) => e.name.endsWith('settings.gradle.kts')
+            ? { ...e, content: 'rootProject.name = "p"\ninclude(":proof")\nincludeBuild("../design-system")\n' }
+            : e);
+        stageArchive(project, entries);
+        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?.source_digest == null).toBe(true);
+    });
     test('assembles the inline structural block (facts) onto the screen entry', async () => {
         const project = makeProject({ screens: { XProof: 'x.png' } });
         writeReference(project, 'x.png');
@@ -541,6 +614,139 @@ describe('android render runtime — error isolation', () => {
         expect(y?.error?.code).toBe('RENDER_FAILED');
     });
 });
+/** Materialize a well-formed Gradle render project (fake gradlew) on disk. */
+function writeGradleProjectDir(dir) {
+    mkdirSync(join(dir, 'proof'), { recursive: true });
+    writeFileSync(join(dir, 'settings.gradle.kts'), 'rootProject.name = "p"\ninclude(":proof")\n');
+    const gradlew = join(dir, 'gradlew');
+    writeFileSync(gradlew, FAKE_GRADLEW_LINES.join('\n') + '\n');
+    chmodSync(gradlew, 0o755);
+    writeFileSync(join(dir, 'proof', 'build.gradle.kts'), '// module\n');
+}
+describe('package_source: repo', () => {
+    test('rejects an unknown package_source value', async () => {
+        const executor = new UiFidelityRenderAndroidStepExecutor();
+        await expect(executor.execute({ package_source: 'cloud' }, {}, testConfig)).rejects.toThrow(/package_source/);
+    });
+    test('package_source repo requires package_path', async () => {
+        const executor = new UiFidelityRenderAndroidStepExecutor();
+        await expect(executor.execute({ package_source: 'repo' }, {}, testConfig)).rejects.toThrow(/package_path/);
+    });
+    test('omitting package_source bakes no packageSource/packagePath into the config', async () => {
+        const script = await buildScript();
+        const configLine = script.split('\n').find((l) => l.startsWith('var CONFIG = '));
+        expect(configLine).toBeDefined();
+        expect(configLine).not.toContain('packageSource');
+        expect(configLine).not.toContain('packagePath');
+    });
+    test('renders the checked-out Gradle project at package_path (no archive)', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        // The committed project lives at a repo-relative path; no package.tar.gz.
+        writeGradleProjectDir(join(project.dir, 'android-app'));
+        const run = runScript(project, await buildScript({ package_source: 'repo', package_path: 'android-app' }), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
+        const doc = readResult(project);
+        expect(doc.package_source).toBe('repo');
+        expect(doc.error).toBeNull();
+        const screen = doc.screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.rendered_image_path).toBe('ui-fidelity/rendered/XProof.png');
+        // The render came from the checkout, not an extracted tarball.
+        expect(existsSync(join(project.dir, '.ci', 'inputs', 'package.tar.gz'))).toBe(false);
+    });
+    test('a missing package_path directory fails cleanly with a per-build error', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        // No project at the path.
+        const run = runScript(project, await buildScript({ package_source: 'repo', package_path: 'nope' }), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(1);
+        const doc = readResult(project);
+        expect(doc.package_source).toBe('repo');
+        expect(doc.error?.code).toBe('ANDROID_PROJECT_MISSING');
+    });
+    test('a package_path without a settings script fails cleanly', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        // A directory that is not a Gradle project root.
+        mkdirSync(join(project.dir, 'not-a-project'), { recursive: true });
+        writeFileSync(join(project.dir, 'not-a-project', 'README.md'), '# nope\n');
+        const run = runScript(project, await buildScript({ package_source: 'repo', package_path: 'not-a-project' }), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(1);
+        expect(readResult(project).error?.code).toBe('ANDROID_PROJECT_ROOT_MISSING');
+    });
+    test('composes with reference_source repo (project + reference both from the checkout)', async () => {
+        const project = makeProject({ screens: { XProof: 'refs/x.png' } });
+        mkdirSync(join(project.dir, 'refs'), { recursive: true });
+        writeFileSync(join(project.dir, 'refs', 'x.png'), Buffer.concat([PNG_MAGIC, Buffer.from('ref:x')]));
+        writeGradleProjectDir(join(project.dir, 'android-app'));
+        const run = runScript(project, await buildScript({
+            package_source: 'repo',
+            package_path: 'android-app',
+            reference_source: 'repo',
+        }), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
+        const doc = readResult(project);
+        expect(doc.package_source).toBe('repo');
+        const screen = doc.screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.reference_image_path).toBe('ui-fidelity/references/XProof.png');
+    });
+});
+describe('reference_source: repo', () => {
+    test('rejects an unknown reference_source value', async () => {
+        const executor = new UiFidelityRenderAndroidStepExecutor();
+        await expect(executor.execute({ reference_source: 'artifact' }, {}, testConfig)).rejects.toThrow(/reference_source/);
+    });
+    test('omitting reference_source bakes no referenceSource into the script config', async () => {
+        const script = await buildScript();
+        const configLine = script.split('\n').find((l) => l.startsWith('var CONFIG = '));
+        expect(configLine).toBeDefined();
+        expect(configLine).not.toContain('referenceSource');
+    });
+    test('reads each screen reference from its repo-relative path in the checkout', async () => {
+        const project = makeProject({
+            screens: { XProof: 'refs/x.png', YProof: 'design/y.png' },
+        });
+        // Committed references live at repo-relative paths (resolved against cwd),
+        // NOT in .ci/inputs.
+        mkdirSync(join(project.dir, 'refs'), { recursive: true });
+        mkdirSync(join(project.dir, 'design'), { recursive: true });
+        writeFileSync(join(project.dir, 'refs', 'x.png'), Buffer.concat([PNG_MAGIC, Buffer.from('ref:x')]));
+        writeFileSync(join(project.dir, 'design', 'y.png'), Buffer.concat([PNG_MAGIC, Buffer.from('ref:y')]));
+        stageArchive(project, gradleProjectEntries());
+        const run = runScript(project, await buildScript({ reference_source: 'repo' }), {
+            FAKE_ROBORAZZI_SCREENS: 'XProof,YProof',
+        });
+        expect(run.status).toBe(0);
+        const doc = readResult(project);
+        expect(doc.screens.map((s) => s.status)).toEqual(['rendered', 'rendered']);
+        expect(doc.screens.map((s) => s.reference_image_path)).toEqual([
+            'ui-fidelity/references/XProof.png',
+            'ui-fidelity/references/YProof.png',
+        ]);
+        expect(isPng(artifact(project, 'ui-fidelity/references/XProof.png'))).toBe(true);
+        expect(isPng(artifact(project, 'ui-fidelity/references/YProof.png'))).toBe(true);
+    });
+    test('fails one screen when its committed reference is missing, renders the rest', async () => {
+        const project = makeProject({
+            screens: { XProof: 'refs/x.png', GhostProof: 'refs/ghost.png' },
+        });
+        mkdirSync(join(project.dir, 'refs'), { recursive: true });
+        writeFileSync(join(project.dir, 'refs', 'x.png'), Buffer.concat([PNG_MAGIC, Buffer.from('ref:x')]));
+        // refs/ghost.png intentionally absent.
+        stageArchive(project, gradleProjectEntries());
+        const run = runScript(project, await buildScript({ reference_source: 'repo' }), {
+            FAKE_ROBORAZZI_SCREENS: 'XProof',
+        });
+        expect(run.status).not.toBe(0);
+        const doc = readResult(project);
+        expect(doc.screens.find((s) => s.screen === 'XProof')?.status).toBe('rendered');
+        const ghost = doc.screens.find((s) => s.screen === 'GhostProof');
+        expect(ghost?.status).toBe('render_failed');
+        expect(ghost?.error?.code).toBe('REFERENCE_MISSING');
+    });
+});
 // The fake gradlew/swift cannot exercise the real Roborazzi/Robolectric render
 // or the CoreGraphics trim. This end-to-end guard ships the committed Roborazzi
 // fixture as the render package and runs the whole step with the real

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

@@ -75,6 +75,16 @@ export interface UiFidelityRenderInputs {
      * product.
      */
     target?: string;
+    /**
+     * Where each screen's reference image comes from (default "inputs"):
+     * - "inputs" (default / v1): `params.screens[<Screen>]` is a plain file
+     *   basename read from `.ci/inputs/<basename>` (an agent-uploaded run input).
+     * - "repo": `params.screens[<Screen>]` is a repo-relative path to a COMMITTED
+     *   reference image, resolved against the checkout. Lets a triggered
+     *   (agent-less) run point at a reference that lives in the cloned repo.
+     *   Omitting reference_source generates a byte-identical v1 script.
+     */
+    reference_source?: 'repo' | 'inputs';
     /** Render size in device points, formatted "<width>x<height>" (default 393x852) */
     render_size?: string;
     /** Display scale factor applied to the render (default 2) */
@@ -94,6 +104,11 @@ export declare const PACKAGE_SOURCES: readonly ["repo", "inputs"];
 export type PackageSource = (typeof PACKAGE_SOURCES)[number];
 /** Default package source: the package lives in the repo checkout. */
 export declare const DEFAULT_PACKAGE_SOURCE: PackageSource;
+/** Valid values for the reference_source input. */
+export declare const REFERENCE_SOURCES: readonly ["repo", "inputs"];
+export type ReferenceSource = (typeof REFERENCE_SOURCES)[number];
+/** Default reference source: references arrive as run inputs (v1 behaviour). */
+export declare const DEFAULT_REFERENCE_SOURCE: ReferenceSource;
 /** Basename of the shipped package archive inside the run-inputs directory. */
 export declare const PACKAGE_ARCHIVE_BASENAME = "package.tar.gz";
 /**
@@ -140,6 +155,12 @@ export interface RenderScriptConfig {
     height: number;
     scale: number;
     packageSource?: PackageSource;
+    /**
+     * Only present (and only ever "repo") when reference_source was explicitly set
+     * to "repo". When absent, references are read from `.ci/inputs/<basename>` and
+     * the generated reference-sourcing code is byte-identical to v1.
+     */
+    referenceSource?: ReferenceSource;
 }
 /** Options consumed by the pure Swift-source generators. */
 export interface HarnessGeneratorOptions {

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

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-render.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ui-fidelity-render.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render.ts"],"names":[],"mappings":"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"}