pi-quiver 6.5.0 → 6.6.0

package/CHANGELOG.md

@@ -8,6 +8,14 @@ Published to npm as `pi-quiver` (`pi install npm:pi-quiver`). Pushing a
 via OIDC trusted publishing. The release helper at
 `.agents/skills/release/scripts/release.sh` cuts the tag; CI publishes.
 
+## v6.6.0 - 2026-09-29
+
+- `doc_to_md` converts local `.html`/`.htm` (markdownify; Readability-free Turndown fallback) with local and `data:` images copied into the bundle and remote images kept as links.
+- `doc_to_md` accepts `.png .jpg .jpeg .tif .tiff .bmp .gif`; the image is copied into the bundle.
+- Pages without a text layer now keep a page picture on both Python tiers (a scanned PDF used to convert to nothing).
+- Opt-in OCR: `ocr` (default `false`) and `ocrLanguage` (default `eng`) tunables, `--ocr`/`--no-ocr`; needs Tesseract language data (optional OS dependency). A small-image gate and a time budget keep OCR from eating the primary timeout; the handle's `OCR:` line reports what ran.
+- DOCX tables with `|` in a cell now render as `\|` instead of breaking the table; code blocks with a `language-*` class keep their fence language.
+
 ## v6.5.0 - 2026-09-29
 
 - `doc_to_md` converts DOCX directly in the Python child (mammoth -> markdownify, python-docx text fallback) instead of LibreOffice -> PDF: heading styles survive as `#` headings, hyperlinks and footnotes are kept, pictures land under `images/` (#24). DOCX page semantics change: only author-inserted page breaks become `--- end of page.page_number=N ---` markers, `Page-Count` is suffixed `(explicit page breaks, not printed pages)` / `(no explicit page breaks)`, `pages` selects those segments and is rejected on a break-less file, and DOCX that falls back to LibreOffice (no DOCX-capable Python, or both DOCX engines failed) is marked degraded with `(LibreOffice pagination)` and rejects `pages`. LibreOffice is now optional for DOCX and still required for PPTX. Backend probe gains a `DOCX` line and pins `mammoth==1.13.0`, `markdownify==1.2.3`, `python-docx==1.2.0`; the managed venv moves to `doc-to-md-venv-v3` and the older venvs are removed after the first successful build.

package/README.md

@@ -16,7 +16,7 @@ But the moment an agent does that, one `fetch` or PDF read can dump hundreds of
 
 ## Why pi-quiver exists
 
-`fetch` brings real web pages and GitHub issues/PRs into context and is size-gated by construction: over 32 KB or 1000 lines spills to a temp file with a preview and a grep/read hint. `doc_to_md` converts local PDF/DOCX/PPTX/XLSX/XLS files into a Markdown bundle on disk and returns only a concise handle. Ingestion is what makes data-driven work possible; bounded tool results keep it safe.
+`fetch` brings real web pages and GitHub issues/PRs into context and is size-gated by construction: over 32 KB or 1000 lines spills to a temp file with a preview and a grep/read hint. `doc_to_md` converts local PDF/DOCX/PPTX/XLSX/XLS, HTML, and image files into a Markdown bundle on disk and returns only a concise handle; OCR is opt-in and uses optional Tesseract language data. Ingestion is what makes data-driven work possible; bounded tool results keep it safe.
 
 `session-name`, `sword-header`, `fast-mode`, `provider-stall-watchdog`, and `slack` are opt-in ergonomics, recovery, and integration controls: session labeling, a themed startup header, Anthropic fast mode, semantic-stall recovery, and context-safe Slack search/threads/posting with repo-policy injection, `@name` mention resolution, cached emails, and per-call unfurl control.
 
@@ -65,7 +65,7 @@ A 300 KB changelog page never touches your context window - you get a preview an
 | Extension | Tool | What it does |
 | --- | --- | --- |
 | `extensions/fetch.ts` | `fetch` | Retrieve URLs over HTTP(S). HTML -> Markdown (Readability extraction, Turndown conversion). Binary saved untouched to a temp file. GitHub issue/PR/repo/actions-run/actions-job URLs auto-route through `gh` (falls back to HTTP); failed runs/jobs include failed-step logs (best-effort, summary-only otherwise). Same size gate as `fetch`. Behavior lives in `lib/fetch-core.ts`; also exposed as the `pi-quiver fetch` CLI (see [Claude Code support](#claude-code-support)). |
-| `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX/XLSX/XLS to a Markdown bundle on disk (`<stem>.md` + `images/` and spreadsheet `sheets/`) and return a handle (paths, page count, outline, diagnostics) - never inline Markdown. `info` mode inspects first; `pages` selects 1-based pages (DOCX: explicit-page-break segments); every selected PDF/PPTX page or DOCX segment when `pageCount > 1` ends with `--- end of page.page_number=N ---`. Tiers: pymupdf4llm -> PyMuPDF text (degraded) -> unpdf worker (no Python only). Excel -> sheet inventory, full CSVs, bounded previews, and optional rendered views. DOCX converts directly (mammoth, python-docx fallback); LibreOffice pagination marks the degraded route. The Outline lists `L<line>` and `p<page>` per heading. Settings under `quiver.docToMd`. |
+| `extensions/doc_to_md.ts` | `doc_to_md` | Convert a local PDF/DOCX/PPTX/XLSX/XLS, HTML, or image file to a Markdown bundle on disk (`<stem>.md` + `images/` and spreadsheet `sheets/`) and return a handle (paths, page count, outline, diagnostics) - never inline Markdown. `info` inspects PDF/Office inputs; `pages` selects 1-based PDF/Office pages (DOCX: explicit-page-break segments); HTML and image inputs reject both; every selected PDF/PPTX page or DOCX segment when `pageCount > 1` ends with `--- end of page.page_number=N ---`. Tiers: pymupdf4llm -> PyMuPDF text (degraded) -> unpdf worker (no Python only). Excel -> sheet inventory, full CSVs, bounded previews, and optional rendered views. HTML keeps local and `data:` images in the bundle and remote images as links; image inputs keep the original image. Scanned PDF pages keep a page picture on both Python tiers; opt-in OCR needs Tesseract language data. DOCX converts directly (mammoth, python-docx fallback); LibreOffice pagination marks the degraded route. The Outline lists `L<line>` and `p<page>` per heading. Settings under `quiver.docToMd`. |
 | `extensions/session-name.ts` | `/session-name` | Manual + opt-in automatic session naming, naming rules and deny list, long-session revisits, and Ghostty/Herdr tab rename. OFF by default. |
 | `extensions/sword-header.ts` | `/builtin-header` | Themed ASCII startup header replacing pi's default logo. OFF by default. |
 | `extensions/fast-mode.ts` | `/fast` | Inject Anthropic fast-mode (`speed: "fast"` + `anthropic-beta: fast-mode-2026-02-01`) into every Claude Opus 4.8 / Opus 5 request, any thinking level. `--fast` flag + `/fast [on\|off\|status]`. OFF by default. |
@@ -134,6 +134,7 @@ The npm package's bundled JS deps install automatically on `pi install`. A few *
 | --- | --- | --- |
 | `gh` (GitHub CLI, installed + `gh auth login`) | `fetch` GitHub issue/PR/repo/actions-run/actions-job routing | Falls back to an HTTP fetch of the rendered page (private repos hit a login wall). |
 | `uv` (+ managed Python 3.14, fetched on first use) | `doc_to_md` high-fidelity PDF and Excel conversion and DOCX (preferred route), with `pymupdf4llm`, `openpyxl`, `xlrd`, `pillow`, `mammoth`, `markdownify`, and `python-docx` | Falls back to a system Python >= 3.12 or one-time managed venv; PDF degrades to `unpdf` only when no capable Python exists. Excel requires the Python backend (no JS fallback). |
+| Tesseract language data (`tesseract` on `PATH` or `TESSDATA_PREFIX`) | `doc_to_md` OCR with `ocr: true` for scanned pages and images | OCR is skipped and the handle reports `OCR: unavailable` (or an install hint when OCR is off); pages keep their picture. |
 | LibreOffice (`soffice` on `PATH`) | `doc_to_md` PPTX conversion, the DOCX fallback route, and Excel rendered views | PPTX errors with a remedy; DOCX converts directly via the Python backend (LibreOffice fills in when that backend lacks the DOCX packages or its DOCX child exits 1); Excel omits rendered views. |
 
 None is a hard install-time dependency of the package; they are tools you provide in the environment where pi runs.
@@ -304,6 +305,8 @@ Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `
 | `imageFormat` | `png` | Rendered image format: `png` or `jpg`; embedded images retain their extension. |
 | `maxOutputBytes` | `20000000` | Child stdout cap in bytes. |
 | `outlineMaxEntries` | `40` | Heading outline, TOC, or sheet inventory entries in the handle. |
+| `ocr` | `false` | Opt-in OCR for scanned pages and images when Tesseract language data is installed. |
+| `ocrLanguage` | `eng` | Plain `+`-joined Tesseract language codes for OCR. |
 
 A bundle is `<outputDir>/<stem>.md` plus `<outputDir>/images/` and, for spreadsheets with data, `<outputDir>/sheets/`; without `outputDir`, the tool creates a per-call temp root. A conversion owns `<stem>.md.lock` until it atomically publishes the Markdown. An existing `<stem>.md` fails the call unless `overwrite` is set; `overwrite` replaces that Markdown and the files it owns (`images/<stem>-p<N>-<n>.*`, `images/<stem>-s<idx>[-<n>].*`, `sheets/<stem>-s<idx>-<slug>.csv`), nothing else. Temp bundles are caller-owned - the tool never deletes a bundle it produced.
 

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, 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, 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,6 +741,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(`${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 = [];
@@ -754,6 +825,7 @@ 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("    "));
+  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");
@@ -785,8 +857,10 @@ 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. 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" },
@@ -800,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])
@@ -827,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":
@@ -865,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) {
@@ -1247,6 +1325,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 = 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";
@@ -1312,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 });
@@ -1327,11 +1490,63 @@ async function convertDocument(o, signal, seams) {
   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, 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) {
@@ -1441,9 +1656,9 @@ async function convertDocument(o, signal, seams) {
       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 ?? []];
+    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}`);
@@ -1455,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, 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, 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);
@@ -1470,6 +1685,7 @@ 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}`);
@@ -1511,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") {
@@ -1544,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;