@machinal/scenes 0.0.0-stage → 0.1.0

package/node/toolchain.mjs

@@ -0,0 +1,113 @@
+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(), ['-h']); }
+  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) {
+    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);
+  }
+  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) {
+  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;
+  }
+  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.0",
+  "description": "Author, preview and render frame-driven Svelte, HTML and Three.js scenes to MP4 and WebM",
+  "license": "Apache-2.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/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": {
+    "dev": "pnpm --filter @direction/scene-studio dev",
+    "build": "pnpm run build:package && pnpm --filter @direction/scene-studio build",
+    "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-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:evaluation": "node --test scripts/evaluate-production.test.mjs",
+    "test:browser": "playwright test",
+    "test:go": "go -C renderer test ./...",
+    "test:native": "node scripts/test-native.mjs",
+    "prepack": "pnpm run build:package && pnpm run build:renderer",
+    "prepublishOnly": "pnpm check && pnpm test && pnpm test:cli && 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",
+    "ffmpeg-static": "^5.3.0",
+    "ffprobe-static": "^3.1.0",
+    "svelte": "^5.15.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.12"
+  }
+}

package/renderer/browser.go

@@ -0,0 +1,116 @@
+package sceneengine
+
+import (
+	"context"
+	"fmt"
+	"os/exec"
+	"sync"
+	"time"
+
+	"github.com/chromedp/chromedp"
+)
+
+const (
+	defaultConcurrency  = 2
+	maxConcurrency      = 16
+	defaultFrameTimeout = 30 * time.Second
+)
+
+// Renderer owns one Chromium process reused across sequential render jobs.
+// Each active frame has an exclusive tab; concurrent Render calls are rejected.
+type Renderer struct {
+	browser         context.Context
+	cancelBrowser   context.CancelFunc
+	cancelAllocator context.CancelFunc
+	options         Options
+	lease           chan struct{}
+	closeOnce       sync.Once
+	browserLog      *browserLog
+}
+
+// New starts a pinned browser whose lifetime is owned by ctx or Close.
+func New(ctx context.Context, options Options) (*Renderer, error) {
+	options, err := normalizeOptions(options)
+	if err != nil {
+		return nil, err
+	}
+	diagnostics := &browserLog{}
+	flags := append([]chromedp.ExecAllocatorOption{}, chromedp.DefaultExecAllocatorOptions[:]...)
+	flags = append(flags,
+		chromedp.CombinedOutput(diagnostics),
+		chromedp.ExecPath(options.BrowserExecutable),
+		chromedp.Flag("disable-background-timer-throttling", true),
+		chromedp.Flag("disable-renderer-backgrounding", true),
+		chromedp.Flag("disable-backgrounding-occluded-windows", true),
+		chromedp.Flag("force-color-profile", "srgb"),
+		chromedp.Flag("hide-scrollbars", true),
+		chromedp.Flag("mute-audio", true),
+	)
+	if options.NoSandbox {
+		flags = append(flags, chromedp.NoSandbox)
+	}
+	if options.EnableGPU {
+		flags = append(flags, chromedp.Flag("disable-gpu", false), chromedp.Flag("enable-gpu", true))
+	}
+	allocator, cancelAllocator := chromedp.NewExecAllocator(ctx, flags...)
+	browser, cancelBrowser := chromedp.NewContext(allocator)
+	renderer := &Renderer{browser: browser, cancelBrowser: cancelBrowser, cancelAllocator: cancelAllocator, options: options, lease: make(chan struct{}, 1), browserLog: diagnostics}
+	startupTimeout := time.AfterFunc(options.FrameTimeout, cancelBrowser)
+	defer startupTimeout.Stop()
+	if err := chromedp.Do(browser); err != nil {
+		renderer.Close()
+		return nil, diagnostics.wrap(fmt.Errorf("start Chromium: %w", err))
+	}
+	return renderer, nil
+}
+
+func normalizeOptions(options Options) (Options, error) {
+	if options.BrowserExecutable == "" {
+		return options, fmt.Errorf("BrowserExecutable is required; use a pinned Chrome Headless Shell binary")
+	}
+	if options.FFmpegExecutable == "" {
+		options.FFmpegExecutable = "ffmpeg"
+	}
+	ffmpeg, err := exec.LookPath(options.FFmpegExecutable)
+	if err != nil {
+		return options, fmt.Errorf("locate FFmpeg: %w", err)
+	}
+	options.FFmpegExecutable = ffmpeg
+	if options.X264Preset == "" {
+		options.X264Preset = "medium"
+	}
+	switch options.X264Preset {
+	case "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow":
+	default:
+		return options, fmt.Errorf("invalid x264 preset")
+	}
+	if options.EncoderThreads < 0 || options.EncoderThreads > 32 {
+		return options, fmt.Errorf("encoder threads must be between 0 (automatic) and 32")
+	}
+	if options.Concurrency == 0 {
+		options.Concurrency = defaultConcurrency
+	}
+	if options.Concurrency < 1 || options.Concurrency > maxConcurrency {
+		return options, fmt.Errorf("concurrency must be between 1 and %d", maxConcurrency)
+	}
+	if options.FrameTimeout == 0 {
+		options.FrameTimeout = defaultFrameTimeout
+	}
+	if options.FrameTimeout < 0 {
+		return options, fmt.Errorf("frame timeout must be positive")
+	}
+	for _, origin := range options.AllowedOrigins {
+		if _, err := parseOrigin(origin); err != nil {
+			return options, fmt.Errorf("allowed origin %q: %w", origin, err)
+		}
+	}
+	return options, nil
+}
+
+// Close cancels active jobs and releases the browser process; it is idempotent.
+func (r *Renderer) Close() {
+	r.closeOnce.Do(func() {
+		r.cancelBrowser()
+		r.cancelAllocator()
+	})
+}

