animader-cli 0.0.0-stage → 0.1.1

package/adapters/export-run.mjs

@@ -0,0 +1,126 @@
+// The export operation behind both entries: `animader export` (the CLI
+// command) and the legacy `node demo/export.mjs` compatibility adapter.
+// It inspects the source project, resolves the output paths from the
+// invocation directory, refuses paths that alias the authored inputs, and
+// runs the portable staged export (lib/export.mjs) over the real node
+// producers (export-node.mjs / build-node.mjs). The process boundary —
+// argv parsing and the error:/remedy: printing — belongs to each entry,
+// never to this operation.
+//
+// Stage 1 of the installed-toolchain plan moved this operation into the
+// package: the CLI no longer imports across the checkout boundary.
+
+import { realpath } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+
+import {
+  assertSafeExportPaths,
+  createExportIo,
+  measureBytes,
+  prepareRelease,
+} from './export-node.mjs';
+import { createBuildProducers } from './build-node.mjs';
+import { createNodeIo } from './node-fs.mjs';
+import { inspectProject } from '../lib/contract.mjs';
+import { DemoError } from '../lib/errors.mjs';
+import { exportShow } from '../lib/export.mjs';
+
+/**
+ * One export run: inspect the source project, resolve the output paths from
+ * the invocation directory, refuse paths that alias the authored inputs,
+ * then run the portable staged export over the real producers. The caller
+ * owns the process boundary through `say`/`warn` and may inject `producer`
+ * (the bake/derive/pack/bundle adapter) or `producers` (the build stage
+ * ports inside prepareRelease) for tests; the default is the real vendored
+ * producer chain, which fails loudly where the prepared runtime is absent.
+ *
+ * @param {Object} options
+ * @param {string} options.folder the project folder (realpath'd here)
+ * @param {number} options.seconds the resolved host show length
+ * @param {string} options.out the --out value, resolved from the invocation
+ *   directory by this operation
+ * @param {string} [options.title] the first output line
+ * @param {(line: string) => void} [options.say] stdout line writer
+ * @param {(line: string) => void} [options.warn] stderr line writer
+ * @param {{prepare: Function}} [options.producer] test seam
+ * @param {object} [options.producers] test seam for the build stage ports
+ * @param {object} [options.toolchain] the toolchain descriptor
+ *   (src/toolchain.mjs); the default is the contributor workspace toolchain
+ * @returns {Promise<object>} the exportShow result (manifest, report, paths)
+ */
+export async function runExport({
+  folder,
+  seconds,
+  out,
+  title = 'animader demo export',
+  say: outLine = (line) => process.stdout.write(`${line}\n`),
+  warn: warnLine = (line) => process.stderr.write(`${line}\n`),
+  producer,
+  producers,
+  toolchain = null,
+}) {
+  let real;
+  try {
+    real = await realpath(folder);
+  } catch {
+    throw new DemoError('folder_missing', `the project folder does not exist: ${folder}`, {
+      exitCode: 3,
+      remedy: 'Pass the folder that holds program.sjon, timeline.piece.sjon and one of soundtrack.wav, soundtrack.ogg, soundtrack.opus.',
+    });
+  }
+
+  const io = createNodeIo();
+  const project = await inspectProject({ folder: real, io });
+
+  // A relative --out resolves from the invocation directory, not from the
+  // project: `export ./my-demo --out ./release` writes ./release.
+  const outDir = resolve(out);
+  const paths = {
+    outDir,
+    stageDir: `${outDir}.next`,
+    sizePath: `${outDir}.size.json`,
+    parentDir: dirname(outDir),
+  };
+  await assertSafeExportPaths({ folder: real, paths });
+
+  outLine(title);
+  outLine(`project: ${real}`);
+  outLine(`show: ${seconds}s (host policy)`);
+  outLine(`out: ${outDir}`);
+
+  let prepared = null;
+  const result = await exportShow({
+    project,
+    seconds,
+    paths,
+    io: createExportIo(),
+    producer: producer ?? {
+      async prepare() {
+        const buildProducers = producers ?? createBuildProducers(toolchain ? { toolchain } : {});
+        prepared = await prepareRelease({ project, seconds, paths, producers: buildProducers, toolchain });
+        return { files: prepared.files };
+      },
+    },
+    measure: measureBytes,
+  });
+
+  if (prepared !== null) {
+    outLine(`runtime: ${prepared.meta.runtimeDigest}`);
+    outLine(`payload: assets/show.png (${prepared.meta.payload.bytes} bytes, sha256 ${prepared.meta.payload.sha256})`);
+    outLine(`score: assets/score.pacb (${prepared.meta.score.bytes} bytes, sha256 ${prepared.meta.score.sha256})`);
+    outLine(`pacer runtime: pacer-rt.wasm (${prepared.meta.pacerRtWasm.bytes} bytes, sha256 ${prepared.meta.pacerRtWasm.sha256})`);
+    outLine(`soundtrack: assets/${prepared.meta.soundtrack.name} (${prepared.meta.soundtrack.bytes} bytes, sha256 ${prepared.meta.soundtrack.sha256})`);
+    outLine(`bundle: app.mjs (${prepared.meta.bundle.bytes} bytes, sha256 ${prepared.meta.bundle.sha256}, esbuild ${prepared.meta.bundle.esbuild})`);
+  }
+  outLine(`manifest: ${result.manifest.files.length} files (self excluded)`);
+  for (const file of result.manifest.files) {
+    outLine(`  ${file.path} (${file.bytes} bytes, sha256 ${file.sha256})`);
+  }
+  const { sums, display } = result.report;
+  outLine(`size: ${result.sizePath}`);
+  outLine(`  all: ${sums.all.raw} B raw / ${sums.all.gzip9} B gzip-9 / ${sums.all.brotli11} B brotli-11 (${display.all.rawKiB} KiB raw)`);
+  outLine(`  without music: ${sums.withoutMusic.raw} B raw / ${sums.withoutMusic.gzip9} B gzip-9 / ${sums.withoutMusic.brotli11} B brotli-11`);
+  outLine(`  music: ${sums.music.raw} B raw / ${sums.music.gzip9} B gzip-9 / ${sums.music.brotli11} B brotli-11`);
+  outLine('next: serve the OUT folder; the size report sits beside it and is not part of the payload.');
+  return result;
+}

