@algorisys/tinyfly 0.92.0 → 0.93.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. package/README.md +7 -6
  2. package/bin/tinyfly.mjs +34 -1
  3. package/docs/2d-animation-roadmap.md +191 -0
  4. package/docs/3d-rotations.md +164 -0
  5. package/docs/3d-support-plan.md +628 -0
  6. package/docs/DEPLOYMENT.md +414 -0
  7. package/docs/acting.md +466 -0
  8. package/docs/api-reference.md +2353 -0
  9. package/docs/camera.md +94 -0
  10. package/docs/cartoon-hands.md +96 -0
  11. package/docs/character-system-m1.md +218 -0
  12. package/docs/character-system-plan.md +384 -0
  13. package/docs/dance.md +315 -0
  14. package/docs/editor-guide.md +1249 -0
  15. package/docs/examples.md +765 -0
  16. package/docs/extending.md +168 -0
  17. package/docs/file-format.md +690 -0
  18. package/docs/getting-started.md +314 -0
  19. package/docs/grid-and-snapping.md +64 -0
  20. package/docs/gsap-compat.md +1241 -0
  21. package/docs/llm-guide.md +123 -0
  22. package/docs/maps.md +116 -0
  23. package/docs/onion-skinning.md +41 -0
  24. package/docs/pen-tool.md +65 -0
  25. package/docs/polygon-star.md +44 -0
  26. package/docs/scene-3d.md +299 -0
  27. package/docs/scroll-animation.md +314 -0
  28. package/docs/shape-morph.md +61 -0
  29. package/docs/sprite-sheet-export.md +54 -0
  30. package/docs/symbols-and-library.md +137 -0
  31. package/docs/teaching.md +348 -0
  32. package/docs/video-rendering.md +728 -0
  33. package/lib/addons/adapters.js +22 -18
  34. package/lib/addons/characters.js +2694 -1809
  35. package/lib/addons/target-properties-BtN9skb-.js +142 -0
  36. package/lib/browser/tinyfly.iife.js +9 -4
  37. package/lib/browser/tinyfly.js +6498 -5483
  38. package/lib/browser/tinyfly.umd.js +9 -4
  39. package/lib/engine/tinyfly-engine.js +286 -258
  40. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  41. package/lib/types/adapters/canvas/canvas-adapter.d.ts +6 -0
  42. package/lib/types/adapters/canvas/index.d.ts +1 -0
  43. package/lib/types/adapters/canvas/target-properties.d.ts +68 -0
  44. package/lib/types/characters/acting/beat-check.d.ts +95 -0
  45. package/lib/types/characters/acting/hand-path.d.ts +32 -0
  46. package/lib/types/characters/acting/index.d.ts +2 -0
  47. package/lib/types/characters/acting/script.d.ts +66 -7
  48. package/lib/types/characters/capabilities.d.ts +50 -0
  49. package/lib/types/characters/code-panel.d.ts +201 -0
  50. package/lib/types/characters/figure-actions.d.ts +11 -0
  51. package/lib/types/characters/figure-props.d.ts +87 -0
  52. package/lib/types/characters/gaits.d.ts +8 -0
  53. package/lib/types/characters/index.d.ts +3 -0
  54. package/lib/types/characters/stick-figure.d.ts +2 -0
  55. package/lib/types/engine/authoring/did-you-mean.d.ts +14 -0
  56. package/lib/types/engine/authoring/index.d.ts +1 -0
  57. package/llms-full.txt +12548 -0
  58. package/llms.txt +57 -0
  59. package/package.json +6 -2
  60. package/skills/tinyfly/SKILL.md +64 -0
  61. package/lib/addons/camera-C7bZOWMB.js +0 -33
@@ -0,0 +1,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
+ ```