@openvidstudio/mcp-server 0.1.0 → 1.4.0

package/templates/default/openvidstudio-stem/src/Equation.tsx

@@ -0,0 +1,132 @@
+import React, { useEffect, useMemo, useState } from "react";
+import { cancelRender, continueRender, delayRender, useCurrentFrame, useVideoConfig } from "remotion";
+import { E, tween } from "@openvidstudio/core";
+import { VOID } from "./designSystem";
+import { cachedSvg, texToSvg } from "./mathjax";
+import type { Point } from "./paths";
+
+export interface EquationProps {
+  /** The equation, as TeX. */
+  tex: string;
+  /**
+   * The equation as it is said, in plain words ("x squared plus one"). Required: a lesson's
+   * narration and its equation must say the same thing, and check_script compares this string with
+   * the narration of the beat. It is exposed on the element as `data-spoken`.
+   */
+  spoken: string;
+  /** Composition frame the first term appears. Default 0. */
+  at?: number;
+  /** Font size in px. Default 8.5% of the shorter side of the frame. */
+  size?: number;
+  /** Defaults to the Void's warm white. */
+  color?: string;
+  /** Centre of the equation. Default: the centre of the frame. */
+  center?: Point;
+  /** Frames between one term appearing and the next. Default 7. */
+  stagger?: number;
+}
+
+/** The frames a single term takes to arrive. */
+export const EQUATION_TERM_FRAMES = 10;
+
+export interface Parsed {
+  svg: SVGSVGElement;
+}
+
+/**
+ * The typeset equation as a DOM element. Parsed as HTML, which accepts what the SVG serialisation of
+ * MathJax's output contains; an XML parser rejects it when the TeX has a control character in it
+ * (MathJax keeps the TeX in a data-latex attribute, and a plain JavaScript string "\frac" holds a form feed).
+ */
+export function parse(markup: string): Parsed {
+  const doc = new DOMParser().parseFromString(markup, "text/html");
+  const svg = doc.body.querySelector("svg");
+  if (!svg) throw new Error("Equation: the typeset markup has no <svg> in it.");
+  return { svg: svg as unknown as SVGSVGElement };
+}
+
+/** The top-level terms of a typeset equation: the children of the root mrow, left to right. */
+export function termsOf(root: Element): { parent: Element; kids: Element[] } | null {
+  const math = root.querySelector('g[data-mml-node="math"]');
+  if (!math) return null;
+  const parent = math.children.length === 1 && math.children[0].getAttribute("data-mml-node") === "mrow" ? math.children[0] : math;
+  return { parent, kids: Array.from(parent.children) };
+}
+
+/**
+ * An equation, typeset in sans-serif maths and revealed term by term: each top-level term fades in and
+ * rises a little, one after another, as a pure function of the frame. Sized from the composition.
+ */
+export const Equation: React.FC<EquationProps> = ({ tex, spoken, at = 0, size, color, center, stagger = 7 }) => {
+  if (typeof spoken !== "string" || spoken.trim() === "") {
+    throw new Error("Equation: `spoken` is required, the equation as it is said (for example \"x squared plus one\"), so the narration and the equation can be checked against each other.");
+  }
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  const [markup, setMarkup] = useState<string | undefined>(() => cachedSvg(tex));
+  const [handle] = useState(() => delayRender(`Equation: typesetting ${tex.slice(0, 40)}`));
+
+  useEffect(() => {
+    if (markup !== undefined) {
+      continueRender(handle);
+      return;
+    }
+    let alive = true;
+    texToSvg(tex).then(
+      (svg) => {
+        if (!alive) return;
+        setMarkup(svg);
+      },
+      (err) => cancelRender(err),
+    );
+    return () => {
+      alive = false;
+    };
+  }, [tex, markup, handle]);
+
+  const parsed = useMemo(() => (markup === undefined ? null : parse(markup)), [markup]);
+  if (!parsed) return null;
+
+  const px = size ?? Math.round(Math.min(width, height) * 0.085);
+  const c = center ?? { x: width / 2, y: height / 2 };
+  // Rebuild the equation's own structure around each term, so the term's own transform is untouched.
+  const html = (() => {
+    const root = parsed.svg.cloneNode(true) as SVGSVGElement;
+    const terms = termsOf(root);
+    // Unrecognised structure: show the equation whole rather than not at all.
+    if (!terms) return root.outerHTML;
+    terms.kids.forEach((kid, i) => {
+      const start = at + i * stagger;
+      const p = tween(frame, [start, start + EQUATION_TERM_FRAMES], [0, 1], E.cinematic);
+      const wrapper = root.ownerDocument.createElementNS("http://www.w3.org/2000/svg", "g");
+      // Fill and stroke opacity, not `opacity`: group opacity makes the browser rasterise each term
+      // into an offscreen layer, whose antialiasing can differ by a few levels from one visit to the
+      // same frame to the next. The markup for a frame is always identical; this keeps the pixels close.
+      wrapper.setAttribute("fill-opacity", p.toFixed(4));
+      wrapper.setAttribute("stroke-opacity", p.toFixed(4));
+      // The root group is flipped (scale(1,-1)), so a negative y is down: terms rise from 0.25em below.
+      wrapper.setAttribute("transform", `translate(0,${(-(1 - p) * 250).toFixed(2)})`);
+      terms.parent.replaceChild(wrapper, kid);
+      wrapper.appendChild(kid);
+    });
+    return root.outerHTML;
+  })();
+  return (
+    <div
+      data-ovs-equation=""
+      data-spoken={spoken}
+      data-tex={tex}
+      style={{
+        position: "absolute",
+        left: c.x,
+        top: c.y,
+        transform: "translate(-50%, -50%)",
+        fontSize: px,
+        color: color ?? VOID.text,
+        lineHeight: 0,
+        pointerEvents: "none",
+      }}
+      dangerouslySetInnerHTML={{ __html: html }}
+    />
+  );
+};

