From a81b34410868208035095fe454a09403bf4aaaba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Fri, 6 Nov 2026 04:09:52 +0000 Subject: [PATCH] feat(cli): a line_unread finding carries the frames it measured around where the line was first read (#7294) * feat(cli): a line_unread finding carries the frames it measured around where the line was first read * style(cli): shorten the measured field's comment * feat(cli): measured frames at both ends of the line, with fewer comment lines --- packages/cli/src/utils/checkTypes.ts | 1 + packages/cli/src/utils/craftAudit.test.ts | 28 +++++++++++++ packages/cli/src/utils/craftAudit.ts | 49 ++++++++++++++++++++++- 3 files changed, 76 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/utils/checkTypes.ts b/packages/cli/src/utils/checkTypes.ts index d2ca6bd3b8..17cf1b4ddb 100644 --- a/packages/cli/src/utils/checkTypes.ts +++ b/packages/cli/src/utils/checkTypes.ts @@ -350,6 +350,7 @@ export interface CraftFinding extends CheckFinding { fontPx?: number; floorPx?: number; until?: number; + measured?: { time: number; opacity: number | null; heightPx: number | null }[]; elements?: { selector: string; text: string; fontPx: number; time: number; seconds: number }[]; } diff --git a/packages/cli/src/utils/craftAudit.test.ts b/packages/cli/src/utils/craftAudit.test.ts index 41341b97cc..1b4af12f93 100644 --- a/packages/cli/src/utils/craftAudit.test.ts +++ b/packages/cli/src/utils/craftAudit.test.ts @@ -119,6 +119,34 @@ describe("line_unread", () => { expect(finding?.message).toContain("references/motion.md"); }); + // fails without the fix: a finding carried no measured frames, so a report of a line read late could not show why. + it("carries the frames it measured at both ends of the line, with none painted before or after it", async () => { + const shown: Shown[] = [ + { key: 1, text: "Every team gets one shared calendar now", from: 6.2, to: 6.9 }, + { key: 2, text: "Try it today", from: 13, to: 20 }, + ]; + const [finding] = await detectLineUnread(film(20, shown), 20, CANVAS, probeFor(shown)); + const measured = finding?.measured ?? []; + expect(measured.map((frame) => frame.opacity)).toEqual([ + null, + null, + null, + 1, + 1, + 1, + 1, + 1, + 1, + null, + null, + null, + ]); + expect(measured[3]).toMatchObject({ time: 6.25, heightPx: 115 }); + expect(measured.map((frame) => frame.time)).toEqual([ + 5.875, 6, 6.125, 6.25, 6.375, 6.5, 6.625, 6.75, 6.875, 7, 7.125, 7.25, + ]); + }); + it("does not warn on a landed title held 1.5 s, a 0.4 s chapter word, captions or a 2.5 s end card", async () => { const shown: Shown[] = [ { key: 1, text: "Ship it faster", from: 0.5, to: 2 }, diff --git a/packages/cli/src/utils/craftAudit.ts b/packages/cli/src/utils/craftAudit.ts index cc06b8f66f..242cd867bb 100644 --- a/packages/cli/src/utils/craftAudit.ts +++ b/packages/cli/src/utils/craftAudit.ts @@ -301,6 +301,7 @@ interface LineCandidate { floor: number; window: LineWindow; firstIndex: number; + lastIndex: number; } /** A run that reaches the last sample lasts to the film's end; one at sample 0 starts exactly there. */ @@ -348,7 +349,16 @@ function lineCandidates(frames: CraftFrame[], duration: number, canvas: Canvas): const floor = lineFloorSec(words, finalLine); // Clearly long enough even at the shortest the grid allows. if (window.endIn - window.startIn >= floor) continue; - candidates.push({ track, words, text, finalLine, floor, window, firstIndex: run[0] }); + candidates.push({ + track, + words, + text, + finalLine, + floor, + window, + firstIndex: run[0], + lastIndex: run[1], + }); } return candidates; } @@ -393,7 +403,7 @@ export async function detectLineUnread( const held = windowSeconds(window); if (held >= candidate.floor - T.measureToleranceSec) continue; const error = Math.max(window.startIn - window.startOut, window.endOut - window.endIn) / 2; - findings.push(lineUnreadFinding(candidate, window, held, error)); + findings.push(lineUnreadFinding(candidate, window, held, error, frames)); } return findings; } @@ -403,6 +413,7 @@ function lineUnreadFinding( window: LineWindow, held: number, error: number, + frames: CraftFrame[], ): CraftFinding { const { track, words, text, finalLine, floor } = candidate; const quoted = quote(text, 60); @@ -429,9 +440,43 @@ function lineUnreadFinding( words, seconds: round(held), floorSeconds: round(floor), + measured: measuredAround(frames, track.key, candidate.firstIndex, candidate.lastIndex), }; } +const MEASURED_SPAN = 3; + +/** The samples at both ends of the line's run, as the sampler measured them. */ +function measuredAround( + frames: CraftFrame[], + key: number, + first: number, + last: number, +): NonNullable { + const indices = new Set(); + for (const edge of [first, last]) { + for (let at = edge - MEASURED_SPAN; at <= edge + MEASURED_SPAN; at += 1) indices.add(at); + } + const out: NonNullable = []; + for (const index of [...indices].sort((a, b) => a - b)) { + const frame = frames[index]; + if (!frame) continue; + const parts = frame.parts.filter((part) => part.block === key && !part.captions); + if (parts.length === 0) { + out.push({ time: round(frame.time), opacity: null, heightPx: null }); + continue; + } + const top = Math.min(...parts.map((part) => part.rect.top)); + const bottom = Math.max(...parts.map((part) => part.rect.top + part.rect.height)); + out.push({ + time: round(frame.time), + opacity: round(Math.max(...parts.map((part) => part.opacity))), + heightPx: Math.round(bottom - top), + }); + } + return out; +} + // ---------- text_below_floor ---------- interface SmallText {