@docyrus/animaguru 0.11.0 → 0.14.0

package/templates/video/scripts/review-analysis.mjs

@@ -1,4 +1,53 @@
-/** Numerical checks complement viewing; they do not infer visual occlusion or factual truth. */
+import { readFileSync } from "node:fs";
+
+const safeAreas=JSON.parse(readFileSync(new URL("../shared/safe-areas.json",import.meta.url),"utf8"));
+const short=(text)=>{const line=String(text).replace(/\s+/g," ").trim();return line.length>60?`${line.slice(0,57)}…`:line;};
+const area=(b)=>Math.max(0,b.width)*Math.max(0,b.height);
+const intersection=(a,b)=>Math.max(0,Math.min(a.x+a.width,b.x+b.width)-Math.max(a.x,b.x))*Math.max(0,Math.min(a.y+a.height,b.y+b.height)-Math.max(a.y,b.y));
+// A text box reserves room above the capitals and below the baseline; tightly leaded lines overlap only there.
+const ink=(b)=>{const top=b.fontSize?.2*b.fontSize:.15*b.height,bottom=b.fontSize?.15*b.fontSize:.1*b.height;return {...b,y:b.y+top,height:Math.max(0,b.height-top-bottom)};};
+
+/** film.config.json safeArea: a preset name from shared/safe-areas.json (scaled to the film width) or { top, right, bottom, left } insets. */
+export function safeInsets(config) {
+  if(!config.safeArea)return null;
+  if(typeof config.safeArea==="object")return config.safeArea;
+  const preset=safeAreas.presets[config.safeArea];
+  if(!preset)throw new Error(`Unknown safeArea "${config.safeArea}" in film.config.json. Use ${Object.keys(safeAreas.presets).join(", ")} or { top, right, bottom, left } insets.`);
+  const scale=config.width/safeAreas.referenceWidth;
+  return Object.fromEntries(Object.entries(preset).map(([edge,value])=>[edge,value*scale]));
+}
+
+/**
+ * Layout warnings from sampled text boxes: overlapping text, text outside the platform safe area,
+ * text smaller than config.minTextSize (default 2.2% of the shorter side) and film text under a burned-in caption.
+ * Consecutive samples of the same finding are merged into one warning with a time range.
+ */
+export function analyzeLayout(samples,config) {
+  const insets=safeInsets(config),minimum=config.minTextSize??Math.round(Math.min(config.width,config.height)*.022);
+  const found=new Map();
+  const note=(key,time,data)=>{const run=found.get(key);if(run){run.to=time;run.samples++;}else found.set(key,{...data,from:time,to:time,samples:1});};
+  for(const sample of samples) {
+    const boxes=sample.texts.filter((b)=>b.text.trim()&&area(b)>0&&[b.x,b.y,b.width,b.height].every(Number.isFinite));
+    const captions=boxes.filter((b)=>b.role==="caption"),film=boxes.filter((b)=>b.role!=="caption");
+    for(const b of boxes) {
+      if(b.fontSize!==undefined&&b.fontSize<minimum-.5)note(`small\0${b.text}`,sample.time,{type:"small-text",text:short(b.text),fontSize:b.fontSize,minimum});
+      if(insets) {
+        const edges=[b.y<insets.top-2&&"top",b.x+b.width>config.width-insets.right+2&&"right",b.y+b.height>config.height-insets.bottom+2&&"bottom",b.x<insets.left-2&&"left"].filter(Boolean);
+        if(edges.length)note(`safe\0${b.text}\0${edges}`,sample.time,{type:"safe-area",text:short(b.text),edges});
+      }
+    }
+    for(let i=0;i<film.length;i++)for(let j=i+1;j<film.length;j++) {
+      const a=ink(film[i]),b=ink(film[j]),shared=intersection(a,b);
+      if(shared>.12*Math.min(area(a),area(b))) {const texts=[short(a.text),short(b.text)].sort();note(`overlap\0${texts.join("\0")}`,sample.time,{type:"text-overlap",texts});}
+    }
+    for(const caption of captions)for(const b of film) {
+      if(intersection(caption,b)>.05*Math.min(area(caption),area(b)))note(`caption\0${b.text}`,sample.time,{type:"caption-overlap",text:short(b.text),caption:short(caption.text)});
+    }
+  }
+  return [...found.values()].sort((a,b)=>a.from-b.from);
+}
+
+/** Numerical checks complement viewing; they do not judge artistic quality or factual truth. */
 export function analyzeReview(report, config) {
   const problems=[],warnings=[],runs=new Map(),active=new Map();
   const finish=(key)=>{const run=active.get(key);if(run){const previous=runs.get(key);if(!previous||run.duration>previous.duration)runs.set(key,run);active.delete(key);}};
@@ -21,9 +70,30 @@ export function analyzeReview(report, config) {
     if(run.duration<need)warnings.push({type:"reading-hold",...run,suggested:need});
   }
   if(!report.samples.some((s)=>s.texts.length))warnings.push({type:"text-not-checked",message:"Expose actual visible text bounds through window.animaguru.texts."});
+  warnings.push(...analyzeLayout(report.samples,config));
   if(report.seekMatches.some((s)=>!s.match))problems.push({type:"seek-determinism",samples:report.seekMatches.filter((s)=>!s.match)});
   for(const cue of report.cues??[]) {
     if(cue.audioTime!==undefined&&Math.abs(cue.time-cue.audioTime)>1/config.fps)problems.push({type:"cue-alignment",cue});
   }
   return {pass:problems.length===0,problems,warnings,readingRuns:[...runs.values()]};
 }
