greenlight-motion 0.4.0 → 0.5.0

package/NOTICE

@@ -19,5 +19,9 @@ Files the engine downloads from the GreenLight CDN when a project uses them (sou
 lighting environments) are not part of this software and are not covered by the Apache License; see
 legal/THIRD_PARTY_ASSETS.md and legal/README.md.
 
+The 3D Scene engine is not part of this software: it is the 3D plugin, the separate package greenlight-motion-3d, which
+the engine downloads only when a project has a 3D Scene (or a page asks for it). It has its own licence (use yes; no
+copying, redistribution, modification or competing products) and is not covered by the Apache License.
+
 "GreenLight", "GreenLight Dash", "GLEA" and "GreenLight Motion" are trademarks of WPSOUL. The Apache
 License does not grant permission to use them; see legal/TRADEMARKS.md.

package/README.md

@@ -17,16 +17,16 @@ The agent writes the video as data: a `project.json` and its files. The engine t
 ## Quick start
 
 ```bash
-npx greenlight-motion@0.4.0 doctor          # Node 18+, Chrome or Edge, WebGPU, H.264: what's missing and how to fix it
-npx greenlight-motion@0.4.0 init my-video   # a working starter: index.html, project.json, assets/
+npx greenlight-motion@0.5.0 doctor          # Node 18+, Chrome or Edge, WebGPU, H.264: what's missing and how to fix it
+npx greenlight-motion@0.5.0 init my-video   # a working starter: index.html, project.json, assets/
 # edit my-video/project.json, put pictures / video / sound in my-video/assets/
 # or: write my-video/script.json (a scene script, skill/references/scene-script.md), then
-npx greenlight-motion@0.4.0 script my-video # script.json → project.json with the Video Editor's own presets
-npx greenlight-motion@0.4.0 check my-video  # what to fix: missing files, template mistakes, blank frames, broken plugins
-npx greenlight-motion@0.4.0 stills my-video # frames + a labelled contact sheet, to look at
-npx greenlight-motion@0.4.0 render my-video --fps 60 --motion-blur
-npx greenlight-motion@0.4.0 pack my-video   # everything in ONE html file
-npx greenlight-motion@0.4.0 pack my-video --glvideo   # ONE .glvideo: double-clicked, it opens in GreenLight Dash
+npx greenlight-motion@0.5.0 script my-video # script.json → project.json with the Video Editor's own presets
+npx greenlight-motion@0.5.0 check my-video  # what to fix: missing files, template mistakes, blank frames, broken plugins
+npx greenlight-motion@0.5.0 stills my-video # frames + a labelled contact sheet, to look at
+npx greenlight-motion@0.5.0 render my-video --fps 60 --motion-blur
+npx greenlight-motion@0.5.0 pack my-video   # everything in ONE html file
+npx greenlight-motion@0.5.0 pack my-video --glvideo   # ONE .glvideo: double-clicked, it opens in GreenLight Dash
 ```
 
 Also: `trace` (every animated layer's values frame by frame, plus the layer's moments), `set key=value`
