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.

facts.json: every claim sourced or labelled generated; wired into launch new/ship

Alex Greenshpund475bafd3f85
diff --git a/plugins/anidoodle/skills/anidoodle/SKILL.md b/plugins/anidoodle/skills/anidoodle/SKILL.md
index 6d84259..b465b34 100644
--- a/plugins/anidoodle/skills/anidoodle/SKILL.md
+++ b/plugins/anidoodle/skills/anidoodle/SKILL.md
@@ -36,7 +36,7 @@ say why in one line. Write the answers into a short brief before drawing.
| A loop, sticker, animated logo, ambient header | Loop workflow below, `references/formats.md` |
| A story film, any length | Film workflow below, `references/workflows/long-film.md` |
| An explainer or infographic; a machine that comes apart to explain an idea, in any style | `references/workflows/explainer.md`, `references/workflows/machines.md` |
-| A launch or product video (their screenshots welcome) | `references/workflows/launch-video.md`; build it on `references/workflows/launch-video-kit.md` |
+| A launch or product video (their screenshots welcome) | `references/workflows/launch-video.md`; build it on `references/workflows/launch-video-kit.md`; its claims: `references/workflows/facts.md` |
| Art for a site (hero by a headline, tiles, spots, share card) on its page colour and brand; or a web animation that reacts to the UI | `references/workflows/site-art.md`; `references/workflows/interactive.md` |
| A drawing lesson, or "how do I draw this?" | `references/workflows/teach-drawing.md` |
| A character kept identical in any style (woodcut to toy brick) | `references/workflows/character-consistency.md`, `references/anatomy.md` |
@@ -82,9 +82,9 @@ longer films, a spine plus one line per chapter. If you cannot write it, stop. (
a beat is 60 x fps / bpm frames, the bpm from the brief's score; one cue table holds every frame number and a checker
runs at load. (3) **Real reference** for anything that exists. (4) **ONE look still**, the hardest
frame, critiqued in writing. ✋ **Approval.** (5) **ONE 8-second music sample.** ✋ **Approval.**
-(6) **Build the whole film**; mechanical checks run continuously. (7) **Review once** from the
-rendered file, as four readings with a scorecard (`references/workflows/review.md`). One ranked fix
-list, one rebuild. (8) ✋ **Final approval.** Say what you verified and what you cannot.
+(6) **Build the whole film**; mechanical checks run continuously. (7) **A fresh critic reviews, never you**
+(`references/workflows/review.md`): after the storyboard, each scene and the full render, a new subagent that saw none of the building returns ranked, timestamped problems and a verdict. Fix the biggest, a NEW critic rechecks; 3 rounds at most, logged in `ledger.md`.
+(8) ✋ **Final approval.** Say what you verified and what you cannot.
Three approval gates at most. Approval is a budget; spend it where being wrong is expensive.
@@ -125,7 +125,7 @@ node <skill>/engine/tools/soundfetch.mjs get piano rooms # on their yes (piano
| `registry.mjs` / `gallery.mjs` | the style list from the plates themselves / the gallery sheet |
| `docs-check.mjs` | fails when any doc's style count, length or path disagrees with the code |
| `verify-export.mjs` | QA on the rendered file: frames, duration, score, A/V sync, true peak after the encode; opt-in first frame, loop seam, `--delivery` |
-| `launch.mjs` | a launch film: `new <name>` scaffolds the spec; `ship <name> --shapes 16x9,9x16` renders, posters, captions, verifies and framechecks each (`framecheck.mjs`: no text cut by the frame's edge) |
+| `launch.mjs` | a launch film: `new <name>` scaffolds the spec; `ship <name> --shapes 16x9,9x16` renders, posters, captions, verifies and framechecks each (`framecheck.mjs`: text whole, up long enough to read, clear of the 9:16 phone zones) and checks `facts.json` (`facts.mjs`) |
| `test.mjs` (`npm test`) | unit suites in `engine/test/`, no browser |
| `music.mjs` | `vocab` prints a style's vocabulary; `check` gates your composed score (key, master, guards, stems, novelty, which parts played recordings) and prints its shape (ARC); `render`, `meter` |
| `soundfetch.mjs` | the sound pack: `list`, `get <id...\|all>`, `where`, `verify`, `remove <id>` |
diff --git a/plugins/anidoodle/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts b/plugins/anidoodle/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts
index 93c744f..c9391ce 100644
--- a/plugins/anidoodle/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts
+++ b/plugins/anidoodle/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts
@@ -88,6 +88,7 @@ export type LaunchSpec = {
sfx?: boolean; // sound cues from the picture's timing (default true; false = the score alone)
motif?: boolean; // the relay into the end card (default true): the drop becomes the mark's dot
captions?: "sidecar" | "burn"; // .srt/.vtt only (default), or also burned into their own band (phone shapes)
+ claims?: string[]; // any other on-screen or narrated claim (a number in the UI, a spoken line); the words, split words and tagline are claims already
};
// the clean preset: a quiet canvas, one accent, type as the design. Our own palette, drawn for it.
@@ -137,6 +138,7 @@ export type LaunchFilm = Omit<Film, "reshape"> & {
seams: Seam[]; // the motif's seams, each checked (checkRelay)
timing: { base: number; len: number; tin: number; b: number; down: number; up: number; drop: Drop; times: number[] }[]; // each ask's own timing, content frames at 30 fps
captions: { from: number; to: number; text: string }[]; // = meta.captions
+ claims: string[]; // every claim the film makes, each to be listed in facts.json with its source (tools/facts.mjs)
};
export const makeLaunchFilm = (spec: LaunchSpec): LaunchFilm => {
const fps = spec.fps ?? 30, m = fps / 30, n = spec.asks.length, shape = spec.shape ?? "16x9", clean = spec.preset === "clean";
@@ -558,6 +560,7 @@ export const makeLaunchFilm = (spec: LaunchSpec): LaunchFilm => {
assets: { images: {} },
shots: [{ id: "cut", start: 0, end: cut.N * m, draw }],
audio,
+ claims: [...new Set([...words.flat().map((x) => x.text), ...spec.asks.flatMap((a) => (isChat(a) ? [] : (a.split ?? []).map((x) => x.text))), spec.tagline, ...(spec.claims ?? [])].map((x) => x.trim()).filter(Boolean))],
cut, layout: L, cues, seams, heroPx: HERO ? HERO.TEXT.px : null, timing: T, captions: caps.map((c) => ({ from: Math.round(c.from * m), to: Math.round(c.to * m), text: c.text })),
// the same film composed for another frame shape (one timeline: the cut, the timing and the sound do not change)
reshape: (s: string) => { if (s === shape) return self; memo ??= new Map(); let f = memo.get(s); if (!f) { f = makeLaunchFilm({ ...spec, shape: s as Shape }); memo.set(s, f); } return f; },
diff --git a/plugins/anidoodle/skills/anidoodle/engine/test/facts.test.ts b/plugins/anidoodle/skills/anidoodle/engine/test/facts.test.ts
new file mode 100644
index 0000000..197e4cc
--- /dev/null
+++ b/plugins/anidoodle/skills/anidoodle/engine/test/facts.test.ts
@@ -0,0 +1,42 @@
+// FACTS TESTS. Every claim a film declares must be listed in facts.json with its source, or labelled
+// generated; nothing invented. Held to known answers, with the failing cases.
+// @ts-ignore: a plain ES module shared with the tools
+import { checkFacts, entryProblems, normClaim, EMPTY_FACTS } from "../tools/factsrules.mjs";
+import { makeLaunchFilm } from "../src/canvas-core/launchTemplate";
+import type { Film } from "../src/canvas-core/film";
+
+export const name = "facts";
+export const run = (ok: (cond: boolean, label: string) => void) => {
+ const src = { sentence: "Setup takes about 40 minutes.", url: "https://example.com/docs" };
+ const good = { claim: "Ships in 40 minutes.", where: "on-screen", source: src };
+ const slogan = { claim: "IDEA IN.", where: "on-screen", generated: true, note: "slogan written for this film" };
+ const facts = { version: 1, claims: [good, slogan] };
+ ok(normClaim(" Ships IN 40 minutes! ") === normClaim("ships in 40 minutes."), "claims match ignoring case, spacing and end punctuation");
+ ok(checkFacts(["Ships in 40 minutes.", "IDEA IN."], facts).status === "PASS", "every claim listed with a source or labelled generated passes");
+ ok(checkFacts([], facts).status === "N/A" && checkFacts(undefined, facts).status === "N/A", "a film that declares no claims is N/A, never a pass");
+
+ const missing = checkFacts(["Ships in 40 minutes.", "Loved by 10,000 teams."], facts);
+ ok(missing.status === "FAIL" && missing.problems.length === 1 && /not listed/.test(missing.problems[0].why), "NEGATIVE: a claim missing from facts.json fails");
+ ok(checkFacts(["IDEA IN."], null).status === "FAIL", "NEGATIVE: claims with no facts.json fail");
+ ok(checkFacts(["IDEA IN."], EMPTY_FACTS).status === "FAIL", "NEGATIVE: the empty scaffold fails until the claims are listed");
+ ok(checkFacts(["TODO CLAIM."], { claims: [{ claim: "TODO CLAIM.", generated: true, note: "x" }] }).status === "FAIL", "NEGATIVE: a TODO is not a claim");
+
+ const bad = (e: object) => entryProblems(e).join("; ");
+ ok(/source.sentence/.test(bad({ claim: "c", source: { url: "https://a.b" } })), "NEGATIVE: a sourced claim needs the exact sentence");
+ ok(/source.url or source.file/.test(bad({ claim: "c", source: { sentence: "c" } })), "NEGATIVE: a sourced claim needs a URL or a file");
+ ok(bad({ claim: "c", source: { sentence: "c", file: "notes/brief.md#2" } }) === "", "a file is a source too");
+ ok(/not an http/.test(bad({ claim: "c", source: { sentence: "c", url: "ftp://x" } })), "NEGATIVE: a source URL is http(s)");
+ ok(/no note/.test(bad({ claim: "c", generated: true })), "NEGATIVE: generated content must say what it is");
+ ok(/states a number/.test(bad({ claim: "5 stars", generated: true, note: "n" })), "NEGATIVE: a generated claim cannot state a number (no invented ratings or prices)");
+ ok(/states 99/.test(bad({ claim: "Saves 99% of time", source: src })), "NEGATIVE: a number the source sentence does not contain is caught");
+ ok(bad({ claim: "Takes 40 minutes", source: src }) === "", "a number that is in the source passes");
+ ok(checkFacts(["Ships in 40 minutes."], { claims: [{ ...good, source: { ...src, sentence: "" } }] }).status === "FAIL", "an entry with an empty sentence fails");
+ ok(checkFacts(["IDEA IN."], { claims: [slogan, { claim: "Narrated: best in class", where: "narration" }] }).status === "FAIL", "NEGATIVE: a narrated claim listed with no source fails too");
+
+ // the launch template declares its claims: the type-frame words, the split words and the tagline
+ const plate: Film = { meta: { title: "plate", W: 1080, H: 1080, fps: 30, bpm: 120, durationFrames: 60 }, assets: { images: {} }, shots: [{ id: "p", start: 0, end: 60, draw: () => {} }] };
+ const film = makeLaunchFilm({ title: "Tally", asks: [{ prompt: "draw it", plate, label: "l" }, { prompt: "again", plate, label: "l" }], words: [[{ text: "ONE.", style: "ink", color: "#111" }, { text: "TWO.", style: "ink", color: "#111" }]], tagline: "Counts things.", install: ["npm i tally"], bpm: 120, askBeats: 8, endBeats: 12, sfx: false, score: null, claims: ["Fast.", "ONE."] });
+ ok(film.claims.join("|") === "ONE.|TWO.|Counts things.|Fast.", `a launch film declares its words, tagline and extra claims once each (${film.claims.join("|")})`);
+ ok(film.reshape("9x16").claims.join("|") === film.claims.join("|"), "the claims are the same in every shape");
+ ok(!film.claims.includes("draw it") && !film.claims.includes("npm i tally"), "prompts and install lines are not claims");
+};
diff --git a/plugins/anidoodle/skills/anidoodle/engine/tools/captions.mjs b/plugins/anidoodle/skills/anidoodle/engine/tools/captions.mjs
index 7b942d4..9fbd427 100644
--- a/plugins/anidoodle/skills/anidoodle/engine/tools/captions.mjs
+++ b/plugins/anidoodle/skills/anidoodle/engine/tools/captions.mjs
@@ -12,12 +12,13 @@ import { requireFilm, splitShape } from "./names.mjs";
import { toSrt, toVtt } from "./avsync.mjs";
import { isMain } from "./is-main.mjs";
-export const filmMeta = async (name) => {
+export const loadFilm = async (name) => {
const { base, shape } = splitShape(name);
const js = (await build({ stdin: { contents: `export { ${base} as film } from "./src/canvas-core/${base}";`, resolveDir: process.cwd(), loader: "ts" }, bundle: true, format: "esm", write: false, platform: "neutral", plugins: [overlay], logLevel: "error" })).outputFiles[0].text;
const { film } = await import("data:text/javascript;base64," + Buffer.from(js).toString("base64"));
- return (shape ? film.reshape(shape) : film).meta;
+ return shape ? film.reshape(shape) : film;
};
+export const filmMeta = async (name) => (await loadFilm(name)).meta;
export const writeCaptions = async (name, out = `out/${name}`) => {
const meta = await filmMeta(name), caps = meta.captions ?? [];
if (!caps.length) return { count: 0, files: [] };
diff --git a/plugins/anidoodle/skills/anidoodle/engine/tools/facts.mjs b/plugins/anidoodle/skills/anidoodle/engine/tools/facts.mjs
new file mode 100644
index 0000000..0e17fda
--- /dev/null
+++ b/plugins/anidoodle/skills/anidoodle/engine/tools/facts.mjs
@@ -0,0 +1,42 @@
+// FACTS. Every claim a film makes, on screen or narrated, is listed in facts.json with the exact
+// sentence it comes from and where that sentence lives (a URL or a file). Nothing is invented: no
+// testimonial, rating, price, result or real person. What the film generates (a slogan, a drawn
+// scene, a mock UI) is labelled `generated`. This is the explainer's research ledger, for any film.
+//
+// facts.json
+// { "version": 1, "claims": [
+// { "claim": "Ships in 40 minutes.", "where": "on-screen",
+// "source": { "sentence": "Setup takes about 40 minutes.", "url": "https://example.com/docs" } },
+// { "claim": "IDEA IN. ART OUT.", "where": "on-screen", "generated": true, "note": "slogan written for this film, states no fact" } ] }
+//
+// node tools/facts.mjs <film>[-<shape>] [--facts facts.json] every claim the film declares is listed and well formed
+// node tools/facts.mjs init [--facts facts.json] write an empty facts.json (never overwrites)
+//
+// A film declares its claims as `film.claims` (a launch template film: the type-frame words, the split
+// words and the tagline, plus any `claims: [...]` in its spec). A film that declares none is N/A,
+// never a pass. The check is light on purpose: it cannot know a sentence is true, so it holds what it can.
+// - every declared claim has an entry (matched ignoring case, spacing and end punctuation);
+// - a sourced entry has the exact sentence and a URL (http/https) or a file;
+// - a generated entry says what it is, and states no number (a number needs a source);
+// - every number in a sourced claim appears in its source sentence;
+// - a TODO is not a claim yet.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isMain } from "./is-main.mjs";
+import { EMPTY_FACTS, checkFacts, claimsOf } from "./factsrules.mjs";
+
+export const readFacts = (file) => { if (!existsSync(file)) return { facts: null }; try { return { facts: JSON.parse(readFileSync(file, "utf8")) }; } catch (e) { return { facts: null, error: `${file} is not valid JSON: ${e.message}` }; } };
+export const initFacts = (file) => { if (existsSync(file)) return false; writeFileSync(file, JSON.stringify(EMPTY_FACTS, null, 2) + "\n"); return true; };
+
+if (isMain(import.meta.url)) {
+ const argv = process.argv.slice(2), fi = argv.indexOf("--facts"), file = resolve(fi >= 0 ? argv[fi + 1] : "facts.json"), name = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--facts");
+ const USAGE = "node tools/facts.mjs <film>[-<shape>] [--facts facts.json]\n node tools/facts.mjs init [--facts facts.json]";
+ if (name === "init") { console.log(initFacts(file) ? `facts: wrote ${file}` : `facts: ${file} already exists; left as it is`); process.exit(0); }
+ const { requireFilm } = await import("./names.mjs"), { loadFilm } = await import("./captions.mjs");
+ const film = requireFilm(name, "facts", USAGE), f = await loadFilm(film), { facts, error } = readFacts(file);
+ const r = error ? { status: "FAIL", checked: 0, problems: [{ claim: "(facts.json)", why: error }] } : checkFacts(claimsOf(f), facts);
+ console.log(`FACTS ${film} ${file}`);
+ for (const p of r.problems) console.log(` FAIL "${p.claim.slice(0, 60)}" ${p.why}`);
+ console.log(r.status === "N/A" ? `FACTS: N/A ${r.reason}` : r.status === "PASS" ? `FACTS: PASS ${r.checked} claim(s), each listed with its source or labelled generated` : `FACTS: FAIL ${r.problems.length} problem(s) in ${r.checked} claim(s)`);
+ process.exit(r.status === "FAIL" ? 1 : 0);
+}
diff --git a/plugins/anidoodle/skills/anidoodle/engine/tools/factsrules.mjs b/plugins/anidoodle/skills/anidoodle/engine/tools/factsrules.mjs
new file mode 100644
index 0000000..1f347d7
--- /dev/null
+++ b/plugins/anidoodle/skills/anidoodle/engine/tools/factsrules.mjs
@@ -0,0 +1,50 @@
+// FACTS RULES. The pure half of facts.mjs (no files, no browser), so it is unit-tested: what makes a
+// claim's entry well formed, and whether every claim a film declares is listed. See facts.mjs for the
+// file format and the command.
+export const normClaim = (s) => String(s ?? "").toLowerCase().replace(/\s+/g, " ").replace(/^[\s"'“”]+|[\s.!?:;"'“”]+$/g, "");
+const numbers = (s) => (String(s).match(/\d[\d.,]*\d|\d/g) ?? []).map((n) => n.replace(/[.,]+$/, ""));
+export const EMPTY_FACTS = { version: 1, about: "Every claim the film makes, on screen or narrated. Sourced: { claim, where, source: { sentence, url or file } }. Generated: { claim, where, generated: true, note }. Nothing invented.", claims: [] };
+
+/** One entry's own problems (shape only). */
+export const entryProblems = (e) => {
+ const out = [], claim = String(e?.claim ?? "").trim();
+ if (!claim) return ["has no claim text"];
+ if (/^todo\b/i.test(claim)) out.push("is still a TODO");
+ if (e.generated === true) {
+ if (!String(e.note ?? "").trim()) out.push("is generated but has no note saying what it is");
+ if (numbers(claim).length) out.push("is generated but states a number (a number needs a source)");
+ return out;
+ }
+ const src = e.source ?? {}, sentence = String(src.sentence ?? "").trim();
+ if (!sentence) out.push("has no source.sentence (the exact sentence it comes from)");
+ if (!String(src.url ?? "").trim() && !String(src.file ?? "").trim()) out.push("has no source.url or source.file");
+ else if (src.url && !/^https?:\/\/\S+$/i.test(String(src.url).trim())) out.push(`source.url '${src.url}' is not an http(s) link`);
+ if (sentence) { const have = new Set(numbers(sentence).map((n) => n.replace(/,/g, ""))); for (const n of numbers(claim)) if (!have.has(n.replace(/,/g, ""))) out.push(`states ${n}, which the source sentence does not`); }
+ return out;
+};
+
+/**
+ * claims: the strings a film declares (or undefined/empty). facts: the parsed facts.json, or null when absent.
+ * -> { status: "PASS" | "FAIL" | "N/A", checked, problems: [{ claim, why }] }
+ */
+export const checkFacts = (claims, facts) => {
+ const declared = [...new Set((Array.isArray(claims) ? claims : []).map((c) => String(c).trim()).filter(Boolean))];
+ if (!declared.length) return { status: "N/A", checked: 0, problems: [], reason: "the film declares no claims (film.claims), so nothing was checked" };
+ if (!facts) return { status: "FAIL", checked: declared.length, problems: declared.map((c) => ({ claim: c, why: "has no facts.json to be listed in (node tools/facts.mjs init)" })) };
+ const entries = Array.isArray(facts.claims) ? facts.claims : [], problems = [];
+ if (!Array.isArray(facts.claims)) problems.push({ claim: "(facts.json)", why: "has no claims array" });
+ const by = new Map(); for (const e of entries) { const k = normClaim(e?.claim); if (k && !by.has(k)) by.set(k, e); }
+ for (const c of declared) {
+ if (/^todo\b/i.test(c)) { problems.push({ claim: c, why: "is still a TODO in the film" }); continue; }
+ const e = by.get(normClaim(c));
+ if (!e) { problems.push({ claim: c, why: "is on screen but not listed in facts.json" }); continue; }
+ for (const why of entryProblems(e)) problems.push({ claim: c, why });
+ }
+ const declaredKeys = new Set(declared.map(normClaim));
+ for (const e of entries) if (!declaredKeys.has(normClaim(e?.claim))) for (const why of entryProblems(e)) problems.push({ claim: String(e?.claim ?? "(no claim)"), why }); // narrated and other listed claims are held to the same shape
+ return { status: problems.length ? "FAIL" : "PASS", checked: declared.length, problems };
+};
+
+/** The film's declared claims (a launch film: film.claims; any film may set film.claims or meta.claims). */
+export const claimsOf = (film) => film?.claims ?? film?.meta?.claims;
+
diff --git a/plugins/anidoodle/skills/anidoodle/engine/tools/launch.mjs b/plugins/anidoodle/skills/anidoodle/engine/tools/launch.mjs
index 900ba70..92048f1 100644
--- a/plugins/anidoodle/skills/anidoodle/engine/tools/launch.mjs
+++ b/plugins/anidoodle/skills/anidoodle/engine/tools/launch.mjs
@@ -2,36 +2,44 @@
//
// node tools/launch.mjs new <name> [--preset drawn|clean]
// writes src/canvas-core/<name>.ts (a launch template spec to fill from the brief: every line
-// that must come from the product is marked TODO) and its host page src/hosts/page-<name>.ts.
+// that must come from the product is marked TODO) and its host page src/hosts/page-<name>.ts,
+// and an empty facts.json beside the project (kept if one is there) for the claims and their sources.
// It renders as it is (placeholder plates and UI), so the pipeline can be proved before the art.
//
// node tools/launch.mjs ship <name> [--shapes 16x9,1x1,4x5,9x16] [--blur auto] [--shutter 180]
-// [--poster-frame N] [--gate]
+// [--poster-frame N] [--gate] [--strict-zones]
// for each shape, from ONE timeline (launchLayout re-composes it, never a crop):
// 1 render out/<name>-<shape>.mp4 (render.mjs; --blur/--shutter/--poster-frame pass through)
// 2 poster out/<name>-<shape>.poster.png, the film's own legible frame (meta.poster: the end card)
// 3 captions out/<name>-<shape>.srt and .vtt (the sidecar; captions: "burn" also burns them in)
// 4 verify verify-export --delivery: size, frame count, duration, the score, the sync of every
// marker, the true peak after the encode, a legible frame 0
-// 5 frame framecheck.mjs: no text and no card or window cut by the frame's edge, every frame
+// 5 frame framecheck.mjs: no text and no card or window cut by the frame's edge, every frame;
+// each text cue up for max(0.7 s, 0.3 s per word) (N/A without cues); on 9:16 no text in
+// the platforms' top, bottom or right-hand zones (FLAG only; --strict-zones makes it fail)
// 6 gate with --gate: gate.mjs (determinism, contract, dead air) on the rendered file
-// then one table. Exit 1 if any shape fails anything.
+// and once for the film, before the shapes: facts.mjs, every claim it makes is listed in facts.json
+// with its source (a film that makes no claims is N/A). Then one table. Exit 1 if anything fails.
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, writeFileSync } from "node:fs";
import { resolve } from "node:path";
import { knownFilms, requireFilm, SHAPE_NAMES } from "./names.mjs";
-import { filmMeta, writeCaptions } from "./captions.mjs";
+import { filmMeta, loadFilm, writeCaptions } from "./captions.mjs";
+import { checkFacts, claimsOf } from "./factsrules.mjs";
+import { initFacts, readFacts } from "./facts.mjs";
const [cmd, name, ...rest] = process.argv.slice(2);
const arg = (k, d) => { const i = rest.indexOf(`--${k}`); return i >= 0 ? rest[i + 1] : d; };
const die = (m) => { console.error(`launch: ${m}`); process.exit(2); };
-const USAGE = "node tools/launch.mjs new <name> [--preset drawn|clean]\n node tools/launch.mjs ship <name> [--shapes 16x9,1x1,4x5,9x16] [--blur auto] [--shutter 180] [--poster-frame N] [--gate]";
+const USAGE = "node tools/launch.mjs new <name> [--preset drawn|clean]\n node tools/launch.mjs ship <name> [--shapes 16x9,1x1,4x5,9x16] [--blur auto] [--shutter 180] [--poster-frame N] [--gate] [--strict-zones]";
const DRAWN = (n) => `// ${n}: a launch film on the template (references/workflows/launch-video-kit.md).
// Fill every TODO from the sourced brief (references/workflows/launch-video.md, "Ground it in the real
// product first"): the words on screen quote the brief, never memory. The plates below are STAND-INS
// (anidoodle's stock plates) so the film renders today; replace each with a plate drawn for YOUR
// product's subject, in the style the brief chose (references/styles.md).
+// Every claim the film makes (the words, the tagline) is listed in facts.json with its source sentence
+// and URL or file, or labelled generated (references/workflows/facts.md); ship checks it.
// node tools/still.mjs ${n}-9x16 --frames 0,120,330 --sheet out/${n}-9x16.jpg one look per shape, one browser
// node tools/launch.mjs ship ${n} --shapes 16x9,1x1,9x16
import { C } from "./launchKit";
@@ -57,7 +65,8 @@ export const ${n} = makeLaunchFilm({
});
`;
const CLEAN = (n) => `// ${n}: a UI-first launch film on the template, in the clean preset (a quiet canvas, one accent,
-// type as the design). Fill every TODO from the sourced brief; the UI data below is a STAND-IN:
+// type as the design). Fill every TODO from the sourced brief and list each claim in facts.json
+// (references/workflows/facts.md); the UI data below is a STAND-IN:
// replace it with your product's real screens and states (references/workflows/launch-video-kit.md).
// node tools/launch.mjs ship ${n} --shapes 16x9,9x16
import { makeLaunchFilm } from "./launchTemplate";
@@ -91,7 +100,8 @@ if (cmd === "new") {
if (existsSync(src) || existsSync(host) || knownFilms().includes(name)) die(`${name} already exists; pick another name (never overwritten)`);
writeFileSync(src, (preset === "clean" ? CLEAN : DRAWN)(name));
writeFileSync(host, `import { ${name} } from "../canvas-core/${name}";\nimport { mountFilm } from "./page";\n\nmountFilm(${name});\n`);
- console.log(`new launch film: ${src}\n host: ${host}\nnext: fill the TODOs from the brief, then\n node tools/still.mjs ${name} --frames 0,120,330 --sheet out/${name}.jpg\n node tools/launch.mjs ship ${name} --shapes 16x9,9x16`);
+ const made = initFacts(resolve("facts.json"));
+ console.log(`new launch film: ${src}\n host: ${host}\n facts: ${resolve("facts.json")}${made ? "" : " (already there, kept)"}\nnext: fill the TODOs from the brief and list every claim in facts.json, then\n node tools/still.mjs ${name} --frames 0,120,330 --sheet out/${name}.jpg\n node tools/launch.mjs ship ${name} --shapes 16x9,9x16`);
process.exit(0);
}
if (cmd !== "ship") die(`unknown command '${cmd ?? ""}'\nusage: ${USAGE}`);
@@ -103,7 +113,10 @@ const pass = ["blur", "shutter", "poster-frame", "blur-max", "blur-px"].flatMap(
const node = (args) => spawnSync(process.execPath, args, { stdio: "inherit" }).status === 0;
const quiet = (args) => { const r = spawnSync(process.execPath, args, { encoding: "utf8", maxBuffer: 1 << 26 }); return { ok: r.status === 0, out: (r.stdout ?? "") + (r.stderr ?? "") }; };
mkdirSync(resolve("out"), { recursive: true });
-const rows = [];
+const rows = [], zoneMode = rest.includes("--strict-zones") ? "fail" : "warn";
+const fx = readFacts(resolve("facts.json")), factsRes = fx.error ? { status: "FAIL", checked: 0, problems: [{ claim: "(facts.json)", why: fx.error }] } : checkFacts(claimsOf(await loadFilm(film)), fx.facts);
+console.log(`\nFACTS ${film}: ${factsRes.status}${factsRes.status === "N/A" ? ` ${factsRes.reason}` : ` ${factsRes.checked} claim(s)`}`);
+for (const p of factsRes.problems) console.log(` FAIL "${p.claim.slice(0, 60)}" ${p.why}`);
for (const sh of shapes) {
const f = `${film}-${sh}`, mp4 = `out/${f}.mp4`, row = { shape: sh, mp4, render: false, poster: "", captions: 0, verify: "", frame: "", gate: "" };
console.log(`\n==================== ${f} ====================`);
@@ -114,13 +127,13 @@ for (const sh of shapes) {
row.captions = (await writeCaptions(f)).count;
const v = quiet(["tools/verify-export.mjs", f, "--file", mp4, "--delivery"]); console.log(v.out.split("\n").filter((l) => /FAIL|PASS (frame|true peak|decoded)|VERIFY-EXPORT/.test(l)).join("\n"));
row.verify = (v.out.match(/VERIFY-EXPORT: (PASS|FAIL)[^\n]*/) ?? ["", "FAIL"])[0].replace("VERIFY-EXPORT: ", "");
- const fc = quiet(["tools/framecheck.mjs", f]); row.frame = (fc.out.match(/FRAMECHECK: (PASS|FAIL)[^\n]*/) ?? ["", "FAIL"])[0].replace("FRAMECHECK: ", ""); if (!fc.ok) console.log(fc.out.split("\n").filter((l) => /FAIL/.test(l)).join("\n"));
+ const fc = quiet(["tools/framecheck.mjs", f, "--zones", zoneMode]); row.frame = (fc.out.match(/FRAMECHECK: (PASS|FAIL)[^\n]*/) ?? ["", "FAIL"])[0].replace("FRAMECHECK: ", ""); console.log(fc.out.split("\n").filter((l) => /FAIL|FLAG/.test(l) && !/^FRAMECHECK/.test(l)).slice(0, 12).join("\n"));
if (rest.includes("--gate")) { const g = quiet(["tools/gate.mjs", f, "--mp4", mp4]); row.gate = (g.out.match(/GATE: (PASS|FAIL)[^\n]*/) ?? [g.ok ? "PASS" : "FAIL"])[0]; if (!g.ok) console.log(g.out.split("\n").filter((l) => /FAIL/.test(l)).join("\n")); }
}
rows.push(row);
}
-console.log(`\nSHIP ${film}`);
+console.log(`\nSHIP ${film}\n facts ${factsRes.status}${factsRes.status === "N/A" ? ` (${factsRes.reason})` : ` ${factsRes.checked} claim(s)${factsRes.problems.length ? `, ${factsRes.problems.length} problem(s)` : ""}`}`);
for (const r of rows) console.log(` ${r.shape.padEnd(5)} ${r.render ? r.mp4 : "RENDER FAILED"}\n verify ${r.verify || "-"}\n frame ${r.frame || "-"}${r.gate ? `\n gate ${r.gate}` : ""}\n poster ${r.poster || "-"} captions ${r.captions} cues -> out/${film}-${r.shape}.srt/.vtt`);
-const ok = rows.every((r) => r.render && /^PASS/.test(r.verify) && /^PASS/.test(r.frame) && r.poster !== "FAIL" && (!r.gate || /PASS/.test(r.gate)));
+const ok = factsRes.status !== "FAIL" && rows.every((r) => r.render && /^PASS/.test(r.verify) && /^PASS/.test(r.frame) && r.poster !== "FAIL" && (!r.gate || /PASS/.test(r.gate)));
console.log(ok ? `\nSHIP: PASS ${rows.length} shape(s)` : "\nSHIP: FAIL");
process.exit(ok ? 0 : 1);
diff --git a/plugins/anidoodle/skills/anidoodle/references/workflows/explainer.md b/plugins/anidoodle/skills/anidoodle/references/workflows/explainer.md
index 9b1cfc4..5da763e 100644
--- a/plugins/anidoodle/skills/anidoodle/references/workflows/explainer.md
+++ b/plugins/anidoodle/skills/anidoodle/references/workflows/explainer.md
@@ -6,11 +6,12 @@ the facts come before any drawing.
## The research ledger (before the storyboard)
-For every claim the piece makes: the claim in one sentence, the source (URL or exact passage),
-your confidence, and what you are simplifying. A claim you cannot source is cut or clearly shown
-as a metaphor. Numbers on screen come from the ledger, and each carries its source in a comment
-beside the code that draws it. Record the audience (age band, expertise) because it sets the
-reading level and the pace.
+The ledger is the film's `facts.json` (`facts.md`, for any film that makes claims). For every
+claim the piece makes: the claim, the exact source sentence and its URL or file. Beside it in
+your notes: your confidence, and what you are simplifying. A claim you cannot source is cut or
+clearly shown as a metaphor. Numbers on screen come from the ledger, and each carries its source
+in a comment beside the code that draws it. Record the audience (age band, expertise) because it
+sets the reading level and the pace.
## The storyboard (`STORYBOARD.md`)
@@ -25,8 +26,8 @@ review when the person wants that step; otherwise build from it.
on, never faded in. The drawing process (`drawing-process.md`) is the explainer's best tool:
the diagram assembling IS the explanation.
- **Captions are drawn lettering** (`lettering.ts`, `drafting.ts`, a style's own hand), sized for
- the smallest shape the piece ships in. Keep them short enough to read twice in their time on
- screen.
+ the smallest shape the piece ships in. Each stays up at least max(0.7 s, 0.3 s per word), and
+ longer for a young or non-expert audience (`craft-bar.md`).
- **A mechanism beats a diagram.** When the idea has moving parts, build it as a real machine that
comes apart and reads out its own state, in whichever style the piece uses: `machines.md`.
- **A recurring guide** (a mascot, a hand, an object) gives continuity across chapters; build it
diff --git a/plugins/anidoodle/skills/anidoodle/references/workflows/facts.md b/plugins/anidoodle/skills/anidoodle/references/workflows/facts.md
new file mode 100644
index 0000000..550cf05
--- /dev/null
+++ b/plugins/anidoodle/skills/anidoodle/references/workflows/facts.md
@@ -0,0 +1,48 @@
+# Facts: every claim has a source
+
+Any film that makes a claim, on screen or spoken, keeps a `facts.json`. It is the explainer's
+research ledger (`explainer.md`) made general, and the launch film's list of approved claims
+(`launch-video.md`). A viewer cannot check a film; this is how you can.
+
+## The rule
+
+- **Every claim is listed**: each line of words, each number, each label that asserts something,
+ and each narrated sentence.
+- **Each has its source**: the exact sentence it comes from, copied, and a URL or a file path.
+- **Nothing is invented.** No testimonial, rating, review, price, result, user count or real
+ person that the sources do not give. A quote needs its speaker and its page.
+- **What the film generates is labelled.** A slogan, a drawn scene, a mock screen, made-up sample
+ data: `generated: true` with a note saying what it is. A generated entry states no number; a
+ number needs a source.
+- **A claim you cannot source is cut**, or shown plainly as a metaphor.
+
+## The file
+
+```json
+{ "version": 1, "claims": [
+ { "claim": "Setup takes 40 minutes.", "where": "on-screen",
+ "source": { "sentence": "Setup takes about 40 minutes.", "url": "https://example.com/docs/start" } },
+ { "claim": "IDEA IN. ART OUT.", "where": "on-screen", "generated": true, "note": "slogan written for this film, states no fact" },
+ { "claim": "It runs offline.", "where": "narration",
+ "source": { "sentence": "No network is needed after install.", "file": "brief/readme.md#offline" } } ] }
+```
+
+`where` is `on-screen` or `narration`. `launch.mjs new <name>` writes an empty one beside the
+project and never overwrites one that is there; `node tools/facts.mjs init` does the same for
+any project.
+
+## The check
+
+`node tools/facts.mjs <film>` (and `launch.mjs ship`, once per film) reads the claims the film
+declares. A launch template film declares its type-frame words, its split words and its tagline,
+and any `claims: [...]` in its spec; any other film sets `film.claims`. It fails when:
+
+- a declared claim is not in `facts.json` (matched ignoring case, spacing and end punctuation);
+- a sourced entry lacks the sentence, or a URL (http/https) or file;
+- a generated entry has no note, or states a number;
+- a number in a sourced claim is not in its source sentence;
+- a claim is still a TODO.
+
+A film that declares no claims reports `N/A`, never a pass. The check is light on purpose: it
+cannot know a sentence is true. The critic does that by reading each source beside the film
+(`review.md`), and the delivery says which facts were independently checked.
diff --git a/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video-kit.md b/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video-kit.md
index ac31b8c..3d0fd27 100644
--- a/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video-kit.md
+++ b/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video-kit.md
@@ -20,8 +20,9 @@ node tools/launch.mjs ship myLaunch --shapes 16x9,1x1,9x16 --blur auto --gate
`ship` renders every shape to `out/myLaunch-<shape>.mp4`, writes its poster (`.poster.png`, the
film's own legible frame) and its captions (`.srt`, `.vtt`), runs `verify-export --delivery` on each
file (size, frames, score, A/V sync at every marker, the true peak after the encode, a legible frame
-0), `framecheck.mjs` on every frame (no text, no card, no product window cut by the frame's edge)
-and, with `--gate`, the gate; one table at the end, exit 1 if any shape fails.
+0), `framecheck.mjs` on every frame (no text, no card, no product window cut by the frame's edge;
+text held long enough to read; on 9:16 no text in the phone zones), `facts.mjs` once (every claim
+sourced) and, with `--gate`, the gate; one table at the end, exit 1 if any shape fails.
### Design review checklist (every shape, before anything ships)
@@ -31,6 +32,13 @@ contact sheet of EVERY shape against this list, and fix, never waive:
- **No clipped type.** Every word a viewer reads is whole on every frame: the typed prompt, the
bubbles, the labels, the words, the install lines. `framecheck.mjs` (run by `ship`) fails any
line of text the frame's edge cuts through.
+- **Time to read.** Each text up at least `max(0.7 s, 0.3 s per word)`, and never over a busy picture
+ without a plate (`craft-bar.md`). `framecheck.mjs` fails a declared cue held too briefly.
+- **Phone safe zones on 9:16.** No text in the top 14 %, the bottom 25 % or the right 14 % of the
+ frame, where the platforms put their own interface (`formats.md`). `ship` flags it per shape;
+ `--strict-zones` fails it.
+- **Every claim sourced.** The words, the tagline and any extra `claims` in the spec are listed in
+ `facts.json` with their source sentence and URL or file (`workflows/facts.md`); `ship` checks it.
- **No edge-cropped content.** A card, a product window, a film's card sits whole in the frame
with a margin, unless it is a deliberate full-bleed (the whole frame is that one thing). What
the camera is about to cut fades before it does. `framecheck.mjs` checks the cards and windows.
@@ -146,6 +154,7 @@ many subframes as each frame's measured on-screen speed needs (1 on a still fram
| `words[i]` | the type frame after `asks[i]` (not after the last ask; it flows into the end card) |
| `tagline`, `install[]`, `footer` | the end card; install lines are shown exactly as given |
| `bpm` (required), `fps` (30 or 60), `askBeats`, `typeBeats`, `endBeats` | the beat grid (a beat is 60 x 30 / bpm frames at 30 fps) and each part's length in beats |
+| `claims` | extra on-screen or narrated claims for `facts.json`; the words, split words and tagline are claims already |
| `claimBar` | land the end card on this bar's downbeat, counting from bar 0 (`claimBar: 4` = frame 4 x bar); throws if it cannot. A longer last ask is really longer, never slowed |
| `score` (required) or `audio` | the score composed for this product (the `Material` function compose.md writes, or a `Piece`), as a bed; `null` for silence; or your own finished mix (not checked; it replaces the cues too) |
| `shape`, `preset`, `sfx`, `motif`, `captions` | the frame (16x9 default); the look (drawn, clean); sound cues (default on); the relay into the end card (default on); `"sidecar"` (default) or `"burn"` |
diff --git a/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video.md b/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video.md
index 51b23df..277a173 100644
--- a/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video.md
+++ b/plugins/anidoodle/skills/anidoodle/references/workflows/launch-video.md
@@ -21,7 +21,8 @@ that invents its subject draws a mascot of a product, not the product.
components, the live page. Note the two or three REAL features a viewer should recognise on
screen, the exact product name and mark, the brand colours as hex.
2. **Collect approved claims.** The one-line promise and any numbers come from their own
- materials (site copy, release notes, README), each with its source next to it. Anything you
+ materials (site copy, release notes, README), each with its source next to it, in `facts.json`
+ (`facts.md`; `launch.mjs new` scaffolds it). Anything you
cannot source becomes a question, not a line in the film. List the claims the film must NOT make.
3. **Ask the grounding questions**, one message: which features to show (recommend your three),
which shapes to ship, where it will run, the exact CTA lines.
@@ -170,14 +171,15 @@ into place), round iris seams, the product's own UI. Pick one per film; never mi
5. **Music as an mp3 on a page**, heard by a human. ✋ Approval.
6. **Cut as data**: content scenes on one timeline, the cut as `pic`/`type` segments on the
beat grid (`launchCut.ts`). Re-timing edits the list, never scene code.
-7. **Review from the render**: contact sheets per beat, cuts as before/after pairs, DESIGN
- first (type over art, spacing, hierarchy), then timing. Render only the changed range
+7. **Review from the render, by a fresh critic** (`review.md`, three rounds at most): contact
+ sheets, cuts as before/after pairs, DESIGN first (type over art, spacing, hierarchy), then timing. Render only the changed range
(`render.mjs --from F --to T` writes `out/<film>.<F>-<T>.mp4`, silent). Give notes in camera words ("slow this zoom to 0.7x",
"hold the word 10 frames longer"), never "make it better".
8. **QA**: review every shape's contact sheet against the design checklist in
`launch-video-kit.md` (no clipped type, no edge-cropped content, balanced per shape, coherent
content). `launch.mjs ship <film> --shapes ... --gate` runs, for EVERY shape shipped, `framecheck`
- (text and cards whole on every frame), the gate
+ (text and cards whole on every frame; each text up long enough to read; on 9:16 nothing under
+ the phone UI; `craft-bar.md`), `facts.mjs` (every claim sourced, `facts.md`), the gate
(determinism, contract, dead air; declare real holds in `meta.holds`, each with its reason)
and `verify-export --delivery` (size, frames, score, sync, true peak, a legible frame 0), and
writes the poster and captions; add `verify-export <film>-<shape> --first-frame #rrggbb` for a
diff --git a/skills/anidoodle/SKILL.md b/skills/anidoodle/SKILL.md
index 6d84259..b465b34 100644
--- a/skills/anidoodle/SKILL.md
+++ b/skills/anidoodle/SKILL.md
@@ -36,7 +36,7 @@ say why in one line. Write the answers into a short brief before drawing.
| A loop, sticker, animated logo, ambient header | Loop workflow below, `references/formats.md` |
| A story film, any length | Film workflow below, `references/workflows/long-film.md` |
| An explainer or infographic; a machine that comes apart to explain an idea, in any style | `references/workflows/explainer.md`, `references/workflows/machines.md` |
-| A launch or product video (their screenshots welcome) | `references/workflows/launch-video.md`; build it on `references/workflows/launch-video-kit.md` |
+| A launch or product video (their screenshots welcome) | `references/workflows/launch-video.md`; build it on `references/workflows/launch-video-kit.md`; its claims: `references/workflows/facts.md` |
| Art for a site (hero by a headline, tiles, spots, share card) on its page colour and brand; or a web animation that reacts to the UI | `references/workflows/site-art.md`; `references/workflows/interactive.md` |
| A drawing lesson, or "how do I draw this?" | `references/workflows/teach-drawing.md` |
| A character kept identical in any style (woodcut to toy brick) | `references/workflows/character-consistency.md`, `references/anatomy.md` |
@@ -82,9 +82,9 @@ longer films, a spine plus one line per chapter. If you cannot write it, stop. (
a beat is 60 x fps / bpm frames, the bpm from the brief's score; one cue table holds every frame number and a checker
runs at load. (3) **Real reference** for anything that exists. (4) **ONE look still**, the hardest
frame, critiqued in writing. ✋ **Approval.** (5) **ONE 8-second music sample.** ✋ **Approval.**
-(6) **Build the whole film**; mechanical checks run continuously. (7) **Review once** from the
-rendered file, as four readings with a scorecard (`references/workflows/review.md`). One ranked fix
-list, one rebuild. (8) ✋ **Final approval.** Say what you verified and what you cannot.
+(6) **Build the whole film**; mechanical checks run continuously. (7) **A fresh critic reviews, never you**
+(`references/workflows/review.md`): after the storyboard, each scene and the full render, a new subagent that saw none of the building returns ranked, timestamped problems and a verdict. Fix the biggest, a NEW critic rechecks; 3 rounds at most, logged in `ledger.md`.
+(8) ✋ **Final approval.** Say what you verified and what you cannot.
Three approval gates at most. Approval is a budget; spend it where being wrong is expensive.
@@ -125,7 +125,7 @@ node <skill>/engine/tools/soundfetch.mjs get piano rooms # on their yes (piano
| `registry.mjs` / `gallery.mjs` | the style list from the plates themselves / the gallery sheet |
| `docs-check.mjs` | fails when any doc's style count, length or path disagrees with the code |
| `verify-export.mjs` | QA on the rendered file: frames, duration, score, A/V sync, true peak after the encode; opt-in first frame, loop seam, `--delivery` |
-| `launch.mjs` | a launch film: `new <name>` scaffolds the spec; `ship <name> --shapes 16x9,9x16` renders, posters, captions, verifies and framechecks each (`framecheck.mjs`: no text cut by the frame's edge) |
+| `launch.mjs` | a launch film: `new <name>` scaffolds the spec; `ship <name> --shapes 16x9,9x16` renders, posters, captions, verifies and framechecks each (`framecheck.mjs`: text whole, up long enough to read, clear of the 9:16 phone zones) and checks `facts.json` (`facts.mjs`) |
| `test.mjs` (`npm test`) | unit suites in `engine/test/`, no browser |
| `music.mjs` | `vocab` prints a style's vocabulary; `check` gates your composed score (key, master, guards, stems, novelty, which parts played recordings) and prints its shape (ARC); `render`, `meter` |
| `soundfetch.mjs` | the sound pack: `list`, `get <id...\|all>`, `where`, `verify`, `remove <id>` |
diff --git a/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts b/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts
index 93c744f..c9391ce 100644
--- a/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts
+++ b/skills/anidoodle/engine/src/canvas-core/launchTemplate.ts
@@ -88,6 +88,7 @@ export type LaunchSpec = {
sfx?: boolean; // sound cues from the picture's timing (default true; false = the score alone)
motif?: boolean; // the relay into the end card (default true): the drop becomes the mark's dot
captions?: "sidecar" | "burn"; // .srt/.vtt only (default), or also burned into their own band (phone shapes)
+ claims?: string[]; // any other on-screen or narrated claim (a number in the UI, a spoken line); the words, split words and tagline are claims already
};
// the clean preset: a quiet canvas, one accent, type as the design. Our own palette, drawn for it.
@@ -137,6 +138,7 @@ export type LaunchFilm = Omit<Film, "reshape"> & {
seams: Seam[]; // the motif's seams, each checked (checkRelay)
timing: { base: number; len: number; tin: number; b: number; down: number; up: number; drop: Drop; times: number[] }[]; // each ask's own timing, content frames at 30 fps
captions: { from: number; to: number; text: string }[]; // = meta.captions
+ claims: string[]; // every claim the film makes, each to be listed in facts.json with its source (tools/facts.mjs)
};
export const makeLaunchFilm = (spec: LaunchSpec): LaunchFilm => {
const fps = spec.fps ?? 30, m = fps / 30, n = spec.asks.length, shape = spec.shape ?? "16x9", clean = spec.preset === "clean";
@@ -558,6 +560,7 @@ export const makeLaunchFilm = (spec: LaunchSpec): LaunchFilm => {
assets: { images: {} },
shots: [{ id: "cut", start: 0, end: cut.N * m, draw }],
audio,
+ claims: [...new Set([...words.flat().map((x) => x.text), ...spec.asks.flatMap((a) => (isChat(a) ? [] : (a.split ?? []).map((x) => x.text))), spec.tagline, ...(spec.claims ?? [])].map((x) => x.trim()).filter(Boolean))],
cut, layout: L, cues, seams, heroPx: HERO ? HERO.TEXT.px : null, timing: T, captions: caps.map((c) => ({ from: Math.round(c.from * m), to: Math.round(c.to * m), text: c.text })),
// the same film composed for another frame shape (one timeline: the cut, the timing and the sound do not change)
reshape: (s: string) => { if (s === shape) return self; memo ??= new Map(); let f = memo.get(s); if (!f) { f = makeLaunchFilm({ ...spec, shape: s as Shape }); memo.set(s, f); } return f; },
diff --git a/skills/anidoodle/engine/test/facts.test.ts b/skills/anidoodle/engine/test/facts.test.ts
new file mode 100644
index 0000000..197e4cc
--- /dev/null
+++ b/skills/anidoodle/engine/test/facts.test.ts
@@ -0,0 +1,42 @@
+// FACTS TESTS. Every claim a film declares must be listed in facts.json with its source, or labelled
+// generated; nothing invented. Held to known answers, with the failing cases.
+// @ts-ignore: a plain ES module shared with the tools
+import { checkFacts, entryProblems, normClaim, EMPTY_FACTS } from "../tools/factsrules.mjs";
+import { makeLaunchFilm } from "../src/canvas-core/launchTemplate";
+import type { Film } from "../src/canvas-core/film";
+
+export const name = "facts";
+export const run = (ok: (cond: boolean, label: string) => void) => {
+ const src = { sentence: "Setup takes about 40 minutes.", url: "https://example.com/docs" };
+ const good = { claim: "Ships in 40 minutes.", where: "on-screen", source: src };
+ const slogan = { claim: "IDEA IN.", where: "on-screen", generated: true, note: "slogan written for this film" };
+ const facts = { version: 1, claims: [good, slogan] };
+ ok(normClaim(" Ships IN 40 minutes! ") === normClaim("ships in 40 minutes."), "claims match ignoring case, spacing and end punctuation");
+ ok(checkFacts(["Ships in 40 minutes.", "IDEA IN."], facts).status === "PASS", "every claim listed with a source or labelled generated passes");
+ ok(checkFacts([], facts).status === "N/A" && checkFacts(undefined, facts).status === "N/A", "a film that declares no claims is N/A, never a pass");
+
+ const missing = checkFacts(["Ships in 40 minutes.", "Loved by 10,000 teams."], facts);
+ ok(missing.status === "FAIL" && missing.problems.length === 1 && /not listed/.test(missing.problems[0].why), "NEGATIVE: a claim missing from facts.json fails");
+ ok(checkFacts(["IDEA IN."], null).status === "FAIL", "NEGATIVE: claims with no facts.json fail");
+ ok(checkFacts(["IDEA IN."], EMPTY_FACTS).status === "FAIL", "NEGATIVE: the empty scaffold fails until the claims are listed");
+ ok(checkFacts(["TODO CLAIM."], { claims: [{ claim: "TODO CLAIM.", generated: true, note: "x" }] }).status === "FAIL", "NEGATIVE: a TODO is not a claim");
+
+ const bad = (e: object) => entryProblems(e).join("; ");
+ ok(/source.sentence/.test(bad({ claim: "c", source: { url: "https://a.b" } })), "NEGATIVE: a sourced claim needs the exact sentence");
+ ok(/source.url or source.file/.test(bad({ claim: "c", source: { sentence: "c" } })), "NEGATIVE: a sourced claim needs a URL or a file");
+ ok(bad({ claim: "c", source: { sentence: "c", file: "notes/brief.md#2" } }) === "", "a file is a source too");
+ ok(/not an http/.test(bad({ claim: "c", source: { sentence: "c", url: "ftp://x" } })), "NEGATIVE: a source URL is http(s)");
+ ok(/no note/.test(bad({ claim: "c", generated: true })), "NEGATIVE: generated content must say what it is");
+ ok(/states a number/.test(bad({ claim: "5 stars", generated: true, note: "n" })), "NEGATIVE: a generated claim cannot state a number (no invented ratings or prices)");
+ ok(/states 99/.test(bad({ claim: "Saves 99% of time", source: src })), "NEGATIVE: a number the source sentence does not contain is caught");
+ ok(bad({ claim: "Takes 40 minutes", source: src }) === "", "a number that is in the source passes");
+ ok(checkFacts(["Ships in 40 minutes."], { claims: [{ ...good, source: { ...src, sentence: "" } }] }).status === "FAIL", "an entry with an empty sentence fails");
+ ok(checkFacts(["IDEA IN."], { claims: [slogan, { claim: "Narrated: best in class", where: "narration" }] }).status === "FAIL", "NEGATIVE: a narrated claim listed with no source fails too");
+
+ // the launch template declares its claims: the type-frame words, the split words and the tagline
+ const plate: Film = { meta: { title: "plate", W: 1080, H: 1080, fps: 30, bpm: 120, durationFrames: 60 }, assets: { images: {} }, shots: [{ id: "p", start: 0, end: 60, draw: () => {} }] };
+ const film = makeLaunchFilm({ title: "Tally", asks: [{ prompt: "draw it", plate, label: "l" }, { prompt: "again", plate, label: "l" }], words: [[{ text: "ONE.", style: "ink", color: "#111" }, { text: "TWO.", style: "ink", color: "#111" }]], tagline: "Counts things.", install: ["npm i tally"], bpm: 120, askBeats: 8, endBeats: 12, sfx: false, score: null, claims: ["Fast.", "ONE."] });
+ ok(film.claims.join("|") === "ONE.|TWO.|Counts things.|Fast.", `a launch film declares its words, tagline and extra claims once each (${film.claims.join("|")})`);
+ ok(film.reshape("9x16").claims.join("|") === film.claims.join("|"), "the claims are the same in every shape");
+ ok(!film.claims.includes("draw it") && !film.claims.includes("npm i tally"), "prompts and install lines are not claims");
+};
diff --git a/skills/anidoodle/engine/tools/captions.mjs b/skills/anidoodle/engine/tools/captions.mjs
index 7b942d4..9fbd427 100644
--- a/skills/anidoodle/engine/tools/captions.mjs
+++ b/skills/anidoodle/engine/tools/captions.mjs
@@ -12,12 +12,13 @@ import { requireFilm, splitShape } from "./names.mjs";
import { toSrt, toVtt } from "./avsync.mjs";
import { isMain } from "./is-main.mjs";
-export const filmMeta = async (name) => {
+export const loadFilm = async (name) => {
const { base, shape } = splitShape(name);
const js = (await build({ stdin: { contents: `export { ${base} as film } from "./src/canvas-core/${base}";`, resolveDir: process.cwd(), loader: "ts" }, bundle: true, format: "esm", write: false, platform: "neutral", plugins: [overlay], logLevel: "error" })).outputFiles[0].text;
const { film } = await import("data:text/javascript;base64," + Buffer.from(js).toString("base64"));
- return (shape ? film.reshape(shape) : film).meta;
+ return shape ? film.reshape(shape) : film;
};
+export const filmMeta = async (name) => (await loadFilm(name)).meta;
export const writeCaptions = async (name, out = `out/${name}`) => {
const meta = await filmMeta(name), caps = meta.captions ?? [];
if (!caps.length) return { count: 0, files: [] };
diff --git a/skills/anidoodle/engine/tools/facts.mjs b/skills/anidoodle/engine/tools/facts.mjs
new file mode 100644
index 0000000..0e17fda
--- /dev/null
+++ b/skills/anidoodle/engine/tools/facts.mjs
@@ -0,0 +1,42 @@
+// FACTS. Every claim a film makes, on screen or narrated, is listed in facts.json with the exact
+// sentence it comes from and where that sentence lives (a URL or a file). Nothing is invented: no
+// testimonial, rating, price, result or real person. What the film generates (a slogan, a drawn
+// scene, a mock UI) is labelled `generated`. This is the explainer's research ledger, for any film.
+//
+// facts.json
+// { "version": 1, "claims": [
+// { "claim": "Ships in 40 minutes.", "where": "on-screen",
+// "source": { "sentence": "Setup takes about 40 minutes.", "url": "https://example.com/docs" } },
+// { "claim": "IDEA IN. ART OUT.", "where": "on-screen", "generated": true, "note": "slogan written for this film, states no fact" } ] }
+//
+// node tools/facts.mjs <film>[-<shape>] [--facts facts.json] every claim the film declares is listed and well formed
+// node tools/facts.mjs init [--facts facts.json] write an empty facts.json (never overwrites)
+//
+// A film declares its claims as `film.claims` (a launch template film: the type-frame words, the split
+// words and the tagline, plus any `claims: [...]` in its spec). A film that declares none is N/A,
+// never a pass. The check is light on purpose: it cannot know a sentence is true, so it holds what it can.
+// - every declared claim has an entry (matched ignoring case, spacing and end punctuation);
+// - a sourced entry has the exact sentence and a URL (http/https) or a file;
+// - a generated entry says what it is, and states no number (a number needs a source);
+// - every number in a sourced claim appears in its source sentence;
+// - a TODO is not a claim yet.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { isMain } from "./is-main.mjs";
+import { EMPTY_FACTS, checkFacts, claimsOf } from "./factsrules.mjs";
+
+export const readFacts = (file) => { if (!existsSync(file)) return { facts: null }; try { return { facts: JSON.parse(readFileSync(file, "utf8")) }; } catch (e) { return { facts: null, error: `${file} is not valid JSON: ${e.message}` }; } };
+export const initFacts = (file) => { if (existsSync(file)) return false; writeFileSync(file, JSON.stringify(EMPTY_FACTS, null, 2) + "\n"); return true; };
+
+if (isMain(import.meta.url)) {
+ const argv = process.argv.slice(2), fi = argv.indexOf("--facts"), file = resolve(fi >= 0 ? argv[fi + 1] : "facts.json"), name = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--facts");
+ const USAGE = "node tools/facts.mjs <film>[-<shape>] [--facts facts.json]\n node tools/facts.mjs init [--facts facts.json]";
+ if (name === "init") { console.log(initFacts(file) ? `facts: wrote ${file}` : `facts: ${file} already exists; left as it is`); process.exit(0); }
+ const { requireFilm } = await import("./names.mjs"), { loadFilm } = await import("./captions.mjs");
+ const film = requireFilm(name, "facts", USAGE), f = await loadFilm(film), { facts, error } = readFacts(file);
+ const r = error ? { status: "FAIL", checked: 0, problems: [{ claim: "(facts.json)", why: error }] } : checkFacts(claimsOf(f), facts);
+ console.log(`FACTS ${film} ${file}`);
+ for (const p of r.problems) console.log(` FAIL "${p.claim.slice(0, 60)}" ${p.why}`);
+ console.log(r.status === "N/A" ? `FACTS: N/A ${r.reason}` : r.status === "PASS" ? `FACTS: PASS ${r.checked} claim(s), each listed with its source or labelled generated` : `FACTS: FAIL ${r.problems.length} problem(s) in ${r.checked} claim(s)`);
+ process.exit(r.status === "FAIL" ? 1 : 0);
+}
diff --git a/skills/anidoodle/engine/tools/factsrules.mjs b/skills/anidoodle/engine/tools/factsrules.mjs
new file mode 100644
index 0000000..1f347d7
--- /dev/null
+++ b/skills/anidoodle/engine/tools/factsrules.mjs
@@ -0,0 +1,50 @@
+// FACTS RULES. The pure half of facts.mjs (no files, no browser), so it is unit-tested: what makes a
+// claim's entry well formed, and whether every claim a film declares is listed. See facts.mjs for the
+// file format and the command.
+export const normClaim = (s) => String(s ?? "").toLowerCase().replace(/\s+/g, " ").replace(/^[\s"'“”]+|[\s.!?:;"'“”]+$/g, "");
+const numbers = (s) => (String(s).match(/\d[\d.,]*\d|\d/g) ?? []).map((n) => n.replace(/[.,]+$/, ""));
+export const EMPTY_FACTS = { version: 1, about: "Every claim the film makes, on screen or narrated. Sourced: { claim, where, source: { sentence, url or file } }. Generated: { claim, where, generated: true, note }. Nothing invented.", claims: [] };
+
+/** One entry's own problems (shape only). */
+export const entryProblems = (e) => {
+ const out = [], claim = String(e?.claim ?? "").trim();
+ if (!claim) return ["has no claim text"];
+ if (/^todo\b/i.test(claim)) out.push("is still a TODO");
+ if (e.generated === true) {
+ if (!String(e.note ?? "").trim()) out.push("is generated but has no note saying what it is");
+ if (numbers(claim).length) out.push("is generated but states a number (a number needs a source)");
+ return out;
+ }
+ const src = e.source ?? {}, sentence = String(src.sentence ?? "").trim();
+ if (!sentence) out.push("has no source.sentence (the exact sentence it comes from)");
+ if (!String(src.url ?? "").trim() && !String(src.file ?? "").trim()) out.push("has no source.url or source.file");
+ else if (src.url && !/^https?:\/\/\S+$/i.test(String(src.url).trim())) out.push(`source.url '${src.url}' is not an http(s) link`);
+ if (sentence) { const have = new Set(numbers(sentence).map((n) => n.replace(/,/g, ""))); for (const n of numbers(claim)) if (!have.has(n.replace(/,/g, ""))) out.push(`states ${n}, which the source sentence does not`); }
+ return out;
+};
+
+/**
+ * claims: the strings a film declares (or undefined/empty). facts: the parsed facts.json, or null when absent.
+ * -> { status: "PASS" | "FAIL" | "N/A", checked, problems: [{ claim, why }] }
+ */
+export const checkFacts = (claims, facts) => {
+ const declared = [...new Set((Array.isArray(claims) ? claims : []).map((c) => String(c).trim()).filter(Boolean))];
+ if (!declared.length) return { status: "N/A", checked: 0, problems: [], reason: "the film declares no claims (film.claims), so nothing was checked" };
+ if (!facts) return { status: "FAIL", checked: declared.length, problems: declared.map((c) => ({ claim: c, why: "has no facts.json to be listed in (node tools/facts.mjs init)" })) };
+ const entries = Array.isArray(facts.claims) ? facts.claims : [], problems = [];
+ if (!Array.isArray(facts.claims)) problems.push({ claim: "(facts.json)", why: "has no claims array" });
+ const by = new Map(); for (const e of entries) { const k = normClaim(e?.claim); if (k && !by.has(k)) by.set(k, e); }
+ for (const c of declared) {
+ if (/^todo\b/i.test(c)) { problems.push({ claim: c, why: "is still a TODO in the film" }); continue; }
+ const e = by.get(normClaim(c));
+ if (!e) { problems.push({ claim: c, why: "is on screen but not listed in facts.json" }); continue; }
+ for (const why of entryProblems(e)) problems.push({ claim: c, why });
+ }
+ const declaredKeys = new Set(declared.map(normClaim));
+ for (const e of entries) if (!declaredKeys.has(normClaim(e?.claim))) for (const why of entryProblems(e)) problems.push({ claim: String(e?.claim ?? "(no claim)"), why }); // narrated and other listed claims are held to the same shape
+ return { status: problems.length ? "FAIL" : "PASS", checked: declared.length, problems };
+};
+
+/** The film's declared claims (a launch film: film.claims; any film may set film.claims or meta.claims). */
+export const claimsOf = (film) => film?.claims ?? film?.meta?.claims;
+
diff --git a/skills/anidoodle/engine/tools/launch.mjs b/skills/anidoodle/engine/tools/launch.mjs
index 900ba70..92048f1 100644
--- a/skills/anidoodle/engine/tools/launch.mjs
+++ b/skills/anidoodle/engine/tools/launch.mjs
@@ -2,36 +2,44 @@
//
// node tools/launch.mjs new <name> [--preset drawn|clean]
// writes src/canvas-core/<name>.ts (a launch template spec to fill from the brief: every line
-// that must come from the product is marked TODO) and its host page src/hosts/page-<name>.ts.
+// that must come from the product is marked TODO) and its host page src/hosts/page-<name>.ts,
+// and an empty facts.json beside the project (kept if one is there) for the claims and their sources.
// It renders as it is (placeholder plates and UI), so the pipeline can be proved before the art.
//
// node tools/launch.mjs ship <name> [--shapes 16x9,1x1,4x5,9x16] [--blur auto] [--shutter 180]
-// [--poster-frame N] [--gate]
+// [--poster-frame N] [--gate] [--strict-zones]
// for each shape, from ONE timeline (launchLayout re-composes it, never a crop):
// 1 render out/<name>-<shape>.mp4 (render.mjs; --blur/--shutter/--poster-frame pass through)
// 2 poster out/<name>-<shape>.poster.png, the film's own legible frame (meta.poster: the end card)
// 3 captions out/<name>-<shape>.srt and .vtt (the sidecar; captions: "burn" also burns them in)
// 4 verify verify-export --delivery: size, frame count, duration, the score, the sync of every
// marker, the true peak after the encode, a legible frame 0
-// 5 frame framecheck.mjs: no text and no card or window cut by the frame's edge, every frame
+// 5 frame framecheck.mjs: no text and no card or window cut by the frame's edge, every frame;
+// each text cue up for max(0.7 s, 0.3 s per word) (N/A without cues); on 9:16 no text in
+// the platforms' top, bottom or right-hand zones (FLAG only; --strict-zones makes it fail)
// 6 gate with --gate: gate.mjs (determinism, contract, dead air) on the rendered file
-// then one table. Exit 1 if any shape fails anything.
+// and once for the film, before the shapes: facts.mjs, every claim it makes is listed in facts.json
+// with its source (a film that makes no claims is N/A). Then one table. Exit 1 if anything fails.
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, writeFileSync } from "node:fs";
import { resolve } from "node:path";
import { knownFilms, requireFilm, SHAPE_NAMES } from "./names.mjs";
-import { filmMeta, writeCaptions } from "./captions.mjs";
+import { filmMeta, loadFilm, writeCaptions } from "./captions.mjs";
+import { checkFacts, claimsOf } from "./factsrules.mjs";
+import { initFacts, readFacts } from "./facts.mjs";
const [cmd, name, ...rest] = process.argv.slice(2);
const arg = (k, d) => { const i = rest.indexOf(`--${k}`); return i >= 0 ? rest[i + 1] : d; };
const die = (m) => { console.error(`launch: ${m}`); process.exit(2); };
-const USAGE = "node tools/launch.mjs new <name> [--preset drawn|clean]\n node tools/launch.mjs ship <name> [--shapes 16x9,1x1,4x5,9x16] [--blur auto] [--shutter 180] [--poster-frame N] [--gate]";
+const USAGE = "node tools/launch.mjs new <name> [--preset drawn|clean]\n node tools/launch.mjs ship <name> [--shapes 16x9,1x1,4x5,9x16] [--blur auto] [--shutter 180] [--poster-frame N] [--gate] [--strict-zones]";
const DRAWN = (n) => `// ${n}: a launch film on the template (references/workflows/launch-video-kit.md).
// Fill every TODO from the sourced brief (references/workflows/launch-video.md, "Ground it in the real
// product first"): the words on screen quote the brief, never memory. The plates below are STAND-INS
// (anidoodle's stock plates) so the film renders today; replace each with a plate drawn for YOUR
// product's subject, in the style the brief chose (references/styles.md).
+// Every claim the film makes (the words, the tagline) is listed in facts.json with its source sentence
+// and URL or file, or labelled generated (references/workflows/facts.md); ship checks it.
// node tools/still.mjs ${n}-9x16 --frames 0,120,330 --sheet out/${n}-9x16.jpg one look per shape, one browser
// node tools/launch.mjs ship ${n} --shapes 16x9,1x1,9x16
import { C } from "./launchKit";
@@ -57,7 +65,8 @@ export const ${n} = makeLaunchFilm({
});
`;
const CLEAN = (n) => `// ${n}: a UI-first launch film on the template, in the clean preset (a quiet canvas, one accent,
-// type as the design). Fill every TODO from the sourced brief; the UI data below is a STAND-IN:
+// type as the design). Fill every TODO from the sourced brief and list each claim in facts.json
+// (references/workflows/facts.md); the UI data below is a STAND-IN:
// replace it with your product's real screens and states (references/workflows/launch-video-kit.md).
// node tools/launch.mjs ship ${n} --shapes 16x9,9x16
import { makeLaunchFilm } from "./launchTemplate";
@@ -91,7 +100,8 @@ if (cmd === "new") {
if (existsSync(src) || existsSync(host) || knownFilms().includes(name)) die(`${name} already exists; pick another name (never overwritten)`);
writeFileSync(src, (preset === "clean" ? CLEAN : DRAWN)(name));
writeFileSync(host, `import { ${name} } from "../canvas-core/${name}";\nimport { mountFilm } from "./page";\n\nmountFilm(${name});\n`);
- console.log(`new launch film: ${src}\n host: ${host}\nnext: fill the TODOs from the brief, then\n node tools/still.mjs ${name} --frames 0,120,330 --sheet out/${name}.jpg\n node tools/launch.mjs ship ${name} --shapes 16x9,9x16`);
+ const made = initFacts(resolve("facts.json"));
+ console.log(`new launch film: ${src}\n host: ${host}\n facts: ${resolve("facts.json")}${made ? "" : " (already there, kept)"}\nnext: fill the TODOs from the brief and list every claim in facts.json, then\n node tools/still.mjs ${name} --frames 0,120,330 --sheet out/${name}.jpg\n node tools/launch.mjs ship ${name} --shapes 16x9,9x16`);
process.exit(0);
}
if (cmd !== "ship") die(`unknown command '${cmd ?? ""}'\nusage: ${USAGE}`);
@@ -103,7 +113,10 @@ const pass = ["blur", "shutter", "poster-frame", "blur-max", "blur-px"].flatMap(
const node = (args) => spawnSync(process.execPath, args, { stdio: "inherit" }).status === 0;
const quiet = (args) => { const r = spawnSync(process.execPath, args, { encoding: "utf8", maxBuffer: 1 << 26 }); return { ok: r.status === 0, out: (r.stdout ?? "") + (r.stderr ?? "") }; };
mkdirSync(resolve("out"), { recursive: true });
-const rows = [];
+const rows = [], zoneMode = rest.includes("--strict-zones") ? "fail" : "warn";
+const fx = readFacts(resolve("facts.json")), factsRes = fx.error ? { status: "FAIL", checked: 0, problems: [{ claim: "(facts.json)", why: fx.error }] } : checkFacts(claimsOf(await loadFilm(film)), fx.facts);
+console.log(`\nFACTS ${film}: ${factsRes.status}${factsRes.status === "N/A" ? ` ${factsRes.reason}` : ` ${factsRes.checked} claim(s)`}`);
+for (const p of factsRes.problems) console.log(` FAIL "${p.claim.slice(0, 60)}" ${p.why}`);
for (const sh of shapes) {
const f = `${film}-${sh}`, mp4 = `out/${f}.mp4`, row = { shape: sh, mp4, render: false, poster: "", captions: 0, verify: "", frame: "", gate: "" };
console.log(`\n==================== ${f} ====================`);
@@ -114,13 +127,13 @@ for (const sh of shapes) {
row.captions = (await writeCaptions(f)).count;
const v = quiet(["tools/verify-export.mjs", f, "--file", mp4, "--delivery"]); console.log(v.out.split("\n").filter((l) => /FAIL|PASS (frame|true peak|decoded)|VERIFY-EXPORT/.test(l)).join("\n"));
row.verify = (v.out.match(/VERIFY-EXPORT: (PASS|FAIL)[^\n]*/) ?? ["", "FAIL"])[0].replace("VERIFY-EXPORT: ", "");
- const fc = quiet(["tools/framecheck.mjs", f]); row.frame = (fc.out.match(/FRAMECHECK: (PASS|FAIL)[^\n]*/) ?? ["", "FAIL"])[0].replace("FRAMECHECK: ", ""); if (!fc.ok) console.log(fc.out.split("\n").filter((l) => /FAIL/.test(l)).join("\n"));
+ const fc = quiet(["tools/framecheck.mjs", f, "--zones", zoneMode]); row.frame = (fc.out.match(/FRAMECHECK: (PASS|FAIL)[^\n]*/) ?? ["", "FAIL"])[0].replace("FRAMECHECK: ", ""); console.log(fc.out.split("\n").filter((l) => /FAIL|FLAG/.test(l) && !/^FRAMECHECK/.test(l)).slice(0, 12).join("\n"));
if (rest.includes("--gate")) { const g = quiet(["tools/gate.mjs", f, "--mp4", mp4]); row.gate = (g.out.match(/GATE: (PASS|FAIL)[^\n]*/) ?? [g.ok ? "PASS" : "FAIL"])[0]; if (!g.ok) console.log(g.out.split("\n").filter((l) => /FAIL/.test(l)).join("\n")); }
}
rows.push(row);
}
-console.log(`\nSHIP ${film}`);
+console.log(`\nSHIP ${film}\n facts ${factsRes.status}${factsRes.status === "N/A" ? ` (${factsRes.reason})` : ` ${factsRes.checked} claim(s)${factsRes.problems.length ? `, ${factsRes.problems.length} problem(s)` : ""}`}`);
for (const r of rows) console.log(` ${r.shape.padEnd(5)} ${r.render ? r.mp4 : "RENDER FAILED"}\n verify ${r.verify || "-"}\n frame ${r.frame || "-"}${r.gate ? `\n gate ${r.gate}` : ""}\n poster ${r.poster || "-"} captions ${r.captions} cues -> out/${film}-${r.shape}.srt/.vtt`);
-const ok = rows.every((r) => r.render && /^PASS/.test(r.verify) && /^PASS/.test(r.frame) && r.poster !== "FAIL" && (!r.gate || /PASS/.test(r.gate)));
+const ok = factsRes.status !== "FAIL" && rows.every((r) => r.render && /^PASS/.test(r.verify) && /^PASS/.test(r.frame) && r.poster !== "FAIL" && (!r.gate || /PASS/.test(r.gate)));
console.log(ok ? `\nSHIP: PASS ${rows.length} shape(s)` : "\nSHIP: FAIL");
process.exit(ok ? 0 : 1);
diff --git a/skills/anidoodle/references/workflows/explainer.md b/skills/anidoodle/references/workflows/explainer.md
index 9b1cfc4..5da763e 100644
--- a/skills/anidoodle/references/workflows/explainer.md
+++ b/skills/anidoodle/references/workflows/explainer.md
@@ -6,11 +6,12 @@ the facts come before any drawing.
## The research ledger (before the storyboard)
-For every claim the piece makes: the claim in one sentence, the source (URL or exact passage),
-your confidence, and what you are simplifying. A claim you cannot source is cut or clearly shown
-as a metaphor. Numbers on screen come from the ledger, and each carries its source in a comment
-beside the code that draws it. Record the audience (age band, expertise) because it sets the
-reading level and the pace.
+The ledger is the film's `facts.json` (`facts.md`, for any film that makes claims). For every
+claim the piece makes: the claim, the exact source sentence and its URL or file. Beside it in
+your notes: your confidence, and what you are simplifying. A claim you cannot source is cut or
+clearly shown as a metaphor. Numbers on screen come from the ledger, and each carries its source
+in a comment beside the code that draws it. Record the audience (age band, expertise) because it
+sets the reading level and the pace.
## The storyboard (`STORYBOARD.md`)
@@ -25,8 +26,8 @@ review when the person wants that step; otherwise build from it.
on, never faded in. The drawing process (`drawing-process.md`) is the explainer's best tool:
the diagram assembling IS the explanation.
- **Captions are drawn lettering** (`lettering.ts`, `drafting.ts`, a style's own hand), sized for
- the smallest shape the piece ships in. Keep them short enough to read twice in their time on
- screen.
+ the smallest shape the piece ships in. Each stays up at least max(0.7 s, 0.3 s per word), and
+ longer for a young or non-expert audience (`craft-bar.md`).
- **A mechanism beats a diagram.** When the idea has moving parts, build it as a real machine that
comes apart and reads out its own state, in whichever style the piece uses: `machines.md`.
- **A recurring guide** (a mascot, a hand, an object) gives continuity across chapters; build it
diff --git a/skills/anidoodle/references/workflows/facts.md b/skills/anidoodle/references/workflows/facts.md
new file mode 100644
index 0000000..550cf05
--- /dev/null
+++ b/skills/anidoodle/references/workflows/facts.md
@@ -0,0 +1,48 @@
+# Facts: every claim has a source
+
+Any film that makes a claim, on screen or spoken, keeps a `facts.json`. It is the explainer's
+research ledger (`explainer.md`) made general, and the launch film's list of approved claims
+(`launch-video.md`). A viewer cannot check a film; this is how you can.
+
+## The rule
+
+- **Every claim is listed**: each line of words, each number, each label that asserts something,
+ and each narrated sentence.
+- **Each has its source**: the exact sentence it comes from, copied, and a URL or a file path.
+- **Nothing is invented.** No testimonial, rating, review, price, result, user count or real
+ person that the sources do not give. A quote needs its speaker and its page.
+- **What the film generates is labelled.** A slogan, a drawn scene, a mock screen, made-up sample
+ data: `generated: true` with a note saying what it is. A generated entry states no number; a
+ number needs a source.
+- **A claim you cannot source is cut**, or shown plainly as a metaphor.
+
+## The file
+
+```json
+{ "version": 1, "claims": [
+ { "claim": "Setup takes 40 minutes.", "where": "on-screen",
+ "source": { "sentence": "Setup takes about 40 minutes.", "url": "https://example.com/docs/start" } },
+ { "claim": "IDEA IN. ART OUT.", "where": "on-screen", "generated": true, "note": "slogan written for this film, states no fact" },
+ { "claim": "It runs offline.", "where": "narration",
+ "source": { "sentence": "No network is needed after install.", "file": "brief/readme.md#offline" } } ] }
+```
+
+`where` is `on-screen` or `narration`. `launch.mjs new <name>` writes an empty one beside the
+project and never overwrites one that is there; `node tools/facts.mjs init` does the same for
+any project.
+
+## The check
+
+`node tools/facts.mjs <film>` (and `launch.mjs ship`, once per film) reads the claims the film
+declares. A launch template film declares its type-frame words, its split words and its tagline,
+and any `claims: [...]` in its spec; any other film sets `film.claims`. It fails when:
+
+- a declared claim is not in `facts.json` (matched ignoring case, spacing and end punctuation);
+- a sourced entry lacks the sentence, or a URL (http/https) or file;
+- a generated entry has no note, or states a number;
+- a number in a sourced claim is not in its source sentence;
+- a claim is still a TODO.
+
+A film that declares no claims reports `N/A`, never a pass. The check is light on purpose: it
+cannot know a sentence is true. The critic does that by reading each source beside the film
+(`review.md`), and the delivery says which facts were independently checked.
diff --git a/skills/anidoodle/references/workflows/launch-video-kit.md b/skills/anidoodle/references/workflows/launch-video-kit.md
index ac31b8c..3d0fd27 100644
--- a/skills/anidoodle/references/workflows/launch-video-kit.md
+++ b/skills/anidoodle/references/workflows/launch-video-kit.md
@@ -20,8 +20,9 @@ node tools/launch.mjs ship myLaunch --shapes 16x9,1x1,9x16 --blur auto --gate
`ship` renders every shape to `out/myLaunch-<shape>.mp4`, writes its poster (`.poster.png`, the
film's own legible frame) and its captions (`.srt`, `.vtt`), runs `verify-export --delivery` on each
file (size, frames, score, A/V sync at every marker, the true peak after the encode, a legible frame
-0), `framecheck.mjs` on every frame (no text, no card, no product window cut by the frame's edge)
-and, with `--gate`, the gate; one table at the end, exit 1 if any shape fails.
+0), `framecheck.mjs` on every frame (no text, no card, no product window cut by the frame's edge;
+text held long enough to read; on 9:16 no text in the phone zones), `facts.mjs` once (every claim
+sourced) and, with `--gate`, the gate; one table at the end, exit 1 if any shape fails.
### Design review checklist (every shape, before anything ships)
@@ -31,6 +32,13 @@ contact sheet of EVERY shape against this list, and fix, never waive:
- **No clipped type.** Every word a viewer reads is whole on every frame: the typed prompt, the
bubbles, the labels, the words, the install lines. `framecheck.mjs` (run by `ship`) fails any
line of text the frame's edge cuts through.
+- **Time to read.** Each text up at least `max(0.7 s, 0.3 s per word)`, and never over a busy picture
+ without a plate (`craft-bar.md`). `framecheck.mjs` fails a declared cue held too briefly.
+- **Phone safe zones on 9:16.** No text in the top 14 %, the bottom 25 % or the right 14 % of the
+ frame, where the platforms put their own interface (`formats.md`). `ship` flags it per shape;
+ `--strict-zones` fails it.
+- **Every claim sourced.** The words, the tagline and any extra `claims` in the spec are listed in
+ `facts.json` with their source sentence and URL or file (`workflows/facts.md`); `ship` checks it.
- **No edge-cropped content.** A card, a product window, a film's card sits whole in the frame
with a margin, unless it is a deliberate full-bleed (the whole frame is that one thing). What
the camera is about to cut fades before it does. `framecheck.mjs` checks the cards and windows.
@@ -146,6 +154,7 @@ many subframes as each frame's measured on-screen speed needs (1 on a still fram
| `words[i]` | the type frame after `asks[i]` (not after the last ask; it flows into the end card) |
| `tagline`, `install[]`, `footer` | the end card; install lines are shown exactly as given |
| `bpm` (required), `fps` (30 or 60), `askBeats`, `typeBeats`, `endBeats` | the beat grid (a beat is 60 x 30 / bpm frames at 30 fps) and each part's length in beats |
+| `claims` | extra on-screen or narrated claims for `facts.json`; the words, split words and tagline are claims already |
| `claimBar` | land the end card on this bar's downbeat, counting from bar 0 (`claimBar: 4` = frame 4 x bar); throws if it cannot. A longer last ask is really longer, never slowed |
| `score` (required) or `audio` | the score composed for this product (the `Material` function compose.md writes, or a `Piece`), as a bed; `null` for silence; or your own finished mix (not checked; it replaces the cues too) |
| `shape`, `preset`, `sfx`, `motif`, `captions` | the frame (16x9 default); the look (drawn, clean); sound cues (default on); the relay into the end card (default on); `"sidecar"` (default) or `"burn"` |
diff --git a/skills/anidoodle/references/workflows/launch-video.md b/skills/anidoodle/references/workflows/launch-video.md
index 51b23df..277a173 100644
--- a/skills/anidoodle/references/workflows/launch-video.md
+++ b/skills/anidoodle/references/workflows/launch-video.md
@@ -21,7 +21,8 @@ that invents its subject draws a mascot of a product, not the product.
components, the live page. Note the two or three REAL features a viewer should recognise on
screen, the exact product name and mark, the brand colours as hex.
2. **Collect approved claims.** The one-line promise and any numbers come from their own
- materials (site copy, release notes, README), each with its source next to it. Anything you
+ materials (site copy, release notes, README), each with its source next to it, in `facts.json`
+ (`facts.md`; `launch.mjs new` scaffolds it). Anything you
cannot source becomes a question, not a line in the film. List the claims the film must NOT make.
3. **Ask the grounding questions**, one message: which features to show (recommend your three),
which shapes to ship, where it will run, the exact CTA lines.
@@ -170,14 +171,15 @@ into place), round iris seams, the product's own UI. Pick one per film; never mi
5. **Music as an mp3 on a page**, heard by a human. ✋ Approval.
6. **Cut as data**: content scenes on one timeline, the cut as `pic`/`type` segments on the
beat grid (`launchCut.ts`). Re-timing edits the list, never scene code.
-7. **Review from the render**: contact sheets per beat, cuts as before/after pairs, DESIGN
- first (type over art, spacing, hierarchy), then timing. Render only the changed range
+7. **Review from the render, by a fresh critic** (`review.md`, three rounds at most): contact
+ sheets, cuts as before/after pairs, DESIGN first (type over art, spacing, hierarchy), then timing. Render only the changed range
(`render.mjs --from F --to T` writes `out/<film>.<F>-<T>.mp4`, silent). Give notes in camera words ("slow this zoom to 0.7x",
"hold the word 10 frames longer"), never "make it better".
8. **QA**: review every shape's contact sheet against the design checklist in
`launch-video-kit.md` (no clipped type, no edge-cropped content, balanced per shape, coherent
content). `launch.mjs ship <film> --shapes ... --gate` runs, for EVERY shape shipped, `framecheck`
- (text and cards whole on every frame), the gate
+ (text and cards whole on every frame; each text up long enough to read; on 9:16 nothing under
+ the phone UI; `craft-bar.md`), `facts.mjs` (every claim sourced, `facts.md`), the gate
(determinism, contract, dead air; declare real holds in `meta.holds`, each with its reason)
and `verify-export --delivery` (size, frames, score, sync, true peak, a legible frame 0), and
writes the poster and captions; add `verify-export <film>-<shape> --first-frame #rrggbb` for a