@algorisys/tinyfly 0.126.0 → 0.127.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
@@ -173,6 +173,14 @@ cross-outs and scribble-outs drawn on over time). Text and fonts are yours. See
173
173
  [Noir and Detective Scenes](docs/noir-detective.md) and the
174
174
  [Noir Case File](https://tinyfly.app/examples/live-noir-case-file) example.
175
175
 
176
+ **Cosmic explainer scenes**: a canvas kit for animated science explainers, deterministic from time:
177
+ saturated gradient skies, parallax dust and bokeh, flat-shaded shapes (`drawShadedBall`, `drawIsoCube`,
178
+ `drawHaze`), zooming through scale in growing portals (`drawZoomLevels` with `depthAt` / `zoomAt`),
179
+ burned-in short captions two words at a time (`drawShortCaption`) and label chips; and sound effects made
180
+ from numbers in `tinyfly/headless` (`soundWhoosh`, `soundPop`, `soundThud`, `soundShimmer`, `soundTick`,
181
+ `soundClick`, `soundPad`) that `renderMix` takes as samples. See
182
+ [Cosmic Explainer Scenes](docs/cosmic-explainer.md) and `examples/headless-video/cosmic-explainer.mjs`.
183
+
176
184
  The [Young Adult Manga Cast](https://tinyfly.app/examples/live-manga-cast)
177
185
  adds four original presets with angular jaws, tapered chins, narrower eyes
178
186
  and pointed hair tufts. Use `MANGA_CAST` or `castMember('mangaYoungMan', 300)`;
@@ -302,7 +310,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
302
310
  itself.
303
311
 
304
312
  ```html
305
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly.iife.js"></script>
313
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly.iife.js"></script>
306
314
  <script>
307
315
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
308
316
 
@@ -339,7 +347,7 @@ A teaching figure needs no code at all:
339
347
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
340
348
  <figcaption>Appending to a full slice</figcaption>
341
349
  </figure>
342
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
350
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
343
351
  ```
344
352
 
345
353
  See [Teaching Animations](docs/teaching.md).
@@ -438,7 +446,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
438
446
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
439
447
  </div>
440
448
 
441
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-player.iife.js"></script>
449
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly-player.iife.js"></script>
442
450
  <script>
443
451
  tinyfly.play('#animation', './animation.json', { loop: -1 })
444
452
  </script>
@@ -547,7 +555,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
547
555
  <svg viewBox="0 0 720 200">…</svg>
548
556
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
549
557
  </figure>
550
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
558
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
551
559
  ```
552
560
 
553
561
  ### Audio / Video Sync
@@ -0,0 +1,129 @@
1
+ # Cosmic Explainer Scenes
2
+
3
+ A kit for animated science explainers in the bright, flat, glowing look of
4
+ popular science channels: a saturated gradient sky per scene, drifting dust
5
+ and soft bokeh for depth, flat-shaded shapes with no outlines (a sphere with a
6
+ shadow crescent and a highlight, an isometric cube, a probability haze),
7
+ zooming through scale with growing portals (a hand → skin → cells → one atom),
8
+ burned-in short captions two words at a time, label chips, and sound effects
9
+ made from numbers.
10
+
11
+ Every function draws on a Canvas 2D context, takes the time in ms and plain
12
+ options, and draws the same thing for the same input: particles sit where a
13
+ hash of their index puts them, never `Math.random`, so a frame looks the same
14
+ whether it is rendered in order, out of order or scrubbed to. Text is yours
15
+ (any script that separates words with spaces, Devanagari included) and so are
16
+ the fonts. Pair it with the noir kit's `drawGlow` and `drawVignette`, the
17
+ scene's `bloom`, and the characters.
18
+
19
+ ```js
20
+ import { drawSkyGradient, drawDust, drawBokeh, drawShadedBall, drawHaze, drawZoomLevels,
21
+ depthAt, levelPresence, drawShortCaption, drawLabelChip, drawGlow } from '@algorisys/tinyfly/characters'
22
+
23
+ const dive = [{ time: 1800, value: 0 }, { time: 3400, value: 1.35 }, { time: 5400, value: 2.35 }]
24
+ const atom = (ctx, time) => {
25
+ drawSkyGradient(ctx, { width: 720, height: 1280, sky: 'space' })
26
+ drawHaze(ctx, time, { x: 360, y: 576, radius: 120 })
27
+ drawGlow(ctx, { x: 360, y: 576, radius: 60, color: '#fb923c' })
28
+ }
29
+
30
+ function frame(ctx, time) {
31
+ const depth = depthAt(time, dive)
32
+ drawZoomLevels(ctx, time, { width: 720, height: 1280, depth, levels: [hand, cells, atom], center: { x: 360, y: 576 } })
33
+ drawBokeh(ctx, time, { width: 720, height: 1280, offset: { x: depth * 40, y: 0 } })
34
+ drawDust(ctx, time, { width: 720, height: 1280, offset: { x: depth * 60, y: 0 } })
35
+ if (levelPresence(depth, 2) > 0.5) drawLabelChip(ctx, time, { text: 'one atom', x: 360, y: 150, at: 5150 })
36
+ drawShortCaption(ctx, time, { lines: narrationCues, x: 360, y: 920 })
37
+ }
38
+ ```
39
+
40
+ `examples/headless-video/cosmic-explainer.mjs` is a whole 9:16 short built
41
+ this way, with its sound mix made entirely from the generators.
42
+
43
+ ## Skies and depth
44
+
45
+ | Function | Draws |
46
+ |---|---|
47
+ | `drawSkyGradient(ctx, { width, height, sky?, top?, bottom? })` | A vertical gradient filling the frame. `sky` is one of `COSMIC_SKIES`: `space`, `micro`, `magenta`, `cyan`, `lime`, `sunset`, `ocean`; or give `top` and `bottom`. An unknown name throws with the list. |
48
+ | `drawDust(ctx, time, { width, height, count?, color?, opacity?, size?, drift?, offset?, seed? })` | Twinkling specks in three parallax depths, wrapping round the frame. `drift` is px per second for the nearest layer; `offset` is the camera's shift (far specks move less). |
49
+ | `drawBokeh(ctx, time, { width, height, count?, color?, opacity?, minRadius?, maxRadius?, drift?, offset?, seed? })` | Big soft out-of-focus discs drifting across (foreground depth); they move 1.6× the camera offset. |
50
+
51
+ Give each scene a different sky, so a scene change reads even without a hard
52
+ cut, and keep dust and bokeh in every shot, so no frame is ever still.
53
+
54
+ ## Flat-shaded shapes
55
+
56
+ | Function | Draws |
57
+ |---|---|
58
+ | `drawShadedBall(ctx, { x, y, radius, color, light?, shadow?, highlight?, opacity? })` | A sphere: the base fill, a darker crescent away from `light` (each axis −1..1, default top left), a small white highlight. No outline. |
59
+ | `drawIsoCube(ctx, { x, y, size, color, opacity?, sheen? })` | An isometric cube: lit top, a mid left face, a dark right face, an optional sparkle. `isoCubeFaces` gives the three polygons. |
60
+ | `drawHaze(ctx, time, { x, y, radius, color?, dots?, dot?, opacity?, squash?, spin?, seed? })` | A probability cloud of flickering dots, densest on a ring at `radius` (an electron shell). |
61
+ | `cosmicShade(color, amount, alpha?)` | The colour toward black (`amount` < 0) or white (> 0): the flat-shading palette from one base colour. |
62
+
63
+ Colours are `#rgb`, `#rrggbb` or `rgb()`; anything else throws, since the kit
64
+ has to shade it.
65
+
66
+ ## Zooming through scale
67
+
68
+ The signature move: a dive from something you know down through levels of
69
+ scale. The levels are drawings, each `factor` times smaller than the one
70
+ before (default 14); one number, the **depth**, drives them all. Level *k* is
71
+ drawn at scale `factor ** (depth − k)` inside a circular portal at the zoom
72
+ centre, so the next level opens as a window in the middle of the current one
73
+ and grows until it fills the frame; levels hidden behind a covering portal are
74
+ not drawn.
75
+
76
+ | Function | |
77
+ |---|---|
78
+ | `depthAt(time, keys)` | The depth at a time, eased between `{ time, value }` keys. About `k + 0.35` shows level *k* filling the frame. |
79
+ | `zoomAt(time, keys)` | A zoom factor eased in log space (values > 0): halfway between 1× and 100× is 10×, so a dive feels steady. |
80
+ | `drawZoomLevels(ctx, time, { width, height, depth, levels, factor?, center?, portalRadius?, rim?, rimWidth? })` | Draw the visible levels; each level function draws itself at scale 1 around `center`. `rim: null` drops the glowing ring. |
81
+ | `zoomLevelLayout({ width, height, depth, levelCount, factor?, portalRadius? })` | Which levels draw at a depth, with their scale and portal radius. |
82
+ | `levelPresence(depth, level)` | 0..1: how fully a level fills the screen, to show or fade its label. |
83
+ | `drawPortalRim(ctx, x, y, radius, color?, width?)` | The glowing ring on its own (a lens edge, an inset). |
84
+
85
+ Time the depth keys to the narration: put each level's arrival on the word
86
+ that names it. For an endless, self-similar zoom (the same frame inside
87
+ itself forever) use `nestedZoom` from `tinyfly/adapters` instead.
88
+
89
+ ## Short captions and chips
90
+
91
+ | Function | |
92
+ |---|---|
93
+ | `drawShortCaption(ctx, time, { lines, x, y, size?, font?, color?, shadow?, wordsPerChunk?, lowercase? })` | Burned-in captions one to three words at a time (default 2), lower case, boxless, with a drop shadow; returns the text drawn. `lines` are `{ text, start, end }` (narration cues fit as they are). Sit them at about 72% of the height in 9:16, 86% in 16:9. |
94
+ | `captionChunkAt(line, time, wordsPerChunk?)` | The chunk showing at a time: each chunk gets its share of the line by its share of the characters, close enough for a few words at a time. |
95
+ | `captionChunks(text, wordsPerChunk?)` | A line cut at spaces. |
96
+ | `drawLabelChip(ctx, time, { text, x, y, size?, font?, fill?, color?, at?, pop? })` | A rounded chip that pops on at `at`; returns its width. |
97
+ | `drawCornerNote(ctx, { text, x, y, size?, font?, color? })` | A small right-aligned note, such as `*not to scale`. |
98
+
99
+ ## Sound effects from numbers
100
+
101
+ `@algorisys/tinyfly/headless` makes sound effects as mono `Float32Array`
102
+ samples, seeded and deterministic, with no files to find or license:
103
+ `soundWhoosh(rate, { duration?, rise?, seed? })` for zooms and cuts,
104
+ `soundPop(rate, { frequency?, duration? })` for chips, `soundThud(rate)` for
105
+ impacts, `soundShimmer(rate)` for reveals, `soundTick(rate)` for counters,
106
+ `soundClick(rate)` for a latch or padlock, and `soundPad(rate, { duration })`,
107
+ a slow ambient drone to mix low under narration.
108
+
109
+ `renderMix` layers take `samples` as well as `file`, so a mix needs no ffmpeg
110
+ decoding for them:
111
+
112
+ ```js
113
+ import { renderMix, soundPad, soundWhoosh, soundPop } from '@algorisys/tinyfly/headless'
114
+
115
+ const audio = await renderMix([
116
+ { id: 'voice', file: 'build/narration.wav' },
117
+ { samples: soundPad(48000, { duration: END }), gain: 0.2, duck: { under: 'voice', amount: 0.5 } },
118
+ { samples: soundWhoosh(48000), at: [3000, 5200], gain: 0.5 },
119
+ { samples: soundPop(48000), at: [3300, 5500], gain: 0.4 },
120
+ ], { output: 'build/mix.wav', duration: END, baseDir: here })
121
+ ```
122
+
123
+ ## Style notes
124
+
125
+ - One sky per scene; dust and bokeh always on; a slow push-in on every shot.
126
+ - A whoosh on every zoom or scene change, a pop on every chip, ticks for
127
+ counters, a thud for impacts, a shimmer for reveals, a quiet pad under all.
128
+ - Anything drawn at an illustrative scale gets a `drawCornerNote` saying so;
129
+ anything that claims a scale is drawn to it.
@@ -1143,7 +1143,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
1143
1143
  **Steps to embed:**
1144
1144
  1. Build the player: `npm run build:player`
1145
1145
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
1146
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-player.iife.js`
1146
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly-player.iife.js`
1147
1147
  instead; see [Deployment](DEPLOYMENT.md))
1148
1148
  3. Copy the generated code into your HTML
1149
1149
  4. Adjust the script `src` path if needed
package/docs/examples.md CHANGED
@@ -754,7 +754,7 @@ For simple website embedding without a build system.
754
754
  </html>
755
755
  ```
756
756
 
757
- Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-player.iife.js`.
757
+ Build the player with `npm run build:player` to generate `lib/player/tinyfly-player.iife.js`, or load it from the CDN: `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly-player.iife.js`.
758
758
 
759
759
  ---
760
760
 
@@ -185,7 +185,7 @@ with a GSAP-style call (durations are in seconds here):
185
185
  ```html
186
186
  <div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
187
187
 
188
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly.iife.js"></script>
189
189
  <script>
190
190
  tinyfly.to('.box', { x: 200, duration: 1 })
191
191
  </script>
@@ -74,7 +74,7 @@ Without a build step, the all-in-one bundle exposes the same functions on a
74
74
  global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
75
75
 
76
76
  ```html
77
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly.iife.js"></script>
78
78
  <script>
79
79
  tinyfly.to('.box', { x: 200, duration: 1 })
80
80
  </script>
package/docs/llm-guide.md CHANGED
@@ -226,6 +226,13 @@ lines (`bean: { limbs: 'tube' | 'line' }`), a shaped body (`bean.torso` fullness
226
226
  Household clothes on a bean: `bean: { skirt: '#c2410c' }` (a sari to the ankle) or
227
227
  `skirt: { color, length: 0.45 }` (a kurta hem; pair it with `trousers`), `drape` (a pallu or dupatta sash)
228
228
  and `bangles`; preset `beanSari`. The skirt follows the legs (flared standing, along the thighs seated).
229
+ For science explainers use the cosmic kit (docs/cosmic-explainer.md): `drawSkyGradient` (one sky per scene),
230
+ `drawDust` and `drawBokeh` (always on; pass the camera `offset`), flat-shaded `drawShadedBall`, `drawIsoCube`,
231
+ `drawHaze`; a dive through scale with `drawZoomLevels(ctx, time, { width, height, depth: depthAt(time, keys), levels })`
232
+ (each level function draws itself at scale 1 around the centre; put each level's arrival on the word that names it);
233
+ burned-in `drawShortCaption(ctx, time, { lines, x, y })` and `drawLabelChip`. Sound effects come from
234
+ tinyfly/headless (`soundWhoosh`, `soundPop`, `soundThud`, `soundShimmer`, `soundTick`, `soundClick`, `soundPad`)
235
+ as `renderMix` layers `{ samples, at, gain }`; no files needed.
229
236
  For detective / noir scenes use the canvas kit (docs/noir-detective.md): `drawRain(ctx, time, box)`,
230
237
  `drawBlinds`, `drawDarkness(ctx, { amount, cones: [{ x, y, angle /* degrees */, length, width }], holes })`,
231
238
  `drawGlow`, `drawVignette`, `drawClueMarker(ctx, time, { x, y, at })`, `drawNameCard(ctx, time, { name, role, at, anchor })`,
package/docs/maps.md CHANGED
@@ -14,8 +14,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
14
14
  adds to the same `tinyfly` global:
15
15
 
16
16
  ```html
17
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly-maps.iife.js"></script>
19
19
  ```
20
20
 
21
21
  It is a separate script because the offline world map it carries adds about
package/docs/math.md CHANGED
@@ -258,7 +258,7 @@ lesson's step options (`duration`, `easing`, `delay`).
258
258
  <figcaption>The determinant is the area of the unit square after the map.</figcaption>
259
259
  </figure>
260
260
 
261
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-math.iife.js" data-tinyfly-auto></script>
261
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly-math.iife.js" data-tinyfly-auto></script>
262
262
  ```
263
263
 
264
264
  The figure draws itself into an SVG and redraws from the timeline whenever the
package/docs/teaching.md CHANGED
@@ -25,7 +25,7 @@ path for all of that:
25
25
  </figure>
26
26
 
27
27
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
28
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
29
29
  ```
30
30
 
31
31
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post