pi-quiver 6.5.0 → 6.7.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,16 +471,103 @@ 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 readFileSync3, 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, readdirSync as readdirSync2, renameSync as renameSync2, rmSync as rmSync2, statSync as statSync2 } from "node:fs";
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync3, mkdtempSync, readFileSync as readFileSync2, 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
-import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { extname, join as join2, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
@@ -535,31 +578,59 @@ function ownedPattern(stem) {
 function ownedCsvPattern(stem) {
   return new RegExp(`^${escRe(stem)}-s\\d+-[a-z0-9-]+\\.csv$`);
 }
-var SHEET_LINK_RE = /\[[^\]]*\]\(\s*(sheets\/[^)\s]+)\s*\)/g;
+function ownedPagePattern(stem) {
+  return new RegExp(`^${escRe(stem)}-p\\d+\\.[a-z0-9]+$`);
+}
+var FILE_LINK_RE = /\[[^\]]*\]\(\s*((?:sheets|attachments)\/[^)\s]+)\s*\)/g;
 var IMG_LINK_RE = /!\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)]*?))\s*\)|<img\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/gi;
 function imageTarget(m) {
   const target = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? "").trim();
   const destination = target.replace(/^<([\s\S]*)>$/, "$1").trim();
   return m[2] === void 0 ? destination : destination.replace(/\s+(?:"[^"]*"|'[^']*'|\([^)]*\))$/, "");
 }
