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

package/dist/tween.d.ts

@@ -0,0 +1,44 @@
+import type { LatexToken } from "./geometry.js";
+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[];
+/**
+ * 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 declare function prepareLatexTween(from: LatexToken[], to: LatexToken[]): (t: number) => AnimatedToken[];
+//# sourceMappingURL=tween.d.ts.map

package/dist/tween.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tween.d.ts","sourceRoot":"","sources":["../src/tween.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACzB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,EAAE,MAAM,KAAK,aAAa,EAAE,CAAC;AA2J1G;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,iBAAiB,CAC7B,IAAI,EAAE,UAAU,EAAE,EAClB,EAAE,EAAE,UAAU,EAAE,GACjB,CAAC,CAAC,EAAE,MAAM,KAAK,aAAa,EAAE,CAmFhC"}

package/dist/tween.js

@@ -0,0 +1,233 @@
+import { lerpNumber } from "@motionscript/sdk";
+/** The coordinate pairs a `PathCommand` can carry, as (x, y) field names. */
+const POINT_FIELDS = [["x", "y"], ["x1", "y1"], ["x2", "y2"]];
+/**
+ * Compute the centroid of a token's path for position-based interpolation.
+ */
+function centroid(path) {
+    let sx = 0, sy = 0, n = 0;
+    for (const cmd of path) {
+        if ("x" in cmd && "y" in cmd) {
+            sx += cmd.x;
+            sy += cmd.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) {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const cmd of path) {
+        const c = cmd;
+        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, to) {
+    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, to, t) {
+    const out = new Array(from.length);
+    for (let i = 0; i < from.length; i++) {
+        const f = from[i];
+        const g = to[i];
+        const c = { ...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;
+    }
+    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, cx, cy, s, dx, dy) {
+    return path.map(cmd => {
+        const c = { ...cmd };
+        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;
+    });
+}
+/**
+ * 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, to) {
+    const remaining = [...to];
+    const matched = [];
+    const deleted = [];
+    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, to) {
+    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) => {
+        const tokens = [];
+        // 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;
+    };
+}
+//# sourceMappingURL=tween.js.map

package/dist/tween.js.map

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

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@motionscript/latex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-alpha.3",
+  "type": "module",
+  "description": "Animated LaTeX math for Motion Script, rendering formulas to glyph paths via MathJax and morphing them token by token.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/motionscript-dev/motionscript.git",
+    "directory": "packages/components/latex"
+  },
+  "homepage": "https://motionscript.dev",
+  "bugs": {
+    "url": "https://github.com/motionscript-dev/motionscript/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "registry.json",
+    "CHANGELOG.md",
+    "!dist/**/*.tsbuildinfo",
+    "!src/**/tests/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.fixtures.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "motion-script",
+    "motion script",
+    "latex",
+    "math",
+    "animation"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@motionscript/sdk": "^0.1.0-alpha.3"
+  },
+  "dependencies": {
+    "@mathjax/mathjax-newcm-font": "^4.1.1",
+    "@mathjax/src": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "eslint": "^9.39.4",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.1",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.1.5",
+    "@motionscript/sdk": "0.1.0-alpha.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths && node ../../../scripts/build-browser.mjs",
+    "dev": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --resolve-full-paths -w",
+    "clean": "rimraf --glob dist .turbo *.tsbuildinfo",
+    "test": "vitest --passWithNoTests",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }

package/registry.json

@@ -0,0 +1,6 @@
+{
+  "kit": { "barrel": "src/engine.ts", "specifier": "@motionscript/latex" },
+  "items": [
+    { "name": "latex", "root": "src", "files": ["node.ts"], "flatten": true }
+  ]
+}

package/src/cache.ts

@@ -0,0 +1,61 @@
+/**
+ * A bounded, least-recently-used memo.
+ *
+ * Sits under `geometry.ts`, and imports nothing, so it is testable in bare Node:
+ * everything else in this package reaches MathJax's browser adaptor at module
+ * scope, which means a test that touches it needs a DOM. The one piece of logic
+ * here worth being sure about — what gets thrown away when the memo is full —
+ * is exactly the piece that does not need one.
+ *
+ * Least-recently-used rather than oldest-first, and that matters for the shape
+ * of work this sees. A `Latex` node re-resolves its formula whenever `fontSize`
+ * changes, so animating the size of one formula inserts a fresh key every frame
+ * and would, under a first-in-first-out rule, walk the whole memo out of it in a
+ * couple of seconds — including the entries for every *other* formula in the
+ * scene, none of which had done anything wrong. Touching an entry on read keeps
+ * the formulas that are actually being asked for ahead of the ones streaming
+ * past.
+ */
+
+export interface BoundedCache<T> {
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    /** Entries held. For tests and for anyone measuring. */
+    readonly size: number;
+}
+
+/**
+ * @param limit Most entries to hold. One more arriving evicts the least
+ *              recently read or written.
+ */
+export function createBoundedCache<T>(limit: number): BoundedCache<T> {
+    // Insertion order is the eviction order, which is what makes a plain `Map`
+    // an LRU as long as every read re-inserts.
+    const entries = new Map<string, T>();
+
+    return {
+        get(key) {
+            if (!entries.has(key)) return undefined;
+            const value = entries.get(key) as T;
+            // Delete-then-set moves the key to the end, so the next eviction
+            // takes the genuinely coldest entry rather than the oldest one.
+            entries.delete(key);
+            entries.set(key, value);
+            return value;
+        },
+
+        set(key, value) {
+            entries.delete(key);
+            entries.set(key, value);
+            while (entries.size > limit) {
+                const coldest = entries.keys().next().value;
+                if (coldest === undefined) break;
+                entries.delete(coldest);
+            }
+        },
+
+        get size() {
+            return entries.size;
+        },
+    };
+}

package/src/engine.ts

@@ -0,0 +1,11 @@
+// The Latex "engine": MathJax-backed glyph-path building and morph
+// interpolation, kept separate from node.ts so `ms add latex` can copy just
+// the node declaration and import this behind `@motionscript/latex` instead
+// What gets copied is whatever this package's registry.json declares, which
+// for this component is node.ts; packages/site/scripts/build-registry.mjs
+// enforces that anything it reaches for is either copied alongside it or
+// re-exported from here.
+export { buildLatexPath } from './geometry';
+export type { LatexToken, LatexPathResult } from './geometry';
+export { prepareLatexTween as defaultLatexMorph } from './tween';
+export type { AnimatedToken, LatexMorphStrategy } from './tween';