@algorisys/tinyfly 0.102.0 → 0.103.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/llms-full.txt CHANGED
@@ -204,7 +204,7 @@ with a GSAP-style call (durations are in seconds here):
204
204
  ```html
205
205
  <div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
206
206
 
207
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
207
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
208
208
  <script>
209
209
  tinyfly.to('.box', { x: 200, duration: 1 })
210
210
  </script>
@@ -412,7 +412,7 @@ Without a build step, the all-in-one bundle exposes the same functions on a
412
412
  global — `tinyfly.to()`, `tinyfly.timeline()` and so on:
413
413
 
414
414
  ```html
415
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
415
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
416
416
  <script>
417
417
  tinyfly.to('.box', { x: 200, duration: 1 })
418
418
  </script>
@@ -1586,8 +1586,29 @@ quickPlay({
1586
1586
 
1587
1587
  Practical examples for common animation patterns using the tinyfly API.
1588
1588
 
1589
+ ## Festive Garba and Dandiya
1590
+
1591
+ The [Navratri example](https://tinyfly.app/examples/live-festive-dandiya)
1592
+ appears under 3D, Showcase, Video and Algorisys. Six festively dressed dancers
1593
+ circle, strike larger decorated sticks with partners, and alternate half
1594
+ and full spins. Its code uses native character dance, world foot contacts,
1595
+ partner IK and the 3D canvas renderer. It loops every 24 seconds.
1596
+
1597
+ From this repository, build the libraries first with `npm run build:libs`.
1598
+ Video rendering needs `ffmpeg` on PATH and `@napi-rs/canvas`; see
1599
+ [Rendering Video from Code](video-rendering.md).
1600
+
1601
+ ```sh
1602
+ tinyfly video examples/headless-video/festive-dandiya.mjs --loop-check
1603
+ tinyfly video examples/headless-video/festive-dandiya.mjs -o festive-dandiya.mp4
1604
+ ```
1605
+
1606
+ Add an `audio` path to the headless scene to use your own music. The browser
1607
+ example runs without bundled audio.
1608
+
1589
1609
  ## Table of Contents
1590
1610
 
1611
+ - [Festive Garba and Dandiya](#festive-garba-and-dandiya)
1591
1612
  - [Basic: Fade In](#basic-fade-in)
1592
1613
  - [Multi-Property Animation](#multi-property-animation)
1593
1614
  - [Infinite Looping](#infinite-looping)
@@ -2278,7 +2299,7 @@ For simple website embedding without a build system.
2278
2299
  </html>
2279
2300
  ```
2280
2301
 
2281
- 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.102.0/cdn/tinyfly-player.iife.js`.
2302
+ 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.103.0/cdn/tinyfly-player.iife.js`.
2282
2303
 
2283
2304
  ---
2284
2305
 
@@ -4006,6 +4027,67 @@ Dance and flips (see [Dance and Flips](dance.md)): the pose fields `leftWrist`/`
4006
4027
  `DANCE_STYLES`, `DanceStyle`, `DanceMove`, `DanceKey`, `Groove`, `RoutineStep`, `MUDRAS`, `danceFrame()`, `dancePose()`, `danceTaps()`, `danceTravel()`, `danceTravelTrack()`, `stickToHuman()`, `mirrorHumanPose()`, `handProp()`, `DanceTap`, `TapName`, `routineBeats()`, `beatAt()`, `mirrorPose()`, `applyGroove()`, `danceStance()`, `dancer()`, `danceTracks()`, `bakeDanceTracks()`, `stickFigureTarget({ dance })` with the `beat` and `dancing` props, `resolveStickFrame()`;
4007
4028
  `FLIPS`, `Flip`, `FlipKey`, `flipPose()`, `flipTravel()`, `flipTracks()`; `POSES.sideSplit` and `POSES.frontSplit`.
4008
4029
 
4030
+ Native v2 dance APIs (also from `@algorisys/tinyfly/characters`):
4031
+
4032
+ | API | Result / options |
4033
+ |---|---|
4034
+ | `HUMAN_DANCES` | JSON routines: `garba`, `garbaThreeClap`, `dandiya`, each eight beats at 120 BPM |
4035
+ | `humanDanceFrame(style, beat, base?)` | `HumanDanceFrame`: `{ pose, contact: { side, start, weight }, strike }`; `style` is a `HumanDanceName` or custom `HumanDanceStyle`; `base` defaults to `HUMAN_REST` |
4036
+ | `humanDanceTracks(target, options)` | `Track[]`; `HumanDanceTrackOptions`: required `style`, optional `bpm`, `beats`, `start` (ms), `pose`, `samplesPerBeat` (default 16); tempo and length default to the style |
4037
+ | `danceCircleAt(beat, options)` | `DanceCircleMember[]`: `{ character, pose, position, heading, strike, planted }`; absolute beat, world position and heading in degrees |
4038
+ | `danceCircleTracks(targets, options)` | Scene `Track[]` on targets such as `stage/dancer`; requires `beats`, defaults to 120 BPM, `start: 0` ms and 16 samples per beat; an explicit `count` must equal `targets.length` |
4039
+ | `danceJoint(partner, chain, joint)` | World `Vec3` with grounding, yaw, roll and placement; wrist/ankle index 2, toe index 3 |
4040
+ | `plantDanceFoot(partner, side, worldPoint, point = 'toe')` | `DanceFootPlant`: partner with adjusted `pose`, `position` and `reached`; `point` is `toe` or `ankle`; apply both pose and position |
4041
+ | `meetDandiya(a, b, options?)` | `DandiyaMeeting`: `{ a, b, sticks, point, reached }`; `a`/`b` are poses, `sticks` a pair of `DandiyaStick` (`{ grip, tip }`); options `sideA`, `sideB` (default right), `point`, `length` (default 0.22 of the shorter height) |
4042
+
4043
+ `HumanDanceStyle` is `{ label, bpm, beats, keys: [{ beat, pose }], strikes }`.
4044
+ Keys must be nonempty, strictly ordered within `[0, beats)`, with finite pose
4045
+ values; strike beats must lie in that interval. Frames interpolate smoothly
4046
+ and wrap the beat into the loop. Missing fields fall back to base, human/hand
4047
+ rest, then zero. `turn` and `roll` are controlled by the caller. The contact
4048
+ pattern alternates left/right at each integer beat, starting left, with full
4049
+ stance through 0.6 of a beat and smooth release; custom keys do not change it.
4050
+ `strike` peaks at 1 and fades to 0 a quarter beat either side of a hit.
4051
+
4052
+ `DanceCircleOptions` requires a positive `radius`; other fields are `center`
4053
+ ([x,z], default [0,0]), `count` (default 8 in direct sampling), `beatsPerTurn`
4054
+ (32), `angle` (0 degrees, first dancer along +z), `direction` (1 clockwise
4055
+ viewed from above, or -1), `facing` (`inward` by default, `outward`, `tangent`
4056
+ or numeric degrees), `spins` (extra signed revolutions per orbit, default 0),
4057
+ `style` (`garba`), `character` (default height 1.7), `pose`, `plantFeet` (true).
4058
+ `DancePartner` is `{ character, pose, position: [x,y,z] }`, with placement,
4059
+ stick lengths and character height in the same units. Include world heading
4060
+ in `pose.turn` (quarter-turns) for contacts; object rotations are not read.
4061
+ `reached` uses a tolerance of 0.002 times the character height for foot plants
4062
+ or the shorter partner height for both stick tips.
4063
+
4064
+ The bakers return linear JSON keyframes and omit unchanged base/rest pose
4065
+ fields, so rendered targets need the same base pose. Pose tracks omit
4066
+ `turn`/`roll`; zero-roll circle tracks use `rotateY`, while rolled circles
4067
+ use pose `turn`/`roll` and `rotateY: 0`. Core bakers include hand fields;
4068
+ the editor filters them when hands are disabled. Partner IK and stick
4069
+ drawing are separate from the routines and circle bakes.
4070
+ See [Dance and Flips](dance.md#native-character-dances-circles-and-spins)
4071
+ for loop closure, contact handling and examples.
4072
+
4073
+ `characterScript3D(id, beats, options)` and `checkCharacterBeats3D(beats)`
4074
+ accept the `CharacterBeat3D` actions `spin` and `dance`:
4075
+
4076
+ | Action | Timing and behavior |
4077
+ |---|---|
4078
+ | `{ do: 'spin', turns?, for?, at? }` | Linear rotation from the current heading; signed/fractional `turns`, default 1, duration `for` in ms, default 1000 |
4079
+ | `{ do: 'dance', dance, bpm?, beats?, for?, at? }` | Named native routine, in place; defaults to style tempo and length; `for` alone derives beats at the BPM, while `beats` with `for` fits those beats into that duration |
4080
+ | `{ do: 'face', toward, for?, at? }` | Shortest turn to a heading (degrees) or [x,z]; explicit duration applies even without a turn |
4081
+
4082
+ Dance entry blends for `min(150 ms, duration / 4)` within the action,
4083
+ preserving prior holds and heading/roll. Missing hand fields start at
4084
+ `HAND_REST`; explicit zeros are retained. `at` must be finite and non-negative;
4085
+ `for`, `bpm`, `beats` must be finite and positive, and `turns` finite.
4086
+ See [3D Scenes](scene-3d.md#characters) for script options and result tracks.
4087
+ `capabilities().character.dances` lists native human dance names;
4088
+ `capabilities().stickFigure.dances` continues to map stick-figure styles to
4089
+ their move names.
4090
+
4009
4091
  ### Beats
4010
4092
 
4011
4093
  In the engine (`@algorisys/tinyfly`), pure:
@@ -5589,11 +5671,16 @@ tempo, then click **🕺 Dance from playhead**. Or pick a flip (front, back,
5589
5671
  layout, scissor, side flip, cartwheel, back handspring, split leap, toe touch)
5590
5672
  and click **🤸 Flip at playhead**. Both write ordinary keyframes from the
5591
5673
  playhead, a few a beat, keeping the character's keys before and after, so
5592
- every step can be edited afterwards. With cartoon gloves, dances key the hand
5674
+ every step can be edited afterwards. Native **Garba · two clap**, **Garba ·
5675
+ three clap** and **Dandiya · partner strikes** are also available as eight-beat
5676
+ whole routines. Their body-local steps keep the character's current view
5677
+ and existing turn/roll tracks, without mirroring the steps when facing left.
5678
+ Circle travel, planted-foot formations and paired stick contacts use the
5679
+ code APIs; the menu keys the dance on the spot. With cartoon gloves or natural hands, dances key the hand
5593
5680
  shapes too. When an audio element has a tempo, **Follow beat** (on by default)
5594
5681
  dances at the music's tempo and starts on the beat nearest the playhead. Popping's glides
5595
5682
  and moonwalk travel from where the character stands (an x track, the planted foot staying put); facing
5596
- left, a character dances the mirror image and glides the other way. Flips travel from where the character is (an x track), the way it
5683
+ left, converted stick-figure dances are mirrored and glide the other way. Flips travel from where the character is (an x track), the way it
5597
5684
  faces: pick the *Side* or *Side (left)* view first. Facing left, a front-on
5598
5685
  flip (a cartwheel, a side flip) is the mirror image: it steps off on the other
5599
5686
  foot and wheels left. See [Dance and Flips](dance.md).
@@ -5704,7 +5791,9 @@ red box. In the property panel:
5704
5791
  outline. **Lights**: colour and intensity.
5705
5792
  - **Characters**: a look (*Clean*, *Pencil*, *Silhouette* drawn by their pens
5706
5793
  in perspective, or *Solid*) and **🕺 Dance from playhead** with any dance
5707
- style.
5794
+ style, including native garba (two/three clap) and dandiya whole routines.
5795
+ The 3D Scene menu uses the style's default tempo and omits hand tracks;
5796
+ native styles keep the object's heading and pose turn/roll independent.
5708
5797
  - **Props**: which prop from the catalog (car, truck, bus, tractor, cart, train
5709
5798
  car, bike, motorbike, tree, house, helicopter, airplane, horse, dog, cat, cow,
5710
5799
  songbird, crow, chicken), its look (*Clean*, *Pencil*, *Silhouette*, or
@@ -6536,7 +6625,7 @@ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button.
6536
6625
  **Steps to embed:**
6537
6626
  1. Build the player: `npm run build:player`
6538
6627
  2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
6539
- `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-player.iife.js`
6628
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-player.iife.js`
6540
6629
  instead; see [Deployment](DEPLOYMENT.md))
6541
6630
  3. Copy the generated code into your HTML
6542
6631
  4. Adjust the script `src` path if needed
@@ -7707,7 +7796,7 @@ npx @algorisys/tinyfly capabilities --json # the same as data
7707
7796
  It lists the easings, track kinds, every property each canvas shape can
7708
7797
  animate (with units and ranges), the stick figure's joints, poses,
7709
7798
  expressions, gags, gaits, beat actions, dances, flips and hand shapes, the v2
7710
- character's poses, expressions, builds, hairstyles, facial hair, glasses,
7799
+ character's poses, native dances, expressions, builds, hairstyles, facial hair, glasses,
7711
7800
  hats and cast, the code panel's languages, every surface's anchors and
7712
7801
  edits (code panel, whiteboard, chart), camera shots and the teaching
7713
7802
  helpers. It is generated from the code, so it can't
@@ -7746,6 +7835,35 @@ tracks (`cameraMoveTracks`, `cameraHandheldTracks`), a mood from
7746
7835
  sound from `renderMix`; draw it with `depthBuffer: true` when shapes cross.
7747
7836
  See `docs/props.md` and `docs/scene-3d.md`.
7748
7837
 
7838
+ Native garba/dandiya use `humanDanceFrame(style, beat, base)` or
7839
+ `humanDanceTracks(target, { style, bpm, beats })`, keeping heading independent
7840
+ of local limb motion. `danceCircleAt` / `danceCircleTracks` coordinate a
7841
+ formation's x/z travel, facing and foot plants. Sparse clip fields use base,
7842
+ human/hand rest or zero defaults throughout the loop and JSON bakes.
7843
+ Contacts alternate left/right each integer beat, starting left, with stance
7844
+ through 0.6 of the beat; custom keys do not change this. For different
7845
+ footwork use `plantFeet: false` and your own `plantDanceFoot` contacts.
7846
+ Circle bakes require `beats` and default to 120 BPM (not the custom style's
7847
+ tempo); explicit `count` must match the targets. Render with the bake's base
7848
+ pose and build, since unchanged pose fields are omitted. Whole orbits and
7849
+ routines close only when the extra body spins also total whole revolutions.
7850
+ Zero-roll circle bakes use `rotateY`; with nonzero `pose.roll`, they use
7851
+ pose `turn` (quarter-turns), include roll, and set `rotateY: 0` to preserve
7852
+ yaw before roll and grounding. Supply roll when baking; apply all tracks
7853
+ together without adding heading twice. Apply both `pose` and
7854
+ `position` from `plantDanceFoot`; ankle/toe IK preserves authored `leg.*.rotate`
7855
+ hip turn-out. `meetDandiya` gives paired poses and 3D
7856
+ grip/tip segments with a `reached` flag. Build contact characters from the
7857
+ rendered dancers' options so body proportions, line width and hands match.
7858
+ Scripted dance entry and hand pose transitions use `HAND_REST` for missing
7859
+ hand fields, preserving relaxed hands during preceding holds and explicit zeros.
7860
+ Use `{ do: 'spin', turns: 2,
7861
+ for: 1500 }` for full rotations: `face` takes the shortest route, so facing
7862
+ 360° does not spin. A script dance stays in place; `for` alone derives its
7863
+ beat count at the BPM, and `beats` with `for` fits the beats into that duration.
7864
+ Stick geometry and paired IK are separate from native frames and circle
7865
+ bakes. See `docs/dance.md`.
7866
+
7749
7867
  ## Characters with a look
7750
7868
 
7751
7869
  A v2 character's appearance is plain options to `character()`, never drawing
@@ -7947,7 +8065,7 @@ path for all of that:
7947
8065
  </figure>
7948
8066
 
7949
8067
  <!-- once, anywhere on the page (a site-wide footer is fine) -->
7950
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
8068
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
7951
8069
  ```
7952
8070
 
7953
8071
  Every `[data-tinyfly-embed]` mounts when the page is ready, with no per-post
@@ -9219,8 +9337,8 @@ On a page with no build step, load the maps add-on after the browser bundle; it
9219
9337
  adds to the same `tinyfly` global:
9220
9338
 
9221
9339
  ```html
9222
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly.iife.js"></script>
9223
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.102.0/cdn/tinyfly-maps.iife.js"></script>
9340
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly.iife.js"></script>
9341
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.103.0/cdn/tinyfly-maps.iife.js"></script>
9224
9342
  ```
9225
9343
 
9226
9344
  It is a separate script because the offline world map it carries adds about
@@ -10607,6 +10725,154 @@ renders to video and syncs to music exactly.
10607
10725
 
10608
10726
  Try it on the Examples page: **Dance Floor (Characters)**.
10609
10727
 
10728
+ ## Native character dances, circles and spins
10729
+
10730
+ For v2 characters use `humanDanceFrame(style, beat, basePose)`, with
10731
+ `style` set to `garba`, `garbaThreeClap` or `dandiya`, or a custom `HumanDanceStyle`.
10732
+ These stylised eight-beat routines author limbs in the body's own 3D space,
10733
+ including weight shifts, knee lifts, clap preparation and recovery. `turn`
10734
+ and `roll` stay with the caller, so the same steps work from the front, back
10735
+ or either side. `HUMAN_DANCES` is plain JSON: copy a routine's `keys`,
10736
+ `strikes`, `beats`, `bpm` and `label` to customise it. Keys are ordered by beat,
10737
+ within `[0, beats)`, and loop back to the first key. Sparse keys use the full
10738
+ clip's field union at every beat: a missing value uses the caller's base pose,
10739
+ then the human or hand rest value, then zero for other fields. Both bakers
10740
+ preserve these numeric fields even when first authored at a later key.
10741
+ The frame also contains `contact: { side, start, weight }`: the support side,
10742
+ the absolute integer planting beat, and a weight that is 1 through stance
10743
+ and fades smoothly to 0 before the next beat. `strike` is 1 at a clap or
10744
+ stick-strike beat and fades linearly to 0 a quarter beat either side. Foot plants
10745
+ assume left/right alternation at each integer beat, starting with the left
10746
+ foot, and stance through 0.6 of each beat. Custom keys do not change this
10747
+ contact pattern. For hops, longer stances or reversed support, set
10748
+ `plantFeet: false` and supply your own contacts with `plantDanceFoot`.
10749
+
10750
+ ```js
10751
+ import { character, drawCharacter, humanDanceFrame, humanDanceTracks, danceCircleAt, danceCircleTracks } from '@algorisys/tinyfly/characters'
10752
+
10753
+ const who = character({ height: 220, hands: 'cartoon', handStyle: 'natural' })
10754
+ const frame = humanDanceFrame('garba', time * 120 / 60000, { turn: 2 })
10755
+ drawCharacter(ctx, who, frame.pose) // back view, without mirroring the step
10756
+
10757
+ const tracks = humanDanceTracks('dancer', { style: 'garba', bpm: 120, beats: 8 })
10758
+ // Ordinary JSON keyframes; turn/roll tracks can animate independently.
10759
+
10760
+ const members = danceCircleAt(time * 120 / 60000, {
10761
+ radius: 1.8, count: 8, beatsPerTurn: 32, facing: 'inward', style: 'garba',
10762
+ })
10763
+ // Each member: character, pose, position [x,y,z], heading (degrees), strike,
10764
+ // planted. Heading is already included in pose.turn for direct drawing.
10765
+
10766
+ const circleTracks = danceCircleTracks(['stage/a', 'stage/b'], {
10767
+ radius: 1.8, beatsPerTurn: 32, beats: 32, bpm: 120,
10768
+ })
10769
+ // Scene tracks: x/y/z, rotateY, and local pose fields; no doubled pose.turn.
10770
+ ```
10771
+
10772
+ `humanDanceTracks(target, { style, bpm?, beats?, start?, pose?, samplesPerBeat? })`
10773
+ defaults to the style's tempo and beat count, `start: 0` ms, `HUMAN_REST`
10774
+ and 16 samples per beat. It samples from beat 0 through `beats`, with
10775
+ linear JSON keys at `start + beat * 60000 / bpm`; between samples playback
10776
+ approximates the smoothly interpolated frame. It omits `turn`, `roll` and
10777
+ fields that stay at the supplied base/rest value. Give the target the same
10778
+ base pose, since omitted fields are not reset. Hand fields are included;
10779
+ use a hand rig to display them or filter `hand.*` tracks for dot hands.
10780
+
10781
+ Circle positions use `center: [x,z]`, `radius`, initial `angle` (degrees),
10782
+ `direction: 1 | -1`, and equal spacing. Facing can be `inward`, `outward`,
10783
+ `tangent`, or a fixed numeric heading. `spins` adds independent body turns
10784
+ per orbit, including negative or fractional turns. Defaults are
10785
+ `center: [0,0]`, `count: 8`, `beatsPerTurn: 32`, `angle: 0`, `direction: 1`
10786
+ (clockwise viewed from above), `facing: 'inward'`, `spins: 0`, `style: 'garba'`
10787
+ and `plantFeet: true`; `radius` must be positive. At angle 0 the first
10788
+ dancer stands along +z; heading 0 faces +z, 90 faces +x.
10789
+ Height and placement use the same units (default 1.7 metres).
10790
+ `danceCircleTracks(targets, options)` requires `beats`, takes its member
10791
+ count from `targets.length`, and defaults to 120 BPM, `start: 0` ms and
10792
+ 16 samples per beat, even when a custom style has a different tempo.
10793
+ Its linear keys omit unchanged base/rest pose fields but always include
10794
+ world placement; give the rendered characters the same base pose and build.
10795
+ With zero roll, circle bakes put heading in object `rotateY` (degrees) and
10796
+ omit pose `turn`; start with neutral object rotation and pose `turn: 0`.
10797
+ With a nonzero `pose.roll`, they instead bake heading into pose `turn`
10798
+ (quarter-turns), include the supplied `roll`, and write `rotateY: 0`. This
10799
+ keeps native yaw before roll, including its grounding and foot contacts.
10800
+ Apply these tracks together and do not add the same heading as object yaw.
10801
+ Set roll in the bake options so the contact solver uses that roll too.
10802
+ Use `character: who` for a custom build. Support toes are held at their
10803
+ planting point through the first 0.6 beat, then released smoothly;
10804
+ `plantFeet: false` disables this. `planted: false` also reports an unreachable
10805
+ plant, a releasing stance, or disabled planting. Keep travel per step within
10806
+ leg reach. To close a loop, use complete orbits and routines, an even number
10807
+ of beats for the alternating contacts, and a whole number of extra body
10808
+ revolutions (`spins * orbits`). Fractional spins can require multiple orbits
10809
+ to close. Run the video loop check for the whole scene.
10810
+
10811
+ For a custom path or pivot, `plantDanceFoot({ character, pose, position },
10812
+ side, worldPoint, 'toe' | 'ankle')` returns the adjusted **pose and position**
10813
+ and a `reached` flag. Apply both outputs: the vertical position correction
10814
+ transfers weight to the supporting leg. It does not translate sideways to
10815
+ hide an unreachable target. The default point is `toe`; `reached` means
10816
+ the joint is within 0.002 times the character height of the target.
10817
+ `danceJoint(partner, chain, joint)` reads a world-space joint with pose yaw,
10818
+ roll, grounding and position applied: arm index 2 is the wrist, leg index 2
10819
+ the ankle, and leg index 3 the toe. Include heading in `pose.turn`
10820
+ (quarter-turns); these contact helpers do not read scene object rotations.
10821
+ Foot IK preserves authored `leg.left.rotate` and
10822
+ `leg.right.rotate` hip turn-out when placing either ankle or toe, including
10823
+ straight-leg contacts at full reach.
10824
+
10825
+ For partner dandiya use `meetDandiya(a, b, { sideA, sideB, point, length })`,
10826
+ where each partner has `{ character, pose, position: [x,y,z] }`. Both grips
10827
+ and stick tips are solved in world space. It returns `a`/`b` poses, two
10828
+ `sticks` (`grip` → `tip` segments), the shared `point`, and `reached`. Defaults:
10829
+ right hands, chest-height contact, stick length 0.22 of the shorter height.
10830
+ The default point is halfway between the partners in x/z and at the higher
10831
+ position y plus 0.62 times the shorter height. `reached` means both tips
10832
+ are within 0.002 times that height of the point; inspect it before applying
10833
+ an unreachable solve. Neither partner's position changes. The returned
10834
+ poses set the selected hands to the `hold` shape. Dandiya frames and circle
10835
+ bakes supply choreography, not stick geometry or automatic partner IK;
10836
+ call `meetDandiya` and draw its segments yourself.
10837
+ Blend strike poses with `humanDanceFrame('dandiya', beat).pose` between hits,
10838
+ using its `strike` envelope; draw the returned sticks at each arm's depth.
10839
+ Construct the contact character from the same options as the rendered dancers,
10840
+ including height, head size, figure, limb proportions, line width and hands.
10841
+ The festive live and headless examples use `character(people[0])` so their
10842
+ solver and displayed bodies share the same geometry.
10843
+
10844
+ In a 3D beat script, use `{ do: 'dance', dance: 'garba', bpm: 120, beats: 8 }`
10845
+ and `{ do: 'spin', turns: 2, for: 1500 }`. Spin preserves the full signed
10846
+ rotation, unlike `face`, which deliberately chooses the shortest route.
10847
+ `spin` starts from the current heading, defaults to one positive revolution
10848
+ over 1000 ms, and turns at constant angular speed; negative and fractional
10849
+ `turns` are allowed. `dance` defaults to the style's BPM and one routine.
10850
+ With only `for`, its beat count is `for * bpm / 60000`; with both `beats`
10851
+ and `for`, that many beats are fitted into `for` ms, overriding the tempo.
10852
+ The script dances in place: use circle helpers for travel and foot plants.
10853
+ `at` must be finite and non-negative; `for`, `bpm` and `beats` must be
10854
+ finite and positive, and `turns` must be finite. Invalid beats are reported
10855
+ by `checkCharacterBeats3D` and rejected by `characterScript3D`.
10856
+ `face` honors an explicit `for` duration even when already facing the target.
10857
+ Scripted dances blend in for up to 150 ms within their duration, preserving
10858
+ a preceding hold, including relaxed hands. Missing hand fields use `HAND_REST`
10859
+ for both the start anchor and entry blend; explicit values, including zero,
10860
+ are preserved. Hand pose transitions use the same rest fallback.
10861
+ Unchanged action-start anchors preserve the preceding
10862
+ transition's endpoint easing; the next action keeps its own easing.
10863
+ Circle track `count`, when given, must match the target count.
10864
+ Garba, three-clap garba and dandiya are also in the editor's Character and
10865
+ 3D Scene dance menus. The Character menu follows the audio's beat grid.
10866
+ Native styles offer a whole routine, without individual moves; their tracks
10867
+ do not replace existing view or spin tracks. The Character menu keys hands
10868
+ only with Cartoon gloves or Natural hands. The 3D Scene menu uses the style's
10869
+ default tempo and omits hand tracks.
10870
+
10871
+ See `examples/headless-video/garba-circle.mjs` for a complete looping scene.
10872
+ The Examples page also includes **Navratri: Festive Garba & Dandiya**, with
10873
+ festive clothing, larger decorated sticks, partner strikes and half/full
10874
+ spins. Render `examples/headless-video/festive-dandiya.mjs` for its video.
10875
+
10610
10876
  ![Every dance style's moves and every flip](model-sheet/dance-and-flips.png)
10611
10877
 
10612
10878
  The sheet is `examples/headless-video/dance-sheet.mjs`.
@@ -10842,7 +11108,8 @@ move (or the whole routine) and a tempo, then **🕺 Dance from playhead**. Or
10842
11108
  pick a flip and **🤸 Flip at playhead**. Both write ordinary keyframes, a few
10843
11109
  a beat, and keep the character's keys before and after. Glides and the
10844
11110
  moonwalk also write an `x` track from where the character stands. A character
10845
- facing left (the *Side (left)* view) dances the mirror image (`mirrorHumanPose()`:
11111
+ using a converted stick-figure style and facing left (the *Side (left)* view)
11112
+ dances the mirror image (`mirrorHumanPose()`:
10846
11113
  sides swap, it turns, tips and rolls the other way) and glides the other way;
10847
11114
  it turns between 3 (side-on, facing left) and 4 (front-on), never round the
10848
11115
  back. With **Hands:
@@ -11242,7 +11509,8 @@ A character faces +z before any turn and stands on its object's ground: its
11242
11509
  lowest point at the object's y, so at y 0 it stands on a floor at y 0. Its
11243
11510
  pose fields are tracks on its object, next to `x`, `rotateY` and the rest:
11244
11511
  `stage/tum` `arm.right.spread`, `stage/tum` `turn`. Every dance and flip
11245
- plays in 3D: `stickToHuman(danceFrame(style, beat))` gives the pose, and
11512
+ plays in 3D: `const frame = danceFrame(style, beat)` followed by
11513
+ `stickToHuman(frame.pose, frame.hands)` gives the pose, and
11246
11514
  `mirrorHumanPose()` its mirror image for a partner. Its `turn`, `roll`,
11247
11515
  `lift` and ground contact behave as they do front-on; seen front-on through a
11248
11516
  flat camera, a character is exactly the 2D figure.
@@ -11250,6 +11518,25 @@ flat camera, a character is exactly the 2D figure.
11250
11518
  **Walking in metres.** `characterScript3D(id, beats, { scene, position, heading, height })`
11251
11519
  scripts a character in world metres, as `propScript3D` does props:
11252
11520
 
11521
+ It also accepts `{ do: 'spin', turns: 2, for: 1500 }` (signed full turns,
11522
+ linear angular motion) and `{ do: 'dance', dance: 'garba', bpm: 120, beats: 8 }`.
11523
+ `face` still takes the shortest turn and can use `for` to set its duration.
11524
+ An explicit duration is consumed even when no turn is needed. `spin`
11525
+ defaults to one revolution over 1000 ms; negative or fractional `turns`
11526
+ are allowed. A native `dance` stays in place, using the style's tempo and
11527
+ beat count by default. With only `for`, beats follow the BPM; with both
11528
+ `beats` and `for`, those beats are fitted into that duration.
11529
+ For circle formations with planted toes and independent facing/spins use
11530
+ `danceCircleTracks(['stage/a', 'stage/b'], { radius: 1.8, beatsPerTurn: 32,
11531
+ beats: 32, bpm: 120 })`. These write ordinary world-position, `rotateY` and
11532
+ native pose tracks. For nonzero `pose.roll`, heading uses pose `turn`
11533
+ (quarter-turns) with `rotateY: 0`, preserving native yaw before roll and
11534
+ grounding. Supply roll when baking and apply all returned tracks together.
11535
+ Use the same character build and base pose for baking and rendering; omitted
11536
+ base/rest fields are not reset. Partner stick contacts require `meetDandiya`
11537
+ and drawing its returned segments separately.
11538
+ See [Native character dances](dance.md#native-character-dances-circles-and-spins).
11539
+
11253
11540
  ```js
11254
11541
  import { characterScript3D } from '@algorisys/tinyfly/characters'
11255
11542
 
@@ -11881,6 +12168,8 @@ The project uses a separate OSS (Open Source Software) repository for public rel
11881
12168
  Files listed in `.ossignore` are excluded from OSS publishing:
11882
12169
  - `scripts/` - Internal publishing scripts
11883
12170
  - `CLAUDE.md` - Internal AI instructions
12171
+ - `.no-mistakes.yaml` - Internal release validation configuration (Codex reviewer,
12172
+ tests with two workers, and the TypeScript check)
11884
12173
 
11885
12174
  ### Publishing Process
11886
12175
 
@@ -13926,7 +14215,7 @@ magnet.addEventListener('pointerleave', () => {
13926
14215
 
13927
14216
  <!-- capabilities: generated from the library -->
13928
14217
 
13929
- # tinyfly capabilities (v0.102.0)
14218
+ # tinyfly capabilities (v0.103.0)
13930
14219
 
13931
14220
  Generated from the library itself: every name below is accepted, and names not listed are rejected (beat scripts, code panels and `checkTracks` say which name was probably meant).
13932
14221
 
@@ -14149,7 +14438,7 @@ A prop is a 3D rig of simple parts drawn with the characters’ pens (clean, pen
14149
14438
  - `horse() · dog() · cat() · cow()`: animals (quadruped(spec) makes your own): gaits with footfall patterns keyed in step with the distance, sit, jump, their calls, species actions
14150
14439
  - `songbird() · crow() · chicken()`: birds (bird(spec) makes your own): hop, walk, peck, flap, fly and land (a chicken flutters), their calls; wings fold and beat in rhythm
14151
14440
  - `{ kind: 'prop', prop: 'car', position, rotation, values } with loadScene3D(scene, { kinds: [characterObjects, propObjects] })`: props in 3D scenes, by preset name, seen in perspective by the scene camera; controls are tracks on the object
14152
- - `characterScript3D(id, beats, { scene, position?, heading?, height?, pose? })`: a v2 character in a 3D scene in world metres: gaits to [x, z] or through points (its walk phase keyed with the distance), face, hold, pose, gag; checkCharacterBeats3D checks the beats
14441
+ - `characterScript3D(id, beats, { scene, position?, heading?, height?, pose? })`: a v2 character in world metres: gaits, face (shortest turn), spin (signed turns and duration), dance (native style, bpm, beats), hold, pose, gag; checkCharacterBeats3D checks the beats
14153
14442
  - `propRide3D({ prop, propId, propTracks, scene, placement, anchor, riderId, pose, start, end, mount?, dismount? })`: a character riding a prop in a 3D scene: hips on a seat anchor (saddle, seat) as it moves, hopping on and off; RIDING_POSES.astride / .seated / .driving / .cycling / .wheeling (a wheelchair)
14154
14443
  - `propScript3D(id, prop, beats, { scene, position?, heading?, values? })`: props scripted in world metres for 3D scenes: moves to [x, z] or through points (wheels and strides keyed with the distance), face, hold, and their actions; checkPropBeats3D checks the beats
14155
14444
  - `propPreset(name, options?)`: a prop preset by name (did-you-mean on a wrong one)
@@ -14203,6 +14492,7 @@ Scenery: `scenery({ x, y, width, height, kind: sky | room, hour, clouds, wind, r
14203
14492
  ## Character (v2 human)
14204
14493
 
14205
14494
  Poses: `rest`, `wave`, `cheer`, `point`, `handsOnHips`, `think`, `shrug`, `sit`, `kneel`, `crouch`, `crawl`, `lieDown`, `sleep`, `stretch`, `sitFloor`, `carry`, `cane`, `lift`, `push`, `pull`, `drink`, `phone`, `read`, `type`. Expressions: `neutral`, `happy`, `joyful`, `sad`, `crying`, `surprised`, `shocked`, `angry`, `furious`, `worried`, `scared`, `confused`, `skeptical`, `thinking`, `sleepy`, `disgusted`, `smug`, `wink`, `laughing`, `afraid`, `bored`, `tired`, `embarrassed`, `proud`, `determined`, `affectionate`, `hurt`, `suspicious`, `relieved`, `excited`. Gags: `take`, `doubleTake`, `windUp`, `land`, `tremble`, `deflate`.
14495
+ Native dances: `garba`, `garbaThreeClap`, `dandiya`; `humanDanceFrame(style, beat, base)` keeps body heading independent; `humanDanceTracks(target, options)` bakes JSON pose tracks. `danceCircleAt(beat, { radius, count, beatsPerTurn, facing, spins })` gives a formation with planted toes; `danceCircleTracks(targets, options)` bakes scene tracks. `plantDanceFoot(partner, side, worldPoint)` returns pose AND position; `meetDandiya(a, b)` solves both stick tips to one shared world point and reports unreachable contacts.
14206
14496
 
14207
14497
  Appearance options of `character({ … })`, all plain data that turns with the head (see docs/character-appearance.md):
14208
14498
 
package/llms.txt CHANGED
@@ -13,47 +13,47 @@ Key facts:
13
13
  - For language models: read the capability catalog first (`npx @algorisys/tinyfly capabilities`, or the end of llms-full.txt). It is generated from the library, so every name in it (poses, expressions, gags, gaits, beat actions, canvas properties, code-panel edits) is accepted, and names not in it are rejected with the name probably meant. Check beat scripts with `npx @algorisys/tinyfly check beats.json`, tracks with `checkTracks(tracks, targets)`, and ask any target what it animates with `describeTarget(target)`. The npm package ships `docs/`, `llms.txt`, `llms-full.txt` and an agent skill (`skills/tinyfly/SKILL.md`); `docs/llm-guide.md` describes the workflow.
14
14
  - Source: https://github.com/algorisys-oss/tinyfly. License: MIT.
15
15
 
16
- All documentation and the interactive course in a single file: [llms-full.txt](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/llms-full.txt)
16
+ All documentation and the interactive course in a single file: [llms-full.txt](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/llms-full.txt)
17
17
 
18
18
  ## Start here
19
19
 
20
- - [Getting Started](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/getting-started.md): What tinyfly is, making a first animation in the editor, and using it from code, a script tag or the CDN.
21
- - [GSAP Compatibility](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/gsap-compat.md): The GSAP-style API (`live.to`, `tf.timeline`): supported vars, motion paths, morphSVG, text, inertia, Draggable, Flip, and where it differs from GSAP.
22
- - [Code Examples](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/examples.md): Recipes with the engine API: fades, loops, colour and bezier easing, loading JSON, canvas and SVG rendering, multi-scene sequences, motion paths and script-tag embeds.
23
- - [Building Animations with an LLM](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/llm-guide.md): For assistants and the people setting them up: read the capability catalog (`tinyfly capabilities`), ask targets what they animate (`describeTarget`), check beats and tracks with did-you-mean errors (`tinyfly check`, `checkTracks`), render stills to look at, and the agent skill shipped in the package.
20
+ - [Getting Started](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/getting-started.md): What tinyfly is, making a first animation in the editor, and using it from code, a script tag or the CDN.
21
+ - [GSAP Compatibility](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/gsap-compat.md): The GSAP-style API (`live.to`, `tf.timeline`): supported vars, motion paths, morphSVG, text, inertia, Draggable, Flip, and where it differs from GSAP.
22
+ - [Code Examples](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/examples.md): Recipes with the engine API: fades, loops, colour and bezier easing, loading JSON, canvas and SVG rendering, multi-scene sequences, motion paths and script-tag embeds; a festive garba/dandiya scene with partner contacts, circle travel and spins, also rendered to video.
23
+ - [Building Animations with an LLM](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/llm-guide.md): For assistants and the people setting them up: read the capability catalog (`tinyfly capabilities`), ask targets what they animate (`describeTarget`), check beats and tracks with did-you-mean errors (`tinyfly check`, `checkTracks`), render stills to look at, and the agent skill shipped in the package.
24
24
 
25
25
  ## Reference
26
26
 
27
- - [API Reference](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/api-reference.md): Every public engine, player and adapter API: Timeline, tracks, keyframes, easing, drivers, serialization and exports.
28
- - [File Format](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/file-format.md): The JSON animation format: timelines, every track kind, keyframes, easing and the project file — for generating or consuming animations.
27
+ - [API Reference](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/api-reference.md): Every public engine, player and adapter API: Timeline, tracks, keyframes, easing, drivers, serialization and exports.
28
+ - [File Format](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/file-format.md): The JSON animation format: timelines, every track kind, keyframes, easing and the project file — for generating or consuming animations.
29
29
 
30
30
  ## Editor features
31
31
 
32
- - [Editor Guide](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/editor-guide.md): Every panel and feature of the visual editor, from elements and keyframes to text and inertia tracks, preview and export.
33
- - [Shape Morphing](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/shape-morph.md): Tweening one path into another, including shapes with different point counts and several subpaths.
34
- - [Pen Tool](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/pen-tool.md): Drawing custom paths point by point with straight segments and bezier curves.
35
- - [Polygons & Stars](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/polygon-star.md): Parametric polygon and star shapes that stay editable while animating like any path.
36
- - [Grid & Snapping](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/grid-and-snapping.md): The grid overlay, snapping to grid, elements and artboard centre, and alignment guides.
37
- - [Onion Skinning](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/onion-skinning.md): Ghost frames before and after the playhead for judging arcs and easing.
38
- - [Sprite-sheet Export](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/sprite-sheet-export.md): Exporting frames as a PNG grid plus JSON metadata for game engines and canvas players.
32
+ - [Editor Guide](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/editor-guide.md): Every panel and feature of the visual editor, from elements and keyframes to text and inertia tracks, preview and export.
33
+ - [Shape Morphing](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/shape-morph.md): Tweening one path into another, including shapes with different point counts and several subpaths.
34
+ - [Pen Tool](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/pen-tool.md): Drawing custom paths point by point with straight segments and bezier curves.
35
+ - [Polygons & Stars](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/polygon-star.md): Parametric polygon and star shapes that stay editable while animating like any path.
36
+ - [Grid & Snapping](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/grid-and-snapping.md): The grid overlay, snapping to grid, elements and artboard centre, and alignment guides.
37
+ - [Onion Skinning](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/onion-skinning.md): Ghost frames before and after the playhead for judging arcs and easing.
38
+ - [Sprite-sheet Export](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/sprite-sheet-export.md): Exporting frames as a PNG grid plus JSON metadata for game engines and canvas players.
39
39
 
40
40
  ## Guides
41
41
 
42
- - [Scroll Animation](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/scroll-animation.md): Scroll-driven and play-when-visible animation with ScrollDriver and VisibilityDriver.
43
- - [Props: Everyday Objects with Behaviours](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/props.md): Cars, trucks, buses, tractors, carts, train carriages, bikes, motorbikes, trees, houses, a helicopter and a plane: 3D rigs drawn with the characters’ pens (clean, pencil) that turn toward the camera, with beats acted through the 12 principles (anticipation, squash and stretch, follow-through, an exaggeration dial), wheels that roll exactly, effects, and figures riding them.
44
- - [Teaching Animations](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/teaching.md): Step-through explanatory figures: markers, captions in several languages, the teaching player, step controls, one-script declarative embeds, tinyfly/teach diagram primitives, and validate / render for build pipelines.
45
- - [Rendering Video from Code](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/video-rendering.md): Rendering a scene to MP4 without a browser: `tinyfly video`, custom canvas targets drawn by code, timing from narration and recorded voice-over, the stick-figure character, SRT/WebVTT captions, stills, porting Cairo scripts, and a benchmark against pycairo.
46
- - [Animated Maps](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/maps.md): Maps that animate: a camera that flies in to a city, pins that drop in, routes that draw themselves while a marker travels them, on OpenStreetMap tiles or an offline world outline (also in pencil), in the browser and in headless video.
47
- - [Cartoon Hands](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/cartoon-hands.md): A hand you can pose: a palm and five fingers in 3D, posed by numbers (curls, thumb, spread, wrist turn), ready-made shapes from a fist to a pencil grip, left and right, four or five fingers, in clean, pencil and silhouette looks; the animator's hand and character gloves are built on it.
48
- - [Character Appearance](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/character-appearance.md): Hair (34 styles), facial hair (20), glasses, hats and ears for the v2 character as plain data on the head, so they turn with it through all eight views; builds (child, tall, short…), a recurring cast (castMember), expressions with blush, tears and sweat, everyday poses, held items (mug, phone, bags, umbrella, parcel) and two characters’ hands meeting (meetHands: handshake, high five, hand-over).
49
- - [Cartoon Acting](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/acting.md): actTracks(): the same key poses, acted: anticipation, overshoot and settle, overlapping joints, eyes that lead and blink, moving holds and jump squash, in full, snappy or limited styles; gags as data (take, double take, wind-up); a line of action (bend); gaits with personality; lip-sync from text (Latin and Devanagari); beat scripts compiled to acted tracks; your own actions (defineAction), gaits (defineGait) and personas (persona()); acting on code (codePanel lines and words as anchors: leap onto a line, point at it, swipe it away wiped, knocked off or blurred; grab, throw, kick, carry and drop words, push them along their line, write new text in by hand; ride a line as gaps close); camera shots (push in, cut, shake, follow); the cartoon zip; speed lines, dust puffs and impact stars; drawing on twos (a timeline setting); acting, gags, walks and lines in the editor.
50
- - [Dance and Flips](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/dance.md): The stick figure dances disco, hip hop, breaking, jazz, K-pop, Bollywood, Bhangra, Bharatanatyam (with mudras), the Charleston, tap (with tap sounds) and popping (side glide, moonwalk), and does front, back, layout and scissor flips, cartwheels, handsprings, split leaps and full splits: wrists, ankles, turn-out, spin and rise as pose fields; moves keyed in beats; styles, grooves and routines as plain data.
51
- - [3D Scenes](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/scene-3d.md): @algorisys/tinyfly/scene-3d: cameras, lights and meshes as JSON, in metres, animated by tracks at <scene>/<object> (cuts with activeCamera), drawn on a 2D canvas with flat, smooth or toon shading, ink outlines and fog, in browsers, Workers and Node (MP4 with tinyfly video); v2 characters in scenes, dancing, in their pen looks or as solid figures, seen by any camera.
52
- - [3D Transforms and Rotations](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/3d-rotations.md): CSS-style 3D for flat elements in every renderer (rotateX, rotateY, z, perspective, backface visibility; true perspective on Canvas and WebGL, matching CSS within a pixel), one documented transform order, the editor's 3D fields; smooth quaternion rotations with interpolation: "slerp"; the vec3, quat and mat4 helpers; format version 2.
53
- - [Extending tinyfly](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/extending.md): Writing a render adapter, animating any object with live and the ticker, custom and parametric eases, stagger offsets, adding a track kind, and contributing gallery examples.
54
- - [Deployment](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/docs/DEPLOYMENT.md): Building and hosting the editor, and serving the player bundles.
42
+ - [Scroll Animation](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/scroll-animation.md): Scroll-driven and play-when-visible animation with ScrollDriver and VisibilityDriver.
43
+ - [Props: Everyday Objects with Behaviours](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/props.md): Cars, trucks, buses, tractors, carts, train carriages, bikes, motorbikes, trees, houses, a helicopter and a plane: 3D rigs drawn with the characters’ pens (clean, pencil) that turn toward the camera, with beats acted through the 12 principles (anticipation, squash and stretch, follow-through, an exaggeration dial), wheels that roll exactly, effects, and figures riding them.
44
+ - [Teaching Animations](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/teaching.md): Step-through explanatory figures: markers, captions in several languages, the teaching player, step controls, one-script declarative embeds, tinyfly/teach diagram primitives, and validate / render for build pipelines.
45
+ - [Rendering Video from Code](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/video-rendering.md): Rendering a scene to MP4 without a browser: `tinyfly video`, custom canvas targets drawn by code, timing from narration and recorded voice-over, the stick-figure character, SRT/WebVTT captions, stills, porting Cairo scripts, and a benchmark against pycairo.
46
+ - [Animated Maps](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/maps.md): Maps that animate: a camera that flies in to a city, pins that drop in, routes that draw themselves while a marker travels them, on OpenStreetMap tiles or an offline world outline (also in pencil), in the browser and in headless video.
47
+ - [Cartoon Hands](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/cartoon-hands.md): A hand you can pose: a palm and five fingers in 3D, posed by numbers (curls, thumb, spread, wrist turn), ready-made shapes from a fist to a pencil grip, left and right, four or five fingers, in clean, pencil and silhouette looks; the animator's hand and character gloves are built on it.
48
+ - [Character Appearance](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/character-appearance.md): Hair (34 styles), facial hair (20), glasses, hats and ears for the v2 character as plain data on the head, so they turn with it through all eight views; builds (child, tall, short…), a recurring cast (castMember), expressions with blush, tears and sweat, everyday poses, held items (mug, phone, bags, umbrella, parcel) and two characters’ hands meeting (meetHands: handshake, high five, hand-over).
49
+ - [Cartoon Acting](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/acting.md): actTracks(): the same key poses, acted: anticipation, overshoot and settle, overlapping joints, eyes that lead and blink, moving holds and jump squash, in full, snappy or limited styles; gags as data (take, double take, wind-up); a line of action (bend); gaits with personality; lip-sync from text (Latin and Devanagari); beat scripts compiled to acted tracks; your own actions (defineAction), gaits (defineGait) and personas (persona()); acting on code (codePanel lines and words as anchors: leap onto a line, point at it, swipe it away wiped, knocked off or blurred; grab, throw, kick, carry and drop words, push them along their line, write new text in by hand; ride a line as gaps close); camera shots (push in, cut, shake, follow); the cartoon zip; speed lines, dust puffs and impact stars; drawing on twos (a timeline setting); acting, gags, walks and lines in the editor.
50
+ - [Dance and Flips](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/dance.md): The stick figure dances disco, hip hop, breaking, jazz, K-pop, Bollywood, Bhangra, Bharatanatyam (with mudras), the Charleston, tap and popping, and does flips, leaps and splits; native v2 garba (two/three clap) and dandiya add body-local routines, circle formations, world foot plants, paired stick-tip contacts and signed spins; JSON bakes, timing, contact limits and editor menus.
51
+ - [3D Scenes](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/scene-3d.md): @algorisys/tinyfly/scene-3d: cameras, lights and meshes as JSON, in metres, animated by tracks at <scene>/<object> (cuts with activeCamera), drawn on a 2D canvas with flat, smooth or toon shading, ink outlines and fog, in browsers, Workers and Node (MP4 with tinyfly video); v2 characters in pen or solid looks, scripted native dances, timed signed spins and circle formations with foot contacts.
52
+ - [3D Transforms and Rotations](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/3d-rotations.md): CSS-style 3D for flat elements in every renderer (rotateX, rotateY, z, perspective, backface visibility; true perspective on Canvas and WebGL, matching CSS within a pixel), one documented transform order, the editor's 3D fields; smooth quaternion rotations with interpolation: "slerp"; the vec3, quat and mat4 helpers; format version 2.
53
+ - [Extending tinyfly](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/extending.md): Writing a render adapter, animating any object with live and the ticker, custom and parametric eases, stagger offsets, adding a track kind, and contributing gallery examples.
54
+ - [Deployment](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/docs/DEPLOYMENT.md): Building and hosting the editor, and serving the player bundles.
55
55
 
56
56
  ## Optional
57
57
 
58
- - [README](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/README.md): Feature overview, project layout and development setup.
59
- - [Release notes](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.102.0/release-notes/README.md): What changed in each version.
58
+ - [README](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/README.md): Feature overview, project layout and development setup.
59
+ - [Release notes](https://raw.githubusercontent.com/algorisys-oss/tinyfly/v0.103.0/release-notes/README.md): What changed in each version.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@algorisys/tinyfly",
3
- "version": "0.102.0",
3
+ "version": "0.103.0",
4
4
  "type": "module",
5
5
  "description": "Lightweight, API-driven animation engine and editor. The engine is framework-agnostic and runs in browsers, Web Workers, and Node.",
6
6
  "license": "MIT",
@@ -56,6 +56,34 @@ names.
56
56
  surfaces). Places name items by id: declare them first (`items`, `data`).
57
57
  - A figure that starts on the right walking left needs `facing: -1` in the
58
58
  script options.
59
+ - For native garba or dandiya, use `humanDanceFrame(style, beat, base)` or
60
+ `humanDanceTracks(target, { style, bpm, beats })`; heading stays independent
61
+ of local limb motion. `danceCircleAt` / `danceCircleTracks` coordinate a
62
+ circle's travel, facing, spins and foot plants. Sparse custom keys use base,
63
+ human/hand rest or zero defaults across the loop. Contacts always alternate
64
+ left/right each integer beat, starting left, with stance through 0.6;
65
+ custom keys do not change this. Use `plantFeet: false` and your own
66
+ `plantDanceFoot` contacts for different footwork. Circle bakes require
67
+ `beats`, default to 120 BPM and reject `count` different from target count.
68
+ Render with the same base pose and build: unchanged pose fields are omitted.
69
+ Close whole orbits/routines with whole extra body revolutions too.
70
+ Zero-roll circle bakes
71
+ use `rotateY`; nonzero `pose.roll` keeps heading in pose `turn` (quarter-turns),
72
+ includes roll, and sets `rotateY: 0`, preserving yaw before roll and grounding.
73
+ Supply roll when baking and apply all tracks without adding heading twice.
74
+ Apply both pose and position
75
+ from `plantDanceFoot`; ankle/toe IK preserves authored `leg.*.rotate` hip turn-out.
76
+ `meetDandiya` gives paired strike poses and world-space
77
+ grip/tip segments, with unreachable contacts reported. Construct contact
78
+ characters from the rendered dancers' options to match proportions,
79
+ line width and hands. Scripted dance entry and hand pose transitions use
80
+ `HAND_REST` for missing hand fields, preserving relaxed hands through holds
81
+ and explicit zero values. In a 3D script use
82
+ `{ do: 'spin', turns: 2, for: 1500 }` for full revolutions: `face` takes the
83
+ shortest route, so facing 360° does not spin. A scripted dance stays in
84
+ place; `for` alone derives beats at the BPM, while `beats` with `for` fits
85
+ those beats into the duration. Stick drawing and paired IK are separate
86
+ from native frames and circle bakes. See `docs/dance.md`.
59
87
  - A figure changes a prop's state through `propSurface(propTarget(…))`
60
88
  (`switch` / `set` on `control:door`, `control:lights`; aim at `anchor:NAME`
61
89
  or `part:ID`). Walk figures on a prop's front line (a house's
@@ -1,12 +0,0 @@
1
- import type { Point } from './sketch';
2
- /**
3
- * Polyline helpers measured by length, so `progress` 0..1 means "this much of
4
- * the way along", whatever the spacing of the points. Drawing on, erasing and
5
- * the hand that follows a stroke all use them.
6
- */
7
- /** Total length of a polyline. */
8
- export declare function pathLength(points: Point[]): number;
9
- /** The start of a polyline, up to `progress` (0..1) of its length. */
10
- export declare function partialPath(points: Point[], progress: number): Point[];
11
- /** Where along a polyline `progress` (0..1) of its length is. */
12
- export declare function pointAlong(points: Point[], progress: number): Point;