pi-quiver 5.4.0 → 6.0.0

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

@@ -1,25 +1,33 @@
 /**
  * Bundle protocol: a call owns `<stem>` for its whole duration via `<stem>.md.lock`;
- * children stage images under `images/.stage-<lockId>/p<N>/` and mark pages `.done`;
- * Node publishes done pages to `images/<stem>-p<N>-<n>.<ext>`, records every file it
+ * children stage images under `images/.stage-<lockId>/p<N>/` and CSVs under `sheets/.stage-<lockId>/s<idx>-<slug>.csv`;
+ * Node publishes them to `images/<stem>-p<N>-<n>.<ext>` and `sheets/<stem>-s<idx>-<slug>.csv`, and records every file it
  * wrote in a manifest, and commits `<stem>.md` atomically (tmp + rename).
  */
-import fs, { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import fs, { closeSync, existsSync, mkdirSync, openSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { extname, join, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
 
 export interface Bundle {
 	root: string; stem: string; mdPath: string; lockPath: string; imagesDir: string; stagingDir: string; lockId: string;
+	sheetsDir: string; sheetsStagingDir: string;
 	manifest: Set<string>;
+	csvManifest: Set<string>;
 	sourceMap: Map<string, string>;
 }
 
+const escRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
 export function ownedPattern(stem: string): RegExp {
-	const esc = stem.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-	return new RegExp(`^${esc}-(p|s)\\d+-\\d+\\.[a-z0-9]+$`);
+	return new RegExp(`^${escRe(stem)}-(p|s)\\d+(-\\d+)?\\.[a-z0-9]+$`);
+}
+
+export function ownedCsvPattern(stem: string): RegExp {
+	return new RegExp(`^${escRe(stem)}-s\\d+-[a-z0-9-]+\\.csv$`);
 }
 
+const SHEET_LINK_RE = /\[[^\]]*\]\(\s*(sheets\/[^)\s]+)\s*\)/g;
 const IMG_LINK_RE = /!\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)]*?))\s*\)|<img\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/gi;
 
 function imageTarget(m: RegExpMatchArray): string {
@@ -28,17 +36,6 @@ function imageTarget(m: RegExpMatchArray): string {
 	return m[2] === undefined ? destination : destination.replace(/\s+(?:"[^"]*"|'[^']*'|\([^)]*\))$/, "");
 }
 
-function linkedFiles(md: string): string[] {
-	const out: string[] = [];
-	for (const m of md.matchAll(IMG_LINK_RE)) {
-		const target = imageTarget(m);
-		if (!target.startsWith("images/")) continue;
-		const file = target.slice("images/".length);
-		if (file && file !== "." && file !== ".." && /^[^/\\]+$/.test(file)) out.push(file);
-	}
-	return out;
-}
-
 export function openBundle(root: string, stem: string, overwrite: boolean): Bundle {
 	mkdirSync(root, { recursive: true });
 	const mdPath = join(root, `${stem}.md`);
@@ -51,18 +48,20 @@ export function openBundle(root: string, stem: string, overwrite: boolean): Bund
 	}
 	closeSync(fd);
 	const imagesDir = join(root, "images");
+	const sheetsDir = join(root, "sheets");
 	try {
 		if (existsSync(mdPath)) {
 			if (!overwrite) throw new Error(`Output exists: ${mdPath} (pass overwrite)`);
-			const owned = ownedPattern(stem);
-			const linked = new Set(linkedFiles(readFileSync(mdPath, "utf8")));
+			const owned = ownedPattern(stem), ownedCsv = ownedCsvPattern(stem);
 			unlinkSync(mdPath);
-			if (existsSync(imagesDir)) for (const f of readdirSync(imagesDir)) if (owned.test(f) || linked.has(f)) rmSync(join(imagesDir, f), { force: true });
+			if (existsSync(imagesDir)) for (const f of readdirSync(imagesDir)) if (owned.test(f)) rmSync(join(imagesDir, f), { force: true });
+			if (existsSync(sheetsDir)) for (const f of readdirSync(sheetsDir)) if (ownedCsv.test(f)) rmSync(join(sheetsDir, f), { force: true });
 		}
 		const lockId = randomBytes(6).toString("hex");
 		const stagingDir = join(imagesDir, `.stage-${lockId}`);
+		const sheetsStagingDir = join(sheetsDir, `.stage-${lockId}`);
 		mkdirSync(stagingDir, { recursive: true });
-		return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, manifest: new Set(), sourceMap: new Map() };
+		return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, manifest: new Set(), csvManifest: new Set(), sourceMap: new Map() };
 	} catch (e) { rmSync(lockPath, { force: true }); throw e; }
 }
 