package/templates/default/openvidstudio-stem/src/FreeBody.tsx

@@ -0,0 +1,152 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { E, tween } from "@openvidstudio/core";
+import { SUBJECT_ACCENT, VOID, bodyStack, displayStack } from "./designSystem";
+import { lineWeight } from "./graph";
+import type { Point } from "./paths";
+
+export interface Force {
+  label: string;
+  /** In the units the scale is given in (newtons, say). */
+  magnitude: number;
+  /** Degrees, counter-clockwise from the right: 0 is right, 90 is up, 270 is down. */
+  angle: number;
+  color?: string;
+}
+
+export interface FreeBodyProps {
+  forces: Force[];
+  /** Pixels per unit of magnitude. An arrow is exactly `magnitude * scale` px from tail to tip. */
+  scale: number;
+  /** Unit shown on the scale bar. Default "N". */
+  unit?: string;
+  /** The length the scale bar stands for, in the same units as `magnitude`. Default: a round value near the largest force. */
+  scaleValue?: number;
+  /** Where the scale bar's left end sits. Default: lower left of the frame. */
+  scaleAt?: Point;
+  /** Where the object is. Default: the centre of the frame. */
+  origin?: Point;
+  /** Side of the object in px. Default 9% of the shorter side. */
+  objectSize?: number;
+  /** Tilt of the object, degrees clockwise, for a block on a slope. Default 0. */
+  objectRotation?: number;
+  /** Composition frame the first arrow starts to grow. Default 0. */
+  at?: number;
+  /** Frames between one arrow starting and the next. Default 18. */
+  stagger?: number;
+  /** The order the arrows arrive in, as indices into `forces`. Default: as given. */
+  order?: number[];
+  /** Also draw the net force, a dashed arrow, after the others have arrived. Left out when the net is zero. */
+  net?: boolean;
+  /** Shown on the object. */
+  objectLabel?: string;
+}
+
+/** Frames one arrow takes to grow to full length. */
+export const ARROW_GROW_FRAMES = 14;
+
+const toRad = (deg: number) => (deg * Math.PI) / 180;
+
+function roundValue(v: number): number {
+  const pow = 10 ** Math.floor(Math.log10(v));
+  const f = v / pow;
+  return (f >= 5 ? 5 : f >= 2 ? 2 : 1) * pow;
+}
+
+const Arrow: React.FC<{ from: Point; angle: number; length: number; color: string; weight: number; dashed?: boolean; dataset: Record<string, string> }> = ({ from, angle, length, color, weight, dashed, dataset }) => {
+  if (length <= 0) return null;
+  const dx = Math.cos(toRad(angle));
+  const dy = -Math.sin(toRad(angle));
+  const head = Math.min(weight * 5, length * 0.6);
+  const tip = { x: from.x + dx * length, y: from.y + dy * length };
+  const base = { x: from.x + dx * (length - head), y: from.y + dy * (length - head) };
+  const half = head * 0.55;
+  const left = { x: base.x - dy * half, y: base.y + dx * half };
+  const right = { x: base.x + dy * half, y: base.y - dx * half };
+  return (
+    <g {...dataset}>
+      <line x1={from.x} y1={from.y} x2={base.x} y2={base.y} stroke={color} strokeWidth={weight} strokeDasharray={dashed ? `${weight * 2.5} ${weight * 2}` : undefined} />
+      <polygon points={`${tip.x},${tip.y} ${left.x},${left.y} ${right.x},${right.y}`} fill={color} />
+    </g>
+  );
+};
+
+/**
+ * An object with labelled force arrows, the picture a physics lesson explains. The arrows are honest:
+ * each is exactly `magnitude * scale` px long, and a scale bar says how much that is, so a viewer can
+ * compare two forces by eye and be right. Arrows arrive one at a time. A pure function of the frame.
+ */
+export const FreeBody: React.FC<FreeBodyProps> = ({ forces, scale, unit = "N", scaleValue, scaleAt, origin, objectSize, objectRotation = 0, at = 0, stagger = 18, order, net = false, objectLabel }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  const weight = lineWeight(width, height);
+  const o = origin ?? { x: width / 2, y: height / 2 };
+  const size = objectSize ?? Math.round(Math.min(width, height) * 0.09);
+  const sequence = order ?? forces.map((_, i) => i);
+  const labelPx = Math.round(Math.min(width, height) * 0.03);
+  const accent = SUBJECT_ACCENT.physics;
+  const palette = [accent.accent, "#5CC8FF", accent.accentAlt, "#7CFFB2", "#B58CFF"];
+
+  const grown = (i: number) => {
+    const slot = sequence.indexOf(i);
+    if (slot < 0) return 0;
+    const start = at + slot * stagger;
+    return tween(frame, [start, start + ARROW_GROW_FRAMES], [0, 1], E.cinematic);
+  };
+  const allDone = at + (sequence.length - 1) * stagger + ARROW_GROW_FRAMES;
+  const netVec = forces.reduce((acc, f) => ({ x: acc.x + f.magnitude * Math.cos(toRad(f.angle)), y: acc.y + f.magnitude * Math.sin(toRad(f.angle)) }), { x: 0, y: 0 });
+  const netMagnitude = Math.hypot(netVec.x, netVec.y);
+  const netAngle = (Math.atan2(netVec.y, netVec.x) * 180) / Math.PI;
+  const netP = tween(frame, [allDone + 6, allDone + 6 + ARROW_GROW_FRAMES], [0, 1], E.cinematic);
+
+  const maxMagnitude = Math.max(...forces.map((f) => f.magnitude), 1e-9);
+  const barValue = scaleValue ?? roundValue(maxMagnitude / 2);
+  const barAt = scaleAt ?? { x: Math.round(width * 0.12), y: Math.round(height * 0.88) };
+  const barLength = barValue * scale;
+  const fmt = (v: number) => String(Number(v.toFixed(2)));
+
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none" }} data-ovs-freebody="">
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+        <g transform={`rotate(${objectRotation} ${o.x} ${o.y})`}>
+          <rect data-ovs-object="" x={o.x - size / 2} y={o.y - size / 2} width={size} height={size} rx={size * 0.08} fill={VOID.panel} stroke={VOID.textDim} strokeWidth={weight} />
+        </g>
+        {objectLabel && <text x={o.x} y={o.y + labelPx * 0.35} textAnchor="middle" fontSize={labelPx} fill={VOID.textDim} fontFamily={bodyStack()}>{objectLabel}</text>}
+        {forces.map((f, i) => {
+          const p = grown(i);
+          const color = f.color ?? palette[i % palette.length];
+          const length = f.magnitude * scale * p;
+          const dx = Math.cos(toRad(f.angle));
+          const dy = -Math.sin(toRad(f.angle));
+          return (
+            <g key={i}>
+              <Arrow from={o} angle={f.angle} length={length} color={color} weight={weight * 1.6} dataset={{ "data-ovs-force": f.label }} />
+              {p >= 0.6 && (
+                <text
+                  x={o.x + dx * (f.magnitude * scale + labelPx * 1.1)}
+                  y={o.y + dy * (f.magnitude * scale + labelPx * 1.1) + labelPx * 0.35}
+                  textAnchor="middle"
+                  fontSize={labelPx}
+                  fill={color}
+                  fontFamily={displayStack()}
+                  fontWeight={700}
+                >
+                  {f.label}
+                </text>
+              )}
+            </g>
+          );
+        })}
+        {net && netMagnitude > 1e-3 * maxMagnitude && netP > 0 && (
+          <Arrow from={o} angle={netAngle} length={netMagnitude * scale * netP} color={VOID.text} weight={weight * 1.3} dashed dataset={{ "data-ovs-force": "net" }} />
+        )}
+        <g data-ovs-scale="">
+          <line x1={barAt.x} y1={barAt.y} x2={barAt.x + barLength} y2={barAt.y} stroke={VOID.textDim} strokeWidth={weight} />
+          <line x1={barAt.x} y1={barAt.y - weight * 3} x2={barAt.x} y2={barAt.y + weight * 3} stroke={VOID.textDim} strokeWidth={weight} />
+          <line x1={barAt.x + barLength} y1={barAt.y - weight * 3} x2={barAt.x + barLength} y2={barAt.y + weight * 3} stroke={VOID.textDim} strokeWidth={weight} />
+          <text x={barAt.x + barLength + weight * 5} y={barAt.y + labelPx * 0.35} fontSize={labelPx} fill={VOID.textDim} fontFamily={bodyStack()}>{`${fmt(barValue)} ${unit}`}</text>
+        </g>
+      </svg>
+    </div>
+  );
+};

