@algorisys/tinyfly 0.91.0 → 0.93.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.
Files changed (63) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +466 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +123 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +2785 -1794
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6575 -5454
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +95 -0
  45. package/lib/types/characters/acting/hand-path.d.ts +32 -0
  46. package/lib/types/characters/acting/index.d.ts +2 -0
  47. package/lib/types/characters/acting/script.d.ts +66 -7
  48. package/lib/types/characters/capabilities.d.ts +50 -0
  49. package/lib/types/characters/code-panel.d.ts +201 -0
  50. package/lib/types/characters/figure-actions.d.ts +11 -0
  51. package/lib/types/characters/figure-props.d.ts +87 -0
  52. package/lib/types/characters/gaits.d.ts +8 -0
  53. package/lib/types/characters/index.d.ts +4 -0
  54. package/lib/types/characters/species/human-motion.d.ts +45 -0
  55. package/lib/types/characters/species/human.d.ts +2 -0
  56. package/lib/types/characters/stick-figure.d.ts +2 -0
  57. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  58. package/lib/types/engine/authoring/index.d.ts +1 -0
  59. package/llms-full.txt +12548 -0
  60. package/llms.txt +57 -0
  61. package/package.json +6 -2
  62. package/skills/tinyfly/SKILL.md +64 -0
  63. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,299 @@
