@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
package/README.md CHANGED
@@ -61,7 +61,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
61
61
  - **The drawing hand** - `drawnPathTarget()` draws a sketched stroke on from a `draw` track while a cartoon hand holds the pencil at its end in a writing grip; the same hand can hold the eraser. `handAt()` gives one hand for a whole scene: it follows each stroke, lifts and glides to the next, and enters and leaves the page
62
62
  - **Erasing** - An eraser rubs out part of a target (`erasable()`, animated by an `erase` track) or of anything drawn in code (`withErased()`); clip-based, so it works in the browser and headless alike
63
63
  - **Cartoon hands** - A hand rig in 3D, drawn flat: thumb and fingers posed by numbers (`index.curl`, `thumb.across`, `spread`, `turn`), ready-made shapes (fist, point, thumbs-up, peace, OK, pinch, wave, pencil grip…), left and right, four or five fingers, in every look; the animator's hand and (opt-in) character gloves are built on it. See [docs/cartoon-hands.md](docs/cartoon-hands.md)
64
- - **Cartoon acting** - `actTracks()` turns the same key poses into acted motion: wind-ups, overshoot that settles or wobbles, joints that overlap (hips lead, wrists drag), eyes that dart ahead and blink on head turns, moving holds and jump squash, in `full`, `snappy` or `limited` styles. Gags come as data (`gag('take')`, double take, wind-up, tremble). A line of action (`bend`) curves the spine, and gaits have personality (bouncy, double bounce, sneak, strut, tired, run). Lip-sync works from text, Latin or Devanagari. `scriptTracks()` compiles a story written as beats (`{ do: 'walk', to: 640 }`, `{ do: 'take' }`, `{ do: 'say', say: '…' }`) into all of it. `cameraTracks()` films it with push-ins, cuts, shakes and follows. The cartoon zip (`{ do: 'zip' }`) has the legs wheel in place before it is gone. In the editor, a Character's **Acting** section acts its keyed poses in a style and adds gags, walks in a gait and lip-synced lines, with drawing on twos as a timeline setting. It also adds speed lines from earlier frames (`drawStickSmear()`), dust puffs, impact stars, and drawing on twos for video (`drawingRate`). Output is plain keyframes. See [docs/acting.md](docs/acting.md)
64
+ - **Cartoon acting** - `actTracks()` turns the same key poses into acted motion: wind-ups, overshoot that settles or wobbles, joints that overlap (hips lead, wrists drag), eyes that dart ahead and blink on head turns, moving holds and jump squash, in `full`, `snappy` or `limited` styles. Gags come as data (`gag('take')`, double take, wind-up, tremble). A line of action (`bend`) curves the spine, and gaits have personality (bouncy, double bounce, sneak, strut, tired, run). Lip-sync works from text, Latin or Devanagari. `scriptTracks()` compiles a story written as beats (`{ do: 'walk', to: 640 }`, `{ do: 'take' }`, `{ do: 'say', say: '…' }`) into all of it. `cameraTracks()` films it with push-ins, cuts, shakes and follows. The cartoon zip (`{ do: 'zip' }`) has the legs wheel in place before it is gone. Figures can act on code, Animator vs Animation style: `codePanel()` lays a listing out so every line and word is a place in the scene, and beats leap onto lines, point at them and swipe them away (`{ do: 'swipe', target: code.line(7) }`), with the line wiped, knocked off the panel or blurred out of focus on the frames the hand crosses it. Words come loose too: a figure grabs `var` and throws it, kicks another out of a loop, carries a stray `;` to where it belongs, pushes a word along its line (the text closing up behind it), and writes `mut` into a line by hand. A figure standing on a line rides it when a gap above closes (`code.ride()`). In the editor, a Character's **Acting** section acts its keyed poses in a style and adds gags, walks in a gait and lip-synced lines, with drawing on twos as a timeline setting. Characters come in builds (slim, kid, broad, curvy, stocky), and the v2 human has its own line of action, gaits and gags, posed in 3D so they read from every view. It also adds speed lines from earlier frames (`drawStickSmear()`), dust puffs, impact stars, and drawing on twos for video (`drawingRate`). Output is plain keyframes. See [docs/acting.md](docs/acting.md)
65
65
  - **Pencil story example** - `examples/pencil-story-hindi/index.html` tells a short Hindi story (प्यासा राहगीर, the thirsty traveller) Pencilmation-style with the browser bundle alone: the hand draws the scene and writes the narration, then rubs out the pot
