@algorisys/tinyfly 0.106.1 → 0.107.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
@@ -54,7 +54,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
54
54
  - **Code-drawn targets** - A `custom` canvas target draws with code (characters, charts, props) while the timeline animates its position, opacity and its own `props`, so drawing stays code and timing stays JSON
55
55
  - **Immediate mode too** - A scene's `background` and `draw(ctx, { time })` functions paint each frame directly, Cairo/Processing-style, and mix freely with timeline targets
56
56
  - **Timing from narration** - `planNarration()` lays spoken lines out from their clip lengths (lead, gap, tail) into cues, scene spans and markers; `voiceNarration()` measures recorded clips with ffmpeg and writes the sample-aligned narration WAV
57
- - **Characters** - A poseable stick figure (`@algorisys/tinyfly/characters`): named poses, facial expressions (brows, eyes that widen, close and look around, mouth shapes), squash and stretch, rubber-hose limbs, blending, walk cycles and talking, all driven by timeline tracks. **Characters v2**: one skeleton in 3D drawn flat, turning front to side to back, resting on whatever touches the ground, reaching for points, in clean, pencil or silhouette looks, and a 🧍 Character element in the editor you pose and keyframe. **Character appearance**: 34 hairstyles, 20 facial-hair styles, glasses, hats and ears as plain data on the head (they turn with it through all eight views), builds from toddler to tall, a recurring cast (`castMember`), 30 expressions with blush, tears and sweat, and hair that swings after a turn or a run and settles (`hairFollowTracks` keys the lag from the character's own tracks, so drawing stays stateless); four-legged animals' ears lay back on a run the way their tails already trail. Clothes are data too (`outfit.over`: an apron, a lab coat, a hoodie, a cardigan, overalls, a sari; boots), a mouth opens on teeth and a tongue, feet come in shapes, two people hug and help each other up (`embrace`, `helpUp`), and a cane in the hand or a wheelchair to ride are accessories any character can have, not part of an age ([guide](docs/character-appearance.md))
57
+ - **Characters** - A poseable stick figure (`@algorisys/tinyfly/characters`): named poses, facial expressions (brows, eyes that widen, close and look around, mouth shapes), squash and stretch, rubber-hose limbs, blending, walk cycles and talking, all driven by timeline tracks. **Characters v2**: one skeleton in 3D drawn flat, turning front to side to back, resting on whatever touches the ground, reaching for points, in clean, pencil or silhouette looks, and a 🧍 Character element in the editor you pose and keyframe. **Character appearance**: 41 hairstyles, including soft sweeps, flowing bobs and cascading waves with scalp-attached curved locks and individual flexibility, 20 facial-hair styles, glasses, hats and ears as plain data on the head (they turn with it through all eight views), builds from toddler to tall, a recurring cast (`castMember`), 30 expressions with blush, tears and sweat, and hair that swings after a turn or a run and settles (`hairFollowTracks` keys the lag from the character's own tracks, so drawing stays stateless); four-legged animals' ears lay back on a run the way their tails already trail. Clothes are data too (`outfit.over`: an apron, a lab coat, a hoodie, a cardigan, overalls, a sari; boots), a mouth opens on teeth and a tongue, feet come in shapes, two people hug and help each other up (`embrace`, `helpUp`), and a cane in the hand or a wheelchair to ride are accessories any character can have, not part of an age ([guide](docs/character-appearance.md))
58
58
  - **Dance and flips** - The stick figure dances disco, hip hop, breaking toprock, jazz, K-pop, Bollywood, Bhangra, Bharatanatyam (with mudras), the Charleston, tap (foot strikes as data, for tap sounds) and popping (side glide, moonwalk, forward glide, which travel with the planted foot staying put), and does front, back, layout, scissor and side flips, cartwheels, back handsprings, split leaps, toe touches and full splits. Wrists, ankles, foot turn-out, whole-body `spin` and `rise` are pose fields; moves are keyed in beats, so any tempo plays them; styles, grooves and routines are plain JSON (`danceFrame()`, `danceTracks()`, `flipPose()`, `flipTracks()`). In the editor a 🧍 Character dances from the playhead, in time with the music: an Audio element's tempo is detected (`detectTempo()`) or tapped, the timeline shows its beats and bars, and keyframes snap to them. Native v2 garba (two/three clap) and dandiya add body-local poses, circle formations with planted toes, paired stick-tip contacts, and timed full spins (`humanDanceFrame`, `danceCircleTracks`, `meetDandiya`, `characterScript3D`). Sparse custom keys keep numeric hand and pose values through JSON playback; rolled circles preserve native yaw-before-roll and foot grounding. Foot IK preserves authored hip turn-out for ankle and toe plants. Scripted dance entry preserves relaxed or explicitly posed hands through preceding holds. Script action boundaries retain preceding easing; festive examples solve contacts with their rendered body options. See [docs/dance.md](docs/dance.md)
59
59
  - **Maps** - Animated maps on OpenStreetMap tiles or an offline world outline (also in pencil): the camera flies in, pins drop, routes draw themselves while a marker travels them; a 🗺 Map element in the editor with a one-click trip
60
60
  - **Pencil sketch style** - Hand-drawn strokes with line boil (`sketch` style, `sketchPen`) for a pencil-test, Pencilmation-like look, on the stick figure and on canvas rect / circle / line / path shapes (also from the editor's Properties panel); a `drawOn` track draws any of those shapes on; the wobble is seeded by time, so renders stay deterministic
@@ -157,6 +157,19 @@ stick figure also supports `style.armLength` (default `1`).
157
157
  Clothed characters keep their upper legs behind shirt hems through turns and
158
158
  moving poses; shared garments follow the same order in 2D and camera views.
159
159
 
160
+ The [Flowing Cartoon Hair](https://tinyfly.app/examples/live-flowing-hair)
161
+ example compares `softSweep`, `flowingBob` and `cascadingWaves`: curved locks
162
+ fit the scalp and flex after quick head turns, then settle. Choose a face type
163
+ and hairstyle; the selected combination is highlighted in the animation and
164
+ shown in eight resting views. Compare simple and expressive round faces,
165
+ soft angular features with rounded cheeks and a fuller chin, broad jaws and
166
+ older expressive faces. Change colours
167
+ and drawing looks, or use the same styles with
168
+ `characterScript` and `hairFollowTracks` to act out a story.
169
+ Follow-through keeps lock centers and ribbon edges outside the skull while
170
+ roots stay pinned and free hanging tips retain their motion. Scalp-relative
171
+ clearance stays continuous even when motion would collapse a lock center.
172
+
160
173
  Every catalog example has an **Open full page** action. It opens a shareable
161
174
  `/examples/<id>/full` URL in a new tab, with the animation and its controls
162
175
  filling the page. [Open the manga example full page](https://tinyfly.app/examples/live-manga-cast/full).
@@ -261,7 +274,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
261
274
  itself.
262
275
 
263
276
  ```html
264
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.106.1/cdn/tinyfly.iife.js"></script>
277
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly.iife.js"></script>
265
278
  <script>
266
279
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
267
280
 
@@ -297,7 +310,7 @@ A teaching figure needs no code at all:
297
310
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
298
311
  <figcaption>Appending to a full slice</figcaption>
299
312
  </figure>
300
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.106.1/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
313
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
301
314
  ```
302
315
 
303
316
  See [Teaching Animations](docs/teaching.md).
@@ -396,7 +409,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
396
409
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
397
410
  </div>
398
411
 
399
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.106.1/cdn/tinyfly-player.iife.js"></script>
412
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly-player.iife.js"></script>
400
413
  <script>
401
414
  tinyfly.play('#animation', './animation.json', { loop: -1 })
402
415
  </script>
@@ -505,7 +518,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
505
518
  <svg viewBox="0 0 720 200">…</svg>
506
519
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
507
520
  </figure>
508
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.106.1/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
521
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
509
522
  ```
510
523
 
511
524
  ### Audio / Video Sync
@@ -97,6 +97,11 @@ Medium and long hair: `pixie`, `bob`, `longBob`, `wavyBob`, `shoulderStraight`,
97
97
  `lowPonytail`, `highPonytail`, `ponytail`, `sidePonytail`, `topBun`, `lowBun`,
98
98
  `singleBraid`, `twinBraids`, `braids`.
99
99
 
100
+ Flowing cartoon hair: `softSweep`, `flowingBob`, `cascadingWaves`. These use
101
+ broad curved locks over a fitted scalp cap, with soft tapered ends and gentle
102
+ asymmetry. The bob and long waves include a narrowing supporting mass so the
103
+ locks overlap without gaps. Each description serves every head angle.
104
+
100
105
  Every style is the same few fields (`resolveHair(spec)` fills them all in):
101
106
 
102
107
  | Field | Meaning |
@@ -113,16 +118,45 @@ Every style is the same few fields (`resolveHair(spec)` fills them all in):
113
118
  | `part`, `strands` | A parting (degrees round from the middle of the face) and the detail lines: `none`, `part`, `sweep`, `combed`, `hanging`, `thin` |
114
119
  | `fill` | `solid`, or `stipple` (close-cropped: dots on the scalp) |
115
120
  | `ties` | Ponytails, buns and braids: `{ kind: 'ponytail' \| 'bun' \| 'braid', at: 'top' \| 'high' \| 'low' \| 'left' \| 'right', length?, size? }` |
121
+ | `locks` | Curved sections: `{ path, width, follow? }`; `width` is in head radii; `follow` scales their flex (default 1, 0 pins a lock) |
122
+ | `fall` | Hanging mass: `{ taper, wave }`, narrowing toward the ends (0..1 head radii) and a soft uneven hem (nonnegative head radii) |
123
+ | `shine` | Soft highlight opacity on the locks, 0..1 (default 0); drawn in the clean look |
116
124
  | `coversEars` | The hair hides the ears |
117
125
 
118
126
  A style stays a starting point: any style suits anyone.
119
127
 
128
+ A lock's `path` has a root, two controls and a tip for a cubic curve; append
129
+ groups of three points for additional segments. Each point is
130
+ `{ around, up, lift? }`: `around` is degrees from the face toward the character's
131
+ left, `up` is head radii from the centre (at most 1), and nonnegative `lift`
132
+ adds distance outside the cap. The root must have `up` between 0 and 1 and no
133
+ extra lift. Sweeps follow the scalp rather than cutting through the skull.
134
+ Use continuous angles across the back, such as 160, 190, 220. Invalid lock
135
+ paths, widths, flexibility, shine and fall values throw during `resolveHair`.
136
+
137
+ ```js
138
+ const hair = resolveHair({ style: 'cascadingWaves', color: '#985b32' })
139
+ // Edit the resolved data; presets and other characters keep their own paths.
140
+ hair.locks[0].follow = 0.65
141
+ character({ hair })
142
+ // Remove the sculpted locks, keeping the cap and supporting mass:
143
+ character({ hair: { style: 'flowingBob', locks: [], shine: 0 } })
144
+ ```
145
+
146
+ `length` changes the supporting mass; edit lock path points to change their
147
+ individual lengths and curls. Public types: `HairLock`, `HairLockPoint`.
148
+ See the **Flowing Cartoon Hair** example and the
149
+ [eight-view reference sheet](model-sheet/flowing-hair.png).
150
+
120
151
  ## Hair in motion
121
152
 
122
153
  Hair that hangs (long hair, ponytails, braids) lags behind the head: it swings
123
154
  round after a turn, streams back on a run, drops on a jump and lifts on the
124
155
  landing. The roots stay on the head; the ends move, more the further they hang.
125
- Short hair, buns, beards and hats stay put.
156
+ Ordinary short hair, buns, beards and hats stay put. Flowing locks also flex,
157
+ including the short `softSweep`: their roots remain fixed while their ends
158
+ respond by each lock's `follow` amount. The presets use smaller amounts on
159
+ the fringe and larger, varied amounts on the hanging locks.
126
160
 
127
161
  The lag is three pose fields, so it keys, saves and mirrors like any other:
128
162
 
@@ -324,6 +358,10 @@ const hero = character(castMember('mangaYoungMan', 300, {
324
358
  projected 3D tapered head, following yaw, nod and roll. `jawWidth` is the
325
359
  half-width at the jaw (clamped to 0.55–0.95 head radii, default 0.74);
326
360
  `chinWidth` is the half-width just above the chin (0.03–0.35, default 0.14).
361
+ `jawRoundness` softens angular cheek and chin corners (0–1, default 0 keeps
362
+ the sharp outline). The Flowing Cartoon Hair demo's soft angular face uses
363
+ `jawWidth: 0.8`, `chinWidth: 0.28` and `jawRoundness: 1` for a fuller,
364
+ rounded chin. Behind-head hair, ears and beards clip to this same outline.
327
365
  `shape: 'round'` is the original default. The underlying rig and contact
328
366
  geometry retain their original head bounds; solid mesh characters retain
329
367
  their existing mesh head.
@@ -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.106.1/cdn/tinyfly-player.iife.js`
1146
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.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
@@ -743,7 +743,7 @@ For simple website embedding without a build system.
743
743
  </html>
744
744
  ```
745
745
 
746
- 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.106.1/cdn/tinyfly-player.iife.js`.
746
+ 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.107.1/cdn/tinyfly-player.iife.js`.
747
747
 
748
748
  ---
749
749
 
@@ -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.106.1/cdn/tinyfly.iife.js"></script>
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.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.106.1/cdn/tinyfly.iife.js"></script>
77
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.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
@@ -113,8 +113,15 @@ and the close-up fields `pupil`, `lid` and `bulge`, so any face goes with any
113
113
  action or view; `drawCharacterHead(ctx, who, pose, { x, y, radius })` draws
114
114
  just the head big, and `face: { nose, inPupil }` adds a nose and a drawing in
115
115
  the pupils. Hair and hats turn with the head:
116
- don't draw a different hairstyle per view. Hanging hair swings on its own:
117
- after the character's tracks add `hairFollowTracks(target, tracks, who)` (or,
116
+ don't draw a different hairstyle per view.
117
+ `softSweep`, `flowingBob` and `cascadingWaves` provide flowing cartoon hair
118
+ with editable cubic `locks: [{ path, width, follow? }]`. Each path is a root
119
+ plus groups of three `{ around, up, lift? }` points (degrees around the head,
120
+ head radii up/out); the root has up 0..1 and lift 0. `follow: 0` pins a lock.
121
+ `length` changes the supporting mass; edit the path to change a lock's length.
122
+ These styles work with the same acting and story tracks as other characters.
123
+ Hanging hair and flexible locks, including short sweeps, follow motion through
124
+ the same API: after the character's tracks add `hairFollowTracks(target, tracks, who)` (or,
118
125
  posing per frame, `hairFollow` once and `hairMotionAt(keys, t)` each frame)
119
126
  rather than keying `hair.swing` by hand. Put things in hands with `holding`
120
127
  (`{ right: 'mug' }`, `{ both: 'parcel' }`; the pose field `held.both` lets go),
@@ -270,6 +277,7 @@ or link `llms-full.txt`.
270
277
 
271
278
  `MANGA_CAST` supplies four original young adult presets through `castMember`.
272
279
  `face.shape: 'angular'`, `jawWidth` and `chinWidth` shape the projected pen head;
280
+ `jawRoundness: 1` rounds cheek/chin corners (default `0` preserves sharp jaws).
273
281
  `eyeScale` and `eyeAspect` shape anime eyes. Hair and outfit overrides remain
274
282
  independent; spread the preset's face when changing one nested field.
275
283
  `mangaSpikes` / `mangaSweep` contain editable `hair.spikes` tufts as JSON
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.106.1/cdn/tinyfly.iife.js"></script>
18
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.106.1/cdn/tinyfly-maps.iife.js"></script>
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.1/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.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/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.106.1/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
28
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.107.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