+
+/** One line per finding, for the terminal, so the report file rarely needs opening. */
+export function reviewLines(analysis,limit=14) {
+  const span=(item)=>item.from===undefined?"":item.from===item.to?`${item.from.toFixed(1)}s `:`${item.from.toFixed(1)}–${item.to.toFixed(1)}s `;
+  const describe=(item)=>{
+    switch(item.type) {
+      case "text-bounds": return `${item.time.toFixed(1)}s text outside the frame: "${short(item.text)}"`;
+      case "seek-determinism": return `seeking is not deterministic at ${item.samples.map((s)=>`${s.time.toFixed(2)}s`).join(", ")}`;
+      case "cue-alignment": return `cue ${item.cue.label??item.cue.id} at ${item.cue.time}s is off its audio time ${item.cue.audioTime}s`;
+      case "reading-hold": return `${item.start.toFixed(1)}s reading-hold ${item.duration.toFixed(1)}s (needs ${item.suggested.toFixed(1)}s): "${short(item.text)}"`;
+      case "text-overlap": return `${span(item)}text-overlap: "${item.texts[0]}" × "${item.texts[1]}"`;
+      case "safe-area": return `${span(item)}safe-area (${item.edges.join(", ")}): "${item.text}"`;
+      case "small-text": return `${span(item)}small-text ${item.fontSize}px < ${item.minimum}px: "${item.text}"`;
+      case "caption-overlap": return `${span(item)}caption-overlap: "${item.text}" under caption "${item.caption}"`;
+      default: return item.message??item.type;
+    }
+  };
+  const all=[...analysis.problems.map((item)=>`✗ ${describe(item)}`),...analysis.warnings.map((item)=>`• ${describe(item)}`)];
+  return all.length>limit?[...all.slice(0,limit),`… ${all.length-limit} more in report.json`]:all;
+}

package/templates/video/scripts/review-audio.mjs

@@ -12,7 +12,8 @@ export async function inspectAudio(root,config) {
   const {stdout}=await run(ffprobe.path,["-v","error","-show_streams","-show_format","-of","json",file]);
   const probe=JSON.parse(stdout),stream=probe.streams.find((s)=>s.codec_type==="audio");
   if(!stream)throw new Error("Configured soundtrack has no audio stream.");
-  const {stderr}=await run(ffmpeg.path,["-hide_banner","-nostats","-i",file,"-af","loudnorm=I=-14:TP=-1.2:print_format=json","-f","null","-"],{maxBuffer:1024*1024});
+  // Same targets as npm run audio:mix (−14 LUFS, −2 dBTP); the measured input values do not depend on them.
+  const {stderr}=await run(ffmpeg.path,["-hide_banner","-nostats","-i",file,"-af","loudnorm=I=-14:TP=-2:LRA=9:print_format=json","-f","null","-"],{maxBuffer:1024*1024});
   const json=stderr.match(/\{\s*"input_i"[\s\S]*?\}/)?.[0];
   if(!json)throw new Error("Audio loudness could not be measured.");
   const levels=JSON.parse(json),duration=Number(probe.format.duration);

package/templates/video/scripts/review.mjs

@@ -5,12 +5,14 @@ import { fileURLToPath } from "node:url";
 import { createServer } from "vite";
 import { projectArguments, projectContext } from "./project-context.mjs";
 import { workspacePlugin } from "./workspace-plugin.mjs";
-import { analyzeReview } from "./review-analysis.mjs";
+import { analyzeReview, reviewLines } from "./review-analysis.mjs";
 import { inspectAudio } from "./review-audio.mjs";
+import { captureHeadless, takeHeadlessFlag } from "./headless-browser.mjs";
 
 const root=fileURLToPath(new URL("../",import.meta.url));
 const selection=projectArguments(process.argv.slice(2));
-if(selection.rest.length)throw new Error("Usage: npm run review -- [--animation NAME]");
+const headless=takeHeadlessFlag(selection.rest);
+if(selection.rest.length)throw new Error("Usage: npm run review -- [--animation NAME] [--headless]");
 const context=await projectContext(root,selection.animation),config=context.config;
 const token=randomUUID(),port=Number(process.env.ANIMAGURU_REVIEW_PORT??5197);
 const output=path.join(context.projectRoot,"production/review");
@@ -31,7 +33,9 @@ const server=await createServer({configFile:false,root,base:"./",publicDir:conte
         await writeFile(path.join(output,`frame-${String(i).padStart(2,"0")}.jpg`),Buffer.from(frame.image.split(",")[1],"base64"));
       }
       await writeFile(path.join(output,"report.json"),JSON.stringify({config,samples:report.samples,seekMatches:report.seekMatches,cues:report.cues,analysis,audio},null,2)+"\n");
-      console.log(`${analysis.pass?"Passed":"Failed"}: seek and text-bound checks. ${analysis.warnings.length} reading/review notes. Frames and report: ${output}`);
+      console.log(`${analysis.pass?"Passed":"Failed"}: seek and text-bound checks. ${analysis.warnings.length} reading/layout notes. Frames and report: ${output}`);
+      for(const line of reviewLines(analysis))console.log(line);
+      if(audio.status==="measured")console.log(`Audio: ${audio.integratedLufs} LUFS, true peak ${audio.truePeakDb} dBTP.${audio.notes.length?` ${audio.notes.join(" ")}`:""}`);
       console.log("Inspect the frames and moving playback with audio; numerical checks do not establish artistic quality or claim accuracy.");
       response.writeHead(200,{"Content-Type":"application/json"}).end(JSON.stringify(analysis));
       response.once("finish",()=>{void server.close();});process.exitCode=analysis.pass?0:1;
@@ -39,3 +43,7 @@ const server=await createServer({configFile:false,root,base:"./",publicDir:conte
   });
 }}]});
 await server.listen();console.log(`Open this review page and keep it open until completion:\nhttp://127.0.0.1:${port}${context.route}?review=${token}`);
