@invarn/cibuild 2.3.8 → 2.4.0

package/dist/src/yaml/steps/trim-align.js

@@ -0,0 +1,348 @@
+/**
+ * Pure-JS trim/align helper — the CoreGraphics port (fidelity-linux 06).
+ *
+ * This is a PORT of the embedded Swift helper that used to live in
+ * render-post-processor.ts (`TRIM_HELPER_SWIFT_SOURCE`), not a redesign: the
+ * bounding-box semantics (alpha pass, corner-derived uniform background,
+ * tolerance 4, never-crop-to-nothing fallback), the fit-pad geometry
+ * (aspect-preserving scale, centered, transparent letterbox) and the TRIMDIMS
+ * contract are byte-for-byte the Swift behavior. CoreGraphics/ImageIO do not
+ * exist on Linux, so the pixel work moved into the ci binary itself (pngjs is
+ * pure JS and bundles via bundle.mjs) — iOS and Android now run the SAME bytes,
+ * and output pixels can only change with our lockfile, never with a runner OS
+ * upgrade.
+ *
+ * Port-fidelity notes, load-bearing for the corpus gate:
+ * - The Swift helper ANALYZED pixels through a premultiplied-alpha CGContext
+ *   but CROPPED the original (straight-alpha) image. We mirror both: the
+ *   bounding box is computed over premultiplied values, the trimmed output is
+ *   a raw copy of the source pixels.
+ * - The Swift aligned output was drawn through a premultiplied context and
+ *   unpremultiplied on PNG encode, which is lossy on semi-transparent pixels;
+ *   we reproduce that roundtrip. Where CoreGraphics RESAMPLED (trimmed size ≠
+ *   reference size), its proprietary `.high` interpolation is not bit-exactly
+ *   reproducible — we use bilinear filtering in premultiplied space. The
+ *   trimmed image and TRIMDIMS never depend on resampling and are the
+ *   pixel-identical surface the corpus gate enforces.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { PNG } from 'pngjs';
+/** Mirror of the Swift helper's exit codes. */
+export const TRIM_EXIT_USAGE = 64;
+export const TRIM_EXIT_UNREADABLE = 65;
+export const TRIM_EXIT_NO_CONTENT = 66;
+export const TRIM_EXIT_WRITE_FAILED = 68;
+// Tight tolerance: exact solid fills match, near-colored content does not.
+// (Same constant, same meaning as the Swift helper.)
+const TOLERANCE = 4;
+/**
+ * Premultiply one straight-alpha channel value, matching the rounding
+ * CoreGraphics/vImage applies when drawing into a premultiplied context:
+ * (v * a + 127) / 255, truncated.
+ */
+function premultiply(value, alpha) {
+    return ((value * alpha + 127) / 255) | 0;
+}
+/**
+ * Un-premultiply one channel value, matching ImageIO's PNG encode of a
+ * premultiplied bitmap. Transparent pixels collapse to zero (which is also
+ * why the Swift aligned output zeroes the RGB of fully-transparent pixels).
+ */
+function unpremultiply(value, alpha) {
+    if (alpha === 0)
+        return 0;
+    const v = Math.round((value * 255) / alpha);
+    return v > 255 ? 255 : v;
+}
+/**
+ * Bounding box of content: pixels that are neither transparent nor part of a
+ * uniform solid background. Two passes, because the renderer forces the view
+ * into a fixed device frame whose margins are transparent: (1) bound the
+ * non-transparent pixels, then (2) detect a uniform opaque background from the
+ * CORNERS OF THAT OPAQUE BOX — not the raw frame, whose corners are the
+ * transparent device margin — and bound everything that is not that
+ * background. A wrapper that fills the canvas with .background(.white) is thus
+ * trimmed to its real content. When the opaque corners disagree, only
+ * transparency is trimmed. Top-left image coordinates.
+ *
+ * `data` is straight-alpha RGBA8 (as pngjs decodes); the color comparisons run
+ * on premultiplied values to mirror the Swift helper's analysis context.
+ */
+export function contentBoundingBox(data, width, height) {
+    if (width === 0 || height === 0)
+        return null;
+    const bytesPerRow = width * 4;
+    // Pass 1: bounding box of all non-transparent pixels.
+    let aMinX = width;
+    let aMinY = height;
+    let aMaxX = -1;
+    let aMaxY = -1;
+    for (let y = 0; y < height; y++) {
+        const rowBase = y * bytesPerRow;
+        for (let x = 0; x < width; x++) {
+            if (data[rowBase + x * 4 + 3] > 0) {
+                if (x < aMinX)
+                    aMinX = x;
+                if (x > aMaxX)
+                    aMaxX = x;
+                if (y < aMinY)
+                    aMinY = y;
+                if (y > aMaxY)
+                    aMaxY = y;
+            }
+        }
+    }
+    if (aMaxX < 0)
+        return null;
+    const opaqueBox = {
+        x: aMinX,
+        y: aMinY,
+        width: aMaxX - aMinX + 1,
+        height: aMaxY - aMinY + 1,
+    };
+    // Premultiplied RGBA of one pixel — the analysis view of the image.
+    function sample(x, y) {
+        const i = y * bytesPerRow + x * 4;
+        const a = data[i + 3];
+        return [
+            premultiply(data[i], a),
+            premultiply(data[i + 1], a),
+            premultiply(data[i + 2], a),
+            a,
+        ];
+    }
+    // Detect a uniform opaque background from the corners of the opaque box.
+    // As in the Swift helper, every corner is compared against the FIRST corner
+    // (background only ever holds corners[0] or null).
+    const corners = [
+        sample(aMinX, aMinY),
+        sample(aMaxX, aMinY),
+        sample(aMinX, aMaxY),
+        sample(aMaxX, aMaxY),
+    ];
+    let background = corners[0];
+    for (const c of corners) {
+        if (background !== null) {
+            if (c[3] === 0 ||
+                Math.abs(c[0] - background[0]) > TOLERANCE ||
+                Math.abs(c[1] - background[1]) > TOLERANCE ||
+                Math.abs(c[2] - background[2]) > TOLERANCE ||
+                Math.abs(c[3] - background[3]) > TOLERANCE) {
+                background = null;
+            }
+        }
+    }
+    // No uniform background: the opaque box is the content.
+    if (background === null)
+        return opaqueBox;
+    const bg = background;
+    // Pass 2: within the opaque box, bound everything that is not the background.
+    let minX = aMaxX + 1;
+    let minY = aMaxY + 1;
+    let maxX = aMinX - 1;
+    let maxY = aMinY - 1;
+    for (let y = aMinY; y <= aMaxY; y++) {
+        const rowBase = y * bytesPerRow;
+        for (let x = aMinX; x <= aMaxX; x++) {
+            const idx = rowBase + x * 4;
+            const a = data[idx + 3];
+            if (a === 0)
+                continue;
+            const r = premultiply(data[idx], a);
+            const g = premultiply(data[idx + 1], a);
+            const b = premultiply(data[idx + 2], a);
+            if (Math.abs(r - bg[0]) <= TOLERANCE &&
+                Math.abs(g - bg[1]) <= TOLERANCE &&
+                Math.abs(b - bg[2]) <= TOLERANCE &&
+                Math.abs(a - bg[3]) <= TOLERANCE) {
+                continue;
+            }
+            if (x < minX)
+                minX = x;
+            if (x > maxX)
+                maxX = x;
+            if (y < minY)
+                minY = y;
+            if (y > maxY)
+                maxY = y;
+        }
+    }
+    // All background, no distinct content: keep the opaque box, never crop to nothing.
+    if (maxX < minX)
+        return opaqueBox;
+    return { x: minX, y: minY, width: maxX - minX + 1, height: maxY - minY + 1 };
+}
+/** Raw pixel copy of a region — the Swift `image.cropping(to:)` equivalent. */
+export function cropImage(src, box) {
+    const out = new PNG({ width: box.width, height: box.height });
+    for (let y = 0; y < box.height; y++) {
+        const srcStart = ((box.y + y) * src.width + box.x) * 4;
+        src.data.copy(out.data, y * box.width * 4, srcStart, srcStart + box.width * 4);
+    }
+    return out;
+}
+/**
+ * Draw `src` centered on a transparent reference-sized canvas, scaled to fit
+ * while PRESERVING its aspect ratio. Unlike a stretch-to-fit (which distorts
+ * proportions when the aspect ratios differ), this keeps the rendered shape
+ * honest: an aspect mismatch shows as transparent letterbox/pillarbox padding
+ * rather than a squished image, while the canvas stays exactly reference-sized
+ * so the pair still overlays 1:1.
+ *
+ * Compositing happens in premultiplied space with an unpremultiply on the way
+ * out, mirroring the Swift context roundtrip. Resampling is bilinear (see the
+ * module docblock for why CG's `.high` filter is not reproducible).
+ */
+export function fitPad(src, width, height) {
+    if (width <= 0 || height <= 0)
+        return null;
+    const out = new PNG({ width, height }); // zero-initialized: transparent canvas
+    const scale = Math.min(width / src.width, height / src.height);
+    const drawW = src.width * scale;
+    const drawH = src.height * scale;
+    const originX = (width - drawW) / 2;
+    const originY = (height - drawH) / 2;
+    // Premultiplied source, sampled by the filter below.
+    const pre = Buffer.alloc(src.width * src.height * 4);
+    for (let i = 0; i < src.width * src.height * 4; i += 4) {
+        const a = src.data[i + 3];
+        pre[i] = premultiply(src.data[i], a);
+        pre[i + 1] = premultiply(src.data[i + 1], a);
+        pre[i + 2] = premultiply(src.data[i + 2], a);
+        pre[i + 3] = a;
+    }
+    const identity = scale === 1 && Number.isInteger(originX) && Number.isInteger(originY);
+    for (let dy = 0; dy < height; dy++) {
+        for (let dx = 0; dx < width; dx++) {
+            const cx = dx + 0.5;
+            const cy = dy + 0.5;
+            if (cx < originX || cx > originX + drawW || cy < originY || cy > originY + drawH) {
+                continue; // transparent padding
+            }
+            const di = (dy * width + dx) * 4;
+            if (identity) {
+                // 1:1 placement — no filtering, but still the premultiply roundtrip
+                // the Swift context applied.
+                const si = ((dy - originY) * src.width + (dx - originX)) * 4;
+                const a = pre[si + 3];
+                out.data[di] = unpremultiply(pre[si], a);
+                out.data[di + 1] = unpremultiply(pre[si + 1], a);
+                out.data[di + 2] = unpremultiply(pre[si + 2], a);
+                out.data[di + 3] = a;
+                continue;
+            }
+            // Bilinear sample at the source-space position of this dest pixel center,
+            // clamped to the source edges.
+            const sx = (cx - originX) / scale - 0.5;
+            const sy = (cy - originY) / scale - 0.5;
+            const x0 = Math.floor(sx);
+            const y0 = Math.floor(sy);
+            const fx = sx - x0;
+            const fy = sy - y0;
+            const clampX = (v) => (v < 0 ? 0 : v >= src.width ? src.width - 1 : v);
+            const clampY = (v) => (v < 0 ? 0 : v >= src.height ? src.height - 1 : v);
+            const i00 = (clampY(y0) * src.width + clampX(x0)) * 4;
+            const i10 = (clampY(y0) * src.width + clampX(x0 + 1)) * 4;
+            const i01 = (clampY(y0 + 1) * src.width + clampX(x0)) * 4;
+            const i11 = (clampY(y0 + 1) * src.width + clampX(x0 + 1)) * 4;
+            const w00 = (1 - fx) * (1 - fy);
+            const w10 = fx * (1 - fy);
+            const w01 = (1 - fx) * fy;
+            const w11 = fx * fy;
+            const blend = (offset) => pre[i00 + offset] * w00 +
+                pre[i10 + offset] * w10 +
+                pre[i01 + offset] * w01 +
+                pre[i11 + offset] * w11;
+            const a = Math.round(blend(3));
+            out.data[di] = unpremultiply(Math.round(blend(0)), a);
+            out.data[di + 1] = unpremultiply(Math.round(blend(1)), a);
+            out.data[di + 2] = unpremultiply(Math.round(blend(2)), a);
+            out.data[di + 3] = a;
+        }
+    }
+    return out;
+}
+/**
+ * The helper entry point, argv-compatible with the retired Swift helper:
+ * `[in.png, out.png]` or `[in.png, out.png, aligned.png, reference.png]`.
+ * Crops the input to its content bounding box, optionally writes a
+ * reference-sized aligned copy (best-effort), and reports a TRIMDIMS line.
+ * Same exit codes, same stdout/stderr shape as the Swift helper.
+ */
+export function runTrimAlign(argv) {
+    if (argv.length < 2) {
+        return {
+            status: TRIM_EXIT_USAGE,
+            stdout: '',
+            stderr: 'usage: fidelity-trim <in.png> <out.png> [<aligned.png> <reference.png>]',
+        };
+    }
+    const [inputPath, outputPath] = argv;
+    let image;
+    try {
+        image = PNG.sync.read(readFileSync(inputPath));
+    }
+    catch {
+        return {
+            status: TRIM_EXIT_UNREADABLE,
+            stdout: '',
+            stderr: 'could not read image at ' + inputPath,
+        };
+    }
+    const box = contentBoundingBox(image.data, image.width, image.height);
+    if (box === null) {
+        return {
+            status: TRIM_EXIT_NO_CONTENT,
+            stdout: '',
+            stderr: 'no content to trim (image is uniform)',
+        };
+    }
+    const cropped = cropImage(image, box);
+    try {
+        writeFileSync(outputPath, PNG.sync.write(cropped));
+    }
+    catch {
+        return {
+            status: TRIM_EXIT_WRITE_FAILED,
+            stdout: '',
+            stderr: 'could not write trimmed PNG to ' + outputPath,
+        };
+    }
+    // Optional aligned output: the trimmed image fit onto a reference-sized
+    // canvas, preserving aspect ratio (transparent letterbox/pillarbox padding
+    // when aspect ratios differ). A reference-sized, undistorted overlay pair.
+    // Best-effort; dimensions are reported either way.
+    let referenceWidth = 0;
+    let referenceHeight = 0;
+    if (argv.length >= 4) {
+        const alignedPath = argv[2];
+        const referencePath = argv[3];
+        let reference = null;
+        try {
+            reference = PNG.sync.read(readFileSync(referencePath));
+        }
+        catch {
+            reference = null;
+        }
+        if (reference !== null) {
+            referenceWidth = reference.width;
+            referenceHeight = reference.height;
+            const aligned = fitPad(cropped, referenceWidth, referenceHeight);
+            if (aligned !== null) {
+                try {
+                    writeFileSync(alignedPath, PNG.sync.write(aligned));
+                }
+                catch {
+                    // best effort, as in the Swift helper
+                }
+            }
+        }
+    }
+    // Report: rendered (trimmed) px, reference px (0 0 when unavailable), then
+    // the pre-trim source px so the caller can log how much margin was removed.
+    const stdout = 'TRIMDIMS ' +
+        [box.width, box.height, referenceWidth, referenceHeight, image.width, image.height].join(' ') +
+        '\n';
+    return { status: 0, stdout, stderr: '' };
+}
+//# sourceMappingURL=trim-align.js.map

