@algorisys/tinyfly 0.123.0 → 0.124.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
@@ -68,7 +68,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
68
68
  - **The drawing hand** - `drawnPathTarget()` draws a sketched stroke on from a `draw` track while a cartoon hand holds the pencil at its end in a writing grip; the same hand can hold the eraser. `handAt()` gives one hand for a whole scene: it follows each stroke, lifts and glides to the next, and enters and leaves the page
69
69
  - **Erasing** - An eraser rubs out part of a target (`erasable()`, animated by an `erase` track) or of anything drawn in code (`withErased()`); clip-based, so it works in the browser and headless alike
70
70
  - **Cartoon hands** - A hand rig in 3D, drawn flat: thumb and fingers posed by numbers (`index.curl`, `thumb.across`, `spread`, `turn`), ready-made shapes (fist, point, thumbs-up, peace, OK, pinch, wave, pencil grip…), left and right, four or five fingers, in every look; the animator's hand and (opt-in) character gloves are built on it. See [docs/cartoon-hands.md](docs/cartoon-hands.md)
71
- - **Cartoon acting** - `actTracks()` turns the same key poses into acted motion: wind-ups, overshoot that settles or wobbles, joints that overlap (hips lead, wrists drag), eyes that dart ahead and blink on head turns, moving holds and jump squash, in `full`, `snappy` or `limited` styles. Gags come as data (`gag('take')`, double take, wind-up, tremble). A line of action (`bend`) curves the spine, and gaits have personality (bouncy, double bounce, sneak, strut, tired, run). Lip-sync works from text, Latin or Devanagari. `scriptTracks()` compiles a story written as beats (`{ do: 'walk', to: 640 }`, `{ do: 'take' }`, `{ do: 'say', say: '…' }`) into all of it, and `characterScript()` compiles the same beats for a v2 character from the cast, on its own body and stride. `cameraTracks()` films it with push-ins, cuts, shakes and follows. The cartoon zip (`{ do: 'zip' }`) has the legs wheel in place before it is gone. Figures can act on code, Animator vs Animation style: `codePanel()` lays a listing out so every line and word is a place in the scene, and beats leap onto lines, point at them and swipe them away (`{ do: 'swipe', target: code.line(7) }`), with the line wiped, knocked off the panel or blurred out of focus on the frames the hand crosses it. Words come loose too: a figure grabs `var` and throws it, kicks another out of a loop, carries a stray `;` to where it belongs, pushes a word along its line (the text closing up behind it), and writes `mut` into a line by hand. A figure standing on a line rides it when a gap above closes (`code.ride()`). Code is one *surface*; `whiteboard()` is another, a board or chalkboard of texts and hand-drawn circles, boxes, underlines and arrows, so a figure can work through a lesson that is not code, `chart()` a third, bar, line, pie and donut charts whose bars a figure points at, highlights and stands on as they grow, with slices it pulls out or kicks loose as pieces, several series with a legend, and axis titles, and `propSurface()` makes any prop one, so a figure opens a car's door or switches a house's lights on, kicks a wheel loose (parts are pieces), and rides on the roof as the car lifts (anchors and parts are floors). Boards write in a handwriting font, bend arrows round what is in the way, and come as ruled paper too. In the editor, a 🧍 Character's **Beats** box compiles a story into its tracks, aimed at a ⌨ **Code** element's lines or a 📊 **Chart** element's bars (which carry the figure as they grow), and riders drive or pedal (`RIDING_POSES.driving`, `pedallingKeys`). Places on a surface have names (`line:7`, `token:4:Println`, `term:eq:+ 4`), and `surfaceScript()` takes a whole scene as JSON: beats aim at named places and say what the surface does in answer, at the moment the hand touches or lets go. Props give the story a world: cars, trucks, buses, tractors, carts, train carriages, bikes, motorbikes, trees, houses, a helicopter and a plane, furniture with the places a figure uses them at (a chair, a desk, a bed, a door, a wheelchair), a horse, dogs, cats, cows, goats, rabbits, squirrels and birds from songbirds to owls and parrots are 3D rigs drawn with the figures' pens, so they turn toward the camera and boil in pencil, or as line art beside stick figures. They act from beats through the same principles (they rock back before they go, dip on the stop, skid, bump, sway, take off and loop; animals walk, trot and gallop with their feet keeping pace, sit and jump; birds hop, peck, flap and fly up to a perch), with an exaggeration dial, and figures can ride them. `scenery()` puts a sky over it all (the sun and moon on their arcs, clouds on the wind, rain and snow, hills or a city) or a room with a window, with the hour, the clouds and the weather as tracks, and `scenePreset` gives park, street, office and home scenes. See [docs/props.md](docs/props.md). Your own behaviours are plain values: `defineAction()` (from beats or timed pose steps), `defineGait()`, and `persona()` for a recurring character's look, acting style, gait, usual face and stance. In the editor, a Character's **Acting** section acts its keyed poses in a style and adds gags, walks in a gait and lip-synced lines, with drawing on twos as a timeline setting. Characters come in builds (slim, kid, broad, curvy, stocky), and the v2 human has its own line of action, gaits and gags, posed in 3D so they read from every view. It also adds speed lines from earlier frames (`drawStickSmear()`), dust puffs, impact stars, and drawing on twos for video (`drawingRate`). Output is plain keyframes. See [docs/acting.md](docs/acting.md)
71
+ - **Cartoon acting** - `actTracks()` turns the same key poses into acted motion: wind-ups, overshoot that settles or wobbles, joints that overlap (hips lead, wrists drag), eyes that dart ahead and blink on head turns, moving holds and jump squash, in `full`, `snappy` or `limited` styles. Gags come as data (`gag('take')`, double take, wind-up, tremble). A line of action (`bend`) curves the spine, and gaits have personality (bouncy, double bounce, sneak, strut, tired, run: airborne with the legs apart, landing on a bent knee), with arms that hang plumb however far the body leans. Lip-sync works from text, Latin or Devanagari. `scriptTracks()` compiles a story written as beats (`{ do: 'walk', to: 640 }`, `{ do: 'take' }`, `{ do: 'say', say: '…' }`) into all of it, and `characterScript()` compiles the same beats for a v2 character from the cast, on its own body and stride. `cameraTracks()` films it with push-ins, cuts, shakes and follows. The cartoon zip (`{ do: 'zip' }`) has the legs wheel in place before it is gone. Figures can act on code, Animator vs Animation style: `codePanel()` lays a listing out so every line and word is a place in the scene, and beats leap onto lines, point at them and swipe them away (`{ do: 'swipe', target: code.line(7) }`), with the line wiped, knocked off the panel or blurred out of focus on the frames the hand crosses it. Words come loose too: a figure grabs `var` and throws it, kicks another out of a loop, carries a stray `;` to where it belongs, pushes a word along its line (the text closing up behind it), and writes `mut` into a line by hand. A figure standing on a line rides it when a gap above closes (`code.ride()`). Code is one *surface*; `whiteboard()` is another, a board or chalkboard of texts and hand-drawn circles, boxes, underlines and arrows, so a figure can work through a lesson that is not code, `chart()` a third, bar, line, pie and donut charts whose bars a figure points at, highlights and stands on as they grow, with slices it pulls out or kicks loose as pieces, several series with a legend, and axis titles, and `propSurface()` makes any prop one, so a figure opens a car's door or switches a house's lights on, kicks a wheel loose (parts are pieces), and rides on the roof as the car lifts (anchors and parts are floors). Boards write in a handwriting font, bend arrows round what is in the way, and come as ruled paper too. In the editor, a 🧍 Character's **Beats** box compiles a story into its tracks, aimed at a ⌨ **Code** element's lines or a 📊 **Chart** element's bars (which carry the figure as they grow), and riders drive or pedal (`RIDING_POSES.driving`, `pedallingKeys`). Places on a surface have names (`line:7`, `token:4:Println`, `term:eq:+ 4`), and `surfaceScript()` takes a whole scene as JSON: beats aim at named places and say what the surface does in answer, at the moment the hand touches or lets go. Props give the story a world: cars, trucks, buses, tractors, carts, train carriages, bikes, motorbikes, trees, houses, a helicopter and a plane, furniture with the places a figure uses them at (a chair, a desk, a bed, a door, a wheelchair), a horse, dogs, cats, cows, goats, rabbits, squirrels and birds from songbirds to owls and parrots are 3D rigs drawn with the figures' pens, so they turn toward the camera and boil in pencil, or as line art beside stick figures. They act from beats through the same principles (they rock back before they go, dip on the stop, skid, bump, sway, take off and loop; animals walk, trot and gallop with their feet keeping pace, sit and jump; birds hop, peck, flap and fly up to a perch), with an exaggeration dial, and figures can ride them. `scenery()` puts a sky over it all (the sun and moon on their arcs, clouds on the wind, rain and snow, hills or a city) or a room with a window, with the hour, the clouds and the weather as tracks, and `scenePreset` gives park, street, office and home scenes. See [docs/props.md](docs/props.md). Your own behaviours are plain values: `defineAction()` (from beats or timed pose steps), `defineGait()`, and `persona()` for a recurring character's look, acting style, gait, usual face and stance. In the editor, a Character's **Acting** section acts its keyed poses in a style and adds gags, walks in a gait and lip-synced lines, with drawing on twos as a timeline setting. Characters come in builds (slim, kid, broad, curvy, stocky), and the v2 human has its own line of action, gaits and gags, posed in 3D so they read from every view. It also adds speed lines from earlier frames (`drawStickSmear()`), dust puffs, impact stars, and drawing on twos for video (`drawingRate`). Output is plain keyframes. See [docs/acting.md](docs/acting.md)
72
72
  - **Pencil story example** - `examples/pencil-story-hindi/index.html` tells a short Hindi story (प्यासा राहगीर, the thirsty traveller) Pencilmation-style with the browser bundle alone: the hand draws the scene and writes the narration, then rubs out the pot
