@machinal/scenes 0.0.0-stage → 0.1.1

package/native/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,158 @@
+Go standard library
+
+Copyright 2009 The Go Authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+   * Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+   * Redistributions in binary form must reproduce the above
+copyright notice, this list of conditions and the following disclaimer
+in the documentation and/or other materials provided with the
+distribution.
+   * Neither the name of Google LLC nor the names of its
+contributors may be used to endorse or promote products derived from
+this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+--------------------
+
+github.com/chromedp/cdproto v0.157.8 (LICENSE)
+
+The MIT License (MIT)
+
+Copyright (c) 2016-2026 Kenneth Shaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+--------------------
+
+github.com/chromedp/chromedp v0.20.1 (LICENSE)
+
+The MIT License (MIT)
+
+Copyright (c) 2016-2026 Kenneth Shaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+--------------------
+
+gopkg.in/yaml.v3 v3.0.1 (LICENSE)
+
+
+This project is covered by two different licenses: MIT and Apache.
+
+#### MIT License ####
+
+The following files were ported to Go from C files of libyaml, and thus
+are still covered by their original MIT license, with the additional
+copyright staring in 2011 when the project was ported over:
+
+    apic.go emitterc.go parserc.go readerc.go scannerc.go
+    writerc.go yamlh.go yamlprivateh.go
+
+Copyright (c) 2006-2010 Kirill Simonov
+Copyright (c) 2006-2011 Kirill Simonov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+### Apache License ###
+
+All the remaining project files are covered by the Apache license:
+
+Copyright (c) 2011-2019 Canonical Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+--------------------
+
+gopkg.in/yaml.v3 v3.0.1 (NOTICE)
+
+Copyright 2011-2016 Canonical Ltd.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/native/manifest.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "targets": [
+    {
+      "platform": "win32",
+      "arch": "x64",
+      "file": "win32-x64/scene-render.exe",
+      "size": 8543232,
+      "sha256": "34bd5002c16df9e73ea4104694e440c06c8c503f735a6fe0850672024f05a3c5"
+    },
+    {
+      "platform": "linux",
+      "arch": "x64",
+      "file": "linux-x64/scene-render",
+      "size": 8274080,
+      "sha256": "59e027f9293829f3aa4db965b2e73039c3ee54ea107b847e0d8ef3dfca7eab73"
+    },
+    {
+      "platform": "darwin",
+      "arch": "x64",
+      "file": "darwin-x64/scene-render",
+      "size": 8497744,
+      "sha256": "8e718e1863cdc97432fa3baa65444fe2f65e2c3e7c04e9c5eb9b60818043fdd8"
+    },
+    {
+      "platform": "darwin",
+      "arch": "arm64",
+      "file": "darwin-arm64/scene-render",
+      "size": 7940450,
+      "sha256": "ae9789bc30c2808ecb8bf5c636c31cf26409509b9e039ffc3e2674d5e3e063dc"
+    }
+  ]
+}

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/download.mjs

@@ -0,0 +1,37 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { constants, copyFile, mkdir, rm } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+export async function sha256(path) {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest('hex');
+}
+
+export async function downloadVerified(url, destination, expectedHash, fetchFile = fetch) {
+  if (new URL(url).protocol !== 'https:') throw new Error('Tool downloads require HTTPS');
+  const response = await fetchFile(url, { signal: AbortSignal.timeout(300_000) });
+  if (!response.ok || !response.body) throw new Error(`Tool download failed: HTTP ${response.status}`);
+  await mkdir(dirname(destination), { recursive: true });
+  const temporary = `${destination}.partial-${randomUUID()}`;
+  const hash = createHash('sha256');
+  let received = 0;
+  const meter = new Transform({
+    transform(chunk, encoding, next) {
+      received += chunk.length;
+      if (received > 128 * 1024 * 1024) return next(new Error('Tool download exceeds the 128 MiB limit'));
+      hash.update(chunk);
+      next(null, chunk);
+    },
+  });
+  try {
+    await pipeline(Readable.fromWeb(response.body), meter, createWriteStream(temporary, { flags: 'wx' }));
+    if (hash.digest('hex') !== expectedHash) throw new Error('Tool download SHA-256 mismatch; no executable was installed');
+    await copyFile(temporary, destination, constants.COPYFILE_EXCL);
+  } finally {
+    await rm(temporary, { force: true });
+  }
+}

