@openvidstudio/mcp-server 0.1.0 → 1.3.1

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

@@ -0,0 +1,118 @@
+import React, { createContext, useContext } from "react";
+import { useVideoConfig } from "remotion";
+import { SUBJECT_ACCENT, VOID, bodyStack, displayStack } from "./designSystem";
+import { lineWeight } from "./graph";
+import { Spark } from "./Spark";
+import { keyframePath, type Keyframe, type Path, type Point } from "./paths";
+import { useCurrentFrame } from "remotion";
+
+export interface ArrayPointer {
+  /** Shown under the pointer: "low", "high", "mid". */
+  name: string;
+  /** The cell it points at, or keyframes `{ frame, index }` to move it (eased, fractional between cells). */
+  index: number | { frame: number; index: number }[];
+  color?: string;
+  /** Draw this pointer's tip as the Spark, so its move leaves a trail. At most one pointer may. */
+  spark?: boolean;
+}
+
+export interface ArrayVizProps {
+  values: (number | string)[];
+  pointers?: ArrayPointer[];
+  /** Cells to fill with the accent, inclusive on both ends: the range still in play. */
+  highlights?: { from: number; to: number; color?: string }[];
+  /** Cells to dim, inclusive: what has been ruled out. */
+  dimmed?: { from: number; to: number }[];
+  /** Top-left of the row. Default: centred across the frame, 45% down. */
+  origin?: Point;
+  /** Side of one cell, px. Default: fits the row in 84% of the width, never more than 11% of the shorter side. */
+  cellSize?: number;
+  /** Picks the accent. Default "cs". */
+  subject?: "math" | "physics" | "cs" | "chemistry" | "biology";
+  children?: React.ReactNode;
+}
+
+export interface ArrayGeometry {
+  cellSize: number;
+  left: number;
+  top: number;
+  /** The centre of cell `i` (fractional i is between cells). */
+  cellCenter: (i: number) => Point;
+}
+
+const ArrayContext = createContext<ArrayGeometry | null>(null);
+/** The geometry of the enclosing <ArrayViz>, so a Spark can be walked across its cells. */
+export function useArrayViz(): ArrayGeometry {
+  const g = useContext(ArrayContext);
+  if (!g) throw new Error("useArrayViz must be used inside <ArrayViz>.");
+  return g;
+}
+
+const indexAt = (pointer: ArrayPointer, frame: number): number => {
+  if (typeof pointer.index === "number") return pointer.index;
+  const keys: Keyframe[] = pointer.index.map((k) => ({ frame: k.frame, x: k.index, y: 0 }));
+  return keyframePath(keys)(frame).x;
+};
+
+/**
+ * A row of cells holding values, with named pointers (low, high, mid), a highlighted range and a
+ * dimmed one: enough to teach binary search and a sorting pass. A pointer can be the Spark, so its
+ * move across the cells leaves a trail. One idea on screen: at most one thing moves.
+ */
+export const ArrayViz: React.FC<ArrayVizProps> = ({ values, pointers = [], highlights = [], dimmed = [], origin, cellSize, subject = "cs", children }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  const weight = lineWeight(width, height);
+  const accent = SUBJECT_ACCENT[subject].accent;
+  const n = values.length;
+  const cell = cellSize ?? Math.min(Math.floor((width * 0.84) / Math.max(1, n)), Math.round(Math.min(width, height) * 0.11));
+  const left = origin?.x ?? Math.round((width - n * cell) / 2);
+  const top = origin?.y ?? Math.round(height * 0.45);
+  const geometry: ArrayGeometry = { cellSize: cell, left, top, cellCenter: (i) => ({ x: left + (i + 0.5) * cell, y: top + cell / 2 }) };
+  const sparks = pointers.filter((p) => p.spark);
+  if (sparks.length > 1) throw new Error("ArrayViz: at most one pointer can be the Spark (one glowing element at a time).");
+  const inAny = (ranges: { from: number; to: number }[], i: number) => ranges.some((r) => i >= r.from && i <= r.to);
+  const fontPx = Math.round(cell * 0.38);
+  const labelPx = Math.round(Math.min(width, height) * 0.026);
+  const tri = cell * 0.2;
+  const palette = [accent, "#FFB347", "#FF4D5E", "#7CFFB2"];
+  const sparkPointer = sparks[0];
+  const sparkPath: Path | null = sparkPointer
+    ? (t: number) => {
+        const p = geometry.cellCenter(indexAt(sparkPointer, t));
+        return { x: p.x, y: top + cell + tri * 1.4 };
+      }
+    : null;
+  return (
+    <ArrayContext.Provider value={geometry}>
+      <div style={{ position: "absolute", inset: 0, pointerEvents: "none" }} data-ovs-arrayviz="">
+        <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+          {values.map((v, i) => {
+            const hl = highlights.find((h) => i >= h.from && i <= h.to);
+            const faded = inAny(dimmed, i);
+            return (
+              <g key={i} data-ovs-cell={i} opacity={faded ? 0.3 : 1}>
+                <rect x={left + i * cell + weight / 2} y={top + weight / 2} width={cell - weight} height={cell - weight} rx={cell * 0.08} fill={hl ? (hl.color ?? accent) : VOID.panel} fillOpacity={hl ? 0.3 : 1} stroke={hl ? (hl.color ?? accent) : VOID.textDim} strokeWidth={weight} strokeOpacity={hl ? 1 : 0.6} />
+                <text x={left + (i + 0.5) * cell} y={top + cell / 2 + fontPx * 0.35} textAnchor="middle" fontSize={fontPx} fill={VOID.text} fontFamily={displayStack()} fontWeight={500}>{String(v)}</text>
+                <text x={left + (i + 0.5) * cell} y={top - labelPx * 0.5} textAnchor="middle" fontSize={labelPx} fill={VOID.textDim} fontFamily={bodyStack()}>{i}</text>
+              </g>
+            );
+          })}
+          {pointers.map((p, k) => {
+            const c = geometry.cellCenter(indexAt(p, frame));
+            const color = p.color ?? palette[k % palette.length];
+            const base = top + cell + tri * 0.6;
+            return (
+              <g key={p.name} data-ovs-pointer={p.name}>
+                {!p.spark && <polygon data-ovs-pointer-tip="" points={`${c.x},${base} ${c.x - tri},${base + tri * 1.5} ${c.x + tri},${base + tri * 1.5}`} fill={color} />}
+                <text x={c.x} y={base + tri * 1.5 + labelPx * 1.25} textAnchor="middle" fontSize={labelPx * 1.1} fill={color} fontFamily={displayStack()} fontWeight={700}>{p.name}</text>
+              </g>
+            );
+          })}
+        </svg>
+        {sparkPointer && sparkPath && <Spark path={sparkPath} trail={14} color={sparkPointer.color ?? palette[pointers.indexOf(sparkPointer) % palette.length]} size={Math.max(4, Math.round(tri))} />}
+        {children}
+      </div>
+    </ArrayContext.Provider>
+  );
+};

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;
+
+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).
+ */
+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. */
+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/Nova.tsx

