@algorisys/tinyfly 0.115.0 → 0.117.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 (71) hide show
  1. package/README.md +11 -6
  2. package/docs/api-reference.md +2 -1
  3. package/docs/editor-guide.md +1 -1
  4. package/docs/examples.md +1 -1
  5. package/docs/getting-started.md +1 -1
  6. package/docs/gsap-compat.md +1 -1
  7. package/docs/llm-guide.md +18 -0
  8. package/docs/maps.md +2 -2
  9. package/docs/math.md +313 -0
  10. package/docs/teaching.md +1 -1
  11. package/lib/addons/characters.js +2614 -2548
  12. package/lib/addons/math.js +3384 -0
  13. package/lib/browser/tinyfly-math.iife.js +53 -0
  14. package/lib/browser/tinyfly.iife.js +12 -12
  15. package/lib/browser/tinyfly.js +993 -905
  16. package/lib/browser/tinyfly.umd.js +12 -12
  17. package/lib/embed/tinyfly-embed.iife.js +1 -1
  18. package/lib/embed/tinyfly-embed.js +8 -0
  19. package/lib/engine/tinyfly-engine.js +112 -98
  20. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  21. package/lib/player/tinyfly-player.es.js +8 -0
  22. package/lib/player/tinyfly-player.iife.js +1 -1
  23. package/lib/player/tinyfly-player.umd.js +1 -1
  24. package/lib/types/characters/capabilities.d.ts +8 -0
  25. package/lib/types/engine/authoring/random.d.ts +7 -0
  26. package/lib/types/math/browser-entry.d.ts +3 -0
  27. package/lib/types/math/embed/auto-mount-math.d.ts +7 -0
  28. package/lib/types/math/embed/explorable.d.ts +46 -0
  29. package/lib/types/math/embed/mount-math.d.ts +31 -0
  30. package/lib/types/math/expr/differentiate.d.ts +7 -0
  31. package/lib/types/math/expr/evaluate.d.ts +21 -0
  32. package/lib/types/math/expr/parse-expression.d.ts +50 -0
  33. package/lib/types/math/figure/derived.d.ts +17 -0
  34. package/lib/types/math/figure/display-list.d.ts +87 -0
  35. package/lib/types/math/figure/figure-spec.d.ts +349 -0
  36. package/lib/types/math/figure/item-context.d.ts +39 -0
  37. package/lib/types/math/figure/items/calculus.d.ts +7 -0
  38. package/lib/types/math/figure/items/curves.d.ts +7 -0
  39. package/lib/types/math/figure/items/grid.d.ts +5 -0
  40. package/lib/types/math/figure/items/probability.d.ts +13 -0
  41. package/lib/types/math/figure/items/regions.d.ts +5 -0
  42. package/lib/types/math/figure/items/text.d.ts +5 -0
  43. package/lib/types/math/figure/items/vectors.d.ts +9 -0
  44. package/lib/types/math/figure/layout-figure.d.ts +13 -0
  45. package/lib/types/math/figure/plane.d.ts +20 -0
  46. package/lib/types/math/figure/validate-spec.d.ts +2 -0
  47. package/lib/types/math/index.d.ts +49 -0
  48. package/lib/types/math/linear/mat2.d.ts +41 -0
  49. package/lib/types/math/linear/vec2.d.ts +18 -0
  50. package/lib/types/math/presets/calculus.d.ts +59 -0
  51. package/lib/types/math/presets/linear-algebra.d.ts +42 -0
  52. package/lib/types/math/presets/probability.d.ts +62 -0
  53. package/lib/types/math/prob/bayes.d.ts +16 -0
  54. package/lib/types/math/prob/distributions.d.ts +58 -0
  55. package/lib/types/math/prob/galton.d.ts +18 -0
  56. package/lib/types/math/prob/histogram.d.ts +20 -0
  57. package/lib/types/math/prob/scatter.d.ts +24 -0
  58. package/lib/types/math/render/arrow.d.ts +10 -0
  59. package/lib/types/math/render/display-list-to-svg.d.ts +10 -0
  60. package/lib/types/math/render/draw-display-list.d.ts +6 -0
  61. package/lib/types/math/steps/math-steps.d.ts +34 -0
  62. package/lib/types/math/targets/math-target.d.ts +43 -0
  63. package/lib/types/math/tex/equation-morph.d.ts +21 -0
  64. package/lib/types/math/tex/glyph-metrics.d.ts +24 -0
  65. package/lib/types/math/tex/tex-layout.d.ts +59 -0
  66. package/lib/types/math/tex/tex-parser.d.ts +88 -0
  67. package/lib/types/player/player.d.ts +6 -0
  68. package/llms-full.txt +400 -10
  69. package/llms.txt +32 -31
  70. package/package.json +6 -2
  71. package/skills/tinyfly/SKILL.md +12 -0
