@algorisys/tinyfly 0.82.0 → 0.87.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 (71) hide show
  1. package/README.md +13 -4
  2. package/bin/tinyfly.mjs +44 -6
  3. package/lib/addons/adapters.js +411 -248
  4. package/lib/addons/characters.js +1652 -1470
  5. package/lib/addons/dom-adapter-Cphr2HZn.js +372 -0
  6. package/lib/addons/gsap-compat.js +197 -187
  7. package/lib/addons/load-scene-vp14_Jj-.js +324 -0
  8. package/lib/addons/maps.js +1 -1
  9. package/lib/addons/scene-3d-webgl.js +240 -0
  10. package/lib/addons/scene-3d.js +306 -0
  11. package/lib/addons/shading-o5T_v9DT.js +89 -0
  12. package/lib/addons/{sketch-CA8ZXhxI.js → sketch-CYPUbk3Q.js} +2 -2
  13. package/lib/browser/tinyfly-scene-3d-webgl.iife.js +116 -0
  14. package/lib/browser/tinyfly-scene-3d.iife.js +3 -0
  15. package/lib/browser/tinyfly.iife.js +4 -4
  16. package/lib/browser/tinyfly.js +4333 -3726
  17. package/lib/browser/tinyfly.umd.js +4 -4
  18. package/lib/cli/tools.js +137 -22
  19. package/lib/embed/tinyfly-embed.iife.js +4 -4
  20. package/lib/embed/tinyfly-embed.js +921 -833
  21. package/lib/engine/tinyfly-engine.js +1022 -776
  22. package/lib/engine/tinyfly-engine.umd.cjs +2 -2
  23. package/lib/headless/headless.js +410 -8
  24. package/lib/player/tinyfly-player.es.js +459 -371
  25. package/lib/player/tinyfly-player.iife.js +2 -2
  26. package/lib/player/tinyfly-player.umd.js +2 -2
  27. package/lib/types/adapters/canvas/bloom.d.ts +33 -0
  28. package/lib/types/adapters/canvas/canvas-adapter.d.ts +36 -0
  29. package/lib/types/adapters/canvas/index.d.ts +2 -0
  30. package/lib/types/adapters/canvas/offscreen.d.ts +13 -0
  31. package/lib/types/adapters/transform-3d.d.ts +99 -0
  32. package/lib/types/adapters/webgl/webgl-adapter.d.ts +17 -0
  33. package/lib/types/browser/index.d.ts +2 -0
  34. package/lib/types/characters/character.d.ts +20 -1
  35. package/lib/types/characters/index.d.ts +2 -0
  36. package/lib/types/characters/rig/body-plan.d.ts +3 -1
  37. package/lib/types/characters/rig/skeleton.d.ts +57 -0
  38. package/lib/types/characters/scene-objects.d.ts +2 -0
  39. package/lib/types/compat/gsap/vars.d.ts +8 -0
  40. package/lib/types/engine/core/bake.d.ts +3 -1
  41. package/lib/types/engine/index.d.ts +1 -0
  42. package/lib/types/engine/interpolation/interpolators.d.ts +10 -3
  43. package/lib/types/engine/math/index.d.ts +11 -0
  44. package/lib/types/engine/math/mat4.d.ts +37 -0
  45. package/lib/types/engine/math/quat.d.ts +39 -0
  46. package/lib/types/engine/math/vec3.d.ts +16 -0
  47. package/lib/types/engine/types.d.ts +23 -2
  48. package/lib/types/headless/index.d.ts +1 -0
  49. package/lib/types/headless/loop-check.d.ts +41 -0
  50. package/lib/types/headless/node-video.d.ts +8 -0
  51. package/lib/types/headless/video-scene.d.ts +7 -1
  52. package/lib/types/scene-3d/camera.d.ts +27 -0
  53. package/lib/types/scene-3d/canvas-2d-renderer.d.ts +21 -0
  54. package/lib/types/scene-3d/geometry/extrude.d.ts +17 -0
  55. package/lib/types/scene-3d/geometry/mesh.d.ts +36 -0
  56. package/lib/types/scene-3d/geometry/primitives.d.ts +16 -0
  57. package/lib/types/scene-3d/geometry/triangulate.d.ts +24 -0
  58. package/lib/types/scene-3d/index.d.ts +20 -0
  59. package/lib/types/scene-3d/load-scene.d.ts +31 -0
  60. package/lib/types/scene-3d/object-kind.d.ts +54 -0
  61. package/lib/types/scene-3d/resolve-scene.d.ts +122 -0
  62. package/lib/types/scene-3d/scene-3d-adapter.d.ts +46 -0
  63. package/lib/types/scene-3d/scene-types.d.ts +192 -0
  64. package/lib/types/scene-3d/shading.d.ts +20 -0
  65. package/lib/types/scene-3d/validate-scene.d.ts +11 -0
  66. package/lib/types/scene-3d/webgl/gl-data.d.ts +29 -0
  67. package/lib/types/scene-3d/webgl/index.d.ts +16 -0
  68. package/lib/types/scene-3d/webgl/shaders.d.ts +29 -0
  69. package/lib/types/scene-3d/webgl/webgl2-renderer.d.ts +33 -0
  70. package/package.json +10 -2
  71. package/lib/addons/dom-adapter-CrNwoomd.js +0 -243
