pi-quiver 5.5.0 → 6.0.0

package/CHANGELOG.md

@@ -8,6 +8,13 @@ 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.0.0 - 2026-09-10
+
+- doc_to_md (Excel, breaking): `maxCellsPerSheet` is removed from the tool schema, CLI (`--max-cells-per-sheet`), and `quiver.docToMd` settings; a leftover key is reported by the settings lint. Sheet indices are now 0-based workbook positions covering worksheets and chartsheets, so embedded-image files move from `<stem>-s1-<n>.*` to `<stem>-s0-<n>.*` and `SheetInfo.index` is rebased.
+- doc_to_md (Excel): the Markdown opens with a `## Sheets` inventory (kind, size, hidden, chart/image counts, rendered view, CSV link); every non-empty worksheet's full content is exported to `sheets/<stem>-s<idx>-<slug>.csv`; the in-Markdown preview is capped at 100 rows x 50 columns and, when truncated, followed by a per-column profile (type, non-empty, min/max, distinct). Chartsheets and embedded charts are listed with type, title, and series refs.
+- doc_to_md (Excel): sheets carrying charts or images get a rendered view (`images/<stem>-s<idx>.<fmt>`) when LibreOffice is on `PATH` - one PDF page per sheet via `calc_pdf_Export` `SinglePageSheets`, rasterized by a new PyMuPDF `render-pages` child under a 16 Mpx budget. Any soffice or render failure degrades to `Rendered view: unavailable (<reason>)` plus a handle note; the conversion never fails. `.xls` keeps inventory/CSV/preview but has no visual detection.
+- doc_to_md: handle prints `Sheets-Dir` when CSVs were written; `info` lists chartsheets with kind and chart/image counts. Bundle overwrite now removes only this stem's owned-pattern files in `images/` and `sheets/`.
+
 ## v5.5.0 - 2026-09-10
 
 - doc_to_md: rewrite primary-PDF image links correctly on Windows.

package/README.md

@@ -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 return a handle (paths, page count, outline, diagnostics) - never inline Markdown. `info` mode inspects first; `pages` selects 1-based pages; every page ends with `--- end of page.page_number=N ---`. Tiers: pymupdf4llm -> PyMuPDF text (degraded) -> unpdf worker (no Python only). Excel -> per-worksheet matrices with formulas/cached values/merged/hidden. Settings under `quiver.docToMd`. |
+| `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; every page 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. 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. |
@@ -93,7 +93,7 @@ Full routing rules, size-gate mechanics, and config: [doc/fetch.md](doc/fetch.md
 ## When NOT to use
 
 - You need a general-purpose web scraper (JS-rendered pages, pagination, auth flows) - `fetch` does plain HTTP + Readability extraction, nothing more.
-- You need `.xlsm`, sheet/range selection or chart rendering - out of scope.
+- You need in-grid chart/image placement, `.xls` visual detection, `.xlsm`, or range selection - out of scope; chart/image association is per sheet only.
 - You want automatic session naming, a custom header, fast mode, or stall recovery without opting in - all stay off until you flip the config.
 - You need *mid-stream* stall recovery in JSON, RPC, or print runs - only the pre-first-event tier arms there; mid-stream silence falls through to pi's transport timeout.
 
@@ -289,22 +289,21 @@ Each setting can also be overridden per-process via `PI_QUIVER_SLACK_ENABLED`, `
 | Key | Default | Meaning |
 |---|---|---|
 | `primaryTimeoutMs` | `60000` | pymupdf4llm tier and unpdf tier deadline. |
-| `fallbackTimeoutMs` | `30000` | PyMuPDF text tier and PDF info deadline. |
-| `sofficeTimeoutMs` | `120000` | DOCX/PPTX -> PDF deadline. |
+| `fallbackTimeoutMs` | `30000` | PyMuPDF text tier, PDF info, and Excel rendered-view rasterization deadline. |
+| `sofficeTimeoutMs` | `120000` | DOCX/PPTX -> PDF deadline; also the Excel rendered-view export. |
 | `excelTimeoutMs` | `60000` | Excel child and Excel info deadline. |
 | `warmTimeoutMs` | `120000` | Absolute first-call backend discovery/bootstrap deadline. |
 | `pymupdfVersion` | `1.27.2.3` | pymupdf4llm pin, minimum `1.27.0`. |
