@invarn/cibuild 2.1.1 → 2.1.2

package/dist/src/yaml/steps/structural-facts.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Structural-facts deriver — Signal A of the UI-fidelity structural pass.
+ *
+ * Pure and platform-agnostic: it takes a per-node layout dump (bounds in px,
+ * parent, clip flag) emitted alongside the render and derives intent-agnostic
+ * geometric facts the fidelity judge should check instead of discovering them
+ * by eye:
+ *
+ *   - `overflow`          — a node extends past its parent's box (parent does
+ *                           NOT clip, so the excess is visibly sticking out).
+ *   - `clipped_by_parent` — a node extends past a CLIPPING parent's box, so the
+ *                           excess is cut away (the motivating euro-coin case).
+ *   - `off_screen`        — a node extends past the root canvas.
+ *   - `overlap`           — two siblings overlap by a significant area.
+ *
+ * The deriver does NOT judge or score; it reports facts. The verdict stays the
+ * agent's. This is the brain of Signal A; the render-side emission + facts
+ * artifact wiring live in the render step (a separate slice).
+ */
+export interface LayoutBounds {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+export interface LayoutNode {
+    /** Stable id/label for the node within one dump. */
+    id: string;
+    /** Root-space bounds in px. */
+    bounds: LayoutBounds;
+    /** Parent node id, or null for a root node. */
+    parentId: string | null;
+    /** Whether this node clips its children to its bounds. */
+    clipsChildren: boolean;
+}
+export interface LayoutDump {
+    /** The captured canvas / root bounds in px. */
+    canvas: LayoutBounds;
+    nodes: LayoutNode[];
+}
+export type Edge = 'left' | 'top' | 'right' | 'bottom';
+export type StructuralFact = {
+    kind: 'overflow';
+    nodeId: string;
+    parentId: string;
+    edges: Edge[];
+    overflowPx: Partial<Record<Edge, number>>;
+} | {
+    kind: 'clipped_by_parent';
+    nodeId: string;
+    clipperId: string;
+    edges: Edge[];
+    clippedPx: Partial<Record<Edge, number>>;
+} | {
+    kind: 'off_screen';
+    nodeId: string;
+    edges: Edge[];
+    offscreenPx: Partial<Record<Edge, number>>;
+} | {
+    kind: 'overlap';
+    nodeIds: [string, string];
+    overlapPx: {
+        width: number;
+        height: number;
+    };
+    ratio: number;
+};
+export interface DeriveStructuralFactsOptions {
+    /** Edge excesses / overlaps at or below this many px are ignored, so that
+     *  exact-touching layout edges don't read as overflow or overlap. */
+    tolerancePx?: number;
+    /** Minimum (intersection area / smaller node area) for an overlap to be
+     *  reported as significant. */
+    overlapMinRatio?: number;
+}
+export declare function deriveStructuralFacts(dump: LayoutDump, options?: DeriveStructuralFactsOptions): StructuralFact[];
+/**
+ * Render-side embedded form of the deriver.
+ *
+ * The Android render runs as a single self-contained generated script (see
+ * `generateAndroidRenderScript`), so render-side pure logic is embedded as a
+ * JS-source string and concatenated in — exactly like `RENDER_SCRIPT_TRIM_STAGE`.
+ * The typed `deriveStructuralFacts` above stays the canonical, tested spec; the
+ * `parity` test asserts this embedded port produces identical facts on shared
+ * fixtures so the two cannot drift.
+ *
+ * `deriveStructuralFacts` here is pure; `deriveAndWriteFacts` references runtime
+ * globals (`fs`, `path`, `artifactsDir`, `log`) defined in the main script and
+ * is only invoked from there — harmless to define in the eval sandbox.
+ */
+export declare const RENDER_SCRIPT_FACTS_STAGE: string;
+/**
+ * Evaluates the embedded facts stage and returns its pure `deriveStructuralFacts`,
+ * so the parity test exercises exactly the code that ships in the runtime script
+ * (mirrors `getPostProcessorInternals`). `deriveAndWriteFacts` references runtime
+ * globals only when called, so defining it in the sandbox is harmless.
+ */
+export declare function getStructuralFactsStageInternals(): {
+    deriveStructuralFacts: (dump: LayoutDump, options?: DeriveStructuralFactsOptions) => StructuralFact[];
+};
+//# sourceMappingURL=structural-facts.d.ts.map

package/dist/src/yaml/steps/structural-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural-facts.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/structural-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,MAAM,EAAE,YAAY,CAAC;IACrB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,0DAA0D;IAC1D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,UAAU,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEvD,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC3C,GACD;IACE,IAAI,EAAE,mBAAmB,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC1C,GACD;IACE,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,IAAI,EAAE,CAAC;IACd,WAAW,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;CAC5C,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1B,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,4BAA4B;IAC3C;yEACqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;mCAC+B;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoCD,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,UAAU,EAChB,OAAO,GAAE,4BAAiC,GACzC,cAAc,EAAE,CA2ElB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAuHvC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gCAAgC,IAAI;IAClD,qBAAqB,EAAE,CACrB,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,4BAA4B,KACnC,cAAc,EAAE,CAAC;CACvB,CAWA"}

package/dist/src/yaml/steps/structural-facts.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure unit tests for the structural-facts deriver (UI-fidelity structural
+ * pass, Signal A). Fixture-driven, no toolchain — the deriver turns a
+ * per-node layout dump into intent-agnostic geometric facts the fidelity
+ * judge checks instead of eyeballing.
+ *
+ * The canonical regression fixture is the motivating miss: a card clips an
+ * overflowing voucher tag; the deriver must surface the bottom clip as a
+ * fact so it is never again skipped by eye.
+ */
+export {};
+//# sourceMappingURL=structural-facts.test.d.ts.map

package/dist/src/yaml/steps/structural-facts.test.d.ts.map

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

package/dist/src/yaml/steps/structural-facts.test.js

@@ -0,0 +1,174 @@
+/**
+ * Pure unit tests for the structural-facts deriver (UI-fidelity structural
+ * pass, Signal A). Fixture-driven, no toolchain — the deriver turns a
+ * per-node layout dump into intent-agnostic geometric facts the fidelity
+ * judge checks instead of eyeballing.
+ *
+ * The canonical regression fixture is the motivating miss: a card clips an
+ * overflowing voucher tag; the deriver must surface the bottom clip as a
+ * fact so it is never again skipped by eye.
+ */
+import { deriveStructuralFacts, getStructuralFactsStageInternals, } from './structural-facts.js';
+// 200x400 canvas in px for all fixtures unless noted.
+const CANVAS = { left: 0, top: 0, right: 200, bottom: 400 };
+describe('deriveStructuralFacts — containment', () => {
+    test('a fully-contained child produces no clip/overflow fact', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'card', bounds: { left: 20, top: 20, right: 180, bottom: 200 }, parentId: null, clipsChildren: true },
+                { id: 'label', bounds: { left: 30, top: 30, right: 170, bottom: 60 }, parentId: 'card', clipsChildren: false },
+            ],
+        };
+        expect(deriveStructuralFacts(dump)).toEqual([]);
+    });
+});
+describe('deriveStructuralFacts — overflow vs clip', () => {
+    test('child overflowing a NON-clipping parent is reported as overflow, not clipped', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'row', bounds: { left: 20, top: 20, right: 180, bottom: 100 }, parentId: null, clipsChildren: false },
+                // sticks out 15px past the row's right edge
+                { id: 'chip', bounds: { left: 150, top: 30, right: 195, bottom: 80 }, parentId: 'row', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        expect(facts).toHaveLength(1);
+        expect(facts[0]).toMatchObject({
+            kind: 'overflow',
+            nodeId: 'chip',
+            parentId: 'row',
+            edges: ['right'],
+            overflowPx: { right: 15 },
+        });
+    });
+    test('child overflowing a CLIPPING parent is reported as clipped-by-parent with the clipped extent', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'card', bounds: { left: 20, top: 20, right: 180, bottom: 200 }, parentId: null, clipsChildren: true },
+                // overflows the card's bottom by 24px → that extent is clipped away
+                { id: 'tag', bounds: { left: 60, top: 150, right: 140, bottom: 224 }, parentId: 'card', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        expect(facts).toHaveLength(1);
+        expect(facts[0]).toMatchObject({
+            kind: 'clipped_by_parent',
+            nodeId: 'tag',
+            clipperId: 'card',
+            edges: ['bottom'],
+            clippedPx: { bottom: 24 },
+        });
+    });
+});
+describe('deriveStructuralFacts — off-screen', () => {
+    test('a node extending past the canvas is reported off-screen on those edges', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                // bottom edge 30px below the canvas
+                { id: 'sheet', bounds: { left: 0, top: 360, right: 200, bottom: 430 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        const offscreen = facts.filter((f) => f.kind === 'off_screen');
+        expect(offscreen).toHaveLength(1);
+        expect(offscreen[0]).toMatchObject({
+            kind: 'off_screen',
+            nodeId: 'sheet',
+            edges: ['bottom'],
+            offscreenPx: { bottom: 30 },
+        });
+    });
+});
+describe('deriveStructuralFacts — overlap', () => {
+    test('two significantly overlapping siblings are reported as an overlap', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'a', bounds: { left: 20, top: 20, right: 120, bottom: 120 }, parentId: 'root', clipsChildren: false },
+                { id: 'b', bounds: { left: 80, top: 60, right: 180, bottom: 160 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        const overlap = deriveStructuralFacts(dump).filter((f) => f.kind === 'overlap');
+        expect(overlap).toHaveLength(1);
+        expect(overlap[0]).toMatchObject({ kind: 'overlap', nodeIds: ['a', 'b'] });
+    });
+    test('barely-touching siblings within tolerance are not an overlap', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'a', bounds: { left: 20, top: 20, right: 100, bottom: 100 }, parentId: 'root', clipsChildren: false },
+                { id: 'b', bounds: { left: 100, top: 20, right: 180, bottom: 100 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        expect(deriveStructuralFacts(dump).filter((f) => f.kind === 'overlap')).toEqual([]);
+    });
+});
+describe('embedded render-side stage parity', () => {
+    // The render script ships a JS-source port of the deriver. It must produce
+    // byte-identical facts to the canonical typed module, or render-side facts
+    // would silently diverge from what the tests guarantee.
+    const { deriveStructuralFacts: embedded } = getStructuralFactsStageInternals();
+    const fixtures = {
+        clip: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'card', bounds: { left: 20, top: 20, right: 180, bottom: 200 }, parentId: null, clipsChildren: true },
+                { id: 'tag', bounds: { left: 60, top: 150, right: 140, bottom: 224 }, parentId: 'card', clipsChildren: false },
+            ],
+        },
+        overflow: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'row', bounds: { left: 20, top: 20, right: 180, bottom: 100 }, parentId: null, clipsChildren: false },
+                { id: 'chip', bounds: { left: 150, top: 30, right: 195, bottom: 80 }, parentId: 'row', clipsChildren: false },
+            ],
+        },
+        overlap: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'a', bounds: { left: 20, top: 20, right: 120, bottom: 120 }, parentId: 'root', clipsChildren: false },
+                { id: 'b', bounds: { left: 80, top: 60, right: 180, bottom: 160 }, parentId: 'root', clipsChildren: false },
+            ],
+        },
+    };
+    for (const [name, dump] of Object.entries(fixtures)) {
+        test(`embedded port matches the module for the ${name} fixture`, () => {
+            expect(embedded(dump)).toEqual(deriveStructuralFacts(dump));
+        });
+    }
+});
+describe('deriveStructuralFacts — motivating regression (voucher tag bottom-clip)', () => {
+    // The render-side layout dump for the HubPromoBanner-style case: a card
+    // clips children, and the voucher tag (with its euro coin) overflows the
+    // card's bottom. The deriver MUST surface the bottom clip so the verdict
+    // can compare its extent to the design and never miss it by eye again.
+    test('reports the voucher tag as clipped by the card at the bottom, with the clipped px', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 360, bottom: 720 },
+            nodes: [
+                { id: 'HubPromoBanner', bounds: { left: 16, top: 100, right: 344, bottom: 262 }, parentId: null, clipsChildren: true },
+                { id: 'promoText', bounds: { left: 32, top: 116, right: 240, bottom: 180 }, parentId: 'HubPromoBanner', clipsChildren: false },
+                // voucher tag overflows the card bottom (262) down to 280 → 18px clipped
+                { id: 'voucherTag', bounds: { left: 250, top: 210, right: 330, bottom: 280 }, parentId: 'HubPromoBanner', clipsChildren: false },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        const clip = facts.find((f) => f.kind === 'clipped_by_parent' && f.nodeId === 'voucherTag');
+        expect(clip).toMatchObject({
+            kind: 'clipped_by_parent',
+            nodeId: 'voucherTag',
+            clipperId: 'HubPromoBanner',
+            edges: ['bottom'],
+            clippedPx: { bottom: 18 },
+        });
+    });
+});
+//# sourceMappingURL=structural-facts.test.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;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;AAmsBD;;;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"}
+{"version":3,"file":"ui-fidelity-render-android.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/ui-fidelity-render-android.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;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;AAKpE,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;AA4uBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAWrF;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"}

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