1
+ # 3D Scenes
2
+
3
+ `@algorisys/tinyfly/scene-3d` draws real 3D scenes: cameras, lights and
4
+ meshes, in world space, seen through a perspective or orthographic camera. The
5
+ scene is plain JSON; its motion is ordinary timeline tracks. It draws on a 2D
6
+ canvas in the **stylized** look (flat, smooth or toon shading, ink outlines,
7
+ fog), in browsers, Web Workers and Node, so the same scene plays on a page and
8
+ renders to MP4 with `tinyfly video`. No WebGL, no GPU, no dependencies.
9
+
10
+ Try it on the Examples page: **3D Scene: Orbiting Camera** and **3D Scene:
11
+ Dancing Characters** (under **3D**).
12
+ The plan for what comes next (a WebGL renderer, glTF models, 3D characters,
13
+ the realistic look, films) is [3D support](3d-support-plan.md).
14
+
15
+ ```js
16
+ import { Timeline } from '@algorisys/tinyfly'
17
+ import { loadScene3D, drawScene3D } from '@algorisys/tinyfly/scene-3d'
18
+
19
+ const scene = loadScene3D({
20
+ id: 'stage',
21
+ camera: 'cam',
22
+ background: '#1e293b',
23
+ materials: { red: { color: '#ef4444', shading: 'toon', outline: { width: 2, color: '#0f172a' } } },
24
+ objects: [
25
+ { id: 'cam', kind: 'camera', projection: 'perspective', fov: 45, near: 0.1, far: 50, position: [0, 2, 6], lookAt: [0, 0, 0] },
26
+ { id: 'sun', kind: 'light', light: 'directional', color: '#ffffff', intensity: 0.9, position: [3, 5, 4] },
27
+ { id: 'box', kind: 'mesh', geometry: { type: 'box', size: [1, 1, 1] }, material: 'red' },
28
+ ],
29
+ })
30
+
31
+ const timeline = new Timeline({
32
+ id: 'spin',
33
+ tracks: [{ id: 'turn', target: 'stage/box', property: 'rotateY', keyframes: [{ time: 0, value: 0 }, { time: 2000, value: 360 }] }],
34
+ })
35
+
36
+ // Each frame:
37
+ drawScene3D(ctx, scene, timeline.getStateAtTime(time).values, { width: 800, height: 450 })
38
+ ```
39
+
40
+ On a page with no build step, load `tinyfly-scene-3d.iife.js` after
41
+ `tinyfly.iife.js`; it adds these functions to the same `tinyfly` global.
42
+
43
+ ## The scene
44
+
45
+ | | |
46
+ |---|---|
47
+ | Units | metres |
48
+ | Axes | right-handed: +x right, +y up, +z toward the default camera (a camera looks down its own -z) |
49
+ | Angles | degrees; Euler `rotation` in YXZ order (yaw, pitch, roll), or a `quaternion` `[x, y, z, w]` |
50
+ | Order | `objects` is an array: parents before children; ties in depth are broken by array order |
51
+
52
+ **Objects** share `id`, `position`, `rotation` or `quaternion`, `scale` (one
53
+ number or three), `parent` (an earlier object it moves with), `visible`, and
54
+ `layer` (below).
55
+
56
+ | `kind` | Fields |
57
+ |---|---|
58
+ | `group` | (just a transform: move several objects together, or carry a camera) |
59
+ | `mesh` | `geometry`, `material` (a key of `materials`) |
60
+ | `camera` | `projection: 'perspective'` with `fov` (vertical, degrees), or `'orthographic'` with `height` (metres); `near`, `far`; optional `lookAt: [x, y, z]` |
61
+ | `light` | `light: 'ambient' \| 'directional' \| 'point' \| 'spot'`, `color`, `intensity` (1 is full light); directional and spot shine from their position toward `target` (default the origin); point and spot fade to nothing at `range`; spot's cone is `angle` (half-angle, default 30°) |
62
+
63
+ **Geometry**: `box` (`size: [w, h, d]`), `sphere` (`radius`, `segments`),
64
+ `cylinder` and `cone` (`radius`, `height`, `segments`), `torus` (`radius` to
65
+ the tube's middle, `tube`, `segments`), `plane` (a floor: `size: [w, d]`
66
+ facing up, `segments` per side), and `extrude`: any SVG `path` made solid,
67
+ `depth` metres thick and scaled to `width` metres wide (default 1), with
68
+ `curveSegments` points per curve (default 12). Subpaths inside others are
69
+ holes (an "o", a ring); outlines inside holes are solid again. The path's y
70
+ (down) is flipped to 3D's y (up). All centred on the origin.
71
+
72
+ ```js
73
+ { id: 'star', kind: 'mesh', material: 'gold',
74
+ geometry: { type: 'extrude', path: 'M 50 0 L 61 35 L 98 35 L 68 57 L 79 91 L 50 70 L 21 91 L 32 57 L 2 35 L 39 35 Z', depth: 0.3, width: 1.4 } }
75
+ ```
76
+
77
+ **Materials**: `color`, `opacity`, `doubleSided`, and for the stylized look:
78
+
79
+ | `shading` | Looks |
80
+ |---|---|
81
+ | `unlit` | the colour as it is |
82
+ | `flat` | lit per face: faceted |
83
+ | `lambert` (default) | lit with smoothed normals: curved shapes read as round |
84
+ | `toon` | lit in `bands` steps (default 3) |
85
+
86
+ `outline: { width, color }` inks silhouettes, creases (edges sharper than 30°)
87
+ and open rims. `emissive` is light the surface gives off itself: it is added
88
+ after lighting, so the surface shows in the dark, in both renderers. Pair it
89
+ with a video's `bloom` (see [Rendering Video from Code](video-rendering.md#bloom))
90
+ for a neon glow: `{ color: '#000000', emissive: '#ff2bd6', shading: 'unlit' }`.
91
+ `roughness` and `metalness` are for the realistic look (three.js, a later
92
+ milestone); the stylized renderers ignore them, so one material serves both.
93
+
94
+ The scene can have `background` and `fog: { color, near, far }` (metres from
95
+ the camera). A scene with no lights gets a soft default (ambient plus a key
96
+ light from upper right).
97
+
98
+ ## Animating it
99
+
100
+ Tracks address objects as **`<sceneId>/<objectId>`**, so a 3D scene's tracks
101
+ live in the same timeline as everything else.
102
+
103
+ | Property | On | Value |
104
+ |---|---|---|
105
+ | `x`, `y`, `z` or `position` | any object | metres |
106
+ | `rotateX`, `rotateY`, `rotateZ` or `quaternion` | any object | degrees (YXZ), or `[x, y, z, w]` on a track with `interpolation: "slerp"` |
107
+ | `scale`, `scaleX`, `scaleY`, `scaleZ` | any object | |
108
+ | `visible` | any object | 0 or 1 (children hide with their parent) |
109
+ | `opacity` | meshes | 0..1, times the material's |
110
+ | `color` | meshes, lights | a colour, over the material's or light's |
111
+ | `intensity`, `target` | lights | |
112
+ | `fov` / `height`, `lookAt` | cameras | |
113
+ | `color`, `width`, `opacity` | lines, trails | |
114
+ | `length` | trails | ms |
115
+ | `activeCamera` | the scene, target `<sceneId>` | a camera's id: **a cut is one keyframe** |
116
+
117
+ Animate either the components (`x`, `rotateY`) or the vector (`position`,
118
+ `quaternion`) of one object, not both: `validateScene3D(scene, tracks)` says
119
+ so instead of picking a winner.
120
+
121
+ **Orbiting** is a rotation, not a path: put the camera on a `group` and turn
122
+ the group. `orbitPosition(target, yaw, pitch, distance)` and
123
+ `dollyPosition(eye, target, amount)` place cameras for keyframes.
124
+
125
+ ## Lines and trails
126
+
127
+ Two more kinds of object draw a band that faces the camera, as wide as
128
+ `width` metres (so it narrows with distance):
129
+
130
+ ```js
131
+ // A polyline through points in its own space (it moves with its transform and parent)
132
+ { id: 'ring', kind: 'line', points: [[0, 0, 0], [1, 0, 0], [1, 1, 0]], closed: true, width: 0.04, color: '#b6ff3b' }
133
+ // Where another object has been over the last `length` ms
134
+ { id: 'tail', kind: 'trail', follow: 'comet', length: 1200, samples: 64, width: 0.1, color: '#00e5ff', blend: 'add' }
135
+ ```
136
+
137
+ | Field | Meaning |
138
+ |---|---|
139
+ | `color`, `width` (default 0.05), `opacity` | |
140
+ | `taper`, `fade` | 0..1: how much it narrows and fades toward its start (a line's first point, a trail's tail). Trails default to 1, lines to 0 |
141
+ | `blend` | `normal` paints over what is behind; `add` adds its light: glowing beams, best on dark scenes and with [bloom](video-rendering.md#bloom) |
142
+ | `follow`, `length`, `samples` (trail) | The object it follows, how far back it reaches (ms), points along it (default 32) |
143
+ | `period` (trail) | For motion that repeats every `period` ms: earlier times wrap, so a loop's first frame already has the last lap's tail |
144
+
145
+ Each segment of the band is placed in the draw order by its own depth, so a
146
+ trail passes behind one shape and in front of another. Fog turns a normal
147
+ band toward the fog colour and dims an added one. The head ends round.
148
+
149
+ A trail is not a history of frames: it asks where the object was at earlier
150
+ times, so the same time always draws the same trail (scrubbing, seeking,
151
+ frames in any order, loops). The renderer needs a way to ask:
152
+
153
+ - in a video, nothing to do: the frame carries `stateAt`, and
154
+ `drawScene3D(ctx, scene, frame.state?.values, frame)` passes it on;
155
+ - elsewhere, `valuesAt`: `drawScene3D(ctx, scene, values, { width, height, time, valuesAt: (t) => timeline.getStateAtTime(t).values })`,
156
+ `resolveScene3D(…, { time, valuesAt })`, or `new Scene3DAdapter(renderer, { width, height, valuesAt })`.
157
+
158
+ Without it a trail draws nothing. `examples/headless-video/comet-trails.mjs`
159
+ is a looping comet video; the **3D Scene: Comet Trails** demo is the live
160
+ version. With the WebGL2 renderer, lines and trails go on the overlay, in
161
+ front of the meshes. For trails on a plain 2D canvas, see `drawTrail` in
162
+ [Rendering Video from Code](video-rendering.md#light-trails).
163
+
164
+ ## Drawing
165
+
166
+ ```ts
167
+ loadScene3D(json): LoadedScene3D // validates and builds meshes once (throws with every problem)
168
+ validateScene3D(json, tracks?): string[] // problems as sentences, empty when fine
169
+ resolveScene3D(loaded, values, { width, height, time?, valuesAt? }): ResolvedScene3D // pure: matrices, camera, lights, sorted triangles
170
+ drawScene3D(ctx, loaded, values, { width, height, time?, valuesAt? | stateAt? }) // resolve and draw, in one call
171
+ new Scene3DAdapter(new Canvas2DRenderer(ctx), { width, height, valuesAt? }) // registerScene, applyState(state), render()
172
+ ```
173
+
174
+ `resolveScene3D` is the whole 3D pipeline as data: world matrices, the
175
+ camera's view and projection, lights in world space, and every visible
176
+ triangle on screen with its depth, normals and outline edges, sorted. A
177
+ renderer only paints it. The same values always give the same frame, and
178
+ frames can be drawn in any order.
179
+
180
+ **In a video**, draw the scene from the frame's timeline state:
181
+
182
+ ```js
183
+ export default {
184
+ width: 1280, height: 720, duration: 9000,
185
+ timeline: { id: 'orbit', tracks: [ /* stage/... tracks */ ] },
186
+ draw(ctx, frame) {
187
+ drawScene3D(ctx, scene, frame.state?.values, frame)
188
+ },
189
+ }
190
+ ```
191
+
192
+ `examples/headless-video/scene-3d-orbit.mjs` orbits a camera around lit
193
+ shapes and cuts to a wide shot; `characters-3d-dance.mjs` has two characters
194
+ dance while the camera cranes up, then cuts to a close shot.
195
+
196
+ Golden frames (`src/scene-3d/golden/`) pin the look: the same scenes must draw
197
+ exactly the same pixels on every run.
198
+
199
+ ## In the editor
200
+
201
+ The editor's **🧊 3D Scene** element holds a scene like these: add shapes,
202
+ characters and lights, move and key them, dance characters from the playhead,
203
+ pick camera views and cut between cameras. Its tracks are on the element,
204
+ named `object.property` (`box.rotateY`); see the
205
+ [Editor Guide](editor-guide.md#3d-scenes).
206
+
207
+ ## Characters
208
+
209
+ tinyfly's v2 characters stand in 3D scenes, seen by the scene's camera from
210
+ anywhere: in front, behind, from above. A character is an object like any
211
+ other; drawing it comes from the characters add-on, so this entry stays small:
212
+
213
+ ```js
214
+ import { loadScene3D, drawScene3D } from '@algorisys/tinyfly/scene-3d'
215
+ import { characterObjects, danceFrame, stickToHuman } from '@algorisys/tinyfly/characters'
216
+
217
+ const scene = loadScene3D({
218
+ id: 'stage', camera: 'cam', /* … */
219
+ objects: [
220
+ /* camera, lights, a floor … */
221
+ { id: 'tum', kind: 'character', position: [-0.9, 0, 0], character: { look: 'clean', skin: '#f2c49b', hands: 'cartoon' } },
222
+ { id: 'didi', kind: 'character', look: 'solid', position: [0.9, 0, 0], solid: { color: '#7c3aed' } },
223
+ ],
224
+ }, { kinds: [characterObjects] })
225
+ ```
226
+
227
+ | Field | |
228
+ |---|---|
229
+ | `character` | `character()` options: `figure`, `look` (`clean`, `pencil`, `silhouette`), `ink`, `skin`, `hands`, `handStyle`, … |
230
+ | `height` | metres (default 1.7) |
231
+ | `pose` | its pose: character pose fields (`arm.right.spread`, `turn`, `lean`, …) |
232
+ | `look` | `pen` (default): drawn by its pens, in perspective, with its face and hands. `solid`: shaded capsules along its bones, an ellipsoid head with eyes, lit, outlined and depth-sorted like the scene's meshes |
233
+ | `solid` | the solid look's `color`, `skin`, `shading` (default toon) and `outline` (or `false`) |
234
+ | `shadow` | a soft shadow on the ground under it (default true) |
235
+
236
+ A character faces +z before any turn and stands on its object's ground: its
237
+ lowest point at the object's y, so at y 0 it stands on a floor at y 0. Its
238
+ pose fields are tracks on its object, next to `x`, `rotateY` and the rest:
239
+ `stage/tum` `arm.right.spread`, `stage/tum` `turn`. Every dance and flip
240
+ plays in 3D: `stickToHuman(danceFrame(style, beat))` gives the pose, and
241
+ `mirrorHumanPose()` its mirror image for a partner. Its `turn`, `roll`,
242
+ `lift` and ground contact behave as they do front-on; seen front-on through a
243
+ flat camera, a character is exactly the 2D figure.
244
+
245
+ Outside scenes, `drawCharacterInView(ctx, character, pose, projection, { height })`
246
+ draws a character through any camera (`projection.toView` / `toScreen`), and
247
+ `skeletonInView` / `stagePlanSpace` give its joints.
248
+
249
+ **Other object kinds** come the same way: an `ObjectKind` validates its
250
+ objects, prepares them once, and each frame returns meshes (shaded and sorted
251
+ with the scene's) and drawables (drawn whole at their depth). Pass it in
252
+ `loadScene3D(scene, { kinds })`.
253
+
254
+ ## The WebGL2 renderer
255
+
256
+ `@algorisys/tinyfly/scene-3d/webgl` (`tinyfly-scene-3d-webgl.iife.js` for
257
+ script tags) draws the same resolved frame with WebGL2:
258
+
259
+ ```js
260
+ import { loadScene3D, resolveScene3D } from '@algorisys/tinyfly/scene-3d'
261
+ import { WebGL2Renderer } from '@algorisys/tinyfly/scene-3d/webgl'
262
+
263
+ const renderer = new WebGL2Renderer(canvas.getContext('webgl2'), { overlay })
264
+ renderer.render(resolveScene3D(scene, values, { width: canvas.width, height: canvas.height }))
265
+ // or drive it from a timeline: new Scene3DAdapter(renderer, { width, height })
266
+ ```
267
+
268
+ - **A depth buffer**: shapes that cut through each other, huge floors and
269
+ long meshes draw right, with no `layer` needed.
270
+ - **Light per pixel**: smooth shading is smooth, toon bands and spot pools
271
+ have clean edges, fog fades per pixel. The same light model as the Canvas
272
+ 2D renderer (up to 8 lights).
273
+ - **Outlines** by the inverted hull: silhouettes in the ink colour and
274
+ width. (Creases inside a silhouette are inked only by the Canvas 2D
275
+ renderer.)
276
+ - **See-through meshes** are drawn after the opaque ones, far to near.
277
+ - Objects drawn whole, such as characters in their pen look, lines and
278
+ trails, go on `overlay`, a 2D canvas laid over the GL one (in front of the meshes);
279
+ solid characters are meshes and sort properly.
280
+
281
+ It runs on a page or in a Worker (OffscreenCanvas). Node has no WebGL2, so
282
+ headless video uses the Canvas 2D renderer. The cross-browser checks
283
+ (`npm run e2e -- --check scene-3d-webgl`) compile it in Chromium, Firefox and
284
+ WebKit, compare its silhouettes with the Canvas 2D renderer's and check the
285
+ depth buffer.
286
+
287
+ ## Draw order and its limits
288
+
289
+ The Canvas 2D renderer paints back to front (painter's algorithm), culling
290
+ back faces and clipping at the camera's near plane. Within a `layer`
291
+ (default 0) triangles sort far to near; lower layers draw first, so a floor at
292
+ `layer: -1` never covers what stands on it. Triangles that cross each other,
293
+ or very long ones, can sort wrongly: give big planes `segments`, keep meshes
294
+ modest, or use a layer. Each triangle has one colour, so smooth shading is
295
+ smoothed per triangle, not per pixel; more segments look rounder. The WebGL2
296
+ renderer (above) has a depth buffer and per-pixel light.
297
+
298
+ Rendering speed in Node: a 1280×720 scene of a few thousand triangles renders
299
+ at a few frames a second; parallel rendering for long films is planned.
@@ -0,0 +1,314 @@
1
+ # Scroll-driven animation
2
+
3
+ Scroll animation in tinyfly is a **driver**, not a special kind of timeline.
4
+
5
+ The engine is a pure function of time: give it a time, it gives you values. A
6
+ driver is the boundary where something real-world — a clock, a scroll position,
7
+ a drag — becomes a time. `ScrollDriver` does nothing but call `seek()` on an
8
+ ordinary timeline, which means every animation you already have can be
9
+ scroll-driven without changing it, and a scroll animation still exports to the
10
+ same JSON.
11
+
12
+ ```ts
13
+ import { VisibilityDriver, ScrollDriver } from '@algorisys/tinyfly/drivers'
14
+ ```
15
+
16
+ ## Which driver do you want?
17
+
18
+ **"Play it when it comes into view"** → `VisibilityDriver`. This is the common
19
+ case and it is much simpler — no geometry, no scrub maths, just
20
+ IntersectionObserver.
21
+
22
+ **"Tie it to how far I've scrolled"** → `ScrollDriver`.
23
+
24
+ Each has a one-call form that creates the driver and starts it:
25
+
26
+ ```ts
27
+ import { playWhenVisible, scrubOnScroll } from '@algorisys/tinyfly/drivers'
28
+
29
+ const visible = playWhenVisible({ timeline, trigger: section }) // a started VisibilityDriver
30
+ const scrub = scrubOnScroll({ timeline, trigger: panel, scrub: true }) // a started ScrollDriver
31
+ ```
32
+
33
+ **Drivers move the playhead; they do not render.** `VisibilityDriver` calls
34
+ `timeline.play()`, so something must still tick the timeline and apply its state
35
+ (a `Clock` or your own rAF loop).
36
+ `ScrollDriver` calls `timeline.seek()`, so apply the state in `onUpdate`:
37
+
38
+ ```ts
39
+ new ScrollDriver({
40
+ timeline,
41
+ trigger: panel,
42
+ scrub: true,
43
+ onUpdate: () => adapter.applyState(timeline.getStateAtTime(timeline.currentTime)),
44
+ }).start()
45
+ ```
46
+
47
+ ## VisibilityDriver
48
+
49
+ ```ts
50
+ import { VisibilityDriver } from '@algorisys/tinyfly/drivers'
51
+
52
+ const driver = new VisibilityDriver({
53
+ timeline,
54
+ trigger: document.querySelector('#section')!,
55
+ behaviour: 'once', // 'once' | 'repeat' | 'reset'
56
+ threshold: 0.25, // fraction visible before it counts
57
+ })
58
+ driver.start()
59
+ ```
60
+
61
+ | `behaviour` | What happens |
62
+ |---|---|
63
+ | `once` (default) | Plays the first time it appears, never again |
64
+ | `repeat` | Rewinds and plays on every appearance |
65
+ | `reset` | Plays on appear, rewinds when it leaves |
66
+
67
+ Options: `rootMargin` and `root` pass through to IntersectionObserver;
68
+ `onEnter` / `onLeave` fire on every crossing regardless of behaviour.
69
+
70
+ Where `IntersectionObserver` does not exist (SSR, a worker, an old browser) the
71
+ driver plays immediately — better to show the animation than to leave it stuck
72
+ on frame 0 forever.
73
+
74
+ Call `driver.reset()` to let a `once` driver fire again.
75
+
76
+ ## ScrollDriver
77
+
78
+ ```ts
79
+ import { ScrollDriver } from '@algorisys/tinyfly/drivers'
80
+
81
+ const driver = new ScrollDriver({
82
+ timeline,
83
+ trigger: document.querySelector('#panel')!,
84
+ start: 'top bottom', // when the panel's top hits the viewport's bottom
85
+ end: 'bottom top', // when the panel's bottom hits the viewport's top
86
+ scrub: true,
87
+ })
88
+ driver.start()
89
+ ```
90
+
91
+ The driver pauses the timeline when it starts — scroll position is now the only
92
+ thing advancing it.
93
+
94
+ ### Trigger positions
95
+
96
+ A position is `"<element edge> <viewport edge>"`:
97
+
98
+ ```
99
+ 'top bottom' the element's top reaching the viewport's bottom
100
+ 'center center' the element's middle at the viewport's middle
101
+ 'bottom top' the element's bottom reaching the viewport's top
102
+ '25% 75%' percentages work for either edge
103
+ 'top top+=400' 400px past that point
104
+ 'top bottom-=100' 100px before it
105
+ 300 a bare number: 300px down from the element's top
106
+ ```
107
+
108
+ Keywords: `top`/`left`/`start` (0), `center`/`centre`/`middle` (0.5),
109
+ `bottom`/`right`/`end` (1). A single token is read as the element edge with the
110
+ viewport edge defaulting to `top`.
111
+
112
+ A common fixed-length scrub — `end` starting with `+=` is measured from the start:
113
+
114
+ ```ts
115
+ { start: 'top top', end: '+=500' } // 500px of scrolling, exactly
116
+ { start: 'top top', end: '+=150%' } // one and a half viewport heights
117
+ ```
118
+
119
+ ### Scrub modes
120
+
121
+ ```ts
122
+ scrub: true // playhead tracks scroll exactly — snappy, frame-accurate
123
+ scrub: 0.5 // playhead eases toward the scroll position over ~0.5s
124
+ ```
125
+
126
+ Smoothing feels nicer but makes the displayed time frame-rate dependent, since
127
+ it advances by elapsed time. `scrub: true` is the exact path; use it when the
128
+ animation needs to land on specific frames.
129
+
130
+ ### Callbacks
131
+
132
+ `onUpdate(progress, velocity)` fires whenever progress or scroll speed changes.
133
+ `velocity` is in px/s, positive scrolling down, and returns to 0 (with one more
134
+ call) about 120 ms after scrolling stops — enough for skew-on-scroll effects.
135
+ `onEnter` / `onLeave` / `onEnterBack` / `onLeaveBack` fire at the edges of the
136
+ active range, with `Back` meaning you were scrolling up. A scroll that jumps
137
+ across the whole range in one step (a fast flick, or loading the page already
138
+ past it) fires both edges, in order.
139
+
140
+ Without a `timeline`, the driver only reports progress and fires callbacks.
141
+
142
+ ### Nested scrollers
143
+
144
+ ```ts
145
+ new ScrollDriver({ timeline, trigger, scroller: document.querySelector('#pane')! })
146
+ ```
147
+
148
+ Positions are then measured against that element's box instead of the viewport.
149
+
150
+ ### Performance, and re-measuring
151
+
152
+ **Scrolling does no layout work.** The driver measures the trigger when it
153
+ starts and on window resize, turning `start` and `end` into absolute scroll
154
+ offsets. A scroll event then reads only the scroll offset. With `scrub: <seconds>`
155
+ its frame loop runs only until the playhead catches up, then stops.
156
+
157
+ So if layout changes without a resize — images or web fonts loading, content
158
+ inserted above the trigger — call `driver.refresh()` (or
159
+ `ScrollDriver.refreshAll()` for every driver, in the order they started).
160
+ `driver.progress` is the current progress, 0..1; `driver.velocity` the scroll
161
+ speed.
162
+
163
+ On touch devices, resizes that only change the height by less than a quarter
164
+ (the address bar showing and hiding) are skipped, so pins do not jump mid-scroll.
165
+ `start` and `end` may be functions, called again on every refresh, and
166
+ `onRefresh` runs before each re-measure (after the first), which is where
167
+ `invalidateOnRefresh` rebuilds an animation.
168
+
169
+ ### Snap, markers and horizontal containers
170
+
171
+ - **`snap`** takes a progress step, a list of points, a function, or
172
+ `{ snapTo, duration, delay, ease }`. It scrolls to the nearest point once
173
+ scrolling stops inside the range, allowing for the speed scrolling had, and
174
+ stops at once if the person scrolls, touches, clicks or types.
175
+ `snapProgress(progress, velocity, snapTo)` is the pure choice.
176
+ - **`markers: true`** draws the start and end lines while developing.
177
+ - **`container: { range(), progress(), shiftAt(progress) }`** puts a trigger
178
+ inside something that moves sideways as the page scrolls. `containerProgressAt()`
179
+ is the pure solver, and `live` builds `container` for you from
180
+ `containerAnimation`.
181
+
182
+ ### Smooth scrolling
183
+
184
+ `SmoothScroll` (and `live.smoothScroll()`) eases wheel scrolling on the page's
185
+ real scroll position, so drivers follow it with no setup, and adds `data-speed` /
186
+ `data-lag` parallax layers. It rests those layers while drivers measure and
187
+ measures them again after pins apply (`ScrollDriver.onRefresh`). See
188
+ [Smooth scrolling](./gsap-compat.md#smooth-scrolling).
189
+
190
+ ```ts
191
+ const smoother = new SmoothScroll({ smooth: 0.8, effects: true }).start()
192
+ ```
193
+
194
+ ### Smooth-scroll libraries
195
+
196
+ Libraries that keep native scrolling (Lenis, and Locomotive Scroll v5 built on
197
+ it) fire ordinary `scroll` events, so drivers follow them with no setup. For a
198
+ scroller that moves content with transforms instead, push its position:
199
+
200
+ ```ts
201
+ virtualScroller.on('scroll', ({ scroll }) => driver.update(scroll))
202
+ ```
203
+
204
+ ## Pinning
205
+
206
+ `pin: true` holds the trigger in place for the length of the range; pass an
207
+ element to pin something else:
208
+
209
+ ```ts
210
+ new ScrollDriver({
211
+ timeline,
212
+ trigger: document.querySelector('.panels')!,
213
+ start: 'top top',
214
+ end: '+=2000', // stays pinned for 2000px of scrolling
215
+ scrub: true,
216
+ pin: true,
217
+ }).start()
218
+ ```
219
+
220
+ It is the CSS sticky recipe below, automated. The element is wrapped in a
221
+ `div.pin-spacer` as tall as the element plus the pinned distance, and made
222
+ `position: sticky` at the offset where the range starts, so content after it is
223
+ pushed down by that distance and the browser does the holding. Nothing is
224
+ written while scrolling. `destroy()` removes the spacer and restores the
225
+ element's styles.
226
+
227
+ Two things to know:
228
+
229
+ - Sticky positioning stops working if an ancestor between the element and the
230
+ scroller has `overflow: hidden` or `auto`.
231
+ - Create pinned drivers top to bottom. A pin pushes the content below it down,
232
+ and resize refreshes run in start order so later drivers measure after it.
233
+
234
+ ### Doing it by hand
235
+
236
+ The same effect in plain CSS, if you prefer to own the layout:
237
+
238
+ ```html
239
+ <div class="pin-container">
240
+ <div class="pin-target">…animated content…</div>
241
+ </div>
242
+ ```
243
+
244
+ ```css
245
+ .pin-container { height: 300vh; } /* how long the pin lasts */
246
+ .pin-target { position: sticky; top: 0; height: 100vh; }
247
+ ```
248
+
249
+ Then drive the animation off the container:
250
+
251
+ ```ts
252
+ new ScrollDriver({
253
+ timeline,
254
+ trigger: document.querySelector('.pin-container')!,
255
+ start: 'top top',
256
+ end: 'bottom bottom',
257
+ scrub: true,
258
+ })
259
+ ```
260
+
261
+ The element sticks for the container's height while the timeline scrubs across
262
+ it.
263
+
264
+ ## With the GSAP-style API
265
+
266
+ `live` accepts GSAP's `scrollTrigger` vars on a timeline or a single tween, built
267
+ on the same driver — see [gsap-compat.md](gsap-compat.md#scroll-triggers).
268
+
269
+ ## Authoring in the editor
270
+
271
+ Click **⇅ Scroll** in the preview header to switch the preview into scroll-scrub
272
+ mode. A scrollable strip appears with a trigger element inside it; scroll the
273
+ strip and the animation scrubs.
274
+
275
+ This is not a simulation. The preview attaches a real `ScrollDriver` to a real
276
+ scroll container, so a start/end pair tuned here behaves identically on your
277
+ page. The panel shows the exact snippet to reproduce what you are looking at:
278
+
279
+ - **Start** / **End** — the trigger positions, from the same grammar above
280
+ - **Scrub** — `exact`, or a smoothing time
281
+ - **Runway** — how much space sits above and below the trigger
282
+ - A live progress percentage, and the code to paste
283
+
284
+ Normal playback is paused while the mode is on, because scroll position is the
285
+ only thing that should be moving the playhead — the same as in production.
286
+
287
+ ## Determinism
288
+
289
+ A driver is not a hole in the determinism guarantee. The engine is deterministic
290
+ *given a time*; it was never deterministic given a wall clock, and the existing
291
+ rAF `Clock` already reads real time. A scroll driver is the same kind of
292
+ boundary — and `scrollProgress()` itself is a pure function of geometry, unit
293
+ tested without a browser.
294
+
295
+ The geometry helpers are exported for the same reason: `parseTrigger(position)`,
296
+ `triggerDistance(rect, viewportHeight, position)` (px until a trigger fires,
297
+ positive while it is still ahead), `scrollProgress(rect, viewportHeight, start,
298
+ end)`, and `smoothToward(current, target, smoothingSeconds, deltaMs)` (the
299
+ smoothing behind `scrub: <seconds>`). See the
300
+ [API reference](./api-reference.md#drivers).
301
+
302
+ ## Cleaning up
303
+
304
+ ```ts
305
+ driver.stop() // remove listeners, keep the driver usable
306
+ driver.destroy() // stop and release everything
307
+ ```
308
+
309
+ Both are safe to call twice.
310
+
311
+ ## See also
312
+
313
+ - [`docs/gsap-compat.md`](./gsap-compat.md) — how this compares to ScrollTrigger
314
+ - [`docs/api-reference.md`](./api-reference.md) — the underlying timeline API
@@ -0,0 +1,61 @@
1
+ # Shape morphing (shape tween)
2
+
3
+ Animate one path into another — a hexagon into a star, a blob into a circle — by
4
+ tweening the path's `d` over the timeline.
5
+
6
+ ## Using it
7
+
8
+ 1. Select a path (a ⬡ Polygon / ★ Star, or any path).
9
+ 2. In **Properties → 🌀 Shape Morph**, pick the **target** shape (Polygon or Star)
10
+ and its points / inner %.
11
+ 3. Click **Create shape morph →**. A `d` track is added that tweens from the
12
+ current shape to the target across the timeline.
13
+ 4. Press **Play** to watch it morph. The `d` track appears in the timeline like
14
+ any other; edit or delete it there.
15
+
16
+ ## How it works
17
+
18
+ The engine interpolates path `d` strings natively. `getInterpolator` detects path
19
+ data (a string starting with a moveto) and routes it to a **path morph**:
20
+
21
+ ```ts
22
+ // src/engine/path/path-morph.ts
23
+ morphPath(fromD, toD, progress, { shapeIndex? })
24
+ ```
25
+
26
+ Both paths are resampled into matching point lists, which are blended by
27
+ `progress`. The matching is worked out once per pair of shapes and cached:
28
+
29
+ - **Subpaths are paired** when both paths have the same number, so holes morph
30
+ into holes.
31
+ - **The start point and winding are chosen** so points travel least (about each
32
+ shape's centre) — nothing twists or turns inside out. Pass `shapeIndex` to
33
+ force a particular alignment.
34
+ - **Corners are kept**: samples are spaced by length and always include every
35
+ corner of both shapes.
36
+ - Open paths stay open; at progress 0 and 1 the original strings come back
37
+ exactly.
38
+
39
+ It is deterministic and needs no DOM (it runs in the engine, workers, and tests).
40
+ From code, use `morphSVG` in `live` or `tf` — see
41
+ [gsap-compat.md](gsap-compat.md#shape-morphing).
42
+
43
+ ## Where it renders
44
+
45
+ Because morphing is engine-level, it works everywhere a `d` value can be applied:
46
+
47
+ - **DOM preview** — the path binds its `d` to the animated value.
48
+ - **SVG preview** — the SVG adapter sets the `d` attribute.
49
+ - **Canvas preview & raster export** — the Canvas adapter rebuilds a `Path2D`
50
+ from the animated `d` each frame.
51
+ - **Embeds / player** — the DOM adapter drives the child `<path>`'s `d`.
52
+
53
+ ## Limitations / later
54
+
55
+ - Mid-morph shapes are drawn as dense polylines (about one point per 2.5px of
56
+ length, plus every corner), so curves are faithful at normal sizes; very large
57
+ curved shapes can show faint facets mid-tween.
58
+ - Fill/stroke morph independently via their own tracks; only geometry is tweened
59
+ by the `d` track.
60
+ - In the editor, authoring targets are polygon/star today. From code, `morphSVG`
61
+ morphs between any paths or basic shapes.