@@ -0,0 +1,104 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { E, jitter, tween, useMusicClock } from "@openvidstudio/core";
+import { Glow } from "./glow";
+import { SUBJECT_ACCENT, VOID, type Subject } from "./designSystem";
+import type { Point } from "./paths";
+
+export interface NovaProps {
+  /** Composition frame of the flash. Or name the score's impact with `beatId` and `impact`. */
+  at?: number;
+  /** With `impact`: read the frame from this beat's music clock (useMusicClock(beatId).impact(impact)). */
+  beatId?: string;
+  impact?: string;
+  /** Where it goes off. Default: the centre of the frame. */
+  origin?: Point;
+  /** Defaults to the subject's accent. */
+  color?: string;
+  subject?: Subject;
+  /** Frames from the flash until the content is fully formed. Default 60. */
+  duration?: number;
+  /** The payoff: condenses from particles. Absent before the flash, fully formed by the end. */
+  children?: React.ReactNode;
+}
+
+/** Frames the flash lasts. */
+export const NOVA_FLASH_FRAMES = 3;
+const PARTICLES = 56;
+
+/**
+ * The payoff, used once per video, on the aha sentence. Nothing is drawn before it. Then a
+ * three-frame flash, a thin shockwave ring that decelerates and fades, and the `children` condense
+ * from particles that converge on the origin. The beat of silence before it is the narration's:
+ * leave a pause before `at`. Scatter comes from a seeded hash of the particle index, so two renders
+ * of a frame are identical. The flash and ring are drawn as one glowing element through the glow
+ * helper; the particles do not glow, so a Nova is one entry in the glow budget.
+ */
+export const Nova: React.FC<NovaProps> = ({ at, beatId, impact, origin, color, subject = "math", duration = 60, children }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  // The hook is called every time, as hooks must be; it is only consulted when an impact is named.
+  const clock = useMusicClock(beatId ?? "");
+  const named = beatId !== undefined && impact !== undefined ? clock.impact(impact) : null;
+  const start = named ?? at;
+  if (start === undefined || start === null) {
+    throw new Error("Nova needs `at` (a frame), or `beatId` and `impact` naming an impact point in the score's cues.");
+  }
+  const t = frame - start;
+  if (t < 0) return null;
+
+  const tint = color ?? SUBJECT_ACCENT[subject].accent;
+  const o = origin ?? { x: width / 2, y: height / 2 };
+  const reach = Math.min(width, height) * 0.9;
+  const flash = t < NOVA_FLASH_FRAMES ? 1 - t / NOVA_FLASH_FRAMES : 0;
+  const ringLife = Math.max(1, Math.round(duration * 0.8));
+  const ringP = Math.min(1, t / ringLife);
+  const ringRadius = reach * (1 - (1 - ringP) ** 3);
+  const ringOpacity = ringP >= 1 ? 0 : (1 - ringP) ** 1.5;
+  const stroke = Math.max(2, Math.round(Math.min(width, height) * 0.0025));
+
+  const condense = tween(t, [NOVA_FLASH_FRAMES, duration], [0, 1], E.cinematic);
+  const formed = t >= duration;
+  const scatter = Math.min(width, height) * 0.55;
+  const particles = formed
+    ? []
+    : Array.from({ length: PARTICLES }, (_, i) => {
+        const angle = jitter(i, 1) * Math.PI * 2;
+        const dist = scatter * (0.35 + 0.65 * jitter(i, 2));
+        const k = 1 - condense; // 1 at the start, 0 when they have arrived
+        return { x: o.x + Math.cos(angle) * dist * k, y: o.y + Math.sin(angle) * dist * k, r: 2 + jitter(i, 3) * 2.5 };
+      });
+  const particleOpacity = t < NOVA_FLASH_FRAMES ? 0 : Math.min(1, condense * 4) * (1 - condense ** 6);
+
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none" }}>
+      {children !== undefined && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            opacity: formed ? 1 : condense ** 1.5,
+            transform: formed ? undefined : `scale(${0.9 + 0.1 * condense})`,
+            transformOrigin: `${o.x}px ${o.y}px`,
+            filter: formed ? undefined : `blur(${(1 - condense) * 10}px)`,
+          }}
+        >
+          {children}
+        </div>
+      )}
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+        {particles.map((p, i) => (
+          <circle key={i} cx={p.x} cy={p.y} r={p.r} fill={tint} opacity={particleOpacity} />
+        ))}
+      </svg>
+      <Glow kind="nova" x={o.x} y={o.y} radius={Math.hypot(width, height)} color={VOID.text} level={flash}>
+        {null}
+      </Glow>
+      {ringOpacity > 0 && (
+        <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+          <circle cx={o.x} cy={o.y} r={ringRadius} fill="none" stroke={tint} strokeWidth={stroke} opacity={ringOpacity} />
+        </svg>
+      )}
+    </div>
+  );
+};

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

