pi-filler 0.2.0 → 0.3.0

package/README.md

@@ -10,11 +10,11 @@ version](https://img.shields.io/npm/v/pi-filler.svg)](https://www.npmjs.com/pack
 downloads](https://img.shields.io/npm/dt/pi-filler.svg)](https://www.npmjs.com/package/pi-filler)
 [![license](https://img.shields.io/npm/l/pi-filler.svg)](https://gitlab.com/Joao-O-Santos/pi-filler/-/blob/main/LICENSE)
 
-**Deterministic DOCX, PDF, and XLSX tooling for Pi.**
+**Deterministic DOCX, PDF, PPTX, and XLSX tooling for Pi.**
 
 `pi-filler` covers document tasks that do not fit an ordinary Markdown
 workflow. It delegates conversion and PDF extraction to mature
-command-line tools while keeping DOCX and XLSX mutations narrow,
+command-line tools while keeping DOCX, PPTX, and XLSX mutations narrow,
 transactional, and inspectable.
 
 The project is experimental and pre-1.0. The README documents the
@@ -45,15 +45,15 @@ Node.js and do not require an office suite.
 The extension exposes one `filler` tool:
 
 ``` text
-format: docx | pdf | xlsx
+format: docx | pdf | pptx | xlsx
 action: read | search | write | patch
 view: text | formatting | image | structure
 ```
 
-`format` names the document or target format, not every input: DOCX
-writes take Markdown at `path`, and XLSX writes take a workbook template
-at `path` plus CSV at `source_csv`. Choose a supported combination and
-supply only its relevant fields:
+`format` names the document or target format, not every input: DOCX and
+PPTX writes take Markdown at `path`, and XLSX writes take a workbook
+template at `path` plus CSV at `source_csv`. Choose a supported
+combination and supply only its relevant fields:
 
 | Format | Action | View | Required additional fields |
 |---------------|---------------|---------------|---------------------------|
@@ -62,11 +62,16 @@ supply only its relevant fields:
 | DOCX | `search` | `text` or omitted | `query`; optional `ignore_case` |
 | DOCX | `write` | omitted | Markdown `path`, `output`; optional `reference_docx` |
 | DOCX | `patch` | omitted | `output`, `patches`; optional `dry_run` |
+| PPTX | `read` | `text` or `formatting` | none |
+| PPTX | `read` | `image` | `output`; optional `first_page`, `last_page` |
+| PPTX | `search` | `text` or omitted | `query`; optional `ignore_case` |
+| PPTX | `write` | omitted | Markdown `path`, `output`; optional `reference_pptx` |
+| PPTX | `patch` | omitted | `output`, `pptx_patches`; optional `dry_run` |
 | PDF | `read` | `text` | optional `first_page`, `last_page` |
 | PDF | `read` | `image` | `output`; optional `first_page`, `last_page` |
 | PDF | `search` | `text` or omitted | `query`; optional `first_page`, `last_page`, `literal`, `ignore_case` |
 | XLSX | `read` | `structure` | none |
-| XLSX | `read` | `image` | `output`; optional `first_page`, `last_page`; all workbook print pages |
+| XLSX | `read` | `image` | `output`; optional `first_page`, `last_page` select resulting workbook print pages |
 | XLSX | `write` | omitted | template `path`, `source_csv`, `sheet`, A1 `start_cell`, `output`; optional `column_map` |
 | XLSX | `patch` | omitted | `sheet`, A1 `range`, `xlsx_patches`, `output` |
 
@@ -115,8 +120,9 @@ filler({
 ```
 
 Results may be truncated. For a truncated PDF text read, use a page
-range; for PDF or DOCX search, narrow the query. PDF search can also use
-a page range. Dry runs still read and validate all local inputs.
+range; for PDF, DOCX, or PPTX search, narrow the query. PDF search can
+also use a page range. Dry runs still read and validate all local
+inputs.
 
 ## PDF operations
 
@@ -156,17 +162,20 @@ or element ordering may change.
 
 ## XLSX operations and privacy
 
-Spreadsheet cell values, CSV fields, formulas, comments, and other
-workbook text are processed locally and are not returned to the model.
-Structural results contain sheet names, ranges, dimensions, counts,
+Spreadsheet cell values, CSV fields, formula contents, and comments are
+processed locally and are not returned to the model. When a
+deterministic XLSX write or patch does not require inspection, do not
+read CSV or cell contents into model context merely to perform it.
+Structural results may contain sheet names, ranges, dimensions, counts,
 merged-range addresses, hidden row and column ranges, changed package
-parts, and write status---not workbook or CSV contents. Layout-range
-arrays are capped and report whether they were truncated; this metadata
-can reveal limited layout and occupancy information.
+parts, and write status---not cell or CSV contents. Layout-range arrays
+are capped and report whether they were truncated; this metadata can
+reveal limited layout and occupancy information.
 
 - `read` with `view: "structure"` reports workbook and worksheet shape.
-- `read` with `view: "image"` renders all workbook print pages through
+- `read` with `view: "image"` renders workbook print pages through
   LibreOffice to numbered PNG files; it does not select a sheet.
+  `first_page` and `last_page` select resulting print pages.
 - `write` fills an existing workbook template from CSV.
 - `patch` changes formatting or layout while preserving cell contents.
 
@@ -189,12 +198,31 @@ calculation or generation, spreadsheet scripting, or manipulation of
 charts, pivots, macros, comments, named ranges, tables, data validation,
 conditional formatting, or external data.
 
+## PPTX operations
+
+- Text reads and search convert PPTX through Pandoc to GFM Markdown.
+- Writes convert GFM Markdown into a validated PPTX; an optional
+  reference PPTX supplies Pandoc presentation styles.
+- Formatting reads report slide dimensions, slide count, and common core
+  metadata.
+- Patches change slide dimensions, common core metadata, and targeted
+  text in slide text paragraphs. Text replacements may target one
+  1-based slide or all slides. They can span formatted text runs, with
+  replacement text inheriting the first run's formatting.
+- PPTX-to-Markdown extraction is semantic and lossy: it is not a
+  reversible representation of positions, animations, themes, or all
+  presentation objects.
+
+Slide dimensions use EMUs (English Metric Units); 914,400 EMUs equal one
+inch. PPTX image reads convert slides through LibreOffice to PDF and
+render numbered PNG files; `first_page` and `last_page` select slides.
+
 ## Output and mutation behavior
 
-DOCX and XLSX writes and patches use temporary sibling files, validate
-the result, and rename it into place only after success. Source files
-are not modified. PDF image rendering similarly protects prior output
-until the new render succeeds.
+DOCX, PPTX, and XLSX writes and patches use temporary sibling files,
+validate the result, and rename it into place only after success. Source
+files are not modified. PDF and office image rendering similarly
+protects prior output until the new render succeeds.
 
 `dry_run` validates the requested operation and inputs without creating
 or replacing output; its required `output` path is still validated.
@@ -203,10 +231,10 @@ or replacing output; its required `output` path is still validated.
 
 Required for the corresponding operations:
 
-- `pandoc` for DOCX text conversion, search, and generation;
-- `libreoffice` for DOCX and XLSX image rendering;
+- `pandoc` for DOCX/PPTX text conversion, search, and generation;
+- `libreoffice` for DOCX, PPTX, and XLSX image rendering;
 - `pdftotext` for PDF text extraction;
-- `pdftocairo` for PDF, DOCX, and XLSX page rendering; and
+- `pdftocairo` for PDF, DOCX, PPTX, and XLSX page rendering; and
 - `pdfgrep` for page-aware PDF search.
 
 A missing executable produces an explicit error naming the unavailable
@@ -221,8 +249,9 @@ make site
 ```
 
 `make verify` runs typechecking, lint and formatting checks,
-deterministic tests, and `npm pack --dry-run`. `make site` regenerates
-the tracked static site after documentation changes.
+deterministic tests, project-wide line/function coverage checks, and
+`npm pack --dry-run`. `make site` regenerates the tracked static site
+after documentation changes.
 
 Dependencies and CI actions follow current upstream releases rather than
 being pinned. GitLab is canonical and the only release authority. GitHub

package/package.json

@@ -1,11 +1,12 @@
 {
 	"name": "pi-filler",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "Deterministic DOCX, PDF, and XLSX tooling for Pi",
 	"keywords": [
 		"pi-package",
 		"pi-extension",
 		"docx",
+		"pptx",
 		"pdf",
 		"xlsx",
 		"pandoc",
@@ -32,6 +33,7 @@
 	],
 	"scripts": {
 		"test": "node --import tsx --test test/*.test.ts",
+		"test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-include=src/**/*.ts --test-coverage-lines=90 --test-coverage-functions=90 test/*.test.ts",
 		"typecheck": "tsc --noEmit",
 		"lint": "biome lint src test scripts",
 		"format:check": "biome ci --linter-enabled=false --assist-enabled=false src test scripts biome.json package.json tsconfig.json",
@@ -39,7 +41,7 @@
 		"markdown:check": "node scripts/format-markdown.mjs",
 		"markdown:fix": "node scripts/format-markdown.mjs --write",
 		"style": "npm run lint && npm run format:check && npm run markdown:check",
-		"check": "npm run typecheck && npm run style && npm test",
+		"check": "npm run typecheck && npm run style && npm test && npm run test:coverage",
 		"site": "make site"
 	},
 	"pi": {

package/src/index.ts

@@ -10,8 +10,16 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { type DocxPatchSet, inspectDocx, patchDocx } from "./docx.js";
-import { readDocxText, searchDocx, writeDocx } from "./pandoc.js";
+import {
+	readDocxText,
+	readPptxText,
+	searchDocx,
+	searchPptx,
+	writeDocx,
+	writePptx,
+} from "./pandoc.js";
 import { readPdfText, renderPdfPages, searchPdf } from "./pdf.js";
+import { inspectPptx, type PptxPatchSet, patchPptx } from "./pptx.js";
 import { commandError, runCommand } from "./process.js";
 import { fillXlsxFromCsv, inspectXlsxStructure, patchXlsx, type XlsxPatchSet } from "./xlsx.js";
 
@@ -115,6 +123,70 @@ const docxPatchesSchema = Type.Object(
 	},
 );
 
+const pptxPatchesSchema = Type.Object(
+	{
+		slideSize: Type.Optional(
+			Type.Object(
+				{
+					width: Type.Optional(Type.Integer({ description: "Slide width in EMUs", minimum: 1 })),
+					height: Type.Optional(Type.Integer({ description: "Slide height in EMUs", minimum: 1 })),
+				},
+				{
+					additionalProperties: false,
+					description: "Presentation slide size in EMUs",
+					minProperties: 1,
+				},
+			),
+		),
+		metadata: Type.Optional(
+			Type.Object(
+				{
+					title: Type.Optional(Type.String()),
+					subject: Type.Optional(Type.String()),
+					creator: Type.Optional(Type.String()),
+					keywords: Type.Optional(Type.String()),
+					description: Type.Optional(Type.String()),
+					lastModifiedBy: Type.Optional(Type.String()),
+				},
+				{
+					additionalProperties: false,
+					description: "Common docProps/core.xml metadata fields",
+					minProperties: 1,
+				},
+			),
+		),
+		replaceText: Type.Optional(
+			Type.Array(
+				Type.Object(
+					{
+						find: Type.String({
+							description: "Text to find within a slide text paragraph",
+							minLength: 1,
+						}),
+						replace: Type.String({ description: "Replacement text; may be empty" }),
+						slide: Type.Optional(
+							Type.Integer({
+								description: "1-based slide number; omit for all slides",
+								minimum: 1,
+							}),
+						),
+					},
+					{ additionalProperties: false, minProperties: 2 },
+				),
+				{ minItems: 1, description: "Targeted text replacements in slide text" },
+			),
+		),
+		clearCoreMetadata: Type.Optional(
+			Type.Boolean({ description: "Clear common core metadata fields" }),
+		),
+	},
+	{
+		additionalProperties: false,
+		description: "PPTX slide, metadata, and targeted text changes for action=patch",
+		minProperties: 1,
+	},
+);
+
 const xlsxPatchesSchema = Type.Object(
 	{
 		font: Type.Optional(
@@ -174,7 +246,7 @@ const xlsxPatchesSchema = Type.Object(
 
 export const fillerSchema = Type.Object(
 	{
-		format: StringEnum(["docx", "pdf", "xlsx"] as const, {
+		format: StringEnum(["docx", "pdf", "pptx", "xlsx"] as const, {
 			description: "Document or target format; selects supported operations and path roles",
 		}),
 		action: StringEnum(["read", "search", "write", "patch"] as const, {
@@ -187,7 +259,7 @@ export const fillerSchema = Type.Object(
 		),
 		path: Type.String({
 			description:
-				"Input path: document for read/search/patch, Markdown source for DOCX write, or template for XLSX write",
+				"Input path: document for read/search/patch, Markdown source for DOCX/PPTX write, or template for XLSX write",
 			minLength: 1,
 		}),
 		output: Type.Optional(
@@ -197,11 +269,17 @@ export const fillerSchema = Type.Object(
 				minLength: 1,
 			}),
 		),
-		query: Type.Optional(Type.String({ description: "DOCX or PDF search query", minLength: 1 })),
+		query: Type.Optional(
+			Type.String({ description: "DOCX, PDF, or PPTX search query", minLength: 1 }),
+		),
 		reference_docx: Type.Optional(
 			Type.String({ description: "Reference DOCX for writes", minLength: 1 }),
 		),
 		patches: Type.Optional(docxPatchesSchema),
+		pptx_patches: Type.Optional(pptxPatchesSchema),
+		reference_pptx: Type.Optional(
+			Type.String({ description: "Reference PPTX for writes", minLength: 1 }),
+		),
 		source_csv: Type.Optional(
 			Type.String({ description: "CSV source path for XLSX write", minLength: 1 }),
 		),
@@ -242,7 +320,7 @@ export const fillerSchema = Type.Object(
 			Type.Boolean({
 				default: false,
 				description:
-					"Validate and report without creating or replacing output; output remains required for DOCX patch or XLSX write/patch",
+					"Validate and report without creating or replacing output; output remains required for DOCX/PPTX patch or XLSX write/patch",
 			}),
 		),
 		literal: Type.Optional(
@@ -257,14 +335,14 @@ export const fillerSchema = Type.Object(
 		first_page: Type.Optional(
 			Type.Integer({
 				description:
-					"First 1-based inclusive page for PDF read/search or DOCX/PDF image read; must not exceed last_page",
+					"First 1-based inclusive page for PDF read/search or DOCX/PPTX/XLSX image read; must not exceed last_page",
 				minimum: 1,
 			}),
 		),
 		last_page: Type.Optional(
 			Type.Integer({
 				description:
-					"Last 1-based inclusive page for PDF read/search or DOCX/PDF image read; must not precede first_page",
+					"Last 1-based inclusive page for PDF read/search or DOCX/PDF/XLSX image read; must not precede first_page",
 				minimum: 1,
 			}),
 		),
@@ -280,6 +358,8 @@ const controlFields: ControlField[] = [
 	"output",
 	"query",
 	"reference_docx",
+	"pptx_patches",
+	"reference_pptx",
 	"patches",
 	"source_csv",
 	"sheet",
@@ -364,6 +444,42 @@ function assertSupported(input: FillerInput): void {
 		return;
 	}
 
+	if (input.format === "pptx") {
+		if (input.action === "read") {
+			if (input.view === "image") {
+				if (!input.output) throw new Error("PPTX image reads require output");
+				assertParameters(input, ["output", "first_page", "last_page"]);
+				return;
+			}
+			if (input.view !== "text" && input.view !== "formatting") {
+				throw new Error("PPTX read requires view=text, view=formatting, or view=image");
+			}
+			assertParameters(input, []);
+			return;
+		}
+		if (input.action === "search") {
+			if (input.view !== undefined && input.view !== "text") {
+				throw new Error("PPTX search requires view=text or no view");
+			}
+			if (!input.query) throw new Error("PPTX search requires query");
+			assertParameters(input, ["query", "ignore_case"]);
+			return;
+		}
+		if (input.action === "write") {
+			if (input.view !== undefined || !input.output) {
+				throw new Error("PPTX write requires output and does not accept view");
+			}
+			assertParameters(input, ["output", "reference_pptx"]);
+			return;
+		}
+		if (input.view !== undefined || !input.output) {
+			throw new Error("PPTX patch requires output and does not accept view");
+		}
+		if (input.pptx_patches === undefined) throw new Error("PPTX patch requires pptx_patches");
+		assertParameters(input, ["output", "pptx_patches", "dry_run"]);
+		return;
+	}
+
 	if (input.format === "xlsx") {
 		if (input.action === "read") {
 			if (input.view === "image") {
@@ -502,6 +618,69 @@ export async function executeFiller(
 		return { text: `Wrote ${output}`, details: { output } };
 	}
 
+	if (input.format === "pptx") {
+		if (input.action === "read" && input.view === "formatting") {
+			const formatting = await inspectPptx(path);
+			return { text: JSON.stringify(formatting, null, 2), details: { formatting } };
+		}
+		if (input.action === "read" && input.view === "image") {
+			const output = normalizePath(input.output ?? "", cwd);
+			const temporary = await mkdtemp(join(tmpdir(), "pi-filler-pptx-"));
+			try {
+				const converted = await runCommand(
+					"libreoffice",
+					["--headless", "--convert-to", "pdf", "--outdir", temporary, path],
+					{ signal, cwd: temporary },
+				);
+				if (converted.code !== 0) throw commandError(converted, "libreoffice");
+				const pdf = join(temporary, `${basename(path, extname(path))}.pdf`);
+				const result = await withFileMutationQueue(output, () =>
+					renderPdfPages(pdf, output, range, { signal }),
+				);
+				return {
+					text: `Rendered ${result.length} slide image${result.length === 1 ? "" : "s"}:\n${result.join("\n")}`,
+					details: { files: result },
+				};
+			} finally {
+				await rm(temporary, { recursive: true, force: true });
+			}
+		}
+		if (input.action === "read") {
+			const result = await readPptxText(path, { signal });
+			return { text: result.text, details: { truncation: result.truncation } };
+		}
+		if (input.action === "search") {
+			const result = await searchPptx(path, input.query ?? "", {
+				ignoreCase: input.ignore_case,
+				signal,
+			});
+			return {
+				text: result.text || "No matches found",
+				details: { matchCount: result.matchCount, truncation: result.truncation },
+			};
+		}
+		if (input.action === "patch") {
+			const output = normalizePath(input.output ?? "", cwd);
+			const result = await withFileMutationQueue(output, () =>
+				patchPptx(path, output, input.pptx_patches as PptxPatchSet, input.dry_run),
+			);
+			return {
+				text: JSON.stringify(result, null, 2),
+				details: result as unknown as Record<string, unknown>,
+			};
+		}
+
+		const output = normalizePath(input.output ?? "", cwd);
+		if (output === path) throw new Error("PPTX write output must differ from input");
+		const referencePptx = input.reference_pptx
+			? normalizePath(input.reference_pptx, cwd)
+			: undefined;
+		await withFileMutationQueue(output, () =>
+			writePptx(path, output, { referencePptx, signal, cwd: dirname(path) }),
+		);
+		return { text: `Wrote ${output}`, details: { output } };
+	}
+
 	if (input.format === "xlsx") {
 		if (input.action === "read") {
 			if (input.view === "image") {
@@ -605,15 +784,19 @@ export default function extension(pi: ExtensionAPI): void {
 		name: "filler",
 		label: "Filler",
 		description:
-			"Work directly with local DOCX, PDF, and XLSX files. Read, search, or render DOCX and PDF; write DOCX from Markdown; inspect or render XLSX, fill XLSX templates from CSV, and patch supported formatting.",
+			"Work directly with local DOCX, PDF, PPTX, and XLSX files. Read, search, or render DOCX/PPTX and PDF; write DOCX/PPTX from Markdown; inspect or render XLSX, fill XLSX templates from CSV, and patch supported formatting.",
 		promptSnippet:
-			"Work directly with local DOCX, PDF, and XLSX files using supported format/action/view combinations.",
+			"Work directly with local DOCX, PDF, PPTX, and XLSX files using supported format/action/view combinations.",
 		promptGuidelines: [
-			"Use filler directly for local DOCX, PDF, or XLSX work; choose a supported format/action/view combination and provide only that operation's fields.",
-			"For filler read, use DOCX text, formatting, or image; PDF text or image; or XLSX structure or image. XLSX images render all workbook print pages through LibreOffice and do not accept sheet. For filler search, use DOCX or PDF text (or omit view); XLSX search is unsupported. Image output is an existing directory or PNG prefix that creates page images, not one final PNG.",
-			"For filler DOCX write, path is Markdown and output is the new DOCX; reference_docx is optional. For filler XLSX write, 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. XLSX processing stays local and results do not return cell or CSV contents.",
-			"For filler patch, provide a new output path plus DOCX patches, or XLSX sheet, A1-style range, and xlsx_patches. dry_run: true still requires output but does not create or replace it. 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 search may be truncated; narrow its query. PDF text or search may be truncated; narrow its page range or query.",
+			"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 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.",
+			"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 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,
 		async execute(_toolCallId, input, signal, _onUpdate, ctx: ExtensionContext) {

package/src/pandoc.ts

@@ -3,6 +3,7 @@ import { mkdir, rename, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { type TruncationResult, truncateHead } from "@earendil-works/pi-coding-agent";
 import { inspectDocx } from "./docx.js";
+import { inspectPptx } from "./pptx.js";
 import { commandError, type RunCommandOptions, runCommand } from "./process.js";
 
 export interface DocxTextResult {
@@ -30,16 +31,28 @@ async function runPandoc(
 	return result.stdout;
 }
 
-async function extractDocxMarkdown(path: string, options?: RunCommandOptions): Promise<string> {
+async function extractMarkdown(
+	path: string,
+	from: "docx" | "pptx",
+	options?: RunCommandOptions,
+): Promise<string> {
 	const source = resolve(path);
 	const output = await runPandoc(
-		["--from=docx", "--to=gfm", "--wrap=none", source],
+		[`--from=${from}`, "--to=gfm", "--wrap=none", source],
 		options,
 		source,
 	);
 	return output.toString("utf8");
 }
 
+async function extractDocxMarkdown(path: string, options?: RunCommandOptions): Promise<string> {
+	return extractMarkdown(path, "docx", options);
+}
+
+async function extractPptxMarkdown(path: string, options?: RunCommandOptions): Promise<string> {
+	return extractMarkdown(path, "pptx", options);
+}
+
 export async function readDocxText(
 	path: string,
 	options?: RunCommandOptions,
@@ -48,26 +61,49 @@ export async function readDocxText(
 	return { text: truncation.content, truncation };
 }
 
-export async function searchDocx(
-	path: string,
-	query: string,
-	options: RunCommandOptions & { ignoreCase?: boolean } = {},
-): Promise<DocxSearchResult> {
-	const extracted = await extractDocxMarkdown(path, options);
-	const needle = options.ignoreCase ? query.toLocaleLowerCase() : query;
+function searchMarkdown(extracted: string, query: string, ignoreCase = false): DocxSearchResult {
+	const needle = ignoreCase ? query.toLocaleLowerCase() : query;
 	const matches: string[] = [];
 	for (const [index, text] of extracted.split(/\r?\n/).entries()) {
-		const haystack = options.ignoreCase ? text.toLocaleLowerCase() : text;
+		const haystack = ignoreCase ? text.toLocaleLowerCase() : text;
 		if (haystack.includes(needle)) matches.push(`line ${index + 1}: ${text}`);
 	}
 	const truncation = truncateHead(matches.join("\n"));
 	return { matchCount: matches.length, text: truncation.content, truncation };
 }
 
+export async function searchDocx(
+	path: string,
+	query: string,
+	options: RunCommandOptions & { ignoreCase?: boolean } = {},
+): Promise<DocxSearchResult> {
+	return searchMarkdown(await extractDocxMarkdown(path, options), query, options.ignoreCase);
+}
+
+export async function readPptxText(
+	path: string,
+	options?: RunCommandOptions,
+): Promise<DocxTextResult> {
+	const truncation = truncateHead(await extractPptxMarkdown(path, options));
+	return { text: truncation.content, truncation };
+}
+
+export async function searchPptx(
+	path: string,
+	query: string,
+	options: RunCommandOptions & { ignoreCase?: boolean } = {},
+): Promise<DocxSearchResult> {
+	return searchMarkdown(await extractPptxMarkdown(path, options), query, options.ignoreCase);
+}
+
 export interface WriteDocxOptions extends RunCommandOptions {
 	referenceDocx?: string;
 }
 
+export interface WritePptxOptions extends RunCommandOptions {
+	referencePptx?: string;
+}
+
 export async function writeDocx(
 	sourcePath: string,
 	outputPath: string,
@@ -96,3 +132,32 @@ export async function writeDocx(
 		await rm(temporary, { force: true });
 	}
 }
+
+export async function writePptx(
+	sourcePath: string,
+	outputPath: string,
+	options: WritePptxOptions = {},
+): Promise<void> {
+	const source = resolve(sourcePath);
+	const output = resolve(outputPath);
+	if (source === output) throw new Error("PPTX write output must differ from input");
+	const temporary = join(
+		dirname(output),
+		`.${output.split(/[\\/]/).pop() ?? "output.pptx"}.${randomUUID()}.tmp`,
+	);
+	await mkdir(dirname(output), { recursive: true });
+	const args = ["--from=gfm", "--to=pptx", "--output", temporary];
+	if (options.referencePptx) args.push("--reference-doc", resolve(options.referencePptx));
+	args.push(source);
+	try {
+		const result = await runCommand("pandoc", args, {
+			...options,
+			cwd: options.cwd ?? dirname(source),
+		});
+		if (result.code !== 0) throw commandError(result, "pandoc");
+		await inspectPptx(temporary);
+		await rename(temporary, output);
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}

package/src/pptx.ts

@@ -0,0 +1,511 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, posix, resolve } from "node:path";
+import { XMLBuilder, XMLParser } from "fast-xml-parser";
+import { type OfficePackage, packOfficePackage, unpackOfficePackage } from "./ooxml.js";
+
+export interface PptxPatchSet {
+	slideSize?: { width?: number; height?: number };
+	metadata?: {
+		title?: string;
+		subject?: string;
+		creator?: string;
+		keywords?: string;
+		description?: string;
+		lastModifiedBy?: string;
+	};
+	replaceText?: Array<{ find: string; replace: string; slide?: number }>;
+	clearCoreMetadata?: boolean;
+}
+
+export interface PptxFormatting {
+	slideSize: { width?: number; height?: number };
+	slideCount: number;
+	metadata: Record<string, string>;
+}
+
+export interface PptxPatchResult {
+	formatting: PptxFormatting;
+	replacementCount: number;
+	changedParts: string[];
+	preservedParts: string[];
+	written: boolean;
+}
+
+type Package = OfficePackage;
+type XmlObject = Record<string, unknown>;
+
+type TextNode = { parent: XmlObject; key: string; text: string };
+
+const PRESENTATION_NS = "http://schemas.openxmlformats.org/presentationml/2006/main";
+const DRAWING_NS = "http://schemas.openxmlformats.org/drawingml/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 metadataNamespaces: Record<string, string> = {
+	title: DC_NS,
+	subject: DC_NS,
+	creator: DC_NS,
+	keywords: CORE_NS,
+	description: DC_NS,
+	lastModifiedBy: CORE_NS,
+};
+
+const parser = new XMLParser({
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	trimValues: false,
+});
+const builder = new XMLBuilder({
+	ignoreAttributes: false,
+	attributeNamePrefix: "@_",
+	format: false,
+});
+
+function isObject(value: unknown): value is XmlObject {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function localName(name: string): string {
+	return name.replace(/^@_/, "").split(":").at(-1) ?? name;
+}
+
+function parseXml(bytes: Uint8Array | undefined, part: string): XmlObject {
+	if (!bytes) throw new Error(`PPTX is missing required part ${part}`);
+	try {
+		return parser.parse(new TextDecoder().decode(bytes), true) as XmlObject;
+	} 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));
+}
+
+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);
+			}
+		}
+		findAll(child, suffix, found);
+	}
+	return found;
+}
+
+function findPrefixed(
+	value: unknown,
+	prefix: string,
+	suffix: string,
+	found: XmlObject[] = [],
+): XmlObject[] {
+	if (!value || typeof value !== "object") return found;
+	for (const [key, child] of Object.entries(value)) {
+		if (!key.startsWith("@_") && key === `${prefix}:${suffix}`) {
+			for (const item of Array.isArray(child) ? child : [child]) {
+				if (isObject(item)) found.push(item);
+			}
+		}
+		findPrefixed(child, prefix, suffix, found);
+	}
+	return found;
+}
+
+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;
+	}
+	return undefined;
+}
+
+function rootObject(value: XmlObject, suffix: string): XmlObject {
+	const root = directObject(value, suffix);
+	if (!root) throw new Error(`PPTX XML is missing ${suffix}`);
+	return root;
+}
+
+function attr(value: XmlObject | undefined, name: string): string | undefined {
+	if (!value) return undefined;
+	for (const [key, child] of Object.entries(value)) {
+		if (key.startsWith("@_") && localName(key) === name && child !== undefined)
+			return String(child);
+	}
+	return undefined;
+}
+
+function numberAttr(value: XmlObject | undefined, name: string): number | undefined {
+	const raw = attr(value, name);
+	return raw === undefined ? undefined : Number(raw);
+}
+
+function existingNamespacePrefix(root: XmlObject, uri: string): string | undefined {
+	for (const [key, value] of Object.entries(root)) {
+		if (key === "@_xmlns" && value === uri) return "";
+		if (key.startsWith("@_xmlns:") && value === uri) return key.slice("@_xmlns:".length);
+	}
+	return undefined;
+}
+
+function namespacePrefix(root: XmlObject, uri: string, preferred: string): string {
+	return (
+		existingNamespacePrefix(root, uri) ??
+		(() => {
+			root[`@_xmlns:${preferred}`] = uri;
+			return preferred;
+		})()
+	);
+}
+
+function setAttr(value: XmlObject, name: string, setting: number | string, prefix?: string): void {
+	const existing = Object.keys(value).find(
+		(key) => key.startsWith("@_") && localName(key) === name,
+	);
+	value[existing ?? `@_${prefix ? `${prefix}:` : ""}${name}`] = String(setting);
+}
+
+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);
+		}
+	}
+	return 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;
+	}
+	const uri = metadataNamespaces[name] ?? DC_NS;
+	const prefix = namespacePrefix(value, uri, uri === CORE_NS ? "cp" : "dc");
+	value[`${prefix ? `${prefix}:` : ""}${name}`] = text;
+}
+
+function coreMetadata(pkg: Package): Record<string, string> {
+	const bytes = pkg["docProps/core.xml"];
+	if (!bytes) return {};
+	const props = rootObject(parseXml(bytes, "docProps/core.xml"), "coreProperties");
+	const result: Record<string, string> = {};
+	for (const name of Object.keys(metadataNamespaces)) {
+		const value = childText(props, name);
+		if (value !== undefined) result[name] = value;
+	}
+	return result;
+}
+
+function relationshipBase(part: string): string {
+	if (part.startsWith("_rels/")) return "";
+	const marker = "/_rels/";
+	const index = part.indexOf(marker);
+	return index === -1 ? posix.dirname(part) : part.slice(0, index);
+}
+
+function relationshipTarget(part: string, target: string): string {
+	return target.startsWith("/")
+		? posix.normalize(target.slice(1))
+		: posix.normalize(posix.join(relationshipBase(part), target));
+}
+
+function validateRelationships(pkg: Package): void {
+	for (const part of Object.keys(pkg).filter((name) => name.endsWith(".rels"))) {
+		const root = parseXml(pkg[part], part);
+		for (const relationship of findAll(root, "Relationship")) {
+			const target = attr(relationship, "Target");
+			if (!target || attr(relationship, "TargetMode") === "External") continue;
+			const normalized = relationshipTarget(part, target);
+			if (!pkg[normalized]) throw new Error(`PPTX relationship target is missing: ${normalized}`);
+		}
+	}
+}
+
+function validatePackage(pkg: Package): void {
+	for (const part of [
+		"[Content_Types].xml",
+		"ppt/presentation.xml",
+		"ppt/_rels/presentation.xml.rels",
+	]) {
+		parseXml(pkg[part], part);
+	}
+	for (const [part, bytes] of Object.entries(pkg)) {
+		if (part.endsWith(".xml") || part.endsWith(".rels")) parseXml(bytes, part);
+	}
+	validateRelationships(pkg);
+}
+
+function slideParts(pkg: Package, presentation: XmlObject): string[] {
+	const relsPart = "ppt/_rels/presentation.xml.rels";
+	const relationships = findAll(parseXml(pkg[relsPart], relsPart), "Relationship");
+	const slides = new Map<string, string>();
+	for (const relationship of relationships) {
+		const type = attr(relationship, "Type");
+		const id = attr(relationship, "Id");
+		const target = attr(relationship, "Target");
+		if (type?.endsWith("/slide") && id && target)
+			slides.set(id, relationshipTarget(relsPart, target));
+	}
+	const ordered = findAll(presentation, "sldId")
+		.map((slide) => attr(slide, "id"))
+		.filter((id): id is string => id !== undefined)
+		.map((id) => slides.get(id))
+		.filter((part): part is string => part !== undefined);
+	return ordered.length > 0 ? ordered : [...slides.values()];
+}
+
+function inspectPackage(pkg: Package): PptxFormatting {
+	const presentation = parseXml(pkg["ppt/presentation.xml"], "ppt/presentation.xml");
+	const root = rootObject(presentation, "presentation");
+	const size = directObject(root, "sldSz");
+	return {
+		slideSize: { width: numberAttr(size, "cx"), height: numberAttr(size, "cy") },
+		slideCount: slideParts(pkg, presentation).length,
+		metadata: coreMetadata(pkg),
+	};
+}
+
+function textNodes(value: unknown, found: TextNode[] = []): TextNode[] {
+	if (!value || typeof value !== "object") return found;
+	for (const [key, child] of Object.entries(value)) {
+		if (key.startsWith("@_")) continue;
+		if (localName(key) === "t" && (typeof child === "string" || typeof child === "number")) {
+			found.push({ parent: value as XmlObject, key, text: String(child) });
+		} else {
+			textNodes(child, found);
+		}
+	}
+	return found;
+}
+
+function replaceInParagraph(paragraph: XmlObject, find: string, replacement: string): number {
+	const nodes = textNodes(paragraph);
+	let full = nodes.map((node) => node.text).join("");
+	let count = 0;
+	let start = full.indexOf(find);
+	while (start !== -1) {
+		const end = start + find.length;
+		let cursor = 0;
+		let startNode: TextNode | undefined;
+		let endNode: TextNode | undefined;
+		let startOffset = 0;
+		let endOffset = 0;
+		for (const node of nodes) {
+			const nodeEnd = cursor + node.text.length;
+			if (!startNode && start >= cursor && start <= nodeEnd) {
+				startNode = node;
+				startOffset = start - cursor;
+			}
+			if (end >= cursor && end <= nodeEnd) {
+				endNode = node;
+				endOffset = end - cursor;
+				break;
+			}
+			cursor = nodeEnd;
+		}
+		if (!startNode || !endNode) break;
+		if (startNode === endNode) {
+			startNode.text =
+				startNode.text.slice(0, startOffset) + replacement + startNode.text.slice(endOffset);
+			startNode.parent[startNode.key] = startNode.text;
+		} else {
+			startNode.text = startNode.text.slice(0, startOffset) + replacement;
+			startNode.parent[startNode.key] = startNode.text;
+			let clearing = false;
+			for (const node of nodes) {
+				if (node === startNode) {
+					clearing = true;
+					continue;
+				}
+				if (node === endNode) {
+					node.text = node.text.slice(endOffset);
+					node.parent[node.key] = node.text;
+					break;
+				}
+				if (clearing) {
+					node.text = "";
+					node.parent[node.key] = "";
+				}
+			}
+		}
+		full = nodes.map((node) => node.text).join("");
+		count += 1;
+		start = full.indexOf(find, start + replacement.length);
+	}
+	return count;
+}
+
+function replaceInSlide(document: XmlObject, find: string, replacement: string): number {
+	const root = rootObject(document, "sld");
+	const drawingPrefix = existingNamespacePrefix(root, DRAWING_NS) ?? "a";
+	let count = 0;
+	for (const paragraph of findPrefixed(document, drawingPrefix, "p")) {
+		count += replaceInParagraph(paragraph, find, replacement);
+	}
+	return count;
+}
+
+function applyPatch(
+	pkg: Package,
+	patch: PptxPatchSet,
+): { changedParts: string[]; replacementCount: number } {
+	const changed = new Set<string>();
+	let replacementCount = 0;
+	const presentation = parseXml(pkg["ppt/presentation.xml"], "ppt/presentation.xml");
+	const root = rootObject(presentation, "presentation");
+	if (patch.slideSize) {
+		const size =
+			directObject(root, "sldSz") ??
+			(() => {
+				const value: XmlObject = {};
+				const prefix = existingNamespacePrefix(root, PRESENTATION_NS) ?? "p";
+				root[`${prefix ? `${prefix}:` : ""}sldSz`] = value;
+				return value;
+			})();
+		if (patch.slideSize.width !== undefined) setAttr(size, "cx", patch.slideSize.width);
+		if (patch.slideSize.height !== undefined) setAttr(size, "cy", patch.slideSize.height);
+		pkg["ppt/presentation.xml"] = serializeXml(presentation);
+		changed.add("ppt/presentation.xml");
+	}
+
+	if (patch.metadata || patch.clearCoreMetadata) {
+		const core = parseXml(pkg["docProps/core.xml"], "docProps/core.xml");
+		const props = rootObject(core, "coreProperties");
+		if (patch.clearCoreMetadata) {
+			for (const name of Object.keys(metadataNamespaces)) {
+				if (childText(props, name) !== undefined) setChildText(props, name, "");
+			}
+		}
+		for (const [name, value] of Object.entries(patch.metadata ?? {}))
+			setChildText(props, name, value);
+		pkg["docProps/core.xml"] = serializeXml(core);
+		changed.add("docProps/core.xml");
+	}
+
+	if (patch.replaceText) {
+		const parts = slideParts(pkg, presentation);
+		const documents = new Map<string, XmlObject>();
+		for (const request of patch.replaceText) {
+			const targets = request.slide === undefined ? parts : [parts[request.slide - 1]];
+			if (targets.some((part) => part === undefined))
+				throw new Error("PPTX text replacement slide is out of range");
+			let matches = 0;
+			for (const part of targets) {
+				let document = documents.get(part);
+				if (!document) {
+					document = parseXml(pkg[part], part);
+					documents.set(part, document);
+				}
+				matches += replaceInSlide(document, request.find, request.replace);
+			}
+			if (matches === 0) throw new Error("PPTX text replacement found no matches");
+			replacementCount += matches;
+		}
+		for (const [part, document] of documents) {
+			pkg[part] = serializeXml(document);
+			changed.add(part);
+		}
+	}
+	return { changedParts: [...changed].sort(), replacementCount };
+}
+
+function hasValues(value: object | undefined): boolean {
+	return Boolean(value && Object.keys(value).length > 0);
+}
+
+function validatePatch(patch: PptxPatchSet): void {
+	if (
+		!hasValues(patch.slideSize) &&
+		!hasValues(patch.metadata) &&
+		!patch.replaceText?.length &&
+		patch.clearCoreMetadata !== true
+	) {
+		throw new Error("PPTX patch requires at least one change");
+	}
+	if (patch.replaceText?.some((request) => !request.find)) {
+		throw new Error("PPTX text replacements require non-empty find values");
+	}
+}
+
+function validateRequested(formatting: PptxFormatting, patch: PptxPatchSet): void {
+	if (patch.slideSize) {
+		for (const [key, value] of Object.entries(patch.slideSize)) {
+			if (formatting.slideSize[key as keyof typeof formatting.slideSize] !== value) {
+				throw new Error(`PPTX slide size patch validation failed for ${key}`);
+			}
+		}
+	}
+	if (patch.metadata) {
+		for (const [key, value] of Object.entries(patch.metadata)) {
+			if (formatting.metadata[key] !== value)
+				throw new Error(`PPTX metadata patch validation failed for ${key}`);
+		}
+	}
+	if (patch.clearCoreMetadata) {
+		for (const name of Object.keys(metadataNamespaces)) {
+			if (patch.metadata?.[name as keyof NonNullable<PptxPatchSet["metadata"]>] !== undefined)
+				continue;
+			if (formatting.metadata[name])
+				throw new Error(`PPTX core metadata clearing validation failed for ${name}`);
+		}
+	}
+}
+
+async function load(path: string): Promise<Package> {
+	return unpackOfficePackage(new Uint8Array(await readFile(resolve(path))), "PPTX");
+}
+
+export async function inspectPptx(path: string): Promise<PptxFormatting> {
+	const pkg = await load(path);
+	validatePackage(pkg);
+	return inspectPackage(pkg);
+}
+
+export async function patchPptx(
+	inputPath: string,
+	outputPath: string,
+	patch: PptxPatchSet,
+	dryRun = false,
+): Promise<PptxPatchResult> {
+	const input = resolve(inputPath);
+	const output = resolve(outputPath);
+	if (input === output) throw new Error("PPTX patch output must differ from input");
+	validatePatch(patch);
+	const pkg = await load(input);
+	validatePackage(pkg);
+	const applied = applyPatch(pkg, patch);
+	validatePackage(pkg);
+	const formatting = inspectPackage(pkg);
+	validateRequested(formatting, patch);
+	const allParts = Object.keys(pkg).sort();
+	const result: PptxPatchResult = {
+		formatting,
+		replacementCount: applied.replacementCount,
+		changedParts: applied.changedParts,
+		preservedParts: allParts.filter((part) => !applied.changedParts.includes(part)),
+		written: false,
+	};
+	if (dryRun) return result;
+	const temporary = join(dirname(output), `.${output.split(/[\\/]/).pop()}.${randomUUID()}.tmp`);
+	await mkdir(dirname(output), { recursive: true });
+	try {
+		await writeFile(temporary, packOfficePackage(pkg));
+		await inspectPptx(temporary);
+		await rename(temporary, output);
+		result.written = true;
+		return result;
+	} finally {
+		await rm(temporary, { force: true });
+	}
+}