@@ -91,10 +90,10 @@ export function publishStaged(b: Bundle): Map<number, string[]> {
 	return out;
 }
 
-/** Excel: files staged flat in stagingDir as `s<idx>-<n>.<ext>` -> `images/<stem>-s<idx>-<n>.<ext>`. */
+/** Excel: `s<idx>-<n>.<ext>` (embedded) and `s<idx>.<fmt>` (rendered view) staged flat -> `images/<stem>-<file>`. */
 export function publishSheetImages(b: Bundle): void {
 	for (const f of readdirSync(b.stagingDir).sort()) {
-		if (!/^s\d+-\d+\.[a-z0-9]+$/i.test(f)) continue;
+		if (!/^s\d+(-\d+)?\.[a-z0-9]+$/i.test(f)) continue;
 		const name = `${b.stem}-${f.toLowerCase()}`;
 		renameSync(join(b.stagingDir, f), join(b.imagesDir, name));
 		b.manifest.add(name);
@@ -102,19 +101,38 @@ export function publishSheetImages(b: Bundle): void {
 	}
 }
 
-export function rewriteImageLinks(md: string, sourceMap: Map<string, string>): string {
-	return md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
+/** Excel: `sheetsStagingDir/s<idx>-<slug>.csv` -> `sheets/<stem>-s<idx>-<slug>.csv`; `sheets/` is created only when a CSV exists. */
+export function publishSheetCsvs(b: Bundle): void {
+	if (!existsSync(b.sheetsStagingDir)) return;
+	for (const f of readdirSync(b.sheetsStagingDir).sort()) {
+		if (!/^s\d+-[a-z0-9-]+\.csv$/.test(f)) continue;
+		const name = `${b.stem}-${f}`;
+		renameSync(join(b.sheetsStagingDir, f), join(b.sheetsDir, name));
+		b.csvManifest.add(name);
+		b.sourceMap.set(`sheets/${f}`, `sheets/${name}`);
+	}
+}
+
+export function rewriteLinks(md: string, sourceMap: Map<string, string>): string {
+	const images = md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
 		const target = imageTarget([whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted] as unknown as RegExpMatchArray);
 		const dest = sourceMap.get(target) ?? sourceMap.get(target.replace(/^\.\//, ""));
 		return dest ? whole.replace(mdAngle === undefined ? target : `<${mdAngle}>`, dest) : whole;
 	});
+	return images.replace(SHEET_LINK_RE, (whole, target: string) => {
+		const dest = sourceMap.get(target);
+		return dest ? whole.split(target).join(dest) : whole;
+	});
 }
 
-export function validateImageLinks(md: string, manifest: Set<string>): void {
+export function validateImageLinks(md: string, manifest: Set<string>, csvManifest: Set<string> = new Set()): void {
 	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}`);
 	}
+	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]}`);
+	}
 }
 
 export function commitBundle(b: Bundle, markdown: string): void {
@@ -122,13 +140,16 @@ export function commitBundle(b: Bundle, markdown: string): void {
 	writeFileSync(tmp, markdown, "utf8");
 	renameSync(tmp, b.mdPath);
 	try { fs.rmSync(b.stagingDir, { recursive: true, force: true }); } catch { /* Markdown is published; cleanup is best-effort. */ }
+	try { fs.rmSync(b.sheetsStagingDir, { recursive: true, force: true }); } catch { /* best-effort */ }
 	try { fs.rmSync(b.lockPath, { force: true }); } catch { /* Markdown is published; cleanup is best-effort. */ }
 }
 
 export function abortBundle(b: Bundle): void {
 	for (const f of b.manifest) rmSync(join(b.imagesDir, f), { force: true });
+	for (const f of b.csvManifest) rmSync(join(b.sheetsDir, 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.lockPath, { force: true });
 }
 

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

@@ -12,7 +12,7 @@ import { type ChildProcess, spawn } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { type Bundle, abortBundle, commitBundle, openBundle, publishSheetImages, publishStaged, rewriteImageLinks, tempBundleRoot, validateImageLinks } from "./doc-to-md-bundle.ts";
+import { type Bundle, abortBundle, commitBundle, openBundle, publishSheetCsvs, publishSheetImages, publishStaged, rewriteLinks, 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";
 
@@ -28,6 +28,7 @@ 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 const EXCEL_PDF_FILTER = 'pdf:calc_pdf_Export:{"SinglePageSheets":{"type":"boolean","value":"true"}}';
 
 export interface BackendConfig { pymupdfVersion: string; warmTimeoutMs: number; }
 
@@ -59,12 +60,12 @@ export function uvChildArgs(cfg: BackendConfig, script: string, mode: string): s
 
 export function pythonChildArgs(script: string, mode: string): string[] { return [script, mode]; }
 
-export function soffArgs(src: string, profileDir: string, outDir: string): string[] {
+export function soffArgs(src: string, profileDir: string, outDir: string, filter = "pdf"): string[] {
 	return [
 		"--headless", "--invisible", "--nocrashreport", "--nodefault", "--nofirststartwizard",
 		"--nolockcheck", "--nologo", "--norestore", "--quickstart=no",
 		`-env:UserInstallation=${pathToFileURL(profileDir).href}`,
-		"--convert-to", "pdf", "--outdir", outDir, src,
+		"--convert-to", filter, "--outdir", outDir, src,
 	];
 }
 
@@ -367,37 +368,37 @@ export function resetBackendCacheForTests(): void {
 	backendPromise = null;
 }
 
-export async function convertOffice(
-	sofficeTimeoutMs: number,
-	src: string,
-	signal?: AbortSignal,
-	run: RunFn = runCapped,
-): Promise<{ pdfPath: string; cleanup: () => void }> {
+export type OfficeResult =
+	| { ok: true; pdfPath: string; cleanup: () => void }
+	| { ok: false; kind: "missing" | "timeout" | "exit" | "no-pdf"; code: number | null; timedOut: boolean; stderr: string };
+
+export async function tryConvertOffice(sofficeTimeoutMs: number, src: string, signal?: AbortSignal, run: RunFn = runCapped, filter = "pdf"): Promise<OfficeResult> {
 	const profileDir = mkdtempSync(join(tmpdir(), "pi-doc-soffice-prof-"));
 	const outDir = mkdtempSync(join(tmpdir(), "pi-doc-soffice-out-"));
-	const cleanup = () => {
-		for (const d of [profileDir, outDir]) {
-			try { rmSync(d, { recursive: true, force: true }); } catch { /* ignore */ }
-		}
-	};
+	const cleanup = () => { for (const d of [profileDir, outDir]) try { rmSync(d, { recursive: true, force: true }); } catch { /* ignore */ } };
 	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: sofficeTimeoutMs, capBytes: OUTPUT_MAX_BYTES, env, signal });
+		const r = await run("soffice", soffArgs(src, profileDir, outDir, filter), { 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.");
-		}
-		if (r.timedOut || r.code !== 0) throw new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr.slice(0, 500)}`);
-		const base = basename(src).replace(/\.[^.]+$/, "");
-		const pdfPath = join(outDir, `${base}.pdf`);
+		const fail = (kind: "missing" | "timeout" | "exit" | "no-pdf"): OfficeResult => { cleanup(); return { ok: false, kind, code: r.code, timedOut: r.timedOut, stderr: r.stderr.slice(0, 500) }; };
+		if (r.code === null && !r.timedOut) return fail("missing");
+		if (r.timedOut) return fail("timeout");
+		if (r.code !== 0) return fail("exit");
+		const pdfPath = join(outDir, `${basename(src).replace(/\.[^.]+$/, "")}.pdf`);
 		const st = statSync(pdfPath, { throwIfNoEntry: false });
-		if (!st || !st.isFile() || st.size === 0) {
-			throw new Error("LibreOffice (soffice) ran but produced no usable PDF for this file. Ensure LibreOffice can open the document, or convert it to PDF manually first.");
-		}
-		return { pdfPath, cleanup };
+		if (!st || !st.isFile() || st.size === 0) return fail("no-pdf");
+		return { ok: true, pdfPath, cleanup };
 	} catch (e) { cleanup(); throw e; }
 }
 
+export async function convertOffice(sofficeTimeoutMs: number, src: string, signal?: AbortSignal, run: RunFn = runCapped): Promise<{ pdfPath: string; cleanup: () => void }> {
+	const r = await tryConvertOffice(sofficeTimeoutMs, src, signal, run);
+	if (r.ok) return r;
+	if (r.kind === "missing") throw new Error("LibreOffice (soffice) is required to convert .docx/.pptx but was not found on PATH. Install LibreOffice or convert the file to PDF first.");
+	if (r.kind === "no-pdf") throw new Error("LibreOffice (soffice) ran but produced no usable PDF for this file. Ensure LibreOffice can open the document, or convert it to PDF manually first.");
+	throw new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr}`);
+}
+
 
 // --- Conversion tiers and bundle orchestration ---
 
@@ -405,13 +406,14 @@ export const DEGRADED_TEXT = "PyMuPDF text extraction - layout/tables not preser
 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 Mode = "info" | "pdf-primary" | "pdf-fallback" | "xlsx" | "pdf-text" | "render-pages";
+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[]; renderPages?: number[]; sheetCount?: number; ok?: boolean; reason?: string; rendered?: { idx: number; file: string; dpi: number }[]; failed?: { idx: number; reason: string }[]; }
 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>;
+	office: typeof tryConvertOffice;
 }
 
 export function resolveUnpdfWorker(candidates: string[], exists: (path: string) => boolean): string {
@@ -463,8 +465,19 @@ function detailSuffix(r: Extract<TierResult, { ok: false; reason: string }>): st
 	return r.detail ? ` (${r.detail})` : "";
 }
 
