@invarn/cibuild 2.3.1 → 2.3.3

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, derivePresenceFacts, deriveCopyFacts, deriveSpanFacts, deriveLineFacts, deriveColorFacts, ciede2000, hexToLab, diffKeyGeometry, buildStructuralBlock, buildReviewScaffold, appearanceReferenceFromPreviousRender, buildAppearanceReferenceFromParams, getStructuralFactsStageInternals, getGeometryStageInternals, } from './structural-facts.js';
+import { deriveStructuralFacts, derivePresenceFacts, deriveCopyFacts, deriveSpanFacts, deriveLineFacts, deriveColorFacts, deriveTypefaceFacts, ciede2000, hexToLab, diffKeyGeometry, buildStructuralBlock, buildReviewScaffold, appearanceReferenceFromPreviousRender, buildAppearanceReferenceFromParams, 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', () => {
@@ -223,6 +223,18 @@ describe('embedded render-side stage parity', () => {
                 { id: 'chip', bounds: { left: 150, top: 30, right: 195, bottom: 80 }, unclippedBounds: { left: 150, top: 30, right: 195, bottom: 80 }, parentId: 'row', clipsChildren: false },
             ],
         },
+        // A duplicated testTag: the collision guard must withhold the child's
+        // (mispairable) overflow and emit the duplicate_tag fact identically.
+        duplicateTag: {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'list', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'copy_button', bounds: { left: 20, top: 20, right: 180, bottom: 60 }, parentId: 'list', clipsChildren: false },
+                { id: 'copy_button', bounds: { left: 20, top: 80, right: 180, bottom: 120 }, parentId: 'list', clipsChildren: false },
+                { id: 'copy_button', bounds: { left: 20, top: 140, right: 180, bottom: 180 }, parentId: 'list', clipsChildren: false },
+                { id: 'copy_label', bounds: { left: 30, top: 30, right: 120, bottom: 50 }, parentId: 'copy_button', clipsChildren: false },
+            ],
+        },
     };
     for (const [name, dump] of Object.entries(fixtures)) {
         test(`embedded port matches the module for the ${name} fixture`, () => {
@@ -256,6 +268,45 @@ describe('deriveStructuralFacts — motivating regression (voucher tag bottom-cl
         });
     });
 });
+describe('deriveStructuralFacts — duplicate testTag collision guard', () => {
+    // Repeated rows tagging their pill with one shared testTag: parent lookups
+    // resolve through a last-wins id map, so overflow/clip derived through the
+    // duplicated tag compares arbitrary instances (a child of the first row
+    // measured against the last row's box reads as a huge spurious overflow).
+    // The deriver must refuse to guess — name the collision as a fact and
+    // withhold the pairing-derived facts for that tag.
+    test('three nodes sharing one testTag yield a duplicate_tag fact and no overflow/clip facts through that tag', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'list', bounds: { left: 0, top: 0, right: 200, bottom: 400 }, parentId: null, clipsChildren: false },
+                { id: 'copy_button', bounds: { left: 20, top: 20, right: 180, bottom: 60 }, parentId: 'list', clipsChildren: false },
+                { id: 'copy_button', bounds: { left: 20, top: 80, right: 180, bottom: 120 }, parentId: 'list', clipsChildren: false },
+                { id: 'copy_button', bounds: { left: 20, top: 140, right: 180, bottom: 180 }, parentId: 'list', clipsChildren: false },
+                // Sits inside the FIRST pill; paired against the last-wins instance
+                // (top 140) it would read as a spurious 110px top overflow.
+                { id: 'copy_label', bounds: { left: 30, top: 30, right: 120, bottom: 50 }, parentId: 'copy_button', clipsChildren: false },
+            ],
+        };
+        expect(deriveStructuralFacts(dump)).toEqual([
+            { kind: 'duplicate_tag', tag: 'copy_button', instanceCount: 3 },
+        ]);
+    });
+    test('a duplicated node overflowing its unique parent is withheld too — attribution is ambiguous', () => {
+        const dump = {
+            canvas: CANVAS,
+            nodes: [
+                { id: 'row', bounds: { left: 20, top: 20, right: 180, bottom: 100 }, parentId: null, clipsChildren: false },
+                // The first instance sticks out 15px past the row; the second is contained.
+                { id: 'chip', bounds: { left: 150, top: 30, right: 195, bottom: 80 }, parentId: 'row', clipsChildren: false },
+                { id: 'chip', bounds: { left: 30, top: 30, right: 60, bottom: 60 }, parentId: 'row', clipsChildren: false },
+            ],
+        };
+        expect(deriveStructuralFacts(dump)).toEqual([
+            { kind: 'duplicate_tag', tag: 'chip', instanceCount: 2 },
+        ]);
+    });
+});
 // ---- Signal B: key-geometry diff + inline structural-block assembly ----
 describe('diffKeyGeometry — dimensional gaps', () => {
     test('reports a size delta on the right element beyond tolerance', () => {
@@ -743,6 +794,57 @@ describe('deriveLineFacts — declared line split vs rendered laid-out lines', (
         ]);
     });
 });
