@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.
Files changed (64) 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 +529 -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 +131 -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 +3045 -2024
  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 +6968 -5817
  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 +102 -0
  45. package/lib/types/characters/acting/custom.d.ts +66 -0
  46. package/lib/types/characters/acting/gags.d.ts +10 -0
  47. package/lib/types/characters/acting/hand-path.d.ts +35 -0
  48. package/lib/types/characters/acting/index.d.ts +4 -0
  49. package/lib/types/characters/acting/persona.d.ts +93 -0
  50. package/lib/types/characters/acting/script.d.ts +75 -11
  51. package/lib/types/characters/capabilities.d.ts +61 -0
  52. package/lib/types/characters/code-panel.d.ts +201 -0
  53. package/lib/types/characters/figure-actions.d.ts +12 -0
  54. package/lib/types/characters/figure-props.d.ts +87 -0
  55. package/lib/types/characters/gaits.d.ts +8 -0
  56. package/lib/types/characters/index.d.ts +3 -0
  57. package/lib/types/characters/stick-figure.d.ts +9 -2
  58. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  59. package/lib/types/engine/authoring/index.d.ts +1 -0
  60. package/llms-full.txt +12631 -0
  61. package/llms.txt +57 -0
  62. package/package.json +6 -2
  63. package/skills/tinyfly/SKILL.md +67 -0
  64. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,690 @@
