@invarn/cibuild 2.3.0 → 2.3.2

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, 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', () => {
@@ -688,6 +688,112 @@ describe('deriveSpanFacts — declared highlight extents vs rendered background
         ]);
     });
 });
+describe('deriveLineFacts — declared line split vs rendered laid-out lines', () => {
+    test('rendered lines matching the declared split produce no fact', () => {
+        expect(deriveLineFacts({
+            promoCopy: [
+                { start: 0, end: 28, text: 'Get 5 EUR off your first order' },
+                { start: 29, end: 50, text: 'placed by tomorrow.' },
+            ],
+        }, { promoCopy: ['Get 5 EUR off your first order', 'placed by tomorrow.'] })).toEqual([]);
+    });
+    test('a break on the wrong word yields line_break_mismatch with both splits', () => {
+        expect(deriveLineFacts({
+            promoCopy: [
+                { start: 0, end: 31, text: 'Get 5 EUR off your first order placed' },
+                { start: 32, end: 45, text: 'by tomorrow.' },
+            ],
+        }, { promoCopy: ['Get 5 EUR off your first order', 'placed by tomorrow.'] })).toEqual([
+            {
+                kind: 'line_break_mismatch',
+                elementId: 'promoCopy',
+                rendered: 'Get 5 EUR off your first order placed\nby tomorrow.',
+                reference: 'Get 5 EUR off your first order\nplaced by tomorrow.',
+            },
+        ]);
+    });
+    test('a dropped break (single rendered line vs a declared two-line split) is a fact', () => {
+        expect(deriveLineFacts({ promoCopy: [{ start: 0, end: 50, text: 'Get 5 EUR off your first order placed by tomorrow.' }] }, { promoCopy: ['Get 5 EUR off your first order', 'placed by tomorrow.'] })).toEqual([
+            {
+                kind: 'line_break_mismatch',
+                elementId: 'promoCopy',
+                rendered: 'Get 5 EUR off your first order placed by tomorrow.',
+                reference: 'Get 5 EUR off your first order\nplaced by tomorrow.',
+            },
+        ]);
+    });
+    test('a node that emitted no lines produces no fact (old packages degrade gracefully)', () => {
+        expect(deriveLineFacts({}, { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] })).toEqual([]);
+    });
+    test('no declared entry / an empty declared split produces no fact (absence of signal is not a divergence)', () => {
+        expect(deriveLineFacts({ promoCopy: [{ start: 0, end: 3, text: 'Get' }] }, {})).toEqual([]);
+        expect(deriveLineFacts({ promoCopy: [{ start: 0, end: 3, text: 'Get' }] }, { promoCopy: [] })).toEqual([]);
+        expect(deriveLineFacts({ promoCopy: [{ start: 0, end: 3, text: 'Get' }] }, { promoCopy: ['', ''] })).toEqual([]);
+    });
+    test('result is order-independent and deterministic (sorted by element id)', () => {
+        const rendered = {
+            b: [{ start: 0, end: 1, text: 'x' }],
+            a: [{ start: 0, end: 1, text: 'y' }],
+        };
+        const one = deriveLineFacts(rendered, { a: ['right'], b: ['x'] });
+        const two = deriveLineFacts(rendered, { b: ['x'], a: ['right'] });
+        expect(one).toEqual(two);
+        expect(one).toEqual([
+            { kind: 'line_break_mismatch', elementId: 'a', rendered: 'y', reference: 'right' },
+        ]);
+    });
+});
+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);
@@ -905,6 +1011,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) ----
 //
@@ -953,6 +1170,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'],
@@ -1190,9 +1448,65 @@ describe('buildAppearanceReferenceFromParams — union of geometry/text/color id
             spans: { discountText: { text: '5 EUR off', background: '#ffe45e' } },
         });
     });