-| `imageDpi` | `150` | Render DPI for page images. |
+| `imageDpi` | `150` | Render DPI for page images and Excel rendered views (capped by a 16 Mpx budget). |
 | `imageFormat` | `png` | Rendered image format: `png` or `jpg`; embedded images retain their extension. |
-| `maxCellsPerSheet` | `50000` | Rows x columns budget per worksheet. |
 | `maxOutputBytes` | `20000000` | Child stdout cap in bytes. |
 | `outlineMaxEntries` | `40` | Heading outline, TOC, or sheet inventory entries in the handle. |
 
-A bundle is `<outputDir>/<stem>.md` plus `<outputDir>/images/`; 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 images it owns (`<stem>-p<N>-<n>.*` / `<stem>-s<idx>-<n>.*`), nothing else. Temp bundles are caller-owned - the tool never deletes a bundle it produced.
+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.
 
-Excel needs a Python backend with openpyxl, xlrd and pillow - otherwise the call fails with `Remedy: install uv, or pip install openpyxl xlrd pillow`.
+Excel needs a Python backend with openpyxl, xlrd and pillow - otherwise the call fails with `Remedy: install uv, or pip install openpyxl xlrd pillow`. The Markdown opens with a `## Sheets` table listing every sheet in workbook order (0-based `#`, `worksheet`/`chartsheet`, size, hidden, chart and image counts, rendered view, CSV link for non-empty worksheets), then one section per sheet: a `Data:` line linking the full-content CSV under `sheets/` for non-empty worksheets, chart metadata from the workbook model, embedded images, an optional rendered view, a preview of at most the first 100 rows x 50 columns, and - only when the preview is truncated - a `Columns:` profile (type, non-empty count, min/max, distinct up to 50). Sizes are the extent of non-empty cells (the `info` handle reports the raw worksheet dimensions instead, which may be larger). Rendered views (`images/<stem>-s<idx>.<fmt>`) are produced for sheets carrying charts or images when LibreOffice is on `PATH`: the workbook is exported one PDF page per sheet and rasterized under a 16 Mpx budget. Any LibreOffice or rasterization failure degrades to `Rendered view: unavailable (<reason>)` and a handle note; it never fails the conversion. Workbooks whose chartsheet drawings carry a zero-size anchor (openpyxl-authored files; Excel-authored files are unaffected) render as a degenerate page and are reported as such. `.xls` gets the inventory, CSVs and previews but no visual detection or rendering.
 
-Worst-case wall time is `warmTimeoutMs (first call) + sofficeTimeoutMs (Office only) + primaryTimeoutMs + fallbackTimeoutMs + KILL_GRACE_MS x kills` (Excel: `warmTimeoutMs + excelTimeoutMs + KILL_GRACE_MS`). There is no cap on image count, image bytes or workbook memory - deliberately; the per-tier timeouts and `maxOutputBytes` are the bounds.
+Worst-case wall time is `warmTimeoutMs (first call) + sofficeTimeoutMs (Office only) + primaryTimeoutMs + fallbackTimeoutMs + KILL_GRACE_MS x kills` (Excel: `warmTimeoutMs + excelTimeoutMs + sofficeTimeoutMs + fallbackTimeoutMs + 2 * KILL_GRACE_MS`). There is no cap on image count, image bytes, cell count or workbook memory - deliberately; the per-tier timeouts, the rendered-view pixel budget and `maxOutputBytes` are the bounds.
 
 ### Migrating from flat keys
 