73
73
  - **Captions** - `toSRT()` / `toWebVTT()` from narration cues or from a timeline's markers
74
74
 
@@ -302,7 +302,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
302
302
  itself.
303
303
 
304
304
  ```html
305
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.123.0/cdn/tinyfly.iife.js"></script>
305
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.0/cdn/tinyfly.iife.js"></script>
306
306
  <script>
307
307
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
308
308
 
@@ -339,7 +339,7 @@ A teaching figure needs no code at all:
339
339
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
340
340
  <figcaption>Appending to a full slice</figcaption>
341
341
  </figure>
342
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.123.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
342
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
343
343
  ```
344
344
 
345
345
  See [Teaching Animations](docs/teaching.md).
@@ -438,7 +438,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
438
438
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
439
439
  </div>
440
440
 
441
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.123.0/cdn/tinyfly-player.iife.js"></script>
441
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.0/cdn/tinyfly-player.iife.js"></script>
442
442
  <script>
443
443
  tinyfly.play('#animation', './animation.json', { loop: -1 })
444
444
  </script>
@@ -547,7 +547,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
547
547
  <svg viewBox="0 0 720 200">…</svg>
548
548
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
549
549
  </figure>
550
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.123.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
550
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
551
551
  ```
552
552
 
553
553
  ### Audio / Video Sync
package/docs/acting.md CHANGED
@@ -172,7 +172,8 @@ shoots up and curls on landing. At 0 the figure is drawn exactly as before.
172
172
  How a figure walks is data: `GAITS` has `walk` (the plain walk, the same as
173
173
  `walkPose()`), `bouncy`, `doubleBounce` (two bobs a step), `sneak` (tiptoe in
174
174
  a crouch, paws up), `strut` (chest out), `tired` (slumped and dragging) and
175
- `run` (knees high, arms pumping, off the ground between steps).
175
+ `run` (knees high, arms pumping, in the air with the legs apart and landing
176
+ on a bent knee as they pass).
176
177
 
177
178
  ```js