package/README.md CHANGED
@@ -9,6 +9,11 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
9
9
 
10
10
  **GSAP-level power with Excalidraw-level simplicity.**
11
11
 
12
+ > **Beta.** tinyfly is in beta testing. Watch out for breaking changes: we
13
+ > keep them to a minimum, and when a release has any, its
14
+ > [release notes](release-notes/README.md) say what changed and how to
15
+ > upgrade.
16
+
12
17
  ## Features
13
18
 
14
19
  ### Core Engine
@@ -91,6 +96,10 @@ A lightweight, API-driven animation engine and visual editor for creating high-p
91
96
  - **Camera** - Animate a pan/zoom/rotate over the whole stage (a reserved `Camera` layer driven by ordinary tracks). One-click add, a **🎥 Camera inspector** (Pan/Zoom/Rotation keyframed at the playhead), on-stage **✋ Pan** dragging, and a dedicated 🎥 lane at the top of the timeline; applies in every preview, export, and embed. Ready-made Push In / Pan Across / Orbit Reveal samples
92
97
  - **Polygon & star shapes** - ⬡ Polygon and ★ Star elements are parametric paths — edit sides / points / inner ratio in Properties and they regenerate and rescale; they render and export like any path
93
98
  - **Pen tool** - ✒️ Draw custom bezier paths: click for corners, click-drag for curves (Alt for a cusp), drag existing anchors/handles to adjust, snap points to grid/guides, click the first point or Enter to finish
