@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,133 @@
1
+ import type { Timeline } from '../engine';
2
+ import { type ObserverState } from './observer';
3
+ /**
4
+ * Drag a target, or drag to scrub a timeline.
5
+ *
6
+ * Two output modes, and the difference matters:
7
+ *
8
+ * - `mode: 'scrub'` maps horizontal or vertical drag distance onto a
9
+ * timeline's playhead. Nothing new is stored; the timeline is still the
10
+ * source of truth, so this composes with everything else.
11
+ * - `mode: 'move'` reports positions for the caller to apply to a target.
12
+ * This is live interaction with **no serializable representation** — a
13
+ * dragged position is not part of the animation document. Use it for
14
+ * editors and toys, not for something you intend to export.
15
+ */
16
+ export type DragAxis = 'x' | 'y' | 'both';
17
+ export type DragMode = 'move' | 'scrub';
18
+ export interface DragBounds {
19
+ minX?: number;
20
+ maxX?: number;
21
+ minY?: number;
22
+ maxY?: number;
23
+ }
24
+ export interface DraggableOptions {
25
+ /** Element that receives the drag gestures */
26
+ target: EventTarget;
27
+ /** Which axes can move (default: 'both') */
28
+ axis?: DragAxis;
29
+ /** What dragging does (default: 'move') */
30
+ mode?: DragMode;
31
+ /** Clamp the dragged position */
32
+ bounds?: DragBounds;
33
+ /** Snap the dragged position to a grid of this size, in pixels */
34
+ snap?: number;
35
+ /**
36
+ * Extra positions to snap to, in pixels — e.g. other elements' edges or
37
+ * guides. Combined with the grid; the nearest match within `snapThreshold`
38
+ * wins.
39
+ */
40
+ snapLinesX?: number[];
41
+ snapLinesY?: number[];
42
+ /**
43
+ * How close a snap line must be to catch, in pixels.
44
+ *
45
+ * Defaults to half the grid size when `snap` is set, so every position is
46
+ * within reach of a grid line and grid snapping behaves like plain rounding.
47
+ * With no grid it defaults to 8px, which is the right feel for snapping to
48
+ * another element's edge.
49
+ */
50
+ snapThreshold?: number;
51
+ /** Starting position */
52
+ initialX?: number;
53
+ initialY?: number;
54
+ /**
55
+ * Where the target is when a gesture begins. Use when something else can move
56
+ * it between drags — a throw with inertia, say — so the next drag starts from
57
+ * where it actually is rather than where the last drag left it.
58
+ */
59
+ getPosition?: () => {
60
+ x: number;
61
+ y: number;
62
+ };
63
+ /** mode: 'scrub' — the timeline to scrub */
64
+ timeline?: Timeline;
65
+ /**
66
+ * mode: 'scrub' — pixels of drag that cover the whole timeline
67
+ * (default: 500). Negative reverses the direction.
68
+ */
69
+ scrubDistance?: number;
70
+ /** Called with the new position on every move */
71
+ onDrag?: (position: {
72
+ x: number;
73
+ y: number;
74
+ }, state: ObserverState) => void;
75
+ /**
76
+ * Called with the lines that caught on this move (null where nothing did),
77
+ * so a host can draw snap guides.
78
+ */
79
+ onSnap?: (lines: {
80
+ x: number | null;
81
+ y: number | null;
82
+ }) => void;
83
+ onPress?: (state: ObserverState) => void;
84
+ onRelease?: (state: ObserverState) => void;
85
+ }
86
+ export declare class Draggable {
87
+ private options;
88
+ private observer;
89
+ private x;
90
+ private y;
91
+ /** Position when the current gesture began */
92
+ private originX;
93
+ private originY;
94
+ /** Lines that caught on the last constraint pass, for guide drawing */
95
+ private snappedX;
96
+ private snappedY;
97
+ constructor(options: DraggableOptions);
98
+ start(): void;
99
+ stop(): void;
100
+ destroy(): void;
101
+ /** Current dragged position. */
102
+ get position(): {
103
+ x: number;
104
+ y: number;
105
+ };
106
+ /** Velocity at the last movement, in pixels per second. */
107
+ get velocity(): {
108
+ x: number;
109
+ y: number;
110
+ };
111
+ /** Move the target programmatically, applying bounds and snapping. */
112
+ setPosition(x: number, y: number): void;
113
+ /** The snap lines that caught on the last move, for drawing guides. */
114
+ get snapLines(): {
115
+ x: number | null;
116
+ y: number | null;
117
+ };
118
+ /** See `snapThreshold` in the options. */
119
+ private snapThreshold;
120
+ private handleMove;
121
+ /** Map the dragged distance onto the timeline's playhead. */
122
+ private scrub;
123
+ /**
124
+ * Apply snapping, then bounds. Snapping uses the shared `snapAxis` helper —
125
+ * the same one the editor stage snaps with — rather than a private rounding
126
+ * rule, so grid and edge snapping behave identically in both places.
127
+ *
128
+ * Bounds are applied last so a snap can never push the target out of range.
129
+ */
130
+ private applyConstraints;
131
+ }
132
+ /** Convenience wrapper: create a started Draggable. */
133
+ export declare function draggable(options: DraggableOptions): Draggable;
@@ -0,0 +1,3 @@
1
+ export * from './observer';
2
+ export * from './snap';
3
+ export * from './draggable';
@@ -0,0 +1,80 @@
1
+ /**
2
+ * Unified pointer / wheel / touch input.
3
+ *
4
+ * GSAP's Observer in miniature: one event source that normalises mouse, touch
5
+ * and wheel into the same delta+velocity shape, so `Draggable` and any
6
+ * scroll-like gesture can be written once.
7
+ *
8
+ * This lives outside the engine and outside the default player bundle — it is
9
+ * live interaction, which by definition has no serializable representation.
10
+ */
11
+ export interface ObserverState {
12
+ /** Movement since the last event, in pixels */
13
+ deltaX: number;
14
+ deltaY: number;
15
+ /** Smoothed speed in pixels per second */
16
+ velocityX: number;
17
+ velocityY: number;
18
+ /** Total movement since the gesture began */
19
+ totalX: number;
20
+ totalY: number;
21
+ /** Whether a press/touch is currently down */
22
+ isDragging: boolean;
23
+ /** The originating event, for callers that need modifiers or targets */
24
+ event: Event;
25
+ }
26
+ export type ObserverCallback = (state: ObserverState) => void;
27
+ export interface ObserverOptions {
28
+ /** Element to listen on */
29
+ target: EventTarget;
30
+ /** Which input kinds to observe (default: pointer and touch, not wheel) */
31
+ type?: Array<'pointer' | 'touch' | 'wheel'>;
32
+ /** Gesture started */
33
+ onPress?: ObserverCallback;
34
+ /** Pointer moved while down, or the wheel turned */
35
+ onMove?: ObserverCallback;
36
+ /** Gesture ended */
37
+ onRelease?: ObserverCallback;
38
+ /**
39
+ * Ignore movements smaller than this many pixels before starting a drag,
40
+ * so a click is not mistaken for a drag (default: 3).
41
+ */
42
+ tolerance?: number;
43
+ /** Call preventDefault on handled events (default: true) */
44
+ preventDefault?: boolean;
45
+ }
46
+ export declare class Observer {
47
+ private options;
48
+ private target;
49
+ private running;
50
+ private dragging;
51
+ private passedTolerance;
52
+ private lastX;
53
+ private lastY;
54
+ private startX;
55
+ private startY;
56
+ private velocityX;
57
+ private velocityY;
58
+ private lastTime;
59
+ constructor(options: ObserverOptions);
60
+ start(): void;
61
+ stop(): void;
62
+ destroy(): void;
63
+ /** Current velocity, in pixels per second. Read it on release for inertia. */
64
+ get velocity(): {
65
+ x: number;
66
+ y: number;
67
+ };
68
+ private begin;
69
+ private move;
70
+ private end;
71
+ private updateVelocity;
72
+ private stateFrom;
73
+ private onPointerDown;
74
+ private onPointerMove;
75
+ private onPointerUp;
76
+ private onTouchStart;
77
+ private onTouchMove;
78
+ private onTouchEnd;
79
+ private onWheel;
80
+ }
@@ -0,0 +1,30 @@
1
+ /**
2
+ * Snapping math, shared by the editor stage and `Draggable`.
3
+ *
4
+ * Pure and unit-tested: callers feed it the moving object's candidate lines
5
+ * (left/centre/right, top/middle/bottom) and the static lines to snap against
6
+ * (grid multiples + other elements' edges), and get back the smallest
7
+ * adjustment plus the line that caught, for drawing a guide.
8
+ *
9
+ * Unit-agnostic. The editor works in stage (artboard) units and converts its
10
+ * pixel threshold by the preview scale; `Draggable` works in raw pixels.
11
+ */
12
+ export interface AxisSnap {
13
+ /** Amount to add to the moving element on this axis to align (0 = no snap). */
14
+ delta: number;
15
+ /** The static line the element snapped to, or null when nothing was close. */
16
+ line: number | null;
17
+ }
18
+ /**
19
+ * Find the closest snap on one axis. `movingLines` are the moving element's
20
+ * candidate positions (e.g. its left, centre, right); `staticLines` are the
21
+ * positions to snap to. Returns the delta that aligns the nearest pair within
22
+ * `threshold`, preferring the closest match.
23
+ */
24
+ export declare function snapAxis(movingLines: number[], staticLines: number[], threshold: number): AxisSnap;
25
+ /**
26
+ * Grid snap lines near a set of moving lines: for each moving line, the nearest
27
+ * multiple of `gridSize`. Returns [] when the grid is off (size <= 0), so grid
28
+ * snapping composes with edge snapping by concatenating both static-line sets.
29
+ */
30
+ export declare function gridLinesFor(movingLines: number[], gridSize: number): number[];
@@ -0,0 +1,7 @@
1
+ export { TinyflyPlayer, play, create } from './player';
2
+ export type { PlayerOptions, TargetMapping, SymbolAnimation } from './player';
3
+ export { MediaSync, syncMediaElement } from './media-sync';
4
+ export type { SyncableMedia, MediaSyncOptions } from './media-sync';
5
+ export { TinyflySequencer, playSequence } from './sequencer';
6
+ export type { TransitionType, SceneTransition, SerializedElement, SequenceScene, SequenceDefinition, SequencerOptions, } from './sequence-types';
7
+ export { DEFAULT_TRANSITION } from './sequence-types';
@@ -0,0 +1,60 @@
1
+ /**
2
+ * Keeps an audio/video element locked to the animation timeline's clock.
3
+ *
4
+ * The engine stays framework-agnostic — this helper depends only on a small
5
+ * structural subset of `HTMLMediaElement`, so it is trivial to test and can also
6
+ * drive any custom media source. The timeline remains the single source of truth
7
+ * for time; the media follows it, and drift is corrected when it exceeds a
8
+ * tolerance (seeking every frame would stutter playback).
9
+ */
10
+ /** The minimal media interface MediaSync needs (satisfied by HTMLMediaElement). */
11
+ export interface SyncableMedia {
12
+ /** Playback position in seconds. */
13
+ currentTime: number;
14
+ /** Whether the media is currently paused. */
15
+ readonly paused: boolean;
16
+ /** Playback rate multiplier. */
17
+ playbackRate: number;
18
+ play(): Promise<void> | void;
19
+ pause(): void;
20
+ }
21
+ export interface MediaSyncOptions {
22
+ /** Seconds added to the timeline time before mapping to media time. Default 0. */
23
+ offset?: number;
24
+ /**
25
+ * Maximum allowed drift in seconds before the media is hard-corrected while
26
+ * playing. Default 0.15s — small enough to stay in sync, large enough to avoid
27
+ * constant re-seeking.
28
+ */
29
+ driftTolerance?: number;
30
+ }
31
+ export declare class MediaSync {
32
+ private media;
33
+ private offset;
34
+ private driftTolerance;
35
+ constructor(media: SyncableMedia, options?: MediaSyncOptions);
36
+ /** Map a timeline time (ms) to the media's time (seconds), never negative. */
37
+ private targetTime;
38
+ /**
39
+ * Reconcile the media with the timeline for the current frame.
40
+ *
41
+ * @param timelineTimeMs current timeline time in milliseconds
42
+ * @param isPlaying whether the timeline is playing
43
+ */
44
+ update(timelineTimeMs: number, isPlaying: boolean): void;
45
+ /** Hard-align the media to a timeline time (used on explicit seeks). */
46
+ seek(timelineTimeMs: number): void;
47
+ /** Mirror the timeline playback rate onto the media. */
48
+ setRate(rate: number): void;
49
+ /** Pause the media and release it. */
50
+ dispose(): void;
51
+ private safePlay;
52
+ }
53
+ /**
54
+ * Reconcile a media element that begins at a timeline offset.
55
+ *
56
+ * Before `startMs` the media stays silent at 0; from `startMs` onward it is
57
+ * synced (via `sync`) to the elapsed time. Shared by the editor preview and the
58
+ * embed player so both behave identically.
59
+ */
60
+ export declare function syncMediaElement(sync: MediaSync, media: SyncableMedia, timelineMs: number, isPlaying: boolean, startMs: number): void;
@@ -0,0 +1,238 @@
1
+ import type { TimelineDefinition, AnimationState, TimelineMarker } from '../engine';
2
+ import { type SyncableMedia, type MediaSyncOptions } from './media-sync';
3
+ export interface PlayerOptions {
4
+ /** Playback speed multiplier (default: 1) */
5
+ speed?: number;
6
+ /** Number of times to loop (-1 for infinite, 0 for no loop) */
7
+ loop?: number;
8
+ /** Alternate direction on each loop (ping-pong effect) */
9
+ alternate?: boolean;
10
+ /** Auto-play on load (default: false) */
11
+ autoplay?: boolean;
12
+ /**
13
+ * Which frame to show as soon as the animation loads, before anything plays:
14
+ * `'start'` (default), `'end'`, a time in milliseconds, or `'none'` to leave the
15
+ * markup as it is.
16
+ */
17
+ initialFrame?: 'start' | 'end' | 'none' | number;
18
+ /**
19
+ * Under `prefers-reduced-motion: reduce`, never autoplay, show the final frame,
20
+ * and make stepping jump instead of animate. Follows changes to the setting.
21
+ * Default `true`.
22
+ */
23
+ respectReducedMotion?: boolean;
24
+ /**
25
+ * Pause while the container is off screen or the tab is hidden, and resume
26
+ * when it comes back. With `autoplay`, playback waits until it is first seen.
27
+ * Default `false`.
28
+ */
29
+ playWhenVisible?: boolean;
30
+ /** `play()` runs to the next marker and stops there. Default `false`. */
31
+ stepMode?: boolean;
32
+ /** Called when the current marker changes (undefined before the first one) */
33
+ onMarker?: (marker: TimelineMarker | undefined) => void;
34
+ /**
35
+ * Captions per language, per marker id, from a separate file: merged over the
36
+ * timeline's own captions, so translations can ship without touching its JSON.
37
+ */
38
+ captions?: Record<string, Record<string, string>>;
39
+ /** Callback when animation completes */
40
+ onComplete?: () => void;
41
+ /** Callback on each frame update */
42
+ onUpdate?: (state: AnimationState) => void;
43
+ /**
44
+ * Nested-symbol timelines keyed by symbol id. When the container has symbol
45
+ * instances (`[data-tinyfly-symbol="id"]`), each instance's inner elements are
46
+ * animated by the matching symbol timeline, looped over its duration and synced
47
+ * to the main playhead. Emitted by the editor's embed export.
48
+ */
49
+ symbols?: SymbolAnimation[];
50
+ }
51
+ /** A symbol's nested timeline, keyed by its id (for embedded symbol instances). */
52
+ export interface SymbolAnimation {
53
+ id: string;
54
+ timeline: TimelineDefinition;
55
+ }
56
+ export interface TargetMapping {
57
+ [targetName: string]: HTMLElement | string;
58
+ }
59
+ /**
60
+ * Lightweight animation player for embedding tinyfly animations.
61
+ *
62
+ * Usage:
63
+ * ```ts
64
+ * const player = new TinyflyPlayer(container)
65
+ * await player.load('animation.json')
66
+ * player.play()
67
+ * ```
68
+ */
69
+ export declare class TinyflyPlayer {
70
+ private container;
71
+ private timeline;
72
+ private adapter;
73
+ private animationFrameId;
74
+ private lastTime;
75
+ private options;
76
+ private targets;
77
+ private isDestroyed;
78
+ private mediaSync;
79
+ private mediaTargets;
80
+ private symbolInstances;
81
+ private markerList;
82
+ private readonly listeners;
83
+ /** Where the playhead was when marker crossings were last worked out */
84
+ private playhead;
85
+ /** Stop at the next marker crossed (step mode, or `next()`) */
86
+ private stepping;
87
+ private lastMarkerId;
88
+ private reducedQuery;
89
+ private readonly onReducedChange;
90
+ private visibilityObserver;
91
+ private onScreen;
92
+ /** Playback was paused by leaving the screen, and resumes on return */
93
+ private pausedByVisibility;
94
+ /** `autoplay` waits for the first time the container is seen */
95
+ private autoplayWhenSeen;
96
+ private readonly onDocumentVisibility;
97
+ constructor(container: HTMLElement | string, options?: PlayerOptions);
98
+ /**
99
+ * Load animation from a URL or JSON object.
100
+ */
101
+ load(source: string | TimelineDefinition): Promise<void>;
102
+ /**
103
+ * Be told whenever the time, play state or current marker may have changed —
104
+ * for controls and captions. Returns a function that stops it.
105
+ */
106
+ subscribe(listener: () => void): () => void;
107
+ private notify;
108
+ /** Whether the reader asked for reduced motion (and the player respects it). */
109
+ get reducedMotion(): boolean;
110
+ /** The timeline's markers, in time order. */
111
+ get markers(): TimelineMarker[];
112
+ /** The last marker at or before the playhead. */
113
+ get currentMarker(): TimelineMarker | undefined;
114
+ /**
115
+ * Caption for a marker (default: the current one) in a language (default: the
116
+ * container's closest `lang`, then the document's), falling back to the
117
+ * marker's own label.
118
+ */
119
+ caption(markerId?: string, lang?: string): string | undefined;
120
+ /** Move to the next marker: animated, or a jump under reduced motion. At the last marker, to the end. */
121
+ next(): void;
122
+ /** Jump back to the previous marker (or the start). */
123
+ prev(): void;
124
+ /** Jump to a marker by id, paused there. */
125
+ goToMarker(id: string): void;
126
+ private language;
127
+ private showInitialFrame;
128
+ private watchReducedMotion;
129
+ /** Under reduced motion: stop, and show the finished state. */
130
+ private applyReducedMotion;
131
+ private watchVisibility;
132
+ private updateVisibility;
133
+ /** Report the current marker if it changed since the last frame. */
134
+ private announceMarker;
135
+ /**
136
+ * Find embedded media elements (`[data-tinyfly-media]`) in the container and
137
+ * bind each to the timeline. Emitted by the editor's export for audio/video
138
+ * scene elements; the `data-tinyfly-start` attribute sets when each begins.
139
+ */
140
+ private scanMedia;
141
+ /** Sync all discovered media targets to a timeline time. */
142
+ private syncAllMedia;
143
+ /**
144
+ * Load animation from inline JSON string.
145
+ */
146
+ loadFromString(json: string): void;
147
+ /**
148
+ * Register a target element by name.
149
+ */
150
+ registerTarget(name: string, element: HTMLElement | string): void;
151
+ /**
152
+ * Auto-register targets using data-tinyfly attribute.
153
+ */
154
+ private autoRegisterTargets;
155
+ /**
156
+ * Bind each embedded symbol instance (`[data-tinyfly-symbol="id"]`) to its
157
+ * symbol's nested timeline: a private adapter drives the instance's inner
158
+ * elements, looped over the symbol's duration and synced to the main playhead.
159
+ */
160
+ private setupSymbolInstances;
161
+ /**
162
+ * Attach an audio/video element (or any {@link SyncableMedia}) that should
163
+ * stay in sync with the animation timeline. The timeline remains the clock;
164
+ * the media follows its play/pause/seek and rate, with drift corrected as it
165
+ * plays. Pass `{ offset }` to start the media at a timeline offset.
166
+ */
167
+ attachMedia(media: SyncableMedia, options?: MediaSyncOptions): void;
168
+ /** Detach and pause the currently synced media, if any. */
169
+ detachMedia(): void;
170
+ /**
171
+ * Start or resume playback.
172
+ */
173
+ play(): void;
174
+ private startPlaying;
175
+ /**
176
+ * Pause playback.
177
+ */
178
+ pause(): void;
179
+ /**
180
+ * Stop playback and reset to beginning.
181
+ */
182
+ stop(): void;
183
+ /**
184
+ * Seek to a specific time (in milliseconds).
185
+ */
186
+ seek(time: number): void;
187
+ /**
188
+ * Set playback speed.
189
+ */
190
+ setSpeed(speed: number): void;
191
+ /**
192
+ * Reverse playback direction.
193
+ */
194
+ reverse(): void;
195
+ /**
196
+ * Get current playback time.
197
+ */
198
+ get currentTime(): number;
199
+ /**
200
+ * Get total duration.
201
+ */
202
+ get duration(): number;
203
+ /**
204
+ * Check if currently playing.
205
+ */
206
+ get isPlaying(): boolean;
207
+ /**
208
+ * Clean up resources.
209
+ */
210
+ destroy(): void;
211
+ private startAnimationLoop;
212
+ /**
213
+ * If this frame crossed a marker it should stop at — the next one while
214
+ * stepping, or any marker with `pause` — put the playhead exactly there and pause.
215
+ */
216
+ private stopAtMarker;
217
+ private stopAnimationLoop;
218
+ private applyState;
219
+ }
220
+ /**
221
+ * Simple function to play an animation on a container.
222
+ *
223
+ * Usage:
224
+ * ```ts
225
+ * tinyfly.play('#my-element', 'animation.json', { loop: -1 })
226
+ * ```
227
+ */
228
+ export declare function play(container: HTMLElement | string, source: string | TimelineDefinition, options?: PlayerOptions): Promise<TinyflyPlayer>;
229
+ /**
230
+ * Create a player without auto-playing.
231
+ */
232
+ export declare function create(container: HTMLElement | string, options?: PlayerOptions): TinyflyPlayer;
233
+ declare const _default: {
234
+ TinyflyPlayer: typeof TinyflyPlayer;
235
+ play: typeof play;
236
+ create: typeof create;
237
+ };
238
+ export default _default;
@@ -0,0 +1,68 @@
1
+ import type { TimelineDefinition } from '../engine';
2
+ /** Available transition effects between scenes */
3
+ export type TransitionType = 'none' | 'fade' | 'slide-left' | 'slide-right' | 'slide-up' | 'slide-down';
4
+ /** Transition configuration when entering a scene */
5
+ export interface SceneTransition {
6
+ /** Transition effect type */
7
+ type: TransitionType;
8
+ /** Duration of the transition in milliseconds */
9
+ duration: number;
10
+ }
11
+ /** Default transition (no transition) */
12
+ export declare const DEFAULT_TRANSITION: SceneTransition;
13
+ /** Minimal element representation for the sequencer/embed player */
14
+ export interface SerializedElement {
15
+ type: string;
16
+ name: string;
17
+ x: number;
18
+ y: number;
19
+ width: number;
20
+ height: number;
21
+ rotation: number;
22
+ opacity: number;
23
+ /** Pre-rendered HTML for this element (complete tag with attributes) */
24
+ html: string;
25
+ }
26
+ /** A scene within a sequence (player-facing format) */
27
+ export interface SequenceScene {
28
+ id: string;
29
+ name: string;
30
+ elements: SerializedElement[];
31
+ timeline: TimelineDefinition | null;
32
+ /** Transition when entering this scene (ignored for first scene) */
33
+ transition: SceneTransition;
34
+ }
35
+ /** Serializable sequence definition for the multi-scene player */
36
+ /** A symbol's nested timeline, keyed by id, for embedded symbol instances. */
37
+ export interface SequenceSymbol {
38
+ id: string;
39
+ timeline: TimelineDefinition;
40
+ }
41
+ export interface SequenceDefinition {
42
+ id: string;
43
+ name: string;
44
+ canvas: {
45
+ width: number;
46
+ height: number;
47
+ };
48
+ scenes: SequenceScene[];
49
+ /** Loop count: -1 for infinite, 0 for no loop, n for n times */
50
+ loop?: number;
51
+ /**
52
+ * Nested-symbol timelines used by scene elements tagged with
53
+ * `data-tinyfly-symbol`. The sequencer animates each instance's inner elements
54
+ * from the matching symbol timeline.
55
+ */
56
+ symbols?: SequenceSymbol[];
57
+ }
58
+ /** Options for the TinyflySequencer */
59
+ export interface SequencerOptions {
60
+ /** Loop count override (-1 for infinite, 0 for no loop) */
61
+ loop?: number;
62
+ /** Auto-play on load (default: false) */
63
+ autoplay?: boolean;
64
+ /** Callback when entire sequence completes */
65
+ onComplete?: () => void;
66
+ /** Callback when a scene starts playing */
67
+ onSceneChange?: (sceneIndex: number) => void;
68
+ }