@motionscript/math 0.1.0 → 0.1.1-alpha.0

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 (252) hide show
  1. package/CHANGELOG.md +19 -0
  2. package/dist/annotate/angle-mark.d.ts +4 -14
  3. package/dist/annotate/angle-mark.d.ts.map +1 -1
  4. package/dist/annotate/angle-mark.js +2 -1
  5. package/dist/annotate/angle-mark.js.map +1 -1
  6. package/dist/annotate/curly-brace.d.ts +4 -16
  7. package/dist/annotate/curly-brace.d.ts.map +1 -1
  8. package/dist/annotate/curly-brace.js.map +1 -1
  9. package/dist/annotate/emphasis-mark.d.ts +0 -5
  10. package/dist/annotate/emphasis-mark.d.ts.map +1 -1
  11. package/dist/annotate/emphasis-mark.js.map +1 -1
  12. package/dist/browser/chunks/chunk-FZ2YBTPL.js +2 -0
  13. package/dist/browser/chunks/chunk-FZ2YBTPL.js.map +7 -0
  14. package/dist/browser/chunks/chunk-T42HWKBC.js +2 -0
  15. package/dist/browser/chunks/chunk-T42HWKBC.js.map +7 -0
  16. package/dist/browser/chunks/{mathjax-WV55AC2P.js → mathjax-SOM6RSPV.js} +1 -1
  17. package/dist/browser/chunks/{mathjax-WV55AC2P.js.map → mathjax-SOM6RSPV.js.map} +2 -2
  18. package/dist/browser/index.js +1 -1
  19. package/dist/browser/index.js.map +3 -3
  20. package/dist/browser/kit.js +1 -1
  21. package/dist/browser/manifest.json +1 -1
  22. package/dist/browser/tex.js +1 -1
  23. package/dist/engine.d.ts +3 -4
  24. package/dist/engine.d.ts.map +1 -1
  25. package/dist/engine.js +3 -4
  26. package/dist/engine.js.map +1 -1
  27. package/dist/kit/cache.d.ts +10 -21
  28. package/dist/kit/cache.d.ts.map +1 -1
  29. package/dist/kit/cache.js +33 -24
  30. package/dist/kit/cache.js.map +1 -1
  31. package/dist/kit/component.d.ts +5 -14
  32. package/dist/kit/component.d.ts.map +1 -1
  33. package/dist/kit/component.js +1 -8
  34. package/dist/kit/component.js.map +1 -1
  35. package/dist/kit/coords.d.ts +1 -1
  36. package/dist/kit/coords.d.ts.map +1 -1
  37. package/dist/kit/coords.js +2 -1
  38. package/dist/kit/coords.js.map +1 -1
  39. package/dist/kit/curve.d.ts +1 -5
  40. package/dist/kit/curve.d.ts.map +1 -1
  41. package/dist/kit/curve.js.map +1 -1
  42. package/dist/kit/equation.d.ts +10 -30
  43. package/dist/kit/equation.d.ts.map +1 -1
  44. package/dist/kit/equation.js +9 -44
  45. package/dist/kit/equation.js.map +1 -1
  46. package/dist/kit/equation3d.d.ts +3 -3
  47. package/dist/kit/equation3d.d.ts.map +1 -1
  48. package/dist/kit/equation3d.js +27 -59
  49. package/dist/kit/equation3d.js.map +1 -1
  50. package/dist/kit/expression.d.ts +7 -7
  51. package/dist/kit/expression.d.ts.map +1 -1
  52. package/dist/kit/expression.js +18 -17
  53. package/dist/kit/expression.js.map +1 -1
  54. package/dist/kit/field-mark.d.ts +0 -7
  55. package/dist/kit/field-mark.d.ts.map +1 -1
  56. package/dist/kit/field-mark.js.map +1 -1
  57. package/dist/kit/field.d.ts +2 -2
  58. package/dist/kit/field.d.ts.map +1 -1
  59. package/dist/kit/field.js +11 -31
  60. package/dist/kit/field.js.map +1 -1
  61. package/dist/kit/follow.d.ts +3 -10
  62. package/dist/kit/follow.d.ts.map +1 -1
  63. package/dist/kit/follow.js +5 -11
  64. package/dist/kit/follow.js.map +1 -1
  65. package/dist/kit/furniture.d.ts +2 -1
  66. package/dist/kit/furniture.d.ts.map +1 -1
  67. package/dist/kit/furniture.js +6 -3
  68. package/dist/kit/furniture.js.map +1 -1
  69. package/dist/kit/geometry.d.ts +1 -0
  70. package/dist/kit/geometry.d.ts.map +1 -1
  71. package/dist/kit/geometry.js +3 -0
  72. package/dist/kit/geometry.js.map +1 -1
  73. package/dist/kit/mark.d.ts +4 -10
  74. package/dist/kit/mark.d.ts.map +1 -1
  75. package/dist/kit/mark.js.map +1 -1
  76. package/dist/kit/place.d.ts +3 -5
  77. package/dist/kit/place.d.ts.map +1 -1
  78. package/dist/kit/place.js +3 -5
  79. package/dist/kit/place.js.map +1 -1
  80. package/dist/kit/sampler.d.ts +0 -5
  81. package/dist/kit/sampler.d.ts.map +1 -1
  82. package/dist/kit/sampler.js.map +1 -1
  83. package/dist/kit/system.d.ts +0 -1
  84. package/dist/kit/system.d.ts.map +1 -1
  85. package/dist/kit/system.js +3 -10
  86. package/dist/kit/system.js.map +1 -1
  87. package/dist/marks/curve-area.d.ts +2 -12
  88. package/dist/marks/curve-area.d.ts.map +1 -1
  89. package/dist/marks/curve-area.js +4 -9
  90. package/dist/marks/curve-area.js.map +1 -1
  91. package/dist/marks/drop-lines.d.ts +1 -5
  92. package/dist/marks/drop-lines.d.ts.map +1 -1
  93. package/dist/marks/drop-lines.js.map +1 -1
  94. package/dist/marks/plot-point.d.ts +4 -13
  95. package/dist/marks/plot-point.d.ts.map +1 -1
  96. package/dist/marks/plot-point.js.map +1 -1
  97. package/dist/marks/riemann-sum.d.ts +1 -7
  98. package/dist/marks/riemann-sum.d.ts.map +1 -1
  99. package/dist/marks/riemann-sum.js +2 -2
  100. package/dist/marks/riemann-sum.js.map +1 -1
  101. package/dist/marks/tangent-line.d.ts +2 -12
  102. package/dist/marks/tangent-line.d.ts.map +1 -1
  103. package/dist/marks/tangent-line.js +1 -5
  104. package/dist/marks/tangent-line.js.map +1 -1
  105. package/dist/marks/vector-arrow.d.ts +2 -11
  106. package/dist/marks/vector-arrow.d.ts.map +1 -1
  107. package/dist/marks/vector-arrow.js +3 -6
  108. package/dist/marks/vector-arrow.js.map +1 -1
  109. package/dist/nodes.d.ts +1 -12
  110. package/dist/nodes.d.ts.map +1 -1
  111. package/dist/nodes.js.map +1 -1
  112. package/dist/plots/function-plot.d.ts +1 -6
  113. package/dist/plots/function-plot.d.ts.map +1 -1
  114. package/dist/plots/function-plot.js +1 -5
  115. package/dist/plots/function-plot.js.map +1 -1
  116. package/dist/plots/points-plot.d.ts +1 -6
  117. package/dist/plots/points-plot.d.ts.map +1 -1
  118. package/dist/plots/points-plot.js.map +1 -1
  119. package/dist/plots/stream-lines.d.ts +0 -7
  120. package/dist/plots/stream-lines.d.ts.map +1 -1
  121. package/dist/plots/stream-lines.js.map +1 -1
  122. package/dist/plots/traced-path.d.ts +1 -12
  123. package/dist/plots/traced-path.d.ts.map +1 -1
  124. package/dist/plots/traced-path.js +1 -6
  125. package/dist/plots/traced-path.js.map +1 -1
  126. package/dist/plots/vector-field.d.ts +1 -10
  127. package/dist/plots/vector-field.d.ts.map +1 -1
  128. package/dist/plots/vector-field.js +3 -6
  129. package/dist/plots/vector-field.js.map +1 -1
  130. package/dist/structures/network-graph.d.ts +15 -34
  131. package/dist/structures/network-graph.d.ts.map +1 -1
  132. package/dist/structures/network-graph.js +2 -5
  133. package/dist/structures/network-graph.js.map +1 -1
  134. package/dist/structures/sample-space.d.ts +8 -22
  135. package/dist/structures/sample-space.d.ts.map +1 -1
  136. package/dist/structures/sample-space.js +3 -5
  137. package/dist/structures/sample-space.js.map +1 -1
  138. package/dist/systems/axes2d.d.ts +0 -1
  139. package/dist/systems/axes2d.d.ts.map +1 -1
  140. package/dist/systems/axes2d.js +3 -4
  141. package/dist/systems/axes2d.js.map +1 -1
  142. package/dist/systems/number-line.d.ts +7 -22
  143. package/dist/systems/number-line.d.ts.map +1 -1
  144. package/dist/systems/number-line.js +2 -2
  145. package/dist/systems/number-line.js.map +1 -1
  146. package/dist/systems/number-plane.d.ts +12 -27
  147. package/dist/systems/number-plane.d.ts.map +1 -1
  148. package/dist/systems/number-plane.js +1 -7
  149. package/dist/systems/number-plane.js.map +1 -1
  150. package/dist/systems/polar-plane.d.ts +11 -26
  151. package/dist/systems/polar-plane.d.ts.map +1 -1
  152. package/dist/systems/polar-plane.js +7 -10
  153. package/dist/systems/polar-plane.js.map +1 -1
  154. package/dist/tex/geometry.d.ts +5 -24
  155. package/dist/tex/geometry.d.ts.map +1 -1
  156. package/dist/tex/geometry.js +19 -90
  157. package/dist/tex/geometry.js.map +1 -1
  158. package/dist/tex/mathjax.d.ts +0 -13
  159. package/dist/tex/mathjax.d.ts.map +1 -1
  160. package/dist/tex/mathjax.js +4 -24
  161. package/dist/tex/mathjax.js.map +1 -1
  162. package/dist/tex/matrix.d.ts +1 -10
  163. package/dist/tex/matrix.d.ts.map +1 -1
  164. package/dist/tex/matrix.js +1 -5
  165. package/dist/tex/matrix.js.map +1 -1
  166. package/dist/tex/tween.d.ts +9 -30
  167. package/dist/tex/tween.d.ts.map +1 -1
  168. package/dist/tex/tween.js +19 -67
  169. package/dist/tex/tween.js.map +1 -1
  170. package/dist/tex/typeset.d.ts +2 -23
  171. package/dist/tex/typeset.d.ts.map +1 -1
  172. package/dist/tex/typeset.js +4 -30
  173. package/dist/tex/typeset.js.map +1 -1
  174. package/dist/three/axes3d.d.ts +32 -62
  175. package/dist/three/axes3d.d.ts.map +1 -1
  176. package/dist/three/axes3d.js +5 -13
  177. package/dist/three/axes3d.js.map +1 -1
  178. package/dist/three/curve-plot3d.d.ts +4 -15
  179. package/dist/three/curve-plot3d.d.ts.map +1 -1
  180. package/dist/three/curve-plot3d.js.map +1 -1
  181. package/dist/three/plot-point3d.d.ts +7 -14
  182. package/dist/three/plot-point3d.d.ts.map +1 -1
  183. package/dist/three/plot-point3d.js.map +1 -1
  184. package/dist/three/space.d.ts +3 -8
  185. package/dist/three/space.d.ts.map +1 -1
  186. package/dist/three/space.js +1 -8
  187. package/dist/three/space.js.map +1 -1
  188. package/dist/three/surface-plot3d.d.ts +9 -23
  189. package/dist/three/surface-plot3d.d.ts.map +1 -1
  190. package/dist/three/surface-plot3d.js.map +1 -1
  191. package/dist/three/vector-arrow3d.d.ts +1 -7
  192. package/dist/three/vector-arrow3d.d.ts.map +1 -1
  193. package/dist/three/vector-arrow3d.js.map +1 -1
  194. package/package.json +4 -4
  195. package/src/annotate/angle-mark.ts +4 -14
  196. package/src/annotate/curly-brace.ts +2 -14
  197. package/src/annotate/emphasis-mark.ts +1 -6
  198. package/src/engine.ts +3 -4
  199. package/src/kit/cache.ts +33 -25
  200. package/src/kit/component.ts +5 -19
  201. package/src/kit/coords.ts +2 -2
  202. package/src/kit/curve.ts +1 -5
  203. package/src/kit/equation.ts +12 -50
  204. package/src/kit/equation3d.ts +23 -59
  205. package/src/kit/expression.ts +18 -23
  206. package/src/kit/field-mark.ts +1 -7
  207. package/src/kit/field.ts +10 -26
  208. package/src/kit/follow.ts +5 -13
  209. package/src/kit/furniture.ts +7 -4
  210. package/src/kit/geometry.ts +4 -0
  211. package/src/kit/mark.ts +4 -11
  212. package/src/kit/place.ts +3 -5
  213. package/src/kit/sampler.ts +0 -6
  214. package/src/kit/system.ts +3 -12
  215. package/src/marks/curve-area.ts +3 -16
  216. package/src/marks/drop-lines.ts +0 -6
  217. package/src/marks/plot-point.ts +2 -12
  218. package/src/marks/riemann-sum.ts +2 -10
  219. package/src/marks/tangent-line.ts +1 -13
  220. package/src/marks/vector-arrow.ts +3 -13
  221. package/src/nodes.ts +1 -12
  222. package/src/plots/function-plot.ts +1 -6
  223. package/src/plots/points-plot.ts +0 -7
  224. package/src/plots/stream-lines.ts +1 -8
  225. package/src/plots/traced-path.ts +2 -13
  226. package/src/plots/vector-field.ts +4 -12
  227. package/src/structures/network-graph.ts +6 -25
  228. package/src/structures/sample-space.ts +5 -20
  229. package/src/systems/axes2d.ts +3 -6
  230. package/src/systems/number-line.ts +4 -20
  231. package/src/systems/number-plane.ts +4 -19
  232. package/src/systems/polar-plane.ts +11 -25
  233. package/src/tex/geometry.ts +24 -126
  234. package/src/tex/mathjax.ts +4 -26
  235. package/src/tex/matrix.ts +1 -11
  236. package/src/tex/tween.ts +21 -75
  237. package/src/tex/typeset.ts +4 -37
  238. package/src/three/axes3d.ts +7 -42
  239. package/src/three/curve-plot3d.ts +0 -12
  240. package/src/three/plot-point3d.ts +0 -10
  241. package/src/three/space.ts +2 -11
  242. package/src/three/surface-plot3d.ts +0 -15
  243. package/src/three/vector-arrow3d.ts +0 -8
  244. package/dist/browser/chunks/chunk-IRZCG6PM.js +0 -2
  245. package/dist/browser/chunks/chunk-IRZCG6PM.js.map +0 -7
  246. package/dist/browser/chunks/chunk-WMVW6ZIV.js +0 -2
  247. package/dist/browser/chunks/chunk-WMVW6ZIV.js.map +0 -7
  248. package/dist/kit/withdrawn.d.ts +0 -9
  249. package/dist/kit/withdrawn.d.ts.map +0 -1
  250. package/dist/kit/withdrawn.js +0 -9
  251. package/dist/kit/withdrawn.js.map +0 -1
  252. package/src/kit/withdrawn.ts +0 -8
