@invarn/cibuild 2.0.9 → 2.1.1

package/dist/src/yaml/steps/fidelity-aspect-guard.js

@@ -0,0 +1,72 @@
+/**
+ * Fidelity aspect-ratio guard.
+ *
+ * One named composable per state is the authoring norm; the failure this
+ * catches is the opposite — several states stacked into one composable, which
+ * renders far taller (or wider) than the single-state reference it is paired
+ * against. That shows up as a sharp divergence between the rendered and
+ * reference aspect ratios, well before a human reads the diff.
+ *
+ * The guard is a pure comparison over the dimensions the render already
+ * reports (`rendered_px`, `reference_px`). It emits a WARNING when the
+ * divergence exceeds a documented fold factor — it never fails the render, and
+ * it stays silent when there is no reference to compare against.
+ */
+/**
+ * Fold factor beyond which a rendered/reference aspect-ratio divergence is
+ * worth a warning. A faithful single-state wrapper sits near 1.0; trim and
+ * reference alignment nudge it a few percent; a re-stacked 2-up wrapper roughly
+ * doubles one dimension and lands near 2.0. 1.5 catches the stack while
+ * tolerating the wobble.
+ */
+export const ASPECT_RATIO_WARN_FACTOR = 1.5;
+function isPositiveSize(size) {
+    return (Array.isArray(size) &&
+        size.length === 2 &&
+        Number.isFinite(size[0]) &&
+        Number.isFinite(size[1]) &&
+        size[0] > 0 &&
+        size[1] > 0);
+}
+/**
+ * Compares a rendered size against its reference size. Returns a
+ * non-warning, non-comparable result when either size is missing or
+ * non-positive — the guard only speaks when it has two real frames to compare.
+ */
+export function evaluateAspectRatio(renderedPx, referencePx, factor = ASPECT_RATIO_WARN_FACTOR) {
+    if (!isPositiveSize(renderedPx) || !isPositiveSize(referencePx)) {
+        return {
+            comparable: false,
+            renderedAspect: null,
+            referenceAspect: null,
+            divergence: null,
+            warn: false,
+        };
+    }
+    const renderedAspect = renderedPx[0] / renderedPx[1];
+    const referenceAspect = referencePx[0] / referencePx[1];
+    const divergence = Math.max(renderedAspect / referenceAspect, referenceAspect / renderedAspect);
+    return {
+        comparable: true,
+        renderedAspect,
+        referenceAspect,
+        divergence,
+        warn: divergence > factor,
+    };
+}
+/**
+ * Human/agent-readable warning line for a divergent screen, or null when the
+ * screen does not warrant one. The caller decides where to surface it (preview
+ * result, preflight output) — it is advisory, never a failure.
+ */
+export function formatAspectRatioWarning(screen, check) {
+    if (!check.warn || check.divergence === null)
+        return null;
+    const r = check.renderedAspect?.toFixed(2);
+    const ref = check.referenceAspect?.toFixed(2);
+    return (`Screen "${screen}" renders at aspect ratio ${r}:1 but its reference is ` +
+        `${ref}:1 (${check.divergence.toFixed(1)}× divergence). This often means ` +
+        `multiple states were stacked into one composable — author one named ` +
+        `composable per state instead.`);
+}
+//# sourceMappingURL=fidelity-aspect-guard.js.map

package/dist/src/yaml/steps/fidelity-aspect-guard.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Unit tests for the fidelity aspect-ratio guard.
+ *
+ * A wrapper that stacks several states into one composable renders far taller
+ * (or wider) than its single-state reference, so its aspect ratio diverges
+ * sharply from the reference's. The guard is the early warning for that
+ * re-stacking: it compares the rendered vs reference aspect ratios and flags a
+ * divergence beyond a documented fold factor — a WARNING, never a failure.
+ */
+export {};
+//# sourceMappingURL=fidelity-aspect-guard.test.d.ts.map

package/dist/src/yaml/steps/fidelity-aspect-guard.test.d.ts.map

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

package/dist/src/yaml/steps/fidelity-aspect-guard.test.js

