@invarn/cibuild 2.0.6 → 2.0.8

package/dist/src/lib.d.ts

@@ -19,6 +19,8 @@ export { loadYAMLPipeline, getWorkflowNames, hasWorkflow, YAMLParseError, YAMLVa
 export { convertYAMLToPipelineDef, getAvailableWorkflows, YAMLConversionError, } from './yaml/converter.js';
 export type { ConversionResult } from './yaml/converter.js';
 export { pipeline } from './pipeline.js';
+export { renderUiFidelityPreview } from './yaml/steps/ui-fidelity-preview.js';
+export type { UiFidelityPreviewOptions, UiFidelityPreviewScreen, UiFidelityPreviewResult, UiFidelityPreviewScreenResult, UiFidelityPreviewDimensions, } from './yaml/steps/ui-fidelity-preview.js';
 export { getStepExecutor, hasStep, getAvailableSteps, registerStep, getStepMetadata, } from './yaml/steps/registry.js';
 export type { StepDef, PipelineDef, CIConfig, PipelineFactory, PipelineContext, StepBuilders, } from './types.js';
 export type { StepExecutor, StepMetadata, StepPlatform, StepExecutionContext, } from './yaml/steps/base.js';

package/dist/src/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,uBAAuB,CAAC;AAI/B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIjE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIzC,OAAO,EACL,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EACV,OAAO,EACP,WAAW,EACX,QAAQ,EACR,eAAe,EACf,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC;AAIpB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAI9B,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,UAAU,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,uBAAuB,CAAC;AAI/B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIjE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,qCAAqC,CAAC;AAI7C,OAAO,EACL,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EACV,OAAO,EACP,WAAW,EACX,QAAQ,EACR,eAAe,EACf,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC;AAIpB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAI9B,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,UAAU,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/src/lib.js

@@ -25,6 +25,8 @@ export { loadYAMLPipeline, getWorkflowNames, hasWorkflow, YAMLParseError, YAMLVa
 export { convertYAMLToPipelineDef, getAvailableWorkflows, YAMLConversionError, } from './yaml/converter.js';
 // ─── Pipeline DSL factory ───────────────────────────────────────────────
 export { pipeline } from './pipeline.js';
+// ─── UI fidelity local preview ──────────────────────────────────────────
+export { renderUiFidelityPreview } from './yaml/steps/ui-fidelity-preview.js';
 // ─── Step registry ──────────────────────────────────────────────────────
 export { getStepExecutor, hasStep, getAvailableSteps, registerStep, getStepMetadata, } from './yaml/steps/registry.js';
 // ─── Error types ────────────────────────────────────────────────────────

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

@@ -0,0 +1,99 @@
+/**
+ * Local ui-fidelity render preview.
+ *
+ * Runs the EXACT same render path the runner uses -- the generated
+ * `ui-fidelity-render` node script in `package_source: "inputs"` mode (harness
+ * synthesis, asset-catalog compile, content trim, reference alignment, dimension
+ * reporting) -- but locally, against a SwiftPM package the caller already has on
+ * disk. This lets an agent eyeball the wrapper in seconds before dispatching a
+ * remote run, so the remote pass becomes a one-shot authoritative render rather
+ * than the inner loop of an iterate cycle.
+ *
+ * It is a faithful mirror, not a re-implementation: the package directory is
+ * archived to a temp `package.tar.gz` and fed through the same
+ * `generateRenderScript` output, so the target is auto-discovered, the archive
+ * is validated, and the produced rendered/aligned images and dimensions match
+ * what a remote run would produce on the same toolchain.
+ */
+/** One wrapper view to render, paired with the reference image to align to. */
+export interface UiFidelityPreviewScreen {
+    /** Wrapper view type name (e.g. the public, parameterless `XProof`). */
+    screen: string;
+    /** Path to the reference image; copied into the inputs by basename. */
+    reference: string;
+}
+export interface UiFidelityPreviewOptions {
+    /**
+     * Local SwiftPM package directory to render. Archived to a temp
+     * package.tar.gz and rendered in inputs mode. Mutually exclusive with
+     * packageArchive.
+     */
+    packagePath?: string;
+    /**
+     * A prebuilt package.tar.gz to render as-is (preview the exact artifact a
+     * remote run would receive). Mutually exclusive with packagePath.
+     */
+    packageArchive?: string;
+    /** Screens to render, each mapped to a reference image path. */
+    screens: UiFidelityPreviewScreen[];
+    /**
+     * SPM library target to import. Auto-discovered from the shipped manifest
+     * when omitted (the package must declare exactly one library product).
+     */
+    target?: string;
+    /** Render size in device points, "<width>x<height>" (default 393x852). */
+    renderSize?: string;
+    /** Display scale (default 2). */
+    scale?: number | string;
+    /** Directory to receive the artifacts; a temp dir is used when omitted. */
+    outDir?: string;
+    /**
+     * Extra entries prepended to PATH for the render child process, so callers
+     * (and tests) can supply a specific swift/xcrun/tar toolchain. Optional.
+     */
+    toolchainPath?: string;
+}
+export interface UiFidelityPreviewDimensions {
+    rendered_px: [number, number];
+    logical_pt: [number, number];
+    reference_px: [number, number] | null;
+}
+export interface UiFidelityPreviewScreenResult {
+    screen: string;
+    /** "rendered" when the screen rendered; otherwise "render_failed". */
+    status: string;
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    /** Absolute path to the (per-screen) reference copy, or null. */
+    referenceImagePath: string | null;
+    /** Absolute path to the trimmed rendered image, or null. */
+    renderedImagePath: string | null;
+    /** Absolute path to the reference-aligned image, or null. */
+    alignedImagePath: string | null;
+    dimensions: UiFidelityPreviewDimensions | null;
+}
+export interface UiFidelityPreviewResult {
+    /** Always "inputs": the preview mirrors a shipped-package remote run. */
+    packageSource: 'inputs';
+    /** Per-build package error (archive/target validation), or null. */
+    buildError: {
+        code: string;
+        message: string;
+    } | null;
+    /** One entry per requested screen, in request order. */
+    screens: UiFidelityPreviewScreenResult[];
+    /** Absolute path to the artifacts directory holding the images. */
+    artifactsDir: string;
+    /** True only when every screen rendered and there was no build error. */
+    ok: boolean;
+}
+/**
+ * Render the requested screens locally and return the produced image paths and
+ * dimensions. Throws only on caller errors (bad options) or when the render
+ * script could not run at all; per-screen and per-build render failures are
+ * reported in the returned result (mirroring the remote result document).
+ */
+export declare function renderUiFidelityPreview(options: UiFidelityPreviewOptions): UiFidelityPreviewResult;
+//# sourceMappingURL=ui-fidelity-preview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ui-fidelity-preview.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAwBH,+EAA+E;AAC/E,MAAM,WAAW,uBAAuB;IACtC,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAChD,iEAAiE;IACjE,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4DAA4D;IAC5D,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,6DAA6D;IAC7D,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,EAAE,2BAA2B,GAAG,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,aAAa,EAAE,QAAQ,CAAC;IACxB,oEAAoE;IACpE,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,wDAAwD;IACxD,OAAO,EAAE,6BAA6B,EAAE,CAAC;IACzC,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,EAAE,EAAE,OAAO,CAAC;CACb;AAkCD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,uBAAuB,CAoIzB"}

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

@@ -0,0 +1,152 @@
+/**
+ * Local ui-fidelity render preview.
+ *
+ * Runs the EXACT same render path the runner uses -- the generated
+ * `ui-fidelity-render` node script in `package_source: "inputs"` mode (harness
+ * synthesis, asset-catalog compile, content trim, reference alignment, dimension
+ * reporting) -- but locally, against a SwiftPM package the caller already has on
+ * disk. This lets an agent eyeball the wrapper in seconds before dispatching a
+ * remote run, so the remote pass becomes a one-shot authoritative render rather
+ * than the inner loop of an iterate cycle.
+ *
+ * It is a faithful mirror, not a re-implementation: the package directory is
+ * archived to a temp `package.tar.gz` and fed through the same
+ * `generateRenderScript` output, so the target is auto-discovered, the archive
+ * is validated, and the produced rendered/aligned images and dimensions match
+ * what a remote run would produce on the same toolchain.
+ */
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { DEFAULT_RENDER_SIZE, DEFAULT_SCALE, generateRenderScript, parseRenderSize, parseScale, } from './ui-fidelity-render.js';
+function runTar(args, pathPrepend) {
+    const env = pathPrepend
+        ? { ...process.env, PATH: pathPrepend + ':' + (process.env.PATH ?? '') }
+        : process.env;
+    const result = spawnSync('tar', args, { encoding: 'utf-8', env, maxBuffer: 64 * 1024 * 1024 });
+    if (result.status !== 0) {
+        const detail = (result.stderr || result.error?.message || '').toString().trim();
+        throw new Error(`failed to archive the package (tar exited ${result.status}): ${detail}`);
+    }
+}
+/** Resolve an artifact-relative path to absolute, or null. */
+function absOrNull(artifactsDir, relative) {
+    return typeof relative === 'string' && relative !== '' ? resolve(artifactsDir, relative) : null;
+}
+/**
+ * Render the requested screens locally and return the produced image paths and
+ * dimensions. Throws only on caller errors (bad options) or when the render
+ * script could not run at all; per-screen and per-build render failures are
+ * reported in the returned result (mirroring the remote result document).
+ */
+export function renderUiFidelityPreview(options) {
+    if (!options || typeof options !== 'object') {
+        throw new Error('renderUiFidelityPreview: options are required');
+    }
+    const hasDir = typeof options.packagePath === 'string' && options.packagePath !== '';
+    const hasArchive = typeof options.packageArchive === 'string' && options.packageArchive !== '';
+    if (hasDir === hasArchive) {
+        throw new Error('renderUiFidelityPreview: provide exactly one of packagePath or packageArchive');
+    }
+    if (!Array.isArray(options.screens) || options.screens.length === 0) {
+        throw new Error('renderUiFidelityPreview: at least one screen is required');
+    }
+    const { width, height } = parseRenderSize(options.renderSize ?? DEFAULT_RENDER_SIZE);
+    const scale = parseScale(options.scale ?? DEFAULT_SCALE);
+    const workDir = mkdtempSync(join(tmpdir(), 'ui-fidelity-preview-'));
+    const inputsDir = join(workDir, '.ci', 'inputs');
+    mkdirSync(inputsDir, { recursive: true });
+    // Stage references by basename and build the screens -> basename map, exactly
+    // as a remote caller would pass params.screens.
+    const screensParam = {};
+    for (const entry of options.screens) {
+        if (!entry || typeof entry.screen !== 'string' || entry.screen === '') {
+            throw new Error('renderUiFidelityPreview: each screen needs a non-empty screen name');
+        }
+        if (typeof entry.reference !== 'string' || entry.reference === '') {
+            throw new Error(`renderUiFidelityPreview: screen ${entry.screen} needs a reference path`);
+        }
+        if (!existsSync(entry.reference) || !statSync(entry.reference).isFile()) {
+            throw new Error(`renderUiFidelityPreview: reference for ${entry.screen} not found: ${entry.reference}`);
+        }
+        const base = basename(entry.reference);
+        copyFileSync(entry.reference, join(inputsDir, base));
+        screensParam[entry.screen] = base;
+    }
+    const archivePath = join(inputsDir, 'package.tar.gz');
+    if (hasArchive) {
+        const src = options.packageArchive;
+        if (!existsSync(src) || !statSync(src).isFile()) {
+            throw new Error(`renderUiFidelityPreview: packageArchive not found: ${src}`);
+        }
+        copyFileSync(src, archivePath);
+    }
+    else {
+        const dir = options.packagePath;
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+            throw new Error(`renderUiFidelityPreview: packagePath is not a directory: ${dir}`);
+        }
+        // Archive with Package.swift at the archive root; exclude build/VCS noise so
+        // the upload stays lean and matches what a careful caller would ship.
+        runTar([
+            '--exclude',
+            '.build',
+            '--exclude',
+            '.git',
+            '--exclude',
+            '.DS_Store',
+            '-czf',
+            archivePath,
+            '-C',
+            dir,
+            '.',
+        ], options.toolchainPath);
+    }
+    // The standard params.json the render script reads: screen -> reference basename.
+    writeFileSync(join(inputsDir, 'params.json'), JSON.stringify({ screens: screensParam }, null, 2) + '\n');
+    const artifactsDir = options.outDir ? resolve(options.outDir) : join(workDir, '.ci', 'artifacts');
+    mkdirSync(artifactsDir, { recursive: true });
+    const config = {
+        packagePath: null,
+        target: options.target ?? null,
+        width,
+        height,
+        scale,
+        packageSource: 'inputs',
+    };
+    const script = generateRenderScript(config);
+    const env = {
+        ...process.env,
+        CIBUILD_ARTIFACTS_DIR: artifactsDir,
+    };
+    if (options.toolchainPath) {
+        env.PATH = options.toolchainPath + ':' + (process.env.PATH ?? '');
+    }
+    const run = spawnSync('node', ['-e', script], {
+        cwd: workDir,
+        env,
+        encoding: 'utf-8',
+        maxBuffer: 32 * 1024 * 1024,
+    });
+    const resultPath = join(artifactsDir, 'protocol-result.json');
+    if (!existsSync(resultPath)) {
+        const detail = ((run.stdout || '') + '\n' + (run.stderr || '')).trim();
+        throw new Error(`renderUiFidelityPreview: render script produced no result document` +
+            (detail ? `:\n${detail}` : ''));
+    }
+    const raw = JSON.parse(readFileSync(resultPath, 'utf-8'));
+    const screens = (raw.screens || []).map((s) => ({
+        screen: s.screen,
+        status: s.status,
+        error: s.error ?? null,
+        referenceImagePath: absOrNull(artifactsDir, s.reference_image_path),
+        renderedImagePath: absOrNull(artifactsDir, s.rendered_image_path),
+        alignedImagePath: absOrNull(artifactsDir, s.aligned_image_path),
+        dimensions: s.dimensions ?? null,
+    }));
+    const buildError = raw.error ?? null;
+    const ok = buildError === null && screens.length > 0 && screens.every((s) => s.status === 'rendered');
+    return { packageSource: 'inputs', buildError, screens, artifactsDir, ok };
+}
+//# sourceMappingURL=ui-fidelity-preview.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * Tests for the local ui-fidelity render preview engine.
+ *
+ * Validation and result-shaping run with a PATH-shimmed fake `swift`/`xcrun`
+ * (the engine spawns the real generated render script, which spawns the
+ * toolchain). The CoreGraphics render itself is covered by an opt-in
+ * real-toolchain test, gated on CIBUILD_UI_FIDELITY_REAL_SWIFT, since the fake
+ * toolchain cannot exercise the actual pixel render/trim.
+ */
+export {};
+//# sourceMappingURL=ui-fidelity-preview.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ui-fidelity-preview.test.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

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

@@ -0,0 +1,168 @@
+/**
+ * Tests for the local ui-fidelity render preview engine.
+ *
+ * Validation and result-shaping run with a PATH-shimmed fake `swift`/`xcrun`
+ * (the engine spawns the real generated render script, which spawns the
+ * toolchain). The CoreGraphics render itself is covered by an opt-in
+ * real-toolchain test, gated on CIBUILD_UI_FIDELITY_REAL_SWIFT, since the fake
+ * toolchain cannot exercise the actual pixel render/trim.
+ */
+import { describe, expect, test, afterAll } from '@jest/globals';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderUiFidelityPreview } from './ui-fidelity-preview.js';
+const FIXTURE_PACKAGE = resolve(dirname(fileURLToPath(import.meta.url)), '../../../test/fixtures/ui-fidelity-package');
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+// A real, decodable 1x1 transparent PNG, used as the reference for the
+// real-toolchain test so the aligned step has something to read.
+const ONE_BY_ONE_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==', 'base64');
+const tempDirs = [];
+afterAll(() => {
+    for (const dir of tempDirs) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // best effort
+        }
+    }
+});
+function tempDir(prefix) {
+    const dir = mkdtempSync(join(tmpdir(), prefix));
+    tempDirs.push(dir);
+    return dir;
+}
+// Compact fake toolchain: enough of `swift`/`xcrun` for the inputs-mode render
+// script to discover the target, "build", "render" a PNG stub, and "trim" it.
+const FAKE_SWIFT = [
+    '#!/bin/bash',
+    'cmd="$1"; shift',
+    'case "$cmd" in',
+    '  package)',
+    '    printf \'{"name":"shipped","products":[{"name":"FixtureViews","type":{"library":["automatic"]}}]}\\n\'',
+    '    exit 0 ;;',
+    '  build)',
+    '    while [ $# -gt 0 ]; do case "$1" in --show-bin-path) echo "$PWD/.build/debug"; exit 0 ;; *) shift ;; esac; done',
+    '    exit 0 ;;',
+    '  run)',
+    '    pos=()',
+    '    while [ $# -gt 0 ]; do case "$1" in --package-path) shift 2 ;; --skip-build) shift ;; *) pos+=("$1"); shift ;; esac; done',
+    '    out="${pos[1]}"',
+    "    printf '\\x89PNG\\r\\n\\x1a\\n' > \"$out\"; printf 'fake-render' >> \"$out\"",
+    '    exit 0 ;;',
+    '  *.swift)',
+    '    out_png="$2"; aligned_png="$3"',
+    "    printf '\\x89PNG\\r\\n\\x1a\\n' > \"$out_png\"; printf 'trimmed' >> \"$out_png\"",
+    '    if [ -n "$aligned_png" ]; then printf \'\\x89PNG\\r\\n\\x1a\\n\' > "$aligned_png"; printf \'aligned\' >> "$aligned_png"; fi',
+    '    echo "TRIMDIMS 320 640 160 320 400 800"',
+    '    exit 0 ;;',
+    '  *) exit 0 ;;',
+    'esac',
+].join('\n');
+const FAKE_XCRUN = ['#!/bin/bash', 'exit 0'].join('\n');
+function fakeToolchain() {
+    const bin = tempDir('ui-fidelity-fakebin-');
+    const swiftPath = join(bin, 'swift');
+    writeFileSync(swiftPath, FAKE_SWIFT + '\n');
+    chmodSync(swiftPath, 0o755);
+    const xcrunPath = join(bin, 'xcrun');
+    writeFileSync(xcrunPath, FAKE_XCRUN + '\n');
+    chmodSync(xcrunPath, 0o755);
+    return bin;
+}
+function writeReference() {
+    const dir = tempDir('ui-fidelity-ref-');
+    const ref = join(dir, 'reference.png');
+    writeFileSync(ref, Buffer.concat([PNG_MAGIC, Buffer.from('ref')]));
+    return ref;
+}
+function isPng(filePath) {
+    return readFileSync(filePath).subarray(0, PNG_MAGIC.length).equals(PNG_MAGIC);
+}
+describe('renderUiFidelityPreview — option validation', () => {
+    test('requires exactly one of packagePath or packageArchive', () => {
+        expect(() => renderUiFidelityPreview({ screens: [] })).toThrow(/exactly one/);
+        expect(() => renderUiFidelityPreview({
+            packagePath: FIXTURE_PACKAGE,
+            packageArchive: '/tmp/x.tar.gz',
+            screens: [{ screen: 'HomeView', reference: writeReference() }],
+        })).toThrow(/exactly one/);
+    });
+    test('requires at least one screen', () => {
+        expect(() => renderUiFidelityPreview({ packagePath: FIXTURE_PACKAGE, screens: [] })).toThrow(/at least one screen/);
+    });
+    test('rejects a missing reference image', () => {
+        expect(() => renderUiFidelityPreview({
+            packagePath: FIXTURE_PACKAGE,
+            screens: [{ screen: 'HomeView', reference: '/no/such/reference.png' }],
+        })).toThrow(/reference for HomeView not found/);
+    });
+});
+describe('renderUiFidelityPreview — fake toolchain', () => {
+    test('archives the package, renders in inputs mode, and returns image paths + dims', () => {
+        const result = renderUiFidelityPreview({
+            packagePath: FIXTURE_PACKAGE,
+            screens: [{ screen: 'HomeView', reference: writeReference() }],
+            toolchainPath: fakeToolchain(),
+        });
+        expect(result.packageSource).toBe('inputs');
+        expect(result.buildError).toBeNull();
+        expect(result.ok).toBe(true);
+        expect(result.screens).toHaveLength(1);
+        const [screen] = result.screens;
+        expect(screen.screen).toBe('HomeView');
+        expect(screen.status).toBe('rendered');
+        expect(screen.error).toBeNull();
+        // Paths are absolute and point at real files the caller can read.
+        expect(screen.renderedImagePath && isPng(screen.renderedImagePath)).toBe(true);
+        expect(screen.alignedImagePath && isPng(screen.alignedImagePath)).toBe(true);
+        expect(screen.referenceImagePath && isPng(screen.referenceImagePath)).toBe(true);
+        expect(screen.dimensions).toEqual({
+            rendered_px: [320, 640],
+            logical_pt: [160, 320],
+            reference_px: [160, 320],
+        });
+    });
+    test('writes images under the requested outDir', () => {
+        const outDir = tempDir('ui-fidelity-out-');
+        const result = renderUiFidelityPreview({
+            packagePath: FIXTURE_PACKAGE,
+            screens: [{ screen: 'HomeView', reference: writeReference() }],
+            outDir,
+            toolchainPath: fakeToolchain(),
+        });
+        expect(result.artifactsDir).toBe(resolve(outDir));
+        expect(result.screens[0].renderedImagePath?.startsWith(resolve(outDir))).toBe(true);
+        expect(existsSync(join(outDir, 'ui-fidelity', 'rendered', 'HomeView.png'))).toBe(true);
+    });
+});
+// Opt-in: renders the fixture with the real Swift toolchain and asserts the
+// content trim actually crops below the forced device canvas. Requires macOS
+// with Xcode; skipped unless explicitly requested.
+describe('renderUiFidelityPreview — real toolchain', () => {
+    const realTest = process.env.CIBUILD_UI_FIDELITY_REAL_SWIFT === '1' ? test : test.skip;
+    realTest('renders the fixture and trims the filled canvas down to its content', () => {
+        const refDir = tempDir('ui-fidelity-realref-');
+        const reference = join(refDir, 'reference.png');
+        writeFileSync(reference, ONE_BY_ONE_PNG);
+        const result = renderUiFidelityPreview({
+            packagePath: FIXTURE_PACKAGE,
+            screens: [{ screen: 'HomeView', reference }],
+            renderSize: '393x852',
+            scale: 2,
+        });
+        expect(result.ok).toBe(true);
+        const [screen] = result.screens;
+        expect(screen.status).toBe('rendered');
+        expect(screen.renderedImagePath && isPng(screen.renderedImagePath)).toBe(true);
+        // HomeView fills the canvas with a uniform translucent background and a
+        // little text; the content trim must crop well below the 786x1704 (@2x)
+        // device canvas to the text region.
+        const [rw, rh] = screen.dimensions.rendered_px;
+        expect(rw).toBeLessThan(786);
+        expect(rh).toBeLessThan(1704);
+    }, 600_000);
+});
+//# sourceMappingURL=ui-fidelity-preview.test.js.map

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

