pi-filler 0.3.0 → 0.4.0

package/README.md

@@ -47,7 +47,7 @@ The extension exposes one `filler` tool:
 ``` text
 format: docx | pdf | pptx | xlsx
 action: read | search | write | patch
-view: text | formatting | image | structure
+view: text | formatting | image | structure | review
 ```
 
 `format` names the document or target format, not every input: DOCX and
@@ -57,9 +57,11 @@ combination and supply only its relevant fields:
 
 | Format | Action | View | Required additional fields |
 |---------------|---------------|---------------|---------------------------|
-| DOCX | `read` | `text` or `formatting` | none |
+| DOCX | `read` | `text` | optional `track_changes` |
+| DOCX | `read` | `formatting` | none |
+| DOCX | `read` | `review` | optional `review_offset`, `review_limit` |
 | DOCX | `read` | `image` | `output`; optional `first_page`, `last_page` |
-| DOCX | `search` | `text` or omitted | `query`; optional `ignore_case` |
+| DOCX | `search` | `text` or omitted | `query`; optional `ignore_case`, `track_changes` |
 | DOCX | `write` | omitted | Markdown `path`, `output`; optional `reference_docx` |
 | DOCX | `patch` | omitted | `output`, `patches`; optional `dry_run` |
 | PPTX | `read` | `text` or `formatting` | none |
@@ -136,17 +138,40 @@ inputs.
 
 ## DOCX operations
 
-- Text reads and search convert DOCX through Pandoc.
+- Text reads and search use Pandoc Markdown, not GFM. `track_changes`
+  defaults to `accept`; choose `reject` for pre-edit text or `all` for
+  insertion/deletion spans and comments. This selects an extraction
+  view; it does not perform native Word acceptance or rejection.
 - Image reads convert DOCX through LibreOffice and then render the
   resulting PDF pages.
-- Writes convert a Markdown input into a validated DOCX, optionally
-  using a reference DOCX for styles and layout.
+- Writes convert Pandoc Markdown into a validated DOCX, including
+  supported native review spans and anchored comments. Smart typography
+  is disabled, preserving literal quotes and dashes. An optional
+  reference DOCX supplies styles and layout defaults; conversion is not
+  a lossless round trip of existing Word layout, comment threads, or
+  every revision type.
 - Formatting reads inspect page setup, margins, sections, line and page
   numbering, comments, inserted/deleted tracked-change markers, and
   common core metadata.
+- Review reads return comment IDs, bounded text/author/date fields,
+  main-document anchor excerpts, and supported legacy reply/resolution
+  metadata. They never edit comments or resolve threads.
 - Patches change first-section page setup, margins, line numbering, page
   numbering, and common core metadata.
 
+Review pagination uses zero-based `review_offset` (default 0) and
+`review_limit` (default 20, maximum 50). A byte budget may return fewer
+records; follow `nextOffset` until it is null. Comment text is capped at
+1,000 Unicode code points and anchor excerpts at 200, with truncation
+flags; author/date fields are bounded to 128/64 UTF-16 code units.
+Ranges include insertion and deletion text, not an accepted-view
+projection. Point anchors show paragraph context. A missing anchor means
+not found in the main document, not necessarily a damaged comment.
+Legacy `commentsExtended` metadata supports resolution and reply-parent
+reporting where matched; additional modern thread features may be
+unsupported and are reported as warnings. This is not native Word
+acceptance/rejection or a complete review-history export.
+
 DOCX page dimensions and margins use twips (twentieths of a point); 1
 inch is 1,440 twips. Page setup, margins, line numbering, and page
 numbering patches apply to the first section only. Core-metadata patches
@@ -232,7 +257,8 @@ or replacing output; its required `output` path is still validated.
 Required for the corresponding operations:
 
 - `pandoc` for DOCX/PPTX text conversion, search, and generation;
-- `libreoffice` for DOCX, PPTX, and XLSX image rendering;
+- `libreoffice` for DOCX, PPTX, and XLSX image rendering (each
+  conversion uses a private temporary profile, removed on completion);
 - `pdftotext` for PDF text extraction;
 - `pdftocairo` for PDF, DOCX, PPTX, and XLSX page rendering; and
 - `pdfgrep` for page-aware PDF search.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-filler",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Deterministic DOCX, PDF, and XLSX tooling for Pi",
 	"keywords": [
 		"pi-package",

package/src/docx.ts

@@ -51,21 +51,30 @@ export interface DocxPatchResult {
 }
 
 type Package = OfficePackage;
-type XmlObject = Record<string, unknown>;
+type XmlObject = { children: XmlEntry[]; attributes: Record<string, string> };
+type XmlEntry = Record<string, unknown>;
 
 const WORD_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
 const CORE_NS = "http://schemas.openxmlformats.org/package/2006/metadata/core-properties";
 const DC_NS = "http://purl.org/dc/elements/1.1/";
 
-const parser = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "@_" });
-const builder = new XMLBuilder({
+const xmlOptions = {
 	ignoreAttributes: false,
 	attributeNamePrefix: "@_",
-	format: false,
-});
+	preserveOrder: true,
+	parseTagValue: false,
+	parseAttributeValue: false,
+	trimValues: false,
+	commentPropName: "#comment",
+	cdataPropName: "#cdata",
+};
+const parser = new XMLParser(xmlOptions);
+const builder = new XMLBuilder(xmlOptions);
 
