@openvidstudio/mcp-server 0.1.0 → 1.4.0

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

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/Orbit.tsx

@@ -0,0 +1,241 @@
+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 type { Path, Point } from "./paths";
+
+export interface OrbitProps {
+  /** Semi-major axis in px (the radius, for a circle). Default 34% of the shorter side. */
+  semiMajor?: number;
+  /** 0 is a circle; up to 0.95. The central mass sits at a focus. Default 0. */
+  eccentricity?: number;
+  /** Frames for one full orbit. Exactly this: the body is back where it started after `period` frames. */
+  period: number;
+  /** Where the central mass is (the focus the body orbits). Default: placed so the whole ellipse is centred in the frame. */
+  centre?: Point;
+  /** Direction of periapsis (the closest point) as seen from the centre, degrees counter-clockwise from the right. The body starts there. Default 0. */
+  periapsisAngle?: number;
+  /** Orbit the other way. Default false (counter-clockwise on screen). */
+  clockwise?: boolean;
+  /** The speed at a distance of `semiMajor` from the centre, in the caller's units (m/s, say). On a circle this is the speed all the way round. */
+  v?: number;
+  /** The force at a distance of `semiMajor` from the centre, in the caller's units (N, say). On a circle this is the force all the way round. */
+  F?: number;
+  /** Override: speed as a function of distance from the centre in px. Default: vis-viva, v * sqrt(2a/r - 1). */
+  speedAt?: (r: number) => number;
+  /** Override: force as a function of distance from the centre in px. Default: inverse square, F * (a/r)^2. */
+  forceAt?: (r: number) => number;
+  /** Pixels per unit of magnitude for the two arrows. An arrow is exactly `magnitude * scale` px from tail to tip. */
+  scale: { velocity: number; force: number };
+  /** Units on the scale bars. Defaults "m/s" and "N". */
+  units?: { velocity?: string; force?: string };
+  /** The length each scale bar stands for, in the same units as the magnitudes. Default: a round value near half the largest. */
+  scaleValue?: { velocity?: number; force?: number };
+  /** Draw the velocity and force arrows. Default true. */
+  arrows?: boolean;
+  /** Composition frame the orbit starts and the body is released. Default 0. */
+  at?: number;
+  /** Composition frame the arrows start to grow. Default `at + 12`. */
+  arrowsAt?: number;
+  /** Radius of the central mass in px. Default 3.2% of the shorter side. */
+  massRadius?: number;
+  /** Shown on the central mass. */
+  centreLabel?: string;
+}
+
+/** Frames an arrow takes to grow to full length. */
+export const ORBIT_ARROW_FRAMES = 14;
+const MAX_ECCENTRICITY = 0.95;
+
+const toRad = (deg: number) => (deg * Math.PI) / 180;
+
+export interface OrbitShape {
+  semiMajor: number;
+  eccentricity: number;
+  period: number;
+  periapsisAngle?: number;
+  clockwise?: boolean;
+}
+
+export interface OrbitState {
+  /** Eccentric anomaly, radians. */
+  anomaly: number;
+  /** Distance from the central mass, px: a (1 - e cos E). */
+  r: number;
+  /** Offset of the body from the central mass, in screen px. */
+  offset: Point;
+  /** Unit vector of the direction of motion, in screen coordinates (y down). Tangent to the path. */
+  tangent: Point;
+  /** Unit vector from the body to the central mass. */
+  towardCentre: Point;
+}
+
+/** Solves Kepler's equation M = E - e sin E by Newton's method, to better than 1e-12. */
+export function eccentricAnomaly(meanAnomaly: number, e: number): number {
+  const m = meanAnomaly;
+  let x = e < 0.8 ? m : Math.PI;
+  for (let i = 0; i < 60; i++) {
+    const dx = (x - e * Math.sin(x) - m) / (1 - e * Math.cos(x));
+    x -= dx;
+    if (Math.abs(dx) < 1e-14) break;
+  }
+  return x;
+}
+
+/**
+ * The body's place on its orbit `t` frames after release, with no drawing. Time runs by Kepler's
+ * equation, so the body is at periapsis at t = 0 and every `period`, and at apoapsis half a period
+ * in. Distances are a (1 - e) and a (1 + e) there.
+ */
+export function orbitState(shape: OrbitShape, t: number): OrbitState {
+  const a = shape.semiMajor;
+  const e = Math.max(0, Math.min(MAX_ECCENTRICITY, shape.eccentricity));
+  const b = a * Math.sqrt(1 - e * e);
+  const dir = shape.clockwise ? -1 : 1;
+  const pa = toRad(shape.periapsisAngle ?? 0);
+  const E_ = eccentricAnomaly((2 * Math.PI * t) / shape.period, e);
+  // Perifocal frame: x toward periapsis, y a quarter turn on. Then onto the screen (y down).
+  const toScreen = (px: number, py: number): Point => ({
+    x: px * Math.cos(pa) - dir * py * Math.sin(pa),
+    y: -px * Math.sin(pa) - dir * py * Math.cos(pa),
+  });
+  const offset = toScreen(a * (Math.cos(E_) - e), b * Math.sin(E_));
+  const tv = toScreen(-a * Math.sin(E_), b * Math.cos(E_));
+  const tl = Math.hypot(tv.x, tv.y);
+  const r = a * (1 - e * Math.cos(E_));
+  return { anomaly: E_, r, offset, tangent: { x: tv.x / tl, y: tv.y / tl }, towardCentre: { x: -offset.x / r, y: -offset.y / r } };
+}
+
+/** Speed at distance r in the caller's units: vis-viva, v sqrt(2a/r - 1), where v is the speed at r = a. */
+export const visViva = (v: number, a: number, r: number): number => v * Math.sqrt(Math.max(0, 2 * a / r - 1));
+/** Force at distance r: inverse square, F (a / r)^2, where F is the force at r = a. */
+export const inverseSquare = (F: number, a: number, r: number): number => F * (a / r) ** 2;
+
+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; dir: Point; length: number; color: string; weight: number; dataset: Record<string, string> }> = ({ from, dir, length, color, weight, dataset }) => {
+  if (length <= 0) return null;
+  const head = Math.min(weight * 5, length * 0.6);
+  const tip = { x: from.x + dir.x * length, y: from.y + dir.y * length };
+  const base = { x: from.x + dir.x * (length - head), y: from.y + dir.y * (length - head) };
+  const half = head * 0.55;
+  const left = { x: base.x - dir.y * half, y: base.y + dir.x * half };
+  const right = { x: base.x + dir.y * half, y: base.y - dir.x * half };
+  return (
+    <g {...dataset}>
+      <line x1={from.x} y1={from.y} x2={base.x} y2={base.y} stroke={color} strokeWidth={weight} />
+      <polygon points={`${tip.x},${tip.y} ${left.x},${left.y} ${right.x},${right.y}`} fill={color} />
+    </g>
+  );
+};
+
+/**
+ * A body on a circular or elliptical orbit with its velocity and force arrows drawn to scale: each is
+ * exactly `magnitude * scale` px from tail to tip, and a scale bar for each says how much that is.
+ *
+ * What is exact: the position (Kepler's equation, so the body is at periapsis at t = 0 and every
+ * `period`, apoapsis half way, at distances a(1 - e) and a(1 + e)); the force arrow always points at
+ * the central mass; the velocity arrow is tangent to the path (perpendicular to the radius on a
+ * circle); the magnitudes follow vis-viva for speed and the inverse square law for force, both
+ * measured from `v` and `F` at r = a. What is not: `v` and `F` are the caller's numbers in the
+ * caller's units, so the picture is not checked against a real gravitational constant, and the
+ * arrow scale is separate from the scale of the drawn orbit. The body is the one Spark; the central
+ * mass is a plain disc. A pure function of the frame.
+ */
+export const Orbit: React.FC<OrbitProps> = (props) => {
+  const frame = useCurrentFrame();
+  const { width, height } = useVideoConfig();
+  const S = Math.min(width, height);
+  const at = props.at ?? 0;
+  const t = frame - at;
+  const weight = lineWeight(width, height);
+  const labelPx = Math.round(S * 0.03);
+  const accent = SUBJECT_ACCENT.physics;
+  const a = props.semiMajor ?? Math.round(S * 0.34);
+  const e = Math.max(0, Math.min(MAX_ECCENTRICITY, props.eccentricity ?? 0));
+  const b = a * Math.sqrt(1 - e * e);
+  const pa = props.periapsisAngle ?? 0;
+  const shape: OrbitShape = { semiMajor: a, eccentricity: e, period: props.period, periapsisAngle: pa, clockwise: props.clockwise };
+  // The ellipse's own centre is a e from the focus, away from periapsis.
+  const focusToCentre = { x: -a * e * Math.cos(toRad(pa)), y: a * e * Math.sin(toRad(pa)) };
+  const frameCentre = { x: width / 2, y: height * 0.46 };
+  const centre = props.centre ?? { x: frameCentre.x - focusToCentre.x, y: frameCentre.y - focusToCentre.y };
+  const ellipseCentre = { x: centre.x + focusToCentre.x, y: centre.y + focusToCentre.y };
+  const massRadius = props.massRadius ?? Math.round(S * 0.032);
+
+  const speedAt = props.speedAt ?? ((r: number) => visViva(props.v ?? 0, a, r));
+  const forceAt = props.forceAt ?? ((r: number) => inverseSquare(props.F ?? 0, a, r));
+  const bodyAt = (local: number): Point => {
+    const s = orbitState(shape, local);
+    return { x: centre.x + s.offset.x, y: centre.y + s.offset.y };
+  };
+  const pathFn: Path = bodyAt;
+
+  const arrowsAt = props.arrowsAt ?? at + 12;
+  const grow = tween(frame, [arrowsAt, arrowsAt + ORBIT_ARROW_FRAMES], [0, 1], E.cinematic);
+  const pathOpacity = tween(frame, [at, at + 12], [0, 1], E.cinematic);
+
+  if (t < 0) return null;
+  const st = orbitState(shape, t);
+  const body = { x: centre.x + st.offset.x, y: centre.y + st.offset.y };
+  const speed = speedAt(st.r);
+  const force = forceAt(st.r);
+  const vLen = speed * props.scale.velocity;
+  const fLen = force * props.scale.force;
+  const showArrows = props.arrows !== false && grow > 0;
+  const colorV = "#5CC8FF";
+  const colorF = accent.accentAlt;
+
+  // Scale bars: the largest values are at periapsis.
+  const vMax = speedAt(a * (1 - e));
+  const fMax = forceAt(a * (1 - e));
+  const bars = [
+    { key: "velocity", value: props.scaleValue?.velocity ?? roundValue(Math.max(vMax, 1e-9) / 2), scale: props.scale.velocity, unit: props.units?.velocity ?? "m/s", color: colorV },
+    { key: "force", value: props.scaleValue?.force ?? roundValue(Math.max(fMax, 1e-9) / 2), scale: props.scale.force, unit: props.units?.force ?? "N", color: colorF },
+  ];
+  const barX = Math.round(width * 0.12);
+  const barY0 = Math.round(height * 0.72);
+  const fmt = (v: number) => String(Number(v.toFixed(2)));
+
+  return (
+    <div style={{ position: "absolute", inset: 0, pointerEvents: "none" }} data-ovs-orbit="">
+      <svg width={width} height={height} style={{ position: "absolute", left: 0, top: 0, willChange: "transform" }}>
+        <ellipse data-ovs-orbit-path="" data-ovs-semi-major={a} data-ovs-semi-minor={b} data-ovs-eccentricity={e} cx={ellipseCentre.x} cy={ellipseCentre.y} rx={a} ry={b} transform={pa === 0 ? undefined : `rotate(${-pa} ${ellipseCentre.x} ${ellipseCentre.y})`} fill="none" stroke={`rgba(140,135,153,${(pathOpacity * 0.7).toFixed(4)})`} strokeWidth={weight} />
+        <circle data-ovs-mass="" cx={centre.x} cy={centre.y} r={massRadius} fill={VOID.textDim} />
+        {props.centreLabel && <text x={centre.x} y={centre.y + labelPx * 0.35} textAnchor="middle" fontSize={labelPx} fill={VOID.base} fontFamily={displayStack()} fontWeight={700}>{props.centreLabel}</text>}
+        <circle data-ovs-body="" data-ovs-r={st.r.toFixed(4)} cx={body.x} cy={body.y} r={1} fill="none" />
+        {showArrows && (
+          <>
+            <Arrow from={body} dir={st.tangent} length={vLen * grow} color={colorV} weight={weight * 1.6} dataset={{ "data-ovs-arrow": "velocity", "data-ovs-magnitude": String(speed), "data-ovs-length": String(vLen * grow), "data-ovs-dx": String(st.tangent.x), "data-ovs-dy": String(st.tangent.y) }} />
+            <Arrow from={body} dir={st.towardCentre} length={fLen * grow} color={colorF} weight={weight * 1.6} dataset={{ "data-ovs-arrow": "force", "data-ovs-magnitude": String(force), "data-ovs-length": String(fLen * grow), "data-ovs-dx": String(st.towardCentre.x), "data-ovs-dy": String(st.towardCentre.y) }} />
+            {grow >= 0.6 && (
+              <>
+                <text x={body.x + st.tangent.x * (vLen + labelPx * 1.1)} y={body.y + st.tangent.y * (vLen + labelPx * 1.1) + labelPx * 0.35} textAnchor="middle" fontSize={labelPx} fill={colorV} fontFamily={displayStack()} fontWeight={700}>v</text>
+                <text x={body.x + st.towardCentre.x * (fLen + labelPx * 1.1)} y={body.y + st.towardCentre.y * (fLen + labelPx * 1.1) + labelPx * 0.35} textAnchor="middle" fontSize={labelPx} fill={colorF} fontFamily={displayStack()} fontWeight={700}>F</text>
+              </>
+            )}
+          </>
+        )}
+        {props.arrows !== false && bars.map((bar, i) => {
+          const y = barY0 + i * labelPx * 1.9;
+          const len = bar.value * bar.scale;
+          return (
+            <g key={bar.key} data-ovs-scale={bar.key} data-ovs-scale-length={len}>
+              <line x1={barX} y1={y} x2={barX + len} y2={y} stroke={bar.color} strokeWidth={weight} />
+              <line x1={barX} y1={y - weight * 3} x2={barX} y2={y + weight * 3} stroke={bar.color} strokeWidth={weight} />
+              <line x1={barX + len} y1={y - weight * 3} x2={barX + len} y2={y + weight * 3} stroke={bar.color} strokeWidth={weight} />
+              <text x={barX + len + weight * 5} y={y + labelPx * 0.35} fontSize={labelPx} fill={VOID.textDim} fontFamily={bodyStack()}>{`${fmt(bar.value)} ${bar.unit}`}</text>
+            </g>
+          );
+        })}
+      </svg>
+      <Spark path={pathFn} at={at} trail={18} subject="physics" />
+    </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>
+  );
+};