+describe('deriveTypefaceFacts — resolved vs design typeface per element', () => {
+    test('a family mismatch yields one typeface fact carrying both fonts', () => {
+        const facts = deriveTypefaceFacts({ code: { family: 'Roboto', weight: 400 } }, { code: { family: 'Poppins', weight: 600 } });
+        expect(facts).toEqual([
+            {
+                kind: 'typeface',
+                elementId: 'code',
+                channel: 'text',
+                rendered: { family: 'Roboto', weight: 400 },
+                reference: { family: 'Poppins', weight: 600 },
+            },
+        ]);
+    });
+    test('a weight mismatch on the same family yields a typeface fact', () => {
+        const facts = deriveTypefaceFacts({ code: { family: 'Poppins', weight: 400 } }, { code: { family: 'Poppins', weight: 600 } });
+        expect(facts).toHaveLength(1);
+        expect(facts[0]).toMatchObject({ kind: 'typeface', elementId: 'code', channel: 'text' });
+    });
+    test('an exact family+weight match produces no fact', () => {
+        expect(deriveTypefaceFacts({ code: { family: 'Poppins', weight: 600 } }, { code: { family: 'Poppins', weight: 600 } })).toEqual([]);
+    });
+    test('a normalization-equivalent pair produces no fact (suffix-encoded weight vs numeric, case, separators)', () => {
+        // design names "Poppins-SemiBold"; render resolved "Poppins" weight 600 — same font.
+        expect(deriveTypefaceFacts({ code: { family: 'Poppins', weight: 600 } }, { code: { family: 'Poppins-SemiBold' } })).toEqual([]);
+        // resource-name encoding "fira_sans_medium" vs design "Fira Sans" weight 500.
+        expect(deriveTypefaceFacts({ code: { family: 'fira_sans_medium' } }, { code: { family: 'Fira Sans', weight: 500 } })).toEqual([]);
+        // pure case difference on the family.
+        expect(deriveTypefaceFacts({ code: { family: 'POPPINS', weight: 600 } }, { code: { family: 'poppins', weight: 600 } })).toEqual([]);
+    });
+    test('a suffix-encoded family that disagrees on weight still flags', () => {
+        // design "Poppins-SemiBold" (→600) vs resolved "Poppins" Regular (400) — a real
+        // weight fallback the suffix normalization must NOT mask.
+        const facts = deriveTypefaceFacts({ code: { family: 'Poppins', weight: 400 } }, { code: { family: 'Poppins-SemiBold' } });
+        expect(facts).toHaveLength(1);
+        expect(facts[0]).toMatchObject({ kind: 'typeface', elementId: 'code' });
+    });
+    test('a missing rendered or reference font produces no fact (graceful, no false positive)', () => {
+        // reference declares a font the render never resolved → no signal → no fact
+        expect(deriveTypefaceFacts({ code: undefined }, { code: { family: 'Poppins', weight: 600 } })).toEqual([]);
+        expect(deriveTypefaceFacts({ code: { family: '' } }, { code: { family: 'Poppins', weight: 600 } })).toEqual([]);
+        // render resolved a font the reference never declared → no reference signal → no fact
+        expect(deriveTypefaceFacts({ code: { family: 'Roboto', weight: 400 } }, {})).toEqual([]);
+        expect(deriveTypefaceFacts({ code: { family: 'Roboto', weight: 400 } }, { code: { family: '' } })).toEqual([]);
+    });
+    test('result is order-independent and deterministic (sorted by element id)', () => {
+        const a = deriveTypefaceFacts({ b: { family: 'Roboto', weight: 400 }, a: { family: 'Arial', weight: 400 } }, { a: { family: 'Poppins', weight: 600 }, b: { family: 'Roboto', weight: 400 } });
+        const b = deriveTypefaceFacts({ a: { family: 'Arial', weight: 400 }, b: { family: 'Roboto', weight: 400 } }, { b: { family: 'Roboto', weight: 400 }, a: { family: 'Poppins', weight: 600 } });
+        expect(a).toEqual(b);
+        expect(a.map((f) => f.elementId)).toEqual(['a']);
+    });
+});
 describe('buildStructuralBlock — appearance container (Signal C, additive)', () => {
     test('no appearanceReference → no appearance container; facts + geometry unchanged', () => {
         const withC = buildStructuralBlock(HUB_PROMO_DUMP, HUB_PROMO_REFERENCE, 2);
@@ -960,6 +1062,117 @@ describe('buildStructuralBlock — appearance container (Signal C, additive)', (
         const block = buildStructuralBlock(COLOR_DUMP, null, 2);
         expect(block.appearance).toBeUndefined();
     });
+    // ---- Signal C typeface facts (resolved vs design font, issue 03) ----
+    // A dump whose text node carries the resolved-typeface enrichment (issue 03):
+    // the font that ACTUALLY painted, post-fallback — here a Roboto fallback where
+    // the design wants Poppins SemiBold. The dump also declares the render SDK the
+    // proof ran at (TextRunShaper, the capture seam, is API 31+).
+    const TYPEFACE_DUMP = {
+        canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+        renderSdk: 34,
+        nodes: [
+            {
+                id: 'code',
+                bounds: { left: 0, top: 0, right: 100, bottom: 20 },
+                parentId: null,
+                clipsChildren: false,
+                text: 'INV-50',
+                resolvedTypeface: { family: 'Roboto', weight: 400 },
+            },
+        ],
+    };
+    test('with a reference typeface → a typeface fact fires on divergence and the resolved font is persisted (issue 03)', () => {
+        const block = buildStructuralBlock(TYPEFACE_DUMP, null, 2, undefined, {
+            baseline: 'figma',
+            elementIds: ['code'],
+            typeface: { code: { family: 'Poppins', weight: 600 } },
+        });
+        expect(block.appearance?.facts).toEqual([
+            {
+                kind: 'typeface',
+                elementId: 'code',
+                channel: 'text',
+                rendered: { family: 'Roboto', weight: 400 },
+                reference: { family: 'Poppins', weight: 600 },
+            },
+        ]);
+        expect(block.appearance?.rendered?.typeface).toEqual({ code: { family: 'Roboto', weight: 400 } });
+    });
+    test('a matching resolved typeface → no fact; the snapshot still persists the resolved font (issue 03)', () => {
+        const block = buildStructuralBlock(TYPEFACE_DUMP, null, 2, undefined, {
+            baseline: 'figma',
+            elementIds: ['code'],
+            typeface: { code: { family: 'Roboto', weight: 400 } },
+        });
+        expect(block.appearance?.facts).toEqual([]);
+        expect(block.appearance?.rendered?.typeface).toEqual({ code: { family: 'Roboto', weight: 400 } });
+    });
+    test('a node without the enrichment yields no typeface signal and no snapshot entry (old packages degrade gracefully)', () => {
+        const block = buildStructuralBlock(COPY_DUMP, null, 2, undefined, {
+            baseline: 'figma',
+            elementIds: ['title'],
+            typeface: { title: { family: 'Poppins', weight: 600 } },
+        });
+        expect(block.appearance?.facts).toEqual([]);
+        expect(block.appearance?.rendered?.typeface).toBeUndefined();
+    });
+    test('a render SDK below 31 omits typeface facts AND carries the advisory — never a silent pass (issue 03)', () => {
+        const oldSdkDump = {
+            canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+            renderSdk: 28,
+            nodes: [
+                { id: 'code', bounds: { left: 0, top: 0, right: 100, bottom: 20 }, parentId: null, clipsChildren: false, text: 'INV-50' },
+            ],
+        };
+        const block = buildStructuralBlock(oldSdkDump, null, 2, undefined, {
+            baseline: 'figma',
+            elementIds: ['code'],
+            typeface: { code: { family: 'Poppins', weight: 600 } },
+        });
+        expect(block.appearance?.facts).toEqual([]);
+        expect(block.appearance?.advisories).toEqual([
+            'typeface check requires render SDK >= 31; this proof rendered at SDK 28 — typeface facts were not derived (not checked, not passing)',
+        ]);
+    });
+    test('a render SDK below 31 without a typeface reference carries no advisory (nothing was checkable)', () => {
+        const oldSdkDump = {
+            canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+            renderSdk: 28,
+            nodes: [
+                { id: 'code', bounds: { left: 0, top: 0, right: 100, bottom: 20 }, parentId: null, clipsChildren: false },
+            ],
+        };
+        const block = buildStructuralBlock(oldSdkDump, null, 2, undefined, {
+            baseline: 'figma',
+            elementIds: ['code'],
+        });
+        expect(block.appearance?.advisories).toBeUndefined();
+    });
+    test('a render SDK >= 31 or an undeclared one carries no advisory; facts derive normally', () => {
+        // Declared modern SDK → facts derive, no advisory.
+        const modern = buildStructuralBlock(TYPEFACE_DUMP, null, 2, undefined, {
+            baseline: 'figma',
+            elementIds: ['code'],
+            typeface: { code: { family: 'Poppins', weight: 600 } },
+        });
+        expect(modern.appearance?.advisories).toBeUndefined();
+        expect(modern.appearance?.facts).toHaveLength(1);
+        // Undeclared SDK (an old package's dump): no advisory, derivation still runs
+        // (it just finds no rendered typefaces → no facts, the graceful path).
+        const undeclared = {
+            canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+            nodes: [
+                { id: 'code', bounds: { left: 0, top: 0, right: 100, bottom: 20 }, parentId: null, clipsChildren: false },
+            ],
+        };
+        const block = buildStructuralBlock(undeclared, null, 2, undefined, {
+            baseline: 'figma',
+            elementIds: ['code'],
+            typeface: { code: { family: 'Poppins', weight: 600 } },
+        });
+        expect(block.appearance?.advisories).toBeUndefined();
+        expect(block.appearance?.facts).toEqual([]);
+    });
 });
 // ---- Signal C: previous-render → AppearanceReference mapper (issue 01) ----
 //
@@ -1008,6 +1221,47 @@ describe('appearanceReferenceFromPreviousRender — previous render snapshot →
             text: { copy: 'Get 5 € off your first order placed by 1 lug 2026.' },
         });
     });
