Files
hyperframes/packages/cli/src/utils/craftAudit.test.ts
T
Miguel Ángel c31e7dd08c fix(cli): check times a line held across a split clip as one hold (#7733)
* fix(cli): check times a line held across a split clip as one hold

A clip split in two hands its line to a second element at the same place.
line_unread timed each element alone, so the first half warned while the
same text stayed on screen.

* refactor(cli): name the split-clip line hand-off instead of commenting it
2026-11-14 13:45:08 +00:00

387 lines
15 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import { describe, expect, it } from "vitest";
import {
auditCraft,
detectDeadStretches,
detectFilmSilent,
detectFirstFrameEmpty,
detectLineUnread,
detectTextBelowFloor,
lineFloorSec,
readingWords,
typeFloorPx,
} from "./craftAudit.js";
import type { CraftFrame, CraftTextPart } from "./checkTypes.js";
const CANVAS = { width: 1920, height: 1080 };
const STEP = 0.125;
interface Shown {
key: number;
text: string;
from: number;
to: number;
fontPx?: number;
captions?: boolean;
/** Block key; defaults to the element's own key. */
block?: number;
/** The block's rendered text; defaults to `text`. */
blockText?: string;
/** Top edge in px; defaults to a row per key. */
top?: number;
}
function part(shown: Shown): CraftTextPart {
const fontPx = shown.fontPx ?? 96;
return {
key: shown.key,
block: shown.block ?? shown.key,
selector: `#t${shown.key}`,
blockSelector: `#t${shown.block ?? shown.key}`,
sourceFile: "compositions/scene.html",
text: shown.text,
blockText: shown.blockText ?? shown.text,
opacity: 1,
fontPx,
rect: { left: 100, top: shown.top ?? 100 + shown.key * 10, width: 800, height: fontPx * 1.2 },
captions: shown.captions ?? false,
};
}
/** A frame at `time` showing every element whose [from, to) window holds it. */
function frameAt(
time: number,
shown: Shown[],
extra: Partial<Omit<CraftFrame, "time" | "parts">> = {},
): CraftFrame {
return {
time,
parts: shown.filter((entry) => time >= entry.from && time < entry.to).map(part),
held: false,
painted: true,
signature: `moving-${time}`,
...extra,
};
}
function grid(duration: number, step = STEP): number[] {
const times: number[] = [];
for (let time = 0; time < duration - 1e-9; time += step)
times.push(Math.round(time * 1000) / 1000);
return times;
}
function film(duration: number, shown: Shown[]): CraftFrame[] {
return grid(duration).map((time) => frameAt(time, shown));
}
/** An exact probe: re-samples the same scene at any time, as a seek would. */
function probeFor(shown: Shown[]) {
return async (time: number) => frameAt(time, shown);
}
describe("readingWords", () => {
it("counts letter and number runs, and CJK by dictionary word", () => {
expect(readingWords("Every team gets one shared calendar now")).toBe(7);
expect(readingWords("42%")).toBe(1);
expect(readingWords("✓ — →")).toBe(0);
expect(readingWords("今天天气很好")).toBeGreaterThan(1);
});
it("counts Korean by its spaces and a number with its counter as one unit", () => {
expect(readingWords("실패 12회")).toBe(2);
expect(readingWords("오류 3건 발생")).toBe(3);
expect(readingWords("테스트 실패 12/40")).toBe(4);
expect(readingWords("커피12잔")).toBe(1);
});
it("still segments scripts written without spaces", () => {
expect(readingWords("ฉันรักภาษาไทยมาก")).toBeGreaterThan(1);
expect(readingWords("ខ្ញុំស្រលាញ់ភាសាខ្មែរ")).toBeGreaterThan(1);
expect(readingWords("ຂ້ອຍຮັກພາສາລາວຫຼາຍ")).toBeGreaterThan(1);
expect(readingWords("ကျွန်တော်မြန်မာစကားကိုချစ်တယ်")).toBeGreaterThan(1);
});
it("keeps counting a Japanese number and its counter as two", () => {
expect(readingWords("12回")).toBe(2);
expect(readingWords("実行12回失敗")).toBe(4);
});
it("counts a contraction as one word", () => {
expect(readingWords("a tooth can't get in")).toBe(5);
expect(readingWords("a tooth can’t get in")).toBe(5);
expect(readingWords("it's 'quoted'")).toBe(2);
});
});
describe("lineFloorSec", () => {
it("lets a 1–2 word line flash for 0.4 s and asks 3+ words for 3/4 of 0.5 s + 0.3 s a word", () => {
expect(lineFloorSec(1, false)).toBe(0.4);
expect(lineFloorSec(2, false)).toBe(0.4);
expect(lineFloorSec(3, false)).toBeCloseTo(1.05);
expect(lineFloorSec(6, false)).toBeCloseTo(1.725);
expect(lineFloorSec(1, true)).toBe(2);
expect(lineFloorSec(12, true)).toBeCloseTo(3.075);
});
});
describe("line_unread", () => {
it("warns on a 7-word line on screen 0.7 s, measured between grid samples", 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 findings = await detectLineUnread(film(20, shown), 20, CANVAS, probeFor(shown));
expect(findings).toHaveLength(1);
const [finding] = findings;
expect(finding).toMatchObject({ code: "line_unread", severity: "warning", words: 7 });
expect(finding?.seconds).toBeCloseTo(0.7, 1);
expect(finding?.floorSeconds).toBeCloseTo(1.95);
expect(finding?.message).toContain("0.5 s + 0.3 s a word");
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 },
{ key: 2, text: "Chapter", from: 3, to: 3.4 },
{ key: 3, text: "fast", from: 4, to: 4.3, captions: true },
{ key: 4, text: "caption words flash past", from: 4.3, to: 4.6, captions: true },
{ key: 5, text: "Try it today", from: 7.5, to: 10 },
];
expect(await detectLineUnread(film(10, shown), 10, CANVAS, probeFor(shown))).toEqual([]);
});
it("holds the film's last line to 2 s even when it is one word", async () => {
const shown: Shown[] = [
{ key: 1, text: "Ship it faster", from: 0, to: 5 },
{ key: 2, text: "HyperFrames", from: 9, to: 10 },
];
const findings = await detectLineUnread(film(10, shown), 10, CANVAS, probeFor(shown));
expect(findings.map((finding) => finding.selector)).toEqual(["#t2"]);
expect(findings[0]?.floorSeconds).toBe(2);
expect(findings[0]?.message).toContain("last line");
});
it("reads a headline split into inline word spans as one line", async () => {
const words = ["Every", "team", "gets", "one", "shared", "calendar", "now"];
const shown: Shown[] = words.map((text, index) => ({
key: 10 + index,
block: 1,
text,
blockText: words.join(" "),
from: 2,
to: 2.6,
}));
shown.push({ key: 2, text: "End card here", from: 5, to: 8 });
const findings = await detectLineUnread(film(8, shown), 8, CANVAS, probeFor(shown));
expect(findings).toHaveLength(1);
expect(findings[0]).toMatchObject({ selector: "#t1", words: 7 });
});
it("counts a line split into one span per glyph by its words, not its letters", async () => {
const line = "That camera move at 0:12 though";
const shown: Shown[] = Array.from(line.replaceAll(" ", ""), (text, index) => ({
key: 10 + index,
block: 1,
text,
blockText: line,
from: 0,
to: 5.5,
}));
shown.push({ key: 2, text: "End card here", from: 6, to: 12 });
expect(await detectLineUnread(film(12, shown), 12, CANVAS, probeFor(shown))).toEqual([]);
});
// fails without the fix: each instance of a split clip was timed alone, so its 0.5 s first half warned.
it("times a line held across a split clip's two instances as one hold", async () => {
const line = "Your reminder card holds here";
const shown: Shown[] = [
{ key: 1, text: line, from: 3, to: 3.5, top: 800 },
{ key: 2, text: line, from: 3.5, to: 8, top: 800 },
];
expect(await detectLineUnread(film(8, shown), 8, CANVAS, probeFor(shown))).toEqual([]);
});
it("still times a different line that takes over the same place on its own", async () => {
const shown: Shown[] = [
{ key: 1, text: "Every team gets one shared calendar now", from: 3, to: 3.5, top: 800 },
{ key: 2, text: "Start your free trial today", from: 3.5, to: 8, top: 800 },
];
const findings = await detectLineUnread(film(8, shown), 8, CANVAS, probeFor(shown));
expect(findings.map((finding) => finding.selector)).toEqual(["#t1"]);
});
it("skips text too small to be a reading line", async () => {
const shown: Shown[] = [
{ key: 1, text: "Legal fine print that flashes by", from: 1, to: 1.3, fontPx: 18 },
{ key: 2, text: "End card here", from: 4, to: 8 },
];
expect(await detectLineUnread(film(8, shown), 8, CANVAS, probeFor(shown))).toEqual([]);
});
});
describe("dead_stretch", () => {
const still = (from: number, to: number) => (time: number) =>
time >= from && time <= to ? "still" : `moving-${time}`;
function framesWith(
duration: number,
signature: (time: number) => string,
held: (time: number) => boolean = () => false,
) {
return grid(duration).map((time) =>
frameAt(time, [], { signature: signature(time), held: held(time) }),
);
}
it("warns on 5 s of nothing changing mid-film", () => {
const findings = detectDeadStretches(framesWith(20, still(7.5, 12.5)), 20);
expect(findings).toHaveLength(1);
expect(findings[0]).toMatchObject({ code: "dead_stretch", time: 7.5, until: 12.5 });
expect(findings[0]?.message).toContain("data-hold");
});
it("does not warn on a 1.5 s landed title or a 3 s still end card", () => {
const signature = (time: number) =>
(time >= 2 && time <= 3.5) || time >= 17 ? "still" : `moving-${time}`;
expect(detectDeadStretches(framesWith(20, signature), 20)).toEqual([]);
});
it("leaves the final 3 s out of a long still ending", () => {
expect(detectDeadStretches(framesWith(20, still(14, 20)), 20)).toEqual([]);
const findings = detectDeadStretches(framesWith(20, still(12.5, 20)), 20);
expect(findings).toHaveLength(1);
expect(findings[0]?.until).toBe(17);
});
it("does not count a stretch where a data-hold element is on screen", () => {
const held = (time: number) => time >= 7 && time < 13;
expect(detectDeadStretches(framesWith(20, still(7.5, 12.5), held), 20)).toEqual([]);
});
it("defers to sweep_static and keepsMoving when the pipeline says stillness is judged elsewhere", async () => {
const result = await auditCraft({
frames: framesWith(20, still(7.5, 12.5)),
duration: 20,
canvas: CANVAS,
soundSources: 1,
stillnessJudgedElsewhere: true,
});
expect(result.findings.map((finding) => finding.code)).not.toContain("dead_stretch");
});
});
describe("text_below_floor", () => {
it("puts the floor at 2.6% of the short side", () => {
expect(typeFloorPx(CANVAS)).toBe(28);
expect(typeFloorPx({ width: 1080, height: 1920 })).toBe(28);
expect(typeFloorPx({ width: 3840, height: 2160 })).toBe(56);
});
it("warns once per file on small text held 0.5 s or more", () => {
const shown: Shown[] = [
{ key: 1, text: "v2.4 release notes", from: 0.5, to: 6, fontPx: 18 },
{ key: 2, text: "Q1", from: 1, to: 6, fontPx: 14 },
];
const findings = detectTextBelowFloor(film(10, shown), 10, CANVAS);
expect(findings).toHaveLength(1);
expect(findings[0]).toMatchObject({ code: "text_below_floor", fontPx: 14, floorPx: 28 });
expect(findings[0]?.elements).toHaveLength(2);
expect(findings[0]?.message).toContain("references/look.md");
});
it("does not warn on 28 px text, a brief small flash, captions or symbols", () => {
const shown: Shown[] = [
{ key: 1, text: "Body copy at the floor", from: 0, to: 10, fontPx: 28 },
{ key: 2, text: "tiny flash", from: 2, to: 2.3, fontPx: 16 },
{ key: 3, text: "caption words", from: 0, to: 10, fontPx: 20, captions: true },
{ key: 4, text: "✓", from: 0, to: 10, fontPx: 8 },
];
expect(detectTextBelowFloor(film(10, shown), 10, CANVAS)).toEqual([]);
});
});
describe("first_frame_empty", () => {
it("warns when frame 0 paints nothing but the background", () => {
const findings = detectFirstFrameEmpty([
frameAt(0, [], { painted: false }),
frameAt(0.125, []),
]);
expect(findings).toHaveLength(1);
expect(findings[0]?.message).toContain("thumbnail");
expect(findings[0]?.message).toContain("references/review.md");
});
it("names the element covering frame 0, even when content is painted beneath it", () => {
const findings = detectFirstFrameEmpty([frameAt(0, [], { coveredBy: "#bg-rect" })]);
expect(findings).toHaveLength(1);
expect(findings[0]?.message).toContain("covered by #bg-rect");
});
it("does not warn when the title is already on screen at 0 s", () => {
expect(detectFirstFrameEmpty([frameAt(0, [], { painted: true })])).toEqual([]);
expect(detectFirstFrameEmpty([frameAt(0.5, [], { painted: false })])).toEqual([]);
});
});
describe("film_silent", () => {
it("warns on a film over 15 s with no sound source", () => {
const [finding] = detectFilmSilent(20, 0);
expect(finding?.code).toBe("film_silent");
expect(finding?.message).toContain("unless the person asked for silence");
expect(finding?.message).toContain("references/sound.md");
});
it("does not warn on a short film, a film with sound, or when sound was not inspected", () => {
expect(detectFilmSilent(12, 0)).toEqual([]);
expect(detectFilmSilent(20, 1)).toEqual([]);
expect(detectFilmSilent(20, null)).toEqual([]);
});
});
describe("auditCraft", () => {
it("reports nothing on a well-made film", async () => {
const shown: Shown[] = [
{ key: 1, text: "Ship faster with fewer meetings", from: 0, to: 5.8 },
{ key: 2, text: "42% fewer meetings", from: 6.3, to: 12.8 },
{ key: 3, text: "Try it today", from: 13.2, to: 20 },
];
const signature = (time: number) =>
(time >= 1 && time <= 2.5) || time >= 17 ? "still" : `moving-${time}`;
const frames = grid(20).map((time) => frameAt(time, shown, { signature: signature(time) }));
const result = await auditCraft(
{ frames, duration: 20, canvas: CANVAS, soundSources: 2, stillnessJudgedElsewhere: false },
probeFor(shown),
);
expect(result).toMatchObject({ enabled: true, step: STEP, samples: 160, findings: [] });
});
});