@open-press/core 1.1.3 → 1.1.4

package/engine/cli.mjs

@@ -85,7 +85,7 @@ 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]
+  image [--output <outputDir>] [--pages <selector>] [--no-build] [--dry-run]
   pdf [--output <outputDir>/<pdf.filename>] [--no-build] [--dry-run]
   deploy --confirm [--dry-run]
   doctor [--json] [--no-cache]                          # version + skill staleness check

package/engine/commands/_shared.mjs

@@ -40,6 +40,7 @@ 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.startsWith("--")) throw new Error(`Unknown option: ${value}`);
     else positional.push(value);
   }
@@ -145,6 +146,7 @@ export async function buildReactImages({
   port = "5186",
   noBuild = false,
   recurse,
+  pageSelector = null,
 }) {
   config ??= await loadConfig(root);
   outDir ??= path.join(config.paths.outputDir, "images");
@@ -162,9 +164,18 @@ export async function buildReactImages({
       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 label = pageSelector
+      ? `${result.files.length}/${result.pageCount} OpenPress pages exported to PNG`
+      : `${result.files.length} OpenPress pages exported to PNG`;
+    console.log(label);
+    return {
+      outDir,
+      files: result.files,
+      pageCount: result.pageCount,
+      selectedPageNumbers: result.selectedPageNumbers,
+    };
   } finally {
     await stopChildProcess(server);
   }

package/engine/commands/image.mjs

@@ -1,15 +1,21 @@
 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 host = options.host ?? "127.0.0.1";
   const port = options.port ?? "5186";
 
+  const pageSelector = options.pages ? parsePageSelector(options.pages) : null;
+
   if (options.dryRun) {
     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`);
+    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(outputDir, "page-001.png"))}`);
     return 0;
   }
@@ -22,8 +28,12 @@ export async function run({ root, config, options, recurse }) {
     port,
     noBuild: options.noBuild,
     recurse,
+    pageSelector,
   });
 
