@motionscript/math 0.1.0-alpha.7 → 0.1.0-alpha.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/LICENSE +201 -201
  3. package/NOTICE +49 -48
  4. package/README.md +390 -391
  5. package/dist/annotate/angle-mark.d.ts +6 -6
  6. package/dist/annotate/angle-mark.js.map +1 -1
  7. package/dist/annotate/curly-brace.d.ts +9 -9
  8. package/dist/annotate/curly-brace.js.map +1 -1
  9. package/dist/annotate/emphasis-mark.d.ts +9 -9
  10. package/dist/annotate/emphasis-mark.js.map +1 -1
  11. package/dist/browser/chunks/{chunk-ABYBW64J.js → chunk-IRZCG6PM.js} +2 -2
  12. package/dist/browser/chunks/chunk-IRZCG6PM.js.map +7 -0
  13. package/dist/browser/chunks/{chunk-K77KLQX4.js → chunk-WMVW6ZIV.js} +2 -2
  14. package/dist/browser/chunks/chunk-WMVW6ZIV.js.map +7 -0
  15. package/dist/browser/chunks/{mathjax-DNP3YRES.js → mathjax-WV55AC2P.js} +1 -1
  16. package/dist/browser/chunks/{mathjax-DNP3YRES.js.map → mathjax-WV55AC2P.js.map} +1 -1
  17. package/dist/browser/index.js +1 -1
  18. package/dist/browser/index.js.map +3 -3
  19. package/dist/browser/kit.js +1 -1
  20. package/dist/browser/manifest.json +1 -1
  21. package/dist/browser/tex.js +1 -1
  22. package/dist/browser/tex.js.map +1 -1
  23. package/dist/engine.d.ts +1 -1
  24. package/dist/engine.js +1 -1
  25. package/dist/engine.js.map +1 -1
  26. package/dist/index.js.map +1 -1
  27. package/dist/kit/brace.js.map +1 -1
  28. package/dist/kit/cache.js.map +1 -1
  29. package/dist/kit/component.d.ts.map +1 -1
  30. package/dist/kit/component.js.map +1 -1
  31. package/dist/kit/contour.js.map +1 -1
  32. package/dist/kit/coords.js.map +1 -1
  33. package/dist/kit/curve.js.map +1 -1
  34. package/dist/kit/equation.js.map +1 -1
  35. package/dist/kit/equation3d.js.map +1 -1
  36. package/dist/kit/expression.js.map +1 -1
  37. package/dist/kit/field-mark.d.ts.map +1 -1
  38. package/dist/kit/field-mark.js.map +1 -1
  39. package/dist/kit/field.js.map +1 -1
  40. package/dist/kit/follow.d.ts +2 -2
  41. package/dist/kit/follow.d.ts.map +1 -1
  42. package/dist/kit/follow.js.map +1 -1
  43. package/dist/kit/furniture.js.map +1 -1
  44. package/dist/kit/geometry.js.map +1 -1
  45. package/dist/kit/graph.js.map +1 -1
  46. package/dist/kit/mark.js.map +1 -1
  47. package/dist/kit/part-fills.js.map +1 -1
  48. package/dist/kit/place.js.map +1 -1
  49. package/dist/kit/sampler.js +1 -1
  50. package/dist/kit/sampler.js.map +1 -1
  51. package/dist/kit/scale.js.map +1 -1
  52. package/dist/kit/source.js.map +1 -1
  53. package/dist/kit/system.js.map +1 -1
  54. package/dist/kit/ticks.js.map +1 -1
  55. package/dist/kit/withdrawn.js.map +1 -1
  56. package/dist/marks/curve-area.js.map +1 -1
  57. package/dist/marks/drop-lines.d.ts +6 -6
  58. package/dist/marks/drop-lines.js.map +1 -1
  59. package/dist/marks/plot-point.d.ts +3 -3
  60. package/dist/marks/plot-point.js.map +1 -1
  61. package/dist/marks/riemann-sum.d.ts +3 -3
  62. package/dist/marks/riemann-sum.js.map +1 -1
  63. package/dist/marks/tangent-line.d.ts +6 -6
  64. package/dist/marks/tangent-line.js.map +1 -1
  65. package/dist/marks/vector-arrow.d.ts +6 -6
  66. package/dist/marks/vector-arrow.js.map +1 -1
  67. package/dist/nodes.js.map +1 -1
  68. package/dist/plots/function-plot.d.ts +8 -8
  69. package/dist/plots/function-plot.d.ts.map +1 -1
  70. package/dist/plots/function-plot.js.map +1 -1
  71. package/dist/plots/points-plot.js.map +1 -1
  72. package/dist/plots/stream-lines.js.map +1 -1
  73. package/dist/plots/traced-path.js.map +1 -1
  74. package/dist/plots/vector-field.js.map +1 -1
  75. package/dist/structures/graph-layout.js.map +1 -1
  76. package/dist/structures/network-graph.js.map +1 -1
  77. package/dist/structures/sample-space.js.map +1 -1
  78. package/dist/systems/axes2d.d.ts.map +1 -1
  79. package/dist/systems/axes2d.js.map +1 -1
  80. package/dist/systems/number-line.js.map +1 -1
  81. package/dist/systems/number-plane.js.map +1 -1
  82. package/dist/systems/polar-plane.js.map +1 -1
  83. package/dist/tex/geometry.js.map +1 -1
  84. package/dist/tex/index.js.map +1 -1
  85. package/dist/tex/mathjax.js.map +1 -1
  86. package/dist/tex/matrix.d.ts +2 -2
  87. package/dist/tex/matrix.js.map +1 -1
  88. package/dist/tex/node.d.ts +2 -2
  89. package/dist/tex/node.js.map +1 -1
  90. package/dist/tex/tween.js.map +1 -1
  91. package/dist/tex/typeset.d.ts +4 -4
  92. package/dist/tex/typeset.d.ts.map +1 -1
  93. package/dist/tex/typeset.js.map +1 -1
  94. package/dist/three/axes3d.js.map +1 -1
  95. package/dist/three/curve-plot3d.d.ts +27 -27
  96. package/dist/three/curve-plot3d.d.ts.map +1 -1
  97. package/dist/three/curve-plot3d.js +3 -2
  98. package/dist/three/curve-plot3d.js.map +1 -1
  99. package/dist/three/entries.js.map +1 -1
  100. package/dist/three/label3d.d.ts.map +1 -1
  101. package/dist/three/label3d.js +3 -1
  102. package/dist/three/label3d.js.map +1 -1
  103. package/dist/three/plot-point3d.d.ts +27 -27
  104. package/dist/three/plot-point3d.js.map +1 -1
  105. package/dist/three/space.js.map +1 -1
  106. package/dist/three/surface-plot3d.d.ts +36 -36
  107. package/dist/three/surface-plot3d.js +6 -1
  108. package/dist/three/surface-plot3d.js.map +1 -1
  109. package/dist/three/vector-arrow3d.d.ts +27 -27
  110. package/dist/three/vector-arrow3d.js.map +1 -1
  111. package/package.json +5 -4
  112. package/registry.json +251 -251
  113. package/src/annotate/angle-mark.ts +137 -137
  114. package/src/annotate/curly-brace.ts +148 -148
  115. package/src/annotate/emphasis-mark.ts +118 -118
  116. package/src/engine.ts +86 -86
  117. package/src/index.ts +29 -29
  118. package/src/kit/brace.ts +37 -37
  119. package/src/kit/cache.ts +61 -61
  120. package/src/kit/component.ts +57 -57
  121. package/src/kit/contour.ts +94 -94
  122. package/src/kit/coords.ts +278 -278
  123. package/src/kit/curve.ts +47 -47
  124. package/src/kit/equation.ts +181 -181
  125. package/src/kit/equation3d.ts +137 -137
  126. package/src/kit/expression.ts +159 -159
  127. package/src/kit/field-mark.ts +171 -171
  128. package/src/kit/field.ts +50 -50
  129. package/src/kit/follow.ts +229 -229
  130. package/src/kit/furniture.ts +113 -113
  131. package/src/kit/geometry.ts +49 -49
  132. package/src/kit/graph.ts +116 -116
  133. package/src/kit/mark.ts +152 -152
  134. package/src/kit/part-fills.ts +61 -61
  135. package/src/kit/place.ts +77 -77
  136. package/src/kit/sampler.ts +281 -281
  137. package/src/kit/scale.ts +39 -39
  138. package/src/kit/source.ts +57 -57
  139. package/src/kit/system.ts +105 -105
  140. package/src/kit/ticks.ts +85 -85
  141. package/src/kit/withdrawn.ts +8 -8
  142. package/src/marks/curve-area.ts +89 -89
  143. package/src/marks/drop-lines.ts +71 -71
  144. package/src/marks/plot-point.ts +102 -102
  145. package/src/marks/riemann-sum.ts +99 -99
  146. package/src/marks/tangent-line.ts +119 -119
  147. package/src/marks/vector-arrow.ts +98 -98
  148. package/src/nodes.ts +99 -99
  149. package/src/plots/function-plot.ts +220 -220
  150. package/src/plots/points-plot.ts +103 -103
  151. package/src/plots/stream-lines.ts +160 -160
  152. package/src/plots/traced-path.ts +70 -70
  153. package/src/plots/vector-field.ts +107 -107
  154. package/src/structures/graph-layout.ts +145 -145
  155. package/src/structures/network-graph.ts +291 -291
  156. package/src/structures/sample-space.ts +210 -210
  157. package/src/systems/axes2d.ts +226 -226
  158. package/src/systems/number-line.ts +130 -130
  159. package/src/systems/number-plane.ts +232 -232
  160. package/src/systems/polar-plane.ts +177 -177
  161. package/src/tex/geometry.ts +703 -703
  162. package/src/tex/index.ts +15 -15
  163. package/src/tex/mathjax.ts +82 -82
  164. package/src/tex/matrix.ts +97 -97
  165. package/src/tex/node.ts +74 -74
  166. package/src/tex/tween.ts +308 -308
  167. package/src/tex/typeset.ts +461 -461
  168. package/src/three/axes3d.ts +267 -267
  169. package/src/three/curve-plot3d.ts +146 -144
  170. package/src/three/entries.ts +42 -42
  171. package/src/three/label3d.ts +52 -50
  172. package/src/three/plot-point3d.ts +63 -63
  173. package/src/three/space.ts +92 -92
  174. package/src/three/surface-plot3d.ts +318 -312
  175. package/src/three/vector-arrow3d.ts +88 -88
  176. package/dist/browser/chunks/chunk-ABYBW64J.js.map +0 -7
  177. package/dist/browser/chunks/chunk-K77KLQX4.js.map +0 -7
  178. package/dist/kit/placement.d.ts +0 -8
  179. package/dist/kit/placement.d.ts.map +0 -1
  180. package/dist/kit/placement.js +0 -8
  181. package/dist/kit/placement.js.map +0 -1
