@machinal/scenes 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.1.2
+
+- Fix `init` failing with `Target already exists: cp returned EEXIST` on newer Node.js releases: copy starter entries into the newly created directory instead of copying over the directory itself. Existing destinations are still refused without changing their files.
+
+## 0.1.1
+
+- Show readable setup/doctor status and a concise render result by default; use `--json` for complete tool and scene metadata. The Node API and saved scene manifests are unchanged.
+- Report the native renderer's real version instead of its help banner.
+- Reuse cached tools without announcing another Chrome or FFmpeg installation; FFmpeg integrity and license checks still run.
+- Fix negative preview frames when an animation timestamp precedes the Play click, including pause/resume and end-of-scene replay.
+- Default the starter scene to 1280×720 and show the complete local export path; clarify that the standalone tool has no S3 upload or project connection.
+- Styled, responsive quickstart workspace with preview transport and an in-browser local export panel.
+- Explicit rendering-tool download, prerequisite checks, build/render status, actionable errors and completed MP4 downloads.
+- Browser exports save unique videos and manifests in `renders/` without replacing earlier exports; CLI export remains available.
+
 ## 0.1.0
 
 - Initial public `@machinal/scenes` distribution, combining the runtime and Svelte integration in one package.

package/README.md

@@ -12,7 +12,7 @@ In a Svelte 5 project with a Svelte-aware bundler, such as Vite:
 npm install @machinal/scenes
 ```
 
-Requires Node.js 22.12+ and Svelte 5.15+. Three.js and its public TypeScript types are installed as dependencies. There are no install scripts: Chromium and FFmpeg are downloaded only when you explicitly run `setup`. The native renderer is already in the package.
+Requires Node.js 22.12+ and Svelte 5.15+. Three.js and its public TypeScript types are installed as dependencies. There are no install scripts: Chromium and FFmpeg are downloaded only when you explicitly run `setup` or click **Download rendering tools** in the starter. The native renderer is already in the package. Run `npm install` inside a project directory, not a drive root such as `D:\`.
 
 The library is ESM. The root and `/svelte` entrypoints contain Svelte components and runes, so they must be processed by a Svelte-aware bundler. Use `/runtime` for framework-independent code, plain Node.js imports and manifest validation.
 
@@ -28,7 +28,18 @@ npm run render
 
 This creates **`scene.mp4`** and **`scene.mp4.scene.json`**, a manifest containing the output's dimensions, duration, frame count and SHA-256. `setup` is a one-time download of pinned Chrome Headless Shell and FFmpeg into a user cache; it checks that the tools execute. `npm run render` builds the scene with Vite and exports the video locally using the included renderer.
 
-Edit `src/Title.svelte` to change the artwork and `scene.config.json` to change dimensions, FPS, duration, props or audio. For interactive preview, run `npm run dev`; preview does not require `setup`. `npm run doctor` checks rendering prerequisites without downloading anything.
+The CLI shows readable tool status and a short export summary, not the internal metadata report. For scripts that need the complete JSON result, use `npm run setup -- --json`, `npm run doctor -- --json` or `npm run render -- --json`. Progress stays on stderr; call `machinal-scenes render --json` directly for JSON-only stdout (the npm script also prints Vite build output). The Node API and saved manifests always retain the full metadata.
+
+For the browser workflow, run `npm run dev` and open the local URL shown in the terminal:
+
+1. **Preview**: play, pause, reset or scrub the default **1280 × 720** scene, scaled to fit the available preview space. No rendering tools are required.
+2. **Download rendering tools**: the export panel checks the included renderer, Chrome and FFmpeg. If tools are missing, this explicit action downloads them once to your user cache. Already installed tools are marked **Ready**.
+3. **Render MP4**: builds the current scene source and exports it locally, with visible status and renderer progress.
+4. **Download MP4**: saves the completed video through your browser. A copy and its manifest also remain in a **local** `renders/` directory, created inside the starter next to its `package.json` when you render. For example, a starter at `D:\my-scene` saves browser exports under `D:\my-scene\renders\`. The completed export shows the full local path. Each export uses a unique filename; previous exports are preserved. Nothing is uploaded to S3 or Machinal, and the tool does not connect to your application or any Machinal project.
+
+The browser export actions run only through the loopback Vite development server (`npm run dev`), not on a statically hosted build or `npm run preview`. They require same-origin requests; there is no cloud render service or automatic download on page load. The terminal workflow above remains available.
+
+Edit `src/Title.svelte` to change the artwork and `scene.config.json` to change dimensions, FPS, duration, props or audio. `npm run doctor` checks rendering prerequisites without downloading anything.
 
 The initializer refuses to overwrite an existing directory. Rendering also refuses to replace an existing video or manifest. Choose another output filename for another export:
 
@@ -148,6 +159,26 @@ Linux requires glibc, `unzip`, and Chromium's system libraries (NSS, ATK, X11, G
 
 Scenes are executable code, not a security sandbox. Use trusted scenes or provide your own execution isolation, authorization and resource limits.
 
+## VS Code reports missing children or rejects onclick
+
+These two diagnostics can appear together when the Svelte extension is running in **Restricted Mode**:
+
+```text
+Property 'children' is missing in type '{ background: string; }'
+'"onclick"' does not exist in type 'HTMLProps<"button", HTMLAttributes<any>>'
+```
+
+In an untrusted workspace, the extension avoids loading the project's local compiler and can fall back to its bundled Svelte 4 compiler/types. The starter uses Svelte 5: nested component content supplies the `children` snippet, and `onclick` is a supported button attribute.
+
+Open the generated starter directory itself in VS Code and run `npm install` there. If you have reviewed and trust its code, use **Workspaces: Manage Workspace Trust** to trust only that folder, then **Svelte: Restart Language Server**. Do not disable Workspace Trust globally. You can also validate the project independently of the editor:
+
+```sh
+npm run check
+npm ls svelte
+```
+
+With the local Svelte 5 compiler, these starter components should pass the check. If the terminal also reports errors, investigate those diagnostics and the installed dependency versions rather than treating them as an editor-only issue. Do not make `SceneCanvas.children` optional or replace Svelte 5 event handlers just to suppress a mismatched editor diagnostic.
+
 ## License
 
 Apache-2.0 for the library and renderer sources. See [LICENSE](LICENSE), [NOTICE](NOTICE), [LICENSING.md](LICENSING.md) and the included native third-party notices. Downloaded Chrome/FFmpeg and dependencies retain their own licenses; in particular, the downloaded FFmpeg builds have separate GPL/LGPL terms. This package license does not relicense those tools, the surrounding Machinal application or its private services.

package/bin/machinal-scenes.mjs

@@ -1,9 +1,10 @@
 #!/usr/bin/env node
-import { cp, mkdir, readFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { doctor, renderVideo, setup } from '../node/index.mjs';
+import { formatRenderResult, formatToolchainStatus } from '../node/cli-output.mjs';
+import { initProject } from '../node/init.mjs';
 
 const help = `@machinal/scenes
 