99
+ - **Loop check** - `tinyfly video scene.mjs --loop-check` renders five frames and says whether a video loops: whether the frame at the duration matches the first, and whether the last → first seam looks like any other step (exit 1 when it does not). `--frames 0,79,88` renders stills at chosen frames. See [docs/video-rendering.md](docs/video-rendering.md#loops)
100
+ - **Bloom** - `bloom: true` on a video scene adds a deterministic glow around bright things (bright pass, blur, add; no `ctx.filter`), and 3D materials take `emissive` light that shines in the dark and feeds it. `applyBloom(ctx)` works on any 2D canvas. See [docs/video-rendering.md](docs/video-rendering.md#bloom)
101
+ - **3D scenes** - `@algorisys/tinyfly/scene-3d`: cameras, lights and meshes (box, sphere, cylinder, cone, torus, floor, any SVG path extruded) as JSON in metres, animated by ordinary tracks (`stage/box`), cut between cameras with one keyframe, drawn on a plain canvas with flat, smooth or toon shading, ink outlines and fog: in the browser, in Workers, and to MP4 in Node. Characters stand in scenes and dance, seen by any camera, in their pen looks (clean, pencil) or as solid figures (`characterObjects`). In the editor, a 🧊 3D Scene element builds them without code: add shapes, characters and lights, key them, dance from the playhead, cut between cameras. No WebGL needed (about 7 KB gzipped, its own entry and CDN script); for big or tangled scenes the optional WebGL2 renderer (`@algorisys/tinyfly/scene-3d/webgl`) adds a depth buffer and light per pixel. See [docs/scene-3d.md](docs/scene-3d.md)
102
+ - **3D transforms** - Cards, images, text and shapes turn in 3D (`rotateX`, `rotateY`, `z`, `perspective`, `backfaceVisibility`) and land on the same pixels in DOM, SVG, Canvas (true perspective, also headless) and WebGL, checked against each browser's own CSS. One documented transform order everywhere; Tilt / Turn / Depth / Perspective fields in the editor; 3D Card Flip and Cover Flow samples. Quaternion tracks with `interpolation: "slerp"` turn without gimbal lock; the engine's `vec3`, `quat` and `mat4` helpers are plain arrays. The first steps of [3D support](docs/3d-support-plan.md). See [docs/3d-rotations.md](docs/3d-rotations.md)
94
103
  - **Shape morph** - 🌀 Tween one path into another over the timeline (engine-level path interpolation); plays in every renderer, export, and embed
95
104
  - **Grid, snapping & guides** - ▦ 20px grid, 🧲 snapping of drag/resize to grid/element-edges/artboard with live alignment guides, and 📏 rulers with draggable guides
96
105
  - **Onion skinning** - 🧅 Faint ghost frames before/after the playhead (Canvas renderer) to see the arc of a move while editing one frame
@@ -225,7 +234,7 @@ GSAP-shaped functions at the top level. Teaching embeds are included: add
225
234
  itself.
226
235
 
227
236
  ```html
228
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.82.0/cdn/tinyfly.iife.js"></script>
237
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.87.0/cdn/tinyfly.iife.js"></script>
229
238
  <script>
230
239
  tinyfly.to('.box', { x: 200, rotate: 90, duration: 1, ease: 'power2.out' })
231
240
 
@@ -261,7 +270,7 @@ A teaching figure needs no code at all:
261
270
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON with markers… }</script>
262
271
  <figcaption>Appending to a full slice</figcaption>
263
272
  </figure>
264
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.82.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
273
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.87.0/cdn/tinyfly.iife.js" data-tinyfly-auto></script>
265
274
  ```
266
275
 
267
276
  See [Teaching Animations](docs/teaching.md).
@@ -360,7 +369,7 @@ Without a build step, the player bundle puts the same functions on a `tinyfly` g
360
369
  <div data-tinyfly="box" style="width: 60px; height: 60px; background: #4a9eff;"></div>
361
370
  </div>
362
371
 
363
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.82.0/cdn/tinyfly-player.iife.js"></script>
372
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.87.0/cdn/tinyfly-player.iife.js"></script>
364
373
  <script>
365
374
  tinyfly.play('#animation', './animation.json', { loop: -1 })
366
375
  </script>
@@ -469,7 +478,7 @@ Or skip the code entirely with declarative embeds (see [Teaching Animations](doc
469
478
  <svg viewBox="0 0 720 200">…</svg>
470
479
  <script type="application/json" data-tinyfly-timeline>{ …timeline JSON… }</script>
471
480
  </figure>
472
- <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.82.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
481
+ <script src="https://cdn.jsdelivr.net/gh/algorisys-oss/tinyfly@v0.87.0/cdn/tinyfly-embed.iife.js" data-tinyfly-auto></script>
473
482
  ```
474
483
 
475
484
  ### Audio / Video Sync
package/bin/tinyfly.mjs CHANGED
@@ -14,13 +14,16 @@
14
14
  * Print the markup with that frame written in, for places that run no
15
15
  * JavaScript (RSS, email, print, previews).
16
16
  *
17
- * tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--scale <n>] [--fps <n>]
18
- * [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]
17
+ * tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,ms,…>]
18
+ * [--loop-check] [--scale <n>] [--fps <n>] [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]
19
19
  * Render a scene module to an MP4 without a browser. The module's default
20
20
  * export is a VideoScene (or a function returning one): a timeline and
21
21
  * canvas targets, a draw(ctx, frame) function, or both. --stills writes
22
- * one PNG per marker step instead of a video. Needs ffmpeg on the PATH
23
- * and the optional package @napi-rs/canvas.
22
+ * one PNG per marker step instead of a video, or one per frame / time
23
+ * given with --frames or --times. --loop-check renders five frames and
24
+ * says whether the video loops (exit 1 when it does not). Needs ffmpeg on
25
+ * the PATH (not for stills or --loop-check) and the optional package
26
+ * @napi-rs/canvas.
24
27
  */
25
28
  import { readFileSync, writeFileSync } from 'node:fs'
26
29
  import { basename, dirname, extname, join, resolve } from 'node:path'
@@ -51,12 +54,25 @@ const numberFlag = (name) => {
51
54
  return number
52
55
  }
53
56
 
57
+ /** A comma-separated list of numbers (frames or ms), or undefined when the flag is absent. */
58
+ function listFlag(name) {
59
+ const value = flag(name)
60
+ if (value === undefined) return undefined
61
+ const numbers = value.split(',').map((part) => Number(part.trim()))
62
+ if (numbers.length === 0 || numbers.some((n) => !Number.isFinite(n) || n < 0)) {
63
+ console.error(`tinyfly: ${name} needs numbers separated by commas (got ${value})`)
64
+ process.exit(2)
65
+ }
66
+ return numbers
67
+ }
68
+
54
69
  const usage = () => {
55
70
  console.error(
56
71
  'Usage:\n' +
57
72
  ' tinyfly validate <timeline.json> [<timeline.json> …] [--markup <file>]\n' +
58
73
  ' tinyfly render <timeline.json> <markup file> [--at start|end|<ms>|<marker id>]\n' +
59
- ' tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--scale <n>] [--fps <n>] [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]'
74
+ ' tinyfly video <scene.mjs> [-o <out.mp4>] [--stills <dir>] [--frames <i,j,…> | --times <ms,…>] [--loop-check]\n' +
75
+ ' [--scale <n>] [--fps <n>] [--crf <n>] [--no-audio] [--srt <file>] [--vtt <file>]'
60
76
  )
61
77
  process.exit(2)
62
78
  }
@@ -114,8 +130,15 @@ async function video() {
114
130
  const fps = numberFlag('--fps')
115
131
  const crf = numberFlag('--crf')
116
132
  const silent = has('--no-audio')
133
+ const loopCheck = has('--loop-check')
134
+ const framesList = listFlag('--frames')
135
+ const timesList = listFlag('--times')
117
136
  const [sceneFile] = rest
118
137
  if (!sceneFile || rest.length > 1) usage()
138
+ if ((framesList || timesList) && !stillsDir) {
139
+ console.error('tinyfly: --frames and --times choose stills: add --stills <dir>')
140
+ process.exit(2)
141
+ }
119
142
 
120
143
  const headless = await import('../lib/headless/headless.js')
121
144
  const scenePath = resolve(sceneFile)
@@ -134,8 +157,23 @@ async function video() {
134
157
  if (vttFile) writeFileSync(vttFile, headless.toWebVTT(cues))
135
158
  console.error(`captions: ${cues.length} cue(s)`)
136
159
  }
160
+ if (loopCheck) {
161
+ const report = await headless.checkLoop(scene, { baseDir, scale, fps })
162
+ const db = (value) => (Number.isFinite(value) ? `${value.toFixed(2)} dB` : 'identical')
163
+ console.error(`frame at the duration vs the first: ${db(report.closure)}`)
164
+ console.error(`last → first (the seam): ${db(report.seam)}`)
165
+ console.error(`ordinary steps: ${db(report.steps[0])}, ${db(report.steps[1])}`)
166
+ console.error(`${report.loops ? '✓' : '✗'} ${report.verdict}`)
167
+ if (!report.loops) process.exit(1)
168
+ return
169
+ }
137
170
  if (stillsDir) {
138
- const files = await headless.renderStills(scene, { dir: stillsDir, baseDir, scale })
171
+ // Stills at chosen frames or times, else one per marker step.
172
+ const sceneFps = fps ?? scene.fps ?? 30
173
+ const times = framesList
174
+ ? framesList.map((frame) => ({ id: `frame-${frame}`, time: (frame * 1000) / sceneFps }))
175
+ : timesList?.map((time) => ({ id: `t-${time}ms`, time }))
176
+ const files = await headless.renderStills(scene, { dir: stillsDir, baseDir, scale, times })
139
177
  console.error(`stills: ${files.length} PNG(s) in ${stillsDir}`)
140
178
  return
141
179
  }