package/adapters/generations.mjs

@@ -0,0 +1,183 @@
+// The dev session's generation store (plan section 5). Each watch-mode
+// build stages into its own directory under the session root; a successful
+// build publishes that tree as an immutable, sequentially numbered
+// generation, and the served "current" pointer swaps in one assignment —
+// no filesystem-wide transaction is claimed, and none is needed: every
+// generation directory is finished before it can be named, and nothing
+// writes into it afterwards.
+//
+// Retention: a generation retired by a newer publish stays on disk until
+// its in-flight responses finish AND a grace window has passed since its
+// last activity — the grace covers a client that just learned the id (from
+// /config.json or the notify channel) and is still about to fetch its
+// pinned URLs. Sweeping happens on publish and on every response
+// completion, so no timers keep the process alive; at most a couple of
+// retired trees exist at a time. The current generation is never swept.
+//
+// The store is Node-bound on purpose (real directories under one session
+// root); the coherence decisions it serves are the server's.
+
+import { promises as fsp } from 'node:fs';
+import { join } from 'node:path';
+
+import { isSoundtrackName, PLAYER_CONFIG_FORMATS, soundtrackNamesText } from '../lib/soundtrack.mjs';
+import { serverError } from '../lib/errors.mjs';
+import { removeTree } from './node-fs.mjs';
+
+/** How long a retired generation with no in-flight responses is kept. */
+export const DEFAULT_GENERATION_GRACE_MS = 30_000;
+
+/**
+ * @param {Object} options
+ * @param {string} options.root the session-owned root directory (outside
+ *   the project tree); the store never removes anything outside it
+ * @param {number} [options.graceMs] retirement grace window
+ * @param {() => number} [options.now] the clock (a port, injectable for tests)
+ */
+export function createGenerationStore({ root, graceMs = DEFAULT_GENERATION_GRACE_MS, now = Date.now }) {
+  let nextId = 1;
+  let currentId = null;
+  let disposed = false;
+  /** @type {Map<number, {id: number, staging: string, dir: string, configBody: string,
+   *                       lastActivityAt: number, inflight: number, retiredAt: number|null}>} */
+  const generations = new Map();
+
+  function requireCurrentConfig({ seconds, soundtrack }) {
+    if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) {
+      throw serverError(
+        'missing_seconds',
+        `a generation needs the resolved host show length; got ${String(seconds)}`,
+        'The dev build resolves animader.json (or --seconds) before staging a generation.',
+      );
+    }
+    if (!isSoundtrackName(soundtrack)) {
+      throw serverError(
+        'invalid_soundtrack',
+        `a generation needs the inspected soundtrack selection; got ${JSON.stringify(soundtrack ?? null)}`,
+        `Pass the selected name from the project inspection: one of ${soundtrackNamesText()}.`,
+      );
+    }
+  }
+
+  async function sweep(now) {
+    for (const [id, generation] of generations) {
+      if (id === currentId) continue;
+      if (generation.inflight > 0) continue;
+      if (now - generation.lastActivityAt < graceMs) continue;
+      generations.delete(id);
+      await removeTree(generation.staging);
+    }
+  }
+
+  return {
+    /** A fresh empty staging directory under the session root. */
+    async stagingRoot() {
+      if (disposed) throw serverError('generations_disposed', 'the dev session has stopped', 'Start a new animader dev session.');
+      return fsp.mkdtemp(join(root, 'staging-'));
+    },
+
+    /**
+     * Publish one finished build tree as the next generation and retire the
+     * previous current. The tree must be complete: nothing may write into
+     * it after this call.
+     *
+     * @param {Object} options
+     * @param {string} options.staging the staging root this build owns
+     * @param {string} options.dir the finished generation tree (served as
+     *   the generation's project files)
+     * @param {number} options.seconds this generation's resolved host length
+     * @param {string} options.soundtrack this generation's inspected selection
+     */
+    async publish({ staging, dir, seconds, soundtrack }) {
+      if (disposed) {
+        await removeTree(staging);
+        throw serverError('generations_disposed', 'the dev session has stopped', 'Start a new animader dev session.');
+      }
+      requireCurrentConfig({ seconds, soundtrack });
+      // The served tree is canonicalised here, so no caller can hand the
+      // server a generation root that sits behind a symlink (macOS temp
+      // directories routinely do): containment and serving then agree on
+      // one spelling. A tree that cannot be realpath'd was never finished.
+      let realDir;
+      try {
+        realDir = await fsp.realpath(dir);
+      } catch {
+        await removeTree(staging);
+        throw serverError(
+          'generation_tree_missing',
+          `the finished generation tree cannot be resolved: ${dir}`,
+          'The build stages its tree before publishing; check the session root and retry the build.',
+        );
+      }
+      const id = nextId;
+      nextId += 1;
+      const config = {
+        format: PLAYER_CONFIG_FORMATS.demo,
+        seconds,
+        soundtrack,
+        generation: id,
+      };
+      const generation = {
+        id,
+        staging,
+        dir: realDir,
+        configBody: `${JSON.stringify(config)}\n`,
+        lastActivityAt: now(),
+        inflight: 0,
+        retiredAt: null,
+      };
+      generations.set(id, generation);
+      if (currentId !== null && generations.has(currentId)) {
+        generations.get(currentId).retiredAt = now();
+      }
+      currentId = id;
+      await sweep(now());
+      return generation;
+    },
+
+    /** The current generation, or null before the first successful build. */
+    current() {
+      if (currentId === null) return null;
+      return generations.get(currentId) ?? null;
+    },
+
+    /** One retained generation by id, or null once it has been swept. */
+    get(id) {
+      return generations.get(id) ?? null;
+    },
+
+    /** The page URL that pins a session to one generation. */
+    pageUrl(id) {
+      return `/?gen=${id}`;
+    },
+
+    /** Mark one in-flight response onto a generation. */
+    retain(id) {
+      const generation = generations.get(id);
+      if (generation) generation.inflight += 1;
+    },
+
+    /** Finish one in-flight response and sweep what became collectable. */
+    release(id) {
+      const generation = generations.get(id);
+      if (generation && generation.inflight > 0) generation.inflight -= 1;
+      if (generation) generation.lastActivityAt = now();
+      return sweep(now());
+    },
+
+    /** Refresh the grace window for activity on a generation. */
+    touch(id) {
+      const generation = generations.get(id);
+      if (generation) generation.lastActivityAt = now();
+    },
+
+    /** Remove the whole session root; the store is unusable afterwards. */
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+      currentId = null;
+      generations.clear();
+      await removeTree(root);
+    },
+  };
+}

