@algorisys/tinyfly 0.91.0 → 0.93.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 (63) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +466 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +123 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +2785 -1794
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6575 -5454
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +95 -0
  45. package/lib/types/characters/acting/hand-path.d.ts +32 -0
  46. package/lib/types/characters/acting/index.d.ts +2 -0
  47. package/lib/types/characters/acting/script.d.ts +66 -7
  48. package/lib/types/characters/capabilities.d.ts +50 -0
  49. package/lib/types/characters/code-panel.d.ts +201 -0
  50. package/lib/types/characters/figure-actions.d.ts +11 -0
  51. package/lib/types/characters/figure-props.d.ts +87 -0
  52. package/lib/types/characters/gaits.d.ts +8 -0
  53. package/lib/types/characters/index.d.ts +4 -0
  54. package/lib/types/characters/species/human-motion.d.ts +45 -0
  55. package/lib/types/characters/species/human.d.ts +2 -0
  56. package/lib/types/characters/stick-figure.d.ts +2 -0
  57. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  58. package/lib/types/engine/authoring/index.d.ts +1 -0
  59. package/llms-full.txt +12548 -0
  60. package/llms.txt +57 -0
  61. package/package.json +6 -2
  62. package/skills/tinyfly/SKILL.md +64 -0
  63. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,54 @@