66
66
  - **Captions** - `toSRT()` / `toWebVTT()` from narration cues or from a timeline's markers
67
67
 
@@ -140,6 +140,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
140
140
  ## Documentation
141
141
 
142
142
  - [Getting Started](docs/getting-started.md) — Installation, setup, and your first animation
143
+ - [Building Animations with an LLM](docs/llm-guide.md) — The capability catalog, `describeTarget`, did-you-mean checks for beats and tracks, rendering stills to look at, and the agent skill
143
144
  - [Editor Guide](docs/editor-guide.md) — Complete guide to the visual editor (elements, timeline, scenes, presets, shortcuts)
144
145
  - [API Reference](docs/api-reference.md) — Full engine, player, adapter, and export API documentation
145
146
  - [File Format](docs/file-format.md) — The tinyfly JSON format (animation documents, timelines, projects, sequences) for integrations
@@ -154,7 +155,7 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
154
155
 
155
156
  **Feature guides:** [Symbols & Library](docs/symbols-and-library.md) · [Camera](docs/camera.md) · [Polygon & Star](docs/polygon-star.md) · [Pen tool](docs/pen-tool.md) · [Shape morph](docs/shape-morph.md) · [Grid & snapping](docs/grid-and-snapping.md) · [Onion skinning](docs/onion-skinning.md) · [Sprite-sheet export](docs/sprite-sheet-export.md)
156
157
 
