Skip to content

Art and animation, written as code. Illustrations, loops, interactive web art, launch-videos and scored films in dozens of styles, identical on every render.

framecheck: reading time for declared text cues, 9:16 phone safe zones

Alex Greenshpunb406d7392e99
diff --git a/plugins/anidoodle/skills/anidoodle/engine/src/hosts/page.ts b/plugins/anidoodle/skills/anidoodle/engine/src/hosts/page.ts
index eafcbcb..a1853e4 100644
--- a/plugins/anidoodle/skills/anidoodle/engine/src/hosts/page.ts
+++ b/plugins/anidoodle/skills/anidoodle/engine/src/hosts/page.ts
@@ -129,9 +129,11 @@ export const mountFilm = (film: Film) => {
// THE FRAME PROBE (tools/framecheck.mjs). For each frame asked, every line of text (fillText on the
// frame or a full-frame sheet, writeOn, setType) and every content box the art core reports
// (probeRect: a card, a window) is collected in device pixels; a box the frame's edge cuts through
- // is returned. Whatever lies wholly outside the frame, or wholly inside it, is fine.
- const probe = (frames: number[]) => {
- const out: (ProbeRec & { frame: number })[] = [], g = globalThis as { __ANIDOODLE_PROBE__?: (r: ProbeRec) => void };
+ // is returned. Whatever lies wholly outside the frame, or wholly inside it, is fine. With `all`, every
+ // visible line of text is returned too (cut: false when whole), for the checks that judge where
+ // text sits (the 9:16 safe zones, textrules.mjs).
+ const probe = (frames: number[], all = false) => {
+ const out: (ProbeRec & { frame: number; cut?: boolean })[] = [], g = globalThis as { __ANIDOODLE_PROBE__?: (r: ProbeRec) => void };
const protos = [CanvasRenderingContext2D.prototype, ...(typeof OffscreenCanvasRenderingContext2D !== "undefined" ? [OffscreenCanvasRenderingContext2D.prototype] : [])] as unknown as { fillText: (t: string, x: number, y: number, w?: number) => void }[];
const orig = protos.map((p) => p.fillText);
let frame = 0, recs: ProbeRec[] = [];
@@ -147,7 +149,7 @@ export const mountFilm = (film: Film) => {
try {
for (frame of frames) {
recs = []; seek(frame); const W = canvas.width, H = canvas.height, tol = 1.5;
- for (const r of recs) { const inter = r.x1 > 0 && r.x0 < W && r.y1 > 0 && r.y0 < H, inside = r.x0 >= -tol && r.y0 >= -tol && r.x1 <= W + tol && r.y1 <= H + tol; if (inter && !inside) out.push({ ...r, frame }); }
+ for (const r of recs) { const inter = r.x1 > 0 && r.x0 < W && r.y1 > 0 && r.y0 < H, inside = r.x0 >= -tol && r.y0 >= -tol && r.x1 <= W + tol && r.y1 <= H + tol; if (inter && !inside) out.push({ ...r, frame }); else if (all && inter && r.kind === "text") out.push({ ...r, frame, cut: false }); }
}
} finally { protos.forEach((p, i) => (p.fillText = orig[i] as never)); delete g.__ANIDOODLE_PROBE__; }
return out;
diff --git a/plugins/anidoodle/skills/anidoodle/engine/test/textrules.test.ts b/plugins/anidoodle/skills/anidoodle/engine/test/textrules.test.ts
new file mode 100644
index 0000000..0e30534
--- /dev/null
+++ b/plugins/anidoodle/skills/anidoodle/engine/test/textrules.test.ts
@@ -0,0 +1,40 @@
+// TEXT RULES TESTS. The reading-time rule and the 9:16 phone safe zones, held to known answers,
+// including the failing cases: a cue that is too short, text under the platforms' buttons.
+// @ts-ignore: a plain ES module shared with the tools
+import { SAFE_ZONES, isPortrait916, readingNeed, readingTime, safeZoneHits, zoneRects } from "../tools/textrules.mjs";
+
+export const name = "textrules";
+export const run = (ok: (cond: boolean, label: string) => void) => {
+ // ---- reading time: max(0.7 s, 0.3 s per word)
+ ok(readingNeed("Hi") === 0.7 && readingNeed("one two") === 0.7, "one or two words need the 0.7 s floor");
+ ok(Math.abs(readingNeed("one two three four five six") - 1.8) < 1e-9, "six words need 1.8 s (0.3 s each)");
+ const fps = 30, cue = (text: string, s: number) => ({ from: 100, to: 100 + Math.round(s * fps), text });
+ ok(readingTime([cue("IDEA IN.", 0.7), cue("one two three four five six", 1.8)], fps).status === "PASS", "cues exactly at their reading time pass");
+ const short = readingTime([cue("IDEA IN.", 0.7), cue("one two three four five six", 1.5)], fps);
+ ok(short.status === "FAIL" && short.bad.length === 1 && short.bad[0].need === 1.8 && short.bad[0].seconds === 1.5, `NEGATIVE: a 6-word cue up for 1.5 s fails (${JSON.stringify(short.bad[0])})`);
+ ok(readingTime([cue("Yes", 0.6)], fps).status === "FAIL", "NEGATIVE: one word up for 0.6 s fails the 0.7 s floor");
+ ok(readingTime([{ from: 0, to: 20, text: "Yes" }], 30).status === "FAIL" && readingTime([{ from: 0, to: 21, text: "Yes" }], 30).status === "PASS", "the floor is 21 frames at 30 fps, 20 fails");
+ ok(readingTime([], fps).status === "N/A" && readingTime(undefined, fps).status === "N/A", "no declared cues is N/A, never a pass");
+ ok(readingTime([{ from: 0, to: 5, text: " " }], fps).status === "N/A", "a blank cue is not text: N/A");
+ ok(readingTime([cue("IDEA IN.", 0.7)], fps).status !== "N/A", "declared text is judged");
+
+ // ---- the 9:16 frame and its zones
+ ok(isPortrait916(1080, 1920) && isPortrait916(720, 1280) && !isPortrait916(1920, 1080) && !isPortrait916(1080, 1350) && !isPortrait916(1080, 1080), "9:16 is detected by shape, not by name");
+ const z = zoneRects(1080, 1920);
+ ok(z.length === 3 && z[0].y1 === 1920 * SAFE_ZONES.top && z[1].y0 === 1920 * (1 - SAFE_ZONES.bottom) && z[2].x0 === 1080 * (1 - SAFE_ZONES.right), "three zones: top band, bottom band, right button column");
+ ok(SAFE_ZONES.top >= 0.12 && SAFE_ZONES.bottom >= 0.2 && SAFE_ZONES.right >= 0.1, "the shares are the conservative ones, not the minimum");
+ const text = (label: string, x0: number, y0: number, x1: number, y1: number, frame = 0) => ({ kind: "text", label, x0, y0, x1, y1, frame });
+ const inside = text("whole", 200, 600, 800, 700), W = 1080, H = 1920;
+ ok(safeZoneHits([inside], W, H).status === "PASS", "text in the middle of the frame passes");
+ const top = safeZoneHits([text("TITLE", 100, 40, 900, 120)], W, H);
+ ok(top.status === "FAIL" && top.hits[0].zone === "top band", "NEGATIVE: text in the top band fails");
+ const bottom = safeZoneHits([text("npm i x", 100, 1600, 900, 1700)], W, H);
+ ok(bottom.status === "FAIL" && bottom.hits[0].zone === "bottom band", "NEGATIVE: text in the bottom band fails");
+ const right = safeZoneHits([text("CLAIM", 700, 800, 1060, 900)], W, H);
+ ok(right.status === "FAIL" && right.hits[0].zone === "right button column", "NEGATIVE: text running into the right button column fails");
+ ok(safeZoneHits([text("edge", 100, 270, 900, 280)], W, H).status === "PASS", "text that only touches a zone's border passes");
+ const many = safeZoneHits([text("TITLE", 100, 40, 900, 120, 0), text("TITLE", 100, 40, 900, 120, 5), text("TITLE", 100, 40, 900, 120, 9)], W, H);
+ ok(many.hits.length === 1 && many.hits[0].frames.join() === "0,5,9", "one row per text and zone, with every frame it was seen on");
+ ok(safeZoneHits([{ kind: "box", label: "card", x0: 0, y0: 0, x1: 1080, y1: 1920, frame: 0 }], W, H).status === "PASS", "content boxes are not judged here, only text");
+ ok(safeZoneHits([text("TITLE", 100, 40, 900, 120)], 1920, 1080).status === "N/A", "a 16:9 frame is N/A, never judged against phone zones");
+};
diff --git a/plugins/anidoodle/skills/anidoodle/engine/tools/adapters/playwright.mjs b/plugins/anidoodle/skills/anidoodle/engine/tools/adapters/playwright.mjs
index 07b47dd..a0ea434 100644
--- a/plugins/anidoodle/skills/anidoodle/engine/tools/adapters/playwright.mjs
+++ b/plugins/anidoodle/skills/anidoodle/engine/tools/adapters/playwright.mjs
@@ -34,7 +34,7 @@ export const open = async ({ pw, browser: found }, pagePath, { scale = 1, worker
blurHash: (n, samples, w = 0) => pick(w).evaluate(([f, s]) => { window.FILM.blur(f, s); return window.FILM.hash(); }, [n, samples]),
audio: (sr) => pages[0].evaluate((s) => window.FILM.audio(s), sr),
// the frame probe (hosts/page.ts): text and content boxes the frame's edge cuts through
- probe: (frames) => pages[0].evaluate((fs) => window.FILM.probe(fs), frames),
+ probe: (frames, all = false) => pages[0].evaluate(([fs, a]) => window.FILM.probe(fs, a), [frames, all]),
// keeps the fresh bakes, then closes; returns how many plate frames were stored
close: async () => { let saved = 0; if (useBakes) for (const p of pages) saved += await saveBakes(p, bv).catch(() => 0); await browser.close(); return saved; },
};
diff --git a/plugins/anidoodle/skills/anidoodle/engine/tools/framecheck.mjs b/plugins/anidoodle/skills/anidoodle/engine/tools/framecheck.mjs
index 99620ca..09d963c 100644
--- a/plugins/anidoodle/skills/anidoodle/engine/tools/framecheck.mjs
+++ b/plugins/anidoodle/skills/anidoodle/engine/tools/framecheck.mjs
@@ -1,28 +1,50 @@
-// FRAMECHECK. A design fault the determinism gate cannot see: type or content cut by the frame's
-// edge. Every line of text (fillText, writeOn, setType) and every content box the art reports
-// (probeRect: an answer card, a product window, a film's card) must lie wholly inside the frame or
-// wholly outside it, on every frame checked. A deliberate full-bleed is not reported as a box.
-// node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T]
+// FRAMECHECK. Design faults the determinism gate cannot see, found on the frames themselves.
+// 1. Cut by the edge. Every line of text (fillText, writeOn, setType) and every content box the art
+// reports (probeRect: an answer card, a product window, a film's card) must lie wholly inside the
+// frame or wholly outside it, on every frame checked. A deliberate full-bleed is not reported as a box.
+// 2. Reading time. Each declared text cue (meta.captions) stays up for max(0.7 s, 0.3 s per word).
+// A film that declares no cues reports N/A, never a pass.
+// 3. Phone safe zones, 9:16 frames only. No text inside the top band, the bottom band or the right
+// button column the platforms cover with their own interface. Other shapes report N/A.
+// The rules and their numbers are textrules.mjs.
+// node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T] [--zones fail|warn]
+// --zones warn lists safe-zone text as FLAG and does not fail the run (launch.mjs ship uses it, because
+// the launch template's phone layouts are a chat window across the whole frame; --strict-zones there
+// makes it fail). Reading time and the edge cut always fail.
import { resolve } from "node:path";
import { buildPage } from "./build-page.mjs";
import { detect } from "./detect.mjs";
import * as playwright from "./adapters/playwright.mjs";
import { requireFilm } from "./names.mjs";
+import { isMain } from "./is-main.mjs";
+import { SAFE_ZONES, isPortrait916, readingTime, safeZoneHits } from "./textrules.mjs";
-const pos = [], opt = {};
-for (let i = 2; i < process.argv.length; i++) { const a = process.argv[i]; if (a.startsWith("--")) opt[a.slice(2)] = process.argv[++i]; else pos.push(a); }
-const film = requireFilm(pos[0], "framecheck", "node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T]");
+const USAGE = "node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T] [--zones fail|warn]";
export const frameCheck = async (film, { every = 1, from = 0, to } = {}) => {
const page = await buildPage({ entry: `src/hosts/page-${film}.ts`, out: resolve(`dist/${film}.html`), title: film });
- const s = await playwright.open(detect(), page.out, { workers: 1 }), meta = await s.info(), N = to ?? meta.durationFrames;
+ const s = await playwright.open(detect(), page.out, { workers: 1 }), meta = await s.info(), N = to ?? meta.durationFrames, portrait = isPortrait916(meta.W, meta.H);
const frames = []; for (let f = from; f < N; f += every) frames.push(f);
- const bad = []; for (let i = 0; i < frames.length; i += 40) bad.push(...(await s.probe(frames.slice(i, i + 40))));
+ const recs = []; for (let i = 0; i < frames.length; i += 40) recs.push(...(await s.probe(frames.slice(i, i + 40), portrait)));
await s.close();
- return { meta, frames: frames.length, bad };
+ return { meta, frames: frames.length, bad: recs.filter((r) => r.cut !== false), reading: readingTime(meta.captions, meta.fps), zones: safeZoneHits(recs, meta.W, meta.H) };
};
-const r = await frameCheck(film, { every: Number(opt.every ?? 1), from: Number(opt.from ?? 0), to: opt.to === undefined ? undefined : Number(opt.to) });
-const groups = new Map(); for (const b of r.bad) { const k = `${b.kind} "${b.label.slice(0, 48)}"`; const g = groups.get(k) ?? []; g.push(b.frame); groups.set(k, g); }
-console.log(`FRAMECHECK ${film} ${r.meta.W}x${r.meta.H}, ${r.frames} frames`);
-for (const [k, fs] of groups) { const b = r.bad.find((x) => `${x.kind} "${x.label.slice(0, 48)}"` === k); console.log(` FAIL ${k} cut by the frame's edge on ${fs.length} frame(s): ${fs.slice(0, 8).join(", ")}${fs.length > 8 ? " ..." : ""} box ${[b.x0, b.y0, b.x1, b.y1].map((v) => Math.round(v)).join(",")}`); }
-console.log(r.bad.length ? `FRAMECHECK: FAIL ${groups.size} item(s) cut by the frame's edge` : `FRAMECHECK: PASS no text or content box cut by the frame's edge`);
-process.exit(r.bad.length ? 1 : 0);
+if (isMain(import.meta.url)) {
+ const pos = [], opt = {};
+ for (let i = 2; i < process.argv.length; i++) { const a = process.argv[i]; if (a.startsWith("--")) opt[a.slice(2)] = process.argv[++i]; else pos.push(a); }
+ const film = requireFilm(pos[0], "framecheck", USAGE), warnZones = opt.zones === "warn";
+ if (opt.zones !== undefined && !["fail", "warn"].includes(opt.zones)) { console.error(`framecheck: --zones is fail or warn, got '${opt.zones}'\nusage: ${USAGE}`); process.exit(2); }
+ const r = await frameCheck(film, { every: Number(opt.every ?? 1), from: Number(opt.from ?? 0), to: opt.to === undefined ? undefined : Number(opt.to) });
+ const list = (fs) => `${fs.slice(0, 8).join(", ")}${fs.length > 8 ? " ..." : ""}`;
+ const groups = new Map(); for (const b of r.bad) { const k = `${b.kind} "${b.label.slice(0, 48)}"`; const g = groups.get(k) ?? []; g.push(b.frame); groups.set(k, g); }
+ console.log(`FRAMECHECK ${film} ${r.meta.W}x${r.meta.H}, ${r.frames} frames`);
+ for (const [k, fs] of groups) { const b = r.bad.find((x) => `${x.kind} "${x.label.slice(0, 48)}"` === k); console.log(` FAIL ${k} cut by the frame's edge on ${fs.length} frame(s): ${list(fs)} box ${[b.x0, b.y0, b.x1, b.y1].map((v) => Math.round(v)).join(",")}`); }
+ const rd = r.reading, zn = r.zones;
+ for (const b of rd.bad) console.log(` FAIL text "${b.text.slice(0, 48)}" is up ${b.seconds} s from frame ${b.from}; reading it takes ${b.need} s`);
+ for (const h of zn.hits ?? []) console.log(` ${warnZones ? "FLAG" : "FAIL"} text "${h.label.slice(0, 48)}" sits in the ${h.zone} on ${h.frames.length} frame(s): ${list(h.frames)}`);
+ const zp = (x) => Math.round(x * 100);
+ console.log(` READING-TIME: ${rd.status}${rd.status === "N/A" ? ` ${rd.reason}` : ` ${rd.checked} cue(s), each at least max(0.7 s, 0.3 s per word)`}`);
+ console.log(` SAFE-ZONES: ${zn.status === "FAIL" && warnZones ? "FLAG" : zn.status}${zn.status === "N/A" ? ` ${zn.reason}` : ` ${zn.hits.length ? `${zn.hits.length} text(s) inside` : "no text in"} the top ${zp(SAFE_ZONES.top)}%, bottom ${zp(SAFE_ZONES.bottom)}% or right ${zp(SAFE_ZONES.right)}% of the frame`}`);
+ const nz = zn.hits?.length ?? 0, fails = groups.size + rd.bad.length + (warnZones ? 0 : nz);
+ console.log(fails ? `FRAMECHECK: FAIL ${fails} problem(s): ${groups.size} cut by the frame's edge, ${rd.bad.length} read too briefly, ${warnZones ? 0 : nz} in a phone safe zone` : `FRAMECHECK: PASS no text or content box cut by the frame's edge; reading time ${rd.status}; safe zones ${nz ? `FLAGGED (${nz} text(s))` : zn.status}`);
+ process.exit(fails ? 1 : 0);
+}
diff --git a/plugins/anidoodle/skills/anidoodle/engine/tools/textrules.mjs b/plugins/anidoodle/skills/anidoodle/engine/tools/textrules.mjs
new file mode 100644
index 0000000..19d8967
--- /dev/null
+++ b/plugins/anidoodle/skills/anidoodle/engine/tools/textrules.mjs
@@ -0,0 +1,58 @@
+// TEXT RULES. Two rules about words on screen, as pure functions (no browser, no ffmpeg) so they are
+// unit-tested and framecheck.mjs only has to feed them.
+// 1. Reading time. A text cue stays up for at least max(0.7 s, 0.3 s per word). Judged on the cues a
+// film declares (meta.captions: { from, to, text } in frames). A film that declares none is N/A,
+// never a pass: the tool cannot see words it was not told about.
+// 2. Phone safe zones. On a 9:16 frame the platforms lay their own buttons, names and captions over
+// the top band, the bottom band and a right-hand column of buttons. Text under them is lost.
+// The shares below are conservative: the most cautious end of the creator safe-area guidance the
+// big short-video apps publish for vertical video, rounded up. Their layouts change, so treat the
+// numbers as a floor to re-check, not as a spec.
+export const MIN_READ_S = 0.7, READ_S_PER_WORD = 0.3;
+export const SAFE_ZONES = { top: 0.14, bottom: 0.25, right: 0.14 }; // shares of the frame: top and bottom of its height, right of its width
+
+export const wordCount = (text) => String(text ?? "").trim().split(/\s+/).filter(Boolean).length;
+/** Seconds a text needs on screen to be read. */
+export const readingNeed = (text) => Math.max(MIN_READ_S, READ_S_PER_WORD * wordCount(text));
+
+/** cues: [{ from, to, text }] in frames. -> { status: "PASS" | "FAIL" | "N/A", checked, bad: [{ text, from, seconds, need }] } */
+export const readingTime = (cues, fps) => {
+ const list = (Array.isArray(cues) ? cues : []).filter((c) => c && String(c.text ?? "").trim());
+ if (!list.length || !(fps > 0)) return { status: "N/A", checked: 0, bad: [], reason: "the film declares no text cues (meta.captions), so nothing was checked" };
+ const bad = [];
+ for (const c of list) {
+ const need = readingNeed(c.text), frames = c.to - c.from;
+ if (frames < Math.ceil(need * fps - 1e-9)) bad.push({ text: String(c.text), from: c.from, seconds: Math.round((frames / fps) * 100) / 100, need: Math.round(need * 100) / 100 });
+ }
+ return { status: bad.length ? "FAIL" : "PASS", checked: list.length, bad };
+};
+
+/** True for a 9:16 frame (1080x1920 and anything that shape). */
+export const isPortrait916 = (W, H) => W > 0 && H > 0 && Math.abs(W / H - 9 / 16) < 0.02;
+
+/** The three platform-UI rectangles of a W x H frame. The right column sits between the two bands. */
+export const zoneRects = (W, H, z = SAFE_ZONES) => [
+ { name: "top band", x0: 0, y0: 0, x1: W, y1: H * z.top },
+ { name: "bottom band", x0: 0, y0: H * (1 - z.bottom), x1: W, y1: H },
+ { name: "right button column", x0: W * (1 - z.right), y0: H * z.top, x1: W, y1: H * (1 - z.bottom) },
+];
+
+/**
+ * recs: text boxes in device pixels [{ kind, label, frame, x0, y0, x1, y1 }] (the frame probe).
+ * Returns [{ zone, label, frames: [..] }], one row per (zone, text), for text that overlaps a zone by
+ * more than `tol` px on both axes. A 9:16 frame is the only one judged: any other shape is N/A.
+ */
+export const safeZoneHits = (recs, W, H, { zones = SAFE_ZONES, tol = 2 } = {}) => {
+ if (!isPortrait916(W, H)) return { status: "N/A", hits: [], reason: `${W}x${H} is not a 9:16 frame` };
+ const rects = zoneRects(W, H, zones), rows = new Map();
+ for (const r of recs ?? []) {
+ if (r.kind !== "text") continue;
+ for (const z of rects) {
+ if (Math.min(r.x1, z.x1) - Math.max(r.x0, z.x0) <= tol || Math.min(r.y1, z.y1) - Math.max(r.y0, z.y0) <= tol) continue;
+ const k = `${z.name}\u0000${r.label}`, row = rows.get(k) ?? { zone: z.name, label: r.label, frames: [] };
+ row.frames.push(r.frame); rows.set(k, row);
+ }
+ }
+ const hits = [...rows.values()];
+ return { status: hits.length ? "FAIL" : "PASS", hits };
+};
diff --git a/plugins/anidoodle/skills/anidoodle/references/craft-bar.md b/plugins/anidoodle/skills/anidoodle/references/craft-bar.md
index d6f0ad9..98cccff 100644
--- a/plugins/anidoodle/skills/anidoodle/references/craft-bar.md
+++ b/plugins/anidoodle/skills/anidoodle/references/craft-bar.md
@@ -34,6 +34,15 @@ Check it with the tool AND by eye: a creeping camera changes every pixel and sat
while the eye sees a still.
+**Words get time to be read, and a quiet ground.** A text stays on screen at least
+`max(0.7 s, 0.3 s per word)`: "ART OUT." needs 0.7 s, a six-word line 1.8 s. Count from the frame
+the last word is whole, and give a slower audience (children, a second language) more. Text is
+never set over a busy picture without a plate under it: a solid or softly tinted panel, a scrim, or
+a clear patch of the drawing, so every letter has a ground it can be read against. Squint at the
+frame; if a letter disappears, the plate is missing. `framecheck.mjs` holds the first rule on every
+declared text cue (`meta.captions`) and reports N/A for a film that declares none; the second is a
+review finding (`workflows/review.md`), because only an eye can judge busy.
+
**Judge the design, not only the collisions.** A review still can have nothing overlapping and
still fail: no hierarchy, cramped spacing, a frame that would not pass as a poster. Look at each
review frame as a designer first, a checker second.
diff --git a/plugins/anidoodle/skills/anidoodle/references/formats.md b/plugins/anidoodle/skills/anidoodle/references/formats.md
index 4190672..7a0a984 100644
--- a/plugins/anidoodle/skills/anidoodle/references/formats.md
+++ b/plugins/anidoodle/skills/anidoodle/references/formats.md
@@ -86,6 +86,24 @@ Render options that hold for every moving format:
- `--hashes out/x.md5`: the md5 of every frame handed to the encoder, for frame-exact
comparisons of two renders before any codec blurs the difference.
+Words on screen, wherever the shape:
+
+- **Reading time.** Each text stays up at least `max(0.7 s, 0.3 s per word)`. A launch film's cues
+ are `meta.captions`; `node tools/framecheck.mjs <name>` fails any cue held shorter and reports
+ `N/A` for a film that declares no cues (it cannot see words it was not told about).
+- **No text on a busy picture without a plate** (`craft-bar.md`).
+- **Phone safe zones, 9:16 only.** Reels, TikTok and Shorts lay their own name, caption, buttons
+ and progress bar over the frame. Keep text and key content out of the top 14 % and bottom 25 %
+ of the height, and the right 14 % of the width (the button column) between them. The shares are
+ the cautious end of the creator safe-area guidance those apps publish for vertical video,
+ rounded up; their layouts change, so re-check before a campaign. `framecheck.mjs` finds text in
+ those zones on any 9:16 frame (`SAFE-ZONES`); on `launch.mjs ship` it is a FLAG that does not
+ fail the shape, because the launch template's phone layouts are a chat window across the whole
+ frame; `--strict-zones` makes it fail. Other shapes report N/A. Burned-in captions
+ (`captions: "burn"`) sit in the bottom zone by design: for those feeds, ship the sidecar.
+- **Claims** in a film, on screen or spoken, are listed with their sources in `facts.json`
+ (`workflows/facts.md`).
+
After any encode, `node tools/verify-export.mjs <name> [--first-frame #hex] [--fidelity-psnr 40]`
proves the file on disk is the film: size, exact frame count, duration, the score (an audio
stream exactly when the film has one, as long as the picture, not silent), its SYNC (the decoded
diff --git a/skills/anidoodle/engine/src/hosts/page.ts b/skills/anidoodle/engine/src/hosts/page.ts
index eafcbcb..a1853e4 100644
--- a/skills/anidoodle/engine/src/hosts/page.ts
+++ b/skills/anidoodle/engine/src/hosts/page.ts
@@ -129,9 +129,11 @@ export const mountFilm = (film: Film) => {
// THE FRAME PROBE (tools/framecheck.mjs). For each frame asked, every line of text (fillText on the
// frame or a full-frame sheet, writeOn, setType) and every content box the art core reports
// (probeRect: a card, a window) is collected in device pixels; a box the frame's edge cuts through
- // is returned. Whatever lies wholly outside the frame, or wholly inside it, is fine.
- const probe = (frames: number[]) => {
- const out: (ProbeRec & { frame: number })[] = [], g = globalThis as { __ANIDOODLE_PROBE__?: (r: ProbeRec) => void };
+ // is returned. Whatever lies wholly outside the frame, or wholly inside it, is fine. With `all`, every
+ // visible line of text is returned too (cut: false when whole), for the checks that judge where
+ // text sits (the 9:16 safe zones, textrules.mjs).
+ const probe = (frames: number[], all = false) => {
+ const out: (ProbeRec & { frame: number; cut?: boolean })[] = [], g = globalThis as { __ANIDOODLE_PROBE__?: (r: ProbeRec) => void };
const protos = [CanvasRenderingContext2D.prototype, ...(typeof OffscreenCanvasRenderingContext2D !== "undefined" ? [OffscreenCanvasRenderingContext2D.prototype] : [])] as unknown as { fillText: (t: string, x: number, y: number, w?: number) => void }[];
const orig = protos.map((p) => p.fillText);
let frame = 0, recs: ProbeRec[] = [];
@@ -147,7 +149,7 @@ export const mountFilm = (film: Film) => {
try {
for (frame of frames) {
recs = []; seek(frame); const W = canvas.width, H = canvas.height, tol = 1.5;
- for (const r of recs) { const inter = r.x1 > 0 && r.x0 < W && r.y1 > 0 && r.y0 < H, inside = r.x0 >= -tol && r.y0 >= -tol && r.x1 <= W + tol && r.y1 <= H + tol; if (inter && !inside) out.push({ ...r, frame }); }
+ for (const r of recs) { const inter = r.x1 > 0 && r.x0 < W && r.y1 > 0 && r.y0 < H, inside = r.x0 >= -tol && r.y0 >= -tol && r.x1 <= W + tol && r.y1 <= H + tol; if (inter && !inside) out.push({ ...r, frame }); else if (all && inter && r.kind === "text") out.push({ ...r, frame, cut: false }); }
}
} finally { protos.forEach((p, i) => (p.fillText = orig[i] as never)); delete g.__ANIDOODLE_PROBE__; }
return out;
diff --git a/skills/anidoodle/engine/test/textrules.test.ts b/skills/anidoodle/engine/test/textrules.test.ts
new file mode 100644
index 0000000..0e30534
--- /dev/null
+++ b/skills/anidoodle/engine/test/textrules.test.ts
@@ -0,0 +1,40 @@
+// TEXT RULES TESTS. The reading-time rule and the 9:16 phone safe zones, held to known answers,
+// including the failing cases: a cue that is too short, text under the platforms' buttons.
+// @ts-ignore: a plain ES module shared with the tools
+import { SAFE_ZONES, isPortrait916, readingNeed, readingTime, safeZoneHits, zoneRects } from "../tools/textrules.mjs";
+
+export const name = "textrules";
+export const run = (ok: (cond: boolean, label: string) => void) => {
+ // ---- reading time: max(0.7 s, 0.3 s per word)
+ ok(readingNeed("Hi") === 0.7 && readingNeed("one two") === 0.7, "one or two words need the 0.7 s floor");
+ ok(Math.abs(readingNeed("one two three four five six") - 1.8) < 1e-9, "six words need 1.8 s (0.3 s each)");
+ const fps = 30, cue = (text: string, s: number) => ({ from: 100, to: 100 + Math.round(s * fps), text });
+ ok(readingTime([cue("IDEA IN.", 0.7), cue("one two three four five six", 1.8)], fps).status === "PASS", "cues exactly at their reading time pass");
+ const short = readingTime([cue("IDEA IN.", 0.7), cue("one two three four five six", 1.5)], fps);
+ ok(short.status === "FAIL" && short.bad.length === 1 && short.bad[0].need === 1.8 && short.bad[0].seconds === 1.5, `NEGATIVE: a 6-word cue up for 1.5 s fails (${JSON.stringify(short.bad[0])})`);
+ ok(readingTime([cue("Yes", 0.6)], fps).status === "FAIL", "NEGATIVE: one word up for 0.6 s fails the 0.7 s floor");
+ ok(readingTime([{ from: 0, to: 20, text: "Yes" }], 30).status === "FAIL" && readingTime([{ from: 0, to: 21, text: "Yes" }], 30).status === "PASS", "the floor is 21 frames at 30 fps, 20 fails");
+ ok(readingTime([], fps).status === "N/A" && readingTime(undefined, fps).status === "N/A", "no declared cues is N/A, never a pass");
+ ok(readingTime([{ from: 0, to: 5, text: " " }], fps).status === "N/A", "a blank cue is not text: N/A");
+ ok(readingTime([cue("IDEA IN.", 0.7)], fps).status !== "N/A", "declared text is judged");
+
+ // ---- the 9:16 frame and its zones
+ ok(isPortrait916(1080, 1920) && isPortrait916(720, 1280) && !isPortrait916(1920, 1080) && !isPortrait916(1080, 1350) && !isPortrait916(1080, 1080), "9:16 is detected by shape, not by name");
+ const z = zoneRects(1080, 1920);
+ ok(z.length === 3 && z[0].y1 === 1920 * SAFE_ZONES.top && z[1].y0 === 1920 * (1 - SAFE_ZONES.bottom) && z[2].x0 === 1080 * (1 - SAFE_ZONES.right), "three zones: top band, bottom band, right button column");
+ ok(SAFE_ZONES.top >= 0.12 && SAFE_ZONES.bottom >= 0.2 && SAFE_ZONES.right >= 0.1, "the shares are the conservative ones, not the minimum");
+ const text = (label: string, x0: number, y0: number, x1: number, y1: number, frame = 0) => ({ kind: "text", label, x0, y0, x1, y1, frame });
+ const inside = text("whole", 200, 600, 800, 700), W = 1080, H = 1920;
+ ok(safeZoneHits([inside], W, H).status === "PASS", "text in the middle of the frame passes");
+ const top = safeZoneHits([text("TITLE", 100, 40, 900, 120)], W, H);
+ ok(top.status === "FAIL" && top.hits[0].zone === "top band", "NEGATIVE: text in the top band fails");
+ const bottom = safeZoneHits([text("npm i x", 100, 1600, 900, 1700)], W, H);
+ ok(bottom.status === "FAIL" && bottom.hits[0].zone === "bottom band", "NEGATIVE: text in the bottom band fails");
+ const right = safeZoneHits([text("CLAIM", 700, 800, 1060, 900)], W, H);
+ ok(right.status === "FAIL" && right.hits[0].zone === "right button column", "NEGATIVE: text running into the right button column fails");
+ ok(safeZoneHits([text("edge", 100, 270, 900, 280)], W, H).status === "PASS", "text that only touches a zone's border passes");
+ const many = safeZoneHits([text("TITLE", 100, 40, 900, 120, 0), text("TITLE", 100, 40, 900, 120, 5), text("TITLE", 100, 40, 900, 120, 9)], W, H);
+ ok(many.hits.length === 1 && many.hits[0].frames.join() === "0,5,9", "one row per text and zone, with every frame it was seen on");
+ ok(safeZoneHits([{ kind: "box", label: "card", x0: 0, y0: 0, x1: 1080, y1: 1920, frame: 0 }], W, H).status === "PASS", "content boxes are not judged here, only text");
+ ok(safeZoneHits([text("TITLE", 100, 40, 900, 120)], 1920, 1080).status === "N/A", "a 16:9 frame is N/A, never judged against phone zones");
+};
diff --git a/skills/anidoodle/engine/tools/adapters/playwright.mjs b/skills/anidoodle/engine/tools/adapters/playwright.mjs
index 07b47dd..a0ea434 100644
--- a/skills/anidoodle/engine/tools/adapters/playwright.mjs
+++ b/skills/anidoodle/engine/tools/adapters/playwright.mjs
@@ -34,7 +34,7 @@ export const open = async ({ pw, browser: found }, pagePath, { scale = 1, worker
blurHash: (n, samples, w = 0) => pick(w).evaluate(([f, s]) => { window.FILM.blur(f, s); return window.FILM.hash(); }, [n, samples]),
audio: (sr) => pages[0].evaluate((s) => window.FILM.audio(s), sr),
// the frame probe (hosts/page.ts): text and content boxes the frame's edge cuts through
- probe: (frames) => pages[0].evaluate((fs) => window.FILM.probe(fs), frames),
+ probe: (frames, all = false) => pages[0].evaluate(([fs, a]) => window.FILM.probe(fs, a), [frames, all]),
// keeps the fresh bakes, then closes; returns how many plate frames were stored
close: async () => { let saved = 0; if (useBakes) for (const p of pages) saved += await saveBakes(p, bv).catch(() => 0); await browser.close(); return saved; },
};
diff --git a/skills/anidoodle/engine/tools/framecheck.mjs b/skills/anidoodle/engine/tools/framecheck.mjs
index 99620ca..09d963c 100644
--- a/skills/anidoodle/engine/tools/framecheck.mjs
+++ b/skills/anidoodle/engine/tools/framecheck.mjs
@@ -1,28 +1,50 @@
-// FRAMECHECK. A design fault the determinism gate cannot see: type or content cut by the frame's
-// edge. Every line of text (fillText, writeOn, setType) and every content box the art reports
-// (probeRect: an answer card, a product window, a film's card) must lie wholly inside the frame or
-// wholly outside it, on every frame checked. A deliberate full-bleed is not reported as a box.
-// node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T]
+// FRAMECHECK. Design faults the determinism gate cannot see, found on the frames themselves.
+// 1. Cut by the edge. Every line of text (fillText, writeOn, setType) and every content box the art
+// reports (probeRect: an answer card, a product window, a film's card) must lie wholly inside the
+// frame or wholly outside it, on every frame checked. A deliberate full-bleed is not reported as a box.
+// 2. Reading time. Each declared text cue (meta.captions) stays up for max(0.7 s, 0.3 s per word).
+// A film that declares no cues reports N/A, never a pass.
+// 3. Phone safe zones, 9:16 frames only. No text inside the top band, the bottom band or the right
+// button column the platforms cover with their own interface. Other shapes report N/A.
+// The rules and their numbers are textrules.mjs.
+// node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T] [--zones fail|warn]
+// --zones warn lists safe-zone text as FLAG and does not fail the run (launch.mjs ship uses it, because
+// the launch template's phone layouts are a chat window across the whole frame; --strict-zones there
+// makes it fail). Reading time and the edge cut always fail.
import { resolve } from "node:path";
import { buildPage } from "./build-page.mjs";
import { detect } from "./detect.mjs";
import * as playwright from "./adapters/playwright.mjs";
import { requireFilm } from "./names.mjs";
+import { isMain } from "./is-main.mjs";
+import { SAFE_ZONES, isPortrait916, readingTime, safeZoneHits } from "./textrules.mjs";
-const pos = [], opt = {};
-for (let i = 2; i < process.argv.length; i++) { const a = process.argv[i]; if (a.startsWith("--")) opt[a.slice(2)] = process.argv[++i]; else pos.push(a); }
-const film = requireFilm(pos[0], "framecheck", "node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T]");
+const USAGE = "node tools/framecheck.mjs <film>[-<shape>] [--every 1] [--from F] [--to T] [--zones fail|warn]";
export const frameCheck = async (film, { every = 1, from = 0, to } = {}) => {
const page = await buildPage({ entry: `src/hosts/page-${film}.ts`, out: resolve(`dist/${film}.html`), title: film });
- const s = await playwright.open(detect(), page.out, { workers: 1 }), meta = await s.info(), N = to ?? meta.durationFrames;
+ const s = await playwright.open(detect(), page.out, { workers: 1 }), meta = await s.info(), N = to ?? meta.durationFrames, portrait = isPortrait916(meta.W, meta.H);
const frames = []; for (let f = from; f < N; f += every) frames.push(f);
- const bad = []; for (let i = 0; i < frames.length; i += 40) bad.push(...(await s.probe(frames.slice(i, i + 40))));
+ const recs = []; for (let i = 0; i < frames.length; i += 40) recs.push(...(await s.probe(frames.slice(i, i + 40), portrait)));
await s.close();
- return { meta, frames: frames.length, bad };
+ return { meta, frames: frames.length, bad: recs.filter((r) => r.cut !== false), reading: readingTime(meta.captions, meta.fps), zones: safeZoneHits(recs, meta.W, meta.H) };
};
-const r = await frameCheck(film, { every: Number(opt.every ?? 1), from: Number(opt.from ?? 0), to: opt.to === undefined ? undefined : Number(opt.to) });
-const groups = new Map(); for (const b of r.bad) { const k = `${b.kind} "${b.label.slice(0, 48)}"`; const g = groups.get(k) ?? []; g.push(b.frame); groups.set(k, g); }
-console.log(`FRAMECHECK ${film} ${r.meta.W}x${r.meta.H}, ${r.frames} frames`);
-for (const [k, fs] of groups) { const b = r.bad.find((x) => `${x.kind} "${x.label.slice(0, 48)}"` === k); console.log(` FAIL ${k} cut by the frame's edge on ${fs.length} frame(s): ${fs.slice(0, 8).join(", ")}${fs.length > 8 ? " ..." : ""} box ${[b.x0, b.y0, b.x1, b.y1].map((v) => Math.round(v)).join(",")}`); }
-console.log(r.bad.length ? `FRAMECHECK: FAIL ${groups.size} item(s) cut by the frame's edge` : `FRAMECHECK: PASS no text or content box cut by the frame's edge`);
-process.exit(r.bad.length ? 1 : 0);
+if (isMain(import.meta.url)) {
+ const pos = [], opt = {};
+ for (let i = 2; i < process.argv.length; i++) { const a = process.argv[i]; if (a.startsWith("--")) opt[a.slice(2)] = process.argv[++i]; else pos.push(a); }
+ const film = requireFilm(pos[0], "framecheck", USAGE), warnZones = opt.zones === "warn";
+ if (opt.zones !== undefined && !["fail", "warn"].includes(opt.zones)) { console.error(`framecheck: --zones is fail or warn, got '${opt.zones}'\nusage: ${USAGE}`); process.exit(2); }
+ const r = await frameCheck(film, { every: Number(opt.every ?? 1), from: Number(opt.from ?? 0), to: opt.to === undefined ? undefined : Number(opt.to) });
+ const list = (fs) => `${fs.slice(0, 8).join(", ")}${fs.length > 8 ? " ..." : ""}`;
+ const groups = new Map(); for (const b of r.bad) { const k = `${b.kind} "${b.label.slice(0, 48)}"`; const g = groups.get(k) ?? []; g.push(b.frame); groups.set(k, g); }
+ console.log(`FRAMECHECK ${film} ${r.meta.W}x${r.meta.H}, ${r.frames} frames`);
+ for (const [k, fs] of groups) { const b = r.bad.find((x) => `${x.kind} "${x.label.slice(0, 48)}"` === k); console.log(` FAIL ${k} cut by the frame's edge on ${fs.length} frame(s): ${list(fs)} box ${[b.x0, b.y0, b.x1, b.y1].map((v) => Math.round(v)).join(",")}`); }
+ const rd = r.reading, zn = r.zones;
+ for (const b of rd.bad) console.log(` FAIL text "${b.text.slice(0, 48)}" is up ${b.seconds} s from frame ${b.from}; reading it takes ${b.need} s`);
+ for (const h of zn.hits ?? []) console.log(` ${warnZones ? "FLAG" : "FAIL"} text "${h.label.slice(0, 48)}" sits in the ${h.zone} on ${h.frames.length} frame(s): ${list(h.frames)}`);
+ const zp = (x) => Math.round(x * 100);
+ console.log(` READING-TIME: ${rd.status}${rd.status === "N/A" ? ` ${rd.reason}` : ` ${rd.checked} cue(s), each at least max(0.7 s, 0.3 s per word)`}`);
+ console.log(` SAFE-ZONES: ${zn.status === "FAIL" && warnZones ? "FLAG" : zn.status}${zn.status === "N/A" ? ` ${zn.reason}` : ` ${zn.hits.length ? `${zn.hits.length} text(s) inside` : "no text in"} the top ${zp(SAFE_ZONES.top)}%, bottom ${zp(SAFE_ZONES.bottom)}% or right ${zp(SAFE_ZONES.right)}% of the frame`}`);
+ const nz = zn.hits?.length ?? 0, fails = groups.size + rd.bad.length + (warnZones ? 0 : nz);
+ console.log(fails ? `FRAMECHECK: FAIL ${fails} problem(s): ${groups.size} cut by the frame's edge, ${rd.bad.length} read too briefly, ${warnZones ? 0 : nz} in a phone safe zone` : `FRAMECHECK: PASS no text or content box cut by the frame's edge; reading time ${rd.status}; safe zones ${nz ? `FLAGGED (${nz} text(s))` : zn.status}`);
+ process.exit(fails ? 1 : 0);
+}
diff --git a/skills/anidoodle/engine/tools/textrules.mjs b/skills/anidoodle/engine/tools/textrules.mjs
new file mode 100644
index 0000000..19d8967
--- /dev/null
+++ b/skills/anidoodle/engine/tools/textrules.mjs
@@ -0,0 +1,58 @@
+// TEXT RULES. Two rules about words on screen, as pure functions (no browser, no ffmpeg) so they are
+// unit-tested and framecheck.mjs only has to feed them.
+// 1. Reading time. A text cue stays up for at least max(0.7 s, 0.3 s per word). Judged on the cues a
+// film declares (meta.captions: { from, to, text } in frames). A film that declares none is N/A,
+// never a pass: the tool cannot see words it was not told about.
+// 2. Phone safe zones. On a 9:16 frame the platforms lay their own buttons, names and captions over
+// the top band, the bottom band and a right-hand column of buttons. Text under them is lost.
+// The shares below are conservative: the most cautious end of the creator safe-area guidance the
+// big short-video apps publish for vertical video, rounded up. Their layouts change, so treat the
+// numbers as a floor to re-check, not as a spec.
+export const MIN_READ_S = 0.7, READ_S_PER_WORD = 0.3;
+export const SAFE_ZONES = { top: 0.14, bottom: 0.25, right: 0.14 }; // shares of the frame: top and bottom of its height, right of its width
+
+export const wordCount = (text) => String(text ?? "").trim().split(/\s+/).filter(Boolean).length;
+/** Seconds a text needs on screen to be read. */
+export const readingNeed = (text) => Math.max(MIN_READ_S, READ_S_PER_WORD * wordCount(text));
+
+/** cues: [{ from, to, text }] in frames. -> { status: "PASS" | "FAIL" | "N/A", checked, bad: [{ text, from, seconds, need }] } */
+export const readingTime = (cues, fps) => {
+ const list = (Array.isArray(cues) ? cues : []).filter((c) => c && String(c.text ?? "").trim());
+ if (!list.length || !(fps > 0)) return { status: "N/A", checked: 0, bad: [], reason: "the film declares no text cues (meta.captions), so nothing was checked" };
+ const bad = [];
+ for (const c of list) {
+ const need = readingNeed(c.text), frames = c.to - c.from;
+ if (frames < Math.ceil(need * fps - 1e-9)) bad.push({ text: String(c.text), from: c.from, seconds: Math.round((frames / fps) * 100) / 100, need: Math.round(need * 100) / 100 });
+ }
+ return { status: bad.length ? "FAIL" : "PASS", checked: list.length, bad };
+};
+
+/** True for a 9:16 frame (1080x1920 and anything that shape). */
+export const isPortrait916 = (W, H) => W > 0 && H > 0 && Math.abs(W / H - 9 / 16) < 0.02;
+
+/** The three platform-UI rectangles of a W x H frame. The right column sits between the two bands. */
+export const zoneRects = (W, H, z = SAFE_ZONES) => [
+ { name: "top band", x0: 0, y0: 0, x1: W, y1: H * z.top },
+ { name: "bottom band", x0: 0, y0: H * (1 - z.bottom), x1: W, y1: H },
+ { name: "right button column", x0: W * (1 - z.right), y0: H * z.top, x1: W, y1: H * (1 - z.bottom) },
+];
+
+/**
+ * recs: text boxes in device pixels [{ kind, label, frame, x0, y0, x1, y1 }] (the frame probe).
+ * Returns [{ zone, label, frames: [..] }], one row per (zone, text), for text that overlaps a zone by
+ * more than `tol` px on both axes. A 9:16 frame is the only one judged: any other shape is N/A.
+ */
+export const safeZoneHits = (recs, W, H, { zones = SAFE_ZONES, tol = 2 } = {}) => {
+ if (!isPortrait916(W, H)) return { status: "N/A", hits: [], reason: `${W}x${H} is not a 9:16 frame` };
+ const rects = zoneRects(W, H, zones), rows = new Map();
+ for (const r of recs ?? []) {
+ if (r.kind !== "text") continue;
+ for (const z of rects) {
+ if (Math.min(r.x1, z.x1) - Math.max(r.x0, z.x0) <= tol || Math.min(r.y1, z.y1) - Math.max(r.y0, z.y0) <= tol) continue;
+ const k = `${z.name}\u0000${r.label}`, row = rows.get(k) ?? { zone: z.name, label: r.label, frames: [] };
+ row.frames.push(r.frame); rows.set(k, row);
+ }
+ }
+ const hits = [...rows.values()];
+ return { status: hits.length ? "FAIL" : "PASS", hits };
+};
diff --git a/skills/anidoodle/references/craft-bar.md b/skills/anidoodle/references/craft-bar.md
index d6f0ad9..98cccff 100644
--- a/skills/anidoodle/references/craft-bar.md
+++ b/skills/anidoodle/references/craft-bar.md
@@ -34,6 +34,15 @@ Check it with the tool AND by eye: a creeping camera changes every pixel and sat
while the eye sees a still.
+**Words get time to be read, and a quiet ground.** A text stays on screen at least
+`max(0.7 s, 0.3 s per word)`: "ART OUT." needs 0.7 s, a six-word line 1.8 s. Count from the frame
+the last word is whole, and give a slower audience (children, a second language) more. Text is
+never set over a busy picture without a plate under it: a solid or softly tinted panel, a scrim, or
+a clear patch of the drawing, so every letter has a ground it can be read against. Squint at the
+frame; if a letter disappears, the plate is missing. `framecheck.mjs` holds the first rule on every
+declared text cue (`meta.captions`) and reports N/A for a film that declares none; the second is a
+review finding (`workflows/review.md`), because only an eye can judge busy.
+
**Judge the design, not only the collisions.** A review still can have nothing overlapping and
still fail: no hierarchy, cramped spacing, a frame that would not pass as a poster. Look at each
review frame as a designer first, a checker second.
diff --git a/skills/anidoodle/references/formats.md b/skills/anidoodle/references/formats.md
index 4190672..7a0a984 100644
--- a/skills/anidoodle/references/formats.md
+++ b/skills/anidoodle/references/formats.md
@@ -86,6 +86,24 @@ Render options that hold for every moving format:
- `--hashes out/x.md5`: the md5 of every frame handed to the encoder, for frame-exact
comparisons of two renders before any codec blurs the difference.
+Words on screen, wherever the shape:
+
+- **Reading time.** Each text stays up at least `max(0.7 s, 0.3 s per word)`. A launch film's cues
+ are `meta.captions`; `node tools/framecheck.mjs <name>` fails any cue held shorter and reports
+ `N/A` for a film that declares no cues (it cannot see words it was not told about).
+- **No text on a busy picture without a plate** (`craft-bar.md`).
+- **Phone safe zones, 9:16 only.** Reels, TikTok and Shorts lay their own name, caption, buttons
+ and progress bar over the frame. Keep text and key content out of the top 14 % and bottom 25 %
+ of the height, and the right 14 % of the width (the button column) between them. The shares are
+ the cautious end of the creator safe-area guidance those apps publish for vertical video,
+ rounded up; their layouts change, so re-check before a campaign. `framecheck.mjs` finds text in
+ those zones on any 9:16 frame (`SAFE-ZONES`); on `launch.mjs ship` it is a FLAG that does not
+ fail the shape, because the launch template's phone layouts are a chat window across the whole
+ frame; `--strict-zones` makes it fail. Other shapes report N/A. Burned-in captions
+ (`captions: "burn"`) sit in the bottom zone by design: for those feeds, ship the sidecar.
+- **Claims** in a film, on screen or spoken, are listed with their sources in `facts.json`
+ (`workflows/facts.md`).
+
After any encode, `node tools/verify-export.mjs <name> [--first-frame #hex] [--fidelity-psnr 40]`
proves the file on disk is the film: size, exact frame count, duration, the score (an audio
stream exactly when the film has one, as long as the picture, not silent), its SYNC (the decoded