@invarn/cibuild 2.0.8 → 2.0.9

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;AA4CrE;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,uBAAuB,CAsKzB"}

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

@@ -0,0 +1,216 @@
+/**
+ * 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 { 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() !== '';
+}
+/**
+ * Report which env-level Android prerequisites are missing: the JVM (`java`) and
+ * the SDK (`ANDROID_HOME`/`ANDROID_SDK_ROOT`). 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(pathPrepend) {
+    const missing = [];
+    if (!commandExists('java', pathPrepend))
+        missing.push('a JDK (java not on PATH)');
+    const sdk = process.env.ANDROID_HOME || process.env.ANDROID_SDK_ROOT || '';
+    if (!sdk || !existsSync(sdk))
+        missing.push('the Android SDK (ANDROID_HOME not set)');
+    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 missing = missingToolchain(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 ?? '');
+    }
+    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"}

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

@@ -0,0 +1,247 @@
+/**
+ * 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.
+ */
+import { describe, expect, test, afterAll } from '@jest/globals';
+import { chmodSync, existsSync, mkdirSync, 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 { renderUiFidelityPreviewAndroid } from './ui-fidelity-preview-android.js';
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+// Fake `java`: presence is all the toolchain guard checks (command -v java).
+const FAKE_JAVA = ['#!/bin/bash', 'exit 0'].join('\n');
+// Fake project `gradlew`: mimics a Roborazzi record by writing one PNG per
+// screen named in FAKE_ROBORAZZI_SCREENS (comma-separated) to
+// proof/build/outputs/roborazzi/<Screen>.png.
+const FAKE_GRADLEW = [
+    '#!/bin/bash',
+    'out="proof/build/outputs/roborazzi"',
+    'mkdir -p "$out"',
+    'IFS=","',
+    'for s in $FAKE_ROBORAZZI_SCREENS; do',
+    '  [ -z "$s" ] && continue',
+    "  printf '\\x89PNG\\r\\n\\x1a\\n' > \"$out/$s.png\"",
+    '  printf \'roborazzi:%s\' "$s" >> "$out/$s.png"',
+    'done',
+    'exit 0',
+].join('\n');
+// Fake `swift`: only the script-interpreter branch the shared trim stage uses
+// (`swift <Trim.swift> <in> <out> <aligned> <ref>`). Writes trimmed + aligned
+// PNGs and emits a fixed TRIMDIMS line.
+const FAKE_SWIFT = [
+    '#!/bin/bash',
+    'case "$1" in',
+    '  *.swift)',
+    '    in_png="$2"; out_png="$3"; aligned_png="$4"',
+    "    printf '\\x89PNG\\r\\n\\x1a\\n' > \"$out_png\"",
+    '    printf \'trimmed:%s\' "$(basename "$in_png")" >> "$out_png"',
+    '    if [ -n "$aligned_png" ]; then',
+    "      printf '\\x89PNG\\r\\n\\x1a\\n' > \"$aligned_png\"",
+    '      printf \'aligned:%s\' "$(basename "$in_png")" >> "$aligned_png"',
+    '    fi',
+    '    echo "TRIMDIMS 320 640 160 320 400 800"',
+    '    exit 0 ;;',
+    '  *) exit 0 ;;',
+    'esac',
+].join('\n');
+function fakeToolchain() {
+    const bin = tempDir('ui-fidelity-android-fakebin-');
+    for (const [name, body] of [
+        ['java', FAKE_JAVA],
+        ['swift', FAKE_SWIFT],
+    ]) {
+        const p = join(bin, name);
+        writeFileSync(p, body + '\n');
+        chmodSync(p, 0o755);
+    }
+    return bin;
+}
+function isPng(filePath) {
+    return readFileSync(filePath).subarray(0, PNG_MAGIC.length).equals(PNG_MAGIC);
+}
+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;
+}
+function writeReference() {
+    const dir = tempDir('ui-fidelity-android-ref-');
+    const ref = join(dir, 'reference.png');
+    writeFileSync(ref, Buffer.concat([PNG_MAGIC, Buffer.from('ref')]));
+    return ref;
+}
+/** A minimal Gradle render-project directory with a fake gradlew. */
+function gradleProject() {
+    const dir = tempDir('ui-fidelity-android-pkg-');
+    writeFileSync(join(dir, 'settings.gradle.kts'), 'rootProject.name = "p"\ninclude(":proof")\n');
+    mkdirSync(join(dir, 'proof'), { recursive: true });
+    writeFileSync(join(dir, 'proof', 'build.gradle.kts'), '// module\n');
+    const gradlew = join(dir, 'gradlew');
+    writeFileSync(gradlew, FAKE_GRADLEW + '\n');
+    chmodSync(gradlew, 0o755);
+    return dir;
+}
+/** Run `fn` with ANDROID_HOME and the named screens set for the fake gradlew. */
+function withAndroidEnv(screens, fn) {
+    const home = tempDir('ui-fidelity-android-sdk-');
+    const saved = {
+        home: process.env.ANDROID_HOME,
+        root: process.env.ANDROID_SDK_ROOT,
+        screens: process.env.FAKE_ROBORAZZI_SCREENS,
+    };
+    process.env.ANDROID_HOME = home;
+    delete process.env.ANDROID_SDK_ROOT;
+    process.env.FAKE_ROBORAZZI_SCREENS = screens;
+    try {
+        return fn();
+    }
+    finally {
+        for (const [k, v] of [
+            ['ANDROID_HOME', saved.home],
+            ['ANDROID_SDK_ROOT', saved.root],
+            ['FAKE_ROBORAZZI_SCREENS', saved.screens],
+        ]) {
+            if (v === undefined)
+                delete process.env[k];
+            else
+                process.env[k] = v;
+        }
+    }
+}
+describe('renderUiFidelityPreviewAndroid — option validation', () => {
+    test('requires exactly one of packagePath or packageArchive', () => {
+        expect(() => renderUiFidelityPreviewAndroid({ screens: [] })).toThrow(/exactly one/);
+        expect(() => renderUiFidelityPreviewAndroid({
+            packagePath: gradleProject(),
+            packageArchive: '/tmp/x.tar.gz',
+            screens: [{ screen: 'XProof', reference: writeReference() }],
+        })).toThrow(/exactly one/);
+    });
+    test('requires at least one screen', () => {
+        expect(() => renderUiFidelityPreviewAndroid({ packagePath: gradleProject(), screens: [] })).toThrow(/at least one screen/);
+    });
+    test('rejects a missing reference image', () => {
+        expect(() => renderUiFidelityPreviewAndroid({
+            packagePath: gradleProject(),
+            screens: [{ screen: 'XProof', reference: '/no/such/reference.png' }],
+        })).toThrow(/reference for XProof not found/);
+    });
+});
+describe('renderUiFidelityPreviewAndroid — fake toolchain', () => {
+    test('archives the project, renders in inputs mode, and returns image paths + dims', () => {
+        const result = withAndroidEnv('XProof', () => renderUiFidelityPreviewAndroid({
+            packagePath: gradleProject(),
+            screens: [{ screen: 'XProof', 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('XProof');
+        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);
+        // logical_pt = rendered_px / scale (default 2); reference from the fake trim.
+        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-android-out-');
+        const result = withAndroidEnv('XProof', () => renderUiFidelityPreviewAndroid({
+            packagePath: gradleProject(),
+            screens: [{ screen: 'XProof', reference: writeReference() }],
+            outDir,
+            toolchainPath: fakeToolchain(),
+        }));
+        expect(result.artifactsDir).toBe(outDir);
+        expect(result.screens[0].renderedImagePath?.startsWith(outDir)).toBe(true);
+        expect(existsSync(join(outDir, 'ui-fidelity', 'rendered', 'XProof.png'))).toBe(true);
+    });
+});
+describe('renderUiFidelityPreviewAndroid — missing local toolchain', () => {
+    test('reports a clear toolchain-missing build error instead of crashing', () => {
+        const savedHome = process.env.ANDROID_HOME;
+        const savedRoot = process.env.ANDROID_SDK_ROOT;
+        delete process.env.ANDROID_HOME;
+        delete process.env.ANDROID_SDK_ROOT;
+        try {
+            const result = renderUiFidelityPreviewAndroid({
+                packagePath: gradleProject(),
+                screens: [{ screen: 'XProof', reference: writeReference() }],
+            });
+            expect(result.ok).toBe(false);
+            expect(result.buildError?.code).toBe('ANDROID_TOOLCHAIN_MISSING');
+            expect(result.buildError?.message).toMatch(/Android SDK|JDK/);
+            // Degrades cleanly: it never tried to render.
+            expect(result.screens).toEqual([]);
+        }
+        finally {
+            if (savedHome === undefined)
+                delete process.env.ANDROID_HOME;
+            else
+                process.env.ANDROID_HOME = savedHome;
+            if (savedRoot === undefined)
+                delete process.env.ANDROID_SDK_ROOT;
+            else
+                process.env.ANDROID_SDK_ROOT = savedRoot;
+        }
+    });
+});
+// Opt-in: previews the committed Roborazzi fixture with the real Android
+// toolchain and asserts a non-blank paired render at the expected size. Requires
+// the Android toolchain (JDK + SDK) and warm Roborazzi caches; gated behind
+// CIBUILD_UI_FIDELITY_REAL_ANDROID=1 (the Android analog of the iOS real-Swift
+// gate). It needs ANDROID_HOME set on the dev machine.
+describe('renderUiFidelityPreviewAndroid — real toolchain', () => {
+    const realAndroidTest = process.env.CIBUILD_UI_FIDELITY_REAL_ANDROID === '1' ? test : test.skip;
+    // A real, decodable 1x1 PNG so the trim helper's reference load/align succeeds.
+    const ONE_BY_ONE_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', 'base64');
+    const FIXTURE_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../cibuild-runner/scripts/roborazzi-fixture');
+    realAndroidTest('previews the Roborazzi fixture and returns a paired, non-blank render', () => {
+        const refDir = tempDir('ui-fidelity-android-realref-');
+        const reference = join(refDir, 'reference.png');
+        writeFileSync(reference, ONE_BY_ONE_PNG);
+        const result = renderUiFidelityPreviewAndroid({
+            packagePath: FIXTURE_DIR,
+            screens: [{ screen: 'XProof', reference }],
+            scale: 2,
+        });
+        expect(result.buildError).toBeNull();
+        expect(result.ok).toBe(true);
+        const [screen] = result.screens;
+        expect(screen.status).toBe('rendered');
+        expect(screen.renderedImagePath && isPng(screen.renderedImagePath)).toBe(true);
+        expect(screen.alignedImagePath && isPng(screen.alignedImagePath)).toBe(true);
+        const [rw, rh] = screen.dimensions.rendered_px;
+        expect(rw).toBeGreaterThan(0);
+        expect(rh).toBeGreaterThan(0);
+    }, 600_000);
+});
+//# sourceMappingURL=ui-fidelity-preview-android.test.js.map

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

@@ -0,0 +1,92 @@
+/**
+ * ui-fidelity-render-android step implementation.
+ *
+ * Renders parameterless Jetpack Compose wrappers from a self-contained Gradle
+ * project to PNGs via Roborazzi + Robolectric on the JVM — no device, no
+ * emulator — on a macOS runner. The step returns a self-contained node script
+ * that, at runtime:
+ *
+ *   1. Reads `.ci/inputs/params.json`
+ *      ({ "screens": { "<ScreenName>": "<referenceFileBasename>" } });
+ *      reference images live at `.ci/inputs/<basename>`.
+ *   2. Extracts and validates the shipped Gradle project shipped as
+ *      `.ci/inputs/package.tar.gz` (single project root carrying a settings
+ *      script, bounded extracted size, safe member paths).
+ *   3. Runs the project's Roborazzi record task (default
+ *      `recordRoborazziDebug`) once. A build/compile failure means the project
+ *      does not render and every screen is marked RENDER_UNSUPPORTED — the
+ *      Android analog of the iOS probe gate (one Gradle module compiles as a
+ *      unit, so a wrapper compile error cannot be isolated to one screen).
+ *   4. Locates each screen's Roborazzi golden inside the project (recorded as
+ *      `build/outputs/roborazzi/...render<ScreenName>.png` from a test method
+ *      named render<ScreenName>, or a flat `<ScreenName>.png`), runs it through
+ *      the shared render-output
+ *      post-processor (content trim, reference alignment, dimension
+ *      reporting), and writes, inside the artifacts dir
+ *      (${CIBUILD_ARTIFACTS_DIR:-.ci/artifacts}):
+ *      - ui-fidelity/rendered/<Screen>.png
+ *      - ui-fidelity/references/<Screen>.png
+ *      - ui-fidelity/aligned/<Screen>.png
+ *      - protocol-result.json (always written, even on partial/total failure)
+ *   5. Exits non-zero iff the archive was invalid or any screen is not
+ *      "rendered".
+ *
+ * The result payload and artifact layout are identical in shape to the iOS
+ * ui-fidelity-render step, so the dashboard compare view, the artifact
+ * download tool, and the agent's compare flow are reused unchanged. Image
+ * paths in protocol-result.json are relative to the artifacts dir, and error
+ * messages are sanitized so absolute runner paths are rewritten before they
+ * are stored.
+ */
+import { BaseStepExecutor } from './base.js';
+import type { StepDef, CIConfig } from '../../types.js';
+import type { ValidationRequirement } from '../validation-types.js';
+/** Inputs for the ui-fidelity-render-android step. */
+export interface UiFidelityRenderAndroidInputs {
+    /**
+     * Display scale factor applied when reporting logical points (default 2).
+     * Must match the density qualifier the render test pins (xhdpi = 2x), so
+     * logical_pt = rendered_px / scale lines up with design references.
+     */
+    scale?: number | string;
+    /**
+     * Gradle task that records the Roborazzi PNGs (default
+     * "recordRoborazziDebug"). Run from the project root, so it executes in
+     * whichever module declares it.
+     */
+    gradle_task?: string;
+}
+/**
+ * Default Roborazzi record task. Run from the project root so Gradle resolves
+ * it in whichever subproject declares it.
+ */
+export declare const DEFAULT_GRADLE_TASK = "recordRoborazziDebug";
+/** Basename of the shipped Gradle-project archive inside the run-inputs dir. */
+export declare const PACKAGE_ARCHIVE_BASENAME = "package.tar.gz";
+/** Renderer identifier recorded in protocol-result.json. */
+export declare const ANDROID_RENDERER = "roborazzi-robolectric";
+/**
+ * Validates a Gradle task name: a non-empty token of letters, digits, and the
+ * separators Gradle allows in a task path (`:`, `-`, `_`). Rejects shell
+ * metacharacters so the task is safe to pass to the runner.
+ */
+export declare function isValidGradleTask(task: string): boolean;
+/** Config baked into the generated runtime script at YAML-conversion time. */
+export interface AndroidRenderScriptConfig {
+    scale: number;
+    gradleTask: string;
+}
+/**
+ * Generates the self-contained runtime node script for the step. Pure function
+ * of its config — exported so tests can execute the script directly.
+ */
+export declare function generateAndroidRenderScript(config: AndroidRenderScriptConfig): string;
+/**
+ * ui-fidelity-render-android step executor. Returns a node-kind StepDef whose
+ * script performs the render at runtime on the macOS runner.
+ */
+export declare class UiFidelityRenderAndroidStepExecutor extends BaseStepExecutor {
+    getValidationRequirements(_inputs: UiFidelityRenderAndroidInputs, _env: Record<string, string>, _config: CIConfig): ValidationRequirement[];
+    execute(inputs: UiFidelityRenderAndroidInputs, _env: Record<string, string>, _config: CIConfig): Promise<StepDef>;
+}
+//# sourceMappingURL=ui-fidelity-render-android.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAIpE,sDAAsD;AACtD,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,mBAAmB,CAAC;AAEzD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAExD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAqnBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAUrF;AAED;;;GAGG;AACH,qBAAa,mCAAoC,SAAQ,gBAAgB;IACvE,yBAAyB,CACvB,OAAO,EAAE,6BAA6B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,qBAAqB,EAAE;IAepB,OAAO,CACX,MAAM,EAAE,6BAA6B,EACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,OAAO,EAAE,QAAQ,GAChB,OAAO,CAAC,OAAO,CAAC;CAgBpB"}