-function openBundle(root, stem, overwrite) {
+function openBundle(root, requested, overwrite) {
   mkdirSync2(root, { recursive: true });
-  const mdPath = join2(root, `${stem}.md`);
-  const lockPath = `${mdPath}.lock`;
-  let fd;
-  try {
-    fd = openSync(lockPath, "wx");
-  } catch (e) {
-    if (e.code === "EEXIST") throw new Error(`Another conversion owns ${mdPath} (lock: ${lockPath}); if no conversion is running, delete the lock`);
-    throw new Error(`Output directory not writable: ${root} (${e.message})`);
+  let stem, mdPath, lockPath;
+  let renameReason = null;
+  const exists = `${requested}.md exists`;
+  const held = `${requested}.md.lock held; delete it if no conversion is running`;
+  for (let i = 1; ; i++) {
+    stem = i === 1 ? requested : `${requested}-${i}`;
+    mdPath = join2(root, `${stem}.md`);
+    lockPath = `${mdPath}.lock`;
+    if (!overwrite) {
+      const mdExists = existsSync(mdPath);
+      if (mdExists || existsSync(lockPath)) {
+        if (i === 1) renameReason = mdExists ? exists : held;
+        continue;
+      }
+    }
+    let fd;
+    try {
+      fd = openSync(lockPath, "wx");
+    } catch (e) {
+      if (e.code !== "EEXIST") throw new Error(`Output directory not writable: ${root} (${e.message})`);
+      if (overwrite) throw new Error(`Another conversion owns ${mdPath} (lock: ${lockPath}); if no conversion is running, delete the lock`);
+      if (i === 1) renameReason = held;
+      continue;
+    }
+    closeSync(fd);
+    if (!overwrite && existsSync(mdPath)) {
+      unlinkSync(lockPath);
+      if (i === 1) renameReason = exists;
+      continue;
+    }
+    break;
   }
-  closeSync(fd);
+  const renamedFrom = stem === requested ? null : requested;
   const imagesDir = join2(root, "images");
   const sheetsDir = join2(root, "sheets");
+  const pagesDir = join2(root, "pages");
+  const attachmentsDir = join2(root, "attachments");
   try {
-    if (existsSync(mdPath)) {
-      if (!overwrite) throw new Error(`Output exists: ${mdPath} (pass overwrite)`);
-      const owned = ownedPattern(stem), ownedCsv = ownedCsvPattern(stem);
+    if (existsSync(mdPath) && overwrite) {
+      const owned = ownedPattern(stem), ownedCsv = ownedCsvPattern(stem), ownedPage = ownedPagePattern(stem);
+      const attachments = new Set([...readFileSync(mdPath, "utf8").matchAll(FILE_LINK_RE)].filter((m) => m[1].startsWith("attachments/")).map((m) => m[1].slice("attachments/".length)).filter((f) => f.startsWith(`${stem}-`)));
       unlinkSync(mdPath);
       if (existsSync(imagesDir)) {
         for (const f of readdirSync(imagesDir)) if (owned.test(f)) rmSync(join2(imagesDir, f), { force: true });
@@ -567,12 +638,20 @@ function openBundle(root, stem, overwrite) {
       if (existsSync(sheetsDir)) {
         for (const f of readdirSync(sheetsDir)) if (ownedCsv.test(f)) rmSync(join2(sheetsDir, f), { force: true });
       }
+      if (existsSync(pagesDir)) {
+        for (const f of readdirSync(pagesDir)) if (ownedPage.test(f)) rmSync(join2(pagesDir, f), { force: true });
+      }
+      if (existsSync(attachmentsDir)) {
+        for (const f of readdirSync(attachmentsDir)) if (attachments.has(f)) rmSync(join2(attachmentsDir, f), { force: true });
+      }
     }
     const lockId = randomBytes(6).toString("hex");
     const stagingDir = join2(imagesDir, `.stage-${lockId}`);
     const sheetsStagingDir = join2(sheetsDir, `.stage-${lockId}`);
     mkdirSync2(stagingDir, { recursive: true });
-    return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, manifest: /* @__PURE__ */ new Set(), csvManifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
+    const pagesStagingDir = join2(pagesDir, `.stage-${lockId}`);
+    const attachmentsStagingDir = join2(attachmentsDir, `.stage-${lockId}`);
+    return { root, stem, renamedFrom, renameReason, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, pagesDir, pagesStagingDir, attachmentsDir, attachmentsStagingDir, manifest: /* @__PURE__ */ new Set(), csvManifest: /* @__PURE__ */ new Set(), pageManifest: /* @__PURE__ */ new Set(), attachmentManifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
   } catch (e) {
     rmSync(lockPath, { force: true });
     throw e;
@@ -623,24 +702,54 @@ function publishSheetCsvs(b) {
     b.sourceMap.set(`sheets/${f}`, `sheets/${name}`);
   }
 }
+function publishPageImages(b, pageCount) {
+  if (!existsSync(b.pagesStagingDir)) return;
+  for (const f of readdirSync(b.pagesStagingDir).sort()) {
+    const m = f.match(/^p(\d+)(\.[a-z0-9]+)$/i);
+    if (!m || !statSync(join2(b.pagesStagingDir, f)).isFile()) continue;
+    const name = `${b.stem}-p${m[1].padStart(String(pageCount).length, "0")}${m[2]}`;
+    mkdirSync2(b.pagesDir, { recursive: true });
+    renameSync(join2(b.pagesStagingDir, f), join2(b.pagesDir, name));
+    b.pageManifest.add(name);
+    b.sourceMap.set(`pages/${f}`, `pages/${name}`);
+  }
+  rmSync(b.pagesStagingDir, { recursive: true, force: true });
+}
+function publishAttachments(b) {
+  if (!existsSync(b.attachmentsStagingDir)) return;
+  for (const f of readdirSync(b.attachmentsStagingDir).sort()) {
+    if (!statSync(join2(b.attachmentsStagingDir, f)).isFile()) continue;
+    const name = `${b.stem}-${f}`;
+    mkdirSync2(b.attachmentsDir, { recursive: true });
+    renameSync(join2(b.attachmentsStagingDir, f), join2(b.attachmentsDir, name));
+    b.attachmentManifest.add(name);
+    b.sourceMap.set(`attachments/${f}`, `attachments/${name}`);
+  }
+  rmSync(b.attachmentsStagingDir, { recursive: true, force: true });
+}
 function rewriteLinks(md, sourceMap) {
   const images = md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
     const target = imageTarget([whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted]);
     const dest = sourceMap.get(target) ?? sourceMap.get(target.replace(/^\.\//, ""));
     return dest ? whole.replace(mdAngle === void 0 ? target : `<${mdAngle}>`, dest) : whole;
   });
-  return images.replace(SHEET_LINK_RE, (whole, target) => {
+  return images.replace(FILE_LINK_RE, (whole, target) => {
     const dest = sourceMap.get(target);
     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, pageManifest = /* @__PURE__ */ new Set(), attachmentManifest = /* @__PURE__ */ new Set()) {
   for (const m of md.matchAll(IMG_LINK_RE)) {
     const target = imageTarget(m);
-    if (!target.startsWith("images/") || !manifest.has(target.slice("images/".length))) throw new Error(`unexpected image reference in output: ${target}`);
+    if (html && !target.replace(/^\.\//, "").startsWith("p1/")) continue;
+    if (target.startsWith("pages/")) {
+      if (!pageManifest.has(target.slice("pages/".length))) throw new Error(`unexpected image reference in output: ${target}`);
+    } else 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)) {
-    if (!csvManifest.has(m[1].slice("sheets/".length))) throw new Error(`unexpected sheet reference in output: ${m[1]}`);
+  for (const m of md.matchAll(FILE_LINK_RE)) {
+    if (m[1].startsWith("attachments/")) {
+      if (!attachmentManifest.has(m[1].slice("attachments/".length))) throw new Error(`unexpected attachment reference in output: ${m[1]}`);
+    } else if (!csvManifest.has(m[1].slice("sheets/".length))) throw new Error(`unexpected sheet reference in output: ${m[1]}`);
   }
 }
 function commitBundle(b, markdown) {
@@ -655,6 +764,14 @@ function commitBundle(b, markdown) {
     fs.rmSync(b.sheetsStagingDir, { recursive: true, force: true });
   } catch {
   }
+  try {
+    fs.rmSync(b.pagesStagingDir, { recursive: true, force: true });
+  } catch {
+  }
+  try {
+    fs.rmSync(b.attachmentsStagingDir, { recursive: true, force: true });
+  } catch {
+  }
   try {
     fs.rmSync(b.lockPath, { force: true });
   } catch {
@@ -663,9 +780,13 @@ function commitBundle(b, markdown) {
 function abortBundle(b) {
   for (const f of b.manifest) rmSync(join2(b.imagesDir, f), { force: true });
   for (const f of b.csvManifest) rmSync(join2(b.sheetsDir, f), { force: true });
+  for (const f of b.pageManifest) rmSync(join2(b.pagesDir, f), { force: true });
+  for (const f of b.attachmentManifest) rmSync(join2(b.attachmentsDir, f), { force: true });
   rmSync(`${b.mdPath}.tmp`, { force: true });
   rmSync(b.stagingDir, { recursive: true, force: true });
   rmSync(b.sheetsStagingDir, { recursive: true, force: true });
+  rmSync(b.pagesStagingDir, { recursive: true, force: true });
+  rmSync(b.attachmentsStagingDir, { recursive: true, force: true });
   rmSync(b.lockPath, { force: true });
 }
 function tempBundleRoot() {
@@ -697,6 +818,33 @@ 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(`no text on pages ${compactRanges(ocr.noText)}`);
+      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 = [];
@@ -739,13 +887,15 @@ function outlineLines(entries, total) {
 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"})`;
+  if (h.tier === "docx") return (h.explicitBreaks ?? 0) > 0 ? `${n} (explicit page breaks, not printed pages)` : `${n} (no explicit page breaks) - no page markers; cite by Outline line`;
   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}`);
+  if (h.pagesDir && h.pageImageCount > 0) lines.push(`Pages-Dir: ${h.pagesDir} (${h.pageImageCount} pages)`);
+  else if (h.pageImagesReason) lines.push(`Pages-Dir: none - ${h.pageImagesReason}`);
   lines.push(`Type: ${h.type}   Engine: ${h.engine}   Tier: ${h.tier}`);
   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}`);
@@ -754,7 +904,8 @@ function formatHandle(h) {
   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("    "));
-  h.notes.slice(0, NOTE_MAX_LINES).forEach((n, i) => lines.push(`${i === 0 ? "Notes: " : "       "}${trunc(n, NOTE_MAX_CHARS)}`));
+  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: " : "       "}${n.startsWith("preview truncated:") ? n : trunc(n, NOTE_MAX_CHARS)}`));
   lines.push(...outlineLines(h.outline, h.outlineTotal));
   return lines.join("\n");
 }
@@ -785,12 +936,15 @@ 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 .doc .pptx .xlsx .xlsm .xls .msg .eml .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. 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: "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/DOC/PPTX only); default all; "" means all pages. 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. <stem> = basename without extension with [^A-Za-z0-9._-]+ -> _ (empty -> document); a second call on the same stem writes <stem>-2.md" },
   { key: "overwrite", flag: "--overwrite", type: "bool", default: false, settable: false, help: "Replace an existing completed <stem>.md bundle" },
+  { key: "pageImages", flag: "--page-images", type: "bool", default: false, settable: false, help: "Also render every selected page to pages/<stem>-pNNN.<imageFormat> at imageDpi (PDF, PPTX, .doc, DOCX via LibreOffice); off by default" },
   { 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" },
@@ -800,7 +954,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])
@@ -827,6 +983,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":
@@ -849,6 +1007,7 @@ function coerceDocToMdSettings(raw, warn = console.warn) {
   return out;
 }
 function parsePages(spec) {
+  if (spec.trim() === "") return null;
   const out = /* @__PURE__ */ new Set();
   const parts = spec.split(",").map((s) => s.trim());
   if (parts.length === 0 || parts.some((p) => p === "")) throw new UsageError(`invalid --pages "${spec}": expected e.g. "12-15" or "3,7,10-12"`);
@@ -865,10 +1024,11 @@ 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", ".xlsm": "xlsm", ".doc": "doc", ".msg": "email", ".eml": "email", ".html": "html", ".htm": "html", ...Object.fromEntries(IMAGE_EXTS.map((ext) => [ext, "image"])) };
+var SUPPORTED_EXTENSIONS = Object.keys(SUPPORTED);
 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) {
@@ -891,8 +1051,8 @@ function resolveOptions(perCall, settings, env) {
     out[d.key] = value;
   }
   const o = out;
-  if (o.info && (o.pages !== null || o.outputDir !== null || o.overwrite)) {
-    throw new UsageError("--info cannot be combined with --pages, --output-dir or --overwrite");
+  if (o.info && (o.pages !== null || o.outputDir !== null || o.overwrite || o.pageImages)) {
+    throw new UsageError("--info cannot be combined with --pages, --output-dir, --overwrite or --page-images");
   }
   return o;
 }
@@ -913,14 +1073,14 @@ 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", mammoth: "1.13.0", markdownify: "1.2.3", "python-docx": "1.2.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", "extract-msg": "0.56.1" };
 var KILL_GRACE_MS = 2e3;
-var VENV_DIR_NAME = "doc-to-md-venv-v3";
-var LEGACY_VENV_DIR_NAMES = ["pymupdf-venv", "doc-to-md-venv-v2"];
+var VENV_DIR_NAME = "doc-to-md-venv-v4";
+var LEGACY_VENV_DIR_NAMES = ["pymupdf-venv", "doc-to-md-venv-v2", "doc-to-md-venv-v3"];
 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"]}`];
+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"]}`, `extract-msg==${PACKAGE_PINS["extract-msg"]}`];
 function withArgs(cfg) {
   return pinSpecs(cfg).flatMap((spec) => ["--with", spec]);
 }
@@ -928,7 +1088,7 @@ function pipInstallArgs(cfg) {
   return ["-m", "pip", "install", ...pinSpecs(cfg)];
 }
 function warmArgs(cfg) {
-  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL, mammoth, markdownify, docx"];
+  return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL, mammoth, markdownify, docx, extract_msg"];
 }
 function uvChildArgs(cfg, script, mode) {
   return ["run", ...withArgs(cfg), "--python", "3.14", "python", script, mode];
@@ -1085,6 +1245,11 @@ try:
     print("DOCX", "yes")
 except Exception:
     print("DOCX", "no")
+try:
+    import extract_msg, markdownify
+    print("EMAIL", "yes")
+except Exception:
+    print("EMAIL", "no")
 `;
 var PROBE_TIMEOUT_MS = 5e3;
 function probeArgs() {
@@ -1092,8 +1257,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)\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;
+  const m = stdout.match(/^PY (\d+) (\d+)\r?\nPDF (yes|no)\r?\nXLSX (yes|no)\r?\nDOCX (yes|no)\r?\nEMAIL (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", email: m[6] === "yes" } : null;
 }
 function meetsFloor(p) {
   return p.major > 3 || p.major === 3 && p.minor >= 12;
@@ -1118,7 +1283,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, docx: true };
+  if (warm.code === 0 && !warm.timedOut) return { kind: "uv", pdf: true, xlsx: true, docx: true, email: true };
   const uvAbsent = warm.code === null && !warm.timedOut;
   const isDeadline = (result) => result !== null && "kind" in result;
   const probe = async (exe, tmp) => {
@@ -1134,19 +1299,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, docx: p.docx };
+    if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx, docx: p.docx, email: p.email };
     eligible ??= { exe, version: `${p.major}.${p.minor}` };
   }
-  const healthy = (p) => meetsFloor(p) && p.pdf && p.xlsx && p.docx;
+  const healthy = (p) => meetsFloor(p) && p.pdf && p.xlsx && p.docx && p.email;
   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 && healthy(cached)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+  if (cached && healthy(cached)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
   if (eligible) {
     const recheck = await probe(venvExe);
     if (isDeadline(recheck)) return recheck;
-    if (recheck && healthy(recheck)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+    if (recheck && healthy(recheck)) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     const tmp = `${venvDir}.tmp-${deps.pid}`;
     const bootFail = (stderr) => {
       deps.rmrf(tmp);
@@ -1172,18 +1337,18 @@ async function resolveBackend(cfg, deps, signal) {
     };
     if (publish()) {
       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 { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     }
     const winner = await probe(venvExe, tmp);
     if (isDeadline(winner)) return winner;
     if (winner && healthy(winner)) {
       deps.rmrf(tmp);
-      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true };
+      return { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     }
     deps.rmrf(venvDir);
     if (publish()) {
       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 { kind: "venv", exe: venvExe, pdf: true, xlsx: true, docx: true, email: true };
     }
     return bootFail("rename after competing bootstrap");
   }
@@ -1247,6 +1412,76 @@ function officeFailure(r) {
   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 = readFileSync2(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";
@@ -1312,26 +1547,96 @@ 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}`);
+  if (st.size === 0) throw new Error(`empty file: ${o.path}`);
   const type = classifyInput(inputPath);
-  const isExcel = type === "xlsx" || type === "xls";
+  if (o.pages && (type === "html" || type === "image" || type === "email")) throw new Error(`--pages does not apply to ${type === "html" ? "HTML files" : type === "image" ? "images" : "email"}`);
+  const isExcel = type === "xlsx" || type === "xlsm" || 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 });
   if (isExcel && (backend.kind === "none" || !backend.xlsx)) throw new Error(`Excel conversion needs a Python backend with openpyxl, xlrd and pillow (${backend.kind === "none" ? backend.reason : `${backend.kind} lacks the Excel packages`}). ${EXCEL_REMEDY}`);
+  if (type === "email" && extname3(inputPath).toLowerCase() === ".msg" && (backend.kind === "none" || !backend.email)) throw new Error(`MSG conversion needs the extract-msg package. Python backend: ${backendState(backend, "found without extract-msg")}. Remedy: install uv, or pip install extract-msg markdownify into that Python`);
+  if (type === "email" && extname3(inputPath).toLowerCase() !== ".msg" && lacksDocx(backend)) throw new Error(`EML conversion needs the Python DOCX/HTML packages (mammoth, markdownify, python-docx). Python backend: ${backendState(backend, "found without mammoth/markdownify/python-docx")}. ${docxRemedy}`);
   const stem = sanitizeStem(basename(inputPath, extname3(inputPath)));
   const b = openBundle(o.outputDir ? resolve2(o.outputDir) : tempBundleRoot(), stem, o.overwrite);
   let office = null;
   try {
     let pdfPath = inputPath;
-    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 };
+    const base = { path: inputPath, pages: o.pages, stagingDir: b.stagingDir, sheetsStagingDir: b.sheetsStagingDir, pageImages: o.pageImages, pagesStagingDir: b.pagesStagingDir, 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 = [];
     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)}`;
+      }
+      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) {
@@ -1361,13 +1666,23 @@ async function convertDocument(o, signal, seams) {
       office = r;
       pdfPath = r.pdfPath;
     }
-    if (type === "pptx") {
+    if (type === "doc" || 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 && r.kind === "missing") throw new Error(`${type.toUpperCase()} 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;
     }
+    if (type === "email") {
+      const isMsg = extname3(inputPath).toLowerCase() === ".msg";
+      const r = await s.runTier("email", { ...base, stem: b.stem, attachmentsStagingDir: b.attachmentsStagingDir }, b, signal, o.primaryTimeoutMs, backend);
+      if (!r.ok) throw new Error("userError" in r ? r.userError : `Conversion failed: email ${r.reason}${detailSuffix(r)}`);
+      publishStaged(b);
+      publishAttachments(b);
+      tier = "email";
+      engine = isMsg ? "extract-msg" : "email";
+      json = r.json;
+    }
     const pdfBase = { ...base, path: pdfPath };
     if (json === void 0) {
       if (isExcel) {
@@ -1382,7 +1697,7 @@ async function convertDocument(o, signal, seams) {
         tier = "excel";
         engine = type === "xls" ? "xlrd" : "openpyxl";
         json = r.json;
-        notes = [...json.notes ?? []];
+        notes = (json.notes ?? []).map((n) => n.replace(/sheets\/[^\s,;]+/g, (m) => b.sourceMap.get(m) ?? m));
         const renderPages = json.renderPages ?? [];
         let skip = null;
         const perSheet = /* @__PURE__ */ new Map();
@@ -1421,12 +1736,15 @@ async function convertDocument(o, signal, seams) {
           tier = "primary";
           engine = "pymupdf4llm";
           json = p.json;
+          if (json.pageImages?.length) publishPageImages(b, json.pageCount ?? 0);
         } 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]));
+          rmSync2(b.pagesStagingDir, { recursive: true, force: true });
           const f = await s.runTier("pdf-fallback", { ...pdfBase, keepPages }, b, signal, o.fallbackTimeoutMs, backend);
           publishStaged(b);
+          if (f.ok && f.json.pageImages?.length) publishPageImages(b, f.json.pageCount ?? 0);
           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";
@@ -1436,14 +1754,14 @@ async function convertDocument(o, signal, seams) {
         }
       }
     }
-    if (officeRoute !== null) {
-      degraded = DEGRADED_DOCX_OFFICE;
-      fallbackReason = fallbackReason ? `${officeRoute}; ${fallbackReason}` : officeRoute;
-    }
+    if (type === "doc" || officeRoute !== null) degraded = DEGRADED_DOCX_OFFICE;
+    if (officeRoute !== null) 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 = json.notes ?? [];
-    const body = rewriteLinks(json.markdown ?? "", b.sourceMap);
-    validateImageLinks(body, b.manifest, b.csvManifest);
+    if (!isExcel) notes = [...notes, ...json.notes ?? []];
+    if (b.renamedFrom) notes.splice(notes[0]?.startsWith("preview truncated:") ? 1 : 0, 0, `renamed to ${b.stem} (${b.renameReason})`);
+    const pageImagesReason = !o.pageImages || b.pageManifest.size || tier === "primary" || tier === "fallback" ? null : tier === "unpdf" ? "page images need the Python backend" : `${type} has no page geometry`;
+    const body = resolveOcrLabels(rewriteLinks(json.markdown ?? "", b.sourceMap), b.sourceMap);
+    validateImageLinks(body, b.manifest, b.csvManifest, type === "html" || type === "email", b.pageManifest, b.attachmentManifest);
     const head = [];
     if (degraded) head.push(`Degraded: ${degraded}`);
     if (fallbackReason) head.push(`Fallback-Reason: ${fallbackReason}`);
@@ -1455,7 +1773,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, 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 };
+    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, pagesDir: b.pageManifest.size ? b.pagesDir : null, pageImageCount: b.pageManifest.size, pageImagesReason, 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);
@@ -1469,8 +1787,10 @@ async function inspectDocument(o, signal, 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}`);
+  if (st.size === 0) throw new Error(`empty file: ${o.path}`);
   const type = classifyInput(inputPath);
-  const isExcel = type === "xlsx" || type === "xls";
+  if (type === "html" || type === "image" || type === "email") throw new Error(`info does not apply to ${type === "html" ? "HTML files" : type === "image" ? "images" : "email"}; convert directly`);
+  const isExcel = type === "xlsx" || type === "xlsm" || 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;
@@ -1478,7 +1798,7 @@ async function inspectDocument(o, signal, seams) {
     let path = inputPath;
     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") {
+    } else if (type === "pptx" || type === "doc") {
       const r2 = await s.office(o.sofficeTimeoutMs, inputPath, signal);
       if (!r2.ok) throw officeFailure(r2);
       office = r2;
@@ -1499,25 +1819,32 @@ async function inspectDocument(o, signal, seams) {
 }
 
 // bin/pi-quiver.ts
-var USAGE = 'Usage: pi-quiver fetch <url> [--method GET|HEAD|POST] [--header "K: V"]... [--body <str>] [--raw] [--timeout-ms <n>]\n       pi-quiver doc-to-md [--info] [--pages <spec>] [--output-dir <dir>] [--overwrite] [tunable flags] <path>   (--help for all flags)';
+var USAGE = 'Usage: pi-quiver fetch <url> [--method GET|HEAD|POST] [--header "K: V"]... [--body <str>] [--raw] [--timeout-ms <n>]\n       pi-quiver doc-to-md [--json] [--info] [--page-images] [--pages <spec>] [--output-dir <dir>] [--overwrite] [tunable flags] <path>   (--help for all flags)';
 function parseDocToMd(rest) {
   if (rest.includes("--help") || rest.includes("-h")) return { ok: true, cmd: "doc-to-md-help" };
+  const json = rest.includes("--json");
+  const args = rest.filter((a) => a !== "--json");
   const perCall = {};
   let path;
-  for (let i = 0; i < rest.length; i++) {
-    const arg = rest[i];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
     if (!arg.startsWith("--")) {
       if (path !== void 0) return { ok: false, error: `unexpected argument: ${arg}` };
       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") {
       perCall[d.key] = true;
       continue;
     }
-    const value = rest[++i];
+    const value = args[++i];
     if (value === void 0) return { ok: false, error: `${arg} requires a value` };
     if (d.type === "int") {
       const n = Number(value);
@@ -1526,7 +1853,7 @@ function parseDocToMd(rest) {
     } else perCall[d.key] = value;
   }
   if (!path) return { ok: false, error: "missing <path>" };
-  return { ok: true, cmd: "doc-to-md", perCall: { ...perCall, path } };
+  return { ok: true, cmd: "doc-to-md", perCall: { ...perCall, path }, json };
 }
 function cliAgentDir(env) {
   const raw = env.PI_CODING_AGENT_DIR;
@@ -1544,7 +1871,7 @@ function readCliSettings(cwd, env, warn) {
     if (!existsSync3(file)) continue;
     let raw;
     try {
-      raw = JSON.parse(readFileSync(file, "utf8")).quiver?.docToMd;
+      raw = JSON.parse(readFileSync3(file, "utf8")).quiver?.docToMd;
     } catch {
       warn(`pi-quiver: ${file} is not valid JSON; ignored.`);
       continue;
@@ -1639,7 +1966,11 @@ ${USAGE}
     }
     try {
       const r = o.info ? await inspectDocument(o) : await convertDocument(o);
-      process.stdout.write(`${r.output}
+      if (parsed.json) {
+        const payload = o.info ? r.details : (({ path, backend, pymupdfVersion, inputType, file, outputDir, ...handle }) => handle)(r.details);
+        process.stdout.write(`${JSON.stringify(payload)}
+`);
+      } else process.stdout.write(`${r.output}
 `);
       return 0;
     } catch (err) {