@invarn/cibuild 2.4.0 → 2.4.2

package/dist/src/yaml/steps/render-post-processor.d.ts

@@ -52,6 +52,12 @@ export interface TrimDims {
 export interface TrimHelperInvocation {
     cmd: string;
     args: string[];
+    /** Child environment override. Set only for the pkg self-exec, where the
+     *  node-invoke sentinel (PKG_EXECPATH) must be stripped so the re-executed ci
+     *  binary runs its baked cli entrypoint (dispatching `fidelity-trim`) instead
+     *  of re-entering Node-emulation and treating it as a script path. Absent for
+     *  the other homes, which spawn with the inherited environment unchanged. */
+    env?: Record<string, string>;
 }
 /**
  * The platform-neutral helpers embedded in the trim-stage script.

package/dist/src/yaml/steps/render-post-processor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-post-processor.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/render-post-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,EAAE,MA+GtC,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAAC;IAC3D,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1F;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,CAAC,EAAE;IACpD,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,sBAAsB,CASzB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAqBhD"}
+{"version":3,"file":"render-post-processor.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/render-post-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAMH;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,EAAE,MA6HtC,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;iFAI6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAAC;IAC3D,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1F;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,CAAC,EAAE;IACpD,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,sBAAsB,CASzB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,IAAI,CAqBhD"}

package/dist/src/yaml/steps/render-post-processor.js

@@ -88,7 +88,22 @@ function trimHelperInvocation(args) {
     };
   }
   if (process.pkg) {
-    return { cmd: process.execPath, args: ['fidelity-trim'].concat(args) };
+    // The runner spawns this script as 'node <script>', which the pkg binary
+    // intercepts and runs in Node-emulation mode -- so process.env carries
+    // pkg's node-invoke sentinel (PKG_EXECPATH). Re-execing process.execPath
+    // with it still set makes the child ci binary ALSO enter Node-emulation and
+    // treat 'fidelity-trim' as a main-module script path (Cannot find module
+    // '<cwd>/fidelity-trim'), never reaching the subcommand dispatch -- so the
+    // trim silently fails and untrimmed renders ship. Strip PKG_EXECPATH from
+    // the child env so the re-exec runs the baked cli entrypoint, which routes
+    // 'fidelity-trim' to the in-binary helper (with bundled pngjs).
+    var invocation = { cmd: process.execPath, args: ['fidelity-trim'].concat(args) };
+    if (process.env.PKG_EXECPATH !== undefined) {
+      var appEnv = Object.assign({}, process.env);
+      delete appEnv.PKG_EXECPATH;
+      invocation.env = appEnv;
+    }
+    return invocation;
   }
   return { cmd: 'ci', args: ['fidelity-trim'].concat(args) };
 }
@@ -97,10 +112,9 @@ function trimHelperInvocation(args) {
 // stdout line, and exit codes are the retired CoreGraphics helper's contract).
 function runTrimHelper(args) {
   var invocation = trimHelperInvocation(args);
-  var result = cp.spawnSync(invocation.cmd, invocation.args, {
-    encoding: 'utf-8',
-    maxBuffer: 16 * 1024 * 1024,
-  });
+  var options = { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 };
+  if (invocation.env !== undefined) options.env = invocation.env;
+  var result = cp.spawnSync(invocation.cmd, invocation.args, options);
   if (result.stdout) process.stdout.write(result.stdout);
   if (result.stderr) process.stderr.write(result.stderr);
   if (result.error) {

package/dist/src/yaml/steps/render-post-processor.test.js

@@ -97,6 +97,56 @@ describe('trim stage — helper invocation resolution', () => {
             args: ['fidelity-trim', 'in.png', 'out.png'],
         });
     });
+    // The production runner spawns the render step as `node <script>`, which the
+    // pkg-built ci binary intercepts and runs in Node-emulation mode — so the
+    // running script's process.env carries pkg's node-invoke sentinel
+    // (PKG_EXECPATH). If the trim re-exec inherits it, the child ci binary ALSO
+    // enters Node-emulation and treats 'fidelity-trim' as a main-module script
+    // path ("Cannot find module '<cwd>/fidelity-trim'") instead of dispatching
+    // the subcommand — the exact failure observed in production, which silently
+    // ships untrimmed renders. The re-exec must clear PKG_EXECPATH so the binary
+    // runs its baked cli entrypoint.
+    test('under pkg node-emulation the re-exec clears PKG_EXECPATH so the binary runs its app entrypoint', () => {
+        const { trimHelperInvocation } = internalsWith({
+            env: { PKG_EXECPATH: 'PKG_INVOKE_NODEJS', PATH: '/usr/bin:/bin' },
+            pkg: {},
+            execPath: '/opt/homebrew/bin/ci',
+        });
+        const invocation = trimHelperInvocation(['in.png', 'out.png']);
+        expect(invocation.cmd).toBe('/opt/homebrew/bin/ci');
+        expect(invocation.args).toEqual(['fidelity-trim', 'in.png', 'out.png']);
+        // A child env is supplied with the node-invoke sentinel removed, but the
+        // rest of the environment (PATH, etc.) preserved.
+        expect(invocation.env).toBeDefined();
+        expect(invocation.env?.PKG_EXECPATH).toBeUndefined();
+        expect(invocation.env?.PATH).toBe('/usr/bin:/bin');
+    });
+    test('runTrimHelper spawns the pkg re-exec with a PKG_EXECPATH-cleared env', () => {
+        const calls = [];
+        const fakeCp = {
+            spawnSync: (...args) => {
+                calls.push(args);
+                return { status: 0, stdout: 'TRIMDIMS 10 10 0 0 10 10\n', stderr: '' };
+            },
+        };
+        const { runTrimHelper } = getPostProcessorInternals({
+            cp: fakeCp,
+            processRef: {
+                env: { PKG_EXECPATH: 'PKG_INVOKE_NODEJS', FOO: 'bar' },
+                pkg: {},
+                execPath: '/opt/homebrew/bin/ci',
+                stdout: { write: () => true },
+                stderr: { write: () => true },
+            },
+        });
+        runTrimHelper(['in.png', 'out.png']);
+        expect(calls).toHaveLength(1);
+        const [cmd, , options] = calls[0];
+        expect(cmd).toBe('/opt/homebrew/bin/ci');
+        expect(options.env).toBeDefined();
+        expect(options.env?.PKG_EXECPATH).toBeUndefined();
+        expect(options.env?.FOO).toBe('bar');
+    });
     test('runTrimHelper reports a spawn error as status 127 with the message appended', () => {
         const calls = [];
         const fakeCp = {

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

@@ -76,12 +76,16 @@ export interface UiFidelityRenderAndroidInputs {
  */
 export declare const DEFAULT_GRADLE_TASK = "recordRoborazziDebug";
 /** Valid values for the package_source input. */
-export declare const PACKAGE_SOURCES: readonly ["repo", "inputs"];
+export declare const PACKAGE_SOURCES: readonly ["repo", "inputs", "url"];
 export type PackageSource = (typeof PACKAGE_SOURCES)[number];
 /**
  * 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.
+ * "url" (fidelity-linux 03) downloads the same package.tar.gz from a signed
+ * package_url into the run-inputs directory and then proceeds byte-for-byte
+ * like inputs mode — the clone-free delivery for triggered runs, on macOS
+ * and Linux workers alike.
  */
 export declare const DEFAULT_PACKAGE_SOURCE: PackageSource;
 /** Valid values for the reference_source input. */
@@ -107,16 +111,23 @@ export interface AndroidRenderScriptConfig {
     scale: number;
     gradleTask: string;
     /**
-     * Only present (and only ever "repo") when package_source was explicitly set
-     * to "repo". When absent, the project ships as package.tar.gz and is
+     * Only present when package_source was explicitly set to a non-default mode
+     * ("repo" or "url"). When absent, the project ships as package.tar.gz and is
      * extracted/validated exactly as the default, byte-identical script.
      */
     packageSource?: PackageSource;
     /**
      * Repo-relative path to the committed Gradle project. Present (and required)
-     * only with packageSource "repo"; ignored otherwise.
+     * with packageSource "repo" (the checkout dir to render) and "url" (the
+     * prefix committed reference paths are resolved under, inside the extracted
+     * package); ignored otherwise.
      */
     packagePath?: string;
+    /**
+     * Signed download URL for package.tar.gz. Present (and required) only with
+     * packageSource "url"; ignored otherwise.
+     */
+    packageUrl?: string;
     /**
      * Only present (and only ever "repo") when reference_source was explicitly set
      * to "repo". When absent, references are read from `.ci/inputs/<basename>` and
@@ -138,7 +149,7 @@ export declare function generateAndroidRenderScript(config: AndroidRenderScriptC
  * script performs the render at runtime on the macOS runner.
  */
 export declare class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
-    getValidationRequirements(_inputs: UiFidelityRenderAndroidInputs, _env: Record<string, string>, _config: CIConfig): ValidationRequirement[];
+    getValidationRequirements(inputs: UiFidelityRenderAndroidInputs, _env: Record<string, string>, _config: CIConfig): ValidationRequirement[];
     execute(inputs: UiFidelityRenderAndroidInputs, _env: Record<string, string>, _config: CIConfig): Promise<StepDef>;
 }
 //# sourceMappingURL=ui-fidelity-render-android.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;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;AAMpE,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,iDAAiD;AACjD,eAAO,MAAM,eAAe,6BAA8B,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AAElE,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;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAuhCD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAqBrF;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;IAapB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CA0EpB"}
+{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;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;AAMpE,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,iDAAiD;AACjD,eAAO,MAAM,eAAe,oCAAqC,CAAC;AAClE,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AAElE,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;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAurCD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CA0BrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAyBpB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CAiGpB"}

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

@@ -63,11 +63,15 @@ import { RENDER_SCRIPT_SOURCE_DIGEST_STAGE } from '../fidelity-input-digest.js';
  */
 export const DEFAULT_GRADLE_TASK = 'recordRoborazziDebug';
 /** Valid values for the package_source input. */
-export const PACKAGE_SOURCES = ['repo', 'inputs'];
+export const PACKAGE_SOURCES = ['repo', 'inputs', 'url'];
 /**
  * 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.
+ * "url" (fidelity-linux 03) downloads the same package.tar.gz from a signed
+ * package_url into the run-inputs directory and then proceeds byte-for-byte
+ * like inputs mode — the clone-free delivery for triggered runs, on macOS
+ * and Linux workers alike.
  */
 export const DEFAULT_PACKAGE_SOURCE = 'inputs';
 /** Valid values for the reference_source input. */
@@ -1114,6 +1118,145 @@ function buildAndroidReferenceRepoMain(base) {
         '    }\n' +
         '    var source = path.resolve(refPath);');
 }
+/**
+ * Builds the runtime main for package_source "url" (fidelity-linux 03) by
+ * patching the default (inputs) runtime text. Three departures from the
+ * default, all forced by the same fact — a clone-free worker has no checkout:
+ *
+ * 1. The package is DOWNLOADED (curl, already a runner requirement in this
+ *    mode) to `.ci/inputs/package.tar.gz` and extracted BEFORE the per-screen
+ *    reference stage, because committed references travel inside it. A failed
+ *    download is one structured per-build error, never per-screen noise.
+ * 2. Each screen's reference is the committed repo-relative path resolved
+ *    INSIDE the extracted package: the path must sit under packagePath, and
+ *    the remainder resolves against the extracted project root.
+ * 3. The render stage reuses the already-extracted root (no second extract);
+ *    cleanup mirrors the inputs path. The result document records
+ *    package_source "url".
+ *
+ * ANDROID_RENDER_SCRIPT_MAIN itself is never modified, so omitting
+ * package_source keeps the generated script byte-identical to the default.
+ */
+function buildAndroidPackageUrlMain(base) {
+    let main = base;
+    // The result document advertises the url package source.
+    main = replaceOnce(main, "package_source: 'inputs',", "package_source: 'url',");
+    // Download + extract FIRST — the reference stage below reads from inside
+    // the extracted package.
+    main = replaceOnce(main, '  // 2. Per-screen validation + reference copies. Each screen gets its OWN copy\n' +
+        '  //    named by screen, even when two screens share a reference basename.\n' +
+        '  currentEntries.forEach(function (entry) {', '  // 2a. Download + extract the shipped package FIRST (URL mode): committed\n' +
+        '  //     references live inside it, so the per-screen reference copies below\n' +
+        '  //     need the extracted project root. A failed download or an invalid\n' +
+        '  //     archive is ONE structured per-build error; per-screen reference\n' +
+        '  //     work then stops cleanly (no bogus REFERENCE_MISSING noise).\n' +
+        '  var urlProjectRoot = null;\n' +
+        '  (function () {\n' +
+        '    try {\n' +
+        '      fs.mkdirSync(inputsDir, { recursive: true });\n' +
+        '    } catch (mkdirError) {\n' +
+        '      // statSync below reports the real failure\n' +
+        '    }\n' +
+        '    var dest = path.join(inputsDir, PACKAGE_ARCHIVE_NAME);\n' +
+        "    log('downloading render package');\n" +
+        '    var download = cp.spawnSync(\n' +
+        "      'curl',\n" +
+        "      ['-fsSL', '--retry', '2', '--max-time', '300', '-o', dest, CONFIG.packageUrl],\n" +
+        "      { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 }\n" +
+        '    );\n' +
+        '    if (download.error) {\n' +
+        '      download.status = download.status == null ? 127 : download.status;\n' +
+        "      download.stderr = (download.stderr || '') + String(download.error.message || download.error);\n" +
+        '    }\n' +
+        '    if (download.status !== 0) {\n' +
+        '      setBuildError(\n' +
+        "        'ANDROID_PACKAGE_DOWNLOAD_FAILED',\n" +
+        "        'render package download failed (curl exit ' + download.status + '):\\n' + outputTail(download)\n" +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    urlProjectRoot = prepareShippedProject();\n' +
+        '  })();\n' +
+        '\n' +
+        '  // 2. Per-screen validation + reference copies. Each screen gets its OWN copy\n' +
+        '  //    named by screen, even when two screens share a reference basename.\n' +
+        '  currentEntries.forEach(function (entry) {');
+    // References resolve INSIDE the extracted package: repo-relative path minus
+    // the packagePath prefix, against the extracted project root.
+    main = replaceOnce(main, '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' +
+        '    if (urlProjectRoot === null) {\n' +
+        '      // Package unavailable: the per-build error above carries the cause.\n' +
+        '      return;\n' +
+        '    }\n' +
+        "    var packagePrefix = CONFIG.packagePath.replace(/^\\.\\//, '').replace(/\\/+$/, '');\n" +
+        "    var normalizedRef = refPath.replace(/^\\.\\//, '');\n" +
+        "    if (normalizedRef.indexOf(packagePrefix + '/') !== 0) {\n" +
+        '      setError(\n' +
+        '        entry,\n' +
+        "        'REFERENCE_MISSING',\n" +
+        "        'reference for ' + entry.screen + ' must live inside the shipped package (' +\n" +
+        "          packagePrefix + '), got: ' + JSON.stringify(refPath)\n" +
+        '      );\n' +
+        '      return;\n' +
+        '    }\n' +
+        '    var source = path.join(urlProjectRoot, normalizedRef.slice(packagePrefix.length + 1));');
+    // Render from the package extracted in stage 2a — no second extract.
+    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. Render from the package downloaded + extracted in stage 2a. The\n' +
+        '  //    extraction already reported packaging mistakes as the per-build\n' +
+        '  //    error, so a null root here just skips the render.\n' +
+        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
+        '  try {\n' +
+        '    if (urlProjectRoot !== null) {\n' +
+        '      if (renderable.length > 0) {\n' +
+        '        renderScreens(renderable, urlProjectRoot);\n' +
+        '      } else if (currentEntries.length > 0) {\n' +
+        "        log('no renderable screens, skipping render');\n" +
+        '      }\n' +
+        '    }\n' +
+        '  } finally {\n' +
+        '    cleanupShippedProject();\n' +
+        '  }');
+    return main;
+}
+const ANDROID_RENDER_SCRIPT_MAIN_URL = buildAndroidPackageUrlMain(ANDROID_RENDER_SCRIPT_MAIN);
 /**
  * Generates the self-contained runtime node script for the step. Pure function
  * of its config — exported so tests can execute the script directly.
@@ -1123,10 +1266,15 @@ function buildAndroidReferenceRepoMain(base) {
  * runtime is used).
  */
 export function generateAndroidRenderScript(config) {
-    let main = config.packageSource === 'repo' ? ANDROID_RENDER_SCRIPT_MAIN_REPO : ANDROID_RENDER_SCRIPT_MAIN;
+    let main = config.packageSource === 'repo'
+        ? ANDROID_RENDER_SCRIPT_MAIN_REPO
+        : config.packageSource === 'url'
+            ? ANDROID_RENDER_SCRIPT_MAIN_URL
+            : 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).
+    // basename behaviour). URL mode embeds its own reference sourcing and the
+    // executor rejects the combination before this point.
     if (config.referenceSource === 'repo') {
         main = buildAndroidReferenceRepoMain(main);
     }