1
+ # Sprite-sheet export
2
+
3
+ Export an animation as a **sprite sheet**: every frame packed into one PNG grid,
4
+ plus a JSON metadata file. This is the format game engines (Phaser, Unity, Godot,
5
+ PixiJS) and custom `<canvas>` players expect.
6
+
7
+ ## Using it
8
+
9
+ 1. Open **Export** and choose **Sprite**.
10
+ 2. Set the **FPS** (frame count = duration × fps) and **scale** (each frame is the
11
+ scaled artboard size). Turn on **Transparent** for an alpha PNG.
12
+ 3. Click **Export SPRITE**. You get two files:
13
+ - `name-spritesheet.png` — the grid of frames (up to 8 columns).
14
+ - `name-spritesheet.json` — the metadata below.
15
+
16
+ ## Metadata
17
+
18
+ ```json
19
+ {
20
+ "frameWidth": 200,
21
+ "frameHeight": 200,
22
+ "columns": 8,
23
+ "rows": 4,
24
+ "frames": 30,
25
+ "fps": 30,
26
+ "durationMs": 1000
27
+ }
28
+ ```
29
+
30
+ Frames are packed left-to-right, top-to-bottom; frame `i` sits at
31
+ `col = i % columns`, `row = floor(i / columns)`, pixel origin
32
+ `(col × frameWidth, row × frameHeight)`. Frames are sampled evenly across the
33
+ duration (`i / frames`), so a looping clip doesn't repeat the first pose.
34
+
35
+ ## How it works
36
+
37
+ The layout math is a pure, unit-tested helper:
38
+
39
+ ```ts
40
+ // src/engine/export/sprite-sheet.ts
41
+ spriteSheetLayout(frames, frameWidth, frameHeight, maxColumns) // grid + sheet size
42
+ frameCell(index, layout) // cell col/row/x/y
43
+ spriteFrameTimes(frames, durationMs) // sample times
44
+ spriteSheetMeta(layout, fps, durationMs) // JSON metadata
45
+ ```
46
+
47
+ The export dialog reuses the **same per-frame `draw`** as GIF/WebP/MP4 (so shapes,
48
+ text, paths, images, video layers, symbols, and the camera all composite in),
49
+ translating and clipping it into each cell.
50
+
51
+ ## Limitations / later
52
+
53
+ - Max 8 columns (keeps sheets reasonably square); configurable later.
54
+ - Very long / high-fps clips make large PNGs — lower the fps or scale if needed.
@@ -0,0 +1,137 @@
1
+ # Symbols + Library — Phase A design
2
+
3
+ **Status:** In progress (foundation landing incrementally)
4
+ **Date:** 2026-07-22
5
+ **Roadmap:** [2d-animation-roadmap.md](2d-animation-roadmap.md) → Phase A
6
+
7
+ Symbols make a bundle of elements **reusable**: define once, place many instances,
8
+ edit-once-update-everywhere. It's the highest-leverage Adobe-Animate-parity
9
+ feature and stays true to tinyfly's JSON-first, loosely-coupled design — a symbol
10
+ is just a small self-contained scene, and an instance is just an element that
11
+ references it.
12
+
13
+ ---
14
+
15
+ ## Data model
16
+
17
+ A **symbol definition** is a self-contained mini-scene (its own elements +
18
+ optional internal timeline), stored on the **project** so it's shared across all
19
+ scenes:
20
+
21
+ ```ts
22
+ interface SymbolDefinition {
23
+ id: string
24
+ name: string
25
+ /** Intrinsic size; instances scale from this into their placement box. */
26
+ width: number
27
+ height: number
28
+ elements: SceneElement[] // the symbol's own contents
29
+ timeline: TimelineDefinition | null // the symbol's own (nested) animation
30
+ created: number
31
+ modified: number
32
+ }
33
+
34
+ interface Project {
35
+ // …existing fields…
36
+ symbols: SymbolDefinition[] // the Library
37
+ }
38
+ ```
39
+
40
+ A **symbol instance** is a new scene-element type. Its base transform
41
+ (`x, y, width, height, rotation, opacity`) places and sizes the instance; the
42
+ symbol's contents render scaled from the symbol's intrinsic size into that box:
43
+
44
+ ```ts
45
+ type ElementType = /* …existing… */ | 'symbol'
46
+
47
+ interface SymbolInstanceElement extends BaseElement {
48
+ type: 'symbol'
49
+ symbolId: string // → SymbolDefinition.id
50
+ /** Reserved for later per-instance property overrides / symbol-swap. */
51
+ overrides?: Record<string, unknown>
52
+ }
53
+ ```
54
+
55
+ Everything remains plain JSON and serializes with the project exactly like scenes
56
+ do — no engine change is required to *store* symbols.
57
+
58
+ ---
59
+
60
+ ## Why on the project (not the scene)
61
+
62
+ Symbols are reusable across scenes (a "button" symbol used on every scene), so the
63
+ Library belongs to the project. Instances live inside scenes like any other
64
+ element. Deleting a symbol that still has instances is guarded (warn / block).
65
+
66
+ ---
67
+
68
+ ## Rendering an instance
69
+
70
+ An instance renders like a `group`: expand the symbol's `elements`, transformed
71
+ into the instance's box (translate to `x,y`, scale `width/symbol.width` ×
72
+ `height/symbol.height`, then rotate/opacity from the instance). This reuses the
73
+ existing per-element renderers in the preview and the DOM/Canvas/SVG adapters.
74
+
75
+ - **Static first:** render the symbol's elements at their base values (the poster
76
+ frame). Editing the symbol updates every instance immediately.
77
+ - **Nested timeline next:** play the symbol's own timeline relative to the
78
+ instance. Deterministic and still JSON — the engine composes the nested tracks.
79
+
80
+ ---
81
+
82
+ ## Editing: "edit in place"
83
+
84
+ Double-clicking an instance enters the symbol: the stage shows the symbol's
85
+ contents, the timeline shows the symbol's tracks, and a **breadcrumb**
86
+ (`Scene ▸ SymbolName`) returns to the parent scene. The parent scene is dimmed.
87
+ Changes affect the definition, so all instances update.
88
+
89
+ ---
90
+
91
+ ## Lip-sync for free
92
+
93
+ Because an instance references a symbol by id, a **symbol-swap** track (change
94
+ `symbolId` / an override per keyframe) gives mouth-shape swapping and similar
95
+ "which drawing shows now" workflows **without a bone system** — a genuinely
96
+ on-brand shortcut.
97
+
98
+ ---
99
+
100
+ ## Implementation slices
101
+
102
+ 1. **Foundation (this slice):** types (`SymbolDefinition`, `SymbolInstanceElement`,
103
+ `'symbol'` element type), `project.symbols` + migration, project-store Library
104
+ methods (`createSymbol`, `getSymbols`, `getSymbol`, `renameSymbol`,
105
+ `deleteSymbol`, `symbolInstanceCount`), serialization, and unit tests. No UI
106
+ yet — the model is proven in isolation.
107
+ 2. **Convert & place:** "Convert to Symbol" command (bundle selection → symbol +
108
+ replace with an instance) and a Library panel (list, place instance).
109
+ 3. **Render:** expand instances in the preview + DOM/Canvas/SVG adapters (static
110
+ poster frame).
111
+ 4. **Edit-in-place:** breadcrumb + nested-timeline editing.
112
+ 5. **Nested playback + symbol-swap:** compose the symbol's timeline at play time;
113
+ symbol-swap track for lip-sync.
114
+
115
+ ---
116
+
117
+ ## Store API (foundation)
118
+
119
+ ```ts
120
+ createSymbol(name, elements, opts?): SymbolDefinition // add to the Library
121
+ getSymbols(): SymbolDefinition[]
122
+ getSymbol(id): SymbolDefinition | undefined
123
+ renameSymbol(id, name): void
124
+ deleteSymbol(id): boolean // guarded if instances exist
125
+ symbolInstanceCount(id): number // across all scenes
126
+ ```
127
+
128
+ Instances are created by the "Convert to Symbol" / "Place instance" flows (slice
129
+ 2), which add a `type: 'symbol'` element via the scene store.
130
+
131
+ ---
132
+
133
+ ## Non-goals (Phase A)
134
+
135
+ - Bone/IK rigging (see roadmap — out of scope).
136
+ - Deep per-property instance overrides beyond transform + symbol-swap (later).
137
+ - Recursive symbols-in-symbols beyond a sane depth guard.
@@ -0,0 +1,348 @@
1
+ # Teaching animations
2
+
3
+ Explanatory figures inside tutorials show how a slice grows, how a value moves
4
+ through a channel, or how a request passes through middleware. They differ from
5
+ marketing motion: readers step through them, each **state** is the message, they
6
+ carry captions in several languages, and there are many on one page. tinyfly has a
7
+ path for all of that:
8
+
9
+ | Piece | What it gives you |
10
+ |---|---|
11
+ | **Markers** in the JSON | Named steps: step through them, stop at them, caption them |
12
+ | **The player** | Shows a frame on load; steps between markers; respects reduced motion; pauses off screen |
13
+ | **`@algorisys/tinyfly/embed`** | Step controls with captions and questions, and one-script declarative mounting for CMS pages |
14
+ | **Scenarios** | Several timelines on one figure, and the reader chooses: options, a stepped slider, or clickable parts of the SVG |
15
+ | **`@algorisys/tinyfly/teach`** | A `lesson()` step builder, and diagram primitives (cells, pointer, stack, queue, table, pipeline) |
16
+ | **The `tinyfly` command** | `validate` for build pipelines; `render` a frame to static SVG for RSS, email and print |
17
+
18
+ ## Quick start: one script, declarative figures
19
+
20
+ ```html
21
+ <figure data-tinyfly-embed data-alt="Appending to a full slice">
22
+ <svg viewBox="0 0 720 200">…<rect data-tinyfly="cell-3" …/>…</svg>
23
+ <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
24
+ <figcaption>Appending to a full slice allocates a new array.</figcaption>
25
+ </figure>
26
+
27
+ <!-- once, anywhere on the page (a site-wide footer is fine) -->
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
29
+ ```
30
+
31
+ Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
32
+ JavaScript, so optimisation plugins that defer or strip inline scripts don't break
33
+ it. Without `data-tinyfly-auto`, call `tinyfly.mountAll()` yourself.
34
+
35
+ **Which script:**
36
+
37
+ | Script | Use it when |
38
+ |---|---|
39
+ | `tinyfly.iife.js` (~53 kB gzipped) | The site also animates with code (`tinyfly.to`, scroll triggers, …). It includes the embeds too; `data-tinyfly-auto` works the same |
40
+ | `tinyfly-embed.iife.js` (~19 kB gzipped) | The page only shows teaching figures |
41
+
42
+ Loading more than one is safe: they add to the same `tinyfly` global.
43
+
44
+ | Attribute | Meaning |
45
+ |---|---|
46
+ | `data-options` | Player options as JSON, e.g. `'{"stepMode": true, "autoplay": true}'` |
47
+ | `data-src` | Load the timeline from a URL instead of an inline script |
48
+ | `data-controls="false"` | No controls (a looping illustration) |
49
+ | `data-labels` | Control labels as JSON: `'{"play": "Reproducir", "next": "Siguiente"}'` |
50
+ | `data-markers` | Steps by time for a timeline without markers: `"0,2300,3800"` (ids `step-1`, `step-2`, …) |
51
+ | `data-alt` | The figure's accessible name (otherwise its `<figcaption>`) |
52
+ | `<script type="application/json" data-tinyfly-captions>` | Translated captions for this figure |
53
+
54
+ **Embed defaults:**
55
+
56
+ - **Frame on load:** the first frame shows as soon as the figure mounts.
57
+ - **Off screen:** playback pauses while the figure is off screen or the tab is hidden.
58
+ - **Accessibility:** the SVG becomes `role="img"` with an accessible name, and step
59
+ captions are announced politely.
60
+
61
+ For a pinned version, lock the file with its SRI hash from the CDN's `cdn/README.md`.
62
+
63
+ ## Markers: the steps
64
+
65
+ ```json
66
+ {
67
+ "formatVersion": 1,
68
+ "id": "append",
69
+ "config": {
70
+ "duration": 3200,
71
+ "markers": [
72
+ { "id": "before", "time": 0, "label": "len 3, cap 4" },
73
+ { "id": "full", "time": 1400, "label": "cap is full", "pause": true, "question": "What happens on the next append?" },
74
+ { "id": "grown", "time": 3200, "label": "new array, cap 8" }
75
+ ]
76
+ },
77
+ "captions": {
78
+ "es": { "before": "len 3, cap 4", "full": "la capacidad está llena", "grown": "arreglo nuevo, cap 8" },
79
+ "zh-CN": { "full": "容量已满" }
80
+ },
81
+ "tracks": [ … ]
82
+ }
83
+ ```
84
+
85
+ - **`label`** is the caption in the timeline's own language.
86
+ - **`captions`** translate labels per marker id. The page's `lang` (the closest
87
+ `[lang]` ancestor, then `<html lang>`) chooses the language, and `es-MX` falls back
88
+ to `es` and then to the label. Translations never touch the tracks.
89
+ - **`pause: true`** stops playback at the marker, even when not stepping.
90
+ - **`question`** is shown while stopped there, with a **Reveal** button: the
91
+ predict-then-reveal pattern.
92
+
93
+ ## The player
94
+
95
+ ```js
96
+ const player = tinyfly.create('#figure', { stepMode: true, onMarker: (m) => console.log(m?.id) })
97
+ await player.load(definition)
98
+
99
+ player.next() // animate to the next marker (a jump under reduced motion)
100
+ player.prev() // jump to the previous marker
101
+ player.goToMarker('full')
102
+ player.currentMarker // { id, time, label, … }
103
+ player.caption() // the current caption, in the page's language
104
+ player.subscribe(render) // called when time, play state or the marker changes
105
+ ```
106
+
107
+ | Option | Default | |
108
+ |---|---|---|
109
+ | `initialFrame` | `'start'` | The frame shown on load: `'start'`, `'end'`, a time in ms, or `'none'`. Reduced motion takes precedence and shows the final frame; set `respectReducedMotion: false` to opt out |
110
+ | `stepMode` | `false` | `play()` runs to the next marker and stops |
111
+ | `respectReducedMotion` | `true` | Under `prefers-reduced-motion: reduce`: never autoplay, show the final frame, steps jump. Follows changes |
112
+ | `playWhenVisible` | `false` (embeds: `true`) | Pause off screen and in hidden tabs; `autoplay` waits until the figure is seen |
113
+ | `captions` | — | Captions per language per marker id, merged over the timeline's |
114
+ | `onMarker(marker)` | — | Called when the current marker changes |
115
+
116
+ **Values that change in steps:**
117
+
118
+ - **Text:** a `text` keyframe (`"len = 3"` → `"len = 4"`) switches exactly at its
119
+ time. Strings never blend.
120
+ - **Numbers:** to hold a number and jump, give the keyframe
121
+ `{ "type": "steps", "count": 1, "position": "start" }`.
122
+ - **SVG paint:** `fill`, `stroke`, `strokeWidth` and `strokeDashoffset` on SVG
123
+ elements are written as SVG paint, so colouring a cell works. On HTML elements
124
+ `fill` still means background.
125
+
126
+ ## Controls
127
+
128
+ The embed bundle has them built in. To add them to your own player:
129
+
130
+ ```js
131
+ import { createControls } from '@algorisys/tinyfly/embed'
132
+ createControls(player, figureElement, { labels: { play: 'Reproducir' }, speeds: [0.5, 1, 2] })
133
+ ```
134
+
135
+ - **Controls:** restart, previous step, play/pause, next step, a scrub bar, a step
136
+ counter ("2 / 5"), speed, the caption line and the question.
137
+ - **Keys:** while focus is inside that figure, Space plays or pauses, ← and → step,
138
+ Home restarts, and F toggles full screen when it's on. Several figures on one page
139
+ never react to the same key press.
140
+ - **Styling:** use custom properties on `.tf-ctl`: `--tf-ctl-fg`, `--tf-ctl-bg`,
141
+ `--tf-ctl-accent`, `--tf-ctl-radius`, `--tf-ctl-font`. Every class is prefixed
142
+ `tf-ctl`.
143
+ - **Text:** all visible text comes from `labels`. The step counter reads
144
+ `"{index} / {total}"` by default; set `labels.stepFormat` to use words, e.g.
145
+ `"Step {index} of {total}"` or `"第 {index} 步,共 {total} 步"`.
146
+ - **Empty rows:** with no captions (no marker labels and no translations) the caption
147
+ line is left out, and the question row only appears at a step that asks one.
148
+ - **Several bundles:** `tinyfly-player.iife.js`, `tinyfly-embed.iife.js` and
149
+ `tinyfly.iife.js` add to one `tinyfly` global, so loading more than one keeps every
150
+ bundle's functions.
151
+
152
+ ## Full screen
153
+
154
+ A detailed diagram is easier to follow when it fills the screen. Turn on a full screen
155
+ button per figure:
156
+
157
+ ```html
158
+ <figure data-tinyfly-embed data-fullscreen="true">…</figure>
159
+ ```
160
+
161
+ or in code, `createControls(player, figure, { fullscreen: true })`.
162
+
163
+ - **Where the browser supports it:** the button uses the Fullscreen API on the figure,
164
+ so the figure, its controls and its captions fill the screen, and the browser's own
165
+ Esc leaves it.
166
+ - **Where it doesn't:** iPhone Safari only supports element fullscreen on iPad. There,
167
+ and whenever the browser refuses a request, the figure becomes a fixed overlay over
168
+ the page, the page behind stops scrolling, and Esc or the button closes it.
169
+ - **Layout:** in both modes the figure gets the class `tf-fullscreen` and becomes a
170
+ column: the controls and captions keep their size, and the SVG or canvas takes the
171
+ remaining space, scaled to fit. Those rules use `!important` on purpose, so a host
172
+ page's figure CSS, such as a `max-width` or a phone `min-width`, can't keep the drawing
173
+ at its in-page size. The background comes from `--tf-fullscreen-bg` (default white).
174
+ - **Short landscape screens** (a phone on its side, up to 520px tall): the controls and
175
+ captions move into a column beside the drawing, so the drawing keeps most of the width
176
+ instead of shrinking into the strip left above a stack of controls.
177
+ - **Accessibility:** the button is labelled `labels.fullscreen` / `labels.exitFullscreen`
178
+ ("Full screen", "Exit full screen") and reports its state with `aria-pressed`.
179
+ - **From code:** `controls.fullscreen.enter()`, `.exit()` and `.active`.
180
+
181
+ ## Scenarios: let the reader change something
182
+
183
+ Some ideas are a comparison, not a sequence: a request with and without a cache, a
184
+ cluster before and after its leader fails, one server against ten. Give the figure
185
+ one timeline per case, and the reader chooses which one plays.
186
+
187
+ ```html
188
+ <figure data-tinyfly-embed data-scenario-legend="Cache">
189
+ <svg viewBox="0 0 720 240">
190
+ …<rect data-tinyfly="db" …/>…
191
+ <g data-tinyfly-choose="cache" aria-label="Turn the cache on">…</g>
192
+ </svg>
193
+ <script type="application/json" data-tinyfly-timeline
194
+ data-scenario="no-cache" data-scenario-label="Off">{ …timeline… }</script>
195
+ <script type="application/json" data-tinyfly-timeline
196
+ data-scenario="cache" data-scenario-label="On">{ …timeline… }</script>
197
+ <figcaption>The same request, with and without a cache.</figcaption>
198
+ </figure>
199
+ ```
200
+
201
+ Every scenario animates the same markup. The controls add a choice under the bar.
202
+
203
+ | Attribute | On | Meaning |
204
+ |---|---|---|
205
+ | `data-scenario` | a timeline script | The scenario's id |
206
+ | `data-scenario-label` | a timeline script | What the reader sees on the choice (default: the id) |
207
+ | `data-scenario` | the figure | The scenario shown first (default: the first script) |
208
+ | `data-scenario-legend` | the figure | Names the choice: "Cache", "Servers" (default: `labels.scenario`, "Scenario") |
209
+ | `data-scenario-control` | the figure | `buttons` (default), a group of options; or `slider`, for points on a scale |
210
+ | `data-tinyfly-choose` | any element inside | Makes it a button that chooses that scenario |
211
+
212
+ **Two or more timeline scripts make a scenario figure.** One script with a
213
+ `data-scenario` does too, and `validate` warns that it gives the reader nothing to
214
+ choose. `data-markers` gives steps to every scenario that has none. Scenarios are
215
+ inline only; `data-src` isn't read for them.
216
+
217
+ **What switching does:**
218
+
219
+ - **Clean slate:** whatever the previous scenario drew is undone first. Each
220
+ target's authored `style` attribute, its text (for elements holding only text)
221
+ and its path geometry are put back, then the new scenario draws. A box one
222
+ scenario paints red is back to its authored colour in a scenario that never
223
+ touches it.
224
+ - **Same step:** when the new scenario has a marker with the current marker's id,
225
+ the reader lands on it. Give comparable moments the same ids ("ask", "answer")
226
+ and the reader can flip between cases without losing their place.
227
+ - **The end stays the end.** Otherwise, the start.
228
+ - **Playing stays playing.** A paused figure stays paused.
229
+ - **Reduced motion:** the new scenario's final frame.
230
+
231
+ **Choosing a control:**
232
+
233
+ - **Options** (radio buttons) for distinct cases: "HTTP/2" or "HTTP/3", "Read
234
+ committed" or "Serializable". Arrow keys move between them.
235
+ - **Slider** for points on a scale: 1, 10, 100 servers. It's a range input with one
236
+ stop per scenario, in script order. The value's label is shown beside it and
237
+ announced as `aria-valuetext`.
238
+ - **Hotspots** for acting on the diagram itself: click the leader to take it down.
239
+ Each `[data-tinyfly-choose]` becomes a toggle button (`role="button"`,
240
+ `tabindex="0"`, `aria-pressed` while its scenario shows), chosen with a click,
241
+ Enter or Space. It's named by its own `aria-label` or else the scenario's label.
242
+ Hotspots work with `data-controls="false"` too.
243
+
244
+ **Numbers come from the author, not the browser.** A slider's stops are
245
+ precomputed timelines, not a formula evaluated on the page. That keeps figures
246
+ deterministic and JSON-only, and lets a build script generate every stop from the
247
+ same calculation the text quotes.
248
+
249
+ From code:
250
+
251
+ ```js
252
+ const player = tinyfly.create('#figure')
253
+ await player.loadScenarios([
254
+ { id: 'no-cache', label: 'Off', timeline: slow },
255
+ { id: 'cache', label: 'On', timeline: fast },
256
+ ], { initial: 'no-cache' })
257
+
258
+ player.scenarios // [{ id: 'no-cache', label: 'Off' }, { id: 'cache', label: 'On' }]
259
+ player.scenario // 'no-cache'
260
+ player.setScenario('cache')
261
+ createControls(player, figure, { scenarioControl: 'slider', labels: { scenario: 'Cache' } })
262
+ bindChoiceHotspots(player, figure) // returns a function that unbinds them
263
+ ```
264
+
265
+ ## Authoring with `@algorisys/tinyfly/teach`
266
+
267
+ ```js
268
+ import { lesson, figure, cells, pointer } from '@algorisys/tinyfly/teach'
269
+
270
+ const slice = cells({ id: 's', values: [1, 2, 3, ''], x: 20, y: 30 })
271
+ const len = pointer({ id: 'len', label: 'len', x: slice.center(2).x, y: 100 })
272
+
273
+ const l = lesson({ id: 'append' })
274
+ l.marker('before', { label: 'len 3, cap 4', captions: { es: 'len 3, cap 4' } })
275
+ slice.write(l, 3, 4)
276
+ len.moveTo(l, slice.center(3).x)
277
+ l.marker('after', { label: 'len 4', pause: true, question: 'What is cap(s) now?' })
278
+ slice.highlight(l, 3)
279
+
280
+ const markup = figure({ width: 360, height: 160, title: 'Appending to a slice', children: [slice, len] })
281
+ const definition = l.definition()
282
+ ```
283
+
284
+ **`lesson()` builds keyframes from steps:**
285
+
286
+ | Call | Effect |
287
+ |---|---|
288
+ | `to(target, values, { duration, easing, delay })` | Animates from each property's last value |
289
+ | `set(target, values)` | Changes at once |
290
+ | `wait(ms)` | Moves the cursor forward |
291
+ | `together(() => …)` | Starts several steps at the same moment |
292
+ | `marker(id, { label, pause, question, captions })` | Adds a named step at the cursor |
293
+ | `initial(target, values)` | Sets starting values |
294
+
295
+ **Primitives return SVG markup, geometry, and step helpers that write to a lesson:**
296
+
297
+ | Primitive | Helpers |
298
+ |---|---|
299
+ | `cells` (array / slice) | `write(l, i, value)`, `highlight(l, i, colour)`, `center(i)` |
300
+ | `pointer` | `moveTo(l, x)` |
301
+ | `stack` (call frames) | `push(l, label)`, `pop(l)` |
302
+ | `queue` (queue / channel) | `send(l, label)`, `receive(l)` |
303
+ | `table` (map / buckets) | `put(l, key, value)` |
304
+ | `pipeline` (middleware, stages) | `advance(l, stage)` |
305
+
306
+ They run anywhere: in a browser, or in Node while a static site builds.
307
+
308
+ ## In build pipelines
309
+
310
+ ```bash
311
+ npx @algorisys/tinyfly validate append.json --markup append.svg
312
+ npx @algorisys/tinyfly render append.json append.svg --at end > append-final.svg
313
+ npx @algorisys/tinyfly render append.json append.svg --at full > append-question.svg
314
+ ```
315
+
316
+ Pass every scenario's timeline to check a scenario figure. Each is named by its
317
+ `id`:
318
+
319
+ ```bash
320
+ npx @algorisys/tinyfly validate no-cache.json cache.json --markup cache-figure.svg
321
+ ```
322
+
323
+ **`validate`** exits with code 1 when:
324
+
325
+ - a track targets a `data-tinyfly` name the markup lacks;
326
+ - a marker is out of order, duplicated or outside the animation;
327
+ - a keyframe comes after an explicit duration;
328
+ - a caption names an unknown marker;
329
+ - with several timelines: two share an id, or a `data-tinyfly-choose` names no
330
+ scenario. Each timeline's problems are prefixed with its id.
331
+
332
+ It also warns about markers missing a caption in some language, and elements that
333
+ are never animated.
334
+
335
+ **`render`** writes the state at `start`, `end`, a time in ms, or a marker id into
336
+ each animated element's `style` and text. The result is a static figure for RSS
337
+ readers, email, print, AMP and Open Graph images. The same functions are exported as
338
+ `validateEmbed` and `renderFrame` from `@algorisys/tinyfly/embed`.
339
+
340
+ ## Format version
341
+
342
+ Timeline JSON carries `"formatVersion": 1`. A tinyfly that finds a newer version
343
+ refuses to play it, with an error saying to update, rather than playing it wrongly.
344
+
345
+ - **Additions:** new optional fields, such as markers and captions, do not change the
346
+ version, so figures written today keep playing on later releases.
347
+ - **Breaking changes:** a change that would make an old player misread a file bumps
348
+ the version and is announced in the release notes.