@@ -3,8 +3,6 @@ import { PathCommand } from '@motionscript/sdk';
3
3
 
4
4
  import { createBoundedCache } from '../kit/cache';
5
5
 
6
- // --- MathJax, on demand ---
7
-
8
6
  type MathJaxRuntime = typeof import('./mathjax');
9
7
 
10
8
  let runtime: MathJaxRuntime | null = null;
@@ -27,14 +25,13 @@ export function loadMathJax(): Promise<void> {
27
25
  return loading;
28
26
  }
29
27
 
30
- /** Whether MathJax has loaded, so a formula can be typeset now. */
31
28
  export function mathJaxLoaded(): boolean {
32
29
  return runtime !== null;
33
30
  }
34
31
 
35
32
  /** What a formula is before MathJax has loaded: nothing to draw, and nothing cached. */
36
33
  export function blankLatex(): LatexPathResult {
37
- return { tokens: [], parts: [], commands: [], width: 0, height: 0, bounds: [0, 0, 0, 0] };
34
+ return { tokens: [], parts: [], width: 0, height: 0, bounds: [0, 0, 0, 0] };
38
35
  }
39
36
 
40
37
  /** MathJax is not loaded yet: what typesetting throws before {@link loadMathJax} has resolved. */
@@ -45,23 +42,13 @@ export class LatexNotLoaded extends Error {
45
42
  }
