@invarn/cibuild 2.0.1 → 2.0.3

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

@@ -28,8 +28,25 @@
  *
  * protocol-result.json contains relative paths only: image paths are relative
  * to the artifacts dir, and error messages are sanitized so absolute runner
- * paths (resolved package_path, harness temp dir, compiler diagnostics) are
- * rewritten to relative paths or placeholders before they are stored.
+ * paths (resolved package_path, harness temp dir, extracted shipped package,
+ * compiler diagnostics) are rewritten to relative paths or placeholders
+ * before they are stored.
+ *
+ * The package_source input picks where the SwiftPM package comes from:
+ *   - "repo" (default): the package lives in the checkout at package_path.
+ *     Omitting the input generates a byte-identical script to the original
+ *     step (locked by a snapshot test), and the result document keeps its
+ *     original { renderer, screens } shape.
+ *   - "inputs": the caller ships the package as .ci/inputs/package.tar.gz.
+ *     The archive is extracted into a scratch directory and validated
+ *     (single package root, Package.swift at its top, bounded extracted
+ *     size); rendering then proceeds exactly as in repo mode. Validation
+ *     failures are per-build structured errors (PACKAGE_ARCHIVE_MISSING,
+ *     PACKAGE_ARCHIVE_INVALID, PACKAGE_MANIFEST_MISSING,
+ *     PACKAGE_ARCHIVE_TOO_LARGE, PACKAGE_TARGET_UNRESOLVED) recorded as a
+ *     top-level error object in the result document, distinct from
+ *     per-screen render errors. With an explicit package_source the result
+ *     document is { renderer, package_source, error, screens }.
  */
 import { BaseStepExecutor } from './base.js';
 /**
@@ -41,6 +58,21 @@ import { BaseStepExecutor } from './base.js';
 export const DEFAULT_RENDER_SIZE = '393x852';
 /** Default display scale (@2x), matching how references are typically exported. */
 export const DEFAULT_SCALE = 2;
