pi-quiver 6.4.0 → 6.6.0

package/dist/bin/pi-quiver.js

@@ -1,12 +1,39 @@
 #!/usr/bin/env node
-
-// bin/pi-quiver.ts
-import { existsSync as existsSync3, readFileSync, realpathSync } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join4, resolve as resolve3 } from "node:path";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 
 // lib/fetch-core.ts
+var fetch_core_exports = {};
+__export(fetch_core_exports, {
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  applyGate: () => applyGate,
+  binaryExtension: () => binaryExtension,
+  buildGhArgs: () => buildGhArgs,
+  buildGhLogArgs: () => buildGhLogArgs,
+  categorize: () => categorize,
+  classifyGitHubTarget: () => classifyGitHubTarget,
+  collectBody: () => collectBody,
+  executeGhRouting: () => executeGhRouting,
+  fetchUrl: () => fetchUrl,
+  formatSize: () => formatSize,
+  htmlToMarkdown: () => htmlToMarkdown,
+  htmlToMarkdownRaw: () => htmlToMarkdownRaw,
+  planGhRouting: () => planGhRouting,
+  prettyJson: () => prettyJson,
+  runGh: () => runGh
+});
 import { mkdirSync, writeFileSync, createWriteStream } from "node:fs";
 import { rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -27,24 +54,6 @@ function formatSize(bytes) {
     return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
   }
 }
-var RESERVED_OWNERS = /* @__PURE__ */ new Set([
-  "orgs",
-  "users",
-  "sponsors",
-  "topics",
-  "marketplace",
-  "apps",
-  "collections",
-  "stars",
-  "settings",
-  "notifications",
-  "codespaces",
-  "features",
-  "trending",
-  "security",
-  "customer-stories"
-]);
-var GH_NAME = /^[A-Za-z0-9._-]+$/;
 function classifyGitHubTarget(url) {
   const host = url.hostname.toLowerCase();
   if (host !== "github.com" && host !== "www.github.com") return null;
@@ -82,22 +91,6 @@ function buildGhLogArgs(target) {
   if (target.kind === "job") return ["run", "view", "--job", target.jobId, "--log-failed", "--repo", target.slug];
   return null;
 }
-var GH_MAX_BUFFER = 1e7;
-var execFileAsync = promisify(execFile);
-var runGh = async (args, timeoutMs, signal) => {
-  try {
-    const { stdout } = await execFileAsync("gh", args, {
-      timeout: timeoutMs,
-      signal,
-      maxBuffer: GH_MAX_BUFFER,
-      encoding: "utf8"
-    });
-    if (!stdout.trim()) return { ok: false };
-    return { ok: true, stdout };
-  } catch {
-    return { ok: false };
-  }
-};
 function planGhRouting(params, url) {
   if (params.raw) return null;
   if ((params.method ?? "GET") !== "GET") return null;
@@ -176,16 +169,6 @@ async function executeGhRouting(params, url, signal, runner = runGh) {
   }
   return renderGhResult(target, gh.stdout, failedLogs);
 }
-var PARSABLE_MAX_BYTES = 1e6;
-var BINARY_MAX_BYTES = 5e7;
-var SNIFF_MAX_BYTES = 64e3;
-var DEFAULT_TIMEOUT_MS = 2e4;
-var INLINE_MAX_BYTES = 32e3;
-var INLINE_MAX_LINES = 1e3;
-var PREVIEW_LINES = 60;
-var PREVIEW_MAX_BYTES = 4e3;
-var FIREFOX_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14.7; rv:135.0) Gecko/20100101 Firefox/135.0";
-var DEFAULT_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
 function parseCharset(contentType) {
   const m = /charset\s*=\s*"?([^";\s]+)"?/i.exec(contentType);
   return (m?.[1] ?? "utf-8").trim().toLowerCase();
@@ -205,27 +188,9 @@ function buildPreview(body) {
   }
   return preview;
 }
-var turndownService = new TurndownService({
-  headingStyle: "atx",
-  codeBlockStyle: "fenced",
-  bulletListMarker: "-"
-});
-turndownService.use(gfm);
 function mimeType(contentType) {
   return contentType.split(";")[0].trim().toLowerCase();
 }