package/templates/default/openvidstudio-stem/src/GraphViz.tsx

@@ -0,0 +1,249 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { E, tween } from "@openvidstudio/core";
+import { SUBJECT_ACCENT, VOID, bodyStack, displayStack } from "./designSystem";
+import { lineWeight } from "./graph";
+import { Spark } from "./Spark";
+import { walk as walkPath, type Point } from "./paths";
+
+export type GraphRole = "unvisited" | "frontier" | "visiting" | "done" | "path";
+export const GRAPH_ROLES: readonly GraphRole[] = ["unvisited", "frontier", "visiting", "done", "path"];
+
+/** The fill of each role: dim, accent, warm white, a second accent, ember. Text on a filled node is the void colour. */
+export const GRAPH_ROLE_COLOR: Record<GraphRole, string> = {
+  unvisited: VOID.panel,
+  frontier: SUBJECT_ACCENT.cs.accent,
+  visiting: VOID.text,
+  done: SUBJECT_ACCENT.math.accent,
+  path: SUBJECT_ACCENT.physics.accentAlt,
+};
+
+export interface GraphNode {
+  id: string;
+  /** Fractions of the layout box, 0..1. Give all nodes both, or none (then they sit on a circle). */
+  x?: number;
+  y?: number;
+  /** Text inside the node. Default: the id. */
+  label?: string;
+}
+
+/** A snapshot from `frame` on: the latest step at or before the current frame says every node's role. */
+export interface GraphStep {
+  frame: number;
+  visit?: string;
+  frontier?: string[];
+  done?: string[];
+  path?: string[];
+}
+
+export interface GraphVizProps {
+  nodes: GraphNode[];
+  /** `[from, to]` pairs of node ids. */
+  edges: [string, string][];
+  directed?: boolean;
+  steps?: GraphStep[];
+  /** An ordered list of node ids a single Spark hops along. */
+  walk?: string[];
+  /** Frames to hop, and to rest on each node. Defaults 20 and 20. */
+  hop?: number;
+  hold?: number;
+  /** Frame the Spark starts, default `at`. */
+  walkAt?: number;
+  /** Frame the graph appears. Default 0. */
+  at?: number;
+  /** The layout box in px. Default: 80% of the width, from 17% down, 45% of the height. */
+  box?: { x: number; y: number; w: number; h: number };
+  /** Node radius, px. Default 4.5% of the shorter side. */
+  radius?: number;
+  /** Draw the legend of roles. Default true. */
+  legend?: boolean;
+}
+
+export type Adjacency = Record<string, string[]>;
+
+/** Adjacency lists from an edge list. Undirected unless `directed`. Neighbours keep edge order. */
+export function adjacencyFrom(edges: [string, string][], directed = false, ids: string[] = []): Adjacency {
+  const adj: Adjacency = {};
+  for (const id of ids) adj[id] = [];
+  for (const [a, b] of edges) {
+    (adj[a] ??= []).push(b);
+    (adj[b] ??= []);
+    if (!directed) adj[b].push(a);
+  }
+  return adj;
+}
+
+/** Breadth-first visiting order from `start`, neighbours taken in their listed order. */
+export function bfsOrder(adjacency: Adjacency, start: string): string[] {
+  const seen = new Set([start]);
+  const order: string[] = [];
+  const queue = [start];
+  for (let i = 0; i < queue.length; i++) {
+    const v = queue[i];
+    order.push(v);
+    for (const w of adjacency[v] ?? []) if (!seen.has(w)) { seen.add(w); queue.push(w); }
+  }
+  return order;
+}
+
+/** A shortest path (fewest edges) from `from` to `to`, both included, or null when unreachable. */
+export function shortestPath(adjacency: Adjacency, from: string, to: string): string[] | null {
+  const parent = new Map<string, string | null>([[from, null]]);
+  const queue = [from];
+  for (let i = 0; i < queue.length; i++) {
+    const v = queue[i];
+    if (v === to) break;
+    for (const w of adjacency[v] ?? []) if (!parent.has(w)) { parent.set(w, v); queue.push(w); }
+  }
+  if (!parent.has(to)) return null;
+  const path = [to];
+  while (parent.get(path[0]) != null) path.unshift(parent.get(path[0]) as string);
+  return path;
+}
+
+/**
+ * Steps for a real BFS: visiting the k-th node of the order at frame `first + k * every`, with
+ * the nodes already visited as done and the discovered-but-unvisited as the frontier. With `goal`,
+ * a last step `every` frames after shows the shortest path.
+ */
+export function bfsSteps(adjacency: Adjacency, start: string, opts: { first?: number; every?: number; goal?: string } = {}): GraphStep[] {
+  const first = opts.first ?? 0;
+  const every = opts.every ?? 30;
+  const order = bfsOrder(adjacency, start);
+  const steps: GraphStep[] = order.map((visit, k) => {
+    const visited = new Set(order.slice(0, k + 1));
+    const frontier = order.slice(k + 1).filter((v) => order.slice(0, k + 1).some((u) => (adjacency[u] ?? []).includes(v)) && !visited.has(v));
+    return { frame: first + k * every, visit, done: order.slice(0, k), frontier };
+  });
+  if (opts.goal) {
+    const path = shortestPath(adjacency, start, opts.goal);
+    if (path) steps.push({ frame: first + order.length * every, path });
+  }
+  return steps;
+}
+
+export interface GraphLayout {
+  box: { x: number; y: number; w: number; h: number };
+  radius: number;
+  /** Node centres in px, by id. */
+  centers: Record<string, Point>;
+}
+
+/** Where the nodes sit. Fractional nodes: box.x + x * box.w. No fractions: evenly round a circle that fits the box. */
+export function graphLayout(nodes: GraphNode[], width: number, height: number, opts: { box?: GraphVizProps["box"]; radius?: number } = {}): GraphLayout {
+  const box = opts.box ?? { x: Math.round(width * 0.1), y: Math.round(height * 0.17), w: Math.round(width * 0.8), h: Math.round(height * 0.45) };
+  const radius = opts.radius ?? Math.round(Math.min(width, height) * 0.045);
+  const centers: Record<string, Point> = {};
+  const placed = nodes.every((n) => n.x !== undefined && n.y !== undefined);
+  nodes.forEach((n, i) => {
+    if (placed) centers[n.id] = { x: box.x + (n.x as number) * box.w, y: box.y + (n.y as number) * box.h };
+    else {
+      const a = -Math.PI / 2 + (2 * Math.PI * i) / nodes.length;
+      const rr = Math.min(box.w, box.h) / 2 - radius;
+      centers[n.id] = { x: box.x + box.w / 2 + rr * Math.cos(a), y: box.y + box.h / 2 + rr * Math.sin(a) };
+    }
+  });
+  return { box, radius, centers };
+}
+
+const roleAt = (steps: GraphStep[], frame: number): { roles: Map<string, GraphRole>; path: string[] } => {
+  const roles = new Map<string, GraphRole>();
+  let current: GraphStep | undefined;
+  for (const s of steps) if (s.frame <= frame && (!current || s.frame >= current.frame)) current = s;
+  if (!current) return { roles, path: [] };
+  for (const id of current.frontier ?? []) roles.set(id, "frontier");
+  for (const id of current.done ?? []) roles.set(id, "done");
+  if (current.visit) roles.set(current.visit, "visiting");
+  for (const id of current.path ?? []) roles.set(id, "path");
+  return { roles, path: current.path ?? [] };
+};
+
+/**
+ * Nodes and edges, with node colours that say where a search has got to: dim until reached, violet
+ * on the frontier, warm white on the node being visited, blue once done, ember along the final
+ * path. The legend names the roles. A `walk` hops one Spark node to node; it is the only glowing
+ * thing. Pure in the frame; sizes from the composition.
+ */
+export const GraphViz: React.FC<GraphVizProps> = ({ nodes, edges, directed = false, steps = [], walk, hop = 20, hold = 20, walkAt, at = 0, box, radius, legend = true }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  if (frame < at) return null;
+  const weight = lineWeight(width, height);
+  const layout = graphLayout(nodes, width, height, { box, radius });
+  const { centers, radius: r } = layout;
+  const fontPx = Math.round(r * 0.8);
+  const legendPx = Math.round(Math.min(width, height) * 0.027);
+  const opacity = tween(frame, [at, at + 12], [0, 1], E.cinematic);
+  const { roles, path } = roleAt(steps, frame);
+  const onPath = new Set<string>();
+  path.forEach((id, i) => { if (i > 0) onPath.add(`${path[i - 1]}|${id}`); });
+  const isPathEdge = (a: string, b: string) => onPath.has(`${a}|${b}`) || (!directed && onPath.has(`${b}|${a}`));
+  const head = Math.max(weight * 4, r * 0.35);
+
+  // legend rows, wrapped to the box width
+  const items = GRAPH_ROLES.map((role) => ({ role, w: legendPx * 0.9 + legendPx * 0.4 + role.length * legendPx * 0.62 + legendPx * 1.2 }));
+  const rows: (typeof items)[] = [[]];
+  let rowW = 0;
+  for (const it of items) {
+    if (rowW + it.w > layout.box.w && rows[rows.length - 1].length) { rows.push([]); rowW = 0; }
+    rows[rows.length - 1].push(it);
+    rowW += it.w;
+  }
+  const legendTop = layout.box.y + layout.box.h + Math.round(height * 0.05);
+
+  // The first node is repeated so that node k is rested on during local frames [k*(hop+hold)+hop, (k+1)*(hop+hold)].
+  const stops = walk?.map((id) => centers[id]).filter(Boolean) ?? [];
+  const walkPoints = stops.length ? [stops[0], ...stops] : [];
+
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none" }} data-ovs-graphviz="">
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }} opacity={opacity < 1 ? opacity : undefined}>
+        {edges.map(([a, b]) => {
+          const p = centers[a];
+          const q = centers[b];
+          if (!p || !q) return null;
+          const hot = isPathEdge(a, b);
+          const d = Math.hypot(q.x - p.x, q.y - p.y) || 1;
+          const ux = (q.x - p.x) / d;
+          const uy = (q.y - p.y) / d;
+          const end = directed ? { x: q.x - ux * r, y: q.y - uy * r } : q;
+          const color = hot ? GRAPH_ROLE_COLOR.path : VOID.textDim;
+          return (
+            <g key={`${a}-${b}`} data-ovs-edge={`${a}-${b}`} data-ovs-edge-hot={hot ? "1" : "0"}>
+              <line x1={p.x} y1={p.y} x2={end.x} y2={end.y} data-ovs-edge-line="" stroke={color} strokeWidth={hot ? weight * 2 : weight} strokeLinecap="round" />
+              {directed && <polygon points={`${end.x},${end.y} ${end.x - ux * head - uy * head * 0.55},${end.y - uy * head + ux * head * 0.55} ${end.x - ux * head + uy * head * 0.55},${end.y - uy * head - ux * head * 0.55}`} fill={color} />}
+            </g>
+          );
+        })}
+        {nodes.map((n) => {
+          const c = centers[n.id];
+          const role = roles.get(n.id) ?? "unvisited";
+          const fill = GRAPH_ROLE_COLOR[role];
+          const stroke = role === "unvisited" ? VOID.textDim : role === "visiting" ? SUBJECT_ACCENT.cs.accent : fill;
+          return (
+            <g key={n.id} data-ovs-node={n.id} data-ovs-role={role}>
+              <circle data-ovs-node-circle="" cx={c.x} cy={c.y} r={r - weight / 2} fill={fill} stroke={stroke} strokeWidth={weight} />
+              <text x={c.x} y={c.y + fontPx * 0.35} textAnchor="middle" fontSize={fontPx} fontWeight={700} fontFamily={displayStack()} fill={role === "unvisited" ? VOID.text : VOID.base}>{n.label ?? n.id}</text>
+            </g>
+          );
+        })}
+        {legend && rows.map((row, ri) => {
+          const total = row.reduce((s, it) => s + it.w, 0);
+          let x = layout.box.x + (layout.box.w - total) / 2;
+          const y = legendTop + ri * legendPx * 1.9;
+          return row.map((it) => {
+            const sx = x + legendPx * 0.45;
+            x += it.w;
+            return (
+              <g key={it.role} data-ovs-legend={it.role}>
+                <circle cx={sx} cy={y} r={legendPx * 0.45} fill={GRAPH_ROLE_COLOR[it.role]} stroke={it.role === "unvisited" ? VOID.textDim : GRAPH_ROLE_COLOR[it.role]} strokeWidth={weight} />
+                <text x={sx + legendPx * 0.8} y={y + legendPx * 0.35} fontSize={legendPx} fontFamily={bodyStack()} fill={VOID.textDim}>{it.role}</text>
+              </g>
+            );
+          });
+        })}
+      </svg>
+      {walkPoints.length > 0 && <Spark path={walkPath(walkPoints, { hop, hold })} at={Math.max(at, walkAt ?? at)} trail={10} size={Math.max(4, Math.round(r * 0.3))} subject="cs" />}
+    </div>
+  );
+};