-  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/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: [
@@ -137,6 +140,7 @@ export async function printUrlToPdf({
       await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
       const readyResult = await waitForReady(client);
+      warnAboutOverflowingPages("PDF", readyResult);
       const result = await client.send("Page.printToPDF", {
         ...DEFAULT_PRINT_OPTIONS,
         ...printOptions,
@@ -152,6 +156,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 +176,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 +205,25 @@ export async function captureUrlPagesToPng({
     try {
       await preparePdfPage(client, { viewport });
       await client.send("Page.navigate", { url });
-      const pageCount = await waitForReady(client);
+      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 +241,7 @@ export async function captureUrlPagesToPng({
         files.push(filePath);
       }
 
-      return { pageCount, files };
+      return { pageCount, files, selectedPageNumbers };
     } finally {
       client.close();
     }
@@ -282,59 +309,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) {

package/engine/runtime/inspection.mjs

@@ -139,9 +139,51 @@ export async function inspectRenderedOverflow({ root, config, host = "127.0.0.1"
   }
 }
 
-export async function waitForInspectionReady(client) {
-  const deadline = Date.now() + 30000;
-  while (Date.now() < deadline) {
+export const INSPECTION_READY_DEFAULTS = Object.freeze({
+  totalTimeoutMs: 300_000,
+  idleTimeoutMs: 30_000,
+  pollIntervalMs: 100,
+});
+
+export function resolveInspectionReadyTiming(env = process.env) {
+  const total = Number(env.OPENPRESS_INSPECTION_TIMEOUT_MS);
+  const idle = Number(env.OPENPRESS_INSPECTION_IDLE_MS);
+  return {
+    totalTimeoutMs: Number.isFinite(total) && total > 0 ? total : INSPECTION_READY_DEFAULTS.totalTimeoutMs,
+    idleTimeoutMs: Number.isFinite(idle) && idle > 0 ? idle : INSPECTION_READY_DEFAULTS.idleTimeoutMs,
+    pollIntervalMs: INSPECTION_READY_DEFAULTS.pollIntervalMs,
+  };
+}
+
+function formatInspectionTimeoutMessage(reason, snapshot, timing, elapsedMs) {
+  const seconds = Math.round(elapsedMs / 1000);
+  const observed = `(observed ${snapshot.pageCount} page(s))`;
+  if (reason === "idle") {
+    return (
+      `Timed out waiting for OpenPress pagination before inspection. ` +
+      `No progress for ${seconds}s ${observed}. ` +
+      `Raise OPENPRESS_INSPECTION_IDLE_MS (currently ${timing.idleTimeoutMs}ms) to extend the idle window.`
+    );
+  }
+  return (
+    `Timed out waiting for OpenPress pagination before inspection. ` +
+    `Total ${seconds}s exceeded ${observed}. ` +
+    `Raise OPENPRESS_INSPECTION_TIMEOUT_MS (currently ${timing.totalTimeoutMs}ms) to extend the hard cap.`
+  );
+}
+
+export async function waitForInspectionReady(client, timing = resolveInspectionReadyTiming()) {
+  const startedAt = Date.now();
+  let lastSignature = "";
+  let lastProgressAt = startedAt;
+  let lastSnapshot = { pageCount: 0 };
+
+  while (true) {
+    const totalElapsed = Date.now() - startedAt;
+    if (totalElapsed > timing.totalTimeoutMs) {
+      throw new Error(formatInspectionTimeoutMessage("total", lastSnapshot, timing, totalElapsed));
+    }
+
     const result = await client.send("Runtime.evaluate", {
       returnByValue: true,
       awaitPromise: true,
@@ -149,9 +191,23 @@ export async function waitForInspectionReady(client) {
     });
     const value = result.result?.value;
     if (Array.isArray(value)) return value;
-    await delay(100);
+
+    const pageCount = Number.isFinite(Number(value?.pageCount)) ? Number(value.pageCount) : lastSnapshot.pageCount;
+    lastSnapshot = { pageCount };
+
+    const signature = String(pageCount);
+    if (signature !== lastSignature) {
+      lastSignature = signature;
+      lastProgressAt = Date.now();
+    }
+
+    const idleElapsed = Date.now() - lastProgressAt;
+    if (idleElapsed > timing.idleTimeoutMs) {
+      throw new Error(formatInspectionTimeoutMessage("idle", lastSnapshot, timing, idleElapsed));
+    }
+
+    await delay(timing.pollIntervalMs);
   }
-  throw new Error("Timed out waiting for OpenPress pagination before inspection.");
 }
 
 export function overflowIssuesFromMeasurements(measurements) {
@@ -241,7 +297,9 @@ function humanOverflowTarget(code) {
 function inspectionExpression() {
   return `Promise.resolve().then(async () => {
     const root = document.querySelector('[data-openpress-print-document="true"]');
-    if (!root || root.querySelectorAll('.openpress-html-page').length === 0) return null;
+    if (!root) return { pending: true, pageCount: 0 };
+    const candidates = root.querySelectorAll('.openpress-html-page');
+    if (candidates.length === 0) return { pending: true, pageCount: 0 };
 
     await document.fonts?.ready;
     await Promise.all(Array.from(document.images).map(async (img) => {
@@ -290,7 +348,7 @@ function inspectionExpression() {
     };
 
     const wrappers = Array.from(document.querySelectorAll('.openpress-public-page > .openpress-html-page'));
-    if (wrappers.length === 0) return null;
+    if (wrappers.length === 0) return { pending: true, pageCount: candidates.length };
     return wrappers.map((wrapper, index) => {
       const page = wrapper.querySelector('.reader-page') || wrapper;
       const frame = page.querySelector('.page-frame') || page;

package/engine/runtime/page-selector.mjs

@@ -0,0 +1,87 @@
+const TOKEN_PATTERN = /^\s*(-?\d*)\s*(?:-\s*(\d*))?\s*$/;
+
+export function parsePageSelector(input) {
+  if (typeof input !== "string") {
+    throw new TypeError("Page selector must be a string");
+  }
+  const trimmed = input.trim();
+  if (trimmed === "") {
+    throw new Error("Page selector is empty; expected something like '3', '3,5-7', or '12-'.");
+  }
+
+  const segments = trimmed.split(",").map((part) => part.trim()).filter(Boolean);
+  if (segments.length === 0) {
+    throw new Error(`Page selector "${input}" has no usable segments.`);
+  }
+
+  return segments.map((segment) => parseSegment(segment, input));
+}
+
+function parseSegment(segment, original) {
+  if (!segment.includes("-")) {
+    const value = toPositiveInteger(segment, original);
+    return { kind: "single", value };
+  }
+
+  if (segment === "-") {
+    throw new Error(`Page selector "${original}" contains a bare "-"; ranges need at least one bound.`);
+  }
+
+  const dashIndex = segment.indexOf("-");
+  if (segment.indexOf("-", dashIndex + 1) !== -1) {
+    throw new Error(`Page selector segment "${segment}" has too many dashes.`);
+  }
+
+  const leftRaw = segment.slice(0, dashIndex);
+  const rightRaw = segment.slice(dashIndex + 1);
+  const from = leftRaw.trim() === "" ? null : toPositiveInteger(leftRaw, original);
+  const to = rightRaw.trim() === "" ? null : toPositiveInteger(rightRaw, original);
+
+  if (from != null && to != null && from > to) {
+    throw new Error(`Page selector range "${segment}" goes backwards (${from} > ${to}).`);
+  }
+
+  return { kind: "range", from, to };
+}
+
+function toPositiveInteger(raw, original) {
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new Error(`Page selector "${original}" contains non-integer token "${raw}".`);
+  }
+  const value = Number(trimmed);
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`Page selector "${original}" contains out-of-range page number "${raw}"; pages start at 1.`);
+  }
+  return value;
+}
+
+export function resolvePageSelector(spec, totalPages) {
+  if (!Array.isArray(spec)) {
+    throw new TypeError("resolvePageSelector expects a parsed selector array");
+  }
+  if (!Number.isInteger(totalPages) || totalPages < 0) {
+    throw new TypeError("resolvePageSelector expects a non-negative integer totalPages");
+  }
+  if (totalPages === 0) return [];
+
+  const selected = new Set();
+  for (const segment of spec) {
+    if (segment.kind === "single") {
+      if (segment.value > totalPages) {
+        throw new Error(`Page ${segment.value} is out of range; document has ${totalPages} page(s).`);
+      }
+      selected.add(segment.value);
+      continue;
+    }
+    const from = segment.from ?? 1;
+    const to = segment.to ?? totalPages;
+    if (from > totalPages) {
+      throw new Error(`Range start ${from} is out of range; document has ${totalPages} page(s).`);
+    }
+    const upper = Math.min(to, totalPages);
+    for (let i = from; i <= upper; i += 1) selected.add(i);
+  }
+
+  return Array.from(selected).sort((a, b) => a - b);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-press/core",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "type": "module",
   "description": "open-press core — runtime primitives, CLI, and render pipeline for AI-first fixed-layout documents.",
   "license": "MIT",