@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,123 @@
1
+ # Building Animations with an LLM
2
+
3
+ tinyfly is built to be written by code, and that includes code a language
4
+ model writes. This page is for you, setting up an assistant (Claude Code,
5
+ Cursor, Copilot, a chat window), and for the assistant itself.
6
+
7
+ The short version: **read the catalog, write, check, look.**
8
+
9
+ ## 1. Read the catalog first
10
+
11
+ Everything tinyfly can do, read from the library itself:
12
+
13
+ ```bash
14
+ npx @algorisys/tinyfly capabilities # markdown
15
+ npx @algorisys/tinyfly capabilities --json # the same as data
16
+ ```
17
+
18
+ It lists the easings, track kinds, every property each canvas shape can
19
+ animate (with units and ranges), the stick figure's joints, poses,
20
+ expressions, gags, gaits, beat actions, dances, flips and hand shapes, the v2
21
+ character's poses, the code panel's languages, anchors and edits, camera
22
+ shots and the teaching helpers. It is generated from the code, so it can't
23
+ fall behind: **a name in it is accepted, and a name not in it is rejected.**
24
+ It is also the last part of `llms-full.txt`.
25
+
26
+ From code, the same catalog is `capabilities()` (and `capabilitiesMarkdown()`)
27
+ in `@algorisys/tinyfly/characters`.
28
+
29
+ ## 2. Ask a target what it can do
30
+
31
+ ```js
32
+ import { stickFigureTarget, codePanel, describeTarget } from '@algorisys/tinyfly/characters'
33
+
34
+ describeTarget({ type: 'rect', x: 0, y: 0, width: 80, height: 40 })
35
+ // { type: 'rect', properties: [{ name: 'opacity', unit: '0..1', min: 0, max: 1, value: … }, …] }
36
+
37
+ describeTarget(stickFigureTarget({ x: 200, y: 300 }))
38
+ // { kind: 'stick figure', properties: [{ name: 'rightShoulder', unit: 'degrees', description: '…', value: 18 }, …],
39
+ // actions: { walk: '…', grab: 'Steps to where its arm reaches the target …', … } }
40
+ ```
41
+
42
+ Custom targets can describe themselves with `about` (`kind`, `summary`,
43
+ `props`, `actions`); the stick figure and the code panel do.
44
+ `animatableProperties(target)` is just the names.
45
+
46
+ ## 3. Check before you play
47
+
48
+ Wrong names fail loudly, with the name that was probably meant:
49
+
50
+ ```text
51
+ scriptTracks: 2 problem(s) in the beats:
52
+ beat 0: Unknown action "jumpp": did you mean "jump"? Known: walk, bouncy, …
53
+ beat 1: Unknown beat field "expression": did you mean "mood"? Known: do, at, for, …
54
+ ```
55
+
56
+ - **Beat scripts**: `scriptTracks()` throws on errors. `checkBeats(beats)`
57
+ returns errors and warnings without throwing, and from the command line:
58
+ `npx @algorisys/tinyfly check beats.json`.
59
+ - **Tracks**: `checkTracks(tracks, targets)` finds tracks aimed at targets
60
+ that aren't there, properties a target can't animate (`rotation` → `rotate`),
61
+ keys out of time order, values of the wrong kind and values out of range.
62
+ - **Code panels** reject unknown languages and remove styles. `token()` throws
63
+ when a line doesn't have the word.
64
+ - **Teaching timelines**: `npx @algorisys/tinyfly validate timeline.json --markup figure.svg`.
65
+
66
+ ## 4. Look at it
67
+
68
+ An animation that compiles can still look wrong. Render frames and look at
69
+ them before calling it done:
70
+
71
+ ```bash
72
+ npx @algorisys/tinyfly video scene.mjs --stills frames --times 0,800,1600,2400
73
+ ```
74
+
75
+ A model that can read images should look at the PNGs: is the hand on the
76
+ word, does the figure stand on the line, does the text land where it should?
77
+ Fix, render again.
78
+
79
+ ## The rules that trip models up
80
+
81
+ - **Milliseconds in JSON, seconds in the GSAP-style API.** Timeline keyframes
82
+ and beats are ms; `live.to(el, { duration: 1 })` is seconds.
83
+ - **Canvas `x`/`y` tracks are offsets** from where the target was placed, not
84
+ positions. A beat script's `to` is a scene x, and its tracks are offsets
85
+ from `from` (and `ground` for y).
86
+ - **Scene y grows downward.** A floor higher up the screen has a smaller y.
87
+ - **Angles are degrees.** Stick-figure arms: 0 hangs down, 90 straight out,
88
+ 180 straight up; in profile the left arm's forward is negative.
89
+ - **Aim beats at anchors, not guessed numbers**: `code.line(7)`,
90
+ `code.token(3, 'var')`, `code.spot(2, 8, 4)`, `piece.home`.
91
+ - **Key reactions to contact times.** Beats that touch something report
92
+ `result.beats[i].contact` (and `release`): wipe the line, fling the word or
93
+ type the text at those times.
94
+ - **Record panel edits before `code.ride()`**, which reads the moves they make.
95
+
96
+ ## Set up your assistant
97
+
98
+ The npm package ships everything an agent needs, at the version installed:
99
+
100
+ ```text
101
+ node_modules/@algorisys/tinyfly/
102
+ llms.txt the index
103
+ llms-full.txt every doc, the course and the capability catalog
104
+ docs/*.md the docs
105
+ skills/tinyfly/SKILL.md
106
+ ```
107
+
108
+ **Claude Code**: copy the skill into your project and it loads when you ask
109
+ for an animation:
110
+
111
+ ```bash
112
+ mkdir -p .claude/skills && cp -r node_modules/@algorisys/tinyfly/skills/tinyfly .claude/skills/
113
+ ```
114
+
115
+ **Other agents** (Cursor, Copilot, Codex, Aider): point them at the skill
116
+ from your `AGENTS.md` or rules file:
117
+
118
+ ```markdown
119
+ When writing tinyfly animations, follow node_modules/@algorisys/tinyfly/skills/tinyfly/SKILL.md.
120
+ ```
121
+
122
+ **A chat window**: paste the output of `npx @algorisys/tinyfly capabilities`,
123
+ or link `llms-full.txt`.
package/docs/maps.md ADDED
@@ -0,0 +1,116 @@
1
+ # Animated Maps
2
+
3
+ `@algorisys/tinyfly/maps` draws animated maps on a canvas: a camera that flies
4
+ from the whole world in to a city, pins that drop in, and routes that draw
5
+ themselves while a marker travels them. Everything that moves is a number, so
6
+ it is a timeline track like any other, and it renders the same in a browser and
7
+ in headless video.
8
+
9
+ ```js
10
+ import { mapTarget, mapFlyTracks, routeStops, fitView } from '@algorisys/tinyfly/maps'
11
+ ```
12
+
13
+ On a page with no build step, load the maps add-on after the browser bundle; it
14
+ adds to the same `tinyfly` global:
15
+
16
+ ```html
17
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js"></script>
18
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly-maps.iife.js"></script>
19
+ ```
20
+
21
+ It is a separate script because the offline world map it carries adds about
22
+ 33 KB (gzipped), which pages without maps should not pay for.
23
+
24
+ In the editor, the **🗺 Map** element does all of this without code (see the
25
+ [editor guide](editor-guide.md#maps)).
26
+
27
+ ## Two base maps
28
+
29
+ | Base | What | Use it for |
30
+ |---|---|---|
31
+ | `tiles` | Raster map tiles: OpenStreetMap by default, or any server with the standard `{z}/{x}/{y}` scheme | Real street maps in a browser |
32
+ | `outline` (default) | Country outlines from Natural Earth (public domain), bundled | Headless video, offline use, and the pencil look |
33
+
34
+ **Tiles come from a server.** OpenStreetMap's tile servers allow light use with
35
+ attribution ("© OpenStreetMap contributors", which the map draws for you) and
36
+ do not allow heavy use. For anything busy, set `url` to your own tile server or
37
+ a commercial provider:
38
+
39
+ ```js
40
+ const tiles = { url: 'https://tiles.example.com/{z}/{x}/{y}.png', attribution: '© My Maps', maxZoom: 18 }
41
+ ```
42
+
43
+ Tiles load in the background. Until a tile arrives, the matching corner of an
44
+ already-loaded zoomed-out tile stands in, so flying in never shows blank
45
+ squares. For frames that must be complete (exports, stills), call
46
+ `preloadTiles(cache, source, views)` first.
47
+
48
+ **The outline needs nothing.** It is drawn from vector shapes, so it renders
49
+ the same everywhere, colours countries the way you ask
50
+ (`style.highlight: { IND: '#f7d9a8' }`), and can be drawn in hand-drawn
51
+ pencil strokes that boil (`style.sketch`).
52
+
53
+ ## A map target
54
+
55
+ ```js
56
+ const trip = mapTarget({
57
+ x: 0, y: 0, width: 1280, height: 720,
58
+ view: { lon: 30, lat: 25, zoom: 2.2 }, // where it starts
59
+ base: 'outline',
60
+ style: { highlight: { IND: '#f7d9a8', NPL: '#f3c9a0' } },
61
+ places: [
62
+ { id: 'mumbai', lon: 72.88, lat: 19.08, label: 'Mumbai' },
63
+ { id: 'delhi', lon: 77.10, lat: 28.70, label: 'Delhi' },
64
+ { id: 'kathmandu', lon: 85.32, lat: 27.72, label: 'Kathmandu' },
65
+ ],
66
+ routes: [{ id: 'trip', through: ['mumbai', 'delhi', 'kathmandu'] }],
67
+ })
68
+ ```
69
+
70
+ Its props are the values tracks animate:
71
+
72
+ | Prop | Meaning |
73
+ |---|---|
74
+ | `view.lon`, `view.lat`, `view.zoom` | The camera: what is at the centre, and the zoom (0 is the whole world, each step doubles) |
75
+ | `<place>.show` | 0..1: the pin drops in and its label fades up (default 1) |
76
+ | `<route>.draw` | 0..1: how much of the route is drawn (default 1) |
77
+ | `<route>.marker` | 0..1: where a marker travelling the route is; below 0 hides it (default -1) |
78
+
79
+ The view's props are named with a dot so they never clash with a CSS property
80
+ (`zoom` is one).
81
+
82
+ Routes are `arc` (a flight-path bow, the default), `great-circle` (the shortest
83
+ way over the globe) or `straight`, in a colour and width, optionally dashed,
84
+ with an `arrow` or `dot` marker.
85
+
86
+ ## Helpers
87
+
88
+ | | |
89
+ |---|---|
90
+ | `fitView(places, width, height, padding)` | The centre and zoom that show every place |
91
+ | `flyView(from, to, t)` | A view part way along a flight, pulling out in the middle when the ends are far apart |
92
+ | `mapFlyTracks(target, from, to, start, end)` | That flight as `view.*` keyframe tracks |
93
+ | `routeStops(options, routeId)` | How far along a route each stop is (0..1), so a pin can drop as the line arrives |
94
+ | `mapAt(target, frame, id)` | The view in a frame, and `point(lon, lat)` in the scene, for drawing that stays on the map |
95
+ | `project(view, lon, lat)`, `unproject(view, x, y)` | Web Mercator, the projection web maps use |
96
+ | `greatCircle(from, to)` | Points along the shortest route over the globe |
97
+ | `WORLD_CITIES`, `findCity(name)` | About 80 major cities, so you need not look up coordinates |
98
+ | `worldCountries()`, `findCountry(code)` | The outline map's countries, by ISO code or name |
99
+
100
+ ## A trip in a timeline
101
+
102
+ ```js
103
+ const stops = routeStops(trip.map, 'trip')
104
+ tracks: [
105
+ ...mapFlyTracks('map', world, india, 800, 3200), // fly in
106
+ { id: 'd', target: 'map', property: 'trip.draw', keyframes: [{ time: 3600, value: 0 }, { time: 8200, value: 1 }] },
107
+ { id: 'm', target: 'map', property: 'trip.marker', keyframes: [{ time: 3599, value: -1 }, { time: 3600, value: 0 }, { time: 8200, value: 1 }] },
108
+ // Delhi's pin drops as the line reaches it:
109
+ { id: 'p', target: 'map', property: 'delhi.show', keyframes: [{ time: 0, value: 0 }, { time: 3600 + 4600 * stops[1], value: 1 }] },
110
+ ]
111
+ ```
112
+
113
+ The full scene is
114
+ [`examples/headless-video/map-route.mjs`](../examples/headless-video/map-route.mjs);
115
+ the **Map Route** card in the Examples gallery plays the same trip on
116
+ OpenStreetMap tiles.
@@ -0,0 +1,41 @@
1
+ # Onion skinning
2
+
3
+ Onion skinning shows faint **ghost frames** of the animation just before and
4
+ after the playhead, so you can see the arc of a move (a bounce, a swing, an
5
+ ease) while editing a single frame.
6
+
7
+ ## Using it
8
+
9
+ 1. Switch the preview to the **Canvas** renderer.
10
+ 2. Click **🧅 Onion** in the preview header.
11
+ 3. Scrub the playhead — dim copies of the moving elements appear at nearby times,
12
+ brightest closest to the playhead.
13
+
14
+ Onion skin only draws while **paused** (it would just blur during playback) and
15
+ is an **editor-only visualization** — it is never part of the exported animation
16
+ or the saved JSON.
17
+
18
+ ## Why Canvas only
19
+
20
+ The Canvas renderer can cheaply redraw the whole stage several times per frame at
21
+ different opacities. The DOM/SVG renderers would need cloned element trees per
22
+ ghost, which is heavier and easy to get wrong — so onion skin is Canvas-only for
23
+ now. The camera is honoured per ghost, so ghosts land where they actually appear.
24
+
25
+ ## How it works
26
+
27
+ `src/editor/utils/onion.ts` is a pure helper:
28
+
29
+ ```ts
30
+ onionGhostTimes(now, duration, { frames = 3, step = 120, maxAlpha = 0.35 })
31
+ // → [{ time, alpha }, …] nearer ghosts brighter; out-of-range times dropped
32
+ ```
33
+
34
+ The preview (`preview-panel.tsx`, `renderCanvas`) samples each ghost time with
35
+ `timeline.getStateAtTime`, applies it to the Canvas adapter, and renders at the
36
+ ghost's alpha before drawing the current frame at full opacity.
37
+
38
+ ## Config
39
+
40
+ The defaults (3 frames each side, 120 ms apart, 0.35 max opacity) are baked in for
41
+ now. Exposing them in the UI is a possible later refinement.
@@ -0,0 +1,65 @@
1
+ # Pen tool
2
+
3
+ Draw custom paths point by point — straight segments and smooth bezier curves —
4
+ in the DOM preview.
5
+
6
+ ## Using it
7
+
8
+ 1. In the DOM preview header, click **✒️ Pen**.
9
+ 2. **Click** on the stage to drop anchor points (straight segments between them).
10
+ 3. **Click-drag** to pull out a curve handle as you place a point (a smooth
11
+ bezier, with symmetric handles).
12
+ 4. **Finish**:
13
+ - **Click the first point** to close the path (filled). It grows and turns cyan
14
+ when the cursor is close enough to close.
15
+ - **Enter** or **double-click** to finish an open path (stroked).
16
+ - **Backspace / Delete** removes the last point you placed.
17
+ - **Esc** to cancel.
18
+
19
+ The result is a normal `PathElement`, so it animates, morphs, and exports like any
20
+ other path. Open paths default to a 2px stroke with no fill; closed paths get a
21
+ solid fill.
22
+
23
+ ## How it works
24
+
25
+ The geometry is a pure, unit-tested helper:
26
+
27
+ ```ts
28
+ // src/editor/utils/pen-path.ts
29
+ buildPenPath(nodes, closed) // nodes → "M … L/C … [Z]"
30
+ penNodesBounds(nodes) // bbox incl. handles
31
+ localizePenPath(nodes, closed) // → { x, y, width, height, d } in local coords
32
+ mirrorHandle(ax, ay, h) // symmetric drag handle
33
+ ```
34
+
35
+ The preview tracks pen nodes in stage coordinates (mapped from the pointer via the
36
+ canvas rect, so it's correct at any zoom), draws the in-progress path, anchors,
37
+ and handles live, and on finish localises the nodes into an element box via
38
+ `localizePenPath` and adds a `PathElement`.
39
+
40
+ ## Adjusting as you draw
41
+
42
+ Before finishing, you can grab what you've already placed:
43
+
44
+ - **Drag an anchor** to move that point (its handles move with it).
45
+ - **Drag a handle** to reshape the curve; the opposite handle mirrors it, keeping
46
+ the anchor smooth.
47
+ - **Hold Alt while dragging a handle** to break symmetry — the opposite handle
48
+ stays put, giving a corner (cusp) instead of a smooth point.
49
+
50
+ Handles take priority over anchors when they overlap, so you can always grab a
51
+ handle sitting on its point.
52
+
53
+ ## Snapping
54
+
55
+ When **🧲 Snap** is on, pen **points** snap to the grid (**▦ Grid**), your guides
56
+ (**📏 Rulers**), other elements' edges/centres, and the artboard — with the same
57
+ pink alignment guides as element editing. Bezier **handles** stay free so curves
58
+ aren't constrained.
59
+
60
+ ## Limitations / later
61
+
62
+ - After finishing, edit the path with the existing path control points, or the
63
+ raw SVG field in Properties.
64
+ - Backspace removes points from the end; the first anchor is reserved for closing,
65
+ so it can't be repositioned mid-draw (its handle still can).
@@ -0,0 +1,44 @@
1
+ # Polygon & star shapes
2
+
3
+ Add regular polygons and stars from the **Elements** panel. They are ordinary
4
+ closed paths under the hood, so they render, animate, and export exactly like any
5
+ other path — while staying parametric (editable sides/points, resizable).
6
+
7
+ ## Using them
8
+
9
+ - In the **Elements** panel, click **⬡ Polygon** or **★ Star**.
10
+ - Select the shape and open **Properties**:
11
+ - **Sides** (polygon) or **Points** (star)
12
+ - **Inner %** (star) — the inner radius as a percentage of the outer radius
13
+ - **Resize** the shape on the stage like any box; the geometry regenerates to fill
14
+ the new width/height, so sides/points stay crisp at any size.
15
+
16
+ ## How it works
17
+
18
+ `src/editor/utils/poly-star.ts` is a pure, unit-tested geometry helper:
19
+
20
+ ```ts
21
+ polygonVertices(width, height, sides) // inscribed in the box, first vertex up
22
+ starVertices(width, height, points, innerRatio)
23
+ verticesToPath(verts) // → "M … L … Z"
24
+ polyStarPath(spec, width, height) // → path `d`
25
+ ```
26
+
27
+ A polygon/star is a `PathElement` with an extra `shape: { kind, points, innerRatio }`
28
+ spec. The scene store keeps the path `d` in sync:
29
+
30
+ - `addPolyStar(spec, overrides)` creates it (solid fill, closed).
31
+ - `updateShape(id, patch)` changes sides/points/inner ratio and regenerates `d`.
32
+ - `updateElement` regenerates `d` whenever the width/height (or spec) changes, so
33
+ resizing rescales the shape.
34
+
35
+ Because it's a plain path with a generated `d`, every renderer (DOM/Canvas/SVG),
36
+ raster export, and embed handles it with no special cases. In the editor, a
37
+ parametric shape shows the box + resize handles (not per-vertex control points) so
38
+ it resizes as a unit.
39
+
40
+ ## Limitations / later
41
+
42
+ - Corner rounding and per-vertex editing aren't offered for parametric shapes
43
+ (convert intent is a plain path if you need free vertices).
44
+ - Grid size / rotation snapping apply as they do for any element.