@invarn/cibuild 2.1.3 → 2.1.5

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

@@ -81,6 +81,128 @@ 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;
+}>;
+/**
+ * Per-edge overhang of an element that overflows its frame (Signal B v2). For a
+ * clipping element the load-bearing invariant is its overhang per edge (= the
+ * clip), NOT its raw w/h: width can match and the clip still be wrong. Frame-
+ * relative edge overhang is the real clip, so it IS flagged — unlike absolute
+ * canvas x/y, which stays suppressed as a canvas-width artifact.
+ *
+ *   rendered[edge] = element's unclipped edge − frame's edge (dp)
+ *   design[edge]   = design element edge − design frame edge (from reference_geometry)
+ *   deltas         = edges where |rendered − design| > overhangTolerance
+ *   clipFlag       = any delta present
+ */
+export interface StructuralOverhang {
+    unit: 'dp';
+    rendered: Partial<Record<Edge, number>>;
+    design: Partial<Record<Edge, number>>;
+    deltas: Array<{
+        edge: Edge;
+        delta: number;
+    }>;
+    clipFlag: boolean;
+}
+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;
+    /** Present only when the element overflows its (declared) frame. */
+    overhang?: StructuralOverhang;
+}
+export interface StructuralGeometry {
+    unit: 'dp';
+    density: number;
+    elements: StructuralGeometryElement[];
+}
+export interface StructuralSummary {
+    clean: boolean;
+    factCount: number;
+    maxSizeDeltaDp: number | null;
+    /** Largest |overhang delta| in dp, or null when there is no geometry. */
+    maxClipDeltaDp: 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;
+    overhangTolerancePx?: 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.
  *
@@ -105,4 +227,34 @@ 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;
+        overhangTolerancePx?: 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;6CACyC;IACzC,MAAM,EAAE,YAAY,CAAC;IACrB;;;+EAG2E;IAC3E,eAAe,CAAC,EAAE,YAAY,CAAC;IAC/B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB;oFACgF;IAChF,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,CAuHlB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAgJvC,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', () => {
@@ -256,4 +256,181 @@ 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, maxClipDeltaDp: 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, maxClipDeltaDp: 0 });
+        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 });
+    });
+});
+// ---- Signal B v2: per-edge overhang (clip) diff ----
+//
+// The euro-coin miss: a voucher tag meant to overflow-and-clip on the bottom-right
+// reproduced at the wrong size, so its bottom clip came out wrong even though its
+// width matched. Signal B v1 (raw w/h) is blind here — the load-bearing invariant
+// for a clipping element is its per-edge OVERHANG (= the clip), not its raw size.
+// These two fixtures are the field validation numbers (px @ density 2): the
+// logged-in state MUST flag (bottom Δ−9), the guest state MUST NOT (bottom Δ+2,
+// within tolerance). Same fixtures + expectations as Invarn's preview copy.
+// Logged-in: rendered voucher unclipped 289..370 × 16..86.5dp, frame card 343×70.5dp.
+// right overhang 27=27 (match); bottom overhang 16 vs design 25 → Δ−9 (FLAG).
+const OVERHANG_LOGGED_IN_DUMP = {
+    canvas: { left: 0, top: 0, right: 760, bottom: 200 },
+    nodes: [
+        { id: 'node-1', bounds: { left: 0, top: 0, right: 760, bottom: 200 }, unclippedBounds: { left: 0, top: 0, right: 760, bottom: 200 }, parentId: null, clipsChildren: false },
+        { id: 'banner', bounds: { left: 0, top: 0, right: 686, bottom: 141 }, unclippedBounds: { left: 0, top: 0, right: 686, bottom: 141 }, parentId: 'node-1', clipsChildren: false },
+        { id: 'voucher', bounds: { left: 578, top: 32, right: 740, bottom: 173 }, unclippedBounds: { left: 578, top: 32, right: 740, bottom: 173 }, parentId: 'banner', clipsChildren: false },
+    ],
+};
+const OVERHANG_LOGGED_IN_REF = { banner: { x: 0, y: 0, w: 343, h: 72 }, voucher: { x: 289, y: 16, w: 81, h: 81 } };
+// Guest: rendered voucher unclipped 272..381 × 19..127.5dp, frame card 343×108.5dp.
+// right overhang 38=38 (match); bottom overhang 19 vs design 17 → Δ+2 (within tol, PASS).
+const OVERHANG_GUEST_DUMP = {
+    canvas: { left: 0, top: 0, right: 800, bottom: 280 },
+    nodes: [
+        { id: 'node-1', bounds: { left: 0, top: 0, right: 800, bottom: 280 }, unclippedBounds: { left: 0, top: 0, right: 800, bottom: 280 }, parentId: null, clipsChildren: false },
+        { id: 'banner', bounds: { left: 0, top: 0, right: 686, bottom: 217 }, unclippedBounds: { left: 0, top: 0, right: 686, bottom: 217 }, parentId: 'node-1', clipsChildren: false },
+        { id: 'voucher', bounds: { left: 544, top: 38, right: 762, bottom: 255 }, unclippedBounds: { left: 544, top: 38, right: 762, bottom: 255 }, parentId: 'banner', clipsChildren: false },
+    ],
+};
+const OVERHANG_GUEST_REF = { banner: { x: 0, y: 0, w: 343, h: 111 }, voucher: { x: 272, y: 19, w: 109, h: 109 } };
+describe('buildStructuralBlock — per-edge overhang (Signal B v2)', () => {
+    test('logged-in voucher: flags the bottom clip (Δ−9), not the matching right edge', () => {
+        const block = buildStructuralBlock(OVERHANG_LOGGED_IN_DUMP, OVERHANG_LOGGED_IN_REF, 2);
+        const voucher = block.geometry?.elements.find((e) => e.id === 'voucher');
+        expect(voucher?.overhang).toEqual({
+            unit: 'dp',
+            rendered: { right: 27, bottom: 16 },
+            design: { right: 27, bottom: 25 },
+            deltas: [{ edge: 'bottom', delta: -9 }],
+            clipFlag: true,
+        });
+        expect(block.summary.clean).toBe(false);
+        expect(block.summary.maxClipDeltaDp).toBe(9);
+    });
+    test('guest voucher: matching right edge, bottom within tolerance → no clipFlag', () => {
+        const block = buildStructuralBlock(OVERHANG_GUEST_DUMP, OVERHANG_GUEST_REF, 2);
+        const voucher = block.geometry?.elements.find((e) => e.id === 'voucher');
+        expect(voucher?.overhang).toEqual({
+            unit: 'dp',
+            rendered: { right: 38, bottom: 19 },
+            design: { right: 38, bottom: 17 },
+            deltas: [],
+            clipFlag: false,
+        });
+    });
+    test('a fully-contained element gets no overhang block', () => {
+        const block = buildStructuralBlock(HUB_PROMO_DUMP, HUB_PROMO_REFERENCE, 2);
+        const voucher = block.geometry?.elements.find((e) => e.id === 'voucher');
+        expect(voucher?.overhang).toBeUndefined();
+        expect(block.summary.maxClipDeltaDp).toBe(0);
+    });
+});
+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)');
+    });
+    test('a clipFlag element forces a verdict row describing the overhang mismatch', () => {
+        const block = buildStructuralBlock(OVERHANG_LOGGED_IN_DUMP, OVERHANG_LOGGED_IN_REF, 2);
+        const review = buildReviewScaffold(block);
+        expect(review.mustExplain).toContain('voucher');
+        const clipRow = review.rows.find((r) => r.element === 'voucher' && r.fact.startsWith('clip'));
+        expect(clipRow).toEqual({
+            element: 'voucher',
+            rendered: 'bottom 16dp',
+            design: 'bottom 25dp',
+            fact: 'clip bottom 16dp vs design 25dp (-9)',
+            verdict: null,
+        });
+    });
+});
+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));
+    });
+    const parityCases = [
+        { name: 'factsOnly', dump: HUB_PROMO_DUMP, ref: null },
+        { name: 'withGeometry', dump: HUB_PROMO_DUMP, ref: HUB_PROMO_REFERENCE },
+        { name: 'overhangLoggedIn', dump: OVERHANG_LOGGED_IN_DUMP, ref: OVERHANG_LOGGED_IN_REF },
+        { name: 'overhangGuest', dump: OVERHANG_GUEST_DUMP, ref: OVERHANG_GUEST_REF },
+    ];
+    for (const { name, dump, ref } of parityCases) {
+        test(`embedded buildStructuralBlock matches the module (${name})`, () => {
+            expect(embedded.buildStructuralBlock(dump, ref, 2)).toEqual(buildStructuralBlock(dump, ref, 2));
+        });
+        test(`embedded buildReviewScaffold matches the module (${name})`, () => {
+            const block = buildStructuralBlock(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, maxClipDeltaDp: 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, maxClipDeltaDp: 0 });
+        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.3",
+  "version": "2.1.5",
   "description": "CI Build CLI — local pipeline orchestration and validation",
   "type": "module",
   "main": "dist/cli.cjs",