46
43
  }
47
44
 
48
- // --- Public API ---
49
-
50
45
  /**
51
- * A formula MathJax could not typeset.
52
- *
53
- * MathJax does not throw on malformed TeX. It typesets an error box in place of
54
- * the formula and tags it `data-mjx-error`, so the failure arrives as a drawing:
55
- * nothing at all from the browser adaptor and a filled bar from the DOM-free
56
- * one, which left a host able to tell a bad formula from a blank one only by the
57
- * token count. {@link buildLatexPath} raises this instead, the same way under
58
- * both adaptors. `\require` is an error too, since only the packages named above
59
- * are loaded.
46
+ * A formula MathJax could not typeset. MathJax does not throw on malformed TeX:
47
+ * it typesets an error box tagged `data-mjx-error`, so {@link buildLatexPath}
48
+ * raises this instead, the same under both adaptors. `\require` is an error too.
60
49
  */
61
50
  export class LatexError extends Error {
62
- /** The formula that failed, as it was given. */
63
51
  readonly latex: string;
64
- /** MathJax's own description of what is wrong with it. */
65
52
  readonly reason: string;
66
53
 
67
54
  constructor(latex: string, reason: string) {
@@ -72,9 +59,8 @@ export class LatexError extends Error {
72
59
  }
73
60
  }
74
61
 
75
- /** A single rendered glyph or shape with its character key and path commands. */
76
62
  export interface LatexToken {
77
- /** Character this token represents, or a synthetic key for non-glyph shapes. */
63
+ /** The character, or a synthetic key (`__rect_N`, `__path_N`) for a rule or bare path. */
78
64
  token: string;
79
65
  path: PathCommand[];
80
66
  /** The source of the top-level term the token belongs to, `a^2` in `a^2 + b^2`; empty for none. */
@@ -86,7 +72,6 @@ export interface LatexToken {
86
72
  * `+`. Every group the typesetter makes is one, so parts nest.
87
73
  */
88
74
  export interface LatexPart {
89
- /** The part's own source. */
90
75
  latex: string;
91
76
  /** The tokens it draws, as a span of the formula's token list: `from` up to, not including, `to`. */
92
77
  from: number;
@@ -96,36 +81,19 @@ export interface LatexPart {
96
81
  }
97
82
 
98
83
  export interface LatexPathResult {
99
- /** All tokens in render order. */
100
84
  tokens: LatexToken[];
101
85
  /** Every part of the formula, outermost first, in source order. */
102
86
  parts: LatexPart[];
103
- /** Flat array of all path commands (for legacy single-path rendering). */
104
- commands: PathCommand[];
105
87
  width: number;
106
88
  height: number;
107
- /**
108
- * Bounding box over every token, in token coordinate space:
109
- * [minX, minY, maxX, maxY]. All tokens share this frame, so passing it as
110
- * each path's center frame keeps their relative layout (instead of each
111
- * glyph centering on its own bbox).
112
- */
89
+ /** [minX, minY, maxX, maxY] over every token: the one centring frame they all share. */
113
90
  bounds: [number, number, number, number];
114
91
  }
115
92
 
116
93
  /**
117
- * A formula's glyph geometry, before a type size is applied to it.
118
- *
119
- * The dividing line this whole module's caching turns on. Getting here is the
120
- * expensive part — MathJax lays the formula out, then the SVG it produces is
121
- * parsed, its glyph dictionary resolved and every `<use>` walked through its
122
- * transform stack — and **none of it depends on `fontSize`**: `mjDoc.convert`
123
- * is called at a fixed em/ex, and the size arrives at the very end as one
124
- * uniform scale (see {@link scaleLatexGeometry}).
125
- *
126
- * So this is what gets remembered per formula, and the size is applied to it
127
- * afresh. A formula animating from 24pt to 120pt is one trip through MathJax
128
- * and one DOM parse, not one per frame.
94
+ * A formula's glyph geometry before a type size is applied. Getting here is the
95
+ * expensive part (MathJax, the SVG walk) and none of it depends on `fontSize`,
96
+ * which arrives at the end as one uniform scale, so this is what gets cached.
129
97
  */
130
98
  interface LatexGeometry {
131
99
  tokens: RawToken[];
@@ -137,29 +105,10 @@ interface LatexGeometry {
137
105
  }
138
106
 
139
107
  /**
140
- * Formulas already worked out, and formulas already sized.
141
- *
142
- * `buildLatexPath` is a pure function of `(text, fontSize)` and used to have no
143
- * memory, which made every caller pay full price for a question it had already
144
- * asked. The callers are not occasional about it either: constructing a `Latex`
145
- * resolves its formula, and so does every `to({ latex })` the moment it starts,
146
- * so a scene re-resolves every formula in it whenever it is rebuilt *and*
147
- * whenever the playhead moves backwards, since a backward seek replays the
148
- * scene's generator from its first frame. An editor that rebuilds on a keystroke
149
- * and seeks on a click asks for the same handful of formulas hundreds of times.
150
- *
151
- * Two memos, each keyed by what its stage actually depends on, and deliberately
152
- * different sizes:
153
- *
154
- * - {@link geometryCache} is everything up to the type size, keyed by the text
155
- * alone. This is the expensive one, and it is generously sized because
156
- * nothing a scene does can churn it: a deck holds as many distinct formulas
157
- * as it holds, and it holds them for as long as it is open.
158
- * - {@link pathCache} is the finished result, keyed by text *and* size. Small
159
- * on purpose: an animated `fontSize` inserts a distinct key every frame, and
160
- * the right thing for a stream like that is to churn a little memo rather
161
- * than a big one. What a miss costs here is arithmetic over glyphs already
162
- * worked out — no MathJax, no parse.
108
+ * `geometryCache` is keyed by text alone and sized for a whole deck. `pathCache`
109
+ * is keyed by text and size and kept small: an animated `fontSize` adds a key
110
+ * every frame, and a miss there is only arithmetic over cached geometry.
111
+ * Backward seeks and rebuilds re-ask for the same formulas hundreds of times.
163
112
  */
164
113
  const geometryCache = createBoundedCache<LatexGeometry>(128);
165
114
  const pathCache = createBoundedCache<LatexPathResult>(64);
@@ -195,11 +144,7 @@ function buildLatexGeometry(text: string): LatexGeometry {
195
144
  return parseLatexSvg(svgEl, parseFloat(heightAttr) || 0);
196
145
  }
197
146
 
198
- /**
199
- * MathJax's description of the error box in a typeset formula, or `null` when
200
- * there is none. Read through the adaptor, so a real DOM and the DOM-free tree
201
- * give the same answer.
202
- */
147
+ /** MathJax's description of the error box in a typeset formula, or `null`; read through the adaptor so a real DOM and the DOM-free tree agree. */
203
148
  function mathJaxError(svgEl: unknown): string | null {
204
149
  for (const el of adaptor.tags(svgEl, 'g') as unknown[]) {
205
150
  const reason = adaptor.getAttribute(el, 'data-mjx-error');
@@ -209,27 +154,15 @@ function mathJaxError(svgEl: unknown): string | null {
209
154
  }
210
155
 
211
156
  /**
212
- * A cached result, handed out safely.
213
- *
214
- * `tokens`, `commands` and the path arrays inside them are shared: they are read
215
- * by everything downstream and written by none of it — `Latex` maps tokens into
216
- * its own wrappers, and the morph builds new paths rather than editing the ones
217
- * it is given — so copying them would be copying the whole formula for nothing.
218
- *
219
- * `bounds` is copied, because it is the one field a caller *stores*: `Latex`
220
- * assigns `result.bounds` straight to `this._bounds` and hands it to the
221
- * renderer as a shared centring frame. That was one node holding its own array
222
- * before there was a memo, and would be two nodes drawing the same formula
223
- * holding one array between them after — four numbers is not a price worth
224
- * paying to find out whether anything downstream ever writes to it.
157
+ * Tokens and their paths are shared, since nothing downstream writes to them.
158
+ * `bounds` is copied: `Latex` stores it and hands it to the renderer as a
159
+ * centring frame, and two nodes on one formula must not share an array.
225
160
  */
226
161
  function lend(result: LatexPathResult): LatexPathResult {
227
162
  const [minX, minY, maxX, maxY] = result.bounds;
228
163
  return { ...result, bounds: [minX, minY, maxX, maxY] };
229
164
  }
230
165
 
231
- // --- High-Speed Matrix Math ---
232
-
233
166
  type Matrix = [number, number, number, number, number, number]; // [a, b, c, d, tx, ty]
234
167
  const identityMatrix: Matrix = [1, 0, 0, 1, 0, 0];
235
168
 
@@ -272,12 +205,7 @@ function applyMatrix(x: number, y: number, m: Matrix): [number, number] {
272
205
  ];
273
206
  }
274
207
 
275
- // --- Glyph ID → character decoding ---
276
-
277
- /**
278
- * MathJax SVG glyph IDs look like "MJX-1-TEX-N-78" or "MJX-1-TEX-I-1D465".
279
- * The last segment is the Unicode codepoint in hex.
280
- */
208
+ /** A MathJax glyph id ends in the codepoint in hex: `MJX-1-TEX-I-1D465`. */
281
209
  function glyphIdToChar(id: string): string {
282
210
  const parts = id.split('-');
283
211
  const hex = parts[parts.length - 1];
@@ -288,8 +216,6 @@ function glyphIdToChar(id: string): string {
288
216
  return id;
289
217
  }
290
218
 
291
- // --- Core Fast Traversal Engine ---
292
-
293
219
  type RawToken = { token: string; cmds: Array<{ cmd: string; args: number[] }>; term?: string };
294
220
 
295
221
  /** The tag name of a node's parent, or "" at the root. */
@@ -299,23 +225,11 @@ function parentKind(node: unknown): string {
299
225
  }
300
226
 
301
227
  /**
302
- * The size-independent half: MathJax's own SVG tree in, glyph geometry out.
303
- *
304
- * Walked through the **adaptor** rather than a `DOMParser`. MathJax already
305
- * builds this tree, and the adaptor is its own abstraction over "a real DOM" and
306
- * "the DOM-free `LiteElement` tree" — the two this module already picks between
307
- * at load. Serialising it to a string and parsing it back needed a `DOMParser`,
308
- * which Node does not have, so every LaTeX node threw `DOMParser is not defined`
309
- * and could not render headlessly at all: no export, and nothing the visual
310
- * suite could check.
311
- *
312
- * Reading the tree directly is also one representation instead of three (tree →
313
- * string → tree), so a browser and a headless host cannot disagree about how the
314
- * markup re-parsed.
228
+ * The size-independent half. Walks MathJax's tree through the adaptor, not a
229
+ * `DOMParser`, which Node lacks: a headless host could not render any formula.
315
230
  */
316
231
  function parseLatexSvg(svgEl: unknown, heightEx: number): LatexGeometry {
317
- // Pre-parse the glyph dictionary. `tags` reaches every <path> in the tree,
318
- // including the ones inside <defs> that the `use` elements reference.
232
+ // `tags` reaches the <path>s inside <defs> that the `use` elements reference.
319
233
  const glyphMap = new Map<string, Array<{ cmd: string; args: number[] }>>();
320
234
  for (const el of adaptor.tags(svgEl, 'path') as unknown[]) {
321
235
  const id = adaptor.getAttribute(el, 'id');
@@ -325,7 +239,6 @@ function parseLatexSvg(svgEl: unknown, heightEx: number): LatexGeometry {
325
239
  }
326
240
  }
327
241
 
328
- // Collect raw tokens — each <use> is one token, rects/paths are grouped as synthetic tokens
329
242
  const rawTokens: RawToken[] = [];
330
243
  const parts: LatexPart[] = [];
331
244
  let synthIdx = 0;
@@ -369,7 +282,6 @@ function parseLatexSvg(svgEl: unknown, heightEx: number): LatexGeometry {
369
282
  }
370
283
  cmds.push({ cmd: gc.cmd, args: shiftedArgs });
371
284
  }
372
- // Derive character from glyph ID
373
285
  const rawId = href.startsWith('#') ? href.slice(1) : href;
374
286
  pushCmds(glyphIdToChar(rawId), cmds);
375
287
  }
@@ -425,20 +337,14 @@ function parseLatexSvg(svgEl: unknown, heightEx: number): LatexGeometry {
425
337
  for (let i = part.from; i < part.to; i++) rawTokens[i].term = part.latex;
426
338
  }
427
339
 
428
- // Bounding box across all raw commands, in the SVG's own coordinates.
429
340
  const box = svgBBox(rawTokens.flatMap(t => t.cmds));
430
341
  return { tokens: rawTokens, parts, box, heightEx };
431
342
  }
432
343
 
433
- /**
434
- * The size-dependent half: glyph geometry in, a laid-out formula out.
435
- *
436
- * Everything here is one uniform scale about the geometry's own centre, which
437
- * is exactly why {@link LatexGeometry} is worth remembering on its own.
438
- */
344
+ /** The size-dependent half: one uniform scale about the geometry's own centre. */
439
345
  function scaleLatexGeometry(geometry: LatexGeometry, fontSize: number): LatexPathResult {
440
346
  const { tokens: rawTokens, parts, box, heightEx } = geometry;
441
- if (rawTokens.length === 0) return { tokens: [], parts: [], commands: [], width: 0, height: 0, bounds: [0, 0, 0, 0] };
347
+ if (rawTokens.length === 0) return { tokens: [], parts: [], width: 0, height: 0, bounds: [0, 0, 0, 0] };
442
348
 
443
349
  const { minX, minY, maxX, maxY } = box;
444
350
  const svgW = maxX - minX;
@@ -478,19 +384,13 @@ function scaleLatexGeometry(geometry: LatexGeometry, fontSize: number): LatexPat
478
384
  ...(rt.term !== undefined && { term: rt.term }),
479
385
  }));
480
386
 
481
- const commands = tokens.flatMap(t => t.path);
482
-
483
- // Shared center frame for all tokens, in token coordinate space. tx/ty map
484
- // the SVG bbox corners; this is the frame every token's path is laid out in.
485
387
  const bounds: [number, number, number, number] = [
486
388
  tx(minX), ty(minY), tx(maxX), ty(maxY),
487
389
  ];
488
390
 
489
- return { tokens, parts, commands, width: svgW * scale, height: svgH * scale, bounds };
391
+ return { tokens, parts, width: svgW * scale, height: svgH * scale, bounds };
490
392
  }
491
393
 
492
- // --- Parts ---
493
-
494
394
  // Spacing and grouping braces are how a source is written, not what it says:
495
395
  // `x^{2}` and `x^2` name one part.
496
396
  function partKey(latex: string): string {
@@ -551,8 +451,6 @@ export function findLatexParts(parts: readonly LatexPart[], selector: string): A
551
451
  return [...found.values()].sort((x, y) => x[0] - y[0] || x[1] - y[1]);
552
452
  }
553
453
 
554
- // --- SVG Path Utilities ---
555
-
556
454
  type RawCmd = { cmd: string; args: number[] };
557
455
 
558
456
  function tokenisePath(d: string): RawCmd[] {
@@ -24,25 +24,8 @@ import '@mathjax/mathjax-newcm-font/js/svg/dynamic/monospace.js';
24
24
  import '@mathjax/mathjax-newcm-font/js/svg/dynamic/sans-serif.js';
25
25
  import '@mathjax/mathjax-newcm-font/js/svg/dynamic/script.js';
26
26
 
27
- /**
28
- * MathJax, set up: the one module that imports it, loaded on demand by
29
- * `loadMathJax` so a scene with no formula in it never downloads or parses it.
30
- */
31
-
32
-
33
- /**
34
- * MathJax needs a DOM to build its output in, and there isn't always one.
35
- *
36
- * `browserAdaptor()` reads `window` **as it is constructed**, at module scope —
37
- * so importing this file at all threw in Node, and a project with one LaTeX
38
- * scene could not be rendered headlessly no matter which scene was asked for.
39
- * `liteAdaptor` is MathJax's own DOM-free implementation and produces the same
40
- * SVG; we only ever read paths back out of it, never attach it to a page.
41
- */
42
- // The two adaptors are structurally different (a `LiteElement` tree vs. a real
43
- // one) and MathJax's generics track that, but nothing here touches an element
44
- // except through the adaptor's own accessors — so the element type is genuinely
45
- // opaque to us, and pinning it to either concrete one would be a lie.
27
+ // `browserAdaptor()` reads `window` at construction, so it cannot run in Node; `liteAdaptor` is DOM-free.
28
+ // Elements are only touched through the adaptor's accessors, so their type is opaque.
46
29
  export const adaptor: any = typeof window === 'undefined' && typeof document === 'undefined'
47
30
  ? liteAdaptor()
48
31
  : browserAdaptor();
@@ -56,13 +39,8 @@ const texJax = new TeX({
56
39
  ],
57
40
  });
58
41
 
59
- /**
60
- * The font files behind `\mathcal`, `\mathbb`, `\mathfrak`, `\mathsf`, `\mathtt`
61
- * and `\mathscr`, imported above. MathJax fetches these asynchronously the first
62
- * time a formula needs one, which a synchronous typesetter cannot wait for, so
63
- * they are bundled and set up on the font before anything is typeset. The font
64
- * class is passed explicitly so the one they register on is the one in use.
65
- */
42
+ // The font files behind the `mathcal`/`mathbb`/... alphabets. MathJax would fetch them asynchronously,
43
+ // which a synchronous typesetter cannot wait for, so they are bundled and set up before anything is typeset.
66
44
  const BUNDLED_FONT_FILES = ['calligraphic', 'double-struck', 'fraktur', 'monospace', 'sans-serif', 'script'];
67
45
 
68
46
  const svgJax = new SVG({ fontCache: 'local', fontData: MathJaxNewcmFont });
package/src/tex/matrix.ts CHANGED
@@ -18,7 +18,6 @@ import {
18
18
  type StrokeResolved as _StrokeResolved,
19
19
  type Vector2 as _Vector2,
20
20
  } from "@motionscript/sdk";
21
- import type { LatexProps } from "./node";
22
21
  import {
23
22
  drawFormula, formula, formulaFrame, layoutFormula, lerpMorph, loadFormula, measureFormula, morphOf, TYPESET, TYPESET_COMMANDS,
24
23
  type Morphing,
@@ -26,11 +25,6 @@ import {
26
25
 
27
26
  export type MatrixBrackets = "square" | "round" | "bar" | "double" | "curly" | "none";
28
27
 
29
- export interface LatexMatrixProps extends LatexProps {
30
- entries: string[][];
31
- brackets: MatrixBrackets;
32
- }
33
-
34
28
  const ENVIRONMENT: Record<MatrixBrackets, string> = {
35
29
  square: "bmatrix",
36
30
  round: "pmatrix",
@@ -73,11 +67,7 @@ const state = {
73
67
  }),
74
68
  };
75
69
 
76
- /**
77
- * A matrix typeset from its entries, row by row, inside the brackets it is
78
- * given. Each entry is a piece of LaTeX and is one of the formula's parts, so
79
- * it can be painted, boxed or braced by its own source.
80
- */
70
+ /** A matrix typeset from its entries inside its brackets; each entry is a formula part, addressable by its source. */
81
71
  export const LatexMatrix = formula(component2d({
82
72
  key: "latexMatrix",
83
73
  state,
package/src/tex/tween.ts CHANGED
@@ -6,9 +6,7 @@ export interface AnimatedToken {
6
6
  path: LatexToken["path"];
7
7
  /** The top-level term it belongs to at rest; a morph matches on it. */
8
8
  term?: string;
9
- /** 0 = invisible, 1 = fully visible */
10
9
  opacity: number;
11
- /** Interpolated position offset applied during morph (x, y in formula space). */
12
10
  x: number;
13
11
  y: number;
14
12
  /** Mid-morph: the index of the token it was in the formula left, and of the one it becomes. */
@@ -17,20 +15,13 @@ export interface AnimatedToken {
17
15
  }
18
16
 
19
17
  /**
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.
18
+ * How a `Latex` node interpolates between two formulas: a pure `t -> tokens`
19
+ * frame function. {@link defaultLatexMorph} is the default; pass a `morph` to replace it.
25
20
  */
26
21
  export type LatexMorphStrategy = (from: LatexToken[], to: LatexToken[]) => (t: number) => AnimatedToken[];
27
22
 
28
- /** The coordinate pairs a `PathCommand` can carry, as (x, y) field names. */
29
23
  const POINT_FIELDS = [["x", "y"], ["x1", "y1"], ["x2", "y2"]] as const;
30
24
 
31
- /**
32
- * Compute the centroid of a token's path for position-based interpolation.
33
- */
34
25
  function centroid(path: LatexToken["path"]): { x: number; y: number } {
35
26
  let sx = 0, sy = 0, n = 0;
36
27
  for (const cmd of path) {
@@ -43,13 +34,7 @@ function centroid(path: LatexToken["path"]): { x: number; y: number } {
43
34
  return n > 0 ? { x: sx / n, y: sy / n } : { x: 0, y: 0 };
44
35
  }
45
36
 
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
- */
37
+ /** The diagonal of a path's control-point bbox: only ever a ratio between the two ends of a match, so the control-point overshoot cancels. */
53
38
  function extent(path: LatexToken["path"]): number {
54
39
  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
55
40
  for (const cmd of path) {
@@ -68,14 +53,9 @@ function extent(path: LatexToken["path"]): number {
68
53
  }
69
54
 
70
55
  /**
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.
56
+ * Whether two paths share command count and types. A matched pair almost always
57
+ * does: a character's glyph id keys one outline in `<defs>`, emitted under two
58
+ * transforms.
79
59
  */
80
60
  function isPointwiseCompatible(from: PathCommand[], to: PathCommand[]): boolean {
81
61
  if (from.length !== to.length) return false;
@@ -86,13 +66,9 @@ function isPointwiseCompatible(from: PathCommand[], to: PathCommand[]): boolean
86
66
  }
87
67
 
88
68
  /**
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.
69
+ * Lerp two structurally identical paths point by point. Matched glyphs are one
70
+ * outline under two uniform-scale-plus-translate transforms, and a blend of
71
+ * those is another, so the in-between is a well-formed glyph at an in-between size.
96
72
  */
97
73
  function lerpPath(from: PathCommand[], to: PathCommand[], t: number): PathCommand[] {
98
74
  const out: PathCommand[] = new Array(from.length);
@@ -112,14 +88,9 @@ function lerpPath(from: PathCommand[], to: PathCommand[], t: number): PathComman
112
88
  }
113
89
 
114
90
  /**
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.
91
+ * Scale a path about (cx, cy), then translate by (dx, dy). The fallback for a
92
+ * matched pair whose paths differ in structure (a stretchy delimiter built from
93
+ * different pieces): the target outline starts at the source's size and grows back.
123
94
  */
124
95
  function scaleAbout(
125
96
  path: PathCommand[],
@@ -146,7 +117,6 @@ function scaleAbout(
146
117
  * write first: the `x^2` of `x^2 + 1` travels to the `x^2` of `y = x^2` as
147
118
  * one, instead of lending its `2` to whichever `2` comes first. What is left
148
119
  * is matched greedily by character alone.
149
- * Returns three lists: matched pairs, deleted tokens (only in from), added tokens (only in to).
150
120
  */
151
121
  function matchTokens(
152
122
  from: LatexToken[],
@@ -184,38 +154,21 @@ function matchTokens(
184
154
  }
185
155
 
186
156
  /**
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`.
157
+ * Precompute a formula-change morph as a pure `t -> tokens` frame function:
158
+ * deleted tokens fade out over the first half, matched tokens interpolate place
159
+ * and size across the whole range, added tokens fade in over the second half.
193
160
  *
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.
161
+ * Size must be interpolated with place: a matched glyph is rarely the same size
162
+ * at both ends (the `2` of `b^2` against the `2` of `2a`), and sliding only the
163
+ * centroid would snap to the new size before the glide. `t` is already eased.
209
164
  */
210
- export function prepareLatexTween(
165
+ export function defaultLatexMorph(
211
166
  from: LatexToken[],
212
167
  to: LatexToken[],
213
168
  ): (t: number) => AnimatedToken[] {
214
169
  const { matched, deleted, added } = matchTokens(from, to);
215
170
 
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.
171
+ // Properties of the pair rather than of `t`, settled once.
219
172
  const fromIndex = new Map(from.map((token, i) => [token, i]));
220
173
  const toIndex = new Map(to.map((token, i) => [token, i]));
221
174
  const matchedData = matched.map(({ from: f, to: t }) => {
@@ -229,7 +182,6 @@ export function prepareLatexTween(
229
182
  token: t.token,
230
183
  fromCenter: centroid(f.path),
231
184
  toCenter: centroid(t.path),
232
- /** Only the fallback needs it, and only as a ratio. */
233
185
  fromScale: toExtent > 0 ? extent(f.path) / toExtent : 1,
234
186
  };
235
187
  });
@@ -237,15 +189,13 @@ export function prepareLatexTween(
237
189
  return (t: number): AnimatedToken[] => {
238
190
  const tokens: AnimatedToken[] = [];
239
191
 
240
- // Matched tokens: interpolate place and size across the full duration.
241
192
  for (const m of matchedData) {
242
193
  if (m.pointwise) {
243
194
  tokens.push({
244
195
  token: m.token,
245
196
  path: lerpPath(m.fromPath, m.toPath, t),
246
197
  opacity: 1,
247
- // Baked into the path above: the lerp carries every point,
248
- // which includes where the glyph sits.
198
+ // The lerp already carries where the glyph sits.
249
199
  x: 0,
250
200
  y: 0,
251
201
  from: m.from,
@@ -275,7 +225,6 @@ export function prepareLatexTween(
275
225
  });
276
226
  }
277
227
 
278
- // Deleted tokens: fade out over the first half, gone by t=0.5
279
228
  for (const d of deleted) {
280
229
  const fadeT = Math.min(t * 2, 1);
281
230
  tokens.push({
@@ -288,7 +237,6 @@ export function prepareLatexTween(
288
237
  });
289
238
  }
290
239
 
291
- // Added tokens: fade in over the second half, starting at t=0.5
292
240
  for (const a of added) {
293
241
  const fadeT = Math.max(t * 2 - 1, 0);
294
242
  tokens.push({
@@ -304,5 +252,3 @@ export function prepareLatexTween(
304
252
  return tokens;
305
253
  };
306
254
  }
307
-
308
- export { prepareLatexTween as defaultLatexMorph };