@@ -0,0 +1,50 @@
+/**
+ * Unit tests for the fidelity aspect-ratio guard.
+ *
+ * A wrapper that stacks several states into one composable renders far taller
+ * (or wider) than its single-state reference, so its aspect ratio diverges
+ * sharply from the reference's. The guard is the early warning for that
+ * re-stacking: it compares the rendered vs reference aspect ratios and flags a
+ * divergence beyond a documented fold factor — a WARNING, never a failure.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { evaluateAspectRatio, ASPECT_RATIO_WARN_FACTOR, } from './fidelity-aspect-guard.js';
+describe('evaluateAspectRatio', () => {
+    test('does not warn when rendered and reference aspect ratios match', () => {
+        // A faithful single-state banner: same proportions as its reference.
+        const check = evaluateAspectRatio([720, 1280], [360, 640]);
+        expect(check.comparable).toBe(true);
+        expect(check.warn).toBe(false);
+        expect(check.divergence).toBeCloseTo(1, 5);
+    });
+    test('warns when a stacked render is far off the reference aspect ratio', () => {
+        // The canonical miss: two banner states stacked in one Column render at
+        // ~2.2:1, judged against a single-state ~4.76:1 reference.
+        const rendered = [880, 400]; // 2.2:1
+        const reference = [952, 200]; // 4.76:1
+        const check = evaluateAspectRatio(rendered, reference);
+        expect(check.comparable).toBe(true);
+        expect(check.warn).toBe(true);
+        expect(check.divergence).toBeCloseTo(4.76 / 2.2, 1);
+    });
+    test('tolerates a small alignment/trim wobble within the fold factor', () => {
+        // Trim + reference alignment can nudge dimensions a few percent; that must
+        // not trip the warning.
+        const check = evaluateAspectRatio([726, 1280], [360, 640]);
+        expect(check.warn).toBe(false);
+    });
+    test('is not comparable when there is no reference', () => {
+        const check = evaluateAspectRatio([720, 1280], null);
+        expect(check.comparable).toBe(false);
+        expect(check.warn).toBe(false);
+    });
+    test('is not comparable when a dimension is zero or negative', () => {
+        expect(evaluateAspectRatio([720, 0], [360, 640]).comparable).toBe(false);
+        expect(evaluateAspectRatio([720, 1280], [0, 640]).comparable).toBe(false);
+    });
+    test('exposes a sane default fold factor', () => {
+        expect(ASPECT_RATIO_WARN_FACTOR).toBeGreaterThan(1);
+        expect(ASPECT_RATIO_WARN_FACTOR).toBeLessThan(2);
+    });
+});
+//# sourceMappingURL=fidelity-aspect-guard.test.js.map

package/dist/src/yaml/steps/fidelity-reference-provenance.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG the gate cannot read, so reference validity
+ * is asserted at export time as provenance metadata (`figmaNode`, `locale`,
+ * `resolved`, `exportedAt`) and the gate checks that METADATA — never the
+ * pixels, never via OCR. A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in a locale other than the
+ * render's is UNVERIFIABLE: a hard, mechanical verdict that fails loud instead
+ * of producing a confident-but-false PASS, and that kills the ad-hoc-Figma-fetch
+ * root cause (an ad-hoc fetch has no provenance, so it is Unverifiable).
+ *
+ * Content differences (copy wording, geometry) are deliberately NOT evaluated
+ * here — those are soft, judged findings that legitimately drift between
+ * reference-export and gate-run.
+ *
+ * This module is the authoritative spec for the check. The Android render
+ * runtime inlines an equivalent JS implementation (it ships as a self-contained
+ * script string and cannot import this module); the render-step integration
+ * tests exercise that inlined copy end-to-end against the same fixtures, so the
+ * two cannot silently drift.
+ */
+/** Export-time provenance as it travels in the run-input sidecar. */
+export interface ReferenceProvenanceMeta {
+    figmaNode?: string;
+    locale?: string;
+    resolved?: boolean;
+    exportedAt?: string;
+}
+/** A reason a reference cannot be honestly judged. */
+export interface ProvenanceFault {
+    /** Stable machine code (NO_PROVENANCE / UNRESOLVED_REFERENCE / …). */
+    code: string;
+    /** Human/agent-readable reason, naming the screen. */
+    message: string;
+}
+/** The per-state status string written to protocol-result.json. */
+export declare const UNVERIFIABLE_STATUS = "unverifiable";
+/**
+ * Returns the reason a reference is UNVERIFIABLE, or null when it is verifiable.
+ * Checks metadata then existence; order is irrelevant for single-fault inputs
+ * but deterministic when several faults coincide.
+ */
+export declare function provenanceFault(screen: string, provenance: ReferenceProvenanceMeta | null | undefined, renderLocale: string, referenceExists: boolean): ProvenanceFault | null;
+//# sourceMappingURL=fidelity-reference-provenance.d.ts.map

