@algorisys/tinyfly 0.92.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 (61) 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 +2694 -1809
  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 +6498 -5483
  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 +3 -0
  54. package/lib/types/characters/stick-figure.d.ts +2 -0
  55. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  56. package/lib/types/engine/authoring/index.d.ts +1 -0
  57. package/llms-full.txt +12548 -0
  58. package/llms.txt +57 -0
  59. package/package.json +6 -2
  60. package/skills/tinyfly/SKILL.md +64 -0
  61. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,314 @@
1
+ # Getting Started with tinyfly
2
+
3
+ Welcome! **tinyfly** is a free, open-source tool for making animations right in
4
+ your browser — then using them anywhere (a website, an app, or as a GIF / video
5
+ file). You don't need to be a programmer to use the editor. This guide walks you
6
+ from "never opened it" to "made and exported your first animation."
7
+
8
+ > **In a hurry?** Open the editor → click **Examples** → **Open in editor** on one → press **Play**.
9
+ > That's the 30-second version. The rest of this page slows it down.
10
+
11
+ ---
12
+
13
+ ## 1. Open the editor
14
+
15
+ If someone has given you a link to a hosted version, just open it — nothing to
16
+ install.
17
+
18
+ To run it on your own machine you need [Node.js](https://nodejs.org) (version 18
19
+ or newer). Then:
20
+
21
+ ```bash
22
+ git clone https://github.com/algorisys-oss/tinyfly.git
23
+ cd tinyfly
24
+ npm install # one-time setup
25
+ npm run dev # start the editor
26
+ ```
27
+
28
+ Open the address it prints (usually **http://localhost:5173**). That is the
29
+ tinyfly home page; the editor is at **/studio** (or click **Open the editor**), and a
30
+ hands-on course at **/learn** teaches the code API step by step.
31
+ Nothing you make is uploaded anywhere — it all lives in your browser.
32
+
33
+ ---
34
+
35
+ ## 2. The editor at a glance
36
+
37
+ When it opens, here's what you're looking at:
38
+
39
+ ```
40
+ ┌─────────────────────────────────────────────────────────────┐
41
+ │ tinyfly BETA [Save] New AI My Animations Examples Export More │ ← top toolbar
42
+ ├─────────────────────────────────────────────────────────────┤
43
+ │ Describe an animation… [ Generate ] │ ← AI prompt bar (click AI)
44
+ ├────────────┬───────────────────────────────┬────────────────┤
45
+ │ Elements │ │ Properties │
46
+ │ Tracks │ Preview (the stage) │ Presets │ ← side panels
47
+ │ (left) │ │ (right) │
48
+ ├────────────┴───────────────────────────────┴────────────────┤
49
+ │ ▶ Play 0.00 / 2.00 ───●─────────────── │ ← playback
50
+ ├─────────────────────────────────────────────────────────────┤
51
+ │ [ Dope Sheet | Curves ] Timeline / keyframes │ ← timeline
52
+ └─────────────────────────────────────────────────────────────┘
53
+ ```
54
+
55
+ - **Preview (the stage)** — where your animation plays.
56
+ - **Elements / Tracks (left)** — the shapes on the stage, and the list of things
57
+ being animated. You can **hide this panel** with the `«` button to get more room.
58
+ - **Properties / Presets (right)** — edit the selected shape or keyframe, and
59
+ apply one-click animation presets. Also collapsible.
60
+ - **Timeline (bottom)** — the heart of it: a ruler of time with **keyframes**
61
+ (diamonds) marking values at moments in time. Two views: **Dope Sheet** (timing)
62
+ and **Curves** (the shape of the motion). More on these below.
63
+ - **Playback bar** — Play/pause, the current time, and a scrubber you can drag.
64
+
65
+ ---
66
+
67
+ ## 3. The fastest first win: open an example
68
+
69
+ The quickest way to *feel* how it works:
70
+
71
+ 1. Click **Examples** in the toolbar. Hover over a card to watch it play.
72
+ 2. On one you like (try "Fade In/Out" or a Showcase demo), click **Open in editor**.
73
+ It opens as a new project, so nothing you already made is touched.
74
+ 3. Press the big **▶ Play** button.
75
+
76
+ Watch the diamonds on the timeline and the shape on the stage move together.
77
+ Drag the scrubber back and forth to "scrub" through time. Congrats — that's an
78
+ animation.
79
+
80
+ You can also click **My Animations** to see every project you've made (each is
81
+ saved automatically), or click **AI**, type a sentence in the prompt bar (e.g.
82
+ *"a title that fades up with a shine"*) and click **Generate** to have AI build
83
+ one for you.
84
+
85
+ ---
86
+
87
+ ## 4. Make one from scratch
88
+
89
+ Let's build a simple "fade and slide in" by hand.
90
+
91
+ **Step 1 — Add a shape.** In the left **Elements** panel, add a **Rectangle**
92
+ (or Circle). It appears on the stage. Drag it where you want, or set exact
93
+ position/size in the **Properties** panel on the right.
94
+
95
+ **Step 2 — Add something to animate (a track).** In the **Tracks** panel, click
96
+ **+**. Type the shape's name (as shown in the Elements panel) as the **Target**, and
97
+ the property to animate as the **Property** — start with **opacity** (how
98
+ see-through it is). Then click **Add Track**.
99
+
100
+ **Step 3 — Place keyframes.** A **keyframe** says "at *this* time, the value is
101
+ *this*." On the timeline, **double-click** the track to drop a keyframe, then
102
+ select it and set its value in the Properties panel. Make two:
103
+
104
+ - At **0 ms**: opacity = **0** (invisible)
105
+ - At **500 ms**: opacity = **1** (fully visible)
106
+
107
+ Add an **x** (horizontal position) track the same way to make it slide in:
108
+
109
+ - At **0 ms**: x = **-50**
110
+ - At **500 ms**: x = **60**
111
+
112
+ **Step 4 — Play it.** Press **▶**. Your shape fades and slides in. Between the
113
+ two keyframes, tinyfly fills in every in-between value automatically — that's
114
+ *interpolation*.
115
+
116
+ **Step 5 — Make the motion feel nice (easing).** Right now the motion is a
117
+ straight, robotic ramp. Select the keyframe at 500 ms and give it an **easing**
118
+ like `ease-out` (fast then settling). Prefer to *see* it? Switch the timeline to
119
+ the **Curves** view (top-left of the timeline): each track becomes a line showing
120
+ its value over time, and you can drag the **amber handles** to shape the motion
121
+ by eye.
122
+
123
+ **Step 6 — Save & name it.** tinyfly auto-saves as you go (the **Saved ✓** badge
124
+ confirms it). **Double-click the title** in the toolbar to rename your project.
125
+ On a tablet, tap **Save** any time for peace of mind.
126
+
127
+ **Step 7 — Export.** Click **Export** to download a **GIF**, **WebP**, an **MP4**
128
+ (or WebM) video, a sprite sheet, or **CSS** / **Lottie** code. The **More** menu
129
+ has **Embed…** for copy-paste HTML for a website, and **Export JSON** to save the
130
+ raw animation as a `.json` file you can re-import later with **Import JSON…**.
131
+ **Export Animation Document** saves the elements together with the tracks, for
132
+ apps that rebuild the shapes themselves, such as YappyDraw.
133
+
134
+ That's the whole loop: **add → animate → ease → play → export.**
135
+
136
+ ---
137
+
138
+ ## 5. The five ideas behind everything
139
+
140
+ Once these click, the rest of tinyfly makes sense.
141
+
142
+ | Idea | What it is |
143
+ |------|-----------|
144
+ | **Timeline** | The clock for one animation. It plays, pauses, loops, and holds all the tracks. |
145
+ | **Track** | One property of one shape being animated (e.g. *this circle's opacity*). |
146
+ | **Keyframe** | A value pinned at a moment in time — a diamond on the timeline. |
147
+ | **Easing** | The *feel* of the motion between two keyframes: constant (`linear`), or accelerating/settling (`ease-in`, `ease-out`, `ease-in-out`, …), or a fully custom curve. |
148
+ | **Element** | A thing on the stage you animate: rectangle, circle, polygon, star, text, image, video, audio, line, arrow, or path. |
149
+
150
+ And two bigger ones:
151
+
152
+ - **Scene** — an independent stage with its own elements and timeline. A project
153
+ can have several scenes with **transitions** (fade, slide) between them — like
154
+ slides in a deck.
155
+ - **Project** — everything together, saved in your browser and listed in **My
156
+ Animations**.
157
+
158
+ ---
159
+
160
+ ## 6. Dope Sheet vs. Curves (the two timeline views)
161
+
162
+ The timeline has a switch at its top-left:
163
+
164
+ - **Dope Sheet** — keyframes as diamonds on a time grid. Best for **timing**:
165
+ when things happen, dragging them earlier/later, copy/paste.
166
+ - **Curves** — each numeric track drawn as a **line of value over time**, with
167
+ the real easing shown between keyframes. Best for **feel**: drag points up/down
168
+ to change values, and drag the easing **handles** to shape acceleration.
169
+
170
+ Both show the same animation — switch anytime. Use **Ctrl/⌘ + scroll** to zoom
171
+ the timeline and the bottom scrollbar (or Shift + scroll) to pan.
172
+
173
+ ---
174
+
175
+ ## 7. For developers: use it from code
176
+
177
+ The editor is optional — the engine is a small, framework-free library. Every
178
+ animation is plain JSON, and everything the editor does, you can do in code.
179
+
180
+ ### Use it in a web page
181
+
182
+ The quickest start needs no build step. Add one script tag and animate elements
183
+ with a GSAP-style call (durations are in seconds here):
184
+
185
+ ```html
186
+ <div class="box" style="width:60px;height:60px;background:#4a9eff"></div>
187
+
188
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.93.0/cdn/tinyfly.iife.js"></script>
189
+ <script>
190
+ tinyfly.to('.box', { x: 200, duration: 1 })
191
+ </script>
192
+ ```
193
+
194
+ In a project with a bundler, the same API is a module import:
195
+
196
+ ```typescript
197
+ import { live } from '@algorisys/tinyfly/gsap-compat'
198
+
199
+ live.to('.box', { x: 200, duration: 1 })
200
+ ```
201
+
202
+ > The package is not on npm yet. Until it is, use the script tag above, or build
203
+ > this repo (`npm run build:libs`) and `npm install /path/to/tinyfly`.
204
+
205
+ See **[GSAP Compatibility](gsap-compat.md)** for everything `live` supports.
206
+
207
+ ### Timelines and adapters
208
+
209
+ Underneath, an animation is a timeline of tracks. Times here are in
210
+ milliseconds:
211
+
212
+ ```typescript
213
+ import { Timeline, createTrack } from '@algorisys/tinyfly'
214
+ import { DOMAdapter } from '@algorisys/tinyfly/adapters'
215
+
216
+ // 1. A timeline that loops forever
217
+ const timeline = new Timeline({ id: 'fade', config: { duration: 1000, loop: -1 } })
218
+
219
+ // 2. Animate the opacity of a target called "box"
220
+ timeline.addTrack(createTrack({
221
+ id: 'opacity',
222
+ target: 'box',
223
+ property: 'opacity',
224
+ keyframes: [
225
+ { time: 0, value: 0 },
226
+ { time: 500, value: 1, easing: 'ease-out' },
227
+ { time: 1000, value: 0, easing: 'ease-in' },
228
+ ],
229
+ }))
230
+
231
+ // 3. Point "box" at a real DOM element and play
232
+ const adapter = new DOMAdapter()
233
+ adapter.registerTarget('box', document.querySelector('#my-box'))
234
+ timeline.onUpdate = (state) => adapter.applyState(state)
235
+
236
+ timeline.play()
237
+ ;(function loop() {
238
+ timeline.tick(16.67) // advance ~1 frame (60fps)
239
+ requestAnimationFrame(loop)
240
+ })()
241
+ ```
242
+
243
+ Prefer to just play an exported file on a web page? Use the tiny player bundle:
244
+
245
+ ```html
246
+ <div id="animation">
247
+ <div data-tinyfly="box"
248
+ style="position:absolute;width:60px;height:60px;background:#4a9eff"></div>
249
+ </div>
250
+
251
+ <script src="tinyfly-player.iife.js"></script>
252
+ <script>
253
+ tinyfly.play('#animation', './animation.json', { loop: -1, autoplay: true })
254
+ </script>
255
+ ```
256
+
257
+ Build the player with `npm run build:player` (outputs
258
+ `lib/player/tinyfly-player.iife.js`).
259
+
260
+ For the exact JSON shape, see the **[File Format](file-format.md)** reference.
261
+
262
+ ---
263
+
264
+ ## Common animatable properties
265
+
266
+ | Property | Meaning |
267
+ |----------|---------|
268
+ | `x`, `y` | Position (px) |
269
+ | `width`, `height` | Size (px) |
270
+ | `rotate` | Rotation (degrees) |
271
+ | `scale`, `scaleX`, `scaleY` | Scale |
272
+ | `opacity` | Transparency (0–1) |
273
+ | `fill`, `stroke` | Colours |
274
+ | `strokeWidth`, `borderRadius` | Border width / corner radius (px) |
275
+ | `blur`, `glow`, `shadowX`/`shadowY`/`shadowBlur` | Filters |
276
+ | `clipTop`/`Right`/`Bottom`/`Left` | Reveal / wipe |
277
+
278
+ The full list is in the [File Format](file-format.md#animatable-properties) doc.
279
+
280
+ ---
281
+
282
+ ## Going further
283
+
284
+ Once you're comfortable, tinyfly has a lot more built in:
285
+
286
+ - **Shapes & drawing** — ⬡ polygons, ★ stars (parametric sides/points), and a
287
+ ✒️ **Pen** tool for custom bezier paths.
288
+ - **🌀 Shape morph** — tween one shape into another over the timeline.
289
+ - **Text tracks** — scramble a text element into new words, or type it on.
290
+ - **Springs and inertia** — physics tracks: a spring settles on a value, an
291
+ inertia track is a throw that slows under friction. Add them from the **+** in
292
+ the Tracks panel.
293
+ - **🎥 Camera** — animate a pan / zoom / rotate over the whole stage (drag to pan
294
+ on stage, or keyframe it in the timeline).
295
+ - **Precision** — ▦ grid, 🧲 snapping, and 📏 rulers with draggable guides.
296
+ - **🧅 Onion skinning** — see ghost frames around the playhead while you edit.
297
+ - **Export** — GIF, WebP, MP4/WebM, a **sprite sheet** (PNG grid + JSON), CSS, or
298
+ Lottie — plus copy-paste **embed** code.
299
+ - **🎬 Video from code** — write a scene in JavaScript and render it to MP4 with
300
+ `npx tinyfly video`, no browser needed: narration timing, code-drawn
301
+ characters, captions and stills. See **[Rendering Video from Code](video-rendering.md)**.
302
+
303
+ Each is covered in the **[Editor Guide](editor-guide.md)**. From code, the same
304
+ features (plus Flip layout transitions and draggable throws) are in
305
+ **[GSAP Compatibility](gsap-compat.md)**.
306
+
307
+ ## Where to next
308
+
309
+ - **[Editor Guide](editor-guide.md)** — every panel, button, and shortcut in depth.
310
+ - **[Examples](examples.md)** — ready-made animations to learn from.
311
+ - **[File Format](file-format.md)** — the JSON behind it all, for integrations.
312
+ - **[GSAP Compatibility](gsap-compat.md)** — the `live.to()` API for web pages.
313
+ - **[API Reference](api-reference.md)** — the full engine/player/adapter API.
314
+ - **[Rendering Video from Code](video-rendering.md)** — whole videos from a script, Cairo-style.
@@ -0,0 +1,64 @@
1
+ # Grid & snapping
2
+
3
+ Line elements up quickly: a toggleable grid overlay plus snapping that pulls a
4
+ dragged element to the grid, to other elements, and to the artboard centre —
5
+ with pink alignment guides that appear as you drag.
6
+
7
+ ## Using it
8
+
9
+ In the **DOM** preview (the editing surface) the header shows two toggles:
10
+
11
+ - **▦ Grid** — overlays a 20px grid on the artboard.
12
+ - **🧲 Snap** — snaps dragged elements (on by default).
13
+
14
+ Drag an element and, when an edge / centre lines up with a snap target within a
15
+ few pixels, it clicks into place and a **pink guide line** shows what it caught.
16
+
17
+ Snapping considers, per axis:
18
+
19
+ - the moving element's **left / centre / right** (and **top / middle / bottom**),
20
+ - against every **other element's** edges and centre,
21
+ - the **artboard** edges and centre,
22
+ - and the **grid** (only while ▦ Grid is on).
23
+
24
+ Grid and snapping are **editor-only** — they never change the animation or the
25
+ saved JSON.
26
+
27
+ ## How it works
28
+
29
+ `src/editor/utils/snap.ts` is pure and unit-tested:
30
+
31
+ ```ts
32
+ snapAxis(movingLines, staticLines, threshold) // → { delta, line }
33
+ gridLinesFor(movingLines, gridSize) // nearest grid multiple per line
34
+ ```
35
+
36
+ The preview (`preview-panel.tsx`) captures the element's bounds at drag start,
37
+ builds the static lines from the other elements + artboard, appends grid lines,
38
+ and asks `snapAxis` for the smallest nudge on each axis. The caught line is
39
+ published to `guideX` / `guideY` and drawn as a guide. The pixel threshold is
40
+ divided by the preview scale so the feel is constant at any zoom.
41
+
42
+ ## Resize snapping
43
+
44
+ Resizing snaps too: the edge (or corner) you drag snaps to the same targets —
45
+ grid, other elements' edges/centres, and the artboard — with the pink guide
46
+ showing what caught. Each handle drives specific edges (e.g. **e** snaps the
47
+ right edge, **se** snaps right + bottom, **n** snaps the top). Holding **Shift**
48
+ to lock the aspect ratio turns snapping off for that drag so the two don't fight.
49
+
50
+ ## Rulers & guides
51
+
52
+ Toggle **📏 Rulers** to show rulers along the top and left of the stage. **Drag
53
+ out of a ruler** to drop a guide line — down from the top ruler for a vertical
54
+ guide, right from the left ruler for a horizontal one. Guides are cyan, can be
55
+ **dragged to reposition**, and are removed by **dropping them off the stage**.
56
+
57
+ While the rulers are shown, dragged and resized elements **snap to your guides**
58
+ too (alongside the grid, elements, and artboard). Guides are editor-only — never
59
+ part of the animation or the saved JSON.
60
+
61
+ ## Limitations / later
62
+
63
+ - Rulers show tick marks but not numeric labels yet.
64
+ - Grid size (20px) is fixed for now.