package/renderer/browser_log.go

@@ -0,0 +1,36 @@
+package sceneengine
+
+import (
+	"bytes"
+	"fmt"
+	"sync"
+)
+
+const maxBrowserLogBytes = 8 << 10
+
+type browserLog struct {
+	mu     sync.Mutex
+	buffer []byte
+}
+
+func (l *browserLog) Write(data []byte) (int, error) {
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	l.buffer = append(l.buffer, data...)
+	if len(l.buffer) > maxBrowserLogBytes {
+		l.buffer = bytes.Clone(l.buffer[len(l.buffer)-maxBrowserLogBytes:])
+	}
+	return len(data), nil
+}
+
+func (l *browserLog) wrap(err error) error {
+	if l == nil || err == nil {
+		return err
+	}
+	l.mu.Lock()
+	defer l.mu.Unlock()
+	if len(l.buffer) == 0 {
+		return err
+	}
+	return fmt.Errorf("%w\nChromium diagnostics:\n%s", err, l.buffer)
+}

package/renderer/browser_log_test.go

@@ -0,0 +1,48 @@
+package sceneengine
+
+import (
+	"errors"
+	"strings"
+	"sync"
+	"testing"
+)
+
+func TestBrowserLogRetainsBoundedFailureDetails(t *testing.T) {
+	var log browserLog
+	data := []byte(strings.Repeat("x", maxBrowserLogBytes) + "\nNo space left on device")
+	written, err := log.Write(data)
+	if err != nil || written != len(data) {
+		t.Fatalf("write browser output: %d, %v", written, err)
+	}
+	if len(log.buffer) != maxBrowserLogBytes {
+		t.Fatalf("browser log has %d bytes", len(log.buffer))
+	}
+	cause := errors.New("capture frame 1405 failed")
+	failure := log.wrap(cause)
+	if !errors.Is(failure, cause) || !strings.HasSuffix(failure.Error(), "No space left on device") {
+		t.Fatalf("lost capture failure or browser diagnostic: %v", failure)
+	}
+}
+
+func TestBrowserLogWithoutOutputPreservesOriginalError(t *testing.T) {
+	cause := errors.New("capture failed")
+	for _, log := range []*browserLog{nil, {}} {
+		if log.wrap(cause) != cause {
+			t.Fatal("empty browser output changed the original error")
+		}
+	}
+}
+
+func TestBrowserLogSupportsConcurrentOutputAndFailures(t *testing.T) {
+	var log browserLog
+	var writers sync.WaitGroup
+	for range 4 {
+		writers.Go(func() {
+			for range 100 {
+				log.Write([]byte("browser diagnostic\n"))
+				log.wrap(errors.New("capture failed"))
+			}
+		})
+	}
+	writers.Wait()
+}