+    test('a previous render with per-element resolved typefaces → the mapper carries typeface into the reference (typeface issue 05)', () => {
+        // The previous render's RESOLVED font becomes the drift reference: a
+        // previously-correct element that silently falls back on a later build then
+        // diverges from its own prior snapshot and is flagged.
+        const previous = {
+            elementIds: ['banner', 'code'],
+            typeface: { code: { family: 'poppins_semibold', weight: 600 } },
+        };
+        expect(appearanceReferenceFromPreviousRender(previous)).toEqual({
+            baseline: 'previous_render',
+            elementIds: ['banner', 'code'],
+            typeface: { code: { family: 'poppins_semibold', weight: 600 } },
+        });
+        // An empty typeface map is no signal on that axis — not carried.
+        expect(appearanceReferenceFromPreviousRender({ elementIds: ['banner'], typeface: {} })).toEqual({ baseline: 'previous_render', elementIds: ['banner'] });
+    });
+    test('fed into buildStructuralBlock, a typeface that drifts from the previous render yields a previous_render typeface fact (typeface issue 05)', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 343, bottom: 72 },
+            renderSdk: 34,
+            nodes: [
+                { id: 'code', bounds: { left: 0, top: 0, right: 343, bottom: 40 }, parentId: null, clipsChildren: false, text: 'INV-50', resolvedTypeface: { family: 'Roboto-Regular', weight: 400 } },
+            ],
+        };
+        const previous = {
+            elementIds: ['code'],
+            typeface: { code: { family: 'poppins_semibold' } },
+        };
+        const block = buildStructuralBlock(dump, null, 2, undefined, appearanceReferenceFromPreviousRender(previous));
+        expect(block.appearance?.baseline).toBe('previous_render');
+        const typefaceFacts = (block.appearance?.facts ?? []).filter((f) => f.kind === 'typeface');
+        expect(typefaceFacts).toEqual([
+            {
+                kind: 'typeface',
+                elementId: 'code',
+                channel: 'text',
+                rendered: { family: 'Roboto-Regular', weight: 400 },
+                reference: { family: 'poppins_semibold' },
+            },
+        ]);
+    });
     test('a previous render with both color and text → the reference carries both maps (issue 03)', () => {
         const previous = {
             elementIds: ['banner', 'copy'],
@@ -1256,9 +1510,54 @@ describe('buildAppearanceReferenceFromParams — union of geometry/text/color id
             lines: { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] },
         });
     });