package/dist/src/yaml/steps/fidelity-reference-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-reference-provenance.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-reference-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAgBlD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,EACtD,YAAY,EAAE,MAAM,EACpB,eAAe,EAAE,OAAO,GACvB,eAAe,GAAG,IAAI,CAgCxB"}

package/dist/src/yaml/steps/fidelity-reference-provenance.js

@@ -0,0 +1,69 @@
+/**
+ * Reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG the gate cannot read, so reference validity
+ * is asserted at export time as provenance metadata (`figmaNode`, `locale`,
+ * `resolved`, `exportedAt`) and the gate checks that METADATA — never the
+ * pixels, never via OCR. A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in a locale other than the
+ * render's is UNVERIFIABLE: a hard, mechanical verdict that fails loud instead
+ * of producing a confident-but-false PASS, and that kills the ad-hoc-Figma-fetch
+ * root cause (an ad-hoc fetch has no provenance, so it is Unverifiable).
+ *
+ * Content differences (copy wording, geometry) are deliberately NOT evaluated
+ * here — those are soft, judged findings that legitimately drift between
+ * reference-export and gate-run.
+ *
+ * This module is the authoritative spec for the check. The Android render
+ * runtime inlines an equivalent JS implementation (it ships as a self-contained
+ * script string and cannot import this module); the render-step integration
+ * tests exercise that inlined copy end-to-end against the same fixtures, so the
+ * two cannot silently drift.
+ */
+/** The per-state status string written to protocol-result.json. */
+export const UNVERIFIABLE_STATUS = 'unverifiable';
+function hasProvenance(p) {
+    // Provenance is only "present" when the fields the gate reasons over are
+    // there. A partial object (e.g. a hand-dropped `{ figmaNode }`) is treated as
+    // no provenance — verifiable is earned only through the full export path.
+    return (p != null &&
+        typeof p === 'object' &&
+        typeof p.locale === 'string' &&
+        typeof p.resolved === 'boolean');
+}
+/**
+ * Returns the reason a reference is UNVERIFIABLE, or null when it is verifiable.
+ * Checks metadata then existence; order is irrelevant for single-fault inputs
+ * but deterministic when several faults coincide.
+ */
+export function provenanceFault(screen, provenance, renderLocale, referenceExists) {
+    if (!hasProvenance(provenance)) {
+        return {
+            code: 'NO_PROVENANCE',
+            message: `reference for ${screen} has no export provenance; a reference is ` +
+                `verifiable only when exported through the deterministic path`,
+        };
+    }
+    if (provenance.resolved === false) {
+        return {
+            code: 'UNRESOLVED_REFERENCE',
+            message: `reference for ${screen} still has unresolved copy placeholders ` +
+                `(resolved=false) — export it with the copy filled in`,
+        };
+    }
+    if (provenance.locale !== renderLocale) {
+        return {
+            code: 'LOCALE_MISMATCH',
+            message: `reference for ${screen} is locale "${provenance.locale}" but the ` +
+                `render locale is "${renderLocale}"`,
+        };
+    }
+    if (!referenceExists) {
+        return {
+            code: 'REFERENCE_ABSENT',
+            message: `reference image for ${screen} is absent`,
+        };
+    }
+    return null;
+}
+//# sourceMappingURL=fidelity-reference-provenance.js.map

package/dist/src/yaml/steps/fidelity-reference-provenance.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Unit tests for the reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG; the gate cannot read its text. So validity
+ * is asserted at export time as provenance metadata, and the gate checks the
+ * METADATA, never the pixels (no OCR). A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in the wrong locale is
+ * UNVERIFIABLE — a loud, mechanical verdict, not a confident-but-false PASS.
+ *
+ * Content differences (copy wording, geometry) are NOT checked here — those are
+ * soft, judged findings that legitimately drift between export and run.
+ */
+export {};
+//# sourceMappingURL=fidelity-reference-provenance.test.d.ts.map

