@docyrus/animaguru 0.13.0 → 0.15.0

package/templates/video/src/kit/components.ts

@@ -0,0 +1,95 @@
+import { Container, Graphics, type Text } from "pixi.js";
+import { clamp01, win } from "./motion";
+import { check } from "./shapes";
+import { txt, type Family, type Weight } from "./text";
+import type { Caption } from "./timing";
+
+export type CaptionStyle = {
+  x: number; y: number; maxWidth?: number; size?: number; weight?: Weight;
+  color?: number; background?: number; backgroundAlpha?: number; border?: number; borderAlpha?: number; radius?: number;
+};
+
+/**
+ * Burned-in captions for muted autoplay feeds. Hidden when film.captions is false (clean exports with .srt/.vtt).
+ * Its text is labelled "caption", so review treats it as a caption rather than film text.
+ */
+export class CaptionBar extends Container {
+  private readonly box = new Graphics();
+  private readonly line: Text;
+  private current = "";
+  constructor(private readonly captions: Caption[], private readonly style: CaptionStyle) {
+    super();
+    const maxWidth = style.maxWidth ?? 860, size = style.size ?? 38;
+    this.line = txt("", size, { weight: style.weight ?? "600", fill: style.color ?? 0xffffff, align: "center", wordWrap: true, wordWrapWidth: maxWidth, lineHeight: Math.round(size * 1.32) });
+    this.line.label = "caption";
+    this.line.anchor.set(0.5);
+    this.line.position.set(style.x, style.y);
+    this.addChild(this.box, this.line);
+  }
+  update(t: number, enabled = true) {
+    const cue = enabled ? this.captions.find((caption) => t >= caption.start && t < caption.end) : undefined;
+    this.visible = Boolean(cue);
+    if (!cue) return;
+    if (cue.text !== this.current) {
+      this.current = cue.text;
+      this.line.text = cue.text;
+      const { x, y, maxWidth = 860, radius = 22 } = this.style;
+      const w = Math.min(maxWidth + 100, this.line.width + 64), h = this.line.height + 30;
+      this.box.clear().roundRect(x - w / 2, y - h / 2, w, h, radius).fill({ color: this.style.background ?? 0x070d28, alpha: this.style.backgroundAlpha ?? 0.86 });
+      if (this.style.border !== undefined) this.box.roundRect(x - w / 2, y - h / 2, w, h, radius).stroke({ color: this.style.border, alpha: this.style.borderAlpha ?? 0.3, width: 2 });
+    }
+    // Back-to-back captions swap without a flash; isolated ones fade in and out.
+    const joinedBefore = this.captions.some((caption) => Math.abs(caption.end - cue.start) < 0.05);
+    const joinedAfter = this.captions.some((caption) => Math.abs(caption.start - cue.end) < 0.05);
+    this.alpha = (joinedBefore ? 1 : win(t, cue.start, 0.1)) * (joinedAfter ? 1 : 1 - win(t, cue.end - 0.1, 0.1));
+  }
+}
+
+/** Round status badge: an alert "!" that flips edge-on to a check mark. */
+export class Badge extends Container {
+  private readonly alert = new Container();
+  private readonly ok = new Graphics();
+  constructor(readonly radius = 16, { alertColor = 0xe04a4a, alertText = 0xff8a8a, okColor = 0x15c783 } = {}) {
+    super();
+    this.alert.addChild(new Graphics().circle(0, 0, radius).fill({ color: alertColor, alpha: 0.18 }).circle(0, 0, radius).stroke({ color: alertColor, alpha: 0.75, width: 2 }));
+    const bang = txt("!", radius * 1.25, { weight: "700", fill: alertText });
+    bang.anchor.set(0.5, 0.52);
+    this.alert.addChild(bang);
+    this.ok.circle(0, 0, radius).fill({ color: okColor, alpha: 0.2 }).circle(0, 0, radius).stroke({ color: okColor, alpha: 0.9, width: 2 });
+    check(this.ok, 0, 0, radius * 0.95, okColor, Math.max(2.5, radius * 0.18));
+    this.addChild(this.alert, this.ok);
+    this.flip(0);
+  }
+  /** 0 = alert, 1 = ok. */
+  flip(progress: number) {
+    this.alert.visible = progress < 0.5;
+    this.ok.visible = progress >= 0.5;
+    this.scale.x = Math.max(0.04, Math.abs(Math.cos(Math.PI * clamp01(progress))));
+  }
+}
+
+export type PillStyle = { color?: number; fill?: number; fillAlpha?: number; stroke?: number; strokeAlpha?: number; highlight?: number; padX?: number; padY?: number; family?: Family; weight?: Weight; left?: number };
+
+/** A centred rounded label (chip). Fade `highlight.alpha` in to light it up; `left` reserves room for an icon. */
+export class Pill extends Container {
+  readonly background = new Graphics();
+  readonly highlight = new Graphics();
+  readonly caption: Text;
+  readonly w: number;
+  readonly h: number;
+  constructor(text: string, size: number, style: PillStyle = {}) {
+    super();
+    this.caption = txt(text, size, { family: style.family ?? "mono", weight: style.weight ?? "500", fill: style.color ?? 0xedf1ff });
+    const padX = style.padX ?? 24, padY = style.padY ?? 14, left = style.left ?? 0;
+    this.w = this.caption.width + padX * 2 + left;
+    this.h = this.caption.height + padY * 2;
+    const draw = (g: Graphics, stroke: number, strokeAlpha: number, fill: number, fillAlpha: number) =>
+      g.roundRect(-this.w / 2, -this.h / 2, this.w, this.h, this.h / 2).fill({ color: fill, alpha: fillAlpha }).roundRect(-this.w / 2, -this.h / 2, this.w, this.h, this.h / 2).stroke({ color: stroke, alpha: strokeAlpha, width: 2 });
+    draw(this.background, style.stroke ?? 0x7282f2, style.strokeAlpha ?? 0.3, style.fill ?? 0x0a1030, style.fillAlpha ?? 0.92);
+    draw(this.highlight, style.highlight ?? 0x15c783, 0.95, style.highlight ?? 0x15c783, 0.14);
+    this.highlight.alpha = 0;
+    this.caption.anchor.set(0.5);
+    this.caption.position.set(left / 2, 1);
+    this.addChild(this.background, this.highlight, this.caption);
+  }
+}

