@algorisys/tinyfly 0.115.0 → 0.116.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 (61) 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 +16 -0
  8. package/docs/maps.md +2 -2
  9. package/docs/math.md +280 -0
  10. package/docs/teaching.md +1 -1
  11. package/lib/addons/characters.js +2607 -2548
  12. package/lib/addons/math.js +2864 -0
  13. package/lib/browser/tinyfly-math.iife.js +53 -0
  14. package/lib/browser/tinyfly.iife.js +3 -3
  15. package/lib/browser/tinyfly.js +705 -638
  16. package/lib/browser/tinyfly.umd.js +3 -3
  17. package/lib/embed/tinyfly-embed.iife.js +1 -1
  18. package/lib/embed/tinyfly-embed.js +8 -0
  19. package/lib/player/tinyfly-player.es.js +8 -0
  20. package/lib/player/tinyfly-player.iife.js +1 -1
  21. package/lib/player/tinyfly-player.umd.js +1 -1
  22. package/lib/types/characters/capabilities.d.ts +8 -0
  23. package/lib/types/math/browser-entry.d.ts +3 -0
  24. package/lib/types/math/embed/auto-mount-math.d.ts +7 -0
  25. package/lib/types/math/embed/explorable.d.ts +46 -0
  26. package/lib/types/math/embed/mount-math.d.ts +31 -0
  27. package/lib/types/math/expr/differentiate.d.ts +7 -0
  28. package/lib/types/math/expr/evaluate.d.ts +21 -0
  29. package/lib/types/math/expr/parse-expression.d.ts +50 -0
  30. package/lib/types/math/figure/derived.d.ts +17 -0
  31. package/lib/types/math/figure/display-list.d.ts +87 -0
  32. package/lib/types/math/figure/figure-spec.d.ts +239 -0
  33. package/lib/types/math/figure/item-context.d.ts +33 -0
  34. package/lib/types/math/figure/items/calculus.d.ts +7 -0
  35. package/lib/types/math/figure/items/curves.d.ts +7 -0
  36. package/lib/types/math/figure/items/grid.d.ts +5 -0
  37. package/lib/types/math/figure/items/regions.d.ts +5 -0
  38. package/lib/types/math/figure/items/text.d.ts +5 -0
  39. package/lib/types/math/figure/items/vectors.d.ts +9 -0
  40. package/lib/types/math/figure/layout-figure.d.ts +13 -0
  41. package/lib/types/math/figure/plane.d.ts +20 -0
  42. package/lib/types/math/figure/validate-spec.d.ts +2 -0
  43. package/lib/types/math/index.d.ts +43 -0
  44. package/lib/types/math/linear/mat2.d.ts +41 -0
  45. package/lib/types/math/linear/vec2.d.ts +18 -0
  46. package/lib/types/math/presets/calculus.d.ts +59 -0
  47. package/lib/types/math/presets/linear-algebra.d.ts +42 -0
  48. package/lib/types/math/render/arrow.d.ts +10 -0
  49. package/lib/types/math/render/display-list-to-svg.d.ts +10 -0
  50. package/lib/types/math/render/draw-display-list.d.ts +6 -0
  51. package/lib/types/math/steps/math-steps.d.ts +34 -0
  52. package/lib/types/math/targets/math-target.d.ts +43 -0
  53. package/lib/types/math/tex/equation-morph.d.ts +21 -0
  54. package/lib/types/math/tex/glyph-metrics.d.ts +24 -0
  55. package/lib/types/math/tex/tex-layout.d.ts +59 -0
  56. package/lib/types/math/tex/tex-parser.d.ts +88 -0
  57. package/lib/types/player/player.d.ts +6 -0
  58. package/llms-full.txt +358 -10
  59. package/llms.txt +32 -31
  60. package/package.json +6 -2
  61. package/skills/tinyfly/SKILL.md +10 -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), 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 and calculus 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.116.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.116.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.116.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.116.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, equation steps, embeds and explorables (`src/math`) | 76 |
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.116.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.116.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.116.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.116.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,22 @@ 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. See `docs/math.md`.
276
+
261
277
  ## Your own behaviours