+    test('typeface only (no geometry/text/color) → a reference carrying typeface, ids from the typeface keys (typeface issue 04)', () => {
+        const ref = buildAppearanceReferenceFromParams({
+            refTypeface: { code: { family: 'Poppins', weight: 600 } },
+            baseline: 'figma',
+        });
+        expect(ref).toEqual({
+            baseline: 'figma',
+            elementIds: ['code'],
+            typeface: { code: { family: 'Poppins', weight: 600 } },
+        });
+    });
     test('none present → null (no appearance container)', () => {
         expect(buildAppearanceReferenceFromParams({ baseline: 'figma' })).toBeNull();
-        expect(buildAppearanceReferenceFromParams({ baseline: 'figma', refGeom: {}, refColor: {}, refText: {}, refSpans: {}, refLines: {} })).toBeNull();
+        expect(buildAppearanceReferenceFromParams({ baseline: 'figma', refGeom: {}, refColor: {}, refText: {}, refSpans: {}, refLines: {}, refTypeface: {} })).toBeNull();
+    });
+    test('fed into buildStructuralBlock, a typeface reference flags a diverging resolved font and stays silent on a matching or unresolvable one (typeface issue 04)', () => {
+        // The design (Figma) declares Poppins 600 on `code` and Fira Sans 500 on
+        // `label`. The render resolved a Roboto fallback on `code` (→ one fact) and
+        // the correct font on `label` (→ none); `legacyText` has a declared font but
+        // no resolved enrichment (old package) → no signal, no fact.
+        const dump = {
+            canvas: { left: 0, top: 0, right: 686, bottom: 282 },
+            renderSdk: 34,
+            nodes: [
+                { id: 'code', bounds: { left: 0, top: 0, right: 300, bottom: 40 }, parentId: null, clipsChildren: false, text: 'INV-50', resolvedTypeface: { family: 'Roboto-Regular', weight: 400 } },
+                { id: 'label', bounds: { left: 0, top: 50, right: 300, bottom: 90 }, parentId: null, clipsChildren: false, text: 'Your code', resolvedTypeface: { family: 'fira_sans_medium' } },
+                { id: 'legacyText', bounds: { left: 0, top: 100, right: 300, bottom: 140 }, parentId: null, clipsChildren: false, text: 'Old' },
+            ],
+        };
+        const ref = buildAppearanceReferenceFromParams({
+            refTypeface: {
+                code: { family: 'Poppins', weight: 600 },
+                label: { family: 'Fira Sans', weight: 500 },
+                legacyText: { family: 'Poppins', weight: 400 },
+            },
+            baseline: 'figma',
+        });
+        const block = buildStructuralBlock(dump, null, 2, undefined, ref);
+        const typefaceFacts = (block.appearance?.facts ?? []).filter((f) => f.kind === 'typeface');
+        expect(typefaceFacts).toEqual([
+            {
+                kind: 'typeface',
+                elementId: 'code',
+                channel: 'text',
+                rendered: { family: 'Roboto-Regular', weight: 400 },
+                reference: { family: 'Poppins', weight: 600 },
+            },
+        ]);
     });
     test('fed into buildStructuralBlock, a spans-only reference emits exactly one span_mismatch for the wrong extent (issue 16)', () => {
         const dump = {
@@ -1524,6 +1823,235 @@ describe('buildStructuralBlock — placement facts (composition runs)', () => {
         }
     });
 });
