@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,414 @@
|
|
|
1
|
+
# Deployment Guide
|
|
2
|
+
|
|
3
|
+
This guide covers how to deploy tinyfly to various platforms.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
- Node.js 18+ installed
|
|
8
|
+
- npm or yarn package manager
|
|
9
|
+
|
|
10
|
+
## Build for Production
|
|
11
|
+
|
|
12
|
+
```bash
|
|
13
|
+
# Install dependencies
|
|
14
|
+
npm install
|
|
15
|
+
|
|
16
|
+
# Build the application
|
|
17
|
+
npm run build
|
|
18
|
+
|
|
19
|
+
# Build the embeddable player (optional)
|
|
20
|
+
npm run build:player
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The build output is in the `dist/` directory. The player build goes to
|
|
24
|
+
`lib/player/` instead, so an app build (which empties `dist/`) doesn't delete it.
|
|
25
|
+
|
|
26
|
+
Besides the editor, `npm run build` writes the docs for language models to the
|
|
27
|
+
site root (see `vite-llms-plugin.ts`):
|
|
28
|
+
|
|
29
|
+
- `llms.txt` — an [llmstxt.org](https://llmstxt.org) index of the docs
|
|
30
|
+
- `llms-full.txt` — every doc in one file
|
|
31
|
+
- `docs/<page>.md` — each doc as raw markdown
|
|
32
|
+
|
|
33
|
+
Configure your host to serve `.md` and `.txt` files as text (`text/markdown` and
|
|
34
|
+
`text/plain`), not as downloads, and make sure the SPA fallback below doesn't
|
|
35
|
+
replace them with `index.html`. Because `/docs` is also an editor route, the host
|
|
36
|
+
must answer `/docs` with `index.html`, not a directory listing or an error for the
|
|
37
|
+
`docs/` folder. The dev server serves the same paths.
|
|
38
|
+
|
|
39
|
+
## Publishing to OSS Repository
|
|
40
|
+
|
|
41
|
+
The project uses a separate OSS (Open Source Software) repository for public releases. The `publish-oss.sh` script handles publishing a cleaned version without internal files.
|
|
42
|
+
|
|
43
|
+
### What Gets Excluded
|
|
44
|
+
|
|
45
|
+
Files listed in `.ossignore` are excluded from OSS publishing:
|
|
46
|
+
- `scripts/` - Internal publishing scripts
|
|
47
|
+
- `CLAUDE.md` - Internal AI instructions
|
|
48
|
+
|
|
49
|
+
### Publishing Process
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Dry run - preview what will be published
|
|
53
|
+
npm run release:oss:dry-run # ./scripts/publish-oss.sh
|
|
54
|
+
|
|
55
|
+
# Push to the OSS repo, build the CDN bundles into cdn/, and tag v{version}
|
|
56
|
+
npm run release:oss # ./scripts/publish-oss.sh --push
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
These two npm scripts exist only in the private repository: the publish script
|
|
60
|
+
replaces the OSS copy's `scripts` with the public set (`dev`, `build`, the library
|
|
61
|
+
builds, `test`, `e2e`), since `scripts/` itself is not published.
|
|
62
|
+
|
|
63
|
+
### What the Script Does
|
|
64
|
+
|
|
65
|
+
1. Creates a clean copy from the latest git commit
|
|
66
|
+
2. Removes paths listed in `.ossignore`
|
|
67
|
+
3. Builds the browser and player bundles from that copy into `cdn/`
|
|
68
|
+
4. Patches `package.json` (removes `private` flag)
|
|
69
|
+
5. Pushes to the OSS repository and tags the commit `v{version}`, unless that
|
|
70
|
+
tag already exists (see [jsDelivr GitHub CDN](#jsdelivr-github-cdn))
|
|
71
|
+
|
|
72
|
+
### Environment Variables
|
|
73
|
+
|
|
74
|
+
| Variable | Description | Default |
|
|
75
|
+
|----------|-------------|---------|
|
|
76
|
+
| `OSS_REMOTE` | Git URL of the OSS repository | `https://github.com/algorisys-oss/tinyfly.git` |
|
|
77
|
+
| `OSS_BRANCH` | Branch to push to | `main` |
|
|
78
|
+
| `OSS_MESSAGE` | Custom commit message | Auto-generated |
|
|
79
|
+
|
|
80
|
+
### Example with Custom Message
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
OSS_REMOTE=https://github.com/algorisys-oss/tinyfly.git \
|
|
84
|
+
OSS_MESSAGE="Release v1.0.0" \
|
|
85
|
+
./scripts/publish-oss.sh --push
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Deployment Options
|
|
89
|
+
|
|
90
|
+
### 1. Static Hosting (Recommended)
|
|
91
|
+
|
|
92
|
+
Tinyfly is a static SPA (Single Page Application) that can be deployed to any static hosting service.
|
|
93
|
+
|
|
94
|
+
#### Vercel
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
# Install Vercel CLI
|
|
98
|
+
npm i -g vercel
|
|
99
|
+
|
|
100
|
+
# Deploy
|
|
101
|
+
vercel
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Or connect your GitHub repository to Vercel for automatic deployments.
|
|
105
|
+
|
|
106
|
+
#### Netlify
|
|
107
|
+
|
|
108
|
+
```bash
|
|
109
|
+
# Install Netlify CLI
|
|
110
|
+
npm i -g netlify-cli
|
|
111
|
+
|
|
112
|
+
# Deploy
|
|
113
|
+
netlify deploy --prod --dir=dist
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Or drag and drop the `dist/` folder to [Netlify Drop](https://app.netlify.com/drop).
|
|
117
|
+
|
|
118
|
+
**netlify.toml** (optional, for redirects):
|
|
119
|
+
```toml
|
|
120
|
+
[[redirects]]
|
|
121
|
+
from = "/*"
|
|
122
|
+
to = "/index.html"
|
|
123
|
+
status = 200
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
#### GitHub Pages
|
|
127
|
+
|
|
128
|
+
1. Build the project:
|
|
129
|
+
```bash
|
|
130
|
+
npm run build
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
2. Add base path to `vite.config.ts` if deploying to a subpath:
|
|
134
|
+
```typescript
|
|
135
|
+
export default defineConfig({
|
|
136
|
+
base: '/tinyfly/',
|
|
137
|
+
plugins: [solid()],
|
|
138
|
+
})
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
3. Deploy using GitHub Actions or manually push the `dist/` folder to the `gh-pages` branch.
|
|
142
|
+
|
|
143
|
+
**GitHub Actions workflow** (`.github/workflows/deploy.yml`):
|
|
144
|
+
```yaml
|
|
145
|
+
name: Deploy to GitHub Pages
|
|
146
|
+
|
|
147
|
+
on:
|
|
148
|
+
push:
|
|
149
|
+
branches: [main]
|
|
150
|
+
|
|
151
|
+
jobs:
|
|
152
|
+
deploy:
|
|
153
|
+
runs-on: ubuntu-latest
|
|
154
|
+
steps:
|
|
155
|
+
- uses: actions/checkout@v4
|
|
156
|
+
|
|
157
|
+
- name: Setup Node.js
|
|
158
|
+
uses: actions/setup-node@v4
|
|
159
|
+
with:
|
|
160
|
+
node-version: '20'
|
|
161
|
+
cache: 'npm'
|
|
162
|
+
|
|
163
|
+
- name: Install dependencies
|
|
164
|
+
run: npm ci
|
|
165
|
+
|
|
166
|
+
- name: Build
|
|
167
|
+
run: npm run build
|
|
168
|
+
|
|
169
|
+
- name: Deploy to GitHub Pages
|
|
170
|
+
uses: peaceiris/actions-gh-pages@v3
|
|
171
|
+
with:
|
|
172
|
+
github_token: ${{ secrets.GITHUB_TOKEN }}
|
|
173
|
+
publish_dir: ./dist
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
#### Cloudflare Pages
|
|
177
|
+
|
|
178
|
+
1. Connect your GitHub repository to Cloudflare Pages
|
|
179
|
+
2. Set build command: `npm run build`
|
|
180
|
+
3. Set output directory: `dist`
|
|
181
|
+
|
|
182
|
+
#### AWS S3 + CloudFront
|
|
183
|
+
|
|
184
|
+
```bash
|
|
185
|
+
# Build
|
|
186
|
+
npm run build
|
|
187
|
+
|
|
188
|
+
# Sync to S3 bucket
|
|
189
|
+
aws s3 sync dist/ s3://your-bucket-name --delete
|
|
190
|
+
|
|
191
|
+
# Invalidate CloudFront cache (if using)
|
|
192
|
+
aws cloudfront create-invalidation --distribution-id YOUR_DIST_ID --paths "/*"
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### 2. Docker Deployment
|
|
196
|
+
|
|
197
|
+
Create a `Dockerfile`:
|
|
198
|
+
|
|
199
|
+
```dockerfile
|
|
200
|
+
# Build stage
|
|
201
|
+
FROM node:20-alpine AS builder
|
|
202
|
+
WORKDIR /app
|
|
203
|
+
COPY package*.json ./
|
|
204
|
+
RUN npm ci
|
|
205
|
+
COPY . .
|
|
206
|
+
RUN npm run build
|
|
207
|
+
|
|
208
|
+
# Production stage
|
|
209
|
+
FROM nginx:alpine
|
|
210
|
+
COPY --from=builder /app/dist /usr/share/nginx/html
|
|
211
|
+
COPY nginx.conf /etc/nginx/conf.d/default.conf
|
|
212
|
+
EXPOSE 80
|
|
213
|
+
CMD ["nginx", "-g", "daemon off;"]
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
Create `nginx.conf`:
|
|
217
|
+
|
|
218
|
+
```nginx
|
|
219
|
+
server {
|
|
220
|
+
listen 80;
|
|
221
|
+
server_name localhost;
|
|
222
|
+
root /usr/share/nginx/html;
|
|
223
|
+
index index.html;
|
|
224
|
+
|
|
225
|
+
# Serve docs/*.md as text instead of a download (.txt is text/plain already)
|
|
226
|
+
location ~* \.md$ {
|
|
227
|
+
default_type text/markdown;
|
|
228
|
+
charset utf-8;
|
|
229
|
+
charset_types text/markdown;
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
# Handle SPA routing. No `$uri/`: /docs is an editor route, but dist/docs/
|
|
233
|
+
# is also a folder of .md files, and nginx would answer 403 for the folder.
|
|
234
|
+
location / {
|
|
235
|
+
try_files $uri /index.html;
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
# Cache static assets
|
|
239
|
+
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
|
|
240
|
+
expires 1y;
|
|
241
|
+
add_header Cache-Control "public, immutable";
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
# Gzip compression
|
|
245
|
+
gzip on;
|
|
246
|
+
gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Build and run:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
# Build image
|
|
254
|
+
docker build -t tinyfly .
|
|
255
|
+
|
|
256
|
+
# Run container
|
|
257
|
+
docker run -p 8080:80 tinyfly
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
### 3. Node.js Server (with serve)
|
|
261
|
+
|
|
262
|
+
For simple deployments:
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
# Install serve globally
|
|
266
|
+
npm i -g serve
|
|
267
|
+
|
|
268
|
+
# Build and serve
|
|
269
|
+
npm run build
|
|
270
|
+
serve -s dist -l 3000
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
## Environment Configuration
|
|
274
|
+
|
|
275
|
+
### Base URL
|
|
276
|
+
|
|
277
|
+
If deploying to a subpath (e.g., `https://example.com/tinyfly/`), update `vite.config.ts`:
|
|
278
|
+
|
|
279
|
+
```typescript
|
|
280
|
+
export default defineConfig({
|
|
281
|
+
base: '/tinyfly/',
|
|
282
|
+
plugins: [solid()],
|
|
283
|
+
})
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### SPA Routing
|
|
287
|
+
|
|
288
|
+
tinyfly uses client-side routing. Addresses such as `/studio` (the editor; `/app`
|
|
289
|
+
redirects there), `/learn/…`, `/examples/<id>`, `/showcase/…` and `/docs/…` are
|
|
290
|
+
not files, so opening or **refreshing** one gives "page not found" unless the host
|
|
291
|
+
answers unknown addresses with `index.html`. Real files (assets, `llms.txt`,
|
|
292
|
+
`docs/*.md`) must still be served as themselves.
|
|
293
|
+
|
|
294
|
+
The build includes a fallback for the common hosts:
|
|
295
|
+
|
|
296
|
+
| Host | What handles it |
|
|
297
|
+
|---|---|
|
|
298
|
+
| Netlify, Cloudflare Pages | `public/_redirects` → `dist/_redirects` (`/* /index.html 200`) |
|
|
299
|
+
| Vercel | `vercel.json` (rewrites paths without a file extension to `/index.html`) |
|
|
300
|
+
| GitHub Pages and plain static hosts that serve `404.html` | `dist/404.html`, a copy of `index.html` written by the build |
|
|
301
|
+
| nginx | `try_files $uri /index.html;` (see the nginx example above) |
|
|
302
|
+
| Apache, LiteSpeed (Hostinger and most shared hosting) | `public/.htaccess` → `dist/.htaccess`: rewrites missing paths to `index.html`, serves `.md` / `.txt` as text, caches hashed assets. Upload the dotfile with the rest of `dist/` |
|
|
303
|
+
| Caddy | `try_files {path} /index.html` |
|
|
304
|
+
|
|
305
|
+
If refreshing a page still shows "not found", the host is ignoring these files.
|
|
306
|
+
Set its single-page-app or rewrite option to serve `/index.html` for missing paths.
|
|
307
|
+
|
|
308
|
+
## Embedding the Player
|
|
309
|
+
|
|
310
|
+
The embeddable player can be built separately:
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
npm run build:player
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
This writes `lib/player/tinyfly-player.{iife,es,umd}.js`. The IIFE build is a
|
|
317
|
+
plain script that puts the player on a `tinyfly` global:
|
|
318
|
+
|
|
319
|
+
```html
|
|
320
|
+
<div id="container"></div>
|
|
321
|
+
|
|
322
|
+
<script src="https://your-cdn.com/tinyfly-player.iife.js"></script>
|
|
323
|
+
<script>
|
|
324
|
+
tinyfly.play('#container', 'animation.json', { loop: -1, autoplay: true })
|
|
325
|
+
</script>
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
This is the same code the editor's **Embed** dialog generates.
|
|
329
|
+
|
|
330
|
+
## jsDelivr GitHub CDN
|
|
331
|
+
|
|
332
|
+
Every release publishes the bundles to the `cdn/` folder of
|
|
333
|
+
[algorisys-oss/tinyfly](https://github.com/algorisys-oss/tinyfly) and tags the
|
|
334
|
+
commit `v{version}` (`./scripts/publish-oss.sh --push`, above). jsDelivr serves
|
|
335
|
+
them straight from GitHub, so you don't need to host the scripts yourself:
|
|
336
|
+
|
|
337
|
+
```
|
|
338
|
+
https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v{version}/cdn/tinyfly.iife.js
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
| File | What | Global |
|
|
342
|
+
|---|---|---|
|
|
343
|
+
| `tinyfly.iife.js` | Everything: engine, player, `live` (GSAP-style), drivers, interaction | `@algorisys/tinyfly` |
|
|
344
|
+
| `tinyfly.umd.js` | The same, as UMD | `@algorisys/tinyfly` |
|
|
345
|
+
| `tinyfly.esm.js` | The same, as an ES module | — |
|
|
346
|
+
| `tinyfly-player.iife.js` | Player only, for playing exported JSON | `@algorisys/tinyfly` |
|
|
347
|
+
|
|
348
|
+
Pin a version tag in production. The script never moves an existing tag, so a
|
|
349
|
+
pinned URL keeps serving the same file; bump the version in `package.json` to
|
|
350
|
+
publish new bundles. `@main` follows the latest publish and jsDelivr caches it for
|
|
351
|
+
up to a day.
|
|
352
|
+
|
|
353
|
+
## Performance Optimization
|
|
354
|
+
|
|
355
|
+
### Caching Headers
|
|
356
|
+
|
|
357
|
+
Configure your server/CDN with appropriate cache headers:
|
|
358
|
+
|
|
359
|
+
| File Type | Cache Duration |
|
|
360
|
+
|-----------|---------------|
|
|
361
|
+
| `*.html` | No cache or short (5 min) |
|
|
362
|
+
| `*.js`, `*.css` | 1 year (files are hashed) |
|
|
363
|
+
| `*.json` (animations) | Based on update frequency |
|
|
364
|
+
|
|
365
|
+
### CDN Configuration
|
|
366
|
+
|
|
367
|
+
For best performance:
|
|
368
|
+
1. Enable gzip/brotli compression
|
|
369
|
+
2. Use HTTP/2 or HTTP/3
|
|
370
|
+
3. Configure appropriate cache headers
|
|
371
|
+
4. Consider edge caching for static assets
|
|
372
|
+
|
|
373
|
+
## Monitoring
|
|
374
|
+
|
|
375
|
+
### Health Check Endpoint
|
|
376
|
+
|
|
377
|
+
The application serves static files, so a simple HTTP 200 check on `/` suffices.
|
|
378
|
+
|
|
379
|
+
### Error Tracking
|
|
380
|
+
|
|
381
|
+
Consider integrating error tracking (Sentry, LogRocket, etc.) by adding the script to `index.html`:
|
|
382
|
+
|
|
383
|
+
```html
|
|
384
|
+
<script src="https://js.sentry-cdn.com/your-key.min.js" crossorigin="anonymous"></script>
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
## Troubleshooting
|
|
388
|
+
|
|
389
|
+
### Routes return 404
|
|
390
|
+
|
|
391
|
+
Ensure your server is configured to serve `index.html` for all routes (SPA fallback).
|
|
392
|
+
|
|
393
|
+
### Assets not loading
|
|
394
|
+
|
|
395
|
+
Check the `base` path in `vite.config.ts` matches your deployment path.
|
|
396
|
+
|
|
397
|
+
### CORS issues with animations
|
|
398
|
+
|
|
399
|
+
If loading animation JSON files from a different domain, ensure CORS headers are set:
|
|
400
|
+
|
|
401
|
+
```
|
|
402
|
+
Access-Control-Allow-Origin: *
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
## Security Considerations
|
|
406
|
+
|
|
407
|
+
1. **Content Security Policy**: Configure appropriate CSP headers
|
|
408
|
+
2. **HTTPS**: Always use HTTPS in production
|
|
409
|
+
3. **Subresource Integrity**: Consider adding SRI to external scripts
|
|
410
|
+
|
|
411
|
+
Example CSP header:
|
|
412
|
+
```
|
|
413
|
+
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;
|
|
414
|
+
```
|