@@ -157,6 +157,34 @@ export interface RenderScriptInternals {
     generateProbeSwift(options: HarnessGeneratorOptions): string;
     generateScreenSwift(screen: string, options: HarnessGeneratorOptions): string;
 }
+/**
+ * Runtime support for trimming the rendered output (package_source variants).
+ *
+ * The render entry forces the view into a fixed device-sized frame, so a
+ * component smaller than the canvas renders with transparent margins. After a
+ * screen renders, crop the PNG in place to the bounding box of its
+ * non-transparent pixels, so the rendered artifact is the component itself,
+ * tight -- no canvas, no background ambiguity for the human comparing screens.
+ *
+ * The crop is done by a small CoreGraphics helper run in Swift's
+ * script-interpreter mode (so it needs no extra harness target and reuses the
+ * one `swift` the runner already has). Best-effort: a trim failure is logged
+ * (warn-and-continue) and the untrimmed render is kept -- a cosmetic post-step
+ * never fails an otherwise good render. This is prep, not scoring: it produces
+ * a tighter image for the human's judgment and computes nothing about
+ * fidelity.
+ */
+/**
+ * The CoreGraphics trim/align helper source, run via
+ * `swift <Trim.swift> <in> <out> <aligned> <ref>` (script-interpreter mode).
+ * Crops a PNG to its content bounding box (transparent or uniform-background
+ * margins), writes a reference-sized aligned copy, and prints a TRIMDIMS line.
+ *
+ * Exported so a real-toolchain test can exercise the pixel logic directly --
+ * the fake `swift` in the unit tests cannot, which is why a background-detection
+ * bug shipped twice undetected before a real-pixel guard existed.
+ */
+export declare const TRIM_HELPER_SWIFT_SOURCE: string;
 /**
  * Evaluates the embedded generator source and returns the real functions, so
  * unit tests exercise exactly the code that ships inside the runtime script.

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

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