@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.
- package/README.md +7 -6
- package/bin/tinyfly.mjs +34 -1
- package/docs/2d-animation-roadmap.md +191 -0
- package/docs/3d-rotations.md +164 -0
- package/docs/3d-support-plan.md +628 -0
- package/docs/DEPLOYMENT.md +414 -0
- package/docs/acting.md +466 -0
- package/docs/api-reference.md +2353 -0
- package/docs/camera.md +94 -0
- package/docs/cartoon-hands.md +96 -0
- package/docs/character-system-m1.md +218 -0
- package/docs/character-system-plan.md +384 -0
- package/docs/dance.md +315 -0
- package/docs/editor-guide.md +1249 -0
- package/docs/examples.md +765 -0
- package/docs/extending.md +168 -0
- package/docs/file-format.md +690 -0
- package/docs/getting-started.md +314 -0
- package/docs/grid-and-snapping.md +64 -0
- package/docs/gsap-compat.md +1241 -0
- package/docs/llm-guide.md +123 -0
- package/docs/maps.md +116 -0
- package/docs/onion-skinning.md +41 -0
- package/docs/pen-tool.md +65 -0
- package/docs/polygon-star.md +44 -0
- package/docs/scene-3d.md +299 -0
- package/docs/scroll-animation.md +314 -0
- package/docs/shape-morph.md +61 -0
- package/docs/sprite-sheet-export.md +54 -0
- package/docs/symbols-and-library.md +137 -0
- package/docs/teaching.md +348 -0
- package/docs/video-rendering.md +728 -0
- package/lib/addons/adapters.js +22 -18
- package/lib/addons/characters.js +2785 -1794
- package/lib/addons/target-properties-BtN9skb-.js +142 -0
- package/lib/browser/tinyfly.iife.js +9 -4
- package/lib/browser/tinyfly.js +6575 -5454
- package/lib/browser/tinyfly.umd.js +9 -4
- package/lib/engine/tinyfly-engine.js +286 -258
- package/lib/engine/tinyfly-engine.umd.cjs +2 -2
- package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
- package/lib/types/adapters/canvas/index.d.ts +1 -0
- package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
- package/lib/types/characters/acting/beat-check.d.ts +95 -0
- package/lib/types/characters/acting/hand-path.d.ts +32 -0
- package/lib/types/characters/acting/index.d.ts +2 -0
- package/lib/types/characters/acting/script.d.ts +66 -7
- package/lib/types/characters/capabilities.d.ts +50 -0
- package/lib/types/characters/code-panel.d.ts +201 -0
- package/lib/types/characters/figure-actions.d.ts +11 -0
- package/lib/types/characters/figure-props.d.ts +87 -0
- package/lib/types/characters/gaits.d.ts +8 -0
- package/lib/types/characters/index.d.ts +4 -0
- package/lib/types/characters/species/human-motion.d.ts +45 -0
- package/lib/types/characters/species/human.d.ts +2 -0
- package/lib/types/characters/stick-figure.d.ts +2 -0
- package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
- package/lib/types/engine/authoring/index.d.ts +1 -0
- package/llms-full.txt +12548 -0
- package/llms.txt +57 -0
- package/package.json +6 -2
- package/skills/tinyfly/SKILL.md +64 -0
- 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.
|