videobook 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to the `videobook` npm package are documented here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the package uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-19
+
+### Added
+
+- `videobook` command-line interface: `serve` runs the MCP server with the
+  bundled web UI (or `--headless` for MCP and API only), `mcp` serves MCP over
+  stdio for agent hosts, `run` and `tools` call MCP tools from the shell,
+  `gc-books` reclaims catalog storage, and `doctor` checks the local
+  environment.
+- Installed data defaults to `~/.videobook`, overridable with `VIDEOBOOK_HOME`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justin Tanner
+
+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.

package/README.md

@@ -1,3 +1,134 @@
-# Temporary Holding Version
+# videobook
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Videobook is a local-first notebook studio for generative media: images,
+videos, audio, prompts, characters and scenes live as cells in an executable
+graph, and every change is recorded as a revision. This package installs one
+`videobook` command that runs the Videobook MCP server three ways:
+
+- with the web UI at `http://127.0.0.1:3001/`
+- headless, serving MCP and the HTTP API only
+- over stdio, for agent hosts such as Claude Code
+
+## Requirements
+
+- Node.js 22 or newer.
+- macOS (Apple Silicon or Intel) or Linux (x64 or arm64). Windows x64 has
+  every native binary but is untested.
+- About 1.2 GB of disk. Installing downloads the ffmpeg and yt-dlp binaries
+  from GitHub, and the first video render downloads Chrome Headless Shell
+  (about 150 MB) into `~/.cache/videobook/remotion`.
+- `ffmpeg` and `ffprobe` on `PATH` are recommended. Apple Silicon and Linux
+  arm64 always use the system `ffprobe`, and every platform falls back to the
+  system binaries when the bundled ones are missing.
+
+## Install
+
+```bash
+npm install -g videobook
+videobook doctor
+```
+
+npm 12 and newer skip dependency install scripts unless you approve them.
+Approve the six that videobook needs, either per install or once for your
+user:
+
+```bash
+npm install -g videobook --allow-scripts=ffmpeg-static,ytdlp-nodejs,@dolthub/doltlite,usearch,onnxruntime-node,esbuild
+npm config set allow-scripts=ffmpeg-static,ytdlp-nodejs,@dolthub/doltlite,usearch,onnxruntime-node,esbuild --location=user
+```
+
+- `ffmpeg-static` downloads ffmpeg, which every media operation needs.
+- `ytdlp-nodejs` downloads yt-dlp, which downloading videos from URLs needs.
+- `@dolthub/doltlite`, `usearch` and `onnxruntime-node` use prebuilt native
+  binaries and only compile or fetch extras on unusual platforms.
+- `esbuild` checks its platform binary for the Remotion renderer.
+
+`videobook doctor` reports anything missing and prints the fix.
+
+## Run
+
+```bash
+videobook                      # same as videobook serve
+videobook serve --open         # serve MCP and the web UI, open a browser
+videobook serve --headless     # MCP and HTTP API only
+videobook mcp                  # MCP over stdio for agent hosts
+videobook run list_books       # call one MCP tool and print its result
+videobook run create_book name=demo
+videobook tools                # list tools and their parameters
+videobook gc-books             # reclaim catalog storage in every book
+videobook doctor               # check Node, binaries, native modules and keys
+videobook --version
+```
+
+Every command accepts `--port <n>` (default 3001), `--library <dir>`,
+`--home <dir>` and `--log-level <silent|error|warn|info|debug>`. Tool
+arguments are `key=value`; values that parse as JSON are passed as JSON. Exit
+codes are 0 for success, 1 for a failure and 2 for a usage error.
+
+## Agent hosts
+
+```bash
+claude mcp add videobook -- videobook mcp
+```
+
+Other hosts take the same command, for example
+`{ "command": "videobook", "args": ["mcp"] }`. stdio accepts clients that
+start with the 2025-era `initialize` and clients that use MCP 2026-07-28.
+While `videobook serve` runs, HTTP clients can connect to
+`http://127.0.0.1:3001/mcp`, which speaks MCP 2026-07-28 only.
+
+## One server per library
+
+A library is owned by one videobook process at a time, recorded in
+`<library>/.videobook-server.json`. A second `videobook serve` for the same
+library exits and names the running URL. `videobook mcp` and `videobook run`
+relay to the running server when there is one; otherwise they start one in
+their own process, which `videobook mcp` keeps serving HTTP and the web UI
+for as long as the agent host keeps it open. `videobook gc-books` refuses to
+run while a server owns the library.
+
+## Data and configuration
+
+Installed data lives in `~/.videobook`:
+
+- `books/`, the library of books
+- `app-state.json`, connected X and Dropbox accounts
+- `.env`, provider keys, also editable from Settings in the web UI
+
+`VIDEOBOOK_HOME` or `--home` moves all three. `VIDEOBOOK_LIBRARY_DIR`,
+`VIDEOBOOK_APP_STATE_PATH` and `VIDEOBOOK_ENV_PATH` move one each; `--home`
+overrides any of them inherited from your shell. Set `VIDEOBOOK_HOME` and
+`VIDEOBOOK_ENV_PATH` in the environment, not in `.env`, because they decide
+which `.env` is read.
+
+Provider keys: `OPENAI_API_KEY`, `KIE_API_KEY`, `XAI_API_KEY`, `FAL_API_KEY`,
+`DASHSCOPE_API_KEY`, `ELEVENLABS_API_KEY`, `KIMI_CODING_API_KEY`,
+`X_CLIENT_ID` and `X_CLIENT_SECRET`, `DROPBOX_CLIENT_ID` and
+`DROPBOX_CLIENT_SECRET`, and the `B2_*` storage settings. The server starts
+without any of them; tools that need one report which.
+
+Caches live in `~/.cache/videobook`. Other settings: `PORT`,
+`VIDEOBOOK_FFMPEG_PATH`, `VIDEOBOOK_FFPROBE_PATH`,
+`VIDEOBOOK_REMOTION_CACHE_DIR`, `VIDEOBOOK_MODEL_CACHE_DIR`,
+`VIDEOBOOK_DOWNLOADS_DIR` and `VIDEOBOOK_LOG_LEVEL`.
+
+## Platform notes
+
+- macOS on Apple Silicon is the primary platform. The bundled ffprobe is an
+  Intel build, so install `ffprobe` with `brew install ffmpeg`.
+- macOS on Intel works, but ONNX Runtime has no Intel Mac build, so semantic
+  search is unavailable there.
+- Linux x64 is supported. Linux arm64 needs `ffprobe` from the system package
+  manager.
+- Windows x64 is untested.
+
+## Security
+
+Videobook is a local, single-user service. It listens on `127.0.0.1` only and
+accepts requests from loopback hosts and origins. It has no user
+authentication, so do not expose it to other machines or share it between
+users.
+
+## License
+
+MIT

