@algorisys/tinyfly 0.67.1 → 0.69.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
@@ -39,6 +39,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
39
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
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
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
+ - **Scenarios** - Several timelines on one figure, and the reader chooses which plays: a group of options, a stepped slider, or clickable parts of the SVG (`data-tinyfly-choose`). Switching undoes the previous scenario's drawing and keeps the reader at the same step
42
43
  - **Authoring kit** - `lesson()` step builder and diagram primitives (array cells, pointer, stack, queue / channel, table, pipeline) in `@algorisys/tinyfly/teach`
43
44
  - **Build tools** - `npx @algorisys/tinyfly validate` catches broken figures in CI; `render` writes a frame to static SVG for RSS, email and print
44
45
 
@@ -106,7 +107,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
106
107
  - **Stroke write-on** - Animate a path's stroke drawing itself on (DOM + SVG renderers); one-click "Write On" preset
107
108
  - **Embed code** - Generate copy-paste code for websites (single scene or full sequence)
108
109
  - **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)
109
- - **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
110
+ - **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, 28 lessons, 67 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, smooth scrolling with parallax), 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, from the pointer-lit hero canvas to the magnetic button. Mistakes that would fail silently (a selector that matches nothing, `drawSVG` on a non-shape, a spring on a colour) show as plain-language warnings beside the code, and the last step of each module offers **Copy as page** and, for JSON lessons, **Open in editor**. The course is also in `llms-full.txt`
110
111
  - **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)
111
112
 
112
113
  ## Documentation
@@ -118,7 +119,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
118
119
  - [Examples](docs/examples.md) — Code examples for common animation patterns
119
120
  - [Scroll Animation](docs/scroll-animation.md) — Scroll-driven and visibility-triggered playback via drivers