package/templates/video/src/kit/dark-stage.ts

@@ -0,0 +1,55 @@
+import { Container, Graphics, Sprite } from "pixi.js";
+import type { FilmBase } from "./film-base";
+import { lerp, rng } from "./motion";
+import { gradientFill } from "./text";
+import { glowTexture, vignetteTexture } from "./textures";
+
+export type DarkStageOptions = {
+  /** Vertical background gradient, top to bottom. */
+  background?: string[];
+  /** Brand primary and a second accent for the two drifting glows. */
+  primary?: number; accent?: number;
+  ink?: number; grid?: number; motes?: number;
+  /** 0–1 extra glow over time, e.g. a bloom on the music drop: t => bump(win(t, drop - 0.1, 2.6)). */
+  pulse?: (t: number) => number;
+};
+
+/**
+ * Dark Tech Stage backdrop: deep gradient, a slowly scrolling hairline grid, two drifting brand glows, a centre bloom
+ * driven by `pulse`, seeded dust motes and a vignette. Adds itself under film.world and returns its layers.
+ */
+export function darkStage(film: FilmBase, { background = ["#0C1438", "#071036", "#050A22"], primary = 0x7282f2, accent = 0xb45fc4, ink = 0xedf1ff, grid = 72, motes = 70, pulse = () => 0 }: DarkStageOptions = {}) {
+  const { width: W, height: H } = film;
+  const root = new Container();
+  const base = new Graphics().rect(0, 0, W, H).fill(gradientFill(background, "vertical"));
+  const lines = new Graphics();
+  for (let x = -grid; x <= W + grid; x += grid) lines.moveTo(x, -grid).lineTo(x, H + grid);
+  for (let y = -grid; y <= H + grid; y += grid) lines.moveTo(-grid, y).lineTo(W + grid, y);
+  lines.stroke({ color: ink, alpha: 0.035, width: 1 });
+  const size = Math.max(W, H);
+  const glowA = new Sprite(glowTexture(primary)), glowB = new Sprite(glowTexture(accent)), bloom = new Sprite(glowTexture(primary));
+  for (const [glow, scale] of [[glowA, 0.78], [glowB, 0.68], [bloom, 0.58]] as const) { glow.anchor.set(0.5); glow.width = glow.height = size * scale; }
+  const dust = new Graphics();
+  const random = rng(7);
+  const specks = Array.from({ length: motes }, () => ({ x: random() * W, y: random() * H, s: 1 + random() * 2.2, v: 6 + random() * 16, p: random() * 6.28 }));
+  const vignette = new Sprite(vignetteTexture(W, H));
+  vignette.width = W; vignette.height = H;
+  root.addChild(base, glowA, glowB, bloom, lines, dust, vignette);
+  film.world.addChildAt(root, 0);
+  film.on((t) => {
+    const lift = pulse(t);
+    lines.y = (t * 7) % grid;
+    glowA.position.set(W * 0.8 + 50 * Math.sin(t * 0.21), H * 0.22 + 60 * Math.cos(t * 0.17));
+    glowA.alpha = 0.2 + 0.08 * lift;
+    glowB.position.set(W * 0.16 + 60 * Math.cos(t * 0.19), H * 0.77 + 50 * Math.sin(t * 0.23));
+    glowB.alpha = 0.14 + 0.06 * lift;
+    bloom.position.set(W / 2, lerp(H * 0.6, H * 0.47, lift));
+    bloom.alpha = 0.05 + 0.3 * lift;
+    dust.clear();
+    for (const speck of specks) {
+      const y = (((speck.y - t * speck.v) % H) + H) % H;
+      dust.circle(speck.x + 8 * Math.sin(t * 0.5 + speck.p), y, speck.s).fill({ color: ink, alpha: 0.1 + 0.14 * (0.5 + 0.5 * Math.sin(t * 1.3 + speck.p)) });
+    }
+  });
+  return { root, base, grid: lines, glows: [glowA, glowB, bloom], dust, vignette };
+}