package/bin/videobook.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+const major = Number(process.versions.node.split(".")[0]);
+if (major < 22) {
+  process.stderr.write(`videobook needs Node.js 22 or newer; this is ${process.version}.\nInstall Node.js 22+ from https://nodejs.org or your version manager, then run videobook again.\n`);
+  process.exit(1);
+}
+await import(new URL("../dist/cli/entry.js", import.meta.url).href);

package/dist/acestep/client.js

@@ -0,0 +1,203 @@
+import { readFile } from "node:fs/promises";
+import { AceStepError } from "./errors.js";
+// The live ace-server job flow (tools/ace-server.cpp, verified against version
+// 9761469): POST /synth returns {"id"} immediately, a FIFO worker thread runs
+// the GPU job, GET /job?id reports running|done|failed|cancelled, GET
+// /job?id&result=1 serves the multipart/mixed body (fixed boundary
+// "ace-batch-boundary": one audio part plus one latent part per track), and
+// POST /job?id&cancel=1 cancels a running job. Completed jobs are evicted FIFO
+// past 32, so the result is fetched immediately after the poll reports done.
+const DEFAULT_SYNTH_TIMEOUT_MS = 30 * 60_000;
+const DEFAULT_POLL_INTERVAL_MS = 3_000;
+const SUBMIT_TIMEOUT_MS = 60_000;
+const POLL_TIMEOUT_MS = 5_000;
+const RESULT_TIMEOUT_MS = 120_000;
+const ERROR_BODY_PREVIEW_CHARS = 500;
+export async function isHealthy(baseUrl, timeoutMs = 500) {
+    try {
+        const response = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(timeoutMs) });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+function wireRequest(request) {
+    return {
+        caption: request.caption,
+        lyrics: request.lyrics,
+        task_type: request.taskType,
+        output_format: request.outputFormat,
+        seed: request.seed,
+        inference_steps: request.inferenceSteps,
+        audio_cover_strength: request.audioCoverStrength,
+        synth_batch_size: request.synthBatchSize,
+        synth_model: request.synthModel,
+        duration: request.duration,
+    };
+}
+function headerRecord(headerBlock) {
+    const headers = {};
+    for (const line of headerBlock.split("\r\n")) {
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        headers[line.slice(0, colon).trim().toLowerCase()] = line.slice(colon + 1).trim();
+    }
+    return headers;
+}
+export function parseMultipartMixed(body, contentType) {
+    const boundaryMatch = /boundary="?([^";]+)"?/u.exec(contentType);
+    if (boundaryMatch === null) {
+        throw new AceStepError("malformed_response", `ace-server response has no multipart boundary (content-type: "${contentType}")`);
+    }
+    const delimiter = Buffer.from(`--${boundaryMatch[1]}`);
+    const parts = [];
+    let offset = body.indexOf(delimiter);
+    while (offset !== -1) {
+        const afterDelimiter = offset + delimiter.length;
+        if (body.subarray(afterDelimiter, afterDelimiter + 2).toString("latin1") === "--")
+            break;
+        const boundaryLineEnd = body.indexOf("\r\n", afterDelimiter);
+        const headerEnd = body.indexOf("\r\n\r\n", afterDelimiter);
+        const next = headerEnd === -1 ? -1 : body.indexOf(delimiter, headerEnd + 4);
+        if (boundaryLineEnd === -1 || headerEnd === -1 || next === -1) {
+            throw new AceStepError("malformed_response", "ace-server multipart response is truncated");
+        }
+        const headerBlock = body.subarray(boundaryLineEnd + 2, headerEnd).toString("utf8");
+        let dataEnd = next;
+        if (body.subarray(dataEnd - 2, dataEnd).toString("latin1") === "\r\n")
+            dataEnd -= 2;
+        parts.push({ headers: headerRecord(headerBlock), data: body.subarray(headerEnd + 4, dataEnd) });
+        offset = next;
+    }
+    if (parts.length === 0) {
+        throw new AceStepError("malformed_response", "ace-server multipart response contained no parts");
+    }
+    return parts;
+}
+function describeFetchError(error) {
+    if (error instanceof Error) {
+        const cause = error.cause instanceof Error ? `: ${error.cause.message}` : "";
+        return `${error.message}${cause}`;
+    }
+    return String(error);
+}
+async function readErrorPreview(response) {
+    const bodyText = await response.text().catch(() => "");
+    return bodyText.slice(0, ERROR_BODY_PREVIEW_CHARS);
+}
+async function submitSynthJob(baseUrl, srcWavPath, request, signal) {
+    const sourceBytes = await readFile(srcWavPath);
+    const form = new FormData();
+    form.set("request", new Blob([JSON.stringify(wireRequest(request))], { type: "application/json" }), "request.json");
+    form.set("audio", new Blob([sourceBytes], { type: "audio/wav" }), "source.wav");
+    const response = await fetch(`${baseUrl}/synth`, { method: "POST", body: form, signal });
+    if (!response.ok) {
+        throw new AceStepError("synth_http_error", `ace-server /synth returned ${response.status}: ${await readErrorPreview(response)}`);
+    }
+    const body = (await response.json().catch(() => null));
+    if (typeof body?.id !== "string" || body.id.length === 0) {
+        throw new AceStepError("malformed_response", "ace-server /synth returned no job id");
+    }
+    return body.id;
+}
+async function readJobStatus(baseUrl, jobId) {
+    const response = await fetch(`${baseUrl}/job?id=${encodeURIComponent(jobId)}`, {
+        signal: AbortSignal.timeout(POLL_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new AceStepError("synth_http_error", `ace-server /job returned ${response.status}: ${await readErrorPreview(response)}`);
+    }
+    const body = (await response.json().catch(() => null));
+    if (typeof body?.status !== "string") {
+        throw new AceStepError("malformed_response", "ace-server /job returned no status");
+    }
+    return body.status;
+}
+async function cancelSynthJob(baseUrl, jobId) {
+    try {
+        await fetch(`${baseUrl}/job?id=${encodeURIComponent(jobId)}&cancel=1`, {
+            method: "POST",
+            signal: AbortSignal.timeout(POLL_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // Best-effort: the job also dies with the server, and an orphaned
+        // generation is discarded when its result is never fetched.
+    }
+}
+async function fetchSynthResult(baseUrl, jobId) {
+    const response = await fetch(`${baseUrl}/job?id=${encodeURIComponent(jobId)}&result=1`, {
+        signal: AbortSignal.timeout(RESULT_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        throw new AceStepError("synth_http_error", `ace-server /job result returned ${response.status}: ${await readErrorPreview(response)}`);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const body = Buffer.from(await response.arrayBuffer());
+    if (contentType.startsWith("audio/")) {
+        return { audio: body, audioContentType: contentType, latents: null };
+    }
+    const parts = parseMultipartMixed(body, contentType);
+    const audioPart = parts.find((part) => (part.headers["content-type"] ?? "").startsWith("audio/"));
+    if (audioPart === undefined) {
+        throw new AceStepError("malformed_response", "ace-server synth result contained no audio part");
+    }
+    const latentPart = parts.find((part) => (part.headers["content-type"] ?? "").startsWith("application/octet-stream"));
+    return {
+        audio: audioPart.data,
+        audioContentType: audioPart.headers["content-type"] ?? "audio/wav",
+        latents: latentPart?.data ?? null,
+    };
+}
+async function delay(ms, signal) {
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason instanceof Error ? signal.reason : new Error("Aborted"));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export async function synthCover(baseUrl, srcWavPath, request, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_SYNTH_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const deadlineSignal = AbortSignal.timeout(timeoutMs);
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, deadlineSignal])
+        : deadlineSignal;
+    let jobId = null;
+    try {
+        jobId = await submitSynthJob(baseUrl, srcWavPath, request, AbortSignal.any([signal, AbortSignal.timeout(SUBMIT_TIMEOUT_MS)]));
+        for (;;) {
+            const status = await readJobStatus(baseUrl, jobId);
+            if (status === "done")
+                return await fetchSynthResult(baseUrl, jobId);
+            if (status === "failed") {
+                throw new AceStepError("synth_failed", "ace-server reported the cover synthesis job as failed; the reason is in the [ace-step] logs above");
+            }
+            if (status === "cancelled") {
+                throw new AceStepError("synth_failed", "ace-server cancelled the cover synthesis job");
+            }
+            signal.throwIfAborted();
+            await delay(pollIntervalMs, signal);
+        }
+    }
+    catch (error) {
+        if (error instanceof AceStepError)
+            throw error;
+        if (jobId !== null && signal.aborted)
+            await cancelSynthJob(baseUrl, jobId);
+        if (options.signal?.aborted)
+            throw error;
+        if (deadlineSignal.aborted) {
+            throw new AceStepError("synth_timeout", `ace-server cover synthesis did not finish within ${timeoutMs}ms`);
+        }
+        throw new AceStepError("server_exited", `ace-server request failed: ${describeFetchError(error)}. The server may have crashed or been stopped; check [ace-step] logs.`);
+    }
+}

package/dist/acestep/config.js

@@ -0,0 +1,62 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isHealthy } from "./client.js";
+const DEFAULT_PORT = 8317;
+const DEFAULT_MODEL = "acestep-v15-turbo-Q4_K_M.gguf";
+const TEXT_ENCODER_MODEL = "Qwen3-Embedding-0.6B-Q8_0.gguf";
+const VAE_MODEL = "vae-BF16.gguf";
+const GATE_HEALTH_TIMEOUT_MS = 500;
+function acestepRoot() {
+    return join(homedir(), ".cache", "videobook", "acestep");
+}
+export function aceStepConfig() {
+    const baseUrl = process.env.VIDEOBOOK_ACESTEP_BASE_URL?.trim();
+    const parsedPort = Number.parseInt(process.env.VIDEOBOOK_ACESTEP_PORT ?? "", 10);
+    return {
+        baseUrl: baseUrl ? baseUrl.replace(/\/+$/u, "") : null,
+        serverPath: process.env.VIDEOBOOK_ACESTEP_SERVER_PATH?.trim() || join(acestepRoot(), "bin", "ace-server"),
+        modelsDir: process.env.VIDEOBOOK_ACESTEP_MODELS_DIR?.trim() || join(acestepRoot(), "models"),
+        port: Number.isFinite(parsedPort) && parsedPort > 0 ? parsedPort : DEFAULT_PORT,
+        model: process.env.VIDEOBOOK_ACESTEP_MODEL?.trim() || DEFAULT_MODEL,
+        keepLoaded: process.env.VIDEOBOOK_ACESTEP_KEEP_LOADED === "1",
+    };
+}
+function requiredModelFiles(config = aceStepConfig()) {
+    return [config.model, TEXT_ENCODER_MODEL, VAE_MODEL];
+}
+export function checkLocalAvailability(config = aceStepConfig()) {
+    if (!existsSync(config.serverPath)) {
+        return {
+            available: false,
+            kind: "binary_missing",
+            reason: `acestep.cpp runtime is not installed: ace-server not found at ${config.serverPath}. ` +
+                `Run "npm run install:acestep", or set VIDEOBOOK_ACESTEP_SERVER_PATH / VIDEOBOOK_ACESTEP_BASE_URL.`,
+        };
+    }
+    const missing = requiredModelFiles(config).filter((name) => !existsSync(join(config.modelsDir, name)));
+    if (missing.length > 0) {
+        return {
+            available: false,
+            kind: "models_missing",
+            reason: `ACE-Step models missing from ${config.modelsDir}: ${missing.join(", ")}. Run "npm run install:acestep".`,
+        };
+    }
+    return { available: true };
+}
+export async function checkAceStepAvailability() {
+    const config = aceStepConfig();
+    if (config.baseUrl !== null) {
+        const healthy = await isHealthy(config.baseUrl, GATE_HEALTH_TIMEOUT_MS);
+        if (!healthy) {
+            return {
+                available: false,
+                kind: "unreachable",
+                reason: `ace-server at ${config.baseUrl} did not answer /health within ${GATE_HEALTH_TIMEOUT_MS}ms ` +
+                    `(VIDEOBOOK_ACESTEP_BASE_URL). Start it or unset the variable.`,
+            };
+        }
+        return { available: true };
+    }
+    return checkLocalAvailability(config);
+}

package/dist/acestep/errors.js

@@ -0,0 +1,8 @@
+export class AceStepError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.name = "AceStepError";
+        this.kind = kind;
+    }
+}

package/dist/acestep/process.js

@@ -0,0 +1,175 @@
+import { spawn } from "node:child_process";
+import { isHealthy } from "./client.js";
+import { aceStepConfig, checkLocalAvailability } from "./config.js";
+import { logger } from "../logger.js";
+import { AceStepError } from "./errors.js";
+const state = {
+    child: null,
+    handle: null,
+    starting: null,
+    spawnFailure: null,
+    lock: Promise.resolve(),
+};
+const HEALTH_POLL_INTERVAL_MS = 500;
+const HEALTH_POLL_TIMEOUT_MS = 30_000;
+const PROBE_TIMEOUT_MS = 700;
+const EXTERNAL_HEALTH_ATTEMPTS = 3;
+const STOP_GRACE_MS = 2_000;
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+function drainOutput(stream) {
+    if (stream === null)
+        return;
+    stream.resume();
+}
+// Identity check before adopting a listener on our port: /health must return the
+// documented {"status":"ok"} shape and /props must serve JSON, so we never treat
+// an unrelated local service as ace-server.
+async function probeAceServer(baseUrl) {
+    try {
+        const health = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        if (!health.ok)
+            return false;
+        const healthBody = (await health.json());
+        if (healthBody?.status !== "ok")
+            return false;
+        const props = await fetch(`${baseUrl}/props`, { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) });
+        if (!props.ok)
+            return false;
+        const propsBody = await props.json();
+        return typeof propsBody === "object" && propsBody !== null;
+    }
+    catch {
+        return false;
+    }
+}
+async function startServer(config, signal) {
+    const baseUrl = `http://127.0.0.1:${config.port}`;
+    if (await probeAceServer(baseUrl)) {
+        const adopted = { baseUrl, owned: false };
+        state.handle = adopted;
+        return adopted;
+    }
+    const availability = checkLocalAvailability(config);
+    if (!availability.available) {
+        throw new AceStepError(availability.kind === "models_missing" ? "models_missing" : "binary_missing", availability.reason);
+    }
+    const serverArgs = [
+        "--models",
+        config.modelsDir,
+        "--host",
+        "127.0.0.1",
+        "--port",
+        String(config.port),
+    ];
+    if (config.keepLoaded)
+        serverArgs.push("--keep-loaded");
+    const child = spawn(config.serverPath, serverArgs, { stdio: ["ignore", "pipe", "pipe"] });
+    drainOutput(child.stdout);
+    drainOutput(child.stderr);
+    state.child = child;
+    state.spawnFailure = null;
+    child.on("error", (error) => {
+        state.spawnFailure = new AceStepError("spawn_failed", `Failed to start ace-server at ${config.serverPath}: ${error.message}`);
+    });
+    child.on("exit", (code, exitSignal) => {
+        logger.error("ace-server-exited", { exitCode: code, signal: exitSignal });
+        if (state.child === child) {
+            state.child = null;
+            state.handle = null;
+        }
+    });
+    const deadline = Date.now() + HEALTH_POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        if (signal?.aborted) {
+            child.kill("SIGKILL");
+            state.child = null;
+            signal.throwIfAborted();
+        }
+        if (state.spawnFailure !== null)
+            throw state.spawnFailure;
+        if (child.exitCode !== null) {
+            throw new AceStepError("spawn_failed", `ace-server exited during startup (code ${child.exitCode}); run the configured server directly to inspect its output`);
+        }
+        if (await isHealthy(baseUrl, PROBE_TIMEOUT_MS)) {
+            const owned = { baseUrl, owned: true };
+            state.handle = owned;
+            return owned;
+        }
+        await delay(HEALTH_POLL_INTERVAL_MS);
+    }
+    child.kill("SIGKILL");
+    state.child = null;
+    throw new AceStepError("health_timeout", `ace-server did not become healthy on ${baseUrl} within ${HEALTH_POLL_TIMEOUT_MS}ms`);
+}
+export async function ensureAceServer(options = {}) {
+    const config = aceStepConfig();
+    if (config.baseUrl !== null) {
+        for (let attempt = 0; attempt < EXTERNAL_HEALTH_ATTEMPTS; attempt += 1) {
+            if (await probeAceServer(config.baseUrl))
+                return { baseUrl: config.baseUrl, owned: false };
+            if (attempt < EXTERNAL_HEALTH_ATTEMPTS - 1)
+                await delay(PROBE_TIMEOUT_MS);
+        }
+        throw new AceStepError("unreachable", `ace-server at ${config.baseUrl} is not responding (VIDEOBOOK_ACESTEP_BASE_URL). Start it or unset the variable.`);
+    }
+    if (state.handle !== null && (await isHealthy(state.handle.baseUrl, PROBE_TIMEOUT_MS))) {
+        return state.handle;
+    }
+    if (state.starting !== null)
+        return state.starting;
+    state.starting = startServer(config, options.signal);
+    try {
+        return await state.starting;
+    }
+    finally {
+        state.starting = null;
+    }
+}
+// ace-server runs one GPU job at a time on a FIFO worker thread and evicts
+// completed jobs past a small cap while holding every result in memory, so we
+// keep at most one videobook synthesis in flight: queued covers wait here
+// instead of piling result buffers onto the server.
+export async function withSynthLock(fn) {
+    const previous = state.lock;
+    let release;
+    state.lock = new Promise((resolve) => {
+        release = resolve;
+    });
+    await previous;
+    try {
+        return await fn();
+    }
+    finally {
+        release?.();
+    }
+}
+export async function stopAceServer() {
+    const child = state.child;
+    state.child = null;
+    state.handle = null;
+    state.starting = null;
+    if (child === null || child.exitCode !== null)
+        return;
+    const exited = new Promise((resolve) => {
+        child.once("exit", () => resolve());
+    });
+    child.kill("SIGTERM");
+    const outcome = await Promise.race([
+        exited.then(() => "exited"),
+        delay(STOP_GRACE_MS).then(() => "timeout"),
+    ]);
+    if (outcome === "timeout") {
+        child.kill("SIGKILL");
+        await exited;
+    }
+}
+export function resetAceStepForTests() {
+    state.child?.kill("SIGKILL");
+    state.child = null;
+    state.handle = null;
+    state.starting = null;
+    state.spawnFailure = null;
+    state.lock = Promise.resolve();
+}