@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,2353 @@
1
+ # API Reference
2
+
3
+ Complete reference for the tinyfly animation engine, player, and adapters.
4
+
5
+ ## Table of Contents
6
+
7
+ - [Core Types](#core-types)
8
+ - [Timeline](#timeline)
9
+ - [Track](#track)
10
+ - [Clock](#clock)
11
+ - [Easing](#easing)
12
+ - [Interpolators](#interpolators)
13
+ - [3D Math](#3d-math)
14
+ - [3D Scenes](#3d-scenes)
15
+ - [Motion Path](#motion-path)
16
+ - [Text Tracks](#text-tracks)
17
+ - [Serialization](#serialization)
18
+ - [TinyflyPlayer](#tinyflyplayer)
19
+ - [TinyflySequencer](#tinyflysequencer)
20
+ - [Media Sync](#media-sync)
21
+ - [DOMAdapter](#domadapter)
22
+ - [CanvasAdapter](#canvasadapter)
23
+ - [SVGAdapter](#svgadapter)
24
+ - [Export Formats](#export-formats)
25
+ - [Headless Video](#headless-video)
26
+ - [WebGLAdapter](#webgladapter)
27
+ - [Inertia Tracks](#inertia-tracks)
28
+ - [Spring Tracks](#spring-tracks)
29
+ - [Stagger](#stagger)
30
+ - [Baking](#baking)
31
+ - [Authoring Values](#authoring-values)
32
+ - [Drivers](#drivers)
33
+ - [Interaction](#interaction)
34
+ - [Flip](#flip)
35
+ - [GSAP Compat](#gsap-compat)
36
+
37
+ Entry points: `tinyfly` (engine), `@algorisys/tinyfly/export` (CSS, Lottie, GIF, WebP,
38
+ video and sprite-sheet exporters), `@algorisys/tinyfly/player`, `@algorisys/tinyfly/adapters` (DOM,
39
+ Canvas, SVG and WebGL adapters, Flip helpers), `@algorisys/tinyfly/drivers`,
40
+ `@algorisys/tinyfly/interaction`, `@algorisys/tinyfly/gsap-compat`, `@algorisys/tinyfly/scene-3d` (3D scenes), `@algorisys/tinyfly/browser` (the live
41
+ runtime and everything except the exporters, for `<script>` tags), and `@algorisys/tinyfly/headless`
42
+ (video and stills rendering in Node).
43
+
44
+ ---
45
+
46
+ ## Core Types
47
+
48
+ ### AnimatableValue
49
+
50
+ ```typescript
51
+ type AnimatableValue = number | string | number[]
52
+ ```
53
+
54
+ All values that can be animated. Numbers for position/opacity, strings for colors, arrays for multi-dimensional values.
55
+
56
+ ### EasingType
57
+
58
+ ```typescript
59
+ type BuiltInEasingType =
60
+ | 'linear'
61
+ | 'ease-in' | 'ease-out' | 'ease-in-out'
62
+ | 'ease-in-quad' | 'ease-out-quad' | 'ease-in-out-quad'
63
+ | 'ease-in-cubic' | 'ease-out-cubic' | 'ease-in-out-cubic'
64
+
65
+ interface CubicBezierEasing {
66
+ type: 'cubic-bezier'
67
+ points: [number, number, number, number] // [cp1x, cp1y, cp2x, cp2y]
68
+ }
69
+
70
+ type EaseMode = 'in' | 'out' | 'in-out'
71
+
72
+ type ParametricEasing =
73
+ | { type: 'steps'; count: number; position?: 'start' | 'end' | 'none' | 'both' }
74
+ | { type: 'elastic'; mode?: EaseMode; amplitude?: number; period?: number }
75
+ | { type: 'bounce'; mode?: EaseMode }
76
+ | { type: 'back'; mode?: EaseMode; overshoot?: number }
77
+
78
+ type EasingType = BuiltInEasingType | CubicBezierEasing | ParametricEasing
79
+ ```
80
+
81
+ Parametric eases are evaluated when played, so they stay one keyframe in JSON.
82
+ `isParametricEasing(easing)` tells them apart; `expandParametricEasings(track)`
83
+ samples them into linear keyframes for keyframe-only formats.
84
+
85
+ ### Keyframe
86
+
87
+ ```typescript
88
+ interface Keyframe<T extends AnimatableValue = AnimatableValue> {
89
+ time: number // Time in milliseconds from timeline start
90
+ value: T // Value at this keyframe
91
+ easing?: EasingType // Easing function to use when interpolating TO this keyframe
92
+ }
93
+ ```
94
+
95
+ ### Track
96
+
97
+ ```typescript
98
+ interface Track<T extends AnimatableValue = AnimatableValue> {
99
+ id: string // Unique identifier
100
+ target: string // Target element name
101
+ property: string // Property to animate (e.g., 'opacity', 'x')
102
+ keyframes: Keyframe<T>[] // Must be sorted by time
103
+ delay?: number // Shift every keyframe by this many ms at evaluation time
104
+ endDelay?: number // Extra ms held after the last keyframe (extends duration)
105
+ targets?: string[] // Drive several targets; `target` is then ignored
106
+ stagger?: StaggerConfig // Per-target time offsets for `targets`
107
+ interpolation?: 'slerp' // Values are [x, y, z, w] quaternions: turn the short way (format version 2)
108
+ }
109
+
110
+ interface StaggerConfig {
111
+ each?: number // ms between consecutive targets
112
+ amount?: number // Total spread in ms (wins over `each`)
113
+ from?: 'start' | 'end' | 'center' | 'edges' | number // default 'start'
114
+ }
115
+ ```
116
+
117
+ Every track kind accepts `delay`, `targets` and `stagger`. `endDelay` takes
118
+ effect on keyframe and text tracks; spring and inertia tracks decide their own
119
+ duration. See [Stagger](#stagger).
120
+
121
+ ### MotionPathTrack
122
+
123
+ ```typescript
124
+ interface MotionPathConfig {
125
+ pathData: string // SVG path data (d attribute)
126
+ autoRotate?: boolean // Auto-rotate to follow path tangent
127
+ rotateOffset?: number // Rotation offset in degrees
128
+ matrix?: [a, b, c, d, e, f] // Affine transform applied to points and tangent
129
+ }
130
+
131
+ interface MotionPathTrack {
132
+ id: string
133
+ target: string
134
+ property: 'motionPath'
135
+ motionPathConfig: MotionPathConfig
136
+ keyframes: Keyframe<number>[] // Progress values 0-1
137
+ delay?: number; endDelay?: number; targets?: string[]; stagger?: StaggerConfig
138
+ }
139
+ ```
140
+
141
+ ### AnyTrack / KeyframedTrack
142
+
143
+ ```typescript
144
+ type AnyTrack = Track | MotionPathTrack | TextTrack | SpringTrack | InertiaTrack
145
+ type KeyframedTrack = Track | MotionPathTrack | TextTrack
146
+ ```
147
+
148
+ `AnyTrack` is what a timeline holds. `KeyframedTrack` is the subset with
149
+ `keyframes`; spring and inertia tracks compute values from parameters instead.
150
+ See [Text Tracks](#text-tracks), [Spring Tracks](#spring-tracks) and
151
+ [Inertia Tracks](#inertia-tracks).
152
+
153
+ ### TimelineConfig
154
+
155
+ ```typescript
156
+ interface TimelineConfig {
157
+ duration?: number // Total duration in ms (auto-calculated if not set)
158
+ loop?: number // 0 = no loop, -1 = infinite, n = n times
159
+ speed?: number // Playback speed multiplier (default: 1)
160
+ alternate?: boolean // Ping-pong effect on each loop
161
+ repeatDelay?: number // ms to wait between loop iterations
162
+ drawingRate?: number // drawings per second: 12 holds each for two frames of 24 fps ("on twos")
163
+ }
164
+ ```
165
+
166
+ `drawingRate` steps every value: `getStateAtTime(t)` evaluates at the start of
167
+ the drawing showing at `t` (`heldTime(t, rate)`), as hand-drawn animation is
168
+ timed. The clock still runs smoothly; only the values hold. Set it with
169
+ `timeline.drawingRate = 12` (0 turns it off).
170
+
171
+ `repeatDelay` applies at each loop boundary. Going forward, the playhead holds
172
+ the last frame for the delay, then wraps to the start; with `alternate` it holds
173
+ at the end it reached before turning round. The delay is consumed at `speed`,
174
+ and `seek()` or `stop()` cancels a pending one.
175
+
176
+ ### TimelineDefinition
177
+
178
+ ```typescript
179
+ interface TimelineDefinition {
180
+ formatVersion?: number // 1, or 2 when a track uses `interpolation`; readers refuse newer
181
+ id: string
182
+ name?: string
183
+ config: TimelineConfig
184
+ tracks: AnyTrack[]
185
+ }
186
+ ```
187
+
188
+ The JSON-serializable format used for saving, loading, and embedding animations.
189
+
190
+ ### AnimationState
191
+
192
+ ```typescript
193
+ interface AnimationState {
194
+ values: Map<string, Map<string, AnimatableValue>> // target -> property -> value
195
+ currentTime: number
196
+ playbackState: 'idle' | 'playing' | 'paused'
197
+ direction: 'forward' | 'reverse'
198
+ loopIteration: number
199
+ }
200
+ ```
201
+
202
+ Returned by `timeline.getStateAtTime()`. Contains the computed value for every target and property at the given time.
203
+
204
+ ### Type Guards
205
+
206
+ ```typescript
207
+ function isCubicBezierEasing(easing: EasingType | undefined): easing is CubicBezierEasing
208
+ function isMotionPathTrack(track: AnyTrack): track is MotionPathTrack
209
+ function isTextTrack(track: AnyTrack): track is TextTrack
210
+ function isSpringTrack(track: AnyTrack): track is SpringTrack
211
+ function isInertiaTrack(track: AnyTrack): track is InertiaTrack
212
+ function hasKeyframes(track: AnyTrack): track is KeyframedTrack
213
+ function isMotionPathPoint(value: unknown): value is MotionPathPoint
214
+ function isPathData(value: string): boolean // starts with a moveto
215
+ ```
216
+
217
+ ---
218
+
219
+ ## Timeline
220
+
221
+ The central class that orchestrates animation playback across multiple tracks.
222
+
223
+ ### Constructor
224
+
225
+ ```typescript
226
+ new Timeline(options: TimelineOptions)
227
+ ```
228
+
229
+ ```typescript
230
+ interface TimelineOptions {
231
+ id: string
232
+ name?: string
233
+ tracks?: AnyTrack[]
234
+ config?: TimelineConfig
235
+ }
236
+ ```
237
+
238
+ **Example:**
239
+ ```typescript
240
+ const timeline = new Timeline({
241
+ id: 'my-animation',
242
+ name: 'Fade Pulse',
243
+ config: { duration: 2000, loop: -1, speed: 1 },
244
+ tracks: [myTrack1, myTrack2]
245
+ })
246
+ ```
247
+
248
+ ### Properties
249
+
250
+ | Property | Type | Description |
251
+ |----------|------|-------------|
252
+ | `id` | `string` | Unique identifier (readonly) |
253
+ | `name` | `string \| undefined` | Human-readable name (readonly) |
254
+ | `tracks` | `AnyTrack[]` | Copy of all tracks (readonly) |
255
+ | `duration` | `number` | Total duration in ms (readonly, auto-calculated if not explicit) |
256
+ | `currentTime` | `number` | Current playback position in ms (readonly) |
257
+ | `playbackState` | `PlaybackState` | `'idle'`, `'playing'`, or `'paused'` (readonly) |
258
+ | `direction` | `PlaybackDirection` | `'forward'` or `'reverse'` (readonly) |
259
+ | `loopIteration` | `number` | Current loop iteration, 0-indexed (readonly) |
260
+ | `speed` | `number` | Playback speed multiplier (get/set) |
261
+
262
+ ### Methods
263
+
264
+ #### `play(): void`
265
+
266
+ Start or resume playback. If at the end (forward) or beginning (reverse), resets to the opposite end.
267
+
268
+ #### `pause(): void`
269
+
270
+ Pause playback at the current position.
271
+
272
+ #### `stop(): void`
273
+
274
+ Stop playback and reset to the beginning (time = 0, direction = forward).
275
+
276
+ #### `seek(time: number): void`
277
+
278
+ Jump to a specific time in milliseconds. Clamped to `[0, duration]`.
279
+
280
+ #### `reverse(): void`
281
+
282
+ Toggle playback direction between forward and reverse.
283
+
284
+ #### `tick(delta: number): void`
285
+
286
+ Advance the timeline by `delta` milliseconds. Call this from your animation loop (e.g., `requestAnimationFrame`). The delta is scaled by the `speed` multiplier. Handles looping, alternate direction, `repeatDelay`, and completion automatically. Does nothing unless the timeline is playing.
287
+
288
+ #### `getStateAtTime(time: number): AnimationState`
289
+
290
+ Compute the animation state at a specific time. Returns a map of all target/property values at that time. For motion path tracks, expands the progress value into `motionPathX`, `motionPathY`, and optionally `motionPathRotate`.
291
+
292
+ When several tracks drive the same target and property, the value comes from the track that **started most recently** (its first keyframe plus delay and stagger, at or before `time`). Before any of them has started, the one that **starts first** supplies its starting value. Ties on start time go to the track added last. This is what lets a sequence of tweens on one property play in order. `findConflicts()` names winners by the same rule.
293
+
294
+ #### `addTrack(track: AnyTrack): void`
295
+
296
+ Add a track to the timeline. Accepts every track kind.
297
+
298
+ #### `replaceTrack(trackId: string, track: AnyTrack): void`
299
+
300
+ Swap a track for a new version, keeping its position in the track order (which
301
+ decides ties between overlapping tracks). The new track may have a different id.
302
+ Does nothing if no track has `trackId`.
303
+
304
+ #### `removeTrack(trackId: string): void`
305
+
306
+ Remove a track by its ID.
307
+
308
+ #### `getTracks(filter?: TrackFilter): AnyTrack[]`
309
+
310
+ Tracks matching every field of the filter. An empty filter returns all tracks.
311
+
312
+ #### `removeTracks(filter?: TrackFilter): string[]`
313
+
314
+ Remove every track matching the filter and return their ids.
315
+ `timeline.removeTracks({ target: 'box' })` is the equivalent of killing all
316
+ tweens on an element.
317
+
318
+ ```typescript
319
+ interface TrackFilter {
320
+ target?: string // includes one of a multi-target track's `targets`
321
+ property?: string
322
+ timeRange?: { from: number; to: number } // active span overlaps this range (ms)
323
+ id?: string
324
+ }
325
+ ```
326
+
327
+ #### `getTrackSpan(trackId: string): { from: number; to: number } | undefined`
328
+
329
+ The span a track is active over, in ms: from its first keyframe plus `delay`
330
+ (or from `delay`, for springs and inertia) to its end, including stagger and
331
+ `endDelay`. `undefined` for an unknown id or a track with no keyframes.
332
+
333
+ #### `findConflicts(): TrackConflict[]`
334
+
335
+ Pairs of tracks that write the same property of the same target over
336
+ overlapping spans, with the winner decided by the rule above. The engine
337
+ resolves these silently, so authoring tools should call this and warn.
338
+
339
+ ```typescript
340
+ interface TrackConflict {
341
+ target: string
342
+ property: string
343
+ losingTrackId: string // values discarded where the spans overlap
344
+ winningTrackId: string // values applied
345
+ }
346
+ ```
347
+
348
+ #### `setDuration(duration: number | undefined): void`
349
+
350
+ Set an explicit duration in ms. Pass `undefined` to go back to the duration
351
+ calculated from the tracks.
352
+
353
+ #### `toDefinition(): TimelineDefinition`
354
+
355
+ Return the timeline as a `TimelineDefinition`. Not a copy: `tracks` are the
356
+ timeline's own track objects. Use [`serializeTimeline`](#serialization) for a
357
+ detached copy.
358
+
359
+ ### Callbacks
360
+
361
+ | Callback | Signature | Description |
362
+ |----------|-----------|-------------|
363
+ | `onUpdate` | `(state: AnimationState) => void` | Called on each `tick()` with the current state |
364
+ | `onComplete` | `() => void` | Called when the animation finishes (end of last loop) |
365
+
366
+ **Example:**
367
+ ```typescript
368
+ timeline.onUpdate = (state) => {
369
+ adapter.applyState(state)
370
+ }
371
+
372
+ timeline.onComplete = () => {
373
+ console.log('Animation finished!')
374
+ }
375
+ ```
376
+
377
+ ---
378
+
379
+ ## Track
380
+
381
+ ### createTrack
382
+
383
+ ```typescript
384
+ function createTrack<T extends AnimatableValue>(options: Track<T>): Track<T>
385
+ ```
386
+
387
+ Creates a track with keyframes sorted by time.
388
+
389
+ **Example:**
390
+ ```typescript
391
+ const track = createTrack({
392
+ id: 'box-opacity',
393
+ target: 'box',
394
+ property: 'opacity',
395
+ keyframes: [
396
+ { time: 0, value: 0 },
397
+ { time: 500, value: 1, easing: 'ease-out' },
398
+ { time: 1000, value: 0, easing: 'ease-in' }
399
+ ]
400
+ })
401
+ ```
402
+
403
+ ### Animatable Properties
404
+
405
+ Common properties you can animate:
406
+
407
+ | Property | Value Type | Description |
408
+ |----------|-----------|-------------|
409
+ | `opacity` | number (0-1) | Transparency |
410
+ | `x` | number | Horizontal position |
411
+ | `y` | number | Vertical position |
412
+ | `width` | number | Width |
413
+ | `height` | number | Height |
414
+ | `rotation` | number | Rotation in degrees |
415
+ | `scaleX` | number | Horizontal scale |
416
+ | `scaleY` | number | Vertical scale |
417
+ | `fill` | string | Fill color (hex/rgb/rgba) |
418
+ | `stroke` | string | Stroke color |
419
+ | `strokeWidth` | number | Stroke thickness |
420
+ | `borderRadius` | number | Corner radius |
421
+ | `fontSize` | number | Text font size |
422
+ | `motionPath` | number (0-1) | Progress along a motion path |
423
+
424
+ ---
425
+
426
+ ## Clock
427
+
428
+ ### Clock (Browser/RAF)
429
+
430
+ RAF-based clock for browser environments. Automatically advances time using `requestAnimationFrame`.
431
+
432
+ ```typescript
433
+ const clock = new Clock({ speed: 1 })
434
+
435
+ clock.onTick = (delta, currentTime) => {
436
+ timeline.tick(delta)
437
+ }
438
+
439
+ clock.start()
440
+ ```
441
+
442
+ | Property/Method | Type | Description |
443
+ |----------------|------|-------------|
444
+ | `currentTime` | `number` | Current time in ms (readonly) |
445
+ | `isRunning` | `boolean` | Whether the clock is ticking (readonly) |
446
+ | `speed` | `number` | Speed multiplier (get/set) |
447
+ | `onTick` | `TickCallback \| null` | Called each frame with `(delta, currentTime)` |
448
+ | `start()` | `void` | Start the RAF loop |
449
+ | `stop()` | `void` | Stop the RAF loop |
450
+ | `reset()` | `void` | Reset time to 0 |
451
+ | `seek(time)` | `void` | Set current time |
452
+
453
+ ### ManualClock (Testing/Non-Browser)
454
+
455
+ For testing or environments without `requestAnimationFrame`. Time only advances when `tick()` is called explicitly.
456
+
457
+ ```typescript
458
+ const clock = new ManualClock()
459
+ clock.onTick = (delta, currentTime) => {
460
+ timeline.tick(delta)
461
+ }
462
+
463
+ clock.start()
464
+ clock.tick(16.67) // Advance 16.67ms
465
+ clock.tick(16.67) // Advance another 16.67ms
466
+ ```
467
+
468
+ | Property/Method | Type | Description |
469
+ |----------------|------|-------------|
470
+ | `currentTime` | `number` | Current time (readonly) |
471
+ | `isRunning` | `boolean` | Running state (readonly) |
472
+ | `onTick` | `TickCallback \| null` | Tick callback |
473
+ | `start()` | `void` | Set running to true |
474
+ | `stop()` | `void` | Set running to false |
475
+ | `tick(delta)` | `void` | Advance time by delta ms |
476
+ | `reset()` | `void` | Reset time to 0 |
477
+ | `seek(time)` | `void` | Set current time |
478
+
479
+ ---
480
+
481
+ ## Easing
482
+
483
+ ### Built-in Functions
484
+
485
+ | Function | Description |
486
+ |----------|-------------|
487
+ | `linear` | Constant speed, no acceleration |
488
+ | `easeIn` | Cubic ease in (starts slow, accelerates) |
489
+ | `easeOut` | Cubic ease out (starts fast, decelerates) |
490
+ | `easeInOut` | Cubic ease in-out |
491
+ | `easeInQuad` | Quadratic ease in (gentler curve) |
492
+ | `easeOutQuad` | Quadratic ease out |
493
+ | `easeInOutQuad` | Quadratic ease in-out |
494
+ | `easeInCubic` | Cubic ease in (same as `easeIn`) |
495
+ | `easeOutCubic` | Cubic ease out (same as `easeOut`) |
496
+ | `easeInOutCubic` | Cubic ease in-out (same as `easeInOut`) |
497
+
498
+ Each function takes a normalized time value (0-1) and returns an eased value (0-1).
499
+
500
+ ### createCubicBezier
501
+
502
+ ```typescript
503
+ function createCubicBezier(points: [number, number, number, number]): EasingFunction
504
+ ```
505
+
506
+ Creates a custom cubic bezier easing function from 4 control points `[cp1x, cp1y, cp2x, cp2y]`. Uses Newton-Raphson iteration for accurate x-to-t mapping.
507
+
508
+ **Example:**
509
+ ```typescript
510
+ const customEase = createCubicBezier([0.25, 0.1, 0.25, 1.0])
511
+ const easedValue = customEase(0.5) // Returns ~0.8
512
+ ```
513
+
514
+ ### getEasingFunction
515
+
516
+ ```typescript
517
+ function getEasingFunction(type: EasingType | undefined): EasingFunction
518
+ ```
519
+
520
+ Resolves an easing type identifier to its function. Returns `linear` if type is undefined. Supports both built-in string types and `CubicBezierEasing` objects.
521
+
522
+ ---
523
+
524
+ ## Interpolators
525
+
526
+ Functions that compute intermediate values between two endpoints.
527
+
528
+ ### interpolateNumber
529
+
530
+ ```typescript
531
+ function interpolateNumber(from: number, to: number, progress: number): number
532
+ ```
533
+
534
+ Linear interpolation between two numbers.
535
+
536
+ ### interpolateColor
537
+
538
+ ```typescript
539
+ function interpolateColor(from: string, to: string, progress: number): string
540
+ ```
541
+
542
+ Smooth interpolation between two color values. Supports:
543
+ - Hex colors: `#ff0000`, `#00ff00`
544
+ - RGB: `rgb(255, 0, 0)`
545
+ - RGBA: `rgba(255, 0, 0, 0.5)`
546
+
547
+ Returns a color string in the same format as the inputs.
548
+
549
+ ### interpolateArray
550
+
551
+ ```typescript
552
+ function interpolateArray(from: number[], to: number[], progress: number): number[]
553
+ ```
554
+
555
+ Element-wise interpolation of number arrays.
556
+
557
+ ### interpolateQuaternion
558
+
559
+ ```typescript
560
+ function interpolateQuaternion(from: number[], to: number[], progress: number): number[]
561
+ ```
562
+
563
+ Spherical interpolation of `[x, y, z, w]` rotations: the short way round, at a
564
+ steady angular speed, always a unit quaternion. Used by tracks with
565
+ `interpolation: 'slerp'`.
566
+
567
+ ### interpolateString
568
+
569
+ ```typescript
570
+ function interpolateString(from: string, to: string, progress: number): string
571
+ ```
572
+
573
+ Discrete interpolation — returns `from` when `progress < 1`, `to` when `progress >= 1`.
574
+
575
+ ### morphPath (shape tween)
576
+
577
+ ```typescript
578
+ function morphPath(from: string, to: string, progress: number, options?: MorphOptions): string
579
+ function isPathData(value: string): boolean
580
+
581
+ interface MorphOptions {
582
+ shapeIndex?: number // force the start-point alignment; negative reverses direction
583
+ }
584
+ ```
585
+
586
+ Interpolate between two SVG path `d` strings. Both paths are sampled along their
587
+ length (keeping every corner) and the points are blended by `progress`, so **any**
588
+ two shapes morph smoothly and deterministically (no DOM required). `isPathData` recognises a
589
+ string that starts with a moveto. A `d` track animates a path's shape — see
590
+ [shape-morph.md](shape-morph.md).
591
+
592
+ ### getInterpolator
593
+
594
+ ```typescript
595
+ function getInterpolator<T extends AnimatableValue>(sampleValue: T, interpolation?: 'slerp'): Interpolator<T>
596
+ ```
597
+
598
+ With `interpolation: 'slerp'`, `interpolateQuaternion`. Otherwise auto-detect
599
+ from a sample value:
600
+ - Numbers → `interpolateNumber`
601
+ - Strings starting with `#` or `rgb` → `interpolateColor`
602
+ - **SVG path data** (a moveto) → `morphPath` (shape morph)
603
+ - Other strings → `interpolateString`
604
+ - Arrays → `interpolateArray`
605
+
606
+ ---
607
+
608
+ ## 3D Math
609
+
610
+ Small, pure helpers for rotations and transforms, exported from the engine as
611
+ three namespaces. Values are plain arrays (JSON as they are): `Vec3` is
612
+ `[x, y, z]`, `Quat` is `[x, y, z, w]`, `Mat4` is 16 numbers, **column-major**
613
+ (as WebGL, glTF and CSS `matrix3d()`). Euler angles are degrees in **YXZ**
614
+ order: `quat.fromEuler(x, y, z)` turns as CSS `rotateY(y) rotateX(x) rotateZ(z)`.
615
+
616
+ ```typescript
617
+ import { vec3, quat, mat4 } from '@algorisys/tinyfly'
618
+
619
+ vec3.add / subtract / scale / dot / cross / length / distance / normalize / lerp
620
+ quat.identity() / fromAxisAngle(axis, degrees) / fromEuler(x, y, z) / toEuler(q)
621
+ quat.multiply(a, b) // b first, then a
622
+ quat.slerp(a, b, t) / dot / length / normalize / conjugate / rotateVec3(q, v)
623
+ mat4.identity() / multiply(a, b) / translation(v) / scaling(v) / fromQuat(q)
624
+ mat4.compose(position, rotation, scale) // scale, then rotate, then move
625
+ mat4.invert(m) /* null when singular */ / transpose(m)
626
+ mat4.perspective(fovY, aspect, near, far) / orthographic(l, r, b, t, near, far)
627
+ mat4.lookAt(eye, target, up?) / transformPoint(m, p)
628
+ ```
629
+
630
+ See [3D rotations](3d-rotations.md).
631
+
632
+ ---
633
+
634
+ ## 3D Scenes
635
+
636
+ `@algorisys/tinyfly/scene-3d` (and `tinyfly-scene-3d.iife.js` for script tags):
637
+
638
+ ```typescript
639
+ loadScene3D(scene: Scene3D): LoadedScene3D
640
+ validateScene3D(scene: Scene3D, tracks?: { target, property }[]): string[]
641
+ resolveScene3D(loaded, values: SceneValues, { width, height, time?, valuesAt? }): ResolvedScene3D
642
+ drawScene3D(ctx, loaded, values | undefined, { width, height, time?, valuesAt? | stateAt? }): void
643
+ new Scene3DAdapter(renderer: Renderer3D, { width, height, valuesAt? }) // registerScene, unregisterScene, resize, applyState, render
644
+ new Canvas2DRenderer(ctx) // render(frame); drawResolvedScene(ctx, frame)
645
+ orbitPosition(target, yaw, pitch, distance) / dollyPosition(eye, target, amount) / lookAtView(eye, target) / projectionMatrix(camera, aspect)
646
+ shadeTriangle(triangle, lights, camera, fog?) / lightAt(point, normal, lights) / fogAmount(fog, distance) / parseColor(color)
647
+ boxMesh / planeMesh / sphereMesh / cylinderMesh / coneMesh / torusMesh / extrudeMesh(path, { depth, width?, curveSegments? }) / geometryMesh / meshEdges / MeshBuilder
648
+ triangulate(outline, holes?) / signedArea / pointInPolygon
649
+ ```
650
+
651
+ Objects: `group`, `mesh`, `camera`, `light`, and `line` (`points`, `closed?`)
652
+ and `trail` (`follow`, `length` ms, `samples?`, `period?`), both with
653
+ `color`, `width` (metres), `taper`, `fade`, `opacity`, `blend: 'normal' | 'add'`.
654
+ A trail needs `valuesAt` (a video frame's `stateAt` does it). See
655
+ [3D Scenes](scene-3d.md#lines-and-trails).
656
+
657
+ new WebGL2Renderer(gl, { overlay? }) // @algorisys/tinyfly/scene-3d/webgl: render(frame), destroy()
658
+ loadScene3D(scene, { kinds: [characterObjects] }) // object kinds beyond the built-ins: ObjectKind { kind, validate?, prepare?, resolve }
659
+ // from @algorisys/tinyfly/characters:
660
+ characterObjects // the `character` object kind (pen or solid look)
661
+ drawCharacterInView(ctx, character, pose, projection, { height, time? }) / characterJointsInView(…)
662
+ skeletonInView(plan, pose, { height }, projection) / stagePlanSpace(plan, pose, { height }) / solvePlanSpace(plan, pose, height)
663
+ ```
664
+
665
+ Types: `Scene3D`, `Object3D` (`group`, `mesh`, `camera`, `light`, `character`), `Geometry3D`,
666
+ `Material3D`, `ResolvedScene3D`, `DrawTriangle`. Tracks address objects as
667
+ `<sceneId>/<objectId>`; see [3D Scenes](scene-3d.md) for the properties.
668
+
669
+ ---
670
+
671
+ ## Motion Path
672
+
673
+ Animate elements along SVG paths.
674
+
675
+ ### getMotionPathPoint
676
+
677
+ ```typescript
678
+ function getMotionPathPoint(config: MotionPathConfig, progress: number): MotionPathPoint
679
+ ```
680
+
681
+ Get the position and tangent angle at a given progress (0-1) along the path.
682
+
683
+ ```typescript
684
+ interface MotionPathPoint {
685
+ x: number // X coordinate on the path
686
+ y: number // Y coordinate on the path
687
+ angle: number // Tangent angle in degrees
688
+ }
689
+ ```
690
+
691
+ ### interpolateMotionPath
692
+
693
+ ```typescript
694
+ function interpolateMotionPath(
695
+ config: MotionPathConfig,
696
+ fromProgress: number,
697
+ toProgress: number,
698
+ t: number
699
+ ): MotionPathPoint
700
+ ```
701
+
702
+ Interpolate between two progress values on a path. The `t` parameter is the eased interpolation factor (0-1).
703
+
704
+ ### Usage with Timeline
705
+
706
+ Motion paths are used through `MotionPathTrack`:
707
+
708
+ ```typescript
709
+ const motionTrack: MotionPathTrack = {
710
+ id: 'path-track',
711
+ target: 'ball',
712
+ property: 'motionPath',
713
+ motionPathConfig: {
714
+ pathData: 'M 0 100 Q 150 0 300 100',
715
+ autoRotate: true,
716
+ rotateOffset: 0
717
+ },
718
+ keyframes: [
719
+ { time: 0, value: 0 },
720
+ { time: 2000, value: 1, easing: 'ease-in-out' }
721
+ ]
722
+ }
723
+
724
+ timeline.addTrack(motionTrack)
725
+ ```
726
+
727
+ The timeline automatically expands the motion path progress into `motionPathX`, `motionPathY`, and `motionPathRotate` properties in the animation state.
728
+
729
+ Progress is by arc length, including within curves, so followers move at an even
730
+ speed. `matrix` places the path into another coordinate space (x' = a·x + c·y + e,
731
+ y' = b·x + d·y + f); the tangent is transformed too, so `autoRotate` still faces
732
+ along the path.
733
+
734
+ ### Path utilities
735
+
736
+ ```typescript
737
+ import { parsePath, getPointAtProgress, getPathLength, pointsToPath, shapeToPathData, morphPath } from '@algorisys/tinyfly'
738
+
739
+ getPathLength('M0 0 L30 40') // 50
740
+ getPointAtProgress('M0 0 Q50 100 100 0', 0.5) // { x: 50, y: 50, angle: 0 }
741
+ pointsToPath([{ x: 0, y: 0 }, { x: 50, y: 50 }, { x: 100, y: 0 }], { curviness: 1, closed: false })
742
+ shapeToPathData({ tag: 'circle', attributes: { cx: '50', cy: '50', r: '40' } }) // 'M90 50 A40 40 …'
743
+
744
+ // Trails: where something was, as a pure function of time
745
+ trailSamples(positionAt: (t) => P, time, { length, samples = 32, period?, since? }): { at: P; time; age }[] // oldest first, age 1 → 0
746
+ ribbon(points: { x, y, width }[]): { left, right } // a band's mitred edges
747
+ ribbonHeadCap(points): { x, y, radius, start } | null // its round end
748
+ // @algorisys/tinyfly/adapters (and the browser bundle): draw one
749
+ drawTrail(ctx, samples, { color, width = 6, taper = 1, fade = 1, opacity = 1, blend: 'normal' | 'add', head?: { radius, color? } })
750
+ ```
751
+
752
+ `morphPath(from, to, progress, { shapeIndex? })` blends two paths: subpaths are
753
+ paired, the start point and winding are chosen automatically (or forced with
754
+ `shapeIndex`), and corners of both shapes are kept. `pointAtDistance(segments,
755
+ distance, start?, end?)` samples a run of parsed segments; `parsePath(d).subpaths`
756
+ lists each subpath's segment range, length and whether it is closed.
757
+
758
+ `parsePath` reads every SVG path command, absolute or relative, including compact
759
+ notation (`10-20`, `.5.5`, exponents, unseparated arc flags). It normalises to
760
+ absolute lines and cubic beziers (`Q`/`T` exactly, `S`/`T` with reflected
761
+ controls, arcs split into ≤90° cubics). Results are cached (bounded).
762
+
763
+ ### GSAP-style: `motionPath`
764
+
765
+ `tf`, `timeline()` and `live` accept `motionPath: { path, curviness, autoRotate, start, end }`
766
+ (or shorthand path data / points). `live` also accepts a selector or element for
767
+ `path`, plus `align` and `alignOrigin`. See [gsap-compat.md](gsap-compat.md#motion-paths).
768
+
769
+ ---
770
+
771
+ ## Text Tracks
772
+
773
+ Animate text by typing or scrambling from one string to another.
774
+
775
+ ```typescript
776
+ interface TextConfig {
777
+ from?: string // text at progress 0 (default '')
778
+ to: string // text at progress 1
779
+ mode: 'type' | 'scramble'
780
+ chars?: 'upperCase' | 'lowerCase' | 'upperAndLowerCase' | 'numbers' | string
781
+ refreshRate?: number // scramble: random-character changes per second (default 20)
782
+ revealDelay?: number // scramble: fraction of the tween before characters settle
783
+ tweenLength?: boolean // scramble: grow/shrink length over the tween (default true)
784
+ rightToLeft?: boolean // reveal / type from the end
785
+ seed?: number // scramble: fixes the random characters
786
+ }
787
+
788
+ interface TextTrack {
789
+ id: string
790
+ target: string
791
+ property: 'text'
792
+ textConfig: TextConfig
793
+ keyframes: Keyframe<number>[] // progress 0-1, with easing
794
+ delay?: number; endDelay?: number; targets?: string[]; stagger?: StaggerConfig
795
+ }
796
+ ```
797
+
798
+ The timeline expands progress into a `text` value in the animation state; the DOM
799
+ and SVG adapters set it as `textContent`, and the Canvas adapter as a text
800
+ target's `text`. `textAt(config, progress, elapsedMs)` computes the string
801
+ directly. It is pure: scramble characters come from a hash of the seed, position
802
+ and refresh step, so the same inputs always give the same string.
803
+
804
+ In `type` mode, the new text overwrites the old one character at a time over the
805
+ longer of the two strings, so typing towards shorter text deletes as it goes.
806
+
807
+ ---
808
+
809
+ ## Serialization
810
+
811
+ ### serializeTimeline / deserializeTimeline
812
+
813
+ ```typescript
814
+ function serializeTimeline(timeline: Timeline): TimelineDefinition
815
+ function deserializeTimeline(definition: TimelineDefinition): Timeline
816
+ ```
817
+
818
+ Convert between `Timeline` instances and JSON-serializable `TimelineDefinition` objects.
819
+
820
+ ### toJSON / fromJSON
821
+
822
+ ```typescript
823
+ function toJSON(timeline: Timeline): string
824
+ function fromJSON(json: string): Timeline
825
+ ```
826
+
827
+ Convert between `Timeline` instances and JSON strings.
828
+
829
+ ### serializeTrack / deserializeTrack
830
+
831
+ ```typescript
832
+ function serializeTrack(track: AnyTrack): AnyTrack
833
+ function deserializeTrack(data: AnyTrack): AnyTrack
834
+ ```
835
+
836
+ Serialize/deserialize individual tracks of every kind. Scheduling fields are
837
+ kept when set and omitted otherwise; `deserializeTrack` sorts keyframes by time.
838
+
839
+ **Example:**
840
+ ```typescript
841
+ // Save
842
+ const json = toJSON(timeline)
843
+ localStorage.setItem('animation', json)
844
+
845
+ // Load
846
+ const restored = fromJSON(localStorage.getItem('animation'))
847
+ restored.play()
848
+ ```
849
+
850
+ ---
851
+
852
+ ## TinyflyPlayer
853
+
854
+ Lightweight player for embedding animations in web pages.
855
+
856
+ ### Constructor
857
+
858
+ ```typescript
859
+ new TinyflyPlayer(container: HTMLElement | string, options?: PlayerOptions)
860
+ ```
861
+
862
+ ```typescript
863
+ interface PlayerOptions {
864
+ speed?: number // Playback speed (default: 1)
865
+ loop?: number // -1 = infinite, 0 = no loop, n = n times
866
+ alternate?: boolean // Ping-pong effect
867
+ autoplay?: boolean // Auto-play on load (default: false)
868
+ onComplete?: () => void // Called when animation finishes
869
+ onUpdate?: (state: AnimationState) => void // Called each frame
870
+ }
871
+ ```
872
+
873
+ The container can be an `HTMLElement` or a CSS selector string (e.g., `'#my-animation'`).
874
+
875
+ ### Methods
876
+
877
+ #### `load(source: string | TimelineDefinition): Promise<void>`
878
+
879
+ Load an animation from a URL (fetches JSON) or an inline `TimelineDefinition` object. Automatically discovers target elements in the container.
880
+
881
+ #### `loadFromString(json: string): void`
882
+
883
+ Load an animation from a JSON string.
884
+
885
+ #### `registerTarget(name: string, element: HTMLElement | string): void`
886
+
887
+ Manually register a target element by name. The element can be an `HTMLElement` or a CSS selector (searched within the container).
888
+
889
+ #### `play(): void`
890
+
891
+ Start or resume playback.
892
+
893
+ #### `pause(): void`
894
+
895
+ Pause at the current position.
896
+
897
+ #### `stop(): void`
898
+
899
+ Stop and reset to the beginning.
900
+
901
+ #### `seek(time: number): void`
902
+
903
+ Jump to a specific time in milliseconds.
904
+
905
+ #### `setSpeed(speed: number): void`
906
+
907
+ Change the playback speed.
908
+
909
+ #### `reverse(): void`
910
+
911
+ Toggle playback direction.
912
+
913
+ #### `attachMedia(media: SyncableMedia, options?: MediaSyncOptions): void`
914
+
915
+ Keep an `<audio>` / `<video>` element (or anything shaped like one) in sync with
916
+ the timeline. The timeline stays the clock; the media follows play, pause, seek
917
+ and speed. Replaces any media attached before. See [Media Sync](#media-sync).
918
+
919
+ #### `detachMedia(): void`
920
+
921
+ Pause and release the attached media, if any.
922
+
923
+ #### `destroy(): void`
924
+
925
+ Clean up all resources, stop the animation loop, and clear registered targets.
926
+
927
+ ### Properties
928
+
929
+ | Property | Type | Description |
930
+ |----------|------|-------------|
931
+ | `currentTime` | `number` | Current playback time in ms |
932
+ | `duration` | `number` | Total animation duration in ms |
933
+ | `isPlaying` | `boolean` | Whether currently playing |
934
+
935
+ ### Target Auto-Discovery
936
+
937
+ When `load()` is called, the player automatically finds target elements by searching the container for:
938
+
939
+ 1. `data-tinyfly="name"` attribute (highest priority)
940
+ 2. Class name `.name`
941
+ 3. ID `#name`
942
+
943
+ ```html
944
+ <!-- All three are valid ways to mark a target named "box" -->
945
+ <div data-tinyfly="box"></div>
946
+ <div class="box"></div>
947
+ <div id="box"></div>
948
+ ```
949
+
950
+ On `load()` the player also binds any `[data-tinyfly-media]` audio/video
951
+ elements in the container, starting each at its `data-tinyfly-start` time (ms).
952
+ The editor's embed export writes these attributes.
953
+
954
+ ### Helper Functions
955
+
956
+ #### play()
957
+
958
+ ```typescript
959
+ async function play(
960
+ container: HTMLElement | string,
961
+ source: string | TimelineDefinition,
962
+ options?: PlayerOptions
963
+ ): Promise<TinyflyPlayer>
964
+ ```
965
+
966
+ Create a player and immediately start playback. Shorthand for creating a player with `autoplay: true`.
967
+
968
+ ```typescript
969
+ const player = await tinyfly.play('#animation', './animation.json', {
970
+ loop: -1
971
+ })
972
+ ```
973
+
974
+ #### create()
975
+
976
+ ```typescript
977
+ function create(
978
+ container: HTMLElement | string,
979
+ options?: PlayerOptions
980
+ ): TinyflyPlayer
981
+ ```
982
+
983
+ Create a player without auto-playing. Use this when you need to register targets or configure the player before loading.
984
+
985
+ ```typescript
986
+ const player = tinyfly.create('#animation', { loop: -1 })
987
+ player.registerTarget('box', document.getElementById('my-box'))
988
+ await player.load('./animation.json')
989
+ player.play()
990
+ ```
991
+
992
+ ---
993
+
994
+ ## TinyflySequencer
995
+
996
+ Multi-scene player that plays scenes in order with transitions between them.
997
+
998
+ ### Constructor
999
+
1000
+ ```typescript
1001
+ new TinyflySequencer(container: HTMLElement | string, options?: SequencerOptions)
1002
+ ```
1003
+
1004
+ ```typescript
1005
+ interface SequencerOptions {
1006
+ loop?: number // -1 = infinite, 0 = no loop
1007
+ autoplay?: boolean // Auto-play on load
1008
+ onComplete?: () => void // Called when sequence finishes
1009
+ onSceneChange?: (sceneIndex: number) => void // Called when scene starts
1010
+ }
1011
+ ```
1012
+
1013
+ ### Methods
1014
+
1015
+ #### `load(source: string | SequenceDefinition): Promise<void>`
1016
+
1017
+ Load a sequence from a URL or inline definition. Renders the first scene's elements and sets up the canvas dimensions.
1018
+
1019
+ #### `play(): void`
1020
+
1021
+ Start playing from the current scene. Does nothing if no sequence is loaded or if the sequence is empty.
1022
+
1023
+ #### `pause(): void`
1024
+
1025
+ Pause playback.
1026
+
1027
+ #### `stop(): void`
1028
+
1029
+ Stop and reset to the first scene.
1030
+
1031
+ #### `goToScene(index: number): void`
1032
+
1033
+ Jump directly to a specific scene by index. If the sequencer was playing, playback continues at the new scene. Invalid indices are ignored.
1034
+
1035
+ #### `destroy(): void`
1036
+
1037
+ Clean up all resources, remove scene containers, stop playback.
1038
+
1039
+ ### Properties
1040
+
1041
+ | Property | Type | Description |
1042
+ |----------|------|-------------|
1043
+ | `currentSceneIndex` | `number` | Index of the current scene |
1044
+ | `sceneCount` | `number` | Total number of scenes |
1045
+ | `isPlaying` | `boolean` | Whether currently playing |
1046
+ | `state` | `string` | `'idle'`, `'playing-scene'`, or `'transitioning'` |
1047
+
1048
+ ### Sequence Types
1049
+
1050
+ ```typescript
1051
+ interface SequenceDefinition {
1052
+ id: string
1053
+ name: string
1054
+ canvas: { width: number; height: number }
1055
+ scenes: SequenceScene[]
1056
+ loop?: number
1057
+ }
1058
+
1059
+ interface SequenceScene {
1060
+ id: string
1061
+ name: string
1062
+ elements: SerializedElement[]
1063
+ timeline: TimelineDefinition | null
1064
+ transition: SceneTransition // Ignored for first scene
1065
+ }
1066
+
1067
+ interface SceneTransition {
1068
+ type: TransitionType
1069
+ duration: number // In milliseconds
1070
+ }
1071
+
1072
+ type TransitionType = 'none' | 'fade' | 'slide-left' | 'slide-right' | 'slide-up' | 'slide-down'
1073
+ ```
1074
+
1075
+ ### playSequence()
1076
+
1077
+ ```typescript
1078
+ async function playSequence(
1079
+ container: HTMLElement | string,
1080
+ source: string | SequenceDefinition,
1081
+ options?: SequencerOptions
1082
+ ): Promise<TinyflySequencer>
1083
+ ```
1084
+
1085
+ Create a sequencer and immediately start playback.
1086
+
1087
+ ```typescript
1088
+ const sequencer = await tinyfly.playSequence('#container', './sequence.json', {
1089
+ loop: -1,
1090
+ onSceneChange: (index) => console.log(`Now playing scene ${index}`)
1091
+ })
1092
+ ```
1093
+
1094
+ ---
1095
+
1096
+ ## Media Sync
1097
+
1098
+ Locks media to a timeline. Depends only on a small structural subset of
1099
+ `HTMLMediaElement`, so it can drive any media source and is testable without a
1100
+ browser.
1101
+
1102
+ ```typescript
1103
+ import { MediaSync, syncMediaElement } from '@algorisys/tinyfly/player'
1104
+
1105
+ interface SyncableMedia {
1106
+ currentTime: number // seconds
1107
+ readonly paused: boolean
1108
+ playbackRate: number
1109
+ play(): Promise<void> | void
1110
+ pause(): void
1111
+ }
1112
+
1113
+ interface MediaSyncOptions {
1114
+ offset?: number // seconds added to timeline time (default 0)
1115
+ driftTolerance?: number // seconds of drift allowed while playing (default 0.15)
1116
+ }
1117
+ ```
1118
+
1119
+ | `MediaSync` method | Description |
1120
+ |--------|-------------|
1121
+ | `new MediaSync(media, options?)` | Wrap a media element |
1122
+ | `update(timelineTimeMs, isPlaying)` | Call each frame. Plays or pauses the media to match; re-seeks while playing only when drift exceeds the tolerance, and exactly while paused |
1123
+ | `seek(timelineTimeMs)` | Hard-align on an explicit seek |
1124
+ | `setRate(rate)` | Mirror the timeline speed onto `playbackRate` |
1125
+ | `dispose()` | Pause the media |
1126
+
1127
+ `syncMediaElement(sync, media, timelineMs, isPlaying, startMs)` handles media
1128
+ that starts partway through: before `startMs` it keeps the media paused at 0,
1129
+ after it syncs to the elapsed time. A `play()` rejected by autoplay policy is
1130
+ ignored, so blocked audio never stops the animation.
1131
+
1132
+ ---
1133
+
1134
+ ## DOMAdapter
1135
+
1136
+ Applies animation state to HTML elements using CSS transforms and styles.
1137
+
1138
+ ### Usage
1139
+
1140
+ ```typescript
1141
+ import { DOMAdapter } from '@algorisys/tinyfly/adapters'
1142
+
1143
+ const adapter = new DOMAdapter()
1144
+ adapter.registerTarget('box', document.getElementById('my-box'))
1145
+
1146
+ // In animation loop:
1147
+ const state = timeline.getStateAtTime(timeline.currentTime)
1148
+ adapter.applyState(state)
1149
+ ```
1150
+
1151
+ ### Methods
1152
+
1153
+ | Method | Description |
1154
+ |--------|-------------|
1155
+ | `registerTarget(id, element)` | Register an HTML element as a target |
1156
+ | `unregisterTarget(id)` | Remove a target |
1157
+ | `getTarget(id)` | Get a registered element |
1158
+ | `clearTargets()` | Remove all targets |
1159
+ | `applyState(state)` | Apply animation state to all registered targets |
1160
+
1161
+ ### Property Mappings
1162
+
1163
+ The DOM adapter maps animation properties to CSS:
1164
+
1165
+ **Transform properties** (applied via `style.transform`):
1166
+ - `x` → `translateX`
1167
+ - `y` → `translateY`
1168
+ - `rotation` / `rotate` → `rotate`
1169
+ - `scale` → `scale`
1170
+ - `scaleX` → `scaleX`
1171
+ - `scaleY` → `scaleY`
1172
+ - `skewX` → `skewX`
1173
+ - `skewY` → `skewY`
1174
+ - `z`, `rotateX`, `rotateY`, `rotateZ`, `scaleZ` → `translateZ`, `rotateX`, … (3D)
1175
+ - `perspective` → `perspective()`, first in the list
1176
+ - `quaternion` (`[x, y, z, w]`, a track with `interpolation: 'slerp'`) → `matrix3d()`
1177
+ - Written in one order whatever the track order: perspective, translate, rotate, rotateX, rotateY, quaternion, scale, skew (as the SVG, Canvas and WebGL adapters compose them)
1178
+
1179
+ **3D layout:** `childPerspective` (px) and `perspectiveOriginX` / `perspectiveOriginY` (%) set CSS `perspective` / `perspective-origin` on a parent for its children; `transformStyle` and `backfaceVisibility` pass through as CSS. The Canvas and WebGL adapters take `z`, `rotateX`, `rotateY`, `quaternion`, `perspective` and `backfaceVisibility` too, in true perspective (see [3D transforms](3d-rotations.md)).
1180
+
1181
+ **Style properties:**
1182
+ - `opacity` → `style.opacity`
1183
+ - `fill` → `style.backgroundColor` (or `style.color` for text)
1184
+ - `stroke` → `style.borderColor`
1185
+ - `strokeWidth` → `style.borderWidth`
1186
+ - `width` → `style.width`
1187
+ - `height` → `style.height`
1188
+ - `borderRadius` → `style.borderRadius`
1189
+ - `fontSize` → `style.fontSize`
1190
+
1191
+ **Motion path properties:**
1192
+ - `motionPathX` → adds `translateX` override
1193
+ - `motionPathY` → adds `translateY` override
1194
+ - `motionPathRotate` → adds `rotate` override
1195
+
1196
+ ---
1197
+
1198
+ ## CanvasAdapter
1199
+
1200
+ Draws animated shapes on a Canvas 2D context.
1201
+
1202
+ ### Usage
1203
+
1204
+ ```typescript
1205
+ import { CanvasAdapter } from '@algorisys/tinyfly/adapters'
1206
+
1207
+ const canvas = document.getElementById('my-canvas') as HTMLCanvasElement
1208
+ const ctx = canvas.getContext('2d')
1209
+ const adapter = new CanvasAdapter()
1210
+
1211
+ // Register targets
1212
+ adapter.registerTarget('box', {
1213
+ type: 'rect',
1214
+ x: 50, y: 50, width: 100, height: 100,
1215
+ fillStyle: '#4a9eff'
1216
+ })
1217
+
1218
+ // Animation loop
1219
+ function animate() {
1220
+ const state = timeline.getStateAtTime(timeline.currentTime)
1221
+ adapter.applyState(state)
1222
+
1223
+ ctx.clearRect(0, 0, canvas.width, canvas.height)
1224
+ adapter.render(ctx)
1225
+ requestAnimationFrame(animate)
1226
+ }
1227
+ ```
1228
+
1229
+ ### Methods
1230
+
1231
+ | Method | Description |
1232
+ |--------|-------------|
1233
+ | `registerTarget(id, target, aliasFor?)` | Register a canvas target |
1234
+ | `unregisterTarget(id)` | Remove a target |
1235
+ | `getTarget(id)` | Get a registered target |
1236
+ | `clearTargets()` | Remove all targets |
1237
+ | `applyState(state)` | Update target properties from animation state |
1238
+ | `render(ctx)` | Draw all targets to a canvas context |
1239
+ | `static loadImage(src)` | Load an image for use as ImageTarget |
1240
+
1241
+ ### Sketched and drawn-on shapes
1242
+
1243
+ Rect, circle, line and path targets take two more properties:
1244
+
1245
+ | Property | |
1246
+ |---|---|
1247
+ | `sketch` | A `SketchStyle` (`roughness`, `passes`, `boil`, `seed`): the outline is drawn in hand-drawn pencil strokes that boil; the fill stays clean |
1248
+ | `drawOn` | 0..1, how much of the outline is drawn (default 1). Animate it to draw a shape on; the fill appears once the outline is complete. Circles start at the top and go clockwise |
1249
+
1250
+ ```typescript
1251
+ adapter.registerTarget('box', {
1252
+ type: 'rect', x: 50, y: 50, width: 100, height: 100,
1253
+ fillStyle: '#fde68a', strokeStyle: '#2f2f33', lineWidth: 4,
1254
+ sketch: { roughness: 3, boil: 8 },
1255
+ })
1256
+ // …and a track: { target: 'box', property: 'drawOn', keyframes: [{ time: 0, value: 0 }, { time: 800, value: 1 }] }
1257
+ ```
1258
+
1259
+ Without `sketch`, and with `drawOn` at 1, shapes draw exactly as before. The
1260
+ pen and the outline helpers are exported too: `sketchPen()`, `boilFrame()`,
1261
+ `pathOutline()`, `rectOutline()`, `drawOutline()`, `partialPath()`,
1262
+ `pointAlong()`, `pathLength()`.
1263
+
1264
+ ### Target Types
1265
+
1266
+ #### RectTarget
1267
+
1268
+ ```typescript
1269
+ {
1270
+ type: 'rect'
1271
+ x: number, y: number, width: number, height: number
1272
+ opacity?: number, rotate?: number, scale?: number
1273
+ fillStyle?: string | LinearGradient | RadialGradient
1274
+ strokeStyle?: string, lineWidth?: number
1275
+ borderRadius?: number
1276
+ }
1277
+ ```
1278
+
1279
+ #### CircleTarget
1280
+
1281
+ ```typescript
1282
+ {
1283
+ type: 'circle'
1284
+ x: number, y: number, radius: number
1285
+ opacity?: number, rotate?: number, scale?: number
1286
+ fillStyle?: string | LinearGradient | RadialGradient
1287
+ strokeStyle?: string, lineWidth?: number
1288
+ }
1289
+ ```
1290
+
1291
+ #### TextTarget
1292
+
1293
+ ```typescript
1294
+ {
1295
+ type: 'text'
1296
+ x: number, y: number, text: string
1297
+ fontSize?: number, fontFamily?: string, fontWeight?: number
1298
+ textAlign?: 'left' | 'center' | 'right'
1299
+ textBaseline?: CanvasTextBaseline
1300
+ fillStyle?: string | LinearGradient | RadialGradient
1301
+ strokeStyle?: string
1302
+ }
1303
+ ```
1304
+
1305
+ #### LineTarget
1306
+
1307
+ ```typescript
1308
+ {
1309
+ type: 'line'
1310
+ x: number, y: number, x2: number, y2: number
1311
+ strokeStyle?: string, lineWidth?: number
1312
+ lineCap?: CanvasLineCap
1313
+ }
1314
+ ```
1315
+
1316
+ #### PathTarget
1317
+
1318
+ ```typescript
1319
+ {
1320
+ type: 'path'
1321
+ x: number, y: number, d: string // SVG path data
1322
+ fillStyle?: string | LinearGradient | RadialGradient
1323
+ strokeStyle?: string, lineWidth?: number
1324
+ lineCap?: CanvasLineCap, lineJoin?: CanvasLineJoin
1325
+ }
1326
+ ```
1327
+
1328
+ #### ImageTarget
1329
+
1330
+ ```typescript
1331
+ {
1332
+ type: 'image'
1333
+ x: number, y: number, width: number, height: number
1334
+ image: CanvasImageSource | null
1335
+ opacity?: number
1336
+ }
1337
+ ```
1338
+
1339
+ #### CustomTarget
1340
+
1341
+ Drawn by code, animated by the timeline. The context is translated to `x`/`y`
1342
+ with opacity, transforms, fill, stroke and filters applied, so `draw` works in
1343
+ local coordinates. A track whose property is a key of `props` writes into
1344
+ `props`; base properties (`x`, `opacity`, `rotate`, …) behave as usual.
1345
+
1346
+ ```typescript
1347
+ {
1348
+ type: 'custom'
1349
+ x: number, y: number, width: number, height: number // box = transform pivot
1350
+ draw: (ctx: CanvasRenderingContext2D, target: CustomTarget, time: number) => void
1351
+ props?: Record<string, AnimatableValue> // values tracks may animate
1352
+ opacity?: number, rotate?: number, scale?: number
1353
+ }
1354
+ ```
1355
+
1356
+ ### Gradient Support
1357
+
1358
+ ```typescript
1359
+ interface LinearGradient {
1360
+ type: 'linear'
1361
+ angle: number // Degrees
1362
+ stops: GradientStop[]
1363
+ }
1364
+
1365
+ interface RadialGradient {
1366
+ type: 'radial'
1367
+ centerX: number // 0-1, relative to target
1368
+ centerY: number // 0-1, relative to target
1369
+ radius: number // 0-1, relative to target
1370
+ stops: GradientStop[]
1371
+ }
1372
+
1373
+ interface GradientStop {
1374
+ offset: number // 0-1
1375
+ color: string
1376
+ }
1377
+ ```
1378
+
1379
+ ---
1380
+
1381
+ ## SVGAdapter
1382
+
1383
+ Applies animation state to SVG elements.
1384
+
1385
+ ### Usage
1386
+
1387
+ ```typescript
1388
+ import { SVGAdapter } from '@algorisys/tinyfly/adapters'
1389
+
1390
+ const adapter = new SVGAdapter()
1391
+ const circle = document.querySelector('circle') as SVGElement
1392
+ adapter.registerTarget('ball', circle)
1393
+
1394
+ // In animation loop:
1395
+ adapter.applyState(state)
1396
+ ```
1397
+
1398
+ ### Methods
1399
+
1400
+ Same interface as DOMAdapter:
1401
+
1402
+ | Method | Description |
1403
+ |--------|-------------|
1404
+ | `registerTarget(id, element)` | Register an SVG element |
1405
+ | `unregisterTarget(id)` | Remove a target |
1406
+ | `getTarget(id)` | Get a registered element |
1407
+ | `clearTargets()` | Remove all targets |
1408
+ | `applyState(state)` | Apply state to SVG elements |
1409
+
1410
+ ### Property Mappings
1411
+
1412
+ **SVG attributes** (set via `setAttribute`):
1413
+ - `fill`, `stroke`, `d`, `points`
1414
+ - `x`, `y`, `cx`, `cy`, `r`, `rx`, `ry`
1415
+ - `width`, `height`
1416
+ - `strokeWidth` → `stroke-width`
1417
+ - `borderRadius` → `rx`
1418
+
1419
+ **Transform properties** (set via `style.transform`):
1420
+ - `x`, `y` → `translateX`/`translateY` (for non-positioning elements)
1421
+ - `rotation` → `rotate`
1422
+ - `scale`, `scaleX`, `scaleY` → `scale`
1423
+
1424
+ **Style properties:**
1425
+ - `opacity` → `style.opacity`
1426
+ - `fontSize` → `style.fontSize`
1427
+
1428
+ ---
1429
+
1430
+ ## Export Formats
1431
+
1432
+ The exporters are their own entry point, `@algorisys/tinyfly/export`, so the engine stays
1433
+ small for pages that only play animations (the exporters are about half its size).
1434
+
1435
+ ### CSS Export
1436
+
1437
+ ```typescript
1438
+ import { exportToCSS } from '@algorisys/tinyfly/export'
1439
+
1440
+ interface CSSExportOptions {
1441
+ classPrefix?: string // CSS class prefix (default: 'tinyfly')
1442
+ includeKeyframes?: boolean // Include @keyframes (default: true)
1443
+ includeAnimation?: boolean // Include animation properties (default: true)
1444
+ minify?: boolean // Minify output (default: false)
1445
+ propertyMap?: Record<string, string> // Custom property name mapping
1446
+ }
1447
+
1448
+ interface CSSExportResult {
1449
+ css: string // Full CSS output
1450
+ keyframes: Map<string, string> // Individual @keyframes blocks
1451
+ selectors: Map<string, string> // Individual animation properties
1452
+ }
1453
+
1454
+ const result = exportToCSS(timeline, {
1455
+ classPrefix: 'my-anim',
1456
+ minify: true
1457
+ })
1458
+
1459
+ // result.css contains the full CSS output
1460
+ ```
1461
+
1462
+ Generates standard CSS `@keyframes` animations. Combines transform properties automatically and maps easing to CSS timing functions.
1463
+
1464
+ ### Lottie Export
1465
+
1466
+ ```typescript
1467
+ import { exportToLottie } from '@algorisys/tinyfly/export'
1468
+
1469
+ interface LottieExportOptions {
1470
+ name?: string // Animation name
1471
+ frameRate?: number // Frame rate (default: 60)
1472
+ width?: number // Canvas width (default: 512)
1473
+ height?: number // Canvas height (default: 512)
1474
+ backgroundColor?: string // Background color
1475
+ }
1476
+
1477
+ const lottie = exportToLottie(timeline, {
1478
+ name: 'My Animation',
1479
+ frameRate: 30,
1480
+ width: 800,
1481
+ height: 600
1482
+ })
1483
+
1484
+ // lottie is a bodymovin-compatible JSON object
1485
+ ```
1486
+
1487
+ Exports animations in the Lottie/bodymovin format. Supports position, rotation, scale, and opacity properties.
1488
+
1489
+ ### GIF Export
1490
+
1491
+ ```typescript
1492
+ import { extractFrames } from '@algorisys/tinyfly/export'
1493
+
1494
+ interface GIFExportOptions {
1495
+ width: number
1496
+ height: number
1497
+ frameRate?: number // Default: 30
1498
+ quality?: number // 1-20, lower = better quality
1499
+ backgroundColor?: string
1500
+ loops?: number // 0 = infinite loop
1501
+ renderFrame?: (
1502
+ ctx: CanvasRenderingContext2D,
1503
+ values: Map<string, Map<string, AnimatableValue>>,
1504
+ time: number
1505
+ ) => void
1506
+ }
1507
+
1508
+ interface GIFExportResult {
1509
+ frames: GIFFrame[]
1510
+ duration: number
1511
+ frameCount: number
1512
+ }
1513
+
1514
+ const result = extractFrames(timeline, {
1515
+ width: 400,
1516
+ height: 300,
1517
+ frameRate: 15
1518
+ })
1519
+ ```
1520
+
1521
+ Extracts individual frames from the animation. Use with a GIF encoder library (like gif.js or gifenc) to create the actual GIF file. The `renderFrame` callback lets you customize how each frame is drawn.
1522
+
1523
+ The engine also ships real encoders used by the editor, each taking a
1524
+ `renderFrame` callback:
1525
+
1526
+ ```typescript
1527
+ exportToGIF(timeline: Timeline, options: GIFExportOptions): Promise<Blob>
1528
+ exportToWebP(timeline: Timeline, options: WebPExportOptions): Promise<Blob>
1529
+ ```
1530
+
1531
+ ### Video Export
1532
+
1533
+ ```typescript
1534
+ import { exportVideo, exportToMP4, exportToVideo, getVideoExportFormats, isVideoExportSupported } from '@algorisys/tinyfly/export'
1535
+
1536
+ isVideoExportSupported(): boolean
1537
+ getVideoExportFormats(): VideoExportFormat[] // { id, label, extension, deterministic }, best first
1538
+ exportVideo(options: VideoExportOptions & { format?: string }): Promise<{ blob: Blob; extension: string }>
1539
+ exportToMP4(options: MP4ExportOptions): Promise<Blob>
1540
+ exportToVideo(options: VideoExportOptions): Promise<Blob>
1541
+ ```
1542
+
1543
+ | Function | Description |
1544
+ |----------|-------------|
1545
+ | `isVideoExportSupported` | Whether this environment can export video at all (needs a DOM, and WebCodecs or MediaRecorder) |
1546
+ | `getVideoExportFormats` | Formats this browser can produce: MP4 (H.264) via WebCodecs first (`id: 'mp4-webcodecs'`, deterministic), then MediaRecorder codecs such as WebM VP9/VP8 (real-time) |
1547
+ | `exportVideo` | Export with the format whose `id` you pass, or the best one |
1548
+ | `exportToMP4` | Encode H.264 MP4 with WebCodecs. Not real-time: frames are encoded as fast as possible at exact timestamps. Throws without WebCodecs |
1549
+ | `exportToVideo` | Record with MediaRecorder in real time (a 6s animation takes ~6s). `mimeType` defaults to the best supported codec |
1550
+
1551
+ Shared options: `width`, `height`, `durationMs`, `fps` (default 30), `bitrate`,
1552
+ `background` (default white; `null` keeps transparency),
1553
+ `renderFrame(ctx, timeMs)` (may be async), `onProgress(fraction)` and `signal`
1554
+ (an `AbortSignal`). `exportToMP4` also takes `bitsPerPixel` (default 0.25) and
1555
+ `keyFrameInterval`, and rounds the size up to even numbers. `downloadVideo(blob,
1556
+ filename?)` saves the result.
1557
+
1558
+ `exportToLottieJSON(timeline, options?)` returns `exportToLottie`'s result as a
1559
+ JSON string.
1560
+
1561
+ ### Sprite-sheet layout
1562
+
1563
+ ```typescript
1564
+ import {
1565
+ spriteSheetLayout, frameCell, spriteFrameTimes, spriteSheetMeta
1566
+ } from '@algorisys/tinyfly'
1567
+
1568
+ const layout = spriteSheetLayout(frames, frameWidth, frameHeight, maxColumns) // grid + sheet size
1569
+ const cell = frameCell(index, layout) // { index, col, row, x, y }
1570
+ const times = spriteFrameTimes(frames, durationMs) // even sample times (loop-safe)
1571
+ const meta = spriteSheetMeta(layout, fps, durationMs) // portable JSON metadata
1572
+ ```
1573
+
1574
+ Pure helpers for packing animation frames into a grid PNG and writing matching
1575
+ metadata (frame size, columns/rows, count, fps). The editor's **Sprite** export
1576
+ uses them to render each frame into its cell and download `…-spritesheet.png` +
1577
+ `…-spritesheet.json`. See [sprite-sheet-export.md](sprite-sheet-export.md).
1578
+
1579
+ ---
1580
+
1581
+ ### Captions (SRT / WebVTT)
1582
+
1583
+ ```typescript
1584
+ import { toSRT, toWebVTT, captionCuesFromTimeline } from '@algorisys/tinyfly/export'
1585
+
1586
+ interface CaptionCue { start: number; end: number; text: string } // ms
1587
+
1588
+ toSRT(cues) // "1\n00:00:00,350 --> 00:00:01,750\nMeet the figure.\n…"
1589
+ toWebVTT(cues) // "WEBVTT\n\n00:00:00.350 --> …"
1590
+ captionCuesFromTimeline(definition, { language: 'es' }) // marker → next marker
1591
+ ```
1592
+
1593
+ ---
1594
+
1595
+ ## Headless Video
1596
+
1597
+ Render a scene to MP4 or PNG stills in Node (needs `@napi-rs/canvas` and
1598
+ `ffmpeg`). The guide is [Rendering Video from Code](video-rendering.md).
1599
+
1600
+ ```typescript
1601
+ import { renderVideo, renderStills, FrameRenderer, sceneCaptions } from '@algorisys/tinyfly/headless'
1602
+
1603
+ await renderVideo(scene, { output: 'out.mp4', baseDir, scale, fps, crf, preset, audio, ffmpeg, onProgress })
1604
+ await renderStills(scene, { dir: 'stills', times?: [{ id, time }] }) // default: mid-caption, else mid-marker-step
1605
+
1606
+ const renderer = new FrameRenderer(scene, { scale: 1 }) // no Node API: any 2D context
1607
+ renderer.render(ctx, timeMs)
1608
+ renderer.frameCount; renderer.frameTime(i); renderer.stillTimes()
1609
+ ```
1610
+
1611
+ | `VideoScene` field | Meaning |
1612
+ |---|---|
1613
+ | `width`, `height`, `fps` | Frame size and rate (fps default 30) |
1614
+ | `duration` | ms; defaults to the timeline's duration |
1615
+ | `timeline`, `targets` | A `TimelineDefinition` and the canvas targets it animates |
1616
+ | `background` | Colour, `'transparent'`, or `(ctx, frame) => void` drawn under the targets |
1617
+ | `draw` | `(ctx, frame) => void` drawn over the targets |
1618
+ | `audio`, `fonts` | Soundtrack and font files, relative to `baseDir` |
1619
+ | `captions` | Cues for `--srt` / `--vtt`; default from the timeline's markers |
1620
+ | `bloom` | `true` or `{ threshold, strength, radius, halo, downsample }`: a glow around bright things |
1621
+
1622
+ Loops and glow:
1623
+
1624
+ ```typescript
1625
+ checkLoop(scene, { scale?, fps?, baseDir? }): Promise<LoopReport> // { closure, seam, steps, loops, verdict }
1626
+ psnr(a, b): number; loopReport(frames): LoopReport // pure, on RGBA frames
1627
+
1628
+ // @algorisys/tinyfly/adapters (and the browser bundle): any 2D canvas
1629
+ applyBloom(ctx, { threshold = 0.55, strength = 0.9, radius, halo = 0.6, downsample = 4 })
1630
+ brightPass(rgba, threshold): Float32Array; boxBlur(rgb, width, height, radius): Float32Array
1631
+ ```
1632
+
1633
+ ### Narration audio
1634
+
1635
+ ```typescript
1636
+ voiceNarration(scenes: VoicedScene[], { output, baseDir, sampleRate = 48000, ffmpeg, lead, gap, tail })
1637
+ : Promise<{ plan: NarrationPlan; audio: string }> // lines carry `audio` instead of `duration`
1638
+ decodeAudio(file, { sampleRate, ffmpeg }): Promise<Float32Array> // mono float samples
1639
+ assembleNarration(plan, clips: Float32Array[], sampleRate): Float32Array // pure
1640
+ encodeWav(samples, sampleRate): Uint8Array // pure, 16-bit mono
1641
+ ```
1642
+
1643
+ ### Characters
1644
+
1645
+ `@algorisys/tinyfly/characters` (browser-safe): `StickPose`, `REST_POSE`, `POSES`,
1646
+ `EXPRESSIONS`, `Expression`, `withExpression()`, `pose()`, `blendPose()`, `walkPose()`, `strideLength()`, `talkingMouth()`, `drawStickFigure()`, `rubberLimb()`,
1647
+ `stickFigureTarget()`, `poseTracks()`, joints and costume layers: `stickFigureJoints()`, `resolveStickPose()`, `stickFigureAt()`, `jointsToScene()`, `headPoint()`, `StickStyle.layers`, `StickStyle.shoulderWidth`, the `turn` and `sit` pose fields, `seatHeight()`, `taperedLine()`, `StickStyle.classic` and `StickStyle.headSize`, and the pencil sketch style: `SketchStyle`, `sketchPen()`, `boilFrame()`, erasing: `erasable()`, `withErased()`, `clipErased()`, `scrubPath()`, `drawEraser()`, `partialPath()`, `pointAlong()`, `pathLength()`, and the drawing hand: `drawnPathTarget()`, `drawHand()`, `drawPencil()`, `circlePath()`. See
1648
+ [Rendering Video from Code](video-rendering.md#characters).
1649
+
1650
+ Dance and flips (see [Dance and Flips](dance.md)): the pose fields `leftWrist`/`rightWrist`, `leftAnkle`/`rightAnkle`, `leftFootOut`/`rightFootOut`, `spin`, `rise`; `StickStyle.hands` (cartoon hands), `StickJoints.fingertips`;
1651
+ `DANCE_STYLES`, `DanceStyle`, `DanceMove`, `DanceKey`, `Groove`, `RoutineStep`, `MUDRAS`, `danceFrame()`, `dancePose()`, `danceTaps()`, `danceTravel()`, `danceTravelTrack()`, `stickToHuman()`, `mirrorHumanPose()`, `handProp()`, `DanceTap`, `TapName`, `routineBeats()`, `beatAt()`, `mirrorPose()`, `applyGroove()`, `danceStance()`, `dancer()`, `danceTracks()`, `bakeDanceTracks()`, `stickFigureTarget({ dance })` with the `beat` and `dancing` props, `resolveStickFrame()`;
1652
+ `FLIPS`, `Flip`, `FlipKey`, `flipPose()`, `flipTravel()`, `flipTracks()`; `POSES.sideSplit` and `POSES.frontSplit`.
1653
+
1654
+ ### Beats
1655
+
1656
+ In the engine (`@algorisys/tinyfly`), pure:
1657
+
1658
+ ```typescript
1659
+ interface BeatGrid { bpm: number; offset: number /* ms of a beat */; beatsPerBar?: number }
1660
+ beatLength(grid): number // ms between beats
1661
+ beatTime(grid, n): number // ms of beat n
1662
+ beatAtTime(grid, time): number // which beat (fractional)
1663
+ nearestBeat(grid, time): number
1664
+ nextBeat(grid, time): number
1665
+ beatsBetween(grid, from, to): { time, bar, n }[]
1666
+ detectTempo(samples: Float32Array, sampleRate, { minBpm = 70, maxBpm = 180, maxSeconds = 60 }):
1667
+ { bpm, offset /* ms into the audio */, confidence /* 0..1 */ }
1668
+ ```
1669
+
1670
+ `detectTempo` is deterministic: onset strength from 10 ms loudness frames,
1671
+ autocorrelation for the tempo (gently preferring tempos near 120 to settle
1672
+ half- and double-time), then tempo and phase fitted together over the clip.
1673
+ In Node, feed it `decodeAudio()` samples; the editor decodes clips in the
1674
+ browser.
1675
+
1676
+ ### Narration timing
1677
+
1678
+ In the engine (`@algorisys/tinyfly`):
1679
+
1680
+ ```typescript
1681
+ planNarration(scenes: NarrationScene[], { lead = 350, gap = 300, tail = 550 }): NarrationPlan
1682
+ narrationMarkers(plan): TimelineMarker[] // one per line, labelled with its text
1683
+ narrationSceneAt(plan, time): NarrationSceneTiming | undefined
1684
+ ```
1685
+
1686
+ ---
1687
+
1688
+ ## WebGLAdapter
1689
+
1690
+ A minimal GPU render target: every element is a textured or solid-coloured quad
1691
+ with a transform, opacity and tint. Covers the same ground as the Canvas adapter
1692
+ for moving, scaling, rotating and fading rectangles and images. Paths, text and
1693
+ gradients are out of scope — use the Canvas or SVG adapter for those.
1694
+
1695
+ ```typescript
1696
+ import { WebGLAdapter } from '@algorisys/tinyfly/adapters'
1697
+
1698
+ const gl = canvas.getContext('webgl')!
1699
+ const adapter = new WebGLAdapter(gl)
1700
+
1701
+ adapter.registerTarget('box', { x: 200, y: 100, width: 80, height: 80, fill: '#4f9' })
1702
+
1703
+ timeline.onUpdate = (state) => {
1704
+ adapter.applyState(state)
1705
+ adapter.render()
1706
+ }
1707
+ ```
1708
+
1709
+ Pure helpers `quadMatrix(target, canvasWidth, canvasHeight)` and
1710
+ `parseColor(hex)` are exported for testing and for building your own renderer.
1711
+
1712
+ ---
1713
+
1714
+ ## Inertia Tracks
1715
+
1716
+ A throw: a value released with a velocity that slows under friction and comes to rest.
1717
+
1718
+ ```typescript
1719
+ interface InertiaConfig {
1720
+ from: number
1721
+ velocity: number // units per second at release
1722
+ friction?: number // decay rate per second (default 4)
1723
+ min?: number
1724
+ max?: number
1725
+ end?: number | number[] // snap to multiples of a number, or the nearest listed value
1726
+ restDelta?: number // settle threshold (default: scales with distance)
1727
+ }
1728
+
1729
+ interface InertiaTrack {
1730
+ id: string
1731
+ target: string
1732
+ property: string
1733
+ kind: 'inertia'
1734
+ inertia: InertiaConfig
1735
+ delay?: number; targets?: string[]; stagger?: StaggerConfig
1736
+ }
1737
+ ```
1738
+
1739
+ `x(t) = from + (rest − from)(1 − e^(−friction·t))`, where `rest` is the free
1740
+ throw's stopping point (`from + velocity / friction`), snapped, then clamped to
1741
+ bounds. Settling takes the same time for any distance, like springs.
1742
+
1743
+ ```typescript
1744
+ inertiaValueAt(config, timeMs): number
1745
+ inertiaVelocityAt(config, timeMs): number
1746
+ inertiaRest(config): number // where it comes to rest
1747
+ naturalRest(config): number // where a free throw would stop
1748
+ inertiaDuration(config): number // ms until settled
1749
+ bakeInertiaTrack(track, options?): Track<number>
1750
+ ```
1751
+
1752
+ `Timeline.replaceTrack(id, track)` swaps a track in place — see
1753
+ [Timeline methods](#methods).
1754
+
1755
+ ---
1756
+
1757
+ ## Spring Tracks
1758
+
1759
+ A track whose values come from a physical simulation rather than keyframes.
1760
+
1761
+ ```typescript
1762
+ timeline.addTrack({
1763
+ id: 'pop',
1764
+ target: 'box',
1765
+ property: 'scale',
1766
+ kind: 'spring',
1767
+ spring: { from: 0, to: 1, stiffness: 200, damping: 12, mass: 1, velocity: 0 },
1768
+ })
1769
+ ```
1770
+
1771
+ | Field | Default | Meaning |
1772
+ |---|---|---|
1773
+ | `from` / `to` | — | Start and resting values |
1774
+ | `stiffness` | 180 | Higher is snappier |
1775
+ | `damping` | 12 | Higher settles sooner; 0 oscillates forever |
1776
+ | `mass` | 1 | Higher is more sluggish |
1777
+ | `velocity` | 0 | Initial velocity, units/second |
1778
+ | `restDelta` | 0.01 | Distance from `to` that counts as settled, as a fraction of the travel distance |
1779
+ | `restSpeed` | 0.1 | Speed that counts as settled, as a fraction of the travel distance per second |
1780
+
1781
+ Springs are integrated at a **fixed 1ms timestep from t=0** on every query, so
1782
+ `getValueAtTime` stays a pure function of time: seeking backwards gives the same
1783
+ values as playing forwards, and two runs are byte-identical. The simulation is
1784
+ memoised, so scrubbing is cheap after the first pass. An undamped spring is
1785
+ capped at 60s so its duration stays finite.
1786
+
1787
+ Because the animation is the *parameters*, a spring track serializes like any
1788
+ other track.
1789
+
1790
+ ```typescript
1791
+ import {
1792
+ SpringSampler, springValueAt, springDuration, isUnderdamped, criticalDamping,
1793
+ } from '@algorisys/tinyfly'
1794
+
1795
+ springDuration({ from: 0, to: 100 }) // natural settle time in ms
1796
+ springValueAt({ from: 0, to: 100 }, 120) // value at 120ms
1797
+ isUnderdamped({ from: 0, to: 100, damping: 4 }) // true — it overshoots
1798
+ criticalDamping({ from: 0, to: 100, stiffness: 100, mass: 1 }) // 20
1799
+ ```
1800
+
1801
+ `isUnderdamped` is the closed-form test for whether a spring passes its target
1802
+ before settling (`damping < 2 * sqrt(stiffness * mass)`), so it costs nothing —
1803
+ no simulation needed. Overshoot is usually the point of reaching for a spring,
1804
+ and its absence is the most common reason a "bouncy" one looks flat.
1805
+
1806
+ ### Authoring in the editor
1807
+
1808
+ Add a spring from the **Tracks** panel (**+** → **Add Spring**), then tune it in
1809
+ **Properties**: named feel presets (Gentle, Snappy, Bouncy, Wobbly…), from/to,
1810
+ delay, and sliders for stiffness, damping and mass. The panel shows the settle
1811
+ time and flags whether the spring overshoots.
1812
+
1813
+ The scene extends automatically to fit the settle time — a spring decides its
1814
+ own duration, so a looser one simply takes longer, and without that the tail
1815
+ would be silently cut off.
1816
+
1817
+ ---
1818
+
1819
+ ## Stagger
1820
+
1821
+ One track can drive many targets, each offset in time.
1822
+
1823
+ ```typescript
1824
+ timeline.addTrack(createTrack({
1825
+ id: 'letters',
1826
+ target: 'unused', // ignored when `targets` is present
1827
+ targets: ['l1', 'l2', 'l3'],
1828
+ stagger: { each: 100, from: 'center' },
1829
+ property: 'opacity',
1830
+ keyframes: [{ time: 0, value: 0 }, { time: 500, value: 1 }],
1831
+ }))
1832
+ ```
1833
+
1834
+ | Field | Meaning |
1835
+ |---|---|
1836
+ | `each` | Milliseconds between consecutive targets |
1837
+ | `amount` | Total spread, divided across the targets (wins over `each`) |
1838
+ | `from` | `'start'` (default), `'end'`, `'center'`, `'edges'`, or an index |
1839
+
1840
+ This produces exactly what baking the stagger into N separate tracks would, so
1841
+ either form is valid. **Which to use is a file-size and editability trade-off,
1842
+ not a speed one** — the two evaluate at the same rate (measured; see
1843
+ `stagger-forms.test.ts`), but serialize very differently:
1844
+
1845
+ | Targets | Baked JSON | Runtime JSON |
1846
+ |---|---|---|
1847
+ | 100 | 11,676 bytes | 792 bytes |
1848
+ | 500 | 59,626 bytes | 3,593 bytes |
1849
+
1850
+ Use the **runtime** form when the stagger is uniform and you ship the JSON — a
1851
+ 500-letter split is 59 KB baked and 3.5 KB as one track. Use the **baked** form
1852
+ when each target needs to be tuned individually, which is why the editor's
1853
+ per-letter stagger bakes: it keeps every letter's keyframes draggable.
1854
+
1855
+ Pure helpers, shared by the editor, the engine and the compat facade:
1856
+
1857
+ ```typescript
1858
+ import { staggerOffset, staggerOffsets, staggerSpan, staggerDistance } from '@algorisys/tinyfly'
1859
+
1860
+ staggerOffsets(3, { each: 100 }) // [0, 100, 200]
1861
+ staggerSpan(4, { each: 100 }) // 300 — how far it extends a timeline
1862
+ ```
1863
+
1864
+ ### Track scheduling
1865
+
1866
+ Every track kind also accepts:
1867
+
1868
+ | Field | Meaning |
1869
+ |---|---|
1870
+ | `delay` | Shift every keyframe by this many ms at evaluation time |
1871
+ | `endDelay` | Extra ms held after the last keyframe (extends duration). Keyframe and text tracks |
1872
+
1873
+ ---
1874
+
1875
+ ## Baking
1876
+
1877
+ Turning a computed animation into plain keyframes, for export formats that only
1878
+ understand keyframes (CSS, Lottie) and for eases with no closed form.
1879
+
1880
+ ```typescript
1881
+ import { bakeSpringTrack, bakeEasing, toKeyframedTracks, simplifyKeyframes } from '@algorisys/tinyfly'
1882
+
1883
+ bakeSpringTrack(springTrack, { intervalMs: 1000 / 60, tolerance: 0.01 })
1884
+ bakeEasing(fromKeyframe, toKeyframe, elasticFn, { intervalMs: 16 })
1885
+ toKeyframedTracks(timeline.tracks) // springs baked, everything else untouched
1886
+ ```
1887
+
1888
+ Baking is lossy in file size, not fidelity: sampling a deterministic simulation
1889
+ always produces the same keyframes. `simplifyKeyframes` drops points that lie on
1890
+ a straight line between their neighbours.
1891
+
1892
+ ---
1893
+
1894
+ ## Authoring Values
1895
+
1896
+ Relative and random values are resolved when the timeline is **built**, not when
1897
+ it runs, so what lands in the JSON is a plain number.
1898
+
1899
+ ```typescript
1900
+ import { ValueResolver, resolveValue, resolveSequence, createRandom } from '@algorisys/tinyfly'
1901
+
1902
+ resolveValue('+=100', { base: 50 }) // 150
1903
+ resolveSequence(['+=100', '+=100'], 0) // [100, 200]
1904
+
1905
+ const resolver = new ValueResolver(2024) // the seed
1906
+ resolver.resolve('random(-50, 50)') // same seed → same number, always
1907
+ resolver.seed // store alongside the timeline
1908
+ ```
1909
+
1910
+ Operators: `+=`, `-=`, `*=`, `/=`. Random: `random(min, max)` and
1911
+ `random(min, max, step)`. Non-expression values (numbers, colours, path data)
1912
+ pass through untouched.
1913
+
1914
+ ---
1915
+
1916
+ ## Drivers
1917
+
1918
+ Modules that decide *when* a timeline advances and *to what time*. They may
1919
+ touch the DOM; the engine never imports them. See
1920
+ [scroll-animation.md](scroll-animation.md).
1921
+
1922
+ ```typescript
1923
+ import { VisibilityDriver, ScrollDriver, scrollProgress } from '@algorisys/tinyfly/drivers'
1924
+
1925
+ new VisibilityDriver({ timeline, trigger, behaviour: 'once' }).start()
1926
+ new ScrollDriver({ timeline, trigger, start: 'top bottom', end: 'bottom top', scrub: true }).start()
1927
+ ```
1928
+
1929
+ Both implement `Driver` (`start()`, `stop()`, `destroy()`, each safe to call
1930
+ twice). Drivers only move the playhead: `VisibilityDriver` calls `play()`, so
1931
+ something must still tick the timeline; `ScrollDriver` calls `seek()`, so render
1932
+ in its `onUpdate`.
1933
+
1934
+ ```typescript
1935
+ interface ScrollDriverOptions {
1936
+ timeline?: Timeline // optional: without it, only progress and callbacks
1937
+ trigger: Element
1938
+ start?: TriggerPosition // 'top bottom'
1939
+ end?: TriggerPosition // 'bottom top'; '+=600' / '+=150%' from the start
1940
+ scrub?: boolean | number // true exact; seconds of smoothing
1941
+ pin?: boolean | Element // hold the trigger (or an element) through the range
1942
+ snap?: SnapOption // number | number[] | (p) => number | { snapTo, duration, delay, ease }
1943
+ markers?: boolean | MarkerOptions
1944
+ container?: ContainerAxis // { range(), progress(), shiftAt(progress) } for horizontal triggers
1945
+ scroller?: HTMLElement | null // default: the window
1946
+ onUpdate?: (progress: number, velocity: number) => void // velocity px/s, 0 after scrolling stops
1947
+ onEnter?, onLeave?, onEnterBack?, onLeaveBack?: () => void
1948
+ }
1949
+ ```
1950
+
1951
+ | `ScrollDriver` member | |
1952
+ |---|---|
1953
+ | `progress` / `velocity` | 0..1 through the range / scroll speed in px/s |
1954
+ | `refresh()` | Re-measure (automatic on resize); `sample()` is the same |
1955
+ | `update(scrollPosition?)` | Update from the scroll offset — no layout reads; pass a value to drive it from a virtual scroller |
1956
+ | `ScrollDriver.refreshAll()` | Re-measure every started driver, in start order |
1957
+ | `startOffset` / `endOffset` | The range as scroll offsets |
1958
+ | `destroy()` | Stop and remove any pin spacer |
1959
+
1960
+ `ScrollPin` (also exported) is the sticky-spacer pin the driver uses.
1961
+
1962
+ ```typescript
1963
+ playWhenVisible(options: VisibilityDriverOptions): VisibilityDriver // new VisibilityDriver(options), started
1964
+ scrubOnScroll(options: ScrollDriverOptions): ScrollDriver // new ScrollDriver(options), started
1965
+ ```
1966
+
1967
+ Pure helpers, so trigger geometry can be tested without a browser (`rect` is
1968
+ `{ top, bottom, height }` in viewport coordinates):
1969
+
1970
+ | Function | Returns |
1971
+ |----------|---------|
1972
+ | `parseTrigger(position)` | `{ elementFraction, viewportFraction, offsetPx, absolutePx? }` for a `"<element edge> <viewport edge>"` string or a pixel number |
1973
+ | `triggerDistance(rect, viewportHeight, position)` | Scroll distance in px until the trigger fires; positive means it is still ahead |
1974
+ | `scrollProgress(rect, viewportHeight, start, end)` | Progress between the two triggers, clamped to 0..1 |
1975
+ | `smoothToward(current, target, smoothingSeconds, deltaMs)` | `current` moved toward `target` by exponential smoothing (what `scrub: <seconds>` uses); returns `target` when `smoothingSeconds <= 0` |
1976
+ | `clamp01(value)` | `value` clamped to 0..1 |
1977
+
1978
+ The editor's **⇅ Scroll** preview attaches the same `ScrollDriver` to a real
1979
+ scroll strip, so triggers tuned there behave identically on a page.
1980
+
1981
+ ---
1982
+
1983
+ ## Interaction
1984
+
1985
+ Live input. **Has no serializable representation** — a dragged position is not
1986
+ part of an animation document.
1987
+
1988
+ ```typescript
1989
+ import { Observer, Draggable } from '@algorisys/tinyfly/interaction'
1990
+
1991
+ // Drag to scrub a timeline
1992
+ new Draggable({ target: el, mode: 'scrub', timeline, scrubDistance: 500 }).start()
1993
+
1994
+ // Drag to move, with bounds and snapping
1995
+ new Draggable({ target: el, axis: 'x', bounds: { minX: 0, maxX: 300 }, snap: 25 }).start()
1996
+ ```
1997
+
1998
+ `Observer` normalises pointer, touch and wheel into one `{ deltaX, deltaY,
1999
+ velocityX, velocityY, totalX, totalY, isDragging }` shape.
2000
+
2001
+ Snapping shares the editor stage's math (`snapAxis` / `gridLinesFor`, also
2002
+ exported from this entry point). Pass `snapLinesX` / `snapLinesY` to snap to
2003
+ other elements' edges or guides, and read `draggable.snapLines` — or the
2004
+ `onSnap` callback — to draw a guide for whichever line caught. `snapThreshold`
2005
+ defaults to half the grid size, so a plain `snap: n` behaves like rounding.
2006
+
2007
+ ---
2008
+
2009
+ ## Flip
2010
+
2011
+ FLIP layout transitions, compiled to ordinary keyframes at authoring time.
2012
+
2013
+ ```typescript
2014
+ import { flip, recordFlipState, buildFlipTracks } from '@algorisys/tinyfly/adapters'
2015
+
2016
+ const tracks = flip(
2017
+ [{ name: 'card', element: cardEl }],
2018
+ () => container.classList.add('grid-layout'), // your layout change
2019
+ { duration: 600, easing: 'ease-out' }
2020
+ )
2021
+ tracks.forEach((t) => timeline.addTrack(t))
2022
+ ```
2023
+
2024
+ Measurement happens in the DOM layer, so the engine stays free of live layout
2025
+ reads. The trade-off: the resulting JSON is a snapshot of one specific layout
2026
+ change — recompute it when the layout it was measured against changes.
2027
+
2028
+ ---
2029
+
2030
+ ## GSAP Compat
2031
+
2032
+ A GSAP-flavoured authoring surface that desugars to ordinary tracks. See
2033
+ [gsap-compat.md](gsap-compat.md) for the full mapping table.
2034
+
2035
+ ```typescript
2036
+ import { timeline, quickPlay } from '@algorisys/tinyfly/gsap-compat'
2037
+
2038
+ const tl = timeline()
2039
+ tl.fromTo('box', { x: 0 }, { x: 200, duration: 1, ease: 'power2.out' })
2040
+ tl.to('box', { rotate: 180, duration: 0.5 }, '-=0.25')
2041
+
2042
+ quickPlay({ timeline: tl.timeline, targets: { box: '#box' } })
2043
+ ```
2044
+
2045
+ `quickPlay` also stands alone: it wires a timeline to the DOM and runs the rAF
2046
+ loop, replacing the usual boilerplate.
2047
+
2048
+ ### `live` — play on real elements
2049
+
2050
+ ```typescript
2051
+ import { live, createLive, Stage } from '@algorisys/tinyfly/gsap-compat'
2052
+
2053
+ live.to('.box', { x: 200, duration: 1 }) // → LiveTimeline, already playing
2054
+ live.from(target, vars)
2055
+ live.fromTo(target, fromVars, toVars)
2056
+ live.set(target, vars) // applied on the next microtask
2057
+ live.timeline(options?: LiveTimelineOptions) // chainable .to/.from/.fromTo/.set/.addLabel/.add
2058
+ ```
2059
+
2060
+ `target` is a CSS selector, an `Element`, a plain object, a `NodeList`, or an
2061
+ array of those. A plain object's properties are tweened from its current values
2062
+ and assigned back onto it each frame (for canvas, WebGL or any custom renderer).
2063
+
2064
+ ```typescript
2065
+ live.ticker.add(callback: TickerCallback): void
2066
+ live.ticker.remove(callback: TickerCallback): void
2067
+
2068
+ type TickerCallback = (time: number, deltaTime: number, frame: number) => void
2069
+ ```
2070
+
2071
+ Ticker callbacks run every frame after animations are applied: `time` is seconds
2072
+ since the ticker started, `deltaTime` milliseconds since the last frame. The loop
2073
+ runs while any callback is registered.
2074
+
2075
+ | `LiveTimelineOptions` | |
2076
+ |---|---|
2077
+ | `repeat`, `yoyo`, `repeatDelay`, `timeScale`, `defaults`, `bakeEases`, `onWarning` | As on `timeline()` |
2078
+ | `paused` | Do not autoplay |
2079
+ | `onStart`, `onUpdate`, `onComplete` | Lifecycle callbacks |
2080
+
2081
+ `LiveTimeline` methods: `play()`, `pause()`, `resume()`, `restart()`,
2082
+ `reverse()`, `seek(secondsOrLabel)`, `progress(value?)`, `timeScale(value?)`,
2083
+ `duration()`, `isActive()`, `kill()`, `toDefinition()`. The engine timeline is
2084
+ `.timeline`, the compiled compat timeline `.compat`.
2085
+
2086
+ `createLive(stage?)` binds the same API to a separate `Stage`; `live.stage` is
2087
+ the one the default `live` uses.
2088
+
2089
+ ```typescript
2090
+ live.convertToPath(targets: string | Element | ArrayLike<Element>): Element[]
2091
+ live.draggable(target: TargetInput, options?: LiveDraggableOptions): LiveDraggable
2092
+
2093
+ interface LiveDraggable {
2094
+ readonly draggable: Draggable // the underlying tinyfly/interaction Draggable
2095
+ readonly position: { x: number; y: number } // where the element is now
2096
+ destroy(): void // stop listening and stop any throw in progress
2097
+ }
2098
+ ```
2099
+
2100
+ `convertToPath` replaces basic SVG shapes with equivalent `<path>` elements
2101
+ (selectors resolve within the stage's root) and returns the resulting elements
2102
+ in order. It changes the document. `draggable` options are listed in
2103
+ [gsap-compat.md](gsap-compat.md#inertia-and-dragging); it throws if the target
2104
+ matches nothing.
2105
+
2106
+ ### Springs on `live`
2107
+
2108
+ ```typescript
2109
+ live.to(target, { x: 0, spring: true | SpringPresetName | SpringOptions })
2110
+
2111
+ type SpringPresetName = 'gentle' | 'default' | 'snappy' | 'bouncy' | 'wobbly' | 'stiff'
2112
+ interface SpringOptions {
2113
+ preset?: SpringPresetName
2114
+ stiffness?: number
2115
+ damping?: number
2116
+ mass?: number
2117
+ velocity?: number | Record<string, number> // units/s; unset → the property's current velocity
2118
+ restDelta?: number
2119
+ }
2120
+
2121
+ SPRING_PRESETS: Record<SpringPresetName, { stiffness: number; damping: number; mass: number }> // from tinyfly
2122
+ stage.velocityOf(name, property): number | undefined // units/s from the playing timeline that animates it
2123
+ ```
2124
+
2125
+ Numeric properties compile to spring tracks; the tween lasts until the slowest
2126
+ settles. `CompatTimelineOptions.startVelocity(target, property)` is the hook `live`
2127
+ uses to carry momentum. See [gsap-compat.md](gsap-compat.md#springs).
2128
+
2129
+ ### Line drawing
2130
+
2131
+ ```typescript
2132
+ live.to(shape, { drawSVG: true | false | number | string }) // '60%', '20% 80%', '10 50%'
2133
+
2134
+ drawSegment(value: DrawSvgValue, length: number): [start: number, end: number]
2135
+ drawSvgProperties(value: DrawSvgValue, length: number): { strokeDasharray: [number, number]; strokeDashoffset: number }
2136
+ ```
2137
+
2138
+ `live` measures `getTotalLength()` once per element and compiles to
2139
+ `strokeDasharray` / `strokeDashoffset` tracks. See [gsap-compat.md](gsap-compat.md#line-drawing).
2140
+
2141
+ ### Scroll triggers
2142
+
2143
+ ```typescript
2144
+ live.timeline({ scrollTrigger: ScrollTriggerVars, ...options })
2145
+ live.to(target, { ...vars, scrollTrigger: ScrollTriggerVars })
2146
+ live.scrollTrigger(vars: ScrollTriggerVars & { trigger }): ScrollDriver | undefined
2147
+ live.refreshScroll(): void
2148
+ tl.scrollTrigger: ScrollDriver | undefined // after the next microtask
2149
+ tl.reversed(): boolean
2150
+ tl.invalidate(): LiveTimeline // rebuild from the same calls (function values re-run)
2151
+
2152
+ interface ScrollTriggerVars {
2153
+ trigger?: string | Element
2154
+ start?: TriggerPosition | (() => TriggerPosition) // functions re-run on refresh
2155
+ end?: TriggerPosition | (() => TriggerPosition)
2156
+ invalidateOnRefresh?: boolean // rebuild the animation on every refresh
2157
+ scrub?: boolean | number
2158
+ pin?: boolean | string | Element
2159
+ scroller?: string | HTMLElement
2160
+ toggleActions?: string // 'play none none none'
2161
+ once?: boolean
2162
+ snap?: number | number[] | 'labels' | ((progress: number) => number)
2163
+ | { snapTo, duration?: number | { min, max }, delay?: number, ease?: string }
2164
+ markers?: boolean | { startColor?, endColor?, fontSize?, indent?, id? }
2165
+ containerAnimation?: LiveTimeline // triggers inside a horizontally sliding row
2166
+ onUpdate?: (self: { progress: number; velocity: number; direction: 1 | -1 }) => void
2167
+ onEnter?, onLeave?, onEnterBack?, onLeaveBack?: () => void
2168
+ }
2169
+ ```
2170
+
2171
+ See [gsap-compat.md](gsap-compat.md#scroll-triggers).
2172
+
2173
+ ### Split text
2174
+
2175
+ ```typescript
2176
+ live.splitText(targets: string | Element | ArrayLike<Element>, options?: SplitTextOptions): SplitTextResult
2177
+ splitText(elements: Element[], options?: SplitTextOptions): SplitTextResult // from tinyfly/gsap-compat
2178
+
2179
+ interface SplitTextOptions {
2180
+ type?: string // 'chars,words,lines' (default), any subset
2181
+ mask?: 'chars' | 'words' | 'lines'
2182
+ charsClass?: string // 'char'
2183
+ wordsClass?: string // 'word'
2184
+ linesClass?: string // 'line'
2185
+ aria?: boolean // true: aria-label on the element, aria-hidden on the pieces
2186
+ autoSplit?: boolean // re-split when width changes or fonts load
2187
+ onSplit?: (self: SplitTextResult) => { kill?(): unknown; revert?(): unknown } | void
2188
+ }
2189
+
2190
+ interface SplitTextResult {
2191
+ elements: Element[]
2192
+ chars: HTMLElement[]
2193
+ words: HTMLElement[]
2194
+ lines: HTMLElement[]
2195
+ masks: HTMLElement[]
2196
+ split(): void // re-split now
2197
+ revert(): void
2198
+ }
2199
+ ```
2200
+
2201
+ Lines are measured from layout once, at split time. See
2202
+ [gsap-compat.md](gsap-compat.md#split-text) for what the markup looks like.
2203
+
2204
+ ### Custom eases
2205
+
2206
+ ```typescript
2207
+ // tinyfly (engine): pure generators
2208
+ customEase(definition: string | CubicBezierPoints): { fn: EasingFunction; bezier?: CubicBezierPoints }
2209
+ customBounce(options?: { strength?: number }): EasingFunction
2210
+ customWiggle(options?: { wiggles?: number; type?: 'easeOut' | 'easeInOut' | 'uniform' }): EasingFunction
2211
+
2212
+ // tinyfly/gsap-compat: register by name
2213
+ CustomEase.create(name, definition): string // also live.customEase(name, definition)
2214
+ CustomBounce.create(name, options?): string // live.customBounce
2215
+ CustomWiggle.create(name, options?): string // live.customWiggle
2216
+ registerEase(name, { fn, bezier? }): string
2217
+ ```
2218
+
2219
+ `bakeEasing` ends on the ease's own final value, so an ease that does not end at 1
2220
+ (a wiggle) bakes correctly.
2221
+
2222
+ ### Page transitions
2223
+
2224
+ ```typescript
2225
+ live.pageTransition(options: PageTransitionOptions): Promise<void>
2226
+
2227
+ interface PageTransitionOptions {
2228
+ update: () => void | Promise<void>
2229
+ from?: TargetInput
2230
+ to?: TargetInput | (() => TargetInput)
2231
+ shared?: string // selector; matched by data-flip-id
2232
+ leave?: TweenVars | false // { opacity: 0, y: -16 }
2233
+ enter?: TweenVars | false // { opacity: 0, y: 16 }
2234
+ duration?: number // 0.35 per phase
2235
+ ease?: string // 'power2.inOut'
2236
+ native?: boolean // View Transitions API when available
2237
+ }
2238
+ ```
2239
+
2240
+ ### Image sequences
2241
+
2242
+ ```typescript
2243
+ live.imageSequence(canvas: string | HTMLCanvasElement, options: ImageSequenceOptions): ImageSequence
2244
+
2245
+ interface ImageSequenceOptions {
2246
+ frames: number
2247
+ url: (index: number) => string
2248
+ fit?: 'cover' | 'contain' // 'cover'
2249
+ concurrency?: number // 6
2250
+ onProgress?: (loaded: number, total: number) => void
2251
+ }
2252
+
2253
+ class ImageSequence {
2254
+ frame: number // set it (or tween it) to draw the nearest frame
2255
+ readonly frames: number
2256
+ readonly loaded: number
2257
+ resize(): void
2258
+ destroy(): void
2259
+ }
2260
+ ```
2261
+
2262
+ ### quickTo
2263
+
2264
+ ```typescript
2265
+ live.quickTo(target: TargetInput, property: string, vars?: { duration?: number; ease?: string; spring?: SpringVars }): QuickTo
2266
+
2267
+ interface QuickTo {
2268
+ (value: number): void // animate toward value from the current one; applied next frame
2269
+ readonly tween: LiveTimeline
2270
+ kill(): void
2271
+ }
2272
+ ```
2273
+
2274
+ Defaults: `duration` 0.4, `ease` `'power3.out'`. See [gsap-compat.md](gsap-compat.md#values-that-change-every-event-quickto).
2275
+
2276
+ ### Contexts and media queries
2277
+
2278
+ ```typescript
2279
+ live.context(fn?: (ctx: LiveContext) => unknown, scope?: ParentNode): LiveContext
2280
+ live.matchMedia(scope?: ParentNode): LiveMatchMedia
2281
+
2282
+ class LiveContext {
2283
+ conditions: Record<string, boolean> // set by matchMedia
2284
+ add<T>(fn: () => T): T // run fn collecting; a returned function is cleanup
2285
+ revert(): void // undo everything, restore elements' inline style and SVG d
2286
+ }
2287
+
2288
+ class LiveMatchMedia {
2289
+ add(conditions: string | Record<string, string>, setup: (ctx: LiveContext) => unknown): this
2290
+ revert(): void
2291
+ }
2292
+ ```
2293
+
2294
+ Function values: any non-configuration tween var may be `(index, target) => value`.
2295
+ See [gsap-compat.md](gsap-compat.md#surviving-resizes) and
2296
+ [responsive setups](gsap-compat.md#responsive-setups-reduced-motion-and-cleanup).
2297
+
2298
+ ### Stage
2299
+
2300
+ The shared runtime behind `live`: one frame loop, one DOM adapter, and the
2301
+ values last applied to each element, merged per element so concurrent
2302
+ animations compose.
2303
+
2304
+ ```typescript
2305
+ new Stage(options?: StageOptions)
2306
+
2307
+ interface StageOptions {
2308
+ scheduler?: FrameScheduler // { request(cb): number; cancel(id): void } — default requestAnimationFrame
2309
+ root?: ParentNode // where selectors resolve (default: document)
2310
+ onWarning?: (message: string) => void // warnings from every live timeline on this stage
2311
+ }
2312
+
2313
+ type ObjectTarget = Record<string, unknown>
2314
+ type TargetInput = string | Element | ObjectTarget | ArrayLike<Element> | ReadonlyArray<string | Element | ObjectTarget>
2315
+ ```
2316
+
2317
+ | Member | Description |
2318
+ |--------|-------------|
2319
+ | `root` | The `ParentNode` selectors resolve in (read lazily, so a stage can exist without a document) |
2320
+ | `resolveTargets(input)` | Engine target names for a selector, element, object or list, registering new ones (an element with an `id` is named `#id`, objects `obj-N`) |
2321
+ | `query(selector)` | First matching element within `root` |
2322
+ | `elementFor(name)` | The element registered under a target name |
2323
+ | `objectFor(name)` | The plain object registered under a target name |
2324
+ | `ticker` | `add(callback)` / `remove(callback)`: run after each frame's values are applied; keeps the loop running |
2325
+ | `appliedValue(name, property)` | The last value applied to that property |
2326
+ | `apply(name, values)` | Write values for one target immediately, without a timeline (e.g. while dragging); later tweens start from them |
2327
+ | `render(timeline)` | Apply a timeline's state at its current time, immediately |
2328
+ | `activate(timeline)` / `deactivate(timeline)` | Add a playing timeline to the loop (moving it last, so it wins merges) / remove it, keeping its applied values |
2329
+ | `tick(deltaMs)` | Advance every active timeline and apply the merged result. The loop calls it; call it yourself when you own the loop |
2330
+ | `destroy()` | Stop everything, release elements, and ignore later playback |
2331
+
2332
+ ### Flip
2333
+
2334
+ ```typescript
2335
+ live.getFlipState(targets): LiveFlipState
2336
+ live.flipFrom(state, { duration?, ease?, stagger?, scale?, targets?, enter?, fade?, onComplete? }): LiveTimeline
2337
+ live.flip(targets, change: () => void, vars?): LiveTimeline
2338
+ ```
2339
+
2340
+ Measures where elements appear before a layout change (transforms included) and
2341
+ where they are laid out after (transforms ignored), then animates each from the
2342
+ difference back to rest using centre offsets, plus scale for size changes.
2343
+ Newly visible elements get the `enter` animation — unless they share a
2344
+ `data-flip-id` with a recorded element, in which case they flip from that
2345
+ element's box (`fade: true` cross-fades the two). A flip that starts while
2346
+ another is running takes over each element from where it appears.
2347
+
2348
+ ### Browser bundle
2349
+
2350
+ `@algorisys/tinyfly/browser` (and `lib/browser/tinyfly.iife.js` for `<script>` tags, global
2351
+ `tinyfly`) re-exports the engine, player, drivers, interaction, `tf`, `live`,
2352
+ `Stage` and `quickPlay`, with `to`, `from`, `fromTo`, `set`, `timeline`,
2353
+ `ticker` and `splitText` at the top level bound to `live`.