+describe('buildStructuralBlock — duplicate testTag withhold (geometry / overhang / placement)', () => {
+    // A duplicated tag's entry in the generated-geometry map is last-wins, so its
+    // size diff, any overhang computed against it as a frame, and its placement
+    // drift would all compare an arbitrary instance. Each is withheld; the
+    // deriver's duplicate_tag fact carries the collision.
+    test('a duplicated tag gets no geometry element — no size/clip facts for it', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 360, bottom: 200 },
+            nodes: [
+                { id: 'card', bounds: { left: 0, top: 0, right: 360, bottom: 200 }, parentId: null, clipsChildren: false },
+                // 64×33 rendered vs 60×36 declared — would sizeFlag if compared.
+                { id: 'pill', bounds: { left: 10, top: 10, right: 74, bottom: 43 }, parentId: 'card', clipsChildren: false },
+                { id: 'pill', bounds: { left: 10, top: 60, right: 74, bottom: 93 }, parentId: 'card', clipsChildren: false },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { card: { w: 360, h: 200 }, pill: { w: 60, h: 36 } }, 1);
+        expect(block.facts).toContainEqual({ kind: 'duplicate_tag', tag: 'pill', instanceCount: 2 });
+        expect(block.geometry.elements.map((e) => e.id)).toEqual(['card']);
+        expect(block.summary.clean).toBe(false);
+    });
+    test('no overhang is computed against a duplicated frame — the pairing would be arbitrary', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 360, bottom: 400 },
+            nodes: [
+                { id: 'banner', bounds: { left: 0, top: 0, right: 343, bottom: 72 }, parentId: null, clipsChildren: false },
+                { id: 'banner', bounds: { left: 0, top: 100, right: 343, bottom: 172 }, parentId: null, clipsChildren: false },
+                // Child of the duplicated banner: vs the last-wins instance it would
+                // read a spurious 100dp top clip.
+                { id: 'coin', bounds: { left: 300, top: 40, right: 340, bottom: 90 }, parentId: 'banner', clipsChildren: false },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { banner: { x: 0, y: 0, w: 343, h: 72 }, coin: { x: 300, y: 40, w: 40, h: 50 } }, 1);
+        const coin = block.geometry.elements.find((e) => e.id === 'coin');
+        expect(coin).toBeDefined();
+        expect(coin.overhang).toBeUndefined();
+    });
+    test('placement facts skip a duplicated member tag (composition runs)', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 360, bottom: 640 },
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                { id: 'member', bounds: { left: 0, top: 0, right: 360, bottom: 100 }, parentId: 'root', clipsChildren: false },
+                { id: 'member', bounds: { left: 0, top: 200, right: 360, bottom: 300 }, parentId: 'root', clipsChildren: false },
+                // Genuinely misplaced: rendered y 500 vs design y 540.
+                { id: 'footer', bounds: { left: 0, top: 500, right: 360, bottom: 640 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { member: { x: 0, y: 0, w: 360, h: 100 }, footer: { x: 0, y: 540, w: 360, h: 140 } }, 1, undefined, undefined, { w: 360, h: 640 });
+        expect(block.placement.withheld).toBe(false);
+        expect(block.placement.facts.map((f) => f.elementId)).toEqual(['footer']);
+    });
+    test('the review scaffold rows the collision under the tag with the re-tag remediation', () => {
+        const scaffold = buildReviewScaffold({
+            facts: [{ kind: 'duplicate_tag', tag: 'copy_button', instanceCount: 3 }],
+        });
+        expect(scaffold.mustExplain).toEqual(['copy_button']);
+        expect(scaffold.rows).toHaveLength(1);
+        expect(scaffold.rows[0].element).toBe('copy_button');
+        expect(scaffold.rows[0].fact).toContain('3 nodes');
+        expect(scaffold.rows[0].fact).toContain('unique testTag');
+    });
+});
+describe('buildStructuralBlock — text-aware size tolerance (line-box residue)', () => {
+    // JVM (Robolectric) text metrics differ a few dp from Figma's nominal line
+    // boxes, so a text-driven element legitimately renders ±~2dp per laid-out
+    // line. The significance flag (sizeFlag) gets that band — min(8, 2 + 2·L)dp
+    // over the element's subtree line count — while the MEASUREMENT (deltas)
+    // stays exact and non-text elements keep the strict 1dp band (ADR-0004:
+    // strict, not loosen). Fixtures pin the July log cases.
+    const CANVAS_640 = { left: 0, top: 0, right: 360, bottom: 640 };
+    test('the 1-line pill (64×33 rendered vs 60×36 design) records the deltas but does not size-flag', () => {
+        const dump = {
+            canvas: CANVAS_640,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                { id: 'pill', bounds: { left: 16, top: 16, right: 80, bottom: 49 }, parentId: 'root', clipsChildren: false },
+                {
+                    id: 'pill_label',
+                    bounds: { left: 24, top: 24, right: 72, bottom: 41 },
+                    parentId: 'pill',
+                    clipsChildren: false,
+                    text: 'Copy code',
+                    textLines: [{ start: 0, end: 9, text: 'Copy code' }],
+                },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { pill: { w: 60, h: 36 } }, 1);
+        const pill = block.geometry.elements.find((e) => e.id === 'pill');
+        // Measurement integrity: the deltas are still recorded, exactly.
+        expect(pill.deltas).toEqual([
+            { dimension: 'w', delta: 4 },
+            { dimension: 'h', delta: -3 },
+        ]);
+        // Significance: within the 1-line text band (±4dp) — not a size divergence.
+        expect(pill.sizeFlag).toBe(false);
+        expect(block.summary.clean).toBe(true);
+    });
+    test('the 3-line card (65dp rendered vs 72 design) is within the line-scaled band', () => {
+        const dump = {
+            canvas: CANVAS_640,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                { id: 'card', bounds: { left: 16, top: 16, right: 359, bottom: 81 }, parentId: 'root', clipsChildren: false },
+                {
+                    id: 'title',
+                    bounds: { left: 24, top: 24, right: 351, bottom: 45 },
+                    parentId: 'card',
+                    clipsChildren: false,
+                    text: 'Fresh picks',
+                    textLines: [{ start: 0, end: 11, text: 'Fresh picks' }],
+                },
+                {
+                    id: 'subtitle',
+                    bounds: { left: 24, top: 49, right: 351, bottom: 73 },
+                    parentId: 'card',
+                    clipsChildren: false,
+                    text: 'Two lines of helper copy wrap here',
+                    textLines: [
+                        { start: 0, end: 17, text: 'Two lines of help' },
+                        { start: 18, end: 34, text: 'er copy wrap here' },
+                    ],
+                },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { card: { w: 343, h: 72 } }, 1);
+        const card = block.geometry.elements.find((e) => e.id === 'card');
+        expect(card.deltas).toEqual([{ dimension: 'h', delta: -7 }]);
+        // 3 laid-out lines in the subtree → band min(8, 2 + 2·3) = 8dp ≥ 7.
+        expect(card.sizeFlag).toBe(false);
+    });
+    test('a −2dp helper text node stays unflagged (its own line makes it text-driven)', () => {
+        const dump = {
+            canvas: CANVAS_640,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                {
+                    id: 'helper',
+                    bounds: { left: 16, top: 100, right: 136, bottom: 118 },
+                    parentId: 'root',
+                    clipsChildren: false,
+                    text: 'Terms apply',
+                    textLines: [{ start: 0, end: 11, text: 'Terms apply' }],
+                },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { helper: { w: 120, h: 20 } }, 1);
+        const helper = block.geometry.elements.find((e) => e.id === 'helper');
+        expect(helper.deltas).toEqual([{ dimension: 'h', delta: -2 }]);
+        expect(helper.sizeFlag).toBe(false);
+    });
+    test('the 328 vs 343dp button class still fails — 15dp is no line-box residue', () => {
+        const dump = {
+            canvas: CANVAS_640,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                { id: 'button', bounds: { left: 16, top: 500, right: 344, bottom: 548 }, parentId: 'root', clipsChildren: false },
+                {
+                    id: 'button_label',
+                    bounds: { left: 100, top: 514, right: 260, bottom: 534 },
+                    parentId: 'button',
+                    clipsChildren: false,
+                    text: 'Continue',
+                    textLines: [{ start: 0, end: 8, text: 'Continue' }],
+                },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { button: { w: 343, h: 48 } }, 1);
+        const button = block.geometry.elements.find((e) => e.id === 'button');
+        expect(button.sizeFlag).toBe(true);
+        expect(block.summary.clean).toBe(false);
+    });
+    test('the text band is capped at 8dp — a 10dp delta on a 5-line block still fails', () => {
+        const dump = {
+            canvas: CANVAS_640,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                {
+                    id: 'paragraph',
+                    bounds: { left: 16, top: 16, right: 344, bottom: 126 },
+                    parentId: 'root',
+                    clipsChildren: false,
+                    text: 'five lines of copy wrap',
+                    textLines: [
+                        { start: 0, end: 4, text: 'five' },
+                        { start: 5, end: 10, text: 'lines' },
+                        { start: 11, end: 13, text: 'of' },
+                        { start: 14, end: 18, text: 'copy' },
+                        { start: 19, end: 23, text: 'wrap' },
+                    ],
+                },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { paragraph: { w: 328, h: 120 } }, 1);
+        const paragraph = block.geometry.elements.find((e) => e.id === 'paragraph');
+        // min(8, 2 + 2·5) = 8dp < 10dp — the cap keeps large stacks honest.
+        expect(paragraph.sizeFlag).toBe(true);
+    });
+    test('a non-text element keeps the strict band — a 3dp delta still flags', () => {
+        const dump = {
+            canvas: CANVAS_640,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                { id: 'thumbnail', bounds: { left: 16, top: 16, right: 119, bottom: 116 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { thumbnail: { w: 100, h: 100 } }, 1);
+        const thumbnail = block.geometry.elements.find((e) => e.id === 'thumbnail');
+        expect(thumbnail.deltas).toEqual([{ dimension: 'w', delta: 3 }]);
+        expect(thumbnail.sizeFlag).toBe(true);
+    });
+    test('an old package (text but no textLines) still counts one line per text node', () => {
+        const dump = {
+            canvas: CANVAS_640,
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                { id: 'pill', bounds: { left: 16, top: 16, right: 80, bottom: 49 }, parentId: 'root', clipsChildren: false },
+                {
+                    id: 'pill_label',
+                    bounds: { left: 24, top: 24, right: 72, bottom: 41 },
+                    parentId: 'pill',
+                    clipsChildren: false,
+                    text: 'Copy code',
+                },
+            ],
+        };
+        const block = buildStructuralBlock(dump, { pill: { w: 60, h: 36 } }, 1);
+        expect(block.geometry.elements.find((e) => e.id === 'pill').sizeFlag).toBe(false);
+    });
+});
 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
@@ -1592,6 +2120,20 @@ describe('embedded geometry stage parity', () => {
         };
         expect(embedded.buildAppearanceReferenceFromParams(params)).toEqual(buildAppearanceReferenceFromParams(params));
     });
