@invarn/cibuild 2.9.5 → 2.9.7

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

@@ -1,1597 +0,0 @@
-/**
- * ui-fidelity-render step implementation.
- *
- * Renders parameterless SwiftUI views from a user's SwiftPM package to PNGs
- * with SwiftUI's ImageRenderer on a macOS runner — no app build, no
- * simulator. The step returns a self-contained node script that, at runtime:
- *
- *   1. Reads `.ci/inputs/params.json`
- *      ({ "screens": { "<ViewTypeName>": "<referenceFileBasename>" } });
- *      reference images live at `.ci/inputs/<basename>`.
- *      Optional reference-provenance sidecar: `"render_locale": "<locale>"`
- *      plus `"provenance": { "<ViewTypeName>": { figmaNode, locale, resolved,
- *      exportedAt } }`. The gate arms per screen from provenance presence and
- *      checks METADATA only (never pixels/OCR): an absent reference is FATAL
- *      (status `unverifiable`, REFERENCE_ABSENT); `resolved == false` or
- *      `locale != render_locale` downgrade ONLY the copy channel — the screen
- *      renders and is judged on every non-copy channel, and the downgrade
- *      rides as a per-screen `copy_advisory` (`copy_unverifiable` + reason).
- *      Unprovenanced screens keep legacy behaviour (no NO_PROVENANCE arming
- *      on iOS).
- *   2. Synthesizes a throwaway SwiftPM harness package that depends on the
- *      user's package and contains ONE executable target per screen, so a
- *      compile failure for one screen (unknown view type, unavailable init)
- *      never breaks the others. A screen-free probe target distinguishes
- *      "this screen is broken" from "the whole package does not build for
- *      macOS" (RENDER_UNSUPPORTED).
- *   3. Builds and runs each per-screen executable, which constructs the view
- *      strictly as `<ViewTypeName>()`, renders at render_size x scale on the
- *      MainActor, and writes a PNG via CGImage + ImageIO.
- *   4. Writes, inside the artifacts dir (${CIBUILD_ARTIFACTS_DIR:-.ci/artifacts}):
- *      - ui-fidelity/rendered/<Screen>.png
- *      - ui-fidelity/references/<Screen>.png (one copy per screen, even when
- *        two screens share a reference basename)
- *      - protocol-result.json (always written, even on partial/total failure;
- *        when params.json is absent/malformed the screens array is empty
- *        because screens cannot be enumerated)
- *   5. Exits non-zero iff any screen is not "rendered".
- *
- * 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, 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';
-import { RENDER_SCRIPT_TRIM_STAGE } from './render-post-processor.js';
-import { RENDER_SCRIPT_SOURCE_DIGEST_STAGE } from '../fidelity-input-digest.js';
-/**
- * Default render size in device points. 393x852 is the iPhone-class portrait
- * canvas shared by the iPhone 14 Pro / 15 / 16 — the most common modern
- * iPhone logical resolution, so renders line up with design references by
- * default.
- */
-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', 'url'];
-/** Default package source: the package lives in the repo checkout. */
-export const DEFAULT_PACKAGE_SOURCE = 'repo';
-/** Valid values for the reference_source input. */
-export const REFERENCE_SOURCES = ['repo', 'inputs'];
-/** Default reference source: references arrive as run inputs (v1 behaviour). */
-export const DEFAULT_REFERENCE_SOURCE = 'inputs';
-/** 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
- */
-export function parseRenderSize(value) {
-    const match = /^(\d+)x(\d+)$/.exec(String(value).trim());
-    const width = match ? Number(match[1]) : 0;
-    const height = match ? Number(match[2]) : 0;
-    if (!match || width <= 0 || height <= 0) {
-        throw new Error(`Invalid render_size '${value}' for step 'ui-fidelity-render': ` +
-            `expected "<width>x<height>" in device points, e.g. "${DEFAULT_RENDER_SIZE}"`);
-    }
-    return { width, height };
-}
-/**
- * Parses the scale input into a positive finite number.
- * @throws Error when the value is not a positive number
- */
-export function parseScale(value) {
-    const scale = typeof value === 'number' ? value : Number(String(value).trim());
-    if (!Number.isFinite(scale) || scale <= 0) {
-        throw new Error(`Invalid scale '${value}' for step 'ui-fidelity-render': expected a positive number`);
-    }
-    return scale;
-}
-/**
- * Swift source generators, written as plain dependency-free JS so the exact
- * same code is embedded into the runtime node script AND directly evaluable
- * in unit tests (see getRenderScriptInternals). String.raw keeps escape
- * sequences literal; the body must not contain backticks or "${".
- */
-const RENDER_SCRIPT_GENERATORS = String.raw `
-// ---- Swift source generation (pure string builders) ----
-
-function swiftStringLiteral(value) {
-  var out = '"';
-  var s = String(value);
-  for (var i = 0; i < s.length; i++) {
-    var ch = s[i];
-    var code = s.charCodeAt(i);
-    if (ch === '\\') out += '\\\\';
-    else if (ch === '"') out += '\\"';
-    else if (ch === '\n') out += '\\n';
-    else if (ch === '\r') out += '\\r';
-    else if (ch === '\t') out += '\\t';
-    else if (code < 0x20) out += '\\u{' + code.toString(16) + '}';
-    else out += ch;
-  }
-  return out + '"';
-}
-
-// One executable target (and product) per screen: SwiftPM compiles the user
-// package once, while a per-screen harness compile failure stays isolated to
-// that screen. RenderProbe imports the user package without referencing any
-// screen, so its failure means the package itself does not build for macOS.
-function generateHarnessPackageSwift(screens, options) {
-  var dependency =
-    '.product(name: ' + swiftStringLiteral(options.target) +
-    ', package: ' + swiftStringLiteral(options.packageRef) + ')';
-  var lines = [];
-  lines.push('// swift-tools-version:5.9');
-  lines.push('import PackageDescription');
-  lines.push('');
-  lines.push('let package = Package(');
-  lines.push('    name: "UIFidelityRenderHarness",');
-  lines.push('    platforms: [.macOS(.v13)],');
-  lines.push('    products: [');
-  screens.forEach(function (screen) {
-    lines.push(
-      '        .executable(name: "Render_' + screen +
-      '", targets: ["Render_' + screen + '"]),'
-    );
-  });
-  lines.push('    ],');
-  lines.push('    dependencies: [');
-  lines.push('        .package(path: ' + swiftStringLiteral(options.packagePath) + ')');
-  lines.push('    ],');
-  lines.push('    targets: [');
-  lines.push('        .executableTarget(name: "RenderProbe", dependencies: [' + dependency + ']),');
-  screens.forEach(function (screen) {
-    lines.push(
-      '        .executableTarget(name: "Render_' + screen +
-      '", dependencies: [' + dependency + ']),'
-    );
-  });
-  lines.push('    ]');
-  lines.push(')');
-  return lines.join('\n') + '\n';
-}
-
-function generateProbeSwift(options) {
-  var lines = [];
-  lines.push('import ' + options.target);
-  lines.push('');
-  lines.push('@main');
-  lines.push('struct Probe {');
-  lines.push('    static func main() {}');
-  lines.push('}');
-  return lines.join('\n') + '\n';
-}
-
-// ImageRenderer is MainActor-isolated, so the @main entry point runs on the
-// MainActor. The view is constructed strictly via the parameterless init.
-function generateScreenSwift(screen, options) {
-  var lines = [];
-  lines.push('import Foundation');
-  lines.push('import ImageIO');
-  lines.push('import SwiftUI');
-  lines.push('import UniformTypeIdentifiers');
-  lines.push('import ' + options.target);
-  lines.push('');
-  lines.push('@main');
-  lines.push('struct RenderEntry {');
-  lines.push('    @MainActor');
-  lines.push('    static func main() {');
-  lines.push('        let arguments = CommandLine.arguments');
-  lines.push('        guard arguments.count >= 2 else {');
-  lines.push('            FileHandle.standardError.write(Data("usage: Render_' + screen + ' <output.png>".utf8))');
-  lines.push('            exit(64)');
-  lines.push('        }');
-  lines.push('        let outputPath = arguments[1]');
-  lines.push('        let width: CGFloat = ' + options.width);
-  lines.push('        let height: CGFloat = ' + options.height);
-  lines.push('        let view = ' + screen + '().frame(width: width, height: height)');
-  lines.push('        let renderer = ImageRenderer(content: view)');
-  lines.push('        renderer.scale = ' + options.scale);
-  lines.push('        renderer.proposedSize = ProposedViewSize(width: width, height: height)');
-  lines.push('        guard let image = renderer.cgImage else {');
-  lines.push('            FileHandle.standardError.write(Data("ImageRenderer produced no image for ' + screen + '".utf8))');
-  lines.push('            exit(65)');
-  lines.push('        }');
-  lines.push('        let url = URL(fileURLWithPath: outputPath)');
-  lines.push('        guard let destination = CGImageDestinationCreateWithURL(url as CFURL, UTType.png.identifier as CFString, 1, nil) else {');
-  lines.push('            FileHandle.standardError.write(Data(("could not create PNG destination at " + outputPath).utf8))');
-  lines.push('            exit(66)');
-  lines.push('        }');
-  lines.push('        CGImageDestinationAddImage(destination, image, nil)');
-  lines.push('        guard CGImageDestinationFinalize(destination) else {');
-  lines.push('            FileHandle.standardError.write(Data(("could not write PNG to " + outputPath).utf8))');
-  lines.push('            exit(66)');
-  lines.push('        }');
-  lines.push('    }');
-  lines.push('}');
-  return lines.join('\n') + '\n';
-}
-`;
-/**
- * Runtime body of the generated node script. Plain dependency-free CJS
- * (the runner executes it via "node -e"). Must not contain backticks or
- * "${" — String.raw keeps escape sequences literal.
- */
-const RENDER_SCRIPT_MAIN = String.raw `
-// ---- runtime ----
-
-var fs = require('fs');
-var path = require('path');
-var os = require('os');
-var cp = require('child_process');
-
-var RENDERER = 'imagerenderer-spm';
-var SWIFT_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
-
-var artifactsDir = process.env.CIBUILD_ARTIFACTS_DIR || '.ci/artifacts';
-var inputsDir = path.join('.ci', 'inputs');
-var paramsPath = path.join(inputsDir, 'params.json');
-var resultPath = path.join(artifactsDir, 'protocol-result.json');
-
-var currentEntries = [];
-
-function log(message) {
-  console.log('[ui-fidelity-render] ' + message);
-}
-
-function logError(message) {
-  console.error('[ui-fidelity-render] ' + message);
-}
-
-// ---- result-document path hygiene ----
-//
-// protocol-result.json must contain relative paths only. Error messages can
-// embed absolute runner paths (resolved package_path, harness temp dir,
-// swift compiler diagnostics, copy failures), so every message stored in the
-// result document is passed through sanitizeMessage(), which rewrites each
-// known absolute directory -- and its symlink-resolved variant, since macOS
-// tools print /var/folders/... as /private/var/folders/... -- to a relative
-// path or a stable placeholder.
-
-var pathReplacements = [];
-
-function registerPathReplacement(absolutePath, replacement) {
-  if (!absolutePath || !path.isAbsolute(absolutePath)) return;
-  pathReplacements.push([absolutePath, replacement]);
-  try {
-    var real = fs.realpathSync(absolutePath);
-    if (real !== absolutePath) pathReplacements.push([real, replacement]);
-  } catch (realpathError) {
-    // path does not exist (yet) -- keep the literal form only
-  }
-}
-
-function sanitizeMessage(message) {
-  var sanitized = String(message);
-  pathReplacements
-    .slice()
-    .sort(function (a, b) { return b[0].length - a[0].length; })
-    .forEach(function (pair) {
-      sanitized = sanitized.split(pair[0]).join(pair[1]);
-    });
-  return sanitized;
-}
-
-var resolvedPackagePath = path.resolve(CONFIG.packagePath);
-registerPathReplacement(
-  resolvedPackagePath,
-  path.isAbsolute(CONFIG.packagePath) ? '<package_path>' : CONFIG.packagePath
-);
-registerPathReplacement(
-  path.resolve(artifactsDir),
-  path.isAbsolute(artifactsDir) ? '<artifacts>' : artifactsDir
-);
-registerPathReplacement(process.cwd(), '.');
-registerPathReplacement(os.tmpdir(), '<tmp>');
-
-// protocol-result.json is ALWAYS written, with one entry per screen in
-// params.json order, even on partial or total failure. All paths inside it
-// are relative to the artifacts dir.
-function writeResult() {
-  fs.mkdirSync(artifactsDir, { recursive: true });
-  var doc = { renderer: RENDERER, screens: currentEntries };
-  fs.writeFileSync(resultPath, JSON.stringify(doc, null, 2) + '\n');
-  log('wrote ' + resultPath);
-}
-
-function setError(entry, code, message) {
-  entry.status = 'render_failed';
-  entry.error = { code: code, message: sanitizeMessage(message) };
-}
-
-// A reference the gate cannot honestly judge at all: a hard, mechanical
-// metadata verdict (never pixels/OCR), distinct from render_failed so a rotten
-// reference fails loud instead of producing a confident-but-false PASS.
-function setUnverifiable(entry, code, message) {
-  entry.status = 'unverifiable';
-  entry.error = { code: code, message: sanitizeMessage(message) };
-}
-
-// Inlined twins of src/yaml/steps/fidelity-reference-provenance.ts (this script
-// ships self-contained and cannot import it). The render-step integration tests
-// exercise BOTH against the same fixtures so they cannot silently drift. The
-// iOS gate arms ONLY from provenance presence — the step never refused
-// unprovenanced screens, so NO_PROVENANCE (an Android-legacy arming via
-// render_locale) is deliberately not wired here.
-
-// Provenance is only "present" when the fields the gate reasons over are there.
-// A partial object (e.g. a hand-dropped { figmaNode }) is treated as no
-// provenance — verifiable is earned only through the full export path.
-function hasReferenceProvenance(provenance) {
-  return (
-    provenance != null &&
-    typeof provenance === 'object' &&
-    typeof provenance.locale === 'string' &&
-    typeof provenance.resolved === 'boolean'
-  );
-}
-
-// Assesses one provenanced screen's reference. Returns { fault, copyAdvisory }:
-// a fatal fault makes the screen unverifiable; a copy advisory downgrades only
-// the copy channel (the screen still renders and is judged on every non-copy
-// channel). An absent reference wins over a downgrade — there is nothing to
-// judge against.
-function assessReferenceProvenance(screen, provenance, renderLocale, referenceExists) {
-  if (!referenceExists) {
-    return {
-      fault: {
-        code: 'REFERENCE_ABSENT',
-        message: 'reference image for ' + screen + ' is absent',
-      },
-      copyAdvisory: null,
-    };
-  }
-  if (provenance.resolved === false) {
-    return {
-      fault: null,
-      copyAdvisory: {
-        code: 'copy_unverifiable',
-        reason: 'unresolved_placeholders',
-        message:
-          'reference for ' + screen + ' carries unresolved copy placeholders ' +
-          '(resolved=false); copy comparisons are skipped — non-copy judging ' +
-          'still holds',
-      },
-    };
-  }
-  if (renderLocale !== null && provenance.locale !== renderLocale) {
-    return {
-      fault: null,
-      copyAdvisory: {
-        code: 'copy_unverifiable',
-        reason: 'locale_mismatch',
-        message:
-          'reference for ' + screen + ' is locale "' + provenance.locale +
-          '" but the render locale is "' + renderLocale + '"; copy comparisons ' +
-          'are skipped — non-copy judging still holds',
-      },
-    };
-  }
-  return { fault: null, copyAdvisory: null };
-}
-
-function outputTail(result) {
-  var combined = ((result.stdout || '') + '\n' + (result.stderr || '')).trim();
-  if (combined.length > 2000) combined = '...' + combined.slice(-2000);
-  return combined;
-}
-
-function runSwift(args) {
-  log('swift ' + args.join(' '));
-  var result = cp.spawnSync('swift', 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 = result.status == null ? 127 : result.status;
-    result.stderr =
-      (result.stderr || '') + String(result.error.message || result.error);
-  }
-  return result;
-}
-
-function renderWithHarness(renderable, packagePath) {
-  // Snapshot the user package's input files BEFORE any Swift build, so build
-  // products (.build, DerivedData) never perturb the content key. A package is
-  // safely cacheable only when it is hermetic — its own files are its whole
-  // dependency closure; a non-hermetic one emits no digest and so is never
-  // skipped by a consumer.
-  var packageFiles = __fidCollectPackageFiles(packagePath);
-  var packageHermetic = __fidIsHermetic(packageFiles);
-  var harnessDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ui-fidelity-harness-'));
-  registerPathReplacement(harnessDir, '<harness>');
-  log('harness package: ' + harnessDir);
-  try {
-    var screens = renderable.map(function (entry) { return entry.screen; });
-    var generatorOptions = {
-      packagePath: packagePath,
-      packageRef: path.basename(packagePath),
-      target: CONFIG.target,
-      width: CONFIG.width,
-      height: CONFIG.height,
-      scale: CONFIG.scale,
-    };
-
-    fs.writeFileSync(
-      path.join(harnessDir, 'Package.swift'),
-      generateHarnessPackageSwift(screens, generatorOptions)
-    );
-    var probeDir = path.join(harnessDir, 'Sources', 'RenderProbe');
-    fs.mkdirSync(probeDir, { recursive: true });
-    fs.writeFileSync(path.join(probeDir, 'Probe.swift'), generateProbeSwift(generatorOptions));
-    screens.forEach(function (screen) {
-      var sourceDir = path.join(harnessDir, 'Sources', 'Render_' + screen);
-      fs.mkdirSync(sourceDir, { recursive: true });
-      fs.writeFileSync(
-        path.join(sourceDir, 'Render.swift'),
-        generateScreenSwift(screen, generatorOptions)
-      );
-    });
-
-    // Harness-level gate: the probe imports the user package without touching
-    // any screen. If it fails, the package does not resolve/compile for
-    // macOS and EVERY screen is marked RENDER_UNSUPPORTED.
-    var probe = runSwift(['build', '--package-path', harnessDir, '--target', 'RenderProbe']);
-    if (probe.status !== 0) {
-      var probeDetail = outputTail(probe);
-      currentEntries.forEach(function (entry) {
-        setError(
-          entry,
-          'RENDER_UNSUPPORTED',
-          'the package at ' + packagePath + ' does not build for macOS:\n' + probeDetail
-        );
-      });
-      return;
-    }
-
-    renderable.forEach(function (entry) {
-      var product = 'Render_' + entry.screen;
-      var build = runSwift(['build', '--package-path', harnessDir, '--product', product]);
-      if (build.status !== 0) {
-        setError(
-          entry,
-          'VIEW_COMPILE_FAILED',
-          'harness for ' + entry.screen + ' did not compile (is ' + entry.screen +
-            ' a public View with a parameterless init in ' + CONFIG.target + '?):\n' +
-            outputTail(build)
-        );
-        return;
-      }
-      var relative = 'ui-fidelity/rendered/' + entry.screen + '.png';
-      var outputPath = path.resolve(artifactsDir, relative);
-      var run = runSwift(['run', '--package-path', harnessDir, '--skip-build', product, outputPath]);
-      if (run.status !== 0) {
-        setError(
-          entry,
-          'RENDER_FAILED',
-          'renderer for ' + entry.screen + ' exited with code ' + run.status + ':\n' + outputTail(run)
-        );
-        return;
-      }
-      if (!fs.existsSync(outputPath)) {
-        setError(
-          entry,
-          'RENDER_FAILED',
-          'renderer for ' + entry.screen + ' exited 0 but produced no PNG at ' + outputPath
-        );
-        return;
-      }
-      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);
-    });
-  } finally {
-    if (process.env.UI_FIDELITY_KEEP_HARNESS) {
-      log('keeping harness package (UI_FIDELITY_KEEP_HARNESS set)');
-    } else {
-      try {
-        fs.rmSync(harnessDir, { recursive: true, force: true });
-      } catch (cleanupError) {
-        // best effort
-      }
-    }
-  }
-}
-
-function main() {
-  // 1. Read and validate .ci/inputs/params.json.
-  var paramsProblem = null;
-  var params = null;
-  if (!fs.existsSync(paramsPath)) {
-    paramsProblem = 'not found at ' + paramsPath;
-  } else {
-    try {
-      params = JSON.parse(fs.readFileSync(paramsPath, 'utf-8'));
-    } catch (parseError) {
-      paramsProblem = 'is not valid JSON: ' +
-        (parseError && parseError.message ? parseError.message : String(parseError));
-    }
-  }
-  if (!paramsProblem) {
-    if (
-      !params || typeof params !== 'object' || Array.isArray(params) ||
-      !params.screens || typeof params.screens !== 'object' || Array.isArray(params.screens)
-    ) {
-      paramsProblem =
-        'must have the shape { "screens": { "<ViewTypeName>": "<referenceFileBasename>" } }';
-    }
-  }
-  if (paramsProblem) {
-    // Screens cannot be enumerated, so the result document is written with
-    // an empty screens array and the step fails.
-    logError('params.json ' + paramsProblem);
-    writeResult();
-    return 1;
-  }
-
-  // Reference-provenance sidecar (optional): per-screen export provenance plus
-  // the run's declared render locale. The gate arms per screen from provenance
-  // presence; the locale is only needed for the locale comparison itself.
-  var renderLocale =
-    typeof params.render_locale === 'string' && params.render_locale !== ''
-      ? params.render_locale
-      : null;
-  var provenanceMap =
-    params.provenance && typeof params.provenance === 'object' && !Array.isArray(params.provenance)
-      ? params.provenance
-      : {};
-
-  var screens = Object.keys(params.screens);
-  currentEntries = screens.map(function (screen) {
-    return {
-      screen: screen,
-      status: 'render_failed',
-      error: null,
-      copy_advisory: null,
-      reference_image_path: null,
-      rendered_image_path: null,
-    };
-  });
-  log('screens: ' + (screens.join(', ') || '(none)'));
-
-  fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'rendered'), { recursive: true });
-  fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'references'), { recursive: true });
-
-  // 2. Per-screen validation + reference copies. Each screen gets its OWN
-  //    copy named by screen, even when two screens share a reference
-  //    basename.
-  currentEntries.forEach(function (entry) {
-    if (!SWIFT_IDENTIFIER.test(entry.screen)) {
-      setError(
-        entry,
-        'INVALID_SCREEN_NAME',
-        'screen name ' + JSON.stringify(entry.screen) + ' is not a valid Swift type identifier'
-      );
-      return;
-    }
-    var basename = params.screens[entry.screen];
-    if (
-      typeof basename !== 'string' || basename === '' ||
-      basename === '.' || basename === '..' ||
-      basename !== path.basename(basename)
-    ) {
-      setError(
-        entry,
-        'REFERENCE_MISSING',
-        'reference for ' + entry.screen + ' must be a plain file basename inside ' +
-          inputsDir + ', got: ' + JSON.stringify(basename)
-      );
-      return;
-    }
-    var source = path.join(inputsDir, basename);
-    var sourceStat = null;
-    try {
-      sourceStat = fs.statSync(source);
-    } catch (statError) {
-      sourceStat = null;
-    }
-    var referenceExists = !!(sourceStat && sourceStat.isFile());
-
-    var screenProvenance = provenanceMap[entry.screen];
-    if (hasReferenceProvenance(screenProvenance)) {
-      // Provenance assessment (armed by provenance presence): an absent
-      // reference is FATAL (unverifiable — never a silent PASS); unresolved
-      // placeholders and locale mismatches downgrade ONLY the copy channel —
-      // the screen renders and is judged on every non-copy channel, and the
-      // downgrade rides in the result as a structured copy_advisory.
-      var assessment = assessReferenceProvenance(
-        entry.screen,
-        screenProvenance,
-        renderLocale,
-        referenceExists
-      );
-      if (assessment.fault) {
-        setUnverifiable(entry, assessment.fault.code, assessment.fault.message);
-        return;
-      }
-      if (assessment.copyAdvisory) {
-        entry.copy_advisory = {
-          code: assessment.copyAdvisory.code,
-          reason: assessment.copyAdvisory.reason,
-          message: sanitizeMessage(assessment.copyAdvisory.message),
-        };
-        log(
-          entry.screen + ': copy channel downgraded (' +
-            assessment.copyAdvisory.reason + '), non-copy judging proceeds'
-        );
-      }
-    } else if (!referenceExists) {
-      // Legacy (no provenance for this screen): an absent reference stays a
-      // render_failed REFERENCE_MISSING, exactly as before.
-      setError(
-        entry,
-        'REFERENCE_MISSING',
-        sourceStat
-          ? 'reference for ' + entry.screen + ' is not a regular file: ' + source
-          : 'reference image not found: ' + source
-      );
-      return;
-    }
-    var relative = 'ui-fidelity/references/' + entry.screen + '.png';
-    // The copy is guarded per screen so an unexpected filesystem failure
-    // never escapes this forEach and takes the other screens down with it.
-    try {
-      fs.copyFileSync(source, path.join(artifactsDir, relative));
-    } catch (copyError) {
-      setError(
-        entry,
-        'REFERENCE_MISSING',
-        'could not copy reference for ' + entry.screen + ': ' +
-          (copyError && copyError.message ? copyError.message : String(copyError))
-      );
-      return;
-    }
-    entry.reference_image_path = relative;
-  });
-
-  // 3. Render the remaining screens through the synthesized harness.
-  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });
-  if (renderable.length > 0) {
-    if (!fs.existsSync(resolvedPackagePath)) {
-      currentEntries.forEach(function (entry) {
-        setError(entry, 'RENDER_UNSUPPORTED', 'package_path does not exist: ' + resolvedPackagePath);
-      });
-    } else {
-      renderWithHarness(renderable, resolvedPackagePath);
-    }
-  } else if (currentEntries.length > 0) {
-    log('no renderable screens, skipping harness build');
-  }
-
-  // 4. Exit code: zero only when every screen rendered.
-  writeResult();
-  var failed = currentEntries.filter(function (entry) { return entry.status !== 'rendered'; });
-  if (failed.length > 0) {
-    logError(failed.length + ' of ' + currentEntries.length + ' screen(s) not rendered');
-    return 1;
-  }
-  log('all ' + currentEntries.length + ' screen(s) rendered');
-  return 0;
-}
-
-var exitCode = 1;
-try {
-  exitCode = main();
-} catch (unexpectedError) {
-  logError(
-    'unexpected failure: ' +
-      (unexpectedError && unexpectedError.stack ? unexpectedError.stack : String(unexpectedError))
-  );
-  try {
-    currentEntries.forEach(function (entry) {
-      if (entry.status !== 'rendered' && entry.error === null) {
-        setError(
-          entry,
-          'INTERNAL_ERROR',
-          String(unexpectedError && unexpectedError.message ? unexpectedError.message : unexpectedError)
-        );
-      }
-    });
-    writeResult();
-  } catch (writeError) {
-    logError('could not write protocol-result.json: ' + writeError);
-  }
-  exitCode = 1;
-}
-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();
-}
-
-// Run actool over the given catalogs, emitting Assets.car into outDir.
-// Best-effort: a failure is logged (warn-and-continue) and rendering proceeds.
-function compileCatalogsInto(catalogs, outDir, label) {
-  try {
-    fs.mkdirSync(outDir, { recursive: true });
-  } catch (mkdirError) {
-    // best effort -- actool reports a missing output dir itself
-  }
-  var args = ['actool'].concat(catalogs);
-  args.push(
-    '--compile', outDir,
-    '--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 for ' + label + ' (continuing; catalog ' +
-        'images may not resolve): ' + sanitizeMessage(detail.trim())
-    );
-  }
-}
-
-// SwiftUI resolves Image("name") against Bundle.main and
-// Image("name", bundle: .module) against a target's own resource bundle.
-// swift build copies a .process'd .xcassets into the module bundle but never
-// compiles it, and a loose catalog is copied nowhere. So compile twice:
-// the package's source catalogs into the bin dir (= Bundle.main), AND each
-// module bundle's copied catalog in place (= Bundle.module). This covers both
-// reference idioms, so the agent need not know which bundle the renderer uses.
-function compileAssetCatalogs(packageDir, harnessDir) {
-  var sourceCatalogs = findAssetCatalogs(packageDir);
-  if (sourceCatalogs.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;
-  }
-
-  // Bundle.main: the package's source catalogs, merged into the bin dir.
-  compileCatalogsInto(sourceCatalogs, binPath, 'Bundle.main');
-
-  // Bundle.module: each *.bundle in the bin dir that carries a copied catalog,
-  // compiled in place so Image(..., bundle: .module) resolves.
-  var entries;
-  try {
-    entries = fs.readdirSync(binPath, { withFileTypes: true });
-  } catch (readError) {
-    entries = [];
-  }
-  for (var i = 0; i < entries.length; i++) {
-    var entry = entries[i];
-    if (!entry.isDirectory() || entry.name.slice(-7) !== '.bundle') continue;
-    var bundleDir = path.join(binPath, entry.name);
-    var bundleCatalogs = findAssetCatalogs(bundleDir);
-    if (bundleCatalogs.length > 0) {
-      compileCatalogsInto(bundleCatalogs, bundleDir, entry.name);
-    }
-  }
-}
-`;
-/**
- * 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) {');
-    // Render-trimming stage: define the helpers ahead of renderWithHarness, then
-    // crop each rendered PNG to its content bounding box right after it renders.
-    main = replaceOnce(main, 'function renderWithHarness(renderable, packagePath) {', RENDER_SCRIPT_TRIM_STAGE + '\nfunction renderWithHarness(renderable, packagePath) {');
-    main = replaceOnce(main, "      log('rendered ' + entry.screen + ' -> ' + relative);", "      log('rendered ' + entry.screen + ' -> ' + relative);\n" +
-        '      trimRenderedImage(entry, outputPath);');
-    // Per-screen result entries gain the trimmed-render fields: the aligned
-    // (reference-sized) image and the rendered/logical/reference dimensions.
-    // They stay null until a screen renders and is trimmed.
-    main = replaceOnce(main, '      reference_image_path: null,\n' +
-        '      rendered_image_path: null,\n' +
-        '    };', '      reference_image_path: null,\n' +
-        '      rendered_image_path: null,\n' +
-        '      aligned_image_path: null,\n' +
-        '      dimensions: null,\n' +
-        '    };');
-    return main;
-}
-const RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE = buildPackageSourceMain();
-/**
- * Builds the runtime main for package_source "url" (fidelity-linux 03) by
- * patching the package_source variant. Three departures, all forced by the
- * same fact — a clone-free worker has no checkout:
- *
- * 1. The package is DOWNLOADED (curl, 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: it must sit under packagePath, and the
- *    remainder resolves against the extracted package root.
- * 3. The harness stage reuses the already-extracted root (no second extract);
- *    cleanup mirrors the inputs path. Mirrors the Android step's url mode so
- *    both platform kinds accept the same dispatched inputs.
- */
-function buildPackageUrlMain() {
-    let main = RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE;
-    // 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\n' +
-        '  //    copy named by screen, even when two screens share a reference\n' +
-        '  //    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 package 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 urlPackageRoot = null;\n' +
-        '  (function () {\n' +
-        '    try {\n' +
-        '      fs.mkdirSync(inputsDir, { recursive: true });\n' +
-        '    } catch (mkdirError) {\n' +
-        '      // the download 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' +
-        "        'PACKAGE_DOWNLOAD_FAILED',\n" +
-        "        'render package download failed (curl exit ' + download.status + '):\\n' + outputTail(download)\n" +
-        '      );\n' +
-        '      return;\n' +
-        '    }\n' +
-        '    urlPackageRoot = prepareShippedPackage();\n' +
-        '  })();\n' +
-        '\n' +
-        '  // 2. Per-screen validation + reference copies. Each screen gets its OWN\n' +
-        '  //    copy named by screen, even when two screens share a reference\n' +
-        '  //    basename.\n' +
-        '  currentEntries.forEach(function (entry) {');
-    // References resolve INSIDE the extracted package: repo-relative path minus
-    // the packagePath prefix, against the extracted package 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 (urlPackageRoot === 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(urlPackageRoot, normalizedRef.slice(packagePrefix.length + 1));');
-    // Harness stage: build from the package extracted in stage 2a — no second
-    // extract. This variant only ever runs with packageSource "url".
-    main = replaceOnce(main, '  // 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" +
-        '  }', '  // 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 harness build.\n' +
-        '  var renderable = currentEntries.filter(function (entry) { return entry.error === null; });\n' +
-        '  try {\n' +
-        '    if (urlPackageRoot !== null) {\n' +
-        '      if (renderable.length > 0) {\n' +
-        '        renderWithHarness(renderable, urlPackageRoot);\n' +
-        '      } else if (currentEntries.length > 0) {\n' +
-        "        log('no renderable screens, skipping harness build');\n" +
-        '      }\n' +
-        '    }\n' +
-        '  } finally {\n' +
-        '    cleanupShippedPackage();\n' +
-        '  }');
-    return main;
-}
-const RENDER_SCRIPT_MAIN_URL = buildPackageUrlMain();
-/**
- * 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/`. Applied on top of EITHER base main (v1 or the
- * package_source variant) — the package patches never touch this block, so the
- * anchor is present and unique in both. The downstream stat/copy logic is
- * unchanged; only how `source` is computed differs.
- */
-function buildReferenceRepoMain(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);');
-}
-/**
- * Evaluates the embedded generator source and returns the real functions, so
- * unit tests exercise exactly the code that ships inside the runtime script.
- */
-export function getRenderScriptInternals() {
-    const factory = new Function(RENDER_SCRIPT_GENERATORS +
-        '\nreturn { swiftStringLiteral: swiftStringLiteral,' +
-        ' generateHarnessPackageSwift: generateHarnessPackageSwift,' +
-        ' generateProbeSwift: generateProbeSwift,' +
-        ' generateScreenSwift: generateScreenSwift };');
-    return factory();
-}
-/**
- * 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) {
-    let main = config.packageSource === undefined
-        ? RENDER_SCRIPT_MAIN
-        : config.packageSource === 'url'
-            ? RENDER_SCRIPT_MAIN_URL
-            : RENDER_SCRIPT_MAIN_WITH_PACKAGE_SOURCE;
-    // Reference-from-repo is an independent dimension layered on top of whichever
-    // package base applies. Absent → byte-identical reference block (v1).
-    if (config.referenceSource === 'repo') {
-        main = buildReferenceRepoMain(main);
-    }
-    return [
-        "'use strict';",
-        '// ui-fidelity-render runtime script (generated by cibuild at YAML conversion time)',
-        'var CONFIG = ' + JSON.stringify(config) + ';',
-        RENDER_SCRIPT_GENERATORS,
-        RENDER_SCRIPT_SOURCE_DIGEST_STAGE,
-        main,
-    ].join('\n');
-}
-/**
- * ui-fidelity-render step executor.
- * Returns a node-kind StepDef whose script performs the render at runtime on
- * the macOS runner.
- */
-export class UiFidelityRenderStepExecutor extends BaseStepExecutor {
-    getValidationRequirements(inputs, _env, _config) {
-        if (inputs && (inputs.package_source === 'inputs' || inputs.package_source === 'url')) {
-            // The package ships as .ci/inputs/package.tar.gz at run time (uploaded
-            // run input, or downloaded from the signed package_url in url mode), so
-            // neither package_path nor target is required up front.
-            const requirements = [
-                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'),
-            ];
-            if (inputs.package_source === 'url') {
-                requirements.push(this.requireCommand('curl', 'Downloader used to fetch the render package by signed URL', 'Install curl on the runner'));
-            }
-            return requirements;
-        }
-        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'),
-            this.requireCommand('swift', 'Swift toolchain used to build and run the render harness', 'Install Xcode (or the Swift toolchain) on the runner'),
-        ];
-    }
-    async execute(inputs, _env, _config) {
-        const stepName = 'ui-fidelity-render';
-        // 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;
-        let packageUrl;
-        if (packageSource === 'inputs' || packageSource === 'url') {
-            // package_path names no local directory here: inputs mode ignores it
-            // (the package arrives as a run input); url mode requires it as the
-            // repo-relative prefix committed reference paths sit under, inside the
-            // downloaded package. target is optional and discovered from the
-            // shipped manifest when the package declares exactly one library
-            // product.
-            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`);
-                }
-                packagePath = String(this.getRequiredInput(inputs, 'package_path', stepName));
-            }
-            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)');
-        }
-        // reference_source mirrors 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 v1 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(', ')}`);
-            }
-            // 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';
-            }
-        }
-        const { width, height } = parseRenderSize(String(this.getInput(inputs, 'render_size', DEFAULT_RENDER_SIZE)));
-        const scale = parseScale(this.getInput(inputs, 'scale', DEFAULT_SCALE));
-        const config = { packagePath, target, width, height, scale };
-        if (packageSource !== undefined) {
-            config.packageSource = packageSource;
-        }
-        if (packageUrl !== undefined) {
-            config.packageUrl = packageUrl;
-        }
-        if (referenceSource !== undefined) {
-            config.referenceSource = referenceSource;
-        }
-        const script = generateRenderScript(config);
-        return this.createNodeStep(script, stepName);
-    }
-}
-//# sourceMappingURL=ui-fidelity-render.js.map