+/** Valid values for the package_source input. */
+export const PACKAGE_SOURCES = ['repo', 'inputs'];
+/** Default package source: the package lives in the repo checkout. */
+export const DEFAULT_PACKAGE_SOURCE = 'repo';
+/** Basename of the shipped package archive inside the run-inputs directory. */
+export const PACKAGE_ARCHIVE_BASENAME = 'package.tar.gz';
+/**
+ * Default cap on the extracted size of a shipped package archive (32 MiB),
+ * overridable at runtime via UI_FIDELITY_MAX_PACKAGE_BYTES. The archive
+ * arrives through a size-limited dispatch channel (256 KiB), and gzip tops
+ * out around a 1000:1 ratio, so this bound is a decompression-bomb guard
+ * with enormous headroom for legitimate source slices, which are typically
+ * well under 1 MiB extracted.
+ */
+export const DEFAULT_MAX_EXTRACTED_BYTES = 32 * 1024 * 1024;
 /**
  * Parses a "<width>x<height>" render size string (device points).
  * @throws Error when the value is malformed or non-positive
@@ -555,6 +587,485 @@ try {
 }
 process.exit(exitCode);
 `;
+/**
+ * Runtime support for package_source "inputs": locating, extracting, and
+ * validating the shipped archive, plus target discovery from its manifest.
+ * Inserted into the runtime script only when package_source is explicitly
+ * configured. Plain dependency-free CJS; must not contain backticks, "${",
+ * or bare $UPPERCASE tokens (the pre-execution validator would parse those
+ * as variable references).
+ */
+const RENDER_SCRIPT_PACKAGE_STAGE = String.raw `
+// ---- shipped-package stage (package_source: "inputs") ----
+//
+// The caller ships a SwiftPM package as .ci/inputs/package.tar.gz. Before
+// any rendering, the archive is located, extracted into a scratch
+// directory, and validated. Failures here are PER-BUILD structured errors,
+// recorded as the result document's top-level error object -- distinct from
+// per-screen render errors, which keep their v1 semantics. The extracted
+// size is bounded as a decompression-bomb guard.
+
+var PACKAGE_ARCHIVE_NAME = 'package.tar.gz';
+var DEFAULT_MAX_EXTRACTED_BYTES = 32 * 1024 * 1024;
+var maxExtractedBytes =
+  Number(process.env.UI_FIDELITY_MAX_PACKAGE_BYTES || '') || DEFAULT_MAX_EXTRACTED_BYTES;
+
+var buildError = null;
+var activeTarget = CONFIG.target;
+var shippedExtractDir = null;
+
+function setBuildError(code, message) {
+  buildError = { code: code, message: sanitizeMessage(message) };
+  logError(code + ': ' + buildError.message);
+}
+
+function runTar(args) {
+  var result = cp.spawnSync('tar', args, {
+    encoding: 'utf-8',
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.error) {
+    result.status = result.status == null ? 127 : result.status;
+    result.stderr =
+      (result.stderr || '') + String(result.error.message || result.error);
+  }
+  return result;
+}
+
+function isUnsafeArchiveMember(name) {
+  if (name.charAt(0) === '/') return true;
+  var segments = name.split('/');
+  for (var i = 0; i < segments.length; i++) {
+    if (segments[i] === '..') return true;
+  }
+  return false;
+}
+
+function extractedSize(dir) {
+  var total = 0;
+  var stack = [dir];
+  while (stack.length > 0) {
+    var current = stack.pop();
+    var names = fs.readdirSync(current);
+    for (var i = 0; i < names.length; i++) {
+      var entryPath = path.join(current, names[i]);
+      var stat = fs.lstatSync(entryPath);
+      if (stat.isDirectory()) stack.push(entryPath);
+      else total += stat.size;
+    }
+  }
+  return total;
+}
+
+// Entries that macOS archiving tools add but that say nothing about the
+// package layout are ignored when locating the package root.
+function isJunkEntry(name) {
+  return name === '.DS_Store' || name === '__MACOSX' || name.indexOf('._') === 0;
+}
+
+function hasManifest(dir) {
+  try {
+    return fs.statSync(path.join(dir, 'Package.swift')).isFile();
+  } catch (statError) {
+    return false;
+  }
+}
+
+// Package-root rule: Package.swift at the extraction root wins; otherwise
+// exactly one top-level directory with Package.swift at its top is the
+// root; anything else is a structured per-build error.
+function findPackageRoot(extractDir) {
+  if (hasManifest(extractDir)) return extractDir;
+  var entries = fs.readdirSync(extractDir).filter(function (name) {
+    return !isJunkEntry(name);
+  });
+  if (entries.length === 0) {
+    setBuildError('PACKAGE_ARCHIVE_INVALID', PACKAGE_ARCHIVE_NAME + ' is empty');
+    return null;
+  }
+  if (entries.length > 1) {
+    setBuildError(
+      'PACKAGE_ARCHIVE_INVALID',
+      PACKAGE_ARCHIVE_NAME + ' must contain a single package root; found ' +
+        entries.length + ' top-level entries (' + entries.sort().join(', ') +
+        ') and no Package.swift at the archive root'
+    );
+    return null;
+  }
+  var rootPath = path.join(extractDir, entries[0]);
+  if (!fs.statSync(rootPath).isDirectory()) {
+    setBuildError(
+      'PACKAGE_ARCHIVE_INVALID',
+      PACKAGE_ARCHIVE_NAME + ' must contain a package directory; its only ' +
+        'top-level entry (' + entries[0] + ') is not a directory'
+    );
+    return null;
+  }
+  if (!hasManifest(rootPath)) {
+    setBuildError(
+      'PACKAGE_MANIFEST_MISSING',
+      'no Package.swift at the top of the package root (' + entries[0] + ') in ' +
+        PACKAGE_ARCHIVE_NAME
+    );
+    return null;
+  }
+  return rootPath;
+}
+
+// When no target input is configured, the target is discovered from the
+// shipped package's manifest: the package must declare exactly one library
+// product. The harness depends on the package via .product(name:package:),
+// so library products are the unit of discovery.
+function resolveTargetFromManifest(packageRoot) {
+  var dump = runSwift(['package', '--package-path', packageRoot, 'dump-package']);
+  if (dump.status !== 0) {
+    setBuildError(
+      'PACKAGE_TARGET_UNRESOLVED',
+      'could not read the shipped package manifest (swift package dump-package failed):\n' +
+        outputTail(dump)
+    );
+    return null;
+  }
+  var manifest = null;
+  try {
+    manifest = JSON.parse(dump.stdout);
+  } catch (parseError) {
+    setBuildError(
+      'PACKAGE_TARGET_UNRESOLVED',
+      'swift package dump-package produced unparseable output: ' +
+        (parseError && parseError.message ? parseError.message : String(parseError))
+    );
+    return null;
+  }
+  var libraries = ((manifest && manifest.products) || [])
+    .filter(function (product) {
+      return product && product.type && typeof product.type === 'object' &&
+        'library' in product.type;
+    })
+    .map(function (product) { return String(product.name); });
+  if (libraries.length === 0) {
+    setBuildError(
+      'PACKAGE_TARGET_UNRESOLVED',
+      'the shipped package declares no library products; declare exactly one ' +
+        'library product, or set the target input'
+    );
+    return null;
+  }
+  if (libraries.length > 1) {
+    setBuildError(
+      'PACKAGE_TARGET_UNRESOLVED',
+      'the shipped package declares ' + libraries.length + ' library products (' +
+        libraries.sort().join(', ') + '); set the target input to pick one'
+    );
+    return null;
+  }
+  if (!SWIFT_IDENTIFIER.test(libraries[0])) {
+    setBuildError(
+      'PACKAGE_TARGET_UNRESOLVED',
+      'discovered library product ' + JSON.stringify(libraries[0]) +
+        ' is not a valid Swift module identifier'
+    );
+    return null;
+  }
+  return libraries[0];
+}
+
+// Locates, extracts, and validates the shipped archive. Returns the package
+// root to build from, or null after recording a structured build error.
+function prepareShippedPackage() {
+  var archivePath = path.join(inputsDir, PACKAGE_ARCHIVE_NAME);
+  var archiveStat = null;
+  try {
+    archiveStat = fs.statSync(archivePath);
+  } catch (statError) {
+    archiveStat = null;
+  }
+  if (!archiveStat || !archiveStat.isFile()) {
+    setBuildError(
+      'PACKAGE_ARCHIVE_MISSING',
+      'no ' + PACKAGE_ARCHIVE_NAME + ' in ' + inputsDir + '; ship the SwiftPM ' +
+        'package as a run input named ' + PACKAGE_ARCHIVE_NAME
+    );
+    return null;
+  }
+
+  // bsdtar and GNU tar both refuse absolute and dot-dot member paths by
+  // default; the listing is checked explicitly anyway so the guard does not
+  // depend on the host tar implementation. A failed listing also catches
+  // unreadable or corrupt archives before anything touches the disk.
+  var listing = runTar(['-tzf', archivePath]);
+  if (listing.status !== 0) {
+    setBuildError(
+      'PACKAGE_ARCHIVE_INVALID',
+      PACKAGE_ARCHIVE_NAME + ' is not a readable gzipped tar archive:\n' +
+        outputTail(listing)
+    );
+    return null;
+  }
+  var members = (listing.stdout || '').split('\n').filter(function (name) {
+    return name !== '';
+  });
+  var unsafe = members.filter(isUnsafeArchiveMember);
+  if (unsafe.length > 0) {
+    setBuildError(
+      'PACKAGE_ARCHIVE_INVALID',
+      PACKAGE_ARCHIVE_NAME + ' contains unsafe member paths (absolute or dot-dot): ' +
+        unsafe.slice(0, 5).join(', ')
+    );
+    return null;
+  }
+
+  shippedExtractDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ui-fidelity-package-'));
+  registerPathReplacement(shippedExtractDir, '<package>');
+  log('extracting ' + PACKAGE_ARCHIVE_NAME + ' (' + archiveStat.size + ' bytes)');
+  var extraction = runTar(['-xzf', archivePath, '-C', shippedExtractDir]);
+  if (extraction.status !== 0) {
+    setBuildError(
+      'PACKAGE_ARCHIVE_INVALID',
+      PACKAGE_ARCHIVE_NAME + ' could not be extracted:\n' + outputTail(extraction)
+    );
+    return null;
+  }
+
+  var totalBytes = extractedSize(shippedExtractDir);
+  if (totalBytes > maxExtractedBytes) {
+    setBuildError(
+      'PACKAGE_ARCHIVE_TOO_LARGE',
+      PACKAGE_ARCHIVE_NAME + ' extracts to ' + totalBytes + ' bytes, over the ' +
+        maxExtractedBytes + '-byte limit; ship a leaner source slice'
+    );
+    return null;
+  }
+
+  var packageRoot = findPackageRoot(shippedExtractDir);
+  if (packageRoot === null) return null;
+  var rootLabel = path.relative(shippedExtractDir, packageRoot);
+  log('package root: ' + (rootLabel === '' ? '.' : rootLabel));
+
+  if (activeTarget === null) {
+    var discovered = resolveTargetFromManifest(packageRoot);
+    if (discovered === null) return null;
+    log('discovered library target: ' + discovered);
+    activeTarget = discovered;
+  }
+  return packageRoot;
+}
+
+function cleanupShippedPackage() {
+  if (shippedExtractDir === null) return;
+  if (process.env.UI_FIDELITY_KEEP_HARNESS) {
+    log('keeping extracted package (UI_FIDELITY_KEEP_HARNESS set)');
+    return;
+  }
+  try {
+    fs.rmSync(shippedExtractDir, { recursive: true, force: true });
+  } catch (cleanupError) {
+    // best effort
+  }
+  shippedExtractDir = null;
+}
+`;
+/**
+ * Runtime support for asset catalogs (package_source variants only).
+ *
+ * `swift build` copies a target's .xcassets into its resource bundle but never
+ * runs actool, so SwiftUI's Image("name") finds no compiled catalog and the
+ * image does not resolve. After the harness builds, compile every .xcassets in
+ * the package with actool into the harness bin directory (= the render
+ * executable's Bundle.main), so unmodified Image("name") references resolve.
+ * One actool invocation over all catalogs (it merges them). Best-effort:
+ * a compile failure is logged and rendering continues -- the affected images
+ * simply will not appear, which the human comparing the screens will see.
+ */
+const RENDER_SCRIPT_ASSET_CATALOG_STAGE = String.raw `
+// ---- asset-catalog stage (package_source variants) ----
+
+var ASSET_CATALOG_MIN_MACOS = '13.0';
+
+// Recursively collect *.xcassets directories under root, skipping .build and
+// the catalogs' own contents (a catalog is a leaf for this scan).
+function findAssetCatalogs(root) {
+  var found = [];
+  var stack = [root];
+  while (stack.length > 0) {
+    var dir = stack.pop();
+    var entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (readError) {
+      continue;
+    }
+    for (var i = 0; i < entries.length; i++) {
+      var entry = entries[i];
+      if (!entry.isDirectory()) continue;
+      if (entry.name === '.build') continue;
+      var full = path.join(dir, entry.name);
+      if (entry.name.slice(-9) === '.xcassets') {
+        found.push(full);
+      } else {
+        stack.push(full);
+      }
+    }
+  }
+  return found.sort();
+}
+
+function compileAssetCatalogs(packageDir, harnessDir) {
+  var catalogs = findAssetCatalogs(packageDir);
+  if (catalogs.length === 0) return;
+
+  var binResult = runSwift(['build', '--package-path', harnessDir, '--show-bin-path']);
+  if (binResult.status !== 0) {
+    logError('asset-catalog compile skipped: could not resolve the build bin path');
+    return;
+  }
+  var binPath = String(binResult.stdout || '').trim().split('\n').pop().trim();
+  if (!binPath) {
+    logError('asset-catalog compile skipped: empty build bin path');
+    return;
+  }
+  try {
+    fs.mkdirSync(binPath, { recursive: true });
+  } catch (mkdirError) {
+    // best effort -- actool reports a missing output dir itself
+  }
+
+  var args = ['actool'].concat(catalogs);
+  args.push(
+    '--compile', binPath,
+    '--platform', 'macosx',
+    '--minimum-deployment-target', ASSET_CATALOG_MIN_MACOS,
+    '--output-format', 'human-readable-text'
+  );
+  log('xcrun ' + args.join(' '));
+  var result = cp.spawnSync('xcrun', args, {
+    encoding: 'utf-8',
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error || result.status !== 0) {
+    var detail = (result.stderr || '') +
+      (result.error ? String(result.error.message || result.error) : '');
+    logError(
+      'asset-catalog compile failed (continuing; catalog images may not ' +
+        'resolve): ' + sanitizeMessage(detail.trim())
+    );
+    return;
+  }
+  log('compiled ' + catalogs.length + ' asset catalog(s) for macOS');
+}
+`;
+/**
+ * Replaces exactly one occurrence of `anchor` in `source`. Throws when the
+ * anchor is missing or ambiguous, so any drift between the v1 runtime text
+ * and the package-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: expected exactly one occurrence of anchor: ' + anchor);
+    }
+    return source.slice(0, first) + replacement + source.slice(first + anchor.length);
+}
+/**
+ * Builds the runtime main for explicitly-configured package_source ("repo"
+ * or "inputs") by patching the v1 runtime text. RENDER_SCRIPT_MAIN itself is
+ * never modified: omitting package_source keeps the generated script
+ * byte-identical to v1 (locked by a snapshot test), and the patch points
+ * below are the complete, reviewable diff between the two modes.
+ */
+function buildPackageSourceMain() {
+    let main = RENDER_SCRIPT_MAIN;
+    // The result document gains the configured package source and a top-level
+    // per-build error slot, distinct from per-screen errors.
+    main = replaceOnce(main, 'var doc = { renderer: RENDERER, screens: currentEntries };', 'var doc = {\n' +
+        '    renderer: RENDERER,\n' +
+        '    package_source: CONFIG.packageSource,\n' +
+        '    error: buildError,\n' +
+        '    screens: currentEntries,\n' +
+        '  };');
+    // packagePath is null with package_source "inputs": the package to build
+    // from is only known after extraction.
+    main = replaceOnce(main, "var resolvedPackagePath = path.resolve(CONFIG.packagePath);\n" +
+        'registerPathReplacement(\n' +
+        '  resolvedPackagePath,\n' +
+        "  path.isAbsolute(CONFIG.packagePath) ? '<package_path>' : CONFIG.packagePath\n" +
+        ');', 'var resolvedPackagePath =\n' +
+        '  CONFIG.packagePath === null ? null : path.resolve(CONFIG.packagePath);\n' +
+        'if (resolvedPackagePath !== null) {\n' +
+        '  registerPathReplacement(\n' +
+        '    resolvedPackagePath,\n' +
+        "    path.isAbsolute(CONFIG.packagePath) ? '<package_path>' : CONFIG.packagePath\n" +
+        '  );\n' +
+        '}');
+    // The harness target may be discovered at runtime from the shipped
+    // manifest, so renderWithHarness reads the resolved activeTarget.
+    main = replaceOnce(main, 'target: CONFIG.target,', 'target: activeTarget,');
+    main = replaceOnce(main, "' a public View with a parameterless init in ' + CONFIG.target + '?):\\n' +", "' a public View with a parameterless init in ' + activeTarget + '?):\\n' +");
+    // The shipped-package stage runs before any harness build. It is reached
+    // even when no screen is renderable, so packaging mistakes are always
+    // reported; its scratch directory is cleaned up afterwards.
+    main = replaceOnce(main, '  // 3. Render the remaining screens through the synthesized harness.\n' +
+        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
+        '  if (renderable.length > 0) {\n' +
+        '    if (!fs.existsSync(resolvedPackagePath)) {\n' +
+        '      currentEntries.forEach(function (entry) {\n' +
+        "        setError(entry, 'RENDER_UNSUPPORTED', 'package_path does not exist: ' + resolvedPackagePath);\n" +
+        '      });\n' +
+        '    } else {\n' +
+        '      renderWithHarness(renderable, resolvedPackagePath);\n' +
+        '    }\n' +
+        '  } else if (currentEntries.length > 0) {\n' +
+        "    log('no renderable screens, skipping harness build');\n" +
+        '  }', '  // 3. Resolve the package to build from, then render the remaining\n' +
+        '  //    screens through the synthesized harness.\n' +
+        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
+        "  if (CONFIG.packageSource === 'inputs') {\n" +
+        '    try {\n' +
+        '      var shippedRoot = prepareShippedPackage();\n' +
+        '      if (shippedRoot !== null) {\n' +
+        '        if (renderable.length > 0) {\n' +
+        '          renderWithHarness(renderable, shippedRoot);\n' +
+        '        } else if (currentEntries.length > 0) {\n' +
+        "          log('no renderable screens, skipping harness build');\n" +
+        '        }\n' +
+        '      }\n' +
+        '    } finally {\n' +
+        '      cleanupShippedPackage();\n' +
+        '    }\n' +
+        '  } else if (renderable.length > 0) {\n' +
+        '    if (!fs.existsSync(resolvedPackagePath)) {\n' +
+        '      currentEntries.forEach(function (entry) {\n' +
+        "        setError(entry, 'RENDER_UNSUPPORTED', 'package_path does not exist: ' + resolvedPackagePath);\n" +
+        '      });\n' +
+        '    } else {\n' +
+        '      renderWithHarness(renderable, resolvedPackagePath);\n' +
+        '    }\n' +
+        '  } else if (currentEntries.length > 0) {\n' +
+        "    log('no renderable screens, skipping harness build');\n" +
+        '  }');
+    // A per-build package error fails the step even when no screen reached
+    // the harness (including the zero-screens case).
+    main = replaceOnce(main, '  // 4. Exit code: zero only when every screen rendered.\n' +
+        '  writeResult();\n', '  // 4. Exit code: zero only when the shipped package (if any) was valid\n' +
+        '  //    and every screen rendered.\n' +
+        '  writeResult();\n' +
+        '  if (buildError !== null) {\n' +
+        "    logError('package validation failed: ' + buildError.code);\n" +
+        '    return 1;\n' +
+        '  }\n');
+    // The shipped-package stage is defined ahead of main().
+    main = replaceOnce(main, 'function main() {', RENDER_SCRIPT_PACKAGE_STAGE + '\nfunction main() {');
+    // Asset-catalog stage: define the helpers ahead of renderWithHarness, then
+    // compile any catalogs once the package has proven it builds (after the
+    // probe) and before the per-screen renders that depend on the images.
+    main = replaceOnce(main, 'function renderWithHarness(renderable, packagePath) {', RENDER_SCRIPT_ASSET_CATALOG_STAGE + '\nfunction renderWithHarness(renderable, packagePath) {');
+    main = replaceOnce(main, '    renderable.forEach(function (entry) {', '    compileAssetCatalogs(packagePath, harnessDir);\n\n' +
+        '    renderable.forEach(function (entry) {');
+    return main;
+}
+const RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE = buildPackageSourceMain();
 /**
  * Evaluates the embedded generator source and returns the real functions, so
  * unit tests exercise exactly the code that ships inside the runtime script.
@@ -570,6 +1081,10 @@ export function getRenderScriptInternals() {
 /**
  * Generates the self-contained runtime node script for the step.
  * Pure function of its config — exported so tests can execute the script.
+ *
+ * When config.packageSource is absent the output is byte-identical to the
+ * pre-package_source script (JSON.stringify drops undefined keys, and the
+ * unpatched v1 runtime is used).
  */
 export function generateRenderScript(config) {
     return [
@@ -577,7 +1092,9 @@ export function generateRenderScript(config) {
         '// ui-fidelity-render runtime script (generated by cibuild at YAML conversion time)',
         'var CONFIG = ' + JSON.stringify(config) + ';',
         RENDER_SCRIPT_GENERATORS,
-        RENDER_SCRIPT_MAIN,
+        config.packageSource === undefined
+            ? RENDER_SCRIPT_MAIN
+            : RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE,
     ].join('\n');
 }
 /**
@@ -587,6 +1104,14 @@ export function generateRenderScript(config) {
  */
 export class UiFidelityRenderStepExecutor extends BaseStepExecutor {
     getValidationRequirements(inputs, _env, _config) {
+        if (inputs && inputs.package_source === 'inputs') {
+            // The package ships as .ci/inputs/package.tar.gz at run time, so
+            // neither package_path nor target is required up front.
+            return [
+                this.requireCommand('swift', 'Swift toolchain used to build and run the render harness', 'Install Xcode (or the Swift toolchain) on the runner'),
+                this.requireCommand('tar', 'Archive tool used to extract the shipped package', 'Install tar on the runner'),
+            ];
+        }
         return [
             this.requireInput('package_path', inputs, 'Path to the SwiftPM package containing the screens'),
             this.requireInput('target', inputs, 'SPM library product to import in the render harness'),
@@ -595,15 +1120,43 @@ export class UiFidelityRenderStepExecutor extends BaseStepExecutor {
     }
     async execute(inputs, _env, _config) {
         const stepName = 'ui-fidelity-render';
-        const packagePath = String(this.getRequiredInput(inputs, 'package_path', stepName));
-        const target = String(this.getRequiredInput(inputs, 'target', stepName));
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(target)) {
+        // Omitted package_source means v1 repo behavior with a byte-identical
+        // generated script; an explicit value (repo or inputs) is recorded in
+        // the script config and the result document.
+        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(', ')}`);
+            }
+            packageSource = value;
+        }
+        let packagePath = null;
+        let target = null;
+        if (packageSource === 'inputs') {
+            // package_path is ignored: the package arrives as a run input.
+            // target is optional and discovered from the shipped manifest when
+            // the package declares exactly one library product.
+            const configuredTarget = this.getInput(inputs, 'target', undefined);
+            target = configuredTarget === undefined ? null : String(configuredTarget);
+        }
+        else {
+            packagePath = String(this.getRequiredInput(inputs, 'package_path', stepName));
+            target = String(this.getRequiredInput(inputs, 'target', stepName));
+        }
+        if (target !== null && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(target)) {
             throw new Error(`Invalid target '${target}' for step '${stepName}': ` +
                 'must be a Swift module identifier (letters, digits, underscores)');
         }
         const { width, height } = parseRenderSize(String(this.getInput(inputs, 'render_size', DEFAULT_RENDER_SIZE)));
         const scale = parseScale(this.getInput(inputs, 'scale', DEFAULT_SCALE));
-        const script = generateRenderScript({ packagePath, target, width, height, scale });
+        const config = { packagePath, target, width, height, scale };
+        if (packageSource !== undefined) {
+            config.packageSource = packageSource;
+        }
+        const script = generateRenderScript(config);
         return this.createNodeStep(script, stepName);
     }
 }