@invarn/cibuild 2.0.8 → 2.1.0

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

@@ -0,0 +1,238 @@
+/**
+ * Direct tests for the shared render-output post-processor.
+ *
+ * Two layers, matching how the module is built:
+ *  - The platform-neutral dimension-reporting logic (TRIMDIMS parsing, the
+ *    logical-pt rounding primitive) is pure JS embedded in the trim-stage
+ *    script. It is evaluated out of the shipped string via
+ *    getPostProcessorInternals() and tested directly, so these run in every
+ *    CI pass.
+ *  - The CoreGraphics pixel logic (content trim, uniform-background crop, the
+ *    transparent-frame fallback, align-to-reference) cannot run under a fake
+ *    `swift`, so it is exercised over crafted PNGs with the real toolchain,
+ *    gated behind CIBUILD_UI_FIDELITY_REAL_SWIFT=1 (the same gate iOS uses).
+ */
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { getPostProcessorInternals, TRIM_HELPER_SWIFT_SOURCE, } from './render-post-processor.js';
+describe('dimension reporting (TRIMDIMS parsing)', () => {
+    const { parseTrimDims } = getPostProcessorInternals();
+    test('parses a well-formed TRIMDIMS line into rendered/reference/source px', () => {
+        const dims = parseTrimDims('TRIMDIMS 320 640 160 320 400 800\n');
+        expect(dims).toEqual({
+            rendered: [320, 640],
+            reference: [160, 320],
+            source: [400, 800],
+        });
+    });
+    test('returns null when no TRIMDIMS line is present', () => {
+        expect(parseTrimDims('rendered HomeView\nsome other log line\n')).toBeNull();
+        expect(parseTrimDims('')).toBeNull();
+    });
+    test('takes the last TRIMDIMS line and ignores surrounding log noise', () => {
+        const stdout = [
+            'TRIMDIMS 10 10 10 10 10 10',
+            'helper: warming up',
+            'TRIMDIMS 320 640 160 320 400 800',
+            'helper: done',
+        ].join('\n');
+        expect(parseTrimDims(stdout)).toEqual({
+            rendered: [320, 640],
+            reference: [160, 320],
+            source: [400, 800],
+        });
+    });
+    test('returns null for a truncated or non-numeric TRIMDIMS line', () => {
+        expect(parseTrimDims('TRIMDIMS 320 640 160 320\n')).toBeNull();
+        expect(parseTrimDims('TRIMDIMS 320 x 160 320 400 800\n')).toBeNull();
+    });
+    test('reports a zero reference pair when no reference was available', () => {
+        // The helper prints "0 0" for the reference when it cannot load one; the
+        // render step maps that to a null reference_px when reporting dimensions.
+        const dims = parseTrimDims('TRIMDIMS 320 640 0 0 400 800\n');
+        expect(dims?.reference).toEqual([0, 0]);
+    });
+});
+describe('logical-pt rounding (roundTwo)', () => {
+    const { roundTwo } = getPostProcessorInternals();
+    test('rounds a logical-point value to two decimals', () => {
+        expect(roundTwo(360 / 2)).toBe(180);
+        expect(roundTwo(343 / 2)).toBe(171.5);
+        expect(roundTwo(100 / 3)).toBe(33.33);
+    });
+});
+// The CoreGraphics bounding-box/resize logic cannot run under a fake `swift`,
+// so it is exercised over crafted PNGs with the real toolchain. This is the
+// regression guard for the bug where a wrapper that fills its canvas with an
+// opaque .background(...) was not trimmed to its content: the renderer forces
+// the view into a fixed device frame whose margins are transparent, so the
+// helper must detect a solid background from the corners of the opaque region,
+// not the raw frame.
+describe('trim helper pixel logic (real toolchain)', () => {
+    const realSwiftTest = process.env.CIBUILD_UI_FIDELITY_REAL_SWIFT === '1' ? test : test.skip;
+    const { parseTrimDims } = getPostProcessorInternals();
+    const dirs = [];
+    afterAll(() => {
+        for (const dir of dirs) {
+            try {
+                rmSync(dir, { recursive: true, force: true });
+            }
+            catch {
+                // best effort
+            }
+        }
+    });
+    // PNG IHDR carries width/height as big-endian uint32 at byte offsets 16/20.
+    function pngSize(filePath) {
+        const buf = readFileSync(filePath);
+        return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+    }
+    // A parameterized fixture maker: paints opaque rectangles (colors in 0..1)
+    // onto an otherwise transparent canvas, so a single Swift program can craft
+    // every input shape the bounding-box logic must handle.
+    const MAKE_FIXTURE_SWIFT = [
+        'import Foundation',
+        'import ImageIO',
+        'import CoreGraphics',
+        'import UniformTypeIdentifiers',
+        'let out = CommandLine.arguments[1]',
+        'let spec = try! JSONSerialization.jsonObject(with: CommandLine.arguments[2].data(using: .utf8)!) as! [String: Any]',
+        'let w = spec["w"] as! Int, h = spec["h"] as! Int',
+        'let cs = CGColorSpaceCreateDeviceRGB()',
+        'let c = CGContext(data: nil, width: w, height: h, bitsPerComponent: 8, bytesPerRow: 0, space: cs, bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue)!',
+        'c.clear(CGRect(x: 0, y: 0, width: w, height: h))',
+        'func num(_ v: Any) -> Double { return Double("\\(v)")! }',
+        'for r in spec["rects"] as! [[String: Any]] {',
+        '    c.setFillColor(red: num(r["r"]!), green: num(r["g"]!), blue: num(r["b"]!), alpha: num(r["a"]!))',
+        '    c.fill(CGRect(x: num(r["x"]!), y: num(r["y"]!), width: num(r["w"]!), height: num(r["h"]!)))',
+        '}',
+        'let d = CGImageDestinationCreateWithURL(URL(fileURLWithPath: out) as CFURL, UTType.png.identifier as CFString, 1, nil)!',
+        'CGImageDestinationAddImage(d, c.makeImage()!, nil)',
+        '_ = CGImageDestinationFinalize(d)',
+    ].join('\n') + '\n';
+    const RED = { r: 1, g: 0, b: 0, a: 1 };
+    const BLUE = { r: 0, g: 0, b: 1, a: 1 };
+    const WHITE = { r: 1, g: 1, b: 1, a: 1 };
+    const PINK = { r: 1, g: 240 / 255, b: 238 / 255, a: 1 };
+    // Prints "<r> <g> <b> <a>" (0..255) for one pixel, so a test can tell padding
+    // (transparent) apart from content (opaque) in an aligned image.
+    const PROBE_SWIFT = [
+        'import Foundation',
+        'import ImageIO',
+        'import CoreGraphics',
+        'let src = CGImageSourceCreateWithURL(URL(fileURLWithPath: CommandLine.arguments[1]) as CFURL, nil)!',
+        'let img = CGImageSourceCreateImageAtIndex(src, 0, nil)!',
+        'let x = Int(CommandLine.arguments[2])!, y = Int(CommandLine.arguments[3])!',
+        'let w = img.width, h = img.height',
+        'var data = [UInt8](repeating: 0, count: w * h * 4)',
+        'let cs = CGColorSpaceCreateDeviceRGB()',
+        'let c = CGContext(data: &data, width: w, height: h, bitsPerComponent: 8, bytesPerRow: w * 4, space: cs, bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue)!',
+        'c.draw(img, in: CGRect(x: 0, y: 0, width: w, height: h))',
+        'let i = y * w * 4 + x * 4',
+        'print("\\(data[i]) \\(data[i+1]) \\(data[i+2]) \\(data[i+3])")',
+    ].join('\n') + '\n';
+    function scene() {
+        const dir = mkdtempSync(join(tmpdir(), 'ui-fidelity-postproc-'));
+        dirs.push(dir);
+        writeFileSync(join(dir, 'Make.swift'), MAKE_FIXTURE_SWIFT);
+        writeFileSync(join(dir, 'Trim.swift'), TRIM_HELPER_SWIFT_SOURCE);
+        writeFileSync(join(dir, 'Probe.swift'), PROBE_SWIFT);
+        return dir;
+    }
+    // Alpha (0..255) of one pixel in a PNG.
+    function alphaAt(dir, filePath, x, y) {
+        const probe = spawnSync('swift', [join(dir, 'Probe.swift'), filePath, String(x), String(y)], {
+            encoding: 'utf-8',
+        });
+        expect(probe.status).toBe(0);
+        return Number(probe.stdout.trim().split(/\s+/)[3]);
+    }
+    function craft(dir, name, w, h, rects) {
+        const out = join(dir, name);
+        const make = spawnSync('swift', [join(dir, 'Make.swift'), out, JSON.stringify({ w, h, rects })], { encoding: 'utf-8' });
+        expect(make.stderr + '').toBe('');
+        expect(make.status).toBe(0);
+        return out;
+    }
+    function trim(dir, input, output, aligned, reference) {
+        const args = [join(dir, 'Trim.swift'), input, output];
+        if (aligned && reference)
+            args.push(aligned, reference);
+        const result = spawnSync('swift', args, { encoding: 'utf-8' });
+        expect(result.status).toBe(0);
+        return result;
+    }
+    realSwiftTest('trims a transparent frame down to its single content rectangle', () => {
+        const dir = scene();
+        const input = craft(dir, 'in.png', 200, 200, [{ x: 30, y: 50, w: 60, h: 40, ...RED }]);
+        const out = join(dir, 'out.png');
+        trim(dir, input, out);
+        expect(pngSize(out)).toEqual({ width: 60, height: 40 });
+    }, 600_000);
+    realSwiftTest('crops an opaque uniform-background wrapper to its content card', () => {
+        const dir = scene();
+        // 420x320 transparent canvas, 375x200 white wrapper, 343x168 pink card.
+        const input = craft(dir, 'in.png', 420, 320, [
+            { x: 20, y: 40, w: 375, h: 200, ...WHITE },
+            { x: 36, y: 56, w: 343, h: 168, ...PINK },
+        ]);
+        const out = join(dir, 'out.png');
+        trim(dir, input, out);
+        // Lands on the content card, NOT the white wrapper (375x200) or the raw
+        // canvas (420x320).
+        expect(pngSize(out)).toEqual({ width: 343, height: 168 });
+    }, 600_000);
+    realSwiftTest('trims only transparency when the opaque corners disagree (fallback)', () => {
+        const dir = scene();
+        // Two differently-colored halves: the opaque bounding box is 80x80 but its
+        // corners are not one uniform color, so no background is detected and only
+        // the transparent margin is removed.
+        const input = craft(dir, 'in.png', 120, 120, [
+            { x: 20, y: 20, w: 40, h: 80, ...RED },
+            { x: 60, y: 20, w: 40, h: 80, ...BLUE },
+        ]);
+        const out = join(dir, 'out.png');
+        trim(dir, input, out);
+        expect(pngSize(out)).toEqual({ width: 80, height: 80 });
+    }, 600_000);
+    realSwiftTest('writes a reference-sized aligned image and reports all three dimensions', () => {
+        const dir = scene();
+        const input = craft(dir, 'in.png', 200, 200, [{ x: 30, y: 50, w: 60, h: 40, ...RED }]);
+        const reference = craft(dir, 'ref.png', 100, 50, [{ x: 0, y: 0, w: 100, h: 50, ...BLUE }]);
+        const out = join(dir, 'out.png');
+        const aligned = join(dir, 'aligned.png');
+        const result = trim(dir, input, out, aligned, reference);
+        // The trimmed render is the content; the aligned copy is fit onto a
+        // reference-sized canvas (preserving aspect) for a 1:1 overlay.
+        expect(pngSize(out)).toEqual({ width: 60, height: 40 });
+        expect(pngSize(aligned)).toEqual({ width: 100, height: 50 });
+        // The TRIMDIMS line reports rendered (trimmed) / reference / pre-trim
+        // source px, parsed by the same helper the runtime uses.
+        expect(parseTrimDims(result.stdout)).toEqual({
+            rendered: [60, 40],
+            reference: [100, 50],
+            source: [200, 200],
+        });
+    }, 600_000);
+    realSwiftTest('fits a wide render into a square reference without distortion (transparent letterbox)', () => {
+        const dir = scene();
+        // Content fills its canvas: a 2:1 render (80x40), all opaque red.
+        const input = craft(dir, 'in.png', 80, 40, [{ x: 0, y: 0, w: 80, h: 40, ...RED }]);
+        // Square 1:1 reference (50x50) — a deliberately different aspect ratio.
+        const reference = craft(dir, 'ref.png', 50, 50, [{ x: 0, y: 0, w: 50, h: 50, ...BLUE }]);
+        const out = join(dir, 'out.png');
+        const aligned = join(dir, 'aligned.png');
+        trim(dir, input, out, aligned, reference);
+        // Aligned stays exactly reference-sized (overlay pair holds).
+        expect(pngSize(aligned)).toEqual({ width: 50, height: 50 });
+        // Aspect preserved: the 2:1 content fits by width (50x25) and is centered,
+        // so both letterbox bands are transparent while the center is opaque
+        // content. A stretch-to-fit would make every one of these opaque.
+        expect(alphaAt(dir, aligned, 25, 3)).toBe(0); // top band
+        expect(alphaAt(dir, aligned, 25, 46)).toBe(0); // bottom band
+        expect(alphaAt(dir, aligned, 25, 25)).toBe(255); // content (center)
+    }, 600_000);
+});
+//# sourceMappingURL=render-post-processor.test.js.map

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

