@algorisys/tinyfly 0.126.0 → 0.127.1

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,15 @@ 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), the
183
+ [Cosmic Dive](https://tinyfly.app/examples/live-cosmic-dive) example and `examples/headless-video/cosmic-explainer.mjs`.
184
+
176
185
  The [Young Adult Manga Cast](https://tinyfly.app/examples/live-manga-cast)
177
186
  adds four original presets with angular jaws, tapered chins, narrower eyes
178
187
  and pointed hair tufts. Use `MANGA_CAST` or `castMember('mangaYoungMan', 300)`;
@@ -302,7 +311,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
302
311
  itself.
303
312
 
304
313
  ```html
305
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly.iife.js"></script>
314
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.1/cdn/tinyfly.iife.js"></script>
306
315
  <script>
307
316
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
308
317
 
@@ -339,7 +348,7 @@ A teaching figure needs no code at all:
339
348
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
340
349
  <figcaption>Appending to a full slice</figcaption>
341
350
  </figure>
342
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
351
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.1/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
343
352
  ```
344
353
 
345
354
  See [Teaching Animations](docs/teaching.md).
@@ -438,7 +447,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
438
447
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
439
448
  </div>
440
449
 
441
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-player.iife.js"></script>
450
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.1/cdn/tinyfly-player.iife.js"></script>
442
451
  <script>
443
452
  tinyfly.play('#animation', './animation.json', { loop: -1 })
444
453
  </script>
@@ -547,7 +556,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
547
556
  <svg viewBox="0 0 720 200">…</svg>
548
557
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
549
558
  </figure>
550
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.126.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
559
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.1/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
551
560
  ```
552
561
 
553
562
  ### Audio / Video Sync
@@ -0,0 +1,133 @@
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, and the
42
+ [Cosmic Dive](https://tinyfly.app/examples/live-cosmic-dive) example plays the
43
+ same dive at 16:9 in the browser (pause and scrub it).
44
+
45
+ ## Skies and depth
46
+
47
+ | Function | Draws |
48
+ |---|---|
49
+ | `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. |
50
+ | `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). |
51
+ | `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. |
52
+
53
+ Give each scene a different sky, so a scene change reads even without a hard
54
+ cut, and keep dust and bokeh in every shot, so no frame is ever still.
55
+
56
+ ## Flat-shaded shapes
57
+
58
+ | Function | Draws |
59
+ |---|---|
60
+ | `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. |
61
+ | `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. |
62
+ | `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). |
63
+ | `cosmicShade(color, amount, alpha?)` | The colour toward black (`amount` < 0) or white (> 0): the flat-shading palette from one base colour. |
64
+
65
+ Colours are `#rgb`, `#rrggbb` or `rgb()`; anything else throws, since the kit
66
+ has to shade it.
67
+
68
+ ## Zooming through scale
69
+
70
+ The signature move: a dive from something you know down through levels of
71
+ scale. The levels are drawings, each `factor` times smaller than the one
72
+ before (default 14); one number, the **depth**, drives them all. Level *k* is
73
+ drawn at scale `factor ** (depth − k)` inside a circular portal at the zoom
74
+ centre, so the next level opens as a window in the middle of the current one
75
+ and grows until it fills the frame; levels hidden behind a covering portal are
76
+ not drawn.
77
+
78
+ | Function | |
79
+ |---|---|
80
+ | `depthAt(time, keys)` | The depth at a time, eased between `{ time, value }` keys. About `k + 0.35` shows level *k* filling the frame. |
81
+ | `zoomAt(time, keys)` | A zoom factor eased in log space (values > 0): halfway between 1× and 100× is 10×, so a dive feels steady. |
82
+ | `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. |
83
+ | `zoomLevelLayout({ width, height, depth, levelCount, factor?, portalRadius? })` | Which levels draw at a depth, with their scale and portal radius. |
84
+ | `levelPresence(depth, level)` | 0..1: how fully a level fills the screen, to show or fade its label. |
85
+ | `drawPortalRim(ctx, x, y, radius, color?, width?)` | The glowing ring on its own (a lens edge, an inset). |
86
+
87
+ A level covers the frame once its portal reaches half the frame's diagonal: `portalRadius × factor^(depth − k) ≥ √(w² + h²) / 2`. With the defaults (520 px, ×14) that is depth `k + 0.28` on a 1920×1080 frame; a smaller `portalRadius` needs a deeper key before the level behind stops showing at the corners.
88
+
89
+ Time the depth keys to the narration: put each level's arrival on the word
90
+ that names it. For an endless, self-similar zoom (the same frame inside
91
+ itself forever) use `nestedZoom` from `tinyfly/adapters` instead.
92
+
93
+ ## Short captions and chips
94
+
95
+ | Function | |
96
+ |---|---|
97
+ | `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. |
98
+ | `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. |
99
+ | `captionChunks(text, wordsPerChunk?)` | A line cut at spaces. |
100
+ | `drawLabelChip(ctx, time, { text, x, y, size?, font?, fill?, color?, at?, pop? })` | A rounded chip that pops on at `at`; returns its width. |
101
+ | `drawCornerNote(ctx, { text, x, y, size?, font?, color? })` | A small right-aligned note, such as `*not to scale`. |
102
+
103
+ ## Sound effects from numbers
104
+
105
+ `@algorisys/tinyfly/headless` makes sound effects as mono `Float32Array`
106
+ samples, seeded and deterministic, with no files to find or license:
107
+ `soundWhoosh(rate, { duration?, rise?, seed? })` for zooms and cuts,
108
+ `soundPop(rate, { frequency?, duration? })` for chips, `soundThud(rate)` for
109
+ impacts, `soundShimmer(rate)` for reveals, `soundTick(rate)` for counters,
110
+ `soundClick(rate)` for a latch or padlock, and `soundPad(rate, { duration })`,
111
+ a slow ambient drone to mix low under narration.
112
+
113
+ `renderMix` layers take `samples` as well as `file`, so a mix needs no ffmpeg
114
+ decoding for them:
115
+
116
+ ```js
117
+ import { renderMix, soundPad, soundWhoosh, soundPop } from '@algorisys/tinyfly/headless'
118
+
119
+ const audio = await renderMix([
120
+ { id: 'voice', file: 'build/narration.wav' },
121
+ { samples: soundPad(48000, { duration: END }), gain: 0.2, duck: { under: 'voice', amount: 0.5 } },
122
+ { samples: soundWhoosh(48000), at: [3000, 5200], gain: 0.5 },
123
+ { samples: soundPop(48000), at: [3300, 5500], gain: 0.4 },
124
+ ], { output: 'build/mix.wav', duration: END, baseDir: here })
125
+ ```
126
+
127
+ ## Style notes
128
+
129
+ - One sky per scene; dust and bokeh always on; a slow push-in on every shot.
130
+ - A whoosh on every zoom or scene change, a pop on every chip, ticks for
131
+ counters, a thud for impacts, a shimmer for reveals, a quiet pad under all.
132
+ - Anything drawn at an illustrative scale gets a `drawCornerNote` saying so;
133
+ 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.1/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.1/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.1/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.1/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.1/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.127.1/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.1/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.1/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