package/README.md CHANGED
@@ -47,6 +47,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
47
47
  - **Full screen** - `data-fullscreen="true"` adds a button that fills the screen with the figure, through the Fullscreen API or, on iPhone, an overlay; the drawing scales to the screen whatever the page's figure CSS says
48
48
  - **Scenarios** - Several timelines on one figure, and the reader chooses which plays: a group of options, a stepped slider, or clickable parts of the SVG (`data-tinyfly-choose`). Switching undoes the previous scenario's drawing and keeps the reader at the same step
49
49
  - **Authoring kit** - `lesson()` step builder and diagram primitives (array cells, pointer, stack, queue / channel, table, pipeline) in `@algorisys/tinyfly/teach`
50
+ - **Maths animations** - `@algorisys/tinyfly/math`: figures as JSON (a grid a matrix warps, î and ĵ, vectors, function plots that break at asymptotes, polygons whose area shows the determinant, eigenlines, TeX labels; calculus: tangents and secants with exact slopes, Riemann sums, signed areas, Taylor polynomials from symbolic derivatives, limits; probability: seeded histograms, distributions with shaded probabilities, a Galton board, the central limit theorem, Monte Carlo π, regression and Bayes as areas), a built-in TeX subset (fractions, roots, sums and integrals with limits, matrices, Greek, live values) whose equations rewrite step by step with terms gliding, and ready linear algebra, calculus and probability figures. One layout feeds lesson-page embeds (`<figure data-tinyfly-math>`, stepped with captions and questions), explorables where readers drag î and ĵ, and 9:16 or 16:9 videos ([guide](docs/math.md))
50
51
  - **Build tools** - `npx @algorisys/tinyfly validate` catches broken figures in CI; `render` writes a frame to static SVG for RSS, email and print
51
52
 
52
53
  ### Video from Code