@@ -50,6 +50,7 @@
 import { BaseStepExecutor } from './base.js';
 import { parseScale, DEFAULT_SCALE } from './ui-fidelity-render.js';
 import { RENDER_SCRIPT_TRIM_STAGE } from './render-post-processor.js';
+import { RENDER_SCRIPT_FACTS_STAGE } from './structural-facts.js';
 /**
  * Default Roborazzi record task. Run from the project root so Gradle resolves
  * it in whichever subproject declares it.
@@ -461,6 +462,21 @@ function roborazziPngMatches(basename, screen) {
   return method === screen || method === 'render' + screen;
 }
 
+// The structural-pass layout dump (Signal A) is emitted next to the PNG in a
+// roborazzi output dir, but Roborazzi controls the PNG's golden filename and
+// ignores explicit capture names, so the dump can't reliably share the PNG's
+// stem. Match it the same collision-safe way as the PNG instead — by the final
+// dot-delimited segment of "<...>.layout.json" — so the emitter can write a
+// simple "<Screen>.layout.json" regardless of the PNG's golden name.
+function roborazziLayoutMatches(basename, screen) {
+  var suffix = '.layout.json';
+  if (basename.slice(-suffix.length) !== suffix) return false;
+  var stem = basename.slice(0, -suffix.length);
+  var lastDot = stem.lastIndexOf('.');
+  var seg = lastDot === -1 ? stem : stem.slice(lastDot + 1);
+  return seg === screen || seg === 'render' + screen;
+}
+
 // Roborazzi writes PNGs to <module>/build/outputs/roborazzi/. Collect every
 // such directory in the project so a screen's PNG can be located regardless of
 // which module rendered it.
@@ -561,6 +577,28 @@ function renderScreens(renderable, projectRoot) {
       entry.error = null;
       log('rendered ' + entry.screen + ' -> ' + relative);
       trimRenderedImage(entry, outputPath, workDir);
+      // Signal A: the render emits a per-node layout dump into a roborazzi
+      // output dir (named "<Screen>.layout.json" or "...render<Screen>.layout.json").
+      // Locate it the same way as the PNG and derive structural facts; absent or
+      // malformed is a clean no-op.
+      var layoutSource = null;
+      for (var li = 0; li < roborazziDirs.length && layoutSource === null; li++) {
+        var lnames;
+        try {
+          lnames = fs.readdirSync(roborazziDirs[li]);
+        } catch (lReadError) {
+          lnames = [];
+        }
+        for (var lj = 0; lj < lnames.length; lj++) {
+          if (roborazziLayoutMatches(lnames[lj], entry.screen)) {
+            layoutSource = path.join(roborazziDirs[li], lnames[lj]);
+            break;
+          }
+        }
+      }
+      if (layoutSource !== null) {
+        deriveAndWriteFacts(entry, layoutSource);
+      }
     });
   } finally {
     if (process.env.UI_FIDELITY_KEEP_HARNESS) {
@@ -628,6 +666,8 @@ function main() {
       rendered_image_path: null,
       aligned_image_path: null,
       dimensions: null,
+      layout_path: null,
+      facts_path: null,
     };
   });
   log('screens: ' + (screens.join(', ') || '(none)'));
@@ -635,6 +675,8 @@ function main() {
   fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'rendered'), { recursive: true });
   fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'references'), { recursive: true });
   fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'aligned'), { recursive: true });
+  fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'layout'), { recursive: true });
+  fs.mkdirSync(path.join(artifactsDir, 'ui-fidelity', 'facts'), { recursive: true });
 
   // 2. Per-screen validation + reference copies. Each screen gets its OWN copy
   //    named by screen, even when two screens share a reference basename.
@@ -783,6 +825,7 @@ export function generateAndroidRenderScript(config) {
         'var RENDERER = ' + JSON.stringify(ANDROID_RENDERER) + ';',
         'var PACKAGE_ARCHIVE_NAME = ' + JSON.stringify(PACKAGE_ARCHIVE_BASENAME) + ';',
         RENDER_SCRIPT_TRIM_STAGE,
+        RENDER_SCRIPT_FACTS_STAGE,
         ANDROID_RENDER_SCRIPT_MAIN,
     ].join('\n');
 }

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

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { chmodSync, cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import { gzipSync } from 'node:zlib';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -39,6 +39,16 @@ const FAKE_GRADLEW_LINES = [
     '  [ -z "$s" ] && continue',
     "  printf '\\x89PNG\\r\\n\\x1a\\n' > \"$out/$s.png\"",
     '  printf \'roborazzi:%s\' "$s" >> "$out/$s.png"',
+    // When FAKE_ROBORAZZI_LAYOUT is set, also emit the layout-dump sidecar next
+    // to the PNG (matching basename, .layout.json) — a clipping card with an
+    // overflowing tag, so the deriver yields one clipped-by-parent fact.
+    '  if [ -n "$FAKE_ROBORAZZI_LAYOUT" ]; then',
+    // Layout sidecar basename: flat "<screen>.layout.json" by default, or an
+    // explicit golden-style dotted name via FAKE_ROBORAZZI_LAYOUT_NAME to prove
+    // the consumer finds it by dot-segment match, decoupled from the PNG stem.
+    '    lname="${FAKE_ROBORAZZI_LAYOUT_NAME:-$s.layout.json}"',
+    `    printf '%s' '{"canvas":{"left":0,"top":0,"right":200,"bottom":400},"nodes":[{"id":"card","bounds":{"left":20,"top":20,"right":180,"bottom":200},"parentId":null,"clipsChildren":true},{"id":"tag","bounds":{"left":60,"top":150,"right":140,"bottom":224},"parentId":"card","clipsChildren":false}]}' > "$out/$lname"`,
+    '  fi',
     'done',
     'exit 0',
 ];
@@ -275,6 +285,67 @@ describe('android render runtime — render + trim (happy path)', () => {
         // The rendered file holds the trim helper's output, not the raw render.
         expect(readFileSync(artifact(project, 'ui-fidelity/rendered/XProof.png'), 'utf-8')).toContain('trimmed:XProof.png');
     });
+    test('derives structural facts from the layout dump and records layout_path + facts_path', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        stageArchive(project, gradleProjectEntries());
+        const run = runScript(project, await buildScript(), {
+            FAKE_ROBORAZZI_SCREENS: 'XProof',
+            FAKE_ROBORAZZI_LAYOUT: '1',
+        });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.layout_path).toBe('ui-fidelity/layout/XProof.json');
+        expect(screen?.facts_path).toBe('ui-fidelity/facts/XProof.json');
+        // The layout dump is copied verbatim as a build artifact.
+        expect(existsSync(artifact(project, 'ui-fidelity/layout/XProof.json'))).toBe(true);
+        // The facts artifact surfaces the bottom clip the eye would miss.
+        const facts = JSON.parse(readFileSync(artifact(project, 'ui-fidelity/facts/XProof.json'), 'utf-8'));
+        expect(facts).toEqual({
+            screen: 'XProof',
+            facts: [
+                {
+                    kind: 'clipped_by_parent',
+                    nodeId: 'tag',
+                    clipperId: 'card',
+                    edges: ['bottom'],
+                    clippedPx: { bottom: 24 },
+                },
+            ],
+        });
+    });
+    test('finds the layout dump by dot-segment match even when its name differs from the PNG stem', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        stageArchive(project, gradleProjectEntries());
+        // Golden-style dotted layout name (as real Roborazzi would name a sidecar),
+        // distinct from the flat PNG the fake writes — the consumer must still find it.
+        const run = runScript(project, await buildScript(), {
+            FAKE_ROBORAZZI_SCREENS: 'XProof',
+            FAKE_ROBORAZZI_LAYOUT: '1',
+            FAKE_ROBORAZZI_LAYOUT_NAME: 'com.example.XProofTest.renderXProof.layout.json',
+        });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.facts_path).toBe('ui-fidelity/facts/XProof.json');
+        const facts = JSON.parse(readFileSync(artifact(project, 'ui-fidelity/facts/XProof.json'), 'utf-8'));
+        expect(facts.facts).toHaveLength(1);
+        expect(facts.facts[0].kind).toBe('clipped_by_parent');
+    });
+    test('degrades cleanly when no layout dump is emitted (no facts, render still succeeds)', async () => {
+        const project = makeProject({ screens: { XProof: 'x.png' } });
+        writeReference(project, 'x.png');
+        stageArchive(project, gradleProjectEntries());
+        // No FAKE_ROBORAZZI_LAYOUT → the render emits a PNG but no sidecar.
+        const run = runScript(project, await buildScript(), { FAKE_ROBORAZZI_SCREENS: 'XProof' });
+        expect(run.status).toBe(0);
+        const screen = readResult(project).screens.find((s) => s.screen === 'XProof');
+        expect(screen?.status).toBe('rendered');
+        expect(screen?.layout_path ?? null).toBeNull();
+        expect(screen?.facts_path ?? null).toBeNull();
+        expect(existsSync(artifact(project, 'ui-fidelity/facts/XProof.json'))).toBe(false);
+    });
     test('renders multiple screens independently in one Gradle run', async () => {
         const project = makeProject({ screens: { XProof: 'x.png', YProof: 'y.png' } });
         writeReference(project, 'x.png');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invarn/cibuild",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "description": "CI Build CLI — local pipeline orchestration and validation",
   "type": "module",
   "main": "dist/cli.cjs",