120
121
  - [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
+ - [Teaching Animations](docs/teaching.md) — Step-through figures: markers, captions, the stepping player, controls, declarative embeds, scenarios the reader chooses, `tinyfly/teach`, validate and render
122
123
  - [Extending tinyfly](docs/extending.md) — Writing adapters, custom eases and stagger offsets, adding a track kind, contributing examples
123
124
  - [Deployment](docs/DEPLOYMENT.md) — Hosting, Docker, and CDN configuration
124
125
  - [2D Animation Roadmap](docs/2d-animation-roadmap.md) — Adobe Animate gap analysis and phased plan (symbols/library, camera, onion skinning, …)
@@ -154,7 +155,7 @@ for what you import:
154
155
  | `@algorisys/tinyfly/gsap-compat` | GSAP-style `live.to()` / `timeline()`, plus the compiling `tf` facade | Browser (`tf` anywhere) |
155
156
  | `@algorisys/tinyfly/drivers` | `ScrollDriver`, `VisibilityDriver` | Browser |
156
157
  | `@algorisys/tinyfly/interaction` | `Observer`, `Draggable` | Browser |
157
- | `@algorisys/tinyfly/embed` | Teaching embeds: the player with step controls, captions and one-script `[data-tinyfly-embed]` mounting; `validateEmbed`, `renderFrame` | Browser (tools anywhere) |
158
+ | `@algorisys/tinyfly/embed` | Teaching embeds: the player with step controls, captions, scenarios and one-script `[data-tinyfly-embed]` mounting; `validateEmbed`, `validateScenarios`, `renderFrame` | Browser (tools anywhere) |
158
159
  | `@algorisys/tinyfly/teach` | `lesson()` step builder and diagram primitives (cells, pointer, stack, queue, table, pipeline) | Anywhere |
159
160
  | `@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) |
160
161
  | `@algorisys/tinyfly/browser` | Everything above in one bundle | Browser |
@@ -203,7 +204,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
203
204
  itself.
204
205
 
205
206
  ```html
206
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.67.1/cdn/tinyfly.iife.js"></script>
207
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.69.0/cdn/tinyfly.iife.js"></script>
207
208
  <script>
208
209
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
209
210
 
@@ -225,7 +226,7 @@ itself.
225
226
  | `cdn/tinyfly-player.iife.js` | Player only (~17 KB gzipped), for playing editor exports |
226
227
  | `cdn/tinyfly-embed.iife.js` | Only teaching figures (~19 KB gzipped): player, step controls, auto-mount |
227
228
 
228
- Replace `@v0.67.1` with the version you want. **Pin a version in production**:
229
+ Replace `@v0.69.0` with the version you want. **Pin a version in production**:
229
230
  a tag's files never change, and each release's `cdn/README.md` lists an SRI hash
230
231
  for `integrity=`. `@main` follows the latest release, which jsDelivr caches for up
231
232
  to a day. Loading more than one bundle is safe: they add to the same `tinyfly`
@@ -239,7 +240,7 @@ A teaching figure needs no code at all:
239
240
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
240
241
  <figcaption>Appending to a full slice</figcaption>
241
242
  </figure>
242
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.67.1/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
243
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.69.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
243
244
  ```
244
245
 
245
246
  See [Teaching Animations](docs/teaching.md).
@@ -338,7 +339,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
338
339
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
339
340
  </div>
340
341
 
341
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.67.1/cdn/tinyfly-player.iife.js"></script>
342
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.69.0/cdn/tinyfly-player.iife.js"></script>
342
343
  <script>
343
344
  tinyfly.play('#animation', './animation.json', { loop: -1 })
344
345
  </script>
@@ -447,7 +448,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
447
448
  <svg viewBox="0 0 720 200">…</svg>
448
449
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
449
450
  </figure>
450
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.67.1/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
451
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.69.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
451
452
  ```
452
453
 
453
454
  ### Audio / Video Sync
@@ -719,20 +720,20 @@ load.
719
720
 
720
721
  ### Test Coverage
721
722
 
722
- `npm test` runs 1,999 unit tests in 121 files, all passing:
723
+ `npm test` runs 2,191 unit tests in 127 files, all passing:
723
724
 
724
725
  | Area | Tests |
725
726
  |---|---|
726
727
  | Engine (`src/engine`: timeline, easing, paths, text, exports, serialization) | 521 |
727
- | Editor (`src/editor`: stores, utils, presets, AI, samples) | 393 |
728
- | GSAP-style API (`src/compat/gsap`) | 328 |
729
- | Examples page, GSAP-style demos and showcases (`src/examples`) | 235 |
728
+ | Editor (`src/editor`: stores, utils, presets, AI, samples) | 409 |
729
+ | GSAP-style API (`src/compat/gsap`) | 332 |
730
+ | Examples page, GSAP-style demos and showcases (`src/examples`) | 302 |
730
731
  | Render adapters (`src/adapters`) | 134 |
731
- | Interactive course (`src/learn`) | 129 |
732
+ | Interactive course (`src/learn`) | 211 |
732
733
  | Drivers and interaction (`src/drivers`, `src/interaction`) | 136 |
733
- | Player, media sync, sequencer and teaching (`src/player`) | 92 |
734
- | Docs viewer and `llms.txt` (`src/docs`) | 14 |
735
- | Embeds, teaching kit, framework hooks, landing (`src/embed`, `src/teach`, `src/frameworks`, `src/landing`) | 17 |
734
+ | Player, media sync, sequencer, teaching and scenarios (`src/player`) | 103 |
735
+ | Docs viewer and `llms.txt` (`src/docs`) | 16 |
736
+ | Embeds, teaching kit, framework hooks, landing (`src/embed`, `src/teach`, `src/frameworks`, `src/landing`) | 27 |
736
737
 
737
738
  ## Contributing
738
739
 
package/bin/tinyfly.mjs CHANGED
@@ -2,17 +2,20 @@
2
2
  /**
3
3
  * tinyfly command line.
4
4
  *
5
- * tinyfly validate <timeline.json> [--markup <figure.svg|.html>]
5
+ * tinyfly validate <timeline.json> [<timeline.json> …] [--markup <figure.svg|.html>]
6
6
  * Exit 1 when the timeline has errors: tracks aimed at elements the markup
7
7
  * lacks, markers out of order or outside the animation, keyframes past an
8
8
  * explicit duration, captions for unknown markers. Warnings are printed.
9
+ * Several timelines are a figure's scenarios, each named by its "id": they
10
+ * are checked together, including repeated ids and data-tinyfly-choose
11
+ * hotspots that name no scenario.
9
12
  *
10
13
  * tinyfly render <timeline.json> <figure.svg|.html> [--at start|end|<ms>|<marker id>]
11
14
  * Print the markup with that frame written in, for places that run no
12
15
  * JavaScript (RSS, email, print, previews).
13
16
  */
14
17
  import { readFileSync } from 'node:fs'
15
- import { validateEmbed, renderFrame } from '../lib/cli/tools.js'
18
+ import { validateEmbed, validateScenarios, renderFrame } from '../lib/cli/tools.js'
16
19
 
17
20
  const [command, ...rest] = process.argv.slice(2)
18
21
  const flag = (name) => {
@@ -23,7 +26,7 @@ const flag = (name) => {
23
26
  }
24
27
 
25
28
  const usage = () => {
26
- console.error('Usage:\n tinyfly validate <timeline.json> [--markup <file>]\n tinyfly render <timeline.json> <markup file> [--at start|end|<ms>|<marker id>]')
29
+ console.error('Usage:\n tinyfly validate <timeline.json> [<timeline.json> …] [--markup <file>]\n tinyfly render <timeline.json> <markup file> [--at start|end|<ms>|<marker id>]')
27
30
  process.exit(2)
28
31
  }
29
32
 
@@ -38,9 +41,20 @@ const readJson = (file) => {
38
41
 
39
42
  if (command === 'validate') {
40
43
  const markupFile = flag('--markup')
41
- const [timelineFile] = rest
42
- if (!timelineFile) usage()
43
- const problems = validateEmbed(readJson(timelineFile), { markup: markupFile ? readFileSync(markupFile, 'utf8') : undefined })
44
+ const timelineFiles = rest
45
+ if (timelineFiles.length === 0) usage()
46
+ const markup = markupFile ? readFileSync(markupFile, 'utf8') : undefined
47
+ const timelineFile = timelineFiles.join(', ')
48
+ const problems =
49
+ timelineFiles.length === 1
50
+ ? validateEmbed(readJson(timelineFiles[0]), { markup })
51
+ : validateScenarios(
52
+ timelineFiles.map((file) => {
53
+ const timeline = readJson(file)
54
+ return { id: timeline.id ?? file, timeline }
55
+ }),
56
+ { markup }
57
+ )
44
58
  for (const problem of problems) console.error(`${problem.level}: ${problem.message}`)
45
59
  const errors = problems.filter((problem) => problem.level === 'error').length
46
60
  if (errors > 0) {