@motionscript/latex 0.0.0-stage → 0.1.0-alpha.0

package/src/node.ts

@@ -0,0 +1,381 @@
+import { RenderContext2D, Graphics2D, EasingFunction, command, node, lerpNumber, NodeConfig, ShapeNode, ShapeProps, InsetsProps, Size2D, SizeConstraints, toPathString, InsetsResolved, property, insetsOps, FillResolved, ShadowResolved, driveCommand, type Command, type CommandArgs, type TweenStepper } from "@motionscript/core";
+import { buildLatexPath, defaultLatexMorph, type AnimatedToken, type LatexMorphStrategy, type LatexToken } from "./engine";
+
+export interface LatexProps extends ShapeProps {
+    latex: string;
+    fontSize: number;
+    padding: InsetsProps;
+}
+
+/**
+ * Construction-time-only options: pluggable engine behavior, set once when
+ * the node is created. Deliberately *not* part of {@link LatexProps} — every
+ * `@property` field accepts either a value or a zero-arg reactive binding
+ * (`value | (() => value)`, see `PropInputs`), and the node's own reactive
+ * write path (`_writeProp`) treats any function value as the latter. A
+ * strategy *is* a function, so it can't be told apart from a binding that
+ * computes one — it has to stay outside the reactive prop system entirely.
+ */
+export interface LatexStrategies {
+    /** How the node morphs between two formulas. Defaults to `defaultLatexMorph`. */
+    morph?: LatexMorphStrategy;
+}
+
+@node({
+  key: "latex",
+  parentKey: "shape",
+  forkable: true,
+  layout: {
+    children: "freeform",
+    defaultWidthMode: "hug",
+    defaultHeightMode: "hug",
+    acceptsChildren: true,
+  },
+  seed: {
+    fill: [
+      {
+        type: "solid",
+        color: [
+          0.412,
+          0.565,
+          0.867,
+          1,
+        ],
+        opacity: 1,
+        enabled: true,
+      },
+    ],
+  },
+})
+export class Latex extends ShapeNode<LatexProps> {
+    @property({ default: "" }) declare readonly latex: string;
+    @property({ default: 16 }) declare readonly fontSize: number;
+    @property({ default: 0, mapper: insetsOps.resolve, tween: insetsOps.lerp }) declare readonly padding: InsetsResolved;
+
+    /**
+     * How this node morphs between two formulas. Construction-time-only (see
+     * {@link LatexStrategies}) — resolved once here rather than left as
+     * `?? defaultLatexMorph` at every call site.
+     */
+    private readonly morph: LatexMorphStrategy;
+
+    private _intrinsicWidth: number = 0;
+    private _intrinsicHeight: number = 0;
+
+    /**
+     * Shared center frame for all current tokens, [minX, minY, maxX, maxY] in
+     * token space. Passed to every per-token path so glyphs keep their relative
+     * layout instead of each centering on its own bbox.
+     */
+    private _bounds: [number, number, number, number] = [0, 0, 0, 0];
+
+    /** Current tokens to render. Each has its own opacity for tween transitions. */
+    private _tokens: AnimatedToken[] = [];
+
+    /** Suppresses retokenization while a custom to() is driving frames. */
+    private _animating: boolean = false;
+
+    /** The `fontSize|latex` the live tokens were built from. See {@link _ensureTokens}. */
+    private _tokenizedFrom: string | null = null;
+
+    constructor(props: NodeConfig<Latex, LatexProps> & LatexStrategies) {
+        super(props);
+        this.morph = props.morph ?? defaultLatexMorph;
+        this.applyProp("width", props.width ?? "hug");
+        this.applyProp("height", props.height ?? "hug");
+
+        this._ensureTokens();
+    }
+
+    /**
+     * Rebuild the token list when the formula or size has moved since it last
+     * was built.
+     *
+     * Pulled from every reader rather than pushed from a prop write, because
+     * `latex` can be a binding — and a binding has no write to hang a
+     * subscription on. The key is what the current tokens were built from;
+     * `_animating` hands ownership to the morph command for its open interval.
+     */
+    private _ensureTokens(): void {
+        if (this._animating) return;
+        const key = `${this.fontSize}|${this.latex}`;
+        if (key === this._tokenizedFrom) return;
+        this._tokenizedFrom = key;
+        this._updateTokens();
+    }
+
+    private _updateTokens() {
+        if (this.latex) {
+            const result = buildLatexPath(this.latex, this.fontSize);
+            this._intrinsicWidth = result.width;
+            this._intrinsicHeight = result.height;
+            this._bounds = result.bounds;
+            this._tokens = result.tokens.map(t => ({
+                token: t.token,
+                path: t.path,
+                opacity: 1,
+                x: 0,
+                y: 0,
+            }));
+        } else {
+            this._tokens = [];
+            this._intrinsicWidth = 0;
+            this._intrinsicHeight = 0;
+            this._bounds = [0, 0, 0, 0];
+        }
+    }
+
+    override measure(constraints: SizeConstraints): Partial<Size2D> {
+        this._ensureTokens();
+        const pad = this.padding;
+        const wm = this.width;
+        const hm = this.height;
+
+        const resolvedW = typeof wm === "number"
+            ? wm
+            : wm === "hug"
+                ? this._intrinsicWidth + pad.left + pad.right
+                : constraints.maxWidth ?? 0;
+
+        const resolvedH = typeof hm === "number"
+            ? hm
+            : hm === "hug"
+                ? this._intrinsicHeight + pad.top + pad.bottom
+                : constraints.maxHeight ?? 0;
+
+        return { width: resolvedW, height: resolvedH };
+    }
+
+    /**
+     * A LaTeX morph — one {@link Command}, like every other `to()`.
+     *
+     * Sequence two of them with `sequence(...)` rather than chaining: the chain
+     * builder this used to return existed only so `latexRef().to(a, 1).to(b, 1)`
+     * would read as two steps, and it could not compose with anything that was
+     * not another Latex morph.
+     */
+    override to<D extends Partial<LatexProps> = Partial<LatexProps>>(args: CommandArgs<D> & { duration: number }): Command<LatexProps> {
+        return this._buildMorph(args.data ?? {}, args.duration, args.easing);
+    }
+
+    /**
+     * Morph this formula into another — a document-facing name for {@link to},
+     * which already routes through {@link _buildMorph}.
+     */
+    @command({ args: [{ key: "latex", kind: "text", multiline: true }] })
+    morphTo(args: CommandArgs<{ latex: string }> & { duration: number }): Command<LatexProps> {
+        return this.to({ data: { latex: args.data?.latex } as Partial<LatexProps>, duration: args.duration, easing: args.easing });
+    }
+
+    /**
+     * Build a single LaTeX morph as a {@link Command}: every ordinary
+     * `ShapeProps` field (via the inherited `_prepareStep`), plus the
+     * intrinsic size, shared center frame and per-glyph token list — state a
+     * plain `set()` can't reach — driven together by one eased `t`, matching
+     * the concurrent `parallel` the generator version ran.
+     *
+     * The "from" snapshot (`fromTokens`, `fromLatex`, …) is captured
+     * **lazily, on the command's first evaluation**, not when this is called.
+     * That is what lets two morphs be sequenced: `commandSequence` settles each
+     * prior step before evaluating the next, so a second morph's "from" reads
+     * the first one's end state rather than whatever the node held before either
+     * of them ran.
+     *
+     * `_animating` suppresses {@link _ensureTokens} for the open interval, and
+     * both ends commit: `t === 1`
+     * lands on the target formula, `t === 0` restores the source one — the same
+     * "membership for the open interval, commit at either end" shape
+     * `packages/components/code`'s `runTransition` uses, so seeking into either
+     * side of the morph (not just running it forward) shows the right thing.
+     *
+     * `@internal` — the entry point for authors is {@link to}.
+     */
+    _buildMorph(to: Partial<LatexProps>, duration: number, easing?: EasingFunction): Command<LatexProps> {
+        let setupDone = false;
+        let fromAnimTokens: AnimatedToken[] = [];
+        let fromLatex = "";
+        let fromFontSize = 0;
+        let fromWidth = 0;
+        let fromHeight = 0;
+        let fromBounds: [number, number, number, number] = [0, 0, 0, 0];
+        let toFontSize = 0;
+        let toLatex = "";
+        let toResult: ReturnType<typeof buildLatexPath>;
+        let propStep: TweenStepper;
+        let latexFrame: (t: number) => AnimatedToken[];
+
+        const setup = (): void => {
+            setupDone = true;
+            this._ensureTokens();
+            const fromTokens: LatexToken[] = this._tokens.map(t => ({ token: t.token, path: t.path }));
+            fromAnimTokens = this._tokens.map(t => ({ ...t }));
+            fromLatex = this.latex;
+            fromFontSize = this.fontSize;
+            fromWidth = this._intrinsicWidth;
+            fromHeight = this._intrinsicHeight;
+            fromBounds = this._bounds;
+
+            toFontSize = to.fontSize !== undefined ? to.fontSize : this.fontSize;
+            toLatex = to.latex !== undefined ? to.latex : this.latex;
+            toResult = buildLatexPath(toLatex, toFontSize);
+
+            propStep = this._prepareStep(to, duration);
+            latexFrame = this.morph(fromTokens, toResult.tokens);
+        };
+
+        return driveCommand(duration, (t) => {
+            if (!setupDone) setup();
+            const toBounds = toResult.bounds;
+
+            this._animating = true;
+            propStep.seek(t * duration);
+            this.set({ fontSize: lerpNumber(fromFontSize, toFontSize, t) });
+            // Track the measured size so a hugging box grows/shrinks smoothly
+            // across the morph rather than jumping when the end commits.
+            this._intrinsicWidth = lerpNumber(fromWidth, toResult.width, t);
+            this._intrinsicHeight = lerpNumber(fromHeight, toResult.height, t);
+            // Interpolate the shared center frame in lockstep so glyphs stay
+            // centered within the resizing box.
+            this._bounds = [
+                lerpNumber(fromBounds[0], toBounds[0], t),
+                lerpNumber(fromBounds[1], toBounds[1], t),
+                lerpNumber(fromBounds[2], toBounds[2], t),
+                lerpNumber(fromBounds[3], toBounds[3], t),
+            ];
+            this._tokens = latexFrame(t);
+
+            if (t >= 1) {
+                this.set({ latex: toLatex, fontSize: toFontSize });
+                this._tokens = toResult.tokens.map(tok => ({ token: tok.token, path: tok.path, opacity: 1, x: 0, y: 0 }));
+                this._intrinsicWidth = toResult.width;
+                this._intrinsicHeight = toResult.height;
+                this._bounds = toResult.bounds;
+                this._animating = false;
+                this._tokenizedFrom = `${toFontSize}|${toLatex}`;
+            } else if (t <= 0) {
+                this.set({ latex: fromLatex, fontSize: fromFontSize });
+                this._tokens = fromAnimTokens;
+                this._intrinsicWidth = fromWidth;
+                this._intrinsicHeight = fromHeight;
+                this._bounds = fromBounds;
+                this._animating = false;
+                this._tokenizedFrom = `${fromFontSize}|${fromLatex}`;
+            }
+        }, easing) as Command<LatexProps>;
+    }
+
+    /**
+     * The shadow op comes **first**, as it does on every other painted node.
+     *
+     * The renderer does not draw a shadow when it sees one: `.shadow()` stores
+     * it pending and the *next* fill or stroke op casts it (`_shadow` →
+     * `storePendingShadows`, `_fill`/`_stroke` → `takePendingShadows`). Appended
+     * last, it was stored by every token and then thrown away by the reset at
+     * the end of the draw — a shadow set on a LaTeX node simply never appeared,
+     * with no error to say why. Same failure {@link PaintedNode.renderStroke}
+     * documents for a fill-less stroked shape, and the same one-op fix.
+     *
+     * Order also carries the fill-less case for free: an empty fill returns
+     * before it takes the pending shadow, so the stroke below casts it from the
+     * glyph outlines instead — which is what `castsShadowFromStroke` arranges on
+     * a plain shape.
+     */
+    protected renderSelf(ctx: RenderContext2D): void {
+        this.eachToken(ctx, (graphics, opacity) => graphics
+            .shadow(scaleShadowOpacity(this.shadow as ShadowResolved[], opacity))
+            .fill(scaleFillopacity(this.fill as FillResolved[], opacity))
+            .stroke(this.stroke));
+    }
+
+    /**
+     * The overlay, painted *through* the glyphs.
+     *
+     * `ShapeNode`'s inherited overlay pass fills whatever {@link
+     * ShapeNode.shapeGraphics} describes, and this node describes nothing there:
+     * a formula has no single fillable silhouette — its silhouette *is* the list
+     * of token paths, which is why `renderSelf` is overridden rather than a
+     * `shapeGraphics` supplied. So the generic pass drew nothing and an overlay
+     * set on a LaTeX node simply never appeared, with no error to say why.
+     *
+     * Painted the same way the fill is: one `Graphics2D` per token, all sharing the
+     * centre frame, each scaled by its token's animated opacity — so a morph
+     * carries the overlay along with the glyph it is laid over instead of leaving
+     * a wash hanging over glyphs that have faded out.
+     *
+     * The stroke is *not* re-drawn here. `renderSelf` already strokes each token
+     * (there is no silhouette for the deferred {@link ShapeNode.renderStroke} to
+     * outline), so it is painted under the overlay rather than over it — the one
+     * place this node's draw order differs from a plain shape's, and the price of
+     * a stroke that follows glyphs rather than a box.
+     */
+    protected override renderOverlay(ctx: RenderContext2D): void {
+        const overlay = this.overlay as FillResolved[];
+        if (overlay.length === 0) return;
+        this.eachToken(ctx, (graphics, opacity) => graphics.fill(scaleFillopacity(overlay, opacity)));
+    }
+
+    /**
+     * Draws every visible token's path once, handing each one to `paint` to have
+     * its paint ops appended.
+     *
+     * A fresh `Graphics2D` per token per pass, because `.fill()`/`.stroke()` push
+     * onto one op list and return `this` — a silhouette shared between the fill
+     * pass and the overlay pass would accumulate both.
+     */
+    private eachToken(ctx: RenderContext2D, paint: (graphics: Graphics2D, opacity: number) => Graphics2D): void {
+        // The one funnel every paint pass goes through, so the tokens a frame
+        // draws cannot be older than the formula it holds.
+        this._ensureTokens();
+        for (const token of this._tokens) {
+            if (token.opacity <= 0) continue;
+
+            // Translate the path by token's interpolated position offset
+            const pathStr = token.x !== 0 || token.y !== 0
+                ? toPathString(offsetPath(token.path, token.x, token.y))
+                : toPathString(token.path);
+
+            ctx.draw(paint(new Graphics2D()
+                .path({
+                    data: pathStr,
+                    start: this.start,
+                    end: this.end,
+                    // All tokens share one center frame so they keep their relative
+                    // layout — without this each glyph centers on its own bbox and
+                    // they all stack on the origin.
+                    centerBounds: this._bounds,
+                }), token.opacity));
+        }
+    }
+
+}
+
+function scaleFillopacity(fills: FillResolved[], opacity: number): FillResolved[] {
+    if (opacity >= 1) return fills;
+    return fills.map(f => ({ ...f, opacity: (f.opacity ?? 1) * opacity }));
+}
+
+/**
+ * A morphing token fades, and its shadow has to fade with it — the paints are
+ * scaled the same way the fill's are, so a half-faded glyph casts a half-strength
+ * shadow rather than sitting over a shadow at full weight.
+ */
+function scaleShadowOpacity(shadows: ShadowResolved[], opacity: number): ShadowResolved[] {
+    if (opacity >= 1) return shadows;
+    return shadows.map(s => ({ ...s, fill: scaleFillopacity(s.fill, opacity) }));
+}
+
+function offsetPath(
+    path: LatexToken["path"],
+    dx: number,
+    dy: number,
+): LatexToken["path"] {
+    return path.map(cmd => {
+        const c = cmd as any;
+        const shifted: any = { ...c };
+        if ("x" in c) shifted.x = c.x + dx;
+        if ("y" in c) shifted.y = c.y + dy;
+        if ("x1" in c) { shifted.x1 = c.x1 + dx; shifted.y1 = c.y1 + dy; }
+        if ("x2" in c) { shifted.x2 = c.x2 + dx; shifted.y2 = c.y2 + dy; }
+        return shifted;
+    });
+}