package/node/ffmpeg-releases.mjs

@@ -0,0 +1,24 @@
+// SHA-256 digests published by GitHub for the pinned release assets.
+export const ffmpegRelease = 'b6.1.1';
+export const ffmpegReleases = {
+  'win32-x64': {
+    archive: '8883a3dffbd0a16cf4ef95206ea05283f78908dbfb118f73c83f4951dcc06d77',
+    license: '8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903',
+    readme: 'a636a7183c58006351acbaf35303c0ed85c6e1320fd4e80de453ba6157de6311',
+  },
+  'linux-x64': {
+    archive: 'bfe8a8fc511530457b528c48d77b5737527b504a3797a9bc4866aeca69c2dffa',
+    license: '8ceb4b9ee5adedde47b31e975c1d90c73ad27b6b165a1dcd80c7c545eb65b903',
+    readme: '72f4b1b06d419d22ace6e7cc75f06826f90737345aa0b1736158929f4aacc537',
+  },
+  'darwin-x64': {
+    archive: '929b375c1182d956c51f7ac25e0b2b0411fb01f6f407aa15c9758efeb4242106',
+    license: '2e1d16c72fd74e12063776371da757322f8b77589386532f4fd8634bde7de1af',
+    readme: 'e88a0325f8e5b75210355e37341824f074d3cd82def2125be54c914b62848a36',
+  },
+  'darwin-arm64': {
+    archive: '8923876afa8db5585022d7860ec7e589af192f441c56793971276d450ed3bbfa',
+    license: 'cb48bf09a11f5fb576cddb0431c8f5ed0a60157a9ec942adffc13907cbe083f2',
+    readme: '05ba4b92c96605434b1aaae3eedf5a2c280c9607bf78ffca9a5b536d9af2dc6a',
+  },
+};

package/node/index.d.ts

@@ -0,0 +1,50 @@
+import type { RenderedSceneAsset, SceneRequest } from '../dist/runtime/index.js';
+
+export interface ToolOptions {
+  cacheDirectory?: string;
+  browserExecutable?: string;
+  ffmpegExecutable?: string;
+}
+
+export interface ToolStatus {
+  path?: string;
+  available: boolean;
+  version?: string;
+  error?: string;
+}
+
+export interface ToolchainStatus {
+  ready: boolean;
+  cacheDirectory: string;
+  renderer: ToolStatus;
+  browser: ToolStatus;
+  ffmpeg: ToolStatus;
+}
+
+export interface AudioTrack {
+  file: string;
+  start: number;
+  from?: number;
+  duration: number;
+  volume?: number;
+}
+
+export interface RenderRequest extends SceneRequest {
+  url: string;
+  audio?: AudioTrack[];
+}
+
+export interface RenderOptions extends ToolOptions {
+  request: string | RenderRequest;
+  serveDirectory?: string;
+  output?: string;
+  workers?: number;
+  noSandbox?: boolean;
+  lossless?: boolean;
+  gpu?: boolean;
+  onProgress?: (message: string) => void;
+}
+
+export function setup(options?: ToolOptions & { onProgress?: (message: string) => void }): Promise<ToolchainStatus>;
+export function doctor(options?: ToolOptions): Promise<ToolchainStatus>;
+export function renderVideo(options: RenderOptions): Promise<RenderedSceneAsset>;

package/node/index.mjs

@@ -0,0 +1,2 @@
+export { doctor, setup } from './toolchain.mjs';
+export { renderVideo } from './render.mjs';

package/node/platforms.mjs