+export function reconcileRenderMarkers(md: string, renderPages: number[], fmt: string, sourceMap: Map<string, string>, reason: (idx: number) => string): string {
+	for (const idx of renderPages) {
+		const file = `s${idx}.${fmt}`;
+		const ok = sourceMap.has(file);
+		md = md.replace(`<!--rv:${idx}-->`, ok ? `Rendered view: ![Rendered view of sheet ${idx}](${file})` : `Rendered view: unavailable (${reason(idx)})`);
+		md = md.replace(`<!--rvs:${idx}-->`, ok ? "yes" : "no");
+	}
+	if (/<!--rvs?:\d+-->/.test(md)) throw new Error("internal: unresolved render marker");
+	return md;
+}
+
 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 s: PipelineSeams = { backend: (c) => getBackend(c, undefined, signal), runTier: runTierReal, office: tryConvertOffice, ...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}`);
@@ -479,17 +492,40 @@ export async function convertDocument(o: DocToMdOptions, signal?: AbortSignal, s
 	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 };
+		const base = { path: pdfPath, pages: o.pages, stagingDir: b.stagingDir, sheetsStagingDir: b.sheetsStagingDir, imageDpi: o.imageDpi, imageFormat: o.imageFormat, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion };
 		let tier: Tier, engine: Engine, json: TierJson, degraded: string | null = null, fallbackReason: string | null = null;
+		let notes: string[] = [];
 		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" : "";
+				const remedy = r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes" ? ". Remedy: raise excelTimeoutMs" : "";
 				throw new Error(`Excel conversion failed: ${r.reason}${detailSuffix(r)}${remedy}`);
 			}
-			publishSheetImages(b);
-			tier = "excel"; engine = type === "xls" ? "xlrd" : "openpyxl"; json = r.json;
+			publishSheetImages(b); publishSheetCsvs(b);
+			tier = "excel"; engine = type === "xls" ? "xlrd" : "openpyxl"; json = r.json; notes = [...(json.notes ?? [])];
+			const renderPages = json.renderPages ?? [];
+			let skip: string | null = null;
+			const perSheet = new Map<number, string>();
+			if (renderPages.length) {
+				const off = await s.office(o.sofficeTimeoutMs, inputPath, signal, runCapped, EXCEL_PDF_FILTER);
+				if (!off.ok) skip = off.kind === "missing" ? "LibreOffice not found" : off.kind === "timeout" ? `soffice failed: timeout after ${o.sofficeTimeoutMs}ms` : off.kind === "exit" ? `soffice failed: exit ${off.code}` : "soffice produced no PDF";
+				else {
+					try {
+						const rp = await s.runTier("render-pages", { path: off.pdfPath, sheetIndices: renderPages, expectedPages: json.sheetCount, imageDpi: o.imageDpi, imageFormat: o.imageFormat, stagingDir: b.stagingDir, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.fallbackTimeoutMs, backend);
+						if (!rp.ok) skip = `render failed: ${"userError" in rp ? rp.userError : rp.reason}`;
+						else if (rp.json.ok === false) skip = rp.json.reason ?? "render failed";
+						else {
+							publishSheetImages(b);
+							for (const f of rp.json.failed ?? []) perSheet.set(f.idx, f.reason);
+							for (const d of rp.json.rendered ?? []) if (d.dpi < o.imageDpi) notes.push(`Rendered view s${d.idx}: rendered at ${d.dpi} dpi`);
+						}
+					} finally { off.cleanup(); }
+				}
+				if (skip) notes.push(`Rendered views skipped: ${skip}`);
+				else if (perSheet.size) notes.push(`Rendered views: ${perSheet.size} of ${renderPages.length} unavailable`);
+			}
+			json = { ...json, markdown: reconcileRenderMarkers(json.markdown ?? "", renderPages, o.imageFormat, b.sourceMap, (idx) => perSheet.get(idx) ?? skip ?? "render failed") };
 		} else if (backend.kind === "none") {
 			const r = await s.runTier("pdf-text", base, b, signal, o.primaryTimeoutMs, backend);
 			if (!r.ok) throw new Error("userError" in r ? r.userError : `Conversion failed: unpdf ${r.reason}${detailSuffix(r)}`);
@@ -508,25 +544,26 @@ export async function convertDocument(o: DocToMdOptions, signal?: AbortSignal, s
 				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);
+		if (!isExcel) notes = json.notes ?? [];
+		const body = rewriteLinks(json.markdown ?? "", b.sourceMap);
+		validateImageLinks(body, b.manifest, b.csvManifest);
 		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}`);
