@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,30 @@
1
+ import type { TimelineDefinition, AnyTrack } from '../types';
2
+ import { Timeline } from '../core/timeline';
3
+ /**
4
+ * Serialize a track to a plain JSON-compatible object.
5
+ * Handles both regular tracks and motion path tracks.
6
+ */
7
+ export declare function serializeTrack(track: AnyTrack): AnyTrack;
8
+ /**
9
+ * Deserialize a plain object to a Track.
10
+ * Handles both regular tracks and motion path tracks.
11
+ * Ensures keyframes are sorted by time.
12
+ */
13
+ export declare function deserializeTrack(data: AnyTrack): AnyTrack;
14
+ /**
15
+ * Serialize a Timeline to a TimelineDefinition object.
16
+ */
17
+ export declare function serializeTimeline(timeline: Timeline): TimelineDefinition;
18
+ /**
19
+ * Deserialize a TimelineDefinition to a Timeline instance. A file written for a
20
+ * newer format version is refused with a clear error rather than played wrongly.
21
+ */
22
+ export declare function deserializeTimeline(definition: TimelineDefinition): Timeline;
23
+ /**
24
+ * Convert a Timeline to a JSON string.
25
+ */
26
+ export declare function toJSON(timeline: Timeline): string;
27
+ /**
28
+ * Parse a JSON string to a Timeline instance.
29
+ */
30
+ export declare function fromJSON(json: string): Timeline;
@@ -0,0 +1,2 @@
1
+ /** Text animation: typing and scrambling from one string to another. */
2
+ export { textAt, charactersFor } from './text-value';
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Text animation: the string a text track shows at a moment in time.
3
+ *
4
+ * Pure and deterministic. "Random" scramble characters come from a hash of the
5
+ * seed, the character's position and the current refresh step — never from
6
+ * Math.random — so scrubbing backwards shows exactly what playing forwards did,
7
+ * and every export of the same timeline matches.
8
+ */
9
+ import type { TextChars, TextConfig } from '../types';
10
+ /** The characters a `chars` setting names (split by code point, so emoji work). */
11
+ export declare function charactersFor(chars: TextChars | undefined): string[];
12
+ /**
13
+ * The text at `progress` (0–1, already eased) after `elapsedMs` of the tween.
14
+ * Progress 0 returns `from` and progress 1 returns `to`, exactly.
15
+ */
16
+ export declare function textAt(config: TextConfig, progress: number, elapsedMs?: number): string;
@@ -0,0 +1,401 @@
1
+ /**
2
+ * Core type definitions for tinyfly animation engine.
3
+ * All types are JSON-serializable to support persistence and cross-platform playback.
4
+ */
5
+ /** Supported property value types for animation */
6
+ export type AnimatableValue = number | string | number[];
7
+ /** Easing function signature - takes normalized time (0-1), returns eased value (0-1) */
8
+ export type EasingFunction = (t: number) => number;
9
+ /** Built-in easing type identifiers for JSON serialization */
10
+ export type BuiltInEasingType = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'ease-in-quad' | 'ease-out-quad' | 'ease-in-out-quad' | 'ease-in-cubic' | 'ease-out-cubic' | 'ease-in-out-cubic';
11
+ /** Cubic bezier control points [cp1x, cp1y, cp2x, cp2y] - values from 0 to 1 */
12
+ export type CubicBezierPoints = [number, number, number, number];
13
+ /** Custom cubic-bezier easing definition */
14
+ export interface CubicBezierEasing {
15
+ type: 'cubic-bezier';
16
+ /** Control points: [cp1x, cp1y, cp2x, cp2y] */
17
+ points: CubicBezierPoints;
18
+ }
19
+ /** Which end of an ease carries its character: `out` settles at the end (the default). */
20
+ export type EaseMode = 'in' | 'out' | 'in-out';
21
+ /**
22
+ * A stepped ease (CSS `steps()`): the value holds, then jumps. `position` says
23
+ * where the jumps are, as in CSS: `end` (default) jumps at the end of each step,
24
+ * `start` at the beginning, `none` holds both ends (`count` stops, `count − 1`
25
+ * jumps), `both` jumps at both ends.
26
+ */
27
+ export interface StepsEasing {
28
+ type: 'steps';
29
+ count: number;
30
+ position?: 'start' | 'end' | 'none' | 'both';
31
+ }
32
+ /** Overshoots and oscillates. `amplitude` ≥ 1 scales the overshoot; `period` is the oscillation length (0.3). */
33
+ export interface ElasticEasing {
34
+ type: 'elastic';
35
+ mode?: EaseMode;
36
+ amplitude?: number;
37
+ period?: number;
38
+ }
39
+ /** Rebounds off the end value with decreasing height. */
40
+ export interface BounceEasing {
41
+ type: 'bounce';
42
+ mode?: EaseMode;
43
+ }
44
+ /** Pulls back past the start (or pushes past the end) by `overshoot` (1.70158). */
45
+ export interface BackEasing {
46
+ type: 'back';
47
+ mode?: EaseMode;
48
+ overshoot?: number;
49
+ }
50
+ /** Eases with parameters that are evaluated at play time, not approximated. */
51
+ export type ParametricEasing = StepsEasing | ElasticEasing | BounceEasing | BackEasing;
52
+ /** Easing type - a built-in name, a custom cubic-bezier, or a parametric ease */
53
+ export type EasingType = BuiltInEasingType | CubicBezierEasing | ParametricEasing;
54
+ /** Type guard to check if easing is a cubic-bezier */
55
+ export declare function isCubicBezierEasing(easing: EasingType | undefined): easing is CubicBezierEasing;
56
+ /** Type guard for steps / elastic / bounce / back eases */
57
+ export declare function isParametricEasing(easing: EasingType | undefined): easing is ParametricEasing;
58
+ /** A single keyframe defining a value at a specific time */
59
+ export interface Keyframe<T extends AnimatableValue = AnimatableValue> {
60
+ /** Time in milliseconds from timeline start */
61
+ time: number;
62
+ /** Value at this keyframe */
63
+ value: T;
64
+ /** Easing function to use when interpolating TO this keyframe */
65
+ easing?: EasingType;
66
+ }
67
+ /** A track controls a single property over time */
68
+ export interface Track<T extends AnimatableValue = AnimatableValue> {
69
+ /** Unique identifier for this track */
70
+ id: string;
71
+ /** Target identifier (e.g., element id, object reference key) */
72
+ target: string;
73
+ /** Property name to animate (e.g., 'opacity', 'x', 'transform') */
74
+ property: string;
75
+ /** Ordered list of keyframes (must be sorted by time) */
76
+ keyframes: Keyframe<T>[];
77
+ /**
78
+ * Shift every keyframe by this many milliseconds at evaluation time.
79
+ * Purely a convenience: `delay: 200` is equivalent to adding 200 to each
80
+ * keyframe's `time`. Kept separate so authoring tools can adjust a track's
81
+ * start without rewriting its keyframes.
82
+ */
83
+ delay?: number;
84
+ /**
85
+ * Extra milliseconds held after the last keyframe. Contributes to the track's
86
+ * duration (and therefore the timeline's) without changing its final value.
87
+ */
88
+ endDelay?: number;
89
+ /**
90
+ * Animate several targets from one track, each offset by `stagger`.
91
+ * When present, `target` is ignored. See `StaggerConfig`.
92
+ */
93
+ targets?: string[];
94
+ /** Per-target time offsets for `targets`. Ignored when `targets` is absent. */
95
+ stagger?: StaggerConfig;
96
+ }
97
+ /** Where a stagger starts fanning out from */
98
+ export type StaggerFrom = 'start' | 'end' | 'center' | 'edges' | number;
99
+ /**
100
+ * Runtime stagger: expands one track across `targets` by offsetting each
101
+ * target's time. Serializable, and cheaper than baking N tracks when N is large.
102
+ */
103
+ export interface StaggerConfig {
104
+ /** Milliseconds between consecutive targets. Ignored when `amount` is set. */
105
+ each?: number;
106
+ /** Total spread in milliseconds, divided across the targets. Wins over `each`. */
107
+ amount?: number;
108
+ /** Which target gets offset 0 and which way the fan runs (default: 'start') */
109
+ from?: StaggerFrom;
110
+ /**
111
+ * Explicit milliseconds per target, in target order — for layouts no 1D fan
112
+ * describes (grids, random order). Wins over `each`, `amount` and `from`.
113
+ */
114
+ offsets?: number[];
115
+ }
116
+ /** Timeline playback state */
117
+ export type PlaybackState = 'idle' | 'playing' | 'paused';
118
+ /** Timeline playback direction */
119
+ export type PlaybackDirection = 'forward' | 'reverse';
120
+ /** Timeline configuration */
121
+ export interface TimelineConfig {
122
+ /** Total duration in milliseconds (auto-calculated from tracks if not specified) */
123
+ duration?: number;
124
+ /** Number of times to loop (0 = no loop, -1 = infinite) */
125
+ loop?: number;
126
+ /** Playback speed multiplier (1 = normal, 2 = double speed, 0.5 = half speed) */
127
+ speed?: number;
128
+ /** Whether to alternate direction on each loop iteration */
129
+ alternate?: boolean;
130
+ /** Milliseconds to hold at the end before starting the next loop iteration */
131
+ repeatDelay?: number;
132
+ /**
133
+ * Named points in time, in order — the steps of a teaching animation. Players
134
+ * can step between them, stop at them and show their captions.
135
+ */
136
+ markers?: TimelineMarker[];
137
+ }
138
+ /** A named step on a timeline. */
139
+ export interface TimelineMarker {
140
+ /** Unique within the timeline; captions are keyed by it */
141
+ id: string;
142
+ /** Milliseconds from the start */
143
+ time: number;
144
+ /** A short label, in the timeline's own language (captions can translate it) */
145
+ label?: string;
146
+ /** Playback stops here, even when not stepping (predict-then-reveal) */
147
+ pause?: boolean;
148
+ /** A question to show while stopped here, before revealing the next step */
149
+ question?: string;
150
+ }
151
+ /** The JSON format version this engine writes and reads. */
152
+ export declare const FORMAT_VERSION = 1;
153
+ /** Serializable timeline definition */
154
+ export interface TimelineDefinition {
155
+ /**
156
+ * The format version the file was written for (absent means 1). A reader
157
+ * refuses files from a newer format rather than playing them wrongly.
158
+ */
159
+ formatVersion?: number;
160
+ /** Unique identifier */
161
+ id: string;
162
+ /** Human-readable name */
163
+ name?: string;
164
+ /** Timeline configuration */
165
+ config: TimelineConfig;
166
+ /** Tracks in this timeline (keyframed, motion-path, or spring) */
167
+ tracks: AnyTrack[];
168
+ /**
169
+ * Caption text per language, per marker id: `{ en: { grow: 'The slice grows' } }`.
170
+ * Kept out of the tracks so translating an animation never touches its timing.
171
+ */
172
+ captions?: Record<string, Record<string, string>>;
173
+ }
174
+ /** Current state of an animation at a given time */
175
+ export interface AnimationState {
176
+ /** Map of target -> property -> current value */
177
+ values: Map<string, Map<string, AnimatableValue>>;
178
+ /** Current time in milliseconds */
179
+ currentTime: number;
180
+ /** Current playback state */
181
+ playbackState: PlaybackState;
182
+ /** Current direction */
183
+ direction: PlaybackDirection;
184
+ /** Current loop iteration (0-indexed) */
185
+ loopIteration: number;
186
+ }
187
+ /** Interpolator function signature */
188
+ export type Interpolator<T extends AnimatableValue = AnimatableValue> = (from: T, to: T, progress: number) => T;
189
+ /** Configuration for motion path animation */
190
+ export interface MotionPathConfig {
191
+ /** SVG path data string (d attribute) */
192
+ pathData: string;
193
+ /** Whether to auto-rotate element to follow path tangent */
194
+ autoRotate?: boolean;
195
+ /** Rotation offset in degrees (added to tangent angle when autoRotate is true) */
196
+ rotateOffset?: number;
197
+ /**
198
+ * Affine transform `[a, b, c, d, e, f]` applied to every point on the path
199
+ * (x' = a·x + c·y + e, y' = b·x + d·y + f), and to its tangent. Places a path
200
+ * drawn in one coordinate space — an SVG's user units — into the space of the
201
+ * element that follows it. Omit for identity.
202
+ */
203
+ matrix?: [number, number, number, number, number, number];
204
+ }
205
+ /** A track that animates along a motion path */
206
+ export interface MotionPathTrack {
207
+ /** Unique identifier for this track */
208
+ id: string;
209
+ /** Target identifier (e.g., element id) */
210
+ target: string;
211
+ /** Property type - always 'motionPath' for motion path tracks */
212
+ property: 'motionPath';
213
+ /** Motion path configuration */
214
+ motionPathConfig: MotionPathConfig;
215
+ /** Keyframes with progress values (0-1) */
216
+ keyframes: Keyframe<number>[];
217
+ /** Shift every keyframe by this many milliseconds at evaluation time */
218
+ delay?: number;
219
+ /** Extra milliseconds held after the last keyframe */
220
+ endDelay?: number;
221
+ /** Animate several targets along the path, each offset by `stagger` */
222
+ targets?: string[];
223
+ /** Per-target offsets for `targets` */
224
+ stagger?: StaggerConfig;
225
+ }
226
+ /** Result of computing position on a motion path */
227
+ export interface MotionPathPoint {
228
+ /** X coordinate on the path */
229
+ x: number;
230
+ /** Y coordinate on the path */
231
+ y: number;
232
+ /** Tangent angle in degrees */
233
+ angle: number;
234
+ }
235
+ /** How a text track gets from one string to another. */
236
+ export type TextMode = 'type' | 'scramble';
237
+ /** A character set name, or a string of the characters to use. */
238
+ export type TextChars = 'upperCase' | 'lowerCase' | 'upperAndLowerCase' | 'numbers' | (string & {});
239
+ /**
240
+ * Parameters for animating text. Plain data: the string at any moment is a pure
241
+ * function of these, the eased progress and the elapsed time.
242
+ */
243
+ export interface TextConfig {
244
+ /** Text at progress 0 (default: empty) */
245
+ from?: string;
246
+ /** Text at progress 1 */
247
+ to: string;
248
+ /**
249
+ * `type`: the new text replaces the old one character at a time.
250
+ * `scramble`: unrevealed characters cycle through random ones, then settle.
251
+ */
252
+ mode: TextMode;
253
+ /** Scramble: characters to draw from (default: `upperCase`) */
254
+ chars?: TextChars;
255
+ /** Scramble: how often random characters change, per second (default: 20) */
256
+ refreshRate?: number;
257
+ /** Scramble: fraction of the tween (0–1) before characters start to settle */
258
+ revealDelay?: number;
259
+ /** Scramble: grow or shrink the length from `from` to `to` over the tween (default: true) */
260
+ tweenLength?: boolean;
261
+ /** Reveal from the end of the string instead of the start */
262
+ rightToLeft?: boolean;
263
+ /** Scramble: seed for the random characters, so every playback matches */
264
+ seed?: number;
265
+ }
266
+ /**
267
+ * A track that animates text. Keyframes carry progress (0–1) with easing, like
268
+ * a motion path, and the timeline expands progress into the string.
269
+ */
270
+ export interface TextTrack {
271
+ id: string;
272
+ target: string;
273
+ /** Always 'text' for text tracks */
274
+ property: 'text';
275
+ textConfig: TextConfig;
276
+ /** Keyframes with progress values (0-1) */
277
+ keyframes: Keyframe<number>[];
278
+ delay?: number;
279
+ endDelay?: number;
280
+ targets?: string[];
281
+ stagger?: StaggerConfig;
282
+ }
283
+ /** Type guard to check if a track is a text track */
284
+ export declare function isTextTrack(track: AnyTrack): track is TextTrack;
285
+ /**
286
+ * Parameters for a physically-simulated spring. Serializable: the animation is
287
+ * the parameters, not a baked curve, so a spring track is as portable as a
288
+ * keyframe track.
289
+ */
290
+ export interface SpringConfig {
291
+ /** Starting value */
292
+ from: number;
293
+ /** Resting target value */
294
+ to: number;
295
+ /** Spring constant — higher is snappier (default: 180) */
296
+ stiffness?: number;
297
+ /** Damping coefficient — higher settles sooner, 0 oscillates forever (default: 12) */
298
+ damping?: number;
299
+ /** Mass — higher is more sluggish (default: 1) */
300
+ mass?: number;
301
+ /** Initial velocity in units per second (default: 0) */
302
+ velocity?: number;
303
+ /**
304
+ * How close to `to` counts as settled, as a fraction of the spring's travel
305
+ * distance (default: 0.01, i.e. within 1% of the journey).
306
+ *
307
+ * Relative rather than absolute so that settling depends on the spring's
308
+ * parameters and not on the units of the property it drives — `scale: 0→1`
309
+ * and `x: 0→100` settle at the same time.
310
+ */
311
+ restDelta?: number;
312
+ /**
313
+ * How slow counts as settled, as a fraction of the travel distance per
314
+ * second (default: 0.1). Relative for the same reason as `restDelta`.
315
+ */
316
+ restSpeed?: number;
317
+ }
318
+ /**
319
+ * A track whose values come from a spring simulation instead of keyframes.
320
+ *
321
+ * Evaluated by integrating forward from t=0 at a fixed timestep, so it stays a
322
+ * pure function of time — seeking backwards yields the same values as playing
323
+ * forwards, and two runs produce identical output.
324
+ */
325
+ export interface SpringTrack {
326
+ /** Unique identifier for this track */
327
+ id: string;
328
+ /** Target identifier */
329
+ target: string;
330
+ /** Property name to animate */
331
+ property: string;
332
+ /** Marks this as a spring track for serialization and dispatch */
333
+ kind: 'spring';
334
+ /** Spring parameters */
335
+ spring: SpringConfig;
336
+ /** Milliseconds before the spring starts */
337
+ delay?: number;
338
+ /** Animate several targets, each offset by `stagger` */
339
+ targets?: string[];
340
+ /** Per-target offsets for `targets` */
341
+ stagger?: StaggerConfig;
342
+ }
343
+ /**
344
+ * A throw: a value released with a velocity that slows under friction and comes
345
+ * to rest — optionally snapping to a chosen resting place and staying in
346
+ * bounds. Plain data; the motion is a closed-form function of time.
347
+ */
348
+ export interface InertiaConfig {
349
+ /** Value at release */
350
+ from: number;
351
+ /** Speed at release, in units per second (negative moves down) */
352
+ velocity: number;
353
+ /** How quickly it slows: exponential decay rate per second (default: 4) */
354
+ friction?: number;
355
+ /** Lowest resting value */
356
+ min?: number;
357
+ /** Highest resting value */
358
+ max?: number;
359
+ /**
360
+ * Where it may come to rest. A number snaps to multiples of it (a grid); an
361
+ * array snaps to the nearest listed value. It still slows the same way, just
362
+ * aimed so it lands exactly there.
363
+ */
364
+ end?: number | number[];
365
+ /** How close to the resting value counts as settled (default: scales with distance) */
366
+ restDelta?: number;
367
+ }
368
+ /** A track whose value is a throw with inertia, not keyframes. */
369
+ export interface InertiaTrack {
370
+ id: string;
371
+ target: string;
372
+ property: string;
373
+ /** Marks this as an inertia track for serialization and dispatch */
374
+ kind: 'inertia';
375
+ inertia: InertiaConfig;
376
+ /** Milliseconds before the release */
377
+ delay?: number;
378
+ targets?: string[];
379
+ stagger?: StaggerConfig;
380
+ }
381
+ /** Type guard to check if a track is an inertia track */
382
+ export declare function isInertiaTrack(track: AnyTrack): track is InertiaTrack;
383
+ /** Type guard to check if a track is a spring track */
384
+ export declare function isSpringTrack(track: AnyTrack): track is SpringTrack;
385
+ /** Type guard to check if a track is a motion path track */
386
+ export declare function isMotionPathTrack(track: AnyTrack): track is MotionPathTrack;
387
+ /** Type guard to check if a value is a motion path point */
388
+ export declare function isMotionPathPoint(value: unknown): value is MotionPathPoint;
389
+ /** Union type for any track */
390
+ export type AnyTrack = Track | MotionPathTrack | TextTrack | SpringTrack | InertiaTrack;
391
+ /**
392
+ * Tracks whose values come from keyframes — everything except springs and
393
+ * inertia, whose motion is computed from parameters.
394
+ * Most authoring and export code only makes sense for these.
395
+ */
396
+ export type KeyframedTrack = Track | MotionPathTrack | TextTrack;
397
+ /**
398
+ * Narrow a track to the keyframed kinds. Use this before reaching for
399
+ * `.keyframes`, which spring and inertia tracks do not have.
400
+ */
401
+ export declare function hasKeyframes(track: AnyTrack): track is KeyframedTrack;
@@ -0,0 +1,35 @@
1
+ import { type DependencyList, type RefObject } from 'react';
2
+ import { type LiveApi, type LiveContext } from '../compat/gsap';
3
+ /**
4
+ * `tinyfly/react`: run `live` animations in a component, cleaned up for you
5
+ * (like `@gsap/react`'s `useGSAP`).
6
+ *
7
+ * function Hero() {
8
+ * const root = useRef(null)
9
+ * const { contextSafe } = useTinyfly((live) => {
10
+ * live.from('.title', { y: 40, opacity: 0 }) // selectors match inside root
11
+ * }, { scope: root })
12
+ * const pop = contextSafe(() => live.to('.cta', { scale: 1.1, yoyo: true, repeat: 1 }))
13
+ * return <section ref={root}><h1 className="title">Hi</h1><button className="cta" onClick={pop}>Go</button></section>
14
+ * }
15
+ *
16
+ * Everything the setup creates — tweens, timelines, scroll triggers and pins,
17
+ * split text, draggables, smooth scrolling — is reverted when the component
18
+ * unmounts, and before the setup runs again when `dependencies` change. Work
19
+ * started later (in an event handler) joins through `contextSafe`.
20
+ */
21
+ export interface UseTinyflyOptions {
22
+ /** Selectors in the setup resolve inside this element */
23
+ scope?: RefObject<Element | null>;
24
+ /** Run the setup again when these change (default: once) */
25
+ dependencies?: DependencyList;
26
+ /** The live API to use (default: the shared `live`) */
27
+ live?: LiveApi;
28
+ }
29
+ export interface UseTinyflyResult {
30
+ /** The current context, once the setup has run */
31
+ readonly context: LiveContext | undefined;
32
+ /** Wrap an event handler so what it creates is reverted with the component */
33
+ contextSafe<F extends (...args: never[]) => unknown>(fn: F): F;
34
+ }
35
+ export declare function useTinyfly(setup: (live: LiveApi, context: LiveContext) => void | (() => void), options?: UseTinyflyOptions | DependencyList): UseTinyflyResult;
@@ -0,0 +1,16 @@
1
+ import { type LiveApi, type LiveContext } from '../compat/gsap';
2
+ /**
3
+ * `tinyfly/solid`: run `live` animations in a component, cleaned up for you.
4
+ *
5
+ * let root!: HTMLElement
6
+ * createTinyfly((live) => live.from('.title', { y: 40, opacity: 0 }), () => root)
7
+ * return <section ref={root}><h1 class="title">Hi</h1></section>
8
+ *
9
+ * The setup runs on mount, scoped to the element `scope` returns. Everything it
10
+ * creates is reverted when the owner is cleaned up.
11
+ */
12
+ export declare function createTinyfly(setup: (live: LiveApi, context: LiveContext) => void | (() => void), scope?: () => Element | undefined, api?: LiveApi): {
13
+ readonly context: LiveContext | undefined;
14
+ /** Wrap an event handler so what it creates is reverted with the component */
15
+ contextSafe<F extends (...args: never[]) => unknown>(fn: F): F;
16
+ };
@@ -0,0 +1,19 @@
1
+ import { type LiveApi, type LiveContext } from '../compat/gsap';
2
+ /**
3
+ * `tinyfly/svelte`: a Svelte action (no Svelte import needed).
4
+ *
5
+ * <script>
6
+ * import { tinyfly } from '@algorisys/tinyfly/svelte'
7
+ * const intro = (live) => live.from('.title', { y: 40, opacity: 0 })
8
+ * </script>
9
+ * <section use:tinyfly={intro}><h1 class="title">Hi</h1></section>
10
+ *
11
+ * The setup runs with selectors scoped to the element. Everything it creates is
12
+ * reverted when the element is removed, and before a new setup runs when the
13
+ * action's parameter changes.
14
+ */
15
+ export type TinyflySetup = (live: LiveApi, context: LiveContext, node: Element) => void | (() => void);
16
+ export declare function tinyfly(node: Element, setup: TinyflySetup, api?: LiveApi): {
17
+ update(next: TinyflySetup): void;
18
+ destroy(): void;
19
+ };
@@ -0,0 +1,27 @@
1
+ import { type Ref, type WatchSource } from 'vue';
2
+ import { type LiveApi, type LiveContext } from '../compat/gsap';
3
+ /**
4
+ * `tinyfly/vue`: run `live` animations in a component, cleaned up for you.
5
+ *
6
+ * const root = ref(null)
7
+ * const { contextSafe } = useTinyfly((live) => {
8
+ * live.from('.title', { y: 40, opacity: 0 })
9
+ * }, { scope: root })
10
+ *
11
+ * The setup runs when the component mounts, inside a `live.context` scoped to
12
+ * `scope`. Everything it creates is reverted before the component unmounts, and
13
+ * before the setup runs again when a `watch` source changes.
14
+ */
15
+ export interface UseTinyflyOptions {
16
+ /** Selectors in the setup resolve inside this element */
17
+ scope?: Ref<Element | null | undefined>;
18
+ /** Run the setup again when these change */
19
+ watch?: WatchSource[];
20
+ /** The live API to use (default: the shared `live`) */
21
+ live?: LiveApi;
22
+ }
23
+ export declare function useTinyfly(setup: (live: LiveApi, context: LiveContext) => void | (() => void), options?: UseTinyflyOptions): {
24
+ readonly context: LiveContext | undefined;
25
+ /** Wrap an event handler so what it creates is reverted with the component */
26
+ contextSafe<F extends (...args: never[]) => unknown>(fn: F): F;
27
+ };