package/src/tex/tween.ts CHANGED
@@ -1,308 +1,308 @@
1
- import { lerpNumber, type PathCommand } from "@motionscript/sdk";
2
- import type { LatexToken } from "./geometry";
3
-
4
- export interface AnimatedToken {
5
- token: string;
6
- path: LatexToken["path"];
7
- /** The top-level term it belongs to at rest; a morph matches on it. */
8
- term?: string;
9
- /** 0 = invisible, 1 = fully visible */
10
- opacity: number;
11
- /** Interpolated position offset applied during morph (x, y in formula space). */
12
- x: number;
13
- y: number;
14
- /** Mid-morph: the index of the token it was in the formula left, and of the one it becomes. */
15
- from?: number;
16
- to?: number;
17
- }
18
-
19
- /**
20
- * How a `Latex` node interpolates between two formulas: given the tokens it
21
- * currently holds and the tokens the target formula resolves to, return a
22
- * pure `t → AnimatedToken[]` frame function. `prepareLatexTween` below is the
23
- * default implementation (exported as `defaultLatexMorph`) — pass a `morph`
24
- * of this shape to `<Latex>` to replace it with your own.
25
- */
26
- export type LatexMorphStrategy = (from: LatexToken[], to: LatexToken[]) => (t: number) => AnimatedToken[];
27
-
28
- /** The coordinate pairs a `PathCommand` can carry, as (x, y) field names. */
29
- const POINT_FIELDS = [["x", "y"], ["x1", "y1"], ["x2", "y2"]] as const;
30
-
31
- /**
32
- * Compute the centroid of a token's path for position-based interpolation.
33
- */
34
- function centroid(path: LatexToken["path"]): { x: number; y: number } {
35
- let sx = 0, sy = 0, n = 0;
36
- for (const cmd of path) {
37
- if ("x" in cmd && "y" in cmd) {
38
- sx += (cmd as any).x;
39
- sy += (cmd as any).y;
40
- n++;
41
- }
42
- }
43
- return n > 0 ? { x: sx / n, y: sy / n } : { x: 0, y: 0 };
44
- }
45
-
46
- /**
47
- * A glyph's on-screen extent, as the diagonal of its control-point bbox.
48
- *
49
- * Only ever used as a *ratio* between the two ends of a match, so the fact that
50
- * control points overshoot the true outline doesn't matter: both ends overshoot
51
- * by the same proportion, because they are the same outline.
52
- */
53
- function extent(path: LatexToken["path"]): number {
54
- let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
55
- for (const cmd of path) {
56
- const c = cmd as any;
57
- for (const [kx, ky] of POINT_FIELDS) {
58
- if (kx in c) {
59
- if (c[kx] < minX) minX = c[kx];
60
- if (c[kx] > maxX) maxX = c[kx];
61
- if (c[ky] < minY) minY = c[ky];
62
- if (c[ky] > maxY) maxY = c[ky];
63
- }
64
- }
65
- }
66
- if (minX > maxX) return 0;
67
- return Math.hypot(maxX - minX, maxY - minY);
68
- }
69
-
70
- /**
71
- * Whether two paths can be interpolated point by point: same command count,
72
- * same command types in the same order.
73
- *
74
- * For a matched pair this is the overwhelmingly common case, and not by luck.
75
- * Tokens are matched on the character their MathJax glyph id decodes to, and
76
- * that id *is* the key into the `<defs>` dictionary — so the same character in
77
- * two formulas is the same outline, emitted twice under two different
78
- * transforms. Same commands, different numbers.
79
- */
80
- function isPointwiseCompatible(from: PathCommand[], to: PathCommand[]): boolean {
81
- if (from.length !== to.length) return false;
82
- for (let i = 0; i < from.length; i++) {
83
- if (from[i].type !== to[i].type) return false;
84
- }
85
- return true;
86
- }
87
-
88
- /**
89
- * Lerp two structurally identical paths point by point.
90
- *
91
- * When the two ends are the same outline under two affine transforms — which is
92
- * what a matched glyph is — this is exact at both ends *and* correct in
93
- * between: `(1-t)·A·q + t·B·q = ((1-t)A + tB)·q`, and a blend of two
94
- * uniform-scale-plus-translate transforms is another one. The intermediate is a
95
- * properly formed glyph at an intermediate size, not a smeared one.
96
- */
97
- function lerpPath(from: PathCommand[], to: PathCommand[], t: number): PathCommand[] {
98
- const out: PathCommand[] = new Array(from.length);
99
- for (let i = 0; i < from.length; i++) {
100
- const f = from[i] as any;
101
- const g = to[i] as any;
102
- const c: any = { ...g };
103
- for (const [kx, ky] of POINT_FIELDS) {
104
- if (kx in g && kx in f) {
105
- c[kx] = lerpNumber(f[kx], g[kx], t);
106
- c[ky] = lerpNumber(f[ky], g[ky], t);
107
- }
108
- }
109
- out[i] = c as PathCommand;
110
- }
111
- return out;
112
- }
113
-
114
- /**
115
- * Scale a path uniformly about (cx, cy), then translate by (dx, dy).
116
- *
117
- * The fallback for a matched pair whose paths *aren't* structurally identical —
118
- * a stretchy delimiter assembled from a different number of pieces at the two
119
- * sizes, say. Point-by-point lerping is impossible there, so the target outline
120
- * is shrunk to the source's size instead and grown back over the morph: the
121
- * size still changes continuously, which is the whole point, at the cost of
122
- * showing the target's shape from the start.
123
- */
124
- function scaleAbout(
125
- path: PathCommand[],
126
- cx: number,
127
- cy: number,
128
- s: number,
129
- dx: number,
130
- dy: number,
131
- ): PathCommand[] {
132
- return path.map(cmd => {
133
- const c: any = { ...(cmd as any) };
134
- for (const [kx, ky] of POINT_FIELDS) {
135
- if (kx in c) {
136
- c[kx] = cx + (c[kx] - cx) * s + dx;
137
- c[ky] = cy + (c[ky] - cy) * s + dy;
138
- }
139
- }
140
- return c as PathCommand;
141
- });
142
- }
143
-
144
- /**
145
- * Match tokens from `from` to `to` by character key, a term that both formulas
146
- * write first: the `x^2` of `x^2 + 1` travels to the `x^2` of `y = x^2` as
147
- * one, instead of lending its `2` to whichever `2` comes first. What is left
148
- * is matched greedily by character alone.
149
- * Returns three lists: matched pairs, deleted tokens (only in from), added tokens (only in to).
150
- */
151
- function matchTokens(
152
- from: LatexToken[],
153
- to: LatexToken[],
154
- ): {
155
- matched: Array<{ from: LatexToken; to: LatexToken }>;
156
- deleted: LatexToken[];
157
- added: LatexToken[];
158
- } {
159
- const remaining = [...to];
160
- const partner = new Map<LatexToken, LatexToken>();
161
- // Synthetic shapes (rects/paths) have no natural token key.
162
- const keyed = (t: LatexToken) => !t.token.startsWith("__");
163
- const pair = (same: (f: LatexToken, t: LatexToken) => boolean) => {
164
- for (const ft of from) {
165
- if (!keyed(ft) || partner.has(ft)) continue;
166
- const idx = remaining.findIndex(t => keyed(t) && same(ft, t));
167
- if (idx === -1) continue;
168
- partner.set(ft, remaining[idx]);
169
- remaining.splice(idx, 1);
170
- }
171
- };
172
- pair((f, t) => f.token === t.token && f.term !== undefined && f.term === t.term);
173
- pair((f, t) => f.token === t.token);
174
-
175
- const matched: Array<{ from: LatexToken; to: LatexToken }> = [];
176
- const deleted: LatexToken[] = [];
177
- for (const ft of from) {
178
- const tt = partner.get(ft);
179
- if (tt) matched.push({ from: ft, to: tt });
180
- else deleted.push(ft);
181
- }
182
-
183
- return { matched, deleted, added: remaining };
184
- }
185
-
186
- /**
187
- * Precompute a formula-change morph and return a pure `t → AnimatedToken[]`
188
- * frame function:
189
- * - Deleted tokens fade out over the first half of `t`.
190
- * - Matched tokens are interpolated — place *and* size — across the full range
191
- * of `t`.
192
- * - Added tokens fade in over the second half of `t`.
193
- *
194
- * A matched glyph is rarely the same size at both ends: the `2` of `b^2` is set
195
- * at script size and the `2` of `2a` at full size, and a `\frac`'s arguments
196
- * come back a step smaller than the same symbols on a baseline. So the
197
- * interpolation has to carry the glyph's *geometry*, not just where it sits.
198
- * Sliding the target outline from one centroid to the other — which is all this
199
- * used to do — put the whole size change between the last static frame and the
200
- * morph's first one: a snap to the new size, then a smooth glide to the new
201
- * place. Point-by-point lerping (see {@link lerpPath}) is that same
202
- * interpolation generalised from a glyph's average point to all of them, and it
203
- * costs nothing extra — the path was already being rebuilt every frame to apply
204
- * the slide.
205
- *
206
- * `t` is normalized `[0, 1]` and already eased — the caller (a `Command`'s
207
- * `at`) applies easing once, up front, the same eased value driving every
208
- * concurrent aspect of the morph (props, intrinsic size, tokens) in lockstep.
209
- */
210
- export function prepareLatexTween(
211
- from: LatexToken[],
212
- to: LatexToken[],
213
- ): (t: number) => AnimatedToken[] {
214
- const { matched, deleted, added } = matchTokens(from, to);
215
-
216
- // Per-match interpolation data. Structure compatibility, and the centroids
217
- // and extents behind the fallback, are properties of the pair rather than
218
- // of `t`, so they are settled once here instead of at every frame.
219
- const fromIndex = new Map(from.map((token, i) => [token, i]));
220
- const toIndex = new Map(to.map((token, i) => [token, i]));
221
- const matchedData = matched.map(({ from: f, to: t }) => {
222
- const toExtent = extent(t.path);
223
- return {
224
- from: fromIndex.get(f),
225
- to: toIndex.get(t),
226
- pointwise: isPointwiseCompatible(f.path, t.path),
227
- fromPath: f.path,
228
- toPath: t.path,
229
- token: t.token,
230
- fromCenter: centroid(f.path),
231
- toCenter: centroid(t.path),
232
- /** Only the fallback needs it, and only as a ratio. */
233
- fromScale: toExtent > 0 ? extent(f.path) / toExtent : 1,
234
- };
235
- });
236
-
237
- return (t: number): AnimatedToken[] => {
238
- const tokens: AnimatedToken[] = [];
239
-
240
- // Matched tokens: interpolate place and size across the full duration.
241
- for (const m of matchedData) {
242
- if (m.pointwise) {
243
- tokens.push({
244
- token: m.token,
245
- path: lerpPath(m.fromPath, m.toPath, t),
246
- opacity: 1,
247
- // Baked into the path above: the lerp carries every point,
248
- // which includes where the glyph sits.
249
- x: 0,
250
- y: 0,
251
- from: m.from,
252
- to: m.to,
253
- });
254
- continue;
255
- }
256
-
257
- const s = lerpNumber(m.fromScale, 1, t);
258
- const cx = lerpNumber(m.fromCenter.x, m.toCenter.x, t);
259
- const cy = lerpNumber(m.fromCenter.y, m.toCenter.y, t);
260
- tokens.push({
261
- token: m.token,
262
- path: scaleAbout(
263
- m.toPath,
264
- m.toCenter.x,
265
- m.toCenter.y,
266
- s,
267
- cx - m.toCenter.x,
268
- cy - m.toCenter.y,
269
- ),
270
- opacity: 1,
271
- x: 0,
272
- y: 0,
273
- from: m.from,
274
- to: m.to,
275
- });
276
- }
277
-
278
- // Deleted tokens: fade out over the first half, gone by t=0.5
279
- for (const d of deleted) {
280
- const fadeT = Math.min(t * 2, 1);
281
- tokens.push({
282
- token: d.token,
283
- path: d.path,
284
- opacity: lerpNumber(1, 0, fadeT),
285
- x: 0,
286
- y: 0,
287
- from: fromIndex.get(d),
288
- });
289
- }
290
-
291
- // Added tokens: fade in over the second half, starting at t=0.5
292
- for (const a of added) {
293
- const fadeT = Math.max(t * 2 - 1, 0);
294
- tokens.push({
295
- token: a.token,
296
- path: a.path,
297
- opacity: lerpNumber(0, 1, fadeT),
298
- x: 0,
299
- y: 0,
300
- to: toIndex.get(a),
301
- });
302
- }
303
-
304
- return tokens;
305
- };
306
- }
307
-
308
- export { prepareLatexTween as defaultLatexMorph };
1
+ import { lerpNumber, type PathCommand } from "@motionscript/sdk";
2
+ import type { LatexToken } from "./geometry";
3
+
4
+ export interface AnimatedToken {
5
+ token: string;
6
+ path: LatexToken["path"];
7
+ /** The top-level term it belongs to at rest; a morph matches on it. */
8
+ term?: string;
9
+ /** 0 = invisible, 1 = fully visible */
10
+ opacity: number;
11
+ /** Interpolated position offset applied during morph (x, y in formula space). */
12
+ x: number;
13
+ y: number;
14
+ /** Mid-morph: the index of the token it was in the formula left, and of the one it becomes. */
15
+ from?: number;
16
+ to?: number;
17
+ }
18
+
19
+ /**
20
+ * How a `Latex` node interpolates between two formulas: given the tokens it
21
+ * currently holds and the tokens the target formula resolves to, return a
22
+ * pure `t → AnimatedToken[]` frame function. `prepareLatexTween` below is the
23
+ * default implementation (exported as `defaultLatexMorph`) — pass a `morph`
24
+ * of this shape to `<Latex>` to replace it with your own.
25
+ */
26
+ export type LatexMorphStrategy = (from: LatexToken[], to: LatexToken[]) => (t: number) => AnimatedToken[];
27
+
28
+ /** The coordinate pairs a `PathCommand` can carry, as (x, y) field names. */
29
+ const POINT_FIELDS = [["x", "y"], ["x1", "y1"], ["x2", "y2"]] as const;
30
+
31
+ /**
32
+ * Compute the centroid of a token's path for position-based interpolation.
33
+ */
34
+ function centroid(path: LatexToken["path"]): { x: number; y: number } {
35
+ let sx = 0, sy = 0, n = 0;
36
+ for (const cmd of path) {
37
+ if ("x" in cmd && "y" in cmd) {
38
+ sx += (cmd as any).x;
39
+ sy += (cmd as any).y;
40
+ n++;
41
+ }
42
+ }
43
+ return n > 0 ? { x: sx / n, y: sy / n } : { x: 0, y: 0 };
44
+ }
45
+
46
+ /**
47
+ * A glyph's on-screen extent, as the diagonal of its control-point bbox.
48
+ *
49
+ * Only ever used as a *ratio* between the two ends of a match, so the fact that
50
+ * control points overshoot the true outline doesn't matter: both ends overshoot
51
+ * by the same proportion, because they are the same outline.
52
+ */
53
+ function extent(path: LatexToken["path"]): number {
54
+ let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
55
+ for (const cmd of path) {
56
+ const c = cmd as any;
57
+ for (const [kx, ky] of POINT_FIELDS) {
58
+ if (kx in c) {
59
+ if (c[kx] < minX) minX = c[kx];
60
+ if (c[kx] > maxX) maxX = c[kx];
61
+ if (c[ky] < minY) minY = c[ky];
62
+ if (c[ky] > maxY) maxY = c[ky];
63
+ }
64
+ }
65
+ }
66
+ if (minX > maxX) return 0;
67
+ return Math.hypot(maxX - minX, maxY - minY);
68
+ }
69
+
70
+ /**
71
+ * Whether two paths can be interpolated point by point: same command count,
72
+ * same command types in the same order.
73
+ *
74
+ * For a matched pair this is the overwhelmingly common case, and not by luck.
75
+ * Tokens are matched on the character their MathJax glyph id decodes to, and
76
+ * that id *is* the key into the `<defs>` dictionary — so the same character in
77
+ * two formulas is the same outline, emitted twice under two different
78
+ * transforms. Same commands, different numbers.
79
+ */
80
+ function isPointwiseCompatible(from: PathCommand[], to: PathCommand[]): boolean {
81
+ if (from.length !== to.length) return false;
82
+ for (let i = 0; i < from.length; i++) {
83
+ if (from[i].type !== to[i].type) return false;
84
+ }
85
+ return true;
86
+ }
87
+
88
+ /**
89
+ * Lerp two structurally identical paths point by point.
90
+ *
91
+ * When the two ends are the same outline under two affine transforms — which is
92
+ * what a matched glyph is — this is exact at both ends *and* correct in
93
+ * between: `(1-t)·A·q + t·B·q = ((1-t)A + tB)·q`, and a blend of two
94
+ * uniform-scale-plus-translate transforms is another one. The intermediate is a
95
+ * properly formed glyph at an intermediate size, not a smeared one.
96
+ */
97
+ function lerpPath(from: PathCommand[], to: PathCommand[], t: number): PathCommand[] {
98
+ const out: PathCommand[] = new Array(from.length);
99
+ for (let i = 0; i < from.length; i++) {
100
+ const f = from[i] as any;
101
+ const g = to[i] as any;
102
+ const c: any = { ...g };
103
+ for (const [kx, ky] of POINT_FIELDS) {
104
+ if (kx in g && kx in f) {
105
+ c[kx] = lerpNumber(f[kx], g[kx], t);
106
+ c[ky] = lerpNumber(f[ky], g[ky], t);
107
+ }
108
+ }
109
+ out[i] = c as PathCommand;
110
+ }
111
+ return out;
112
+ }
113
+
114
+ /**
115
+ * Scale a path uniformly about (cx, cy), then translate by (dx, dy).
116
+ *
117
+ * The fallback for a matched pair whose paths *aren't* structurally identical —
118
+ * a stretchy delimiter assembled from a different number of pieces at the two
119
+ * sizes, say. Point-by-point lerping is impossible there, so the target outline
120
+ * is shrunk to the source's size instead and grown back over the morph: the
121
+ * size still changes continuously, which is the whole point, at the cost of
122
+ * showing the target's shape from the start.
123
+ */
124
+ function scaleAbout(
125
+ path: PathCommand[],
126
+ cx: number,
127
+ cy: number,
128
+ s: number,
129
+ dx: number,
130
+ dy: number,
131
+ ): PathCommand[] {
132
+ return path.map(cmd => {
133
+ const c: any = { ...(cmd as any) };
134
+ for (const [kx, ky] of POINT_FIELDS) {
135
+ if (kx in c) {
136
+ c[kx] = cx + (c[kx] - cx) * s + dx;
137
+ c[ky] = cy + (c[ky] - cy) * s + dy;
138
+ }
139
+ }
140
+ return c as PathCommand;
141
+ });
142
+ }
143
+
144
+ /**
145
+ * Match tokens from `from` to `to` by character key, a term that both formulas
146
+ * write first: the `x^2` of `x^2 + 1` travels to the `x^2` of `y = x^2` as
147
+ * one, instead of lending its `2` to whichever `2` comes first. What is left
148
+ * is matched greedily by character alone.
149
+ * Returns three lists: matched pairs, deleted tokens (only in from), added tokens (only in to).
150
+ */
151
+ function matchTokens(
152
+ from: LatexToken[],
153
+ to: LatexToken[],
154
+ ): {
155
+ matched: Array<{ from: LatexToken; to: LatexToken }>;
156
+ deleted: LatexToken[];
157
+ added: LatexToken[];
158
+ } {
159
+ const remaining = [...to];
160
+ const partner = new Map<LatexToken, LatexToken>();
161
+ // Synthetic shapes (rects/paths) have no natural token key.
162
+ const keyed = (t: LatexToken) => !t.token.startsWith("__");
163
+ const pair = (same: (f: LatexToken, t: LatexToken) => boolean) => {
164
+ for (const ft of from) {
165
+ if (!keyed(ft) || partner.has(ft)) continue;
166
+ const idx = remaining.findIndex(t => keyed(t) && same(ft, t));
167
+ if (idx === -1) continue;
168
+ partner.set(ft, remaining[idx]);
169
+ remaining.splice(idx, 1);
170
+ }
171
+ };
172
+ pair((f, t) => f.token === t.token && f.term !== undefined && f.term === t.term);
173
+ pair((f, t) => f.token === t.token);
174
+
175
+ const matched: Array<{ from: LatexToken; to: LatexToken }> = [];
176
+ const deleted: LatexToken[] = [];
177
+ for (const ft of from) {
178
+ const tt = partner.get(ft);
179
+ if (tt) matched.push({ from: ft, to: tt });
180
+ else deleted.push(ft);
181
+ }
182
+
183
+ return { matched, deleted, added: remaining };
184
+ }
185
+
186
+ /**
187
+ * Precompute a formula-change morph and return a pure `t → AnimatedToken[]`
188
+ * frame function:
189
+ * - Deleted tokens fade out over the first half of `t`.
190
+ * - Matched tokens are interpolated — place *and* size — across the full range
191
+ * of `t`.
192
+ * - Added tokens fade in over the second half of `t`.
193
+ *
194
+ * A matched glyph is rarely the same size at both ends: the `2` of `b^2` is set
195
+ * at script size and the `2` of `2a` at full size, and a `\frac`'s arguments
196
+ * come back a step smaller than the same symbols on a baseline. So the
197
+ * interpolation has to carry the glyph's *geometry*, not just where it sits.
198
+ * Sliding the target outline from one centroid to the other — which is all this
199
+ * used to do — put the whole size change between the last static frame and the
200
+ * morph's first one: a snap to the new size, then a smooth glide to the new
201
+ * place. Point-by-point lerping (see {@link lerpPath}) is that same
202
+ * interpolation generalised from a glyph's average point to all of them, and it
203
+ * costs nothing extra — the path was already being rebuilt every frame to apply
204
+ * the slide.
205
+ *
206
+ * `t` is normalized `[0, 1]` and already eased — the caller (a `Command`'s
207
+ * `at`) applies easing once, up front, the same eased value driving every
208
+ * concurrent aspect of the morph (props, intrinsic size, tokens) in lockstep.
209
+ */
210
+ export function prepareLatexTween(
211
+ from: LatexToken[],
212
+ to: LatexToken[],
213
+ ): (t: number) => AnimatedToken[] {
214
+ const { matched, deleted, added } = matchTokens(from, to);
215
+
216
+ // Per-match interpolation data. Structure compatibility, and the centroids
217
+ // and extents behind the fallback, are properties of the pair rather than
218
+ // of `t`, so they are settled once here instead of at every frame.
219
+ const fromIndex = new Map(from.map((token, i) => [token, i]));
220
+ const toIndex = new Map(to.map((token, i) => [token, i]));
221
+ const matchedData = matched.map(({ from: f, to: t }) => {
222
+ const toExtent = extent(t.path);
223
+ return {
224
+ from: fromIndex.get(f),
225
+ to: toIndex.get(t),
226
+ pointwise: isPointwiseCompatible(f.path, t.path),
227
+ fromPath: f.path,
228
+ toPath: t.path,
229
+ token: t.token,
230
+ fromCenter: centroid(f.path),
231
+ toCenter: centroid(t.path),
232
+ /** Only the fallback needs it, and only as a ratio. */
233
+ fromScale: toExtent > 0 ? extent(f.path) / toExtent : 1,
234
+ };
235
+ });
236
+
237
+ return (t: number): AnimatedToken[] => {
238
+ const tokens: AnimatedToken[] = [];
239
+
240
+ // Matched tokens: interpolate place and size across the full duration.
241
+ for (const m of matchedData) {
242
+ if (m.pointwise) {
243
+ tokens.push({
244
+ token: m.token,
245
+ path: lerpPath(m.fromPath, m.toPath, t),
246
+ opacity: 1,
247
+ // Baked into the path above: the lerp carries every point,
248
+ // which includes where the glyph sits.
249
+ x: 0,
250
+ y: 0,
251
+ from: m.from,
252
+ to: m.to,
253
+ });
254
+ continue;
255
+ }
256
+
257
+ const s = lerpNumber(m.fromScale, 1, t);
258
+ const cx = lerpNumber(m.fromCenter.x, m.toCenter.x, t);
259
+ const cy = lerpNumber(m.fromCenter.y, m.toCenter.y, t);
260
+ tokens.push({
261
+ token: m.token,
262
+ path: scaleAbout(
263
+ m.toPath,
264
+ m.toCenter.x,
265
+ m.toCenter.y,
266
+ s,
267
+ cx - m.toCenter.x,
268
+ cy - m.toCenter.y,
269
+ ),
270
+ opacity: 1,
271
+ x: 0,
272
+ y: 0,
273
+ from: m.from,
274
+ to: m.to,
275
+ });
276
+ }
277
+
278
+ // Deleted tokens: fade out over the first half, gone by t=0.5
279
+ for (const d of deleted) {
280
+ const fadeT = Math.min(t * 2, 1);
281
+ tokens.push({
282
+ token: d.token,
283
+ path: d.path,
284
+ opacity: lerpNumber(1, 0, fadeT),
285
+ x: 0,
286
+ y: 0,
287
+ from: fromIndex.get(d),
288
+ });
289
+ }
290
+
291
+ // Added tokens: fade in over the second half, starting at t=0.5
292
+ for (const a of added) {
293
+ const fadeT = Math.max(t * 2 - 1, 0);
294
+ tokens.push({
295
+ token: a.token,
296
+ path: a.path,
297
+ opacity: lerpNumber(0, 1, fadeT),
298
+ x: 0,
299
+ y: 0,
300
+ to: toIndex.get(a),
301
+ });
302
+ }
303
+
304
+ return tokens;
305
+ };
306
+ }
307
+
308
+ export { prepareLatexTween as defaultLatexMorph };