@algorisys/tinyfly 0.92.0 → 0.94.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 (64) 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 +529 -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 +131 -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 +3045 -2024
  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 +6968 -5817
  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 +102 -0
  45. package/lib/types/characters/acting/custom.d.ts +66 -0
  46. package/lib/types/characters/acting/gags.d.ts +10 -0
  47. package/lib/types/characters/acting/hand-path.d.ts +35 -0
  48. package/lib/types/characters/acting/index.d.ts +4 -0
  49. package/lib/types/characters/acting/persona.d.ts +93 -0
  50. package/lib/types/characters/acting/script.d.ts +75 -11
  51. package/lib/types/characters/capabilities.d.ts +61 -0
  52. package/lib/types/characters/code-panel.d.ts +201 -0
  53. package/lib/types/characters/figure-actions.d.ts +12 -0
  54. package/lib/types/characters/figure-props.d.ts +87 -0
  55. package/lib/types/characters/gaits.d.ts +8 -0
  56. package/lib/types/characters/index.d.ts +3 -0
  57. package/lib/types/characters/stick-figure.d.ts +9 -2
  58. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  59. package/lib/types/engine/authoring/index.d.ts +1 -0
  60. package/llms-full.txt +12631 -0
  61. package/llms.txt +57 -0
  62. package/package.json +6 -2
  63. package/skills/tinyfly/SKILL.md +67 -0
  64. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,1249 @@