package/adapters/http.mjs

@@ -0,0 +1,294 @@
+// Node HTTP adapter. It binds one loopback server, serves the actual player
+// page, the host config, the requested project root, the prepared runtime root
+// and the narrow, allowlisted app/example modules, refuses symlink escapes after
+// canonicalization, and exposes an idempotent close() that owns nothing but
+// this server. It is not a project security sandbox and makes no claim about
+// unknown MIME types: those are 415.
+//
+// The page route is the actual player; its module imports are served from
+// separate narrow mounts so the checkout root is never a web root.
+
+import { createReadStream } from 'node:fs';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { serverError } from '../lib/errors.mjs';
+import { resolveRequest } from '../lib/routes.mjs';
+import { isSoundtrackName, PLAYER_CONFIG_FORMATS, soundtrackNamesText } from '../lib/soundtrack.mjs';
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const COMMON_HEADERS = Object.freeze({
+  'X-Content-Type-Options': 'nosniff',
+  'Cache-Control': 'no-store',
+});
+
+/** The plain-text responder every demo server shares (exported for the dev generation server). */
+export function send(res, method, status, body, headers = {}) {
+  const bytes = Buffer.isBuffer(body) ? body : Buffer.from(body);
+  res.writeHead(status, {
+    ...COMMON_HEADERS,
+    'Content-Type': 'text/plain; charset=utf-8',
+    'Content-Length': String(bytes.byteLength),
+    ...headers,
+  });
+  if (method === 'HEAD') res.end();
+  else res.end(bytes);
+}
+
+function notFound(res, method) {
+  send(res, method, 404, 'not found\n');
+}
+
+// Containment is decided in one canonical space. Each root is realpath'd
+// once and cached (roots are stable for a server's life), so a root that
+// merely sits behind a symlink — macOS hands every temp directory out as
+// /var → /private/var — still contains its realpath'd candidates. A root
+// that cannot be realpath'd at all answers 404, never a throw.
+const CANONICAL_ROOT_CACHE_LIMIT = 256;
+const canonicalRoots = new Map();
+
+/** The canonical spelling of one served root, or null when it cannot be
+ * realpath'd (the request then answers 404). */
+function canonicalRoot(root) {
+  let cached = canonicalRoots.get(root);
+  if (cached === undefined) {
+    cached = realpath(root).catch(() => null);
+    if (canonicalRoots.size >= CANONICAL_ROOT_CACHE_LIMIT) canonicalRoots.clear();
+    canonicalRoots.set(root, cached);
+  }
+  return cached;
+}
+
+/** Resolve segments under one root, refusing escapes after canonicalization:
+ * both the lexical pre-check and the post-realpath check compare against the
+ * root's canonical spelling. */
+export async function inside(root, relativeSegments) {
+  const base = await canonicalRoot(root);
+  if (base === null) return null;
+  const candidate = resolve(base, ...relativeSegments);
+  if (candidate !== base && !candidate.startsWith(`${base}${sep}`)) return null;
+  let real;
+  try {
+    real = await realpath(candidate);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+  if (real !== base && !real.startsWith(`${base}${sep}`)) return null;
+  return real;
+}
+
+/** realpath one required root or answer the named server error. */
+export async function requireRoot(root, code, message, remedy) {
+  try {
+    return await realpath(root);
+  } catch {
+    throw serverError(code, message, remedy);
+  }
+}
+
+/**
+ * @param {{
+ *   projectRoot: string,
+ *   runtimeRoot: string,
+ *   seconds: number,
+ *   host?: string,
+ *   port?: number,
+ *   pageRoot?: string,
+ *   appLibRoot?: string,
+ *   appAdaptersRoot?: string,
+ *   examplesRoot?: string,
+ * }} options
+ */
+export async function startServer({
+  projectRoot,
+  runtimeRoot,
+  seconds,
+  soundtrack,
+  host = '127.0.0.1',
+  port = 0,
+  pageRoot = join(PKG_ROOT, 'player'),
+  appLibRoot = join(PKG_ROOT, 'lib'),
+  appAdaptersRoot = join(PKG_ROOT, 'adapters'),
+  examplesRoot = join(PKG_ROOT, 'hello'),
+}) {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds <= 0) {
+    throw serverError(
+      'missing_seconds',
+      'the server needs the host show length from --seconds',
+      'Pass the host show length, for example: node demo/show.mjs <folder> --seconds 8',
+    );
+  }
+
+  const projectReal = await requireRoot(
+    projectRoot,
+    'missing_project_root',
+    `the project folder does not exist: ${projectRoot}`,
+    'Pass the folder that holds program.sjon, timeline.piece.sjon and one of soundtrack.wav, soundtrack.ogg, soundtrack.opus.',
+  );
+  const runtimeReal = await requireRoot(
+    runtimeRoot,
+    'runtime_missing',
+    'the prepared runtime bundle is missing',
+    'Run the one-time prepare: node demo/prepare.mjs',
+  );
+  const pageReal = await requireRoot(
+    pageRoot,
+    'page_missing',
+    'the player page folder is missing',
+    'Restore the package player folder (npm/cli/player).',
+  );
+  const appLibReal = await requireRoot(
+    appLibRoot,
+    'app_missing',
+    'the player core module folder is missing',
+    'Restore the package lib folder (npm/cli/lib).',
+  );
+  const appAdaptersReal = await requireRoot(
+    appAdaptersRoot,
+    'app_missing',
+    'the player adapter folder is missing',
+    'Restore the package adapters folder (npm/cli/adapters).',
+  );
+  const examplesReal = await requireRoot(
+    examplesRoot,
+    'examples_missing',
+    'the hello player source folder is missing',
+    'Restore the package hello player folder (npm/cli/hello); the page imports its run and join modules.',
+  );
+
+  let pageHtml;
+  try {
+    pageHtml = await readFile(join(pageReal, 'index.html'));
+  } catch {
+    throw serverError('page_missing', 'the player page is missing', 'Restore the package player page (npm/cli/player/index.html).');
+  }
+  if (!isSoundtrackName(soundtrack)) {
+    throw serverError(
+      'invalid_soundtrack',
+      `the server needs the inspected soundtrack selection; got ${JSON.stringify(soundtrack ?? null)}`,
+      `Pass the selected name from the project inspection: one of ${soundtrackNamesText()}.`,
+    );
+  }
+  const configBody = `${JSON.stringify({ format: PLAYER_CONFIG_FORMATS.demo, seconds, soundtrack })}\n`;
+  const roots = {
+    project: projectReal,
+    runtime: runtimeReal,
+    player: pageReal,
+    'app-lib': appLibReal,
+    'app-adapters': appAdaptersReal,
+    examples: examplesReal,
+  };
+
+  const server = createServer((req, res) => {
+    handle(req, res).catch(() => {
+      if (!res.headersSent) send(res, req.method, 500, 'internal server error\n');
+      else res.destroy();
+    });
+  });
+
+  async function handle(req, res) {
+    const method = req.method ?? 'GET';
+    if (method !== 'GET' && method !== 'HEAD') {
+      send(res, method, 405, 'method not allowed\n', { Allow: 'GET, HEAD' });
+      return;
+    }
+    const route = resolveRequest(req.url ?? '/');
+    if (route.kind === 'page') {
+      send(res, method, 200, pageHtml, { 'Content-Type': 'text/html; charset=utf-8' });
+      return;
+    }
+    if (route.kind === 'config') {
+      send(res, method, 200, configBody, { 'Content-Type': 'application/json; charset=utf-8' });
+      return;
+    }
+    if (route.kind === 'health') {
+      send(res, method, 200, '{"status":"ok","stage":"preflight"}\n', { 'Content-Type': 'application/json; charset=utf-8' });
+      return;
+    }
+    if (route.kind === 'error') {
+      send(res, method, route.status, `${route.code}: ${route.message}\n`);
+      return;
+    }
+
+    const root = roots[route.mount];
+    if (root === undefined) {
+      notFound(res, method);
+      return;
+    }
+    const real = await inside(root, route.segments);
+    if (real === null) {
+      notFound(res, method);
+      return;
+    }
+    const info = await stat(real);
+    if (!info.isFile()) {
+      notFound(res, method);
+      return;
+    }
+    if (route.mime === null) {
+      send(res, method, 415, `unsupported_media_type: the demo has no MIME mapping for ${route.relative}\n`);
+      return;
+    }
+    const headers = {
+      ...COMMON_HEADERS,
+      'Content-Type': route.mime,
+      'Content-Length': String(info.size),
+    };
+    if (method === 'HEAD') {
+      res.writeHead(200, headers);
+      res.end();
+      return;
+    }
+    res.writeHead(200, headers);
+    const stream = createReadStream(real);
+    stream.on('error', () => {
+      if (!res.writableEnded) res.destroy();
+    });
+    stream.pipe(res);
+  }
+
+  try {
+    await new Promise((resolveListen, rejectListen) => {
+      const onError = (error) => {
+        server.off('listening', onListening);
+        rejectListen(error);
+      };
+      const onListening = () => {
+        server.off('error', onError);
+        resolveListen();
+      };
+      server.once('error', onError);
+      server.once('listening', onListening);
+      server.listen(port, host);
+    });
+  } catch (error) {
+    if (error.code === 'EADDRINUSE') {
+      throw serverError(
+        'port_in_use',
+        `port ${port} on ${host} is already in use`,
+        'Retry with --port 0 (the default) to choose a free port, or pass another --port.',
+      );
+    }
+    if (error.code === 'EACCES') {
+      throw serverError('port_denied', `the operating system refused port ${port} on ${host}`, 'Retry with --port 0 to choose an unprivileged free port.');
+    }
+    throw serverError('server_bind', `could not bind ${host}:${port}: ${error.message}`, 'Retry with --port 0, or inspect the address family and permissions.');
+  }
+
+  const address = server.address();
+  const actualPort = typeof address === 'object' && address !== null ? address.port : port;
+  let closed = false;
+  async function close() {
+    if (closed) return;
+    closed = true;
+    const done = new Promise((resolveClose) => server.close(resolveClose));
+    server.closeAllConnections?.();
+    await done;
+  }
+
+  return { url: `http://${host}:${actualPort}/`, host, port: actualPort, server, close };
+}