157
- **Docs for LLMs:** the repo root has [`llms.txt`](llms.txt), an [llmstxt.org](https://llmstxt.org) index of these docs. The built editor also serves `/llms.txt`, `/llms-full.txt` (every doc in one file) and each page as raw markdown at `/docs/<page>.md`.
158
+ **Docs for LLMs:** the repo root has [`llms.txt`](llms.txt), an [llmstxt.org](https://llmstxt.org) index of these docs, and [`llms-full.txt`](llms-full.txt): every doc, the course, and the capability catalog in one file. Both ship in the npm package with the docs and an agent skill (`skills/tinyfly/SKILL.md`), so an assistant finds them in `node_modules` at the installed version. `npx @algorisys/tinyfly capabilities` prints the catalog: every pose, expression, gag, gait, beat action, canvas property and code-panel edit, read from the library, so a name in it is accepted and a name not in it is rejected with the name probably meant (`tinyfly check beats.json`, `checkTracks`). The built editor also serves `/llms.txt`, `/llms-full.txt` and each page as raw markdown at `/docs/<page>.md`.
158
159
 
159
160
  ## Installation
160
161
 
@@ -236,7 +237,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
236
237
  itself.
237
238
 
238
239
  ```html
239
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.91.0/cdn/tinyfly.iife.js"></script>
240
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js"></script>
240
241
  <script>
241
242
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
242
243
 
@@ -272,7 +273,7 @@ A teaching figure needs no code at all:
272
273
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
273
274
  <figcaption>Appending to a full slice</figcaption>
274
275
  </figure>
275
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.91.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
276
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
276
277
  ```
277
278
 
278
279
  See [Teaching Animations](docs/teaching.md).
@@ -371,7 +372,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
371
372
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
372
373
  </div>
373
374
 
374
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.91.0/cdn/tinyfly-player.iife.js"></script>
375
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly-player.iife.js"></script>
375
376
  <script>
376
377
  tinyfly.play('#animation', './animation.json', { loop: -1 })
377
378
  </script>
@@ -480,7 +481,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
480
481
  <svg viewBox="0 0 720 200">…</svg>
481
482
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
482
483
  </figure>
483
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.91.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
484
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
484
485
  ```
485
486
 
486
487
  ### Audio / Video Sync
package/bin/tinyfly.mjs CHANGED
@@ -2,6 +2,18 @@
2
2
  /**
3
3
  * tinyfly command line.
4
4
  *
5
+ * tinyfly capabilities [--json]
6
+ * Print everything tinyfly can do, read from the library itself: easings,
7
+ * track kinds, what every shape animates, the stick figure's joints,
8
+ * poses, expressions, gags, gaits, beat actions, dances and flips, and the
9
+ * code panel's languages and edits. Read it before writing an animation
10
+ * (it is what a language model should read). --json prints it as data.
11
+ *
12
+ * tinyfly check <beats.json>
13
+ * Check a beat script (an array of beats, or { "beats": [...] }) before
14
+ * compiling it: unknown actions, moods, joints and fields are errors that
15
+ * name what was probably meant. Exit 1 on errors.
16
+ *
5
17
  * tinyfly validate <timeline.json> [<timeline.json> …] [--markup <figure.svg|.html>]
6
18
  * Exit 1 when the timeline has errors: tracks aimed at elements the markup
7
19
  * lacks, markers out of order or outside the animation, keyframes past an
@@ -69,6 +81,8 @@ function listFlag(name) {
69
81
  const usage = () => {
70
82
  console.error(
71
83
  'Usage:\n' +
84
+ ' tinyfly capabilities [--json]\n' +
85
+ ' tinyfly check <beats.json>\n' +
72
86
  ' tinyfly validate <timeline.json> [<timeline.json> …] [--markup <file>]\n' +
73
87
  ' tinyfly render <timeline.json> <markup file> [--at start|end|<ms>|<marker id>]\n' +
74
88
  ' tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,…>] [--loop-check]\n' +
@@ -86,7 +100,26 @@ const readJson = (file) => {
86
100
  }
87
101
  }
88
102
 
89
- if (command === 'validate') {
103
+ if (command === 'capabilities') {
104
+ const json = has('--json')
105
+ const characters = await import('../lib/addons/characters.js')
106
+ const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
107
+ process.stdout.write(json ? `${JSON.stringify(characters.capabilities(version), null, 2)}\n` : characters.capabilitiesMarkdown(version))
108
+ } else if (command === 'check') {
109
+ const [beatsFile] = rest
110
+ if (!beatsFile) usage()
111
+ const data = readJson(beatsFile)
112
+ const beats = Array.isArray(data) ? data : data?.beats
113
+ const { checkBeats } = await import('../lib/addons/characters.js')
114
+ const problems = checkBeats(beats)
115
+ for (const problem of problems) console.error(`${problem.level}: ${problem.beat >= 0 ? `beat ${problem.beat}: ` : ''}${problem.message}`)
116
+ const errors = problems.filter((problem) => problem.level === 'error').length
117
+ if (errors > 0) {
118
+ console.error(`${beatsFile}: ${errors} error(s)`)
119
+ process.exit(1)
120
+ }
121
+ console.error(`${beatsFile}: ok${problems.length ? ` (${problems.length} warning(s))` : ''}`)
122
+ } else if (command === 'validate') {
90
123
  const markupFile = flag('--markup')
91
124
  const timelineFiles = rest
92
125
  if (timelineFiles.length === 0) usage()
@@ -0,0 +1,191 @@
1
+ # 2D Animation Roadmap — Adobe Animate gap analysis & plan
2
+
3
+ **Status:** Planning (no implementation yet)
4
+ **Date:** 2026-07-08
5
+
6
+ This document captures a gap analysis of tinyfly against a full Adobe Animate
7
+ "Complete 2D Animation Course" workflow, and a phased plan for the features and
8
+ UX worth pursuing. It is a living plan — we will implement from it over time.
9
+
10
+ ---
11
+
12
+ ## Positioning (read this first)
13
+
14
+ tinyfly is a **property-animation engine**: you place objects and animate their
15
+ properties over time via keyframe tracks (After Effects / GSAP style), with a
16
+ JSON-first, inspectable, framework-agnostic core.
17
+
18
+ Adobe Animate is a **drawing + rigging studio**: you draw pictures (often frame
19
+ by frame), rig them with bones, and tween them.
20
+
21
+ **Roughly 60% of a "complete Animate course" is a different product category.**
22
+ Matching all of it would break tinyfly's "GSAP-level power with Excalidraw-level
23
+ simplicity" identity and is a multi-year effort. The plan below deliberately
24
+ separates **on-brand wins** from **out-of-scope** studio features.
25
+
26
+ ---
27
+
28
+ ## What the reference course covers
29
+
30
+ Freehand drawing (brush / pencil / shapes / pen), fills / strokes / gradients,
31
+ transform (skew / rotate / free-transform), align & distribute, **symbols +
32
+ Library** (convert-to-symbol, instances), **frame-by-frame** animation,
33
+ motion / classic / **shape tweens**, **onion skinning**, **bone rigging / IK**,
34
+ **lip-sync** (mouth-shape swapping), character design & turnarounds,
35
+ background / scene composition, a **camera**, motion blur / speed lines, and
36
+ publishing (video / GIF / HTML5).
37
+
38
+ ---
39
+
40
+ ## Gap map
41
+
42
+ | Capability | tinyfly today | Verdict |
43
+ |---|---|---|
44
+ | Property tweens (move/scale/rotate/opacity/color…) | ✅ Full (tracks, easing, custom curve editor) | Core strength |
45
+ | Motion path, filters, clip/mask reveal, shine | ✅ | Strong |
46
+ | Multi-scene, transitions, sequencer | ✅ | Strong |
47
+ | Per-letter text, typewriter | ✅ | Strong |
48
+ | Audio/video elements + sync (editor & embed) | ✅ | Strong |
49
+ | Shape / path morph (shape tween) | ⚠️ Partial — can animate path `d`; no morph tooling | Enhance |
50
+ | Export | ⚠️ CSS / Lottie / GIF only | Add video / sprite |
51
+ | **Symbols + Library (reusable instances)** | ❌ (only flat groups) | **Do — #1** |
52
+ | **Camera (pan / zoom / rotate the scene)** | ❌ | **Do** |
53
+ | Onion skinning | ❌ | Do (small) |
54
+ | Drawing tools (pen / pencil, polygon / star) | ❌ (path element + editor, but no create-tool) | Partial-do |
55
+ | Guides / grid / rulers / object snapping | ❌ | UX polish |
56
+ | Bone rig / IK / armature | ❌ | Out of scope (or long-term "pivot rig") |
57
+ | Frame-by-frame drawing paradigm | ❌ (conflicts with the track model) | Skip |
58
+ | Natural-media brush studio, model-sheet tooling | ❌ | Skip |
59
+
60
+ ---
61
+
62
+ ## Phased plan (on-brand)
63
+
64
+ ### Phase A — Reuse & structure (highest leverage)
65
+
66
+ 1. **Symbols + Library** — a symbol is a group with its own nested timeline,
67
+ instanceable multiple times; edit-once-update-everywhere; fully
68
+ JSON-serializable. Unlocks reuse, complex compositions, and a **lightweight
69
+ lip-sync** (swap which symbol/instance shows per keyframe) without a bone
70
+ system. This is the biggest, most on-brand win.
71
+ - Data model: `SymbolDefinition { id, name, elements, timeline }`; instances
72
+ reference a symbol id + an instance transform/override.
73
+ - UI: a Library panel; "Convert to Symbol"; place instances; edit-in-place.
74
+ - Engine: instances expand to their nested timeline at play time; still JSON.
75
+
76
+ ### Phase B — Cinematography & polish
77
+
78
+ 2. **Camera** — a virtual camera whose pan / zoom / rotate animates the whole
79
+ stage. It is just an animated transform on the scene container — very
80
+ on-brand, big demo value.
81
+ 3. **Onion skinning** — ghost the previous / next frames in the preview. Small,
82
+ high-delight.
83
+ 4. **Guides, grid, rulers, object snapping** — editor UX the course leans on
84
+ constantly.
85
+
86
+ ### Phase C — Authoring & output
87
+
88
+ 5. **Drawing tools** — a **pen tool** (author bezier paths on canvas; reuse the
89
+ existing path editor), plus **polygon / star** primitives and a
90
+ freehand → simplified-path tool. Stops short of a full brush studio.
91
+ 6. **Shape-tween tooling** — a proper morph between two path shapes.
92
+ 7. **Export expansion** — **video (WebM / MP4)** and **sprite-sheet / PNG
93
+ sequence** (build on the existing GIF frame-capture plumbing).
94
+
95
+ ---
96
+
97
+ ## Deliberately out of scope
98
+
99
+ To protect the product's identity, we are **not** pursuing:
100
+
101
+ - Bone / IK rigging and armatures (different domain, very complex). If rigging is
102
+ ever wanted, do a **simplified** version: parent / pivot hierarchies on groups,
103
+ not full IK.
104
+ - Frame-by-frame drawing paradigm (conflicts with the property-track model).
105
+ - Natural-media brushes / paint studio.
106
+ - Character-design / model-sheet tooling.
107
+
108
+ ---
109
+
110
+ ## Recommended starting point
111
+
112
+ Begin with **Phase A: Symbols + Library**. It is the one item that is both a real
113
+ Animate gap *and* deeply on-brand (nested JSON timelines), and it retroactively
114
+ enables lip-sync-style workflows without a bone system. **Camera** and **onion
115
+ skinning** are the fast, flashy follow-ups.
116
+
117
+ ---
118
+
119
+ ## UI / interaction plan (Animate parity, tinyfly-flavoured)
120
+
121
+ > **Note (added 2026-07-22):** this section plans the *editor UI* for each phase.
122
+ > Guiding rule: **Excalidraw-level simplicity** — every new surface must be
123
+ > loosely coupled to the engine, discoverable, and skippable. No modal-heavy,
124
+ > panel-explosion Animate clone. Studio-grade features live behind an optional
125
+ > **"Studio" mode** badge so the default editor stays approachable.
126
+
127
+ ### Cross-cutting UI principles
128
+
129
+ - **One codebase, tiered UI.** Advanced tools (Library, Camera, onion skin,
130
+ guides, pen) surface progressively; a `Studio mode` toggle can reveal the
131
+ denser controls. Marketing may call the pro workflow *"tinyflash"*, but it is
132
+ the same app.
133
+ - **Reuse existing surfaces.** New capabilities extend the current header,
134
+ left/right collapsible panels, timeline panel, and preview overlay rather than
135
+ adding new windows.
136
+ - **Everything stays JSON + API-first.** Each UI action maps to a documented
137
+ store/engine call; the editor remains just one consumer.
138
+
139
+ ### Phase A — Symbols + Library (UI)
140
+
141
+ - **Library panel** — a new collapsible section in the **left** sidebar (tab
142
+ alongside Elements/Tracks): a grid of symbol thumbnails with name, instance
143
+ count, and a search box. Drag a symbol onto the stage to place an instance;
144
+ double-click to **edit in place** (breadcrumb: `Scene ▸ SymbolName`).
145
+ - **Convert to Symbol** — a command on the selection (context menu + `Ctrl+K`)
146
+ that bundles the selected elements into a reusable symbol and replaces them
147
+ with an instance.
148
+ - **Instance properties** — the right **Property Panel** gains an "Instance"
149
+ section: transform overrides (x/y/scale/rotation/opacity), a **symbol swap**
150
+ dropdown (the lip-sync primitive), and an "Edit Symbol" button.
151
+ - **Nested timeline** — when editing a symbol, the bottom **Timeline** shows the
152
+ symbol's own tracks; a breadcrumb returns to the scene. The instance's timeline
153
+ in the parent scene controls *its* transform, not the symbol's internals.
154
+ - **Serialization** — `project.symbols: SymbolDefinition[]`; scene elements gain
155
+ a `symbol` type referencing `symbolId`.
156
+
157
+ ### Phase B — Camera, onion skinning, guides (UI)
158
+
159
+ - **Camera** — a **Camera** toggle in the preview header adds an on-stage camera
160
+ frame (drag to pan, corner handles to zoom, a rotate handle). Camera state is a
161
+ single animated transform track (`camera.x/y/zoom/rotation`) shown as a special
162
+ row at the top of the timeline. A "Reset camera" and "fit" control included.
163
+ - **Onion skinning** — a preview-header toggle with a small popover: how many
164
+ before/after frames, opacity falloff, and outline-vs-ghost mode. Ghosts render
165
+ in the preview only.
166
+ - **Guides / grid / rulers / snapping** — a **View** menu (or preview-header
167
+ cluster): toggle grid, rulers, snapping; drag guides off the rulers; snap to
168
+ guides / grid / other objects with a live snap indicator.
169
+
170
+ ### Phase C — Drawing, shape-tween, export (UI)
171
+
172
+ - **Pen / shape tools** — extend the left toolbar with a **Pen** (author bezier
173
+ paths point-by-point on the canvas, reusing the path editor), **Polygon/Star**
174
+ primitives (sides/points inspector), and a freehand → simplified-path tool.
175
+ - **Shape-tween** — select two path keyframes and "Create Shape Tween"; a small
176
+ morph inspector (matching hints / point count). Preview shows the interpolated
177
+ `d`.
178
+ - **Export expansion** — the existing Export dialog gains **sprite-sheet /
179
+ PNG-sequence** output alongside the current GIF/WebP/MP4.
180
+
181
+ ### UI risks & mitigations
182
+
183
+ - **Panel overload** → keep advanced panels collapsed by default and behind
184
+ Studio mode; lean on the existing collapsible-sidebar system.
185
+ - **Edit-in-place confusion** → always show a breadcrumb and a dimmed parent
186
+ scene while inside a symbol.
187
+ - **Mobile/touch** → symbols/library are desktop-first; degrade gracefully (view
188
+ + place, edit on larger screens).
189
+
190
+ See [symbols-and-library.md](symbols-and-library.md) for the detailed Phase A
191
+ data model and implementation plan.
@@ -0,0 +1,164 @@
1
+ # 3D Transforms and Rotations
2
+
3
+ Flat things (cards, images, text, shapes) can turn in 3D, move toward you and
4
+ be seen in perspective, the way CSS 3D transforms work, and they land on the
5
+ same pixels in every renderer: DOM, SVG, Canvas and WebGL. Rotations can be
6
+ **quaternions**, `[x, y, z, w]`, on a track that says `interpolation: "slerp"`,
7
+ which turn from any orientation to any other without gimbal lock. These are the
8
+ first steps of [3D support](3d-support-plan.md): the engine stays
9
+ renderer-agnostic and gains only small math helpers and one interpolation mode.
10
+
11
+ Try it on the Examples page: **Quaternion vs Euler (3D rotation)**, **3D Card
12
+ Flip** and **Cover Flow**.
13
+
14
+ ## The 3D properties
15
+
16
+ | Property | Value | Meaning |
17
+ |---|---|---|
18
+ | `rotateX`, `rotateY` | degrees | Turn about the horizontal / vertical axis (`rotate` / `rotateZ` turns in the picture) |
19
+ | `z` | px | Toward the viewer; shows with perspective |
20
+ | `perspective` | px | The element's own `perspective()`: its distance from the viewer. Smaller is stronger; none is flat |
21
+ | `quaternion` | `[x, y, z, w]` | A whole rotation, on a track with `interpolation: "slerp"` (below) |
22
+ | `backfaceVisibility` | `"visible"` / `"hidden"` | Hidden: not drawn while its back faces you (two of them make a two-sided card) |
23
+ | `childPerspective`, `perspectiveOriginX`, `perspectiveOriginY` | px, % | DOM only: CSS `perspective` on a parent, so its children share one vanishing point |
24
+ | `transformStyle` | `"preserve-3d"` | DOM only: children keep their own depth inside the parent |
25
+
26
+ ```js
27
+ const flip = [
28
+ { id: 'p', target: 'card', property: 'perspective', keyframes: [{ time: 0, value: 600 }] },
29
+ { id: 'b', target: 'card', property: 'backfaceVisibility', keyframes: [{ time: 0, value: 'hidden' }] },
30
+ { id: 'r', target: 'card', property: 'rotateY', keyframes: [{ time: 0, value: 0 }, { time: 1000, value: 180, easing: 'ease-in-out' }] },
31
+ ]
32
+ ```
33
+
34
+ ### One transform order
35
+
36
+ Whatever order the tracks were added in, every adapter composes an element's
37
+ transform in the same order, about its transform origin (`originX` /
38
+ `originY`, the centre by default):
39
+
40
+ ```
41
+ perspective → translate (x, y, z) → rotate → rotateX → rotateY → quaternion → scale → skew
42
+ ```
43
+
44
+ as a CSS transform list (the right-most applies to the element first). So an
45
+ element is skewed and scaled in its own plane, turned, then moved, and seen in
46
+ perspective last. `scale` wins over `scaleX` / `scaleY` in SVG, Canvas and
47
+ WebGL.
48
+
49
+ ### In each renderer
50
+
51
+ - **DOM and SVG:** the browser's own CSS 3D.
52
+ - **Canvas:** the same 4×4 matrix. Without perspective its x / y part is an
53
+ exact 2D transform; with perspective the target is drawn through a mesh of
54
+ small triangles, each a 2D transform of its own, overlapping by a pixel so no
55
+ seam shows. See-through targets in perspective go through one offscreen
56
+ layer, so the overlaps do not darken. It works in Node too (headless video).
57
+ - **WebGL:** the same matrix per quad, with the perspective in `w`, so textures
58
+ stay perspective-correct.
59
+
60
+ The cross-browser checks (`npm run e2e -- --check transforms-3d`) put one card
61
+ through all of them in Chromium, Firefox and WebKit: the projection maths
62
+ matches the browser's CSS exactly, and Canvas and WebGL land within a pixel.
63
+
64
+ ### In the editor
65
+
66
+ Every element has a **3D** section under Transform: **Tilt X**, **Turn Y**,
67
+ **Depth** and **Perspective** at the playhead. Typing a value keys it there, so
68
+ a card flip is two keys on Turn Y. Every preview renderer and every export
69
+ (GIF, MP4, video) draws them.
70
+
71
+ ## Why not just rotateX, rotateY and rotateZ?
72
+
73
+ Euler angles (`rotateX`, `rotateY`, `rotateZ`) are easy to type and still work
74
+ everywhere. But each angle is animated on its own, so going from one
75
+ orientation to another can take a strange path, tumbling about two axes, and
76
+ near straight up or down two of the axes line up and a turn is lost (gimbal
77
+ lock). A quaternion describes the whole orientation at once, and **slerp**
78
+ (spherical interpolation) turns from one to the other about a single axis, the
79
+ short way round, at a steady speed.
80
+
81
+ ```js
82
+ import { Timeline, quat } from '@algorisys/tinyfly'
83
+
84
+ const timeline = new Timeline({
85
+ id: 'flip',
86
+ tracks: [
87
+ {
88
+ id: 'turn',
89
+ target: 'card',
90
+ property: 'quaternion',
91
+ interpolation: 'slerp',
92
+ keyframes: [
93
+ { time: 0, value: quat.identity() },
94
+ { time: 2000, value: quat.fromEuler(0, 180, 180), easing: 'ease-in-out' },
95
+ ],
96
+ },
97
+ ],
98
+ })
99
+ ```
100
+
101
+ Easing shapes the turn as it shapes any value; eases that overshoot (back,
102
+ elastic) carry on along the same arc. When a timeline is exported to a format
103
+ that needs baking (CSS, Lottie), the samples follow the arc too.
104
+
105
+ ## Drawing it
106
+
107
+ - **DOM:** the DOM adapter draws a `quaternion` value as a CSS `matrix3d()`.
108
+ Give the parent `perspective` and the element `transform-style: preserve-3d`
109
+ as for any CSS 3D transform.
110
+ - **Anything else:** `mat4.fromQuat(q)` is the rotation matrix, column-major,
111
+ ready for WebGL, a `matrix3d()` string or your own renderer.
112
+
113
+ ```js
114
+ const q = timeline.getStateAtTime(t).values.get('card').get('quaternion')
115
+ card.style.transform = `matrix3d(${mat4.fromQuat(q).join(', ')})`
116
+ ```
117
+
118
+ ## The math helpers
119
+
120
+ Plain arrays in, plain arrays out, no state: `vec3`, `quat` and `mat4`.
121
+
122
+ | | |
123
+ |---|---|
124
+ | Axes | right-handed, +y up, +z toward the viewer |
125
+ | Angles | degrees |
126
+ | Euler order | **YXZ** (yaw, pitch, roll): `quat.fromEuler(x, y, z)` turns as CSS `rotateY(y) rotateX(x) rotateZ(z)` |
127
+ | Quaternions | `[x, y, z, w]` (glTF order), unit length |
128
+ | Matrices | 16 numbers, column-major (WebGL, glTF, CSS `matrix3d()`); `multiply(a, b)` applies `b` first |
129
+
130
+ ```js
131
+ import { quat, mat4, vec3 } from '@algorisys/tinyfly'
132
+
133
+ const tilt = quat.fromEuler(20, 45, 0)
134
+ quat.toEuler(tilt) // [20, 45, 0]
135
+ quat.rotateVec3(tilt, [0, 0, 1]) // where "forward" points now
136
+ const model = mat4.compose([0, 1, 0], tilt, [1, 1, 1])
137
+ const view = mat4.lookAt([0, 2, 6], [0, 1, 0])
138
+ const projection = mat4.perspective(50, 16 / 9, 0.1, 100)
139
+ mat4.transformPoint(mat4.multiply(projection, mat4.multiply(view, model)), [0, 0, 0])
140
+ ```
141
+
142
+ The full list is in the [API reference](api-reference.md#3d-math).
143
+
144
+ ## In the file format
145
+
146
+ A file that uses `interpolation` is written as **format version 2**, so an
147
+ older tinyfly refuses it with a clear message instead of blending the four
148
+ numbers one by one. Files without it stay at version 1 and open everywhere.
149
+ See [the file format](file-format.md#rotation-tracks-interpolation-slerp).
150
+
151
+ ## Limits
152
+
153
+ - Elements are flat: each is turned and seen on its own (its own
154
+ perspective), not sorted by depth against others; they draw in layer order.
155
+ Real 3D scenes (cameras, lights, meshes, depth) are the next milestones.
156
+ - In the editor, back faces are set with a `backfaceVisibility` track (the
157
+ 3D Card Flip sample shows how); there is no checkbox yet.
158
+
159
+ - Springs and inertia stay numeric: use them on `rotateX` and friends, not on
160
+ `quaternion` tracks.
161
+ - Use either Euler tracks or a quaternion track for one element's rotation,
162
+ not both.
163
+ - 3D scenes (cameras, lights, meshes) are the next milestones of the
164
+ [3D plan](3d-support-plan.md).