@@ -0,0 +1,14 @@
+export const rendererTargets = [
+  { platform: 'win32', arch: 'x64', goos: 'windows', goarch: 'amd64', file: 'win32-x64/scene-render.exe' },
+  { platform: 'linux', arch: 'x64', goos: 'linux', goarch: 'amd64', file: 'linux-x64/scene-render' },
+  { platform: 'darwin', arch: 'x64', goos: 'darwin', goarch: 'amd64', file: 'darwin-x64/scene-render' },
+  { platform: 'darwin', arch: 'arm64', goos: 'darwin', goarch: 'arm64', file: 'darwin-arm64/scene-render' },
+];
+
+export function platformTarget(platform = process.platform, arch = process.arch) {
+  const target = rendererTargets.find(target => target.platform === platform && target.arch === arch);
+  if (!target) {
+    throw new Error(`Native rendering is not supported on ${platform}-${arch}. Supported: ${rendererTargets.map(target => `${target.platform}-${target.arch}`).join(', ')}. Browser authoring/preview remains available.`);
+  }
+  return target;
+}

package/node/render.mjs

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { parseRenderedSceneAsset, validateRequest } from '../dist/runtime/index.js';
+import { doctor } from './toolchain.mjs';
+
+export async function renderVideo(options) {
+  if (!options?.request) throw new Error('A render request filename or object is required');
+  const output = resolve(options.output ?? 'scene.mp4');
+  if (!/\.(mp4|webm)$/i.test(output)) throw new Error('Output must be a new .mp4 or .webm file');
+  for (const path of [output, `${output}.scene.json`]) {
+    try { await access(path); }
+    catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+    throw new Error(`Output already exists: ${path}. No files were changed.`);
+  }
+  if (options.workers !== undefined && (!Number.isInteger(options.workers) || options.workers < 1 || options.workers > 16)) throw new Error('workers must be an integer between 1 and 16');
+  const tools = await doctor(options);
+  if (!tools.ready) throw new Error(`Rendering tools are not ready. Run machinal-scenes setup, then machinal-scenes doctor.\n${[tools.renderer, tools.browser, tools.ffmpeg].filter(tool => !tool.available).map(tool => tool.error).join('\n')}`);
+  const directory = await mkdtemp(join(tmpdir(), 'machinal-scene-render-'));
+  try {
+    let request;
+    if (typeof options.request === 'string') request = resolve(options.request);
+    else {
+      validateRequest(options.request);
+      const audio = options.request.audio?.map(track => ({ ...track, file: resolve(track.file) }));
+      request = join(directory, 'request.json');
+      await writeFile(request, JSON.stringify({ ...options.request, ...(audio ? { audio } : {}) }), 'utf8');
+    }
+    await mkdir(dirname(output), { recursive: true });
+    const args = ['-request', request, '-serve', resolve(options.serveDirectory ?? 'dist'), '-output', output, '-browser', tools.browser.path, '-ffmpeg', tools.ffmpeg.path, '-workers', String(options.workers ?? 2)];
+    if (options.noSandbox) args.push('-no-sandbox');
+    if (options.lossless) args.push('-lossless');
+    if (options.gpu) args.push('-gpu');
+    const result = await runRenderer(tools.renderer.path, args, options.onProgress);
+    const asset = parseRenderedSceneAsset(JSON.parse(result));
+    const persisted = JSON.parse(await readFile(`${output}.scene.json`, 'utf8'));
+    if (asset.sha256 !== persisted.sha256) throw new Error('Native renderer result and output manifest do not match');
+    return asset;
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+function runRenderer(executable, args, onProgress = () => {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', chunk => { stdout += chunk; });
+    child.stderr.on('data', chunk => {
+      stderr = (stderr + chunk).slice(-64 * 1024);
+      try { onProgress(chunk.toString()); }
+      catch (error) { child.kill(); reject(error); }
+    });
+    child.once('error', reject);
+    child.once('close', code => code === 0 ? resolve(stdout) : reject(new Error(`Scene rendering failed (${code}):\n${stderr}`)));
+  });
+}

package/node/toolchain.mjs

@@ -0,0 +1,118 @@
+import { execFile } from 'node:child_process';
+import { createReadStream, createWriteStream } from 'node:fs';
+import { access, chmod, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { createGunzip } from 'node:zlib';
+import { Browser, computeExecutablePath, install } from '@puppeteer/browsers';
+import { downloadVerified, sha256 } from './download.mjs';
+import { ffmpegRelease, ffmpegReleases } from './ffmpeg-releases.mjs';
+import { platformTarget } from './platforms.mjs';
+
+export const browserBuild = '151.0.7922.34';
+const execute = promisify(execFile);
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+
+export function cacheDirectory(options = {}) {
+  if (options.cacheDirectory || process.env.MACHINAL_SCENES_CACHE) return resolve(options.cacheDirectory || process.env.MACHINAL_SCENES_CACHE);
+  const base = process.platform === 'win32' ? process.env.LOCALAPPDATA ?? join(homedir(), 'AppData/Local')
+    : process.platform === 'darwin' ? join(homedir(), 'Library/Caches')
+      : process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache');
+  return join(base, 'machinal-scenes');
+}
+
+export function toolPaths(options = {}) {
+  platformTarget();
+  const cache = cacheDirectory(options);
+  return {
+    cache,
+    browser: resolve(options.browserExecutable || process.env.SCENE_BROWSER || computeExecutablePath({ browser: Browser.CHROMEHEADLESSSHELL, buildId: browserBuild, cacheDir: join(cache, 'browser') })),
+    ffmpeg: resolve(options.ffmpegExecutable || process.env.SCENE_FFMPEG || join(cache, 'ffmpeg', ffmpegRelease, `${process.platform}-${process.arch}`, process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg')),
+  };
+}
+
+export async function rendererPath() {
+  const target = platformTarget();
+  const manifest = JSON.parse(await readFile(join(packageRoot, 'native/manifest.json'), 'utf8').catch(error => {
+    throw new Error(`This installation is missing the precompiled renderer manifest. Install a complete @machinal/scenes release. (${error.code})`);
+  }));
+  const entry = manifest.targets.find(entry => entry.platform === target.platform && entry.arch === target.arch);
+  if (!entry || entry.file !== target.file) throw new Error('Missing native renderer for this platform');
+  const executable = join(packageRoot, 'native', entry.file);
+  if (await sha256(executable) !== entry.sha256) throw new Error('Native renderer checksum mismatch; reinstall the package');
+  return executable;
+}
+
+async function probe(path, args) {
+  try {
+    await access(path);
+    const { stdout, stderr } = await execute(path, args, { timeout: 15_000, maxBuffer: 128 * 1024, windowsHide: true });
+    return { path, available: true, version: (stdout || stderr).split(/\r?\n/)[0] };
+  } catch (error) {
+    return { path, available: false, error: error.code === 'ENOENT' ? 'Not installed. Run machinal-scenes setup.' : `Cannot execute tool: ${error.message}` };
+  }
+}
+
+export async function doctor(options = {}) {
+  const paths = toolPaths(options);
+  let renderer;
+  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 };
+}
+
+export async function setup(options = {}) {
+  const paths = toolPaths(options);
+  await rendererPath();
+  const report = options.onProgress ?? (() => {});
+  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) {
+    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 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);
+  try {
+    const installed = JSON.parse(await readFile(join(directory, 'installation.json'), 'utf8'));
+    if (installed.archiveSHA256 !== hashes.archive || await sha256(executable) !== installed.executableSHA256) throw new Error(`Cached FFmpeg checksum mismatch: ${directory}`);
+    if (await sha256(join(directory, 'LICENSE')) !== hashes.license || await sha256(join(directory, 'README')) !== hashes.readme) throw new Error(`Cached FFmpeg license/build information is damaged: ${directory}`);
+    return;
+  } 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}`;
+  try {
+    await downloadVerified(`${base}/ffmpeg-${target}.gz`, join(temporary, 'ffmpeg.gz'), hashes.archive);
+    await downloadVerified(`${base}/${target}.LICENSE`, join(temporary, 'LICENSE'), hashes.license);
+    await downloadVerified(`${base}/${target}.README`, join(temporary, 'README'), hashes.readme);
+    const binary = join(temporary, process.platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg');
+    await pipeline(createReadStream(join(temporary, 'ffmpeg.gz')), createGunzip(), createWriteStream(binary, { flags: 'wx' }));
+    await chmod(binary, 0o755);
+    await writeFile(join(temporary, 'installation.json'), JSON.stringify({ archiveSHA256: hashes.archive, executableSHA256: await sha256(binary) }), 'utf8');
+    await rm(join(temporary, 'ffmpeg.gz'));
+    await rename(temporary, directory);
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+}

package/package.json

@@ -1,6 +1,91 @@
 {
   "name": "@machinal/scenes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Author, preview and render frame-driven Svelte, HTML and Three.js scenes to MP4 and WebM",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/catalinfl/machinal-scenes#readme",
+  "repository": { "type": "git", "url": "git+https://github.com/catalinfl/machinal-scenes.git" },
+  "bugs": { "url": "https://github.com/catalinfl/machinal-scenes/issues" },
+  "packageManager": "pnpm@11.9.0",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "svelte": "./dist/index.js",
+  "bin": { "machinal-scenes": "bin/machinal-scenes.mjs" },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "default": "./dist/runtime/index.js"
+    },
+    "./svelte": {
+      "types": "./dist/svelte/index.d.ts",
+      "svelte": "./dist/svelte/index.js",
+      "default": "./dist/svelte/index.js"
+    },
+    "./node": {
+      "types": "./node/index.d.ts",
+      "import": "./node/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "node/",
+    "native/",
+    "renderer/*.go",
+    "renderer/cmd/**/*.go",
+    "renderer/go.mod",
+    "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",
+    "examples/quickstart/package.json",
+    "examples/quickstart/tsconfig.json",
+    "examples/quickstart/vite.config.js",
+    "examples/quickstart/svelte.config.js",
+    "LICENSE",
+    "NOTICE",
+    "LICENSING.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": ["**/*.css"],
+  "engines": { "node": ">=22.12.0" },
+  "keywords": ["svelte", "svelte5", "animation", "motion-graphics", "video", "threejs", "scenes", "frame-driven"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "scripts": {
+    "build": "pnpm run build:package",
+    "build:package": "pnpm --filter @direction/scene-runtime build && pnpm --filter @direction/scene-svelte build && node scripts/build-package.mjs",
+    "build:renderer": "node scripts/build-renderer.mjs",
+    "check": "pnpm --filter @direction/scene-runtime check && pnpm --filter @direction/scene-runtime build && pnpm --filter @direction/scene-svelte check",
+    "test": "pnpm --filter @direction/scene-runtime build && vitest run",
+    "test:package": "pnpm run build:package && pnpm run build:renderer && node --test tests/package.test.mjs",
+    "test:cli": "pnpm run build:package && node --test tests/cli.test.mjs tests/local-export.test.mjs",
+    "test:go": "go -C renderer test ./...",
+    "prepack": "pnpm run build:package && pnpm run build:renderer",
+    "prepublishOnly": "pnpm check && pnpm test && pnpm test:cli && pnpm test:go && pnpm test:package"
+  },
+  "dependencies": {
+    "@puppeteer/browsers": "3.2.6",
+    "@types/three": "^0.180.0",
+    "@webgpu/types": "^0.1.74",
+    "three": "^0.180.0"
+  },
+  "peerDependencies": { "svelte": "^5.15.0" },
+  "devDependencies": {
+    "@playwright/test": "^1.62.0",
+    "@types/node": "^26.1.2",
+    "cross-spawn": "^7.0.6",
+    "svelte": "^5.15.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
+  }
+}