@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.
- package/LICENSE +21 -0
- package/README.md +672 -0
- package/bin/tinyfly.mjs +59 -0
- package/lib/addons/adapters.js +756 -0
- package/lib/addons/dom-adapter-ChrbtkLC.js +243 -0
- package/lib/addons/drivers.js +72 -0
- package/lib/addons/export.js +1169 -0
- package/lib/addons/gsap-compat.js +2576 -0
- package/lib/addons/interaction.js +225 -0
- package/lib/addons/smooth-scroll-DaSacemU.js +671 -0
- package/lib/addons/teach.js +215 -0
- package/lib/browser/tinyfly.iife.js +2 -0
- package/lib/browser/tinyfly.js +6372 -0
- package/lib/browser/tinyfly.umd.js +2 -0
- package/lib/cli/tools.js +2325 -0
- package/lib/embed/tinyfly-embed.iife.js +18 -0
- package/lib/embed/tinyfly-embed.js +2316 -0
- package/lib/engine/tinyfly-engine.js +1972 -0
- package/lib/engine/tinyfly-engine.umd.cjs +2 -0
- package/lib/frameworks/react.js +32 -0
- package/lib/frameworks/solid.js +27 -0
- package/lib/frameworks/svelte.js +15 -0
- package/lib/frameworks/vue.js +29 -0
- package/lib/player/tinyfly-player.es.js +2306 -0
- package/lib/player/tinyfly-player.iife.js +2 -0
- package/lib/player/tinyfly-player.umd.js +2 -0
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +238 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/dom/dom-adapter.d.ts +50 -0
- package/lib/types/adapters/dom/flip.d.ts +60 -0
- package/lib/types/adapters/dom/index.d.ts +2 -0
- package/lib/types/adapters/filter-utils.d.ts +32 -0
- package/lib/types/adapters/index.d.ts +5 -0
- package/lib/types/adapters/shine-utils.d.ts +26 -0
- package/lib/types/adapters/svg/index.d.ts +1 -0
- package/lib/types/adapters/svg/svg-adapter.d.ts +47 -0
- package/lib/types/adapters/svg-transform-box.d.ts +13 -0
- package/lib/types/adapters/text-content.d.ts +11 -0
- package/lib/types/adapters/webgl/index.d.ts +1 -0
- package/lib/types/adapters/webgl/webgl-adapter.d.ts +69 -0
- package/lib/types/browser/index.d.ts +41 -0
- package/lib/types/compat/gsap/custom-eases.d.ts +28 -0
- package/lib/types/compat/gsap/defaults.d.ts +19 -0
- package/lib/types/compat/gsap/draw-svg-vars.d.ts +36 -0
- package/lib/types/compat/gsap/ease-map.d.ts +51 -0
- package/lib/types/compat/gsap/image-sequence.d.ts +61 -0
- package/lib/types/compat/gsap/index.d.ts +65 -0
- package/lib/types/compat/gsap/inertia-vars.d.ts +39 -0
- package/lib/types/compat/gsap/keyframes-vars.d.ts +8 -0
- package/lib/types/compat/gsap/layout.d.ts +6 -0
- package/lib/types/compat/gsap/live-context.d.ts +87 -0
- package/lib/types/compat/gsap/live-draggable.d.ts +75 -0
- package/lib/types/compat/gsap/live-flip.d.ts +73 -0
- package/lib/types/compat/gsap/live-morph.d.ts +18 -0
- package/lib/types/compat/gsap/live-motion-path.d.ts +33 -0
- package/lib/types/compat/gsap/live-scroll-to.d.ts +52 -0
- package/lib/types/compat/gsap/live-scroll.d.ts +108 -0
- package/lib/types/compat/gsap/live-transition.d.ts +40 -0
- package/lib/types/compat/gsap/live.d.ts +341 -0
- package/lib/types/compat/gsap/morph-vars.d.ts +21 -0
- package/lib/types/compat/gsap/motion-path-vars.d.ts +38 -0
- package/lib/types/compat/gsap/playhead-crossings.d.ts +47 -0
- package/lib/types/compat/gsap/position.d.ts +37 -0
- package/lib/types/compat/gsap/quick-play.d.ts +38 -0
- package/lib/types/compat/gsap/split-text.d.ts +66 -0
- package/lib/types/compat/gsap/spring-vars.d.ts +34 -0
- package/lib/types/compat/gsap/stage.d.ts +182 -0
- package/lib/types/compat/gsap/stagger-grid.d.ts +30 -0
- package/lib/types/compat/gsap/text-vars.d.ts +39 -0
- package/lib/types/compat/gsap/timeline.d.ts +161 -0
- package/lib/types/compat/gsap/utils.d.ts +60 -0
- package/lib/types/compat/gsap/vars.d.ts +79 -0
- package/lib/types/drivers/index.d.ts +8 -0
- package/lib/types/drivers/scroll-driver.d.ts +218 -0
- package/lib/types/drivers/scroll-markers.d.ts +41 -0
- package/lib/types/drivers/scroll-math.d.ts +87 -0
- package/lib/types/drivers/scroll-pin.d.ts +45 -0
- package/lib/types/drivers/scroll-snap.d.ts +47 -0
- package/lib/types/drivers/smooth-scroll.d.ts +118 -0
- package/lib/types/drivers/types.d.ts +23 -0
- package/lib/types/drivers/visibility-driver.d.ts +56 -0
- package/lib/types/embed/controls.d.ts +46 -0
- package/lib/types/embed/index.d.ts +17 -0
- package/lib/types/embed/mount.d.ts +41 -0
- package/lib/types/embed/tools.d.ts +33 -0
- package/lib/types/engine/authoring/custom-ease.d.ts +49 -0
- package/lib/types/engine/authoring/index.d.ts +3 -0
- package/lib/types/engine/authoring/random.d.ts +38 -0
- package/lib/types/engine/authoring/resolve-values.d.ts +57 -0
- package/lib/types/engine/core/bake.d.ts +66 -0
- package/lib/types/engine/core/clock.d.ts +44 -0
- package/lib/types/engine/core/index.d.ts +8 -0
- package/lib/types/engine/core/inertia.d.ts +30 -0
- package/lib/types/engine/core/playhead-crossings.d.ts +47 -0
- package/lib/types/engine/core/spring.d.ts +132 -0
- package/lib/types/engine/core/stagger.d.ts +40 -0
- package/lib/types/engine/core/timeline.d.ts +203 -0
- package/lib/types/engine/core/track.d.ts +90 -0
- package/lib/types/engine/export/byte-writer.d.ts +36 -0
- package/lib/types/engine/export/css.d.ts +31 -0
- package/lib/types/engine/export/gif-decode.test-helper.d.ts +24 -0
- package/lib/types/engine/export/gif.d.ts +134 -0
- package/lib/types/engine/export/index.d.ts +9 -0
- package/lib/types/engine/export/lottie.d.ts +104 -0
- package/lib/types/engine/export/mp4.d.ts +64 -0
- package/lib/types/engine/export/quantize.d.ts +56 -0
- package/lib/types/engine/export/sprite-sheet.d.ts +46 -0
- package/lib/types/engine/export/video.d.ts +99 -0
- package/lib/types/engine/export/webp.d.ts +82 -0
- package/lib/types/engine/index.d.ts +7 -0
- package/lib/types/engine/interpolation/easing.d.ts +65 -0
- package/lib/types/engine/interpolation/index.d.ts +2 -0
- package/lib/types/engine/interpolation/interpolators.d.ts +25 -0
- package/lib/types/engine/path/index.d.ts +11 -0
- package/lib/types/engine/path/motion-path.d.ts +24 -0
- package/lib/types/engine/path/path-builders.d.ts +38 -0
- package/lib/types/engine/path/path-morph.d.ts +47 -0
- package/lib/types/engine/path/path-utils.d.ts +73 -0
- package/lib/types/engine/serialization/index.d.ts +1 -0
- package/lib/types/engine/serialization/json.d.ts +30 -0
- package/lib/types/engine/text/index.d.ts +2 -0
- package/lib/types/engine/text/text-value.d.ts +16 -0
- package/lib/types/engine/types.d.ts +401 -0
- package/lib/types/frameworks/react.d.ts +35 -0
- package/lib/types/frameworks/solid.d.ts +16 -0
- package/lib/types/frameworks/svelte.d.ts +19 -0
- package/lib/types/frameworks/vue.d.ts +27 -0
- package/lib/types/interaction/draggable.d.ts +133 -0
- package/lib/types/interaction/index.d.ts +3 -0
- package/lib/types/interaction/observer.d.ts +80 -0
- package/lib/types/interaction/snap.d.ts +30 -0
- package/lib/types/player/index.d.ts +7 -0
- package/lib/types/player/media-sync.d.ts +60 -0
- package/lib/types/player/player.d.ts +238 -0
- package/lib/types/player/sequence-types.d.ts +68 -0
- package/lib/types/player/sequencer.d.ts +91 -0
- package/lib/types/teach/diagrams.d.ts +137 -0
- package/lib/types/teach/index.d.ts +11 -0
- package/lib/types/teach/lesson.d.ts +55 -0
- 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.
|