@invarn/cibuild 2.1.2 → 2.1.4

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

@@ -1,10 +1,10 @@
 /**
  * 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:
+ * Pure and platform-agnostic: it takes a per-node layout dump (clipped +
+ * unclipped bounds in px, parent) 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).
@@ -26,11 +26,18 @@ export interface LayoutBounds {
 export interface LayoutNode {
     /** Stable id/label for the node within one dump. */
     id: string;
-    /** Root-space bounds in px. */
+    /** Clipped root-space bounds in px (boundsInRoot — the visible region,
+     *  clamped by any clipping ancestor). */
     bounds: LayoutBounds;
+    /** Unclipped root-space bounds in px (positionInRoot + size — the true layout
+     *  extent). Absent in legacy dumps emitted before the structural pass tracked
+     *  it; when present, overflow/clip is derived from this so it survives a
+     *  clamping parent (which would otherwise hide the excess in `bounds`). */
+    unclippedBounds?: LayoutBounds;
     /** Parent node id, or null for a root node. */
     parentId: string | null;
-    /** Whether this node clips its children to its bounds. */
+    /** Legacy clip hint (parent clips its children). The current emitter writes a
+     *  constant false; used only for the legacy (no-`unclippedBounds`) fallback. */
     clipsChildren: boolean;
 }
 export interface LayoutDump {
@@ -74,6 +81,101 @@ export interface DeriveStructuralFactsOptions {
     overlapMinRatio?: number;
 }
 export declare function deriveStructuralFacts(dump: LayoutDump, options?: DeriveStructuralFactsOptions): StructuralFact[];
+/** One element's geometry; x/y optional (position is advisory, see ADR-0004). */
+export interface ElementGeometry {
+    width: number;
+    height: number;
+    x?: number;
+    y?: number;
+}
+export type GeometrySource = Record<string, ElementGeometry>;
+export interface DimensionDelta {
+    dimension: 'width' | 'height' | 'x' | 'y';
+    generated: number;
+    reference: number;
+    delta: number;
+}
+export interface GeometryDelta {
+    elementId: string;
+    deltas: DimensionDelta[];
+}
+/**
+ * Per-element dimensional deltas between a GENERATED geometry (render layout) and
+ * a REFERENCE geometry (design numbers), both in the same unit. Only elements
+ * present on both sides, and only dimensions supplied on both, are compared.
+ * Port of `packages/cli/lib/fidelity-geometry-diff.mjs`.
+ */
+export declare function diffKeyGeometry(generated: GeometrySource, reference: GeometrySource | null | undefined, options?: {
+    tolerancePx?: number;
+}): GeometryDelta[];
+/** `params.reference_geometry["<Screen>"]` — design px, treated 1:1 with dp. */
+export type ReferenceGeometry = Record<string, {
+    w?: number;
+    h?: number;
+    x?: number;
+    y?: number;
+}>;
+export interface StructuralGeometryElement {
+    id: string;
+    rendered: {
+        w: number;
+        h: number;
+    };
+    design: {
+        w: number | undefined;
+        h: number | undefined;
+    };
+    deltas: Array<{
+        dimension: 'w' | 'h' | 'x' | 'y';
+        delta: number;
+    }>;
+    sizeFlag: boolean;
+}
+export interface StructuralGeometry {
+    unit: 'dp';
+    density: number;
+    elements: StructuralGeometryElement[];
+}
+export interface StructuralSummary {
+    clean: boolean;
+    factCount: number;
+    maxSizeDeltaDp: number | null;
+}
+export interface StructuralBlock {
+    summary: StructuralSummary;
+    facts: StructuralFact[];
+    geometry?: StructuralGeometry;
+}
+/**
+ * Assemble the inline `structural` block (ADR-0004): Signal-A facts always, plus
+ * the Signal-B geometry block when `referenceGeometry` is supplied. Size (w/h)
+ * deltas drive `sizeFlag`/`summary.clean`; x/y position deltas are reported but
+ * never flagged (canvas-width artifact). Mirrors Invarn's `buildStructuralBlock`.
+ */
+export declare function buildStructuralBlock(dump: LayoutDump, referenceGeometry?: ReferenceGeometry | null, density?: number, options?: {
+    sizeTolerancePx?: number;
+}): StructuralBlock;
+export interface ReviewRow {
+    element: string;
+    rendered: string | null;
+    design: string | null;
+    fact: string;
+    verdict: null;
+}
+export interface ReviewScaffold {
+    verdict: null;
+    mustExplain: string[];
+    rows: ReviewRow[];
+}
+/**
+ * Build the run-only `review` scaffold from an assembled structural block:
+ * size-flagged geometry elements first (load-bearing), then every structural
+ * fact, each as a row with a null `verdict` the agent must replace.
+ */
+export declare function buildReviewScaffold(structural: {
+    facts?: StructuralFact[];
+    geometry?: StructuralGeometry | null;
+}): ReviewScaffold;
 /**
  * Render-side embedded form of the deriver.
  *
@@ -98,4 +200,33 @@ export declare const RENDER_SCRIPT_FACTS_STAGE: string;
 export declare function getStructuralFactsStageInternals(): {
     deriveStructuralFacts: (dump: LayoutDump, options?: DeriveStructuralFactsOptions) => StructuralFact[];
 };
+/**
+ * Render-side embedded form of the Signal-B differ + structural-block assembler.
+ *
+ * Concatenated into the generated render script alongside `RENDER_SCRIPT_FACTS_STAGE`
+ * (function declarations hoist, so order does not matter — `buildStructuralBlock`
+ * calls the facts stage's `deriveStructuralFacts`). `assembleStructural` references
+ * runtime globals (`fs`, `path`, `log`) defined in the main script and is only
+ * invoked from there. Kept byte-equivalent to the typed `buildStructuralBlock` /
+ * `diffKeyGeometry` above by the parity test, so run-side and preview-side (Invarn)
+ * structural blocks cannot drift.
+ */
+export declare const RENDER_SCRIPT_GEOMETRY_STAGE: string;
+/**
+ * Evaluates the embedded facts + geometry stages together (mirroring how the
+ * render script concatenates them) and returns the pure `diffKeyGeometry` +
+ * `buildStructuralBlock`, so the parity test exercises exactly the shipped code.
+ */
+export declare function getGeometryStageInternals(): {
+    diffKeyGeometry: (generated: GeometrySource, reference: GeometrySource | null | undefined, options?: {
+        tolerancePx?: number;
+    }) => GeometryDelta[];
+    buildStructuralBlock: (dump: LayoutDump, referenceGeometry?: ReferenceGeometry | null, density?: number, options?: {
+        sizeTolerancePx?: number;
+    }) => StructuralBlock;
+    buildReviewScaffold: (structural: {
+        facts?: StructuralFact[];
+        geometry?: StructuralGeometry | null;
+    }) => ReviewScaffold;
+};
 //# sourceMappingURL=structural-facts.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"structural-facts.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/structural-facts.ts"],"names":[],"mappings":"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"}

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

@@ -8,7 +8,7 @@
  * 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';
+import { deriveStructuralFacts, diffKeyGeometry, buildStructuralBlock, buildReviewScaffold, getStructuralFactsStageInternals, getGeometryStageInternals, } 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', () => {
@@ -63,6 +63,75 @@ describe('deriveStructuralFacts — overflow vs clip', () => {
         });
     });
 });