262
278
 
263
279
  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.116.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.116.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,280 @@
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
+ `point` also rides a curve: `{ on: 'sin(x)', x: 'p' }` is the point (p, sin p), and
82
+ `hollow: true` draws an open circle for a hole or a limit. `function` takes
83
+ `derivative: n` to plot f′, f″ … and `dashed: true`.
84
+
85
+ Fields such as `at`, `from`, `to`, `n`, `h` and `order` take a number or the
86
+ name of a number value, so a timeline can slide the point, shrink the secant,
87
+ add rectangles or Taylor terms.
88
+
89
+ ### Derived numbers
90
+
91
+ Items work out numbers that TeX can show with `\val{…}`:
92
+
93
+ | Item | Numbers |
94
+ |---|---|
95
+ | `tangent` | `ID.slope` (exact, or rise over run for a secant), `ID.x`, `ID.y` |
96
+ | `riemann` | `ID.sum`, `ID.exact` (the integral), `ID.n` |
97
+ | `area` | `ID.value` (the signed integral) |
98
+ | `point` on a curve | `ID.x`, `ID.y` |
99
+ | `taylor` | `ID.order`, `ID.degree` (its whole part) |
100
+
101
+ Slopes, derivative plots and Taylor coefficients come from symbolic
102
+ differentiation of the expression (`differentiate`, `compileDerivative`), so
103
+ they are exact, not finite differences. Integrals use Simpson's rule
104
+ (`integrate`). Calculus items need functions with derivatives; `floor`,
105
+ `ceil` and `round` have none and are refused with a message.
106
+
107
+ Every item has an `id` and may set `color` (a theme colour: `blue`, `green`,
108
+ `red`, `yellow`, `purple`, `orange`, `teal`, `pink`, `ink`, `grey`; or any CSS
109
+ colour), `draw` and `opacity`. Items draw in order, later ones on top.
110
+
111
+ Function plots break at gaps and asymptotes (`tan(x)`, `1/x`, `sqrt(x)` below
112
+ 0) instead of joining across them.
113
+
114
+ ### Expressions
115
+
116
+ Functions and curves are written as text, parsed by a small safe parser (never
117
+ `eval`): `+ - * / ^`, brackets, implicit multiplication (`2x`, `3(x + 1)`),
118
+ `pi`, `e`, `tau`, and these functions: `sin cos tan asin acos atan atan2 sinh
119
+ cosh tanh exp ln log log2 sqrt abs floor ceil round sign min max sigmoid relu`.
120
+
121
+ ## What a timeline animates
122
+
123
+ A figure's target takes ordinary tracks:
124
+
125
+ | Property | Animates |
126
+ |---|---|
127
+ | 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 |
128
+ | `ITEM.draw` | 0..1, draws the item on like a pen |
129
+ | `ITEM.opacity` | 0..1 |
130
+ | `ITEM.step` | an equation's step; in between, terms glide |
131
+
132
+ `mathSteps()` writes these as lesson steps on a `lesson()` builder from
133
+ `@algorisys/tinyfly/teach`:
134
+
135
+ ```js
136
+ import { lesson } from '@algorisys/tinyfly/teach'
137
+ import { determinantFigure, mathSteps } from '@algorisys/tinyfly/math'
138
+
139
+ const figure = determinantFigure({ theme: 'light' })
140
+ const l = lesson({ id: 'determinant' })
141
+ const m = mathSteps(l, 'fig', figure, { hidden: ['square'] })
142
+ l.marker('start', { label: 'î and ĵ span the unit square' })
143
+ m.drawOn('square')
144
+ l.marker('square', { label: 'Its area is 1', pause: true })
145
+ m.applyMatrix([2, 0, 0, 1])
146
+ l.marker('stretch', { label: 'Stretch î by 2: the area doubles', pause: true })
147
+ m.applyMatrix([2, 1, 2, 1])
148
+ l.marker('flat', { label: 'ĵ lies on î’s line', pause: true, question: 'What is the area now?' })
149
+ const timeline = l.definition() // plain JSON
150
+ ```
151
+
152
+ `mathSteps` helpers: `toValue(name, value)`, `applyMatrix(m, { name? })`,
153
+ `drawOn(id)`, `fadeIn(id)`, `fadeOut(id)`, `showStep(id, step)`. Each takes the
154
+ lesson's step options (`duration`, `easing`, `delay`).
155
+
156
+ ## In a lesson page
157
+
158
+ ```html
159
+ <figure data-tinyfly-math data-options='{"stepMode": true}'>
160
+ <script type="application/json" data-tinyfly-figure>{ …the figure… }</script>
161
+ <script type="application/json" data-tinyfly-timeline>{ …the timeline… }</script>
162
+ <figcaption>The determinant is the area of the unit square after the map.</figcaption>
163
+ </figure>
164
+
165
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.116.0/cdn/tinyfly-math.iife.js" data-tinyfly-auto></script>
166
+ ```
167
+
168
+ The figure draws itself into an SVG and redraws from the timeline whenever the
169
+ player moves: playing, stepping, seeking, or showing the last frame under
170
+ reduced motion. Everything else is the ordinary embed (see
171
+ [Teaching Animations](teaching.md)): markers, captions in several languages,
172
+ questions, scenarios, pausing off screen. Tracks target `fig` unless the figure
173
+ says `data-target="…"`.
174
+
175
+ `tinyfly-math.iife.js` (about 40 KB gzipped) works on its own: it carries the
176
+ embed player and controls, `lesson()` and everything in the maths module. A figure
177
+ with no timeline is drawn as a still. Without `data-tinyfly-auto`, call
178
+ `tinyfly.mountAllMath()`.
179
+
180
+ `mathFigureToSvg(figure, values, { title })` writes a standalone SVG of a figure
181
+ at some values, for static pages, RSS, email and print.
182
+
183
+ ## Explorables
184
+
185
+ ```js
186
+ import { linearMapFigure, mathExplorable } from '@algorisys/tinyfly/math'
187
+
188
+ const explorable = mathExplorable(element, linearMapFigure(), {
189
+ drag: [{ matrix: 'M', column: 0 }, { matrix: 'M', column: 1 }], // drag î and ĵ
190
+ sliders: [], // { value, min, max, step?, label? }
191
+ snap: 0.1, // world units (0 for none)
192
+ onChange: (values) => console.log(values.M),
193
+ })
194
+ explorable.set('M', [0, -1, 1, 0])
195
+ ```
196
+
197
+ Drag handles take a vector value (`{ vector: 'v' }`) or a matrix column. Sliders
198
+ take number values. Every change re-lays the figure out from its values, so the
199
+ reader sees exactly what the same values give in a video.
200
+
201
+ ## In a video
202
+
203
+ ```js
204
+ // examples/headless-video/linear-map-short.mjs (abridged)
205
+ import { linearMapFigure, mathTarget, mathSteps } from '@algorisys/tinyfly/math'
206
+ import { lesson } from '@algorisys/tinyfly/teach'
207
+
208
+ const figure = linearMapFigure({ width: 1080, height: 1920, x: [-4, 4] })
209
+ const l = lesson({ id: 'short' })
210
+ mathSteps(l, 'fig', figure).applyMatrix([1, 1, 0, 1])
211
+ export default { width: 1080, height: 1920, fps: 30, targets: { fig: mathTarget(figure) }, timeline: l.definition() }
212
+ ```
213
+
214
+ ```bash
215
+ npx tinyfly video examples/headless-video/linear-map-short.mjs
216
+ ```
217
+
218
+ Line widths and text sizes are given for a 600 px figure and scale with the
219
+ figure's smaller side, so a figure reads the same as a 600 px card and as a
220
+ 1080×1920 short. `mathTarget()` is a canvas custom target: register it on any
221
+ `CanvasAdapter` too, and `describeTarget` / `checkTracks` know its props.
222
+
223
+ ## Equations
224
+
225
+ Equations are typeset by a built-in TeX subset, with no KaTeX or MathJax:
226
+
227
+ - `^` and `_`, `\frac`, `\sqrt`, `\vec`, `\hat`, `\bar`
228
+ - `\sum`, `\prod` and `\int`, with limits above and below in display style
229
+ - Named operators: `\sin \cos \tan \log \ln \exp \det \lim \max \min` …
230
+ - Greek letters
231
+ - Symbols: `\cdot \times \pm \le \ge \ne \approx \to \infty \partial \nabla \in` …
232
+ - Matrices: `\begin{pmatrix|bmatrix|vmatrix|matrix} … \end{…}`
233
+ - `\text{…}`, `\color{name}{…}`, and spacing `\, \; \quad`
234
+ - `\left( … \right)`, with delimiters at their natural size
235
+ - `\id{name}{…}`, which names a term
236
+ - `\val{name}` and `\val{name:digits}` for live values
237
+
238
+ Layout uses fixed glyph metrics, never a font's measurements, so an equation
239
+ lands in the same place everywhere. The glyphs are drawn in a serif maths face
240
+ (`MATH_FONT`: Latin Modern Math, STIX Two Math, Cambria Math, then Times-like
241
+ fallbacks).
242
+
243
+ An `equation` item steps between lines of TeX. Terms pair up by their text and
244
+ order (`x#1`, `=#1`, `2#2`), so `2x + 3 = 7` → `2x = 4` keeps `2`, `x` and `=`,
245
+ fades `+ 3` and `7`, and fades in `4`. Name a term with `\id{lhs}{…}` to carry it
246
+ when its text changes. `layoutTex()` and `morphEquation()` are available on
247
+ their own.
248
+
249
+ ## Ready figures
250
+
251
+ | Preset | Shows |
252
+ |---|---|
253
+ | `linearMapFigure()` | The grid, î, ĵ and the unit square carried by `M`, with the matrix in TeX |
254
+ | `determinantFigure()` | The same, with the square's area labelled `det = …` |
255
+ | `eigenFigure({ matrix })` | The eigenlines of `matrix` (value `A`) while `M` animates toward it |
256
+ | `vectorSumFigure({ u, v })` | u + v tip to tail |
257
+ | `spanFigure({ u, v? })` | Vectors and the lines they span |
258
+ | `tangentFigure({ expr, at })` | The tangent at `a`, with its slope |
259
+ | `secantFigure({ expr, at, h })` | The secant through `a` and `a + h`; key `h` to 0 |
260
+ | `riemannFigure({ expr, from, to, n, rule })` | `n` rectangles, the sum and the exact integral |
261
+ | `areaFigure({ expr, from, to })` | The area up to `b`, its value shown |
262
+ | `taylorFigure({ expr, at, order })` | Taylor polynomials of degree `order` |
263
+ | `limitFigure({ expr, at, limit })` | A point `p` sliding toward a hole |
264
+
265
+ Each returns a plain figure to change or extend. In each, `M` starts at the
266
+ identity unless `matrix` is given.
267
+
268
+ ## Examples
269
+
270
+ - Gallery: **Linear Map**, **Eigenvectors**, **Equation Steps**, **Matrix Lesson**,
271
+ **Derivative**, **Riemann Sums** and **Taylor Series**.
272
+ - Videos: `linear-map-short.mjs` and `riemann-short.mjs` (9:16), `eigen-explainer.mjs`
273
+ and `taylor-explainer.mjs` (16:9), in `examples/headless-video/`.
274
+
275
+ ## Next
276
+
277
+ Probability and statistics (sampling, histograms, the Galton board), discrete
278
+ maths (graphs, trees, sets) and AI/ML (networks, gradient descent on a loss
279
+ surface) build on the same figure model.
280
+ 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.116.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