+    test('lines only (no geometry/text/color/spans) → a reference carrying lines, ids from the line keys (issue 18)', () => {
+        const ref = buildAppearanceReferenceFromParams({
+            refLines: { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] },
+            baseline: 'figma',
+        });
+        expect(ref).toEqual({
+            baseline: 'figma',
+            elementIds: ['promoCopy'],
+            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: {} })).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 = {
@@ -1244,6 +1558,63 @@ describe('buildAppearanceReferenceFromParams — union of geometry/text/color id
         const block = buildStructuralBlock(dump, null, 2, undefined, ref);
         expect(block.appearance?.facts).toEqual([]);
     });
+    test('fed into buildStructuralBlock, a lines-only reference emits exactly one line_break_mismatch for a dropped break (issue 18)', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 686, bottom: 282 },
+            nodes: [
+                {
+                    id: 'promoCopy',
+                    bounds: { left: 0, top: 0, right: 600, bottom: 40 },
+                    parentId: null,
+                    clipsChildren: false,
+                    text: 'Get 5 EUR off placed by tomorrow.',
+                    textLines: [{ start: 0, end: 33, text: 'Get 5 EUR off placed by tomorrow.' }],
+                },
+                // Emitted no lines (old package) — the declared split stays silent.
+                { id: 'legacyText', bounds: { left: 0, top: 50, right: 600, bottom: 90 }, parentId: null, clipsChildren: false, text: 'Free delivery' },
+            ],
+        };
+        const ref = buildAppearanceReferenceFromParams({
+            refLines: {
+                promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'],
+                legacyText: ['Free', 'delivery'],
+            },
+            baseline: 'figma',
+        });
+        const block = buildStructuralBlock(dump, null, 2, undefined, ref);
+        expect(block.appearance?.facts).toEqual([
+            {
+                kind: 'line_break_mismatch',
+                elementId: 'promoCopy',
+                rendered: 'Get 5 EUR off placed by tomorrow.',
+                reference: 'Get 5 EUR off\nplaced by tomorrow.',
+            },
+        ]);
+    });
+    test('a matching line split yields a container with zero facts', () => {
+        const dump = {
+            canvas: { left: 0, top: 0, right: 686, bottom: 282 },
+            nodes: [
+                {
+                    id: 'promoCopy',
+                    bounds: { left: 0, top: 0, right: 600, bottom: 40 },
+                    parentId: null,
+                    clipsChildren: false,
+                    text: 'Get 5 EUR off\nplaced by tomorrow.',
+                    textLines: [
+                        { start: 0, end: 13, text: 'Get 5 EUR off' },
+                        { start: 14, end: 33, text: 'placed by tomorrow.' },
+                    ],
+                },
+            ],
+        };
+        const ref = buildAppearanceReferenceFromParams({
+            refLines: { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] },
+            baseline: 'figma',
+        });
+        const block = buildStructuralBlock(dump, null, 2, undefined, ref);
+        expect(block.appearance?.facts).toEqual([]);
+    });
     test('fed into buildStructuralBlock, a color-only reference still emits the color fact', () => {
         const dump = {
             canvas: { left: 0, top: 0, right: 686, bottom: 282 },
@@ -1469,6 +1840,112 @@ 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 = [
+            [
+                { promoCopy: [{ start: 0, end: 13, text: 'Get 5 EUR off' }, { start: 14, end: 33, text: 'placed by tomorrow.' }] },
+                { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] },
+            ],
+            [
+                { promoCopy: [{ start: 0, end: 33, text: 'Get 5 EUR off placed by tomorrow.' }] },
+                { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] },
+            ],
+            [{}, { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] }],
+            [{ promoCopy: [{ start: 0, end: 3, text: 'Get' }] }, { promoCopy: [] }],
+            [
+                { b: [{ start: 0, end: 1, text: 'x' }], a: [{ start: 0, end: 1, text: 'y' }] },
+                { a: ['right'], b: ['x'] },
+            ],
+        ];
+        for (const [rendered, reference] of cases) {
+            expect(embedded.deriveLineFacts(rendered, reference)).toEqual(deriveLineFacts(rendered, reference));
+        }
+    });
+    test('embedded buildStructuralBlock matches the module with an appearanceReference carrying lines (issue 18)', () => {
+        const dumpWithLines = {
+            canvas: { left: 0, top: 0, right: 200, bottom: 400 },
+            nodes: [
+                {
+                    id: 'promoCopy',
+                    bounds: { left: 0, top: 0, right: 100, bottom: 20 },
+                    parentId: null,
+                    clipsChildren: false,
+                    text: 'Get 5 EUR off placed by tomorrow.',
+                    textLines: [{ start: 0, end: 33, text: 'Get 5 EUR off placed by tomorrow.' }],
+                },
+            ],
+        };
+        const appearanceReference = {
+            baseline: 'figma',
+            elementIds: ['promoCopy'],
+            lines: { promoCopy: ['Get 5 EUR off', 'placed by tomorrow.'] },
+        };
+        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' }],

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;AAMpE,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,iDAAiD;AACjD,eAAO,MAAM,eAAe,6BAA8B,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AAElE,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;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAy8BD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAqBrF;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;CA0EpB"}
+{"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;AAMpE,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,iDAAiD;AACjD,eAAO,MAAM,eAAe,6BAA8B,CAAC;AAC3D,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAAwB,CAAC;AAE9D,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAC7D,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;GAGG;AACH,eAAO,MAAM,wBAAwB,EAAE,eAA0B,CAAC;AAElE,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;IACnB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAq+BD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,yBAAyB,GAAG,MAAM,CAqBrF;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;CA0EpB"}

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

@@ -123,6 +123,15 @@ var referenceColor = null;
 // extent per element id per screen, as { text, background }), set in main() and
 // read by the structural assembler. Null when none declared → no span facts.
 var referenceSpans = null;
+// params.reference_lines (Signal C line facts, issue 18: the declared line
+// split per element id per screen, as an array of line texts), set in main()
+// and read by the structural assembler. Null when none declared → no line facts.
+var referenceLines = null;
+// params.reference_typeface (Signal C typeface facts, typeface issue 04: the
+// DESIGN font per element id per screen, as { family, weight }, built by the
+// caller from Figma node metadata), set in main() and read by the structural
+// assembler. Null when none declared → no typeface facts.
+var referenceTypeface = null;
 // params.reference_baseline (Signal C: 'figma' (default) or 'previous_render').
 // Marks whether the appearance reference is the design (divergences) or the
 // previous catalog render (regressions/drift, the no-Figma path).
@@ -669,7 +678,7 @@ function renderScreens(renderable, projectRoot) {
         // 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, referenceText, referenceColor, referenceBaseline, referenceFrame, proofKind, referenceSpans);
+        assembleStructural(entry, layoutSource, referenceGeometry, CONFIG.scale, referenceText, referenceColor, referenceBaseline, referenceFrame, proofKind, referenceSpans, referenceLines, referenceTypeface);
       }
     });
   } finally {
@@ -760,6 +769,25 @@ function main() {
     !Array.isArray(params.reference_spans)
       ? params.reference_spans
       : null;
+  // Signal-C line reference (issue 18): { "<Screen>": { "<elementId>":
+  // ["line 1", "line 2"] } } — the exact line texts the design breaks that
+  // text element into. Absent → no line facts.
+  referenceLines =
+    params.reference_lines &&
+    typeof params.reference_lines === 'object' &&
+    !Array.isArray(params.reference_lines)
+      ? params.reference_lines
+      : null;
+  // Signal-C typeface reference (typeface issue 04): { "<Screen>":
+  // { "<elementId>": { family, weight } } } — the DESIGN font per element, from
+  // Figma node metadata. Diffed against the RESOLVED (painted) font the dump
+  // captured. Absent → no typeface facts.
+  referenceTypeface =
+    params.reference_typeface &&
+    typeof params.reference_typeface === 'object' &&
+    !Array.isArray(params.reference_typeface)
+      ? params.reference_typeface
+      : null;
   // Signal-C baseline marker: 'previous_render' when the appearance reference was
   // sourced from the previous catalog render (no-Figma drift path), else 'figma'.
   referenceBaseline =

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

@@ -50,7 +50,9 @@ const FAKE_GRADLEW_LINES = [
     // explicit golden-style dotted name via FAKE_ROBORAZZI_LAYOUT_NAME to prove
     // the consumer finds it by dot-segment match, decoupled from the PNG stem.
     '    lname="${FAKE_ROBORAZZI_LAYOUT_NAME:-$s.layout.json}"',
-    `    printf '%s' '{"canvas":{"left":0,"top":0,"right":200,"bottom":400},"nodes":[{"id":"card","bounds":{"left":20,"top":20,"right":180,"bottom":200},"parentId":null,"clipsChildren":true},{"id":"tag","bounds":{"left":60,"top":150,"right":140,"bottom":224},"parentId":"card","clipsChildren":false}]}' > "$out/$lname"`,
+    // The tag node carries the resolved-typeface enrichment (a Roboto fallback)
+    // so a run with reference_typeface can prove the params → fact plumbing.
+    `    printf '%s' '{"renderSdk":34,"canvas":{"left":0,"top":0,"right":200,"bottom":400},"nodes":[{"id":"card","bounds":{"left":20,"top":20,"right":180,"bottom":200},"parentId":null,"clipsChildren":true},{"id":"tag","bounds":{"left":60,"top":150,"right":140,"bottom":224},"parentId":"card","clipsChildren":false,"text":"TAG","resolvedTypeface":{"family":"Roboto-Regular","weight":400}}]}' > "$out/$lname"`,
     '  fi',
     'done',
     'exit 0',
@@ -440,6 +442,52 @@ describe('android render runtime — render + trim (happy path)', () => {
         expect(tag?.sizeFlag).toBe(false);
         expect(tag?.deltas).toEqual([]);
     });
+    test('derives a flagged typeface fact when reference_typeface is given and the resolved font diverges (typeface issue 04)', async () => {
+        // The fake dump resolved Roboto-Regular 400 on `tag`; the design declares
+        // Poppins 600 → exactly one typeface fact on the run result. A matching
+        // declaration on a second run produces none.
+        const project = makeProject({
+            screens: { XProof: 'x.png' },
+            reference_typeface: { XProof: { tag: { family: 'Poppins', weight: 600 } } },
+        });
+        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');
+        const typefaceFacts = (screen?.structural?.appearance?.facts ?? []).filter((f) => f.kind === 'typeface');
+        expect(typefaceFacts).toEqual([
+            {
+                kind: 'typeface',
+                elementId: 'tag',
+                channel: 'text',
+                rendered: { family: 'Roboto-Regular', weight: 400 },
+                reference: { family: 'Poppins', weight: 600 },
+            },
+        ]);
+        // The resolved font is persisted as the next drift baseline.
+        expect(screen?.structural?.appearance?.rendered?.typeface).toEqual({
+            tag: { family: 'Roboto-Regular', weight: 400 },
+        });
+        // Matching declaration → no typeface fact (and no advisory).
+        const clean = makeProject({
+            screens: { XProof: 'x.png' },
+            reference_typeface: { XProof: { tag: { family: 'Roboto-Regular', weight: 400 } } },
+        });
+        writeReference(clean, 'x.png');
+        stageArchive(clean, gradleProjectEntries());
+        const cleanRun = runScript(clean, await buildScript(), {
+            FAKE_ROBORAZZI_SCREENS: 'XProof',
+            FAKE_ROBORAZZI_LAYOUT: '1',
+        });
+        expect(cleanRun.status).toBe(0);
+        const cleanScreen = readResult(clean).screens.find((s) => s.screen === 'XProof');
+        expect((cleanScreen?.structural?.appearance?.facts ?? []).filter((f) => f.kind === 'typeface')).toEqual([]);
+        expect(cleanScreen?.structural?.appearance?.advisories).toBeUndefined();
+    });
     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');