+describe('deriveStructuralFacts — unclippedBounds path (real clamping renders)', () => {
+    // A real clipping parent CLAMPS the child's boundsInRoot to its own edge, so
+    // the clipped `bounds` show no excess — the overflow lives only in
+    // `unclippedBounds`. This is the case bounds-only v1 went blind on.
+    test('a clamped child is reported clipped-by-parent, recovered from unclippedBounds', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 360, bottom: 720 },
+            nodes: [
+                {
+                    id: 'HubPromoBanner',
+                    bounds: { left: 16, top: 100, right: 344, bottom: 262 },
+                    unclippedBounds: { left: 16, top: 100, right: 344, bottom: 262 },
+                    parentId: null,
+                    clipsChildren: false,
+                },
+                {
+                    // visible bounds CLAMPED to the card bottom (262); the true extent runs
+                    // 18px past it → 18px cut away. The current emitter writes clipsChildren
+                    // false, so only unclippedBounds can reveal this.
+                    id: 'voucherTag',
+                    bounds: { left: 250, top: 210, right: 330, bottom: 262 },
+                    unclippedBounds: { left: 250, top: 210, right: 330, bottom: 280 },
+                    parentId: 'HubPromoBanner',
+                    clipsChildren: false,
+                },
+            ],
+        };
+        const facts = deriveStructuralFacts(dump);
+        expect(facts).toHaveLength(1);
+        expect(facts[0]).toMatchObject({
+            kind: 'clipped_by_parent',
+            nodeId: 'voucherTag',
+            clipperId: 'HubPromoBanner',
+            edges: ['bottom'],
+            clippedPx: { bottom: 18 },
+        });
+    });
+    test('a child sticking out of a non-clipping parent (bounds == unclippedBounds) is overflow', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                {
+                    id: 'row',
+                    bounds: { left: 20, top: 20, right: 180, bottom: 100 },
+                    unclippedBounds: { left: 20, top: 20, right: 180, bottom: 100 },
+                    parentId: null,
+                    clipsChildren: false,
+                },
+                {
+                    // not clamped (bounds == unclipped) → the 15px excess is visible.
+                    id: 'chip',
+                    bounds: { left: 150, top: 30, right: 195, bottom: 80 },
+                    unclippedBounds: { 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 },
+        });
+    });
+});
 describe('deriveStructuralFacts — off-screen', () => {
     test('a node extending past the canvas is reported off-screen on those edges', () => {
         const dump = {
@@ -138,6 +207,22 @@ describe('embedded render-side stage parity', () => {
                 { id: 'b', bounds: { left: 80, top: 60, right: 180, bottom: 160 }, parentId: 'root', clipsChildren: false },
             ],
         },
+        // New unclippedBounds path: a clamped child (clip) and a visible-excess child
+        // (overflow) — exercises the embedded port's new branch, not just the legacy one.
+        clipReal: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'card', bounds: { left: 20, top: 20, right: 180, bottom: 200 }, unclippedBounds: { left: 20, top: 20, right: 180, bottom: 200 }, parentId: null, clipsChildren: false },
+                { id: 'tag', bounds: { left: 60, top: 150, right: 140, bottom: 200 }, unclippedBounds: { left: 60, top: 150, right: 140, bottom: 224 }, parentId: 'card', clipsChildren: false },
+            ],
+        },
+        overflowReal: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'row', bounds: { left: 20, top: 20, right: 180, bottom: 100 }, unclippedBounds: { left: 20, top: 20, right: 180, bottom: 100 }, parentId: null, clipsChildren: false },
+                { id: 'chip', bounds: { left: 150, top: 30, right: 195, bottom: 80 }, unclippedBounds: { left: 150, top: 30, right: 195, bottom: 80 }, parentId: 'row', clipsChildren: false },
+            ],
+        },
     };
     for (const [name, dump] of Object.entries(fixtures)) {
         test(`embedded port matches the module for the ${name} fixture`, () => {
@@ -171,4 +256,99 @@ describe('deriveStructuralFacts — motivating regression (voucher tag bottom-cl
         });
     });
 });