-function isObject(value: unknown): value is XmlObject {
-	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+function wrap(entry: XmlEntry, key: string): XmlObject {
+	entry[":@"] ??= {};
+	const attributes = entry[":@"] as Record<string, string>;
+	return { children: entry[key] as XmlEntry[], attributes };
 }
 
 function localName(name: string): string {
@@ -75,43 +84,44 @@ function localName(name: string): string {
 function parseXml(bytes: Uint8Array | undefined, part: string): XmlObject {
 	if (!bytes) throw new Error(`DOCX is missing required part ${part}`);
 	try {
-		return parser.parse(new TextDecoder().decode(bytes), true) as XmlObject;
+		return {
+			children: parser.parse(new TextDecoder().decode(bytes), true) as XmlEntry[],
+			attributes: {},
+		};
 	} catch (error) {
 		throw new Error(`Invalid XML in ${part}: ${error instanceof Error ? error.message : error}`);
 	}
 }
 
 function serializeXml(value: XmlObject): Uint8Array {
-	return new TextEncoder().encode(builder.build(value));
+	return new TextEncoder().encode(builder.build(value.children));
 }
 
 function unpack(bytes: Uint8Array): Package {
 	return unpackOfficePackage(bytes, "DOCX");
 }
 
-function findAll(value: unknown, suffix: string, found: XmlObject[] = []): XmlObject[] {
-	if (!value || typeof value !== "object") return found;
-	for (const [key, child] of Object.entries(value)) {
-		if (!key.startsWith("@_") && localName(key) === suffix) {
-			for (const item of Array.isArray(child) ? child : [child]) {
-				if (isObject(item)) found.push(item);
-			}
+function findAll(value: XmlObject, suffix: string, found: XmlObject[] = []): XmlObject[] {
+	for (const entry of value.children) {
+		for (const [key, child] of Object.entries(entry)) {
+			if (!Array.isArray(child)) continue;
+			const node = wrap(entry, key);
+			if (localName(key) === suffix) found.push(node);
+			findAll(node, suffix, found);
 		}
-		findAll(child, suffix, found);
 	}
 	return found;
 }
 
-function first(value: unknown, suffix: string): XmlObject | undefined {
+function first(value: XmlObject, suffix: string): XmlObject | undefined {
 	return findAll(value, suffix)[0];
 }
 
 function directObject(value: XmlObject | undefined, suffix: string): XmlObject | undefined {
 	if (!value) return undefined;
-	for (const [key, child] of Object.entries(value)) {
-		if (key.startsWith("@_") || localName(key) !== suffix) continue;
-		const candidate = Array.isArray(child) ? child[0] : child;
-		return isObject(candidate) ? candidate : undefined;
+	for (const entry of value.children) {
+		const key = Object.keys(entry).find((name) => name !== ":@" && localName(name) === suffix);
+		if (key && Array.isArray(entry[key])) return wrap(entry, key);
 	}
 	return undefined;
 }
@@ -124,7 +134,7 @@ function rootObject(value: XmlObject, suffix: string): XmlObject {
 
 function attr(value: XmlObject | undefined, name: string): string | undefined {
 	if (!value) return undefined;
-	for (const [key, child] of Object.entries(value)) {
+	for (const [key, child] of Object.entries(value.attributes)) {
 		if (key.startsWith("@_") && localName(key) === name && child !== undefined) {
 			return String(child);
 		}
@@ -138,27 +148,35 @@ function numberAttr(value: XmlObject | undefined, name: string): number | undefi
 }
 
 function namespacePrefix(root: XmlObject, uri: string, preferred: string): string {
-	for (const [key, value] of Object.entries(root)) {
+	for (const [key, value] of Object.entries(root.attributes)) {
 		if (key.startsWith("@_xmlns:") && value === uri) return key.slice("@_xmlns:".length);
 	}
-	root[`@_xmlns:${preferred}`] = uri;
-	return preferred;
+	let prefix = preferred;
+	for (let suffix = 1; root.attributes[`@_xmlns:${prefix}`] !== undefined; suffix++) {
+		prefix = `${preferred}${suffix}`;
+	}
+	root.attributes[`@_xmlns:${prefix}`] = uri;
+	return prefix;
 }
 
 function setAttr(value: XmlObject, name: string, setting: number | string, prefix: string): void {
-	const existing = Object.keys(value).find(
+	const existing = Object.keys(value.attributes).find(
 		(key) => key.startsWith("@_") && localName(key) === name,
 	);
-	value[existing ?? `@_${prefix}:${name}`] = String(setting);
+	value.attributes[existing ?? `@_${prefix}:${name}`] = String(setting);
 }
 
 function removeDirect(value: XmlObject, name: string): void {
-	for (const key of Object.keys(value)) {
-		if (!key.startsWith("@_") && localName(key) === name) delete value[key];
-	}
+	value.children.splice(
+		0,
+		value.children.length,
+		...value.children.filter(
+			(entry) => !Object.keys(entry).some((key) => key !== ":@" && localName(key) === name),
+		),
+	);
 }
 
-function countTags(value: unknown, suffix: string): number {
+function countTags(value: XmlObject, suffix: string): number {
 	return findAll(value, suffix).length;
 }
 
@@ -175,31 +193,31 @@ const metadataNamespaces: Record<string, string> = {
 	lastModifiedBy: CORE_NS,
 };
 
-function childText(value: XmlObject, name: string): string | undefined {
-	for (const [key, child] of Object.entries(value)) {
-		if (key.startsWith("@_") || localName(key) !== name) continue;
-		if (typeof child === "string" || typeof child === "number") return String(child);
-		if (isObject(child)) {
-			const text = child["#text"];
-			if (typeof text === "string" || typeof text === "number") return String(text);
-		}
+function literalText(value: XmlObject): string {
+	let text = "";
+	for (const entry of value.children) {
+		if (entry["#text"] !== undefined) text += String(entry["#text"]);
+		else
+			for (const [key, child] of Object.entries(entry)) {
+				if (Array.isArray(child)) text += literalText(wrap(entry, key));
+			}
 	}
-	return undefined;
+	return text;
+}
+
+function childText(value: XmlObject, name: string): string | undefined {
+	const child = directObject(value, name);
+	return child ? literalText(child) : undefined;
 }
 
 function setChildText(value: XmlObject, name: string, text: string): void {
-	const existing = Object.keys(value).find(
-		(key) => !key.startsWith("@_") && localName(key) === name,
-	);
-	if (existing) {
-		const child = value[existing];
-		if (isObject(child)) child["#text"] = text;
-		else value[existing] = text;
-		return;
+	let child = directObject(value, name);
+	if (!child) {
+		const uri = metadataNamespaces[name] ?? DC_NS;
+		const prefix = namespacePrefix(value, uri, uri === CORE_NS ? "cp" : "dc");
+		child = ensureChild(value, name, prefix);
 	}
-	const uri = metadataNamespaces[name] ?? DC_NS;
-	const prefix = namespacePrefix(value, uri, uri === CORE_NS ? "cp" : "dc");
-	value[`${prefix}:${name}`] = text;
+	child.children.splice(0, child.children.length, { "#text": text });
 }
 
 function coreMetadata(pkg: Package): Record<string, string> {
@@ -217,8 +235,9 @@ function coreMetadata(pkg: Package): Record<string, string> {
 function countTrackedChanges(pkg: Package, document: XmlObject): number {
 	let count = countTags(document, "ins") + countTags(document, "del");
 	const contentPart = /^word\/(?:header\d+|footer\d+|footnotes|endnotes|comments)\.xml$/;
+	const commentPart = relatedPart(pkg, "comments", "word/comments.xml");
 	for (const [part, bytes] of Object.entries(pkg)) {
-		if (!contentPart.test(part)) continue;
+		if (!contentPart.test(part) && part !== commentPart) continue;
 		const content = parseXml(bytes, part);
 		count += countTags(content, "ins") + countTags(content, "del");
 	}
@@ -233,6 +252,7 @@ function inspectPackage(pkg: Package): DocxFormatting {
 	const margin = directObject(section, "pgMar");
 	const line = directObject(section, "lnNumType");
 	const pageNum = directObject(section, "pgNumType");
+	const commentsPart = relatedPart(pkg, "comments", "word/comments.xml");
 	return {
 		page: {
 			width: numberAttr(size, "w"),
@@ -251,8 +271,8 @@ function inspectPackage(pkg: Package): DocxFormatting {
 			count_by: numberAttr(line, "countBy"),
 		},
 		pageNumbering: { start: numberAttr(pageNum, "start"), format: attr(pageNum, "fmt") },
-		comments: pkg["word/comments.xml"]
-			? countTags(parseXml(pkg["word/comments.xml"], "word/comments.xml"), "comment")
+		comments: pkg[commentsPart]
+			? countTags(parseXml(pkg[commentsPart], commentsPart), "comment")
 			: 0,
 		trackedChanges: countTrackedChanges(pkg, document),
 		metadata: coreMetadata(pkg),
@@ -264,16 +284,48 @@ function firstSection(document: XmlObject, prefix: string): XmlObject {
 	if (existing) return existing;
 	const body = first(document, "body");
 	if (!body) throw new Error("DOCX is missing document body");
-	const section: XmlObject = {};
-	body[`${prefix}:sectPr`] = section;
-	return section;
-}
+	return ensureChild(body, "sectPr", prefix);
+}
+
+// CT_SectPr sequence: insert new properties without moving existing children.
+const sectionOrder = [
+	"headerReference",
+	"footerReference",
+	"footnotePr",
+	"endnotePr",
+	"type",
+	"pgSz",
+	"pgMar",
+	"paperSrc",
+	"pgBorders",
+	"lnNumType",
+	"pgNumType",
+	"cols",
+	"formProt",
+	"vAlign",
+	"noEndnote",
+	"titlePg",
+	"textDirection",
+	"bidi",
+	"rtlGutter",
+	"docGrid",
+	"printerSettings",
+	"sectPrChange",
+];
 
 function ensureChild(parent: XmlObject, name: string, prefix: string): XmlObject {
 	let child = directObject(parent, name);
 	if (!child) {
-		child = {};
-		parent[`${prefix}:${name}`] = child;
+		const entry: XmlEntry = { [`${prefix}:${name}`]: [] };
+		const rank = sectionOrder.indexOf(name);
+		const next =
+			rank < 0
+				? -1
+				: parent.children.findIndex((node) =>
+						Object.keys(node).some((key) => sectionOrder.indexOf(localName(key)) > rank),
+					);
+		parent.children.splice(next < 0 ? parent.children.length : next, 0, entry);
+		child = wrap(entry, `${prefix}:${name}`);
 	}
 	return child;
 }
@@ -470,6 +522,166 @@ async function load(path: string): Promise<Package> {
 	return unpack(new Uint8Array(await readFile(resolve(path))));
 }
 
+export interface DocxReviewComment {
+	id: string;
+	author?: string;
+	date?: string;
+	text: string;
+	textTruncated: boolean;
+	anchor: { kind: "range" | "point" | "unmatched" | "not-found"; text: string; truncated: boolean };
+	resolved?: boolean;
+	replyTo?: string;
+}
+
+function reviewText(node: XmlObject): string {
+	let text = "";
+	for (const entry of node.children) {
+		for (const [name, value] of Object.entries(entry)) {
+			if (!Array.isArray(value)) continue;
+			const child = wrap(entry, name);
+			const tag = localName(name);
+			if (tag === "t" || tag === "delText") {
+				text += literalText(child);
+			} else if (tag === "tab") text += "\t";
+			else if (tag === "br" || tag === "cr") text += "\n";
+			else text += reviewText(child);
+			if (tag === "p") text += "\n";
+		}
+	}
+	return text;
+}
+
+function relatedPart(pkg: Package, suffix: string, fallback: string): string {
+	const bytes = pkg["word/_rels/document.xml.rels"];
+	if (bytes) {
+		for (const rel of findAll(parseXml(bytes, "word/_rels/document.xml.rels"), "Relationship")) {
+			if (attr(rel, "Type")?.endsWith(`/${suffix}`) && attr(rel, "TargetMode") !== "External") {
+				const target = attr(rel, "Target") ?? "";
+				return posix.normalize(
+					target.startsWith("/") ? target.slice(1) : posix.join("word", target),
+				);
+			}
+		}
+	}
+	return fallback;
+}
+
+/** Read-only, bounded inspection; anchors include all revision text in the main document. */
+export async function inspectDocxReview(path: string, offset = 0, limit = 20) {
+	if (!Number.isInteger(offset) || offset < 0)
+		throw new Error("review_offset must be a nonnegative integer");
+	if (!Number.isInteger(limit) || limit < 1 || limit > 50)
+		throw new Error("review_limit must be between 1 and 50");
+	const pkg = await load(path);
+	validatePackage(pkg);
+	const part = relatedPart(pkg, "comments", "word/comments.xml");
+	const comments = pkg[part] ? findAll(parseXml(pkg[part], part), "comment") : [];
+	const selected = comments.slice(offset, offset + limit);
+	const warnings = new Set<string>();
+	const anchors = new Map<string, DocxReviewComment["anchor"]>();
+	const active = new Set<string>();
+	const ids = new Set(selected.map((comment) => attr(comment, "id") ?? ""));
+	const clip = (value: string, size: number) => [...value].slice(0, size).join("");
+	function append(text: string) {
+		for (const id of active) {
+			const anchor = anchors.get(id);
+			if (!anchor) continue;
+			const combined = anchor.text + text;
+			anchor.text = clip(combined, 200);
+			anchor.truncated ||= anchor.text !== combined;
+		}
+	}
+	function walk(node: XmlObject, paragraph = "") {
+		for (const entry of node.children) {
+			for (const [name, value] of Object.entries(entry)) {
+				if (!Array.isArray(value)) continue;
+				const child = wrap(entry, name);
+				const tag = localName(name);
+				const id = attr(child, "id") ?? "";
+				if (tag === "commentRangeStart" && ids.has(id)) {
+					if (anchors.has(id))
+						warnings.add(
+							"Multiple or overlapping ranges for the same comment ID are not fully represented.",
+						);
+					anchors.set(id, { kind: "unmatched", text: "", truncated: false });
+					active.add(id);
+				} else if (tag === "commentRangeEnd" && ids.has(id)) {
+					const anchor = anchors.get(id);
+					if (anchor && active.has(id)) {
+						anchor.kind = "range";
+						active.delete(id);
+					} else warnings.add("An unmatched comment range end was found.");
+				} else if (tag === "commentReference" && ids.has(id) && !anchors.has(id)) {
+					anchors.set(id, {
+						kind: "point",
+						text: clip(paragraph, 200),
+						truncated: [...paragraph].length > 200,
+					});
+				} else if (tag === "t" || tag === "delText") {
+					append(literalText(child));
+				} else if (tag === "tab") append("\t");
+				else if (tag === "br" || tag === "cr") append("\n");
+				else walk(child, tag === "p" ? reviewText(child) : paragraph);
+				if (tag === "p") append("\n");
+			}
+		}
+	}
+	walk(parseXml(pkg["word/document.xml"], "word/document.xml"));
+	if (active.size) warnings.add("Some comment ranges have no closing marker.");
+	const extendedPart = relatedPart(pkg, "commentsExtended", "word/commentsExtended.xml");
+	const extended = pkg[extendedPart]
+		? findAll(parseXml(pkg[extendedPart], extendedPart), "commentEx")
+		: [];
+	const paraIds = new Map(
+		comments.map((comment) => [attr(findAll(comment, "p").at(-1), "paraId"), attr(comment, "id")]),
+	);
+	const result: DocxReviewComment[] = [];
+	let consumed = 0;
+	for (const comment of selected) {
+		const id = attr(comment, "id") ?? "";
+		if (Buffer.byteLength(id) > 512)
+			throw new Error("DOCX comment identifier exceeds inspection limit");
+		const fullText = reviewText(comment).replace(/\n$/, "");
+		const text = clip(fullText, 1000);
+		const paraId = attr(findAll(comment, "p").at(-1), "paraId");
+		const ex =
+			paraId === undefined ? undefined : extended.find((item) => attr(item, "paraId") === paraId);
+		const done = attr(ex, "done");
+		const knownDone = done !== undefined && ["1", "0", "true", "false", "on", "off"].includes(done);
+		if (done !== undefined && !knownDone)
+			warnings.add("An unsupported comment resolution value was found.");
+		const parent = attr(ex, "paraIdParent");
+		const record: DocxReviewComment = {
+			id,
+			author: attr(comment, "author")?.slice(0, 128),
+			date: attr(comment, "date")?.slice(0, 64),
+			text,
+			textTruncated: text !== fullText,
+			anchor: anchors.get(id) ?? { kind: "not-found", text: "", truncated: false },
+			resolved: knownDone ? ["1", "true", "on"].includes(done ?? "") : undefined,
+			replyTo: parent === undefined ? undefined : paraIds.get(parent),
+		};
+		if (parent !== undefined && record.replyTo === undefined)
+			warnings.add("A comment reply parent could not be matched.");
+		if (result.length && Buffer.byteLength(JSON.stringify([...result, record])) > 24000) break;
+		result.push(record);
+		consumed++;
+	}
+	if (Object.keys(pkg).some((name) => /comments(?:Ids|Extensible)|people\.xml/.test(name)))
+		warnings.add(
+			"Additional modern comment metadata is present; not all thread features are inspected.",
+		);
+	return {
+		totalComments: comments.length,
+		offset,
+		returned: result.length,
+		nextOffset: offset + consumed < comments.length ? offset + consumed : null,
+		comments: result,
+		warnings: [...warnings],
+		anchorScope: "main document, including insertion and deletion text",
+	};
+}
+
 export async function inspectDocx(path: string): Promise<DocxFormatting> {
 	const pkg = await load(path);
 	validatePackage(pkg);

package/src/index.ts

@@ -1,7 +1,7 @@
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
-import { StringEnum } from "@earendil-works/pi-ai";
+import { pathToFileURL } from "node:url";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
 	DEFAULT_MAX_BYTES,
@@ -9,7 +9,7 @@ import {
 	withFileMutationQueue,
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
-import { type DocxPatchSet, inspectDocx, patchDocx } from "./docx.js";
+import { type DocxPatchSet, inspectDocx, inspectDocxReview, patchDocx } from "./docx.js";
 import {
 	readDocxText,
 	readPptxText,
@@ -34,7 +34,7 @@ const docxPatchesSchema = Type.Object(
 					height: Type.Optional(
 						Type.Integer({ description: "Page height in twips (1/20 point)", minimum: 1 }),
 					),
-					orientation: Type.Optional(StringEnum(["portrait", "landscape"] as const)),
+					orientation: Type.Optional(Type.Enum(["portrait", "landscape"], { type: "string" })),
 				},
 				{
 					additionalProperties: false,
@@ -64,7 +64,9 @@ const docxPatchesSchema = Type.Object(
 		lineNumbering: Type.Optional(
 			Type.Object(
 				{
-					mode: Type.Optional(StringEnum(["off", "continuous", "newPage", "newSection"] as const)),
+					mode: Type.Optional(
+						Type.Enum(["off", "continuous", "newPage", "newSection"], { type: "string" }),
+					),
 					start: Type.Optional(Type.Integer({ description: "Starting line number", minimum: 0 })),
 					count_by: Type.Optional(Type.Integer({ description: "Numbering interval", minimum: 1 })),
 				},
@@ -210,8 +212,8 @@ const xlsxPatchesSchema = Type.Object(
 		alignment: Type.Optional(
 			Type.Object(
 				{
-					horizontal: Type.Optional(StringEnum(["left", "center", "right"] as const)),
-					vertical: Type.Optional(StringEnum(["top", "center", "bottom"] as const)),
+					horizontal: Type.Optional(Type.Enum(["left", "center", "right"], { type: "string" })),
+					vertical: Type.Optional(Type.Enum(["top", "center", "bottom"], { type: "string" })),
 					wrap_text: Type.Optional(Type.Boolean()),
 				},
 				{ additionalProperties: false, description: "Cell alignment changes", minProperties: 1 },
@@ -222,7 +224,7 @@ const xlsxPatchesSchema = Type.Object(
 		),
 		border: Type.Optional(
 			Type.Object(
-				{ style: Type.Optional(StringEnum(["thin", "medium", "thick"] as const)) },
+				{ style: Type.Optional(Type.Enum(["thin", "medium", "thick"], { type: "string" })) },
 				{ additionalProperties: false, minProperties: 1 },
 			),
 		),
@@ -246,14 +248,17 @@ const xlsxPatchesSchema = Type.Object(
 
 export const fillerSchema = Type.Object(
 	{
-		format: StringEnum(["docx", "pdf", "pptx", "xlsx"] as const, {
+		format: Type.Enum(["docx", "pdf", "pptx", "xlsx"], {
+			type: "string",
 			description: "Document or target format; selects supported operations and path roles",
 		}),
-		action: StringEnum(["read", "search", "write", "patch"] as const, {
+		action: Type.Enum(["read", "search", "write", "patch"], {
+			type: "string",
 			description: "Operation; supported combinations depend on format and view",
 		}),
 		view: Type.Optional(
-			StringEnum(["text", "formatting", "image", "structure"] as const, {
+			Type.Enum(["text", "formatting", "image", "structure", "review"], {
+				type: "string",
 				description: "Read/search representation; omit for write and patch",
 			}),
 		),
@@ -272,6 +277,28 @@ export const fillerSchema = Type.Object(
 		query: Type.Optional(
 			Type.String({ description: "DOCX, PDF, or PPTX search query", minLength: 1 }),
 		),
+		review_offset: Type.Optional(
+			Type.Integer({
+				minimum: 0,
+				default: 0,
+				description: "DOCX review read: zero-based comment offset",
+			}),
+		),
+		review_limit: Type.Optional(
+			Type.Integer({
+				minimum: 1,
+				maximum: 50,
+				default: 20,
+				description: "DOCX review read: maximum comments; byte budget may return fewer",
+			}),
+		),
+		track_changes: Type.Optional(
+			Type.Enum(["accept", "reject", "all"], {
+				type: "string",
+				default: "accept",
+				description: "DOCX text read/search revision view; all includes review spans and comments",
+			}),
+		),
 		reference_docx: Type.Optional(
 			Type.String({ description: "Reference DOCX for writes", minLength: 1 }),
 		),
@@ -303,7 +330,8 @@ export const fillerSchema = Type.Object(
 			Type.Boolean({ default: true, description: "Skip the first CSV record as a header" }),
 		),
 		value_mode: Type.Optional(
-			StringEnum(["text", "auto"] as const, {
+			Type.Enum(["text", "auto"], {
+				type: "string",
 				default: "text",
 				description: "Write CSV fields as text, or infer only empty, number, and boolean values",
 			}),
@@ -357,6 +385,9 @@ type ControlField = Exclude<keyof FillerInput, "format" | "action" | "view" | "p
 const controlFields: ControlField[] = [
 	"output",
 	"query",
+	"track_changes",
+	"review_offset",
+	"review_limit",
 	"reference_docx",
 	"pptx_patches",
 	"reference_pptx",
@@ -410,15 +441,21 @@ function assertSupported(input: FillerInput): void {
 	if (!input.path) throw new Error("path must not be empty");
 	if (input.format === "docx") {
 		if (input.action === "read") {
+			if (input.view === "review") {
+				assertParameters(input, ["review_offset", "review_limit"]);
+				return;
+			}
 			if (input.view === "image") {
 				if (!input.output) throw new Error("DOCX image reads require output");
 				assertParameters(input, ["output", "first_page", "last_page"]);
 				return;
 			}
 			if (input.view !== "text" && input.view !== "formatting") {
-				throw new Error("DOCX read requires view=text, view=formatting, or view=image");
+				throw new Error(
+					"DOCX read requires view=text, view=formatting, view=review, or view=image",
+				);
 			}
-			assertParameters(input, []);
+			assertParameters(input, input.view === "text" ? ["track_changes"] : []);
 			return;
 		}
 		if (input.action === "search") {
@@ -426,7 +463,7 @@ function assertSupported(input: FillerInput): void {
 				throw new Error("DOCX search requires view=text or no view");
 			}
 			if (!input.query) throw new Error("DOCX search requires query");
-			assertParameters(input, ["query", "ignore_case"]);
+			assertParameters(input, ["query", "ignore_case", "track_changes"]);
 			return;
 		}
 		if (input.action === "write") {
@@ -556,6 +593,17 @@ export async function executeFiller(
 	const range = { firstPage: input.first_page, lastPage: input.last_page };
 
 	if (input.format === "docx") {
+		if (input.action === "read" && input.view === "review") {
+			const review = await inspectDocxReview(path, input.review_offset, input.review_limit);
+			return {
+				text: JSON.stringify(review, null, 2),
+				details: {
+					totalComments: review.totalComments,
+					returned: review.returned,
+					nextOffset: review.nextOffset,
+				},
+			};
+		}
 		if (input.action === "read" && input.view === "formatting") {
 			const formatting = await inspectDocx(path);
 			return { text: JSON.stringify(formatting, null, 2), details: { formatting } };
@@ -566,7 +614,15 @@ export async function executeFiller(
 			try {
 				const converted = await runCommand(
 					"libreoffice",
-					["--headless", "--convert-to", "pdf", "--outdir", temporary, path],
+					[
+						`-env:UserInstallation=${pathToFileURL(join(temporary, "profile")).href}`,
+						"--headless",
+						"--convert-to",
+						"pdf",
+						"--outdir",
+						temporary,
+						path,
+					],
 					{ signal, cwd: temporary },
 				);
 				if (converted.code !== 0) throw commandError(converted, "libreoffice");
@@ -583,11 +639,12 @@ export async function executeFiller(
 			}
 		}
 		if (input.action === "read") {
-			const result = await readDocxText(path, { signal });
+			const result = await readDocxText(path, { signal, trackChanges: input.track_changes });
 			return { text: result.text, details: { truncation: result.truncation } };
 		}
 		if (input.action === "search") {
 			const result = await searchDocx(path, input.query ?? "", {
+				trackChanges: input.track_changes,
 				ignoreCase: input.ignore_case,
 				signal,
 			});
@@ -629,7 +686,15 @@ export async function executeFiller(
 			try {
 				const converted = await runCommand(
 					"libreoffice",
-					["--headless", "--convert-to", "pdf", "--outdir", temporary, path],
+					[
+						`-env:UserInstallation=${pathToFileURL(join(temporary, "profile")).href}`,
+						"--headless",
+						"--convert-to",
+						"pdf",
+						"--outdir",
+						temporary,
+						path,
+					],
 					{ signal, cwd: temporary },
 				);
 				if (converted.code !== 0) throw commandError(converted, "libreoffice");
@@ -689,7 +754,15 @@ export async function executeFiller(
 				try {
 					const converted = await runCommand(
 						"libreoffice",
-						["--headless", "--convert-to", "pdf", "--outdir", temporary, path],
+						[
+							`-env:UserInstallation=${pathToFileURL(join(temporary, "profile")).href}`,
+							"--headless",
+							"--convert-to",
+							"pdf",
+							"--outdir",
+							temporary,
+							path,
+						],
 						{ signal, cwd: temporary },
 					);
 					if (converted.code !== 0) throw commandError(converted, "libreoffice");
@@ -789,13 +862,13 @@ export default function extension(pi: ExtensionAPI): void {
 			"Work directly with local DOCX, PDF, PPTX, and XLSX files using supported format/action/view combinations.",
 		promptGuidelines: [
 			"Use filler when a supported deterministic local DOCX, PDF, PPTX, or XLSX operation satisfies the task; choose a supported format/action/view combination and provide only that operation's fields.",
-			"For filler reads, use DOCX or PPTX text, formatting, or image; PDF text or image; or XLSX structure or image.",
+			"For filler reads, use DOCX text, formatting, review, or image; PPTX text, formatting, or image; PDF text or image; or XLSX structure or image. DOCX review returns bounded comment text, authors, main-document anchor excerpts, and supported legacy reply/resolution metadata; review_offset defaults to 0 and review_limit to 20 (max 50). Follow nextOffset; text/excerpts may be truncated and modern thread metadata may be unsupported.",
 			"For filler searches, use DOCX, PPTX, or PDF text (or omit view); XLSX search is unsupported.",
 			"For filler image output, use an existing directory or PNG prefix; the operation creates numbered page/slide images, not one final PNG. DOCX, PPTX, and XLSX images convert through LibreOffice; XLSX images render workbook print pages and do not accept sheet. first_page and last_page select resulting pages.",
-			"For DOCX/PPTX writes, path is Markdown and output is the new document; reference_docx/reference_pptx is optional. PPTX uses GFM Markdown. For XLSX writes, path is the template and source_csv, sheet, A1-style start_cell, and output are required; column_map optionally maps all CSV ordinals or all exact headers to XLSX columns.",
+			"For DOCX/PPTX writes, path is Markdown and output is the new document; reference_docx/reference_pptx is optional. DOCX uses Pandoc Markdown (smart typography disabled), including native review spans; PPTX uses GFM Markdown. DOCX generation is not a lossless round trip of an existing Word layout. For XLSX writes, path is the template and source_csv, sheet, A1-style start_cell, and output are required; column_map optionally maps all CSV ordinals or all exact headers to XLSX columns.",
 			"When an XLSX write or patch can perform the requested deterministic transformation without inspecting CSV or cell contents, do not read those contents into model context merely to carry out the transformation. Processing stays local and results do not return cell or CSV contents.",
 			"For filler patches, provide a new output path plus DOCX patches, PPTX pptx_patches, or XLSX sheet, A1-style range, and xlsx_patches. PPTX text replacements target slide text paragraphs and may name a 1-based slide. dry_run: true still requires output but does not create or replace it.",
-			"For filler defaults, PDF queries are regular expressions by default; use literal: true for literal text. XLSX writes skip a header and preserve text by default.",
+			"For filler DOCX text reads/searches, track_changes defaults to accept; use reject for the pre-edit text or all for insertion/deletion spans and comments. This selects an extraction view, not native Word acceptance/rejection. For filler defaults, PDF queries are regular expressions by default; use literal: true for literal text. XLSX writes skip a header and preserve text by default.",
 			"For filler results, DOCX/PPTX search may be truncated; narrow its query. PDF text or search may be truncated; narrow its page range or query.",
 		],
 		parameters: fillerSchema,

package/src/pandoc.ts

@@ -6,6 +6,12 @@ import { inspectDocx } from "./docx.js";
 import { inspectPptx } from "./pptx.js";
 import { commandError, type RunCommandOptions, runCommand } from "./process.js";
 
+export type TrackChanges = "accept" | "reject" | "all";
+
+export interface DocxReadOptions extends RunCommandOptions {
+	trackChanges?: TrackChanges;
+}
+
 export interface DocxTextResult {
 	text: string;
 	truncation: TruncationResult;
@@ -34,18 +40,22 @@ async function runPandoc(
 async function extractMarkdown(
 	path: string,
 	from: "docx" | "pptx",
-	options?: RunCommandOptions,
+	options?: DocxReadOptions,
 ): Promise<string> {
 	const source = resolve(path);
-	const output = await runPandoc(
-		[`--from=${from}`, "--to=gfm", "--wrap=none", source],
-		options,
-		source,
-	);
+	const args =
+		from === "docx"
+			? [
+					"--from=docx",
+					"--to=markdown-smart",
+					`--track-changes=${options?.trackChanges ?? "accept"}`,
+				]
+			: ["--from=pptx", "--to=gfm"];
+	const output = await runPandoc([...args, "--wrap=none", source], options, source);
 	return output.toString("utf8");
 }
 
-async function extractDocxMarkdown(path: string, options?: RunCommandOptions): Promise<string> {
+async function extractDocxMarkdown(path: string, options?: DocxReadOptions): Promise<string> {
 	return extractMarkdown(path, "docx", options);
 }
 
@@ -55,7 +65,7 @@ async function extractPptxMarkdown(path: string, options?: RunCommandOptions): P
 
 export async function readDocxText(
 	path: string,
-	options?: RunCommandOptions,
+	options?: DocxReadOptions,
 ): Promise<DocxTextResult> {
 	const truncation = truncateHead(await extractDocxMarkdown(path, options));
 	return { text: truncation.content, truncation };
@@ -75,7 +85,7 @@ function searchMarkdown(extracted: string, query: string, ignoreCase = false): D
 export async function searchDocx(
 	path: string,
 	query: string,
-	options: RunCommandOptions & { ignoreCase?: boolean } = {},
+	options: DocxReadOptions & { ignoreCase?: boolean } = {},
 ): Promise<DocxSearchResult> {
 	return searchMarkdown(await extractDocxMarkdown(path, options), query, options.ignoreCase);
 }
@@ -117,7 +127,7 @@ export async function writeDocx(
 		`.${output.split(/[\\/]/).pop() ?? "output.docx"}.${randomUUID()}.tmp`,
 	);
 	await mkdir(dirname(output), { recursive: true });
-	const args = ["--from=gfm", "--to=docx", "--output", temporary];
+	const args = ["--from=markdown-smart", "--to=docx", "--output", temporary];
 	if (options.referenceDocx) args.push("--reference-doc", resolve(options.referenceDocx));
 	args.push(source);
 	try {