@@ -25,6 +26,7 @@ Render options:
   --no-sandbox      Explicitly disable Chromium sandbox (isolated containers only)
 
 Setup/doctor/render options:
+  --json            Print complete metadata instead of a readable summary
   --browser <file>   Use an existing Chrome/Chromium executable
   --ffmpeg <file>    Use an existing FFmpeg executable
   --cache-dir <dir>  Override the native-tool cache
@@ -50,31 +52,23 @@ async function run(args) {
   if (args.length !== 2 || args[0] !== 'init' || !args[1].trim() || args[1].startsWith('-')) throw new Error(`Expected a supported command.\n\n${help}`);
 
   const destination = resolve(args[1]);
-  try {
-    await mkdir(destination);
-  } catch (error) {
-    if (error.code === 'EEXIST') throw new Error(`Destination already exists: ${destination}. No files were changed.`);
-    throw error;
-  }
-  await cp(fileURLToPath(new URL('../examples/quickstart/', import.meta.url)), destination, {
-    recursive: true, errorOnExist: true, force: false,
-  });
-  console.log(`Created ${destination}\n\nOpen this directory, then run:\n  npm install\n  npm run setup\n  npm run dev\n\nExport a video with:\n  npm run render`);
+  await initProject(destination);
+  console.log(`Created ${destination}\n\nOpen this directory, then run:\n  npm install\n  npm run dev\n\nIn the browser, use Download rendering tools (once), Render MP4, then Download MP4.\n\nTerminal alternative:\n  npm run setup\n  npm run render`);
 }
 
 async function runTools(command, args) {
-  const common = { help: { type: 'boolean' }, browser: { type: 'string' }, ffmpeg: { type: 'string' }, 'cache-dir': { type: 'string' } };
+  const common = { help: { type: 'boolean' }, json: { type: 'boolean' }, browser: { type: 'string' }, ffmpeg: { type: 'string' }, 'cache-dir': { type: 'string' } };
   const rendering = { request: { type: 'string' }, serve: { type: 'string' }, output: { type: 'string' }, workers: { type: 'string' }, lossless: { type: 'boolean' }, gpu: { type: 'boolean' }, 'no-sandbox': { type: 'boolean' } };
   const { values } = parseArgs({ args, options: { ...common, ...(command === 'render' ? rendering : {}) }, strict: true, allowPositionals: false });
   if (values.help) { console.log(help); return; }
   const options = { browserExecutable: values.browser, ffmpegExecutable: values.ffmpeg, cacheDirectory: values['cache-dir'] };
   if (command === 'render') {
     const result = await renderVideo({ ...options, request: values.request ?? 'scene.config.json', serveDirectory: values.serve ?? 'dist', output: values.output ?? 'scene.mp4', workers: values.workers === undefined ? undefined : Number(values.workers), lossless: values.lossless, gpu: values.gpu, noSandbox: values['no-sandbox'], onProgress: message => process.stderr.write(message) });
-    console.log(JSON.stringify(result, null, 2));
+    console.log(values.json ? JSON.stringify(result, null, 2) : formatRenderResult(result));
     return;
   }
   const result = command === 'setup' ? await setup({ ...options, onProgress: message => console.error(message) }) : await doctor(options);
-  console.log(JSON.stringify(result, null, 2));
+  console.log(values.json ? JSON.stringify(result, null, 2) : formatToolchainStatus(result));
   if (!result.ready) process.exitCode = 1;
 }
 

package/examples/quickstart/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+dist/
+renders/
+*.mp4
+*.webm
+*.scene.json

package/examples/quickstart/index.html

@@ -6,15 +6,43 @@
     <title>Machinal scenes quickstart</title>
   </head>
   <body>
+    <header class="command-bar">
+      <span class="brand">Machinal <span>Scenes</span></span>
+      <span>Local scene workspace</span>
+    </header>
     <main>
-      <h1>@machinal/scenes</h1>
-      <div id="scene"></div>
-      <p>
-        <button id="play" type="button" disabled>Play</button>
-        <label>Frame <input id="frame" type="range" min="0" max="179" value="0" disabled /></label>
-        <output id="status" role="status">Preparing scene...</output>
-      </p>
+      <div class="heading">
+        <h1>Your first scene, ready to move.</h1>
+        <p>Preview the animation. Render it locally. Take the MP4 with you.</p>
+      </div>
+      <div class="workbench">
+        <section class="viewer" aria-labelledby="preview-title">
+          <div class="panel-heading">
+            <h2 id="preview-title">Scene preview</h2>
+            <span id="dimensions" class="measurement"></span>
+          </div>
+          <div id="viewport"><div id="scene"></div></div>
+          <div class="transport">
+            <button id="play" type="button" disabled>Play</button>
+            <button id="reset" type="button" disabled>Reset</button>
+            <label class="scrubber"><span class="sr-only">Frame</span><input id="frame" type="range" min="0" max="179" value="0" disabled /></label>
+            <output id="counter" class="measurement" aria-live="off">000 / 179</output>
+          </div>
+          <p id="status" class="preview-status" role="status">Preparing scene...</p>
+        </section>
+        <aside id="export" aria-label="Export video"></aside>
+      </div>
+      <section class="source-guide" aria-labelledby="source-title">
+        <h2 id="source-title">Make it your own</h2>
+        <p>Edit <code>src/Title.svelte</code> for the artwork, or <code>scene.config.json</code> for dimensions, duration and props. Save to update the preview, then render again.</p>
+        <details>
+          <summary>Prefer the terminal?</summary>
+          <p>In this project directory, run <code>npm run setup</code> once, then <code>npm run render</code>. The CLI saves <code>scene.mp4</code> and its manifest in this directory.</p>
+          <p>For another export, use <code>npm run render -- --output second.mp4</code>. Existing files are never replaced.</p>
+        </details>
+      </section>
     </main>