+// ---- Signal B: key-geometry diff + inline structural-block assembly ----
+describe('diffKeyGeometry — dimensional gaps', () => {
+    test('reports a size delta on the right element beyond tolerance', () => {
+        const generated = { card: { width: 328, height: 81 }, chip: { width: 64, height: 24 } };
+        const reference = { card: { width: 328, height: 72 }, chip: { width: 64, height: 24 } };
+        expect(diffKeyGeometry(generated, reference)).toEqual([
+            { elementId: 'card', deltas: [{ dimension: 'height', generated: 81, reference: 72, delta: 9 }] },
+        ]);
+    });
+    test('degrades cleanly to no deltas when there is no reference geometry', () => {
+        const generated = { card: { width: 100, height: 50 } };
+        expect(diffKeyGeometry(generated, null)).toEqual([]);
+        expect(diffKeyGeometry(generated, {})).toEqual([]);
+    });
+});
+// The golden hub promo banner (xhdpi, density 2): banner fills the 720px canvas,
+// voucher 96x96dp vs Figma 81x81, banner 96dp tall vs Figma 72, copy<->voucher
+// overlap. Identical fixture + expectations to Invarn's fidelity-structural test,
+// so preview (Invarn) and run (cibuild) assemble byte-identical blocks.
+const HUB_PROMO_DUMP = {
+    canvas: { left: 0, top: 0, right: 720, bottom: 192 },
+    nodes: [
+        { id: 'node-1', bounds: { left: 0, top: 0, right: 720, bottom: 192 }, unclippedBounds: { left: 0, top: 0, right: 720, bottom: 192 }, parentId: null, clipsChildren: false },
+        { id: 'banner', bounds: { left: 0, top: 0, right: 720, bottom: 192 }, unclippedBounds: { left: 0, top: 0, right: 720, bottom: 192 }, parentId: 'node-1', clipsChildren: false },
+        { id: 'voucher', bounds: { left: 496, top: 0, right: 688, bottom: 192 }, unclippedBounds: { left: 496, top: 0, right: 688, bottom: 192 }, parentId: 'banner', clipsChildren: false },
+        { id: 'copy', bounds: { left: 64, top: 24, right: 656, bottom: 117 }, unclippedBounds: { left: 64, top: 24, right: 656, bottom: 117 }, parentId: 'banner', clipsChildren: false },
+    ],
+};
+const HUB_PROMO_REFERENCE = { voucher: { w: 81, h: 81 }, banner: { w: 343, h: 72 } };
+describe('buildStructuralBlock — facts only (no reference geometry)', () => {
+    test('surfaces facts + summary, no geometry block', () => {
+        const block = buildStructuralBlock(HUB_PROMO_DUMP, null, 2);
+        expect(block.facts).toEqual([
+            { kind: 'overlap', nodeIds: ['copy', 'voucher'], overlapPx: { width: 160, height: 93 }, ratio: 0.4036458333333333 },
+        ]);
+        expect(block.summary).toEqual({ clean: false, factCount: 1, maxSizeDeltaDp: null });
+        expect(block.geometry).toBeUndefined();
+    });
+});
+describe('buildStructuralBlock — with reference geometry (Signal B)', () => {
+    test('reports the golden size deltas and a not-clean summary', () => {
+        const block = buildStructuralBlock(HUB_PROMO_DUMP, HUB_PROMO_REFERENCE, 2);
+        expect(block.summary).toEqual({ clean: false, factCount: 1, maxSizeDeltaDp: 24 });
+        expect(block.geometry?.unit).toBe('dp');
+        expect(block.geometry?.density).toBe(2);
+        const voucher = block.geometry?.elements.find((e) => e.id === 'voucher');
+        expect(voucher).toEqual({
+            id: 'voucher',
+            rendered: { w: 96, h: 96 },
+            design: { w: 81, h: 81 },
+            deltas: [{ dimension: 'w', delta: 15 }, { dimension: 'h', delta: 15 }],
+            sizeFlag: true,
+        });
+        const banner = block.geometry?.elements.find((e) => e.id === 'banner');
+        expect(banner?.sizeFlag).toBe(true);
+        expect(banner?.deltas).toContainEqual({ dimension: 'h', delta: 24 });
+    });
+});
+describe('buildReviewScaffold — run-only verdict obligation', () => {
+    test('forces a verdict per flagged element + fact, with the golden mustExplain', () => {
+        const block = buildStructuralBlock(HUB_PROMO_DUMP, HUB_PROMO_REFERENCE, 2);
+        const review = buildReviewScaffold(block);
+        expect(review.verdict).toBeNull();
+        expect(review.mustExplain).toEqual(['voucher', 'banner', 'copy↔voucher']);
+        expect(review.rows.every((r) => r.verdict === null)).toBe(true);
+        expect(review.rows.find((r) => r.element === 'voucher')).toEqual({
+            element: 'voucher',
+            rendered: '96×96dp',
+            design: '81×81dp',
+            fact: 'size +15×+15',
+            verdict: null,
+        });
+        expect(review.rows.find((r) => r.element === 'copy↔voucher')?.fact).toBe('overlap 160×93px (ratio 0.40)');
+    });
+});
+describe('embedded geometry stage parity', () => {
+    // The render ships a JS-source port of the differ + assembler. It must produce
+    // byte-identical blocks to the canonical typed module, or run-side structural
+    // would diverge from preview-side (Invarn) and from the tests.
+    const embedded = getGeometryStageInternals();
+    test('embedded diffKeyGeometry matches the module', () => {
+        const generated = { card: { width: 328, height: 81 } };
+        const reference = { card: { width: 328, height: 72 } };
+        expect(embedded.diffKeyGeometry(generated, reference)).toEqual(diffKeyGeometry(generated, reference));
+    });
+    for (const [name, ref] of Object.entries({ factsOnly: null, withGeometry: HUB_PROMO_REFERENCE })) {
+        test(`embedded buildStructuralBlock matches the module (${name})`, () => {
+            expect(embedded.buildStructuralBlock(HUB_PROMO_DUMP, ref, 2)).toEqual(buildStructuralBlock(HUB_PROMO_DUMP, ref, 2));
+        });
+        test(`embedded buildReviewScaffold matches the module (${name})`, () => {
+            const block = buildStructuralBlock(HUB_PROMO_DUMP, ref, 2);
+            expect(embedded.buildReviewScaffold(block)).toEqual(buildReviewScaffold(block));
+        });
+    }
+});
 //# 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;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"}