@@ -0,0 +1,69 @@
+import React from "react";
+import { useCurrentFrame, useVideoConfig } from "remotion";
+import { Glow } from "./glow";
+import { SUBJECT_ACCENT, VOID, type Subject } from "./designSystem";
+import { resolvePath, type Keyframe, type Path } from "./paths";
+
+const hex = (h: string): [number, number, number] => [1, 3, 5].map((i) => Number.parseInt(h.slice(i, i + 2), 16)) as [number, number, number];
+/** `color` pulled toward the warm white by `k`: the Spark's core is hotter than its bloom. */
+function toward(color: string, whiteHex: string, k: number): string {
+  const a = hex(color);
+  const b = hex(whiteHex);
+  return `rgb(${a.map((v, i) => Math.round(v + (b[i] - v) * k)).join(",")})`;
+}
+
+export interface SparkProps {
+  /** Where the Spark is at a local time (frames since `at`), or keyframes. See trace, carry, orbit, fall, walk. */
+  path: Path | Keyframe[];
+  /** Composition frame the Spark appears. Default 0. */
+  at?: number;
+  /** How many frames of tail it drags. Default 18. */
+  trail?: number;
+  /** Defaults to the subject's accent. */
+  color?: string;
+  /** Picks the default colour. Default "math". */
+  subject?: Subject;
+  /** Radius of the bright core in px. Default 1.4% of the shorter side of the frame. */
+  size?: number;
+}
+
+/**
+ * A luminous point: a small bright core, a soft bloom and a fading trail. It is the pen, the
+ * pointer and the particle of a lesson, so there is exactly one on screen at a time. A pure
+ * function of the frame; sizes come from the composition, never from a fixed 1920x1080.
+ */
+export const Spark: React.FC<SparkProps> = ({ path, at = 0, trail = 18, color, subject = "math", size }) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  const t = frame - at;
+  if (t < 0) return null;
+  const p = resolvePath(path);
+  const tint = color ?? SUBJECT_ACCENT[subject].accent;
+  const r = size ?? Math.max(2, Math.round(Math.min(width, height) * 0.014));
+  const head = p(t);
+  const tail = Array.from({ length: trail }, (_, k) => ({ k: k + 1, pos: p(Math.max(0, t - (k + 1))) }));
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none" }}>
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0 }}>
+        {tail.map(({ k, pos }) => {
+          const age = k / (trail + 1);
+          return <circle key={k} cx={pos.x} cy={pos.y} r={r * (1 - 0.65 * age)} fill={tint} opacity={0.85 * (1 - age) ** 1.6} />;
+        })}
+      </svg>
+      <Glow kind="spark" x={head.x} y={head.y} radius={r * 5} color={tint}>
+        <div
+          style={{
+            position: "absolute",
+            left: `calc(50% - ${r}px)`,
+            top: `calc(50% - ${r}px)`,
+            width: r * 2,
+            height: r * 2,
+            borderRadius: "50%",
+            background: toward(tint, VOID.text, 0.72),
+            boxShadow: `0 0 ${r}px ${tint}`,
+          }}
+        />
+      </Glow>
+    </div>
+  );
+};

