@machinal/scenes 0.0.0-stage → 0.1.1

package/examples/quickstart/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "machinal-scenes-quickstart",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "setup": "machinal-scenes setup",
+    "doctor": "machinal-scenes doctor",
+    "render": "vite build && machinal-scenes render",
+    "build": "vite build",
+    "preview": "vite preview --host 127.0.0.1",
+    "check": "svelte-check --tsconfig ./tsconfig.json && tsc --noEmit"
+  },
+  "dependencies": {
+    "@machinal/scenes": "^0.1.1",
+    "@fontsource-variable/ibm-plex-sans": "^5.3.0",
+    "svelte": "^5.15.0"
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^5.1.1",
+    "@types/node": "^24.0.0",
+    "svelte-check": "^4.7.6",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.4"
+  }
+}

package/examples/quickstart/scene.config.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "url": "/scene.html",
+  "sceneId": "title",
+  "config": {
+    "width": 1280,
+    "height": 720,
+    "fps": 30,
+    "durationInFrames": 180
+  }
+}

package/examples/quickstart/scene.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Scene capture</title>
+    <style>html,body{margin:0;padding:0;background:transparent;overflow:hidden}</style>
+  </head>
+  <body>
+    <div id="scene"></div>
+    <script type="module" src="/src/scene.ts"></script>
+  </body>
+</html>

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

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import { SceneCanvas, interpolate, useScene } from '@machinal/scenes';
+
+  let { title = 'Make a scene.' }: { title?: string } = $props();
+  const scene = useScene();
+  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)" 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>
+  </div>
+</SceneCanvas>
+
+<style>
+  .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

@@ -0,0 +1,114 @@
+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<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;
+let generation = 0;
+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;
+  generation += 1;
+  cancelAnimationFrame(animation);
+  play.textContent = 'Play';
+}
+
+function fail(error: unknown) {
+  stop();
+  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);
+  counter.textContent = `${String(next).padStart(3, '0')} / ${request.config.durationInFrames - 1}`;
+}
+
+play.addEventListener('click', () => {
+  if (playing) {
+    stop();
+    return;
+  }
+  if (frame === request.config.durationInFrames - 1) frame = 0;
+  playing = true;
+  play.textContent = 'Pause';
+  const active = ++generation;
+  const startFrame = frame;
+  const started = performance.now();
+
+  const advance = async (now: number) => {
+    if (generation !== active) return;
+    const next = playbackFrame(now, started, startFrame, request.config);
+    try {
+      await controller.seek(next, { capture: false });
+      if (generation !== active) return;
+      showFrame(next);
+      if (next === request.config.durationInFrames - 1) stop();
+      else animation = requestAnimationFrame(now => { void advance(now); });
+    } catch (error) {
+      if (generation === active) fail(error);
+    }
+  };
+  animation = requestAnimationFrame(now => { void advance(now); });
+});
+
+function seek(next: number) {
+  stop();
+  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/request.ts

@@ -0,0 +1,5 @@
+import { validateRequest, type SceneRequest } from '@machinal/scenes/runtime';
+import config from '../scene.config.json';
+
+export const request = (window.__sceneRequest ?? config) as SceneRequest;
+validateRequest(request);

package/examples/quickstart/src/scene.ts

@@ -0,0 +1,12 @@
+import { exposeScene } from '@machinal/scenes/runtime';
+import { mountSvelteScene } from '@machinal/scenes/svelte';
+import Title from './Title.svelte';
+import { request } from './request';
+
+const controller = mountSvelteScene(Title, document.getElementById('scene')!, request, {});
+const disconnect = exposeScene(controller);
+void controller.ready().catch(error => { window.__sceneError = error.message; });
+window.addEventListener('pagehide', () => {
+  disconnect();
+  void controller.dispose().catch(() => undefined);
+}, { once: true });

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/svelte.config.js

@@ -0,0 +1 @@
+export default {};

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/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": false,
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.svelte"]
+}

package/examples/quickstart/vite.config.js

@@ -0,0 +1,17 @@
+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(), localExportPlugin({ build, checkTools: doctor, installTools: setup, render: renderVideo })],
+  build: {
+    rollupOptions: {
+      input: {
+        index: fileURLToPath(new URL('./index.html', import.meta.url)),
+        scene: fileURLToPath(new URL('./scene.html', import.meta.url)),
+      },
+    },
+  },
+});