@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
package/README.md ADDED
@@ -0,0 +1,672 @@
1
+ # tinyfly
2
+
3
+ A lightweight, API-driven animation engine and visual editor for creating high-performance, embeddable animations.
4
+
5
+ **GSAP-level power with Excalidraw-level simplicity.**
6
+
7
+ ## Features
8
+
9
+ ### Core Engine
10
+ - **Framework-agnostic** - Works in any JavaScript environment (browser, Node.js, Web Workers)
11
+ - **JSON-first** - Animations are fully serializable, perfect for AI generation and persistence
12
+ - **Deterministic** - Same input always produces the same output
13
+ - **Lightweight** - No heavy dependencies, minimal footprint
14
+
15
+ ### Animation Capabilities
16
+ - **Timeline-based** - Orchestrate multiple tracks with precise timing
17
+ - **Rich easing** - Linear, quad, cubic, custom cubic-bezier, and more
18
+ - **Interpolation** - Numbers, colors, and arrays
19
+ - **Playback control** - Play, pause, stop, seek, reverse, speed adjustment
20
+ - **Looping** - Finite loops, infinite loops, ping-pong (alternate), and `repeatDelay` between iterations
21
+ - **Springs** - Physical spring tracks, integrated at a fixed timestep from t=0 so they stay deterministic *and* serializable (the animation is the parameters, not a baked curve); scale-invariant, so `scale: 0→1` and `x: 0→100` settle identically; authored in the editor with feel presets and sliders
22
+ - **Runtime stagger** - One track fans across many targets (`each` / `amount` / `from`), producing exactly what baking N tracks would — and ~15x smaller in JSON (measured: 100 letters is 11.7 KB baked, 0.8 KB as one track)
23
+ - **Track scheduling** - Per-track `delay` and `endDelay` without rewriting keyframes
24
+ - **Track queries** - `getTracks(filter)`, `removeTracks(filter)`, and `findConflicts()` to surface overlapping writes
25
+ - **Compile-time values** - `"+=100"` and `"random(-50, 50)"` resolve at authoring time from a recorded seed, so the JSON holds plain numbers and replays identically
26
+
27
+ ### Scroll & Interaction
28
+ - **Scroll-driven playback** - `ScrollDriver` scrubs a timeline against scroll position with GSAP-style trigger strings (`'top bottom'`, `'top top+=500'`); the geometry is a pure, unit-tested function
29
+ - **Play when visible** - `VisibilityDriver` plays on appearance (`once` / `repeat` / `reset`) via IntersectionObserver
30
+ - **Drag & pointer input** - `Observer` normalises pointer/touch/wheel; `Draggable` supports bounds, axis lock, grid/edge snapping (shared with the editor stage), and drag-to-scrub
31
+ - **FLIP transitions** - `flip()` measures a layout change in the DOM layer and emits ordinary keyframes, keeping the engine free of live layout reads
32
+
33
+ ### Render Adapters
34
+ - **DOM** - CSS transforms, opacity, colors, clip-path reveal, filters, shine, transform-origin, perspective
35
+ - **Canvas** - Shapes with position, size, rotation, colors, clip reveal, filters, transform-origin pivot
36
+ - **SVG** - Attributes, transforms, clip-path reveal, filters, transform-origin, perspective
37
+ - **WebGL** - Minimal GPU target: textured/solid quads with transform, opacity, and tint
38
+ - **Clip/mask reveal** - Animatable clip-inset (`clipTop/Right/Bottom/Left`) wipes elements into view, consistently across all three renderers
39
+ - **Filters** - Animatable `blur`, `glow`, and drop-shadow, composed identically across DOM, SVG, and Canvas
40
+
41
+ ### Text Animation
42
+ - **Split text into letters** - Break a text element into per-letter elements (Animate-style "break apart"), positioned to match the original layout
43
+ - **Staggered animation** - Fan any preset across the letters (or a multi-selection) with a per-letter delay — the primitive behind Animate-style drop, cascade, and wave effects
44
+ - **Per-letter presets** - Drop & Bounce, Cascade Up, Wave, Assemble, and Pop In, tuned to shine when staggered
45
+ - **Typewriter reveal** - Character-by-character typing with an optional blinking cursor that steps along; the timeline auto-extends to fit
46
+ - **Scramble & type-on text tracks** - Select a text element → **Text Animation** to scramble it into new words or type it on; a text-track inspector edits the words, character set, reveal delay, refresh rate and timing. Seeded, so previews and exports replay identically
47
+ - **Filters** - Animatable blur, glow, and drop-shadow (Blur In, Glow Pulse, Drop Shadow presets)
48
+ - **Shine sweep** - A highlight sweeps across the text, clipped to the glyphs, on all three renderers
49
+ - **All JSON** - A stagger, typewriter, or filter is just keyframe tracks, so it serializes, persists, and plays anywhere the engine runs
50
+
51
+ ### Playback & Sync
52
+ - **Standalone player** - `TinyflyPlayer` loads animation JSON (and animates embedded **symbol instances** via their nested timelines) and plays it onto DOM elements; ships as an ESM/UMD/IIFE bundle for npm or CDN
53
+ - **Audio/video sync** - `MediaSync` / `player.attachMedia()` locks an audio or video element to the timeline clock (play/pause/seek/rate), correcting drift as it plays
54
+ - **Audio & video in the editor** - Add an **Audio** or **Video** element (source, start time, volume, mute, loop; video also has object-fit); it plays in sync while you scrub and preview the timeline
55
+ - **Media in embeds** - Exported/embedded HTML carries the media, and the player auto-discovers and syncs it (`[data-tinyfly-media]`), so audio/video play in time wherever the animation is embedded
56
+
57
+ ### Visual Editor
58
+ - **AI prompt → animation** - Describe an animation in plain language ("a title that fades up with a shine", "three cards sliding in one after another") and generate a fully editable timeline. Bring your own API key for **OpenAI, Google Gemini, or Anthropic** — keys stay in your browser and are sent directly to the provider. The model emits tinyfly's JSON schema, which loads through the same path as the editable examples, so generated animations are ordinary keyframes you can tweak
59
+ - **Any canvas / aspect ratio** - The preview artboard follows the project canvas (DOM, Canvas, and SVG renderers) and fits-to-view, so a vertical 9:16 promo or any custom size previews at true proportions; samples can declare their own canvas size
60
+ - **Device-frame preset** - One click stamps a device mockup (rounded body, camera/notch, and a rounded video "screen") sized to the canvas, in **Phone / Landscape / Tablet** variants — drop a screen-recording into the screen's source for an app promo
61
+ - **Timeline view** - Visual keyframe editing with drag-and-drop
62
+ - **Camera** - Animate a pan/zoom/rotate over the whole stage (a reserved `Camera` layer driven by ordinary tracks). One-click add, a **🎥 Camera inspector** (Pan/Zoom/Rotation keyframed at the playhead), on-stage **✋ Pan** dragging, and a dedicated 🎥 lane at the top of the timeline; applies in every preview, export, and embed. Ready-made Push In / Pan Across / Orbit Reveal samples
63
+ - **Polygon & star shapes** - ⬡ Polygon and ★ Star elements are parametric paths — edit sides / points / inner ratio in Properties and they regenerate and rescale; they render and export like any path
64
+ - **Pen tool** - ✒️ Draw custom bezier paths: click for corners, click-drag for curves (Alt for a cusp), drag existing anchors/handles to adjust, snap points to grid/guides, click the first point or Enter to finish
65
+ - **Shape morph** - 🌀 Tween one path into another over the timeline (engine-level path interpolation); plays in every renderer, export, and embed
66
+ - **Grid, snapping & guides** - ▦ 20px grid, 🧲 snapping of drag/resize to grid/element-edges/artboard with live alignment guides, and 📏 rulers with draggable guides
67
+ - **Onion skinning** - 🧅 Faint ghost frames before/after the playhead (Canvas renderer) to see the arc of a move while editing one frame
68
+ - **Curve editor** - Switch the timeline between the **Dope Sheet** (keyframes & timing) and a **Curves** graph view where each numeric track is a value-over-time curve with the real easing drawn between keyframes; drag points in 2D (time + value), drag the easing handles to shape the cubic-bezier, double-click a lane to add a keyframe, Ctrl/Cmd-click to multi-select
69
+ - **Timeline zoom & scroll** - Zoom the timeline with Ctrl/⌘+scroll or the −/+ control and pan with the scrollbar or Shift+scroll (shared across both views)
70
+ - **Scene duration you can author** - Click the `current / duration` readout to type an exact length in seconds. The timeline **auto-extends** when a keyframe is added or dragged past the end, so late keyframes always play; the end of the scene is drawn as a dashed marker with the unreachable region dimmed, and a **Fit** button snaps the duration back out to the last keyframe after a manual trim
71
+ - **Box-select & curve overlay** - Rubber-band-select keyframes in either timeline view; in Curves, toggle **Overlay** to compare all tracks on one shared axis. Scene tabs show live per-scene thumbnails
72
+ - **Symbols & Library** - Bundle elements into a reusable **symbol** (Convert to Symbol), place instances across scenes, **edit in place** (double-click an instance), give a symbol its own timeline for **nested animation**, and **swap** which symbol an instance shows over time (lip-sync) — all JSON-serialized
73
+ - **Multi-select keyframes** - Ctrl/Cmd-click to select many keyframes; copy/paste (at the playhead) and delete them together
74
+ - **Property panel** - Edit keyframe values and easing
75
+ - **Track management** - Add, remove, and organize animation tracks
76
+ - **Per-letter stagger** - Toggle in the preset panel to split text and fan a preset across its letters
77
+ - **Playback controls** - Preview animations in real-time
78
+ - **Undo/Redo** - Unified history across the timeline and the scene: one Ctrl+Z reverses the last change of either kind (element add/move/resize/group/property edits or keyframe/track edits); drags collapse to a single step
79
+ - **Multiple scenes** - Organize animations into separate scenes with independent elements and timelines
80
+ - **Scene transitions** - Configurable transitions between scenes (fade, slide)
81
+ - **Multi-scene sequencer** - Play all scenes in order with transitions
82
+ - **My Animations gallery** - Every project you make is saved and browsable in a thumbnail grid; open one to keep editing, duplicate, or delete it. Persisted to **IndexedDB** (LocalStorage projects are migrated automatically on first run), so you can accumulate many animations without the old single-slot limit
83
+ - **Collapsible panels** - Hide the Elements/Tracks and Properties/Presets columns to give the canvas more room; a slim tab brings each back
84
+ - **Rename & save** - Double-click the project title to rename it inline; a Save button shows a clear Save / Saving… / Saved ✓ status (handy on touch devices) on top of continuous auto-save
85
+ - **Project management** - Auto-save to IndexedDB (with LocalStorage fallback)
86
+ - **Export/Import** - JSON file support
87
+ - **Named exports** - Choose the download filename in the Export dialog for every format; it defaults to the project name and is sanitized for any filesystem
88
+ - **MP4 export** - Encode the animation to a real MP4 (H.264) via WebCodecs, with a hand-written muxer and no dependencies. Frame-by-frame rather than real-time, so it's faster than playback and reproducible; MediaRecorder (WebM) is the fallback where WebCodecs is missing
89
+ - **Animated GIF export** - Median-cut colour quantization with optional Floyd–Steinberg dithering, per-frame palettes, and transparency
90
+ - **Animated WebP export** - Roughly 3× smaller than GIF at true colour, with full alpha
91
+ - **Sprite-sheet export** - Every frame packed into one PNG grid plus a JSON metadata file (frame size, columns/rows, count, fps) — ready for game engines or a custom `<canvas>` player; alpha kept when transparent
92
+ - **Rich raster export options** - Resolution multiplier (2x by default, so text and edges stay crisp), FPS, background colour or transparency, progress and cancel. Image and video layers are composited too — a device screen's recording is captured with `object-fit` cover/contain and rounded corners, seeked in sync
93
+ - **Resizable preview** - Drag the splitter between the preview and the timeline to resize (double-click to reset)
94
+ - **Stroke write-on** - Animate a path's stroke drawing itself on (DOM + SVG renderers); one-click "Write On" preset
95
+ - **Embed code** - Generate copy-paste code for websites (single scene or full sequence)
96
+ - **Landing page** - `/` introduces tinyfly with tinyfly itself: a masked headline, a pointer-led canvas, a live code playground that shows the JSON its code compiles to, a pinned feature story, a gallery and a copyable script tag, with a reduced-motion mode. It loads without the editor, which lives at `/studio` (lazy-loaded, as are Examples, Showcase and Docs)
97
+ - **Learn** - An interactive course at `/learn`: short steps with live code, a preview you can scrub, and checks that read what your code compiled to. Nine modules, 64 steps: Foundations (animation as JSON), the GSAP-style API, the Editor (build in the studio, Copy JSON, compare with code), Motion craft (timing, anticipation, springs), Text and SVG, Interaction (hover, quickTo, drag and throw, Flip, canvas), Scroll (reveals, scrub, pinning, velocity), Accessibility and performance (a real reduced-motion mode, keyboard parity, transforms, pausing off-screen work), and a Capstone that rebuilds the Agency Landing Page section by section
98
+ - **Examples** - One page (`/examples`, the **Examples** toolbar button), and a shareable page for every example at `/examples/<id>` for every ready-made animation: editable examples open in the editor as a new project, code examples show their timeline JSON and HTML to copy. Includes a full-page **Agency Landing Page** showcase and a **GSAP-style** section of 41 runnable `live.to()` demos (Flip layouts and shared elements, pinned horizontal scroll, line mask reveals, spring release, canvas from object tweens, motion paths, orbits, shape and menu morphs, scramble text, draggable throws, swipe cards, 3D card flips, magnetic button, proximity grid, marquee, split text, SVG draw…), and every card has **Copy code** for a complete standalone HTML page. Hover-to-play previews, search, and filters for kind and category (GSAP-style, Showcase, Basics, Motion, Text, UI, Loaders, Effects, Data, Camera, Scroll, and **Algorisys** product demos)
99
+
100
+ ## Documentation
101
+
102
+ - [Getting Started](docs/getting-started.md) — Installation, setup, and your first animation
103
+ - [Editor Guide](docs/editor-guide.md) — Complete guide to the visual editor (elements, timeline, scenes, presets, shortcuts)
104
+ - [API Reference](docs/api-reference.md) — Full engine, player, adapter, and export API documentation
105
+ - [File Format](docs/file-format.md) — The tinyfly JSON format (animation documents, timelines, projects, sequences) for integrations
106
+ - [Examples](docs/examples.md) — Code examples for common animation patterns
107
+ - [Scroll Animation](docs/scroll-animation.md) — Scroll-driven and visibility-triggered playback via drivers
108
+ - [GSAP Compatibility](docs/gsap-compat.md) — The GSAP-flavoured API, the mapping table, and what we deliberately don't do
109
+ - [Deployment](docs/DEPLOYMENT.md) — Hosting, Docker, and CDN configuration
110
+ - [2D Animation Roadmap](docs/2d-animation-roadmap.md) — Adobe Animate gap analysis and phased plan (symbols/library, camera, onion skinning, …)
111
+
112
+ **Feature guides:** [Symbols & Library](docs/symbols-and-library.md) · [Camera](docs/camera.md) · [Polygon & Star](docs/polygon-star.md) · [Pen tool](docs/pen-tool.md) · [Shape morph](docs/shape-morph.md) · [Grid & snapping](docs/grid-and-snapping.md) · [Onion skinning](docs/onion-skinning.md) · [Sprite-sheet export](docs/sprite-sheet-export.md)
113
+
114
+ **Docs for LLMs:** the repo root has [`llms.txt`](llms.txt), an [llmstxt.org](https://llmstxt.org) index of these docs. The built editor also serves `/llms.txt`, `/llms-full.txt` (every doc in one file) and each page as raw markdown at `/docs/<page>.md`.
115
+
116
+ ## Installation
117
+
118
+ ```bash
119
+ npm install @algorisys/tinyfly
120
+ ```
121
+
122
+ Or use it with no build step from the [GitHub CDN](#use-from-a-script-tag-no-build-step).
123
+
124
+ The package ships these entry points. Each is tree-shakeable, so you pay only
125
+ for what you import:
126
+
127
+ | Import | What it is | Environments |
128
+ |---|---|---|
129
+ | `@algorisys/tinyfly` | The engine — `Timeline`, tracks, easing, JSON | Browser, Web Worker, Node |
130
+ | `@algorisys/tinyfly/player` | `TinyflyPlayer`, `MediaSync`, sequencer — plays editor JSON on the DOM | Browser |
131
+ | `@algorisys/tinyfly/export` | `exportToCSS`, `exportToLottie`, GIF / WebP / MP4 / sprite-sheet export | Browser (CSS and Lottie anywhere) |
132
+ | `@algorisys/tinyfly/adapters` | `DOMAdapter`, `CanvasAdapter`, `SVGAdapter`, `WebGLAdapter` — apply timeline state to a render target | Browser |
133
+ | `@algorisys/tinyfly/gsap-compat` | GSAP-style `live.to()` / `timeline()`, plus the compiling `tf` facade | Browser (`tf` anywhere) |
134
+ | `@algorisys/tinyfly/drivers` | `ScrollDriver`, `VisibilityDriver` | Browser |
135
+ | `@algorisys/tinyfly/interaction` | `Observer`, `Draggable` | Browser |
136
+ | `@algorisys/tinyfly/embed` | Teaching embeds: the player with step controls, captions and one-script `[data-tinyfly-embed]` mounting; `validateEmbed`, `renderFrame` | Browser (tools anywhere) |
137
+ | `@algorisys/tinyfly/teach` | `lesson()` step builder and diagram primitives (cells, pointer, stack, queue, table, pipeline) | Anywhere |
138
+ | `@algorisys/tinyfly/react`, `@algorisys/tinyfly/vue`, `@algorisys/tinyfly/svelte`, `@algorisys/tinyfly/solid` | `useTinyfly` hooks, a Svelte action and a Solid primitive: `live` animations scoped to a component and reverted on unmount | Browser (frameworks are optional peer dependencies) |
139
+ | `@algorisys/tinyfly/browser` | Everything above in one bundle | Browser |
140
+
141
+ ```js
142
+ // The framework-agnostic engine (browser, Web Worker, or Node)
143
+ import { Timeline, createTrack } from '@algorisys/tinyfly'
144
+
145
+ // The DOM player + media sync (browser)
146
+ import { TinyflyPlayer, MediaSync } from '@algorisys/tinyfly/player'
147
+
148
+ // Render adapters: apply timeline state to DOM, Canvas, SVG or WebGL (browser)
149
+ import { DOMAdapter } from '@algorisys/tinyfly/adapters'
150
+
151
+ // GSAP-style animation of real elements (browser)
152
+ import { live } from '@algorisys/tinyfly/gsap-compat'
153
+ live.to('.box', { x: 200, duration: 1, ease: 'power2.out' })
154
+ ```
155
+
156
+ ```jsx
157
+ // React: everything the setup creates is reverted when the component unmounts
158
+ import { useTinyfly } from '@algorisys/tinyfly/react'
159
+
160
+ function Hero() {
161
+ const root = useRef(null)
162
+ useTinyfly((live) => live.from('.title', { y: 40, opacity: 0 }), { scope: root })
163
+ return <section ref={root}><h1 className="title">Hello</h1></section>
164
+ }
165
+ ```
166
+
167
+ TypeScript declarations ship with every entry point. Works with any framework
168
+ or none; the engine has no dependencies. See
169
+ [framework hooks](docs/gsap-compat.md#framework-hooks) for Vue, Svelte and Solid.
170
+
171
+ ### Use from a `<script>` tag (no build step)
172
+
173
+ Every release publishes browser bundles to the `cdn/` folder of
174
+ [algorisys-oss/tinyfly](https://github.com/algorisys-oss/tinyfly), tagged with
175
+ its version, and [jsDelivr](https://www.jsdelivr.com/) serves them straight from
176
+ GitHub. No npm required.
177
+
178
+ `tinyfly.iife.js` (~29 KB gzipped) puts everything on one `tinyfly` global, with
179
+ GSAP-shaped functions at the top level:
180
+
181
+ ```html
182
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.64.0/cdn/tinyfly.iife.js"></script>
183
+ <script>
184
+ tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
185
+
186
+ tinyfly.timeline({ repeat: -1, yoyo: true })
187
+ .fromTo('.dot', { opacity: 0, y: 20 }, { opacity: 1, y: 0, duration: 0.4, stagger: 0.1 })
188
+ .to('.title', { scale: 1.1, duration: 0.3 })
189
+
190
+ // The player, engine, drivers and interaction are on the same global
191
+ const player = new tinyfly.TinyflyPlayer('#stage')
192
+ player.load('animation.json').then(() => player.play())
193
+ </script>
194
+ ```
195
+
196
+ | File | What |
197
+ |---|---|
198
+ | `cdn/tinyfly.iife.js` | Everything, on a `tinyfly` global |
199
+ | `cdn/tinyfly.umd.js` | The same, as UMD |
200
+ | `cdn/tinyfly.esm.js` | The same, as an ES module: `import { live } from '…/cdn/tinyfly.esm.js'` |
201
+ | `cdn/tinyfly-player.iife.js` | Player only (~11 KB gzipped), for playing editor exports |
202
+
203
+ Replace `@v0.59.0` with the version you want. **Pin a version in production**:
204
+ a tag's files never change. `@main` follows the latest release, which jsDelivr
205
+ caches for up to a day. Load one `tinyfly` global, not both.
206
+
207
+ Every card on the [Examples page](docs/editor-guide.md#examples) has **Copy code**, which gives you a
208
+ complete HTML page already using these URLs.
209
+
210
+ ### Build the distributable libraries
211
+
212
+ ```bash
213
+ npm run build:libs # all bundles + type declarations -> lib/
214
+ ```
215
+
216
+ This produces:
217
+
218
+ - `lib/engine/tinyfly-engine.js` (ESM) and `.umd.cjs` — the engine
219
+ - `lib/player/tinyfly-player.{es,umd,iife}.js` — the standalone DOM player
220
+ - `lib/addons/{adapters,export,gsap-compat,drivers,interaction}.js` — the optional entry points
221
+ - `lib/browser/tinyfly.{iife,umd}.js` and `tinyfly.js` — the all-in-one bundle
222
+ - `lib/types/**` — TypeScript declarations
223
+
224
+ ## Quick Start
225
+
226
+ ### Using the Editor
227
+
228
+ ```bash
229
+ # Clone the repository
230
+ git clone https://github.com/algorisys-oss/tinyfly.git
231
+ cd tinyfly
232
+
233
+ # Install dependencies
234
+ npm install
235
+
236
+ # Start the development server
237
+ npm run dev
238
+ ```
239
+
240
+ Open [http://localhost:5173](http://localhost:5173) for the landing page; the visual editor is at [/studio](http://localhost:5173/studio).
241
+
242
+ ### Using the Engine (API)
243
+
244
+ ```typescript
245
+ import { Timeline, createTrack } from '@algorisys/tinyfly';
246
+
247
+ // Create a timeline
248
+ const timeline = new Timeline({
249
+ id: 'my-animation',
250
+ config: { duration: 2000, loop: -1 }
251
+ });
252
+
253
+ // Add a track
254
+ timeline.addTrack(createTrack({
255
+ id: 'opacity',
256
+ target: 'box',
257
+ property: 'opacity',
258
+ keyframes: [
259
+ { time: 0, value: 0 },
260
+ { time: 1000, value: 1, easing: 'ease-out' },
261
+ { time: 2000, value: 0, easing: 'ease-in' }
262
+ ]
263
+ }));
264
+
265
+ // Play the animation
266
+ timeline.play();
267
+
268
+ // Animation loop
269
+ function animate() {
270
+ timeline.tick(16.67); // ~60fps
271
+ const state = timeline.getStateAtTime(timeline.currentTime);
272
+ // Apply state to your elements...
273
+ requestAnimationFrame(animate);
274
+ }
275
+ animate();
276
+ ```
277
+
278
+ ### Embedding Animations
279
+
280
+ ```html
281
+ <div id="animation">
282
+ <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
283
+ </div>
284
+
285
+ <script type="module">
286
+ import { play } from '@algorisys/tinyfly/player';
287
+
288
+ // Load from JSON file
289
+ play('#animation', './animation.json', {
290
+ loop: -1,
291
+ autoplay: true
292
+ });
293
+
294
+ // Or use inline JSON
295
+ play('#animation', {
296
+ id: 'my-animation',
297
+ config: { duration: 1000 },
298
+ tracks: [...]
299
+ });
300
+ </script>
301
+ ```
302
+
303
+ The player automatically finds target elements by:
304
+ - `data-tinyfly="name"` attribute
305
+ - Class name `.name`
306
+ - ID `#name`
307
+
308
+ ## API Reference
309
+
310
+ ### Timeline
311
+
312
+ ```typescript
313
+ const timeline = new Timeline({
314
+ id: string,
315
+ name?: string,
316
+ config?: {
317
+ duration?: number, // Total duration in ms
318
+ loop?: number, // -1 for infinite, 0 for none, n for n times
319
+ alternate?: boolean, // Ping-pong effect
320
+ speed?: number // Playback speed multiplier
321
+ }
322
+ });
323
+
324
+ timeline.play();
325
+ timeline.pause();
326
+ timeline.stop();
327
+ timeline.seek(timeMs);
328
+ timeline.reverse();
329
+ timeline.tick(deltaMs);
330
+ timeline.getStateAtTime(timeMs);
331
+ ```
332
+
333
+ ### Track
334
+
335
+ ```typescript
336
+ const track = createTrack({
337
+ id: string,
338
+ target: string, // Element identifier
339
+ property: string, // Property to animate
340
+ keyframes: [
341
+ {
342
+ time: number, // Time in ms
343
+ value: number | string, // Value at this keyframe
344
+ easing?: EasingType // Easing to next keyframe
345
+ }
346
+ ]
347
+ });
348
+ ```
349
+
350
+ ### Easing Types
351
+
352
+ Built-in easing types:
353
+ - `linear`
354
+ - `ease-in`, `ease-out`, `ease-in-out`
355
+ - `ease-in-quad`, `ease-out-quad`, `ease-in-out-quad`
356
+ - `ease-in-cubic`, `ease-out-cubic`, `ease-in-out-cubic`
357
+
358
+ Custom cubic-bezier easing:
359
+ ```typescript
360
+ {
361
+ type: 'cubic-bezier',
362
+ points: [0.42, 0, 0.58, 1] // [cp1x, cp1y, cp2x, cp2y]
363
+ }
364
+ ```
365
+
366
+ ### Player
367
+
368
+ ```typescript
369
+ import { TinyflyPlayer, play, create } from '@algorisys/tinyfly/player';
370
+
371
+ // Quick play
372
+ const player = await play('#container', 'animation.json', options);
373
+
374
+ // Manual control
375
+ const player = new TinyflyPlayer('#container', options);
376
+ await player.load('animation.json');
377
+ player.play();
378
+ player.pause();
379
+ player.seek(500);
380
+ player.setSpeed(2);
381
+ player.destroy();
382
+ ```
383
+
384
+ ### Audio / Video Sync
385
+
386
+ Attach a media element so it stays locked to the timeline clock (the timeline
387
+ stays the source of truth; the media follows play/pause/seek/rate and drift is
388
+ corrected as it plays).
389
+
390
+ ```typescript
391
+ const player = new TinyflyPlayer('#container');
392
+ await player.load('animation.json');
393
+
394
+ const audio = document.querySelector('audio');
395
+ player.attachMedia(audio, { offset: 0 }); // start media at timeline t=0
396
+
397
+ player.play(); // audio plays in sync
398
+ player.seek(2000); // audio jumps to 2s
399
+ player.detachMedia();
400
+
401
+ // Or use the primitive directly with any { currentTime, paused, play, pause }:
402
+ import { MediaSync } from '@algorisys/tinyfly/player';
403
+ const sync = new MediaSync(audio, { driftTolerance: 0.15 });
404
+ sync.update(timelineMs, isPlaying);
405
+ ```
406
+
407
+ ### Sequencer (Multi-Scene)
408
+
409
+ ```typescript
410
+ import { TinyflySequencer, playSequence } from '@algorisys/tinyfly/player';
411
+
412
+ // Quick play all scenes in sequence
413
+ const sequencer = await playSequence('#container', 'sequence.json', {
414
+ loop: -1,
415
+ autoplay: true,
416
+ onSceneChange: (index) => console.log(`Scene ${index}`),
417
+ });
418
+
419
+ // Manual control
420
+ const sequencer = new TinyflySequencer('#container', options);
421
+ await sequencer.load('sequence.json');
422
+ sequencer.play();
423
+ sequencer.pause();
424
+ sequencer.goToScene(2);
425
+ sequencer.destroy();
426
+
427
+ // Properties
428
+ sequencer.currentSceneIndex; // Current scene index
429
+ sequencer.sceneCount; // Total number of scenes
430
+ sequencer.isPlaying; // Playback state
431
+ ```
432
+
433
+ **Transition types:** `none`, `fade`, `slide-left`, `slide-right`, `slide-up`, `slide-down`
434
+
435
+ ## Scroll, springs, and GSAP-style authoring
436
+
437
+ Three optional entry points sit outside the engine. Each is opt-in and
438
+ tree-shakeable, so an embed that only plays an animation pays nothing for them.
439
+
440
+ ```ts
441
+ import { ScrollDriver, VisibilityDriver } from '@algorisys/tinyfly/drivers'
442
+ import { Observer, Draggable } from '@algorisys/tinyfly/interaction'
443
+ import { timeline, quickPlay } from '@algorisys/tinyfly/gsap-compat'
444
+ ```
445
+
446
+ **Scroll-driven animation** is a *driver*, not a special timeline. The engine is
447
+ a pure function of time; a driver is what decides which time to hand it. So any
448
+ existing animation becomes scroll-driven without changing it — and the editor's
449
+ **⇅ Scroll** preview runs that same driver against a real scroll container, so
450
+ triggers you tune there behave identically on your page:
451
+
452
+ ```ts
453
+ new ScrollDriver({
454
+ timeline,
455
+ trigger: document.querySelector('#panel')!,
456
+ start: 'top bottom',
457
+ end: 'bottom top',
458
+ scrub: true,
459
+ }).start()
460
+ ```
461
+
462
+ **Springs** are a track kind, integrated at a fixed timestep from t=0. That is
463
+ what lets them be physical *and* deterministic *and* serializable at once —
464
+ the animation is the parameters, so it exports like any other track:
465
+
466
+ ```ts
467
+ timeline.addTrack({
468
+ id: 'pop', target: 'box', property: 'scale',
469
+ kind: 'spring',
470
+ spring: { from: 0, to: 1, stiffness: 200, damping: 12 },
471
+ })
472
+ ```
473
+
474
+ **Flip**: `live.flip('.item', () => reorder())` animates any layout change — reorders, class toggles, filters, resizes — from where elements were to where they land, and interrupts smoothly.
475
+
476
+ **Inertia and dragging**: throw elements with `live.draggable(el, { bounds, inertia: { end: slots } })` or the `inertia` tween option. Friction is exact closed-form decay, snapping lands precisely, and it all serializes like any track.
477
+
478
+ **Text animation** types, backspaces and scrambles text (`text` and `scrambleText`), deterministically: scramble characters are seeded, so scrubbing and exports replay exactly.
479
+
480
+ **Shape morphing** turns any path into any other (`morphSVG` in `live` and `tf`): subpaths are paired, the start point and direction are chosen so nothing twists, and corners stay sharp.
481
+
482
+ **Motion paths** follow SVG path data, points, or (with `live`) an SVG element on the page — `align` lays the path over the element where it is drawn and `autoRotate` turns the follower to face along it. The path parser handles everything design tools export, and followers move at an even speed.
483
+
484
+ **Award-site motion** on the same `live` API, all compiled to ordinary tracks:
485
+ - `scrollTrigger` — scrub (exact or smoothed), `pin` (the sticky recipe automated), `toggleActions`, `once`, velocity in `onUpdate`; scrolling does no layout reads
486
+ - `live.splitText()` — characters, words and rendered lines, with clipping masks and accessible labels
487
+ - `drawSVG` — stroke drawing by length or segment (`'20% 80%'`)
488
+ - `spring` — presets or stiffness/damping/mass, carrying the momentum of whatever it interrupts or a drag's release velocity
489
+ - Flip shared elements — `data-flip-id` grows a thumbnail into a different hero element
490
+ - Plain-object targets and `live.ticker` — drive canvas, Three.js or shader uniforms on the same frame as the DOM
491
+ - Survives resizes and breakpoints — function values, `invalidateOnRefresh`, `splitText` `autoSplit`, `live.matchMedia()` (a real reduced-motion mode) and `live.context()` cleanup
492
+ - `live.utils` (clamp, mapRange, interpolate, wrap, snap, seeded random, distribute, pipe…), `"random(…)"` values, `repeatRefresh`, `live.getProperty`; native elastic / bounce / back / steps eases
493
+ - Teaching animations ([guide](docs/teaching.md)): markers and captions in the JSON, a player that steps, respects reduced motion and pauses off screen, step controls with predict-then-reveal questions, one-script declarative embeds, `@algorisys/tinyfly/teach` diagram primitives, and `npx @algorisys/tinyfly validate` / `render`
494
+ - Timeline callbacks and control: `tl.call`, `tl.addPause`, `tl.tweenTo` / `tweenFromTo`, `onRepeat`, `onReverseComplete`, tween callbacks inside timelines, `live.delayedCall`, `live.killTweensOf`
495
+ - `live.quickTo` for pointer and scroll-driven values; `snap`, `markers` and `containerAnimation` on scroll triggers
496
+ - `live.smoothScroll` eased wheel scrolling with `data-speed` / `data-lag` parallax, on the real scroll position so triggers and pins keep working
497
+ - `live.imageSequence` scroll-scrubbed frame sequences, `live.pageTransition` route changes with shared elements, and `CustomEase` / `CustomBounce` / `CustomWiggle`
498
+
499
+ See the **Agency Landing Page** showcase on the Examples page (`/showcase/agency-landing`).
500
+
501
+ **GSAP-flavoured authoring** desugars a familiar API into ordinary tracks:
502
+
503
+ ```ts
504
+ const tl = timeline()
505
+ tl.fromTo('box', { x: 0, opacity: 0 }, { x: 200, opacity: 1, duration: 1, ease: 'power2.out' })
506
+ tl.to(['l1', 'l2', 'l3'], { y: 0, duration: 0.5, stagger: 0.08 }, '-=0.25')
507
+
508
+ quickPlay({ timeline: tl.timeline, targets: { box: '#box', l1: '#l1', l2: '#l2', l3: '#l3' } })
509
+ ```
510
+
511
+ For a page that just wants things to move, **`live`** plays straight onto
512
+ elements — CSS selectors, elements or node lists, no target map, no loop:
513
+
514
+ ```ts
515
+ import { live } from '@algorisys/tinyfly/gsap-compat'
516
+
517
+ live.to('.card', { y: -20, opacity: 1, duration: 0.6, stagger: 0.08, ease: 'power3.out' })
518
+ live.to('#logo', { rotate: 360, duration: 2, repeat: -1 })
519
+ live.timeline({ repeat: -1, yoyo: true })
520
+ .to('.a', { x: 120, duration: 0.5 })
521
+ .to('.b', { scale: 1.4, duration: 0.5 }, '<')
522
+ ```
523
+
524
+ Separate `live` animations on the same element compose (an `x` tween and a
525
+ `rotate` tween both apply) because they share one frame loop and one adapter.
526
+
527
+ It is **familiar, not compatible** — GSAP code will not run unchanged. Anything
528
+ authored through it is ordinary tinyfly JSON that opens in the editor. Read
529
+ [docs/gsap-compat.md](docs/gsap-compat.md) for the mapping table and, more
530
+ importantly, for what we deliberately don't do and why.
531
+
532
+ ## Architecture
533
+
534
+ ```
535
+ tinyfly/
536
+ ├── src/
537
+ │ ├── engine/ # Framework-agnostic core
538
+ │ │ ├── core/ # Timeline, Track, Clock
539
+ │ │ ├── interpolation/# Easing and interpolators
540
+ │ │ └── serialization/# JSON import/export
541
+ │ ├── adapters/ # Render adapters
542
+ │ │ ├── dom/ # DOM/CSS adapter
543
+ │ │ ├── canvas/ # Canvas 2D adapter
544
+ │ │ ├── svg/ # SVG adapter
545
+ │ │ └── webgl/ # WebGL adapter
546
+ │ ├── editor/ # Visual editor (SolidJS)
547
+ │ │ ├── components/ # UI components
548
+ │ │ └── stores/ # State management
549
+ │ └── player/ # Lightweight embed player
550
+ ```
551
+
552
+ ## Roadmap
553
+
554
+ ### Coming Soon
555
+ - [x] Multiple preview elements (shapes, images, text)
556
+ - [x] More animatable properties (colors, borders, shadows)
557
+ - [x] Copy/paste keyframes
558
+ - [x] Multi-select keyframes
559
+ - [x] Visual curve editor for custom easing
560
+ - [x] npm engine package + CDN player build (`npm run build:libs`)
561
+ - [x] All-in-one `<script>` bundle with a GSAP-shaped `tinyfly` global, and `live.to()` that plays on real elements
562
+ - [ ] Publish to npm
563
+
564
+ ### Future
565
+ - [x] Scene transitions (fade, slide between scenes)
566
+ - [x] Multi-scene player/sequencer
567
+ - [x] Per-letter text animation (split + stagger)
568
+ - [x] Typewriter reveal (char-by-char + blinking cursor)
569
+ - [x] Clip/mask reveal (wipe presets, all adapters)
570
+ - [x] Animatable filters (blur, glow, drop-shadow)
571
+ - [x] Shine sweep (highlight clipped to glyphs, all renderers)
572
+ - [x] Audio/video sync (`MediaSync` / `player.attachMedia()`)
573
+ - [x] WebGL adapter (minimal: textured/solid quads with transform, opacity, tint)
574
+ - [x] Scroll-driven playback + visibility triggers (`@algorisys/tinyfly/drivers`)
575
+ - [x] Drag / pointer interaction layer (`@algorisys/tinyfly/interaction`)
576
+ - [x] Deterministic spring tracks
577
+ - [x] FLIP layout transitions
578
+ - [x] GSAP-flavoured compat facade (`@algorisys/tinyfly/gsap-compat`)
579
+ - [x] Scroll-scrub preview in the editor (runs the real driver, not a simulation)
580
+ - [x] Overlapping-track warnings in the Tracks panel
581
+ - [x] Spring curves in the graph editor
582
+ - [x] Spring parameter editing in the editor UI (presets + sliders, auto-extending scene)
583
+ - [x] Spring presets in the Presets panel (Pop, Drop, Slide, Wobble, Settle)
584
+ - [ ] Export-time collapse of baked staggers into runtime stagger tracks
585
+
586
+ **Planned — [Phase 27](todo.md) (closing on GSAP):**
587
+ - [x] Cross-browser checks (`npm run e2e`): Chromium, Firefox and WebKit pass
588
+ - [x] Performance benchmark against GSAP ([results](bench/README.md) — ~3x slower per frame; the DOM adapter is 75% of our cost, not the engine)
589
+ - [ ] Exercise the WebGL adapter against a real GL context (only its maths is tested)
590
+ - [ ] Load-time value resolution + responsive variants (the serializable answer to function values and `matchMedia`)
591
+ - [x] Inertia / throw as an `inertia` track kind
592
+ - [x] Text tracks: type-on and scramble text
593
+ - [x] CustomEase, CustomBounce, CustomWiggle
594
+ - [ ] Framework wrappers (React / Vue / Svelte)
595
+ - [x] Scroll pinning (`scrollTrigger: { pin }`), split text, drawSVG, springs and shared-element Flip on `live` ([Phase 28](todo.md))
596
+ - [x] Interactive tutorial at `/learn` — 9 modules from keyframes to an award-style landing page, checked in three browsers ([Phase 29](todo.md))
597
+ - [ ] Nested timelines at runtime, explicit track priority
598
+ - [ ] React Native adapter
599
+ - [ ] Collaborative editing
600
+
601
+ ## Development
602
+
603
+ ```bash
604
+ # Install dependencies
605
+ npm install
606
+
607
+ # Start dev server
608
+ npm run dev
609
+
610
+ # Run tests
611
+ npm test
612
+
613
+ # Cross-browser checks in Chromium, Firefox and WebKit (see e2e/README.md)
614
+ npx playwright-core install firefox webkit # once
615
+ npm run e2e
616
+
617
+ # Build for production
618
+ npm run build
619
+ ```
620
+
621
+ ### Cross-browser checks
622
+
623
+ `npm run e2e` runs tinyfly in real Chromium, Firefox and WebKit and measures the
624
+ results rather than just looking for errors:
625
+
626
+ - **Engine:** the path parser against each browser's own SVG geometry, determinism,
627
+ and `structuredClone`.
628
+ - **Adapters:** transforms, shine clipped to the glyphs (`background-clip: text`), SVG
629
+ rotating in place (`transform-box`), and canvas drawing, all checked by the pixels
630
+ and boxes actually rendered.
631
+ - **Exports:** GIF, WebP and MP4 (WebCodecs).
632
+ - **Demos:** every GSAP-style demo animating under real mouse input, plus Flip and
633
+ motion-path precision.
634
+ - **Editor:** adding elements, playing in all three renderers, and IndexedDB
635
+ persistence across a reload.
636
+
637
+ Latest run: Chromium 150, Firefox 153 and WebKit 26.5 pass all 33 checks. In WebKit
638
+ on Linux, MP4 export is reported as a note: Playwright's WebKit build crashes while
639
+ starting its bundled GStreamer, before tinyfly's code runs. WebKit needs `libavif16`
640
+ on Linux hosts, and the runner removes the GTK/GIO variables a snap-installed
641
+ terminal (VS Code from the Snap Store) exports, which otherwise break every page
642
+ load.
643
+
644
+ ### Test Coverage
645
+
646
+ `npm test` runs 1,711 unit tests in 99 files, all passing:
647
+
648
+ | Area | Tests |
649
+ |---|---|
650
+ | Engine (`src/engine`: timeline, easing, paths, text, exports, serialization) | 498 |
651
+ | Editor (`src/editor`: stores, utils, presets, AI, samples) | 393 |
652
+ | Examples page and GSAP-style demos (`src/examples`) | 206 |
653
+ | GSAP-style API (`src/compat/gsap`) | 201 |
654
+ | Render adapters (`src/adapters`) | 134 |
655
+ | Player, media sync and sequencer (`src/player`) | 83 |
656
+ | Drivers and interaction (`src/drivers`, `src/interaction`) | 108 |
657
+ | Docs viewer and `llms.txt` (`src/docs`) | 14 |
658
+
659
+ ## Contributing
660
+
661
+ Contributions are welcome! For anything larger than a small fix, please open an
662
+ [issue](https://github.com/algorisys-oss/tinyfly/issues) first to discuss it, then send a pull request.
663
+
664
+ 1. Fork the repository
665
+ 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
666
+ 3. Commit your changes (`git commit -m 'Add amazing feature'`)
667
+ 4. Push to the branch (`git push origin feature/amazing-feature`)
668
+ 5. Open a Pull Request
669
+
670
+ ## License
671
+
672
+ [MIT](LICENSE) © 2026 Algorisys OSS Team. Use it in personal, commercial and SaaS projects, modify it and redistribute it; keep the copyright and license notice with copies of the source.