@@ -1148,13 +1296,19 @@ export function generateAndroidRenderScript(config) {
  * script performs the render at runtime on the macOS runner.
  */
 export class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
-    getValidationRequirements(_inputs, _env, _config) {
+    getValidationRequirements(inputs, _env, _config) {
         // No platform-toolchain requirement: trim/align is pure JS inside the ci
         // binary (fidelity-linux 06), so the step validates on macOS and Linux
         // runners alike.
-        return [
+        const requirements = [
             this.requireCommand('tar', 'Archive tool used to extract the shipped Gradle project', 'Install tar on the runner'),
         ];
+        // URL mode (fidelity-linux 03) downloads the package at runtime; existing
+        // inputs/repo runs gain no new requirement.
+        if (this.getInput(inputs, 'package_source', undefined) === 'url') {
+            requirements.push(this.requireCommand('curl', 'Downloader used to fetch the render package by signed URL', 'Install curl on the runner'));
+        }
+        return requirements;
     }
     async execute(inputs, _env, _config) {
         const stepName = 'ui-fidelity-render-android';
@@ -1165,9 +1319,11 @@ export class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
                 '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
+        // script for) the non-default modes 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).
+        // repo mode package_path is required (the committed project to render); in
+        // url mode (fidelity-linux 03) package_url and package_path are required
+        // (the signed download + the prefix committed reference paths sit under).
         const rawPackageSource = this.getInput(inputs, 'package_source', undefined);
         let packageSource;
         if (rawPackageSource !== undefined) {
@@ -1176,14 +1332,21 @@ export class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
                 throw new Error(`Invalid package_source '${value}' for step '${stepName}': ` +
                     `expected one of: ${PACKAGE_SOURCES.join(', ')}`);
             }
-            if (value === 'repo') {
-                packageSource = 'repo';
+            if (value === 'repo' || value === 'url') {
+                packageSource = value;
             }
         }
         let packagePath;
-        if (packageSource === 'repo') {
+        if (packageSource === 'repo' || packageSource === 'url') {
             packagePath = String(this.getRequiredInput(inputs, 'package_path', stepName));
         }
+        let packageUrl;
+        if (packageSource === 'url') {
+            packageUrl = String(this.getRequiredInput(inputs, 'package_url', stepName));
+            if (!/^https?:\/\//.test(packageUrl)) {
+                throw new Error(`Invalid package_url for step '${stepName}': expected an http(s) URL`);
+            }
+        }
         // 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.
@@ -1195,6 +1358,13 @@ export class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
                 throw new Error(`Invalid reference_source '${value}' for step '${stepName}': ` +
                     `expected one of: ${REFERENCE_SOURCES.join(', ')}`);
             }
+            // URL mode owns reference sourcing (inside the extracted package) —
+            // an explicit reference_source alongside it is a contradiction.
+            if (packageSource === 'url') {
+                throw new Error(`Invalid reference_source for step '${stepName}': ` +
+                    "package_source 'url' resolves references inside the downloaded " +
+                    'package; omit reference_source');
+            }
             if (value === 'repo') {
                 referenceSource = 'repo';
             }
@@ -1206,6 +1376,9 @@ export class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
         if (packagePath !== undefined) {
             config.packagePath = packagePath;
         }
+        if (packageUrl !== undefined) {
+            config.packageUrl = packageUrl;
+        }
         if (referenceSource !== undefined) {
             config.referenceSource = referenceSource;
         }

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

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import { gzipSync } from 'node:zlib';
 import { tmpdir } from 'node:os';
@@ -826,6 +826,161 @@ describe('package_source: repo', () => {
         expect(screen?.reference_image_path).toBe('ui-fidelity/references/XProof.png');
     });
 });
+// Clone-free package delivery (fidelity-linux 03): the dispatched YAML carries
+// a signed package_url; the runtime downloads it to .ci/inputs/package.tar.gz
+// and proceeds byte-for-byte like inputs mode, resolving each screen's
+// committed reference INSIDE the extracted package (repo-relative path minus
+// the package_path prefix) — there is no checkout on a clone-free worker.
+describe('package_source: url', () => {
+    /**
+     * Serve one tar.gz (or a 404) from a loopback HTTP server IN A CHILD
+     * PROCESS. runScript executes the generated script via spawnSync, which
+     * blocks this process's event loop — an in-process server would deadlock
+     * against the script's curl. The child prints its port once listening.
+     */
+    const SERVE_PACKAGE_SRC = [
+        "var http = require('http');",
+        "var fs = require('fs');",
+        'var filePath = process.argv[1];',
+        'var server = http.createServer(function (req, res) {',
+        "  if (filePath === '-') { res.statusCode = 404; res.end('gone'); return; }",
+        "  res.setHeader('content-type', 'application/gzip');",
+        '  res.end(fs.readFileSync(filePath));',
+        '});',
+        "server.listen(0, '127.0.0.1', function () {",
+        "  console.log('PORT ' + server.address().port);",
+        '});',
+    ].join('\n');
+    async function servePackage(archive) {
+        let filePath = '-';
+        if (archive !== null) {
+            const dir = mkdtempSync(join(tmpdir(), 'ui-fidelity-url-serve-'));
+            tempDirs.push(dir);
+            filePath = join(dir, 'package.tar.gz');
+            writeFileSync(filePath, archive);
+        }
+        const child = spawn('node', ['-e', SERVE_PACKAGE_SRC, filePath], {
+            stdio: ['ignore', 'pipe', 'inherit'],
+        });
+        const port = await new Promise((resolvePort, rejectPort) => {
+            let buffered = '';
+            const timer = setTimeout(() => rejectPort(new Error('package server did not start')), 10_000);
+            child.stdout.on('data', (chunk) => {
+                buffered += chunk.toString();
+                const match = /PORT (\d+)/.exec(buffered);
+                if (match) {
+                    clearTimeout(timer);
+                    resolvePort(Number(match[1]));
+                }
+            });
+            child.on('exit', () => rejectPort(new Error('package server exited early')));
+        });
+        return {
+            url: `http://127.0.0.1:${port}/api/fidelity/packages/blob1?exp=1&sig=ab`,
+            close: () => new Promise((resolveClose) => {
+                child.once('exit', () => resolveClose(undefined));
+                child.kill('SIGKILL');
+            }),
+        };
+    }
+    /** Archive shaped like the dashboard's assembly: package-dir contents at the
+     *  archive root, committed references under references/. */
+    function packagedProject() {
+        return makeTarGz([
+            ...gradleProjectEntries(''),
+            { name: 'references/x.png', content: Buffer.concat([PNG_MAGIC, Buffer.from('ref:url-x')]) },
+        ]);
+    }
+    test('package_source url requires package_url and package_path', async () => {
+        const executor = new UiFidelityRenderAndroidStepExecutor();
+        await expect(executor.execute({ package_source: 'url', package_path: 'android-app' }, {}, testConfig)).rejects.toThrow(/package_url/);
+        await expect(executor.execute({ package_source: 'url', package_url: 'https://x.test/p' }, {}, testConfig)).rejects.toThrow(/package_path/);
+    });
+    test('rejects reference_source alongside package_source url (URL mode owns references)', async () => {
+        const executor = new UiFidelityRenderAndroidStepExecutor();
+        await expect(executor.execute({
+            package_source: 'url',
+            package_url: 'https://x.test/p',
+            package_path: 'android-app',
+            reference_source: 'repo',
+        }, {}, testConfig)).rejects.toThrow(/reference_source/);
+    });
+    test('url mode requires curl on the runner (validation requirement)', () => {
+        const executor = new UiFidelityRenderAndroidStepExecutor();
+        const urlReqs = executor.getValidationRequirements({ package_source: 'url' }, {}, testConfig);
+        expect(urlReqs.some((r) => r.name === 'curl')).toBe(true);
+        // Default inputs mode keeps tar only — no new requirement for existing runs.
+        const defaultReqs = executor.getValidationRequirements({}, {}, testConfig);
+        expect(defaultReqs.some((r) => r.name === 'curl')).toBe(false);
+    });
+    test('downloads the package, renders, and resolves references inside it', async () => {
+        const project = makeProject({ screens: { XProof: 'android-app/references/x.png' } });
+        const served = await servePackage(packagedProject());
+        try {
+            const run = runScript(project, await buildScript({
+                package_source: 'url',
+                package_url: served.url,
+                package_path: 'android-app',
+            }), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+            expect(run.status).toBe(0);
+            const doc = readResult(project);
+            expect(doc.package_source).toBe('url');
+            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');
+            expect(isPng(artifact(project, 'ui-fidelity/references/XProof.png'))).toBe(true);
+        }
+        finally {
+            await served.close();
+        }
+    });
+    test('a failed download is one structured build error, not per-screen noise', async () => {
+        const project = makeProject({ screens: { XProof: 'android-app/references/x.png' } });
+        const served = await servePackage(null); // 404
+        try {
+            const run = runScript(project, await buildScript({
+                package_source: 'url',
+                package_url: served.url,
+                package_path: 'android-app',
+            }));
+            expect(run.status).not.toBe(0);
+            const doc = readResult(project);
+            expect(doc.error?.code).toBe('ANDROID_PACKAGE_DOWNLOAD_FAILED');
+            const screen = doc.screens.find((s) => s.screen === 'XProof');
+            // The failure is the build's, not the screen's — no bogus
+            // REFERENCE_MISSING masking the real cause.
+            expect(screen?.error).toBeNull();
+        }
+        finally {
+            await served.close();
+        }
+    });
+    test('a reference outside the package directory fails that screen only', async () => {
+        const project = makeProject({
+            screens: {
+                XProof: 'android-app/references/x.png',
+                Stray: 'design/elsewhere/stray.png',
+            },
+        });
+        const served = await servePackage(packagedProject());
+        try {
+            const run = runScript(project, await buildScript({
+                package_source: 'url',
+                package_url: served.url,
+                package_path: 'android-app',
+            }), { 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 stray = doc.screens.find((s) => s.screen === 'Stray');
+            expect(stray?.status).toBe('render_failed');
+            expect(stray?.error?.code).toBe('REFERENCE_MISSING');
+        }
+        finally {
+            await served.close();
+        }
+    });
+});
 describe('reference_source: repo', () => {
     test('rejects an unknown reference_source value', async () => {
         const executor = new UiFidelityRenderAndroidStepExecutor();