package/dist/src/yaml/steps/trim-align.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Unit tests for the pure-JS trim/align helper (the CoreGraphics port).
+ *
+ * These exercise the pixel logic directly with pngjs-crafted images — no
+ * `swift`, no real toolchain — so the bounding-box/crop/pad semantics that
+ * previously needed CIBUILD_UI_FIDELITY_REAL_SWIFT=1 now run in every CI pass.
+ * The Swift-vs-JS equivalence itself is guarded by the corpus gate in
+ * trim-align-corpus.test.ts (real toolchain, gated).
+ */
+export {};
+//# sourceMappingURL=trim-align.test.d.ts.map

package/dist/src/yaml/steps/trim-align.test.d.ts.map

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

package/dist/src/yaml/steps/trim-align.test.js

@@ -0,0 +1,258 @@
+/**
+ * Unit tests for the pure-JS trim/align helper (the CoreGraphics port).
+ *
+ * These exercise the pixel logic directly with pngjs-crafted images — no
+ * `swift`, no real toolchain — so the bounding-box/crop/pad semantics that
+ * previously needed CIBUILD_UI_FIDELITY_REAL_SWIFT=1 now run in every CI pass.
+ * The Swift-vs-JS equivalence itself is guarded by the corpus gate in
+ * trim-align-corpus.test.ts (real toolchain, gated).
+ */
+import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PNG } from 'pngjs';
+import { describe, test, expect, afterAll } from '@jest/globals';
+import { runTrimAlign } from './trim-align.js';
+const RED = { r: 255, g: 0, b: 0, a: 255 };
+const BLUE = { r: 0, g: 0, b: 255, a: 255 };
+const WHITE = { r: 255, g: 255, b: 255, a: 255 };
+const PINK = { r: 255, g: 240, b: 238, a: 255 };
+/** Paint opaque rects onto a transparent canvas, top-left coordinates. */
+function craftPng(w, h, rects) {
+    const png = new PNG({ width: w, height: h });
+    for (const rect of rects) {
+        for (let y = rect.y; y < rect.y + rect.h; y++) {
+            for (let x = rect.x; x < rect.x + rect.w; x++) {
+                const i = (y * w + x) * 4;
+                png.data[i] = rect.r;
+                png.data[i + 1] = rect.g;
+                png.data[i + 2] = rect.b;
+                png.data[i + 3] = rect.a;
+            }
+        }
+    }
+    return PNG.sync.write(png);
+}
+function pngSize(filePath) {
+    const buf = readFileSync(filePath);
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+}
+function pixelAt(filePath, x, y) {
+    const png = PNG.sync.read(readFileSync(filePath));
+    const i = (y * png.width + x) * 4;
+    return [png.data[i], png.data[i + 1], png.data[i + 2], png.data[i + 3]];
+}
+const dirs = [];
+function scene() {
+    const dir = mkdtempSync(join(tmpdir(), 'trim-align-js-'));
+    dirs.push(dir);
+    return dir;
+}
+afterAll(() => {
+    for (const dir of dirs) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+            // best effort
+        }
+    }
+});
+// ---- trim ----------------------------------------------------------------------
+describe('runTrimAlign — trim', () => {
+    test('trims a transparent frame down to its single content rectangle', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(200, 200, [{ x: 30, y: 50, w: 60, h: 40, ...RED }]));
+        const out = join(dir, 'out.png');
+        const result = runTrimAlign([input, out]);
+        expect(result.stderr).toBe('');
+        expect(result.status).toBe(0);
+        expect(pngSize(out)).toEqual({ width: 60, height: 40 });
+        // The crop is a raw pixel copy of the content region.
+        expect(pixelAt(out, 0, 0)).toEqual([255, 0, 0, 255]);
+        expect(pixelAt(out, 59, 39)).toEqual([255, 0, 0, 255]);
+        // TRIMDIMS: rendered (trimmed) px, reference px (0 0 without one), source px.
+        expect(result.stdout.trim()).toBe('TRIMDIMS 60 40 0 0 200 200');
+    });
+    test('crops an opaque uniform-background wrapper to its content card', () => {
+        const dir = scene();
+        // 420x320 transparent canvas, 375x200 white wrapper, 343x168 pink card.
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(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');
+        const result = runTrimAlign([input, out]);
+        expect(result.status).toBe(0);
+        // Lands on the content card, NOT the white wrapper (375x200) or the raw
+        // canvas (420x320).
+        expect(pngSize(out)).toEqual({ width: 343, height: 168 });
+    });
+    test('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 = join(dir, 'in.png');
+        writeFileSync(input, craftPng(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');
+        const result = runTrimAlign([input, out]);
+        expect(result.status).toBe(0);
+        expect(pngSize(out)).toEqual({ width: 80, height: 80 });
+    });
+    test('keeps a fully-opaque uniform image whole (never crops to nothing)', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(64, 48, [{ x: 0, y: 0, w: 64, h: 48, ...WHITE }]));
+        const out = join(dir, 'out.png');
+        const result = runTrimAlign([input, out]);
+        // All four corners agree (uniform background) and pass 2 finds no distinct
+        // content — the opaque box (the whole image) is kept, exit 0.
+        expect(result.status).toBe(0);
+        expect(pngSize(out)).toEqual({ width: 64, height: 48 });
+        expect(result.stdout.trim()).toBe('TRIMDIMS 64 48 0 0 64 48');
+    });
+    test('is a no-op crop when content touches every edge', () => {
+        const dir = scene();
+        // Content fills the canvas with differing corner colors: nothing to trim.
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(50, 30, [
+            { x: 0, y: 0, w: 25, h: 30, ...RED },
+            { x: 25, y: 0, w: 25, h: 30, ...BLUE },
+        ]));
+        const out = join(dir, 'out.png');
+        const result = runTrimAlign([input, out]);
+        expect(result.status).toBe(0);
+        expect(pngSize(out)).toEqual({ width: 50, height: 30 });
+        // Raw copy: pixels survive untouched.
+        expect(pixelAt(out, 0, 0)).toEqual([255, 0, 0, 255]);
+        expect(pixelAt(out, 49, 29)).toEqual([0, 0, 255, 255]);
+    });
+});
+// ---- align ---------------------------------------------------------------------
+describe('runTrimAlign — aligned output', () => {
+    test('writes a reference-sized aligned image and reports all three dimensions', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(200, 200, [{ x: 30, y: 50, w: 60, h: 40, ...RED }]));
+        const reference = join(dir, 'ref.png');
+        writeFileSync(reference, craftPng(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 = runTrimAlign([input, out, aligned, reference]);
+        expect(result.status).toBe(0);
+        // 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 });
+        expect(result.stdout.trim()).toBe('TRIMDIMS 60 40 100 50 200 200');
+    });
+    test('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 = join(dir, 'in.png');
+        writeFileSync(input, craftPng(80, 40, [{ x: 0, y: 0, w: 80, h: 40, ...RED }]));
+        // Square 1:1 reference (50x50) — a deliberately different aspect ratio.
+        const reference = join(dir, 'ref.png');
+        writeFileSync(reference, craftPng(50, 50, [{ x: 0, y: 0, w: 50, h: 50, ...BLUE }]));
+        const out = join(dir, 'out.png');
+        const aligned = join(dir, 'aligned.png');
+        runTrimAlign([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(pixelAt(aligned, 25, 3)[3]).toBe(0); // top band
+        expect(pixelAt(aligned, 25, 46)[3]).toBe(0); // bottom band
+        expect(pixelAt(aligned, 25, 25)[3]).toBe(255); // content (center)
+    });
+    test('upscales into a larger reference and downscales into a smaller one', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(40, 40, [{ x: 0, y: 0, w: 40, h: 40, ...RED }]));
+        const out = join(dir, 'out.png');
+        // Reference smaller than the render: content is downscaled to fit.
+        const smallRef = join(dir, 'ref-small.png');
+        writeFileSync(smallRef, craftPng(20, 20, [{ x: 0, y: 0, w: 20, h: 20, ...BLUE }]));
+        const alignedSmall = join(dir, 'aligned-small.png');
+        let result = runTrimAlign([input, out, alignedSmall, smallRef]);
+        expect(result.status).toBe(0);
+        expect(pngSize(alignedSmall)).toEqual({ width: 20, height: 20 });
+        expect(pixelAt(alignedSmall, 10, 10)).toEqual([255, 0, 0, 255]);
+        // Reference larger than the render: content is upscaled to fit.
+        const bigRef = join(dir, 'ref-big.png');
+        writeFileSync(bigRef, craftPng(80, 80, [{ x: 0, y: 0, w: 80, h: 80, ...BLUE }]));
+        const alignedBig = join(dir, 'aligned-big.png');
+        result = runTrimAlign([input, out, alignedBig, bigRef]);
+        expect(result.status).toBe(0);
+        expect(pngSize(alignedBig)).toEqual({ width: 80, height: 80 });
+        expect(pixelAt(alignedBig, 40, 40)).toEqual([255, 0, 0, 255]);
+    });
+    test('an identity-size reference yields a pixel-identical aligned copy for opaque content', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(30, 20, [
+            { x: 0, y: 0, w: 15, h: 20, ...RED },
+            { x: 15, y: 0, w: 15, h: 20, ...BLUE },
+        ]));
+        const reference = join(dir, 'ref.png');
+        writeFileSync(reference, craftPng(30, 20, [{ x: 0, y: 0, w: 30, h: 20, ...WHITE }]));
+        const out = join(dir, 'out.png');
+        const aligned = join(dir, 'aligned.png');
+        const result = runTrimAlign([input, out, aligned, reference]);
+        expect(result.status).toBe(0);
+        const outPng = PNG.sync.read(readFileSync(out));
+        const alignedPng = PNG.sync.read(readFileSync(aligned));
+        expect(alignedPng.width).toBe(outPng.width);
+        expect(alignedPng.height).toBe(outPng.height);
+        expect(Buffer.compare(alignedPng.data, outPng.data)).toBe(0);
+    });
+    test('a missing reference is best-effort: no aligned image, zero reference dims', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(100, 100, [{ x: 10, y: 10, w: 50, h: 30, ...RED }]));
+        const out = join(dir, 'out.png');
+        const aligned = join(dir, 'aligned.png');
+        const result = runTrimAlign([input, out, aligned, join(dir, 'nope.png')]);
+        expect(result.status).toBe(0);
+        expect(existsSync(aligned)).toBe(false);
+        expect(result.stdout.trim()).toBe('TRIMDIMS 50 30 0 0 100 100');
+    });
+});
+// ---- failure contract ------------------------------------------------------------
+describe('runTrimAlign — failure contract (Swift helper exit codes)', () => {
+    test('usage error without two paths', () => {
+        const result = runTrimAlign(['only-one.png']);
+        expect(result.status).toBe(64);
+        expect(result.stderr).toContain('usage:');
+    });
+    test('unreadable input exits 65', () => {
+        const dir = scene();
+        const result = runTrimAlign([join(dir, 'missing.png'), join(dir, 'out.png')]);
+        expect(result.status).toBe(65);
+        expect(result.stderr).toContain('could not read image at');
+    });
+    test('a fully-transparent image has no content and exits 66', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(40, 40, []));
+        const result = runTrimAlign([input, join(dir, 'out.png')]);
+        expect(result.status).toBe(66);
+        expect(result.stderr).toContain('no content to trim');
+    });
+    test('an unwritable output path exits 68', () => {
+        const dir = scene();
+        const input = join(dir, 'in.png');
+        writeFileSync(input, craftPng(40, 40, [{ x: 0, y: 0, w: 10, h: 10, ...RED }]));
+        const result = runTrimAlign([input, join(dir, 'no-such-dir', 'out.png')]);
+        expect(result.status).toBe(68);
+        expect(result.stderr).toContain('could not write trimmed PNG');
+    });
+});
+//# sourceMappingURL=trim-align.test.js.map

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