@@ -0,0 +1,66 @@
+/**
+ * Local Android ui-fidelity render preview.
+ *
+ * The Android sibling of `renderUiFidelityPreview` (iOS). It runs the EXACT same
+ * render path the runner uses -- the generated `ui-fidelity-render-android` node
+ * script in `package_source: "inputs"` mode (archive extract/validate, one
+ * Roborazzi record task, golden location, content trim, reference alignment,
+ * dimension reporting) -- but locally, against a self-contained Gradle render
+ * project the caller already has on disk. This lets an agent eyeball the Compose
+ * 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 project directory is
+ * archived to a temp `package.tar.gz` and fed through the same
+ * `generateAndroidRenderScript` output, so the produced rendered/aligned images
+ * and dimensions match what a remote run would produce on the same toolchain.
+ *
+ * The result shape is identical to the iOS preview (`UiFidelityPreviewResult`),
+ * so callers (and the MCP handler) treat both platforms uniformly.
+ */
+import type { UiFidelityPreviewResult, UiFidelityPreviewScreen } from './ui-fidelity-preview.js';
+export interface UiFidelityPreviewAndroidOptions {
+    /**
+     * Local Gradle render-project 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[];
+    /**
+     * Display scale used when reporting logical points (default 2). Must match the
+     * density qualifier the render test pins (xhdpi = 2x).
+     */
+    scale?: number | string;
+    /** Gradle record task to run (default "recordRoborazziDebug"). */
+    gradleTask?: 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 java/gradle/swift/tar toolchain. Optional.
+     */
+    toolchainPath?: string;
+}
+/**
+ * Build error returned when the local Android toolchain is absent, so the caller
+ * can fall back to a remote run instead of a confusing build failure. Generic
+ * wording on purpose -- this engine ships in the public build tooling and must
+ * not name product-specific tools.
+ */
+export declare const ANDROID_TOOLCHAIN_MISSING = "ANDROID_TOOLCHAIN_MISSING";
+/**
+ * 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 (and a
+ * missing local toolchain) are reported in the returned result, mirroring the
+ * remote result document and the iOS preview engine.
+ */
+export declare function renderUiFidelityPreviewAndroid(options: UiFidelityPreviewAndroidOptions): UiFidelityPreviewResult;
+//# sourceMappingURL=ui-fidelity-preview-android.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ui-fidelity-preview-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAsBH,OAAO,KAAK,EAEV,uBAAuB,EACvB,uBAAuB,EAExB,MAAM,0BAA0B,CAAC;AAElC,MAAM,WAAW,+BAA+B;IAC9C;;;;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,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAkBD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAqErE;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,uBAAuB,CA6KzB"}

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