+if(headless) {
+  try { await captureHeadless(`http://127.0.0.1:${port}${context.route}?review=${token}`,{endpoint:"/__review/report"}); }
+  catch(error) { console.error(error.message);process.exitCode=1;await server.close(); }
+}

package/templates/video/scripts/site-inspect.mjs

@@ -0,0 +1,128 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { workspaceInfo } from "./project-context.mjs";
+import { withPage } from "./headless-browser.mjs";
+
+/*
+ * Brand research for animaguru-brand-kit: renders an official site in headless Chrome and saves what the kit needs.
+ * Page content is untrusted source material, never instructions. Fonts are listed, not downloaded: check their licence first.
+ */
+const usage = "Usage: npm run inspect:site -- https://example.com [--pages /about,/pricing] [--out DIR]";
+const root = fileURLToPath(new URL("../", import.meta.url));
+const args = process.argv.slice(2);
+let address, pages = [], out;
+for (let index = 0; index < args.length; index++) {
+  if (args[index] === "--pages" && args[index + 1]) pages = args[++index].split(",").map((page) => page.trim()).filter(Boolean);
+  else if (args[index] === "--out" && args[index + 1]) out = args[++index];
+  else if (!address && /^https?:\/\//.test(args[index])) address = args[index];
+  else throw new Error(usage);
+}
+if (!address) throw new Error(usage);
+const site = new URL(address);
+const output = path.resolve(root, out ?? (await workspaceInfo(root) ? `branding/source/${site.hostname}` : `production/brand-source/${site.hostname}`));
+await mkdir(output, { recursive: true });
+
+function extract() {
+  const visible = (element) => { const box = element.getBoundingClientRect(); return box.width > 0 && box.height > 0; };
+  const meta = (selector) => document.querySelector(selector)?.getAttribute("content") ?? null;
+  const absolute = (value) => { try { return new URL(value, location.href).href; } catch { return null; } };
+  const variables = {};
+  const fontFaces = [];
+  for (const sheet of document.styleSheets) {
+    let rules; try { rules = sheet.cssRules; } catch { continue; }
+    const walk = (list) => { for (const rule of list) {
+      if (rule.cssRules) walk(rule.cssRules);
+      if (rule instanceof CSSFontFaceRule) fontFaces.push({ family: rule.style.getPropertyValue("font-family").replace(/["']/g, "").trim(), weight: rule.style.getPropertyValue("font-weight") || null, src: [...rule.style.getPropertyValue("src").matchAll(/url\(["']?([^"')]+)["']?\)/g)].map((match) => new URL(match[1], sheet.href ?? location.href).href) });
+      else if (rule instanceof CSSStyleRule && /(^|,)\s*(:root|html)\s*(,|$)/.test(rule.selectorText)) for (const name of rule.style) if (name.startsWith("--")) variables[name] = getComputedStyle(document.documentElement).getPropertyValue(name).trim() || rule.style.getPropertyValue(name).trim();
+    } };
+    walk(rules);
+  }
+  const colorish = /^(#[0-9a-f]{3,8}|rgba?\(|hsla?\(|oklch\(|oklab\(|color\()/i;
+  const usage = new Map();
+  const sampled = [...document.querySelectorAll("body, header, nav, main, footer, h1, h2, h3, p, a, button, [class*='btn'], [class*='button']")].filter(visible).slice(0, 400);
+  for (const element of sampled) {
+    const style = getComputedStyle(element);
+    for (const [property, value] of [["text", style.color], ["background", style.backgroundColor]]) {
+      if (!value || /rgba\(0, 0, 0, 0\)|transparent/.test(value)) continue;
+      const key = `${property} ${value}`; usage.set(key, (usage.get(key) ?? 0) + 1);
+    }
+  }
+  const typeOf = (selector) => { const element = [...document.querySelectorAll(selector)].find(visible); if (!element) return null; const style = getComputedStyle(element); return { family: style.fontFamily, weight: style.fontWeight, size: style.fontSize, color: style.color }; };
+  const logos = [];
+  const logoLike = (element) => /logo|brand/i.test(`${element.id} ${element.className?.baseVal ?? element.className} ${element.getAttribute("alt") ?? ""} ${element.getAttribute("aria-label") ?? ""} ${element.closest("a")?.getAttribute("aria-label") ?? ""}`);
+  for (const element of document.querySelectorAll("header img, header svg, nav img, nav svg, footer img, footer svg, img[alt*='logo' i], img[src*='logo' i], svg[class*='logo' i], [class*='logo' i] img, [class*='logo' i] svg, a[href='/'] img, a[href='/'] svg")) {
+    if (element.tagName.toLowerCase() === "svg" && element.parentElement?.closest("svg")) continue;
+    const box = element.getBoundingClientRect();
+    if (box.width < 16 || box.height < 8) continue;
+    const place = element.closest("header, nav") ? "header" : element.closest("footer") ? "footer" : "page";
+    const score = (logoLike(element) || element.closest("a[href='/'], a[href='./']") ? 2 : 0) + (place === "header" ? 1 : 0);
+    if (element.tagName.toLowerCase() === "img") logos.push({ kind: "img", src: absolute(element.currentSrc || element.src), alt: element.alt, width: Math.round(box.width), height: Math.round(box.height), place, score });
+    else if (element.outerHTML.length < 200_000) logos.push({ kind: "svg", svg: element.outerHTML, label: element.getAttribute("aria-label"), width: Math.round(box.width), height: Math.round(box.height), place, score });
+  }
+  const icons = [...document.querySelectorAll("link[rel~='icon'], link[rel='apple-touch-icon'], link[rel='mask-icon']")].map((link) => ({ rel: link.rel, href: absolute(link.getAttribute("href")), sizes: link.getAttribute("sizes") }));
+  return {
+    url: location.href, title: document.title, lang: document.documentElement.lang || null,
+    description: meta("meta[name='description']"), themeColor: meta("meta[name='theme-color']"), ogImage: meta("meta[property='og:image']"), ogSiteName: meta("meta[property='og:site_name']"),
+    variables: Object.fromEntries(Object.entries(variables).slice(0, 200)),
+    colorVariables: Object.fromEntries(Object.entries(variables).filter(([, value]) => colorish.test(value)).slice(0, 60)),
+    colorsInUse: [...usage.entries()].sort((a, b) => b[1] - a[1]).slice(0, 16).map(([key, count]) => ({ use: key.split(" ")[0], color: key.slice(key.indexOf(" ") + 1), count })),
+    typography: { body: typeOf("body"), h1: typeOf("h1"), h2: typeOf("h2"), link: typeOf("nav a, header a, a"), button: typeOf("button, [class*='btn']") },
+    loadedFonts: [...document.fonts].filter((face) => face.status === "loaded").map((face) => ({ family: face.family.replace(/["']/g, ""), weight: face.weight, style: face.style })),
+    fontFaces: fontFaces.slice(0, 40),
+    logos: logos.sort((a, b) => b.score - a.score).slice(0, 8), icons,
+    headings: [...document.querySelectorAll("h1, h2, h3")].filter(visible).map((h) => `${h.tagName.toLowerCase()}: ${h.innerText.replace(/\s+/g, " ").trim()}`).filter((line) => line.length > 4).slice(0, 40),
+    links: [...document.querySelectorAll("header a, nav a, footer a")].filter(visible).map((a) => ({ text: a.innerText.replace(/\s+/g, " ").trim(), href: absolute(a.getAttribute("href")) })).filter((link) => link.text && link.href).slice(0, 60),
+    text: document.body.innerText.replace(/\n{3,}/g, "\n\n").slice(0, 12000),
+  };
+}
+
+const result = await withPage(site.href, async (page) => {
+  await page.waitForLoadState("networkidle", { timeout: 20_000 }).catch(() => {});
+  await page.screenshot({ path: path.join(output, "hero.png") });
+  const home = await page.evaluate(extract);
+  const saved = [];
+  for (const [index, logo] of home.logos.entries()) {
+    const name = `logo-${index + 1}`;
+    if (logo.kind === "svg") {
+      const svg = logo.svg.includes("xmlns=") ? logo.svg : logo.svg.replace(/^<svg\b/, '<svg xmlns="http://www.w3.org/2000/svg"');
+      await writeFile(path.join(output, `${name}.svg`), svg); saved.push({ file: `${name}.svg`, ...logo, svg: undefined });
+    } else if (logo.src && !logo.src.startsWith("data:")) {
+      const response = await page.request.get(logo.src).catch(() => null);
+      const type = response?.headers()["content-type"] ?? "";
+      if (!response?.ok() || !type.startsWith("image/")) continue;
+      const extension = ({ "image/svg+xml": "svg", "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/gif": "gif", "image/avif": "avif" })[type.split(";")[0]] ?? "img";
+      await writeFile(path.join(output, `${name}.${extension}`), await response.body()); saved.push({ file: `${name}.${extension}`, ...logo });
+    }
+  }
+  const more = [];
+  for (const page_ of pages) {
+    const target = new URL(page_, site);
+    await page.goto(target.href, { waitUntil: "domcontentloaded", timeout: 60_000 });
+    await page.waitForLoadState("networkidle", { timeout: 15_000 }).catch(() => {});
+    const data = await page.evaluate(extract);
+    more.push({ url: data.url, title: data.title, headings: data.headings, text: data.text });
+  }
+  return { home, saved, more };
+}, { viewport: { width: 1440, height: 900 } });
+
+const { home, saved, more } = result;
+const { text, logos, ...summary } = home;
+await writeFile(path.join(output, "site.json"), JSON.stringify({ accessed: new Date().toISOString(), ...summary, logos: saved, pages: more.map(({ text: _text, ...page }) => page) }, null, 2) + "\n");
+await writeFile(path.join(output, "text.md"), [`# ${home.title}`, `Source: ${home.url}`, "", home.text, ...more.flatMap((page) => ["", `# ${page.title}`, `Source: ${page.url}`, "", page.text])].join("\n") + "\n");
+const fontFiles = home.fontFaces.flatMap((face) => face.src.map((src) => `${face.family} ${face.weight ?? ""} ${src}`.replace(/\s+/g, " ")));
+console.log([
+  `${home.title} — ${home.url}`,
+  home.description ? `Description: ${home.description}` : null,
+  `Typography: headings ${home.typography.h1?.family ?? home.typography.h2?.family ?? "?"}; body ${home.typography.body?.family ?? "?"}`,
+  `Loaded fonts: ${[...new Set(home.loadedFonts.map((face) => face.family))].join(", ") || "none detected"}`,
+  ...fontFiles.slice(0, 8).map((line) => `  font file: ${line}`),
+  `Color variables: ${Object.entries(home.colorVariables).slice(0, 14).map(([name, value]) => `${name} ${value}`).join(" · ") || "none on :root"}`,
+  `Colors in use: ${home.colorsInUse.slice(0, 8).map((item) => `${item.use} ${item.color} ×${item.count}`).join(" · ")}`,
+  home.themeColor ? `Theme color: ${home.themeColor}` : null,
+  `Logo candidates saved: ${saved.map((logo) => `${logo.file} (${logo.place}, ${logo.width}×${logo.height}${logo.alt ? `, "${logo.alt}"` : ""})`).join("; ") || "none"}`,
+  `Icons: ${home.icons.map((icon) => icon.href).join(" ") || "none"}`,
+  `Headings: ${home.headings.slice(0, 6).join(" | ")}`,
+  `Saved: ${path.join(output, "hero.png")}, site.json, text.md${more.length ? ` (+${more.length} pages)` : ""}`,
+  "Open hero.png and each logo file to confirm they belong to the brand; fonts need a licence check before download.",
+].filter(Boolean).join("\n"));

package/templates/video/scripts/starter-film.sha256

@@ -1 +1 @@
-31dec70bb78b4d3ecc34451c54aeef31366e38c966b6a61763cf6446b464750e
+1b4813e137e12d7784132424c0fa41dfb14cfc0b75acd2df718e04ad3fb086ed

package/templates/video/scripts/workspace-plugin.mjs

@@ -40,7 +40,8 @@ void mountPlayer({config,Film,chapters,branding:${JSON.stringify(context.brandin
           })().catch((error) => response.writeHead(500).end(error.message)); return;
         }
         if (!match) return next();
-        if (/^(?:src|shared)\//.test(match[2]) || ["film.config.json", "animaguru.project.json"].includes(match[2])) return next();
+        // Film modules and the JSON they import (including the voiceover cue map) go to Vite; everything else is public media.
+        if (/^(?:src|shared)\//.test(match[2]) || ["film.config.json", "animaguru.project.json", "production/audio/timing.json"].includes(match[2])) return next();
         void (async () => {
           const context = await projectContext(root, match[1]);
           if (!match[2] || match[2] === "index.html") {

package/templates/video/shared/safe-areas.json

@@ -0,0 +1,7 @@
+{
+  "referenceWidth": 1080,
+  "presets": {
+    "reels": { "top": 220, "right": 120, "bottom": 360, "left": 60 },
+    "none": { "top": 0, "right": 0, "bottom": 0, "left": 0 }
+  }
+}

package/templates/video/src/film.ts

@@ -2,145 +2,117 @@ import { Application, Container, Graphics, Sprite, Text } from "pixi.js";
 import config from "../film.config.json";
 import story from "../shared/locales/en/film.json";
 import { filmResources } from "./film-resources";
+import { FilmBase, easeOut, clamp01, txt, useBrandFonts, hex } from "./kit";
 import type { FilmContext } from "./player-types";
-import type { ResourceTrack } from "./timeline-model";
 
 export const chapters = story.chapters;
-const clamp = (value: number) => Math.max(0, Math.min(1, value));
-const ease = (value: number) => 1 - (1 - clamp(value)) ** 3;
 
-function text(value: string, size: number, color = "#16232A", weight: "400" | "700" = "700") {
-  return new Text({ text: value, style: { fontFamily: "Arial, sans-serif", fontSize: size, fontWeight: weight, fill: color, lineHeight: size * 1.06, letterSpacing: size > 60 ? -3 : 0 } });
-}
+/**
+ * Replace these demo scenes with the film. Keep all motion a function of seconds.
+ * FilmBase (./kit) supplies the player contract, burned-in captions, review text bounds and cues;
+ * a longer film puts each scene in its own module under src/scenes/ and calls it from build().
+ */
+export class Film extends FilmBase {
+  private readonly identity: typeof story;
 
-/** Replace these demo scenes with the film. Keep all motion a function of seconds. */
-export class Film {
-  readonly stage = new Container();
-  readonly resources: ResourceTrack[];
-  private readonly scenes: { root: Container; art: Container; headline: Text; detail: Text }[] = [];
-  private readonly caption = text("", 30, "#FFFFFF", "400");
-  private readonly captionBack = new Graphics();
-  captions = true;
-  get cues() { return chapters.map((chapter,index)=>({id:`chapter-${index}`,time:chapter.start,label:chapter.label})); }
-  get texts() {
-    const result: { id:string; text:string; x:number; y:number; width:number; height:number }[]=[];
-    let index=0;
-    const visit=(node:Container,visible=true,alpha=1)=>{
-      const show=visible&&node.visible,opacity=alpha*node.alpha;
-      if(node instanceof Text) {
-        const id=`text-${index++}`;
-        if(show&&opacity>=.95) {const b=node.getBounds();result.push({id,text:node.text,x:b.x,y:b.y,width:b.width,height:b.height});}
-      }
-      for(const child of node.children)visit(child,show,opacity);
-    };
-    visit(this.stage);return result;
+  constructor(app: Application, context?: FilmContext) {
+    super(app, context, {
+      config, chapters, design: { width: 1920, height: 1080 },
+      captions: chapters.map((chapter) => ({ start: chapter.start, end: chapter.end, text: chapter.caption })),
+      captionStyle: { y: 991, size: 30, weight: "400", maxWidth: 1620, background: 0x172721, backgroundAlpha: 0.92, radius: 18 },
+    });
+    this.identity = { ...story, brand: context?.branding.name ?? story.brand, tagline: context?.branding.tagline ?? story.tagline };
+    this.resources = filmResources(this.identity, config);
+    if (context?.branding.logo) {
+      this.resources = this.resources.filter((track) => track.id !== "branding");
+      this.resources.push({ id: "brand-logo", label: this.identity.brand, kind: "image", clips: [{ id: "brand-logo", label: this.identity.brand, source: context.branding.logo, start: 0, end: config.duration }] });
+    }
   }
 
-  constructor(private readonly app: Application, context?: FilmContext) {
-    const identity = { ...story, brand: context?.branding.name ?? story.brand, tagline: context?.branding.tagline ?? story.tagline };
-    this.resources = filmResources(identity, config);
-    app.stage.addChild(this.stage);
-    this.stage.scale.set(config.width / 1920, config.height / 1080);
-    this.stage.addChild(new Graphics().rect(0, 0, 1920, 1080).fill(context?.branding.colors.background ?? "#F4F1E9"));
+  protected build() {
+    const brand = this.context?.branding;
+    useBrandFonts(brand);
+    const primary = brand ? hex(brand.colors.primary) : 0x2c6bd0;
+    const heading = (value: string, size: number, fill = 0x16232a) => txt(value, size, { family: "heading", weight: "700", fill, lineHeight: size * 1.06 });
+    const body = (value: string, size: number, fill: number) => txt(value, size, { fill });
+
+    this.world.addChild(new Graphics().rect(0, 0, 1920, 1080).fill(brand?.colors.background ?? "#F4F1E9"));
     // Deterministic paper flecks: never use Math.random() during frame rendering.
     const grain = new Graphics();
-    for (let i = 0; i < 850; i++) grain.circle((i * 137.51) % 1920, (i * 71.73) % 1080, 1).fill({ color: "#23302D", alpha: 0.055 });
-    this.stage.addChild(grain);
-    chapters.forEach((chapter, index) => {
-      const root = new Container();
-      const art = new Container();
-      art.position.set(1440, 545);
-      art.addChild(new Graphics().circle(0, 0, 352).fill(chapter.color));
-      const orbit = new Graphics().circle(0, 0, 380).stroke({ color: "#24332D", alpha: 0.2, width: 2 });
-      orbit.rotation = -0.25;
-      art.addChild(orbit);
-      const paper = new Container();
-      paper.rotation = index === 1 ? 0.08 : -0.08;
-      paper.addChild(new Graphics().roundRect(-260, -274, 534, 572, 30).fill({ color: "#152520", alpha: 0.09 }));
-      paper.addChild(new Graphics().roundRect(-274, -290, 534, 572, 30).fill("#FFFDFA"));
-      const small = text(chapter.cardLabel, 21);
-      small.position.set(-230, -244);
-      paper.addChild(small);
-      const shape = new Graphics();
-      if (index === 0) {
-        shape.ellipse(0, 160, 152, 20).fill({ color: "#000000", alpha: 0.07 });
-        shape.roundRect(-106, -126, 210, 290, 70).fill(context?.branding.colors.primary ?? "#2C6BD0");
-        shape.star(0, -4, 8, 104, 52).fill("#F2D68B");
-        shape.circle(0, -4, 30).fill("#FDFBF4");
-      } else if (index === 1) {
-        shape.roundRect(-168, -144, 334, 270, 24).fill("#DCE7BC");
-        shape.circle(88, -67, 36).fill("#F3D88D");
-        shape.poly([-166, 108, -55, -54, 32, 67, 95, 4, 166, 126, -166, 126]).fill(context?.branding.colors.primary ?? "#2C6BD0");
-        shape.star(-148, -137, 4, 62, 17).fill("#263B32");
-      } else {
-        shape.circle(0, 0, 155).fill(context?.branding.colors.primary ?? "#2C6BD0");
-        shape.poly([-34, -65, 75, 0, -34, 65]).fill("#FFFDFA");
-      }
-      paper.addChild(shape);
-      const cardCaption = text(chapter.cardCaption, 25, "#31443E", "400");
-      cardCaption.anchor.set(0.5);
-      cardCaption.position.set(-7, 216);
-      paper.addChild(cardCaption);
-      art.addChild(paper);
-      const sparkle = new Graphics().star(236, -310, 4, 67, 19).fill(context?.branding.colors.primary ?? "#2C6BD0").star(-305, 230, 4, 34, 10).fill("#314B38");
-      art.addChild(sparkle);
-      const eyebrow = text(chapter.eyebrow, 23, "#4D6052");
-      eyebrow.position.set(120, 250);
-      const headline = text(chapter.headline, 112);
-      headline.position.set(114, 338);
-      const detail = text(chapter.detail, 32, "#59675F", "400");
-      detail.style.wordWrap = true;
-      detail.style.wordWrapWidth = 800;
-      detail.style.lineHeight = 46;
-      detail.position.set(120, 630);
-      root.addChild(art, eyebrow, headline, detail);
-      this.stage.addChild(root);
-      this.scenes.push({ root, art, headline, detail });
-    });
-    const mark = context?.logo ? new Sprite(context.logo) : text(identity.brand, 22, context?.branding.colors.text ?? "#16232A");
-    if (context?.logo) mark.scale.set(Math.min(170 / mark.width, 54 / mark.height));
+    for (let i = 0; i < 850; i++) grain.circle((i * 137.51) % 1920, (i * 71.73) % 1080, 1).fill({ color: 0x23302d, alpha: 0.055 });
+    this.world.addChild(grain);
+
+    chapters.forEach((chapter, index) => this.scene(chapter, index, primary, heading, body));
+
+    const mark = this.context?.logo ? new Sprite(this.context.logo) : heading(this.identity.brand, 24, brand ? hex(brand.colors.text) : 0x16232a);
+    if (this.context?.logo) mark.scale.set(Math.min(170 / mark.width, 54 / mark.height));
     mark.position.set(120, 88);
-    const preview = text(identity.tagline, 20, "#637166");
+    const preview = txt(this.identity.tagline, 24, { family: "heading", weight: "700", fill: 0x637166 });
     preview.anchor.set(1, 0);
     preview.position.set(1800, 88);
-    this.caption.anchor.set(0.5);
-    this.caption.position.set(960, 991);
-    this.stage.addChild(mark, preview, this.captionBack, this.caption);
-    if (context) {
-      const visit = (node: Container) => {
-        if (node instanceof Text) node.style.fontFamily = node.style.fontWeight === "700" ? context.branding.fonts.heading.family : context.branding.fonts.body.family;
-        for (const child of node.children) visit(child);
-      };
-      visit(this.stage);
-      if (context.branding.logo) this.resources = this.resources.filter((track) => track.id !== "branding");
-      if (context.branding.logo) this.resources.push({ id: "brand-logo", label: identity.brand, kind: "image", clips: [{ id: "brand-logo", label: identity.brand, source: context.branding.logo, start: 0, end: config.duration }] });
-    }
+    this.world.addChild(mark, preview);
   }
 
-  /** Await video seeks/font readiness here before returning when adding media. */
-  async render(seconds: number) {
-    const time = Math.min(Math.max(seconds, 0), config.duration - 0.00001);
-    this.scenes.forEach((scene, index) => {
-      const chapter = chapters[index];
-      const local = time - chapter.start;
-      scene.root.visible = time >= chapter.start && time < chapter.end;
-      if (!scene.root.visible) return;
-      const enter = index === 0 ? 1 : 0.2 + 0.8 * ease(local / 0.85);
-      const leave = index === chapters.length - 1 ? 1 : clamp((chapter.end - time) / 0.3);
-      scene.root.alpha = enter * leave;
-      scene.headline.x = 114 - 36 * (1 - enter);
-      scene.detail.alpha = index === 0 ? 1 : ease((local - 0.25) / 0.8);
-      scene.art.scale.set(0.94 + 0.06 * enter);
-      scene.art.y = 545 + 50 * (1 - enter) + Math.sin(local * 0.85) * 10;
-      scene.art.rotation = Math.sin(local * 0.65) * 0.018;
-      this.caption.text = chapter.caption;
-    });
-    this.caption.visible = this.captions;
-    this.captionBack.visible = this.captions;
-    if (this.captions) {
-      const width = Math.min(1720, this.caption.width + 64);
-      this.captionBack.clear().roundRect(960 - width / 2, 956, width, 70, 18).fill({ color: "#172721", alpha: 0.92 });
+  /** One chapter: illustrated card on the right, headline and detail on the left. */
+  private scene(chapter: (typeof chapters)[number], index: number, primary: number, heading: (value: string, size: number, fill?: number) => Text, body: (value: string, size: number, fill: number) => Text) {
+    const root = new Container();
+    const art = new Container();
+    art.position.set(1440, 545);
+    art.addChild(new Graphics().circle(0, 0, 352).fill(chapter.color));
+    const orbit = new Graphics().circle(0, 0, 380).stroke({ color: 0x24332d, alpha: 0.2, width: 2 });
+    orbit.rotation = -0.25;
+    art.addChild(orbit);
+    const paper = new Container();
+    paper.rotation = index === 1 ? 0.08 : -0.08;
+    paper.addChild(new Graphics().roundRect(-260, -274, 534, 572, 30).fill({ color: 0x152520, alpha: 0.09 }));
+    paper.addChild(new Graphics().roundRect(-274, -290, 534, 572, 30).fill(0xfffdfa));
+    const small = heading(chapter.cardLabel, 24);
+    small.position.set(-230, -244);
+    paper.addChild(small);
+    const shape = new Graphics();
+    if (index === 0) {
+      shape.ellipse(0, 160, 152, 20).fill({ color: 0x000000, alpha: 0.07 });
+      shape.roundRect(-106, -126, 210, 290, 70).fill(primary);
+      shape.star(0, -4, 8, 104, 52).fill(0xf2d68b);
+      shape.circle(0, -4, 30).fill(0xfdfbf4);
+    } else if (index === 1) {
+      shape.roundRect(-168, -144, 334, 270, 24).fill(0xdce7bc);
+      shape.circle(88, -67, 36).fill(0xf3d88d);
+      shape.poly([-166, 108, -55, -54, 32, 67, 95, 4, 166, 126, -166, 126]).fill(primary);
+      shape.star(-148, -137, 4, 62, 17).fill(0x263b32);
+    } else {
+      shape.circle(0, 0, 155).fill(primary);
+      shape.poly([-34, -65, 75, 0, -34, 65]).fill(0xfffdfa);
     }
-    this.app.render();
+    paper.addChild(shape);
+    const cardCaption = body(chapter.cardCaption, 26, 0x31443e);
+    cardCaption.anchor.set(0.5);
+    cardCaption.position.set(-7, 216);
+    paper.addChild(cardCaption);
+    art.addChild(paper);
+    art.addChild(new Graphics().star(236, -310, 4, 67, 19).fill(primary).star(-305, 230, 4, 34, 10).fill(0x314b38));
+    const eyebrow = heading(chapter.eyebrow, 24, 0x4d6052);
+    eyebrow.position.set(120, 250);
+    const headline = heading(chapter.headline, 112);
+    headline.position.set(114, 338);
+    const detail = body(chapter.detail, 32, 0x59675f);
+    Object.assign(detail.style, { wordWrap: true, wordWrapWidth: 800, lineHeight: 46 });
+    detail.position.set(120, 630);
+    root.addChild(art, eyebrow, headline, detail);
+    this.world.addChild(root);
+
+    this.on((t) => {
+      const local = t - chapter.start;
+      root.visible = t >= chapter.start && t < chapter.end;
+      if (!root.visible) return;
+      const enter = index === 0 ? 1 : 0.2 + 0.8 * easeOut(local / 0.85);
+      const leave = index === chapters.length - 1 ? 1 : clamp01((chapter.end - t) / 0.3);
+      root.alpha = enter * leave;
+      headline.x = 114 - 36 * (1 - enter);
+      detail.alpha = index === 0 ? 1 : easeOut((local - 0.25) / 0.8);
+      art.scale.set(0.94 + 0.06 * enter);
+      art.y = 545 + 50 * (1 - enter) + Math.sin(local * 0.85) * 10;
+      art.rotation = Math.sin(local * 0.65) * 0.018;
+    });
   }
 }