1
+ # tinyfly File Format
2
+
3
+ tinyfly animations are **plain JSON** — no binary blobs, no framework-specific
4
+ wrappers. This document is the reference for anyone generating, consuming, or
5
+ integrating tinyfly animations (tooling, AI generation, importers/exporters,
6
+ custom players).
7
+
8
+ Everything here is stable, serializable data. The same JSON plays in the
9
+ browser, a Web Worker, or any headless JS runtime, and always produces the same
10
+ output for the same input (see [Determinism](#determinism)).
11
+
12
+ ---
13
+
14
+ ## The formats at a glance
15
+
16
+ tinyfly has a few related JSON shapes. Pick the one that matches your task:
17
+
18
+ | Format | Shape | Use it for |
19
+ |--------|-------|------------|
20
+ | **Animation Document** | `{ duration, canvas?, elements[], tracks[] }` | **The integration format.** Author or generate animations by hand/AI. Loaded the same way samples are. |
21
+ | **Timeline Definition** | `{ id, name?, config, tracks[] }` | The engine's serialized timeline (`serializeTimeline()` / `toJSON()`, and the `.json` files the editor exports & imports). What a custom player consumes. |
22
+ | **Project** | `{ id, name, canvas, scenes[], symbols[], ... }` | The editor's saved document — one or more scenes, each with its own elements + timeline, plus a symbol library. |
23
+ | **Sequence** | `{ id, name, canvas, scenes[], symbols? }` | A multi-scene bundle for the embeddable player/sequencer. |
24
+
25
+ If you're integrating with tinyfly, start with the **Animation Document** — it's
26
+ the highest-level, most stable shape and describes *what to draw* as well as
27
+ *how to animate it*.
28
+
29
+ ---
30
+
31
+ ## 1. Animation Document
32
+
33
+ The document a sample, an AI generation, or a hand-authored animation uses. It
34
+ describes a set of **elements** (the things on the artboard) and **tracks** (how
35
+ their properties change over time).
36
+
37
+ ```jsonc
38
+ {
39
+ "duration": 2000, // total length in ms (required, > 0)
40
+ "canvas": { "width": 300, "height": 200 }, // optional artboard size
41
+ "elements": [ /* Element[] */ ], // what to draw
42
+ "tracks": [ /* Track[] */ ] // how to animate it
43
+ }
44
+ ```
45
+
46
+ - `duration` — **required**, milliseconds, must be `> 0`. The timeline can
47
+ auto-extend to fit tracks, but always declare the intended length.
48
+ - `canvas` — optional `{ width, height }` in px. When present, loading the
49
+ document resizes the artboard (e.g. a vertical `360×640` promo). Defaults to
50
+ the current/host canvas.
51
+ - `elements` — array of [Elements](#elements).
52
+ - `tracks` — array of [Tracks](#tracks-and-keyframes). A track's `target` matches
53
+ an **element `name`** (see below).
54
+
55
+ The editor writes one with **More → Export Animation Document** (`*.animation.json`).
56
+ Besides the fields above it adds `name`, playback options other than duration
57
+ under `config` (`loop`, `speed`, `markers`…), `captions` when present, and keeps
58
+ each element's `id` (groups refer to their children by id). Its tracks are the
59
+ editor's tracks unchanged, so springs, staggers and scheduling fields survive for
60
+ a reader that runs the engine; the editor's own loader reads the subset in
61
+ [Track kinds](#track-kinds-in-an-animation-document).
62
+
63
+ > **Key rule:** in the Animation Document, tracks bind to elements by **`name`**,
64
+ > not `id`. Element `id`s are assigned by the editor on load; names are what you
65
+ > author against. Every `track.target` must equal some `element.name`.
66
+
67
+ ### Minimal example
68
+
69
+ ```json
70
+ {
71
+ "duration": 2000,
72
+ "canvas": { "width": 300, "height": 200 },
73
+ "elements": [
74
+ { "type": "rect", "name": "Box", "x": 120, "y": 70, "width": 60, "height": 60, "fill": "#4a9eff", "borderRadius": 8 }
75
+ ],
76
+ "tracks": [
77
+ {
78
+ "target": "Box",
79
+ "property": "opacity",
80
+ "keyframes": [
81
+ { "time": 0, "value": 0 },
82
+ { "time": 500, "value": 1, "easing": "ease-out" },
83
+ { "time": 1500, "value": 1 },
84
+ { "time": 2000, "value": 0, "easing": "ease-in" }
85
+ ]
86
+ }
87
+ ]
88
+ }
89
+ ```
90
+
91
+ ---
92
+
93
+ ## Elements
94
+
95
+ Every element shares a **base** shape and adds a few fields per `type`. When
96
+ authoring a document, most base fields are optional and are filled with sensible
97
+ defaults — but `type` and `name` should always be set (`name` is how tracks find
98
+ it). Coordinates are in artboard pixels; the origin is the top-left.
99
+
100
+ ### Base fields (all element types)
101
+
102
+ | Field | Type | Notes |
103
+ |-------|------|-------|
104
+ | `type` | string | One of the element types below. **Required.** |
105
+ | `name` | string | Human-readable id used as a track `target`. **Required for animation.** |
106
+ | `x`, `y` | number | Top-left position in px. |
107
+ | `width`, `height` | number | Size in px. |
108
+ | `rotation` | number | Degrees. |
109
+ | `opacity` | number | `0`–`1`. |
110
+ | `visible` | boolean | Hidden elements are skipped in render/export. |
111
+ | `locked` | boolean | Editor-only (not selectable); no runtime effect. |
112
+ | `id` | string | Assigned by the editor. Omit when authoring. |
113
+
114
+ ### Element types & their extra fields
115
+
116
+ | `type` | Extra fields |
117
+ |--------|--------------|
118
+ | `rect` | `fill` (color or [gradient](#fills--gradients)), `stroke`, `strokeWidth`, `borderRadius` |
119
+ | `circle` | `fill`, `stroke`, `strokeWidth` |
120
+ | `text` | `text` (string), `fontSize`, `fontFamily`, `fontWeight`, `fill`, `textAlign` (`left`\|`center`\|`right`) |
121
+ | `image` | `src` (URL or data URI), `objectFit` (`contain`\|`cover`\|`fill`) |
122
+ | `video` | `src`, `objectFit`, `borderRadius`, `volume` (0–1), `muted`, `loop`, `startTime` (ms) |
123
+ | `audio` | `src`, `volume` (0–1), `muted`, `loop`, `startTime` (ms) |
124
+ | `line` | `x2`, `y2`, `stroke`, `strokeWidth`, `lineCap` (`butt`\|`round`\|`square`) |
125
+ | `arrow` | `x2`, `y2`, `stroke`, `strokeWidth`, `headSize`, `startHead` (bool), `endHead` (bool) |
126
+ | `path` | `d` (SVG path data), `fill`, `stroke`, `strokeWidth`, `lineCap`, `lineJoin` (`miter`\|`round`\|`bevel`), `closed` (bool), `shape` (optional `{ kind: 'polygon'\|'star', points, innerRatio? }` — a parametric polygon/star whose `d` is regenerated from the spec and the element's size; see [polygon-star.md](polygon-star.md)) |
127
+ | `group` | `childIds` (string[]) — ids of grouped elements |
128
+ | `symbol` | `symbolId` (id of a symbol in the Project's `symbols` library), `swapSet` (optional string[] of symbol ids; a `swapIndex` track picks `swapSet[floor(swapIndex)]`), `overrides` (reserved). Only meaningful inside a [Project](#3-project-format), which carries the library — see [symbols-and-library.md](symbols-and-library.md) |
129
+
130
+ ### Fills & gradients
131
+
132
+ `fill` (on `rect`, `circle`, `path`) is either a CSS color string
133
+ (`"#4a9eff"`, `"rgba(...)"`) **or** a gradient object:
134
+
135
+ ```jsonc
136
+ // Linear gradient — angle in degrees (0 = left→right, 90 = top→bottom)
137
+ {
138
+ "type": "linear",
139
+ "angle": 90,
140
+ "stops": [ { "offset": 0, "color": "#4a9eff" }, { "offset": 1, "color": "#9b59b6" } ]
141
+ }
142
+
143
+ // Radial gradient — center/radius are 0–1, relative to the element box
144
+ {
145
+ "type": "radial",
146
+ "centerX": 0.5,
147
+ "centerY": 0.5,
148
+ "radius": 0.5,
149
+ "stops": [ { "offset": 0, "color": "#fff" }, { "offset": 1, "color": "#000" } ]
150
+ }
151
+ ```
152
+
153
+ `stops[].offset` is `0`–`1`; `angle` is in degrees; `centerX`/`centerY`/`radius`
154
+ are fractions of the element box (`0`–`1`).
155
+
156
+ ---
157
+
158
+ ## Tracks and keyframes
159
+
160
+ A **track** animates one property of one target over time.
161
+
162
+ ```jsonc
163
+ {
164
+ "id": "opacity-1", // optional in a document; the editor assigns one
165
+ "target": "Box", // MUST match an element `name`
166
+ "property": "opacity", // see the animatable-properties table
167
+ "keyframes": [
168
+ { "time": 0, "value": 0 },
169
+ { "time": 500, "value": 1, "easing": "ease-out" }
170
+ ]
171
+ }
172
+ ```
173
+
174
+ - `target` — the element `name` to animate (in the engine Timeline format this
175
+ is the element **id** instead — see [Timeline Definition](#2-timeline-definition)).
176
+ - `property` — the property to animate (below).
177
+ - `keyframes` — **sorted by `time`** (ascending), each:
178
+ - `time` — milliseconds from the timeline start.
179
+ - `value` — a number, a string (colour or path data), or a number array,
180
+ depending on the property (an [AnimatableValue](#value-types)).
181
+ - `easing` — optional; the curve used interpolating **into** this keyframe.
182
+ Defaults to `linear`.
183
+
184
+ ### Value types
185
+
186
+ `value` is one of:
187
+
188
+ - **number** — e.g. `x`, `opacity`, `scale`, `rotate`, `width`.
189
+ - **color string** — e.g. `fill`, `stroke` (`"#ff0000"`, `"rgb(...)"`).
190
+ Interpolated channel-by-channel.
191
+ - **path string** — SVG path data starting with a moveto (`"M0 0 L10 10"`),
192
+ e.g. on a `d` track. Morphed point-by-point between keyframes, so any two
193
+ shapes blend — see [shape-morph.md](shape-morph.md).
194
+ - **other strings** — not interpolated: the value jumps to the next keyframe's
195
+ string when that keyframe is reached. To animate text, use a
196
+ [text track](#text-tracks).
197
+ - **number[]** — for array-valued properties.
198
+
199
+ Between two keyframes, the earlier keyframe's value decides the interpolator: a
200
+ number, an array, a string starting with `#` or `rgb` (colour), a path string,
201
+ or any other string (discrete).
202
+
203
+ ### Animatable properties
204
+
205
+ | Category | Properties |
206
+ |----------|-----------|
207
+ | Position | `x`, `y`, `z` |
208
+ | Transform | `rotate`, `rotateX`, `rotateY`, `rotateZ`, `scale`, `scaleX`, `scaleY`, `scaleZ`, `skewX`, `skewY` |
209
+ | Appearance | `opacity`, `fill`, `stroke`, `strokeWidth`, `width`, `height`, `borderRadius`, `fontSize` |
210
+ | Shape | `d` (path string — morphs the path's shape) |
211
+ | Text | `text` (via a [text track](#text-tracks)) |
212
+ | Clip / reveal | `clipTop`, `clipRight`, `clipBottom`, `clipLeft` (inset %, `0` = fully shown, `100` = fully clipped from that edge) |
213
+ | Filters | `blur`, `glow`, `dropShadow` |
214
+ | Stroke draw-on | `strokeDasharray`, `strokeDashoffset` |
215
+ | Shine | `shine` (0–1 sweep position) |
216
+ | Motion path | `motionPathX`, `motionPathY`, `motionPathRotate` (usually via a motion-path track — below) |
217
+
218
+ Adapters ignore properties that don't apply to a given render target, so an
219
+ unknown/unsupported property is a no-op, never an error.
220
+
221
+ ### Easing values
222
+
223
+ `easing` is either a **built-in name**:
224
+
225
+ ```
226
+ linear
227
+ ease-in ease-out ease-in-out
228
+ ease-in-quad ease-out-quad ease-in-out-quad
229
+ ease-in-cubic ease-out-cubic ease-in-out-cubic
230
+ ```
231
+
232
+ …or a **custom cubic-bezier**:
233
+
234
+ ```json
235
+ { "type": "cubic-bezier", "points": [0.68, -0.55, 0.27, 1.55] }
236
+ ```
237
+
238
+ `points` are `[cp1x, cp1y, cp2x, cp2y]` (CSS `cubic-bezier` order).
239
+
240
+ …or a **parametric ease**, evaluated exactly when played:
241
+
242
+ ```jsonc
243
+ { "type": "elastic", "mode": "out", "amplitude": 1, "period": 0.3 } // overshoots and oscillates
244
+ { "type": "bounce", "mode": "out" } // rebounds off the end
245
+ { "type": "back", "mode": "out", "overshoot": 1.70158 } // goes past, then settles
246
+ { "type": "steps", "count": 5, "position": "end" } // holds, then jumps
247
+ ```
248
+
249
+ `mode` is `"in"`, `"out"` (default) or `"in-out"`. `position` follows CSS
250
+ `steps()`: `"end"` (default), `"start"`, `"none"` (hold both ends) or `"both"`.
251
+ CSS and Lottie exports sample these into keyframes.
252
+
253
+ ### Motion-path tracks
254
+
255
+ A track can animate an element **along an SVG path** instead of listing X/Y
256
+ keyframes. Its `property` is the literal `"motionPath"` and it carries a
257
+ `motionPathConfig`:
258
+
259
+ ```jsonc
260
+ {
261
+ "target": "Ball",
262
+ "property": "motionPath",
263
+ "motionPathConfig": {
264
+ "pathData": "M0,0 C50,-80 150,-80 200,0", // SVG `d`
265
+ "autoRotate": true, // face the path tangent
266
+ "rotateOffset": 0, // degrees added when autoRotate
267
+ "matrix": [1, 0, 0, 1, 40, 20] // optional affine transform
268
+ },
269
+ "keyframes": [
270
+ { "time": 0, "value": 0 }, // progress 0..1 along the path
271
+ { "time": 2000, "value": 1, "easing": "ease-in-out" }
272
+ ]
273
+ }
274
+ ```
275
+
276
+ Keyframe `value`s are **progress** along the path (`0`–`1`), measured by arc
277
+ length. The timeline expands progress into `motionPathX`, `motionPathY` and
278
+ (with `autoRotate`) `motionPathRotate`.
279
+
280
+ `matrix` is an optional affine transform `[a, b, c, d, e, f]` applied to every
281
+ point on the path and to its tangent: `x' = a·x + c·y + e`, `y' = b·x + d·y + f`.
282
+ It places a path drawn in one coordinate space (an SVG's user units) into the
283
+ follower's space. Omit it for identity. `live`'s `motionPath` `align` option
284
+ writes it — see [gsap-compat.md](gsap-compat.md#motion-paths).
285
+
286
+ ### Text tracks
287
+
288
+ A track whose `property` is the literal `"text"` types or scrambles from one
289
+ string to another. Like a motion path, its keyframes carry **progress**
290
+ (`0`–`1`) with easing, and `textConfig` says what the progress means:
291
+
292
+ ```jsonc
293
+ {
294
+ "id": "title-text",
295
+ "target": "Title",
296
+ "property": "text",
297
+ "textConfig": {
298
+ "from": "LOADING", // text at progress 0 (default "")
299
+ "to": "TINYFLY", // text at progress 1 (required)
300
+ "mode": "scramble", // "type" | "scramble" (required)
301
+ "chars": "upperCase", // scramble: upperCase | lowerCase | upperAndLowerCase | numbers | your own characters
302
+ "revealDelay": 0.3, // scramble: fraction of the tween before characters settle
303
+ "seed": 7 // scramble: fixes the random characters
304
+ },
305
+ "keyframes": [
306
+ { "time": 0, "value": 0 },
307
+ { "time": 1200, "value": 1, "easing": "ease-out" }
308
+ ]
309
+ }
310
+ ```
311
+
312
+ Other `textConfig` fields: `refreshRate` (scramble: random-character changes
313
+ per second, default `20`), `tweenLength` (scramble: grow or shrink the length
314
+ over the tween, default `true`), `rightToLeft` (reveal from the end). The
315
+ timeline turns progress into a `text` value; adapters set it as the element's
316
+ text. Scramble characters come from a hash of the seed, position and refresh
317
+ step, so the string at any time is always the same.
318
+
319
+ ### Spring tracks
320
+
321
+ A track with `"kind": "spring"` has no keyframes. Its values come from a
322
+ spring simulation, integrated at a fixed step from `t = 0`, so it is still a pure
323
+ function of time. The track stores the parameters, not a baked curve:
324
+
325
+ ```jsonc
326
+ {
327
+ "id": "pop",
328
+ "target": "Box",
329
+ "property": "scale",
330
+ "kind": "spring",
331
+ "spring": {
332
+ "from": 0, // required
333
+ "to": 1, // required: resting value
334
+ "stiffness": 180, // default 180 — higher is snappier
335
+ "damping": 12, // default 12 — higher settles sooner, 0 oscillates forever
336
+ "mass": 1, // default 1
337
+ "velocity": 0, // default 0, units per second
338
+ "restDelta": 0.01, // default 0.01, fraction of the travel distance
339
+ "restSpeed": 0.1 // default 0.1, fraction of the travel distance per second
340
+ },
341
+ "delay": 200
342
+ }
343
+ ```
344
+
345
+ A spring decides its own duration: the time until it settles, plus `delay`.
346
+
347
+ ### Inertia tracks
348
+
349
+ A track with `"kind": "inertia"` is a throw: a value released with a velocity
350
+ that slows under friction and comes to rest. It has no keyframes; the motion is
351
+ a closed-form function of time.
352
+
353
+ ```jsonc
354
+ {
355
+ "id": "puck-x",
356
+ "target": "Puck",
357
+ "property": "x",
358
+ "kind": "inertia",
359
+ "inertia": {
360
+ "from": 0, // required: value at release
361
+ "velocity": 900, // required: units per second (negative moves down)
362
+ "friction": 4, // default 4 — exponential decay rate per second
363
+ "min": 0, // optional lowest resting value
364
+ "max": 240, // optional highest resting value
365
+ "end": 120 // optional: a number snaps to multiples of it; an array snaps to the nearest listed value
366
+ },
367
+ "delay": 200
368
+ }
369
+ ```
370
+
371
+ `restDelta` (optional) sets how close to the resting value counts as settled;
372
+ by default it scales with the distance travelled. Like a spring, an inertia
373
+ track decides its own duration.
374
+
375
+ ### Rotation tracks (`interpolation: "slerp"`)
376
+
377
+ A keyframe track may say how its values blend. Its one mode today, `"slerp"`,
378
+ marks the values as rotations: `[x, y, z, w]` quaternions, turned the short way
379
+ round at a steady speed (spherical interpolation). Easing shapes the turn as it
380
+ shapes any other value.
381
+
382
+ ```json
383
+ {
384
+ "id": "turn",
385
+ "target": "cube",
386
+ "property": "quaternion",
387
+ "interpolation": "slerp",
388
+ "keyframes": [
389
+ { "time": 0, "value": [0, 0, 0, 1] },
390
+ { "time": 2000, "value": [0, 1, 0, 0], "easing": "ease-in-out" }
391
+ ]
392
+ }
393
+ ```
394
+
395
+ It is data, not guessed: a 4-number array without it blends element-wise, as
396
+ arrays always have. A file that uses it is written as `formatVersion: 2`, so
397
+ older readers refuse it instead of playing the rotation wrongly; files that do
398
+ not stay at version 1. The DOM adapter draws a `quaternion` value as a CSS
399
+ `matrix3d()`. See [3D rotations](3d-rotations.md).
400
+
401
+ ### Track scheduling
402
+
403
+ Every track kind accepts these optional fields. They are omitted from the JSON
404
+ when unset.
405
+
406
+ | Field | Type | Meaning |
407
+ |-------|------|---------|
408
+ | `delay` | number (ms) | Shift the whole track later. `"delay": 200` is the same as adding 200 to every keyframe's `time`. |
409
+ | `endDelay` | number (ms) | Extra time held after the last keyframe. Extends the track's (and so the timeline's) duration without changing its final value. Keyframe and text tracks only. |
410
+ | `targets` | string[] | Drive several targets from this one track. When present, `target` is ignored. |
411
+ | `stagger` | `{ each?, amount?, from?, offsets? }` | Offsets each of `targets` in time. Ignored without `targets`. |
412
+
413
+ `stagger` fields:
414
+
415
+ - `each` — ms between consecutive targets.
416
+ - `amount` — total spread in ms, divided across the targets. Wins over `each`.
417
+ - `from` — which target starts first: `"start"` (default), `"end"`,
418
+ `"center"`, `"edges"`, or a target index.
419
+ - `offsets` — explicit ms per target, in order, for layouts no 1D fan describes
420
+ (grids, random order). Wins over the other fields.
421
+
422
+ With neither `each` nor `amount`, every offset is `0`.
423
+
424
+ ```jsonc
425
+ {
426
+ "id": "letters-in",
427
+ "target": "l1",
428
+ "targets": ["l1", "l2", "l3", "l4"],
429
+ "stagger": { "each": 80, "from": "center" },
430
+ "property": "opacity",
431
+ "keyframes": [
432
+ { "time": 0, "value": 0 },
433
+ { "time": 400, "value": 1, "easing": "ease-out" }
434
+ ],
435
+ "delay": 100
436
+ }
437
+ ```
438
+
439
+ When several tracks drive the same target and property, the value comes from
440
+ the one that started most recently (its first keyframe plus delay and stagger).
441
+ Ties go to the track listed later.
442
+
443
+ ### Track kinds in an Animation Document
444
+
445
+ The editor loads an Animation Document's tracks through its own authoring
446
+ actions, so it reads only part of each track kind:
447
+
448
+ | Track | What the loader keeps |
449
+ |-------|-----------------------|
450
+ | Keyframe | `target`, `property`, `keyframes`. Scheduling fields are dropped. |
451
+ | Motion path | `pathData`, `autoRotate`, `rotateOffset`. Start and end time come from the first and last keyframes, easing from the last. `matrix` and middle keyframes are dropped. |
452
+ | Text | `textConfig`. Start and end time come from the first and last keyframes, easing from the last. |
453
+ | Inertia | `inertia` and `delay` |
454
+ | Spring | Not supported. Add springs in the editor, or use a [Timeline Definition](#2-timeline-definition). |
455
+
456
+ The engine itself reads every field above. Put springs, `matrix`, `targets` and
457
+ `stagger` in a Timeline Definition.
458
+
459
+ ---
460
+
461
+ ## 2. Timeline Definition
462
+
463
+ The engine's serialized timeline — what `serializeTimeline(timeline)` (or
464
+ `toJSON(timeline)` for a string) produces, what `deserializeTimeline()` /
465
+ `fromJSON()` / the standalone player consume, and the shape of the `.json` files
466
+ the editor's JSON export and import write and read.
467
+
468
+ ```ts
469
+ import { serializeTimeline, toJSON, fromJSON } from '@algorisys/tinyfly'
470
+
471
+ const definition = serializeTimeline(timeline) // TimelineDefinition object
472
+ const json = toJSON(timeline) // the same, as a string
473
+ const restored = fromJSON(json) // back to a Timeline
474
+ ```
475
+
476
+ `timeline.toDefinition()` returns the same shape without copying: its `config`
477
+ is exactly what the timeline was built with and its `tracks` are the live track
478
+ objects. Use `serializeTimeline` when you need a detached copy.
479
+
480
+ ```jsonc
481
+ {
482
+ "formatVersion": 1, // optional; absent means 1 (2 when a track uses slerp)
483
+ "id": "scene-1",
484
+ "name": "My Animation", // optional
485
+ "config": {
486
+ "duration": 2000, // ms; omit to auto-derive from tracks
487
+ "loop": 0, // 0 = play once, -1 = infinite, N = repeat N more times
488
+ "speed": 1, // playback multiplier
489
+ "alternate": false, // ping-pong direction each loop
490
+ "repeatDelay": 500, // ms to wait between loop iterations
491
+ "drawingRate": 12, // optional: drawings per second (12 = on twos); values hold between drawings
492
+ "markers": [ // optional named steps, in time order
493
+ { "id": "full", "time": 1400, "label": "cap is full", "pause": true, "question": "What happens next?" }
494
+ ]
495
+ },
496
+ "captions": { // optional: per language, per marker id
497
+ "es": { "full": "la capacidad está llena" }
498
+ },
499
+ "tracks": [
500
+ {
501
+ "id": "track-1",
502
+ "target": "box", // element id (see note)
503
+ "property": "opacity",
504
+ "keyframes": [
505
+ { "time": 0, "value": 0 },
506
+ { "time": 1000, "value": 1, "easing": "ease-out" }
507
+ ]
508
+ }
509
+ ]
510
+ }
511
+ ```
512
+
513
+ Differences from the Animation Document:
514
+
515
+ - It is **timeline-only** — no `elements`. The engine animates *targets*;
516
+ something else (a DOM/Canvas/SVG adapter) owns the actual objects and maps
517
+ `target` → real element.
518
+ - `target` here is whatever key you registered with the adapter — in editor
519
+ exports that's the element **id**; in a hand-wired integration it's your own
520
+ key (e.g. `adapter.registerTarget("box", el)`).
521
+ - Playback options live under `config`.
522
+ - `tracks` may mix every track kind: keyframe, [motion-path](#motion-path-tracks),
523
+ [text](#text-tracks), [spring](#spring-tracks) and [inertia](#inertia-tracks),
524
+ each with the [scheduling fields](#track-scheduling).
525
+
526
+ **Markers** name steps: players step between them, stop at `pause` markers and
527
+ show `question`s. **Captions** translate marker labels without touching the tracks.
528
+ See [Teaching animations](teaching.md).
529
+
530
+ **`formatVersion`** is the format a file was written for. Readers refuse a newer
531
+ version with a clear error. Optional additions keep the version; a change an older
532
+ reader would misread bumps it. Writers use the lowest version a file needs:
533
+
534
+ | Version | Adds |
535
+ |---|---|
536
+ | 1 | the original format |
537
+ | 2 | [`interpolation: "slerp"`](#rotation-tracks-interpolation-slerp) on keyframe tracks |
538
+
539
+ `repeatDelay` applies when the timeline loops (`loop` is not `0`). Going
540
+ forward, the playhead **holds the last frame** for the delay, then wraps to the
541
+ start. With `alternate`, it holds at whichever end it reached before turning
542
+ round. The delay is consumed at the timeline's `speed`, and a `seek()` cancels a
543
+ pending delay.
544
+
545
+ ### Consuming a Timeline (custom integration)
546
+
547
+ ```ts
548
+ import { deserializeTimeline } from '@algorisys/tinyfly'
549
+ import { DOMAdapter } from '@algorisys/tinyfly/adapters'
550
+
551
+ const timeline = deserializeTimeline(json) // json = Timeline Definition
552
+ const adapter = new DOMAdapter()
553
+ adapter.registerTarget('box', document.querySelector('#box'))
554
+
555
+ function frame(dt) {
556
+ timeline.tick(dt) // advance by dt ms
557
+ adapter.applyState(timeline.getStateAtTime(timeline.currentTime))
558
+ requestAnimationFrame(() => frame(16.67))
559
+ }
560
+ timeline.play()
561
+ frame(16.67)
562
+ ```
563
+
564
+ Or skip the wiring entirely with the bundled player (`TinyflyPlayer`) — see the
565
+ [API reference](api-reference.md) and [Getting Started](getting-started.md).
566
+
567
+ ---
568
+
569
+ ## 3. Project format
570
+
571
+ The editor's saved document (in IndexedDB, and what you'd export to move a whole
572
+ project). One project holds one or more **scenes**, each with its own elements
573
+ and timeline.
574
+
575
+ ```jsonc
576
+ {
577
+ "id": "project-…",
578
+ "name": "Untitled Animation",
579
+ "created": 1750000000000, // epoch ms
580
+ "modified": 1750000000000,
581
+ "canvas": { "width": 300, "height": 200, "background": "#252525" },
582
+ "activeSceneId": "scene-…",
583
+ "scenes": [
584
+ {
585
+ "id": "scene-…",
586
+ "name": "Scene 1",
587
+ "order": 0,
588
+ "elements": [ /* Element[] (with ids) */ ],
589
+ "timeline": { /* Timeline Definition | null */ },
590
+ "transition": { "type": "fade", "duration": 400 } // optional
591
+ }
592
+ ],
593
+ "symbols": [ // the Library, shared across scenes
594
+ {
595
+ "id": "symbol-…",
596
+ "name": "Mouth",
597
+ "width": 120, "height": 80, // intrinsic size; instances scale from it
598
+ "elements": [ /* Element[] */ ],
599
+ "timeline": { /* Timeline Definition | null */ },
600
+ "created": 1750000000000,
601
+ "modified": 1750000000000
602
+ }
603
+ ]
604
+ }
605
+ ```
606
+
607
+ - `canvas.background` is a CSS color; also the default background for raster
608
+ exports.
609
+ - `scene.timeline` is a full [Timeline Definition](#2-timeline-definition) (or
610
+ `null` for an empty scene). Here the timeline `target`s are element **ids**.
611
+ - `scene.transition.type` is one of `none`, `fade`, `slide-left`,
612
+ `slide-right`, `slide-up`, `slide-down`.
613
+ - `symbols` holds reusable symbol definitions. A `symbol` element points at one
614
+ by `symbolId`; the symbol's own `timeline` plays inside each instance. Projects
615
+ saved before symbols existed load with an empty list.
616
+
617
+ ---
618
+
619
+ ## 4. Sequence format
620
+
621
+ A flattened, self-contained bundle for the embeddable multi-scene player
622
+ (`TinyflySequencer`). Each scene carries pre-rendered element HTML so the player
623
+ needs no editor code.
624
+
625
+ ```jsonc
626
+ {
627
+ "id": "project-…",
628
+ "name": "My Promo",
629
+ "canvas": { "width": 360, "height": 640, "background": "#111" },
630
+ "scenes": [
631
+ {
632
+ "id": "scene-…",
633
+ "name": "Scene 1",
634
+ "elements": [
635
+ { "type": "rect", "name": "Box", "x": 0, "y": 0, "width": 60, "height": 60,
636
+ "rotation": 0, "opacity": 1, "html": "<div …></div>" }
637
+ ],
638
+ "timeline": { /* Timeline Definition */ },
639
+ "transition": { "type": "fade", "duration": 400 }
640
+ }
641
+ ],
642
+ "loop": 0, // optional: -1 = infinite, 0 = no loop, N = N times
643
+ "symbols": [ // optional: nested timelines for symbol instances
644
+ { "id": "symbol-…", "timeline": { /* Timeline Definition */ } }
645
+ ]
646
+ }
647
+ ```
648
+
649
+ `symbols` lists only symbols that are used in a scene and have a non-empty
650
+ timeline. The sequencer animates each instance's inner elements (tagged
651
+ `data-tinyfly-symbol`) from the matching timeline.
652
+
653
+ This is what the editor's **Embed → All Scenes** option emits. For a single
654
+ scene, embedding emits a plain [Timeline Definition](#2-timeline-definition)
655
+ plus its element HTML.
656
+
657
+ ---
658
+
659
+ ## Determinism
660
+
661
+ tinyfly guarantees **same input → same output**:
662
+
663
+ - All timing is explicit and in **milliseconds**. The engine advances by the
664
+ `dt` you feed `tick(dt)`; it never reads wall-clock time itself.
665
+ - Interpolation and easing are pure functions of `(from, to, progress)`.
666
+ - No implicit browser or global state affects the produced values.
667
+
668
+ So a document rendered at 30fps, 60fps, or frame-stepped for export yields the
669
+ same values at the same timeline times — which is why GIF/WebP/MP4 export is
670
+ reproducible.
671
+
672
+ ---
673
+
674
+ ## Versioning & forward-compatibility
675
+
676
+ - Unknown **element fields** and unknown **animatable properties** are ignored by
677
+ adapters, not rejected — older players tolerate newer documents' extras.
678
+ - Older documents are migrated on load (e.g. a pre-scenes project is wrapped into
679
+ a single scene; a missing `canvas.background` picks up the default).
680
+ - There is no explicit format-version field today; the shapes above are additive.
681
+ Treat missing optional fields as their documented defaults.
682
+
683
+ ---
684
+
685
+ ## See also
686
+
687
+ - [Getting Started](getting-started.md) — install and play your first animation.
688
+ - [API Reference](api-reference.md) — `Timeline`, adapters, `TinyflyPlayer`.
689
+ - [Editor Guide](editor-guide.md) — how these documents are produced in the UI.
690
+ - [Examples](examples.md) — complete, annotated animations.