package/dist/bin/pi-quiver.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // bin/pi-quiver.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2, realpathSync } from "node:fs";
+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";
@@ -524,30 +524,24 @@ import { basename, dirname, extname as extname3, join as join3, resolve as resol
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 // lib/doc-to-md-bundle.ts
-import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import fs, { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readdirSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { tmpdir as tmpdir2 } from "node:os";
 import { extname, join as join2, resolve } from "node:path";
 import { randomBytes } from "node:crypto";
+var escRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 function ownedPattern(stem) {
-  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]+$`);
 }
+function ownedCsvPattern(stem) {
+  return new RegExp(`^${escRe(stem)}-s\\d+-[a-z0-9-]+\\.csv$`);
+}
+var SHEET_LINK_RE = /\[[^\]]*\]\(\s*(sheets\/[^)\s]+)\s*\)/g;
 var IMG_LINK_RE = /!\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)]*?))\s*\)|<img\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>"']+))/gi;
 function imageTarget(m) {
   const target = (m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? "").trim();
   const destination = target.replace(/^<([\s\S]*)>$/, "$1").trim();
   return m[2] === void 0 ? destination : destination.replace(/\s+(?:"[^"]*"|'[^']*'|\([^)]*\))$/, "");
 }
-function linkedFiles(md) {
-  const out = [];
-  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;
-}
 function openBundle(root, stem, overwrite) {
   mkdirSync2(root, { recursive: true });
   const mdPath = join2(root, `${stem}.md`);
@@ -561,20 +555,24 @@ function openBundle(root, stem, overwrite) {
   }
   closeSync(fd);
   const imagesDir = join2(root, "images");
+  const sheetsDir = join2(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(join2(imagesDir, f), { force: true });
+        for (const f of readdirSync(imagesDir)) if (owned.test(f)) rmSync(join2(imagesDir, f), { force: true });
+      }
+      if (existsSync(sheetsDir)) {
+        for (const f of readdirSync(sheetsDir)) if (ownedCsv.test(f)) rmSync(join2(sheetsDir, f), { force: true });
       }
     }
     const lockId = randomBytes(6).toString("hex");
     const stagingDir = join2(imagesDir, `.stage-${lockId}`);
+    const sheetsStagingDir = join2(sheetsDir, `.stage-${lockId}`);
     mkdirSync2(stagingDir, { recursive: true });
-    return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, manifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
+    return { root, stem, mdPath, lockPath, imagesDir, stagingDir, lockId, sheetsDir, sheetsStagingDir, manifest: /* @__PURE__ */ new Set(), csvManifest: /* @__PURE__ */ new Set(), sourceMap: /* @__PURE__ */ new Map() };
   } catch (e) {
     rmSync(lockPath, { force: true });
     throw e;
@@ -608,25 +606,42 @@ function publishStaged(b) {
 }
 function publishSheetImages(b) {
   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(join2(b.stagingDir, f), join2(b.imagesDir, name));
     b.manifest.add(name);
     b.sourceMap.set(f, `images/${name}`);
   }
 }
-function rewriteImageLinks(md, sourceMap) {
-  return md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
+function publishSheetCsvs(b) {
+  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(join2(b.sheetsStagingDir, f), join2(b.sheetsDir, name));
+    b.csvManifest.add(name);
+    b.sourceMap.set(`sheets/${f}`, `sheets/${name}`);
+  }
+}
+function rewriteLinks(md, sourceMap) {
+  const images = md.replace(IMG_LINK_RE, (whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted) => {
     const target = imageTarget([whole, mdAngle, mdPlain, htmlDouble, htmlSingle, htmlUnquoted]);
     const dest = sourceMap.get(target) ?? sourceMap.get(target.replace(/^\.\//, ""));
     return dest ? whole.replace(mdAngle === void 0 ? target : `<${mdAngle}>`, dest) : whole;
   });
+  return images.replace(SHEET_LINK_RE, (whole, target) => {
+    const dest = sourceMap.get(target);
+    return dest ? whole.split(target).join(dest) : whole;
+  });
 }
-function validateImageLinks(md, manifest) {
+function validateImageLinks(md, manifest, csvManifest = /* @__PURE__ */ new Set()) {
   for (const m of md.matchAll(IMG_LINK_RE)) {
     const target = imageTarget(m);
     if (!target.startsWith("images/") || !manifest.has(target.slice("images/".length))) throw new Error(`unexpected image reference in output: ${target}`);
   }
+  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]}`);
+  }
 }
 function commitBundle(b, markdown) {
   const tmp = `${b.mdPath}.tmp`;
@@ -636,6 +651,10 @@ function commitBundle(b, markdown) {
     fs.rmSync(b.stagingDir, { recursive: true, force: true });
   } catch {
   }
+  try {
+    fs.rmSync(b.sheetsStagingDir, { recursive: true, force: true });
+  } catch {
+  }
   try {
     fs.rmSync(b.lockPath, { force: true });
   } catch {
@@ -643,8 +662,10 @@ function commitBundle(b, markdown) {
 }
 function abortBundle(b) {
   for (const f of b.manifest) rmSync(join2(b.imagesDir, f), { force: true });
+  for (const f of b.csvManifest) rmSync(join2(b.sheetsDir, f), { force: true });
   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 });
 }
 function tempBundleRoot() {
@@ -703,6 +724,7 @@ function outlineLines(entries, total) {
 function formatHandle(h) {
   const lines = [`Saved-To: ${h.savedTo}`];
   if (h.imagesDir && h.imageCount > 0) lines.push(`Images-Dir: ${h.imagesDir}`);
+  if (h.sheetsDir) lines.push(`Sheets-Dir: ${h.sheetsDir}`);
   lines.push(`Type: ${h.type}   Engine: ${h.engine}   Tier: ${h.tier}`);
   lines.push(`Page-Count: ${h.pageCount ?? "?"}   Pages: ${h.pages ? compactRanges(h.pages) : "all"}   Images: ${h.imageCount}   Size: ${formatSize2(h.bytes)} / ${h.lines} lines`);
   if (h.degraded) lines.push(`Degraded: ${h.degraded}`);
@@ -719,7 +741,7 @@ function formatInfoHandle(i, max) {
   if (i.sheets) {
     const lines2 = [`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}` : "";
       lines2.push(`  ${trunc(s.name, TITLE_MAX)}  ${s.hidden ? "hidden " : ""}${dims}${hidden}`);
     }
@@ -749,14 +771,13 @@ var DOC_TO_MD_OPTIONS = [
   { key: "outputDir", flag: "--output-dir", type: "string", default: null, settable: false, help: "Bundle root for <stem>.md + images/; default a per-call temp dir" },
   { key: "overwrite", flag: "--overwrite", type: "bool", default: false, settable: false, help: "Replace an existing completed <stem>.md bundle" },
   { key: "primaryTimeoutMs", flag: "--primary-timeout", type: "int", default: 6e4, settable: true, env: "PI_DOC_TO_MD_CONVERT_TIMEOUT_MS", help: "pymupdf4llm tier; also the unpdf tier" },
-  { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier; also info on PDF" },
-  { key: "sofficeTimeoutMs", flag: "--soffice-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", help: "DOCX/PPTX -> PDF via LibreOffice" },
+  { key: "fallbackTimeoutMs", flag: "--fallback-timeout", type: "int", default: 3e4, settable: true, help: "PyMuPDF get_text tier; also info on PDF and Excel rendered views" },
+  { key: "sofficeTimeoutMs", flag: "--soffice-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_SOFFICE_TIMEOUT_MS", help: "DOCX/PPTX -> PDF via LibreOffice; also Excel rendered views" },
   { key: "excelTimeoutMs", flag: "--excel-timeout", type: "int", default: 6e4, settable: true, help: "Excel child (both openpyxl loads); also info on Excel" },
   { key: "warmTimeoutMs", flag: "--warm-timeout", type: "int", default: 12e4, settable: true, env: "PI_DOC_TO_MD_WARM_TIMEOUT_MS", help: "Absolute backend discovery/bootstrap deadline (first call per process)" },
   { 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: 5e4, settable: true, help: "rows x cols budget per worksheet" },
   { 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" }
 ];
@@ -877,6 +898,7 @@ var VENV_DIR_NAME = "doc-to-md-venv-v2";
 var LEGACY_VENV_DIR_NAME = "pymupdf-venv";
 var STDERR_CAP = 1e6;
 var OUTPUT_MAX_BYTES = 2e7;
+var EXCEL_PDF_FILTER = 'pdf:calc_pdf_Export:{"SinglePageSheets":{"type":"boolean","value":"true"}}';
 function withArgs(cfg) {
   return ["--with", `pymupdf4llm==${cfg.pymupdfVersion}`, "--with", `openpyxl==${PACKAGE_PINS.openpyxl}`, "--with", `xlrd==${PACKAGE_PINS.xlrd}`, "--with", `pillow==${PACKAGE_PINS.pillow}`];
 }
@@ -892,7 +914,7 @@ function uvChildArgs(cfg, script, mode) {
 function pythonChildArgs(script, mode) {
   return [script, mode];
 }
-function soffArgs(src, profileDir, outDir) {
+function soffArgs(src, profileDir, outDir, filter = "pdf") {
   return [
     "--headless",
     "--invisible",
@@ -905,7 +927,7 @@ function soffArgs(src, profileDir, outDir) {
     "--quickstart=no",
     `-env:UserInstallation=${pathToFileURL(profileDir).href}`,
     "--convert-to",
-    "pdf",
+    filter,
     "--outdir",
     outDir,
     src
@@ -1162,37 +1184,42 @@ function getBackend(cfg, deps, signal) {
   }
   return backendPromise;
 }
-async function convertOffice(sofficeTimeoutMs, src, signal, run = runCapped) {
+async function tryConvertOffice(sofficeTimeoutMs, src, signal, run = runCapped, filter = "pdf") {
   const profileDir = mkdtempSync(join3(tmpdir3(), "pi-doc-soffice-prof-"));
   const outDir = mkdtempSync(join3(tmpdir3(), "pi-doc-soffice-out-"));
   const cleanup = () => {
-    for (const d of [profileDir, outDir]) {
-      try {
-        rmSync2(d, { recursive: true, force: true });
-      } catch {
-      }
+    for (const d of [profileDir, outDir]) try {
+      rmSync2(d, { recursive: true, force: true });
+    } catch {
     }
   };
   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 = join3(outDir, `${base}.pdf`);
+    const fail = (kind) => {
+      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 = join3(outDir, `${basename(src).replace(/\.[^.]+$/, "")}.pdf`);
     const st = statSync2(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;
   }
 }
+async function convertOffice(sofficeTimeoutMs, src, signal, run = runCapped) {
+  const r = await tryConvertOffice(sofficeTimeoutMs, src, signal, run);
+  if (r.ok) return r;
+  if (r.kind === "missing") throw new Error("LibreOffice (soffice) is required to convert .docx/.pptx but was not found on PATH. Install LibreOffice or convert the file to PDF first.");
+  if (r.kind === "no-pdf") throw new Error("LibreOffice (soffice) ran but produced no usable PDF for this file. Ensure LibreOffice can open the document, or convert it to PDF manually first.");
+  throw new Error(`soffice failed (code=${r.code} timedOut=${r.timedOut}): ${r.stderr}`);
+}
 var DEGRADED_TEXT = "PyMuPDF text extraction - layout/tables not preserved";
 var DEGRADED_UNPDF = "unpdf text extraction - structure not preserved";
 var EXCEL_REMEDY = "Remedy: install uv, or pip install openpyxl xlrd pillow";
@@ -1239,8 +1266,18 @@ async function runTierReal(mode, childOptions, _b, signal, timeoutMs, backend) {
 function detailSuffix(r) {
   return r.detail ? ` (${r.detail})` : "";
 }
+function reconcileRenderMarkers(md, renderPages, fmt, sourceMap, reason) {
+  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;
+}
 async function convertDocument(o, signal, seams) {
-  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, ...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}`);
@@ -1258,19 +1295,46 @@ async function convertDocument(o, signal, seams) {
       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, engine, json, degraded = null, fallbackReason = null;
+    let notes = [];
     if (isExcel) {
       const r = await s.runTier("xlsx", base, b, signal, o.excelTimeoutMs, backend);
       if (!r.ok) {
         if ("userError" in r) throw new Error(r.userError);
-        const remedy = r.reason.startsWith("timeout after") || r.reason === "output exceeded maxOutputBytes" ? ". Remedy: raise excelTimeoutMs 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);
+      publishSheetCsvs(b);
       tier = "excel";
       engine = type === "xls" ? "xlrd" : "openpyxl";
       json = r.json;
+      notes = [...json.notes ?? []];
+      const renderPages = json.renderPages ?? [];
+      let skip = null;
+      const perSheet = /* @__PURE__ */ new Map();
+      if (renderPages.length) {
+        const off = await s.office(o.sofficeTimeoutMs, inputPath, signal, runCapped, EXCEL_PDF_FILTER);
+        if (!off.ok) skip = off.kind === "missing" ? "LibreOffice not found" : off.kind === "timeout" ? `soffice failed: timeout after ${o.sofficeTimeoutMs}ms` : off.kind === "exit" ? `soffice failed: exit ${off.code}` : "soffice produced no PDF";
+        else {
+          try {
+            const rp = await s.runTier("render-pages", { path: off.pdfPath, sheetIndices: renderPages, expectedPages: json.sheetCount, imageDpi: o.imageDpi, imageFormat: o.imageFormat, stagingDir: b.stagingDir, maxOutputBytes: o.maxOutputBytes, pymupdfVersion: o.pymupdfVersion }, b, signal, o.fallbackTimeoutMs, backend);
+            if (!rp.ok) skip = `render failed: ${"userError" in rp ? rp.userError : rp.reason}`;
+            else if (rp.json.ok === false) skip = rp.json.reason ?? "render failed";
+            else {
+              publishSheetImages(b);
+              for (const f of rp.json.failed ?? []) perSheet.set(f.idx, f.reason);
+              for (const d of rp.json.rendered ?? []) if (d.dpi < o.imageDpi) notes.push(`Rendered view s${d.idx}: rendered at ${d.dpi} dpi`);
+            }
+          } finally {
+            off.cleanup();
+          }
+        }
+        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)}`);
@@ -1299,20 +1363,21 @@ async function convertDocument(o, signal, seams) {
         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 = [];
     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")}
 
 ` : "") + 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, 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 = { 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);
@@ -1322,7 +1387,7 @@ async function convertDocument(o, signal, seams) {
   }
 }
 async function inspectDocument(o, signal, seams) {
-  const s = { backend: (c) => getBackend(c, void 0, signal), runTier: runTierReal, ...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}`);
@@ -1340,7 +1405,7 @@ async function inspectDocument(o, signal, seams) {
     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 = (r.json.toc ?? []).map(([level, title, page]) => ({ level, title, page }));
@@ -1397,7 +1462,7 @@ function readCliSettings(cwd, env, warn) {
     if (!existsSync3(file)) continue;
     let raw;
     try {
-      raw = JSON.parse(readFileSync2(file, "utf8")).quiver?.docToMd;
+      raw = JSON.parse(readFileSync(file, "utf8")).quiver?.docToMd;
     } catch {
       warn(`pi-quiver: ${file} is not valid JSON; ignored.`);
       continue;

package/extensions/doc_to_md.ts

@@ -35,7 +35,7 @@ export default function docToMdExtension(pi: ExtensionAPI) {
 		name: "doc_to_md",
 		label: "Convert doc to Markdown bundle",
 		description:
-			"Convert a local PDF/DOCX/PPTX/XLSX/XLS to a Markdown bundle on disk and return a handle (Saved-To, Images-Dir, Page-Count, Outline, diagnostics) - the Markdown itself is never inlined; read the Saved-To file (offset/limit) for content. `info: true` returns page count, metadata and TOC (or the sheet inventory) without converting - use it to pick `pages`. `pages` selects inclusive 1-based pages (PDF/DOCX/PPTX); every page ends with `--- end of page.page_number=N ---`. Images are always extracted into images/ with relative links. Primary engine pymupdf4llm, fallback PyMuPDF text (degraded, marked), pure-JS unpdf only when no Python backend exists. Excel yields per-worksheet matrices with formulas, cached values, merged/hidden disclosure. DOCX/PPTX need LibreOffice (soffice). Use `outputDir` for a durable bundle; without it the bundle lands in a per-call temp dir. Input must be a local file path (use fetch first for URLs).",
+			"Convert a local PDF/DOCX/PPTX/XLSX/XLS to a Markdown bundle on disk and return a handle (Saved-To, Images-Dir, Page-Count, Outline, diagnostics) - the Markdown itself is never inlined; read the Saved-To file (offset/limit) for content. `info: true` returns page count, metadata and TOC (or the sheet inventory) without converting - use it to pick `pages`. `pages` selects inclusive 1-based pages (PDF/DOCX/PPTX); every page ends with `--- end of page.page_number=N ---`. Images are always extracted into images/ with relative links. Primary engine pymupdf4llm, fallback PyMuPDF text (degraded, marked), pure-JS unpdf only when no Python backend exists. Excel yields a sheet inventory (worksheets + chartsheets), a full CSV per non-empty worksheet under sheets/, a bounded preview with formulas and cached values, merged/hidden disclosure, and rendered chart views when LibreOffice is available. DOCX/PPTX need LibreOffice (soffice). Use `outputDir` for a durable bundle; without it the bundle lands in a per-call temp dir. Input must be a local file path (use fetch first for URLs).",
 		promptSnippet: "Convert a local PDF/DOCX/PPTX/XLSX to a Markdown bundle (handle returned; read Saved-To)",
 		parameters: buildSchema(),
 

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 });
 }