package/dist/src/yaml/steps/fidelity-reference-provenance.test.d.ts.map

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

package/dist/src/yaml/steps/fidelity-reference-provenance.test.js

@@ -0,0 +1,54 @@
+/**
+ * Unit tests for the reference-provenance gate.
+ *
+ * A UI-fidelity reference is a PNG; the gate cannot read its text. So validity
+ * is asserted at export time as provenance metadata, and the gate checks the
+ * METADATA, never the pixels (no OCR). A reference that is absent, unprovenanced,
+ * placeholder-bearing (`resolved == false`), or in the wrong locale is
+ * UNVERIFIABLE — a loud, mechanical verdict, not a confident-but-false PASS.
+ *
+ * Content differences (copy wording, geometry) are NOT checked here — those are
+ * soft, judged findings that legitimately drift between export and run.
+ */
+import { describe, test, expect } from '@jest/globals';
+import { provenanceFault, UNVERIFIABLE_STATUS, } from './fidelity-reference-provenance.js';
+const GOOD = {
+    figmaNode: '12:345',
+    locale: 'en',
+    resolved: true,
+    exportedAt: '2026-06-18T10:00:00Z',
+};
+describe('provenanceFault', () => {
+    test('a present, provenanced, resolved, locale-matching reference is verifiable', () => {
+        expect(provenanceFault('Guest', GOOD, 'en', true)).toBeNull();
+    });
+    test('an absent reference is UNVERIFIABLE (REFERENCE_ABSENT)', () => {
+        const fault = provenanceFault('Guest', GOOD, 'en', false);
+        expect(fault?.code).toBe('REFERENCE_ABSENT');
+    });
+    test('a reference with no provenance is UNVERIFIABLE (NO_PROVENANCE)', () => {
+        expect(provenanceFault('Guest', null, 'en', true)?.code).toBe('NO_PROVENANCE');
+        expect(provenanceFault('Guest', undefined, 'en', true)?.code).toBe('NO_PROVENANCE');
+    });
+    test('incomplete provenance (missing locale/resolved) is UNVERIFIABLE (NO_PROVENANCE)', () => {
+        expect(provenanceFault('Guest', { figmaNode: 'x', exportedAt: 'y' }, 'en', true)?.code).toBe('NO_PROVENANCE');
+    });
+    test('a placeholder reference (resolved=false) is UNVERIFIABLE (UNRESOLVED_REFERENCE)', () => {
+        const fault = provenanceFault('Guest', { ...GOOD, resolved: false }, 'en', true);
+        expect(fault?.code).toBe('UNRESOLVED_REFERENCE');
+    });
+    test('a wrong-locale reference is UNVERIFIABLE (LOCALE_MISMATCH)', () => {
+        // Italian reference vs an English render.
+        const fault = provenanceFault('Guest', { ...GOOD, locale: 'it' }, 'en', true);
+        expect(fault?.code).toBe('LOCALE_MISMATCH');
+    });
+    test('every fault carries the screen name and a human reason', () => {
+        const fault = provenanceFault('LoggedIn', { ...GOOD, resolved: false }, 'en', true);
+        expect(fault?.message).toContain('LoggedIn');
+        expect(fault?.message.length).toBeGreaterThan(10);
+    });
+    test('exposes the unverifiable status string the result document uses', () => {
+        expect(UNVERIFIABLE_STATUS).toBe('unverifiable');
+    });
+});
+//# sourceMappingURL=fidelity-reference-provenance.test.js.map

package/dist/src/yaml/steps/render-post-processor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render-post-processor.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/render-post-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAiJpB,CAAC;AAEpB,eAAO,MAAM,wBAAwB,EAAE,MAsFtC,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,sBAAsB,CAMlE"}
+{"version":3,"file":"render-post-processor.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/render-post-processor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,EAAE,MA8JpB,CAAC;AAEpB,eAAO,MAAM,wBAAwB,EAAE,MAsFtC,CAAC;AAEF,iFAAiF;AACjF,MAAM,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACjC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,sBAAsB,CAMlE"}

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

