pi-quiver 5.2.4 → 5.3.0

package/lib/doc-to-md-core.ts

@@ -1,46 +1,35 @@
 /**
  * doc-to-md core (pi-free)
  *
- * Converts a local PDF, DOCX, or PPTX file to Markdown. Primary engine:
- * pymupdf4llm via ephemeral `uv run --with` (warm-once per process, no repo
- * venv). Fallback: unpdf pure-JS text extraction (degraded, explicitly
- * marked). DOCX/PPTX convert to PDF first via headless soffice, then feed
- * the PDF pipeline. Output over 32 KB or 1000 lines is spilled to a temp
- * .md file with a 60-line preview; smaller content is returned inline.
+ * Converts local PDF, DOCX, PPTX, XLSX, and XLS documents into disk bundles
+ * with concise handles. PDF uses primary pymupdf4llm, PyMuPDF-text fallback,
+ * then unpdf when no Python backend exists. DOCX/PPTX convert through
+ * headless soffice before entering the PDF pipeline.
  */
 
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, renameSync, rmSync, statSync } from "node:fs";
+import { type ChildProcess, spawn } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
-import { createHash } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { extractText, getDocumentProxy } from "unpdf";
+import { type Bundle, abortBundle, commitBundle, openBundle, publishSheetImages, publishStaged, rewriteImageLinks, tempBundleRoot, validateImageLinks } from "./doc-to-md-bundle.ts";
+import { type Engine, type HandleData, type InfoData, type Tier, formatHandle, formatInfoHandle, scanOutline, type SheetInfo, type TocEntry } from "./doc-to-md-handle.ts";
+import { type DocToMdOptions, type InputType, TUNABLE_DEFAULTS, classifyInput, sanitizeStem } from "./doc-to-md-options.ts";
+
+export * from "./doc-to-md-options.ts";
+export { compactRanges, formatHandle, formatInfoHandle, formatSize, scanOutline } from "./doc-to-md-handle.ts";
+export type { Engine, HandleData, InfoData, OutlineEntry, SheetInfo, Tier, TocEntry } from "./doc-to-md-handle.ts";
 
 // --- Types ---
 
-export type InputType = "pdf" | "docx" | "pptx";
-export type Engine = "pymupdf4llm" | "unpdf";
+export const PACKAGE_PINS = { pymupdf4llm: TUNABLE_DEFAULTS.pymupdfVersion, openpyxl: "3.1.5", xlrd: "2.0.2", pillow: "12.3.0" } as const;
+export const KILL_GRACE_MS = 2000;
+export const VENV_DIR_NAME = "doc-to-md-venv-v2";
+export const LEGACY_VENV_DIR_NAME = "pymupdf-venv";
+const STDERR_CAP = 1_000_000;
+export const OUTPUT_MAX_BYTES = 20_000_000;
 