+{"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;AA8vBD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAYrF;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,7 +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';
+import { RENDER_SCRIPT_FACTS_STAGE, RENDER_SCRIPT_GEOMETRY_STAGE } from './structural-facts.js';
 /**
  * Default Roborazzi record task. Run from the project root so Gradle resolves
  * it in whichever subproject declares it.
@@ -91,6 +91,10 @@ var resultPath = path.join(artifactsDir, 'protocol-result.json');
 
 var currentEntries = [];
 var buildError = null;
+// params.reference_geometry (design-px geometry per screen), set in main() and
+// read by the structural assembler. Null when the run declared none → Signal B
+// is skipped and the structural block carries facts only.
+var referenceGeometry = null;
 
 function log(message) {
   console.log('[ui-fidelity-render-android] ' + message);
@@ -597,7 +601,13 @@ function renderScreens(renderable, projectRoot) {
         }
       }
       if (layoutSource !== null) {
+        // Signal A: write the facts + layout artifacts (deep-dive path).
         deriveAndWriteFacts(entry, layoutSource);
+        // ADR-0004: assemble the inline structural block (facts + Signal-B
+        // geometry deltas vs reference_geometry) onto the screen entry, so the
+        // judge reads the signals from protocol-result.json without fetching
+        // artifacts. CONFIG.scale is the render density (dp = px / scale).
+        assembleStructural(entry, layoutSource, referenceGeometry, CONFIG.scale);
       }
     });
   } finally {
@@ -655,6 +665,14 @@ function main() {
     params.provenance && typeof params.provenance === 'object' && !Array.isArray(params.provenance)
       ? params.provenance
       : {};
+  // Signal-B design numbers (advisory): { "<Screen>": { "<tagId>": {w,h,x,y} } }
+  // in design px. Absent → the structural block carries Signal-A facts only.
+  referenceGeometry =
+    params.reference_geometry &&
+    typeof params.reference_geometry === 'object' &&
+    !Array.isArray(params.reference_geometry)
+      ? params.reference_geometry
+      : null;
 
   var screens = Object.keys(params.screens);
   currentEntries = screens.map(function (screen) {
@@ -826,6 +844,7 @@ export function generateAndroidRenderScript(config) {
         'var PACKAGE_ARCHIVE_NAME = ' + JSON.stringify(PACKAGE_ARCHIVE_BASENAME) + ';',
         RENDER_SCRIPT_TRIM_STAGE,
         RENDER_SCRIPT_FACTS_STAGE,
+        RENDER_SCRIPT_GEOMETRY_STAGE,
         ANDROID_RENDER_SCRIPT_MAIN,
     ].join('\n');
 }

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

@@ -315,6 +315,57 @@ describe('android render runtime — render + trim (happy path)', () => {
             ],
         });
     });
+    test('assembles the inline structural block (facts) onto the screen entry', 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');
+        // Signal A surfaces inline (no reference_geometry → no geometry block).
+        expect(screen?.structural?.summary).toEqual({ clean: false, factCount: 1, maxSizeDeltaDp: null });
+        expect(screen?.structural?.facts).toHaveLength(1);
+        expect(screen?.structural?.geometry).toBeUndefined();
+        // The verdict obligation is baked onto the run result by the runner: the
+        // clip fact (node 'tag') becomes a must-explain row with a null verdict.
+        expect(screen?.structural?.review?.verdict).toBeNull();
+        expect(screen?.structural?.review?.mustExplain).toEqual(['tag']);
+        expect(screen?.structural?.review?.rows.every((r) => r.verdict === null)).toBe(true);
+    });
+    test('adds Signal-B geometry deltas to the structural block when reference_geometry is given', async () => {
+        // The fake layout dump: card bounds 160x180px, tag 80x74px (density 2 → dp
+        // card 80x90, tag 40x37). Declare design numbers so the card reads +10dp tall.
+        const project = makeProject({
+            screens: { XProof: 'x.png' },
+            reference_geometry: { XProof: { card: { w: 80, h: 80 }, tag: { w: 40, h: 37 } } },
+        });
+        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?.structural?.summary).toEqual({ clean: false, factCount: 1, maxSizeDeltaDp: 10 });
+        const geometry = screen?.structural?.geometry;
+        expect(geometry?.unit).toBe('dp');
+        expect(geometry?.density).toBe(2);
+        const card = geometry?.elements.find((e) => e.id === 'card');
+        expect(card).toEqual({
+            id: 'card',
+            rendered: { w: 80, h: 90 },
+            design: { w: 80, h: 80 },
+            deltas: [{ dimension: 'h', delta: 10 }],
+            sizeFlag: true,
+        });
+        const tag = geometry?.elements.find((e) => e.id === 'tag');
+        expect(tag?.sizeFlag).toBe(false);
+        expect(tag?.deltas).toEqual([]);
+    });
     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');

package/package.json

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