package/templates/default/openvidstudio-stem/src/LessonCaptions.tsx

@@ -0,0 +1,135 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { useNarrationWords } from "@openvidstudio/core";
+import { SUBJECT_ACCENT, VOID, bodyStack, type Subject } from "./designSystem";
+
+export interface LessonCaptionsProps {
+  /** The beat these captions belong to: its word timings are read with `useNarrationWords(beatId)`. */
+  beatId: string;
+  /** The beat's narration text, its `vo`. The word timings carry bare words, so the punctuation comes from here. */
+  text: string;
+  /** Where the block sits: above the bottom safe zone, or below the top one. Default "bottom". */
+  position?: "bottom" | "top";
+  /** Most words in one caption. Default 6. */
+  maxWords?: number;
+  /** Left edge in px. Default 10% of the width. */
+  left?: number;
+  /** Width in px. Default: the frame minus the left edge on both sides. */
+  width?: number;
+  /** Picks the colour of the word being said. Default "math". */
+  subject?: Subject;
+  /** Font size in px. Default 4.8% of the shorter side. */
+  fontSize?: number;
+}
+
+/** A caption never starts or stops mid-sentence: a sentence end always breaks, a comma only after this many words. */
+const COMMA_BREAK_MIN_WORDS = 3;
+const SENTENCE_END = /[.?!:…]["')\]]*$/;
+const CLAUSE_END = /[,;]["')\]]*$/;
+
+/**
+ * Pure: where each caption starts and ends, as `[from, to)` ranges over the words. A caption breaks after a
+ * sentence end, after a comma or semicolon once it holds at least three words, and at `maxWords`. A one word
+ * sentence ("Why?") is a caption on its own.
+ */
+export function captionChunks(words: string[], maxWords = 6): [number, number][] {
+  const limit = Math.max(1, Math.floor(maxWords));
+  const chunks: [number, number][] = [];
+  let from = 0;
+  for (let i = 0; i < words.length; i++) {
+    const size = i - from + 1;
+    const last = i === words.length - 1;
+    if (last || SENTENCE_END.test(words[i]) || (CLAUSE_END.test(words[i]) && size >= COMMA_BREAK_MIN_WORDS) || size >= limit) {
+      chunks.push([from, i + 1]);
+      from = i + 1;
+    }
+  }
+  return chunks;
+}
+
+/** The share of the frame's height kept clear at the bottom and top: Instagram's interface over a vertical reel, a small margin otherwise. */
+export function captionInsets(width: number, height: number): { top: number; bottom: number } {
+  return height > width ? { top: Math.round(height * 0.14), bottom: Math.round(height * 0.22) } : { top: Math.round(height * 0.08), bottom: Math.round(height * 0.08) };
+}
+
+/**
+ * Burned-in captions for a lesson, timed to the narration: the words of the beat's `vo` in short chunks that
+ * break at sentence ends, with the word being said picked out. One line in a scene, with no dependency on the
+ * scene file:
+ *
+ *   <LessonCaptions beatId="hook" text={vo} />
+ *
+ * Reads `useNarrationWords(beatId)`. When the text splits into as many words as the timings hold it shows the text
+ * with its punctuation; when the counts differ it falls back to the timings' bare words. With no timings at all
+ * (an engine that gives none) the words are spread evenly over the scene and the element says so in
+ * `data-ovs-captions-timing="estimated"`. The block is tagged `data-ovs-captions`, which validate_scenes uses to
+ * ignore the captions when it looks for a diagram or a static stretch. A pure function of the frame.
+ */
+export const LessonCaptions: React.FC<LessonCaptionsProps> = ({ beatId, text, position = "bottom", maxWords = 6, left, width: boxWidth, subject = "math", fontSize }) => {
+  const frame = useCurrentFrame();
+  const { width, height, durationInFrames } = useVideoConfig();
+  const narration = useNarrationWords(beatId);
+  const tokens = text.split(/\s+/).filter(Boolean);
+  const timed = narration.available;
+  const words = timed ? (tokens.length === narration.words.length ? tokens : narration.words.map((w) => w.word)) : tokens;
+  const timing = !timed ? "estimated" : tokens.length === narration.words.length ? "matched" : "bare";
+
+  const spoken = timed ? narration.wordAt(frame)?.index ?? -1 : words.length === 0 ? -1 : Math.min(words.length - 1, Math.floor((frame / Math.max(1, durationInFrames)) * words.length));
+  const chunks = captionChunks(words, maxWords);
+  const chunk = spoken < 0 ? null : chunks.find(([from, to]) => spoken >= from && spoken < to) ?? null;
+
+  const px = fontSize ?? Math.round(Math.min(width, height) * 0.048);
+  const edge = left ?? Math.round(width * 0.1);
+  const blockWidth = boxWidth ?? width - 2 * edge;
+  const insets = captionInsets(width, height);
+  const accent = SUBJECT_ACCENT[subject].accent;
+
+  return (
+    <div
+      data-ovs-captions=""
+      data-ovs-captions-timing={timing}
+      data-ovs-captions-position={position}
+      style={{
+        position: "absolute",
+        left: edge,
+        width: blockWidth,
+        ...(position === "bottom" ? { bottom: insets.bottom } : { top: insets.top }),
+        display: "flex",
+        justifyContent: "center",
+        pointerEvents: "none",
+      }}
+    >
+      {chunk && (
+        <div
+          data-ovs-caption=""
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            justifyContent: "center",
+            columnGap: px * 0.28,
+            rowGap: px * 0.1,
+            maxWidth: "100%",
+            padding: `${Math.round(px * 0.3)}px ${Math.round(px * 0.5)}px`,
+            borderRadius: Math.round(px * 0.4),
+            background: "rgba(7,6,11,0.72)",
+            fontFamily: bodyStack(),
+            fontSize: px,
+            lineHeight: 1.25,
+            fontWeight: 600,
+            textAlign: "center",
+          }}
+        >
+          {words.slice(chunk[0], chunk[1]).map((w, k) => {
+            const index = chunk[0] + k;
+            const active = index === spoken;
+            return (
+              <span key={index} data-ovs-word={index} data-active={active ? "true" : "false"} style={{ color: active ? accent : VOID.text }}>
+                {w}
+              </span>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+};