-export interface DocToMdConfig {
-	pymupdfVersion: string;
-	warmTimeoutMs: number;
-	convertTimeoutMs: number;
-	sofficeTimeoutMs: number;
-}
-
-export interface DocToMdDetails {
-	path: string;
-	inputType: InputType;
-	engine: Engine;
-	backend: BackendKind;
-	pymupdfVersion?: string;
-	degraded: boolean;
-	bytes: number;
-	lines: number;
-	spilled: boolean;
-	file?: string;
-}
+export interface BackendConfig { pymupdfVersion: string; warmTimeoutMs: number; }
 
 export interface CappedResult {
 	stdout: string;
@@ -50,110 +39,25 @@ export interface CappedResult {
 	capped: boolean;
 }
 
-// --- Constants ---
-
-const DEFAULT_PYMUPDF_VERSION = "1.27.2.3";
-const WARM_TIMEOUT_DEFAULT = 120_000;
-const CONVERT_TIMEOUT_DEFAULT = 60_000;
-const SOFFICE_TIMEOUT_DEFAULT = 120_000;
-const STDERR_CAP = 1_000_000;
-const INLINE_MAX_BYTES = 32_000;
-const INLINE_MAX_LINES = 1_000;
-const PREVIEW_LINES = 60;
-const PREVIEW_MAX_BYTES = 4_000;
-const VERSION_RE = /^\d+(\.\d+)*$/;
-const PAGE_SEP = "\n\n---\n\n";
-export const OUTPUT_MAX_BYTES = 20_000_000;
-
-export const DEGRADED_MARKER =
-	"[Note: degraded extraction via unpdf — structure (tables/headings) not preserved]";
-
-// --- Config ---
-
-export function parseConfig(env: NodeJS.ProcessEnv): DocToMdConfig {
-	const version = env.PI_DOC_TO_MD_PYMUPDF_VERSION ?? DEFAULT_PYMUPDF_VERSION;
-	if (!VERSION_RE.test(version)) {
-		throw new Error(`PI_DOC_TO_MD_PYMUPDF_VERSION must be digits and dots (got "${version}")`);
-	}
-	const num = (key: string, def: number): number => {
-		const raw = env[key];
-		if (raw === undefined) return def;
-		const n = Number.parseInt(raw, 10);
-		if (!Number.isInteger(n) || n <= 0) throw new Error(`${key} must be a positive integer (got "${raw}")`);
-		return n;
-	};
-	return {
-		pymupdfVersion: version,
-		warmTimeoutMs: num("PI_DOC_TO_MD_WARM_TIMEOUT_MS", WARM_TIMEOUT_DEFAULT),
-		convertTimeoutMs: num("PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", CONVERT_TIMEOUT_DEFAULT),
-		sofficeTimeoutMs: num("PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", SOFFICE_TIMEOUT_DEFAULT),
-	};
-}
-
-// --- Input classification ---
-
-const SUPPORTED: Record<string, InputType> = { ".pdf": "pdf", ".docx": "docx", ".pptx": "pptx" };
-
-export function classifyInput(filePath: string): InputType {
-	const ext = extname(filePath).toLowerCase();
-	const t = SUPPORTED[ext];
-	if (!t) throw new Error(`Unsupported file type "${ext || "(none)"}"; supported: .pdf, .docx, .pptx`);
-	return t;
-}
-
-// --- Size gate ---
-
-export function applyGate(body: string): { spill: boolean; bytes: number; lines: number } {
-	const bytes = Buffer.byteLength(body, "utf8");
-	const lines = body.length ? body.split("\n").length : 0;
-	const spill = body.length > 0 && (bytes > INLINE_MAX_BYTES || lines > INLINE_MAX_LINES);
-	return { spill, bytes, lines };
-}
-
-// --- Markdown helpers ---
-
-export function withMarker(md: string, degraded: boolean): string {
-	return degraded ? `${DEGRADED_MARKER}\n\n${md}` : md;
-}
-
-export function pagesToMarkdown(pages: string[]): string {
-	return pages.map((p) => p.trim()).filter((p) => p.length > 0).join(PAGE_SEP);
-}
-
-// --- Temp file helpers ---
+// --- Subprocess argv builders ---
 
-export function tempFilePath(inputPath: string, ext: string): string {
-	const dir = join(tmpdir(), "pi-doc-to-md");
-	mkdirSync(dir, { recursive: true });
-	const base = basename(inputPath).replace(/\.[^.]+$/, "").replace(/[^\w.-]+/g, "-");
-	const hash = createHash("sha1").update(resolve(inputPath)).digest("hex").slice(0, 8);
-	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-	return join(dir, `${stamp}-${base}-${hash}.${ext}`);
+function withArgs(cfg: BackendConfig): string[] {
+	return ["--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--with", `openpyxl==${PACKAGE_PINS.openpyxl}`, "--with", `xlrd==${PACKAGE_PINS.xlrd}`, "--with", `pillow==${PACKAGE_PINS.pillow}`];
 }
 
-export function spillToFile(inputPath: string, body: string): string {
-	const file = tempFilePath(inputPath, "md");
-	writeFileSync(file, `${body}\n`, "utf8");
-	return file;
+export function pipInstallArgs(cfg: BackendConfig): string[] {
+	return ["-m", "pip", "install", `pymupdf4llm==${cfg.pymupdfVersion}`, `openpyxl==${PACKAGE_PINS.openpyxl}`, `xlrd==${PACKAGE_PINS.xlrd}`, `pillow==${PACKAGE_PINS.pillow}`];
 }
 
-export function buildPreview(body: string): string {
-	let preview = body.split("\n").slice(0, PREVIEW_LINES).join("\n");
-	if (preview.length > PREVIEW_MAX_BYTES) {
-		preview = `${preview.slice(0, PREVIEW_MAX_BYTES)}\n…[preview truncated]`;
-	}
-	return preview;
+export function warmArgs(cfg: BackendConfig): string[] {
+	return ["run", ...withArgs(cfg), "--python", "3.14", "python", "-c", "import pymupdf4llm, openpyxl, xlrd, PIL"];
 }
 
-// --- Subprocess argv builders ---
-
-export function warmArgs(cfg: DocToMdConfig): string[] {
-	return ["run", "--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--python", "3.14", "python", "-c", "import pymupdf4llm"];
+export function uvChildArgs(cfg: BackendConfig, script: string, mode: string): string[] {
+	return ["run", ...withArgs(cfg), "--python", "3.14", "python", script, mode];
 }
 
-export function convertArgs(cfg: DocToMdConfig, scriptPath: string, pdfPath: string): string[] {
-	return ["run", "--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--python", "3.14", "python", scriptPath, pdfPath];
-}
+export function pythonChildArgs(script: string, mode: string): string[] { return [script, mode]; }
 
 export function soffArgs(src: string, profileDir: string, outDir: string): string[] {
 	return [
@@ -166,26 +70,43 @@ export function soffArgs(src: string, profileDir: string, outDir: string): strin
 
 // --- Subprocess runner ---
 
+const LIVE = new Set<ChildProcess>();
+
+function killTree(child: ChildProcess): void {
+	if (child.pid === undefined) return;
+	try {
+		if (process.platform === "win32") spawn("taskkill", ["/T", "/F", "/PID", String(child.pid)], { stdio: "ignore" });
+		else process.kill(-child.pid, "SIGKILL");
+	} catch { try { child.kill("SIGKILL"); } catch { /* already gone */ } }
+}
+
+process.on("exit", () => { for (const c of LIVE) killTree(c); });
+
 export async function runCapped(
 	cmd: string,
 	args: string[],
-	opts: { timeoutMs: number; capBytes: number; env?: NodeJS.ProcessEnv; signal?: AbortSignal },
+	opts: { timeoutMs: number; capBytes: number; env?: NodeJS.ProcessEnv; signal?: AbortSignal; stdin?: string },
 ): Promise<CappedResult> {
 	return new Promise((resolveP) => {
 		let settled = false;
 		let timedOut = false;
 		let capped = false;
+		let timer: ReturnType<typeof setTimeout> | undefined;
+		let graceTimer: ReturnType<typeof setTimeout> | undefined;
 		const stdoutChunks: Buffer[] = [];
 		const stderrChunks: Buffer[] = [];
 		let stdoutBytes = 0;
 		let stderrBytes = 0;
 
-		const child = spawn(cmd, args, { env: opts.env ?? process.env });
+		const child = spawn(cmd, args, { env: opts.env ?? process.env, detached: process.platform !== "win32", stdio: ["pipe", "pipe", "pipe"] });
+		LIVE.add(child);
 
 		const finish = (code: number | null) => {
 			if (settled) return;
 			settled = true;
+			LIVE.delete(child);
 			clearTimeout(timer);
+			clearTimeout(graceTimer);
 			opts.signal?.removeEventListener("abort", onAbort);
 			resolveP({
 				stdout: Buffer.concat(stdoutChunks).toString("utf8"),
@@ -196,13 +117,20 @@ export async function runCapped(
 			});
 		};
 
-		const kill = () => child.kill("SIGKILL");
+		const kill = () => {
+			killTree(child);
+			graceTimer ??= setTimeout(() => finish(null), KILL_GRACE_MS);
+		};
 
 		const onAbort = () => { kill(); };
 		if (opts.signal?.aborted) { kill(); }
 		else opts.signal?.addEventListener("abort", onAbort);
 
-		const timer = setTimeout(() => { timedOut = true; kill(); }, opts.timeoutMs);
+		timer = setTimeout(() => { timedOut = true; kill(); }, opts.timeoutMs);
+
+		child.stdin.on("error", (err: NodeJS.ErrnoException) => { if (err.code !== "EPIPE") throw err; });
+		child.stdin.write(opts.stdin ?? "");
+		child.stdin.end();
 
 		child.stdout.on("data", (chunk: Buffer) => {
 			if (capped) return;
@@ -252,56 +180,8 @@ export function findPackageRoot(startDir: string): string {
 	}
 }
 
-function scriptPath(): string {
-	return join(findPackageRoot(dirname(fileURLToPath(import.meta.url))), "scripts", "pdf_to_md.py");
-}
-
-// Deliberate local copy of the host package's formatSize - this core must stay pi-free (see test/layout.test.ts purity check).
-function formatSize(bytes: number): string {
-	if (bytes < 1024) {
-		return `${bytes}B`;
-	} else if (bytes < 1024 * 1024) {
-		return `${(bytes / 1024).toFixed(1)}KB`;
-	} else {
-		return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-	}
-}
-
-async function convertViaUv(cfg: DocToMdConfig, pdfPath: string, signal?: AbortSignal): Promise<string> {
-	const r = await runCapped("uv", convertArgs(cfg, scriptPath(), pdfPath), {
-		timeoutMs: cfg.convertTimeoutMs, capBytes: OUTPUT_MAX_BYTES, signal,
-	});
-	if (r.timedOut || r.capped || r.code !== 0) {
-		throw new Error(`code=${r.code} timedOut=${r.timedOut} capped=${r.capped}: ${r.stderr.slice(0, 500)}`);
-	}
-	return r.stdout;
-}
-
-async function convertViaPython(cfg: DocToMdConfig, exe: string, pdfPath: string, signal?: AbortSignal): Promise<string> {
-	const r = await runCapped(exe, pythonConvertArgs(scriptPath(), pdfPath), {
-		timeoutMs: cfg.convertTimeoutMs, capBytes: OUTPUT_MAX_BYTES, signal,
-	});
-	if (r.timedOut || r.capped || r.code !== 0) {
-		throw new Error(`code=${r.code} timedOut=${r.timedOut} capped=${r.capped}: ${r.stderr.slice(0, 500)}`);
-	}
-	return r.stdout;
-}
-
-async function convertViaUnpdf(pdfPath: string, cfg: DocToMdConfig, signal?: AbortSignal): Promise<string> {
-	if (signal?.aborted) throw new Error("aborted");
-	const buf = readFileSync(pdfPath);
-	const work = (async () => {
-		const pdf = await getDocumentProxy(new Uint8Array(buf));
-		const { text } = await extractText(pdf, { mergePages: false });
-		const md = pagesToMarkdown(text);
-		if (Buffer.byteLength(md, "utf8") > OUTPUT_MAX_BYTES) throw new Error("unpdf output exceeded cap");
-		return md;
-	})();
-	let timer: NodeJS.Timeout;
-	const timeout = new Promise<never>((_, rej) => {
-		timer = setTimeout(() => rej(new Error("unpdf conversion timed out")), cfg.convertTimeoutMs);
-	});
-	try { return await Promise.race([work, timeout]); } finally { clearTimeout(timer!); }
+export function scriptPath(): string {
+	return join(findPackageRoot(dirname(fileURLToPath(import.meta.url))), "scripts", "doc_to_md.py");
 }
 
 // --- Backend resolver ---
@@ -309,10 +189,17 @@ async function convertViaUnpdf(pdfPath: string, cfg: DocToMdConfig, signal?: Abo
 export const PROBE_PROGRAM = `import sys
 print("PY", sys.version_info[0], sys.version_info[1])
 try:
-    import pymupdf4llm
-    print("PKG", pymupdf4llm.__version__)
+    # pymupdf4llm.__version__ >= 1.27.0
+    import pymupdf, pymupdf4llm
+    v = tuple(int(x) for x in pymupdf4llm.__version__.split(".")[:3])
+    print("PDF", "yes" if v >= (1, 27, 0) else "no")
 except Exception:
-    print("PKG", "none")
+    print("PDF", "no")
+try:
+    import openpyxl, xlrd, PIL
+    print("XLSX", "yes")
+except Exception:
+    print("XLSX", "no")
 `;
 export const PROBE_TIMEOUT_MS = 5000;
 
@@ -321,19 +208,18 @@ export function probeArgs(): string[] {
 }
 export const PYTHON_CANDIDATES = ["python3", "python"] as const;
 
-export type BackendKind = "uv" | "python" | "venv" | "unpdf";
+export type BackendKind = "uv" | "python" | "venv" | "none";
 export type Backend =
-	| { kind: "uv" }
-	| { kind: "python"; exe: string; version: string }
-	| { kind: "venv"; exe: string; version: string }
+	| { kind: "uv"; pdf: true; xlsx: true }
+	| { kind: "python"; exe: string; pdf: boolean; xlsx: boolean }
+	| { kind: "venv"; exe: string; pdf: true; xlsx: true }
 	| { kind: "none"; reason: string };
 
-export interface ProbeResult { major: number; minor: number; pkg: string | null; }
+export interface ProbeResult { major: number; minor: number; pdf: boolean; xlsx: boolean; }
 
 export function parseProbeOutput(stdout: string): ProbeResult | null {
-	const m = stdout.match(/^PY (\d+) (\d+)\r?\nPKG (\S+)\s*$/);
-	if (!m) return null;
-	return { major: Number(m[1]), minor: Number(m[2]), pkg: m[3] === "none" ? null : m[3] };
+	const m = stdout.match(/^PY (\d+) (\d+)\r?\nPDF (yes|no)\r?\nXLSX (yes|no)\s*$/);
+	return m ? { major: Number(m[1]), minor: Number(m[2]), pdf: m[3] === "yes", xlsx: m[4] === "yes" } : null;
 }
 
 export function meetsFloor(p: ProbeResult): boolean {
@@ -350,10 +236,6 @@ export function venvPython(venvDir: string, platform: NodeJS.Platform): string {
 	return platform === "win32" ? join(venvDir, "Scripts", "python.exe") : join(venvDir, "bin", "python");
 }
 
-export function pythonConvertArgs(script: string, pdfPath: string): string[] {
-	return [script, pdfPath];
-}
-
 export type RunFn = (cmd: string, args: string[], opts: { timeoutMs: number; capBytes: number; env?: NodeJS.ProcessEnv; signal?: AbortSignal }) => Promise<CappedResult>;
 
 export interface ResolverDeps {
@@ -369,15 +251,26 @@ export interface ResolverDeps {
 
 const tail = (s: string) => s.slice(-500).trim();
 
-export async function resolveBackend(cfg: DocToMdConfig, deps: ResolverDeps, signal?: AbortSignal): Promise<Backend> {
+export async function resolveBackend(cfg: BackendConfig, deps: ResolverDeps, signal?: AbortSignal): Promise<Backend> {
 	if (signal?.aborted) throw new Error("aborted");
-	const warm = await deps.run("uv", warmArgs(cfg), { timeoutMs: cfg.warmTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
+	const deadline = deps.now() + cfg.warmTimeoutMs;
+	const left = () => Math.max(1, deadline - deps.now());
+	const expired = (tmp?: string): Extract<Backend, { kind: "none" }> | null => {
+		if (deadline - deps.now() > 0) return null;
+		if (tmp) deps.rmrf(tmp);
+		return { kind: "none", reason: `backend discovery exceeded warmTimeoutMs (${cfg.warmTimeoutMs}ms) - raise warmTimeoutMs, or install uv` };
+	};
+	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" };
+	if (warm.code === 0 && !warm.timedOut) return { kind: "uv", pdf: true, xlsx: true };
 	const uvAbsent = warm.code === null && !warm.timedOut; // spawn error (ENOENT)
 
-	const probe = async (exe: string): Promise<ProbeResult | null> => {
-		const r = await deps.run(exe, probeArgs(), { timeoutMs: PROBE_TIMEOUT_MS, capBytes: 4000, env: deps.env, signal });
+	type ProbeOutcome = ProbeResult | Extract<Backend, { kind: "none" }> | null;
+	const isDeadline = (result: ProbeOutcome): result is Extract<Backend, { kind: "none" }> => result !== null && "kind" in result;
+	const probe = async (exe: string, tmp?: string): Promise<ProbeOutcome> => {
+		const timeout = expired(tmp);
+		if (timeout) return timeout;
+		const r = await deps.run(exe, probeArgs(), { timeoutMs: Math.min(PROBE_TIMEOUT_MS, left()), capBytes: 4000, env: deps.env, signal });
 		if (signal?.aborted) throw new Error("aborted");
 		if (r.code !== 0 || r.timedOut) return null;
 		return parseProbeOutput(r.stdout);
@@ -386,45 +279,57 @@ export async function resolveBackend(cfg: DocToMdConfig, deps: ResolverDeps, sig
 	let eligible: { exe: string; version: string } | null = null;
 	for (const exe of PYTHON_CANDIDATES) {
 		const p = await probe(exe);
+		if (isDeadline(p)) return p;
 		if (!p || !meetsFloor(p)) continue;
-		if (p.pkg) return { kind: "python", exe, version: p.pkg };
+		if (p.pdf) return { kind: "python", exe, pdf: true, xlsx: p.xlsx };
 		eligible ??= { exe, version: `${p.major}.${p.minor}` };
 	}
 
-	const venvDir = join(deps.cacheRoot, "pymupdf-venv");
+	const venvDir = join(deps.cacheRoot, VENV_DIR_NAME);
 	const venvExe = venvPython(venvDir, deps.platform);
 	const cached = await probe(venvExe);
-	if (cached && meetsFloor(cached) && cached.pkg) return { kind: "venv", exe: venvExe, version: cached.pkg };
+	if (isDeadline(cached)) return cached;
+	if (cached && meetsFloor(cached) && cached.pdf && cached.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
 
 	if (eligible) {
 		const recheck = await probe(venvExe); // a competing process may have published since the first probe
-		if (recheck && meetsFloor(recheck) && recheck.pkg) return { kind: "venv", exe: venvExe, version: recheck.pkg };
+		if (isDeadline(recheck)) return recheck;
+		if (recheck && meetsFloor(recheck) && recheck.pdf && recheck.xlsx) return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
 		// Build in a sibling tmp dir without touching venvDir - a concurrent process can never probe a half-built venv.
 		const tmp = `${venvDir}.tmp-${deps.pid}`;
-		const deadline = deps.now() + cfg.warmTimeoutMs;
-		const left = () => Math.max(1, deadline - deps.now());
 		const bootFail = (stderr: string): Backend => {
 			deps.rmrf(tmp);
 			return { kind: "none", reason: `python ${eligible!.version} found but venv bootstrap failed: ${tail(stderr)} - install python3-venv, or uv` };
 		};
+		const mkTimeout = expired(tmp);
+		if (mkTimeout) return mkTimeout;
 		const mk = await deps.run(eligible.exe, ["-m", "venv", tmp], { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
 		if (signal?.aborted) throw new Error("aborted");
 		if (mk.code !== 0 || mk.timedOut) return bootFail(mk.stderr);
-		const pip = await deps.run(venvPython(tmp, deps.platform), ["-m", "pip", "install", `pymupdf4llm==${cfg.pymupdfVersion}`], { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
+		const pipTimeout = expired(tmp);
+		if (pipTimeout) return pipTimeout;
+		const pip = await deps.run(venvPython(tmp, deps.platform), pipInstallArgs(cfg), { timeoutMs: left(), capBytes: OUTPUT_MAX_BYTES, env: deps.env, signal });
 		if (signal?.aborted) throw new Error("aborted");
 		if (pip.code !== 0 || pip.timedOut) return bootFail(pip.stderr);
 		const publish = (): boolean => {
 			try { deps.rename(tmp, venvDir); return true; } catch { return false; }
 		};
-		if (publish()) return { kind: "venv", exe: venvExe, version: cfg.pymupdfVersion };
+		if (publish()) {
+			deps.rmrf(join(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
+			return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+		}
 		// Rename failed - a competing process may have published first, or venvDir holds a stale/broken dir.
-		const winner = await probe(venvExe);
-		if (winner && meetsFloor(winner) && winner.pkg) {
+		const winner = await probe(venvExe, tmp);
+		if (isDeadline(winner)) return winner;
+		if (winner && meetsFloor(winner) && winner.pdf && winner.xlsx) {
 			deps.rmrf(tmp); // healthy winner - clean up our loser
-			return { kind: "venv", exe: venvExe, version: winner.pkg };
+			return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
 		}
 		deps.rmrf(venvDir); // unhealthy/absent dest - clear it and retry the rename once
-		if (publish()) return { kind: "venv", exe: venvExe, version: cfg.pymupdfVersion };
+		if (publish()) {
+			deps.rmrf(join(deps.cacheRoot, LEGACY_VENV_DIR_NAME));
+			return { kind: "venv", exe: venvExe, pdf: true, xlsx: true };
+		}
 		return bootFail("rename after competing bootstrap");
 	}
 
@@ -448,7 +353,7 @@ function realDeps(): ResolverDeps {
 	};
 }
 
-export function getBackend(cfg: DocToMdConfig, deps?: ResolverDeps, signal?: AbortSignal): Promise<Backend> {
+export function getBackend(cfg: BackendConfig, deps?: ResolverDeps, signal?: AbortSignal): Promise<Backend> {
 	if (!backendPromise) {
 		const promise = resolveBackend(cfg, deps ?? realDeps(), signal);
 		backendPromise = promise;
@@ -463,7 +368,7 @@ export function resetBackendCacheForTests(): void {
 }
 
 export async function convertOffice(
-	cfg: DocToMdConfig,
+	sofficeTimeoutMs: number,
 	src: string,
 	signal?: AbortSignal,
 	run: RunFn = runCapped,
@@ -477,7 +382,7 @@ export async function convertOffice(
 	};
 	try {
 		const env = { ...process.env, SAL_USE_VCLPLUGIN: "svp", OOO_DISABLE_RECOVERY: "1", SAL_NO_MOUSEGRABS: "1" };
-		const r = await run("soffice", soffArgs(src, profileDir, outDir), { timeoutMs: cfg.sofficeTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env, signal });
+		const r = await run("soffice", soffArgs(src, profileDir, outDir), { timeoutMs: sofficeTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env, signal });
 		if (signal?.aborted) throw new Error("aborted");
 		if (r.code === null && !r.timedOut) {
 			throw new Error("LibreOffice (soffice) is required to convert .docx/.pptx but was not found on PATH. Install LibreOffice or convert the file to PDF first.");
@@ -493,99 +398,154 @@ export async function convertOffice(
 	} catch (e) { cleanup(); throw e; }
 }
 
-export interface PipelineSeams {
-	backend: (cfg: DocToMdConfig) => Promise<Backend>;
-	convertPymupdf: (cfg: DocToMdConfig, backend: Backend, pdfPath: string, signal?: AbortSignal) => Promise<string>;
-	convertUnpdf: (pdfPath: string, cfg: DocToMdConfig, signal?: AbortSignal) => Promise<string>;
-}
 
-export async function runPipeline(
-	cfg: DocToMdConfig,
-	inputPath: string,
-	type: InputType,
-	signal?: AbortSignal,
-	seams?: Partial<PipelineSeams>,
-): Promise<{ markdown: string; engine: Engine; degraded: boolean; fallbackReason?: string; backend: BackendKind; pymupdfVersion?: string }> {
-	const s: PipelineSeams = {
-		backend: (c) => getBackend(c, undefined, signal),
-		convertPymupdf: (c, b, p, sig) => (b.kind === "uv" ? convertViaUv(c, p, sig) : convertViaPython(c, (b as { exe: string }).exe, p, sig)),
-		convertUnpdf: convertViaUnpdf,
-		...seams,
-	};
-	let pdfPath = inputPath;
-	let cleanup: (() => void) | null = null;
-	if (type === "docx" || type === "pptx") {
-		const o = await convertOffice(cfg, inputPath, signal);
-		pdfPath = o.pdfPath;
-		cleanup = o.cleanup;
-	}
-	try {
-		const backend = await s.backend(cfg);
-		if (backend.kind === "none") {
-			return { markdown: await s.convertUnpdf(pdfPath, cfg, signal), engine: "unpdf", degraded: true, fallbackReason: backend.reason, backend: "unpdf" };
-		}
-		try {
-			const markdown = await s.convertPymupdf(cfg, backend, pdfPath, signal);
-			return {
-				markdown, engine: "pymupdf4llm", degraded: false, backend: backend.kind,
-				...(backend.kind === "python" || backend.kind === "venv" ? { pymupdfVersion: backend.version } : {}),
-			};
-		} catch (e) {
-			const msg = e instanceof Error ? e.message : String(e);
-			return {
-				markdown: await s.convertUnpdf(pdfPath, cfg, signal), engine: "unpdf", degraded: true,
-				fallbackReason: `pymupdf4llm (${backend.kind}) conversion failed: ${msg} - fell back to unpdf`, backend: "unpdf",
-			};
-		}
-	} finally {
-		cleanup?.();
+// --- Conversion tiers and bundle orchestration ---
+
+export const DEGRADED_TEXT = "PyMuPDF text extraction - layout/tables not preserved";
+export const DEGRADED_UNPDF = "unpdf text extraction - structure not preserved";
+export const EXCEL_REMEDY = "Remedy: install uv, or pip install openpyxl xlrd pillow";
+
+export type Mode = "info" | "pdf-primary" | "pdf-fallback" | "xlsx" | "pdf-text";
+export interface TierJson { markdown?: string; pages?: number[]; pageCount?: number; emptyPages?: number[]; failedPages?: { page: number; error: string }[]; notes?: string[]; images?: { sheetIndex: number; file: string }[]; metadata?: Record<string, string>; toc?: [number, string, number][]; sheets?: SheetInfo[]; }
+export type TierResult = { ok: true; json: TierJson } | { ok: false; reason: string; detail?: string } | { ok: false; userError: string; pageCount?: number };
+
+export interface PipelineSeams {
+	backend: (cfg: BackendConfig) => Promise<Backend>;
+	runTier: (mode: Mode, childOptions: Record<string, unknown>, bundle: Pick<Bundle, "stagingDir">, signal: AbortSignal | undefined, timeoutMs: number, backend: Backend) => Promise<TierResult>;
+}
+
+export function resolveUnpdfWorker(candidates: string[], exists: (path: string) => boolean): string {
+	for (const candidate of candidates) if (exists(candidate)) return candidate;
+	throw new Error("unpdf worker not found");
+}
+
+function unpdfWorkerPath(): string {
+	const here = dirname(fileURLToPath(import.meta.url));
+	return resolveUnpdfWorker([
+		join(findPackageRoot(here), "dist", "lib", "unpdf-worker.js"),
+		join(here, "unpdf-worker.js"),
+		join(here, "unpdf-worker.ts"),
+	], existsSync);
+}
+
+async function runTierReal(mode: Mode, childOptions: Record<string, unknown>, _b: Pick<Bundle, "stagingDir">, signal: AbortSignal | undefined, timeoutMs: number, backend: Backend): Promise<TierResult> {
+	const cfg = { pymupdfVersion: String(childOptions.pymupdfVersion), warmTimeoutMs: 0 };
+	let cmd: string, args: string[];
+	if (mode === "pdf-text" || (mode === "info" && backend.kind === "none")) { cmd = process.execPath; args = [unpdfWorkerPath(), mode]; }
+	else if (backend.kind === "uv") { cmd = "uv"; args = uvChildArgs(cfg, scriptPath(), mode); }
+	else if (backend.kind === "python" || backend.kind === "venv") { cmd = backend.exe; args = pythonChildArgs(scriptPath(), mode); }
+	else return { ok: false, reason: backend.reason };
+	const r = await runCapped(cmd, args, { timeoutMs, capBytes: Number(childOptions.maxOutputBytes), signal, stdin: JSON.stringify(childOptions) });
+	if (signal?.aborted) return { ok: false, reason: "aborted" };
+	if (r.timedOut) return { ok: false, reason: `timeout after ${timeoutMs}ms` };
+	if (r.capped) return { ok: false, reason: "output exceeded maxOutputBytes" };
+	const detail = r.stderr.slice(-300).trim();
+	let json: TierJson & { error?: string };
+	try { json = JSON.parse(r.stdout); } catch {
+		return r.code === 0 ? { ok: false, reason: "invalid-json" } : { ok: false, reason: `exit ${r.code ?? -1}`, ...(detail ? { detail } : {}) };
 	}
+	if (r.code === 3) return { ok: false, userError: json.error ?? "user error", ...(json.pageCount !== undefined ? { pageCount: json.pageCount } : {}) };
+	if (r.code !== 0) return { ok: false, reason: `exit ${r.code ?? -1}`, ...(detail ? { detail } : {}) };
+	return { ok: true, json };
 }
 
-// --- Public entry point ---
+export interface ConvertOutcome { output: string; details: DocToMdDetails; }
+export interface DocToMdDetails extends HandleData {
+	path: string;
+	backend: BackendKind;
+	pymupdfVersion: string;
+	inputType: InputType;
+	file: string;
+	outputDir: string;
+}
 
-export interface ConvertOutcome {
-	output: string;
-	details: DocToMdDetails;
+function detailSuffix(r: Extract<TierResult, { ok: false; reason: string }>): string {
+	return r.detail ? ` (${r.detail})` : "";
 }
 
-export async function convertDocument(
-	path: string,
-	cfg: DocToMdConfig,
-	signal?: AbortSignal,
-	seams?: Partial<PipelineSeams>,
-): Promise<ConvertOutcome> {
-	const inputPath = resolve(path);
+export async function convertDocument(o: DocToMdOptions, signal?: AbortSignal, seams?: Partial<PipelineSeams>): Promise<ConvertOutcome> {
+	const s: PipelineSeams = { backend: (c) => getBackend(c, undefined, signal), runTier: runTierReal, ...seams };
+	const inputPath = resolve(o.path);
 	const st = statSync(inputPath, { throwIfNoEntry: false });
-	if (!st || !st.isFile()) throw new Error(`Not a readable file: ${path}`);
+	if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
 	const type = classifyInput(inputPath);
-	const { markdown, engine, degraded, fallbackReason, backend, pymupdfVersion } = await runPipeline(cfg, inputPath, type, signal, seams);
-	// The formatter's output carries no trailing newline (the CLI appends exactly one); engines vary here, so normalize once.
-	const body = withMarker(markdown, degraded).replace(/\s+$/, "");
-	const { spill, bytes, lines } = applyGate(body);
-	const details: DocToMdDetails = { path: inputPath, inputType: type, engine, backend, ...(pymupdfVersion !== undefined ? { pymupdfVersion } : {}), degraded, bytes, lines, spilled: spill };
-	const header: string[] = [
-		`Source: ${inputPath}`,
-		`Type: ${type}  Engine: ${engine}${degraded ? " (degraded fallback)" : ""}`,
-	];
-	if (fallbackReason) header.push(`Fallback-Reason: ${fallbackReason}`);
-	// The formatter's output carries no trailing newline (the CLI appends exactly one); strip once more on the composed string, since an empty body leaves a trailing blank-separator newline.
-	const compose = (parts: string[]) => parts.join("\n").replace(/\n+$/, "");
-	if (!spill) {
-		return { output: compose([...header, `Length: ${bytes} bytes, ${lines} lines`, "", body]), details };
-	}
-	const file = spillToFile(inputPath, body);
-	return {
-		output: compose([
-			...header,
-			`Body: ${formatSize(bytes)} across ${lines} lines — written to file (too large to inline)`,
-			`Saved-To: ${file}`,
-			"",
-			"Read slices of this file with the read tool (offset/limit) or grep it; do not read the whole file unless you must. Markdown is grep-able by heading (^#).",
-			"",
-			"----- preview (first 60 lines) -----",
-			buildPreview(body),
-		]),
-		details: { ...details, spilled: true, file },
-	};
+	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 });
+	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}`);
+	const stem = sanitizeStem(basename(inputPath, extname(inputPath)));
+	const b = openBundle(o.outputDir ? resolve(o.outputDir) : tempBundleRoot(), stem, o.overwrite);
+	let office: { pdfPath: string; cleanup: () => void } | null = null;
+	try {
+		let pdfPath = inputPath;
+		if (type === "docx" || type === "pptx") { office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal); pdfPath = office.pdfPath; }
+		const base = { path: pdfPath, pages: o.pages, stagingDir: b.stagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxCellsPerSheet: o.maxCellsPerSheet, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion };
+		let tier: Tier, engine: Engine, json: TierJson, degraded: string | null = null, fallbackReason: string | null = null;
+		if (isExcel) {
+			const r = await s.runTier("xlsx", base, b, signal, o.excelTimeoutMs, backend);
+			if (!r.ok) {
+				if ("userError" in r) throw new Error(r.userError);
+				const remedy = r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes" ? ". Remedy: raise excelTimeoutMs or lower maxCellsPerSheet" : "";
+				throw new Error(`Excel conversion failed: ${r.reason}${detailSuffix(r)}${remedy}`);
+			}
+			publishSheetImages(b);
+			tier = "excel"; engine = type === "xls" ? "xlrd" : "openpyxl"; json = r.json;
+		} else if (backend.kind === "none") {
+			const r = await s.runTier("pdf-text", base, b, signal, o.primaryTimeoutMs, backend);
+			if (!r.ok) throw new Error("userError" in r ? r.userError : `Conversion failed: unpdf ${r.reason}${detailSuffix(r)}`);
+			tier = "unpdf"; engine = "unpdf"; json = r.json; degraded = DEGRADED_UNPDF;
+		} else {
+			const p = await s.runTier("pdf-primary", base, b, signal, o.primaryTimeoutMs, backend);
+			const kept = publishStaged(b);
+			if (p.ok) { tier = "primary"; engine = "pymupdf4llm"; json = p.json; }
+			else if ("userError" in p) throw new Error(p.userError);
+			else {
+				if (signal?.aborted) throw new Error("aborted");
+				const keepPages = Object.fromEntries([...kept.entries()].map(([k, v]) => [String(k), v]));
+				const f = await s.runTier("pdf-fallback", { ...base, keepPages }, b, signal, o.fallbackTimeoutMs, backend);
+				publishStaged(b);
+				if (!f.ok) throw new Error("userError" in f ? f.userError : `Conversion failed: primary ${p.reason}; fallback ${f.reason}${detailSuffix(f)}`);
+				tier = "fallback"; engine = "pymupdf-text"; json = f.json; degraded = DEGRADED_TEXT; fallbackReason = `primary ${p.reason}`;
+			}
+		}
+		let body = rewriteImageLinks(json.markdown ?? "", b.sourceMap);
+		validateImageLinks(body, b.manifest);
+		const head: string[] = [];
+		if (degraded) head.push(`Degraded: ${degraded}`);
+		if (fallbackReason) head.push(`Fallback-Reason: ${fallbackReason}`);
+		if (json.failedPages?.length) head.push(`Failed pages: ${json.failedPages.map((f) => `${f.page} (${f.error})`).join("; ")}`);
+		if (json.emptyPages?.length) head.push(`Empty pages: ${json.emptyPages.join(", ")}`);
+		for (const n of json.notes ?? []) head.push(`Notes: ${n}`);
+		const markdown = (head.length ? `${head.join("\n")}\n\n` : "") + body;
+		commitBundle(b, markdown);
+		const outline = scanOutline(markdown, o.outlineMaxEntries);
+		const details: DocToMdDetails = { path: inputPath, backend: backend.kind, pymupdfVersion: o.pymupdfVersion, inputType: type, file: b.mdPath, outputDir: b.root, savedTo: b.mdPath, imagesDir: b.imagesDir, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, imageCount: b.manifest.size, bytes: Buffer.byteLength(markdown, "utf8"), lines: markdown.split("\n").length, degraded, fallbackReason, failedPages: (json.failedPages ?? []).map((f) => f.page), emptyPages: json.emptyPages ?? [], notes: json.notes ?? [], outline: outline.entries, outlineTotal: outline.total };
+		return { output: formatHandle(details), details };
+	} catch (e) { abortBundle(b); throw e; }
+	finally { office?.cleanup(); }
+}
+
+export async function inspectDocument(o: DocToMdOptions, signal?: AbortSignal, seams?: Partial<PipelineSeams>): Promise<{ output: string; details: InfoData }> {
+	const s: PipelineSeams = { backend: (c) => getBackend(c, undefined, signal), runTier: runTierReal, ...seams };
+	const inputPath = resolve(o.path);
+	const st = statSync(inputPath, { throwIfNoEntry: false });
+	if (!st || !st.isFile()) throw new Error(`Not a readable file: ${o.path}`);
+	const type = classifyInput(inputPath);
+	const isExcel = type === "xlsx" || type === "xls";
+	const backend = await s.backend({ pymupdfVersion: o.pymupdfVersion, warmTimeoutMs: o.warmTimeoutMs });
+	if (isExcel && (backend.kind === "none" || !backend.xlsx)) throw new Error(`Excel inspection needs a Python backend with openpyxl, xlrd and pillow. ${EXCEL_REMEDY}`);
+	let office: { pdfPath: string; cleanup: () => void } | null = null;
+	try {
+		let path = inputPath;
+		if (type === "docx" || type === "pptx") { office = await convertOffice(o.sofficeTimeoutMs, inputPath, signal); path = office.pdfPath; }
+		const r = await s.runTier("info", { path, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, { stagingDir: "" }, signal, isExcel ? o.excelTimeoutMs : o.fallbackTimeoutMs, backend);
+		if (!r.ok) {
+			if ("userError" in r) throw new Error(r.userError);
+			if (isExcel && (r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes")) throw new Error(`Excel inspection failed: ${r.reason}. Remedy: raise excelTimeoutMs or lower maxCellsPerSheet${detailSuffix(r)}`);
+			throw new Error(`Inspection failed: ${r.reason}${detailSuffix(r)}`);
+		}
+		const toc: TocEntry[] = (r.json.toc ?? []).map(([level, title, page]) => ({ level, title, page }));
+		const details: InfoData = { type, backend: backend.kind, pageCount: r.json.pageCount ?? null, metadata: r.json.metadata ?? {}, toc: toc.slice(0, o.outlineMaxEntries), tocTotal: toc.length, sheets: r.json.sheets ? r.json.sheets.slice(0, o.outlineMaxEntries) : null, sheetsTotal: r.json.sheets?.length ?? 0 };
+		return { output: formatInfoHandle(details, o.outlineMaxEntries), details };
+	} finally { office?.cleanup(); }
 }