@@ -192,6 +193,7 @@ filling the page. [Open the manga example full page](https://tinyfly.app/example
192
193
  - [GSAP Compatibility](docs/gsap-compat.md) — The GSAP-flavoured API, the mapping table, and what we deliberately don't do
193
194
  - [Rendering Video from Code](docs/video-rendering.md) — `tinyfly video`, custom code-drawn targets, narration timing, captions and stills, without a browser
194
195
  - [Teaching Animations](docs/teaching.md) — Step-through figures: markers, captions, the stepping player, controls, declarative embeds, scenarios the reader chooses, `tinyfly/teach`, validate and render
196
+ - [Maths Animations](docs/math.md) — `tinyfly/math`: figures, the TeX subset, equation steps, lesson embeds, explorables and videos
195
197
  - [Extending tinyfly](docs/extending.md) — Writing adapters, custom eases and stagger offsets, adding a track kind, contributing examples
196
198
  - [Deployment](docs/DEPLOYMENT.md) — Hosting, Docker, and CDN configuration
197
199
  - [2D Animation Roadmap](docs/2d-animation-roadmap.md) — Adobe Animate gap analysis and phased plan (symbols/library, camera, onion skinning, …)
@@ -230,6 +232,7 @@ for what you import:
230
232
  | `@algorisys/tinyfly/interaction` | `Observer`, `Draggable` | Browser |
231
233
  | `@algorisys/tinyfly/embed` | Teaching embeds: the player with step controls, captions, scenarios and one-script `[data-tinyfly-embed]` mounting; `validateEmbed`, `validateScenarios`, `renderFrame` | Browser (tools anywhere) |
232
234
  | `@algorisys/tinyfly/teach` | `lesson()` step builder and diagram primitives (cells, pointer, stack, queue, table, pipeline) | Anywhere |
235
+ | `@algorisys/tinyfly/math` | Maths figures (`mathFigure`, `layoutFigure`, `mathTarget`), the TeX subset (`layoutTex`, `morphEquation`), lesson steps (`mathSteps`), embeds (`mountMath`) and explorables (`mathExplorable`), linear algebra presets, `vec2` / `mat2` | Anywhere (embeds and explorables: browser) |
233
236
  | `@algorisys/tinyfly/react`, `@algorisys/tinyfly/vue`, `@algorisys/tinyfly/svelte`, `@algorisys/tinyfly/solid` | `useTinyfly` hooks, a Svelte action and a Solid primitive: `live` animations scoped to a component and reverted on unmount | Browser (frameworks are optional peer dependencies) |
234
237
  | `@algorisys/tinyfly/maps` | Animated maps: OpenStreetMap tiles or an offline world outline, places, routes that draw on, a camera that flies (`mapTarget`, `mapFlyTracks`, `fitView`, `WORLD_CITIES`) | Anywhere with a Canvas 2D context (tiles need a network) |
235
238
  | `@algorisys/tinyfly/characters` | Poseable stick figure: `stickFigureTarget`, `poseTracks`, `POSES`, `blendPose`, `walkPose`, `drawStickFigure`; `stickFigureJoints` and `layers` for costumes, hair and props; `turn`, `sit` and ground contact; an organic look by default (`classic` keeps the old one); **characters v2**: `character()` / `characterTarget()`, turnarounds front to back, contact, reaching, clean / pencil / silhouette / illustrated looks; `hair`, `facialHair`, `glasses`, `hat`, `ears`, `face`, `feet`, `build`, `outfit` as data, `castMember()`, `HUMAN_EXPRESSIONS` with face marks; `embrace`, `helpUp`, `scenery` | Anywhere with a Canvas 2D context |
@@ -281,7 +284,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
281
284
  itself.
282
285
 
283
286
  ```html
284
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly.iife.js"></script>
287
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly.iife.js"></script>
285
288
  <script>
286
289
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
287
290
 
@@ -302,6 +305,7 @@ itself.
302
305
  | `cdn/tinyfly.esm.js` | The same, as an ES module: `import { live } from '…/cdn/tinyfly.esm.js'` |
303
306
  | `cdn/tinyfly-player.iife.js` | Player only (~17 KB gzipped), for playing editor exports |
304
307
  | `cdn/tinyfly-embed.iife.js` | Only teaching figures (~19 KB gzipped): player, step controls, auto-mount |
308
+ | `cdn/tinyfly-math.iife.js` | Maths figures, equations, lesson embeds (`data-tinyfly-math`) and explorables (~40 KB gzipped, with the embed player); works on its own or after `tinyfly.iife.js` |
305
309
 
306
310
  Replace `@v0.71.0` with the version you want. **Pin a version in production**:
307
311
  a tag's files never change, and each release's `cdn/README.md` lists an SRI hash
@@ -317,7 +321,7 @@ A teaching figure needs no code at all:
317
321
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
318
322
  <figcaption>Appending to a full slice</figcaption>
319
323
  </figure>
320
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
324
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
321
325
  ```
322
326
 
323
327
  See [Teaching Animations](docs/teaching.md).
@@ -335,7 +339,7 @@ This produces:
335
339
 
336
340
  - `lib/engine/tinyfly-engine.js` (ESM) and `.umd.cjs` — the engine
337
341
  - `lib/player/tinyfly-player.{es,umd,iife}.js` — the standalone DOM player
338
- - `lib/addons/{adapters,export,gsap-compat,drivers,interaction,teach}.js` — the optional entry points
342
+ - `lib/addons/{adapters,export,gsap-compat,drivers,interaction,teach,math}.js` — the optional entry points
339
343
  - `lib/frameworks/{react,vue,svelte,solid}.js` — the framework hooks
340
344
  - `lib/embed/tinyfly-embed.{iife.js,js}` — teaching embeds; `lib/cli/tools.js` — the `tinyfly` command
341
345
  - `lib/browser/tinyfly.{iife,umd}.js` and `tinyfly.js` — the all-in-one bundle
@@ -416,7 +420,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
416
420
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
417
421
  </div>
418
422
 
419
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly-player.iife.js"></script>
423
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly-player.iife.js"></script>
420
424
  <script>
421
425
  tinyfly.play('#animation', './animation.json', { loop: -1 })
422
426
  </script>
@@ -525,7 +529,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
525
529
  <svg viewBox="0 0 720 200">…</svg>
526
530
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
527
531
  </figure>
528
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
532
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
529
533
  ```
530
534
 
531
535
  ### Audio / Video Sync
@@ -835,7 +839,8 @@ Characters browser suite checks 74 desktop/mobile scenarios per browser.
835
839
  | Docs viewer and `llms.txt` (`src/docs`) | 18 |
836
840
  | Embeds, teaching kit, framework hooks, landing (`src/embed`, `src/teach`, `src/frameworks`, `src/landing`) | 33 |
837
841
  | Headless rendering and audio (`src/headless`) | 63 |
838
- | Entry boundaries | 2 |
842
+ | Maths figures, TeX, calculus, probability, equation steps, embeds and explorables (`src/math`) | 99 |
843
+ | Entry boundaries | 3 |
839
844
 
840
845
  ## Contributing
841
846
 
@@ -38,7 +38,8 @@ Complete reference for the tinyfly animation engine, player, and adapters.
38
38
  Entry points: `tinyfly` (engine), `@algorisys/tinyfly/export` (CSS, Lottie, GIF, WebP,
39
39
  video and sprite-sheet exporters), `@algorisys/tinyfly/player`, `@algorisys/tinyfly/adapters` (DOM,
40
40
  Canvas, SVG and WebGL adapters, Flip helpers), `@algorisys/tinyfly/drivers`,
41
- `@algorisys/tinyfly/interaction`, `@algorisys/tinyfly/gsap-compat`, `@algorisys/tinyfly/scene-3d` (3D scenes), `@algorisys/tinyfly/browser` (the live
41
+ `@algorisys/tinyfly/interaction`, `@algorisys/tinyfly/gsap-compat`, `@algorisys/tinyfly/scene-3d` (3D scenes), `@algorisys/tinyfly/math`
42
+ (maths figures, equations and lessons; see [Maths Animations](math.md)), `@algorisys/tinyfly/browser` (the live
42
43
  runtime and everything except the exporters, for `<script>` tags), and `@algorisys/tinyfly/headless`
43
44
  (video and stills rendering in Node).
44
45
 
@@ -1143,7 +1143,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
1143
1143
  **Steps to embed:**
1144
1144
  1. Build the player: `npm run build:player`
1145
1145
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
1146
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly-player.iife.js`
1146
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly-player.iife.js`
1147
1147
  instead; see [Deployment](DEPLOYMENT.md))
1148
1148
  3. Copy the generated code into your HTML
1149
1149
  4. Adjust the script `src` path if needed
package/docs/examples.md CHANGED
@@ -743,7 +743,7 @@ For simple website embedding without a build system.
743
743
  </html>
744
744
  ```
745
745
 
746
- Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly-player.iife.js`.
746
+ Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly-player.iife.js`.
747
747
 
748
748
  ---
749
749
 
@@ -185,7 +185,7 @@ with a GSAP-style call (durations are in seconds here):
185
185
  ```html
186
186
  <div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
187
187
 
188
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly.iife.js"></script>
189
189
  <script>
190
190
  tinyfly.to('.box', { x: 200, duration: 1 })
191
191
  </script>
@@ -74,7 +74,7 @@ Without a build step, the all-in-one bundle exposes the same functions on a
74
74
  global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
75
75
 
76
76
  ```html
77
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly.iife.js"></script>
78
78
  <script>
79
79
  tinyfly.to('.box', { x: 200, duration: 1 })
80
80
  </script>
package/docs/llm-guide.md CHANGED
@@ -258,6 +258,24 @@ are declared up front, each with an id the places use. The catalog lists each
258
258
  surface's places and edits. See "A whole scene as data", "Whiteboards" and
259
259
  "Charts" in `docs/acting.md`.
260
260
 
261
+ ## Maths
262
+
263
+ Maths lessons use `@algorisys/tinyfly/math`: write the figure as JSON (`width`,
264
+ `height`, `values`, `items`: grid, axes, vector, basis, point, function,
265
+ parametric, polygon, line, label, equation), check it with `mathFigure(spec)`,
266
+ and write steps with `mathSteps(lesson, 'fig', figure)` (`applyMatrix`,
267
+ `drawOn`, `showStep`). Matrices are `[a, b, c, d]` row by row; columns are where
268
+ î and ĵ land. Functions are expression strings (`'sin(k x)'`, never JS), and
269
+ equations are TeX in the built-in subset (`\frac`, `\sqrt`, `^`, `_`, matrices,
270
+ `\val{M.det}` for live values). Do not name a value `x`, `y`, `t`, `opacity`
271
+ or `scale`: those belong to the figure's target. The same figure plays in a
272
+ lesson page (`<figure data-tinyfly-math>`), an explorable and a video
273
+ (`mathTarget`). Calculus items (`tangent`, `riemann`, `area`, `taylor`, a
274
+ `point` with `on` and `x`) take numbers or number-value names for `at`, `n`,
275
+ `to`, `order`, and publish `\\val{ID.slope}`, `ID.sum`, `ID.value` for TeX. Probability items
276
+ (`histogram`, `distribution`, `galton`, `scatter`, `bayes`) take a distribution as data
277
+ (`{ kind: 'normal', mean: 'mu', sd: 1 }`) and draw seeded samples, never `Math.random`. See `docs/math.md`.
278
+
261
279
  ## Your own behaviours
262
280
 
263
281
  Write new actions with `defineAction()` (from beats, or as timed pose steps),
package/docs/maps.md CHANGED
@@ -14,8 +14,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
14
14
  adds to the same `tinyfly` global:
15
15
 
16
16
  ```html
17
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly-maps.iife.js"></script>
19
19
  ```
20
20
 
21
21
  It is a separate script because the offline world map it carries adds about
package/docs/math.md ADDED
@@ -0,0 +1,313 @@
1
+ # Maths Animations
2
+
3
+ `@algorisys/tinyfly/math` draws maths the way teaching videos and explorable
4
+ lessons show it: a coordinate plane whose grid a matrix warps, vectors, function
5
+ plots, shaded areas, and equations typeset from TeX that rewrite themselves one
6
+ step at a time.
7
+
8
+ The same figure plays in three places:
9
+
10
+ | Where | How |
11
+ |---|---|
12
+ | **Lesson pages** | A `<figure data-tinyfly-math>` with the figure and a timeline as JSON, stepped with the embed controls (next, back, captions, questions) |
13
+ | **Short videos** | A scene for `tinyfly video`, any size: 1080×1920 for 9:16, 1920×1080 for 16:9 |
14
+ | **Explorables** | `mathExplorable()`: the reader drags vectors or matrix columns and moves sliders |
15
+
16
+ All three run the same layout: one pure function turns the figure and its
17
+ current values into shapes, which are drawn on a canvas or written as SVG. The
18
+ same values always give the same picture, in a browser, a Web Worker or Node.
19
+
20
+ ## A figure is JSON
21
+
22
+ ```js
23
+ import { mathFigure } from '@algorisys/tinyfly/math'
24
+
25
+ const figure = mathFigure({
26
+ width: 600, height: 600, // px
27
+ x: [-5, 5], // world units across (y follows, square)
28
+ theme: 'dark', // dark (default) | light | chalk
29
+ values: { M: [1, 0, 0, 1], k: 1 },
30
+ items: [
31
+ { id: 'grid', kind: 'grid', transform: 'M', ghost: true },
32
+ { id: 'basis', kind: 'basis', transform: 'M' },
33
+ { id: 'wave', kind: 'function', expr: 'sin(k x)', color: 'blue' },
34
+ { id: 'eq', kind: 'label', tex: '\\begin{bmatrix} \\val{M.a} & \\val{M.b} \\\\ \\val{M.c} & \\val{M.d} \\end{bmatrix}', at: [30, 60], screen: true, align: 'left' },
35
+ ],
36
+ })
37
+ ```
38
+
39
+ `mathFigure()` checks the figure and throws a message that says how to fix it:
40
+ unknown kinds and themes with the name probably meant, duplicate ids, values of
41
+ the wrong shape, expressions that do not parse or read a missing parameter, TeX
42
+ mistakes with their position.
43
+
44
+ ### Values
45
+
46
+ Everything that moves is a **value**: a number (`k`), a vector `[x, y]` or a
47
+ matrix `[a, b, c, d]`, written row by row:
48
+
49
+ | a b |
50
+ | c d |
51
+
52
+ The first column `[a, c]` is where î lands and the second `[b, d]` is where ĵ
53
+ lands. Items name the values they use (`transform: 'M'`, `to: 'v'`), and number
54
+ values are the parameters of functions (`sin(k x)`). TeX shows values live with
55
+ `\val{name}` (`\val{name:1}` for one decimal). Matrices also give
56
+ `M.a M.b M.c M.d M.det`, and vectors give `v.x v.y v.length`.
57
+
58
+ Some names are reserved, because a track on them would move the whole figure:
59
+ `x`, `y`, `opacity`, `scale`, `rotate` and the other canvas properties, and `t`.
60
+
61
+ ### Items
62
+
63
+ | Kind | Options |
64
+ |---|---|
65
+ | `grid` | `step?`, `transform?` (a matrix value), `ghost?` (the original grid, faintly underneath) |
66
+ | `axes` | `ticks?` (0 for none), `labels?` |
67
+ | `vector` | `to`, `from?`, `transform?`, `label?` (TeX), `labelAt?: 'tip' \| 'middle'`, `width?` |
68
+ | `basis` | `transform?`, `labels?`: î and ĵ |
69
+ | `point` | `at`, `transform?`, `label?`, `radius?` |
70
+ | `function` | `expr` in `x`, `domain?`, `width?` |
71
+ | `parametric` | `x` and `y` in `t`, `t?` range, `transform?` |
72
+ | `polygon` | `points?` (default the unit square), `transform?`, `fillOpacity?`, `label?` |
73
+ | `line` | `along` (a span) or `eigen` (a matrix value: one line per real eigenvector), `dashed?` |
74
+ | `label` | `tex`, `at`, `screen?` (px instead of world units), `size?`, `align?`, `backdrop?` |
75
+ | `equation` | `steps` (TeX, one per step), `at`, `screen?`, `size?`, `align?`, `backdrop?` |
76
+ | `tangent` | `expr`, `at`, `h?` (a secant through `at` and `at + h`), `length?`, `points?`, `label?` |
77
+ | `riemann` | `expr`, `from`, `to`, `n` (pieces), `rule?: 'left' \| 'right' \| 'midpoint' \| 'trapezoid'`, `fillOpacity?` |
78
+ | `area` | `expr`, `from`, `to`, `lower?` (another function), `negativeColor?`, `fillOpacity?` |
79
+ | `taylor` | `expr`, `at`, `order` (0–20; a fractional order grows the next term in), `domain?` |
80
+
81
+ | `histogram` | `distribution`, `count` (samples so far), `bins?: [from, to, n]`, `scale?: 'density' \| 'count'`, `curve?`, `seed?` |
82
+ | `distribution` | `distribution`, `shade?: [a, b]` (P(a ≤ X ≤ b)), `domain?` |
83
+ | `galton` | `rows?`, `balls` (fractional: the next ball on its way), `spacing?`, `top?`, `seed?` |
84
+ | `scatter` | `points: { kind: 'uniform', x, y }` or `{ kind: 'linear', slope, intercept, noise, x }`, `count`, `inside?` (an expression in x and y, true when ≤ 0), `fit?`, `seed?` |
85
+ | `bayes` | `prior`, `truePositive`, `falsePositive`, `at?`, `size?`, `labels?` |
86
+
87
+ `point` also rides a curve: `{ on: 'sin(x)', x: 'p' }` is the point (p, sin p), and
88
+ `hollow: true` draws an open circle for a hole or a limit. `function` takes
89
+ `derivative: n` to plot f′, f″ … and `dashed: true`.
90
+
91
+ Fields such as `at`, `from`, `to`, `n`, `h` and `order` take a number or the
92
+ name of a number value, so a timeline can slide the point, shrink the secant,
93
+ add rectangles or Taylor terms.
94
+
95
+ ### Derived numbers
96
+
97
+ Items work out numbers that TeX can show with `\val{…}`:
98
+
99
+ | Item | Numbers |
100
+ |---|---|
101
+ | `tangent` | `ID.slope` (exact, or rise over run for a secant), `ID.x`, `ID.y` |
102
+ | `riemann` | `ID.sum`, `ID.exact` (the integral), `ID.n` |
103
+ | `area` | `ID.value` (the signed integral) |
104
+ | `point` on a curve | `ID.x`, `ID.y` |
105
+ | `taylor` | `ID.order`, `ID.degree` (its whole part) |
106
+ | `histogram` | `ID.count`, `ID.mean`, `ID.sd` (of the samples so far) |
107
+ | `distribution` | `ID.p` (the shaded probability), `ID.mean`, `ID.sd` |
108
+ | `galton` | `ID.landed` |
109
+ | `scatter` | `ID.count`, `ID.inside`, `ID.ratio`, `ID.slope`, `ID.intercept`, `ID.r` |
110
+ | `bayes` | `ID.prior`, `ID.posterior`, `ID.positive`, `ID.truePositive`, `ID.falsePositive` |
111
+
112
+ ### Distributions and randomness
113
+
114
+ A distribution is data: `{ kind: 'normal', mean, sd }`, `uniform` (`min`,
115
+ `max`), `exponential` (`rate`), `binomial` (`n`, `p`), `poisson` (`rate`),
116
+ `dice` (`count`, `sides`), or `{ kind: 'mean', of, count }`, the average of
117
+ `count` draws (what the central limit theorem is about). Any of its numbers
118
+ may be a value name, so a slider moves the mean or n. `density`, `meanOf`,
119
+ `sdOf`, `sample` and `samples` work on them directly.
120
+
121
+ Every sample comes from a seed (the item id unless `seed` is given), through
122
+ the engine's `createRandom`, `randomNormal` and `shuffled`. A histogram that
123
+ grows from 10 to 1000 samples keeps its first 10, and every render, video and
124
+ reader sees the same draws.
125
+
126
+ Slopes, derivative plots and Taylor coefficients come from symbolic
127
+ differentiation of the expression (`differentiate`, `compileDerivative`), so
128
+ they are exact, not finite differences. Integrals use Simpson's rule
129
+ (`integrate`). Calculus items need functions with derivatives; `floor`,
130
+ `ceil` and `round` have none and are refused with a message.
131
+
132
+ Every item has an `id` and may set `color` (a theme colour: `blue`, `green`,
133
+ `red`, `yellow`, `purple`, `orange`, `teal`, `pink`, `ink`, `grey`; or any CSS
134
+ colour), `draw` and `opacity`. Items draw in order, later ones on top.
135
+
136
+ Function plots break at gaps and asymptotes (`tan(x)`, `1/x`, `sqrt(x)` below
137
+ 0) instead of joining across them.
138
+
139
+ ### Expressions
140
+
141
+ Functions and curves are written as text, parsed by a small safe parser (never
142
+ `eval`): `+ - * / ^`, brackets, implicit multiplication (`2x`, `3(x + 1)`),
143
+ `pi`, `e`, `tau`, and these functions: `sin cos tan asin acos atan atan2 sinh
144
+ cosh tanh exp ln log log2 sqrt abs floor ceil round sign min max sigmoid relu`.
145
+
146
+ ## What a timeline animates
147
+
148
+ A figure's target takes ordinary tracks:
149
+
150
+ | Property | Animates |
151
+ |---|---|
152
+ | a value's name (`M`, `k`, `v`) | the value; a matrix keyed from `[1, 0, 0, 1]` to `[1, 1, 0, 1]` shears the plane, every point moving in a straight line |
153
+ | `ITEM.draw` | 0..1, draws the item on like a pen |
154
+ | `ITEM.opacity` | 0..1 |
155
+ | `ITEM.step` | an equation's step; in between, terms glide |
156
+
157
+ `mathSteps()` writes these as lesson steps on a `lesson()` builder from
158
+ `@algorisys/tinyfly/teach`:
159
+
160
+ ```js
161
+ import { lesson } from '@algorisys/tinyfly/teach'
162
+ import { determinantFigure, mathSteps } from '@algorisys/tinyfly/math'
163
+
164
+ const figure = determinantFigure({ theme: 'light' })
165
+ const l = lesson({ id: 'determinant' })
166
+ const m = mathSteps(l, 'fig', figure, { hidden: ['square'] })
167
+ l.marker('start', { label: 'î and ĵ span the unit square' })
168
+ m.drawOn('square')
169
+ l.marker('square', { label: 'Its area is 1', pause: true })
170
+ m.applyMatrix([2, 0, 0, 1])
171
+ l.marker('stretch', { label: 'Stretch î by 2: the area doubles', pause: true })
172
+ m.applyMatrix([2, 1, 2, 1])
173
+ l.marker('flat', { label: 'ĵ lies on î’s line', pause: true, question: 'What is the area now?' })
174
+ const timeline = l.definition() // plain JSON
175
+ ```
176
+
177
+ `mathSteps` helpers: `toValue(name, value)`, `applyMatrix(m, { name? })`,
178
+ `drawOn(id)`, `fadeIn(id)`, `fadeOut(id)`, `showStep(id, step)`. Each takes the
179
+ lesson's step options (`duration`, `easing`, `delay`).
180
+
181
+ ## In a lesson page
182
+
183
+ ```html
184
+ <figure data-tinyfly-math data-options='{"stepMode": true}'>
185
+ <script type="application/json" data-tinyfly-figure>{ …the figure… }</script>
186
+ <script type="application/json" data-tinyfly-timeline>{ …the timeline… }</script>
187
+ <figcaption>The determinant is the area of the unit square after the map.</figcaption>
188
+ </figure>
189
+
190
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly-math.iife.js" data-tinyfly-auto></script>
191
+ ```
192
+
193
+ The figure draws itself into an SVG and redraws from the timeline whenever the
194
+ player moves: playing, stepping, seeking, or showing the last frame under
195
+ reduced motion. Everything else is the ordinary embed (see
196
+ [Teaching Animations](teaching.md)): markers, captions in several languages,
197
+ questions, scenarios, pausing off screen. Tracks target `fig` unless the figure
198
+ says `data-target="…"`.
199
+
200
+ `tinyfly-math.iife.js` (about 40 KB gzipped) works on its own: it carries the
201
+ embed player and controls, `lesson()` and everything in the maths module. A figure
202
+ with no timeline is drawn as a still. Without `data-tinyfly-auto`, call
203
+ `tinyfly.mountAllMath()`.
204
+
205
+ `mathFigureToSvg(figure, values, { title })` writes a standalone SVG of a figure
206
+ at some values, for static pages, RSS, email and print.
207
+
208
+ ## Explorables
209
+
210
+ ```js
211
+ import { linearMapFigure, mathExplorable } from '@algorisys/tinyfly/math'
212
+
213
+ const explorable = mathExplorable(element, linearMapFigure(), {
214
+ drag: [{ matrix: 'M', column: 0 }, { matrix: 'M', column: 1 }], // drag î and ĵ
215
+ sliders: [], // { value, min, max, step?, label? }
216
+ snap: 0.1, // world units (0 for none)
217
+ onChange: (values) => console.log(values.M),
218
+ })
219
+ explorable.set('M', [0, -1, 1, 0])
220
+ ```
221
+
222
+ Drag handles take a vector value (`{ vector: 'v' }`) or a matrix column. Sliders
223
+ take number values. Every change re-lays the figure out from its values, so the
224
+ reader sees exactly what the same values give in a video.
225
+
226
+ ## In a video
227
+
228
+ ```js
229
+ // examples/headless-video/linear-map-short.mjs (abridged)
230
+ import { linearMapFigure, mathTarget, mathSteps } from '@algorisys/tinyfly/math'
231
+ import { lesson } from '@algorisys/tinyfly/teach'
232
+
233
+ const figure = linearMapFigure({ width: 1080, height: 1920, x: [-4, 4] })
234
+ const l = lesson({ id: 'short' })
235
+ mathSteps(l, 'fig', figure).applyMatrix([1, 1, 0, 1])
236
+ export default { width: 1080, height: 1920, fps: 30, targets: { fig: mathTarget(figure) }, timeline: l.definition() }
237
+ ```
238
+
239
+ ```bash
240
+ npx tinyfly video examples/headless-video/linear-map-short.mjs
241
+ ```
242
+
243
+ Line widths and text sizes are given for a 600 px figure and scale with the
244
+ figure's smaller side, so a figure reads the same as a 600 px card and as a
245
+ 1080×1920 short. `mathTarget()` is a canvas custom target: register it on any
246
+ `CanvasAdapter` too, and `describeTarget` / `checkTracks` know its props.
247
+
248
+ ## Equations
249
+
250
+ Equations are typeset by a built-in TeX subset, with no KaTeX or MathJax:
251
+
252
+ - `^` and `_`, `\frac`, `\sqrt`, `\vec`, `\hat`, `\bar`
253
+ - `\sum`, `\prod` and `\int`, with limits above and below in display style
254
+ - Named operators: `\sin \cos \tan \log \ln \exp \det \lim \max \min` …
255
+ - Greek letters
256
+ - Symbols: `\cdot \times \pm \le \ge \ne \approx \to \infty \partial \nabla \in` …
257
+ - Matrices: `\begin{pmatrix|bmatrix|vmatrix|matrix} … \end{…}`
258
+ - `\text{…}`, `\color{name}{…}`, and spacing `\, \; \quad`
259
+ - `\left( … \right)`, with delimiters at their natural size
260
+ - `\id{name}{…}`, which names a term
261
+ - `\val{name}` and `\val{name:digits}` for live values
262
+
263
+ Layout uses fixed glyph metrics, never a font's measurements, so an equation
264
+ lands in the same place everywhere. The glyphs are drawn in a serif maths face
265
+ (`MATH_FONT`: Latin Modern Math, STIX Two Math, Cambria Math, then Times-like
266
+ fallbacks).
267
+
268
+ An `equation` item steps between lines of TeX. Terms pair up by their text and
269
+ order (`x#1`, `=#1`, `2#2`), so `2x + 3 = 7` → `2x = 4` keeps `2`, `x` and `=`,
270
+ fades `+ 3` and `7`, and fades in `4`. Name a term with `\id{lhs}{…}` to carry it
271
+ when its text changes. `layoutTex()` and `morphEquation()` are available on
272
+ their own.
273
+
274
+ ## Ready figures
275
+
276
+ | Preset | Shows |
277
+ |---|---|
278
+ | `linearMapFigure()` | The grid, î, ĵ and the unit square carried by `M`, with the matrix in TeX |
279
+ | `determinantFigure()` | The same, with the square's area labelled `det = …` |
280
+ | `eigenFigure({ matrix })` | The eigenlines of `matrix` (value `A`) while `M` animates toward it |
281
+ | `vectorSumFigure({ u, v })` | u + v tip to tail |
282
+ | `spanFigure({ u, v? })` | Vectors and the lines they span |
283
+ | `tangentFigure({ expr, at })` | The tangent at `a`, with its slope |
284
+ | `secantFigure({ expr, at, h })` | The secant through `a` and `a + h`; key `h` to 0 |
285
+ | `riemannFigure({ expr, from, to, n, rule })` | `n` rectangles, the sum and the exact integral |
286
+ | `areaFigure({ expr, from, to })` | The area up to `b`, its value shown |
287
+ | `taylorFigure({ expr, at, order })` | Taylor polynomials of degree `order` |
288
+ | `limitFigure({ expr, at, limit })` | A point `p` sliding toward a hole |
289
+ | `normalFigure({ mean, sd, shade })` | The normal curve with P(a ≤ X ≤ b) shaded (`mu`, `sigma`, `a`, `b`) |
290
+ | `binomialFigure({ n, p })` | Binomial bars |
291
+ | `cltFigure({ of, k, samples })` | Means of `k` draws piling into a normal curve |
292
+ | `galtonFigure({ rows, balls })` | A Galton board |
293
+ | `monteCarloPiFigure({ count })` | Points in a square; the share inside the circle ≈ π/4 |
294
+ | `regressionFigure({ slope, intercept, noise, count })` | Noisy points and the least-squares line |
295
+ | `bayesFigure({ prior, sensitivity, falsePositive })` | A medical test as areas: P(condition given a positive) |
296
+
297
+ Each returns a plain figure to change or extend. In each, `M` starts at the
298
+ identity unless `matrix` is given.
299
+
300
+ ## Examples
301
+
302
+ - Gallery: **Linear Map**, **Eigenvectors**, **Equation Steps**, **Matrix Lesson**,
303
+ **Derivative**, **Riemann Sums**, **Taylor Series**, **Galton Board**, **Central Limit
304
+ Theorem**, **Monte Carlo π** and **Bayes: a Positive Test**.
305
+ - Videos: `linear-map-short.mjs`, `riemann-short.mjs` and `galton-short.mjs` (9:16);
306
+ `eigen-explainer.mjs`, `taylor-explainer.mjs` and `clt-explainer.mjs` (16:9), in
307
+ `examples/headless-video/`.
308
+
309
+ ## Next
310
+
311
+ Discrete maths (graphs, trees, sets) and AI/ML (networks, gradient descent on
312
+ a loss surface) build on the same figure model.
313
+ See `todo.md` for their status.
package/docs/teaching.md CHANGED
@@ -25,7 +25,7 @@ path for all of that:
25
25
  </figure>
26
26
 
27
27
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
28
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.115.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.117.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
29
29
  ```
30
30
 
31
31
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post