@algorisys/tinyfly 0.64.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 (140) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +672 -0
  3. package/bin/tinyfly.mjs +59 -0
  4. package/lib/addons/adapters.js +756 -0
  5. package/lib/addons/dom-adapter-ChrbtkLC.js +243 -0
  6. package/lib/addons/drivers.js +72 -0
  7. package/lib/addons/export.js +1169 -0
  8. package/lib/addons/gsap-compat.js +2576 -0
  9. package/lib/addons/interaction.js +225 -0
  10. package/lib/addons/smooth-scroll-DaSacemU.js +671 -0
  11. package/lib/addons/teach.js +215 -0
  12. package/lib/browser/tinyfly.iife.js +2 -0
  13. package/lib/browser/tinyfly.js +6372 -0
  14. package/lib/browser/tinyfly.umd.js +2 -0
  15. package/lib/cli/tools.js +2325 -0
  16. package/lib/embed/tinyfly-embed.iife.js +18 -0
  17. package/lib/embed/tinyfly-embed.js +2316 -0
  18. package/lib/engine/tinyfly-engine.js +1972 -0
  19. package/lib/engine/tinyfly-engine.umd.cjs +2 -0
  20. package/lib/frameworks/react.js +32 -0
  21. package/lib/frameworks/solid.js +27 -0
  22. package/lib/frameworks/svelte.js +15 -0
  23. package/lib/frameworks/vue.js +29 -0
  24. package/lib/player/tinyfly-player.es.js +2306 -0
  25. package/lib/player/tinyfly-player.iife.js +2 -0
  26. package/lib/player/tinyfly-player.umd.js +2 -0
  27. package/lib/types/adapters/canvas/canvas-adapter.d.ts +238 -0
  28. package/lib/types/adapters/canvas/index.d.ts +1 -0
  29. package/lib/types/adapters/dom/dom-adapter.d.ts +50 -0
  30. package/lib/types/adapters/dom/flip.d.ts +60 -0
  31. package/lib/types/adapters/dom/index.d.ts +2 -0
  32. package/lib/types/adapters/filter-utils.d.ts +32 -0
  33. package/lib/types/adapters/index.d.ts +5 -0
  34. package/lib/types/adapters/shine-utils.d.ts +26 -0
  35. package/lib/types/adapters/svg/index.d.ts +1 -0
  36. package/lib/types/adapters/svg/svg-adapter.d.ts +47 -0
  37. package/lib/types/adapters/svg-transform-box.d.ts +13 -0
  38. package/lib/types/adapters/text-content.d.ts +11 -0
  39. package/lib/types/adapters/webgl/index.d.ts +1 -0
  40. package/lib/types/adapters/webgl/webgl-adapter.d.ts +69 -0
  41. package/lib/types/browser/index.d.ts +41 -0
  42. package/lib/types/compat/gsap/custom-eases.d.ts +28 -0
  43. package/lib/types/compat/gsap/defaults.d.ts +19 -0
  44. package/lib/types/compat/gsap/draw-svg-vars.d.ts +36 -0
  45. package/lib/types/compat/gsap/ease-map.d.ts +51 -0
  46. package/lib/types/compat/gsap/image-sequence.d.ts +61 -0
  47. package/lib/types/compat/gsap/index.d.ts +65 -0
  48. package/lib/types/compat/gsap/inertia-vars.d.ts +39 -0
  49. package/lib/types/compat/gsap/keyframes-vars.d.ts +8 -0
  50. package/lib/types/compat/gsap/layout.d.ts +6 -0
  51. package/lib/types/compat/gsap/live-context.d.ts +87 -0
  52. package/lib/types/compat/gsap/live-draggable.d.ts +75 -0
  53. package/lib/types/compat/gsap/live-flip.d.ts +73 -0
  54. package/lib/types/compat/gsap/live-morph.d.ts +18 -0
  55. package/lib/types/compat/gsap/live-motion-path.d.ts +33 -0
  56. package/lib/types/compat/gsap/live-scroll-to.d.ts +52 -0
  57. package/lib/types/compat/gsap/live-scroll.d.ts +108 -0
  58. package/lib/types/compat/gsap/live-transition.d.ts +40 -0
  59. package/lib/types/compat/gsap/live.d.ts +341 -0
  60. package/lib/types/compat/gsap/morph-vars.d.ts +21 -0
  61. package/lib/types/compat/gsap/motion-path-vars.d.ts +38 -0
  62. package/lib/types/compat/gsap/playhead-crossings.d.ts +47 -0
  63. package/lib/types/compat/gsap/position.d.ts +37 -0
  64. package/lib/types/compat/gsap/quick-play.d.ts +38 -0
  65. package/lib/types/compat/gsap/split-text.d.ts +66 -0
  66. package/lib/types/compat/gsap/spring-vars.d.ts +34 -0
  67. package/lib/types/compat/gsap/stage.d.ts +182 -0
  68. package/lib/types/compat/gsap/stagger-grid.d.ts +30 -0
  69. package/lib/types/compat/gsap/text-vars.d.ts +39 -0
  70. package/lib/types/compat/gsap/timeline.d.ts +161 -0
  71. package/lib/types/compat/gsap/utils.d.ts +60 -0
  72. package/lib/types/compat/gsap/vars.d.ts +79 -0
  73. package/lib/types/drivers/index.d.ts +8 -0
  74. package/lib/types/drivers/scroll-driver.d.ts +218 -0
  75. package/lib/types/drivers/scroll-markers.d.ts +41 -0
  76. package/lib/types/drivers/scroll-math.d.ts +87 -0
  77. package/lib/types/drivers/scroll-pin.d.ts +45 -0
  78. package/lib/types/drivers/scroll-snap.d.ts +47 -0
  79. package/lib/types/drivers/smooth-scroll.d.ts +118 -0
  80. package/lib/types/drivers/types.d.ts +23 -0
  81. package/lib/types/drivers/visibility-driver.d.ts +56 -0
  82. package/lib/types/embed/controls.d.ts +46 -0
  83. package/lib/types/embed/index.d.ts +17 -0
  84. package/lib/types/embed/mount.d.ts +41 -0
  85. package/lib/types/embed/tools.d.ts +33 -0
  86. package/lib/types/engine/authoring/custom-ease.d.ts +49 -0
  87. package/lib/types/engine/authoring/index.d.ts +3 -0
  88. package/lib/types/engine/authoring/random.d.ts +38 -0
  89. package/lib/types/engine/authoring/resolve-values.d.ts +57 -0
  90. package/lib/types/engine/core/bake.d.ts +66 -0
  91. package/lib/types/engine/core/clock.d.ts +44 -0
  92. package/lib/types/engine/core/index.d.ts +8 -0
  93. package/lib/types/engine/core/inertia.d.ts +30 -0
  94. package/lib/types/engine/core/playhead-crossings.d.ts +47 -0
  95. package/lib/types/engine/core/spring.d.ts +132 -0
  96. package/lib/types/engine/core/stagger.d.ts +40 -0
  97. package/lib/types/engine/core/timeline.d.ts +203 -0
  98. package/lib/types/engine/core/track.d.ts +90 -0
  99. package/lib/types/engine/export/byte-writer.d.ts +36 -0
  100. package/lib/types/engine/export/css.d.ts +31 -0
  101. package/lib/types/engine/export/gif-decode.test-helper.d.ts +24 -0
  102. package/lib/types/engine/export/gif.d.ts +134 -0
  103. package/lib/types/engine/export/index.d.ts +9 -0
  104. package/lib/types/engine/export/lottie.d.ts +104 -0
  105. package/lib/types/engine/export/mp4.d.ts +64 -0
  106. package/lib/types/engine/export/quantize.d.ts +56 -0
  107. package/lib/types/engine/export/sprite-sheet.d.ts +46 -0
  108. package/lib/types/engine/export/video.d.ts +99 -0
  109. package/lib/types/engine/export/webp.d.ts +82 -0
  110. package/lib/types/engine/index.d.ts +7 -0
  111. package/lib/types/engine/interpolation/easing.d.ts +65 -0
  112. package/lib/types/engine/interpolation/index.d.ts +2 -0
  113. package/lib/types/engine/interpolation/interpolators.d.ts +25 -0
  114. package/lib/types/engine/path/index.d.ts +11 -0
  115. package/lib/types/engine/path/motion-path.d.ts +24 -0
  116. package/lib/types/engine/path/path-builders.d.ts +38 -0
  117. package/lib/types/engine/path/path-morph.d.ts +47 -0
  118. package/lib/types/engine/path/path-utils.d.ts +73 -0
  119. package/lib/types/engine/serialization/index.d.ts +1 -0
  120. package/lib/types/engine/serialization/json.d.ts +30 -0
  121. package/lib/types/engine/text/index.d.ts +2 -0
  122. package/lib/types/engine/text/text-value.d.ts +16 -0
  123. package/lib/types/engine/types.d.ts +401 -0
  124. package/lib/types/frameworks/react.d.ts +35 -0
  125. package/lib/types/frameworks/solid.d.ts +16 -0
  126. package/lib/types/frameworks/svelte.d.ts +19 -0
  127. package/lib/types/frameworks/vue.d.ts +27 -0
  128. package/lib/types/interaction/draggable.d.ts +133 -0
  129. package/lib/types/interaction/index.d.ts +3 -0
  130. package/lib/types/interaction/observer.d.ts +80 -0
  131. package/lib/types/interaction/snap.d.ts +30 -0
  132. package/lib/types/player/index.d.ts +7 -0
  133. package/lib/types/player/media-sync.d.ts +60 -0
  134. package/lib/types/player/player.d.ts +238 -0
  135. package/lib/types/player/sequence-types.d.ts +68 -0
  136. package/lib/types/player/sequencer.d.ts +91 -0
  137. package/lib/types/teach/diagrams.d.ts +137 -0
  138. package/lib/types/teach/index.d.ts +11 -0
  139. package/lib/types/teach/lesson.d.ts +55 -0
  140. package/package.json +170 -0
