@open-press/core 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 quan0715
+
+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 OF OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @open-press/core
+
+Framework runtime, CLI engine, and page primitives for [open-press](https://github.com/quan0715/open-press) — an AI-first fixed-layout document workspace.
+
+Most users do **not** install this package directly. Instead, scaffold a workspace with the CLI:
+
+```bash
+npx @open-press/cli init my-doc --pack editorial-monograph
+```
+
+The scaffolded workspace contains a snapshot of this package.
+
+## Direct use
+
+If you want the runtime primitives in an existing project:
+
+```bash
+npm install @open-press/core
+```
+
+```tsx
+import {
+  BasePage,
+  BaseCoverPage,
+  BaseTocPage,
+  BaseBackCoverPage,
+  BaseFigure,
+  BaseCallout,
+} from "@open-press/core";
+```
+
+The CLI bin (`open-press`) supports dev / build / preview / validate / pdf / deploy / export commands. It requires a workspace with `openpress.config.mjs` and the surrounding framework files (which the scaffolder installs).
+
+## License
+
+MIT — see [LICENSE](https://github.com/quan0715/open-press/blob/main/LICENSE).

package/engine/chrome-pdf.d.mts

@@ -0,0 +1,34 @@
+import type { ChildProcess } from "node:child_process";
+
+export interface ChromeDevToolsClient {
+  send(method: string, params?: Record<string, unknown>): Promise<any>;
+  close(): void;
+}
+
+export interface PrintUrlToPdfOptions {
+  root: string;
+  url: string;
+  outPath: string;
+  chrome?: string;
+  waitForReady?: (client: ChromeDevToolsClient) => Promise<unknown>;
+  printOptions?: Record<string, unknown>;
+  debuggingPortBase?: number;
+  debuggingPortRange?: number;
+  profilePrefix?: string;
+}
+
+export interface EvaluateUrlWithChromeOptions {
+  root: string;
+  url: string;
+  chrome?: string;
+  evaluate: (client: ChromeDevToolsClient) => Promise<unknown>;
+  emulatedMedia?: "screen" | "print" | "none";
+  debuggingPortBase?: number;
+  debuggingPortRange?: number;
+  profilePrefix?: string;
+}
+
+export function printUrlToPdf(options: PrintUrlToPdfOptions): Promise<unknown>;
+export function evaluateUrlWithChrome(options: EvaluateUrlWithChromeOptions): Promise<unknown>;
+export function waitForPrintReady(client: ChromeDevToolsClient): Promise<number>;
+export function stopChildProcess(child: ChildProcess): Promise<void>;

package/engine/chrome-pdf.mjs

@@ -0,0 +1,344 @@
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const CHROME_CANDIDATE_PATHS = {
+  darwin: [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+  ],
+  linux: [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/snap/bin/chromium",
+    "/opt/google/chrome/chrome",
+  ],
+  win32: [
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+  ],
+};
+
+const CHROME_BIN_NAMES = {
+  darwin: [],
+  linux: ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"],
+  win32: ["chrome.exe"],
+};
+
+let cachedChromePath = null;
+
+function resolveChromePath() {
+  if (cachedChromePath) return cachedChromePath;
+  if (process.env.CHROME) {
+    cachedChromePath = process.env.CHROME;
+    return cachedChromePath;
+  }
+
+  const platform = process.platform;
+  const candidates = [...(CHROME_CANDIDATE_PATHS[platform] ?? [])];
+
+  if (platform === "win32") {
+    const roots = [process.env.PROGRAMFILES, process.env["PROGRAMFILES(X86)"], process.env.LOCALAPPDATA].filter(Boolean);
+    for (const root of roots) {
+      candidates.push(`${root}\\Google\\Chrome\\Application\\chrome.exe`);
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      cachedChromePath = candidate;
+      return cachedChromePath;
+    }
+  }
+
+  const whichCommand = platform === "win32" ? "where" : "which";
+  for (const name of CHROME_BIN_NAMES[platform] ?? []) {
+    try {
+      const result = spawnSync(whichCommand, [name], { encoding: "utf8" });
+      const output = result.stdout?.trim().split(/\r?\n/)[0];
+      if (result.status === 0 && output && existsSync(output)) {
+        cachedChromePath = output;
+        return cachedChromePath;
+      }
+    } catch {
+      // continue
+    }
+  }
+
+  const lines = [
+    `Cannot locate a Chrome / Chromium executable on ${platform}.`,
+    `Set the CHROME environment variable to your Chrome binary path, or install Chrome at one of:`,
+    ...candidates.map((p) => `  - ${p}`),
+  ];
+  throw new Error(lines.join("\n"));
+}
+
+const DEFAULT_PRINT_OPTIONS = {
+  printBackground: true,
+  displayHeaderFooter: false,
+  preferCSSPageSize: true,
+  paperWidth: 8.2677,
+  paperHeight: 11.6929,
+  marginTop: 0,
+  marginRight: 0,
+  marginBottom: 0,
+  marginLeft: 0,
+};
+
+export async function printUrlToPdf({
+  root,
+  url,
+  outPath,
+  chrome,
+  waitForReady = waitForPrintReady,
+  printOptions = {},
+  debuggingPortBase = 9600,
+  debuggingPortRange = 300,
+  profilePrefix = "chrome-pdf",
+}) {
+  chrome ??= resolveChromePath();
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+
+  const debuggingPort = String(debuggingPortBase + Math.floor(Math.random() * debuggingPortRange));
+  const profileDir = path.join(root, ".openpress", "tmp", `${profilePrefix}-${process.pid}-${Date.now()}`);
+  await fs.mkdir(profileDir, { recursive: true });
+
+  const child = spawn(
+    chrome,
+    [
+      "--headless=new",
+      "--disable-gpu",
+      "--no-sandbox",
+      `--remote-debugging-port=${debuggingPort}`,
+      `--user-data-dir=${profileDir}`,
+      "about:blank",
+    ],
+    { cwd: root, stdio: ["ignore", "pipe", "pipe"] },
+  );
+
+  try {
+    const tab = await waitForChromeTab(debuggingPort);
+    const client = await connectChromeDevTools(tab.webSocketDebuggerUrl);
+    try {
+      await client.send("Page.enable");
+      await client.send("Runtime.enable");
+      await client.send("Emulation.setEmulatedMedia", { media: "print" });
+      await client.send("Page.navigate", { url });
+      const readyResult = await waitForReady(client);
+      const result = await client.send("Page.printToPDF", {
+        ...DEFAULT_PRINT_OPTIONS,
+        ...printOptions,
+      });
+      await fs.writeFile(outPath, Buffer.from(String(result.data ?? ""), "base64"));
+      return readyResult;
+    } finally {
+      client.close();
+    }
+  } finally {
+    await stopChildProcess(child);
+    await cleanupChromeProfile(profileDir);
+  }
+}
+
+export async function evaluateUrlWithChrome({
+  root,
+  url,
+  chrome,
+  evaluate,
+  emulatedMedia,
+  debuggingPortBase = 9900,
+  debuggingPortRange = 300,
+  profilePrefix = "chrome-eval",
+}) {
+  chrome ??= resolveChromePath();
+
+  const debuggingPort = String(debuggingPortBase + Math.floor(Math.random() * debuggingPortRange));
+  const profileDir = path.join(root, ".openpress", "tmp", `${profilePrefix}-${process.pid}-${Date.now()}`);
+  await fs.mkdir(profileDir, { recursive: true });
+
+  const child = spawn(
+    chrome,
+    [
+      "--headless=new",
+      "--disable-gpu",
+      "--no-sandbox",
+      `--remote-debugging-port=${debuggingPort}`,
+      `--user-data-dir=${profileDir}`,
+      "about:blank",
+    ],
+    { cwd: root, stdio: ["ignore", "pipe", "pipe"] },
+  );
+
+  try {
+    const tab = await waitForChromeTab(debuggingPort);
+    const client = await connectChromeDevTools(tab.webSocketDebuggerUrl);
+    try {
+      await client.send("Page.enable");
+      await client.send("Runtime.enable");
+      if (emulatedMedia) {
+        await client.send("Emulation.setEmulatedMedia", { media: emulatedMedia });
+      }
+      await client.send("Page.navigate", { url });
+      return await evaluate(client);
+    } finally {
+      client.close();
+    }
+  } finally {
+    await stopChildProcess(child);
+    await cleanupChromeProfile(profileDir);
+  }
+}
+
+export async function waitForPrintReady(client) {
+  const deadline = Date.now() + 30000;
+  while (Date.now() < deadline) {
+    const result = await client.send("Runtime.evaluate", {
+      returnByValue: true,
+      awaitPromise: true,
+      expression: `Promise.resolve().then(async () => {
+        const root = document.querySelector('[data-openpress-print-document="true"]');
+        const ready = root?.getAttribute('data-openpress-pagination') === 'ready';
+        if (!ready) return 0;
+
+        await document.fonts?.ready;
+        await Promise.all(Array.from(document.images).map(async (img) => {
+          if (!img.complete) {
+            await new Promise((resolve) => {
+              const settle = () => {
+                img.removeEventListener('load', settle);
+                img.removeEventListener('error', settle);
+                resolve();
+              };
+
+              img.addEventListener('load', settle, { once: true });
+              img.addEventListener('error', settle, { once: true });
+            });
+          }
+
+          await img.decode?.().catch(() => undefined);
+        }));
+
+        await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+
+        const pages = Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page'));
+        const contentFitsPageBody = (body) => {
+          const bodyBottom = body.getBoundingClientRect().bottom;
+          const contentBottom = Array.from(body.children).reduce((bottom, child) => {
+            if (getComputedStyle(child).display === 'none') return bottom;
+            const marginBottom = Number.parseFloat(getComputedStyle(child).marginBottom) || 0;
+            return Math.max(bottom, child.getBoundingClientRect().bottom + marginBottom);
+          }, body.getBoundingClientRect().top);
+          return contentBottom <= bodyBottom + 1;
+        };
+        const bodyOverflowSafe = pages.every((page) => {
+          const body = page.querySelector('.page-body');
+          return !body || contentFitsPageBody(body);
+        });
+
+        return pages.length > 0 && bodyOverflowSafe ? pages.length : 0;
+      })`,
+    });
+    const count = Number(result.result?.value ?? 0);
+    if (count > 0) return count;
+    await delay(100);
+  }
+  throw new Error("Timed out waiting for OpenPress pagination before PDF export.");
+}
+
+export async function stopChildProcess(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  child.kill();
+  const closed = await waitForChildClose(child, 2500);
+  if (closed || child.exitCode !== null || child.signalCode !== null) return;
+  child.kill("SIGKILL");
+  await waitForChildClose(child, 2500);
+}
+
+async function waitForChromeTab(debuggingPort) {
+  const deadline = Date.now() + 10000;
+  let lastError;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(`http://127.0.0.1:${debuggingPort}/json/list`);
+      const tabs = await response.json();
+      const tab = tabs.find((item) => item.type === "page" && item.webSocketDebuggerUrl);
+      if (tab) return tab;
+    } catch (error) {
+      lastError = error;
+    }
+    await delay(100);
+  }
+  throw new Error(`Timed out waiting for Chrome DevTools${lastError ? `: ${lastError.message}` : ""}`);
+}
+
+async function connectChromeDevTools(webSocketDebuggerUrl) {
+  const socket = new WebSocket(webSocketDebuggerUrl);
+  const pending = new Map();
+  let nextId = 0;
+
+  await new Promise((resolve, reject) => {
+    socket.addEventListener("open", resolve, { once: true });
+    socket.addEventListener("error", reject, { once: true });
+  });
+
+  socket.addEventListener("message", (event) => {
+    const message = JSON.parse(String(event.data));
+    if (!message.id || !pending.has(message.id)) return;
+    const callbacks = pending.get(message.id);
+    pending.delete(message.id);
+    if (message.error) callbacks?.reject(new Error(message.error.message ?? "Chrome DevTools command failed."));
+    else callbacks?.resolve(message.result ?? {});
+  });
+
+  return {
+    send(method, params = {}) {
+      return new Promise((resolve, reject) => {
+        const id = ++nextId;
+        pending.set(id, { resolve, reject });
+        socket.send(JSON.stringify({ id, method, params }));
+      });
+    },
+    close() {
+      socket.close();
+    },
+  };
+}
+
+function waitForChildClose(child, timeoutMs) {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (closed) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.off("close", onClose);
+      child.off("error", onError);
+      resolve(closed);
+    };
+    const onClose = () => finish(true);
+    const onError = () => finish(true);
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    child.once("close", onClose);
+    child.once("error", onError);
+  });
+}
+
+async function cleanupChromeProfile(profileDir) {
+  try {
+    await fs.rm(profileDir, { recursive: true, force: true, maxRetries: 8, retryDelay: 150 });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`Could not remove temporary Chrome profile ${profileDir}: ${message}`);
+  }
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/engine/cli.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+import * as deployCmd from "./commands/deploy.mjs";
+import * as devCmd from "./commands/dev.mjs";
+import * as exportCmd from "./commands/export.mjs";
+import * as initCmd from "./commands/init.mjs";
+import * as inspectCmd from "./commands/inspect.mjs";
+import * as migrateToReactCmd from "./commands/migrate-to-react.mjs";
+import * as pdfCmd from "./commands/pdf.mjs";
+import * as previewCmd from "./commands/preview.mjs";
+import * as replaceCmd from "./commands/replace.mjs";
+import * as renderCmd from "./commands/render.mjs";
+import * as searchCmd from "./commands/search.mjs";
+import * as typecheckCmd from "./commands/typecheck.mjs";
+import * as validateCmd from "./commands/validate.mjs";
+import { parseOptions } from "./commands/_shared.mjs";
+import { loadConfig } from "./config.mjs";
+import { listStylePackSkills } from "./init.mjs";
+import { discoverWorkspace } from "./validation.mjs";
+
+const COMMANDS = {
+  init: initCmd,
+  "migrate-to-react": migrateToReactCmd,
+  validate: validateCmd,
+  inspect: inspectCmd,
+  search: searchCmd,
+  replace: replaceCmd,
+  export: exportCmd,
+  render: renderCmd,
+  dev: devCmd,
+  preview: previewCmd,
+  typecheck: typecheckCmd,
+  pdf: pdfCmd,
+  deploy: deployCmd,
+};
+
+const args = process.argv.slice(2);
+const command = args.shift();
+
+try {
+  const code = await main(command, args);
+  process.exitCode = code;
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
+
+async function main(commandName, argv) {
+  if (!commandName || ["-h", "--help"].includes(commandName)) {
+    await printHelp();
+    return commandName ? 0 : 2;
+  }
+
+  const handler = COMMANDS[commandName];
+  if (!handler) {
+    console.error(`Unknown command: ${commandName}`);
+    await printHelp();
+    return 2;
+  }
+
+  if (handler.needsWorkspace === false) {
+    return handler.run({ argv });
+  }
+
+  const options = parseOptions(argv);
+  const root = await discoverWorkspace(options.path ?? ".");
+  const config = await loadConfig(root);
+  return handler.run({ root, config, options, recurse: main });
+}
+
+async function printHelp() {
+  const packs = await listStylePackSkills();
+  const skillList = packs.length ? packs.join(" | ") : "(none installed)";
+  console.log(`Usage: node engine/cli.mjs <command> [path] [options]
+
+Commands:
+  init <target> [--skill <name>] [--force]
+  migrate-to-react [path] [--dry-run] [--force] [--json]
+  validate
+  inspect [--json] [--no-build] [--dry-run]
+  search [path] <query> [--json] [--scope content|all]
+  replace [path] <from> <to> [--json] [--apply] [--scope content|all]
+  export
+  render --renderer react [--dry-run]
+  preview --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
+  dev --renderer react [--host 127.0.0.1] [--port 5173] [--no-build] [--dry-run]
+  typecheck
+  pdf [--output <outputDir>/<pdf.filename>] [--no-build] [--dry-run]
+  deploy --confirm [--dry-run]
+
+Style packs available for \`init --skill\`: ${skillList}
+`);
+}

package/engine/commands/_shared.mjs

@@ -0,0 +1,170 @@
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { printUrlToPdf, stopChildProcess, waitForPrintReady } from "../chrome-pdf.mjs";
+import { loadConfig, publicPdfHref } from "../config.mjs";
+import { exportDocument } from "../document-export.mjs";
+import { optimizePdfMediaForStaticRoot } from "../pdf-media.mjs";
+
+const ENGINE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const STATIC_SERVER = path.join(ENGINE_DIR, "static-server.mjs");
+
+export function parseOptions(argv) {
+  const options = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (value === "--renderer") options.renderer = argv[++i];
+    else if (value === "--host") options.host = argv[++i];
+    else if (value === "--port") options.port = argv[++i];
+    else if (value === "--dry-run") options.dryRun = true;
+    else if (value === "--force") options.force = true;
+    else if (value === "--confirm") options.confirm = true;
+    else if (value === "--json") options.json = true;
+    else if (value === "--no-build") options.noBuild = true;
+    else if (value === "--apply") options.apply = true;
+    else if (value === "--include-code") options.includeCode = true;
+    else if (value === "--case-sensitive") options.caseSensitive = true;
+    else if (value === "--scope") options.scope = argv[++i];
+    else if (value === "--source") options.source = argv[++i];
+    else if (value === "--output") options.output = argv[++i];
+    else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
+    else positional.push(value);
+  }
+  options.path = positional[0];
+  options.positional = positional;
+  return options;
+}
+
+export function parseInitOptions(argv) {
+  const options = { force: false };
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (value === "--skill") options.skill = argv[++i];
+    else if (value === "--force") options.force = true;
+    else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
+    else positional.push(value);
+  }
+  options.target = positional[0];
+  return options;
+}
+
+export function formatDisplayPath(absolutePath) {
+  const relative = path.relative(process.cwd(), absolutePath);
+  if (!relative || relative.startsWith("..")) return absolutePath;
+  return relative;
+}
+
+export function runCommand(commandName, commandArgs, cwd) {
+  const result = spawnSync(commandName, commandArgs, { cwd, stdio: "inherit" });
+  return result.status ?? 1;
+}
+
+export async function buildReactStatic({ root, noBuild = false, recurse, silent = false }) {
+  if (noBuild) return 0;
+  if (!silent) {
+    return await recurse("render", [root, "--renderer", "react"]);
+  }
+
+  await exportDocument(root);
+  const result = spawnSync("npx", ["vite", "build", "--config", "vite.config.ts"], {
+    cwd: root,
+    encoding: "utf8",
+  });
+  return result.status ?? 1;
+}
+
+export async function buildReactPdf({
+  root,
+  config,
+  outPath,
+  host = "127.0.0.1",
+  port = "5185",
+  noBuild = false,
+  recurse,
+}) {
+  config ??= await loadConfig(root);
+  outPath ??= config.paths.pdf;
+  const renderCode = await buildReactStatic({ root, noBuild, recurse });
+  if (renderCode !== 0) throw new Error(`React render failed with exit code ${renderCode}`);
+  await optimizePdfMediaForStaticRoot(config.paths.outputDir);
+  await fs.mkdir(path.dirname(outPath), { recursive: true });
+
+  const server = await startStaticServer(root, config, host, port);
+  try {
+    const pageCount = await printUrlToPdf({
+      root,
+      url: `http://${host}:${port}/?print=1`,
+      outPath,
+      waitForReady: waitForPrintReady,
+      debuggingPortBase: 9300,
+      debuggingPortRange: 600,
+      profilePrefix: "chrome-pdf",
+    });
+    console.log(`${pageCount} OpenPress pages printed to PDF`);
+  } finally {
+    await stopChildProcess(server);
+  }
+
+  return { pdfPath: outPath };
+}
+
+export function startStaticServer(root, config, host, port) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("node", [STATIC_SERVER, config.outputDir, "--host", host, "--port", port, "--workspace", "."], {
+      cwd: root,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let settled = false;
+    let stderr = "";
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      child.kill();
+      reject(new Error(`Timed out waiting for OpenPress static server on ${host}:${port}`));
+    }, 10000);
+
+    child.stdout.on("data", (chunk) => {
+      const text = String(chunk);
+      if (!settled && text.includes("OpenPress static preview:")) {
+        settled = true;
+        clearTimeout(timer);
+        resolve(child);
+      }
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      reject(new Error(`OpenPress static server exited with code ${code ?? 1}: ${stderr}`));
+    });
+  });
+}
+
+export async function writePdfStageDeployConfig(root, source, config) {
+  const deployRoot = path.resolve(root, source);
+  const openpressDir = path.join(deployRoot, "openpress");
+  await fs.mkdir(openpressDir, { recursive: true });
+  await fs.writeFile(
+    path.join(openpressDir, "deploy.json"),
+    `${JSON.stringify({ pdf: publicPdfHref(config), deployed_at: new Date().toISOString() }, null, 2)}\n`,
+    "utf8",
+  );
+  await fs.writeFile(
+    path.join(deployRoot, "_headers"),
+    `${publicPdfHref(config)}\n  Content-Type: application/pdf\n  Content-Disposition: inline; filename="${config.pdf.filename}"\n`,
+    "utf8",
+  );
+}