178
179
  gaitPose('sneak', phase, base) // a pose at a phase of the cycle
@@ -181,8 +182,12 @@ gaitStrideLength('sneak', height) // ground per cycle, so feet stay plante
181
182
 
182
183
  A gait is a handful of numbers (`swing`, `knee`, `arm`, `elbow`, `forearm`,
183
184
  `shoulder`, `lean`, `bend`, `headTilt`, `bounce`, `bounces`, `squash`,
184
- `crouch`, `tiptoe`, `sway`), so you can write your own and pass it in place of
185
- a name. On a `stickFigureTarget` the `gait` prop picks one, and a string track
185
+ `crouch`, `tiptoe`, `sway`, `flight`, `give`), so you can write your own and
186
+ pass it in place of a name. `flight: true` puts the bounce's peak where the
187
+ legs are furthest apart (a run) instead of where they pass (a walk), and
188
+ `give` (degrees) bends the knee of the leg carrying the weight. Swinging arms
189
+ hang plumb however far the gait leans, so `shoulder` (paws held up) is
190
+ measured from the vertical. On a `stickFigureTarget` the `gait` prop picks one, and a string track
186
191
  switches it: `{ property: 'gait', keyframes: [{ time: 0, value: 'walk' }, { time: 3000, value: 'run' }] }`.
187
192
 
188
193
  ## Lip-sync
@@ -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.123.0/cdn/tinyfly-player.iife.js`
1146
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.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.123.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.124.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.123.0/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.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.123.0/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.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
@@ -306,7 +306,10 @@ Write new actions with `defineAction()` (from beats, or as timed pose steps),
306
306
  new gaits with `defineGait()`, and characters with `persona()`. Pass them where
307
307
  they are used; `persona.describe()` and `capabilities(version, cast)` list them,
308
308
  and the checks accept them. See "Your own actions, gaits and personas" in
309
- `docs/acting.md`.
309
+ `docs/acting.md`. In a gait, swinging arms hang plumb whatever the `lean` and
310
+ `bend` (so `shoulder` is from the vertical); a run-like gait wants
311
+ `flight: true` (airborne with the legs apart, grounded as they pass) and a
312
+ knee `give` of 20–30 so it lands on a bent knee.
310
313
 
311
314
  ## 2. Ask a target what it can do
312
315
 
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.123.0/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.123.0/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.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.123.0/cdn/tinyfly-math.iife.js" data-tinyfly-auto></script>
261
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.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.123.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.124.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