package/templates/video/src/kit/film-base.ts

@@ -0,0 +1,108 @@
+import { AbstractSplitText, Container, Text, type Application } from "pixi.js";
+import type { FilmConfig, FilmContext, TextBox } from "../player-types";
+import type { ResourceTrack } from "../timeline-model";
+import { CaptionBar, type CaptionStyle } from "./components";
+import { safeArea } from "./layout";
+import type { Caption } from "./timing";
+
+export type Update = (t: number) => void;
+export type Cue = { id: string; time: number; label: string };
+
+/** Visible, opaque text with its bounds in film pixels, rendered font size and role; npm run review and npm run frames lint these. */
+export function collectTexts(root: Container): TextBox[] {
+  const result: TextBox[] = [];
+  let index = 0;
+  const visit = (node: Container, visible: boolean, alpha: number, glyphs?: TextBox[]) => {
+    const shown = visible && node.visible, opacity = alpha * node.alpha;
+    if (node instanceof AbstractSplitText) {
+      // One string whose glyphs move on their own: report what is drawn as one box, so tight tracking is not an overlap.
+      const id = `text-${index++}`, drawn: TextBox[] = [];
+      for (const child of node.children) visit(child as Container, shown, opacity, drawn);
+      if (!drawn.length || !node.text.trim()) return;
+      const x = Math.min(...drawn.map((box) => box.x)), y = Math.min(...drawn.map((box) => box.y));
+      const sizes = drawn.flatMap((box) => box.fontSize ? [box.fontSize] : []);
+      result.push({ id, text: node.text, x, y, width: Math.max(...drawn.map((box) => box.x + box.width)) - x, height: Math.max(...drawn.map((box) => box.y + box.height)) - y, ...(sizes.length ? { fontSize: Math.min(...sizes) } : {}) });
+      return;
+    }
+    if (node instanceof Text) {
+      const id = `text-${index++}`;
+      if (shown && opacity >= 0.95 && node.text.trim()) {
+        const bounds = node.getBounds(), matrix = node.worldTransform;
+        const fontSize = typeof node.style.fontSize === "number" ? Math.round(node.style.fontSize * Math.hypot(matrix.c, matrix.d) * 10) / 10 : undefined;
+        (glyphs ?? result).push({ id, text: node.text, x: bounds.x, y: bounds.y, width: bounds.width, height: bounds.height, ...(fontSize ? { fontSize } : {}), ...(node.label === "caption" ? { role: "caption" } : {}) });
+      }
+    }
+    for (const child of node.children) visit(child as Container, shown, opacity, glyphs);
+  };
+  visit(root, true, 1);
+  return result;
+}
+
+export type FilmBaseOptions = {
+  config: FilmConfig;
+  chapters: { start: number; end: number; label: string }[];
+  /** Coordinates the scenes are written in; the stage scales them to config.width × config.height. Defaults to the config size. */
+  design?: { width: number; height: number };
+  /** Burned-in captions (for example timing.json captions); omit for none. */
+  captions?: Caption[];
+  captionStyle?: Partial<CaptionStyle>;
+};
+
+/**
+ * The player contract (stage, resources, captions, texts, cues, render) so a film only adds scenes.
+ * Put scenes in this.world from build() (or from scene modules given the film), and register per-frame updates with
+ * film.on(t => …); every update is a pure function of t.
+ */
+export abstract class FilmBase {
+  readonly stage = new Container();
+  /** Scene layer under the caption bar. */
+  readonly world = new Container();
+  resources: ResourceTrack[] = [];
+  captions = true;
+  /** Design size, in the coordinates scenes use. */
+  readonly width: number;
+  readonly height: number;
+  protected readonly updates: Update[] = [];
+  protected readonly markers: Cue[] = [];
+  protected readonly captionBar: CaptionBar | null;
+  private readonly ready: Promise<void>;
+
+  constructor(protected readonly app: Application, protected readonly context: FilmContext | undefined, protected readonly options: FilmBaseOptions) {
+    const { config } = options;
+    this.width = options.design?.width ?? config.width;
+    this.height = options.design?.height ?? config.height;
+    app.stage.addChild(this.stage);
+    this.stage.scale.set(config.width / this.width, config.height / this.height);
+    this.stage.addChild(this.world);
+    const safe = safeArea(config), toDesign = this.height / config.height, short = Math.min(config.width, config.height);
+    this.captionBar = options.captions?.length ? new CaptionBar(options.captions, {
+      x: safe.cx * toDesign, y: (safe.bottom - 0.06 * short) * toDesign, maxWidth: safe.width * 0.92 * toDesign, size: Math.round(0.035 * short * toDesign), ...options.captionStyle,
+    }) : null;
+    // Deferred so subclass fields exist before build() runs.
+    this.ready = Promise.resolve().then(() => this.build()).then(() => { if (this.captionBar) this.stage.addChild(this.captionBar); });
+  }
+
+  /** Load what the film needs (await fonts, textures), add scenes to this.world and register updates. Runs once. */
+  protected abstract build(): void | Promise<void>;
+  /** Registers a per-frame update; scene modules call film.on(t => …). */
+  on(update: Update) { this.updates.push(update); }
+  /** Adds a named review cue, such as a music hit the picture should land on. */
+  mark(time: number, label: string, id = `marker-${this.markers.length}`) { this.markers.push({ id, time, label }); }
+
+  get cues(): Cue[] {
+    return [
+      ...this.options.chapters.map((chapter, index) => ({ id: `chapter-${index}`, time: chapter.start, label: chapter.label })),
+      ...(this.options.captions ?? []).map((caption, index) => ({ id: `vo-${index}`, time: caption.start, label: caption.text })),
+      ...this.markers,
+    ];
+  }
+  get texts() { return collectTexts(this.stage); }
+
+  async render(seconds: number) {
+    await this.ready;
+    const t = Math.min(Math.max(seconds, 0), this.options.config.duration - 0.00001);
+    for (const update of this.updates) update(t);
+    this.captionBar?.update(t, this.captions);
+    this.app.render();
+  }
+}