package/src/nodes.ts

@@ -0,0 +1,18 @@
+import { Latex } from "./node";
+
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each class's `@node()`
+ * key. The decorator only *declares* that key: nothing is registered by the mere
+ * act of importing a module, so a registry holds exactly what its owner asked
+ * for and two engines in one process can differ about it.
+ *
+ * Listing class **values** is also what survives bundling. This package declares
+ * `sideEffects: false`, which licenses a bundler to drop a module nothing
+ * imports a value from, and a document names a node type by string — so
+ * `import "./node"` for its side effect is exactly what gets shaken out, where an
+ * array of bindings is a data dependency that cannot be.
+ */
+export const NODES = [Latex];

package/src/tween.ts

@@ -0,0 +1,286 @@
+import { lerpNumber, type PathCommand } from "@motionscript/core";
+import type { LatexToken } from "./geometry";
+
+export interface AnimatedToken {
+    token: string;
+    path: LatexToken["path"];
+    /** 0 = invisible, 1 = fully visible */
+    opacity: number;
+    /** Interpolated position offset applied during morph (x, y in formula space). */
+    x: number;
+    y: number;
+}
+
+/**
+ * How a `Latex` node interpolates between two formulas: given the tokens it
+ * currently holds and the tokens the target formula resolves to, return a
+ * pure `t → AnimatedToken[]` frame function. `prepareLatexTween` below is the
+ * default implementation (exported as `defaultLatexMorph`) — pass a `morph`
+ * of this shape to `<Latex>` to replace it with your own.
+ */
+export type LatexMorphStrategy = (from: LatexToken[], to: LatexToken[]) => (t: number) => AnimatedToken[];
+
+/** The coordinate pairs a `PathCommand` can carry, as (x, y) field names. */
+const POINT_FIELDS = [["x", "y"], ["x1", "y1"], ["x2", "y2"]] as const;
+
+/**
+ * Compute the centroid of a token's path for position-based interpolation.
+ */
+function centroid(path: LatexToken["path"]): { x: number; y: number } {
+    let sx = 0, sy = 0, n = 0;
+    for (const cmd of path) {
+        if ("x" in cmd && "y" in cmd) {
+            sx += (cmd as any).x;
+            sy += (cmd as any).y;
+            n++;
+        }
+    }
+    return n > 0 ? { x: sx / n, y: sy / n } : { x: 0, y: 0 };
+}
+
+/**
+ * A glyph's on-screen extent, as the diagonal of its control-point bbox.
+ *
+ * Only ever used as a *ratio* between the two ends of a match, so the fact that
+ * control points overshoot the true outline doesn't matter: both ends overshoot
+ * by the same proportion, because they are the same outline.
+ */
+function extent(path: LatexToken["path"]): number {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const cmd of path) {
+        const c = cmd as any;
+        for (const [kx, ky] of POINT_FIELDS) {
+            if (kx in c) {
+                if (c[kx] < minX) minX = c[kx];
+                if (c[kx] > maxX) maxX = c[kx];
+                if (c[ky] < minY) minY = c[ky];
+                if (c[ky] > maxY) maxY = c[ky];
+            }
+        }
+    }
+    if (minX > maxX) return 0;
+    return Math.hypot(maxX - minX, maxY - minY);
+}
+
+/**
+ * Whether two paths can be interpolated point by point: same command count,
+ * same command types in the same order.
+ *
+ * For a matched pair this is the overwhelmingly common case, and not by luck.
+ * Tokens are matched on the character their MathJax glyph id decodes to, and
+ * that id *is* the key into the `<defs>` dictionary — so the same character in
+ * two formulas is the same outline, emitted twice under two different
+ * transforms. Same commands, different numbers.
+ */
+function isPointwiseCompatible(from: PathCommand[], to: PathCommand[]): boolean {
+    if (from.length !== to.length) return false;
+    for (let i = 0; i < from.length; i++) {
+        if (from[i].type !== to[i].type) return false;
+    }
+    return true;
+}
+
+/**
+ * Lerp two structurally identical paths point by point.
+ *
+ * When the two ends are the same outline under two affine transforms — which is
+ * what a matched glyph is — this is exact at both ends *and* correct in
+ * between: `(1-t)·A·q + t·B·q = ((1-t)A + tB)·q`, and a blend of two
+ * uniform-scale-plus-translate transforms is another one. The intermediate is a
+ * properly formed glyph at an intermediate size, not a smeared one.
+ */
+function lerpPath(from: PathCommand[], to: PathCommand[], t: number): PathCommand[] {
+    const out: PathCommand[] = new Array(from.length);
+    for (let i = 0; i < from.length; i++) {
+        const f = from[i] as any;
+        const g = to[i] as any;
+        const c: any = { ...g };
+        for (const [kx, ky] of POINT_FIELDS) {
+            if (kx in g && kx in f) {
+                c[kx] = lerpNumber(f[kx], g[kx], t);
+                c[ky] = lerpNumber(f[ky], g[ky], t);
+            }
+        }
+        out[i] = c as PathCommand;
+    }
+    return out;
+}
+
+/**
+ * Scale a path uniformly about (cx, cy), then translate by (dx, dy).
+ *
+ * The fallback for a matched pair whose paths *aren't* structurally identical —
+ * a stretchy delimiter assembled from a different number of pieces at the two
+ * sizes, say. Point-by-point lerping is impossible there, so the target outline
+ * is shrunk to the source's size instead and grown back over the morph: the
+ * size still changes continuously, which is the whole point, at the cost of
+ * showing the target's shape from the start.
+ */
+function scaleAbout(
+    path: PathCommand[],
+    cx: number,
+    cy: number,
+    s: number,
+    dx: number,
+    dy: number,
+): PathCommand[] {
+    return path.map(cmd => {
+        const c: any = { ...(cmd as any) };
+        for (const [kx, ky] of POINT_FIELDS) {
+            if (kx in c) {
+                c[kx] = cx + (c[kx] - cx) * s + dx;
+                c[ky] = cy + (c[ky] - cy) * s + dy;
+            }
+        }
+        return c as PathCommand;
+    });
+}
+
+/**
+ * Greedily match tokens from `from` to `to` by character key.
+ * Returns three lists: matched pairs, deleted tokens (only in from), added tokens (only in to).
+ */
+function matchTokens(
+    from: LatexToken[],
+    to: LatexToken[],
+): {
+    matched: Array<{ from: LatexToken; to: LatexToken }>;
+    deleted: LatexToken[];
+    added: LatexToken[];
+} {
+    const remaining = [...to];
+    const matched: Array<{ from: LatexToken; to: LatexToken }> = [];
+    const deleted: LatexToken[] = [];
+
+    for (const ft of from) {
+        // Skip synthetic shapes (rects/paths) — they don't have a natural token key
+        if (ft.token.startsWith("__")) {
+            deleted.push(ft);
+            continue;
+        }
+        const idx = remaining.findIndex(t => t.token === ft.token && !t.token.startsWith("__"));
+        if (idx !== -1) {
+            matched.push({ from: ft, to: remaining[idx] });
+            remaining.splice(idx, 1);
+        } else {
+            deleted.push(ft);
+        }
+    }
+
+    // Remaining to-tokens that weren't matched
+    const added = remaining;
+
+    return { matched, deleted, added };
+}
+
+/**
+ * Precompute a formula-change morph and return a pure `t → AnimatedToken[]`
+ * frame function:
+ * - Deleted tokens fade out over the first half of `t`.
+ * - Matched tokens are interpolated — place *and* size — across the full range
+ *   of `t`.
+ * - Added tokens fade in over the second half of `t`.
+ *
+ * A matched glyph is rarely the same size at both ends: the `2` of `b^2` is set
+ * at script size and the `2` of `2a` at full size, and a `\frac`'s arguments
+ * come back a step smaller than the same symbols on a baseline. So the
+ * interpolation has to carry the glyph's *geometry*, not just where it sits.
+ * Sliding the target outline from one centroid to the other — which is all this
+ * used to do — put the whole size change between the last static frame and the
+ * morph's first one: a snap to the new size, then a smooth glide to the new
+ * place. Point-by-point lerping (see {@link lerpPath}) is that same
+ * interpolation generalised from a glyph's average point to all of them, and it
+ * costs nothing extra — the path was already being rebuilt every frame to apply
+ * the slide.
+ *
+ * `t` is normalized `[0, 1]` and already eased — the caller (a `Command`'s
+ * `at`) applies easing once, up front, the same eased value driving every
+ * concurrent aspect of the morph (props, intrinsic size, tokens) in lockstep.
+ */
+export function prepareLatexTween(
+    from: LatexToken[],
+    to: LatexToken[],
+): (t: number) => AnimatedToken[] {
+    const { matched, deleted, added } = matchTokens(from, to);
+
+    // Per-match interpolation data. Structure compatibility, and the centroids
+    // and extents behind the fallback, are properties of the pair rather than
+    // of `t`, so they are settled once here instead of at every frame.
+    const matchedData = matched.map(({ from: f, to: t }) => {
+        const toExtent = extent(t.path);
+        return {
+            pointwise: isPointwiseCompatible(f.path, t.path),
+            fromPath: f.path,
+            toPath: t.path,
+            token: t.token,
+            fromCenter: centroid(f.path),
+            toCenter: centroid(t.path),
+            /** Only the fallback needs it, and only as a ratio. */
+            fromScale: toExtent > 0 ? extent(f.path) / toExtent : 1,
+        };
+    });
+
+    return (t: number): AnimatedToken[] => {
+        const tokens: AnimatedToken[] = [];
+
+        // Matched tokens: interpolate place and size across the full duration.
+        for (const m of matchedData) {
+            if (m.pointwise) {
+                tokens.push({
+                    token: m.token,
+                    path: lerpPath(m.fromPath, m.toPath, t),
+                    opacity: 1,
+                    // Baked into the path above: the lerp carries every point,
+                    // which includes where the glyph sits.
+                    x: 0,
+                    y: 0,
+                });
+                continue;
+            }
+
+            const s = lerpNumber(m.fromScale, 1, t);
+            const cx = lerpNumber(m.fromCenter.x, m.toCenter.x, t);
+            const cy = lerpNumber(m.fromCenter.y, m.toCenter.y, t);
+            tokens.push({
+                token: m.token,
+                path: scaleAbout(
+                    m.toPath,
+                    m.toCenter.x,
+                    m.toCenter.y,
+                    s,
+                    cx - m.toCenter.x,
+                    cy - m.toCenter.y,
+                ),
+                opacity: 1,
+                x: 0,
+                y: 0,
+            });
+        }
+
+        // Deleted tokens: fade out over the first half, gone by t=0.5
+        for (const d of deleted) {
+            const fadeT = Math.min(t * 2, 1);
+            tokens.push({
+                token: d.token,
+                path: d.path,
+                opacity: lerpNumber(1, 0, fadeT),
+                x: 0,
+                y: 0,
+            });
+        }
+
+        // Added tokens: fade in over the second half, starting at t=0.5
+        for (const a of added) {
+            const fadeT = Math.max(t * 2 - 1, 0);
+            tokens.push({
+                token: a.token,
+                path: a.path,
+                opacity: lerpNumber(0, 1, fadeT),
+                x: 0,
+                y: 0,
+            });
+        }
+
+        return tokens;
+    };
+}