+    <footer>Standalone local tool. No account, API key, project connection or cloud upload.</footer>
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

package/examples/quickstart/package.json

@@ -13,7 +13,8 @@
     "check": "svelte-check --tsconfig ./tsconfig.json && tsc --noEmit"
   },
   "dependencies": {
-    "@machinal/scenes": "^0.1.0",
+    "@machinal/scenes": "^0.1.2",
+    "@fontsource-variable/ibm-plex-sans": "^5.3.0",
     "svelte": "^5.15.0"
   },
   "devDependencies": {

package/examples/quickstart/scene.config.json

@@ -3,8 +3,8 @@
   "url": "/scene.html",
   "sceneId": "title",
   "config": {
-    "width": 640,
-    "height": 360,
+    "width": 1280,
+    "height": 720,
     "fps": 30,
     "durationInFrames": 180
   }

package/examples/quickstart/src/ExportPanel.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { useLocalExport } from './useLocalExport.svelte';
+
+  const exporter = useLocalExport();
+  const status = $derived(exporter.connection.phase === 'connected' ? exporter.connection.status : null);
+  const tools = $derived(status ? [
+    { label: 'Native renderer', tool: status.tools.renderer },
+    { label: 'Chrome Headless Shell', tool: status.tools.browser },
+    { label: 'FFmpeg', tool: status.tools.ffmpeg },
+  ] : []);
+
+  onMount(() => {
+    void exporter.refresh();
+    return exporter.dispose;
+  });
+</script>
+
+<div class="panel-heading"><h2>Export video</h2><span class="measurement">MP4 · local</span></div>
+<div class="export-body">
+  <section class="export-step" aria-labelledby="tools-title">
+    <h3 id="tools-title">1. Prepare this computer</h3>
+    <p>The renderer is included. Chrome and FFmpeg are needed to capture frames and encode your video.</p>
+    <ul class="tool-list" aria-label="Rendering tools">
+      {#each tools as { label, tool }}
+        <li><span>{label}</span><span class:ready={tool.available} class="tool-state">{tool.available ? 'Ready' : 'Not ready'}</span></li>
+      {/each}
+    </ul>
+    {#if status?.tools.ready}
+      <p>All tools are ready. No download needed.</p>
+    {:else}
+      <p>One-time download from Chrome for Testing and the FFmpeg release archive. Tools are saved in your user cache, not installed system-wide.</p>
+      <button class="primary" disabled={exporter.busy || !status} onclick={() => exporter.refresh('setup')}>
+        {status?.job.phase === 'installing' ? 'Downloading tools…' : 'Download rendering tools'}
+      </button>
+    {/if}
+  </section>
+  <section class="export-step" aria-labelledby="render-title">
+    <h3 id="render-title">2. Render your scene</h3>
+    <p>Builds your current source and saves the video on this computer. Nothing is uploaded to S3 or Machinal.</p>
+    <button class="primary" disabled={exporter.busy || !status?.tools.ready} onclick={() => exporter.refresh('render')}>
+      {status?.job.phase === 'building' ? 'Building scene…' : status?.job.phase === 'rendering' ? 'Rendering MP4…' : status?.job.phase === 'done' ? 'Render another MP4' : 'Render MP4'}
+    </button>
+    {#if status && !status.tools.ready}<p>Download the tools above to enable rendering.</p>{/if}
+    {#if status?.job.phase === 'done'}
+      <div class="render-result">
+        <a class="download" href={status.job.download} download={status.job.filename}>
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3v12m-5-5 5 5 5-5M5 16v5h14v-5" /></svg>
+          Download MP4
+        </a>
+        <p>Saved on this computer: <code>{status.job.localFile}</code></p>
+        <p>The local <code>renders/</code> folder is created inside this starter, next to <code>package.json</code>. Each render gets a new filename and manifest.</p>
+      </div>
+    {/if}
+  </section>
+  <div class="operation-status">
+    <div role="status" aria-live="polite">
+      {#if exporter.connection.phase === 'checking'}
+        <p>Checking local rendering tools…</p>
+      {:else if status?.job.phase === 'installing' || status?.job.phase === 'building' || status?.job.phase === 'rendering'}
+        <p>{status.job.message}</p>
+      {:else if status?.job.phase === 'done'}
+        <p>Your video is ready to download.</p>
+      {/if}
+    </div>
+    {#if exporter.connection.phase === 'error'}
+      <p class="export-error" role="alert">{exporter.connection.message}</p>
+      <button disabled={exporter.busy} onclick={() => exporter.refresh()}>Retry connection</button>
+    {:else if status?.job.phase === 'error'}
+      <p class="export-error" role="alert">{status.job.message}</p>
+      <p>Check the message above, then retry the download or render. Terminal alternative: <code>npm run doctor</code>.</p>
+    {/if}
+  </div>
+</div>

package/examples/quickstart/src/Title.svelte

@@ -3,11 +3,11 @@
 
   let { title = 'Make a scene.' }: { title?: string } = $props();
   const scene = useScene();
-  const x = $derived(interpolate(scene.frame.frame, [0, 60], [0, 160]));
+  const x = $derived(interpolate(scene.frame.frame, [0, 60], [0, scene.frame.config.width / 4]));
 </script>
 
 <SceneCanvas background="#f5f2eb">
-  <div class="subject" data-scene-object="title" style:transform="translateX({x}px)">
+  <div class="subject" data-scene-object="title" style:transform="translateX({x}px)" style:font-size="{scene.frame.config.width / 16}px">
     <span class="marker"></span>
     <h2>{title}</h2>
     <p>Frame {scene.frame.frame} / {scene.frame.config.durationInFrames - 1}</p>
@@ -15,8 +15,8 @@
 </SceneCanvas>
 
 <style>
-  .subject { position:absolute; left:40px; top:110px; color:#262a30; font-family:system-ui,sans-serif; }
-  .marker { display:block; width:28px; height:28px; background:#7047c7; }
-  h2 { margin:16px 0 8px; font-size:40px; }
-  p { margin:0; font-variant-numeric:tabular-nums; }
+  .subject { position:absolute; left:6.25%; top:30%; color:#262a30; font-family:system-ui,sans-serif; }
+  .marker { display:block; width:0.7em; height:0.7em; background:#7047c7; }
+  h2 { margin:0.4em 0 0.2em; font-size:1em; }
+  p { margin:0; font-size:0.4em; font-variant-numeric:tabular-nums; }
 </style>

package/examples/quickstart/src/export-api.ts

@@ -0,0 +1,30 @@
+export type ToolReport = {
+  ready: boolean;
+  renderer: { available: boolean; error?: string };
+  browser: { available: boolean; error?: string };
+  ffmpeg: { available: boolean; error?: string };
+};
+
+export type ExportJob =
+  | { phase: 'idle' }
+  | { phase: 'installing' | 'building' | 'rendering'; message: string }
+  | { phase: 'done'; filename: string; download: string; localFile: string }
+  | { phase: 'error'; message: string };
+
+export type ExportStatus = { tools: ToolReport; job: ExportJob };
+
+export async function exportRequest(action: 'status' | 'setup' | 'render', signal: AbortSignal): Promise<ExportStatus> {
+  const response = await fetch(`/__machinal/export/${action}`, {
+    method: action === 'status' ? 'GET' : 'POST',
+    headers: { 'X-Machinal-Export': '1' },
+    signal,
+  });
+
+  if (!response.headers.get('content-type')?.includes('application/json')) {
+    throw new Error('Local export is unavailable. Open this project with npm run dev. You can also use npm run setup and npm run render in the terminal.');
+  }
+
+  const result = await response.json();
+  if (!response.ok) throw new Error(result.error ?? `Local export failed (${response.status}). Please retry.`);
+  return result;
+}

package/examples/quickstart/src/main.ts

@@ -1,11 +1,21 @@
+import { mount, unmount } from 'svelte';
 import { exposeScene } from '@machinal/scenes/runtime';
 import { mountSvelteScene } from '@machinal/scenes/svelte';
+import '@fontsource-variable/ibm-plex-sans';
+import './workspace.css';
+import ExportPanel from './ExportPanel.svelte';
 import Title from './Title.svelte';
 import { request } from './request';
+import { playbackFrame } from './playback';
+
 const target = document.querySelector<HTMLElement>('#scene')!;
+const viewport = document.querySelector<HTMLElement>('#viewport')!;
 const play = document.querySelector<HTMLButtonElement>('#play')!;
+const reset = document.querySelector<HTMLButtonElement>('#reset')!;
 const slider = document.querySelector<HTMLInputElement>('#frame')!;
-const status = document.querySelector<HTMLOutputElement>('#status')!;
+const status = document.querySelector<HTMLElement>('#status')!;
+const counter = document.querySelector<HTMLOutputElement>('#counter')!;
+const panel = mount(ExportPanel, { target: document.querySelector('#export')! });
 const controller = mountSvelteScene(Title, target, request, {});
 const disconnect = exposeScene(controller);
 let animation = 0;
@@ -14,6 +24,16 @@ let frame = 0;
 let playing = false;
 
 slider.max = String(request.config.durationInFrames - 1);
+viewport.style.aspectRatio = `${request.config.width} / ${request.config.height}`;
+target.style.width = `${request.config.width}px`;
+target.style.height = `${request.config.height}px`;
+document.querySelector('#dimensions')!.textContent = `${request.config.width} × ${request.config.height} · ${request.config.fps} fps`;
+
+const resize = new ResizeObserver(() => {
+  target.style.transform = `scale(${viewport.clientWidth / request.config.width})`;
+});
+
+resize.observe(viewport);
 
 function stop() {
   playing = false;
@@ -24,15 +44,16 @@ function stop() {
 
 function fail(error: unknown) {
   stop();
-  status.textContent = error instanceof Error ? error.message : String(error);
+  status.textContent = `Preview failed: ${error instanceof Error ? error.message : String(error)}. Check the scene source and reload to retry.`;
   play.disabled = true;
+  reset.disabled = true;
   slider.disabled = true;
 }
 
 function showFrame(next: number) {
   frame = next;
   slider.value = String(next);
-  status.textContent = `Frame ${next}`;
+  counter.textContent = `${String(next).padStart(3, '0')} / ${request.config.durationInFrames - 1}`;
 }
 
 play.addEventListener('click', () => {
@@ -44,11 +65,12 @@ play.addEventListener('click', () => {
   playing = true;
   play.textContent = 'Pause';
   const active = ++generation;
-  const started = performance.now() - frame / request.config.fps * 1000;
+  const startFrame = frame;
+  const started = performance.now();
 
   const advance = async (now: number) => {
     if (generation !== active) return;
-    const next = Math.min(request.config.durationInFrames - 1, Math.floor((now - started) / 1000 * request.config.fps));
+    const next = playbackFrame(now, started, startFrame, request.config);
     try {
       await controller.seek(next, { capture: false });
       if (generation !== active) return;
@@ -62,25 +84,31 @@ play.addEventListener('click', () => {
   animation = requestAnimationFrame(now => { void advance(now); });
 });
 
-slider.addEventListener('input', () => {
+function seek(next: number) {
   stop();
-  const active = generation;
-  const next = Number(slider.value);
+  const active = ++generation;
   void controller.seek(next).then(() => {
     if (generation === active) showFrame(next);
   }).catch(error => {
     if (generation === active) fail(error);
   });
-});
+}
+
+slider.addEventListener('input', () => seek(Number(slider.value)));
+reset.addEventListener('click', () => seek(0));
 
 window.addEventListener('pagehide', () => {
   stop();
+  resize.disconnect();
   disconnect();
+  void unmount(panel);
   void controller.dispose().catch(() => undefined);
 }, { once: true });
 
 void controller.ready().then(() => {
   play.disabled = false;
+  reset.disabled = false;
   slider.disabled = false;
+  status.textContent = 'Preview ready. Press Play or scrub to inspect a frame.';
   showFrame(0);
 }).catch(fail);

package/examples/quickstart/src/playback.ts

@@ -0,0 +1,6 @@
+import type { SceneConfig } from '@machinal/scenes/runtime';
+
+export function playbackFrame(timestamp: number, startedAt: number, startFrame: number, config: SceneConfig): number {
+  const elapsed = Math.max(0, timestamp - startedAt);
+  return Math.min(config.durationInFrames - 1, startFrame + Math.floor(elapsed * config.fps / 1000));
+}

package/examples/quickstart/src/useLocalExport.svelte.ts

@@ -0,0 +1,46 @@
+import { exportRequest, type ExportStatus } from './export-api';
+
+type Connection =
+  | { phase: 'checking' }
+  | { phase: 'connected'; status: ExportStatus }
+  | { phase: 'error'; message: string };
+
+export function useLocalExport() {
+  let connection = $state<Connection>({ phase: 'checking' });
+  let submitting = $state(false);
+  let request: AbortController | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  function dispose() {
+    request?.abort();
+    clearTimeout(timer);
+  }
+
+  async function refresh(action: 'status' | 'setup' | 'render' = 'status') {
+    dispose();
+    const controller = new AbortController();
+    request = controller;
+    submitting = true;
+    try {
+      const status = await exportRequest(action, controller.signal);
+      if (controller.signal.aborted) return;
+      connection = { phase: 'connected', status };
+      if (['installing', 'building', 'rendering'].includes(status.job.phase)) {
+        timer = setTimeout(() => { void refresh(); }, 800);
+      }
+    } catch (error) {
+      if (!controller.signal.aborted) connection = { phase: 'error', message: error instanceof Error ? error.message : String(error) };
+    } finally {
+      if (!controller.signal.aborted) submitting = false;
+    }
+  }
+
+  return {
+    refresh,
+    dispose,
+    get connection() { return connection; },
+    get busy() {
+      return submitting || connection.phase === 'checking' || connection.phase === 'connected' && ['installing', 'building', 'rendering'].includes(connection.status.job.phase);
+    },
+  };
+}

package/examples/quickstart/src/workspace.css

@@ -0,0 +1,79 @@
+:root {
+  font-family: 'IBM Plex Sans Variable', sans-serif;
+  color: #262a30;
+  background: #f3f2ee;
+  font-synthesis: none;
+  --rule: #cbcbc5;
+  --accent: #7047c7;
+  --secondary: #5e646b;
+}
+
+* { box-sizing: border-box; }
+body { margin: 0; }
+button, input { font: inherit; }
+button, .download { border: 1px solid var(--rule); border-radius: 3px; padding: 10px 14px; background: #faf9f6; color: inherit; cursor: pointer; text-decoration: none; text-align: center; }
+button:hover:not(:disabled), .download:hover { border-color: var(--accent); background: #eae3f2; }
+button:disabled { opacity: 0.55; cursor: not-allowed; }
+button.primary, .download { background: #c6adff; border-color: #ad91e6; font-weight: 550; }
+button.primary:hover:not(:disabled), .download:hover { background: #d5c2ff; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 3px; }
+::selection { background: #d5c2ff; color: #262a30; }
+input { accent-color: var(--accent); caret-color: var(--accent); }
+a { color: #593495; text-underline-offset: 3px; }
+.command-bar { min-height: 64px; display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: 16px 5%; background: #222833; color: #f3f2ee; }
+.brand { font-size: 21px; font-weight: 600; }
+.brand span { font-weight: 400; color: #d9dce2; }
+.command-bar > span:last-child { font-size: 14px; }
+main { max-width: 1320px; margin: auto; padding: 44px 5%; }
+h1 { font-size: clamp(28px, 3.2vw, 42px); font-weight: 550; letter-spacing: -0.025em; line-height: 1.15; margin: 0; text-wrap: balance; }
+.heading > p { color: var(--secondary); line-height: 1.6; margin: 12px 0 28px; }
+.workbench { display: grid; grid-template-columns: minmax(0, 1fr) 330px; border: 1px solid var(--rule); background: #faf9f6; }
+.viewer, #export { min-width: 0; }
+.panel-heading { min-height: 62px; display: flex; align-items: center; justify-content: space-between; flex-wrap: wrap; gap: 10px; padding: 17px 20px; border-bottom: 1px solid var(--rule); }
+h2 { font-size: 18px; line-height: 1.3; font-weight: 550; margin: 0; }
+h3 { font-size: 16px; font-weight: 550; line-height: 1.4; margin: 0; }
+.measurement { font-family: ui-monospace, monospace; font-size: 12px; font-variant-numeric: tabular-nums; color: var(--secondary); }
+#viewport { position: relative; overflow: hidden; background: #f5f2eb; }
+#scene { position: absolute; left: 0; top: 0; transform-origin: top left; }
+.transport { display: flex; align-items: center; gap: 10px; border-top: 1px solid var(--rule); padding: 14px 20px; }
+.scrubber { flex: 1; min-width: 40px; }
+.scrubber input { width: 100%; min-height: 32px; margin: 0; }
+.preview-status { padding: 0 20px 16px; font-size: 13px; color: var(--secondary); margin: 0; line-height: 1.5; }
+#export { border-left: 1px solid var(--rule); }
+.export-body { display: grid; gap: 22px; padding: 22px 20px; }
+.export-step { display: grid; gap: 10px; }
+.export-step + .export-step { border-top: 1px solid var(--rule); padding-top: 22px; }
+.export-body p { font-size: 14px; color: var(--secondary); line-height: 1.6; margin: 0; }
+.tool-list { list-style: none; padding: 0; margin: 0; display: grid; gap: 8px; }
+.tool-list li { display: flex; align-items: baseline; justify-content: space-between; gap: 12px; font-size: 14px; }
+.tool-state { color: var(--secondary); font-size: 13px; }
+.tool-state.ready { color: #386143; }
+.export-body .export-error { color: #a02e32; white-space: pre-wrap; overflow-wrap: anywhere; }
+.operation-status { padding-top: 2px; }
+.render-result { display: grid; gap: 12px; }
+.download { display: block; }
+.download svg { width: 18px; height: 18px; vertical-align: -3px; margin-right: 7px; }
+.source-guide { margin-top: 32px; max-width: 72ch; }
+.source-guide p { color: var(--secondary); font-size: 14px; line-height: 1.75; margin: 12px 0; }
+code { font-family: ui-monospace, monospace; font-size: 0.88em; color: #593495; background: #eae6ef; padding: 2px 4px; overflow-wrap: anywhere; }
+summary { cursor: pointer; font-size: 14px; padding: 8px 0; text-underline-offset: 4px; }
+summary:hover { color: #593495; text-decoration: underline; }
+footer { border-top: 1px solid var(--rule); padding: 20px 5%; font-size: 13px; color: var(--secondary); line-height: 1.6; }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }
+pre { scrollbar-color: #b7abc9 #eae6ef; }
+@media (max-width: 900px) {
+  .workbench { grid-template-columns: 1fr; }
+  #export { border-left: 0; border-top: 1px solid var(--rule); }
+  .export-body { grid-template-columns: 1fr 1fr; }
+  .export-step + .export-step { border-top: 0; padding-top: 0; }
+  .operation-status { grid-column: 1 / -1; }
+}
+@media (max-width: 580px) {
+  main { padding-top: 28px; }
+  .command-bar > span:last-child { display: none; }
+  .panel-heading { padding: 14px; }
+  .transport { padding: 12px; flex-wrap: wrap; }
+  .transport output { width: 100%; text-align: right; }
+  .export-body { grid-template-columns: 1fr; padding: 20px 14px; }
+  .export-step + .export-step { border-top: 1px solid var(--rule); padding-top: 22px; }
+}

package/examples/quickstart/tools/local-export.mjs

@@ -0,0 +1,120 @@
+import { randomUUID } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const prefix = '/__machinal/export/';
+const busyPhases = new Set(['installing', 'building', 'rendering']);
+
+export function localExportPlugin({ build, checkTools, installTools, render }) {
+  return {
+    name: 'machinal-local-export',
+    apply: 'serve',
+    configureServer(server) {
+      const root = server.config.root;
+      let tools;
+      let inspection;
+      let job = { phase: 'idle' };
+      let output;
+
+      async function inspect() {
+        inspection ??= checkTools().then(result => { tools = result; }).finally(() => { inspection = undefined; });
+        await inspection;
+      }
+
+      function progress(message) {
+        job = { ...job, message: String(message).trim().split(/\r?\n/).at(-1).slice(-1200) };
+      }
+
+      async function run(action) {
+        try {
+          if (action === 'setup') {
+            tools = await installTools({ onProgress: progress });
+            job = { phase: 'idle' };
+          } else {
+            await exportVideo();
+          }
+        } catch (error) {
+          job = { phase: 'error', message: (error instanceof Error ? error.message : String(error)).slice(-4000) };
+        }
+      }
+
+      async function exportVideo() {
+        const temporary = await mkdtemp(join(tmpdir(), 'machinal-preview-'));
+        try {
+          const request = JSON.parse(await readFile(join(root, 'scene.config.json'), 'utf8'));
+          const audio = request.audio?.map(track => ({ ...track, file: resolve(root, track.file) }));
+          const filename = `scene-${randomUUID()}.mp4`;
+          await build({ root, configFile: server.config.configFile, logLevel: 'warn', build: { outDir: temporary, emptyOutDir: true } });
+          await mkdir(join(root, 'renders'), { recursive: true });
+          const destination = join(root, 'renders', filename);
+          job = { phase: 'rendering', message: 'Capturing frames and encoding MP4…' };
+          await render({ request: { ...request, ...(audio ? { audio } : {}) }, serveDirectory: temporary, output: destination, onProgress: progress });
+          output = destination;
+          job = { phase: 'done', filename, download: `${prefix}video`, localFile: destination };
+        } finally {
+          await rm(temporary, { recursive: true, force: true });
+        }
+      }
+
+      server.middlewares.use((request, response, next) => {
+        if (!request.url?.startsWith(prefix)) return next();
+        void handle(request, response).catch(error => {
+          if (response.headersSent) response.destroy(error);
+          else json(response, 500, { error: error instanceof Error ? error.message : String(error) });
+        });
+      });
+
+      async function handle(request, response) {
+        const host = request.headers.host;
+        const port = server.httpServer?.address()?.port;
+        const allowedHosts = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`];
+        if (!allowedHosts.includes(host) || request.headers.origin && request.headers.origin !== `http://${host}` || request.headers['sec-fetch-site'] === 'cross-site') {
+          return json(response, 403, { error: 'Local export only accepts same-origin requests on the loopback address.' });
+        }
+        const action = request.url.slice(prefix.length);
+        if (action === 'video' && request.method === 'GET') return download(response);
+        if (action === 'status' && request.method === 'GET') {
+          if (!tools) await inspect();
+          return json(response, 200, { tools, job });
+        }
+        if (!['setup', 'render'].includes(action)) return json(response, 404, { error: 'Unknown local export action.' });
+        if (request.method !== 'POST') return json(response, 405, { error: 'Use POST to start a local export action.' });
+        if (request.headers['x-machinal-export'] !== '1') return json(response, 403, { error: 'Missing local export request header.' });
+        if (busyPhases.has(job.phase)) return json(response, 409, { error: 'A local operation is already running. Wait for it to finish.' });
+        if (!tools) await inspect();
+        if (busyPhases.has(job.phase)) return json(response, 409, { error: 'A local operation is already running. Wait for it to finish.' });
+        if (action === 'render' && !tools.ready) return json(response, 409, { error: 'Download rendering tools before rendering. Use the button above or npm run setup.' });
+        job = action === 'setup'
+          ? { phase: 'installing', message: 'Downloading Chrome Headless Shell and FFmpeg…' }
+          : { phase: 'building', message: 'Building the current scene source…' };
+        json(response, 202, { tools, job });
+        void run(action);
+      }
+
+      async function download(response) {
+        if (job.phase !== 'done' || !output) return json(response, 404, { error: 'No completed video. Render your scene first.' });
+        const filename = job.filename;
+        const destination = output;
+        const file = await stat(destination);
+        response.writeHead(200, {
+          'Content-Type': 'video/mp4',
+          'Content-Length': file.size,
+          'Content-Disposition': `attachment; filename="${filename}"`,
+          'Cache-Control': 'no-store',
+          'X-Content-Type-Options': 'nosniff',
+        });
+        const stream = createReadStream(destination);
+        stream.once('error', error => response.destroy(error));
+        response.once('close', () => stream.destroy());
+        stream.pipe(response);
+      }
+    },
+  };
+}
+
+function json(response, code, value) {
+  response.writeHead(code, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' });
+  response.end(JSON.stringify(value));
+}

package/examples/quickstart/vite.config.js

@@ -1,9 +1,11 @@
-import { defineConfig } from 'vite';
+import { build, defineConfig } from 'vite';
 import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { doctor, renderVideo, setup } from '@machinal/scenes/node';
 import { fileURLToPath } from 'node:url';
+import { localExportPlugin } from './tools/local-export.mjs';
 
 export default defineConfig({
-  plugins: [svelte()],
+  plugins: [svelte(), localExportPlugin({ build, checkTools: doctor, installTools: setup, render: renderVideo })],
   build: {
     rollupOptions: {
       input: {

package/native/manifest.json

@@ -5,29 +5,29 @@
       "platform": "win32",
       "arch": "x64",
       "file": "win32-x64/scene-render.exe",
-      "size": 8543232,
-      "sha256": "8aa4ea2aeb13e7cf0fa1ba63f93b181f0d2538f3244babbf33b2c9fe6a8c4d27"
+      "size": 8544256,
+      "sha256": "462d422cfec1724eb700effeb758c6ad9dd9f695a577464a205f4946682159c6"
     },
     {
       "platform": "linux",
       "arch": "x64",
       "file": "linux-x64/scene-render",
       "size": 8274080,
-      "sha256": "e3d81f2d47a8311d316b8cfa0bf0bc2b0558e3457853371545f62386d62ae9fd"
+      "sha256": "b898cdf3a64d078e132cdd33eb4c00df42e9a335b29c012f6fe112e7d91341b7"
     },
     {
       "platform": "darwin",
       "arch": "x64",
       "file": "darwin-x64/scene-render",
-      "size": 8497728,
-      "sha256": "cccb20e6eca747d97475fa153041e4cd88613f9a22e9aa16d4ad31125568a07d"
+      "size": 8497744,
+      "sha256": "e96ee02651f6e1c06e14fe7df80f38ae3beabcc884d4a6d3081013cea28bb534"
     },
     {
       "platform": "darwin",
       "arch": "arm64",
       "file": "darwin-arm64/scene-render",
-      "size": 7940434,
-      "sha256": "8d81cc4bfab2946d263f7ecb550387fccdac4c151e009e767e007fb239f6611d"
+      "size": 7940450,
+      "sha256": "97b15efacd64557f469775f0dd64ef6fd7ecec45462a6ca3a9e6b586373baa3e"
     }
   ]
 }

package/node/cli-output.mjs

@@ -0,0 +1,10 @@
+export function formatToolchainStatus(status) {
+  const heading = status.ready ? 'Rendering tools are ready.' : 'Rendering tools are not ready.';
+  const tools = [['Renderer', status.renderer], ['Chrome Headless Shell', status.browser], ['FFmpeg', status.ffmpeg]];
+  const lines = tools.map(([name, tool]) => `  ${name}: ${tool.available ? 'ready' : tool.error ?? 'not available'}`);
+  return [heading, ...lines].join('\n');
+}
+
+export function formatRenderResult(asset) {
+  return `Rendered ${asset.file}\n${asset.width} × ${asset.height} · ${asset.fps} fps · ${asset.duration} s`;
+}

package/node/init.mjs

@@ -0,0 +1,20 @@
+import { cp, mkdir, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const template = fileURLToPath(new URL('../examples/quickstart/', import.meta.url));
+
+export async function initProject(destination) {
+  try {
+    await mkdir(destination);
+  } catch (error) {
+    if (error.code === 'EEXIST') throw new Error(`Destination already exists: ${destination}. No files were changed.`);
+    throw error;
+  }
+  for (const name of await readdir(template)) {
+    const target = name === 'gitignore' ? '.gitignore' : name;
+    await cp(join(template, name), join(destination, target), {
+      recursive: true, errorOnExist: true, force: false,
+    });
+  }
+}

package/node/toolchain.mjs

@@ -59,7 +59,7 @@ async function probe(path, args) {
 export async function doctor(options = {}) {
   const paths = toolPaths(options);
   let renderer;
-  try { renderer = await probe(await rendererPath(), ['-h']); }
+  try { renderer = await probe(await rendererPath(), ['-version']); }
   catch (error) { renderer = { available: false, error: error.message }; }
   const [browser, ffmpeg] = await Promise.all([probe(paths.browser, ['--version']), probe(paths.ffmpeg, ['-version'])]);
   return { ready: renderer.available && browser.available && ffmpeg.available, cacheDirectory: paths.cache, renderer, browser, ffmpeg };
@@ -69,20 +69,24 @@ export async function setup(options = {}) {
   const paths = toolPaths(options);
   await rendererPath();
   const report = options.onProgress ?? (() => {});
-  if (!options.browserExecutable && !process.env.SCENE_BROWSER) {
+  if (!options.browserExecutable && !process.env.SCENE_BROWSER && !await isInstalled(paths.browser)) {
     report(`Installing Chrome Headless Shell ${browserBuild} (official Chrome for Testing download)...`);
     await install({ browser: Browser.CHROMEHEADLESSSHELL, buildId: browserBuild, cacheDir: join(paths.cache, 'browser'), installDeps: false });
   }
   if (!options.ffmpegExecutable && !process.env.SCENE_FFMPEG) {
-    report(`Installing FFmpeg ${ffmpegRelease} (checksum-verified release, including license and build information)...`);
-    await installFFmpeg(paths.ffmpeg);
+    await installFFmpeg(paths.ffmpeg, report);
   }
   const status = await doctor(options);
   if (!status.ready) throw new Error(`Rendering tools are not ready:\n${[status.renderer, status.browser, status.ffmpeg].filter(tool => !tool.available).map(tool => `${tool.path ?? 'renderer'}: ${tool.error}`).join('\n')}\nOn Linux, Chromium also requires system shared libraries; see the README.`);
   return status;
 }
 
-async function installFFmpeg(executable) {
+async function isInstalled(executable) {
+  try { await access(executable); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+async function installFFmpeg(executable, report) {
   const target = `${process.platform}-${process.arch}`;
   const hashes = ffmpegReleases[target];
   const directory = dirname(executable);
@@ -94,6 +98,7 @@ async function installFFmpeg(executable) {
   } catch (error) {
     if (error.code !== 'ENOENT') throw error;
   }
+  report(`Installing FFmpeg ${ffmpegRelease} (checksum-verified release, including license and build information)...`);
   await mkdir(dirname(directory), { recursive: true });
   const temporary = await mkdtemp(join(dirname(directory), '.install-'));
   const base = `https://github.com/eugeneware/ffmpeg-static/releases/download/${ffmpegRelease}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@machinal/scenes",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Author, preview and render frame-driven Svelte, HTML and Three.js scenes to MP4 and WebM",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,6 +39,8 @@
     "renderer/go.sum",
     "dist/",
     "examples/quickstart/src/",
+    "examples/quickstart/tools/",
+    "examples/quickstart/gitignore",
     "examples/quickstart/index.html",
     "examples/quickstart/scene.html",
     "examples/quickstart/scene.config.json",
@@ -63,7 +65,7 @@
     "check": "pnpm --filter @direction/scene-runtime check && pnpm --filter @direction/scene-svelte check && pnpm --filter @direction/scene-studio check",
     "test": "vitest run",
     "test:package": "pnpm run build:package && pnpm run build:renderer && node --test tests/package.test.mjs",
-    "test:cli": "node --test tests/cli.test.mjs",
+    "test:cli": "node --test tests/cli.test.mjs tests/init.test.mjs tests/local-export.test.mjs",
     "test:evaluation": "node --test scripts/evaluate-production.test.mjs",
     "test:browser": "playwright test",
     "test:go": "go -C renderer test ./...",

package/renderer/cmd/scene-render/main.go

@@ -16,7 +16,10 @@ import (
 	sceneengine "github.com/catalinfl/viral-server/scene-engine/renderer"
 )
 
+var version = "dev"
+
 type cliOptions struct {
+	printVersion   bool
 	requestFile    string
 	output         string
 	serveDirectory string
@@ -36,6 +39,7 @@ func main() {
 func parseFlags() cliOptions {
 	var options cliOptions
 	var allowedOrigins string
+	flag.BoolVar(&options.printVersion, "version", false, "print the renderer version")
 	flag.StringVar(&options.requestFile, "request", "", "JSON/YAML job file (required)")
 	flag.StringVar(&options.output, "output", "", "new .mp4 or .webm output file (required)")
 	flag.StringVar(&options.serveDirectory, "serve", "", "serve a built scene directory on an ephemeral loopback port")
@@ -59,6 +63,12 @@ func parseFlags() cliOptions {
 }
 
 func run(ctx context.Context, options cliOptions, stdout, stderr io.Writer) error {
+	if options.printVersion {
+		if _, err := fmt.Fprintf(stdout, "machinal-scene-render %s\n", version); err != nil {
+			return fmt.Errorf("write renderer version: %w", err)
+		}
+		return nil
+	}
 	if options.requestFile == "" || options.output == "" {
 		return fmt.Errorf("-request and -output are required")
 	}

package/renderer/cmd/scene-render/main_test.go

@@ -0,0 +1,37 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+)
+
+func TestVersionDoesNotRequireRenderingTools(t *testing.T) {
+	var stdout, stderr bytes.Buffer
+	err := run(context.Background(), cliOptions{printVersion: true}, &stdout, &stderr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := stdout.String(), "machinal-scene-render "+version+"\n"; got != want {
+		t.Fatalf("version output = %q, want %q", got, want)
+	}
+	if stderr.Len() != 0 {
+		t.Fatalf("unexpected diagnostics: %s", stderr.String())
+	}
+}
+
+func TestVersionReportsWriteFailure(t *testing.T) {
+	err := run(context.Background(), cliOptions{printVersion: true}, failingWriter{}, io.Discard)
+	if !errors.Is(err, io.ErrClosedPipe) || !strings.Contains(err.Error(), "write renderer version") {
+		t.Fatalf("expected a wrapped write error, got %v", err)
+	}
+}
+
+type failingWriter struct{}
+
+func (failingWriter) Write([]byte) (int, error) {
+	return 0, io.ErrClosedPipe
+}