@@ -44,7 +44,7 @@ export interface UiFidelityPreviewAndroidOptions {
     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.
+     * (and tests) can supply a specific java/gradle/ci/tar toolchain. Optional.
      */
     toolchainPath?: string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-preview-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAuBH,OAAO,KAAK,EAEV,uBAAuB,EACvB,uBAAuB,EAGxB,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;AAQD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAqErE;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,uBAAuB,CAuKzB"}
+{"version":3,"file":"ui-fidelity-preview-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-preview-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAwBH,OAAO,KAAK,EAEV,uBAAuB,EACvB,uBAAuB,EAGxB,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;AAQD;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAqErE;;;;;;GAMG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,uBAAuB,CA8KzB"}

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

@@ -25,6 +25,7 @@ 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';
 import { buildPreviewScreenResult } from './ui-fidelity-preview.js';
+import { resolveCliJsPath } from './render-post-processor.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
@@ -221,6 +222,14 @@ export function renderUiFidelityPreviewAndroid(options) {
         if (!process.env.ANDROID_SDK_ROOT)
             env.ANDROID_SDK_ROOT = androidSdk;
     }
+    // Hand the script this installation's CLI entrypoint so its trim stage can
+    // spawn `fidelity-trim` without a ci on PATH (library callers like the
+    // Invarn CLI). Never override an explicitly-set entrypoint.
+    if (!env.CIBUILD_CLI_JS) {
+        const cliJs = resolveCliJsPath();
+        if (cliJs !== null)
+            env.CIBUILD_CLI_JS = cliJs;
+    }
     const run = spawnSync('node', ['-e', script], {
         cwd: workDir,
         env,