@open-press/core 1.1.3 → 1.2.0

package/engine/cli.mjs

@@ -85,8 +85,8 @@ Commands:
   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
-  image [--output <outputDir>] [--no-build] [--dry-run]
-  pdf [--output <outputDir>/<pdf.filename>] [--no-build] [--dry-run]
+  image [--output <outputDir>] [--press <slug>] [--pages <selector>] [--no-build] [--dry-run]
+  pdf [--output <outputDir>/<pdf.filename>] [--press <slug>] [--no-build] [--dry-run]
   deploy --confirm [--dry-run]
   doctor [--json] [--no-cache]                          # version + skill staleness check
   upgrade [--dry-run] [--no-deps] [--no-skills] [--json] # apply updates; agent-driven

package/engine/commands/_shared.mjs

@@ -40,6 +40,8 @@ export function parseOptions(argv) {
     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 === "--pages") options.pages = argv[++i];
+    else if (value === "--press") options.press = argv[++i];
     else if (value.startsWith("--")) throw new Error(`Unknown option: ${value}`);
     else positional.push(value);
   }
@@ -102,6 +104,52 @@ export async function buildReactStatic({ root, noBuild = false, recurse, silent
   return result.status ?? 1;
 }
 
+export async function resolvePressSelection({ outputDir, slug }) {
+  const manifestPath = path.join(outputDir, "openpress", "workspace.json");
+  let manifest;
+  try {
+    const body = await fs.readFile(manifestPath, "utf8");
+    manifest = JSON.parse(body);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error(
+        `Cannot resolve --press: workspace manifest not found at ${manifestPath}. ` +
+          `Run a render first (or drop --no-build) so the manifest is regenerated.`,
+      );
+    }
+    throw error;
+  }
+  const presses = Array.isArray(manifest?.presses) ? manifest.presses : [];
+  if (presses.length === 0) {
+    throw new Error(`Workspace manifest at ${manifestPath} declares no Press entries.`);
+  }
+  const knownSlugs = presses.map((press) => press.slug || "").filter(Boolean);
+  const normalized = typeof slug === "string" ? slug.trim().replace(/^\/+|\/+$/g, "") : "";
+  if (!normalized) {
+    return { slug: presses[0].slug ?? "", title: presses[0].title ?? "", knownSlugs };
+  }
+  const match = presses.find((press) => (press.slug ?? "").replace(/^\/+|\/+$/g, "") === normalized);
+  if (!match) {
+    const listed = knownSlugs.length > 0 ? knownSlugs.join(", ") : "(none — workspace has no slugged presses)";
+    throw new Error(`Unknown --press "${slug}". Known slugs: ${listed}.`);
+  }
+  return { slug: match.slug ?? "", title: match.title ?? "", knownSlugs };
+}
+
+function pressPrintUrl(host, port, slug) {
+  const normalized = (slug ?? "").replace(/^\/+|\/+$/g, "");
+  if (!normalized) return `http://${host}:${port}/?print=1`;
+  return `http://${host}:${port}/${normalized}?print=1`;
+}
+
+function pressSuffixedFilename(baseFilename, slug) {
+  const normalized = (slug ?? "").replace(/^\/+|\/+$/g, "");
+  if (!normalized) return baseFilename;
+  const ext = path.extname(baseFilename);
+  const stem = ext ? baseFilename.slice(0, -ext.length) : baseFilename;
+  return `${stem}-${normalized}${ext}`;
+}
+
 export async function buildReactPdf({
   root,
   config,
@@ -110,31 +158,44 @@ export async function buildReactPdf({
   port = "5185",
   noBuild = false,
   recurse,
+  pressSlug = null,
 }) {
   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);
+
+  const selection = pressSlug
+    ? await resolvePressSelection({ outputDir: config.paths.outputDir, slug: pressSlug })
+    : { slug: "", title: "", knownSlugs: [] };
+
+  if (!outPath) {
+    const filename = selection.slug
+      ? pressSuffixedFilename(config.pdf.filename, selection.slug)
+      : config.pdf.filename;
+    outPath = path.join(config.paths.outputDir, filename);
+  }
   await fs.mkdir(path.dirname(outPath), { recursive: true });
 
   const server = await startStaticServer(root, config, host, port);
   try {
-    const pageCount = await printUrlToPdf({
+    const result = await printUrlToPdf({
       root,
-      url: `http://${host}:${port}/?print=1`,
+      url: pressPrintUrl(host, port, selection.slug),
       outPath,
       waitForReady: waitForPrintReady,
       debuggingPortBase: 9300,
       debuggingPortRange: 600,
       profilePrefix: "chrome-pdf",
     });
-    console.log(`${pageCount} OpenPress pages printed to PDF`);
+    const pageCount = result?.pageCount ?? result;
+    const pressLabel = selection.slug ? ` (press: ${selection.title || selection.slug})` : "";
+    console.log(`${pageCount} OpenPress pages printed to PDF${pressLabel}`);
   } finally {
     await stopChildProcess(server);
   }
 
-  return { pdfPath: outPath };
+  return { pdfPath: outPath, pressSlug: selection.slug };
 }
 
 export async function buildReactImages({
@@ -145,26 +206,47 @@ export async function buildReactImages({
   port = "5186",
   noBuild = false,
   recurse,
+  pageSelector = null,
+  pressSlug = null,
 }) {
   config ??= await loadConfig(root);
-  outDir ??= path.join(config.paths.outputDir, "images");
   const renderCode = await buildReactStatic({ root, noBuild, recurse });
   if (renderCode !== 0) throw new Error(`React render failed with exit code ${renderCode}`);
+
+  const selection = pressSlug
+    ? await resolvePressSelection({ outputDir: config.paths.outputDir, slug: pressSlug })
+    : { slug: "", title: "", knownSlugs: [] };
+
+  if (!outDir) {
+    const folder = selection.slug ? `images-${selection.slug}` : "images";
+    outDir = path.join(config.paths.outputDir, folder);
+  }
   await fs.mkdir(outDir, { recursive: true });
 
   const server = await startStaticServer(root, config, host, port);
   try {
     const result = await captureUrlPagesToPng({
       root,
-      url: `http://${host}:${port}/?print=1`,
+      url: pressPrintUrl(host, port, selection.slug),
       outDir,
       waitForReady: waitForPrintReady,
       debuggingPortBase: 9700,
       debuggingPortRange: 600,
       profilePrefix: "chrome-image",
+      pageSelector,
     });
-    console.log(`${result.files.length} OpenPress pages exported to PNG`);
-    return { outDir, files: result.files, pageCount: result.pageCount };
+    const pressLabel = selection.slug ? ` (press: ${selection.title || selection.slug})` : "";
+    const countLabel = pageSelector
+      ? `${result.files.length}/${result.pageCount} OpenPress pages exported to PNG`
+      : `${result.files.length} OpenPress pages exported to PNG`;
+    console.log(`${countLabel}${pressLabel}`);
+    return {
+      outDir,
+      files: result.files,
+      pageCount: result.pageCount,
+      selectedPageNumbers: result.selectedPageNumbers,
+      pressSlug: selection.slug,
+    };
   } finally {
     await stopChildProcess(server);
   }

package/engine/commands/image.mjs

@@ -1,16 +1,27 @@
 import path from "node:path";
 import { STATIC_SERVER, buildReactImages, formatNodeScriptCommand, formatOpenPressCommand } from "./_shared.mjs";
+import { parsePageSelector } from "../runtime/page-selector.mjs";
 
 export async function run({ root, config, options, recurse }) {
-  const outputDir = options.output ? path.resolve(root, options.output) : path.join(config.paths.outputDir, "images");
+  const outputDir = options.output ? path.resolve(root, options.output) : undefined;
   const host = options.host ?? "127.0.0.1";
   const port = options.port ?? "5186";
 
+  const pageSelector = options.pages ? parsePageSelector(options.pages) : null;
+  const pressSlug = options.press ?? null;
+
   if (options.dryRun) {
+    const pressPath = pressSlug ? `/${String(pressSlug).replace(/^\/+|\/+$/g, "")}` : "";
+    const previewDir = outputDir
+      ?? path.join(config.paths.outputDir, pressSlug ? `images-${String(pressSlug).replace(/^\/+|\/+$/g, "")}` : "images");
     console.log(`Command: ${formatOpenPressCommand(["render", ".", "--renderer", "react"])}`);
     console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
-    console.log(`Chrome image export URL: http://${host}:${port}/?print=1`);
-    console.log(`Output: ${path.relative(root, path.join(outputDir, "page-001.png"))}`);
+    console.log(`Chrome image export URL: http://${host}:${port}${pressPath}/?print=1`);
+    if (pressSlug) console.log(`Press: ${pressSlug} (validated against workspace manifest at run time)`);
+    if (pageSelector) {
+      console.log(`Page selector: ${options.pages} (resolved at capture time against the rendered page count)`);
+    }
+    console.log(`Output: ${path.relative(root, path.join(previewDir, "page-001.png"))}`);
     return 0;
   }
 
@@ -22,8 +33,13 @@ export async function run({ root, config, options, recurse }) {
     port,
     noBuild: options.noBuild,
     recurse,
+    pageSelector,
+    pressSlug,
   });
 
-  console.log(`OpenPress images: ${path.relative(root, result.outDir)} (${result.files.length} pages)`);
+  const suffix = pageSelector
+    ? ` (${result.files.length}/${result.pageCount} pages)`
+    : ` (${result.files.length} pages)`;
+  console.log(`OpenPress images: ${path.relative(root, result.outDir)}${suffix}`);
   return 0;
 }

package/engine/commands/pdf.mjs

@@ -7,9 +7,11 @@ export async function run({ root, config, options, recurse }) {
     const relOutput = path.relative(root, outputPath ?? config.paths.pdf);
     const host = options.host ?? "127.0.0.1";
     const port = options.port ?? "5185";
+    const pressPath = options.press ? `/${String(options.press).replace(/^\/+|\/+$/g, "")}` : "";
     console.log(`Command: ${formatOpenPressCommand(["render", ".", "--renderer", "react"])}`);
     console.log(`Command: ${formatNodeScriptCommand(root, STATIC_SERVER)} ${config.outputDir} --host ${host} --port ${port} --workspace .`);
-    console.log(`Command: Chrome --print-to-pdf=${relOutput} http://${host}:${port}/?print=1`);
+    console.log(`Command: Chrome --print-to-pdf=${relOutput} http://${host}:${port}${pressPath}/?print=1`);
+    if (options.press) console.log(`Press: ${options.press} (validated against workspace manifest at run time)`);
     return 0;
   }
   const result = await buildReactPdf({
@@ -20,6 +22,7 @@ export async function run({ root, config, options, recurse }) {
     port: options.port,
     noBuild: options.noBuild,
     recurse,
+    pressSlug: options.press ?? null,
   });
   console.log(`OpenPress PDF: ${path.relative(root, result.pdfPath)}`);
   return 0;

package/engine/output/chrome-pdf.mjs

@@ -2,6 +2,9 @@ import { spawn, spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { resolvePageSelector } from "../runtime/page-selector.mjs";
+
+const defaultResolveSelector = resolvePageSelector;
 
 const CHROME_CANDIDATE_PATHS = {
   darwin: [
@@ -98,6 +101,100 @@ export const DEFAULT_PRINT_VIEWPORT = Object.freeze({
   mobile: false,
 });
 
+export function pageGeometryProbeExpression() {
+  return `(() => {
+    if (!document.body) return null;
+    // OpenPressRuntime sets --openpress-page-width / -height on the
+    // PrintDocument <main> via inline style. The workspace's global
+    // theme also defines a *default* --openpress-page-width on :root
+    // (e.g. 210mm for the A4 preset). If we let getComputedStyle fall
+    // back to :root we will silently return that default before the
+    // print document has even rendered — and the per-document override
+    // never gets a chance to apply. Require the actual print surface
+    // so the probe waits until React paints it instead of locking in
+    // the wrong size from the workspace stylesheet.
+    const target = document.querySelector('[data-openpress-print-document="true"]')
+      || document.querySelector('.openpress-html-page');
+    if (!target) return null;
+    const cs = getComputedStyle(target);
+    const widthStr = cs.getPropertyValue('--openpress-page-width').trim();
+    const heightStr = cs.getPropertyValue('--openpress-page-height').trim();
+    if (!widthStr || !heightStr) return null;
+    const helper = document.createElement('div');
+    helper.style.position = 'absolute';
+    helper.style.left = '-99999px';
+    helper.style.top = '-99999px';
+    helper.style.visibility = 'hidden';
+    helper.style.pointerEvents = 'none';
+    helper.style.width = widthStr;
+    helper.style.height = heightStr;
+    document.body.appendChild(helper);
+    const rect = helper.getBoundingClientRect();
+    helper.remove();
+    if (!Number.isFinite(rect.width) || !Number.isFinite(rect.height) || rect.width <= 0 || rect.height <= 0) return null;
+    return { width: rect.width, height: rect.height };
+  })()`;
+}
+
+export async function measurePageGeometryPx(client, { timeoutMs = 5000, pollIntervalMs = 50 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await client.send("Runtime.evaluate", {
+      returnByValue: true,
+      expression: pageGeometryProbeExpression(),
+    });
+    const dims = result.result?.value;
+    if (dims && Number.isFinite(dims.width) && dims.width > 0) {
+      return { width: dims.width, height: dims.height };
+    }
+    await delay(pollIntervalMs);
+  }
+  return null;
+}
+
+export async function syncViewportToPageGeometry(client, viewport, options = {}) {
+  const dims = await measurePageGeometryPx(client, options);
+  if (!dims) return { viewport, pageDimensionsPx: null };
+  const targetWidth = Math.max(viewport.width, Math.ceil(dims.width));
+  const targetHeight = Math.max(viewport.height, Math.ceil(dims.height));
+  if (targetWidth === viewport.width && targetHeight === viewport.height) {
+    return { viewport, pageDimensionsPx: dims };
+  }
+  const next = { ...viewport, width: targetWidth, height: targetHeight };
+  await client.send("Emulation.setDeviceMetricsOverride", next);
+  return { viewport: next, pageDimensionsPx: dims };
+}
+
+// Chrome's Page.printToPDF takes paperWidth / paperHeight in inches and
+// honors them when preferCSSPageSize falls through. Because our @page
+// rule reads CSS custom properties scoped to <main> instead of :root,
+// preferCSSPageSize cannot resolve the size in headless Chrome — we have
+// to pass the inches explicitly. Convert from CSS px at the 1in = 96px
+// rate the rest of the runtime already assumes.
+//
+// Wider-than-tall geometries (slide 16:9, landscape pages) also need
+// `landscape: true`: with `landscape: false` Chrome silently rotates the
+// MediaBox to portrait so the short side becomes the width, leaving the
+// content laid out for the wide canvas but cropped against the short page.
+export function pageDimensionsPxToPaperInches(dims) {
+  if (!dims || !Number.isFinite(dims.width) || dims.width <= 0) return null;
+  if (!Number.isFinite(dims.height) || dims.height <= 0) return null;
+  // Chrome's printToPDF semantics: paperWidth/paperHeight are taken as
+  // *portrait* page dimensions, and `landscape: true` then rotates the
+  // canvas 90°. So for a 1920×1080 slide we have to pass the short side
+  // as paperWidth (11.25"), the long side as paperHeight (20"), and
+  // landscape: true — Chrome will produce a 20"×11.25" landscape page
+  // whose content frame matches the original 1920×1080 layout.
+  const widthIn = dims.width / 96;
+  const heightIn = dims.height / 96;
+  const landscape = widthIn > heightIn;
+  return {
+    paperWidth: landscape ? heightIn : widthIn,
+    paperHeight: landscape ? widthIn : heightIn,
+    landscape,
+  };
+}
+
 export async function printUrlToPdf({
   root,
   url,
@@ -136,7 +233,15 @@ export async function printUrlToPdf({
     try {
       await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
+      // Widen the headless viewport when the document's page geometry is
+      // wider than the default A4 viewport, so layout uses the full page
+      // width before pagination. Paper size itself is driven by the
+      // @page rule in print-route.css, which now resolves
+      // --openpress-page-width / -height from :root (PrintDocument
+      // mirrors the per-document theme vars onto the document element).
+      await syncViewportToPageGeometry(client, viewport);
       const readyResult = await waitForReady(client);
+      warnAboutOverflowingPages("PDF", readyResult);
       const result = await client.send("Page.printToPDF", {
         ...DEFAULT_PRINT_OPTIONS,
         ...printOptions,
@@ -152,6 +257,16 @@ export async function printUrlToPdf({
   }
 }
 
+function warnAboutOverflowingPages(label, readyResult) {
+  const overflowing = Array.isArray(readyResult?.overflowingPageNumbers) ? readyResult.overflowingPageNumbers : [];
+  if (overflowing.length === 0) return;
+  const preview = overflowing.slice(0, 12).join(", ") + (overflowing.length > 12 ? `, … (+${overflowing.length - 12} more)` : "");
+  console.warn(
+    `OpenPress ${label}: ${overflowing.length} page(s) exceed the page body bounds (pages ${preview}). ` +
+    `Output will still be generated but those pages may clip; run \`openpress inspect\` to locate the overflowing elements.`,
+  );
+}
+
 export async function captureUrlPagesToPng({
   root,
   url,
@@ -162,6 +277,8 @@ export async function captureUrlPagesToPng({
   debuggingPortBase = 9700,
   debuggingPortRange = 300,
   profilePrefix = "chrome-image",
+  pageSelector = null,
+  resolveSelector = null,
 }) {
   chrome ??= resolveChromePath();
   await fs.mkdir(outDir, { recursive: true });
@@ -189,14 +306,26 @@ export async function captureUrlPagesToPng({
     try {
       await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
-      const pageCount = await waitForReady(client);
+      await syncViewportToPageGeometry(client, viewport);
+      const readyResult = await waitForReady(client);
+      warnAboutOverflowingPages("image", readyResult);
+      const pageCount = readyResult?.pageCount ?? 0;
       const rects = await getPrintPageRects(client);
       if (rects.length === 0) throw new Error("No OpenPress pages found for image export.");
 
+      const selectedPageNumbers = pageSelector
+        ? (resolveSelector ?? defaultResolveSelector)(pageSelector, rects.length)
+        : rects.map((_, index) => index + 1);
+      if (selectedPageNumbers.length === 0) {
+        throw new Error("Page selector resolved to zero pages; nothing to export.");
+      }
+
       const padWidth = Math.max(3, String(rects.length).length);
       const files = [];
-      for (const [index, rect] of rects.entries()) {
-        const filename = `page-${String(index + 1).padStart(padWidth, "0")}.png`;
+      for (const pageNumber of selectedPageNumbers) {
+        const rect = rects[pageNumber - 1];
+        if (!rect) continue;
+        const filename = `page-${String(pageNumber).padStart(padWidth, "0")}.png`;
         const filePath = path.join(outDir, filename);
         const result = await client.send("Page.captureScreenshot", {
           format: "png",
@@ -214,7 +343,7 @@ export async function captureUrlPagesToPng({
         files.push(filePath);
       }
 
-      return { pageCount, files };
+      return { pageCount, files, selectedPageNumbers };
     } finally {
       client.close();
     }
@@ -282,59 +411,135 @@ export async function evaluateUrlWithChrome({
   }
 }
 
-export async function waitForPrintReady(client) {
-  const deadline = Date.now() + 30000;
-  while (Date.now() < deadline) {
+export const PRINT_READY_DEFAULTS = Object.freeze({
+  totalTimeoutMs: 300_000,
+  idleTimeoutMs: 30_000,
+  pollIntervalMs: 100,
+  stableMs: 300,
+});
+
+export function resolvePrintReadyTiming(env = process.env) {
+  const total = Number(env.OPENPRESS_PRINT_READY_TIMEOUT_MS);
+  const idle = Number(env.OPENPRESS_PRINT_READY_IDLE_MS);
+  const stable = Number(env.OPENPRESS_PRINT_READY_STABLE_MS);
+  return {
+    totalTimeoutMs: Number.isFinite(total) && total > 0 ? total : PRINT_READY_DEFAULTS.totalTimeoutMs,
+    idleTimeoutMs: Number.isFinite(idle) && idle > 0 ? idle : PRINT_READY_DEFAULTS.idleTimeoutMs,
+    stableMs: Number.isFinite(stable) && stable >= 0 ? stable : PRINT_READY_DEFAULTS.stableMs,
+    pollIntervalMs: PRINT_READY_DEFAULTS.pollIntervalMs,
+  };
+}
+
+export function printReadinessExpression() {
+  return `Promise.resolve().then(async () => {
+    const root = document.querySelector('[data-openpress-print-document="true"]');
+    if (!root) return { pageCount: 0, overflowingPages: 0, overflowingPageNumbers: [] };
+    const candidates = root.querySelectorAll('.openpress-html-page');
+    if (candidates.length === 0) return { pageCount: 0, overflowingPages: 0, overflowingPageNumbers: [] };
+
+    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 overflowingPageNumbers = pages.reduce((nums, page, index) => {
+      const body = page.querySelector('.page-body');
+      if (body && !contentFitsPageBody(body)) nums.push(index + 1);
+      return nums;
+    }, []);
+
+    return {
+      pageCount: pages.length,
+      overflowingPages: overflowingPageNumbers.length,
+      overflowingPageNumbers,
+    };
+  })`;
+}
+
+function formatPrintReadyTimeoutMessage(reason, snapshot, timing, elapsedMs) {
+  const seconds = Math.round(elapsedMs / 1000);
+  const observed = `(observed ${snapshot.pageCount} page(s), ${snapshot.overflowingPages} overflowing)`;
+  if (reason === "idle") {
+    return (
+      `Timed out waiting for OpenPress pagination before PDF export. ` +
+      `No progress for ${seconds}s ${observed}. ` +
+      `Raise OPENPRESS_PRINT_READY_IDLE_MS (currently ${timing.idleTimeoutMs}ms) to extend the idle window.`
+    );
+  }
+  return (
+    `Timed out waiting for OpenPress pagination before PDF export. ` +
+    `Total ${seconds}s exceeded ${observed}. ` +
+    `Raise OPENPRESS_PRINT_READY_TIMEOUT_MS (currently ${timing.totalTimeoutMs}ms) to extend the hard cap.`
+  );
+}
+
+export async function waitForPrintReady(client, timing = resolvePrintReadyTiming()) {
+  const startedAt = Date.now();
+  let lastSignature = "";
+  let lastProgressAt = startedAt;
+  let stableSince = startedAt;
+  let lastSnapshot = { pageCount: 0, overflowingPages: 0, overflowingPageNumbers: [] };
+
+  while (true) {
+    const totalElapsed = Date.now() - startedAt;
+    if (totalElapsed > timing.totalTimeoutMs) {
+      throw new Error(formatPrintReadyTimeoutMessage("total", lastSnapshot, timing, totalElapsed));
+    }
+
     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"]');
-        if (!root || root.querySelectorAll('.openpress-html-page').length === 0) 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;
-      })`,
+      expression: printReadinessExpression(),
     });
-    const count = Number(result.result?.value ?? 0);
-    if (count > 0) return count;
-    await delay(100);
+    const value = result.result?.value ?? {};
+    const pageCount = Number.isFinite(Number(value.pageCount)) ? Number(value.pageCount) : 0;
+    const overflowingPages = Number.isFinite(Number(value.overflowingPages)) ? Number(value.overflowingPages) : 0;
+    const overflowingPageNumbers = Array.isArray(value.overflowingPageNumbers)
+      ? value.overflowingPageNumbers.map(Number).filter(Number.isFinite)
+      : [];
+    lastSnapshot = { pageCount, overflowingPages, overflowingPageNumbers };
+
+    const signature = `${pageCount}:${overflowingPages}`;
+    if (signature !== lastSignature) {
+      lastSignature = signature;
+      stableSince = Date.now();
+      lastProgressAt = Date.now();
+    }
+
+    if (pageCount > 0 && Date.now() - stableSince >= timing.stableMs) {
+      return { pageCount, overflowingPageNumbers };
+    }
+
+    const idleElapsed = Date.now() - lastProgressAt;
+    if (idleElapsed > timing.idleTimeoutMs) {
+      throw new Error(formatPrintReadyTimeoutMessage("idle", lastSnapshot, timing, idleElapsed));
+    }
+
+    await delay(timing.pollIntervalMs);
   }
-  throw new Error("Timed out waiting for OpenPress pagination before PDF export.");
 }
 
 async function getPrintPageRects(client) {