+		for (const n of 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 };
+		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, sheetsDir: b.csvManifest.size ? b.sheetsDir : null, type, engine, tier, pageCount: json.pageCount ?? null, pages: o.pages, imageCount: b.manifest.size, bytes: Buffer.byteLength(markdown, "utf8"), lines: markdown.split("\n").length, degraded, fallbackReason, failedPages: (json.failedPages ?? []).map((f) => f.page), emptyPages: json.emptyPages ?? [], notes, outline: outline.entries, outlineTotal: outline.total };
 		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 s: PipelineSeams = { backend: (c) => getBackend(c, undefined, signal), runTier: runTierReal, office: tryConvertOffice, ...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}`);
@@ -541,7 +578,7 @@ export async function inspectDocument(o: DocToMdOptions, signal?: AbortSignal, s
 		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)}`);
+			if (isExcel && (r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes")) throw new Error(`Excel inspection failed: ${r.reason}. Remedy: raise excelTimeoutMs${detailSuffix(r)}`);
 			throw new Error(`Inspection failed: ${r.reason}${detailSuffix(r)}`);
 		}
 		const toc: TocEntry[] = (r.json.toc ?? []).map(([level, title, page]) => ({ level, title, page }));

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

@@ -6,10 +6,20 @@ export type BackendKind = "uv" | "python" | "venv" | "none";
 
 export interface OutlineEntry { line: number; level: number; title: string; }
 export interface TocEntry { level: number; title: string; page: number; }
-export interface SheetInfo { index: number; name: string; hidden: boolean; rows: number | null; cols: number | null; hiddenRows: number; hiddenCols: number; }
+export interface SheetInfo {
+	index: number;
+	name: string;
+	kind: "worksheet" | "chartsheet";
+	hidden: boolean;
+	rows: number | null; cols: number | null;
+	hiddenRows: number; hiddenCols: number;
+	charts: number; images: number;
+	rendered: boolean;
+	csv: string | null;
+}
 
 export interface HandleData {
-	savedTo: string; imagesDir: string | null; type: InputType; engine: Engine; tier: Tier;
+	savedTo: string; imagesDir: string | null; sheetsDir: string | null; type: InputType; engine: Engine; tier: Tier;
 	pageCount: number | null; pages: number[] | null; imageCount: number; bytes: number; lines: number;
 	degraded: string | null; fallbackReason: string | null; failedPages: number[]; emptyPages: number[];
 	notes: string[]; outline: OutlineEntry[]; outlineTotal: number;
@@ -73,6 +83,7 @@ function outlineLines(entries: OutlineEntry[], total: number): string[] {
 export function formatHandle(h: HandleData): string {
 	const lines = [`Saved-To: ${h.savedTo}`];
 	if (h.imagesDir && h.imageCount > 0) lines.push(`Images-Dir: ${h.imagesDir}`);
+	if (h.sheetsDir) lines.push(`Sheets-Dir: ${h.sheetsDir}`);
 	lines.push(`Type: ${h.type}   Engine: ${h.engine}   Tier: ${h.tier}`);
 	lines.push(`Page-Count: ${h.pageCount ?? "?"}   Pages: ${h.pages ? compactRanges(h.pages) : "all"}   Images: ${h.imageCount}   Size: ${formatSize(h.bytes)} / ${h.lines} lines`);
 	if (h.degraded) lines.push(`Degraded: ${h.degraded}`);
@@ -90,7 +101,7 @@ export function formatInfoHandle(i: InfoData, max: number): string {
 	if (i.sheets) {
 		const lines = [`Type: ${i.type}   Sheets: ${i.sheetsTotal}`];
 		for (const s of i.sheets.slice(0, max)) {
-			const dims = `rows=${s.rows ?? "?"} cols=${s.cols ?? "?"}`;
+			const dims = `${s.kind} rows=${s.rows ?? "-"} cols=${s.cols ?? "-"} charts=${s.charts} images=${s.images}`;
 			const hidden = s.hiddenRows || s.hiddenCols ? ` hiddenRows=${s.hiddenRows} hiddenCols=${s.hiddenCols}` : "";
 			lines.push(`  ${trunc(s.name, TITLE_MAX)}  ${s.hidden ? "hidden " : ""}${dims}${hidden}`);
 		}

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

@@ -16,7 +16,6 @@ export interface Tunables {
 	pymupdfVersion: string;
 	imageDpi: number;
 	imageFormat: ImageFormat;
-	maxCellsPerSheet: number;
 	maxOutputBytes: number;
 	outlineMaxEntries: number;
 }
@@ -63,14 +62,13 @@ export const DOC_TO_MD_OPTIONS: readonly OptionDescriptor[] = [
 	{ key: "outputDir", flag: "--output-dir", type: "string", default: null, settable: false, help: "Bundle root for <stem>.md + images/; default a per-call temp dir" },
 	{ key: "overwrite", flag: "--overwrite", type: "bool", default: false, settable: false, help: "Replace an existing completed <stem>.md bundle" },
 	{ key: "primaryTimeoutMs", flag: "--primary-timeout", type: "int", default: 60000, settable: true, env: "PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", help: "pymupdf4llm tier; also the unpdf tier" },
-	{ key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 30000, settable: true, help: "PyMuPDF get_text tier; also info on PDF" },
-	{ key: "sofficeTimeoutMs", flag: "--soffice-timeout", type: "int", default: 120000, settable: true, env: "PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", help: "DOCX/PPTX -> PDF via LibreOffice" },
+	{ key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 30000, settable: true, help: "PyMuPDF get_text tier; also info on PDF and Excel rendered views" },
+	{ key: "sofficeTimeoutMs", flag: "--soffice-timeout", type: "int", default: 120000, settable: true, env: "PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", help: "DOCX/PPTX -> PDF via LibreOffice; also Excel rendered views" },
 	{ key: "excelTimeoutMs", flag: "--excel-timeout", type: "int", default: 60000, settable: true, help: "Excel child (both openpyxl loads); also info on Excel" },
 	{ key: "warmTimeoutMs", flag: "--warm-timeout", type: "int", default: 120000, settable: true, env: "PI_DOC_TO_MD_WARM_TIMEOUT_MS", help: "Absolute backend discovery/bootstrap deadline (first call per process)" },
 	{ key: "pymupdfVersion", flag: "--pymupdf-version", type: "version", default: "1.27.2.3", settable: true, env: "PI_DOC_TO_MD_PYMUPDF_VERSION", help: "pymupdf4llm pin (>= 1.27.0)" },
-	{ key: "imageDpi", flag: "--image-dpi", type: "int", default: 150, settable: true, help: "Render DPI for page images" },
+	{ 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: "maxCellsPerSheet", flag: "--max-cells-per-sheet", type: "int", default: 50000, settable: true, help: "rows x cols budget per worksheet" },
 	{ key: "maxOutputBytes", flag: "--max-output-bytes", type: "int", default: 20000000, 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" },
 ];

package/lib/extension-config.ts

@@ -47,7 +47,7 @@ export const QUIVER_CONFIG_KEYS: Record<string, readonly string[]> = {
 	sessionAutoName: ["enabled", "ghosttyTab", "herdrTab", "rules", "deny", "revisitFirstTurn", "revisitEveryTurns"],
 	swordHeader: ["enabled"],
 	providerStallWatchdog: ["enabled", "firstEventMs", "warningMs", "recoveryMs", "maxStallRetries"],
-	slack: ["enabled", "cachePath", "policyPath", "userTokenEnv", "botTokenEnv", "uploadThresholdChars"],
+	slack: ["enabled", "cachePath", "policyPath", "userTokenEnv", "userTokenCommand", "userTokenCommandTimeoutSeconds", "botTokenEnv", "uploadThresholdChars"],
 	docToMd: DOC_TO_MD_OPTIONS.filter((o) => o.settable).map((o) => o.key),
 };
 
@@ -104,7 +104,7 @@ export function resolveConfig<T extends object>(
 	cwd: string,
 	key: string,
 	defaults: T,
-	coerce: (raw: unknown) => Partial<T> | undefined,
+	coerce: (raw: unknown, warn?: (message: string) => void) => Partial<T> | undefined,
 	warn?: (message: string) => void,
 ): T {
 	const cfg: T = { ...defaults };
@@ -119,7 +119,7 @@ export function resolveConfig<T extends object>(
 		const hasFlat = Object.hasOwn(settings, key);
 		if (!hasNested && !(hasFlat && LEGACY_FLAT_KEYS.has(key))) continue;
 		const candidate = hasNested ? nested![key] : settings[key];
-		const patch = coerce(candidate);
+		const patch = coerce(candidate, (message) => emitWarning(warn, message));
 		if (patch) Object.assign(cfg, patch);
 		else emitWarning(warn, `pi-quiver: "${key}" in ${path} has an unrecognized value; ignored.`);
 	}

package/lib/slack-core.ts

@@ -9,7 +9,7 @@
  * slack-local `PI_QUIVER_SLACK_*` env-var overlay applied on top.
  */
 
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -21,6 +21,8 @@ export interface SlackConfig {
 	cachePath: string | undefined;
 	policyPath: string | undefined;
 	userTokenEnv: string;
+	userTokenCommand: string[] | undefined;
+	userTokenCommandTimeoutSeconds: number;
 	botTokenEnv: string;
 	uploadThresholdChars: number;
 }
@@ -30,6 +32,8 @@ export const DEFAULT_SLACK_CONFIG: SlackConfig = {
 	cachePath: undefined,
 	policyPath: undefined,
 	userTokenEnv: "SLACK_USER_TOKEN",
+	userTokenCommand: undefined,
+	userTokenCommandTimeoutSeconds: 10,
 	botTokenEnv: "SLACK_BOT_TOKEN",
 	uploadThresholdChars: 4000,
 };
@@ -44,7 +48,9 @@ export class SlackError extends Error {
 	}
 }
 
-export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
+const MAX_TIMER_SECONDS = 2_147_483.647;
+
+export function coerce(raw: unknown, warn?: (message: string) => void): Partial<SlackConfig> | undefined {
 	if (typeof raw === "boolean") return { enabled: raw };
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
 	const o = raw as Record<string, unknown>;
@@ -53,6 +59,28 @@ export function coerce(raw: unknown): Partial<SlackConfig> | undefined {
 	if (typeof o.cachePath === "string") patch.cachePath = o.cachePath;
 	if (typeof o.policyPath === "string") patch.policyPath = o.policyPath;
 	if (typeof o.userTokenEnv === "string") patch.userTokenEnv = o.userTokenEnv;
+	if (
+		Array.isArray(o.userTokenCommand) &&
+		typeof o.userTokenCommand[0] === "string" &&
+		o.userTokenCommand[0].length > 0 &&
+		o.userTokenCommand.every((part) => typeof part === "string")
+	) {
+		patch.userTokenCommand = [...o.userTokenCommand];
+	}
+	if (o.userTokenCommandTimeoutSeconds !== undefined) {
+		if (
+			typeof o.userTokenCommandTimeoutSeconds === "number" &&
+			Number.isFinite(o.userTokenCommandTimeoutSeconds) &&
+			o.userTokenCommandTimeoutSeconds > 0 &&
+			o.userTokenCommandTimeoutSeconds <= MAX_TIMER_SECONDS
+		) {
+			patch.userTokenCommandTimeoutSeconds = o.userTokenCommandTimeoutSeconds;
+		} else {
+			warn?.(
+				`pi-quiver: quiver.slack.userTokenCommandTimeoutSeconds must be a positive finite number no greater than ${MAX_TIMER_SECONDS}; ignored.`,
+			);
+		}
+	}
 	if (typeof o.botTokenEnv === "string") patch.botTokenEnv = o.botTokenEnv;
 	if (typeof o.uploadThresholdChars === "number" && Number.isInteger(o.uploadThresholdChars) && o.uploadThresholdChars > 0) {
 		patch.uploadThresholdChars = o.uploadThresholdChars;
@@ -222,6 +250,42 @@ export function resolveToken(
 	);
 }
 
+function runCredentialCommand(command: string[], timeoutMs: number): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const [file, ...args] = command;
+		execFile(file, args, { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 64 * 1024, encoding: "utf8" }, (err, stdout) => {
+			if (err) {
+				const childError = err as NodeJS.ErrnoException & { killed?: boolean; signal?: string | null };
+				if (childError.killed) {
+					reject(new SlackError("credential_command_failed", `Slack user credential command timed out after ${timeoutMs}ms.`));
+					return;
+				}
+				const status = typeof childError.code === "number" ? ` (status ${childError.code})` : "";
+				reject(new SlackError("credential_command_failed", `Slack user credential command failed${status}.`));
+				return;
+			}
+			const token = stdout.trim();
+			if (!token) {
+				reject(new SlackError("missing_token", "Slack user credential command returned no token."));
+				return;
+			}
+			resolve(token);
+		});
+	});
+}
+
+export async function resolveCredential(
+	identity: "user" | "bot",
+	cfg: SlackConfig,
+	env: Record<string, string | undefined>,
+	repoRoot: string,
+): Promise<string> {
+	if (identity === "user" && cfg.userTokenCommand) {
+		return runCredentialCommand(cfg.userTokenCommand, Math.ceil(cfg.userTokenCommandTimeoutSeconds * 1000));
+	}
+	return resolveToken(identity, cfg, env, repoRoot);
+}
+
 /**
  * Data-plane transport: every Slack API call and file upload funnels through
  * these two injectable functions so tests script responses without network.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-quiver",
-  "version": "5.4.0",
+  "version": "6.0.0",
   "description": "Personal pack of Pi coding-agent extensions: context-safe fetch, doc_to_md PDF/DOCX/PPTX-to-Markdown conversion, session naming, a themed ASCII startup header, Opus 4.8 fast mode, and a provider-stall watchdog.",
   "author": "Jacek Juraszek",
   "license": "MIT",