@@ -61,14 +61,25 @@ export const TRIM_HELPER_SWIFT_SOURCE = [
     '    return CGImageDestinationFinalize(dest)',
     '}',
     '',
-    '// Redraw an image at an exact pixel size (used to match the reference).',
-    'func resize(_ image: CGImage, toWidth w: Int, height h: Int) -> CGImage? {',
+    '// Draw `image` centered on a transparent reference-sized canvas, scaled to fit',
+    '// while PRESERVING its aspect ratio. Unlike `resize` (which stretches to exact',
+    '// dimensions and 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.',
+    'func fitPad(_ image: CGImage, toWidth w: Int, height h: Int) -> CGImage? {',
     '    if w <= 0 || h <= 0 { return nil }',
     '    let bytesPerRow = w * 4',
     '    let space = CGColorSpaceCreateDeviceRGB()',
     '    guard let ctx = CGContext(data: nil, width: w, height: h, bitsPerComponent: 8, bytesPerRow: bytesPerRow, space: space, bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue) else { return nil }',
+    '    ctx.clear(CGRect(x: 0, y: 0, width: w, height: h))',
     '    ctx.interpolationQuality = .high',
-    '    ctx.draw(image, in: CGRect(x: 0, y: 0, width: w, height: h))',
+    '    let scale = min(Double(w) / Double(image.width), Double(h) / Double(image.height))',
+    '    let drawW = Double(image.width) * scale',
+    '    let drawH = Double(image.height) * scale',
+    '    let originX = (Double(w) - drawW) / 2.0',
+    '    let originY = (Double(h) - drawH) / 2.0',
+    '    ctx.draw(image, in: CGRect(x: originX, y: originY, width: drawW, height: drawH))',
     '    return ctx.makeImage()',
     '}',
     '',
@@ -169,8 +180,10 @@ export const TRIM_HELPER_SWIFT_SOURCE = [
     '    exit(68)',
     '}',
     '',
-    '// Optional aligned output: the trimmed image resized to the reference pixel',
-    '// size, a 1:1 overlay pair. Best-effort; dimensions are reported either way.',
+    '// 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.',
     'var referenceWidth = 0',
     'var referenceHeight = 0',
     'if arguments.count >= 5 {',
@@ -179,7 +192,7 @@ export const TRIM_HELPER_SWIFT_SOURCE = [
     '    if let reference = loadCGImage(referencePath) {',
     '        referenceWidth = reference.width',
     '        referenceHeight = reference.height',
-    '        if let aligned = resize(cropped, toWidth: referenceWidth, height: referenceHeight) {',
+    '        if let aligned = fitPad(cropped, toWidth: referenceWidth, height: referenceHeight) {',
     '            _ = writePNG(aligned, to: alignedPath)',
     '        }',
     '    }',

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

@@ -116,13 +116,39 @@ describe('trim helper pixel logic (real toolchain)', () => {
     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' });
@@ -178,8 +204,8 @@ describe('trim helper pixel logic (real toolchain)', () => {
         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 resized to the
-        // reference pixel size for a 1:1 overlay.
+        // 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
@@ -190,5 +216,23 @@ describe('trim helper pixel logic (real toolchain)', () => {
             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.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;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"}
+{"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"}

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

@@ -20,10 +20,11 @@
  */
 import { spawnSync } from 'node:child_process';
 import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, statSync, writeFileSync, } from 'node:fs';
-import { tmpdir } from 'node:os';
+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';
+import { buildPreviewScreenResult } from './ui-fidelity-preview.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
@@ -51,19 +52,44 @@ function commandExists(command, pathPrepend) {
         : 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 (`ANDROID_HOME`/`ANDROID_SDK_ROOT`). Gradle itself ships inside the
+ * 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(pathPrepend) {
+function missingToolchain(sdk, 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)');
+    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. */
@@ -122,7 +148,8 @@ export function renderUiFidelityPreviewAndroid(options) {
     // 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);
+    const androidSdk = resolveAndroidSdk();
+    const missing = missingToolchain(androidSdk, options.toolchainPath);
     if (missing.length > 0) {
         return {
             packageSource: 'inputs',
@@ -187,6 +214,13 @@ export function renderUiFidelityPreviewAndroid(options) {
     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,
@@ -200,15 +234,7 @@ export function renderUiFidelityPreviewAndroid(options) {
             (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 screens = (raw.screens || []).map((s) => buildPreviewScreenResult(s, artifactsDir));
     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 };