+    test('embedded buildAppearanceReferenceFromParams matches the module for a typeface declaration (typeface issue 04)', () => {
+        const cases = [
+            { refTypeface: { code: { family: 'Poppins', weight: 600 } }, baseline: 'figma' },
+            {
+                refGeom: { code: { w: 100, h: 20 } },
+                refTypeface: { code: { family: 'Poppins', weight: 600 }, label: { family: 'Fira Sans' } },
+                baseline: 'figma',
+            },
+            { refTypeface: {}, baseline: 'figma' },
+        ];
+        for (const params of cases) {
+            expect(embedded.buildAppearanceReferenceFromParams(params)).toEqual(buildAppearanceReferenceFromParams(params));
+        }
+    });
     test('embedded deriveLineFacts matches the module (Signal C, issue 18)', () => {
         const cases = [
             [
@@ -1634,6 +2176,56 @@ describe('embedded geometry stage parity', () => {
         };
         expect(embedded.buildStructuralBlock(dumpWithLines, null, 2, undefined, appearanceReference)).toEqual(buildStructuralBlock(dumpWithLines, null, 2, undefined, appearanceReference));
     });
+    test('embedded deriveTypefaceFacts matches the module (Signal C, issue 03)', () => {
+        const cases = [
+            [{ code: { family: 'Roboto', weight: 400 } }, { code: { family: 'Poppins', weight: 600 } }],
+            [{ code: { family: 'Poppins', weight: 600 } }, { code: { family: 'Poppins', weight: 600 } }],
+            [{ code: { family: 'Poppins', weight: 600 } }, { code: { family: 'Poppins-SemiBold' } }],
+            [{ code: { family: 'fira_sans_medium' } }, { code: { family: 'Fira Sans', weight: 500 } }],
+            [{ code: { family: 'Poppins', weight: 400 } }, { code: { family: 'Poppins-SemiBold' } }],
+            [{}, { code: { family: 'Poppins', weight: 600 } }],
+            [{ code: { family: 'Roboto', weight: 400 } }, {}],
+            [
+                { b: { family: 'Roboto', weight: 400 }, a: { family: 'Arial', weight: 400 } },
+                { a: { family: 'Poppins', weight: 600 }, b: { family: 'Roboto', weight: 400 } },
+            ],
+        ];
+        for (const [rendered, reference] of cases) {
+            expect(embedded.deriveTypefaceFacts(rendered, reference)).toEqual(deriveTypefaceFacts(rendered, reference));
+        }
+    });
+    test('embedded buildStructuralBlock matches the module with a typeface reference + the render-SDK gate (issue 03)', () => {
+        const dumps = [
+            {
+                canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+                renderSdk: 34,
+                nodes: [
+                    { id: 'code', bounds: { left: 0, top: 0, right: 100, bottom: 20 }, parentId: null, clipsChildren: false, text: 'INV-50', resolvedTypeface: { family: 'Roboto', weight: 400 } },
+                ],
+            },
+            {
+                canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+                renderSdk: 28,
+                nodes: [
+                    { id: 'code', bounds: { left: 0, top: 0, right: 100, bottom: 20 }, parentId: null, clipsChildren: false, text: 'INV-50' },
+                ],
+            },
+            {
+                canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+                nodes: [
+                    { id: 'code', bounds: { left: 0, top: 0, right: 100, bottom: 20 }, parentId: null, clipsChildren: false },
+                ],
+            },
+        ];
+        const appearanceReference = {
+            baseline: 'figma',
+            elementIds: ['code'],
+            typeface: { code: { family: 'Poppins', weight: 600 } },
+        };
+        for (const dump of dumps) {
+            expect(embedded.buildStructuralBlock(dump, null, 2, undefined, appearanceReference)).toEqual(buildStructuralBlock(dump, null, 2, undefined, appearanceReference));
+        }
+    });
     test('embedded deriveCopyFacts matches the module (Signal C)', () => {
         const cases = [
             [{ title: 'a' }, { title: 'a' }],
@@ -1732,6 +2324,40 @@ describe('embedded geometry stage parity', () => {
         };
         expect(embedded.buildStructuralBlock(dumpWithText, null, 2, undefined, appearanceReference)).toEqual(buildStructuralBlock(dumpWithText, null, 2, undefined, appearanceReference));
     });
+    // Duplicated banner tag + a child declared in the reference: exercises the
+    // collision guard end-to-end (duplicate_tag fact, geometry skip, overhang
+    // withheld against the duplicated frame, scaffold row).
+    const DUPLICATE_TAG_DUMP = {
+        canvas: { left: 0, top: 0, right: 720, bottom: 800 },
+        nodes: [
+            { id: 'banner', bounds: { left: 0, top: 0, right: 686, bottom: 144 }, parentId: null, clipsChildren: false },
+            { id: 'banner', bounds: { left: 0, top: 200, right: 686, bottom: 344 }, parentId: null, clipsChildren: false },
+            { id: 'coin', bounds: { left: 600, top: 80, right: 680, bottom: 180 }, parentId: 'banner', clipsChildren: false },
+        ],
+    };
+    const DUPLICATE_TAG_REF = {
+        banner: { x: 0, y: 0, w: 343, h: 72 },
+        coin: { x: 300, y: 40, w: 40, h: 50 },
+    };
+    // A text-driven pill inside the band (density 2: px are 2× the dp numbers)
+    // plus a non-text sibling outside it — exercises the text-aware size band.
+    const TEXT_BAND_DUMP = {
+        canvas: { left: 0, top: 0, right: 720, bottom: 400 },
+        nodes: [
+            { id: 'root', bounds: { left: 0, top: 0, right: 720, bottom: 400 }, parentId: null, clipsChildren: false },
+            { id: 'pill', bounds: { left: 32, top: 32, right: 160, bottom: 98 }, parentId: 'root', clipsChildren: false },
+            {
+                id: 'pill_label',
+                bounds: { left: 48, top: 48, right: 144, bottom: 82 },
+                parentId: 'pill',
+                clipsChildren: false,
+                text: 'Copy code',
+                textLines: [{ start: 0, end: 9, text: 'Copy code' }],
+            },
+            { id: 'thumbnail', bounds: { left: 200, top: 32, right: 406, bottom: 232 }, parentId: 'root', clipsChildren: false },
+        ],
+    };
+    const TEXT_BAND_REF = { pill: { w: 60, h: 36 }, thumbnail: { w: 100, h: 100 } };
     const parityCases = [
         { name: 'factsOnly', dump: HUB_PROMO_DUMP, ref: null },
         { name: 'withGeometry', dump: HUB_PROMO_DUMP, ref: HUB_PROMO_REFERENCE },
@@ -1739,6 +2365,8 @@ describe('embedded geometry stage parity', () => {
         { name: 'overhangGuest', dump: OVERHANG_GUEST_DUMP, ref: OVERHANG_GUEST_REF },
         { name: 'overhangPosition', dump: OVERHANG_POSITION_DUMP, ref: OVERHANG_POSITION_REF },
         { name: 'overhangMissing', dump: OVERHANG_MISSING_DUMP, ref: OVERHANG_MISSING_REF },
+        { name: 'duplicateTag', dump: DUPLICATE_TAG_DUMP, ref: DUPLICATE_TAG_REF },
+        { name: 'textSizeBand', dump: TEXT_BAND_DUMP, ref: TEXT_BAND_REF },
     ];
     for (const { name, dump, ref } of parityCases) {
         test(`embedded buildStructuralBlock matches the module (${name})`, () => {
@@ -1749,5 +2377,19 @@ describe('embedded geometry stage parity', () => {
             expect(embedded.buildReviewScaffold(block)).toEqual(buildReviewScaffold(block));
         });
     }
+    test('embedded buildStructuralBlock matches the module for a duplicated member tag under a declared frame', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 360, bottom: 640 },
+            nodes: [
+                { id: 'root', bounds: { left: 0, top: 0, right: 360, bottom: 640 }, parentId: null, clipsChildren: false },
+                { id: 'member', bounds: { left: 0, top: 0, right: 360, bottom: 100 }, parentId: 'root', clipsChildren: false },
+                { id: 'member', bounds: { left: 0, top: 200, right: 360, bottom: 300 }, parentId: 'root', clipsChildren: false },
+                { id: 'footer', bounds: { left: 0, top: 500, right: 360, bottom: 640 }, parentId: 'root', clipsChildren: false },
+            ],
+        };
+        const ref = { member: { x: 0, y: 0, w: 360, h: 100 }, footer: { x: 0, y: 540, w: 360, h: 140 } };
+        const frame = { w: 360, h: 640 };
+        expect(embedded.buildStructuralBlock(dump, ref, 1, undefined, undefined, frame)).toEqual(buildStructuralBlock(dump, ref, 1, undefined, undefined, frame));
+    });
 });
 //# sourceMappingURL=structural-facts.test.js.map