@@ -0,0 +1,249 @@
+/**
+ * Local Android ui-fidelity render preview.
+ *
+ * The Android sibling of `renderUiFidelityPreview` (iOS). It runs the EXACT same
+ * render path the runner uses -- the generated `ui-fidelity-render-android` node
+ * script in `package_source: "inputs"` mode (archive extract/validate, one
+ * Roborazzi record task, golden location, content trim, reference alignment,
+ * dimension reporting) -- but locally, against a self-contained Gradle render
+ * project the caller already has on disk. This lets an agent eyeball the Compose
+ * 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 project directory is
+ * archived to a temp `package.tar.gz` and fed through the same
+ * `generateAndroidRenderScript` output, so the produced rendered/aligned images
+ * and dimensions match what a remote run would produce on the same toolchain.
+ *
+ * The result shape is identical to the iOS preview (`UiFidelityPreviewResult`),
+ * so callers (and the MCP handler) treat both platforms uniformly.
+ */
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join, resolve } from 'node:path';
+import { parseScale, DEFAULT_SCALE } from './ui-fidelity-render.js';
+import { DEFAULT_GRADLE_TASK, PACKAGE_ARCHIVE_BASENAME, generateAndroidRenderScript, isValidGradleTask, } from './ui-fidelity-render-android.js';
+/**
+ * Build error returned when the local Android toolchain is absent, so the caller
+ * can fall back to a remote run instead of a confusing build failure. Generic
+ * wording on purpose -- this engine ships in the public build tooling and must
+ * not name product-specific tools.
+ */
+export const ANDROID_TOOLCHAIN_MISSING = 'ANDROID_TOOLCHAIN_MISSING';
+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 project (tar exited ${result.status}): ${detail}`);
+    }
+}
+/** True if `command` resolves on the (optionally prepended) PATH. */
+function commandExists(command, pathPrepend) {
+    const env = pathPrepend
+        ? { ...process.env, PATH: pathPrepend + ':' + (process.env.PATH ?? '') }
+        : process.env;
+    const probe = process.platform === 'win32'
+        ? spawnSync('where', [command], { encoding: 'utf-8', env })
+        : spawnSync(`command -v ${command}`, { encoding: 'utf-8', env, shell: true });
+    return probe.status === 0 && (probe.stdout || '').trim() !== '';
+}
+/**
+ * Resolve the Android SDK directory: prefer an explicit `ANDROID_HOME` /
+ * `ANDROID_SDK_ROOT` env var (when it points at a real directory), otherwise
+ * fall back to the platform's default install location. This mirrors the
+ * auto-detect the Android build step already does, so a dev machine with a
+ * standard Android Studio install previews locally without the caller (or the
+ * MCP server's launch environment) having to export `ANDROID_HOME`. Returns the
+ * resolved path, or null when no SDK can be found.
+ */
+function resolveAndroidSdk() {
+    const fromEnv = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || '';
+    if (fromEnv && existsSync(fromEnv))
+        return fromEnv;
+    const home = process.env.HOME || homedir();
+    const candidates = [
+        join(home, 'Library', 'Android', 'sdk'), // macOS
+        join(home, 'Android', 'Sdk'), // Linux
+        '/usr/local/android-sdk',
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Report which env-level Android prerequisites are missing: the JVM (`java`) and
+ * the SDK (a resolved [resolveAndroidSdk] path). Gradle itself ships inside the
+ * render project (gradlew), so it is not an env-level prerequisite. Returns an
+ * empty array when the toolchain is present.
+ */
+function missingToolchain(sdk, pathPrepend) {
+    const missing = [];
+    if (!commandExists('java', pathPrepend))
+        missing.push('a JDK (java not on PATH)');
+    if (!sdk) {
+        missing.push('the Android SDK (ANDROID_HOME not set and no SDK at the default location)');
+    }
+    return missing;
+}
+/** 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 (and a
+ * missing local toolchain) are reported in the returned result, mirroring the
+ * remote result document and the iOS preview engine.
+ */
+export function renderUiFidelityPreviewAndroid(options) {
+    if (!options || typeof options !== 'object') {
+        throw new Error('renderUiFidelityPreviewAndroid: 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('renderUiFidelityPreviewAndroid: provide exactly one of packagePath or packageArchive');
+    }
+    if (!Array.isArray(options.screens) || options.screens.length === 0) {
+        throw new Error('renderUiFidelityPreviewAndroid: at least one screen is required');
+    }
+    const scale = parseScale(options.scale ?? DEFAULT_SCALE);
+    const gradleTask = String(options.gradleTask ?? DEFAULT_GRADLE_TASK);
+    if (!isValidGradleTask(gradleTask)) {
+        throw new Error(`renderUiFidelityPreviewAndroid: invalid gradleTask '${gradleTask}' ` +
+            '(expected a Gradle task path: letters, digits, and : - _)');
+    }
+    const workDir = mkdtempSync(join(tmpdir(), 'ui-fidelity-android-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('renderUiFidelityPreviewAndroid: each screen needs a non-empty screen name');
+        }
+        if (typeof entry.reference !== 'string' || entry.reference === '') {
+            throw new Error(`renderUiFidelityPreviewAndroid: screen ${entry.screen} needs a reference path`);
+        }
+        if (!existsSync(entry.reference) || !statSync(entry.reference).isFile()) {
+            throw new Error(`renderUiFidelityPreviewAndroid: reference for ${entry.screen} not found: ${entry.reference}`);
+        }
+        const base = basename(entry.reference);
+        copyFileSync(entry.reference, join(inputsDir, base));
+        screensParam[entry.screen] = base;
+    }
+    const artifactsDir = options.outDir
+        ? resolve(options.outDir)
+        : join(workDir, '.ci', 'artifacts');
+    mkdirSync(artifactsDir, { recursive: true });
+    // A render is a heavy Gradle/Robolectric build; if the dev machine has no
+    // local Android toolchain at all, fall back to a remote run with a clear
+    // message instead of letting the build fail confusingly.
+    const androidSdk = resolveAndroidSdk();
+    const missing = missingToolchain(androidSdk, options.toolchainPath);
+    if (missing.length > 0) {
+        return {
+            packageSource: 'inputs',
+            buildError: {
+                code: ANDROID_TOOLCHAIN_MISSING,
+                message: 'the local Android toolchain is unavailable (' +
+                    missing.join(', ') +
+                    '); render this Compose wrapper on a runner instead of locally',
+            },
+            screens: [],
+            artifactsDir,
+            ok: false,
+        };
+    }
+    const archivePath = join(inputsDir, PACKAGE_ARCHIVE_BASENAME);
+    if (hasArchive) {
+        const src = options.packageArchive;
+        if (!existsSync(src) || !statSync(src).isFile()) {
+            throw new Error(`renderUiFidelityPreviewAndroid: packageArchive not found: ${src}`);
+        }
+        copyFileSync(src, archivePath);
+    }
+    else {
+        const dir = options.packagePath;
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) {
+            throw new Error(`renderUiFidelityPreviewAndroid: packagePath is not a directory: ${dir}`);
+        }
+        // Archive with the settings script at the archive root; exclude Gradle/IDE/VCS
+        // build noise so the upload stays lean and matches what a careful caller would
+        // ship. gradlew is kept so the runner uses the pinned wrapper.
+        runTar([
+            '--exclude',
+            './build',
+            '--exclude',
+            '*/build',
+            '--exclude',
+            './.gradle',
+            '--exclude',
+            '*/.gradle',
+            '--exclude',
+            '.git',
+            '--exclude',
+            '.idea',
+            '--exclude',
+            '.DS_Store',
+            '--exclude',
+            'local.properties',
+            '-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 script = generateAndroidRenderScript({ scale, gradleTask });
+    const env = {
+        ...process.env,
+        CIBUILD_ARTIFACTS_DIR: artifactsDir,
+    };
+    if (options.toolchainPath) {
+        env.PATH = options.toolchainPath + ':' + (process.env.PATH ?? '');
+    }
+    // Export the resolved SDK so gradlew sees it even when ANDROID_HOME was
+    // auto-detected (env unset) rather than already present in process.env.
+    if (androidSdk) {
+        env.ANDROID_HOME = androidSdk;
+        if (!process.env.ANDROID_SDK_ROOT)
+            env.ANDROID_SDK_ROOT = androidSdk;
+    }
+    const run = spawnSync('node', ['-e', script], {
+        cwd: workDir,
+        env,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    const resultPath = join(artifactsDir, 'protocol-result.json');
+    if (!existsSync(resultPath)) {
+        const detail = ((run.stdout || '') + '\n' + (run.stderr || '')).trim();
+        throw new Error(`renderUiFidelityPreviewAndroid: 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-android.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * Tests for the local Android ui-fidelity render preview engine.
+ *
+ * The orchestration (archive, params, result shaping) and the toolchain-missing
+ * guard run with a PATH-shimmed fake `java`/`gradlew`/`swift` toolchain: the
+ * engine spawns the real generated Android render script, which spawns the
+ * toolchain. The actual Roborazzi/Robolectric render and the CoreGraphics trim
+ * are covered by an opt-in real-toolchain test, gated on
+ * CIBUILD_UI_FIDELITY_REAL_ANDROID, since the fake toolchain cannot exercise the
+ * real pixel render/trim.
+ */
+export {};
+//# sourceMappingURL=ui-fidelity-preview-android.test.d.ts.map

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

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