@@ -0,0 +1,341 @@
1
+ import type { Timeline, TimelineDefinition } from '../../engine';
2
+ import { CompatTimeline, type CompatTimelineOptions } from './timeline';
3
+ import type { Position } from './position';
4
+ import { type TweenVars } from './vars';
5
+ import { Stage, type TargetInput, type Ticker } from './stage';
6
+ import type { AnimatableValue } from '../../engine';
7
+ import { type LiveDraggable, type LiveDraggableOptions } from './live-draggable';
8
+ import { type FlipState, type FlipVars } from './live-flip';
9
+ import { type SplitTextOptions, type SplitTextResult } from './split-text';
10
+ import { type ScrollTriggerVars } from './live-scroll';
11
+ import { ScrollDriver, SmoothScroll, type SmoothScrollOptions } from '../../drivers';
12
+ import { LiveContext, LiveMatchMedia } from './live-context';
13
+ import { ImageSequence, type ImageSequenceOptions } from './image-sequence';
14
+ import { type PageTransitionOptions } from './live-transition';
15
+ import { type LiveUtils } from './utils';
16
+ import { type ScrollBatchVars, type ScrollDestination, type ScrollToVars } from './live-scroll-to';
17
+ import type { CubicBezierPoints, CustomBounceOptions, CustomWiggleOptions } from '../../engine';
18
+ /**
19
+ * The live facade: GSAP-style calls that play on real elements straight away.
20
+ *
21
+ * live.to('.box', { x: 200, duration: 1, ease: 'power2.out' })
22
+ *
23
+ * `tf` (in index.ts) compiles an animation and leaves playback to you; `live`
24
+ * compiles the same way and then plays it on a shared {@link Stage}. The
25
+ * compilation is identical — `toDefinition()` returns the same plain JSON — so
26
+ * everything that makes tinyfly deterministic still holds for what is built.
27
+ * What `live` adds is only the runtime: selector resolution, the frame loop,
28
+ * and composing concurrent animations on one element.
29
+ *
30
+ * Differences from `tf`, all in the runtime:
31
+ * - Targets are CSS selectors, elements, or lists of them. A selector matching
32
+ * several elements animates all of them (and `stagger` fans them out).
33
+ * - A start value the timeline has not authored comes from the value the stage
34
+ * last applied to that element, before the static defaults. It is resolved
35
+ * once, when the tween is built — never read back per frame.
36
+ * - Playback starts on the next microtask, so tweens chained synchronously onto
37
+ * a timeline are all in place first. `paused: true` (or calling any playback
38
+ * method before then) opts out.
39
+ */
40
+ /** Options for `live.smoothScroll`: a selector may name the scroller. */
41
+ export interface LiveSmoothScrollOptions extends Omit<SmoothScrollOptions, 'scroller'> {
42
+ scroller?: string | HTMLElement | null;
43
+ }
44
+ export interface LiveTimelineOptions extends Omit<CompatTimelineOptions, 'startValue'> {
45
+ /** Do not start automatically (GSAP's `paused`) */
46
+ paused?: boolean;
47
+ onStart?: () => void;
48
+ /** Called after each frame this timeline is applied */
49
+ onUpdate?: () => void;
50
+ onComplete?: () => void;
51
+ /** Each time a repeat begins */
52
+ onRepeat?: () => void;
53
+ /** On arriving back at the start after `reverse()` */
54
+ onReverseComplete?: () => void;
55
+ /**
56
+ * Rebuild the timeline at every repeat (GSAP's `repeatRefresh`): function values
57
+ * and `"random(…)"` strings are drawn again, so each loop differs. The random
58
+ * sequence is seeded, so a replay of the page is still identical.
59
+ */
60
+ repeatRefresh?: boolean;
61
+ /**
62
+ * Drive this timeline from scrolling: scrub it, pin, or play/reverse it as a
63
+ * range is crossed. It does not autoplay.
64
+ */
65
+ scrollTrigger?: ScrollTriggerVars;
66
+ }
67
+ /** Options for `live.quickTo`: how each re-targeted move animates. */
68
+ export interface QuickToVars {
69
+ /** Seconds (default 0.4) */
70
+ duration?: number;
71
+ /** Default `'power3.out'` */
72
+ ease?: string;
73
+ /** Move on a spring instead; each re-target keeps the current velocity */
74
+ spring?: TweenVars['spring'];
75
+ }
76
+ /** Options for `tl.tweenTo()` / `tl.tweenFromTo()`. */
77
+ export interface TweenToVars {
78
+ /** Seconds; default the distance at the timeline's own speed */
79
+ duration?: number;
80
+ /** Default `'none'` */
81
+ ease?: string;
82
+ onStart?: () => void;
83
+ onUpdate?: () => void;
84
+ onComplete?: () => void;
85
+ }
86
+ /** Call it with a value to animate toward it. */
87
+ export interface QuickTo {
88
+ (value: number): void;
89
+ /** The reused timeline */
90
+ readonly tween: LiveTimeline;
91
+ kill(): void;
92
+ }
93
+ export declare class LiveTimeline {
94
+ /** The compiled compat timeline. */
95
+ readonly compat: CompatTimeline;
96
+ private readonly stage;
97
+ private readonly options;
98
+ /** Cleared once playback has been started or explicitly controlled. */
99
+ private autoplayPending;
100
+ private started;
101
+ private killed;
102
+ /** The building calls, in order, so `invalidate()` can replay them. */
103
+ private readonly recipe;
104
+ /** The first element any tween targeted: a scroll trigger's default trigger. */
105
+ private firstElement?;
106
+ private scrollDriver?;
107
+ /** Callbacks and pauses placed on the timeline (`call`, `addPause`, tween onStart / onComplete) */
108
+ private events;
109
+ private ranges;
110
+ /** Where the playhead was when callbacks were last worked out */
111
+ private playhead;
112
+ /** A plain repeat is waiting out its delay; the next loop starts fresh from 0 */
113
+ private waitingToWrap;
114
+ /** The engine finished during this frame; completion callbacks run after the frame's events */
115
+ private finishedThisFrame;
116
+ /** Set by `reverse()`: arriving at the start is a reverse completion */
117
+ private backwards;
118
+ constructor(stage: Stage, options?: LiveTimelineOptions);
119
+ /** The engine timeline. */
120
+ get timeline(): Timeline;
121
+ /** The scroll driver behind `scrollTrigger`, once attached (after a microtask). */
122
+ get scrollTrigger(): ScrollDriver | undefined;
123
+ to(target: TargetInput, vars: TweenVars, position?: Position): this;
124
+ from(target: TargetInput, vars: TweenVars, position?: Position): this;
125
+ fromTo(target: TargetInput, fromVars: TweenVars, toVars: TweenVars, position?: Position): this;
126
+ set(target: TargetInput, vars: TweenVars, position?: Position): this;
127
+ addLabel(name: string, position?: Position): this;
128
+ /** Merge another timeline in at a position (flattened, as in `tf`). */
129
+ add(child: LiveTimeline, position?: Position): this;
130
+ /**
131
+ * Build the timeline again from the same calls: rewind to the start (so start
132
+ * values are read from what elements show before it ran), rebuild every tween —
133
+ * re-running function values — and return to the same progress. Use after a
134
+ * layout change; `scrollTrigger: { invalidateOnRefresh: true }` does it on refresh.
135
+ */
136
+ invalidate(): this;
137
+ /**
138
+ * Run `callback` when the playhead crosses `position` (default: the end so far),
139
+ * in either direction (GSAP's `call`). It takes no time, but a call after the
140
+ * last tween makes the timeline that long.
141
+ */
142
+ call(callback: (...args: never[]) => void, params?: unknown[], position?: Position): this;
143
+ /** Pause exactly at `position` when the playhead reaches it, then run `callback`. `play()` continues. */
144
+ addPause(position?: Position, callback?: (...args: never[]) => void, params?: unknown[]): this;
145
+ /**
146
+ * Pause, and animate the playhead from where it is to `position` (seconds or a
147
+ * label), firing callbacks on the way. Returns the tween that moves it.
148
+ */
149
+ tweenTo(position: number | string, vars?: TweenToVars): LiveTimeline;
150
+ /** Jump to `from`, then animate the playhead to `to` (seconds or labels). */
151
+ tweenFromTo(from: number | string, to: number | string, vars?: TweenToVars): LiveTimeline;
152
+ play(): this;
153
+ pause(): this;
154
+ /** Continue from the current position (GSAP's `resume`). */
155
+ resume(): this;
156
+ /** Play from the start. */
157
+ restart(): this;
158
+ /** Flip direction and keep playing (from the end, if already finished). */
159
+ reverse(): this;
160
+ /** Label times as progress (0..1), in order. */
161
+ labelProgresses(): number[];
162
+ /** Whether the timeline is set to play backwards. */
163
+ reversed(): boolean;
164
+ /** Jump to a time in seconds, or to a label, and apply it immediately. */
165
+ seek(position: number | string): this;
166
+ /**
167
+ * Read or set progress, 0..1. Setting applies immediately and fires the
168
+ * callbacks crossed on the way, so a scroll scrub runs them.
169
+ */
170
+ progress(value?: number): number;
171
+ timeScale(value?: number): number;
172
+ /** Total duration in seconds. */
173
+ duration(): number;
174
+ isActive(): boolean;
175
+ /** Stop and remove every tween, and any scroll trigger (and its pin). Elements keep the values last applied. */
176
+ kill(): this;
177
+ /** The compiled animation, as plain JSON. */
178
+ toDefinition(): TimelineDefinition;
179
+ /**
180
+ * Remove the tweens on these targets (and only these properties, if given)
181
+ * from this timeline — `live.killTweensOf` asks every live timeline. A tween on
182
+ * several elements shares one track, so it stops for all of them.
183
+ */
184
+ killTweensOf(names: string[], properties?: string[]): void;
185
+ /** Run a building step now, and keep it so `invalidate()` can run it again. */
186
+ private record;
187
+ /** A call or pause after the last tween extends the timeline to reach it. */
188
+ private syncDuration;
189
+ private readPlayhead;
190
+ /** Set the playhead to a time (ms) within the current loop, firing what it crosses. */
191
+ private moveTo;
192
+ /**
193
+ * Rebuild for a new loop, keeping the playhead where the engine put it. Unlike
194
+ * `invalidate()`, start values are not re-read from a rewound render: the
195
+ * rebuilt tweens start where the recorded calls say, with fresh function values.
196
+ */
197
+ private refreshForRepeat;
198
+ /** After each frame this timeline played: callbacks crossed, repeats, completion. */
199
+ private afterFrame;
200
+ /** Fire events and repeats between two playheads. Returns true if a pause stopped it. */
201
+ private runCrossings;
202
+ /**
203
+ * Compile one tween call. A track has one start value and one set of values,
204
+ * but some tweens differ per element — each element's own shape, text or stroke
205
+ * length, each plain object's own current values, or function values called per
206
+ * element — so those build one tween per element at the same position, with any
207
+ * stagger turned into delays. `varsList` is `[vars]`, or `[fromVars, toVars]`.
208
+ */
209
+ private tween;
210
+ /**
211
+ * A tween with `keyframes`: its segments one after another, from the tween's
212
+ * position and delay. With `stagger`, each target plays the whole sequence,
213
+ * offset like any stagger. Callbacks belong to the sequence as a whole.
214
+ */
215
+ private keyframed;
216
+ private staggerContext;
217
+ private buildTween;
218
+ /** The element or plain object behind a target name. */
219
+ private targetFor;
220
+ /**
221
+ * Resolve the parts of vars that refer to the page — today, a motion path
222
+ * given as a selector or element, and its `align` — into plain data.
223
+ */
224
+ private prepare;
225
+ private resolve;
226
+ }
227
+ /** The GSAP-shaped entry points, bound to one stage. */
228
+ export interface LiveApi {
229
+ timeline(options?: LiveTimelineOptions): LiveTimeline;
230
+ /**
231
+ * GSAP's utilities: `clamp`, `mapRange`, `normalize`, `interpolate`, `wrap`,
232
+ * `wrapYoyo`, `snap`, `random`, `shuffle`, `distribute`, `pipe`, `splitColor`,
233
+ * `getUnit`. Random draws are seeded (`utils.seed(n)`), so pages replay identically.
234
+ */
235
+ readonly utils: LiveUtils;
236
+ /**
237
+ * The value tinyfly last applied to a property (or a plain object's own value),
238
+ * falling back to the property's static default. tinyfly never reads computed styles.
239
+ */
240
+ getProperty(target: TargetInput, property: string): AnimatableValue | undefined;
241
+ /** Run `callback` after `delay` seconds, on the stage's clock (GSAP's `delayedCall`). `kill()` cancels it. */
242
+ delayedCall(delay: number, callback: (...args: never[]) => void, params?: unknown[]): LiveTimeline;
243
+ /**
244
+ * Stop every tween on these targets — only the given properties (an array or
245
+ * `'x,y'`), if any — in every live timeline (GSAP's `killTweensOf`).
246
+ */
247
+ killTweensOf(target: TargetInput, properties?: string | string[]): void;
248
+ to(target: TargetInput, vars: TweenVars): LiveTimeline;
249
+ from(target: TargetInput, vars: TweenVars): LiveTimeline;
250
+ fromTo(target: TargetInput, fromVars: TweenVars, toVars: TweenVars): LiveTimeline;
251
+ set(target: TargetInput, vars: TweenVars): LiveTimeline;
252
+ /**
253
+ * Replace basic SVG shapes with equivalent `<path>` elements so they can be
254
+ * morphed (selectors resolve within the stage's root). Changes the document.
255
+ */
256
+ convertToPath(targets: string | Element | ArrayLike<Element>): Element[];
257
+ /**
258
+ * Wrap text in char, word and line spans so each can be animated (GSAP's
259
+ * SplitText). Selectors resolve within the stage's root. Changes the document;
260
+ * `revert()` restores it.
261
+ */
262
+ splitText(targets: string | Element | ArrayLike<Element>, options?: SplitTextOptions): SplitTextResult;
263
+ /**
264
+ * A scroll trigger with no animation — for callbacks such as velocity effects
265
+ * (GSAP's `ScrollTrigger.create`). `destroy()` it when done.
266
+ */
267
+ scrollTrigger(vars: ScrollTriggerVars & {
268
+ trigger: string | Element;
269
+ }): ScrollDriver | undefined;
270
+ /**
271
+ * One scroll trigger per element, with elements that cross an edge close
272
+ * together delivered in one callback (GSAP's `ScrollTrigger.batch`).
273
+ */
274
+ scrollBatch(targets: string | Element | ArrayLike<Element>, vars: ScrollBatchVars): ScrollDriver[];
275
+ /**
276
+ * Animate scrolling to an offset, element, selector or `'max'` (GSAP's
277
+ * ScrollToPlugin). Stops if the reader scrolls. Also: `live.to(window, { scrollTo })`.
278
+ */
279
+ scrollTo(destination: ScrollDestination, vars?: ScrollToVars): LiveTimeline;
280
+ /** Re-measure every scroll trigger and smoother, after layout changes a resize would not catch. */
281
+ refreshScroll(): void;
282
+ /**
283
+ * Smooth wheel scrolling, with `data-speed` / `data-lag` parallax when `effects`
284
+ * is set (GSAP's ScrollSmoother). The browser's scroll position still moves, so
285
+ * scroll triggers and pins work unchanged. Off under reduced motion. `kill()` it when done.
286
+ */
287
+ smoothScroll(options?: LiveSmoothScrollOptions): SmoothScroll;
288
+ /**
289
+ * Collect everything the live API creates while `fn` runs (and later, inside
290
+ * `ctx.add()`), so `ctx.revert()` undoes it all. Selectors resolve within `scope`.
291
+ */
292
+ context(fn?: (context: LiveContext) => unknown, scope?: ParentNode): LiveContext;
293
+ /** Setups that apply while media queries match (GSAP's `gsap.matchMedia`). */
294
+ matchMedia(scope?: ParentNode): LiveMatchMedia;
295
+ /**
296
+ * A setter that animates one property toward each value it is given, re-using
297
+ * one tween (GSAP's `gsap.quickTo`) — for values that change on every pointer
298
+ * move or scroll event.
299
+ */
300
+ quickTo(target: TargetInput, property: string, vars?: QuickToVars): QuickTo;
301
+ /**
302
+ * A canvas showing one frame of an image sequence; tween or scrub its `frame`.
303
+ * Selectors resolve within the stage's root.
304
+ */
305
+ imageSequence(canvas: string | HTMLCanvasElement, options: ImageSequenceOptions): ImageSequence;
306
+ /**
307
+ * Animate a client-side page change: the old view out, `update()`, shared elements
308
+ * carried across by `data-flip-id`, the new view in. Resolves when it has finished.
309
+ */
310
+ pageTransition(options: PageTransitionOptions): Promise<void>;
311
+ /** Register a custom ease from SVG path data or bezier points (GSAP's CustomEase.create). Returns the name. */
312
+ customEase(name: string, definition: string | CubicBezierPoints): string;
313
+ /** Register a bouncing ease (GSAP's CustomBounce.create). Returns the name. */
314
+ customBounce(name: string, options?: CustomBounceOptions): string;
315
+ /** Register a wiggle ease that returns to the start (GSAP's CustomWiggle.create). Returns the name. */
316
+ customWiggle(name: string, options?: CustomWiggleOptions): string;
317
+ /** Run a callback every frame, after animations are applied (GSAP's `gsap.ticker`). */
318
+ readonly ticker: Ticker;
319
+ /** Record where elements appear, before a layout change (GSAP's `Flip.getState`). */
320
+ getFlipState(targets: TargetInput): FlipState;
321
+ /** Animate recorded elements from where they were to their new layout (GSAP's `Flip.from`). */
322
+ flipFrom(state: FlipState, vars?: FlipVars): LiveTimeline;
323
+ /** Record, run `change`, and animate the difference — in one call. */
324
+ flip(targets: TargetInput, change: () => void, vars?: FlipVars): LiveTimeline;
325
+ /** Drag an element, and throw it with inertia on release (GSAP's Draggable + InertiaPlugin). */
326
+ draggable(target: TargetInput, options?: LiveDraggableOptions): LiveDraggable;
327
+ /** The stage these calls play on. */
328
+ readonly stage: Stage;
329
+ }
330
+ /**
331
+ * Create a live API bound to a stage. Most pages use the default {@link live};
332
+ * a separate stage is useful for tests, or for an isolated region of a page.
333
+ */
334
+ export declare function createLive(stage?: Stage): LiveApi;
335
+ /**
336
+ * The default live API, on a page-wide stage.
337
+ *
338
+ * One shared stage is the point: it is what lets separate `live.to()` calls on
339
+ * the same element compose. The stage does nothing until something plays.
340
+ */
341
+ export declare const live: LiveApi;
@@ -0,0 +1,21 @@
1
+ import type { TweenVars } from './vars';
2
+ /**
3
+ * GSAP's `morphSVG` tween option, desugared to the `d` property.
4
+ *
5
+ * tl.fromTo('shape', { d: circleData }, { morphSVG: starData, duration: 1 })
6
+ *
7
+ * The engine already interpolates path data (see engine/path/path-morph.ts,
8
+ * which pairs subpaths, picks the start point and keeps corners), so a morph is
9
+ * an ordinary track on `d`. The facade accepts path data only; `live` resolves
10
+ * a selector or element to its path data first, and reads each target's
11
+ * current shape as the start.
12
+ */
13
+ export interface MorphSvgVars {
14
+ /** The shape to morph into: path data (or, in `live`, a selector or element) */
15
+ shape: string;
16
+ }
17
+ export type MorphSvgValue = string | MorphSvgVars;
18
+ /** The shape a `morphSVG` value names, before any DOM resolution. */
19
+ export declare function morphShapeOf(value: unknown): unknown;
20
+ /** Replace `morphSVG` with `d`. Vars without it are returned as they are. */
21
+ export declare function desugarMorph(vars: TweenVars): TweenVars;
@@ -0,0 +1,38 @@
1
+ import { type MotionPathConfig, type PathPoint } from '../../engine';
2
+ /**
3
+ * GSAP's `motionPath` tween option, desugared to a motion-path track.
4
+ *
5
+ * tl.to('dot', { motionPath: { path: 'M0 0 C…', autoRotate: true }, duration: 2 })
6
+ * tl.to('dot', { motionPath: [{ x: 0, y: 0 }, { x: 100, y: 50 }, { x: 200, y: 0 }] })
7
+ *
8
+ * The facade only accepts data here — path data or points. The live runtime
9
+ * additionally resolves a selector or element to its path data (and computes
10
+ * `matrix` for `align`) before handing the result on, so nothing in the
11
+ * compiler ever touches the DOM.
12
+ */
13
+ export type MotionPathMatrix = [number, number, number, number, number, number];
14
+ export interface MotionPathVars {
15
+ /** SVG path data, or points to pass through */
16
+ path: string | PathPoint[];
17
+ /** For points: 0 = straight lines, 1 = natural curve (default), more = bowed */
18
+ curviness?: number;
19
+ /** Rotate to follow the path. A number also rotates, offset by that many degrees. */
20
+ autoRotate?: boolean | number;
21
+ /** Where along the path to start, 0–1 (default 0) */
22
+ start?: number;
23
+ /** Where along the path to end, 0–1 (default 1) */
24
+ end?: number;
25
+ /** Place the path in the follower's space; normally computed by `live` for `align` */
26
+ matrix?: MotionPathMatrix;
27
+ }
28
+ /** What `motionPath:` may be set to: shorthand path data or points, or the full object. */
29
+ export type MotionPathValue = string | PathPoint[] | MotionPathVars;
30
+ export interface CompiledMotionPath {
31
+ config: MotionPathConfig;
32
+ start: number;
33
+ end: number;
34
+ }
35
+ /** Normalise any accepted `motionPath` value. Throws with a useful message otherwise. */
36
+ export declare function compileMotionPath(value: unknown): CompiledMotionPath;
37
+ /** The same motion path travelled the other way — what `from()` animates. */
38
+ export declare function reverseMotionPath(value: unknown): MotionPathVars;
@@ -0,0 +1,47 @@
1
+ /**
2
+ * Which points in time a playhead passed between two frames — the pure part of
3
+ * timeline callbacks (`call`, `addPause`, per-tween `onStart` / `onComplete`,
4
+ * `onRepeat`).
5
+ *
6
+ * A frame moves the playhead from one place to another, possibly across loop
7
+ * boundaries: a plain repeat wraps back to the start, a yoyo turns around. The
8
+ * movement is split into passes, and each pass reports the event times inside it
9
+ * in the order they were crossed:
10
+ *
11
+ * - forward, `(from, to]` — an event exactly where the playhead already was has
12
+ * fired before; a pass that starts a loop (or a first play) includes its start;
13
+ * - reverse, `[to, from)`.
14
+ */
15
+ export type Direction = 'forward' | 'reverse';
16
+ export interface Playhead {
17
+ /** Milliseconds within the current loop */
18
+ time: number;
19
+ /** Loops completed */
20
+ iteration: number;
21
+ direction: Direction;
22
+ /** The playhead is at the very start of a pass, so an event at its position has not fired */
23
+ fresh?: boolean;
24
+ }
25
+ export type Crossing = {
26
+ kind: 'event';
27
+ index: number;
28
+ direction: Direction;
29
+ } | {
30
+ kind: 'repeat';
31
+ };
32
+ export interface CrossingResult {
33
+ crossings: Crossing[];
34
+ /** Every stretch of time covered, in order, as [from, to] (to < from when reversing) */
35
+ passes: Array<[number, number]>;
36
+ }
37
+ export interface LoopShape {
38
+ duration: number;
39
+ /** Yoyo: every other loop plays backwards */
40
+ alternate: boolean;
41
+ /**
42
+ * The frame ended waiting out a repeat delay at a boundary. A plain repeat has
43
+ * not wrapped yet, so the last pass (the new loop) has not started.
44
+ */
45
+ holding?: boolean;
46
+ }
47
+ export declare function playheadCrossings(times: readonly number[], from: Playhead, to: Playhead, shape: LoopShape): CrossingResult;
@@ -0,0 +1,37 @@
1
+ /**
2
+ * GSAP's position parameter.
3
+ *
4
+ * The third argument to `tl.to(target, vars, position)` decides where on the
5
+ * timeline a tween lands. Its grammar is small but load-bearing — it is how
6
+ * GSAP users express sequencing — so it is parsed here as pure data.
7
+ *
8
+ * All times are in milliseconds internally; the facade converts from seconds
9
+ * at its boundary.
10
+ */
11
+ export interface PositionContext {
12
+ /** Where the next appended tween would start (the end of the timeline) */
13
+ cursor: number;
14
+ /** Start of the most recently added tween */
15
+ previousStart: number;
16
+ /** End of the most recently added tween */
17
+ previousEnd: number;
18
+ /** Named positions added with `addLabel` */
19
+ labels: Map<string, number>;
20
+ /**
21
+ * Multiplier applied to literal numbers in the position — 1000 when the
22
+ * caller writes GSAP seconds and the timeline stores milliseconds.
23
+ *
24
+ * Only literals are scaled. The cursor, previous-tween times and label times
25
+ * are already in the timeline's own units.
26
+ */
27
+ scale?: number;
28
+ }
29
+ /** A position parameter: absolute ms, a relative offset, `<`/`>`, or a label. */
30
+ export type Position = number | string | undefined;
31
+ /**
32
+ * Resolve a position parameter to an absolute time in milliseconds.
33
+ *
34
+ * Unrecognised strings resolve to the cursor (append), which is GSAP's default
35
+ * and the least surprising outcome for a typo.
36
+ */
37
+ export declare function resolvePosition(position: Position, context: PositionContext): number;
@@ -0,0 +1,38 @@
1
+ import { Timeline } from '../../engine';
2
+ import { DOMAdapter } from '../../adapters/dom';
3
+ /**
4
+ * Wire a timeline to the DOM and drive it.
5
+ *
6
+ * This is the twelve lines of boilerplate every tinyfly example opens with —
7
+ * register targets, set `onUpdate`, run a rAF loop — reduced to one call. It is
8
+ * the honest reason GSAP feels lighter than us for a quick animation, and it is
9
+ * worth having whether or not anyone uses the rest of the compat layer.
10
+ *
11
+ * The engine still owns the animation; this only feeds it deltas.
12
+ */
13
+ export interface QuickPlayOptions {
14
+ /** Timeline to play */
15
+ timeline: Timeline;
16
+ /**
17
+ * Map of target name → element or CSS selector. The adapter resolves each to
18
+ * an element; the engine still only ever sees names.
19
+ */
20
+ targets: Record<string, Element | string>;
21
+ /** Start immediately (default: true) */
22
+ autoplay?: boolean;
23
+ /** Called on each frame with the engine's state */
24
+ onUpdate?: (state: ReturnType<Timeline['getStateAtTime']>) => void;
25
+ /** Called when the timeline completes */
26
+ onComplete?: () => void;
27
+ }
28
+ export interface QuickPlayHandle {
29
+ timeline: Timeline;
30
+ adapter: DOMAdapter;
31
+ play(): void;
32
+ pause(): void;
33
+ restart(): void;
34
+ seek(seconds: number): void;
35
+ /** Stop the loop and release the targets. */
36
+ destroy(): void;
37
+ }
38
+ export declare function quickPlay(options: QuickPlayOptions): QuickPlayHandle;
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Split text into characters, words and lines wrapped in spans, so each piece
3
+ * can be animated on its own — GSAP's SplitText.
4
+ *
5
+ * const split = live.splitText('.headline', { type: 'lines,words', mask: 'lines' })
6
+ * live.from(split.words, { y: '100%', duration: 0.8, stagger: 0.05 })
7
+ * split.revert() // back to the original markup
8
+ *
9
+ * What it does to the markup, so there are no surprises:
10
+ * - Every word becomes `<span class="word">` (inline-block, so it can move and
11
+ * never breaks in the middle). Spaces stay as plain text between words, so the
12
+ * text still wraps, selects and copies normally.
13
+ * - `chars` wraps each character of a word in `<span class="char">`, using
14
+ * grapheme clusters where the browser supports them (an emoji stays whole).
15
+ * - `lines` measures where the browser wrapped the words — once, at split time
16
+ * — and groups them into `<span class="line">` blocks. Inline markup such as
17
+ * `<em>` or `<a>` is kept: it is cloned into each line it spans.
18
+ * - `mask` wraps each line, word or char in an `overflow: clip` span, for
19
+ * reveals that slide text up from behind an edge.
20
+ * - The element gets `aria-label` with its text and the pieces `aria-hidden`, so
21
+ * a screen reader reads the sentence rather than letter by letter.
22
+ *
23
+ * Lines depend on the element's width. With `autoSplit: true` the split is
24
+ * redone when an element's width changes or web fonts finish loading. Build the
25
+ * animation in `onSplit` and return it, so the old one is killed before the
26
+ * pieces it animated are replaced.
27
+ */
28
+ export type SplitType = 'chars' | 'words' | 'lines';
29
+ /** Anything `onSplit` may return to be cleaned up before a re-split. */
30
+ export interface SplitAnimation {
31
+ kill?(): unknown;
32
+ revert?(): unknown;
33
+ }
34
+ export interface SplitTextOptions {
35
+ /** Which pieces to create, comma-separated (default `'chars,words,lines'`) */
36
+ type?: string;
37
+ /** Wrap each line, word or char in an overflow-clipping span */
38
+ mask?: SplitType;
39
+ charsClass?: string;
40
+ wordsClass?: string;
41
+ linesClass?: string;
42
+ /** Add `aria-label` / `aria-hidden` (default true) */
43
+ aria?: boolean;
44
+ /** Split again when an element's width changes or fonts load (default false) */
45
+ autoSplit?: boolean;
46
+ /**
47
+ * Called after every split, including the first. Return the animation built on
48
+ * the pieces; it is killed before the next split and on `revert()`.
49
+ */
50
+ onSplit?: (self: SplitTextResult) => SplitAnimation | void;
51
+ }
52
+ export interface SplitTextResult {
53
+ /** The elements that were split */
54
+ readonly elements: Element[];
55
+ /** The current pieces (replaced on each re-split) */
56
+ readonly chars: HTMLElement[];
57
+ readonly words: HTMLElement[];
58
+ readonly lines: HTMLElement[];
59
+ /** The mask wrappers, when `mask` was given */
60
+ readonly masks: HTMLElement[];
61
+ /** Split again now, e.g. after changing the text's layout yourself */
62
+ split(): void;
63
+ /** Restore every element's original markup, and stop watching for resizes */
64
+ revert(): void;
65
+ }
66
+ export declare function splitText(elements: Element[], options?: SplitTextOptions): SplitTextResult;
@@ -0,0 +1,34 @@
1
+ import { type SpringConfig, type SpringPresetName } from '../../engine';
2
+ /**
3
+ * The `spring` tween option: animate numeric properties with spring physics
4
+ * instead of a duration and an ease.
5
+ *
6
+ * live.to('.card', { x: 0, scale: 1, spring: 'wobbly' })
7
+ * live.to('.card', { x: 0, y: 0, spring: { stiffness: 260, damping: 14, velocity: { x: vx, y: vy } } })
8
+ *
9
+ * Each numeric property becomes a spring track (see engine/core/spring.ts):
10
+ * deterministic, scrubbable and serializable. A spring settles in its own
11
+ * time, so `duration` and `ease` are ignored for those properties; anything
12
+ * that is not a number (a colour) still tweens with them.
13
+ */
14
+ export interface SpringOptions {
15
+ /** Start from a named spring, then override its parameters */
16
+ preset?: SpringPresetName;
17
+ stiffness?: number;
18
+ damping?: number;
19
+ mass?: number;
20
+ /**
21
+ * Initial velocity in units per second — one number for every property, or per
22
+ * property (`{ x: 800, y: -200 }`, e.g. a drag's release velocity). Unset, `live`
23
+ * carries on the velocity of whatever was animating the property.
24
+ */
25
+ velocity?: number | Record<string, number>;
26
+ /** Settled within this fraction of the travel (default 0.01) */
27
+ restDelta?: number;
28
+ }
29
+ /** `true` (the default spring), a preset name, or options. */
30
+ export type SpringVars = true | SpringPresetName | SpringOptions;
31
+ /** The parameters for one property, apart from `from`, `to` and velocity. */
32
+ export declare function springParameters(value: SpringVars): Omit<SpringConfig, 'from' | 'to' | 'velocity'>;
33
+ /** The velocity the options give a property, if they give one. */
34
+ export declare function springVelocity(value: SpringVars, property: string): number | undefined;