1
+ # Editor Guide
2
+
3
+ The tinyfly visual editor lets you create animations through a graphical interface — no code required. It lives at `/studio` (the site root, `/`, is the tinyfly home page, with **Open the editor** at the top). This guide covers every feature of the editor.
4
+
5
+ ## Editor Layout
6
+
7
+ The editor is divided into several panels:
8
+
9
+ ```
10
+ ┌─────────────────────────────────────────────────────┐
11
+ │ Header: tinyfly BETA · ? · ⚙ · toolbar │
12
+ ├─────────────────────────────────────────────────────┤
13
+ │ AI prompt bar (shown with the AI button) │
14
+ ├──────────┬──────────────────────────┬───────────────┤
15
+ │ Elements │ │ Property │
16
+ │ + Tracks │ Canvas / Preview │ + Presets │
17
+ │ (left «) │ (center) │ (right ») │
18
+ ├──────────┴──────────────────────────┴───────────────┤
19
+ │ Playback Controls │
20
+ ├─────────────────────────────────────────────────────┤
21
+ │ Scene Bar │
22
+ ├─────────────────────────────────────────────────────┤
23
+ │ Timeline [ Dope Sheet | Curves ] zoom − 100% + │
24
+ └─────────────────────────────────────────────────────┘
25
+ ```
26
+
27
+ **Collapsible side panels.** The left (Elements/Tracks) and right
28
+ (Properties/Presets) columns each have a `«` / `»` button to hide them and give
29
+ the canvas more room; a slim tab on the edge brings a hidden panel back. On
30
+ phones/tablets the panels slide in from the edges via the ☰ / ⚙ buttons.
31
+
32
+ ## Toolbar
33
+
34
+ Next to the **tinyfly** logo, the header has a **?** button that replays the
35
+ onboarding tour and a **⚙ Project Settings** button (project name, canvas size and
36
+ background colour; see [Project Settings](#project-settings)). The toolbar follows,
37
+ left to right:
38
+
39
+ - **Project title** — shows the current project's name; **double-click to rename**
40
+ it inline. A `*` means there are unsaved edits.
41
+ - **Save** — an explicit save with a live status: **Save** (unsaved) →
42
+ **Saving…** → **Saved ✓**. Auto-save always runs in the background; this button
43
+ is a reassuring, tap-friendly manual save (handy on tablets).
44
+ - **New** — start a fresh project (prompts if you have unsaved changes).
45
+ - **AI** — show or hide the AI prompt bar, where you describe an animation and
46
+ click **Generate**.
47
+ - **My Animations** — open the gallery of every project you've saved (thumbnails,
48
+ open / duplicate / delete). See [Project Management](#project-management).
49
+ - **Examples** — every ready-made animation on one page (`/examples`). Open one in
50
+ the editor, or copy the code of a code example into your own page.
51
+ - **Export** — open the export dialog: **CSS**, **Lottie**, **GIF**, **WebP**,
52
+ **MP4** (MP4 or WebM, depending on the browser) or **Sprite** sheet. See
53
+ [Export Formats](#export-formats).
54
+ - **More** (⋯) — a menu with **Import JSON…**, **Export JSON** (the timeline only), **Export Animation Document** (the scene's elements and tracks in one file, for apps that rebuild the shapes, such as YappyDraw; see [File format](file-format.md#1-animation-document)), **Copy JSON** (the timeline's JSON on the clipboard, e.g. to paste into a [Learn](/learn) step), **Embed…**
55
+ (copy-paste embed code), **Docs** (this documentation, in-app) and **Keyboard
56
+ Shortcuts** (or press `?`).
57
+
58
+ Shapes, text, images, video, lines, arrows and paths are added from the
59
+ **Elements** panel on the left (see [Adding Elements](#adding-elements)).
60
+
61
+ ## Canvas & Elements
62
+
63
+ ### Element Types
64
+
65
+ | Type | Description |
66
+ |------|-------------|
67
+ | **Rectangle** | Rectangular shape with fill, stroke, border radius |
68
+ | **Circle** | Elliptical shape with fill and stroke |
69
+ | **Text** | Text with font, size, weight, alignment controls |
70
+ | **Image** | Image element with URL source |
71
+ | **Audio** | Audio clip synced to the timeline (source, start time, volume, mute, loop) |
72
+ | **Video** | Video clip synced to the timeline (source, fit, start time, volume, mute, loop) |
73
+ | **Line** | Straight line with stroke and line cap options |
74
+ | **Arrow** | Line with arrowhead(s) at start/end |
75
+ | **Path** | Custom SVG path defined by path data (d attribute) — draw one with the ✒️ Pen tool |
76
+ | **⬡ Polygon** | Regular polygon; edit the number of **sides** in Properties |
77
+ | **★ Star** | Star; edit the number of **points** and the **inner %** in Properties |
78
+ | **Group** | Container that groups multiple elements |
79
+ | **🧍 Character** | A posable figure: pick a view, a pose and a face, and keyframe them to animate (see [Characters](#characters)) |
80
+ | **🗺 Map** | An animated map: places, a route between them, and a camera (see [Maps](#maps)) |
81
+
82
+ Polygon and star are **parametric** paths: change the sides/points/inner ratio in
83
+ the Property Panel and the shape regenerates, and they rescale cleanly when you
84
+ resize the box. See [polygon-star.md](polygon-star.md).
85
+
86
+ ### Adding Elements
87
+
88
+ Click an element type in the **Elements** panel on the left (Rectangle, Circle,
89
+ Text, Line, Arrow, Path, Image, Audio, Video, 🧍 Character, 🗺 Map, or ⬡ Polygon / ★ Star). The element appears at the center of the canvas with default dimensions. You can then:
90
+
91
+ - **Drag** to reposition it on the canvas
92
+ - **Resize** using the 8 handles around the element (corners and midpoints)
93
+ - **Rotate** using the rotation handle above the element
94
+
95
+ ### Audio
96
+
97
+ Add an **Audio** element to play a sound in time with the animation (background
98
+ music, a voiceover, or an effect). It shows as a small speaker badge on the
99
+ canvas and does not render visually in the output.
100
+
101
+ In the property panel you can set:
102
+
103
+ - **Source** — choose a file (embedded as a data URI) or paste a URL
104
+ - **Start (ms)** — the timeline time at which the audio begins
105
+ - **Volume**, **Muted**, **Loop**
106
+
107
+ The clip follows the timeline as you play, pause, and scrub — the timeline stays
108
+ the clock, and the audio is kept in sync (drift is corrected as it plays).
109
+
110
+ **Beat.** Give music a tempo and the timeline shows its beats: a faint line
111
+ each beat behind every track, a stronger one each bar, and the bars numbered
112
+ in the ruler. Dragged keyframes snap to a beat when they come within a few
113
+ pixels of one (hold **Alt** to place them freely), and a Character's dances
114
+ can follow the music (see [Characters](#characters)).
115
+
116
+ - **🎵 Detect tempo** reads the audio and finds its tempo and where the first
117
+ beat falls. It works best on music with a clear pulse; when it is unsure it
118
+ says so.
119
+ - **Tempo (bpm)**, **First beat (ms)** (into the audio), **Beats per bar** can
120
+ be typed or corrected.
121
+ - **👆 Tap the beat**: play the music and tap along; the tempo is the median
122
+ of the gaps between taps.
123
+
124
+ The first audio element with a tempo sets the beat, shifted to its **Start**.
125
+
126
+ A **Video** element works the same way but also renders its frames on the canvas
127
+ (with a **Fit** option). Both audio and video are carried into exported/embedded
128
+ HTML, where the player discovers them (`[data-tinyfly-media]`) and keeps them in
129
+ sync during playback.
130
+
131
+ ### Characters
132
+
133
+ A **🧍 Character** is a posable figure. It stands with its feet at the bottom of
134
+ its box; resize the box to change its height. In the property panel:
135
+
136
+ - **Figure**: *Fluid* (tapered limbs, hands and feet) or *Stick* (the
137
+ traditional stick figure).
138
+ - **Look**: *Clean*, *Pencil* (hand-drawn strokes that boil, with faint
139
+ construction lines) or *Silhouette*.
140
+ - **Build**: *Standard*, *Slim*, *Kid* (big head), *Broad*, *Curvy* or
141
+ *Stocky*, or set **Head**, **Shoulders** and **Hips** with the sliders (the
142
+ Stick figure has a head size only). Clothes, gags, walks and dances fit
143
+ every build.
144
+ - **Line**, **Skin**, and **Clothes** (a T-shirt and trousers, with their
145
+ colours, or none).
146
+ - **Hands**: *Round*, *Cartoon gloves* (a thumb and three plump fingers), or
147
+ *Natural* (five fingers, best for mudras). Gloves and natural hands take hand
148
+ shapes: dances key them (jazz hands, mudras), and each finger is a track
149
+ (`Right hand · index curl`).
150
+ - **View**: *Front*, *¾*, *Side*, *¾ back*, *Back* or *Side (left)*, or any
151
+ angle in between with the **Turn** slider. The figure turns as a whole: its
152
+ far arm goes behind its body and its face slides round, and is gone from
153
+ behind.
154
+ - **Body**: a pose (standing, waving, pointing, cheering, hands on hips,
155
+ thinking, shrugging, sitting, kneeling, crouching, crawling, lying down).
156
+ Poses that rest on a knee, the hands or the back are set down on the ground.
157
+ - **Face**: an expression (happy, sad, surprised, angry…), or the pose's own.
158
+
159
+ To animate a character, pick a view, a pose and a face, and click
160
+ **◆ Keyframe pose at playhead**. Move the playhead, pick the next pose, and
161
+ keyframe again: the character moves between them. The timeline shows only
162
+ the parts that move, in plain words ("Right arm · out / in", "Head · tilt"),
163
+ and each one can be edited, eased and retimed like any other track.
164
+
165
+ **Dance**: pick a style (disco, hip hop, breaking, jazz, K-pop, Bollywood,
166
+ Bhangra, Bharatanatyam, Charleston, tap, popping), a move or the whole routine, and a
167
+ tempo, then click **🕺 Dance from playhead**. Or pick a flip (front, back,
168
+ layout, scissor, side flip, cartwheel, back handspring, split leap, toe touch)
169
+ and click **🤸 Flip at playhead**. Both write ordinary keyframes from the
170
+ playhead, a few a beat, keeping the character's keys before and after, so
171
+ every step can be edited afterwards. With cartoon gloves, dances key the hand
172
+ shapes too. When an audio element has a tempo, **Follow beat** (on by default)
173
+ dances at the music's tempo and starts on the beat nearest the playhead. Popping's glides
174
+ and moonwalk travel from where the character stands (an x track, the planted foot staying put); facing
175
+ left, a character dances the mirror image and glides the other way. Flips travel from where the character is (an x track), the way it
176
+ faces: pick the *Side* or *Side (left)* view first. Facing left, a front-on
177
+ flip (a cartwheel, a side flip) is the mirror image: it steps off on the other
178
+ foot and wheels left. See [Dance and Flips](dance.md).
179
+
180
+ **Acting**: key two or more poses, pick a **Style** (*Full*, *Snappy*,
181
+ *Limited*, or *None* as keyed), and click **🎭 Act the keyed poses**. The
182
+ character winds up before each move, overshoots and settles, its limbs overlap
183
+ (the hips lead and the wrists drag), and its eyes lead and blink as its head
184
+ turns. With acting on, the character keeps its plain key poses, and its tracks
185
+ are generated from them:
186
+ - **◆ Keyframe pose at playhead** adds a key pose and re-acts the whole
187
+ performance.
188
+ - Changing the style re-acts in the new style.
189
+ - **Turn off** puts the plain poses back.
190
+
191
+ Dances and flips are written as they are, and turn acting off.
192
+
193
+ - **Gag**: a *take* (squash, shoot up, hang, land), a *double take*, a
194
+ *wind-up*, a *land*, a *tremble* or a *deflate* (sigh), from the pose at the
195
+ playhead. Gags are posed in the character's own frame, so they read from
196
+ any view.
197
+ - **Gait** and **Distance**: walk, bouncy, double bounce, sneak (tiptoe),
198
+ strut, tired or run. **← Walk left** / **Walk right →** walks that far from
199
+ the playhead. The character turns side-on, its feet stay planted, and an x
200
+ track moves it.
201
+ - **Say**: type a line and click **💬 Say at playhead**: the mouth is
202
+ lip-synced to it (English or Hindi), for as long as the line takes.
203
+ - **Drawing**: *On twos* or *On threes* holds each pose for two or three
204
+ frames, as hand-drawn animation does. It is a timeline setting
205
+ (`drawingRate` in the JSON), so previews, players and exports all hold the
206
+ same way.
207
+
208
+ See [Cartoon Acting](acting.md).
209
+
210
+ Characters show in the DOM and Canvas previews and in GIF / WebP / MP4
211
+ export. They are not part of exported HTML or embeds yet, and the SVG preview
212
+ does not draw them.
213
+
214
+ ### Maps
215
+
216
+ A **🗺 Map** fills the canvas with a map of the world. In the property panel:
217
+
218
+ - **Map**: *Street map* (OpenStreetMap tiles; needs a network), *World
219
+ outline* (bundled, offline) or *Pencil outline*.
220
+ - **Places**: pick a city from the list and click **Add**, or type a name with
221
+ its latitude and longitude. Add them in the order of the trip; ↑ ↓ reorder
222
+ them and ✕ removes one.
223
+ - **Route**: connect the places with a *Flight arc*, a *Great circle* or a
224
+ *Straight* line, in a colour, optionally dashed, with an arrow or a dot
225
+ travelling it.
226
+ - **View**: *Fit to places* or *Whole world*, and a **Zoom** slider.
227
+
228
+ To animate a trip, put the playhead where it should start, set **Trip (s)**,
229
+ and click **✨ Animate trip from playhead**: the first pin drops, the route
230
+ draws itself while its marker travels it, and each pin drops as the line
231
+ arrives. To move the camera, click **◆ Keyframe view at playhead**, move the
232
+ playhead and change the view: once the view is animated, changes to it are
233
+ keyed at the playhead. The timeline names the tracks plainly ("View · zoom",
234
+ "Delhi · pin", "Route · draw").
235
+
236
+ Maps show in the DOM and Canvas previews and in GIF / WebP / MP4 export
237
+ (export waits for the street map's tiles). The street map is © OpenStreetMap
238
+ contributors, credited on the map; its servers are for light use. See
239
+ [Animated Maps](maps.md) for the same from code.
240
+
241
+ ### 3D Scenes
242
+
243
+ A **🧊 3D Scene** fills the canvas with a real 3D scene, seen through its
244
+ camera: it starts with a camera at three-quarters, a key light, a floor and a
245
+ red box. In the property panel:
246
+
247
+ - **Objects**: pick one to edit. **Add** puts a box, sphere, cylinder, cone,
248
+ ring, star (an extruded path), character or light on the next free spot;
249
+ ✕ removes the picked one (not the scene's camera).
250
+ - **Transform**: X, Y, Z (metres, +y up), Tilt X, Turn Y, Roll Z and Scale.
251
+ **◆ Key transform at playhead** keys all of them; once a value is animated
252
+ (◆ by its name), changing it keys it at the playhead.
253
+ - **Meshes**: colour, shading (*Toon*, *Smooth*, *Flat*, *Unlit*) and an ink
254
+ outline. **Lights**: colour and intensity.
255
+ - **Characters**: a look (*Clean*, *Pencil*, *Silhouette* drawn by their pens
256
+ in perspective, or *Solid*) and **🕺 Dance from playhead** with any dance
257
+ style.
258
+ - **Cameras**: field of view, **Look through this camera**, and **✂ Cut to
259
+ this camera at playhead**, which keys the shot change.
260
+ - **Camera** view presets (*Front*, *¾*, *Side*, *Top*) and the scene's
261
+ **Background** and **Fog**.
262
+
263
+ Its tracks are on the element, named `object.property` (`box.rotateY`,
264
+ `character.arm.right.spread`, `activeCamera` for cuts). 3D scenes show in the
265
+ DOM and Canvas previews and in GIF / WebP / MP4 export. See [3D
266
+ Scenes](scene-3d.md) for the same from code.
267
+
268
+ ### Selecting Elements
269
+
270
+ - **Click** an element to select it
271
+ - **Ctrl+Click** (Cmd+Click on Mac) to toggle multi-selection
272
+ - **Ctrl+A** to select all elements
273
+ - **Esc** to deselect all
274
+ - Click empty canvas area to deselect
275
+
276
+ ### Moving & Transforming
277
+
278
+ - **Drag** selected elements to move them
279
+ - **Arrow keys** nudge elements by 1px
280
+ - **Shift+Arrow keys** nudge by 10px
281
+ - **Shift+Drag resize handle** for proportionate resize
282
+ - **Shift+Rotate** to snap to 15-degree increments
283
+
284
+ ### Pen Tool (draw paths)
285
+
286
+ In the **DOM** preview, click **✒️ Pen** to draw a custom path:
287
+
288
+ - **Click** to place anchor points (straight segments).
289
+ - **Click-drag** to pull out a smooth bezier curve as you place a point; hold
290
+ **Alt** while dragging a handle for a **corner** (cusp) instead of a smooth point.
291
+ - **Drag an existing anchor or handle** to adjust it before finishing.
292
+ - With **🧲 Snap** on, pen points snap to the grid, guides, elements, and artboard.
293
+ - **Finish**: click the highlighted **first point** to close (filled), or press
294
+ **Enter** / double-click for an open path (stroked). **Backspace** removes the
295
+ last point; **Esc** cancels.
296
+
297
+ The result is a normal Path element. See [pen-tool.md](pen-tool.md).
298
+
299
+ ### Grid, Snapping, Rulers & Guides
300
+
301
+ In the **DOM** preview header:
302
+
303
+ - **▦ Grid** — overlay a 20px grid on the artboard.
304
+ - **🧲 Snap** (on by default) — while dragging or resizing, an element's
305
+ edges/centre snap to the grid, to other elements' edges/centres, and to the
306
+ artboard centre, with a **pink guide** showing what caught. Hold **Shift** for
307
+ aspect-lock resize (snapping pauses so the two don't fight).
308
+ - **📏 Rulers** — show rulers along the top and left. **Drag out of a ruler** to
309
+ drop a **guide** line (cyan); reposition by dragging, delete by dropping it off
310
+ the stage. Elements snap to your guides too.
311
+
312
+ Grid, guides, and snapping are **editor-only** — they never appear in the saved
313
+ JSON or exports. See [grid-and-snapping.md](grid-and-snapping.md).
314
+
315
+ ### Copy, Paste & Duplicate
316
+
317
+ | Shortcut | Action |
318
+ |----------|--------|
319
+ | Ctrl+C | Copy selected element(s) |
320
+ | Ctrl+X | Cut selected element(s) |
321
+ | Ctrl+V | Paste element(s) with slight offset |
322
+ | Ctrl+D | Duplicate selected element |
323
+
324
+ ### Grouping
325
+
326
+ Select multiple elements, then:
327
+
328
+ - **Ctrl+G** — Group selected elements into a single group
329
+ - **Ctrl+Shift+G** — Ungroup a selected group
330
+
331
+ Groups move and transform as a unit.
332
+
333
+ ### Layer Ordering
334
+
335
+ In the Element Panel (left side), you can reorder layers:
336
+
337
+ - **Bring to Front** — Move element to the top layer
338
+ - **Send to Back** — Move element to the bottom layer
339
+ - **Move Up/Down** — Shift element one layer up or down
340
+ - **Visibility toggle** — Show/hide an element
341
+ - **Lock toggle** — Prevent accidental edits to an element
342
+
343
+ ### Deleting Elements
344
+
345
+ Select an element and press **Delete** or **Backspace**.
346
+
347
+ ## Symbols & Library
348
+
349
+ A **symbol** is a reusable bundle of elements you define once and place many
350
+ times. The **Library** panel (bottom of the left sidebar) holds them, shared
351
+ across all scenes in the project.
352
+
353
+ ### Create a symbol
354
+
355
+ 1. Select one or more elements on the stage.
356
+ 2. In the **Library** panel, click **+ Symbol**.
357
+
358
+ The selected elements are bundled into a new symbol and replaced on the stage
359
+ with a single **instance** — it looks identical to what was there.
360
+
361
+ ### Place instances
362
+
363
+ Click a symbol's thumbnail in the Library to drop another **instance** onto the
364
+ current scene. Move and resize an instance like any element; resizing scales the
365
+ symbol's contents to fit. Because every instance references the same symbol,
366
+ they'll all reflect changes to the definition.
367
+
368
+ ### Edit a symbol (in place)
369
+
370
+ **Double-click an instance** on the stage, or click the **pencil** on a Library
371
+ item, to open the symbol for editing. The stage and timeline switch to the
372
+ symbol's own contents, and a **breadcrumb** appears at the top:
373
+
374
+ ```
375
+ ‹ Scene 1 ▸ 🔷 My Symbol editing symbol — changes apply to all instances
376
+ ```
377
+
378
+ Edit the elements and the symbol's own timeline as usual; **every instance
379
+ updates** to match. Click the breadcrumb's scene name (or the `‹`) to return to
380
+ the scene. Everything auto-saves.
381
+
382
+ ### Manage symbols
383
+
384
+ - **Rename** — double-click a symbol's name.
385
+ - **Delete** — the `×` button. Blocked while instances of it are still in use
386
+ (the `×N` badge shows the instance count).
387
+
388
+ ### Nested animation
389
+
390
+ A symbol can have its **own timeline**. When it does, every instance **plays that
391
+ animation** inside its box as the scene plays — synced to the scene playhead and
392
+ looped over the symbol's duration. Combine it with animating the *instance*
393
+ (move/scale/rotate the whole thing on the scene timeline) for true nested motion:
394
+ the instance travels while its insides animate. Nested playback runs in the
395
+ **DOM** preview.
396
+
397
+ ### Symbol swap (lip-sync)
398
+
399
+ An instance can **swap between several symbols over time** — the primitive behind
400
+ lip-sync (mouth shapes) and any "which drawing shows now" effect, no bones needed.
401
+ With a symbol instance selected, in the Property Panel's **Symbol Swap** section:
402
+
403
+ 1. Build an ordered **swap set** (add symbols from the Library, reorder with ↑/↓).
404
+ 2. Click **+ Add swap track** — it adds a `swapIndex` track that steps through the
405
+ set across the timeline.
406
+ 3. Edit the `swapIndex` keyframes (Dope Sheet / Curves) to time the swaps. The
407
+ instance shows `set[floor(swapIndex)]` at each moment (a plain numeric track
408
+ gives step/hold behaviour).
409
+
410
+ Symbol swap plays in the **DOM** preview.
411
+
412
+ ### Symbols in export & embeds
413
+
414
+ Symbol instances render in the **DOM**, **Canvas** and **SVG** previews, and in your output too. **Raster export (GIF / WebP / MP4)** bakes in a symbol's **nested animation and swaps** — the exported file matches
415
+ what plays in the preview, including lip-sync. **Embeds, thumbnails and the
416
+ Canvas preview** show the symbol's poster frame (static).
417
+
418
+ > **Embeds now animate symbols** — both single-scene (player) and multi-scene
419
+ > sequence (sequencer) embeds run each instance's nested timeline. Still to come:
420
+ > **swap** in embeds and instance-opacity compositing in export — see
421
+ > [symbols-and-library.md](symbols-and-library.md).
422
+
423
+ ## Property Panel
424
+
425
+ When an element is selected, the Property Panel on the right shows editable properties:
426
+
427
+ ### Transform Properties
428
+
429
+ | Property | Description |
430
+ |----------|-------------|
431
+ | X | Horizontal position in pixels |
432
+ | Y | Vertical position in pixels |
433
+ | Width | Element width in pixels |
434
+ | Height | Element height in pixels |
435
+ | Rotation | Rotation angle in degrees |
436
+ | Opacity | Transparency, 0 (invisible) to 1 (fully opaque) |
437
+
438
+ ### Appearance Properties
439
+
440
+ | Property | Description |
441
+ |----------|-------------|
442
+ | Fill | Fill color (solid color or gradient) |
443
+ | Stroke | Border/outline color |
444
+ | Stroke Width | Border thickness in pixels |
445
+ | Border Radius | Corner rounding for rectangles |
446
+
447
+ ### Gradient Fills
448
+
449
+ Elements support gradient fills:
450
+
451
+ - **Linear Gradient** — Color transitions along an angle
452
+ - **Radial Gradient** — Color radiates from a center point
453
+
454
+ To set a gradient:
455
+ 1. Select an element
456
+ 2. In the Fill property, switch from solid color to gradient
457
+ 3. Add color stops and adjust positions
458
+ 4. Set the gradient angle (linear) or center point (radial)
459
+
460
+ ### Text Properties
461
+
462
+ For text elements:
463
+
464
+ | Property | Description |
465
+ |----------|-------------|
466
+ | Content | The text to display |
467
+ | Font Size | Text size in pixels |
468
+ | Font Family | Font name (e.g., Arial, Helvetica) |
469
+ | Font Weight | Weight: normal (400), bold (700), etc. |
470
+ | Text Align | Horizontal alignment: left, center, right |
471
+
472
+ ### Line/Arrow Properties
473
+
474
+ | Property | Description |
475
+ |----------|-------------|
476
+ | X2, Y2 | End point coordinates |
477
+ | Stroke | Line color |
478
+ | Stroke Width | Line thickness |
479
+ | Line Cap | Line end style: butt, round, square |
480
+ | Start Head | Arrow head at start (arrows only) |
481
+ | End Head | Arrow head at end (arrows only) |
482
+ | Head Size | Arrow head size (arrows only) |
483
+
484
+ ### Path Properties
485
+
486
+ | Property | Description |
487
+ |----------|-------------|
488
+ | Path Data (d) | SVG path data string |
489
+ | Fill | Path fill color |
490
+ | Stroke | Path outline color |
491
+ | Stroke Width | Outline thickness |
492
+ | Line Cap | End cap style |
493
+ | Line Join | Corner join style: miter, round, bevel |
494
+
495
+ **✏️ Pencil Sketch.** Rectangles, circles, lines and paths have a Pencil Sketch
496
+ section: tick **Sketched** to draw the outline in hand-drawn pencil strokes that
497
+ boil, and set **Roughness**, **Boil / sec**, **Passes** and **Seed**. It shows in
498
+ the **Canvas** preview and in GIF / WebP / MP4 export; the DOM and SVG previews
499
+ draw the shape clean. Give the shape a visible stroke, since the sketch is
500
+ drawn on the outline.
501
+
502
+ For a **⬡ Polygon / ★ Star**, the panel also shows a **Shape** section (Sides /
503
+ Points / Inner %) that regenerates the path as you change it.
504
+
505
+ **🌀 Shape Morph.** For any path, the Properties panel has a Shape Morph section:
506
+ pick a target shape (Polygon/Star + points/inner %) and click **Create shape
507
+ morph →** to add a `d` track that **tweens the shape** across the timeline. Press
508
+ Play to watch it morph — it plays in every preview, export, and embed. See
509
+ [shape-morph.md](shape-morph.md).
510
+
511
+ ## Timeline & Keyframes
512
+
513
+ The timeline panel at the bottom is where you define how properties change over time.
514
+
515
+ ### Timeline Layout
516
+
517
+ ```
518
+ Track Panel │ Time Ruler (milliseconds)
519
+ ─────────────────── │──0───100───200───300───400───500───
520
+ box > opacity │ ◆─────────────────◆──────────◆
521
+ box > x │ ◆────────────────────────────◆
522
+ box > rotation │ ◆─────◆──────────────────────◆
523
+ ─────────────────── │─────────────────────────────────
524
+ │ ▲ Playhead
525
+ ```
526
+
527
+ - **Tracks** are listed on the left — each controls one property of one element
528
+ - **Keyframes** are shown as diamonds (◆) on the timeline; the **selected** one
529
+ is highlighted (amber). Click one to edit its value in the Property Panel.
530
+ - The **playhead** (vertical line) indicates the current time. Click the ruler to
531
+ move it (scrub).
532
+ - The **end of the scene** is drawn as a dashed amber line, and everything past it
533
+ is dimmed. Nothing in the dimmed region plays or exports — see
534
+ [Scene duration](#scene-duration) below.
535
+
536
+ ### Scene duration
537
+
538
+ The readout in the playback bar shows `current / duration` in seconds. **The
539
+ duration is editable** — click it, type a new length, press Enter.
540
+
541
+ Each scene carries its own duration (new scenes start at 2 seconds), and it is
542
+ the hard end of the animation: playback stops there, the playhead cannot scrub
543
+ past it, and every exporter (GIF, WebP, MP4, sprite sheet, CSS, Lottie) samples
544
+ `0 → duration`.
545
+
546
+ You rarely need to set it by hand, because **the timeline grows to fit your
547
+ keyframes**: drag a keyframe to 4s in a 2s scene, or apply a preset that runs
548
+ long, and the duration extends to cover it. It never shrinks on its own.
549
+
550
+ If you *shorten* the duration below your last keyframe, those keyframes stay put
551
+ but become unreachable — the track just holds its last in-range value. The
552
+ duration turns amber and a **Fit** button appears next to it; click it to snap
553
+ the duration back out to the last keyframe. Both are ordinary edits, so
554
+ <kbd>Ctrl</kbd>+<kbd>Z</kbd> undoes them.
555
+
556
+ ### Two views: Dope Sheet and Curves
557
+
558
+ A switch at the top-left of the timeline flips between two ways to see the same
559
+ keyframes:
560
+
561
+ - **Dope Sheet** — the classic keyframe grid (diamonds on a time ruler). Best for
562
+ **timing**: when things happen, nudging them earlier/later, copy/paste.
563
+ - **Curves** — every *numeric* track (x, y, opacity, scale, rotate, …) is drawn
564
+ as a **value-over-time curve**, with the real easing shown between keyframes.
565
+ Best for **feel**:
566
+ - Drag a point **horizontally** to retime it, **vertically** to change its value.
567
+ - Select a keyframe and drag its **amber easing handles** to shape the
568
+ cubic-bezier between it and the previous keyframe (a named easing becomes a
569
+ custom curve the moment you grab a handle).
570
+ - **Double-click** an empty lane to add a keyframe there.
571
+ - **Ctrl/⌘-click** points to multi-select, or **drag a box** across empty space
572
+ to rubber-band-select every point inside it.
573
+ - **Lanes / Overlay** toggle (top-left of the curve area): *Lanes* gives each
574
+ track its own editable row; *Overlay* draws every curve on one shared axis
575
+ with a colour legend — handy for comparing timing across tracks.
576
+
577
+ Non-numeric tracks (colours, motion paths, arrays) can't be a single curve, so
578
+ they're listed at the bottom — edit those in the Dope Sheet.
579
+
580
+ The Dope Sheet also supports **box (rubber-band) select** — drag across empty
581
+ track space to select every keyframe inside the rectangle.
582
+
583
+ Both views share the playhead, zoom, scroll and selection, so switching never
584
+ loses your place. Scene tabs in the **Scene Bar** show a small live **thumbnail**
585
+ of each scene so you can tell them apart at a glance.
586
+
587
+ ### Zoom & scroll
588
+
589
+ - **Zoom**: the **− / 100% / +** control at the top-right of the timeline, or
590
+ **Ctrl/⌘ + scroll** over the timeline (zooms toward the cursor). Click the
591
+ percentage to reset zoom and scroll to the start.
592
+ - **Scroll (pan)**: drag the **scrollbar** under the timeline, or **Shift + scroll**
593
+ (or a horizontal trackpad swipe).
594
+
595
+ ### Adding Tracks
596
+
597
+ 1. In the Track Panel, click **+**
598
+ 2. Type the **Target**: the element's name as shown in the Elements panel (for
599
+ example `box`)
600
+ 3. Type the **Property** to animate (for example `opacity` or `x`)
601
+ 4. Click **Add Track** for a keyframe track. It starts with two keyframes: `0` at
602
+ the start and `1` at the end of the scene, which you then edit.
603
+
604
+ The same form has **Add Spring** and **Add Inertia**, which create physics tracks
605
+ edited by parameters instead of keyframes (see [Spring tracks](#spring-tracks) and
606
+ [Throws with inertia](#throws-with-inertia-inertia-tracks)). Click **×** to close
607
+ the form.
608
+
609
+ ### Spring tracks
610
+
611
+ A spring track moves a property from one value to another like a physical spring,
612
+ so you set how it feels instead of placing keyframes. It appears as a span on the
613
+ timeline. Select it to edit in Properties:
614
+
615
+ - **Feel** — one-click presets: Gentle, Default, Snappy, Bouncy, Wobbly, Stiff.
616
+ - **Values** — From, To and Delay (ms).
617
+ - **Physics** — Stiffness (higher is snappier), Damping (higher settles sooner; 0
618
+ oscillates forever), Mass (higher is more sluggish) and an initial Velocity.
619
+
620
+ The inspector shows how long the spring takes to settle and flags a spring that
621
+ overshoots its target.
622
+
623
+ ### Adding Keyframes
624
+
625
+ There are a few ways:
626
+
627
+ - **Double-click** a track row (Dope Sheet) or a lane (Curves) at the time you
628
+ want. The new keyframe holds the track's current value at that point (in Curves,
629
+ it takes the value at the height you clicked), so it won't snap to zero.
630
+ - With an element selected, move the playhead and **change a value** in the
631
+ Property Panel — a keyframe is created at the playhead automatically.
632
+
633
+ Then fine-tune the value in the Property Panel (or by dragging in the Curves view).
634
+
635
+ ### Moving Keyframes
636
+
637
+ Drag a keyframe diamond left or right to change its time. The keyframe snaps to the nearest millisecond on release.
638
+
639
+ ### Selecting Multiple Keyframes
640
+
641
+ **Ctrl/Cmd-click** keyframes to add or remove them from a selection (across
642
+ tracks). Selected keyframes are highlighted.
643
+
644
+ ### Copy, Paste & Delete Keyframes
645
+
646
+ With one or more keyframes selected:
647
+
648
+ - **Ctrl/Cmd+C** — copy the selected keyframes
649
+ - **Ctrl/Cmd+V** — paste them starting at the playhead (relative timing between
650
+ copied keyframes is preserved; they return to their source tracks). The pasted
651
+ keyframes become the new selection.
652
+ - **Delete / Backspace** — remove all selected keyframes
653
+
654
+ Keyframe shortcuts take precedence while keyframes are selected; otherwise the
655
+ same shortcuts act on selected elements.
656
+
657
+ ### Easing Between Keyframes
658
+
659
+ Each keyframe has an easing setting that controls how the value transitions FROM the previous keyframe TO this one:
660
+
661
+ - **linear** — Constant speed, no acceleration
662
+ - **ease-in** — Starts slow, speeds up (cubic)
663
+ - **ease-out** — Starts fast, slows down (cubic)
664
+ - **ease-in-out** — Slow start and end, fast middle (cubic)
665
+ - **ease-in-quad** — Quadratic ease in (gentler than cubic)
666
+ - **ease-out-quad** — Quadratic ease out
667
+ - **ease-in-out-quad** — Quadratic ease in-out
668
+ - **ease-in-cubic** — Cubic ease in (steeper)
669
+ - **ease-out-cubic** — Cubic ease out
670
+ - **ease-in-out-cubic** — Cubic ease in-out
671
+ - **elastic** — Overshoots and wobbles into place; set mode (in / out / in-out), amplitude and period
672
+ - **bounce** — Rebounds off the end value; set mode
673
+ - **back (overshoot)** — Goes past the value, then settles; set mode and overshoot
674
+ - **steps** — Holds, then jumps; set the number of steps and where the jumps happen
675
+ - **Custom cubic-bezier** — Define your own curve with the visual curve editor
676
+
677
+ ### Steps (markers) and captions
678
+
679
+ Steps turn an animation into a step-through teaching figure: players can go step
680
+ by step, stop at a step, ask a question there, and show a caption for it in each
681
+ language. They are saved in the timeline JSON as `config.markers` and `captions`.
682
+ See [Teaching Animations](teaching.md).
683
+
684
+ - **Add a step:** press **M**, click **+** in the **Steps** lane under the time
685
+ ruler, or double-click the lane. The step is added at the playhead, or where you
686
+ double-clicked, and opens in Properties.
687
+ - **Move a step:** drag its flag. A drag is one undo step.
688
+ - **Go between steps:** **[** and **]**, or ⏮ / ⏭ in the playback controls.
689
+ - **Edit a step** in Properties:
690
+ - **Label:** the step's caption in the animation's own language.
691
+ - **Time** and **Id:** captions and links refer to the step by its id. Renaming it
692
+ moves its captions along.
693
+ - **Pause here:** playback stops at this step, even when playing through.
694
+ - **Question:** shown while stopped here, with a **Reveal** button in the embed
695
+ controls. Adding one turns on Pause.
696
+ - **Captions:** add a language (`es`, `pt-BR`, `zh-CN`), then write each step's
697
+ caption. A step without one shows its label, and the inspector lists the missing
698
+ languages.
699
+ - **Delete a step:** **Delete**, or **Delete Step** in Properties. Its captions go with it.
700
+
701
+ Red flags mark steps that pause. A **?** marks steps that ask a question.
702
+
703
+ ### Looping, speed and direction
704
+
705
+ The editor has no loop, speed or direction controls. These are playback settings,
706
+ chosen where the animation is played:
707
+
708
+ - **Embed code** passes `loop: -1` (loop forever) to the player; edit it in the
709
+ copied code.
710
+ - The **player** accepts `loop` (`0` none, `-1` infinite, or a count), `alternate`
711
+ (ping-pong) and `speed` options. See [API Reference](api-reference.md).
712
+ - In **JSON**, the same settings are `config.loop`, `config.alternate`,
713
+ `config.speed` and `config.repeatDelay` on the timeline. See
714
+ [File Format](file-format.md).
715
+
716
+ ## Playback Controls
717
+
718
+ The playback bar provides:
719
+
720
+ | Control | Description |
721
+ |---------|-------------|
722
+ | Undo / Redo | Undo the last change (Ctrl+Z); redo it (Ctrl+Shift+Z or Ctrl+Y) |
723
+ | Stop | Stop and return to the beginning |
724
+ | Play/Pause | Start or pause playback |
725
+ | `current / duration` | The playhead time, and the scene duration in seconds, which you can type into. A **Fit** button appears when keyframes sit past the end. See [Scene duration](#scene-duration) |
726
+ | Seek bar | Drag to move the playhead (you can also click the timeline ruler) |
727
+
728
+ ## Scenes & Transitions
729
+
730
+ ### Working with Scenes
731
+
732
+ Scenes are shown in the **Scene Bar** between the canvas and the timeline. Each scene has its own set of elements and its own timeline.
733
+
734
+ - **Add Scene** — Click the **+** button at the end of the scene bar
735
+ - **Switch Scene** — Click a scene tab to switch to it
736
+ - **Rename Scene** — Double-click the scene tab name
737
+ - **Duplicate Scene** — Right-click a scene tab and select "Duplicate"
738
+ - **Delete Scene** — Right-click and select "Delete" (cannot delete the last scene)
739
+ - **Reorder Scenes** — Drag scene tabs to rearrange their order
740
+
741
+ ### Scene Transitions
742
+
743
+ Transitions define how one scene visually transitions into the next. Between scene tabs, you'll see transition indicators.
744
+
745
+ **Available transition types:**
746
+
747
+ | Type | Description |
748
+ |------|-------------|
749
+ | `none` | Instant switch, no animation |
750
+ | `fade` | Cross-fade between scenes |
751
+ | `slide-left` | New scene slides in from the right |
752
+ | `slide-right` | New scene slides in from the left |
753
+ | `slide-up` | New scene slides in from the bottom |
754
+ | `slide-down` | New scene slides in from the top |
755
+
756
+ **To set a transition:**
757
+
758
+ 1. Click the transition indicator between two scene tabs, OR
759
+ 2. Right-click a scene tab (not the first scene) and select "Set Transition..."
760
+ 3. In the Transition Dialog:
761
+ - Choose the transition type from the dropdown
762
+ - Set the duration in milliseconds (default: 500ms)
763
+ - Preview the effect with the live preview
764
+ 4. Click "Apply"
765
+
766
+ The first scene's transition setting is ignored (there's no scene before it to transition from).
767
+
768
+ When you switch scenes in the editor, you'll see a brief preview of the configured transition animation.
769
+
770
+ ## Animation Presets
771
+
772
+ The Preset Panel provides ready-made animation templates that you can apply to any selected element with a single click.
773
+
774
+ ### Entrance Animations
775
+
776
+ | Preset | Duration | Description |
777
+ |--------|----------|-------------|
778
+ | Fade In | 500ms | Fade from transparent to opaque |
779
+ | Fade In Up | 600ms | Fade in while sliding up |
780
+ | Fade In Down | 600ms | Fade in while sliding down |
781
+ | Slide In Left | 500ms | Slide in from the left edge |
782
+ | Slide In Right | 500ms | Slide in from the right edge |
783
+ | Scale In | 500ms | Scale up from 0 to full size |
784
+
785
+ ### Emphasis Animations
786
+
787
+ | Preset | Duration | Description |
788
+ |--------|----------|-------------|
789
+ | Pulse | 800ms | Scale pulse effect |
790
+ | Bounce | 1000ms | Bouncing with scale and vertical movement |
791
+ | Shake | 500ms | Horizontal shake effect |
792
+ | Spin | 600ms | Full 360-degree rotation |
793
+ | Flash | 600ms | Opacity flash effect |
794
+
795
+ ### Exit Animations
796
+
797
+ | Preset | Duration | Description |
798
+ |--------|----------|-------------|
799
+ | Fade Out | 500ms | Fade from opaque to transparent |
800
+ | Fade Out Down | 600ms | Fade out while sliding down |
801
+ | Scale Out | 500ms | Scale down to 0 |
802
+
803
+ ### Motion Animations
804
+
805
+ | Preset | Duration | Description |
806
+ |--------|----------|-------------|
807
+ | Float | 2000ms | Gentle vertical floating |
808
+ | Swing | 1000ms | Pendulum rotation effect |
809
+ | Breathe | 2000ms | Subtle scale breathing |
810
+
811
+ ### Throws with inertia (inertia tracks)
812
+
813
+ In the Tracks panel, click **+**, enter a target and a property (for example `x`),
814
+ then **Add Inertia**. An inertia track is a throw: it starts with a velocity and
815
+ slows under friction until it rests. It appears as a span on the timeline, like a
816
+ spring, and is labelled `inertia` in the track list.
817
+
818
+ Select it to edit in Properties:
819
+
820
+ - **Throw**: From, Velocity (units per second), Friction (higher stops sooner),
821
+ and Delay.
822
+ - **Landing**: Min and Max, and **Snap to**. One number snaps to a grid of that
823
+ size; a list such as `0, 120, 300` snaps to the nearest value. The header shows
824
+ where it comes to rest (marked *snapped* when snapping moved it) and how long
825
+ it takes to settle.
826
+
827
+ The scene grows automatically to fit the throw. Inertia tracks play in every
828
+ preview and bake into keyframes for exports.
829
+
830
+ ### Scramble and type-on (text tracks)
831
+
832
+ Select a text element and use **🔤 Text Animation** in Properties:
833
+
834
+ 1. Choose **Scramble** (the current text scrambles into new words) or **Type on**.
835
+ 2. Enter the new text and a duration, then **Add text animation →**. It starts at
836
+ the playhead.
837
+
838
+ This adds a **text** track (labelled `text` in the track list). Select it to edit:
839
+
840
+ - **Words** — From, To, and right-to-left.
841
+ - **Scramble** — the characters to scramble through (A–Z, a–z, A–z, 0–9, or your own),
842
+ how often they change, how long before they start to settle (reveal delay), and
843
+ whether the length grows or shrinks. **New scramble** picks a different random
844
+ sequence; each sequence is seeded, so it replays identically in previews and exports.
845
+ - **Timing** — start, duration and easing.
846
+
847
+ While a text track exists it decides the element's text (before it starts, the element
848
+ shows *From*). Remove the track and the element's own Content shows again. Text tracks
849
+ play in every preview and in GIF/WebP/MP4/sprite exports; CSS and Lottie exports leave
850
+ them out, since neither can animate text content.
851
+
852
+ ### Text Animations
853
+
854
+ | Preset | Duration | Description |
855
+ |--------|----------|-------------|
856
+ | Text Color Cycle | 2000ms | Smooth color transition |
857
+ | Text Glow | 1500ms | Glow effect with shadow |
858
+ | Text Bounce In | 800ms | Bounce in with scale |
859
+ | Letter Drop & Bounce | 700ms | Letters drop in and bounce (best with per-letter stagger) |
860
+ | Letter Cascade Up | 500ms | Letters fade and rise into place |
861
+ | Letter Wave | 900ms | A rolling wave travels across the letters |
862
+ | Letter Assemble | 650ms | Letters spin and scale in to assemble the word |
863
+ | Letter Pop In | 450ms | Letters pop in with a springy overshoot |
864
+
865
+ **To apply a preset:**
866
+ 1. Select an element on the canvas
867
+ 2. Open the Preset Panel
868
+ 3. Browse by category or scroll through the list
869
+ 4. Click a preset to apply it to the selected element
870
+
871
+ The preset creates the appropriate tracks and keyframes automatically.
872
+
873
+ ### Per-letter stagger (text)
874
+
875
+ Select a **text** element (or multiple elements) and the Preset Panel shows a
876
+ **Per-letter stagger** toggle with a delay control. With it enabled, applying a
877
+ preset:
878
+
879
+ - **Splits the text into one element per letter** (like Adobe Animate's "break
880
+ apart"), positioned to match the original layout, then
881
+ - **Fans the preset across the letters**, each starting `delay` ms after the
882
+ previous one.
883
+
884
+ This is how Animate-style **drop & bounce**, **cascade**, and **wave** text
885
+ effects are built. The `Text` category includes purpose-built letter presets —
886
+ **Letter Drop & Bounce**, **Cascade Up**, **Wave**, **Assemble**, and **Pop
887
+ In** — tuned to look their best when staggered. The stagger is pure data (offset
888
+ keyframe tracks), so it exports to JSON and plays anywhere the engine runs.
889
+
890
+ > Tip: with several elements selected, the stagger fans across the selection in
891
+ > selection order instead of splitting text — handy for animating rows of
892
+ > icons or cards.
893
+
894
+ ### Typewriter (text)
895
+
896
+ Select a **text** element and the Preset Panel shows a **Typewriter** section.
897
+ Set the typing **Speed** (ms per character), optionally enable the **Blinking
898
+ cursor**, and click **Apply Typewriter**. This:
899
+
900
+ - Splits the text into letters, then reveals each one instantly in sequence
901
+ (a crisp character-by-character type-on, not a fade),
902
+ - Optionally adds a thin cursor element that **steps to each letter as it is
903
+ typed** and blinks, and
904
+ - **Extends the timeline automatically** to fit the full reveal plus the cursor
905
+ hold.
906
+
907
+ Like everything else, the result is plain keyframe tracks — it exports to JSON
908
+ and plays anywhere the engine runs.
909
+
910
+ ### Write On (shapes)
911
+
912
+ Select a **path, rectangle, circle or line** and the Preset Panel shows a
913
+ **Write On** section. Set the **Duration** and click **Apply Write-On** to draw
914
+ the shape's outline on, as if by hand:
915
+
916
+ - Every shape gets a `drawOn` track (0 → 1). The **Canvas** preview and GIF /
917
+ WebP / MP4 export draw the outline on along it, and fill the shape once the
918
+ outline is complete. Circles start at the top and go clockwise.
919
+ - A path also gets `stroke-dasharray` / `stroke-dashoffset` tracks, so the DOM
920
+ and SVG previews draw it on too. Rectangles, circles and lines draw on in the
921
+ Canvas preview only.
922
+
923
+ Turn on **Pencil Sketch** for the same shape to draw it on in pencil.
924
+
925
+ ### Reveal / mask wipe
926
+
927
+ The **Entrance** category includes **Reveal Right / Left / Up / Down** presets.
928
+ These animate a clip-inset that wipes the element into view like a mask — no
929
+ extra layer required. Reveal works on any element (text, shapes, images) and is
930
+ rendered consistently across the DOM, SVG, and Canvas renderers.
931
+
932
+ Combine a Reveal preset with **Per-letter stagger** to get a cascading,
933
+ letter-by-letter mask reveal (each glyph wipes in a moment after the last).
934
+
935
+ ### Filters (blur, glow, drop-shadow)
936
+
937
+ Elements support animatable filter properties, composed the same way across the
938
+ DOM, SVG, and Canvas renderers:
939
+
940
+ - `blur` (px) — used by the **Blur In** entrance preset (sharpen into focus)
941
+ - `glow` (+ `glowColor`) — a coloured halo; used by **Glow Pulse**
942
+ - `shadowX` / `shadowY` / `shadowBlur` (+ `shadowColor`) — used by **Drop Shadow**
943
+
944
+ ### Shine sweep
945
+
946
+ The **Shine Sweep** text preset sends a bright highlight travelling across the
947
+ text, clipped to the glyph shapes (like a metallic sheen). The base text colour
948
+ stays visible underneath. Shine renders on the DOM, SVG, and Canvas renderers.
949
+
950
+ ## Examples
951
+
952
+ Every ready-made animation lives on one page. Open it with the **Examples** button
953
+ in the toolbar (or go to `/examples`). Cards show a still frame and play while you
954
+ hover over them.
955
+
956
+ There are two kinds of example, and a filter for each:
957
+
958
+ - **Open in editor** — built in the editor. **Open in editor** loads it into a
959
+ **new project**, so your existing work is never replaced.
960
+ - **Code** — for your own page. Timeline examples show their JSON and HTML under
961
+ **View code** and play on DOM or Canvas. **GSAP-style** examples are real `live.to()` code that
962
+ runs on the card while you hover. The code shown is read from the demo's own
963
+ source file, so it is exactly what runs.
964
+
965
+ ### Categories
966
+
967
+ | Category | Examples |
968
+ |----------|---------|
969
+ | **GSAP-style** | 41 live `live.to()` demos, grouped below |
970
+ | **Showcase** | Draw · Guess · Repeat (vertical promo), Logo Intro, Social Card, Menu Animation |
971
+ | **Basics** | Fade in/out, scale pulse, rotation, shape morph |
972
+ | **Motion** | Bouncing ball, slide-in, orbit, pendulum, wave, zigzag, motion path |
973
+ | **Text** | Letter drop & bounce, fade, slide, scale, bounce, typewriter, wave, glitch, highlight, reveal |
974
+ | **UI & Interactions** | Loading spinner, button press, notification, toggle switch, skeleton loader, like, success check |
975
+ | **Loaders** | Progress bar, dot spinner, orbit loader |
976
+ | **Effects** | Colour morph, particle burst, ripple, confetti, starburst, floating shapes |
977
+ | **Data** | Bar chart, number counter |
978
+ | **Camera** | Push In, Pan Across, Orbit Reveal |
979
+ | **Scroll** | Scroll reveal, parallax, progress bar |
980
+ | **Algorisys** | Product showcase demos (TinyFly, YappyDraw, HappyPaint, ProPeak, SkillzEngine) |
981
+
982
+ The GSAP-style demos cover:
983
+
984
+ - **Flip layout transitions** — shuffle grid, filter gallery, layout switch, expand tile,
985
+ shared-element gallery (`data-flip-id`).
986
+ - **Scroll** — pinned horizontal scroll (`scrollTrigger` with `pin` and `scrub`).
987
+ - **Motion paths** — following an SVG path, a path through points, orbits, draw & follow.
988
+ - **Shape morphing** — shape morph, icon morph (play/pause), menu morph.
989
+ - **Text** — scramble text, typewriter, stats decode, split-text reveal, line mask reveal (`splitText`).
990
+ - **Springs, inertia and dragging** — spring release, throw to slots, inertia carousel, friction, swipe cards.
991
+ - **Canvas and WebGL** — canvas from object tweens (plain-object targets and `live.ticker`).
992
+ - **Timelines and easing** — staggered grid, logo sequence, composed tweens,
993
+ timeline controls, elastic/bounce/steps.
994
+ - **Pointer and UI effects** — pointer follow, magnetic button, proximity grid, dock
995
+ magnify, velocity skew, card stack, card flip, infinite marquee, SVG line draw (`drawSVG`).
996
+
997
+ Above the cards is a **full-page showcase**: an agency-style landing page built from
998
+ the same API — masked headline reveal, a pointer-lit canvas on the ticker, a
999
+ velocity marquee, scroll-lit copy, a pinned horizontal work section, count-ups,
1000
+ drawn icons, a shared-element lightbox and springy type. **Open the page** runs it
1001
+ at `/showcase/agency-landing` on the real window scroll; **Copy code** gives the
1002
+ whole page as one HTML file.
1003
+
1004
+ Every card has a **Copy code** button. It copies a complete, standalone HTML page
1005
+ for that example (markup, styles, the animation, and a script tag that loads
1006
+ tinyfly from the jsDelivr GitHub CDN, pinned to the editor's version) that you can
1007
+ save as a `.html` file and open. For editable examples the animation is the same
1008
+ as the editor's Embed; for GSAP-style examples it is the demo's code, unchanged.
1009
+ Scroll code examples also have **Drive it from scroll**, showing how to scrub the
1010
+ same timeline from scroll position.
1011
+
1012
+ Every example also has its own page at `/examples/<id>`. Click its title to open it,
1013
+ or use **Copy link** there to share it. On its own page an example plays without
1014
+ hovering and lists more from the same category.
1015
+
1016
+ Use the search box to find examples by name, description or tag. Search and filters
1017
+ are part of the URL, so `/examples?kind=code&category=scroll` links straight to a
1018
+ filtered view. Examples are a good way to learn: study how they use tracks,
1019
+ keyframes, and easing to achieve different effects.
1020
+
1021
+ ## Motion Paths
1022
+
1023
+ Motion path animation moves an element along a path you draw.
1024
+
1025
+ 1. Add a **Path** element (or draw one with the ✒️ Pen tool) and select it.
1026
+ 2. In Properties, find the **Motion Path** section:
1027
+ - **Element** — the element to move along this path.
1028
+ - **Duration** — how long the trip takes, in ms.
1029
+ - **Auto-Rotate** — turn the element to face the direction of travel.
1030
+ - **Rotation Offset** — shown with Auto-Rotate; adjusts the facing angle (degrees).
1031
+ 3. Click **Apply Motion Path**.
1032
+
1033
+ This adds a `motionPath` track to that element, starting at 0 ms, with two
1034
+ keyframes that go from `0` (the start of the path) to `1` (the end) with
1035
+ `ease-in-out`. Edit those keyframes like any other to change the timing or easing,
1036
+ or add keyframes in between to pause or reverse along the path.
1037
+
1038
+ The path is standard SVG path data (the `d` attribute), supporting commands like:
1039
+ - `M` (move to), `L` (line to), `C` (cubic bezier curve)
1040
+ - `Q` (quadratic bezier), `A` (arc), `Z` (close path)
1041
+
1042
+ ## Export & Embed
1043
+
1044
+ ### Embed Dialog
1045
+
1046
+ Choose **More → Embed…** in the toolbar to generate copy-paste code for your website.
1047
+
1048
+ **Scope options:**
1049
+ - **Single Scene** — Embed only the current scene's animation
1050
+ - **All Scenes (Sequence)** — Embed all scenes with transitions as a sequence
1051
+
1052
+ **Format options:**
1053
+ - **Inline JSON** — Animation data embedded directly in the HTML. Best for small animations.
1054
+ - **External File** — Animation loads from a separate JSON file. Better for larger animations.
1055
+
1056
+ The dialog shows the generated HTML/JavaScript code with a **Copy Code** button. For external file mode, you can also **Download JSON** to get the animation data file.
1057
+
1058
+ **Steps to embed:**
1059
+ 1. Build the player: `npm run build:player`
1060
+ 2. Copy `lib/player/tinyfly-player.iife.js` to your project (or load
1061
+ `https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.94.0/cdn/tinyfly-player.iife.js`
1062
+ instead; see [Deployment](DEPLOYMENT.md))
1063
+ 3. Copy the generated code into your HTML
1064
+ 4. Adjust the script `src` path if needed
1065
+
1066
+ ### Export Formats
1067
+
1068
+ Click **Export** in the toolbar and pick a format:
1069
+
1070
+ - **CSS** — Generates CSS `@keyframes` animations
1071
+ - **Lottie** — Exports bodymovin-compatible Lottie JSON
1072
+ - **GIF** — A real animated GIF (per-frame palette, transparent background option)
1073
+ - **WebP** — Animated WebP — smaller and truer in colour than GIF, with full alpha
1074
+ - **MP4** — video. Pick the codec from the formats your browser supports: MP4
1075
+ (H.264) is encoded frame by frame with WebCodecs where available; otherwise MP4 or
1076
+ WebM (VP9/VP8) is recorded in real time with MediaRecorder
1077
+ - **Sprite** — Every frame packed into one **PNG grid** plus a **JSON** metadata
1078
+ file (frame size, columns/rows, count, fps) — ready for game engines or a custom
1079
+ `<canvas>` player. Alpha is kept when Transparent is on. See
1080
+ [sprite-sheet-export.md](sprite-sheet-export.md).
1081
+
1082
+ **JSON** export/import lives in the **More** (⋯) menu — the standard tinyfly
1083
+ format, which can be re-imported. GIF/WebP/MP4/Sprite composite shapes, text,
1084
+ paths, images, video layers, symbols, **and the camera**.
1085
+
1086
+ ### Import
1087
+
1088
+ Choose **More → Import JSON…** in the toolbar to load a previously exported JSON file. This replaces the current project.
1089
+
1090
+ ## Renderer Preview
1091
+
1092
+ The preview panel supports three rendering modes, switchable via the renderer selector:
1093
+
1094
+ - **DOM** — Elements rendered as HTML `<div>` elements with CSS
1095
+ - **Canvas** — Elements drawn on a `<canvas>` using Canvas 2D API
1096
+ - **SVG** — Elements rendered as SVG shapes
1097
+
1098
+ All three renderers play the same animation — switch between them to verify cross-renderer compatibility.
1099
+
1100
+ ### Onion skinning
1101
+
1102
+ In the **Canvas** renderer, click **🧅 Onion** to show faint **ghost frames**
1103
+ before and after the playhead — brightest nearest the current time — so you can
1104
+ see the arc of a move (a bounce, a swing) while editing a single frame. It draws
1105
+ only while paused and is editor-only (never exported). See
1106
+ [onion-skinning.md](onion-skinning.md).
1107
+
1108
+ ### Maximizing the preview
1109
+
1110
+ The stage automatically scales up to fill the available preview area. For a much
1111
+ larger view, click **⛶ Maximize** in the preview header — the preview fills the
1112
+ whole window with a floating play / stop / exit bar. Press **Esc** (or **Restore**)
1113
+ to return. Selection and dragging stay pixel-accurate at any scale.
1114
+
1115
+ ## Camera
1116
+
1117
+ A **camera** animates a **pan / zoom / rotate** over the whole stage — cinematic
1118
+ moves without touching your elements. Click **🎥 Camera** in the preview header to
1119
+ add one (click again to remove it).
1120
+
1121
+ Adding a camera creates four tracks on a reserved **`Camera`** target:
1122
+
1123
+ - `x`, `y` — pan the stage
1124
+ - `scale` — zoom (around the centre)
1125
+ - `rotate` — rotate (around the centre)
1126
+
1127
+ They're seeded at identity with a keyframe at the start and end, so the camera
1128
+ starts still. There are three ways to author it:
1129
+
1130
+ - **Camera inspector.** With a camera present and nothing selected, the Property
1131
+ Panel shows a **🎥 Camera** section (Pan X/Y, Zoom, Rotation). Editing a field
1132
+ sets a keyframe **at the playhead** — scrub to a time, dial in the framing, done.
1133
+ "Reset to identity" and "Remove camera" live there too.
1134
+ - **On-stage pan.** Click **✋ Pan** in the preview header, then drag the stage to
1135
+ pan the camera (also keyframed at the playhead).
1136
+ - **Timeline lane.** The Camera tracks float to the top of the timeline as a
1137
+ distinct **🎥 Camera** lane — keyframe/drag them like any track (e.g. `scale`
1138
+ `1`→`2` for a push-in, or `x` across the frame for a pan).
1139
+
1140
+ The camera applies in **all previews (DOM/Canvas/SVG)**, **raster export**
1141
+ (GIF/WebP/MP4/Sprite) and **embeds** (single & multi-scene). Ready-made **Camera**
1142
+ examples (Push In, Pan Across, Orbit Reveal) are on the Examples page. Tip: set up
1143
+ your elements first, then keyframe the camera (editing while the camera is mid-move
1144
+ is approximate for now). See [camera.md](camera.md).
1145
+
1146
+ ## Project Management
1147
+
1148
+ ### Saving & auto-save
1149
+
1150
+ tinyfly saves continuously — like Google Docs, there's no "save or lose it":
1151
+
1152
+ - **Auto-save.** Every edit is written to the browser's **IndexedDB** a moment
1153
+ after you make it. The `*` next to the title means a save is pending; it clears
1154
+ once written. Nothing is uploaded — it's all local to your browser.
1155
+ - **Explicit Save.** The **Save** button shows **Save / Saving… / Saved ✓** and
1156
+ lets you force a save any time (nice on touch devices). It's optional — auto-save
1157
+ already has you covered.
1158
+ - **On close.** The latest edit is flushed when you close or reload the tab, so a
1159
+ fast reload can't lose your last change.
1160
+
1161
+ Projects made before this used a single LocalStorage slot; those are migrated
1162
+ into IndexedDB automatically the first time you open the new version.
1163
+
1164
+ ### My Animations (the gallery)
1165
+
1166
+ Click **My Animations** in the toolbar to see **every project you've made** as a
1167
+ grid of cards, each with a live thumbnail and "last modified" time:
1168
+
1169
+ - **Open** — click a card to keep editing it (the one you're on is badged).
1170
+ - **Duplicate** — make a copy to experiment safely.
1171
+ - **Delete** — remove one (with a confirm).
1172
+ - **New** — start a fresh project from the gallery.
1173
+
1174
+ ### Renaming
1175
+
1176
+ Two ways: **double-click the project title** in the toolbar to rename it inline,
1177
+ or open **Project Settings** (⚙ in the header).
1178
+
1179
+ ### Project Settings
1180
+
1181
+ Open Project Settings (⚙ in the header, next to the logo) to:
1182
+
1183
+ - **Rename** the project
1184
+ - **Set canvas size** (width and height in pixels)
1185
+ - **Set the artboard background** colour (also the default background for GIF/
1186
+ WebP/MP4 export)
1187
+
1188
+ ### New Project
1189
+
1190
+ Click **New** in the toolbar. If you have unsaved changes you'll be asked whether
1191
+ to save first. Your previous project isn't lost — it stays in **My Animations**.
1192
+
1193
+ ## Keyboard Shortcuts
1194
+
1195
+ ### General
1196
+
1197
+ | Shortcut | Action |
1198
+ |----------|--------|
1199
+ | Ctrl+Z | Undo |
1200
+ | Ctrl+Shift+Z | Redo |
1201
+ | Ctrl+Y | Redo (alternate) |
1202
+ | ? | Show keyboard shortcuts |
1203
+
1204
+ ### Selection
1205
+
1206
+ | Shortcut | Action |
1207
+ |----------|--------|
1208
+ | Ctrl+A | Select all elements |
1209
+ | Ctrl+Click | Toggle multi-selection |
1210
+ | Esc | Deselect all |
1211
+
1212
+ ### Elements
1213
+
1214
+ | Shortcut | Action |
1215
+ |----------|--------|
1216
+ | Delete / Backspace | Delete selected element(s) |
1217
+ | Ctrl+D | Duplicate element |
1218
+ | Ctrl+C | Copy element(s) |
1219
+ | Ctrl+X | Cut element(s) |
1220
+ | Ctrl+V | Paste element(s) |
1221
+ | Ctrl+G | Group selected elements |
1222
+ | Ctrl+Shift+G | Ungroup |
1223
+
1224
+ ### Transform
1225
+
1226
+ | Shortcut | Action |
1227
+ |----------|--------|
1228
+ | Arrow keys | Nudge element 1px |
1229
+ | Shift+Arrow | Nudge element 10px |
1230
+ | Shift+Resize | Proportionate resize |
1231
+ | Shift+Rotate | Snap to 15-degree increments |
1232
+
1233
+ > **Mac users:** Replace Ctrl with Cmd for all shortcuts.
1234
+
1235
+ ## Tips & Workflow
1236
+
1237
+ 1. **Start with presets** — Apply a preset to quickly set up tracks and keyframes, then customize from there.
1238
+
1239
+ 2. **Study the examples** — Open examples in the editor to learn common patterns. Look at how tracks, keyframes, and easing work together.
1240
+
1241
+ 3. **Use easing** — Linear animations look mechanical. Use `ease-out` for entrance animations (fast start, gentle landing) and `ease-in` for exits.
1242
+
1243
+ 4. **Layer your animations** — Combine multiple properties (e.g., opacity + x + rotation) for richer effects.
1244
+
1245
+ 5. **Use scenes for multi-step animations** — Break complex animations into scenes with transitions between them.
1246
+
1247
+ 6. **Preview in all renderers** — Switch between DOM, Canvas, and SVG to ensure your animation looks good everywhere.
1248
+
1249
+ 7. **Export early, test often** — Use the Embed dialog to generate test code and verify your animation works in a real webpage.