@@ -72,7 +72,7 @@ The engine is one classic script, so it runs from a double-clicked file, a CDN o
 
 ```html
 <div id="app"></div>
-<script src="https://cdn.jsdelivr.net/npm/greenlight-motion@0.4.0/dist/greenlight-motion.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/greenlight-motion@0.5.0/dist/greenlight-motion.js"></script>
 <script>
   GreenLightMotion.mountStudio(document.getElementById('app'), {
     project: { /* project.json */ },
@@ -108,6 +108,34 @@ const { blob } = await engine.export({ format: 'mp4', fps: 60 });
 In a Claude artifact a page can't start a download by itself, so the page saves the MP4 through the
 artifact's `downloads` capability.
 
+**A 3D Scene** (a layer with `rig.scene`, a scene script's `world`) is drawn by the **3D plugin**, a package of its own:
+[`greenlight-motion-3d`](https://www.npmjs.com/package/greenlight-motion-3d) (GreenLight Dash's 3D engine: live Draft and
+path-traced Final; not open source, see its licence). You never install it by hand:
+
+- **In a browser** the engine fetches it from jsDelivr the first time a project has a Scene: the newest release of the range
+  this engine takes (`peerDependencies`), read from its `manifest.json` and then pinned to that exact release. A 2D video
+  never loads a byte of it. A page that serves the plugin's `dist/world3d/` itself names the folder before mounting:
+
+```js
+GreenLightMotion.setWorldBase('https://cdn.jsdelivr.net/npm/greenlight-motion-3d@0.1.0/dist/world3d/');   // or your own copy
+await GreenLightMotion.world3d.load();          // a "Download 3D plugin" button: get it before any Scene
+GreenLightMotion.world3d.status();              // { state: 'idle' | 'loading' | 'ready' | 'failed', version, bytes, error }
+const { png, hints, objects, lights } = await engine.critique(2);   // the frame at 2 s and what its shot shows, with hints
+```
+
+- **The CLI** downloads it once into this computer's cache (`~/Library/Caches/greenlight-motion/` on a Mac,
+  `%LOCALAPPDATA%\greenlight-motion\Cache` on Windows, `~/.cache/greenlight-motion` on Linux; `GREENLIGHT_MOTION_3D_CACHE`
+  moves it) the first time a folder has a Scene, checks it against the registry's sha512 and copies its `dist/world3d/` beside
+  the page. `npx greenlight-motion add-3d` gets it ahead; `doctor` says which release is there. Offline:
+  `GREENLIGHT_MOTION_3D=<an unpacked copy or its .tgz>`; an installed `greenlight-motion-3d` next to the project is used as it is.
+
+Its files load as modules, so a page that carries them in its own folder runs from a server (the CLI's `review` serves one),
+not from a double-clicked file.
+
+**Final in a page you host:** `GreenLightMotion.setFinalCap({ seconds: 10, spp: 64 })` makes a Final (path-traced) render costlier
+than 10 s at 64 samples per pixel (1080p, 30 fps) wait for a second press of Render (or `page.renderVideo({ confirmLongFinal:
+true })`); the GreenLight Motion connector sets that. No cap is the default; `GreenLightMotion.finalCost(project)` says what a render costs.
+
 ## Requirements
 
 - **Viewing and rendering:** desktop Chrome or Edge with WebGPU (Chrome 113+).

package/THIRD_PARTY_LICENSES.md

@@ -1,6 +1,6 @@
 # Third-party licences
 
-The engine bundle (`dist/greenlight-motion.js`, `dist/greenlight-motion.mjs`) and the scene script (`dist/greenlight-motion-script.mjs`)
+The engine bundle (`dist/greenlight-motion.js`, `dist/greenlight-motion.mjs`), the scene script (`dist/greenlight-motion-script.mjs`)
 include code from these packages.
 Generated by `scripts/prepare.mjs` from the build. Files on the GreenLight CDN are listed in
 [legal/THIRD_PARTY_ASSETS.md](legal/THIRD_PARTY_ASSETS.md); artwork credits are in [NOTICE](NOTICE).

package/cli/index.mjs

@@ -15,6 +15,9 @@
 //   npx greenlight-motion trace <dir> [--fps 30] [--items a,b] [--out f.json]   every keyframed layer's values per frame + its moments
 //   npx greenlight-motion review <dir> [--port 4810] [--open]   the page for the user's review: the notes they mark on it land in <dir>/review/
 //   npx greenlight-motion schema [topic]             the project format (format | template | effects | transitions | easings | paths | expressions | sounds)
+//   npx greenlight-motion add-3d [--json]            the 3D plugin (greenlight-motion-3d) into this computer's cache now (doctor says what is there)
+//   A 3D Scene (a script's `world`) gets the 3D plugin by itself the first time (downloaded once); its folder plays from a local server
+//   (review), and check / stills / render serve it themselves.
 //
 // Needs Node 18+ and Chrome or Edge (the engine draws with WebGPU; a headless *shell* has no WebGPU, so the CLI
 // drives the real browser in its new headless mode). No ffmpeg: the page encodes the MP4 itself.
@@ -26,11 +29,38 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { applyEdits } from './apply.mjs';
 import { glvideoBytes } from './glvideo.mjs';
+import { find3d, cacheRoot, cached, NAME as NAME3D } from './plugin3d.mjs';
 
 const PKG = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const require = createRequire(import.meta.url);
 const ENGINE = path.join(PKG, 'dist', 'greenlight-motion.js');
-const VERSION = JSON.parse(readFileSync(path.join(PKG, 'package.json'), 'utf8')).version;
+// A 3D Scene (a Scene layer: rig.renderer "world", a script's `world`): its 3D engine is the 3D plugin, a package of its own
+// (greenlight-motion-3d, at the release range this engine takes: package.json peerDependencies). The CLI finds it, or downloads it
+// once into this computer's cache (cli/plugin3d.mjs), and copies its dist/world3d/ into the project folder as world3d/; assets.js
+// tells the page to load it from there. Its files load as modules, which a file:// page cannot, so a page with a Scene is opened
+// from a server on this computer (127.0.0.1) — review, and stills / render / check headless.
+const hasWorld = (project) => {
+  const walk = (channels, clips) => (channels || []).some((ch) => (ch?.items || []).some((it) => it?.rig?.renderer === 'world'))
+    || (clips || []).some((c) => c?.sequence && walk(c.sequence.channels, c.sequence.clips));
+  return !!project && walk(project.channels, project.clips);
+};
+const META = JSON.parse(readFileSync(path.join(PKG, 'package.json'), 'utf8'));
+const VERSION = META.version;
+// the plugin's releases this engine takes, and the world API its Scene layer speaks (schema/capabilities.json world3d, written by
+// scripts/prepare.mjs from frontend/src/motionEngine/world3dContract.js)
+const RANGE3D = META.peerDependencies?.[NAME3D] || null;
+const API3D = () => SCHEMA().world3d?.api ?? 1;
+let plugin = null;
+function plugin3d({ quiet = false } = {}) {
+  if (plugin) return plugin;
+  try {
+    plugin = find3d({ range: RANGE3D, api: API3D(), from: [process.cwd(), PKG], log: quiet ? null : (m) => console.log(m) });
+  } catch (e) {
+    fail(`this video has a 3D Scene, and the 3D plugin (${NAME3D}${RANGE3D ? `@${RANGE3D}` : ''}) is not here: ${e.message}`,
+      'run npx greenlight-motion add-3d while online, or set GREENLIGHT_MOTION_3D to an unpacked copy or its .tgz');
+  }
+  return plugin;
+}
 
 // ── arguments ──
 const argv = process.argv.slice(2);
@@ -119,10 +149,11 @@ const indexHtml = (title) => `<!doctype html>
 // JSON inside a <script>: no "</script", no "<!--" (both escapes stay valid JSON and JS, so the app can read a page back)
 const scriptSafe = (s) => s.replace(/<\/(script)/gi, '<\\/$1').replace(/<!--/g, '<\\u0021--');
 
