@algorisys/tinyfly 0.92.0 → 0.94.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.
- package/README.md +7 -6
- package/bin/tinyfly.mjs +34 -1
- package/docs/2d-animation-roadmap.md +191 -0
- package/docs/3d-rotations.md +164 -0
- package/docs/3d-support-plan.md +628 -0
- package/docs/DEPLOYMENT.md +414 -0
- package/docs/acting.md +529 -0
- package/docs/api-reference.md +2353 -0
- package/docs/camera.md +94 -0
- package/docs/cartoon-hands.md +96 -0
- package/docs/character-system-m1.md +218 -0
- package/docs/character-system-plan.md +384 -0
- package/docs/dance.md +315 -0
- package/docs/editor-guide.md +1249 -0
- package/docs/examples.md +765 -0
- package/docs/extending.md +168 -0
- package/docs/file-format.md +690 -0
- package/docs/getting-started.md +314 -0
- package/docs/grid-and-snapping.md +64 -0
- package/docs/gsap-compat.md +1241 -0
- package/docs/llm-guide.md +131 -0
- package/docs/maps.md +116 -0
- package/docs/onion-skinning.md +41 -0
- package/docs/pen-tool.md +65 -0
- package/docs/polygon-star.md +44 -0
- package/docs/scene-3d.md +299 -0
- package/docs/scroll-animation.md +314 -0
- package/docs/shape-morph.md +61 -0
- package/docs/sprite-sheet-export.md +54 -0
- package/docs/symbols-and-library.md +137 -0
- package/docs/teaching.md +348 -0
- package/docs/video-rendering.md +728 -0
- package/lib/addons/adapters.js +22 -18
- package/lib/addons/characters.js +3045 -2024
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6968 -5817
- package/lib/browser/tinyfly.umd.js +9 -4
- package/lib/engine/tinyfly-engine.js +286 -258
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
- package/lib/types/characters/acting/beat-check.d.ts +102 -0
- package/lib/types/characters/acting/custom.d.ts +66 -0
- package/lib/types/characters/acting/gags.d.ts +10 -0
- package/lib/types/characters/acting/hand-path.d.ts +35 -0
- package/lib/types/characters/acting/index.d.ts +4 -0
- package/lib/types/characters/acting/persona.d.ts +93 -0
- package/lib/types/characters/acting/script.d.ts +75 -11
- package/lib/types/characters/capabilities.d.ts +61 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +12 -0
- package/lib/types/characters/figure-props.d.ts +87 -0
- package/lib/types/characters/gaits.d.ts +8 -0
- package/lib/types/characters/index.d.ts +3 -0
- package/lib/types/characters/stick-figure.d.ts +9 -2
- package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/llms-full.txt +12631 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +67 -0
- 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.
|
package/docs/teaching.md
ADDED
|
@@ -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.94.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.
|