-var TEXT_ALLOWLIST = [
-  /^text\//,
-  /^application\/(json|xml|xhtml\+xml|javascript)$/,
-  /\+json$/,
-  /\+xml$/
-];
-var KNOWN_BINARY = [
-  /^audio\//,
-  /^video\//,
-  /^font\//,
-  /^application\/(pdf|zip|gzip|x-tar|x-7z-compressed|x-rar-compressed|wasm)$/
-];
 function categorize(contentType, sniff, raw) {
   const mime = mimeType(contentType);
   if (/^image\//.test(mime)) return "binary";
@@ -265,6 +230,9 @@ function htmlToMarkdown(html, url) {
 ${md}`;
   return md;
 }
+function htmlToMarkdownRaw(html) {
+  return turndownService.turndown(html).trim();
+}
 function prettyJson(text) {
   try {
     return JSON.stringify(JSON.parse(text), null, 2);
@@ -300,18 +268,6 @@ function textExtension(category, contentType) {
   if (category === "json") return "json";
   return mimeType(contentType).includes("xml") ? "xml" : "txt";
 }
-var BINARY_EXT = {
-  "application/pdf": "pdf",
-  "application/zip": "zip",
-  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
-  "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
-  "application/gzip": "gz",
-  "image/png": "png",
-  "image/jpeg": "jpg",
-  "image/gif": "gif",
-  "image/webp": "webp",
-  "image/svg+xml": "svg"
-};
 function binaryExtension(contentType) {
   const mime = mimeType(contentType);
   if (BINARY_EXT[mime]) return BINARY_EXT[mime];
@@ -515,12 +471,99 @@ async function fetchUrl(opts) {
     opts.signal?.removeEventListener("abort", onAbort);
   }
 }
+var RESERVED_OWNERS, GH_NAME, GH_MAX_BUFFER, execFileAsync, runGh, PARSABLE_MAX_BYTES, BINARY_MAX_BYTES, SNIFF_MAX_BYTES, DEFAULT_TIMEOUT_MS, INLINE_MAX_BYTES, INLINE_MAX_LINES, PREVIEW_LINES, PREVIEW_MAX_BYTES, FIREFOX_UA, DEFAULT_ACCEPT, turndownService, TEXT_ALLOWLIST, KNOWN_BINARY, BINARY_EXT;
+var init_fetch_core = __esm({
+  "lib/fetch-core.ts"() {
+    "use strict";
+    RESERVED_OWNERS = /* @__PURE__ */ new Set([
+      "orgs",
+      "users",
+      "sponsors",
+      "topics",
+      "marketplace",
+      "apps",
+      "collections",
+      "stars",
+      "settings",
+      "notifications",
+      "codespaces",
+      "features",
+      "trending",
+      "security",
+      "customer-stories"
+    ]);
+    GH_NAME = /^[A-Za-z0-9._-]+$/;
+    GH_MAX_BUFFER = 1e7;
+    execFileAsync = promisify(execFile);
+    runGh = async (args, timeoutMs, signal) => {
+      try {
+        const { stdout } = await execFileAsync("gh", args, {
+          timeout: timeoutMs,
+          signal,
+          maxBuffer: GH_MAX_BUFFER,
+          encoding: "utf8"
+        });
+        if (!stdout.trim()) return { ok: false };
+        return { ok: true, stdout };
+      } catch {
+        return { ok: false };
+      }
+    };
+    PARSABLE_MAX_BYTES = 1e6;
+    BINARY_MAX_BYTES = 5e7;
+    SNIFF_MAX_BYTES = 64e3;
+    DEFAULT_TIMEOUT_MS = 2e4;
+    INLINE_MAX_BYTES = 32e3;
+    INLINE_MAX_LINES = 1e3;
+    PREVIEW_LINES = 60;
+    PREVIEW_MAX_BYTES = 4e3;
+    FIREFOX_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 14.7; rv:135.0) Gecko/20100101 Firefox/135.0";
+    DEFAULT_ACCEPT = "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8";
+    turndownService = new TurndownService({
+      headingStyle: "atx",
+      codeBlockStyle: "fenced",
+      bulletListMarker: "-"
+    });
+    turndownService.use(gfm);
+    TEXT_ALLOWLIST = [
+      /^text\//,
+      /^application\/(json|xml|xhtml\+xml|javascript)$/,
+      /\+json$/,
+      /\+xml$/
+    ];
+    KNOWN_BINARY = [
+      /^audio\//,
+      /^video\//,
+      /^font\//,
+      /^application\/(pdf|zip|gzip|x-tar|x-7z-compressed|x-rar-compressed|wasm)$/
+    ];
+    BINARY_EXT = {
+      "application/pdf": "pdf",
+      "application/zip": "zip",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+      "application/vnd.openxmlformats-officedocument.presentationml.presentation": "pptx",
+      "application/gzip": "gz",
+      "image/png": "png",
+      "image/jpeg": "jpg",
+      "image/gif": "gif",
+      "image/webp": "webp",
+      "image/svg+xml": "svg"
+    };
+  }
+});
+
+// bin/pi-quiver.ts
+init_fetch_core();
+import { existsSync as existsSync3, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join4, resolve as resolve3 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // lib/doc-to-md-core.ts
-import { existsSync as existsSync2, mkdtempSync, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, mkdtempSync, readFileSync, readdirSync as readdirSync2, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2, writeFileSync as writeFileSync3 } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir, tmpdir as tmpdir3 } from "node:os";
-import { basename, dirname, extname as extname3, join as join3, resolve as resolve2 } from "node:path";
+import { basename, dirname, extname as extname3, isAbsolute, join as join3, resolve as resolve2 } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // lib/doc-to-md-bundle.ts
@@ -634,9 +677,10 @@ function rewriteLinks(md, sourceMap) {
     return dest ? whole.split(target).join(dest) : whole;
   });
 }
-function validateImageLinks(md, manifest, csvManifest = /* @__PURE__ */ new Set()) {
+function validateImageLinks(md, manifest, csvManifest = /* @__PURE__ */ new Set(), html = false) {
   for (const m of md.matchAll(IMG_LINK_RE)) {
     const target = imageTarget(m);
+    if (html && !target.replace(/^\.\//, "").startsWith("p1/")) continue;
     if (!target.startsWith("images/") || !manifest.has(target.slice("images/".length))) throw new Error(`unexpected image reference in output: ${target}`);
   }
   for (const m of md.matchAll(SHEET_LINK_RE)) {
@@ -697,11 +741,46 @@ function compactRanges(nums, maxEntries = 20) {
   if (parts.length <= maxEntries) return parts.join(", ");
   return `${parts.slice(0, maxEntries).join(", ")} (+${parts.length - maxEntries} more)`;
 }
+var INSTALL_HINT = "install Tesseract (see doc/doc-to-md.md), then rerun with ocr=true";
+var BARE_REASONS = ["fallback tier", "no Python backend"];
+function ocrLine(ocr, type) {
+  const image = type === "image";
+  const rerun = ocr.tesseract ? "rerun with ocr=true" : INSTALL_HINT;
+  switch (ocr.status) {
+    case "off":
+      return image ? `OCR: off; ${rerun}` : `OCR: off - ${ocr.textless.length} page(s) without a text layer; ${rerun}`;
+    case "unavailable": {
+      const reason = ocr.reason ?? "";
+      const bare = BARE_REASONS.includes(reason) || reason.startsWith("OCR child failed: ");
+      return `OCR: unavailable - ${reason}${bare ? "" : " (install Tesseract; see doc/doc-to-md.md)"}`;
+    }
+    case "skipped":
+      return "OCR: skipped - image too small";
+    case "ran": {
+      const clauses = [`OCR: ${ocr.pages.length} ${image ? "image" : "page(s)"} (${ocr.lang})`];
+      if (ocr.noText.length) clauses.push(`${ocr.noText.length} returned no text`);
+      if (ocr.ocrFailed.length) clauses.push(`${ocr.ocrFailed.length} failed and were converted without OCR`);
+      if (ocr.budgetStopped.length) {
+        const r = compactRanges(ocr.budgetStopped, Number.POSITIVE_INFINITY).replaceAll(", ", ",");
+        clauses.push(`time budget reached for pages=${r}; rerun with pages=${r} or raise primaryTimeoutMs`);
+      }
+      return clauses.join("; ");
+    }
+  }
+}
+var PAGE_MARKER_RE = /^--- end of page\.page_number=(\d+) ---$/;
 function scanOutline(md, max) {
   const entries = [];
+  let pending = [];
   let total = 0, inFence = false;
   md.split("\n").forEach((raw, i) => {
     const line = raw.replace(/\r$/, "");
+    const marker = line.match(PAGE_MARKER_RE);
+    if (marker) {
+      for (const e of pending) e.page = Number(marker[1]);
+      pending = [];
+      return;
+    }
     if (/^\s*(```|~~~)/.test(line)) {
       inFence = !inFence;
       return;
@@ -710,29 +789,43 @@ function scanOutline(md, max) {
     const m = line.match(/^(#{1,6}) (.*)$/);
     if (!m) return;
     total++;
-    if (entries.length < max) entries.push({ line: i + 1, level: m[1].length, title: trunc(m[2].trim(), TITLE_MAX) });
+    if (entries.length < max) {
+      const e = { line: i + 1, level: m[1].length, title: trunc(m[2].trim(), TITLE_MAX), page: null };
+      entries.push(e);
+      pending.push(e);
+    }
   });
   return { entries, total };
 }
 function outlineLines(entries, total) {
+  if (total === 0) return ["Outline: none"];
   if (entries.length === 0) return [];
-  const width = Math.max(5, Math.max(...entries.map((e) => `L${e.line}`.length)) + 2);
-  const out = ["Outline:", ...entries.map((e) => `  ${`L${e.line}`.padEnd(width)}${"#".repeat(e.level)} ${trunc(e.title, TITLE_MAX)}`)];
+  const lineWidth = Math.max(3, ...entries.map((e) => `L${e.line}`.length)) + 2;
+  const paged = entries.filter((e) => e.page !== null);
+  const pageWidth = paged.length ? Math.max(...paged.map((e) => `p${e.page}`.length)) + 2 : 0;
+  const out = ["Outline:", ...entries.map((e) => `  ${`L${e.line}`.padEnd(lineWidth)}${pageWidth ? (e.page === null ? "" : `p${e.page}`).padEnd(pageWidth) : ""}${"#".repeat(e.level)} ${trunc(e.title, TITLE_MAX)}`)];
   if (total > entries.length) out.push(`  (+${total - entries.length} more)`);
   return out;
 }
+function pageCountLabel(h) {
+  const n = h.pageCount ?? "?";
+  if (h.type !== "docx") return String(n);
+  if (h.tier === "docx") return `${n} (${(h.explicitBreaks ?? 0) > 0 ? "explicit page breaks, not printed pages" : "no explicit page breaks"})`;
+  return `${n} (LibreOffice pagination)`;
+}
 function formatHandle(h) {
   const lines = [`Saved-To: ${h.savedTo}`];
   if (h.imagesDir && h.imageCount > 0) lines.push(`Images-Dir: ${h.imagesDir}`);
   if (h.sheetsDir) lines.push(`Sheets-Dir: ${h.sheetsDir}`);
   lines.push(`Type: ${h.type}   Engine: ${h.engine}   Tier: ${h.tier}`);
-  lines.push(`Page-Count: ${h.pageCount ?? "?"}   Pages: ${h.pages ? compactRanges(h.pages) : "all"}   Images: ${h.imageCount}   Size: ${formatSize2(h.bytes)} / ${h.lines} lines`);
+  lines.push(`Page-Count: ${pageCountLabel(h)}   Pages: ${h.pages ? compactRanges(h.pages) : "all"}   Images: ${h.imageCount}   Size: ${formatSize2(h.bytes)} / ${h.lines} lines`);
   if (h.degraded) lines.push(`Degraded: ${h.degraded}`);
   if (h.fallbackReason) lines.push(`Fallback-Reason: ${h.fallbackReason}`);
   const fe = [];
   if (h.failedPages.length) fe.push(`Failed-Pages: ${compactRanges(h.failedPages)}`);
   if (h.emptyPages.length) fe.push(`Empty-Pages: ${compactRanges(h.emptyPages)}`);
   if (fe.length) lines.push(fe.join("    "));
+  if (h.ocr) lines.push(ocrLine(h.ocr, h.type));
   h.notes.slice(0, NOTE_MAX_LINES).forEach((n, i) => lines.push(`${i === 0 ? "Notes: " : "       "}${trunc(n, NOTE_MAX_CHARS)}`));
   lines.push(...outlineLines(h.outline, h.outlineTotal));
   return lines.join("\n");
@@ -752,9 +845,9 @@ function formatInfoHandle(i, max) {
   const meta = Object.entries(i.metadata).filter(([, v]) => v).map(([k, v]) => `${k[0].toUpperCase()}${k.slice(1)}: ${trunc(v, META_MAX_CHARS)}`);
   if (meta.length) lines.push(meta.join("   "));
   if (i.toc.length) {
-    lines.push("TOC:", ...i.toc.slice(0, max).map((t) => `  L${t.level} ${trunc(t.title, TITLE_MAX)} (p${t.page})`));
+    lines.push("TOC:", ...i.toc.slice(0, max).map((t) => `  L${t.level} ${trunc(t.title, TITLE_MAX)} (p${t.page ?? "?"})`));
     if (i.tocTotal > max) lines.push(`  (+${i.tocTotal - max} more)`);
-  }
+  } else if (i.type === "docx") lines.push("TOC: none (no heading styles found)");
   return lines.join("\n");
 }
 
@@ -764,14 +857,16 @@ var UsageError = class extends Error {
 };
 var MIN_PYMUPDF4LLM = "1.27.0";
 var VERSION_RE = /^\d+(\.\d+)*$/;
+var OCR_LANGUAGE_RE = /^[a-z][a-z0-9_]*(\+[a-z][a-z0-9_]*)*$/;
+var IMAGE_EXTS = [".png", ".jpg", ".jpeg", ".tif", ".tiff", ".bmp", ".gif"];
 var DOC_TO_MD_OPTIONS = [
-  { key: "path", flag: null, type: "string", default: null, settable: false, help: "Local .pdf .docx .pptx .xlsx .xls file" },
+  { key: "path", flag: null, type: "string", default: null, settable: false, help: "Local .pdf .docx .pptx .xlsx .xls .html .htm .png .jpg .jpeg .tif .tiff .bmp .gif file" },
   { key: "info", flag: "--info", type: "bool", default: false, settable: false, help: "Inspect only (page count, metadata, TOC or sheet inventory); no bundle" },
-  { key: "pages", flag: "--pages", type: "pages", default: null, settable: false, help: 'Inclusive 1-based pages, e.g. "12-15" or "3,7,10-12" (PDF/DOCX/PPTX only); default all' },
+  { key: "pages", flag: "--pages", type: "pages", default: null, settable: false, help: 'Inclusive 1-based pages, e.g. "12-15" or "3,7,10-12" (PDF/DOCX/PPTX only); default all. DOCX: selects explicit-page-break segments; rejected when the file has none' },
   { key: "outputDir", flag: "--output-dir", type: "string", default: null, settable: false, help: "Bundle root for <stem>.md + images/; default a per-call temp dir" },
   { key: "overwrite", flag: "--overwrite", type: "bool", default: false, settable: false, help: "Replace an existing completed <stem>.md bundle" },
-  { key: "primaryTimeoutMs", flag: "--primary-timeout", type: "int", default: 6e4, settable: true, env: "PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", help: "pymupdf4llm tier; also the unpdf tier" },
-  { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier; also info on PDF and Excel rendered views" },
+  { key: "primaryTimeoutMs", flag: "--primary-timeout", type: "int", default: 6e4, settable: true, env: "PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", help: "pymupdf4llm tier and DOCX child (docx mode); also the unpdf tier" },
+  { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier (including DOCX LibreOffice fallback); also PDF and DOCX info and Excel rendered views" },
   { key: "sofficeTimeoutMs", flag: "--soffice-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", help: "DOCX/PPTX -> PDF via LibreOffice; also Excel rendered views" },
   { key: "excelTimeoutMs", flag: "--excel-timeout", type: "int", default: 6e4, settable: true, help: "Excel child (both openpyxl loads); also info on Excel" },
   { key: "warmTimeoutMs", flag: "--warm-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_WARM_TIMEOUT_MS", help: "Absolute backend discovery/bootstrap deadline (first call per process)" },
@@ -779,7 +874,9 @@ var DOC_TO_MD_OPTIONS = [
   { key: "imageDpi", flag: "--image-dpi", type: "int", default: 150, settable: true, help: "Render DPI for page images and Excel rendered views" },
   { key: "imageFormat", flag: "--image-format", type: "enum", default: "png", settable: true, enumValues: ["png", "jpg"], help: "Rendered image format (embedded images keep their native extension)" },
   { key: "maxOutputBytes", flag: "--max-output-bytes", type: "int", default: 2e7, settable: true, help: "Child stdout cap in bytes" },
-  { key: "outlineMaxEntries", flag: "--outline-max-entries", type: "int", default: 40, settable: true, help: "Heading outline / TOC / sheet inventory cap in the handle" }
+  { key: "outlineMaxEntries", flag: "--outline-max-entries", type: "int", default: 40, settable: true, help: "Heading outline / TOC / sheet inventory cap in the handle" },
+  { key: "ocr", flag: "--ocr", type: "bool", default: false, settable: true, help: "Run OCR on pages without a text layer and on image inputs when Tesseract language data is installed; off by default (--no-ocr turns a settings-level true off)" },
+  { key: "ocrLanguage", flag: "--ocr-language", type: "lang", default: "eng", settable: true, help: "Tesseract language code(s), +-joined, e.g. deu+eng" }
 ];
 var TUNABLE_DEFAULTS = Object.fromEntries(
   DOC_TO_MD_OPTIONS.filter((d) => d.settable).map((d) => [d.key, d.default])
@@ -806,6 +903,8 @@ function coerceValue(d, raw, fromString = false) {
       if (typeof raw !== "string" || !VERSION_RE.test(raw)) return { ok: false, reason: "must be digits and dots" };
       if (!versionAtLeast(raw, MIN_PYMUPDF4LLM)) return { ok: false, reason: `must be >= ${MIN_PYMUPDF4LLM}` };
       return { ok: true, value: raw };
+    case "lang":
+      return typeof raw === "string" && OCR_LANGUAGE_RE.test(raw) ? { ok: true, value: raw } : { ok: false, reason: "must be Tesseract language codes joined by + (e.g. eng, deu+eng)" };
     case "string":
       return typeof raw === "string" && raw.length > 0 ? { ok: true, value: raw } : { ok: false, reason: "must be a non-empty string" };
     case "pages":
@@ -844,10 +943,10 @@ function sanitizeStem(base) {
   const s = base.replace(/[^A-Za-z0-9._-]+/g, "_");
   return s.length ? s : "document";
 }
-var SUPPORTED = { ".pdf": "pdf", ".docx": "docx", ".pptx": "pptx", ".xlsx": "xlsx", ".xls": "xls" };
+var SUPPORTED = { ".pdf": "pdf", ".docx": "docx", ".pptx": "pptx", ".xlsx": "xlsx", ".xls": "xls", ".html": "html", ".htm": "html", ...Object.fromEntries(IMAGE_EXTS.map((ext) => [ext, "image"])) };
 function classifyInput(filePath) {
   const t = SUPPORTED[extname2(filePath).toLowerCase()];
-  if (!t) throw new Error(`Unsupported file type "${extname2(filePath) || "(none)"}"; supported: .pdf, .docx, .pptx, .xlsx, .xls`);
+  if (!t) throw new Error(`Unsupported file type "${extname2(filePath) || "(none)"}"; supported: ${Object.keys(SUPPORTED).join(", ")}`);
   return t;
 }
 function resolveOptions(perCall, settings, env) {
@@ -892,21 +991,22 @@ function renderHelp() {
 }
 
 // lib/doc-to-md-core.ts
-var PACKAGE_PINS = { pymupdf4llm: TUNABLE_DEFAULTS.pymupdfVersion, openpyxl: "3.1.5", xlrd: "2.0.2", pillow: "12.3.0" };
+var PACKAGE_PINS = { pymupdf4llm: TUNABLE_DEFAULTS.pymupdfVersion, openpyxl: "3.1.5", xlrd: "2.0.2", pillow: "12.3.0", mammoth: "1.13.0", markdownify: "1.2.3", "python-docx": "1.2.0" };
 var KILL_GRACE_MS = 2e3;
-var VENV_DIR_NAME = "doc-to-md-venv-v2";
-var LEGACY_VENV_DIR_NAME = "pymupdf-venv";
+var VENV_DIR_NAME = "doc-to-md-venv-v3";
+var LEGACY_VENV_DIR_NAMES = ["pymupdf-venv", "doc-to-md-venv-v2"];
 var STDERR_CAP = 1e6;
 var OUTPUT_MAX_BYTES = 2e7;
 var EXCEL_PDF_FILTER = 'pdf:calc_pdf_Export:{"SinglePageSheets":{"type":"boolean","value":"true"}}';
+var pinSpecs = (cfg) => [`pymupdf4llm==${cfg.pymupdfVersion}`, `openpyxl==${PACKAGE_PINS.openpyxl}`, `xlrd==${PACKAGE_PINS.xlrd}`, `pillow==${PACKAGE_PINS.pillow}`, `mammoth==${PACKAGE_PINS.mammoth}`, `markdownify==${PACKAGE_PINS.markdownify}`, `python-docx==${PACKAGE_PINS["python-docx"]}`];
 function withArgs(cfg) {
-  return ["--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--with", `openpyxl==${PACKAGE_PINS.openpyxl}`, "--with", `xlrd==${PACKAGE_PINS.xlrd}`, "--with", `pillow==${PACKAGE_PINS.pillow}`];
+  return pinSpecs(cfg).flatMap((spec) => ["--with", spec]);
 }
 function pipInstallArgs(cfg) {
-  return ["-m", "pip", "install", `pymupdf4llm==${cfg.pymupdfVersion}`, `openpyxl==${PACKAGE_PINS.openpyxl}`, `xlrd==${PACKAGE_PINS.xlrd}`, `pillow==${PACKAGE_PINS.pillow}`];
+  return ["-m", "pip", "install", ...pinSpecs(cfg)];
 }
 function warmArgs(cfg) {
-  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL"];
+  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL, mammoth, markdownify, docx"];
 }
 function uvChildArgs(cfg, script, mode) {
   return ["run", ...withArgs(cfg), "--python", "3.14", "python", script, mode];
@@ -1058,6 +1158,11 @@ try:
     print("XLSX", "yes")
 except Exception:
     print("XLSX", "no")
+try:
+    import mammoth, markdownify, docx
+    print("DOCX", "yes")
+except Exception:
+    print("DOCX", "no")
 `;
 var PROBE_TIMEOUT_MS = 5e3;
 function probeArgs() {
@@ -1065,8 +1170,8 @@ function probeArgs() {
 }
 var PYTHON_CANDIDATES = ["python3", "python"];
 function parseProbeOutput(stdout) {
-  const m = stdout.match(/^PY (\d+) (\d+)\r?\nPDF (yes|no)\r?\nXLSX (yes|no)\s*$/);
-  return m ? { major: Number(m[1]), minor: Number(m[2]), pdf: m[3] === "yes", xlsx: m[4] === "yes" } : null;
+  const m = stdout.match(/^PY (\d+) (\d+)\r?\nPDF (yes|no)\r?\nXLSX (yes|no)\r?\nDOCX (yes|no)\s*$/);
+  return m ? { major: Number(m[1]), minor: Number(m[2]), pdf: m[3] === "yes", xlsx: m[4] === "yes", docx: m[5] === "yes" } : null;
 }
 function meetsFloor(p) {
   return p.major > 3 || p.major === 3 && p.minor >= 12;
@@ -1091,7 +1196,7 @@ async function resolveBackend(cfg, deps, signal) {
   };
   const warm = await deps.run("uv", warmArgs(cfg), { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
   if (signal?.aborted) throw new Error("aborted");
-  if (warm.code === 0 && !warm.timedOut) return { kind: "uv", pdf: true, xlsx: true };
+  if (warm.code === 0 && !warm.timedOut) return { kind: "uv", pdf: true, xlsx: true, docx: true };
   const uvAbsent = warm.code === null && !warm.timedOut;
   const isDeadline = (result) => result !== null && "kind" in result;
   const probe = async (exe, tmp) => {
@@ -1107,18 +1212,19 @@ async function resolveBackend(cfg, deps, signal) {
     const p = await probe(exe);
     if (isDeadline(p)) return p;
     if (!p || !meetsFloor(p)) continue;
-    if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx };
+    if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx, docx: p.docx };
     eligible ??= { exe, version: `${p.major}.${p.minor}` };
   }
+  const healthy = (p) => meetsFloor(p) && p.pdf && p.xlsx && p.docx;
   const venvDir = join3(deps.cacheRoot, VENV_DIR_NAME);
   const venvExe = venvPython(venvDir, deps.platform);
   const cached = await probe(venvExe);
   if (isDeadline(cached)) return cached;
-  if (cached && meetsFloor(cached) && cached.pdf && cached.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+  if (cached && healthy(cached)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
   if (eligible) {
     const recheck = await probe(venvExe);
     if (isDeadline(recheck)) return recheck;
-    if (recheck && meetsFloor(recheck) && recheck.pdf && recheck.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+    if (recheck && healthy(recheck)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
     const tmp = `${venvDir}.tmp-${deps.pid}`;
     const bootFail = (stderr) => {
       deps.rmrf(tmp);
@@ -1143,19 +1249,19 @@ async function resolveBackend(cfg, deps, signal) {
       }
     };
     if (publish()) {
-      deps.rmrf(join3(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+      for (const legacy of LEGACY_VENV_DIR_NAMES) deps.rmrf(join3(deps.cacheRoot, legacy));
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
     }
     const winner = await probe(venvExe, tmp);
     if (isDeadline(winner)) return winner;
-    if (winner && meetsFloor(winner) && winner.pdf && winner.xlsx) {
+    if (winner && healthy(winner)) {
       deps.rmrf(tmp);
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
     }
     deps.rmrf(venvDir);
     if (publish()) {
-      deps.rmrf(join3(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+      for (const legacy of LEGACY_VENV_DIR_NAMES) deps.rmrf(join3(deps.cacheRoot, legacy));
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
     }
     return bootFail("rename after competing bootstrap");
   }
@@ -1213,15 +1319,93 @@ async function tryConvertOffice(sofficeTimeoutMs, src, signal, run = runCapped,
     throw e;
   }
 }
-async function convertOffice(sofficeTimeoutMs, src, signal, run = runCapped) {
-  const r = await tryConvertOffice(sofficeTimeoutMs, src, signal, run);
-  if (r.ok) return r;
-  if (r.kind === "missing") throw new Error("LibreOffice (soffice) is required to convert .docx/.pptx but was not found on PATH. Install LibreOffice or convert the file to PDF first.");
-  if (r.kind === "no-pdf") throw new Error("LibreOffice (soffice) ran but produced no usable PDF for this file. Ensure LibreOffice can open the document, or convert it to PDF manually first.");
-  throw new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr}`);
+function officeFailure(r) {
+  if (r.kind === "missing") return new Error("LibreOffice (soffice) is required to convert .docx/.pptx but was not found on PATH. Install LibreOffice or convert the file to PDF first.");
+  if (r.kind === "no-pdf") return new Error("LibreOffice (soffice) ran but produced no usable PDF for this file. Ensure LibreOffice can open the document, or convert it to PDF manually first.");
+  return new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr}`);
 }
 var DEGRADED_TEXT = "PyMuPDF text extraction - layout/tables not preserved";
+var DEGRADED_HTML_TURNDOWN = "Turndown HTML conversion - definition lists and headerless tables not preserved";
+var DATA_IMAGE_RE = /^data:image\/(png|jpeg|gif|bmp|tiff);base64,([A-Za-z0-9+/=\s]+)$/i;
+var DATA_EXT = { png: ".png", jpeg: ".jpg", gif: ".gif", bmp: ".bmp", tiff: ".tif" };
+var DATA_SIGNATURES = {
+  png: [[137, 80, 78, 71]],
+  jpeg: [[255, 216, 255]],
+  gif: [[71, 73, 70, 56]],
+  bmp: [[66, 77]],
+  tiff: [[73, 73, 42, 0], [77, 77, 0, 42]]
+};
+async function prepareHtml(inputPath, stagingDir) {
+  const { JSDOM: JSDOM2 } = await import("jsdom");
+  const bytes = readFileSync(inputPath);
+  let source = bytes;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+  }
+  const dom = new JSDOM2(source);
+  const doc = dom.window.document;
+  const title = doc.querySelector("title")?.textContent?.trim();
+  if (title && !doc.body.querySelector("h1")) {
+    const h1 = doc.createElement("h1");
+    h1.textContent = title;
+    doc.body.prepend(h1);
+  }
+  for (const el of [...doc.querySelectorAll("head, script, style, noscript, template")]) el.remove();
+  const dir = join3(stagingDir, "p1");
+  mkdirSync3(dir, { recursive: true });
+  let k = 0, missing = 0;
+  for (const img of [...doc.querySelectorAll("img")]) {
+    const src = (img.getAttribute("src") ?? "").trim();
+    const alt = img.getAttribute("alt") ?? "";
+    if (/^(?:https?:)?\/\//i.test(src)) {
+      const a = doc.createElement("a");
+      const url = src.startsWith("//") ? `https:${src}` : src;
+      a.setAttribute("href", url);
+      a.textContent = alt || url;
+      img.replaceWith(a);
+      continue;
+    }
+    let target = null;
+    const data = src.match(DATA_IMAGE_RE);
+    if (data) {
+      const buf = Buffer.from(data[2].replace(/\s+/g, ""), "base64");
+      if (DATA_SIGNATURES[data[1].toLowerCase()].some((signature) => signature.every((byte, i) => buf[i] === byte))) {
+        target = `p1/${++k}${DATA_EXT[data[1].toLowerCase()]}`;
+        writeFileSync3(join3(stagingDir, target), buf);
+      }
+    } else if (src && !/^[a-z][a-z0-9+.-]*:/i.test(src) && !isAbsolute(src)) {
+      let file = null;
+      try {
+        file = resolve2(dirname(inputPath), decodeURIComponent(src.split(/[?#]/)[0]));
+      } catch {
+      }
+      const ext = file ? extname3(file).toLowerCase() : "";
+      if (file && IMAGE_EXTS.includes(ext) && statSync2(file, { throwIfNoEntry: false })?.isFile()) {
+        target = `p1/${++k}${ext}`;
+        copyFileSync(file, join3(stagingDir, target));
+      }
+    }
+    if (target) img.setAttribute("src", target);
+    else {
+      missing++;
+      img.replaceWith(doc.createTextNode(alt));
+    }
+  }
+  writeFileSync3(join3(dir, ".done"), "");
+  return { html: dom.serialize(), missing };
+}
 var DEGRADED_UNPDF = "unpdf text extraction - structure not preserved";
+var DEGRADED_DOCX_TEXT = "python-docx text extraction - footnotes, hyperlinks, images not preserved";
+var DEGRADED_DOCX_OFFICE = "LibreOffice PDF route - heading styles and explicit page breaks not preserved; page numbers are LibreOffice pagination";
+var DOCX_PIP = "pip install mammoth markdownify python-docx";
+var DOCX_PAGES_OFFICE = `--pages on a DOCX needs the Python DOCX backend (explicit page-break segments); the LibreOffice route has none. Remedy: install uv, or ${DOCX_PIP}`;
+var docxRemedy = `Remedy: install uv, or ${DOCX_PIP} into a Python that already has pymupdf4llm`;
+var backendState = (b, missing) => b.kind === "none" ? b.reason : missing;
+var lacksDocx = (b) => b.kind === "none" || !b.docx;
+var clearStaging = (b) => {
+  for (const f of readdirSync2(b.stagingDir)) rmSync2(join3(b.stagingDir, f), { recursive: true, force: true });
+};
 var EXCEL_REMEDY = "Remedy: install uv, or pip install openpyxl xlrd pillow";
 function resolveUnpdfWorker(candidates, exists) {
   for (const candidate of candidates) if (exists(candidate)) return candidate;
@@ -1276,12 +1460,27 @@ function reconcileRenderMarkers(md, renderPages, fmt, sourceMap, reason) {
   if (/<!--rvs?:\d+-->/.test(md)) throw new Error("internal: unresolved render marker");
   return md;
 }
+var emptyOcr = (lang) => ({ status: "off", lang, textless: [], pages: [], noText: [], ocrFailed: [], budgetStopped: [], reason: null, tesseract: null });
+var OCR_SENTINEL_RE = /\x00OCR ([^\x00]*)\x00/g;
+function resolveOcrLabels(md, sourceMap) {
+  return md.replace(OCR_SENTINEL_RE, (_, key) => {
+    const dest = sourceMap.get(key);
+    return dest ? `> Text recognized in ${dest} (OCR, may contain recognition errors):` : "> Text recognized by OCR (source image missing):";
+  });
+}
+function handleOcr(tier, type, o, json) {
+  if (tier === "unpdf") return o.ocr ? { ...emptyOcr(o.ocrLanguage), status: "unavailable", reason: "no Python backend" } : null;
+  const x = json.ocr;
+  if (!x || type !== "image" && !x.textless.length && !x.pages.length && !x.ocrFailed.length) return null;
+  return x;
+}
 async function convertDocument(o, signal, seams) {
   const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, office: tryConvertOffice, ...seams };
   const inputPath = resolve2(o.path);
   const st = statSync2(inputPath, { throwIfNoEntry: false });
   if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
   const type = classifyInput(inputPath);
+  if (o.pages && (type === "html" || type === "image")) throw new Error(`--pages does not apply to ${type === "html" ? "HTML files" : "images"}`);
   const isExcel = type === "xlsx" || type === "xls";
   if (isExcel && o.pages) throw new Error("--pages does not apply to spreadsheets: worksheets have no stable page numbering");
   const backend = await s.backend({ pymupdfVersion: o.pymupdfVersion, warmTimeoutMs: o.warmTimeoutMs });
@@ -1291,81 +1490,175 @@ async function convertDocument(o, signal, seams) {
   let office = null;
   try {
     let pdfPath = inputPath;
-    if (type === "docx" || type === "pptx") {
-      office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal);
-      pdfPath = office.pdfPath;
-    }
-    const base = { path: pdfPath, pages: o.pages, stagingDir: b.stagingDir, sheetsStagingDir: b.sheetsStagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion };
+    const base = { path: inputPath, pages: o.pages, stagingDir: b.stagingDir, sheetsStagingDir: b.sheetsStagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion, ocr: o.ocr, ocrLanguage: o.ocrLanguage, ocrBudgetMs: o.primaryTimeoutMs };
     let tier, engine, json, degraded = null, fallbackReason = null;
+    let explicitBreaks = null;
     let notes = [];
-    if (isExcel) {
-      const r = await s.runTier("xlsx", base, b, signal, o.excelTimeoutMs, backend);
-      if (!r.ok) {
-        if ("userError" in r) throw new Error(r.userError);
-        const remedy = r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes" ? ". Remedy: raise excelTimeoutMs" : "";
-        throw new Error(`Excel conversion failed: ${r.reason}${detailSuffix(r)}${remedy}`);
+    let officeRoute = null;
+    if (type === "html") {
+      const prepared = await prepareHtml(inputPath, b.stagingDir);
+      if (signal?.aborted) throw new Error("aborted");
+      if (prepared.missing) notes.push(`${prepared.missing} image(s) not found; replaced with alt text`);
+      if (!lacksDocx(backend)) {
+        const r = await s.runTier("html", { ...base, html: prepared.html }, b, signal, o.primaryTimeoutMs, backend);
+        if (r.ok) {
+          tier = "html";
+          engine = "markdownify";
+          json = r.json;
+        } else if ("userError" in r) throw new Error(r.userError);
+        else if (signal?.aborted || r.reason === "aborted") throw new Error("aborted");
+        else fallbackReason = `html ${r.reason}${detailSuffix(r)}`;
       }
-      publishSheetImages(b);
-      publishSheetCsvs(b);
-      tier = "excel";
-      engine = type === "xls" ? "xlrd" : "openpyxl";
-      json = r.json;
-      notes = [...json.notes ?? []];
-      const renderPages = json.renderPages ?? [];
-      let skip = null;
-      const perSheet = /* @__PURE__ */ new Map();
-      if (renderPages.length) {
-        const off = await s.office(o.sofficeTimeoutMs, inputPath, signal, runCapped, EXCEL_PDF_FILTER);
-        if (!off.ok) skip = off.kind === "missing" ? "LibreOffice not found" : off.kind === "timeout" ? `soffice failed: timeout after ${o.sofficeTimeoutMs}ms` : off.kind === "exit" ? `soffice failed: exit ${off.code}` : "soffice produced no PDF";
-        else {
-          try {
-            const rp = await s.runTier("render-pages", { path: off.pdfPath, sheetIndices: renderPages, expectedPages: json.sheetCount, imageDpi: o.imageDpi, imageFormat: o.imageFormat, stagingDir: b.stagingDir, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.fallbackTimeoutMs, backend);
-            if (!rp.ok) skip = `render failed: ${"userError" in rp ? rp.userError : rp.reason}`;
-            else if (rp.json.ok === false) skip = rp.json.reason ?? "render failed";
-            else {
-              publishSheetImages(b);
-              for (const f of rp.json.failed ?? []) perSheet.set(f.idx, f.reason);
-              for (const d of rp.json.rendered ?? []) if (d.dpi < o.imageDpi) notes.push(`Rendered view s${d.idx}: rendered at ${d.dpi} dpi`);
+      if (json === void 0) {
+        const { htmlToMarkdownRaw: htmlToMarkdownRaw2 } = await Promise.resolve().then(() => (init_fetch_core(), fetch_core_exports));
+        tier = "html";
+        engine = "turndown";
+        degraded = DEGRADED_HTML_TURNDOWN;
+        json = { markdown: `${htmlToMarkdownRaw2(prepared.html)}
+`, notes: [] };
+      }
+      publishStaged(b);
+    }
+    if (type === "image") {
+      let reason = "no Python backend";
+      if (backend.kind !== "none") {
+        const r = await s.runTier("image", { ...base, stem: b.stem }, b, signal, o.primaryTimeoutMs, backend);
+        if (r.ok) {
+          publishStaged(b);
+          tier = "image";
+          engine = "pymupdf4llm";
+          json = r.json;
+        } else if ("userError" in r) throw new Error(r.userError);
+        else if (signal?.aborted || r.reason === "aborted") throw new Error("aborted");
+        else reason = `OCR child failed: ${r.reason}`;
+      }
+      if (signal?.aborted) throw new Error("aborted");
+      if (json === void 0) {
+        clearStaging(b);
+        const file = `original${extname3(inputPath).toLowerCase()}`;
+        const dir = join3(b.stagingDir, "p1");
+        mkdirSync3(dir, { recursive: true });
+        copyFileSync(inputPath, join3(dir, file));
+        writeFileSync3(join3(dir, ".done"), "");
+        publishStaged(b);
+        tier = "image";
+        engine = "copy";
+        json = { markdown: `![${b.stem}](p1/${file})
+`, pageCount: 1, notes: [], ocr: { ...emptyOcr(o.ocrLanguage), status: "unavailable", reason } };
+      }
+    }
+    if (type === "docx" && !lacksDocx(backend)) {
+      const d = await s.runTier("docx", base, b, signal, o.primaryTimeoutMs, backend);
+      if (d.ok) {
+        publishStaged(b);
+        tier = "docx";
+        engine = d.json.engine === "python-docx" ? "python-docx" : "mammoth";
+        json = d.json;
+        explicitBreaks = d.json.explicitBreaks ?? 0;
+        if (d.json.degraded) {
+          degraded = DEGRADED_DOCX_TEXT;
+          fallbackReason = d.json.fallbackReason ?? null;
+        }
+      } else if ("userError" in d) throw new Error(d.userError);
+      else if (d.reason === "exit 1") {
+        officeRoute = `docx ${d.reason}${detailSuffix(d)}`;
+        clearStaging(b);
+      } else throw new Error(`Conversion failed: docx ${d.reason}${detailSuffix(d)}`);
+    } else if (type === "docx") officeRoute = backend.kind === "none" ? backend.reason : "python backend lacks DOCX packages";
+    if (type === "docx" && officeRoute !== null) {
+      if (o.pages) throw new Error(officeRoute.startsWith("docx exit") ? `${DOCX_PAGES_OFFICE} (${officeRoute})` : DOCX_PAGES_OFFICE);
+      const r = await s.office(o.sofficeTimeoutMs, inputPath, signal);
+      if (!r.ok && r.kind === "missing") {
+        if (officeRoute.startsWith("docx exit")) throw new Error(`Conversion failed: ${officeRoute}; LibreOffice (soffice) not found on PATH`);
+        throw new Error(`DOCX conversion needs the Python DOCX packages or LibreOffice. Python backend: ${backendState(backend, "found without mammoth/markdownify/python-docx")}. ${docxRemedy}, or install LibreOffice (soffice)`);
+      }
+      if (!r.ok) throw officeRoute.startsWith("docx exit") ? new Error(`Conversion failed: ${officeRoute}; ${officeFailure(r).message}`) : officeFailure(r);
+      office = r;
+      pdfPath = r.pdfPath;
+    }
+    if (type === "pptx") {
+      const r = await s.office(o.sofficeTimeoutMs, inputPath, signal);
+      if (!r.ok && r.kind === "missing") throw new Error(`PPTX conversion needs LibreOffice (soffice); direct conversion is not available. Python backend: ${backendState(backend, "available")}. Remedy: install LibreOffice`);
+      if (!r.ok) throw officeFailure(r);
+      office = r;
+      pdfPath = r.pdfPath;
+    }
+    const pdfBase = { ...base, path: pdfPath };
+    if (json === void 0) {
+      if (isExcel) {
+        const r = await s.runTier("xlsx", base, b, signal, o.excelTimeoutMs, backend);
+        if (!r.ok) {
+          if ("userError" in r) throw new Error(r.userError);
+          const remedy = r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes" ? ". Remedy: raise excelTimeoutMs" : "";
+          throw new Error(`Excel conversion failed: ${r.reason}${detailSuffix(r)}${remedy}`);
+        }
+        publishSheetImages(b);
+        publishSheetCsvs(b);
+        tier = "excel";
+        engine = type === "xls" ? "xlrd" : "openpyxl";
+        json = r.json;
+        notes = [...json.notes ?? []];
+        const renderPages = json.renderPages ?? [];
+        let skip = null;
+        const perSheet = /* @__PURE__ */ new Map();
+        if (renderPages.length) {
+          const off = await s.office(o.sofficeTimeoutMs, inputPath, signal, runCapped, EXCEL_PDF_FILTER);
+          if (!off.ok) skip = off.kind === "missing" ? "LibreOffice not found" : off.kind === "timeout" ? `soffice failed: timeout after ${o.sofficeTimeoutMs}ms` : off.kind === "exit" ? `soffice failed: exit ${off.code}` : "soffice produced no PDF";
+          else {
+            try {
+              const rp = await s.runTier("render-pages", { path: off.pdfPath, sheetIndices: renderPages, expectedPages: json.sheetCount, imageDpi: o.imageDpi, imageFormat: o.imageFormat, stagingDir: b.stagingDir, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.fallbackTimeoutMs, backend);
+              if (!rp.ok) skip = `render failed: ${"userError" in rp ? rp.userError : rp.reason}`;
+              else if (rp.json.ok === false) skip = rp.json.reason ?? "render failed";
+              else {
+                publishSheetImages(b);
+                for (const f of rp.json.failed ?? []) perSheet.set(f.idx, f.reason);
+                for (const d of rp.json.rendered ?? []) if (d.dpi < o.imageDpi) notes.push(`Rendered view s${d.idx}: rendered at ${d.dpi} dpi`);
+              }
+            } finally {
+              off.cleanup();
             }
-          } finally {
-            off.cleanup();
           }
+          if (skip) notes.push(`Rendered views skipped: ${skip}`);
+          else if (perSheet.size) notes.push(`Rendered views: ${perSheet.size} of ${renderPages.length} unavailable`);
+        }
+        json = { ...json, markdown: reconcileRenderMarkers(json.markdown ?? "", renderPages, o.imageFormat, b.sourceMap, (idx) => perSheet.get(idx) ?? skip ?? "render failed") };
+      } else if (backend.kind === "none") {
+        const r = await s.runTier("pdf-text", pdfBase, b, signal, o.primaryTimeoutMs, backend);
+        if (!r.ok) throw new Error("userError" in r ? r.userError : `Conversion failed: unpdf ${r.reason}${detailSuffix(r)}`);
+        tier = "unpdf";
+        engine = "unpdf";
+        json = r.json;
+        degraded = DEGRADED_UNPDF;
+      } else {
+        const p = await s.runTier("pdf-primary", pdfBase, b, signal, o.primaryTimeoutMs, backend);
+        const kept = publishStaged(b);
+        if (p.ok) {
+          tier = "primary";
+          engine = "pymupdf4llm";
+          json = p.json;
+        } else if ("userError" in p) throw new Error(p.userError);
+        else {
+          if (signal?.aborted) throw new Error("aborted");
+          const keepPages = Object.fromEntries([...kept.entries()].map(([k, v]) => [String(k), v]));
+          const f = await s.runTier("pdf-fallback", { ...pdfBase, keepPages }, b, signal, o.fallbackTimeoutMs, backend);
+          publishStaged(b);
+          if (!f.ok) throw new Error("userError" in f ? f.userError : `Conversion failed: primary ${p.reason}; fallback ${f.reason}${detailSuffix(f)}`);
+          tier = "fallback";
+          engine = "pymupdf-text";
+          json = f.json;
+          degraded = DEGRADED_TEXT;
+          fallbackReason = `primary ${p.reason}`;
         }
-        if (skip) notes.push(`Rendered views skipped: ${skip}`);
-        else if (perSheet.size) notes.push(`Rendered views: ${perSheet.size} of ${renderPages.length} unavailable`);
-      }
-      json = { ...json, markdown: reconcileRenderMarkers(json.markdown ?? "", renderPages, o.imageFormat, b.sourceMap, (idx) => perSheet.get(idx) ?? skip ?? "render failed") };
-    } else if (backend.kind === "none") {
-      const r = await s.runTier("pdf-text", base, b, signal, o.primaryTimeoutMs, backend);
-      if (!r.ok) throw new Error("userError" in r ? r.userError : `Conversion failed: unpdf ${r.reason}${detailSuffix(r)}`);
-      tier = "unpdf";
-      engine = "unpdf";
-      json = r.json;
-      degraded = DEGRADED_UNPDF;
-    } else {
-      const p = await s.runTier("pdf-primary", base, b, signal, o.primaryTimeoutMs, backend);
-      const kept = publishStaged(b);
-      if (p.ok) {
-        tier = "primary";
-        engine = "pymupdf4llm";
-        json = p.json;
-      } else if ("userError" in p) throw new Error(p.userError);
-      else {
-        if (signal?.aborted) throw new Error("aborted");
-        const keepPages = Object.fromEntries([...kept.entries()].map(([k, v]) => [String(k), v]));
-        const f = await s.runTier("pdf-fallback", { ...base, keepPages }, b, signal, o.fallbackTimeoutMs, backend);
-        publishStaged(b);
-        if (!f.ok) throw new Error("userError" in f ? f.userError : `Conversion failed: primary ${p.reason}; fallback ${f.reason}${detailSuffix(f)}`);
-        tier = "fallback";
-        engine = "pymupdf-text";
-        json = f.json;
-        degraded = DEGRADED_TEXT;
-        fallbackReason = `primary ${p.reason}`;
       }
     }
-    if (!isExcel) notes = json.notes ?? [];
-    const body = rewriteLinks(json.markdown ?? "", b.sourceMap);
-    validateImageLinks(body, b.manifest, b.csvManifest);
+    if (officeRoute !== null) {
+      degraded = DEGRADED_DOCX_OFFICE;
+      fallbackReason = fallbackReason ? `${officeRoute}; ${fallbackReason}` : officeRoute;
+    }
+    if (tier === void 0 || engine === void 0 || json === void 0) throw new Error("internal: no tier produced output");
+    if (!isExcel) notes = [...notes, ...json.notes ?? []];
+    const body = resolveOcrLabels(rewriteLinks(json.markdown ?? "", b.sourceMap), b.sourceMap);
+    validateImageLinks(body, b.manifest, b.csvManifest, type === "html");
     const head = [];
     if (degraded) head.push(`Degraded: ${degraded}`);
     if (fallbackReason) head.push(`Fallback-Reason: ${fallbackReason}`);
@@ -1377,7 +1670,7 @@ async function convertDocument(o, signal, seams) {
 ` : "") + body;
     commitBundle(b, markdown);
     const outline = scanOutline(markdown, o.outlineMaxEntries);
-    const details = { path: inputPath, backend: backend.kind, pymupdfVersion: o.pymupdfVersion, inputType: type, file: b.mdPath, outputDir: b.root, savedTo: b.mdPath, imagesDir: b.imagesDir, sheetsDir: b.csvManifest.size ? b.sheetsDir : null, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, imageCount: b.manifest.size, bytes: Buffer.byteLength(markdown, "utf8"), lines: markdown.split("\n").length, degraded, fallbackReason, failedPages: (json.failedPages ?? []).map((f) => f.page), emptyPages: json.emptyPages ?? [], notes, outline: outline.entries, outlineTotal: outline.total };
+    const details = { path: inputPath, backend: backend.kind, pymupdfVersion: o.pymupdfVersion, inputType: type, file: b.mdPath, outputDir: b.root, savedTo: b.mdPath, imagesDir: b.imagesDir, sheetsDir: b.csvManifest.size ? b.sheetsDir : null, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, explicitBreaks, imageCount: b.manifest.size, bytes: Buffer.byteLength(markdown, "utf8"), lines: markdown.split("\n").length, degraded, fallbackReason, failedPages: (json.failedPages ?? []).map((f) => f.page), emptyPages: json.emptyPages ?? [], notes, outline: outline.entries, outlineTotal: outline.total, ocr: handleOcr(tier, type, o, json) };
     return { output: formatHandle(details), details };
   } catch (e) {
     abortBundle(b);
@@ -1392,15 +1685,20 @@ async function inspectDocument(o, signal, seams) {
   const st = statSync2(inputPath, { throwIfNoEntry: false });
   if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
   const type = classifyInput(inputPath);
+  if (type === "html" || type === "image") throw new Error(`info does not apply to ${type === "html" ? "HTML files" : "images"}; convert directly`);
   const isExcel = type === "xlsx" || type === "xls";
   const backend = await s.backend({ pymupdfVersion: o.pymupdfVersion, warmTimeoutMs: o.warmTimeoutMs });
   if (isExcel && (backend.kind === "none" || !backend.xlsx)) throw new Error(`Excel inspection needs a Python backend with openpyxl, xlrd and pillow. ${EXCEL_REMEDY}`);
   let office = null;
   try {
     let path = inputPath;
-    if (type === "docx" || type === "pptx") {
-      office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal);
-      path = office.pdfPath;
+    if (type === "docx") {
+      if (lacksDocx(backend)) throw new Error(`DOCX inspection needs the Python DOCX packages. Python backend: ${backendState(backend, "found without mammoth/markdownify/python-docx")}. ${docxRemedy}`);
+    } else if (type === "pptx") {
+      const r2 = await s.office(o.sofficeTimeoutMs, inputPath, signal);
+      if (!r2.ok) throw officeFailure(r2);
+      office = r2;
+      path = r2.pdfPath;
     }
     const r = await s.runTier("info", { path, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, { stagingDir: "" }, signal, isExcel ? o.excelTimeoutMs : o.fallbackTimeoutMs, backend);
     if (!r.ok) {
@@ -1429,6 +1727,11 @@ function parseDocToMd(rest) {
       path = arg;
       continue;
     }
+    const negated = arg.startsWith("--no-") ? DOC_TO_MD_OPTIONS.find((o) => o.type === "bool" && o.settable && o.flag === `--${arg.slice(5)}`) : void 0;
+    if (negated) {
+      perCall[negated.key] = false;
+      continue;
+    }
     const d = DOC_TO_MD_OPTIONS.find((o) => o.flag === arg);
     if (!d) return { ok: false, error: `unknown flag: ${arg}` };
     if (d.type === "bool") {
@@ -1462,7 +1765,7 @@ function readCliSettings(cwd, env, warn) {
     if (!existsSync3(file)) continue;
     let raw;
     try {
-      raw = JSON.parse(readFileSync(file, "utf8")).quiver?.docToMd;
+      raw = JSON.parse(readFileSync2(file, "utf8")).quiver?.docToMd;
     } catch {
       warn(`pi-quiver: ${file} is not valid JSON; ignored.`);
       continue;