@algorisys/tinyfly 0.92.0 → 0.93.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +466 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +123 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +2694 -1809
  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 +6498 -5483
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +95 -0
  45. package/lib/types/characters/acting/hand-path.d.ts +32 -0
  46. package/lib/types/characters/acting/index.d.ts +2 -0
  47. package/lib/types/characters/acting/script.d.ts +66 -7
  48. package/lib/types/characters/capabilities.d.ts +50 -0
  49. package/lib/types/characters/code-panel.d.ts +201 -0
  50. package/lib/types/characters/figure-actions.d.ts +11 -0
  51. package/lib/types/characters/figure-props.d.ts +87 -0
  52. package/lib/types/characters/gaits.d.ts +8 -0
  53. package/lib/types/characters/index.d.ts +3 -0
  54. package/lib/types/characters/stick-figure.d.ts +2 -0
  55. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  56. package/lib/types/engine/authoring/index.d.ts +1 -0
  57. package/llms-full.txt +12548 -0
  58. package/llms.txt +57 -0
  59. package/package.json +6 -2
  60. package/skills/tinyfly/SKILL.md +64 -0
  61. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,1241 @@
1
+ # GSAP compatibility layer
2
+
3
+ `@algorisys/tinyfly/gsap-compat` gives GSAP-literate developers a syntax they recognise.
4
+
5
+ **It is familiar, not compatible.** GSAP code will not run unchanged against it,
6
+ and it is not a drop-in replacement. What it does is *desugar* a GSAP-shaped API
7
+ into ordinary tinyfly tracks: every call you make compiles to plain keyframe
8
+ data and is handed to a normal `Timeline`. Anything you author through it opens
9
+ in the editor, exports to JSON, and plays in the standard player.
10
+
11
+ If you want the full picture of what tinyfly can and cannot do relative to GSAP,
12
+ read ["What we deliberately don't do"](#what-we-deliberately-dont-do) at the
13
+ bottom — several of the gaps are principled choices, not missing work.
14
+
15
+ ## Install and import
16
+
17
+ ```ts
18
+ import { tf, timeline } from '@algorisys/tinyfly/gsap-compat'
19
+ ```
20
+
21
+ The engine is a peer import, so you get one copy of `Timeline` whether you
22
+ import `tinyfly`, `@algorisys/tinyfly/gsap-compat`, or both.
23
+
24
+ ## A first animation
25
+
26
+ ```ts
27
+ import { timeline } from '@algorisys/tinyfly/gsap-compat'
28
+ import { quickPlay } from '@algorisys/tinyfly/gsap-compat'
29
+
30
+ const tl = timeline()
31
+ tl.fromTo('box', { x: 0, opacity: 0 }, { x: 200, opacity: 1, duration: 1, ease: 'power2.out' })
32
+ tl.to('box', { rotate: 180, duration: 0.5 }, '-=0.25')
33
+
34
+ quickPlay({ timeline: tl.timeline, targets: { box: '#my-box' } })
35
+ ```
36
+
37
+ `quickPlay` is worth knowing about on its own: it wires a timeline to the DOM
38
+ and runs the rAF loop, replacing the dozen lines of boilerplate every
39
+ hand-written tinyfly example starts with.
40
+
41
+ ## Playing on real elements: `live`
42
+
43
+ > Thirty-three runnable demos are on the Examples page under **GSAP-style**
44
+ > (`/examples?category=gsap`), each with its code and **Copy code**: motion
45
+ > paths and orbits, shape and menu morphs, scrambled and typed text, dashboard
46
+ > stats, Flip layouts (shuffle, filter, layout switch, expand), draggable throws (slots, carousel, swipe cards), friction, stagger,
47
+ > labels, 3D card flips, composition, playback controls, baked eases, and
48
+ > interaction effects like a magnetic button, proximity grid, dock
49
+ > magnification, velocity skew, card stack, infinite marquee, split-text reveal
50
+ > and SVG line drawing.
51
+ >
52
+ > **Doing without `overwrite`.** Interactive effects start a new tween on every
53
+ > pointer move. Keep the returned timeline and `kill()` it before starting the
54
+ > next one on the same element (see *Proximity Grid*), so tweens never pile up.
55
+
56
+ `timeline()` and `tf` *compile*: targets are names, and playback is yours to
57
+ wire. `live` compiles the same way and then plays the result on the page:
58
+
59
+ ```ts
60
+ import { live } from '@algorisys/tinyfly/gsap-compat'
61
+
62
+ live.to('.box', { x: 200, duration: 1, ease: 'power2.out' })
63
+ live.from('.card', { opacity: 0, y: 30, duration: 0.6, stagger: 0.1 })
64
+
65
+ const tl = live.timeline({ repeat: -1, yoyo: true })
66
+ .to('#a', { x: 120, duration: 0.5 })
67
+ .to('#b', { rotate: 180, duration: 0.5 }, '<')
68
+
69
+ tl.pause() // play, pause, resume, restart, reverse, seek, progress, timeScale, kill
70
+ tl.toDefinition() // the same plain JSON the compiler produces
71
+ ```
72
+
73
+ Without a build step, the all-in-one bundle exposes the same functions on a
74
+ global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
75
+
76
+ ```html
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js"></script>
78
+ <script>
79
+ tinyfly.to('.box', { x: 200, duration: 1 })
80
+ </script>
81
+ ```
82
+
83
+ What `live` adds, all of it runtime rather than compilation:
84
+
85
+ | | `timeline()` / `tf` | `live` |
86
+ |---|---|---|
87
+ | Targets | Names | CSS selectors, elements, node lists, or arrays of them |
88
+ | Many matches | — | A selector matching several elements animates all of them; `stagger` fans them out |
89
+ | Playback | You call `quickPlay` or drive `tick()` | Starts on the next microtask; `paused: true` opts out |
90
+ | Return value of `to()` etc. | A tween handle | The timeline, so calls chain |
91
+ | Tween-level `repeat`, `yoyo`, `onStart`, `onUpdate`, `onComplete` | On `timeline()` | Also accepted in `live.to(target, vars)` |
92
+ | Start value of a `to()` | Resolution chain | Resolution chain, with **the value tinyfly last applied to that element** inserted before `defaults` |
93
+
94
+ **Autoplay waits a microtask** so every tween chained synchronously onto a
95
+ timeline is in place before it starts. Calling `play`, `pause`, `seek` or
96
+ `progress` before then takes control, and autoplay is cancelled.
97
+
98
+ **Concurrent animations compose.** Every `live` animation shares one frame loop
99
+ and one DOM adapter, which merges values per element before writing. So
100
+
101
+ ```ts
102
+ live.to('#box', { x: 200, duration: 1 })
103
+ live.to('#box', { rotate: 90, duration: 1 })
104
+ ```
105
+
106
+ moves *and* turns the box. (Two separate `quickPlay` calls would each write a
107
+ `transform` missing the other's property.) When two animations drive the *same*
108
+ property at the same time, the one played most recently wins. A finished
109
+ animation's final values are kept, so later tweens compose with them and start
110
+ from them.
111
+
112
+ **Tweens read the DOM once, when they are built — never per frame.** The start
113
+ value `live` adds comes from what tinyfly last applied. Beyond that, a tween
114
+ reads the page only where GSAP's option names something on the page: a shape's
115
+ current path (`morphSVG`), an element's current text (`text`, `scrambleText`),
116
+ and a path's geometry and the follower's layout (`motionPath` with `align`).
117
+ Whatever it reads is written into the compiled tracks as plain values, so the
118
+ JSON still describes the animation completely. It never reads
119
+ `getComputedStyle`: an element styled by CSS alone starts numeric and colour
120
+ properties from the static defaults, so use `fromTo` for the first tween on
121
+ those.
122
+
123
+ Two features measure the page by design, outside that rule. [Flip](#flip)
124
+ measures layout once per `getFlipState` call and once per `flipFrom` call (which
125
+ `live.flip` makes one each of). `live.draggable` re-measures an element `bounds`
126
+ on each press and follows pointer events for the whole drag. Both still hand the
127
+ engine plain values: Flip compiles to ordinary tweens, and a throw is an ordinary
128
+ inertia tween.
129
+
130
+ **Plain objects are targets too.** Pass any JavaScript object and its
131
+ properties are tweened and assigned straight back onto it — no element, no
132
+ adapter. That is how a canvas, a Three.js scene or a shader uniform follows the
133
+ same timeline as the DOM:
134
+
135
+ ```js
136
+ const scene = { radius: 30, color: '#4a9eff' }
137
+ live.to(scene, { radius: 90, color: '#ec4899', duration: 1.4, ease: 'expo.inOut' })
138
+ live.to(mesh.position, { x: 2, y: 1, duration: 1 }) // Three.js
139
+ live.to(material.uniforms.uProgress, { value: 1, duration: 2 })
140
+ ```
141
+
142
+ Each object starts from its own current values, read when the tween is built.
143
+ Numbers, colour strings and number arrays animate. Arrays and `NodeList`s are
144
+ lists of targets, not objects to animate. Objects and elements mix freely in one
145
+ timeline.
146
+
147
+ **The ticker** runs a callback every frame, after that frame's values are
148
+ applied, with GSAP's arguments — `time` in seconds since the ticker started,
149
+ `deltaTime` in milliseconds, and a `frame` counter:
150
+
151
+ ```js
152
+ const render = (time, deltaTime, frame) => renderer.render(threeScene, camera)
153
+ live.ticker.add(render)
154
+ live.ticker.remove(render)
155
+ ```
156
+
157
+ The frame loop keeps running while any callback is registered, even with no
158
+ animation playing, and stops when the last one is removed. In a script tag it is
159
+ `tinyfly.ticker`.
160
+
161
+ **Separate stages.** `createLive(new Stage())` gives an isolated loop and
162
+ adapter — useful for tests (pass a `scheduler`), or for a widget that should not
163
+ compose with the rest of the page. `new Stage({ root })` resolves selectors inside
164
+ `root` only. `stage.tick(ms)` drives it by hand.
165
+
166
+ **Warnings.** Mistakes that would otherwise do nothing quietly (a selector that
167
+ matches no elements, `drawSVG` on something that isn't a stroked shape, a `spring`
168
+ on a colour, which eases instead) are reported to `onWarning`. Give it to the stage
169
+ to hear about every `live` tween and timeline on it; a timeline's own `onWarning`
170
+ takes precedence:
171
+
172
+ ```js
173
+ const live = createLive(new Stage({ onWarning: (message) => console.warn(message) }))
174
+ live.to('.missing', { x: 100 })
175
+ // gsap-compat: no elements found for target ".missing"
176
+ ```
177
+
178
+ Elements stay registered with the stage once animated. For long-lived single-page
179
+ apps that create and discard many elements, use a `Stage` per view and call
180
+ `stage.destroy()` when the view goes away. It stops everything on that stage,
181
+ releases its elements, and ignores any autoplay still queued.
182
+
183
+ ## Mapping table
184
+
185
+ | GSAP | tinyfly/gsap-compat | Notes |
186
+ |---|---|---|
187
+ | `gsap.to(t, vars)` | `tl.to(t, vars)` | Start value resolved, not read from the DOM — see below |
188
+ | `gsap.from(t, vars)` | `tl.from(t, vars)` | |
189
+ | `gsap.fromTo(t, a, b)` | `tl.fromTo(t, a, b)` | The only form with no implicit start value |
190
+ | `gsap.set(t, vars)` | `tl.set(t, vars)` | Compiles to one held keyframe |
191
+ | `gsap.timeline()` | `timeline()` | |
192
+ | `tl.add(child, pos)` | `tl.add(child, pos)` | Flattened at compile time |
193
+ | `tl.addLabel(name)` | `tl.addLabel(name)` | |
194
+ | Position `"+=1"` / `"-=0.5"` | same | Seconds, relative to the timeline end |
195
+ | Position `"<"` / `">"` | same | Start / end of the previous tween |
196
+ | Position `"<0.2"` / `">+=0.2"` | same | Offset from the previous tween |
197
+ | Position `"label+=1"` | same | |
198
+ | `stagger: 0.1` | same | Compiles to one multi-target track |
199
+ | `stagger: { each, amount, from }` | same | `from`: start/end/center/edges/index |
200
+ | `stagger: { grid, from: 'random' \| [x, y], axis, ease }` | same | Worked out into explicit `stagger.offsets` in the JSON; `grid: 'auto'` reads rows from layout |
201
+ | `keyframes: [...]` / `{ '50%': {...} }` / `{ x: [...] }`, `easeEach` | same (`live`) | Consecutive segment tweens; with `stagger`, each target plays the whole sequence |
202
+ | `Draggable` `type: 'rotation'` | `live.draggable(el, { type: 'rotation' })` | |
203
+ | `ScrollTrigger.batch`, `ScrollToPlugin` | `live.scrollBatch`, `live.scrollTo` / `live.to(window, { scrollTo })` | |
204
+ | `repeat` / `yoyo` | `repeat` / `yoyo` on `timeline()` | → `loop` / `alternate` |
205
+ | `repeatDelay` | `repeatDelay` on `timeline()` | |
206
+ | `timeScale()` | `timeScale()` | → `config.speed` |
207
+ | `progress()` | `progress()` | |
208
+ | `seek(t)` / `seek('label')` | same | Seconds |
209
+ | `play/pause/reverse/restart/kill` | same | |
210
+ | `tl.call(fn, params, pos)` / `tl.addPause(pos, fn)` | same (`live`) | See [Callbacks and control](#callbacks-and-control) |
211
+ | `tl.tweenTo(pos)` / `tl.tweenFromTo(a, b)` | same (`live`) | |
212
+ | `onRepeat`, `onReverseComplete`, tween callbacks inside timelines | same (`live`) | |
213
+ | `gsap.delayedCall` / `gsap.killTweensOf` | `live.delayedCall` / `live.killTweensOf` | |
214
+ | `gsap.utils.*`, `gsap.getProperty` | `live.utils.*`, `live.getProperty` | Seeded random — see [Utilities](#utilities-random-values-and-repeatrefresh) |
215
+ | `"random(-100, 100, 5)"`, `repeatRefresh` | same (`live`) | |
216
+ | Tween `.kill()` | handle returned by `to()` etc. | Removes only that tween's tracks |
217
+ | `motionPath: { path, autoRotate, start, end }` | same | Compiles to a motion-path track — see [Motion paths](#motion-paths) |
218
+ | `motionPath: [{x, y}, …]` + `curviness` | same | Points become a smooth path at build time |
219
+ | `motionPath: { path: '#el', align: '#el', alignOrigin }` | `live` only | Element read once, when the tween is built |
220
+ | `morphSVG: 'M…'` | same | Compiles to a `d` track — see [Shape morphing](#shape-morphing) |
221
+ | `morphSVG: '#shape'` / element | `live` only | Target shape and each element's current shape read when built |
222
+ | `MorphSVGPlugin.convertToPath()` | `live.convertToPath()` | |
223
+ | `text: 'Hi'` / `{ value, rightToLeft }` (TextPlugin) | same | Compiles to a text track — see [Text](#text) |
224
+ | `scrambleText: 'Hi'` / `{ text, chars, revealDelay, speed, tweenLength, rightToLeft }` | same | Seeded, so it replays identically |
225
+ | `inertia: { x: { velocity, min, max, end, resistance } }` | same | Compiles to inertia tracks — see [Inertia](#inertia-and-dragging) |
226
+ | `Draggable.create(el, { inertia: true, bounds, snap })` | `live.draggable(el, { inertia, bounds, snap })` | Throw uses the release velocity |
227
+ | `Flip.getState(t)` / `Flip.from(state, vars)` | `live.getFlipState(t)` / `live.flipFrom(state, vars)` | See [Flip](#flip) |
228
+ | `Flip.fit`, `absolute`, `nested` | — | Not yet; see Flip limits |
229
+ | `rotation`, `rotationZ` / `rotationX` / `rotationY` | same | Become tinyfly's `rotate` / `rotateX` / `rotateY` — see [3D](#3d) |
230
+ | `transformPerspective` | same | The element's own perspective (tinyfly's `perspective`) |
231
+ | `perspective` (on a parent) | same | CSS `perspective` for its children (tinyfly's `childPerspective`) |
232
+ | `z`, `rotateX`, `rotateY`, `rotateZ` | same | tinyfly's names pass through unchanged |
233
+ | — | `quaternion: [x, y, z, w]` | A whole rotation, turned the short way (slerp); starts unrotated |
234
+
235
+ Units: the facade speaks **seconds**, like GSAP. Everything it stores is in
236
+ **milliseconds**, like the engine. The conversion happens at the boundary and
237
+ nowhere else.
238
+
239
+ ## 3D
240
+
241
+ GSAP's transform names work, and so do tinyfly's. They compile to the same
242
+ tracks, so a 3D tween draws the same in the DOM, SVG, Canvas and WebGL (see
243
+ [3D transforms](3d-rotations.md)).
244
+
245
+ ```js
246
+ live.set('.stage', { perspective: 800 }) // the parent's: children share a vanishing point
247
+ live.to('.card', { rotationY: 180, z: 40, duration: 1 }) // = rotateY, z
248
+ live.to('.chip', { rotationX: 60, transformPerspective: 500, duration: 0.6 }) // its own perspective
249
+ live.to('.cube', { quaternion: [0, 0.7071, 0, 0.7071], duration: 1 }) // a whole rotation, slerped
250
+ ```
251
+
252
+ As in GSAP, `perspective` belongs on a parent (CSS `perspective`, DOM only),
253
+ and `transformPerspective` on the element itself. `quaternion` has no GSAP
254
+ equivalent: it turns from any orientation to any other the short way, without
255
+ gimbal lock, and starts unrotated unless `fromTo` says otherwise.
256
+
257
+ ## Easing
258
+
259
+ Most GSAP eases map to an exact built-in or a close cubic-bezier:
260
+
261
+ | GSAP | Result |
262
+ |---|---|
263
+ | `none`, `linear` | `linear` |
264
+ | `power1.*`, `power2.*` | Exact built-ins: `power1` is quad, `power2` is cubic, as in GSAP |
265
+ | `power3.*`, `power4.*`, `sine.*`, `expo.*`, `circ.*`, `back.*` | Cubic-bezier |
266
+ | `elastic.*(amplitude, period)`, `bounce.*`, `back.*(overshoot)` | Parametric ease: `{ type: 'elastic', mode, amplitude, period }` … — exact, one keyframe |
267
+ | `steps(n)` | `{ type: 'steps', count: n + 1, position: 'none' }` — GSAP's n + 1 levels from 0 to 1 |
268
+
269
+ GSAP 2 spellings (`Power2.easeOut`) and bare families (`power2`, which defaults
270
+ to `.out`) are both accepted. An unrecognised name falls back to `ease-out`
271
+ rather than throwing.
272
+
273
+ ### Custom eases
274
+
275
+ Build a curve once, name it, and use the name as an ease anywhere:
276
+
277
+ ```js
278
+ import { CustomEase, CustomBounce, CustomWiggle } from '@algorisys/tinyfly/gsap-compat' // or live.customEase(...)
279
+
280
+ CustomEase.create('hop', 'M0,0 C0.25,0 0.3,1.35 0.55,1.15 C0.75,1 0.85,1 1,1')
281
+ CustomEase.create('snappy', [0.7, 0, 0.9, 0.4]) // bezier points
282
+ CustomBounce.create('drop', { strength: 0.65 })
283
+ CustomWiggle.create('shake', { wiggles: 7, type: 'easeOut' })
284
+
285
+ live.to('.ball', { y: 300, ease: 'drop' })
286
+ live.to('.bell', { rotate: 20, ease: 'shake' }) // swings ±20° and comes back
287
+ ```
288
+
289
+ - **CustomEase** takes SVG path data or bezier points. Path data may be in any
290
+ coordinate space or y direction: x is scaled to run 0 → 1, and y to start at 0
291
+ and end at 1. So a curve copied out of a design tool works as is, and it may
292
+ overshoot.
293
+ - **CustomBounce** drops onto the end value and rebounds. Each bounce keeps part
294
+ of the height, timed like a real ball. `strength` (0–1) sets how lively it is.
295
+ - **CustomWiggle** oscillates around the start value and ends back there (unlike
296
+ other eases). `wiggles` sets the count, and `type` is `'easeOut'` (dying away),
297
+ `'easeInOut'` or `'uniform'`.
298
+ - **Serialization:** a curve that is one cubic-bezier stays an exact, serializable
299
+ easing. Anything else is always sampled into keyframes by the tween that uses
300
+ it, even without `bakeEases`, so the JSON plays without the curve. The generators
301
+ are pure functions in the engine (`customEase`, `customBounce`, `customWiggle`).
302
+
303
+ ### Elastic, bounce, back and steps
304
+
305
+ These overshoot or jump, which no cubic-bezier can do. They compile to the
306
+ engine's **parametric eases** — small, exact JSON evaluated when played — so the
307
+ motion is GSAP's own curve and the keyframe stays editable in the studio:
308
+
309
+ ```js
310
+ live.to('.ball', { y: 300, ease: 'bounce.out' })
311
+ live.to('.card', { scale: 1, ease: 'elastic.out(1.2, 0.4)' }) // → { type: 'elastic', mode: 'out', amplitude: 1.2, period: 0.4 }
312
+ live.to('.clock', { rotate: 360, ease: 'steps(12)' })
313
+ ```
314
+
315
+ A plain `back.*` keeps its cubic-bezier (CSS can play that); `back.out(3)` with an
316
+ overshoot becomes parametric. CSS and Lottie exports sample parametric eases into
317
+ keyframes. For a player that predates them, `timeline({ bakeEases: true })` samples
318
+ them at build time instead.
319
+
320
+ For a real spring rather than an elastic *ease*, use a
321
+ [spring track](#springs) instead; it is one line of parameters rather than a
322
+ hundred baked keyframes.
323
+
324
+ ## The implicit start value
325
+
326
+ This is the single biggest behavioural difference, and it is deliberate.
327
+
328
+ GSAP's `to()` reads the element's current computed style to find where to
329
+ animate *from*. tinyfly cannot: reading live DOM state would make the same
330
+ animation JSON play differently depending on the page's CSS, which breaks the
331
+ determinism the engine is built on.
332
+
333
+ So a start value is resolved in this order:
334
+
335
+ 1. An explicit `from` (i.e. you used `fromTo`) — always wins.
336
+ 2. The last value authored for that target+property on this timeline.
337
+ 3. A `defaults` map passed to `timeline({ defaults })`.
338
+ 4. The documented static default (`opacity: 1`, `x: 0`, `scale: 1`, …).
339
+
340
+ Reaching step 4 is where GSAP users get surprised, so the facade tells you:
341
+
342
+ ```ts
343
+ const tl = timeline({ onWarning: (message) => console.warn(message) })
344
+ tl.to('box', { x: 100, duration: 1 })
345
+ // gsap-compat: no start value for "x" on "box" — using the static default 0.
346
+ // GSAP would read the live DOM here; tinyfly cannot, so pass an explicit
347
+ // fromTo() or a defaults map.
348
+ ```
349
+
350
+ **Recommendation: use `fromTo` for the first tween on any property.** After
351
+ that, step 2 chains naturally and you can use `to` freely.
352
+
353
+ ## What we deliberately don't do
354
+
355
+ These are not on a roadmap. Each conflicts with a principle the project is built
356
+ on, and the alternative given is the principled equivalent.
357
+
358
+ Several of these are now **reopened for consideration** in Phase 27 of
359
+ [todo.md](https://github.com/algorisys-oss/tinyfly/blob/main/todo.md), with designs that resolve values once at load rather than
360
+ per frame — which keeps the JSON a complete description of the animation. The
361
+ reasoning below is still the bar any such proposal has to clear.
362
+
363
+ | Not supported | Why | Instead |
364
+ |---|---|---|
365
+ | Per-frame function values (a value recomputed on every frame) | Cannot serialize; the JSON would not describe the animation | Function values and `"random(…)"` run when a tween is built (and again with `repeatRefresh`); for truly per-frame values use `quickTo` or `ticker.add` |
366
+ | Implicit `getComputedStyle` start values | Breaks determinism | The resolution chain above |
367
+ | `overwrite: 'auto'` | Needs live tween objects mutating each other | `timeline.removeTracks(filter)`, and `findConflicts()` to detect overlaps |
368
+ | Plugins (ScrollTrigger, Draggable, Flip, MorphSVG…) | A plugin system would let arbitrary code into the evaluation path | Built in as first-class features — see below |
369
+ | `quickSetter` | Writes outside the timeline, so nothing could serialize it | `live.quickTo`, which re-aims one real tween |
370
+ | Function eases | Cannot serialize | Named ease, or `{ type: 'cubic-bezier', points }` |
371
+
372
+ ### The plugin equivalents
373
+
374
+ What GSAP sells as plugins, tinyfly ships as ordinary features:
375
+
376
+ | GSAP plugin | tinyfly |
377
+ |---|---|
378
+ | ScrollSmoother | `live.smoothScroll()` — eased wheel scrolling with `data-speed` / `data-lag` parallax, on the page's real scroll position — see [Smooth scrolling](#smooth-scrolling) |
379
+ | ScrollTrigger | `scrollTrigger` on `live` (scrub, pin, toggleActions) — see [Scroll triggers](#scroll-triggers); [`@algorisys/tinyfly/drivers`](./scroll-animation.md) underneath, plus a scroll-scrub preview in the editor |
380
+ | Draggable / Observer | `live.draggable()`, and `@algorisys/tinyfly/interaction` — `Draggable`, `Observer` |
381
+ | InertiaPlugin | The `inertia` tween option and inertia tracks — see [Inertia](#inertia-and-dragging) |
382
+ | Flip | `live.flip()` / `live.getFlipState()` + `live.flipFrom()` — see [Flip](#flip); `flip()` in the DOM adapter for authoring |
383
+ | MorphSVG | The `morphSVG` tween option — see [Shape morphing](#shape-morphing) |
384
+ | MotionPathPlugin | The `motionPath` tween option — see [Motion paths](#motion-paths) |
385
+ | DrawSVG | The `drawSVG` tween option — see [Line drawing](#line-drawing) |
386
+ | SplitText | `live.splitText()` — see [Split text](#split-text); text splitting in the editor |
387
+ | `gsap.ticker` | `live.ticker` — see [Playing on real elements](#playing-on-real-elements-live) |
388
+ | TextPlugin | The `text` tween option — see [Text](#text) |
389
+ | ScrambleTextPlugin | The `scrambleText` tween option — see [Text](#text) |
390
+ | Physics2D | [Spring](#springs) and [inertia](#inertia-and-dragging) tracks — deterministic and serializable |
391
+
392
+ ## Motion paths
393
+
394
+ GSAP's `motionPath` option works on `timeline()`, `tf` and `live`:
395
+
396
+ ```ts
397
+ live.to('.plane', {
398
+ motionPath: { path: '#route', align: '#route', autoRotate: true },
399
+ duration: 3,
400
+ ease: 'power1.inOut',
401
+ })
402
+ ```
403
+
404
+ | Option | Meaning |
405
+ |---|---|
406
+ | `path` | SVG path data, an array of `{ x, y }` points, or (in `live`) a selector / element: `<path>`, `<circle>`, `<ellipse>`, `<rect>`, `<line>`, `<polyline>`, `<polygon>` |
407
+ | `curviness` | For points: `0` straight lines, `1` a natural curve (default), higher bows further |
408
+ | `autoRotate` | `true` to face along the path; a number also adds that many degrees |
409
+ | `start`, `end` | The part of the path to travel, 0–1 (defaults 0 and 1) |
410
+ | `align` | `live` only. Lay the path over an element — `true` for the path element itself — so the follower moves along it where it is drawn |
411
+ | `alignOrigin` | `live` only. The follower's point that sits on the path, as fractions of its size (default `[0.5, 0.5]`) |
412
+
413
+ **How it compiles.** One motion-path track, whose keyframes are progress along
414
+ the path (eased like any other tween, and baked for elastic/bounce when
415
+ `bakeEases` is on). Stagger fans several followers along the same path.
416
+ `from()` travels it backwards.
417
+
418
+ **Without `align`**, path coordinates are x/y offsets from where the follower is
419
+ laid out. **With `align`**, `live` measures once, when the tween is built: the
420
+ path element's position and scale on the page (its screen matrix) and the
421
+ follower's layout box (ignoring its own transform). The result is stored as a
422
+ `matrix` on the track, so the JSON still says exactly where the follower goes.
423
+ If the page re-flows later, build the tween again.
424
+
425
+ Rotation happens about the follower's CSS `transform-origin`. With a non-centre
426
+ `alignOrigin`, set `transform-origin` to match.
427
+
428
+ The parser handles what design tools export: every command, absolute or
429
+ relative, compact numbers (`10-20`, `.5.5`), exponents, and arc flags without
430
+ separators. Followers move at an even speed along curves.
431
+
432
+ ## Shape morphing
433
+
434
+ GSAP's `morphSVG` option works on `timeline()`, `tf` and `live`:
435
+
436
+ ```ts
437
+ const [shape] = live.convertToPath('#circle') // a <circle> has no `d` to animate
438
+ live
439
+ .timeline({ repeat: -1 })
440
+ .to(shape, { morphSVG: '#star', duration: 1 })
441
+ .to(shape, { morphSVG: '#heart', duration: 1 }, '+=0.5')
442
+ ```
443
+
444
+ - **In `live`**, `morphSVG` takes a selector, an element (path or any basic shape)
445
+ or path data. Each element starts from the shape it currently draws, or the
446
+ shape tinyfly last gave it, so chained morphs follow on. Several elements each
447
+ morph from their own shape, and a numeric `stagger` is honoured.
448
+ - **In `timeline()` / `tf`**, `morphSVG` takes path data, and the start must be
449
+ known: `fromTo({ d: … }, { morphSVG: … })`, or an earlier morph on the same
450
+ target. Morphing from nothing throws, with a message saying so.
451
+ - **`live.convertToPath(targets)`** replaces circles, ellipses, rects, lines,
452
+ polylines and polygons with equivalent `<path>` elements, keeping class, fill and
453
+ other attributes. It changes the document, so it is an explicit call.
454
+
455
+ How the engine matches two shapes so the morph looks intentional:
456
+
457
+ | | |
458
+ |---|---|
459
+ | **Start point and direction** | For closed shapes, every rotation of the target's points and both windings are tried; the one that moves points least (about each shape's centre) wins. The equivalent of GSAP's `shapeIndex: "auto"`. |
460
+ | **Corners** | Samples always include every corner of both shapes, so star points and square corners stay sharp mid-morph. |
461
+ | **Holes** | Paths with the same number of subpaths morph subpath-to-subpath, so a letter's counter stays a hole. Otherwise the whole path is one run. |
462
+ | **Open paths** | Stay open; only both directions are tried. |
463
+ | **Ends** | At progress 0 and 1 the original path strings are returned exactly. |
464
+
465
+ Plans are cached per pair of shapes, so the matching runs once; each frame only
466
+ blends points.
467
+
468
+ ## Line drawing
469
+
470
+ `drawSVG` animates how much of an SVG stroke is drawn:
471
+
472
+ ```js
473
+ live.from('.line', { drawSVG: 0, duration: 1 }) // draw in
474
+ live.to('.line', { drawSVG: '40% 60%', duration: 0.6 }) // shrink to the middle
475
+ live.fromTo('path', { drawSVG: '50% 50%' }, { drawSVG: true, stagger: 0.1 }) // grow out from the centre
476
+ ```
477
+
478
+ | Value | Drawn |
479
+ |---|---|
480
+ | `true` / `false` | All of it / none |
481
+ | `120` | The first 120px |
482
+ | `'60%'` | The first 60% |
483
+ | `'20% 80%'`, `'10 50%'` | From one point to the other (px and % mix) |
484
+
485
+ `live` measures each element's length once (`getTotalLength()`), so shapes of
486
+ different lengths draw over the same duration, and compiles the draw to two
487
+ ordinary tracks — `strokeDasharray` as `[visible, length]` and `strokeDashoffset`
488
+ as `-start`. A `to()` on a stroke tinyfly has not drawn starts fully drawn. It
489
+ works on anything with a stroke length: `path`, `line`, `polyline`, `polygon`,
490
+ `circle`, `ellipse`, `rect`. It replaces any dash pattern the element had, and
491
+ with `stroke-linecap: round` an empty segment still shows a dot.
492
+
493
+ `timeline()` / `tf` have no page to measure and throw on `drawSVG`; use
494
+ `drawSvgProperties(value, length)` to get the two values yourself.
495
+
496
+ ## Text
497
+
498
+ GSAP's TextPlugin and ScrambleTextPlugin options work on `timeline()`, `tf` and `live`:
499
+
500
+ ```ts
501
+ live.to('.title', { text: 'Hello world', duration: 1, ease: 'none' }) // types it
502
+ live.to('.title', { text: { value: '', rightToLeft: true }, duration: 0.4 }) // backspaces it
503
+ live.to('.code', { scrambleText: { text: 'granted', chars: 'numbers', revealDelay: 0.3 }, duration: 1 })
504
+ ```
505
+
506
+ | `scrambleText` option | Meaning |
507
+ |---|---|
508
+ | `text` | The text to end on |
509
+ | `chars` | `upperCase` (default), `lowerCase`, `upperAndLowerCase`, `numbers`, or your own characters |
510
+ | `revealDelay` | Seconds before characters start to settle |
511
+ | `speed` | How fast random characters change; 1 = 20 per second |
512
+ | `tweenLength` | Grow or shrink the length over the tween (default `true`) |
513
+ | `rightToLeft` | Settle from the end |
514
+ | `seed` | Fix the random sequence (by default derived from the target and text) |
515
+
516
+ **Where the text starts.** In `live`, from the element's current text (or the
517
+ text tinyfly last set), so chains follow on and each of several elements starts
518
+ from its own. In `timeline()` / `tf`, from the text this timeline last set, or
519
+ empty; `fromTo({ text: … }, …)` sets it explicitly.
520
+
521
+ **Deterministic scramble.** The "random" characters are a hash of the seed, the
522
+ character's position and the refresh step — never `Math.random` — so scrubbing
523
+ backwards shows exactly what playing forwards did, and an exported animation
524
+ scrambles the same everywhere.
525
+
526
+ **How it compiles.** A text track: keyframes are eased progress (0–1), and the
527
+ track's `textConfig` holds the start and end text and the options. The timeline
528
+ turns progress into the string, and adapters set it as the element's text.
529
+ Spaces stay spaces while scrambling, so word shapes remain readable.
530
+
531
+ `text` replaces the element's text content. Markup inside it (spans, links) is
532
+ replaced too; animate an inner element if you need to keep the rest.
533
+
534
+ ## Scroll triggers
535
+
536
+ `scrollTrigger` on `live.timeline()` or a single `live` tween ties it to
537
+ scrolling, with GSAP's option names. It is built on
538
+ [`ScrollDriver`](./scroll-animation.md), so scrolling does no layout reads.
539
+
540
+ ```js
541
+ // Scrub: scroll position is the playhead. Pin the section while it plays.
542
+ live.timeline({
543
+ scrollTrigger: { trigger: '.panels', start: 'top top', end: '+=2000', scrub: 0.5, pin: true },
544
+ })
545
+ .to('.track', { x: -1600, ease: 'none' })
546
+
547
+ // Toggle: play when the card comes into view, reverse when scrolling back above it.
548
+ live.from('.card', {
549
+ y: 60, opacity: 0, duration: 0.8,
550
+ scrollTrigger: { start: 'top 80%', toggleActions: 'play none none reverse' },
551
+ })
552
+
553
+ // No animation: just callbacks, e.g. skew by scroll speed.
554
+ live.scrollTrigger({
555
+ trigger: '.gallery',
556
+ onUpdate: ({ velocity }) => live.to('.gallery img', { skewY: velocity / -300, duration: 0.4 }),
557
+ })
558
+ ```
559
+
560
+ | Option | |
561
+ |---|---|
562
+ | `trigger` | Element or selector; default the animation's first target |
563
+ | `start`, `end` | `"<element edge> <viewport edge>"` as in [trigger positions](./scroll-animation.md#trigger-positions); `end: '+=600'` / `'+=150%'` is measured from the start. Defaults `'top bottom'`, `'bottom top'`. A function is called again on every refresh |
564
+ | `invalidateOnRefresh` | On every refresh (a resize), rebuild the animation so function values and start values are read again |
565
+ | `scrub` | `true`: progress follows scroll exactly. A number: smoothed over that many seconds |
566
+ | `pin` | `true` pins the trigger for the range, or an element / selector to pin instead (see [pinning](./scroll-animation.md#pinning)) |
567
+ | `scroller` | A scrolling element or selector instead of the window |
568
+ | `toggleActions` | Without `scrub`: actions on enter, leave, enter back, leave back — `play`, `pause`, `resume`, `reverse`, `restart`, `reset`, `complete` or `none`. Default `'play none none none'` |
569
+ | `once` | Stop watching after the first enter |
570
+ | `snap` | After scrolling stops inside the range, scroll on to the nearest point: a progress step (`1 / 3`), progress points (`[0, 0.4, 1]`), `'labels'`, a function, or `{ snapTo, duration, delay, ease }` |
571
+ | `markers` | Draw start / end lines while developing: `true`, or `{ startColor, endColor, fontSize, indent, id }` |
572
+ | `containerAnimation` | The animation sliding this trigger's row sideways; start and end become horizontal (`'left right'` → `'right left'`) |
573
+ | `onUpdate(self)` | `self` is `{ progress, velocity, direction }`; velocity in px/s, back to 0 when scrolling stops |
574
+ | `onEnter`, `onLeave`, `onEnterBack`, `onLeaveBack` | Edge callbacks |
575
+
576
+ A timeline with `scrollTrigger` does not autoplay, and without `scrub` it shows its
577
+ starting state straight away, so a `from()` reveal never flashes its end state.
578
+ The trigger attaches on the next microtask, after the tweens chained onto the
579
+ timeline. `tl.scrollTrigger` is the driver (`refresh()`, `progress`, `velocity`);
580
+ `tl.kill()` removes it and its pin, as does destroying the stage.
581
+ `live.refreshScroll()` re-measures every trigger after a layout change a resize
582
+ would not catch.
583
+
584
+ On touch devices, resizes that only change the height a little (the address bar
585
+ showing and hiding) do not refresh, so pins do not jump mid-scroll.
586
+
587
+ - **`pinSpacing: false`** pins without pushing later content down; it scrolls up
588
+ underneath the pinned element.
589
+ - **`horizontal: true`** is for a scroller that scrolls sideways. Positions use `left`
590
+ / `right` (`start: 'left right'`), progress follows `scrollLeft`, and pins hold
591
+ horizontally. Markers are vertical only.
592
+ - **`anticipatePin` isn't needed.** Pins use `position: sticky`, so the browser holds
593
+ them on the compositor, with no hand-off frame where a pin could lag behind fast
594
+ scrolling.
595
+
596
+ ### Batches and scrolling to a place
597
+
598
+ ```js
599
+ // Cards that enter together animate together (GSAP's ScrollTrigger.batch).
600
+ live.scrollBatch('.card', {
601
+ start: 'top 85%',
602
+ interval: 0.1, // seconds to collect elements that cross together
603
+ batchMax: 6,
604
+ onEnter: (cards) => live.from(cards, { y: 40, opacity: 0, stagger: 0.08 }),
605
+ })
606
+
607
+ // Scroll as an animation (GSAP's ScrollToPlugin).
608
+ live.scrollTo('#pricing', { duration: 1, offset: 80, ease: 'power2.inOut' })
609
+ live.to(window, { scrollTo: { y: '#pricing', offsetY: 80 }, duration: 1 })
610
+ live.scrollTo('max') // the bottom
611
+ live.scrollTo({ x: 600 }, { scroller: '.gallery' })
612
+ ```
613
+
614
+ `scrollTo` measures the destination once, at the start. It is an ordinary live
615
+ timeline, so it can be killed and takes callbacks. Wheel, touch or key input stops
616
+ it (`autoKill: false` to keep going). With `live.smoothScroll()` running,
617
+ `smoother.scrollTo()` does the same and keeps smoothing afterwards.
618
+
619
+ ### Snapping, markers and horizontal sections
620
+
621
+ **Snap** runs after scrolling stops inside the range. It uses the speed scrolling
622
+ had just before stopping, so a flick carries on to the next point instead of
623
+ falling back. It then animates the scroll offset and gives way at once to a wheel,
624
+ touch, click or key. With `'labels'` it snaps to the timeline's labels, read at
625
+ snap time so a rebuilt timeline's labels count.
626
+
627
+ **Markers** show where a range starts and ends. Green and red lines are fixed to
628
+ the viewport where the element points fire, and matching markers sit on the page
629
+ at the element points. The range is active between the moments each page marker
630
+ crosses its line. Remove `markers` before shipping.
631
+
632
+ **`containerAnimation`** handles the classic pinned horizontal section, where
633
+ items inside the sliding row need their own triggers:
634
+
635
+ ```js
636
+ const row = live
637
+ .timeline({ scrollTrigger: { trigger: '.work', start: 'top top', end: () => `+=${travel()}`, pin: true, scrub: true, snap: 1 / 3 } })
638
+ .to('.track', { x: () => -travel(), ease: 'none' })
639
+
640
+ document.querySelectorAll('.panel').forEach((panel) => {
641
+ live.from(panel.querySelector('h3'), {
642
+ y: 20, opacity: 0,
643
+ scrollTrigger: { trigger: panel, containerAnimation: row, start: 'left 80%', toggleActions: 'play none none reverse' },
644
+ })
645
+ })
646
+ ```
647
+
648
+ The trigger's horizontal positions are solved against the row's own motion (the
649
+ `x` tracks moving its ancestors), and turned into the row's vertical scroll range.
650
+ Create the row's timeline first, keep its motion steady in one direction (an
651
+ `ease: 'none'` slide is the usual case), and don't pin inside it.
652
+
653
+ ## Callbacks and control
654
+
655
+ Callbacks are runtime behaviour, like `onComplete`: they are not part of the JSON.
656
+ On `live` timelines they fire when the playhead **crosses** their time, whether it
657
+ is playing, looping, yoyoing or being scrubbed with `progress()` (so a scroll scrub
658
+ runs them). A `seek()` jumps without firing, as in GSAP.
659
+
660
+ ```js
661
+ const tl = live.timeline({ onRepeat: () => …, onReverseComplete: () => … })
662
+ .to('.intro', { opacity: 1, onStart: () => …, onComplete: () => … })
663
+ .call(showMenu, [menu]) // at the end so far; any position works
664
+ .addPause('+=0.5', () => waitForClick()) // stops exactly there; tl.play() continues
665
+ .addLabel('details')
666
+ .to('.details', { y: 0 })
667
+
668
+ tl.tweenTo('details', { duration: 0.8, ease: 'power2.inOut' }) // animates the playhead
669
+ live.delayedCall(2, hideToast) // a call on the stage's clock; kill() cancels
670
+ live.killTweensOf('.card', 'x,y') // stop what moves these, in every timeline
671
+ ```
672
+
673
+ - **Order.** Callbacks at the same time run in the order they were added. A frame
674
+ that crosses a loop runs the rest of that loop's callbacks, then `onRepeat`, then
675
+ the next loop's.
676
+ - **Tween callbacks** inside a timeline run at that tween's own start and end
677
+ (forward). `onUpdate` runs on every frame whose movement overlaps the tween.
678
+ - **`call` and `addPause`** take no time, but one placed after the last tween makes
679
+ the timeline long enough to reach it.
680
+ - **`onComplete` / `onReverseComplete`.** Arriving back at the start after
681
+ `reverse()` calls `onReverseComplete`, not `onComplete`.
682
+ - **`tweenTo` / `tweenFromTo`** pause the timeline and return the tween moving the
683
+ playhead. Its default duration is the distance at the timeline's own speed, with
684
+ `ease: 'none'`.
685
+ - **`killTweensOf`** removes only the matching properties when given. A staggered
686
+ tween on several elements is one track, so it stops for all of them.
687
+ - Callbacks run after the frame is applied, so they read this frame's values.
688
+
689
+ ## Smooth scrolling
690
+
691
+ `live.smoothScroll()` eases wheel scrolling, like GSAP's ScrollSmoother, and adds
692
+ parallax layers:
693
+
694
+ ```js
695
+ const smoother = live.smoothScroll({ smooth: 0.9, effects: true })
696
+
697
+ // <h2 data-speed="0.8"> scrolls at 80% of the page's speed
698
+ // <img data-lag="0.3"> catches up with the page 0.3s after it moves
699
+
700
+ smoother.scrollTo('#contact', { offset: -80 }) // anchor links, eased
701
+ smoother.paused(true) // e.g. while a modal is open
702
+ ```
703
+
704
+ It does not move the page inside a transformed wrapper, as ScrollSmoother does.
705
+ Wheel input is eased, but the browser's **own scroll position** is what moves. So:
706
+
707
+ - scroll triggers, pins (`position: sticky`), `position: fixed`, anchor links,
708
+ find-in-page and scroll restoration all work unchanged;
709
+ - touch, keyboard and scrollbar scrolling stay native, and smoothing continues
710
+ from wherever they leave the page;
711
+ - pinch-zoom, sideways wheels and scrollable areas inside the page keep their own
712
+ scrolling (mark any other area `data-smooth-ignore`).
713
+
714
+ | Option | Default | |
715
+ |---|---|---|
716
+ | `smooth` | `0.8` | Seconds to catch up with the wheel; `0` turns smoothing off |
717
+ | `wheelMultiplier` | `1` | Scales wheel distance |
718
+ | `effects` | `false` | `true` for `[data-speed], [data-lag]`, or your own selector |
719
+ | `scroller` | the window | A scrolling element or selector |
720
+ | `reducedMotion` | the system setting | With reduced motion there is no smoothing and no effects |
721
+ | `onUpdate(state)` | — | `{ scroll, target, progress, velocity }` after each moving frame |
722
+
723
+ - **`data-speed`**: the element sits at its natural place when centred in the
724
+ viewport, and drifts by `(1 − speed)` of the scroll distance either side of it.
725
+ - **Effects** are written to the CSS `translate` property, so they combine with
726
+ tweens on `transform`. Don't put them on a scroll trigger's `trigger` element;
727
+ put them on a child.
728
+ - **Re-measuring**: effects are measured again whenever scroll triggers re-measure
729
+ (on resize and `live.refreshScroll()`), with the layers at rest while triggers
730
+ measure, and after pins have changed the layout.
731
+ - `smoother.state`, `smoother.refresh()`, and `smoother.kill()`. Contexts and
732
+ `matchMedia` kill it on revert.
733
+
734
+ The [Agency Landing Page showcase](../src/examples/showcases/agency-landing.js) turns
735
+ it on outside reduced motion, alongside its pinned sections.
736
+
737
+ ## Values that change every event: `quickTo`
738
+
739
+ Pointer followers, magnetic buttons and scroll-velocity effects change a value on
740
+ every event. Creating a tween per event works, but it allocates on every move and
741
+ leaves overlapping tweens to compose. `live.quickTo` makes one reusable tween per
742
+ property instead:
743
+
744
+ ```js
745
+ const moveX = live.quickTo('.cursor', 'x', { duration: 0.5, ease: 'power3.out' })
746
+ const moveY = live.quickTo('.cursor', 'y', { duration: 0.5, ease: 'power3.out' })
747
+ window.addEventListener('pointermove', (e) => { moveX(e.clientX); moveY(e.clientY) })
748
+
749
+ const pull = live.quickTo(button, 'x', { spring: 'snappy' }) // springs keep their momentum
750
+ ```
751
+
752
+ - Each call re-targets the tween from the value on screen now, so there is no jump.
753
+ - Nothing is written until the next frame, so several calls in one frame cost
754
+ one write.
755
+ - With `spring`, each re-target carries the current velocity.
756
+ - The setter uses the first element the target matches. `moveX.tween` is the
757
+ reused timeline, and `moveX.kill()` stops it.
758
+
759
+ ## Surviving resizes
760
+
761
+ Anything measured from the page — a pinned section's travel, a marquee's width —
762
+ changes when the window resizes or a phone rotates. Pass **functions** instead of
763
+ numbers and they are called again whenever the animation is rebuilt:
764
+
765
+ ```js
766
+ const travel = () => track.scrollWidth - section.clientWidth
767
+
768
+ live.timeline({
769
+ scrollTrigger: { trigger: section, start: 'top top', end: () => `+=${travel()}`, pin: true, scrub: 0.5, invalidateOnRefresh: true },
770
+ })
771
+ .to(track, { x: () => -travel(), ease: 'none' })
772
+ ```
773
+
774
+ - **Function values** in tween vars are called with `(index, target)` when the
775
+ tween is built. When they differ per target, each target gets its own tween.
776
+ - **`tl.invalidate()`** rebuilds a timeline from the same calls. It rewinds to
777
+ the start, so start values are read from elements before the timeline changed
778
+ them, re-runs every function value, and returns to the same progress. Call it
779
+ yourself for animations without a scroll trigger, e.g. on `resize`.
780
+ - **`invalidateOnRefresh: true`** does that on every scroll refresh, before start
781
+ and end are measured again.
782
+
783
+ ## Responsive setups, reduced motion and cleanup
784
+
785
+ **`live.context(fn, scope?)`** collects everything the live API creates while `fn`
786
+ runs:
787
+
788
+ - timelines and tweens, with their scroll triggers and pins;
789
+ - split text and draggables;
790
+ - stand-alone scroll triggers and ticker callbacks;
791
+ - a cleanup function `fn` returns.
792
+
793
+ `ctx.revert()` undoes it all, newest first. Each element the context animated
794
+ gets its original inline style (and SVG `d`) back, and the stage forgets the
795
+ values it applied, so the next setup starts clean. Selectors inside resolve
796
+ within `scope`. That suits a component or a route: create the context on mount
797
+ and revert it on unmount.
798
+
799
+ ```js
800
+ const ctx = live.context(() => {
801
+ live.from('.card', { y: 40, opacity: 0, stagger: 0.1 })
802
+ button.addEventListener('click', () => ctx.add(() => live.to('.card', { rotate: 5 })))
803
+ }, section)
804
+
805
+ ctx.revert()
806
+ ```
807
+
808
+ Work created later, for example in an event handler, joins the context only when
809
+ it runs inside `ctx.add(fn)`.
810
+
811
+ **`live.matchMedia()`** runs setups while media queries match:
812
+
813
+ ```js
814
+ const mm = live.matchMedia()
815
+ mm.add({ desktop: '(min-width: 800px)', reduce: '(prefers-reduced-motion: reduce)' }, (ctx) => {
816
+ const { desktop, reduce } = ctx.conditions
817
+ if (reduce) return live.set('.hero-title', { opacity: 1 }) // a real reduced-motion mode
818
+ live.timeline({ scrollTrigger: { pin: desktop, … } })
819
+ return () => { /* anything else to undo */ }
820
+ })
821
+ ```
822
+
823
+ - Each setup runs in its own context while any of its queries match.
824
+ - It is reverted when they stop matching, and run again whenever the set of
825
+ matching conditions changes; `ctx.conditions` says which match.
826
+ - `mm.revert()` removes every setup and stops listening.
827
+
828
+ The [Agency Landing Page showcase](../src/examples/showcases/agency-landing.js)
829
+ wraps its whole page this way. Under reduced motion there is no pinning, parallax
830
+ or marquee, and values appear at their final state.
831
+
832
+ ### Framework hooks
833
+
834
+ Each wrapper runs a setup inside `live.context()`, scoped to a component's element.
835
+ It reverts everything the setup made (tweens, scroll triggers and pins, split text,
836
+ draggables, smooth scrolling) when the component goes away:
837
+
838
+ ```jsx
839
+ // React
840
+ import { useTinyfly } from '@algorisys/tinyfly/react'
841
+ const root = useRef(null)
842
+ const { contextSafe } = useTinyfly((live) => {
843
+ live.from('.title', { y: 40, opacity: 0 })
844
+ }, { scope: root, dependencies: [lang] }) // re-run (after reverting) when lang changes
845
+ const onClick = contextSafe(() => live.to('.cta', { scale: 1.1 })) // handlers join the context
846
+ ```
847
+
848
+ ```js
849
+ // Vue (<script setup>)
850
+ import { useTinyfly } from '@algorisys/tinyfly/vue'
851
+ const root = ref(null)
852
+ useTinyfly((live) => live.from('.title', { y: 40, opacity: 0 }), { scope: root, watch: [lang] })
853
+ ```
854
+
855
+ ```svelte
856
+ <!-- Svelte: an action, no import from svelte needed -->
857
+ <script>import { tinyfly } from '@algorisys/tinyfly/svelte'</script>
858
+ <section use:tinyfly={(live) => live.from('.title', { y: 40, opacity: 0 })}>…</section>
859
+ ```
860
+
861
+ ```jsx
862
+ // Solid
863
+ import { createTinyfly } from '@algorisys/tinyfly/solid'
864
+ let root
865
+ createTinyfly((live) => live.from('.title', { y: 40, opacity: 0 }), () => root)
866
+ ```
867
+
868
+ The frameworks are optional peer dependencies, and each wrapper is under 1 KB. All
869
+ of them use the shared `live` from `@algorisys/tinyfly/gsap-compat`; pass `live` (the
870
+ `options.live` field, or the last argument for Svelte and Solid) to use a stage of
871
+ your own.
872
+
873
+ ## Page transitions
874
+
875
+ `live.pageTransition` animates a client-side route change. It plays the old view
876
+ out, runs your `update` (render the next route; it may return a promise), carries
877
+ shared elements across by `data-flip-id`, and plays the new view in. It resolves
878
+ when everything has finished:
879
+
880
+ ```js
881
+ router.onNavigate(async (next) => {
882
+ await live.pageTransition({
883
+ from: '.page',
884
+ to: '.page',
885
+ shared: '[data-flip-id]', // a thumbnail on one page, the hero on the next
886
+ update: () => render(next),
887
+ })
888
+ })
889
+ ```
890
+
891
+ | Option | Default | |
892
+ |---|---|---|
893
+ | `update` | — | Change the page; may be async |
894
+ | `from`, `to` | — | The leaving and arriving views (`to` is resolved after `update`; a function is fine) |
895
+ | `shared` | — | Selector for elements matched across by `data-flip-id` |
896
+ | `leave`, `enter` | fade + 16px lift / drop | The values the old view goes to and the new view comes from, or `false` |
897
+ | `duration`, `ease` | `0.35`, `'power2.inOut'` | Per phase; shared elements take 1.4× the duration |
898
+ | `native` | `false` | Hand the change to the browser's View Transitions API when it has one |
899
+
900
+ - **Shared elements travel on their own.** When `shared` is given, `leave` and
901
+ `enter` animate the view's children that neither are nor contain a shared
902
+ element. Moving the whole view would drag the shared elements along.
903
+ - **Native mode.** Shared elements get `view-transition-name`s from their flip
904
+ ids and the browser runs the transition. Browsers without the API get the
905
+ tinyfly version, so the call works everywhere.
906
+ - **Scope.** It is for changes within one document, such as a client-side
907
+ router; a full page load starts a new document.
908
+
909
+ ## Image sequences
910
+
911
+ `live.imageSequence` draws one frame of a numbered image sequence into a canvas.
912
+ Its `frame` is an ordinary number, so a tween or a scroll scrub turns the object:
913
+
914
+ ```js
915
+ const phone = live.imageSequence('canvas.phone', {
916
+ frames: 120,
917
+ url: (i) => `/frames/phone_${String(i + 1).padStart(4, '0')}.webp`,
918
+ })
919
+
920
+ live.to(phone, {
921
+ frame: phone.frames - 1,
922
+ ease: 'none',
923
+ scrollTrigger: { trigger: '.product', start: 'top top', end: '+=2000', scrub: true, pin: true },
924
+ })
925
+ ```
926
+
927
+ | Option | |
928
+ |---|---|
929
+ | `frames`, `url(index)` | How many frames, and where frame `index` (0-based) is |
930
+ | `fit` | `'cover'` (default) or `'contain'` |
931
+ | `concurrency` | Images loading at once (default 6) |
932
+ | `onProgress(loaded, total)` | Called as frames arrive |
933
+
934
+ - **Loading.** The first frame loads straight away. The rest load a few at a
935
+ time, nearest the frame on screen first. Until a frame arrives, the nearest
936
+ loaded one is drawn, so scrubbing ahead of the network never shows a blank
937
+ canvas.
938
+ - **Drawing.** Setting `frame` draws the nearest whole frame, and only when it
939
+ changes. The canvas is sized to its box at the device pixel ratio (capped at
940
+ 2) and resized with the window.
941
+ - **Cleanup.** `sequence.destroy()` stops loading. Contexts and matchMedia
942
+ setups do this for you.
943
+
944
+ ## Split text
945
+
946
+ `live.splitText` wraps text in spans so characters, words or lines can be
947
+ animated one after another (GSAP's SplitText):
948
+
949
+ ```js
950
+ const split = live.splitText('.headline', { type: 'lines', mask: 'lines' })
951
+ live.fromTo(split.lines, { y: 40 }, { y: 0, duration: 0.9, ease: 'expo.out', stagger: 0.12 })
952
+
953
+ const title = live.splitText('.title', { type: 'words,chars' })
954
+ live.from(title.chars, { opacity: 0, y: 30, rotateX: -90, stagger: 0.03 })
955
+
956
+ split.revert() // the original markup
957
+ ```
958
+
959
+ | Option | Default | |
960
+ |---|---|---|
961
+ | `type` | `'chars,words,lines'` | Which pieces to create, comma-separated |
962
+ | `mask` | — | `'lines'`, `'words'` or `'chars'`: wrap each in an `overflow: clip` span, for reveals from behind an edge. Masks leave 0.12em below the baseline (with a matching negative margin) so descenders aren't clipped |
963
+ | `charsClass`, `wordsClass`, `linesClass` | `char`, `word`, `line` | Class names (masks get `<class>-mask`) |
964
+ | `aria` | `true` | Put the text in the element's `aria-label` and hide the pieces from screen readers |
965
+ | `autoSplit` | `false` | Split again when an element's width changes or fonts load |
966
+ | `onSplit(self)` | — | Called after every split; return the animation built on the pieces |
967
+
968
+ It returns `{ elements, chars, words, lines, masks, revert() }`.
969
+
970
+ What it does to the markup:
971
+
972
+ - **Words** become inline-block spans, so they can move and never break in the
973
+ middle. Spaces stay as real text between them, so the text still wraps,
974
+ selects and copies normally. Words are wrapped even when you only ask for
975
+ `chars` or `lines` (they just aren't returned or classed).
976
+ - **Characters** are grapheme clusters, so an emoji or an accented letter stays in one piece.
977
+ - **Lines** are measured once, from where the browser wrapped the words. Inline
978
+ markup such as `<em>` or `<a>` is kept and cloned into each line it spans;
979
+ `<br>` ends a line. Lines depend on the element's width: with `autoSplit: true`
980
+ the text is split again when an element's width changes or web fonts finish
981
+ loading. Build the animation in `onSplit(self)` and return it, so it is killed
982
+ before the pieces it animated are replaced. `split.split()` re-splits by hand.
983
+ - `revert()` restores the saved HTML. Event listeners attached to elements
984
+ *inside* the split element are lost; attach them to the element itself.
985
+
986
+ ## Flip
987
+
988
+ Animate elements from where they were to where a layout change put them:
989
+
990
+ ```ts
991
+ live.flip('.item', () => grid.classList.toggle('compact'), { duration: 0.6, ease: 'power2.inOut', stagger: 0.03 })
992
+
993
+ // Or in two steps, when the change happens elsewhere:
994
+ const state = live.getFlipState('.item')
995
+ renderNewOrder()
996
+ live.flipFrom(state, { duration: 0.5, targets: '.item' })
997
+ ```
998
+
999
+ | Option | Meaning |
1000
+ |---|---|
1001
+ | `duration`, `ease` | As for any tween (default 0.6s, `power2.inOut`) |
1002
+ | `stagger` | Seconds between elements, in document order |
1003
+ | `scale` | Animate size changes with scaleX/scaleY (default `true`); `false` moves only |
1004
+ | `targets` | Elements that may have appeared in the change (`live.flip` passes its own) |
1005
+ | `enter` | Start values for newly visible elements (default `{ opacity: 0, scale: 0.6 }`), or `false` |
1006
+ | `fade` | Cross-fade shared elements (below): the incoming one fades in, the one it replaces fades out if still shown |
1007
+ | `onComplete` | Called when it finishes |
1008
+
1009
+ Any change works: reorder the DOM, toggle classes, hide and show, resize.
1010
+
1011
+ **How it measures.** Before the change, where each element *appears*, including
1012
+ the transform it may be animating with. After, where it is *laid out*, ignoring
1013
+ transforms. Offsets are between centres, since scale happens about the centre.
1014
+ Each element then gets an ordinary `fromTo` back to rest, so the result is plain
1015
+ track data.
1016
+
1017
+ **Interrupting is smooth.** Starting a flip while another is running takes over
1018
+ each element from where it appears right now.
1019
+
1020
+ **Shared elements.** Give two different elements the same `data-flip-id` and
1021
+ they are treated as one thing: an element that was not recorded, but whose flip
1022
+ id was, flips from where the recorded element was. That is how a gallery
1023
+ thumbnail grows into a detail view's hero image, which is a separate element:
1024
+
1025
+ ```js
1026
+ thumb.addEventListener('click', () => {
1027
+ const state = live.getFlipState(thumb) // record only what is leaving
1028
+ hero.dataset.flipId = thumb.dataset.flipId // same id → same "thing"
1029
+ detail.hidden = false
1030
+ live.flipFrom(state, { targets: hero, fade: true, duration: 0.6 })
1031
+ })
1032
+
1033
+ close.addEventListener('click', () => {
1034
+ const state = live.getFlipState(hero)
1035
+ detail.hidden = true
1036
+ live.flipFrom(state, { targets: thumb, fade: true })
1037
+ })
1038
+ ```
1039
+
1040
+ Record only the element that is leaving: if both elements are in the state, each
1041
+ is matched to itself. Matching works within one document (a client-side route
1042
+ change counts; a full page load does not).
1043
+
1044
+ **Limits.** Size changes scale the element, so its content scales too during
1045
+ the animation (text looks stretched mid-flip). Elements that disappear are not
1046
+ animated out, because they are no longer rendered to see. There is no `absolute`
1047
+ or `nested` mode yet.
1048
+
1049
+ ## Inertia and dragging
1050
+
1051
+ A throw that slows under friction and comes to rest — GSAP's InertiaPlugin:
1052
+
1053
+ ```ts
1054
+ live.to('.puck', { inertia: { x: { velocity: 900, max: 400, end: 50 }, y: -300 } })
1055
+ ```
1056
+
1057
+ | Per-property option | Meaning |
1058
+ |---|---|
1059
+ | `velocity` | Speed at release, units per second (a bare number means just this) |
1060
+ | `min`, `max` | Keep the resting place in bounds |
1061
+ | `end` | Snap: a grid increment, a list of values, or a function `(naturalEnd) => number` |
1062
+ | `friction` / `resistance` | How quickly it slows (friction 4 = resistance 100, the default) |
1063
+
1064
+ A throw decides its own duration, so `duration` is ignored for it, and the next
1065
+ tween on the timeline starts after it — from where it came to rest. An `end`
1066
+ function runs once, when the tween is built; the track stores the number.
1067
+
1068
+ **Dragging.** `live.draggable()` drags an element and throws it on release:
1069
+
1070
+ ```ts
1071
+ const slots = [{ x: 0, y: 0 }, { x: 180, y: 0 }, { x: 0, y: 90 }]
1072
+ live.draggable('.card', { bounds: '.table', inertia: { end: slots, friction: 5 } })
1073
+ live.draggable('.strip', { type: 'x', bounds: { minX: -480, maxX: 0 }, inertia: { end: { x: 120 } } })
1074
+ ```
1075
+
1076
+ | Option | Meaning |
1077
+ |---|---|
1078
+ | `type` | `'x'`, `'y'`, `'x,y'` (default), or `'rotation'` to spin it about its centre |
1079
+ | `bounds` | An element (selector or element) to stay inside, or `{ minX, maxX, minY, maxY }` offsets; for rotation `{ minRotation, maxRotation }` |
1080
+ | `snap` | Grid size while dragging (degrees, for rotation) |
1081
+ | `inertia` | `true`, or `{ friction, resistance, end }` — `end` as a grid size, per-axis `{ x, y }`, or `{x, y}` points (nearest in 2D wins) |
1082
+ | `onPress`, `onDrag`, `onRelease(velocity)`, `onThrowComplete` | Callbacks |
1083
+
1084
+ ```ts
1085
+ // A volume knob: drag around it, 0–270°, snapping to 15°, and flick to spin on.
1086
+ live.draggable('.knob', { type: 'rotation', bounds: { minRotation: 0, maxRotation: 270 }, snap: 15, inertia: true })
1087
+ ```
1088
+
1089
+ Rotation follows the pointer's angle about the element's centre. It keeps turning
1090
+ past ±180° without jumping, and `draggable.rotation` reads it.
1091
+
1092
+ Dragging writes positions straight to the stage; the throw is an ordinary
1093
+ inertia tween. Picking the element up mid-throw stops it where it is. Give
1094
+ draggable elements `touch-action: none` so touch drags are not taken by page
1095
+ scrolling.
1096
+
1097
+ **How it works.** Friction is exponential decay, which has an exact closed form,
1098
+ so the value at any time is computed directly — no simulation, identical when
1099
+ scrubbed backwards. Snapping aims the throw at the snap point while keeping its
1100
+ rate of deceleration, so it lands exactly there without looking steered.
1101
+
1102
+ ## Springs
1103
+
1104
+ `spring` on a tween animates its numeric properties with spring physics instead
1105
+ of a duration and an ease:
1106
+
1107
+ ```js
1108
+ live.to('.card', { x: 0, scale: 1, spring: 'bouncy' })
1109
+ live.to('.card', { y: 0, spring: { stiffness: 260, damping: 14, mass: 1 } })
1110
+
1111
+ // Release a drag into a spring, keeping the fling.
1112
+ live.draggable('.card', {
1113
+ onRelease: (velocity) => live.to('.card', { x: 0, y: 0, spring: { preset: 'wobbly', velocity } }),
1114
+ })
1115
+ ```
1116
+
1117
+ | Value | |
1118
+ |---|---|
1119
+ | `true` | The default spring (stiffness 180, damping 12, mass 1) |
1120
+ | `'gentle'`, `'default'`, `'snappy'`, `'bouncy'`, `'wobbly'`, `'stiff'` | The presets the editor's spring inspector offers (`SPRING_PRESETS`) |
1121
+ | `{ preset?, stiffness?, damping?, mass?, velocity?, restDelta? }` | Parameters, optionally over a preset. `velocity` is units per second — one number, or per property (`{ x: 800, y: -200 }`) |
1122
+
1123
+ - Each numeric property compiles to a **spring track**, so the result is still
1124
+ deterministic, scrubbable and plain JSON. Properties that are not numbers (a
1125
+ colour) keep tweening with `duration` and `ease`.
1126
+ - A spring settles in its own time: `duration` and `ease` are ignored for the
1127
+ sprung properties, and the tween lasts as long as its slowest spring.
1128
+ - **Interruptions keep their momentum.** Without a `velocity`, `live` starts the
1129
+ spring at the speed the property is already moving — measured once from the
1130
+ animation it takes over — so re-targeting mid-motion does not stall.
1131
+ - All the sprung properties run on the shared frame loop, and each element is
1132
+ written once per frame however many there are.
1133
+
1134
+ The same spring as a track, without the GSAP-style API:
1135
+
1136
+ ```ts
1137
+ import { Timeline } from '@algorisys/tinyfly'
1138
+
1139
+ const timeline = new Timeline({ id: 'springy' })
1140
+ timeline.addTrack({
1141
+ id: 'pop',
1142
+ target: 'box',
1143
+ property: 'scale',
1144
+ kind: 'spring',
1145
+ spring: { from: 0, to: 1, stiffness: 200, damping: 12 },
1146
+ })
1147
+ ```
1148
+
1149
+ Spring tracks are integrated at a fixed timestep from t=0, so scrubbing
1150
+ backwards gives the same values as playing forwards and two runs are identical.
1151
+ The animation is the *parameters*, so it serializes like anything else.
1152
+
1153
+ ## Utilities, random values and `repeatRefresh`
1154
+
1155
+ `live.utils` has GSAP's utility functions. Most return a reusable function when the
1156
+ last argument is left out:
1157
+
1158
+ ```js
1159
+ const { clamp, mapRange, interpolate, wrap, snap, random, distribute, pipe } = live.utils
1160
+
1161
+ const toPercent = mapRange(0, innerWidth, 0, 100)
1162
+ const colour = interpolate('#c6ff3d', '#ec4899', 0.5)
1163
+ const lane = wrap(['left', 'middle', 'right']) // lane(4) → 'middle'
1164
+ const settle = pipe(clamp(0, 100), snap(5))
1165
+
1166
+ live.to('.dot', {
1167
+ x: 'random(-200, 200, 10)', // per element, as in GSAP
1168
+ y: () => random(-50, 50),
1169
+ scale: distribute({ base: 0.5, amount: 1, from: 'center' }),
1170
+ })
1171
+
1172
+ live.timeline({ repeat: -1, repeatRefresh: true }) // new random values every loop
1173
+ .to('.star', { x: 'random(-300, 300)', y: 'random(-200, 200)', duration: 1.2 })
1174
+
1175
+ live.getProperty('.card', 'x') // what tinyfly last applied
1176
+ ```
1177
+
1178
+ - **Functions:**
1179
+ - maths: `clamp`, `mapRange`, `normalize`, `interpolate` (numbers, colours, arrays,
1180
+ objects);
1181
+ - cycling: `wrap` (ranges or arrays), `wrapYoyo`;
1182
+ - snapping and random: `snap` (increment, values, radius), `random` (range, snap, or
1183
+ array), `shuffle`;
1184
+ - composing: `distribute`, `pipe`;
1185
+ - parsing: `splitColor`, `getUnit`.
1186
+ - **Random is seeded.** `random`, `shuffle` and `"random(…)"` share one sequence per
1187
+ stage, starting from seed 1. A page builds the same "random" layout on every load,
1188
+ and a replay is identical. Call `live.utils.seed(Date.now())` if it should differ.
1189
+ - **Function values** are called with `(index, target, targets)` when the tween is
1190
+ built, and again by `invalidate()` and scroll refreshes.
1191
+ - **`repeatRefresh: true`** rebuilds the timeline at each repeat, so function and
1192
+ random values are drawn again. The rebuilt tweens start from where the previous loop
1193
+ left the values, as in GSAP.
1194
+ - **`getProperty`** returns the value tinyfly last applied, or a plain object's own
1195
+ value, falling back to the property's static default. It never reads computed styles.
1196
+
1197
+ ## Compile-time values
1198
+
1199
+ `"+=100"` and `"random(-50, 50)"` are resolved when the timeline is built, and
1200
+ the concrete number is what lands in the JSON:
1201
+
1202
+ ```ts
1203
+ import { ValueResolver } from '@algorisys/tinyfly'
1204
+
1205
+ const resolver = new ValueResolver(2024) // the seed
1206
+ resolver.resolveSequence([0, '+=100', 'random(-50, 50)'])
1207
+ // → [0, 100, -12.34] — same seed, same numbers, every time
1208
+
1209
+ resolver.seed // store this alongside the timeline to reproduce it
1210
+ ```
1211
+
1212
+ ## Full example
1213
+
1214
+ ```ts
1215
+ import { timeline, quickPlay } from '@algorisys/tinyfly/gsap-compat'
1216
+
1217
+ const tl = timeline({
1218
+ repeat: -1,
1219
+ yoyo: true,
1220
+ repeatDelay: 0.5,
1221
+ onWarning: console.warn,
1222
+ })
1223
+
1224
+ tl.fromTo('title', { y: -40, opacity: 0 }, { y: 0, opacity: 1, duration: 0.8, ease: 'power3.out' })
1225
+ tl.addLabel('lettersIn')
1226
+ tl.fromTo(
1227
+ ['l1', 'l2', 'l3', 'l4'],
1228
+ { opacity: 0, y: 20 },
1229
+ { opacity: 1, y: 0, duration: 0.5, stagger: { each: 0.08, from: 'center' } },
1230
+ 'lettersIn'
1231
+ )
1232
+ tl.to('title', { scale: 1.05, duration: 0.3 }, '>')
1233
+
1234
+ // Inspect what it compiled to — it is ordinary tinyfly JSON.
1235
+ console.log(JSON.stringify(tl.toDefinition(), null, 2))
1236
+
1237
+ quickPlay({
1238
+ timeline: tl.timeline,
1239
+ targets: { title: '#title', l1: '#l1', l2: '#l2', l3: '#l3', l4: '#l4' },
1240
+ })
1241
+ ```