@algorisys/tinyfly 0.64.0 → 0.66.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/README.md CHANGED
@@ -1,7 +1,12 @@
1
1
  # tinyfly
2
2
 
3
+ [![npm](https://img.shields.io/npm/v/@algorisys/tinyfly)](https://www.npmjs.com/package/@algorisys/tinyfly)
4
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
5
+
3
6
  A lightweight, API-driven animation engine and visual editor for creating high-performance, embeddable animations.
4
7
 
8
+ **Try it:** [studio](https://tinyfly.app/studio) · [interactive course](https://tinyfly.app/learn) · [examples](https://tinyfly.app/examples) · `npm install @algorisys/tinyfly`
9
+
5
10
  **GSAP-level power with Excalidraw-level simplicity.**
6
11
 
7
12
  ## Features
@@ -14,7 +19,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
14
19
 
15
20
  ### Animation Capabilities
16
21
  - **Timeline-based** - Orchestrate multiple tracks with precise timing
17
- - **Rich easing** - Linear, quad, cubic, custom cubic-bezier, and more
22
+ - **Rich easing** - Linear, quad, cubic, custom cubic-bezier, and parametric `elastic` / `bounce` / `back` / `steps` eases that stay one small, exact keyframe in JSON
18
23
  - **Interpolation** - Numbers, colors, and arrays
19
24
  - **Playback control** - Play, pause, stop, seek, reverse, speed adjustment
20
25
  - **Looping** - Finite loops, infinite loops, ping-pong (alternate), and `repeatDelay` between iterations
@@ -30,6 +35,13 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
30
35
  - **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
36
  - **FLIP transitions** - `flip()` measures a layout change in the DOM layer and emits ordinary keyframes, keeping the engine free of live layout reads
32
37
 
38
+ ### Teaching Animations
39
+ - **Markers and captions in the JSON** - Named steps (`pause`, `question` for predict-then-reveal) and captions per language, kept out of the tracks so translation never touches timing
40
+ - **A player that teaches** - Shows a real frame on load, steps between markers (`next` / `prev` / `stepMode`), respects `prefers-reduced-motion`, and pauses off screen
41
+ - **One-script embeds** - `tinyfly-embed.iife.js` with `data-tinyfly-auto` mounts every `[data-tinyfly-embed]` figure with step controls, announced captions and an accessible SVG, with no per-post JavaScript
42
+ - **Authoring kit** - `lesson()` step builder and diagram primitives (array cells, pointer, stack, queue / channel, table, pipeline) in `@algorisys/tinyfly/teach`
43
+ - **Build tools** - `npx @algorisys/tinyfly validate` catches broken figures in CI; `render` writes a frame to static SVG for RSS, email and print
44
+
33
45
  ### Render Adapters
34
46
  - **DOM** - CSS transforms, opacity, colors, clip-path reveal, filters, shine, transform-origin, perspective
35
47
  - **Canvas** - Shapes with position, size, rotation, colors, clip reveal, filters, transform-origin pivot
@@ -106,6 +118,8 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
106
118
  - [Examples](docs/examples.md) — Code examples for common animation patterns
107
119
  - [Scroll Animation](docs/scroll-animation.md) — Scroll-driven and visibility-triggered playback via drivers
108
120
  - [GSAP Compatibility](docs/gsap-compat.md) — The GSAP-flavoured API, the mapping table, and what we deliberately don't do
121
+ - [Teaching Animations](docs/teaching.md) — Step-through figures: markers, captions, the stepping player, controls, declarative embeds, `tinyfly/teach`, validate and render
122
+ - [Extending tinyfly](docs/extending.md) — Writing adapters, custom eases and stagger offsets, adding a track kind, contributing examples
109
123
  - [Deployment](docs/DEPLOYMENT.md) — Hosting, Docker, and CDN configuration
110
124
  - [2D Animation Roadmap](docs/2d-animation-roadmap.md) — Adobe Animate gap analysis and phased plan (symbols/library, camera, onion skinning, …)
111
125
 
@@ -175,11 +189,13 @@ Every release publishes browser bundles to the `cdn/` folder of
175
189
  its version, and [jsDelivr](https://www.jsdelivr.com/) serves them straight from
176
190
  GitHub. No npm required.
177
191
 
178
- `tinyfly.iife.js` (~29 KB gzipped) puts everything on one `tinyfly` global, with
179
- GSAP-shaped functions at the top level:
192
+ `tinyfly.iife.js` (~53 KB gzipped) puts everything on one `tinyfly` global, with
193
+ GSAP-shaped functions at the top level. Teaching embeds are included: add
194
+ `data-tinyfly-auto` to the script tag and every `[data-tinyfly-embed]` figure mounts
195
+ itself.
180
196
 
181
197
  ```html
182
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.64.0/cdn/tinyfly.iife.js"></script>
198
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.66.0/cdn/tinyfly.iife.js"></script>
183
199
  <script>
184
200
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
185
201
 
@@ -195,10 +211,11 @@ GSAP-shaped functions at the top level:
195
211
 
196
212
  | File | What |
197
213
  |---|---|
198
- | `cdn/tinyfly.iife.js` | Everything, on a `tinyfly` global |
214
+ | `cdn/tinyfly.iife.js` | Everything, on a `tinyfly` global, including teaching embeds |
199
215
  | `cdn/tinyfly.umd.js` | The same, as UMD |
200
216
  | `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 |
217
+ | `cdn/tinyfly-player.iife.js` | Player only (~17 KB gzipped), for playing editor exports |
218
+ | `cdn/tinyfly-embed.iife.js` | Only teaching figures (~19 KB gzipped): player, step controls, auto-mount |
202
219
 
203
220
  Replace `@v0.59.0` with the version you want. **Pin a version in production**:
204
221
  a tag's files never change. `@main` follows the latest release, which jsDelivr
@@ -363,6 +380,14 @@ Custom cubic-bezier easing:
363
380
  }
364
381
  ```
365
382
 
383
+ Parametric eases, evaluated exactly when played:
384
+ ```typescript
385
+ { type: 'elastic', mode: 'out', amplitude: 1, period: 0.3 }
386
+ { type: 'bounce', mode: 'in-out' }
387
+ { type: 'back', mode: 'out', overshoot: 1.70158 }
388
+ { type: 'steps', count: 5, position: 'end' } // CSS steps() jump positions
389
+ ```
390
+
366
391
  ### Player
367
392
 
368
393
  ```typescript
@@ -379,6 +404,23 @@ player.pause();
379
404
  player.seek(500);
380
405
  player.setSpeed(2);
381
406
  player.destroy();
407
+
408
+ // Teaching: markers, steps and captions
409
+ const lessonPlayer = new TinyflyPlayer('#figure', { stepMode: true, playWhenVisible: true });
410
+ await lessonPlayer.load('slice.json'); // shows the first frame straight away
411
+ lessonPlayer.next(); // animate to the next marker
412
+ lessonPlayer.prev(); // jump back a step
413
+ lessonPlayer.caption(); // the current step's caption, in the page's language
414
+ ```
415
+
416
+ Or skip the code entirely with declarative embeds (see [Teaching Animations](docs/teaching.md)):
417
+
418
+ ```html
419
+ <figure data-tinyfly-embed data-options='{"stepMode": true}'>
420
+ <svg viewBox="0 0 720 200">…</svg>
421
+ <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
422
+ </figure>
423
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.66.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
382
424
  ```
383
425
 
384
426
  ### Audio / Video Sync
@@ -559,7 +601,7 @@ tinyfly/
559
601
  - [x] Visual curve editor for custom easing
560
602
  - [x] npm engine package + CDN player build (`npm run build:libs`)
561
603
  - [x] All-in-one `<script>` bundle with a GSAP-shaped `tinyfly` global, and `live.to()` that plays on real elements
562
- - [ ] Publish to npm
604
+ - [x] Publish to npm as [`@algorisys/tinyfly`](https://www.npmjs.com/package/@algorisys/tinyfly)
563
605
 
564
606
  ### Future
565
607
  - [x] Scene transitions (fade, slide between scenes)
@@ -591,9 +633,12 @@ tinyfly/
591
633
  - [x] Inertia / throw as an `inertia` track kind
592
634
  - [x] Text tracks: type-on and scramble text
593
635
  - [x] CustomEase, CustomBounce, CustomWiggle
594
- - [ ] Framework wrappers (React / Vue / Svelte)
636
+ - [x] Framework wrappers (`@algorisys/tinyfly/react`, `/vue`, `/svelte`, `/solid`)
595
637
  - [x] Scroll pinning (`scrollTrigger: { pin }`), split text, drawSVG, springs and shared-element Flip on `live` ([Phase 28](todo.md))
596
638
  - [x] Interactive tutorial at `/learn` — 9 modules from keyframes to an award-style landing page, checked in three browsers ([Phase 29](todo.md))
639
+ - [x] GSAP parity: native eases, `live.utils`, keyframes, grid staggers, rotation dragging, scroll batch / scroll-to, smooth scrolling, timeline callbacks ([Phase 29E](todo.md))
640
+ - [x] Teaching embeds: markers, captions, stepping player, controls, declarative mounting, `tinyfly/teach`, validate / render ([Phase 30](todo.md))
641
+ - [ ] Editor UI for markers and captions
597
642
  - [ ] Nested timelines at runtime, explicit track priority
598
643
  - [ ] React Native adapter
599
644
  - [ ] Collaborative editing
@@ -633,8 +678,12 @@ results rather than just looking for errors:
633
678
  motion-path precision.
634
679
  - **Editor:** adding elements, playing in all three renderers, and IndexedDB
635
680
  persistence across a reload.
681
+ - **Site:** the landing page, docs, every example page, the showcases (pins, smooth
682
+ scrolling, parallax, reduced motion) and every course step.
683
+ - **Embeds:** keyboard stepping in the focused figure only, captions in the page
684
+ language, SVG paint, labelled images, play-when-visible and reduced motion.
636
685
 
637
- Latest run: Chromium 150, Firefox 153 and WebKit 26.5 pass all 33 checks. In WebKit
686
+ Latest run: Chromium 150, Firefox 153 and WebKit 26.5 pass every check. In WebKit
638
687
  on Linux, MP4 export is reported as a note: Playwright's WebKit build crashes while
639
688
  starting its bundled GStreamer, before tinyfly's code runs. WebKit needs `libavif16`
640
689
  on Linux hosts, and the runner removes the GTK/GIO variables a snap-installed
@@ -643,18 +692,20 @@ load.
643
692
 
644
693
  ### Test Coverage
645
694
 
646
- `npm test` runs 1,711 unit tests in 99 files, all passing:
695
+ `npm test` runs 1,999 unit tests in 121 files, all passing:
647
696
 
648
697
  | Area | Tests |
649
698
  |---|---|
650
- | Engine (`src/engine`: timeline, easing, paths, text, exports, serialization) | 498 |
699
+ | Engine (`src/engine`: timeline, easing, paths, text, exports, serialization) | 521 |
651
700
  | 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 |
701
+ | GSAP-style API (`src/compat/gsap`) | 328 |
702
+ | Examples page, GSAP-style demos and showcases (`src/examples`) | 235 |
654
703
  | Render adapters (`src/adapters`) | 134 |
655
- | Player, media sync and sequencer (`src/player`) | 83 |
656
- | Drivers and interaction (`src/drivers`, `src/interaction`) | 108 |
704
+ | Interactive course (`src/learn`) | 129 |
705
+ | Drivers and interaction (`src/drivers`, `src/interaction`) | 136 |
706
+ | Player, media sync, sequencer and teaching (`src/player`) | 92 |
657
707
  | Docs viewer and `llms.txt` (`src/docs`) | 14 |
708
+ | Embeds, teaching kit, framework hooks, landing (`src/embed`, `src/teach`, `src/frameworks`, `src/landing`) | 17 |
658
709
 
659
710
  ## Contributing
660
711