package/adapters/launch.mjs

@@ -0,0 +1,83 @@
+// Chromium launch adapter. It spawns a browser with the URL as an argv entry,
+// detached and without a shell. It never reports a successful launch when the
+// executable could not start; the caller prints the URL so the show remains
+// reachable by hand.
+//
+// Platform-aware (plan section 5): darwin launches the Chromium-family
+// application bundles directly — the executable inside the .app, never a
+// shell helper — and falls back to the system `open` launcher last; every
+// other platform keeps the existing PATH candidate behaviour, and the
+// explicit ANIMADER_CHROMIUM override wins everywhere for contributors. No
+// browser is installed or bundled, and a spawn proves nothing about WebGPU:
+// the page is the diagnostic that earns READY.
+
+import { spawn as nodeSpawn } from 'node:child_process';
+
+export const CHROMIUM_CANDIDATES = Object.freeze([
+  'chromium',
+  'chromium-browser',
+  'google-chrome',
+  'google-chrome-stable',
+]);
+
+/**
+ * The darwin candidates, in order: the Chromium-family application bundles
+ * launched directly (no shell), then the system default-browser launcher.
+ */
+export const DARWIN_BROWSER_CANDIDATES = Object.freeze([
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  'open',
+]);
+
+/** The candidate list one platform tries, before any explicit override. */
+export function browserCandidates(platform = process.platform) {
+  return platform === 'darwin' ? DARWIN_BROWSER_CANDIDATES : CHROMIUM_CANDIDATES;
+}
+
+function loopback(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === 'http:' && (parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} url
+ * @param {{spawnImpl?: Function, env?: Object, candidates?: string[], platform?: string}} [options]
+ * @returns {Promise<{ok: true, command: string}|{ok: false, reason: string}>}
+ */
+export async function launchBrowser(url, {
+  spawnImpl = nodeSpawn,
+  env = process.env,
+  candidates = null,
+  platform = process.platform,
+} = {}) {
+  if (!loopback(url)) {
+    return { ok: false, reason: 'refusing to launch a non-loopback URL' };
+  }
+  const list = typeof env.ANIMADER_CHROMIUM === 'string' && env.ANIMADER_CHROMIUM !== ''
+    ? [env.ANIMADER_CHROMIUM]
+    : (candidates ?? browserCandidates(platform));
+  const failures = [];
+  for (const command of list) {
+    try {
+      const child = spawnImpl(command, [url], { detached: true, stdio: 'ignore' });
+      await new Promise((resolve, reject) => {
+        child.once('spawn', resolve);
+        child.once('error', reject);
+      });
+      child.unref();
+      return { ok: true, command };
+    } catch (error) {
+      failures.push(`${command}: ${error?.message ?? String(error)}`);
+    }
+  }
+  return {
+    ok: false,
+    reason: failures.length > 0 ? failures.join('; ') : 'no Chromium executable found',
+  };
+}