package/templates/video/src/kit/fonts.ts

@@ -0,0 +1,29 @@
+/** Font files the film loads itself. Variable fonts get their weight range, so 800 renders as 800 instead of a synthesized bold. */
+export type FontSource = { family: string; url: string; weight?: string; style?: string };
+
+/** Reads the font's table directory for an `fvar` table (TrueType/OpenType and WOFF 1). WOFF2 falls back to the file name. */
+export async function isVariableFont(url: string, bytes?: ArrayBuffer) {
+  try {
+    const data = new DataView(bytes ?? await (await fetch(url)).arrayBuffer());
+    const signature = data.getUint32(0);
+    if (signature === 0x774f4632) return /variable|vf\b|\[wght/i.test(url);
+    const woff = signature === 0x774f4646;
+    const tables = data.getUint16(woff ? 12 : 4);
+    const first = woff ? 44 : 12, size = woff ? 20 : 16;
+    for (let index = 0; index < tables; index++) if (data.getUint32(first + index * size) === 0x66766172) return true;
+    return false;
+  } catch { return /variable|vf\b|\[wght/i.test(url); }
+}
+
+export async function loadFont({ family, url, weight, style }: FontSource) {
+  const bytes = await (await fetch(url)).arrayBuffer();
+  const range = weight ?? (await isVariableFont(url, bytes) ? "100 900" : undefined);
+  const face = new FontFace(family, bytes, { ...(range ? { weight: range } : {}), ...(style ? { style } : {}) });
+  document.fonts.add(await face.load());
+  return face;
+}
+
+export async function loadFonts(sources: FontSource[]) {
+  await Promise.all(sources.map(loadFont));
+  await document.fonts.ready;
+}

package/templates/video/src/kit/index.ts

@@ -0,0 +1,11 @@
+/** Shared film kit: import from "./kit" (standalone) or "../../../runtime/kit" (workspace animation). */
+export * from "./motion";
+export * from "./fonts";
+export * from "./text";
+export * from "./shapes";
+export * from "./textures";
+export * from "./components";
+export * from "./timing";
+export * from "./layout";
+export * from "./film-base";
+export * from "./dark-stage";

package/templates/video/src/kit/layout.ts

@@ -0,0 +1,40 @@
+import type { Container } from "pixi.js";
+import safeAreas from "../../shared/safe-areas.json";
+
+/** Margins in film pixels that platform UI may cover. Set "safeArea" in film.config.json; npm run review checks text against it. */
+export type Insets = { top: number; right: number; bottom: number; left: number };
+/** Insets, or a preset name from shared/safe-areas.json ("reels", "none"). */
+export type SafeAreaSetting = Insets | string | null | undefined;
+
+/**
+ * Presets are conservative starting points defined for a 1080-pixel-wide vertical film and scaled to the film's width.
+ * "reels": Instagram Reels, with the profile and caption at the bottom and actions on the right. Check current platform guidance.
+ */
+export const SAFE_AREA_PRESETS: Record<string, Insets> = safeAreas.presets;
+
+export function safeInsets(config: { width: number; safeArea?: SafeAreaSetting }): Insets {
+  if (!config.safeArea) return SAFE_AREA_PRESETS.none;
+  if (typeof config.safeArea !== "string") return config.safeArea;
+  const preset = SAFE_AREA_PRESETS[config.safeArea], scale = config.width / safeAreas.referenceWidth;
+  if (!preset) throw new Error(`Unknown safeArea "${config.safeArea}" in film.config.json. Use ${Object.keys(SAFE_AREA_PRESETS).join(", ")} or { top, right, bottom, left } insets.`);
+  return { top: preset.top * scale, right: preset.right * scale, bottom: preset.bottom * scale, left: preset.left * scale };
+}
+
+/** The usable rectangle of a film: config.safeArea (insets or a preset name), else the full frame. */
+export function safeArea(config: { width: number; height: number; safeArea?: SafeAreaSetting }) {
+  const insets = safeInsets(config);
+  const x = insets.left, y = insets.top, width = config.width - insets.left - insets.right, height = config.height - insets.top - insets.bottom;
+  return { x, y, width, height, right: x + width, bottom: y + height, cx: x + width / 2, cy: y + height / 2, insets };
+}
+
+/** Stacks nodes vertically from `y`, setting each anchor to the alignment; returns the y below the last one. */
+export function stack(nodes: Container[], { x, y, gap = 0, align = "center" }: { x: number; y: number; gap?: number; align?: "left" | "center" | "right" }) {
+  let cursor = y;
+  for (const node of nodes) {
+    const anchor = (node as Container & { anchor?: { set(x: number, y: number): void } }).anchor;
+    anchor?.set(align === "left" ? 0 : align === "right" ? 1 : 0.5, 0);
+    node.position.set(x, cursor);
+    cursor += node.height + gap;
+  }
+  return cursor - gap;
+}

package/templates/video/src/kit/motion.ts

@@ -0,0 +1,37 @@
+import type { Container, Text } from "pixi.js";
+
+/** Absolute-time helpers: every value is a pure function of film seconds, so seeking and export stay deterministic. */
+export const clamp01 = (value: number) => Math.max(0, Math.min(1, value));
+/** 0 → 1 progress of the window that starts `at` seconds and lasts `duration`. */
+export const win = (t: number, at: number, duration: number) => clamp01((t - at) / duration);
+export const easeOut = (x: number) => 1 - (1 - clamp01(x)) ** 3;
+export const easeIn = (x: number) => clamp01(x) ** 3;
+export const easeInOut = (x: number) => { x = clamp01(x); return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2; };
+/** Overshoots slightly before settling; for pops and snaps. */
+export const easeBack = (x: number) => { x = clamp01(x); const c1 = 1.70158, c3 = c1 + 1; return 1 + c3 * (x - 1) ** 3 + c1 * (x - 1) ** 2; };
+/** 0 → 1 → 0 over the unit interval; for flashes and pulses. */
+export const bump = (x: number) => (x <= 0 || x >= 1 ? 0 : Math.sin(Math.PI * x));
+export const lerp = (a: number, b: number, t: number) => a + (b - a) * t;
+/** Eases in at `at` and out at `out`; multiply alpha or offsets by it. */
+export const inOut = (t: number, at: number, out = Infinity, inSeconds = 0.45, outSeconds = 0.3) => easeOut(win(t, at, inSeconds)) * (1 - easeIn(win(t, out, outSeconds)));
+/** Linear blend of two 0xRRGGBB colors. */
+export function mixColor(a: number, b: number, t: number) {
+  t = clamp01(t);
+  const channel = (shift: number) => Math.round(((a >> shift) & 255) + ((((b >> shift) & 255) - ((a >> shift) & 255)) * t));
+  return (channel(16) << 16) | (channel(8) << 8) | channel(0);
+}
+/** "#7282F2" → 0x7282f2, for brand.json colors. */
+export const hex = (color: string) => Number.parseInt(color.replace(/^#/, ""), 16);
+/** Seeded PRNG (mulberry32). Never call Math.random() while rendering a frame. */
+export function rng(seed: number) {
+  return () => {
+    seed = (seed + 0x6d2b79f5) | 0;
+    let r = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r;
+    return ((r ^ (r >>> 14)) >>> 0) / 4294967296;
+  };
+}
+/** Sets alpha and hides fully transparent nodes, so review only measures text that is actually visible. */
+export const show = (node: Container, alpha: number) => { node.alpha = alpha; node.visible = alpha > 0.002; };
+/** Avoids re-rasterizing a Text whose content did not change. */
+export const setText = (node: Text, value: string) => { if (node.text !== value) node.text = value; };

package/templates/video/src/kit/shapes.ts

@@ -0,0 +1,68 @@
+import { Graphics } from "pixi.js";
+import { clamp01, lerp } from "./motion";
+
+export type Point = [number, number];
+export type PanelStyle = { radius?: number; fill?: number; fillAlpha?: number; stroke?: number; strokeAlpha?: number; strokeWidth?: number };
+
+/** Rounded card with an optional hairline border, drawn from (0, 0). */
+export function panel(width: number, height: number, { radius = 22, fill = 0x0c1437, fillAlpha = 0.9, stroke, strokeAlpha = 0.22, strokeWidth = 2 }: PanelStyle = {}) {
+  const g = new Graphics().roundRect(0, 0, width, height, radius).fill({ color: fill, alpha: fillAlpha });
+  if (stroke !== undefined) g.roundRect(0, 0, width, height, radius).stroke({ color: stroke, alpha: strokeAlpha, width: strokeWidth });
+  return g;
+}
+
+/** Strokes the first `amount` (0–1) of a polyline's length and returns the drawn points. */
+export function partialLine(g: Graphics, points: Point[], amount: number) {
+  if (points.length < 2 || amount <= 0) return [] as Point[];
+  let total = 0;
+  for (let i = 1; i < points.length; i++) total += Math.hypot(points[i][0] - points[i - 1][0], points[i][1] - points[i - 1][1]);
+  let left = total * clamp01(amount);
+  const out: Point[] = [points[0]];
+  for (let i = 1; i < points.length && left > 0; i++) {
+    const [ax, ay] = points[i - 1], [bx, by] = points[i];
+    const length = Math.hypot(bx - ax, by - ay);
+    if (left >= length) { out.push(points[i]); left -= length; } else { out.push([lerp(ax, bx, left / length), lerp(ay, by, left / length)]); left = 0; }
+  }
+  g.moveTo(...out[0]);
+  for (const point of out.slice(1)) g.lineTo(...point);
+  return out;
+}
+
+/** Samples a cubic Bézier into a polyline for partialLine() and pointAt(). */
+export function bezier(p0: Point, p1: Point, p2: Point, p3: Point, steps = 36) {
+  const points: Point[] = [];
+  for (let i = 0; i <= steps; i++) {
+    const u = i / steps, v = 1 - u;
+    points.push([v * v * v * p0[0] + 3 * v * v * u * p1[0] + 3 * v * u * u * p2[0] + u * u * u * p3[0], v * v * v * p0[1] + 3 * v * v * u * p1[1] + 3 * v * u * u * p2[1] + u * u * u * p3[1]]);
+  }
+  return points;
+}
+
+/** The point `fraction` (0–1) of the way along a polyline; for packets travelling along a wire. */
+export function pointAt(points: Point[], fraction: number): Point {
+  let total = 0;
+  const lengths = points.slice(1).map((point, i) => { const length = Math.hypot(point[0] - points[i][0], point[1] - points[i][1]); total += length; return length; });
+  let left = total * clamp01(fraction);
+  for (let i = 0; i < lengths.length; i++) {
+    if (left <= lengths[i]) return lengths[i] ? [lerp(points[i][0], points[i + 1][0], left / lengths[i]), lerp(points[i][1], points[i + 1][1], left / lengths[i])] : points[i];
+    left -= lengths[i];
+  }
+  return points[points.length - 1];
+}
+
+/** A check mark centred on (x, y) that draws on with `amount`. */
+export function check(g: Graphics, x: number, y: number, size: number, color: number, width = 4, amount = 1) {
+  partialLine(g, [[x - size * 0.5, y], [x - size * 0.12, y + size * 0.38], [x + size * 0.55, y - size * 0.4]], amount);
+  return g.stroke({ width, color, cap: "round", join: "round" });
+}
+
+export function cross(g: Graphics, x: number, y: number, size: number, color: number, width = 4, alpha = 1) {
+  return g.moveTo(x - size, y - size).lineTo(x + size, y + size).moveTo(x + size, y - size).lineTo(x - size, y + size).stroke({ width, color, alpha, cap: "round" });
+}
+
+/** A simple head-and-shoulders person icon. */
+export function person(g: Graphics, x: number, y: number, size: number, color: number, alpha = 1) {
+  g.circle(x, y - size * 0.3, size * 0.25).fill({ color, alpha });
+  return g.moveTo(x - size * 0.46, y + size * 0.48).quadraticCurveTo(x - size * 0.46, y + size * 0.04, x, y + size * 0.04)
+    .quadraticCurveTo(x + size * 0.46, y + size * 0.04, x + size * 0.46, y + size * 0.48).closePath().fill({ color, alpha });
+}

package/templates/video/src/kit/text.ts

@@ -0,0 +1,34 @@
+import { FillGradient, Text, type TextStyleOptions } from "pixi.js";
+import type { Branding } from "../player-types";
+
+export type Family = "heading" | "body" | "mono";
+export type Weight = "300" | "400" | "500" | "600" | "700" | "800" | "900";
+export type TextOptions = { family?: Family; weight?: Weight; fill?: TextStyleOptions["fill"] } & Partial<TextStyleOptions>;
+
+/** Font stacks for txt(). useBrandFonts() puts the brand's families first. */
+export const fontStacks: Record<Family, string[]> = { heading: ["Arial", "sans-serif"], body: ["Arial", "sans-serif"], mono: ["Menlo", "Consolas", "monospace"] };
+
+/** Use the brand's heading/body families (already loaded by the player) and optionally a mono family the film loads itself. */
+export function useBrandFonts(branding?: Branding, mono?: string) {
+  const stack = (family: string | undefined, fallback: string[]) => family ? [...family.split(",").map((part) => part.trim().replace(/^["']|["']$/g, "")).filter(Boolean), ...fallback] : fallback;
+  if (branding) {
+    fontStacks.heading = stack(branding.fonts.heading.family, ["system-ui", "sans-serif"]);
+    fontStacks.body = stack(branding.fonts.body.family, ["system-ui", "sans-serif"]);
+  }
+  if (mono) fontStacks.mono = stack(mono, ["Menlo", "Consolas", "monospace"]);
+}
+
+/**
+ * Text in film pixels. Headings get slightly tight tracking at display sizes, mono gets open tracking,
+ * and line height follows the family. Every option is a Pixi TextStyle override.
+ */
+export function txt(value: string, size: number, { family = "body", weight = "400", fill = 0xffffff, ...style }: TextOptions = {}) {
+  const letterSpacing = family === "mono" ? Math.round(size * 0.12) : family === "heading" && size >= 56 ? -Math.round(size * 0.028) : 0;
+  return new Text({ text: value, style: { fontFamily: fontStacks[family], fontSize: size, fontWeight: weight, fill, letterSpacing, lineHeight: Math.round(size * (family === "heading" ? 1.1 : 1.3)), ...style } });
+}
+
+/** A left-to-right (or top-to-bottom) gradient for text or shape fills, e.g. gradientFill(["#B45FC4", "#5566E8"]). */
+export function gradientFill(colors: string[], direction: "horizontal" | "vertical" = "horizontal") {
+  return new FillGradient({ start: { x: 0, y: 0 }, end: direction === "horizontal" ? { x: 1, y: 0 } : { x: 0, y: 1 },
+    colorStops: colors.map((color, index) => ({ offset: colors.length === 1 ? 0 : index / (colors.length - 1), color })) });
+}

package/templates/video/src/kit/textures.ts

@@ -0,0 +1,42 @@
+import { Texture } from "pixi.js";
+
+const rgb = (color: number) => `${(color >> 16) & 255},${(color >> 8) & 255},${color & 255}`;
+function canvasTexture(width: number, height: number, draw: (context: CanvasRenderingContext2D) => void) {
+  const canvas = document.createElement("canvas");
+  canvas.width = width; canvas.height = height;
+  draw(canvas.getContext("2d")!);
+  return Texture.from(canvas);
+}
+
+/** Soft radial light; scale the sprite up and animate alpha for ambient glows and blooms. */
+export function glowTexture(color: number, size = 512) {
+  return canvasTexture(size, size, (context) => {
+    const gradient = context.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+    gradient.addColorStop(0, `rgba(${rgb(color)},1)`); gradient.addColorStop(0.35, `rgba(${rgb(color)},0.42)`); gradient.addColorStop(1, `rgba(${rgb(color)},0)`);
+    context.fillStyle = gradient; context.fillRect(0, 0, size, size);
+  });
+}
+
+/** Darkened edges at half resolution; stretch the sprite to the film size. */
+export function vignetteTexture(width: number, height: number, color = 0x04081a, strength = 0.85) {
+  const w = Math.round(width / 2), h = Math.round(height / 2);
+  return canvasTexture(w, h, (context) => {
+    const gradient = context.createRadialGradient(w / 2, h * 0.46, Math.min(w, h) * 0.33, w / 2, h / 2, Math.max(w, h) * 0.73);
+    gradient.addColorStop(0, `rgba(${rgb(color)},0)`); gradient.addColorStop(1, `rgba(${rgb(color)},${strength})`);
+    context.fillStyle = gradient; context.fillRect(0, 0, w, h);
+  });
+}
+
+/** Rasterizes an SVG (e.g. a brand logo) at an exact pixel width, keeping its viewBox aspect ratio. */
+export async function rasterSvg(url: string, width: number) {
+  const source = await (await fetch(url)).text();
+  const box = /viewBox="([\d.\s,-]+)"/.exec(source)?.[1].trim().split(/[\s,]+/).map(Number);
+  const image = new Image();
+  const aspect = box && box[2] > 0 ? box[3] / box[2] : null;
+  const height = Math.max(1, Math.round(width * (aspect ?? 1)));
+  const tag = /<svg\b[^>]*>/.exec(source)?.[0];
+  const sized = tag ? source.replace(tag, tag.replace(/\s(width|height)="[^"]*"/g, "").replace(/<svg\b/, `<svg width="${width}" height="${height}"`)) : source;
+  image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(sized)}`;
+  await image.decode();
+  return canvasTexture(width, height, (context) => context.drawImage(image, 0, 0, width, height));
+}

package/templates/video/src/kit/timing.ts

@@ -0,0 +1,48 @@
+/** Cue lookup over production/audio/timing.json (written by npm run audio:vo), so scenes follow the voiceover when it is re-cut. */
+export type Caption = { start: number; end: number; text: string; segment?: string };
+export type Timing = { captions: Caption[]; segments?: { id: string; start: number; end: number }[]; voEnd?: number };
+
+export function cueSheet(timing: Timing) {
+  const bySegment = new Map<string, Caption[]>();
+  for (const caption of timing.captions) {
+    if (!caption.segment) continue;
+    bySegment.set(caption.segment, [...bySegment.get(caption.segment) ?? [], caption]);
+  }
+  const caption = (segment: string, index = 0) => {
+    const list = bySegment.get(segment);
+    const found = list?.at(index);
+    if (!found) throw new Error(`No caption ${index} in VO segment "${segment}". Known segments: ${[...bySegment.keys()].join(", ")}`);
+    return found;
+  };
+  return {
+    caption,
+    /** Start of the segment's index-th caption (negative counts from the end), plus an offset in seconds. */
+    at: (segment: string, index = 0, offset = 0) => caption(segment, index).start + offset,
+    /** End of the segment's index-th caption; the last one by default. */
+    end: (segment: string, index = -1, offset = 0) => caption(segment, index).end + offset,
+    segment: (id: string) => {
+      const found = timing.segments?.find((item) => item.id === id);
+      if (found) return found;
+      const list = bySegment.get(id);
+      if (!list?.length) throw new Error(`Unknown VO segment "${id}".`);
+      return { id, start: list[0].start, end: list.at(-1)!.end };
+    },
+    /** The first caption whose text contains `words` (case-insensitive); handy when phrases move between segments. */
+    find: (words: string) => {
+      const found = timing.captions.find((item) => item.text.toLowerCase().includes(words.toLowerCase()));
+      if (!found) throw new Error(`No caption contains "${words}".`);
+      return found;
+    },
+  };
+}
+
+/** Joins captions separated by less than `maxGap` seconds so on-screen captions don't flicker between phrases. */
+export function joinCaptions(captions: Caption[], maxGap = 0.3) {
+  const sorted = [...captions].sort((a, b) => a.start - b.start);
+  return sorted.map((caption, index) => {
+    const next = sorted[index + 1];
+    return next && next.start - caption.end < maxGap && next.start > caption.end ? { ...caption, end: next.start } : { ...caption };
+  });
+}
+
+export type CueSheet = ReturnType<typeof cueSheet>;

package/templates/video/src/player-types.ts

@@ -6,7 +6,13 @@ export type FilmConfig = {
   duration: number; language: string; audio: string | null;
   /** Seconds of the frame the MP4 export saves as its JPEG thumbnail. */
   poster?: number | null;
+  /** Platform UI margins: "reels", "none", or { top, right, bottom, left } in pixels. Review flags text outside it. */
+  safeArea?: { top: number; right: number; bottom: number; left: number } | string | null;
+  /** Smallest readable font size in pixels for review; defaults to 2.2% of the shorter side (24 px at 1080). */
+  minTextSize?: number;
 };
+/** A visible text box in film pixels; fontSize and role come from the kit's collectTexts(). */
+export type TextBox = { id: string; text: string; x: number; y: number; width: number; height: number; fontSize?: number; role?: string };
 export type Branding = {
   name: string; tagline: string; logo: string | null; assets?: Record<string, string>;
   colors: { primary: string; background: string; text: string };
@@ -15,7 +21,7 @@ export type Branding = {
 export type FilmContext = { branding: Branding; logo: Texture | null };
 export type FilmRenderer = {
   captions: boolean; resources: ResourceTrack[];
-  texts: { id: string; text: string; x: number; y: number; width: number; height: number }[];
+  texts: TextBox[];
   cues: unknown[];
   render(seconds: number): void | Promise<void>;
 };

package/templates/video/src/player.ts

@@ -3,6 +3,7 @@ import type { PlayerOptions } from "./player-types";
 import copy from "../shared/locales/en/player.json";
 import { publicAsset } from "./assets";
 import { downloadHtml, downloadUrl } from "./download";
+import { loadFonts } from "./kit/fonts";
 import type { ResourceTimeline } from "./resource-timeline";
 import "./style.css";
 
@@ -55,11 +56,8 @@ export async function mountPlayer({ config, Film, chapters, branding, exportEndp
     app.canvas.setAttribute("aria-label", config.title);
     element("canvas-host").append(app.canvas);
     element("loading").remove();
-    if (branding) {
-      for (const font of Object.values(branding.fonts)) {
-        if (font.file) { const face = new FontFace(font.family, `url(${JSON.stringify(publicAsset(font.file))})`); document.fonts.add(await face.load()); }
-      }
-    }
+    // Variable brand fonts are registered with their weight range, so bold weights are real rather than synthesized.
+    if (branding) await loadFonts(Object.values(branding.fonts).filter((font) => font.file).map((font) => ({ family: font.family.split(",")[0].trim().replace(/^["']|["']$/g, ""), url: publicAsset(font.file!) })));
     const logo = branding?.logo ? await Assets.load(publicAsset(branding.logo)) : null;
     const film = new Film(app, branding ? { branding, logo } : undefined);
     const audio = config.audio ? new Audio() : null;

package/templates/video/src/review.ts

@@ -5,6 +5,8 @@ type TextBounds = {
   y: number;
   width: number;
   height: number;
+  fontSize?: number;
+  role?: string;
 };
 type ReviewApi = {
   width: number;