-const assetsJs = (assets, aliases) => `window.GL_ASSETS = ${scriptSafe(JSON.stringify(assets))};
+// world: the folder holds the 3D plugin's files (world3d/): the page loads its 3D Scene's engine from there, not from the CDN
+const assetsJs = (assets, aliases, world = false) => `window.GL_ASSETS = ${scriptSafe(JSON.stringify(assets))};
 window.GL_ASSET_ALIASES = ${scriptSafe(JSON.stringify(aliases))};
 (function (a, m) { for (var k in m) if (!(k in a)) a[k] = a[m[k]]; })(window.GL_ASSETS, window.GL_ASSET_ALIASES);
-`;
+${world ? 'window.GL_WORLD_BASE = "world3d/";\n' : ''}`;
 
 // The sounds a project's cues play: the library's files are on the sound CDN (schema/capabilities.json sounds.cdn;
 // GREENLIGHT_SOUND_CDN overrides it). A cue's file is downloaded into assets/sounds/ once. Returns the refs still missing.
@@ -183,6 +214,8 @@ function ensure3dFiles(dir, project) {
     else if (hdrs.has(`${s}.hdr`)) addHdr(`${s}.hdr`);
   }
   if ((project.clips || []).some((c) => c?.mediaType === 'model3d') && f.defaultHdr) addHdr(f.defaultHdr);
+  // a 3D Scene without an environment of its own is lit by the Scene's default one (rig3d.js ENV_DEFAULTS)
+  if (hasWorld(project)) addHdr('studio_small_03_1k.hdr');
   const missing = [];
   for (const [rel, [url, ref]] of want) {
     const dest = path.join(dir, 'assets', rel);
@@ -210,26 +243,60 @@ function build(dir, { quiet = false } = {}) {
   }
   const missing = [...[...refsIn(project)].filter((r) => !assets[r] && !aliases[r]), ...soundsMissing];
   writeFileSync(path.join(dir, 'project.js'), `window.GL_PROJECT = ${scriptSafe(JSON.stringify(project))};\n`);
-  writeFileSync(path.join(dir, 'assets.js'), assetsJs(assets, aliases));
+  const world = hasWorld(project);
+  writeFileSync(path.join(dir, 'assets.js'), assetsJs(assets, aliases, world));
   copyFileSync(ENGINE, path.join(dir, 'greenlight-motion.js'));
+  if (world) {
+    // the 3D plugin's files beside the page (copied again only when its release changed)
+    const p = plugin3d({ quiet });
+    const to = path.join(dir, 'world3d');
+    let had = null;
+    try { had = JSON.parse(readFileSync(path.join(to, 'manifest.json'), 'utf8')).version; } catch { /* none yet */ }
+    if (had !== p.version || readdirSync(p.world).some((f) => !existsSync(path.join(to, f)))) {
+      rmSync(to, { recursive: true, force: true });
+      mkdirSync(to, { recursive: true });
+      for (const f of readdirSync(p.world)) copyFileSync(path.join(p.world, f), path.join(to, f));
+    }
+  }
   if (!existsSync(path.join(dir, 'index.html'))) writeFileSync(path.join(dir, 'index.html'), indexHtml(project.template?.title || project.name));
   if (!quiet) {
     console.log(`built ${path.join(dir, 'index.html')} — ${filesUnder(path.join(dir, 'assets')).length} file(s), ${(bytes / 1048576).toFixed(1)} MB of assets`);
+    if (world) console.log(`it has a 3D Scene (the 3D plugin ${plugin?.version} in ${path.join(dir, 'world3d')}): it plays from a local server, not by double-click — npx greenlight-motion review ${dir}`);
     if (missing.length) console.log(`missing (put them in assets/): ${missing.join(', ')}`);
   }
   return { project, assets, aliases, missing, bytes };
 }
 
