@openvidstudio/mcp-server 1.3.1 → 1.4.0

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>
+  );
+};

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

@@ -0,0 +1,187 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { E, tween } from "@openvidstudio/core";
+import { SUBJECT_ACCENT, VOID, bodyStack, displayStack, type Subject } from "./designSystem";
+import { lineWeight, type Box } from "./graph";
+import type { Point } from "./paths";
+
+export type Matrix2 = [[number, number], [number, number]];
+
+export interface MatrixGridProps {
+  /** The 2x2 matrix, rows first: `[[a, b], [c, d]]` sends (x, y) to (a x + b y, c x + d y). */
+  matrix: number[][];
+  /** Composition frame the picture appears and the transform starts. Default 0. */
+  at?: number;
+  /** Frames the plane takes to go from the identity to the matrix. Default 45. */
+  duration?: number;
+  /** Animate the transform. With false the plane is shown already transformed. Default true. */
+  transform?: boolean;
+  /** Shapes the progress 0..1. Default `E.cinematic`; pass `(t) => t` for a linear sweep. */
+  ease?: (t: number) => number;
+  /** The grid of points: `extent` is how far it reaches on each side of the origin and `spacing` the gap, both in graph units. Default 2 and 1. */
+  grid?: { extent?: number; spacing?: number };
+  /** Draw the unit square and its image, with the images of i-hat and j-hat as arrows. Default true. */
+  unitSquare?: boolean;
+  /** Draw the matrix in brackets above (portrait) or beside (landscape) the plane. Default true. */
+  showMatrix?: boolean;
+  /** Where the plane is drawn. Its centre is the origin. Default: the middle band of the frame. */
+  box?: Box;
+  /** Pixels per graph unit. Default: fits the grid, the unit square and their images inside the box. */
+  scale?: number;
+  /** Picks the accent. Default "math". */
+  subject?: Subject;
+}
+
+export interface MatrixGridGeometry {
+  box: Box;
+  origin: Point;
+  scale: number;
+  /** A graph point to composition pixels (y is up in the graph). */
+  toScreen: (x: number, y: number) => Point;
+}
+
+/** The identity moved `progress` of the way to `m`, entry by entry: the matrix on screen at that moment. */
+export function interpolateMatrix(m: number[][], progress: number): Matrix2 {
+  const id = [[1, 0], [0, 1]];
+  const at = (r: number, c: number) => id[r][c] + (m[r][c] - id[r][c]) * progress;
+  return [[at(0, 0), at(0, 1)], [at(1, 0), at(1, 1)]];
+}
+
+/** `m` applied to the point (x, y). */
+export function applyMatrix(m: number[][], x: number, y: number): Point {
+  return { x: m[0][0] * x + m[0][1] * y, y: m[1][0] * x + m[1][1] * y };
+}
+
+/** The default plane box: the middle band in portrait, the right-hand side in landscape (the matrix goes beside it). */
+export function defaultMatrixBox(width: number, height: number): Box {
+  return height > width
+    ? { x: Math.round(width * 0.1), y: Math.round(height * 0.3), width: Math.round(width * 0.8), height: Math.round(height * 0.4) }
+    : { x: Math.round(width * 0.4), y: Math.round(height * 0.14), width: Math.round(width * 0.56), height: Math.round(height * 0.7) };
+}
+
+/** The mapping the picture uses, from the same numbers the component is given, so a test can place any graph point. */
+export function matrixGridGeometry(matrix: number[][], opts: { width: number; height: number; box?: Box; scale?: number; extent?: number }): MatrixGridGeometry {
+  const box = opts.box ?? defaultMatrixBox(opts.width, opts.height);
+  const extent = opts.extent ?? 2;
+  let reach = Math.max(extent, 1);
+  for (const sx of [-1, 1]) {
+    for (const sy of [-1, 1]) {
+      const p = applyMatrix(matrix, sx * extent, sy * extent);
+      reach = Math.max(reach, Math.abs(p.x), Math.abs(p.y));
+    }
+  }
+  const scale = opts.scale ?? (Math.min(box.width, box.height) / 2 / (reach * 1.12));
+  const origin = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
+  return { box, origin, scale, toScreen: (x, y) => ({ x: origin.x + x * scale, y: origin.y - y * scale }) };
+}
+
+const fmt = (v: number) => String(Number(v.toFixed(2)));
+
+const Arrow: React.FC<{ from: Point; to: Point; color: string; weight: number; name: string }> = ({ from, to, color, weight, name }) => {
+  const len = Math.hypot(to.x - from.x, to.y - from.y);
+  const dx = len < 1e-6 ? 0 : (to.x - from.x) / len;
+  const dy = len < 1e-6 ? 0 : (to.y - from.y) / len;
+  const head = Math.min(weight * 5, len * 0.6);
+  const base = { x: to.x - dx * head, y: to.y - dy * head };
+  const half = head * 0.55;
+  return (
+    <g data-ovs-basis={name} data-ovs-tip-x={to.x} data-ovs-tip-y={to.y}>
+      <line x1={from.x} y1={from.y} x2={base.x} y2={base.y} stroke={color} strokeWidth={weight * 1.6} />
+      <polygon points={`${to.x},${to.y} ${base.x - dy * half},${base.y + dx * half} ${base.x + dy * half},${base.y - dx * half}`} fill={color} />
+    </g>
+  );
+};
+
+/**
+ * A matrix acting on the plane. A grid of points (and the lines through them), the unit square and
+ * the images of i-hat and j-hat move from the identity to the matrix: every entry is interpolated
+ * linearly from the identity, so each frame shows the plane under `I + p (M - I)` and the last one
+ * exactly `M`. Honest: a point (x, y) is drawn at `toScreen(M * (x, y))`, `scale` px per unit, and
+ * the square's orientation flips when the determinant is negative. A pure function of the frame.
+ */
+export const MatrixGrid: React.FC<MatrixGridProps> = ({ matrix, at = 0, duration = 45, transform = true, ease = E.cinematic, grid, unitSquare = true, showMatrix = true, box, scale, subject = "math" }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  if (matrix.length !== 2 || matrix.some((r) => r.length !== 2)) throw new Error("MatrixGrid: the matrix must be 2x2, like [[2, 1], [0, 1]].");
+  if (frame < at) return null;
+  const weight = lineWeight(width, height);
+  const accent = SUBJECT_ACCENT[subject].accent;
+  const extent = grid?.extent ?? 2;
+  const spacing = grid?.spacing ?? 1;
+  const geo = matrixGridGeometry(matrix, { width, height, box, scale, extent });
+  const progress = transform ? tween(frame, [at, at + duration], [0, 1], ease) : 1;
+  const m = interpolateMatrix(matrix, progress);
+  const show = tween(frame, [at, at + 8], [0, 1], E.cinematic);
+  const screen = (x: number, y: number) => {
+    const p = applyMatrix(m, x, y);
+    return geo.toScreen(p.x, p.y);
+  };
+  const steps: number[] = [];
+  for (let v = -extent; v <= extent + 1e-9; v += spacing) steps.push(Math.abs(v) < 1e-9 ? 0 : Number(v.toFixed(10)));
+  const minSide = Math.min(width, height);
+  const entryPx = Math.round(minSide * 0.042);
+  const colW = entryPx * 2.2;
+  const rowH = entryPx * 1.5;
+  const portrait = height > width;
+  const mc = portrait ? { x: width / 2, y: Math.round(height * 0.22) } : { x: Math.round(width * 0.2), y: Math.round(height * 0.5) };
+  const bw = colW * 2 + entryPx * 0.8;
+  const bh = rowH * 2;
+  const sq = [[0, 0], [1, 0], [1, 1], [0, 1]].map(([x, y]) => screen(x, y));
+  const area = sq.reduce((s, p, i) => s + (p.x * sq[(i + 1) % 4].y - sq[(i + 1) % 4].x * p.y), 0);
+  // Screen y points down, so a positive area here is a clockwise (flipped) square.
+  const flipped = area > 0;
+  const o = screen(0, 0);
+  const ghost = [[0, 0], [1, 0], [1, 1], [0, 1]].map(([x, y]) => geo.toScreen(x, y));
+  const poly = (pts: Point[]) => pts.map((p) => `${p.x},${p.y}`).join(" ");
+  const bracket = (side: -1 | 1) => {
+    const x = mc.x + side * bw / 2;
+    const t = mc.y - bh / 2;
+    const b = mc.y + bh / 2;
+    const k = entryPx * 0.35;
+    return `M${x - side * k},${t} L${x},${t} L${x},${b} L${x - side * k},${b}`;
+  };
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none", opacity: show }} data-ovs-matrixgrid="" data-ovs-progress={progress}>
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+        <g data-ovs-gridlines="">
+          {steps.map((v) => {
+            const a = screen(v, -extent);
+            const b = screen(v, extent);
+            const c = screen(-extent, v);
+            const d = screen(extent, v);
+            return (
+              <g key={v} stroke={VOID.textDim} strokeOpacity={v === 0 ? 0.55 : 0.28} strokeWidth={weight}>
+                <line x1={a.x} y1={a.y} x2={b.x} y2={b.y} />
+                <line x1={c.x} y1={c.y} x2={d.x} y2={d.y} />
+              </g>
+            );
+          })}
+        </g>
+        {steps.flatMap((x) => steps.map((y) => {
+          const p = screen(x, y);
+          return <circle key={`${x},${y}`} data-ovs-point={`${x},${y}`} data-ovs-sx={p.x} data-ovs-sy={p.y} cx={p.x} cy={p.y} r={weight * 1.4} fill={VOID.textDim} />;
+        }))}
+        {unitSquare && (
+          <g>
+            <polygon data-ovs-ghost="" points={poly(ghost)} fill="none" stroke={VOID.textDim} strokeWidth={weight} strokeDasharray={`${weight * 2.5} ${weight * 2}`} strokeOpacity={0.7} />
+            <polygon data-ovs-unit-square="" data-ovs-orientation={flipped ? "flipped" : "preserved"} points={poly(sq)} fill={accent} fillOpacity={0.2} stroke={accent} strokeWidth={weight} strokeLinejoin="round" />
+            {sq.map((p, i) => <circle key={i} data-ovs-corner={i} data-ovs-sx={p.x} data-ovs-sy={p.y} cx={p.x} cy={p.y} r={weight * 1.4} fill={accent} />)}
+            <Arrow from={o} to={screen(1, 0)} color={accent} weight={weight} name="i" />
+            <Arrow from={o} to={screen(0, 1)} color={VOID.text} weight={weight} name="j" />
+          </g>
+        )}
+        <circle data-ovs-origin="" data-ovs-sx={o.x} data-ovs-sy={o.y} cx={o.x} cy={o.y} r={weight * 2} fill={VOID.text} />
+        {showMatrix && (
+          <g data-ovs-matrix="">
+            <path d={bracket(-1)} fill="none" stroke={VOID.textDim} strokeWidth={weight} />
+            <path d={bracket(1)} fill="none" stroke={VOID.textDim} strokeWidth={weight} />
+            {matrix.flatMap((row, r) => row.map((v, c) => (
+              <text key={`${r}${c}`} data-ovs-entry={`${r},${c}`} x={mc.x + (c - 0.5) * colW} y={mc.y + (r - 0.5) * rowH + entryPx * 0.35} textAnchor="middle" fontSize={entryPx} fill={VOID.text} fontFamily={displayStack()} fontWeight={500}>{fmt(v)}</text>
+            )))}
+            <text x={mc.x} y={mc.y - bh / 2 - entryPx * 0.5} textAnchor="middle" fontSize={Math.round(minSide * 0.026)} fill={VOID.textDim} fontFamily={bodyStack()}>{`det = ${fmt(matrix[0][0] * matrix[1][1] - matrix[0][1] * matrix[1][0])}`}</text>
+          </g>
+        )}
+      </svg>
+    </div>
+  );
+};