package/templates/default/openvidstudio-stem/src/designSystem.ts

@@ -0,0 +1,76 @@
+import { color as coreColor, defineDesignSystem, font as coreFont, type DesignSystem } from "@openvidstudio/core";
+
+/**
+ * Supernova's Void + Spark design system: light is meaning. Everything is dark and flat except
+ * the one thing the viewer must look at, so there is one accent per subject and nothing else glows.
+ */
+
+export type Subject = "math" | "physics" | "cs" | "chemistry" | "biology";
+export const SUBJECTS: readonly Subject[] = ["math", "physics", "cs", "chemistry", "biology"];
+
+/** The base tokens shared by every subject. Text is warm white, never pure white. */
+export const VOID = {
+  base: "#07060B",
+  panel: "#0E0C16",
+  /** Hairline grid: 5% white. */
+  hairline: "rgba(255,255,255,0.05)",
+  text: "#F3EFE6",
+  textDim: "#8C8799",
+} as const;
+
+/** One accent per subject, so a profile grid of lessons reads as a spectrum. */
+export const SUBJECT_ACCENT: Record<Subject, { accent: string; accentAlt: string; name: string }> = {
+  math: { accent: "#5CC8FF", accentAlt: "#5CC8FF", name: "blue giant" },
+  physics: { accent: "#FFB347", accentAlt: "#FF7A3D", name: "solar amber, with ember as the second" },
+  cs: { accent: "#B58CFF", accentAlt: "#B58CFF", name: "nebula violet" },
+  chemistry: { accent: "#FF4D5E", accentAlt: "#FF4D5E", name: "red dwarf" },
+  biology: { accent: "#7CFFB2", accentAlt: "#7CFFB2", name: "aurora" },
+};
+
+/** Display face (headlines, equations' labels) and body face. Both load from local files. */
+export const DISPLAY_FONT = "Space Grotesk";
+export const BODY_FONT = "Inter";
+
+export const displayStack = (): string => `"${DISPLAY_FONT}", ui-sans-serif, system-ui, sans-serif`;
+export const bodyStack = (): string => `"${BODY_FONT}", ui-sans-serif, system-ui, sans-serif`;
+
+/** The stage Supernova videos render at, and the Reels safe zones (PIPELINE.md, about 14% top, 22% bottom). */
+export const SUPERNOVA_STAGE = { width: 1080, height: 1920 } as const;
+export const SUPERNOVA_GRID = { marginX: 108, marginTop: 270, marginBottom: 420 } as const;
+
+export interface SupernovaDesignSystem extends DesignSystem {
+  subject: Subject;
+  /** The display face's family name, which DesignSystem's own `font` has no slot for. */
+  display: string;
+}
+
+/**
+ * The design system for one subject's lesson. Call it from the video's design.ts:
+ * `export const design = supernovaDesignSystem("physics")`.
+ */
+export function supernovaDesignSystem(subject: Subject): SupernovaDesignSystem {
+  const tone = SUBJECT_ACCENT[subject];
+  if (!tone) throw new Error(`supernovaDesignSystem: unknown subject "${subject}", expected one of ${SUBJECTS.join(", ")}.`);
+  const ds = defineDesignSystem({
+    stage: SUPERNOVA_STAGE,
+    color: {
+      ...coreColor,
+      bg0: VOID.base,
+      bg1: VOID.panel,
+      panel: VOID.panel,
+      panelBorder: VOID.hairline,
+      textPrimary: VOID.text,
+      textSecondary: VOID.textDim,
+      accent: tone.accent,
+      accentAlt: tone.accentAlt,
+    },
+    font: { ...coreFont, ui: BODY_FONT },
+    grid: { ...SUPERNOVA_GRID },
+    motif: "void-spark",
+    // A lesson moves slowly and one thing at a time.
+    motion: { easing: "drift", staggerMs: 90, cameraEnergy: "subtle", cutRhythmSeconds: [4, 12] },
+    texture: { grainOpacity: 0.03, vignetteStrength: 0.45 },
+    transitions: ["cut", "fade"],
+  });
+  return { ...ds, subject, display: DISPLAY_FONT };
+}