-// The page, headless: built, opened from file://, settled (files are asked for in waves — a model, then its HDR).
+// A project folder served read-only on 127.0.0.1 (a free port), for a page whose 3D Scene loads its engine as modules.
+async function serveFolder(dir) {
+  const http = await import('node:http');
+  const root = path.resolve(dir);
+  const types = { ...MIME, '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8' };
+  const server = http.createServer((req, res) => {
+    const p = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+    const file = path.resolve(root, p === '/' ? 'index.html' : p.replace(/^\/+/, ''));
+    if (!file.startsWith(root + path.sep) || !existsSync(file) || statSync(file).isDirectory() || (req.method !== 'GET' && req.method !== 'HEAD')) {
+      res.writeHead(404, { 'content-type': 'text/plain' }); res.end('not found'); return;
+    }
+    res.writeHead(200, { 'content-type': types[path.extname(file).toLowerCase()] || 'application/octet-stream', 'cache-control': 'no-store' });
+    res.end(req.method === 'HEAD' ? undefined : readFileSync(file));
+  });
+  await new Promise((ok, no) => { server.once('error', no); server.listen(0, '127.0.0.1', ok); });
+  return { url: `http://127.0.0.1:${server.address().port}/`, close: () => server.close() };
+}
+
+// The page, headless: built, opened from file:// (a 3D Scene's from a local server), settled (files are asked for in waves — a
+// model, then its HDR).
 async function withPage(dir, fn) {
-  build(dir, { quiet: true });
+  const { project } = build(dir, { quiet: true });
+  const served = hasWorld(project) ? await serveFolder(dir) : null;
   const browser = await launch();
   try {
     const context = await browser.newContext({ viewport: { width: 1600, height: 1000 } });
     const page = await context.newPage();
     const errors = [];
     page.on('pageerror', (e) => errors.push(String(e.message || e)));
-    await page.goto('file://' + path.resolve(dir, 'index.html'));
+    await page.goto(served ? served.url : 'file://' + path.resolve(dir, 'index.html'));
     await page.waitForFunction(() => window.GreenLightMotion?.page?.ready, null, { timeout: 90000 });
     const duration = await page.evaluate(() => window.GreenLightMotion.page.duration);
     for (const t of [0, duration / 2, Math.max(0, duration - 0.05)]) await page.evaluate((x) => window.GreenLightMotion.page.renderFrame(x), t);
@@ -237,6 +304,7 @@ async function withPage(dir, fn) {
     return await fn({ page, errors, duration });
   } finally {
     await browser.close();
+    served?.close();
   }
 }
 const parseTimes = (duration) => {
@@ -254,6 +322,13 @@ async function doctor() {
   const chrome = findChrome();
   add('Chrome or Edge', !!chrome, chrome || 'not found', 'install Google Chrome, or set GREENLIGHT_MOTION_CHROME to its executable');
   add('engine bundle', existsSync(ENGINE), existsSync(ENGINE) ? path.relative(process.cwd(), ENGINE) : 'missing', 'reinstall greenlight-motion');
+  // the 3D plugin: not a fault when it is not here yet (a video with a 3D Scene downloads it), only when what is here does not fit
+  let found3d = null, why3d = null;
+  try { found3d = find3d({ range: RANGE3D, api: API3D(), from: [process.cwd(), PKG], download: false }); } catch (e) { why3d = e.message; }
+  const others = cached().filter((c) => c.version !== found3d?.version).map((c) => c.version);
+  add(`3D plugin (${NAME3D}${RANGE3D ? ` ${RANGE3D}` : ''})`, !why3d,
+    found3d ? `${found3d.version} (${found3d.from === 'cache' ? 'cache' : found3d.from}: ${found3d.world})` : why3d || `not downloaded yet: a video with a 3D Scene gets it (once, ~19 MB into ${cacheRoot()}), or now: npx greenlight-motion add-3d${others.length ? `; other releases cached: ${others.join(', ')}` : ''}`,
+    'unset GREENLIGHT_MOTION_3D or point it at a release that fits, then npx greenlight-motion add-3d');
   if (chrome) {
     try {
       const browser = await launch();
@@ -263,16 +338,18 @@ async function doctor() {
       const gpu = await page.evaluate(async () => {
         const a = await navigator.gpu?.requestAdapter();
         const h264 = typeof VideoEncoder === 'function' && (await VideoEncoder.isConfigSupported({ codec: 'avc1.640028', width: 1920, height: 1080, bitrate: 8e6, framerate: 30 })).supported;
-        return { webgpu: !!a, adapter: a?.info ? [a.info.vendor, a.info.architecture].filter(Boolean).join(' ') : '', h264 };
+        return { webgpu: !!a, adapter: a?.info ? [a.info.vendor, a.info.architecture].filter(Boolean).join(' ') : '', h264,
+          storage: a?.limits?.maxStorageBuffersPerShaderStage || 0, maxBuffer: a?.limits?.maxBufferSize || 0 };
       });
       await browser.close();
       add('WebGPU (headless)', gpu.webgpu, gpu.adapter || (gpu.webgpu ? 'adapter' : 'no adapter'), 'update Chrome; on Linux servers WebGPU needs Vulkan or SwiftShader');
       add('H.264 encoding (WebCodecs)', gpu.h264, gpu.h264 ? 'supported' : 'not supported', 'use Google Chrome (open-source Chromium on Linux lacks H.264)');
+      if (gpu.webgpu) add('WebGPU limits for a 3D Scene', gpu.storage >= 8, `${gpu.storage} storage buffers per stage, largest buffer ${Math.round(gpu.maxBuffer / 1048576)} MB`, 'a Final 3D Scene needs 8+ storage buffers per shader stage: update Chrome or the graphics driver');
     } catch (e) {
       add('browser starts headless', false, String(e.message || e).split('\n')[0], 'check that Chrome opens on this computer');
     }
   }
-  if (flags.json) console.log(JSON.stringify({ version: VERSION, ok: checks.every((c) => c.ok), checks }, null, 2));
+  if (flags.json) console.log(JSON.stringify({ version: VERSION, ok: checks.every((c) => c.ok), checks, plugin3d: found3d ? { version: found3d.version, from: found3d.from, dir: found3d.world } : null, range3d: RANGE3D }, null, 2));
   else {
     for (const c of checks) console.log(`${c.ok ? 'ok  ' : 'FIX '} ${c.name.padEnd(28)} ${c.detail}${c.fix ? `\n      → ${c.fix}` : ''}`);
     console.log(checks.every((c) => c.ok) ? '\nready' : '\nfix the lines marked FIX');
@@ -296,10 +373,28 @@ then: npx greenlight-motion check ${dir}  →  stills ${dir}  →  render ${dir}
 
 async function check() {
   const dir = rest[0] || '.';
-  const { missing: unbuilt } = build(dir, { quiet: true });
+  const { missing: unbuilt, project: built } = build(dir, { quiet: true });
+  // a 3D Scene: the scene script's own strict check (the same as `script` and the chat connector), and its critique below
+  const S = hasWorld(built) ? await import(pathToFileURL(path.join(PKG, 'dist', 'greenlight-motion-script.mjs')).href) : null;
+  // a folder `script` made: its Scene is the script's `world`, so fields are named the script's way (world.render.mode)
+  const fromScript = existsSync(path.join(dir, 'script.json'));
+  const asScript = (t) => (!fromScript || !t ? t : String(t).replace(/(^|`)rig\.(?=[a-z])/g, '$1world.').replace(/(^|`)scene\./g, '$1world.scene.')
+    .replace(/(^|`)materials\./g, '$1world.scene.materials.'));
   const result = await withPage(dir, async ({ page, errors, duration }) => {
     const problems = [];
+    const notes = [];
     const project = JSON.parse(readFileSync(path.join(dir, 'project.json'), 'utf8'));
+    if (S?.validateWorld) {
+      for (const ch of project.channels || []) for (const it of ch?.items || []) {
+        if (it?.rig?.renderer !== 'world') continue;
+        const r = S.validateWorld(it.rig, { path: fromScript && it.id === 'world' ? 'world' : `${it.id}.rig` });
+        for (const e of r.errors) problems.push({ code: 'scene', ref: e.path, detail: e.message, fix: 'fix that field (skill/references/video-world3d.md, world3d-schema.json)' });
+        for (const w of r.warnings) notes.push({ code: 'scene', ref: w.path, detail: w.message, fix: 'the 3D engine does not use it as written' });
+      }
+      // what the shot shows, the lights, the picture's numbers: hints naming the field to change (the middle frame)
+      const crit = await page.evaluate(async (t) => (window.GreenLightMotion.page.critique ? window.GreenLightMotion.page.critique(t) : null), duration / 2).catch((e) => ({ hints: [{ kind: 'critique', text: `the 3D critique could not run: ${e.message}` }] }));
+      for (const h of crit?.hints || []) notes.push({ code: '3d-critique', ref: h.kind, detail: asScript(h.text), fix: h.fix ? `change ${asScript(h.fix)}` : 'see the hint' });
+    }
     for (const r of unbuilt) {
       problems.push(r.startsWith('asset:sounds/')
         ? { code: 'missing-file', ref: r, fix: `a cue's sound is downloaded from the GreenLight sound CDN and that failed: check the internet connection and run build again, or put the file at assets/${r.slice(6)}` }
@@ -345,7 +440,6 @@ async function check() {
     }
     for (const e of errors) problems.push({ code: 'page-error', detail: e, fix: 'a value in project.json the engine cannot use; compare with the references in the skill' });
     // notes: worth a look, not wrong by themselves — text the engine wraps onto more lines than it was written with
-    const notes = [];
     for (const w of await page.evaluate((proj) => window.GreenLightMotion.textWraps?.(proj) || [], project)) {
       notes.push({ code: 'text-wraps', ref: w.id, rows: w.rows, written: w.written,
         detail: `"${w.text}" (${w.fontPx} px) wraps onto ${w.rows} lines in its ${w.widthPx} px box, written as ${w.written}`,
@@ -428,6 +522,10 @@ function pack() {
     if (missing.length) console.log(`missing (not inside): ${missing.join(', ')}`);
     return;
   }
+  if (hasWorld(project)) {
+    fail('a video with a 3D Scene does not fit in one HTML file (its 3D engine is the 3D plugin: ~19 MB of files it loads as modules)',
+      `render the MP4: npx greenlight-motion render ${dir} — or show the folder: npx greenlight-motion review ${dir} — or --glvideo for GreenLight Dash`);
+  }
   const out = path.resolve(String(flags.out || path.join(dir, `${(project.template?.title || project.name || 'video').replace(/[^\w-]+/g, '-')}.html`)));
   const engine = readFileSync(ENGINE, 'utf8');
   // Function replacers: a replacement STRING would expand $&, $' and $` — and minified code is full of them.
@@ -686,9 +784,16 @@ async function review() {
   await new Promise(() => {});   // serves until stopped
 }
 
-const COMMANDS = { doctor, init, script, build: () => build(rest[0] || '.'), check, stills, render, pack, set, apply, schema, trace, review };
+// The 3D plugin now, before a video needs it (a scene built from zero, an offline day ahead)
+function add3d() {
+  const p = plugin3d({ quiet: !!flags.json });
+  if (flags.json) console.log(JSON.stringify({ ok: true, package: NAME3D, version: p.version, from: p.from, dir: p.world, range: RANGE3D }));
+  else console.log(`3D plugin ${NAME3D} ${p.version} ready (${p.from}): ${p.world}`);
+}
+
+const COMMANDS = { doctor, init, script, build: () => build(rest[0] || '.'), check, stills, render, pack, set, apply, schema, trace, review, 'add-3d': add3d };
 if (!cmd || cmd === 'help' || flags.help || !COMMANDS[cmd]) {
-  console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(1, 20).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'));
+  console.log(readFileSync(fileURLToPath(import.meta.url), 'utf8').split('\n').slice(1, 24).map((l) => l.replace(/^\/\/ ?/, '')).join('\n'));
   process.exit(cmd && !COMMANDS[cmd] && cmd !== 'help' ? 1 : 0);
 }
 try {

package/cli/plugin3d.mjs

@@ -0,0 +1,202 @@
+// The 3D plugin (`greenlight-motion-3d`) for the CLI: found where it already is, or downloaded once into this computer's cache —
+// the way Playwright keeps its browsers. A project folder with a 3D Scene gets the plugin's dist/world3d/ copied beside its page.
+//
+// Where it is looked for, in order:
+//   1. GREENLIGHT_MOTION_3D: a folder (an unpacked package, or its dist/world3d/) or a .tgz of it — offline installs, tests
+//   2. an installed package (`npm i greenlight-motion-3d` next to the project, or beside this one) whose version fits the range
+//   3. the cache: <cache>/greenlight-motion-3d/<version>/ (GREENLIGHT_MOTION_3D_CACHE, else the OS's cache folder)
+//   4. the npm registry (GREENLIGHT_MOTION_3D_REGISTRY, else npm_config_registry, else registry.npmjs.org): the newest release in
+//      the range, its tarball checked against the registry's sha512 before it is unpacked
+// Synchronous (curl, like the CLI's sound and 3D file downloads), so `build` stays one plain step.
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { gunzipSync } from 'node:zlib';
+import os from 'node:os';
+import path from 'node:path';
+
+export const NAME = 'greenlight-motion-3d';
+// the world API this engine's Scene layer speaks: frontend/src/motionEngine/world3dContract.js WORLD3D_API, which the CLI passes in from
+// its scene script bundle (dist/greenlight-motion-script.mjs); this is only the fallback
+export const API = 1;
+
+/** Whether `version` is inside `range` (~x.y.z, ^x.y.z, x.y.z, or >= / < bounds separated by spaces). */
+export function satisfies(version, range) {
+  const v = /^(\d+)\.(\d+)\.(\d+)$/.exec(String(version || '').trim());
+  if (!v) return false;
+  const n = v.slice(1).map(Number);
+  const cmp = (a, b) => (a[0] - b[0]) || (a[1] - b[1]) || (a[2] - b[2]);
+  return String(range || '').trim().split(/\s+/).every((part) => {
+    const m = /^(>=|<=|>|<|=|~|\^)?(\d+)\.(\d+)\.(\d+)$/.exec(part);
+    if (!m) return false;
+    const r = m.slice(2).map(Number);
+    switch (m[1]) {
+      case '>=': return cmp(n, r) >= 0;
+      case '<=': return cmp(n, r) <= 0;
+      case '>': return cmp(n, r) > 0;
+      case '<': return cmp(n, r) < 0;
+      case '~': return cmp(n, r) >= 0 && n[0] === r[0] && n[1] === r[1];
+      case '^': return cmp(n, r) >= 0 && (r[0] > 0 ? n[0] === r[0] : r[1] > 0 ? n[0] === 0 && n[1] === r[1] : n[0] === 0 && n[1] === 0 && n[2] === r[2]);
+      default: return cmp(n, r) === 0;
+    }
+  });
+}
+const newest = (list) => list.slice().sort((a, b) => {
+  const x = a.split('.').map(Number), y = b.split('.').map(Number);
+  return (y[0] - x[0]) || (y[1] - x[1]) || (y[2] - x[2]);
+})[0];
+
+/** The cache folder the plugin's releases are kept in. */
+export function cacheRoot() {
+  if (process.env.GREENLIGHT_MOTION_3D_CACHE) return path.resolve(process.env.GREENLIGHT_MOTION_3D_CACHE);
+  const home = os.homedir();
+  if (process.platform === 'darwin') return path.join(home, 'Library', 'Caches', 'greenlight-motion', NAME);
+  if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'greenlight-motion', 'Cache', NAME);
+  return path.join(process.env.XDG_CACHE_HOME || path.join(home, '.cache'), 'greenlight-motion', NAME);
+}
+
+/** A plugin folder's facts: { dir, world, version, api, manifest } or null when it is not one. `dir` may be the package or its dist/world3d. */
+export function inspect(dir) {
+  const candidates = [path.join(dir, 'dist', 'world3d'), dir];
+  for (const world of candidates) {
+    const manifestFile = path.join(world, 'manifest.json');
+    if (!existsSync(path.join(world, 'world3d.js')) || !existsSync(manifestFile)) continue;
+    let manifest;
+    try { manifest = JSON.parse(readFileSync(manifestFile, 'utf8')); } catch { continue; }
+    return { dir: world === dir ? path.dirname(path.dirname(dir)) : dir, world, version: manifest.version, api: manifest.api, manifest };
+  }
+  return null;
+}
+
+/** Every file of the manifest there, with its size and sha256: the names of what is missing or changed ([] when the copy is whole). */
+export function verify(found) {
+  const bad = [];
+  for (const [name, f] of Object.entries(found.manifest.files || {})) {
+    const p = path.join(found.world, name);
+    if (!existsSync(p)) { bad.push(`${name} (missing)`); continue; }
+    if (statSync(p).size !== f.bytes) { bad.push(`${name} (size)`); continue; }
+    if (f.sha256 && createHash('sha256').update(readFileSync(p)).digest('hex') !== f.sha256) bad.push(`${name} (content)`);
+  }
+  return bad;
+}
+
+// ── a .tgz → files (npm's tarballs: gzip'd ustar, every path under package/, pax headers for long names) ──
+function untar(gz, into) {
+  const tar = gunzipSync(gz);
+  const str = (b, at, len) => { const s = b.subarray(at, at + len); const z = s.indexOf(0); return s.subarray(0, z < 0 ? len : z).toString('utf8'); };
+  let at = 0, longName = null, count = 0;
+  while (at + 512 <= tar.length) {
+    const head = tar.subarray(at, at + 512);
+    if (head.every((b) => b === 0)) break;
+    const size = parseInt(str(head, 124, 12).trim() || '0', 8) || 0;
+    const type = String.fromCharCode(head[156] || 48);
+    let name = longName || (str(head, 345, 155) ? `${str(head, 345, 155)}/${str(head, 0, 100)}` : str(head, 0, 100));
+    longName = null;
+    const body = tar.subarray(at + 512, at + 512 + size);
+    at += 512 + Math.ceil(size / 512) * 512;
+    if (type === 'x') {   // pax: this entry's path for the next one
+      const m = /\d+ path=([^\n]*)\n/.exec(body.toString('utf8'));
+      if (m) longName = m[1];
+      continue;
+    }
+    if (type === 'g' || type === '5') continue;
+    if (type !== '0' && type !== '\0' && type !== '7') continue;   // links and devices: never in a package of ours
+    name = name.replace(/^package\//, '');
+    if (!name || path.isAbsolute(name) || name.split(/[\\/]/).some((s) => s === '..')) throw new Error(`the 3D plugin's tarball has a path outside its folder: ${name}`);
+    const dest = path.join(into, name);
+    mkdirSync(path.dirname(dest), { recursive: true });
+    writeFileSync(dest, body);
+    count += 1;
+  }
+  return count;
+}
+
+const curl = (url, out = null) => {
+  const args = ['-sfL', '--max-time', '600', ...(out ? ['-o', out] : []), url];
+  const r = spawnSync('curl', args, { maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`could not download ${url} (curl exit ${r.status}${r.error ? `: ${r.error.message}` : ''})`);
+  return out ? null : r.stdout;
+};
+
+/** A .tgz unpacked into the cache under its own version; returns its folder (a version already there is kept as it is). */
+function cacheTarball(bytes, { integrity = null, from = 'a tarball' } = {}) {
+  if (integrity) {
+    const [algo, want] = String(integrity).split('-');
+    const got = createHash(algo || 'sha512').update(bytes).digest('base64');
+    if (got !== want) throw new Error(`the 3D plugin downloaded from ${from} does not match the registry's ${algo} — not unpacked`);
+  }
+  const root = cacheRoot();
+  mkdirSync(root, { recursive: true });
+  const tmp = path.join(root, `.unpack-${process.pid}-${Date.now()}`);
+  try {
+    untar(bytes, tmp);
+    const found = inspect(tmp);
+    if (!found) throw new Error(`${from} is not the 3D plugin (no dist/world3d/manifest.json)`);
+    const meta = JSON.parse(readFileSync(path.join(tmp, 'package.json'), 'utf8'));
+    if (meta.name !== NAME) throw new Error(`${from} is ${meta.name}, not ${NAME}`);
+    const bad = verify(found);
+    if (bad.length) throw new Error(`${from} is not whole: ${bad.slice(0, 4).join(', ')}`);
+    const dest = path.join(root, meta.version);
+    if (existsSync(path.join(dest, '.complete'))) { rmSync(tmp, { recursive: true, force: true }); return dest; }
+    rmSync(dest, { recursive: true, force: true });
+    renameSync(tmp, dest);
+    writeFileSync(path.join(dest, '.complete'), `${new Date().toISOString()} ${from}\n`);
+    return dest;
+  } finally { rmSync(tmp, { recursive: true, force: true }); }
+}
+
+/** The cached releases, newest first: [{ version, dir }]. */
+export function cached() {
+  const root = cacheRoot();
+  if (!existsSync(root)) return [];
+  return readdirSync(root).filter((v) => /^\d+\.\d+\.\d+$/.test(v) && existsSync(path.join(root, v, '.complete')))
+    .sort((a, b) => (newest([a, b]) === a ? -1 : 1)).map((version) => ({ version, dir: path.join(root, version) }));
+}
+
+/**
+ * The plugin for an engine that takes `range`: { dir, world, version, from: 'env' | 'installed' | 'cache' | 'download' }.
+ * `download: false` only looks (doctor). Throws a message for people when it cannot be had.
+ */
+export function find3d({ range, api = API, download = true, from = [process.cwd()], log = null } = {}) {
+  const fits = (found) => found && found.api === api && (!range || satisfies(found.version, range));
+  const why = (found) => (found.api !== api ? `speaks world API ${found.api}, this engine ${api}` : `${found.version} is not in ${range}`);
+  const env = process.env.GREENLIGHT_MOTION_3D;
+  if (env) {
+    const p = path.resolve(env);
+    if (!existsSync(p)) throw new Error(`GREENLIGHT_MOTION_3D=${env}: no such file or folder`);
+    let found = statSync(p).isDirectory() ? inspect(p) : inspect(cacheTarball(readFileSync(p), { from: p }));
+    if (!found) throw new Error(`GREENLIGHT_MOTION_3D=${env} is not the 3D plugin (no dist/world3d/manifest.json)`);
+    if (!fits(found)) throw new Error(`GREENLIGHT_MOTION_3D=${env}: ${why(found)}`);
+    return { ...found, from: 'env' };
+  }
+  for (const base of from) {
+    try {
+      const req = createRequire(path.join(path.resolve(base), 'noop.js'));
+      const found = inspect(path.dirname(req.resolve(`${NAME}/package.json`)));
+      if (fits(found)) return { ...found, from: 'installed' };
+    } catch { /* not installed there */ }
+  }
+  for (const c of cached()) {
+    const found = inspect(c.dir);
+    if (fits(found)) return { ...found, from: 'cache' };
+  }
+  if (!download) return null;
+  const registry = String(process.env.GREENLIGHT_MOTION_3D_REGISTRY || process.env.npm_config_registry || 'https://registry.npmjs.org/').replace(/\/?$/, '/');
+  log?.(`downloading the 3D plugin (${NAME}${range ? `@${range}` : ''}) from ${registry} — once, into ${cacheRoot()}`);
+  let doc;
+  try { doc = JSON.parse(curl(`${registry}${NAME}`).toString('utf8')); } catch (e) { throw new Error(`the 3D plugin could not be looked up: ${e.message}. Online once (or set GREENLIGHT_MOTION_3D to a copy), then try again`); }
+  const versions = Object.keys(doc.versions || {}).filter((v) => /^\d+\.\d+\.\d+$/.test(v) && (!range || satisfies(v, range)));
+  if (!versions.length) throw new Error(`no release of ${NAME} fits this engine (${range}); the registry has ${Object.keys(doc.versions || {}).join(', ') || 'none'}`);
+  const version = newest(versions);
+  const meta = doc.versions[version];
+  const tmp = path.join(os.tmpdir(), `${NAME}-${version}-${process.pid}.tgz`);
+  try {
+    curl(meta.dist.tarball, tmp);
+    const dir = cacheTarball(readFileSync(tmp), { integrity: meta.dist.integrity || null, from: meta.dist.tarball });
+    const found = inspect(dir);
+    if (!fits(found)) throw new Error(`${NAME}@${version}: ${why(found)}`);
+    log?.(`3D plugin ${version} ready (${dir})`);
+    return { ...found, from: 'download' };
+  } finally { rmSync(tmp, { force: true }); }
+}