document-operations 0.0.0 → 1.0.0

package/dist/index.js

@@ -0,0 +1,973 @@
+import { DocumentFormatSchema, UnrecognizedDocumentSchemaError, base64ToBytes, buildDocumentBytes, bytesToBase64, collectDocumentFormulas, createDocx, createLocalDocumentConverter, createMarkdownEditor, createOdg, createOdp, createOds, createOdt, createPdf, createPptx, decodeMarkdownText, decodeOdbPackage, decodePackage, describeFontFace, documentFromJson, documentSchemaKindOf, encodeMarkdownText, evaluateSelect, extractSourceFontsForFormat, odbReportToDocx, odbReportToOdt, odbReportToPdf, odbToCsv, odbToXlsx, odmToPdf, openDocx, openMarkdown, openOdt, parseSelect, readDocumentMetadata, readDocxExtras, readNativeDocumentTree, readOdbForms, readOdbInventory, readOdbReportContent, readOdbReports, readOdbTables, readPdf, rgbHexToColor, setDocumentMetadata } from "documents.js";
+import { z } from "zod";
+import { readFile, writeFile } from "node:fs/promises";
+import { evaluate } from "document-compute.js";
+import { ContentDocumentSchema, EvaluationValueSchema, FormulaBindingsSchema, flattenTree } from "document-schema.js";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { buildOutline, isOutlineNode, outlineLeafText } from "document-outline.js";
+//#region src/operation.ts
+/**
+* Builds a DocumentOperation whose input and output types are both inferred from real Zod schemas, so a call site never has to repeat `z.infer<typeof Schema>` itself. Use `defineOperationWithoutOutputSchema` instead for the rare operation whose original MCP tool registration declared no outputSchema at all.
+*
+* Deliberately returns the parameter object's own inferred literal type rather than an explicit `DocumentOperation<...>` return annotation. Zod 4's ZodType carries its own output type as one of three generic parameters (ZodType<Output, Input, Internals>), and TypeScript cannot prove, from inside this function body, that a generic `InputSchema extends z.ZodType` also extends `z.ZodType<z.infer<InputSchema>>` -- the two-step indirection through an abstract type parameter defeats it even though it is true for every concrete schema. Letting the literal's own type flow out instead sidesteps that: a caller's own concrete schema (e.g. `ConvertDocumentInputSchema`) is trivially assignable to `DocumentOperation<In, Out>`'s `z.ZodType<In>` field wherever that supertype is actually needed (the registry array below, or a future MCP/REST/CLI adapter parameter), because widening a CONCRETE schema's output type to line up is a normal covariant check, not the same self-referential generic one.
+*/
+function defineOperation(operation) {
+	return operation;
+}
+/**
+* The `defineOperation` counterpart for an operation with no output schema to infer from (the original MCP tool registration declared none) -- `Out` is inferred from `run`'s own return type instead. See `defineOperation`'s own comment for why this returns the parameter object's inferred literal type rather than an explicit `DocumentOperation<...>` annotation.
+*/
+function defineOperationWithoutOutputSchema(operation) {
+	return operation;
+}
+//#endregion
+//#region src/io/document-input.ts
+const EXTENSION_TO_FORMAT = {
+	docx: "docx",
+	dotx: "docx",
+	docm: "docx",
+	pptx: "pptx",
+	potx: "pptx",
+	pptm: "pptx",
+	xlsx: "xlsx",
+	xltx: "xlsx",
+	xlsm: "xlsx",
+	odt: "odt",
+	ott: "odt",
+	odp: "odp",
+	otp: "odp",
+	ods: "ods",
+	ots: "ods",
+	odg: "odg",
+	otg: "odg",
+	odf: "odf",
+	otf: "odf",
+	markdown: "markdown",
+	md: "markdown",
+	rtf: "rtf",
+	wpd: "wpd",
+	doc: "doc",
+	xls: "xls",
+	ppt: "ppt",
+	epub: "epub",
+	csv: "csv",
+	svg: "svg",
+	pdf: "pdf"
+};
+function inferFormatFromExtension(path) {
+	const lastSegment = path.split(/[/\\]/).pop() ?? path;
+	const dotIndex = lastSegment.lastIndexOf(".");
+	if (dotIndex <= 0) return;
+	const extension = lastSegment.slice(dotIndex + 1).toLowerCase();
+	return EXTENSION_TO_FORMAT[extension];
+}
+/**
+* The hybrid input shape every MCP tool that accepts a document accepts: either a filesystem path (format inferred from its extension) or inline base64-encoded bytes (format required, since there is no filename to infer it from).
+*/
+const DocumentInputSchema = z.union([z.object({ path: z.string().describe("Filesystem path to the document to read. The document format is inferred from the file extension.") }), z.object({
+	bytesBase64: z.string().describe("Base64-encoded document bytes."),
+	format: DocumentFormatSchema.describe("The document format of bytesBase64 -- required, since inline bytes carry no filename to infer it from.")
+})]);
+/**
+* Resolves the hybrid DocumentInput union to concrete bytes and a format: for the path shape, reads the file from disk and infers its format from the extension (throwing if the extension is unrecognised); for the bytesBase64 shape, decodes the inline payload and uses the caller-supplied format directly.
+*/
+async function resolveDocumentInput(input, options) {
+	if ("path" in input) {
+		const format = inferFormatFromExtension(input.path);
+		if (format === void 0) throw new Error(`Could not infer a document format from the file extension of "${input.path}". Recognised extensions: ${Object.keys(EXTENSION_TO_FORMAT).join(", ")}. Pass an explicit format via the bytesBase64 input shape instead.`);
+		const buffer = await readFile(input.path, { signal: options?.signal });
+		return {
+			bytes: new Uint8Array(buffer),
+			format
+		};
+	}
+	return {
+		bytes: base64ToBytes(input.bytesBase64),
+		format: input.format
+	};
+}
+//#endregion
+//#region src/io/document-output.ts
+/**
+* The hybrid output shape every MCP tool that produces a document accepts: an optional filesystem path to write the result to. Omitting it returns the bytes inline, base64-encoded, instead.
+*/
+const DocumentOutputSchema = z.object({ outputPath: z.string().optional().describe("Filesystem path to write the resulting document to. Omit to receive the document bytes inline, base64-encoded, in the tool result instead.") });
+/**
+* Above this many bytes, an inline base64 result is flagged `large: true` so a caller/LLM can see the response is sizeable before deciding whether to consume it directly. Purely advisory: `resolveDocumentOutput` never truncates or refuses to return large bytes, it only flags them -- silently truncating a document would produce a corrupt file with no indication anything was lost. 5 MB is a reasonable default order of magnitude for "an LLM context probably wants to know before this lands inline", well under typical MCP stdio transport limits.
+*/
+const LARGE_RESULT_THRESHOLD_BYTES = 5242880;
+/**
+* Resolves output bytes against the hybrid DocumentOutput shape: writes to `outputPath` and reports the path plus byte length when one is given, otherwise returns the bytes inline as base64 (flagged `large: true` above `LARGE_RESULT_THRESHOLD_BYTES`, never truncated or refused).
+*/
+async function resolveDocumentOutput(bytes, output) {
+	if (output.outputPath !== void 0) {
+		await writeFile(output.outputPath, bytes);
+		return {
+			path: output.outputPath,
+			byteLength: bytes.byteLength
+		};
+	}
+	const bytesBase64 = bytesToBase64(bytes);
+	if (bytes.byteLength > 5242880) return {
+		bytesBase64,
+		byteLength: bytes.byteLength,
+		large: true
+	};
+	return {
+		bytesBase64,
+		byteLength: bytes.byteLength
+	};
+}
+//#endregion
+//#region src/operations/convert.ts
+const DiagnosticSchema = z.object({
+	severity: z.enum(["info", "warning"]),
+	code: z.string(),
+	message: z.string(),
+	pageIndex: z.number().optional()
+});
+const FontSubstitutionSchema$1 = z.object({
+	requestedFamily: z.string(),
+	requestedBold: z.boolean(),
+	requestedItalic: z.boolean(),
+	reason: z.enum(["missing-face", "vendored-substitute"]),
+	resolvedFamily: z.string()
+});
+const ResolvedDocumentOutputSchema$3 = z.union([z.object({
+	path: z.string(),
+	byteLength: z.number()
+}), z.object({
+	bytesBase64: z.string(),
+	byteLength: z.number(),
+	large: z.literal(true).optional()
+})]);
+const FontInputSchema = z.object({
+	family: z.string().describe("The font family name this face provides."),
+	bold: z.boolean().describe("Whether this face is the bold weight."),
+	italic: z.boolean().describe("Whether this face is the italic slope."),
+	bytesBase64: z.string().describe("Base64-encoded font program bytes (TrueType/OpenType/CFF) for this family/weight/style combination.")
+});
+const ConvertDocumentInputSchema = z.object({
+	source: DocumentInputSchema.describe("The document to convert."),
+	targetFormat: DocumentFormatSchema.describe("The format to convert the document to. Not every (source, targetFormat) pair is supported directly -- call list_document_conversions first to confirm this one is."),
+	output: DocumentOutputSchema.optional().describe("Where to write the converted document. Omit entirely to receive the bytes inline, base64-encoded, instead."),
+	fonts: z.array(FontInputSchema).optional().describe("Extra font faces to make available to the conversion, for a family the source document does not already embed. Only consulted by a conversion that runs a layout engine (a <format>-to-pdf conversion); every other conversion ignores this option entirely."),
+	onSubstitutionDiagnostics: z.boolean().optional().describe("When true, additionally report each individual font-substitution event as structured fontSubstitutions (which family/weight/style was requested, what it resolved to instead, and why). Every substitution is always reported as a plain diagnostic in `diagnostics` regardless of this flag -- this only controls whether the fuller, structured event is also collected."),
+	images: z.record(z.string(), z.string()).optional().describe("A map from a markdown image destination (the part in the parentheses of ![](..)) to its base64-encoded PNG/JPEG bytes, for resolving a markdown source's own non-data: images. Only consulted by a markdown-sourced conversion; every other conversion ignores it. A destination absent from the map degrades to alt text, matching documents.js's own MarkdownImageResolver port -- a caller with no filesystem context has no other way to supply a relative path's bytes.")
+});
+const ConvertDocumentOutputSchema = z.object({
+	targetFormat: DocumentFormatSchema,
+	output: ResolvedDocumentOutputSchema$3,
+	diagnostics: z.array(DiagnosticSchema),
+	fontSubstitutions: z.array(FontSubstitutionSchema$1).optional()
+});
+const ListDocumentConversionsInputSchema = z.object({});
+const ListDocumentConversionsOutputSchema = z.object({ conversions: z.array(z.object({
+	source: DocumentFormatSchema,
+	target: DocumentFormatSchema
+})) });
+const converter = createLocalDocumentConverter();
+const convertDocumentOperation = defineOperation({
+	name: "convert_document",
+	title: "Convert document",
+	description: "Converts a document from one supported format to another via documents.js's DocumentConverter port -- docx, pptx, xlsx, odt, odp, ods, odg, odf, markdown, rtf, wpd, doc, xls, ppt, epub, csv, svg, and pdf. Not every (source, targetFormat) pair is supported directly (odf, for instance, only ever converts to pdf); call list_document_conversions first to see which pairs actually are.",
+	inputSchema: ConvertDocumentInputSchema,
+	outputSchema: ConvertDocumentOutputSchema,
+	async run({ source, targetFormat, output, fonts, onSubstitutionDiagnostics, images }, context) {
+		const signal = context?.signal;
+		const { bytes, format } = await resolveDocumentInput(source, { signal });
+		const fontSubstitutions = [];
+		const conversionSignal = signal ?? new AbortController().signal;
+		const result = await converter.convert({
+			source: {
+				format,
+				bytes
+			},
+			targetFormat
+		}, {
+			signal: conversionSignal,
+			fonts: fonts?.map((font) => ({
+				family: font.family,
+				bold: font.bold,
+				italic: font.italic,
+				bytes: base64ToBytes(font.bytesBase64)
+			})),
+			onFontSubstitution: onSubstitutionDiagnostics === true ? (substitution) => fontSubstitutions.push(substitution) : void 0,
+			images: images === void 0 ? void 0 : (destination) => {
+				const base64 = images[destination];
+				return base64 === void 0 ? void 0 : { bytes: base64ToBytes(base64) };
+			}
+		});
+		const resolvedOutput = await resolveDocumentOutput(result.document.bytes, output ?? {});
+		return {
+			targetFormat: result.document.format,
+			output: resolvedOutput,
+			diagnostics: [...result.diagnostics],
+			...onSubstitutionDiagnostics === true ? { fontSubstitutions: [...fontSubstitutions] } : {}
+		};
+	}
+});
+const listDocumentConversionsOperation = defineOperation({
+	name: "list_document_conversions",
+	title: "List document conversions",
+	description: "Lists every (source, target) format pair convert_document actually supports, straight from documents.js's own DocumentConverter port -- the definitive source of truth for what convert_document will and will not accept as a (source, targetFormat) combination.",
+	inputSchema: ListDocumentConversionsInputSchema,
+	outputSchema: ListDocumentConversionsOutputSchema,
+	run() {
+		return Promise.resolve({ conversions: converter.conversions.map((conversion) => ({
+			source: conversion.source,
+			target: conversion.target
+		})) });
+	}
+});
+//#endregion
+//#region src/operations/compute-formula.ts
+function evaluateFormula(formula, bindings, symbolTable) {
+	if (formula.content === void 0) return { status: "no-content" };
+	try {
+		return {
+			status: "evaluated",
+			result: evaluate(formula.content, bindings, symbolTable)
+		};
+	} catch (error) {
+		return {
+			status: "error",
+			errorType: error instanceof Error ? error.name : String(error),
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+const FormulaOutcomeSchema = z.union([
+	z.object({
+		status: z.literal("evaluated"),
+		result: EvaluationValueSchema
+	}),
+	z.object({ status: z.literal("no-content") }),
+	z.object({
+		status: z.literal("error"),
+		errorType: z.string(),
+		message: z.string()
+	})
+]);
+const documentKindValues = ContentDocumentSchema.options.map((option) => option.shape.kind.value);
+const ComputeFormulaOutputSchema = z.object({
+	sourceFormat: DocumentFormatSchema,
+	documentKind: z.enum(documentKindValues),
+	formulaCount: z.number(),
+	formulas: z.array(z.object({
+		index: z.number(),
+		sourcePath: z.string().optional(),
+		locate: z.string(),
+		latex: z.string().optional(),
+		outcome: FormulaOutcomeSchema
+	}))
+});
+const computeFormulaOperation = defineOperation({
+	name: "compute_formula",
+	title: "Compute document formulas",
+	description: "Reads every formula a document embeds (docx/odt/markdown paragraphs and pptx/odp slide shapes; a table cell's own blocks too -- docx's own reader recovers a real equation nested inside a table cell; structurally, the walk also covers a drawing page's own shape flow, though no writer in the family populates a formula there today; a spreadsheet's own cell-anchored formula objects; a standalone .odf formula document; and a formula nested inside another embedded object at any depth, e.g. a formula embedded in a drawing embedded in a spreadsheet) and evaluates each through document-compute.js's units-typed evaluate() -- a caller's way to check whether a document's stated arithmetic actually checks out. A formula referencing a symbol (e.g. F = m * a) needs that symbol's value supplied via bindings, keyed by the document's own symbol-table id (see the document's symbolTable.symbols[].id, or a returned formula's own latex to identify which symbol is which); a formula with no free symbols (units and numeric literals only) evaluates with no bindings at all. Each formula reports its own outcome independently -- 'evaluated' with the result, 'no-content' when the formula was never lowered to a computable MathExpression (the common case for a spreadsheet's own embedded formula object, or any format other than markdown, none of which yet stores the semantic layer on disk), or 'error' naming which document-compute.js error it hit (e.g. UnboundSymbolError) -- so one formula needing more bindings never blocks the others. Each entry's own `locate` field is the reliable way to tell two formulas in the same document apart -- a structural path guaranteed unique per formula -- unlike `sourcePath`, which several formats leave undefined or stamp with the identical constant across sibling formulas (markdown's own display-math lowering among them).",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe("The document to read formulas from."),
+		bindings: FormulaBindingsSchema.optional().describe("Known values for symbols the document's formulas reference, keyed by symbol-table id (a Quantity { kind: 'quantity', magnitude, dimension } or an Interval { kind: 'interval', min, max, dimension } per symbol). Omit for a document whose formulas are fully closed (units and numeric literals only, no 'sym' nodes).")
+	}),
+	outputSchema: ComputeFormulaOutputSchema,
+	async run({ source, bindings }, context) {
+		const signal = context?.signal;
+		const { bytes, format } = await resolveDocumentInput(source, { signal });
+		const tree = readNativeDocumentTree(format, bytes, { signal });
+		const document = flattenTree(tree);
+		const entries = collectDocumentFormulas(document);
+		const resolvedBindings = bindings ?? {};
+		const formulas = entries.map((entry, index) => ({
+			index,
+			sourcePath: entry.sourcePath,
+			locate: entry.locate,
+			latex: entry.formula.presentation?.latex,
+			outcome: evaluateFormula(entry.formula, resolvedBindings, entry.symbolTable)
+		}));
+		return {
+			sourceFormat: format,
+			documentKind: document.kind,
+			formulaCount: formulas.length,
+			formulas
+		};
+	}
+});
+const docxExtrasOperation = defineOperationWithoutOutputSchema({
+	name: "docx_extras",
+	title: "Docx extras",
+	description: "Reads a docx's own comments, footnotes, header/footer parts, and numbering definitions -- data documents.js's ContentDocument pivot cannot carry, so ordinary document-reading operations never see it. Returns the real DocxExtras object (comments/footnotes/headerFooterParts/sectionHeaderFooters/numbering) as structured data.",
+	inputSchema: z.object({ source: DocumentInputSchema.describe("The docx document to read.") }),
+	async run({ source }) {
+		const { bytes } = await resolveDocumentInput(source);
+		const pkg = decodePackage(bytes);
+		return readDocxExtras(pkg);
+	}
+});
+//#endregion
+//#region src/operations/editor.ts
+const WritableFormatSchema = z.enum([
+	"docx",
+	"pptx",
+	"odt",
+	"odp",
+	"ods",
+	"odg",
+	"pdf",
+	"markdown"
+]);
+const RunSchema = z.object({
+	text: z.string().optional().describe("The run's own text content."),
+	bold: z.boolean().optional(),
+	italic: z.boolean().optional(),
+	strike: z.boolean().optional(),
+	underline: z.boolean().optional().describe("docx/odt only."),
+	fontFamily: z.string().optional().describe("docx/odt only."),
+	sizePt: z.number().positive().optional().describe("docx/odt only."),
+	colorHex: z.string().regex(/^#?[0-9a-fA-F]{6}$/).optional().describe("6-digit hex colour (e.g. 'ff0000' or '#ff0000'). docx/odt only."),
+	hyperlink: z.string().optional().describe("markdown only."),
+	code: z.boolean().optional().describe("markdown only -- renders the run as an inline code span.")
+});
+const ParagraphSchema = z.object({
+	text: z.string().optional().describe("Plain paragraph text, as a single run. Omit and use `runs` instead for mixed formatting within one paragraph."),
+	styleId: z.string().optional(),
+	headingLevel: z.number().int().min(1).max(6).optional().describe("docx/odt only."),
+	alignment: z.enum([
+		"left",
+		"center",
+		"right",
+		"justify"
+	]).optional().describe("docx/odt only."),
+	runs: z.array(RunSchema).optional().describe("Runs to append to this paragraph, each with its own formatting. Combine with `text` for a paragraph that opens with plain text before its first formatted run, or omit `text` entirely for a paragraph built purely from runs.")
+});
+function unsupportedFieldNames(input, unsupported) {
+	return unsupported.filter((key) => input[key] !== void 0);
+}
+function rejectUnsupportedFields(input, unsupported, formatLabel, context) {
+	const present = unsupportedFieldNames(input, unsupported);
+	if (present.length > 0) throw new Error(`${context} does not support ${present.join(", ")} for ${formatLabel} -- remove ${present.length === 1 ? "it" : "them"} or target docx/odt instead.`);
+}
+const DOCX_ODT_UNSUPPORTED_RUN_FIELDS = ["hyperlink", "code"];
+const MARKDOWN_UNSUPPORTED_RUN_FIELDS = [
+	"underline",
+	"fontFamily",
+	"sizePt",
+	"colorHex"
+];
+const MARKDOWN_UNSUPPORTED_PARAGRAPH_FIELDS = ["headingLevel", "alignment"];
+function appendDocxOdtRun(paragraph, run) {
+	rejectUnsupportedFields(run, DOCX_ODT_UNSUPPORTED_RUN_FIELDS, "docx/odt", "A run");
+	paragraph.appendRun({
+		text: run.text,
+		bold: run.bold,
+		italic: run.italic,
+		underline: run.underline,
+		strike: run.strike,
+		fontFamily: run.fontFamily,
+		sizePt: run.sizePt,
+		color: run.colorHex === void 0 ? void 0 : rgbHexToColor(run.colorHex)
+	});
+}
+function appendDocxOdtParagraphs(body, paragraphs) {
+	for (const paragraph of paragraphs) {
+		const built = body.appendParagraph({
+			text: paragraph.text,
+			styleId: paragraph.styleId,
+			headingLevel: paragraph.headingLevel,
+			alignment: paragraph.alignment
+		});
+		for (const run of paragraph.runs ?? []) appendDocxOdtRun(built, run);
+	}
+}
+function appendMarkdownParagraphs(body, paragraphs) {
+	for (const paragraph of paragraphs) {
+		rejectUnsupportedFields(paragraph, MARKDOWN_UNSUPPORTED_PARAGRAPH_FIELDS, "markdown", "A paragraph");
+		const built = body.appendParagraph({
+			text: paragraph.text,
+			styleId: paragraph.styleId
+		});
+		for (const run of paragraph.runs ?? []) {
+			rejectUnsupportedFields(run, MARKDOWN_UNSUPPORTED_RUN_FIELDS, "markdown", "A run");
+			built.appendRun({
+				text: run.text,
+				bold: run.bold,
+				italic: run.italic,
+				strike: run.strike,
+				hyperlink: run.hyperlink,
+				code: run.code
+			});
+		}
+	}
+}
+function createDocumentBytes(format) {
+	switch (format) {
+		case "docx": return createDocx().toBytes();
+		case "pptx": return createPptx().toBytes();
+		case "odt": return createOdt().toBytes();
+		case "odp": return createOdp().toBytes();
+		case "ods": return createOds().toBytes();
+		case "odg": return createOdg().toBytes();
+		case "pdf": return createPdf().toBytes();
+		case "markdown": return encodeMarkdownText(createMarkdownEditor().toMarkdownText());
+	}
+}
+const ResolvedDocumentOutputSchema$2 = z.union([z.object({
+	path: z.string(),
+	byteLength: z.number()
+}), z.object({
+	bytesBase64: z.string(),
+	byteLength: z.number(),
+	large: z.literal(true).optional()
+})]);
+const documentCreateOperation = defineOperation({
+	name: "document_create",
+	title: "Create a blank document",
+	description: "Creates a fresh, blank document in the given format via documents.js's own live-view editors (createDocx/createOdt/createMarkdownEditor/...), the same construction document_append_paragraphs's own edit calls build on. Returns an empty document with no content -- follow with document_append_paragraphs (docx/odt/markdown) to add text.",
+	inputSchema: z.object({
+		format: WritableFormatSchema.describe("The format of document to create."),
+		output: DocumentOutputSchema.optional().describe("Where to write the created document. Omit entirely to receive the bytes inline, base64-encoded.")
+	}),
+	outputSchema: ResolvedDocumentOutputSchema$2,
+	async run({ format, output }) {
+		return resolveDocumentOutput(createDocumentBytes(format), output ?? {});
+	}
+});
+const documentAppendParagraphsOperation = defineOperation({
+	name: "document_append_paragraphs",
+	title: "Append paragraphs to a wordprocessing document",
+	description: "Appends one or more paragraphs -- each optionally built from several independently-formatted runs -- to the end of a docx, odt, or markdown document, through documents.js's own live-view editors (the same DocxBody.appendParagraph/OdtBody.appendParagraph/MarkdownBody.appendParagraph document-cli's own TUI uses). Does not convert format -- the source document's own format and targetFormat must match. docx and odt share an identical field set (underline, fontFamily, sizePt, colorHex, headingLevel, alignment all supported); markdown supports a different, smaller set (hyperlink, code) and rejects the docx/odt-only fields outright rather than silently dropping them. This covers wordprocessing paragraph/run editing only -- slides, sheets, drawings, tables, lists, and images are a separate, larger editing surface not exposed here yet.",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe("The document to append paragraphs to."),
+		targetFormat: z.enum([
+			"docx",
+			"odt",
+			"markdown"
+		]).describe("Must match the source document's own format. document_append_paragraphs never converts format."),
+		paragraphs: z.array(ParagraphSchema).min(1).describe("The paragraphs to append, in order."),
+		output: DocumentOutputSchema.optional().describe("Where to write the edited document. Omit entirely to receive the bytes inline, base64-encoded.")
+	}),
+	outputSchema: ResolvedDocumentOutputSchema$2,
+	async run({ source, targetFormat, paragraphs, output }) {
+		const { bytes, format } = await resolveDocumentInput(source);
+		if (format !== targetFormat) throw new Error(`source document is "${format}", but targetFormat is "${targetFormat}" -- document_append_paragraphs never converts format, so the two must match.`);
+		let resultBytes;
+		if (targetFormat === "markdown") {
+			const editor = openMarkdown(decodeMarkdownText(bytes));
+			appendMarkdownParagraphs(editor.body, paragraphs);
+			resultBytes = encodeMarkdownText(editor.toMarkdownText());
+		} else {
+			const editor = targetFormat === "docx" ? openDocx(bytes) : openOdt(bytes);
+			appendDocxOdtParagraphs(editor.body, paragraphs);
+			resultBytes = editor.toBytes();
+		}
+		return resolveDocumentOutput(resultBytes, output ?? {});
+	}
+});
+//#endregion
+//#region src/operations/fonts.ts
+const FontFaceSummarySchema = z.object({
+	family: z.string(),
+	bold: z.boolean(),
+	italic: z.boolean(),
+	byteLength: z.number()
+});
+const fontsOperation = defineOperation({
+	name: "fonts",
+	title: "List document fonts",
+	description: "Lists every source-embedded font face a docx/pptx/odt/odp/ods/odg document carries (family, weight/style, byte length).",
+	inputSchema: z.object({ source: DocumentInputSchema.describe("The docx/pptx/odt/odp/ods/odg document to extract source-embedded font faces from.") }),
+	outputSchema: z.object({ faces: z.array(FontFaceSummarySchema) }),
+	async run({ source }) {
+		const { bytes, format } = await resolveDocumentInput(source);
+		return { faces: extractSourceFontsForFormat(format, bytes).map((face) => ({
+			family: face.family,
+			bold: face.bold,
+			italic: face.italic,
+			byteLength: face.bytes.length
+		})) };
+	}
+});
+const FontFileInputSchema = z.union([z.object({ path: z.string().describe("Filesystem path to the font file (.ttf/.otf) to read.") }), z.object({ bytesBase64: z.string().describe("Base64-encoded font file bytes.") })]);
+async function resolveFontFileInput(input) {
+	if ("path" in input) {
+		const buffer = await readFile(input.path);
+		return {
+			bytes: new Uint8Array(buffer),
+			source: input.path
+		};
+	}
+	return {
+		bytes: base64ToBytes(input.bytesBase64),
+		source: "inline font bytes"
+	};
+}
+const describeFontFileOperation = defineOperation({
+	name: "describe_font_file",
+	title: "Describe font file",
+	description: "Reads a standalone TrueType/OpenType font file (.ttf/.otf) and reports the family/bold/italic triple it declares about itself.",
+	inputSchema: z.object({ source: FontFileInputSchema.describe("The standalone .ttf/.otf font file to inspect -- not a document.") }),
+	outputSchema: z.object({
+		family: z.string(),
+		bold: z.boolean(),
+		italic: z.boolean()
+	}),
+	async run({ source }) {
+		const { bytes, source: label } = await resolveFontFileInput(source);
+		const face = describeFontFace(bytes, label);
+		return {
+			family: face.family,
+			bold: face.bold,
+			italic: face.italic
+		};
+	}
+});
+//#endregion
+//#region src/operations/from-package.ts
+async function readSourceBytes(source) {
+	if ("path" in source) {
+		const buffer = await readFile(source.path);
+		return new Uint8Array(buffer);
+	}
+	return base64ToBytes(source.bytesBase64);
+}
+const fromPackageOperation = defineOperation({
+	name: "from_package",
+	title: "Build document from package",
+	description: "Rebuilds real document bytes in a target format from a DocumentTree previously serialised to JSON (e.g. by a caller's own --dump-package-equivalent step) -- the read side of the DocumentTree round trip a conversion's onDocument callback produces.",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe("The DocumentTree JSON to read. 'path' points at a JSON file on disk -- its extension is never used to infer a document format, since the file holds a DocumentTree, not a document. 'bytesBase64' carries the JSON inline; its 'format' field is required by the shared hybrid input shape but unused by this operation."),
+		targetFormat: DocumentFormatSchema.describe("The document format to build from the DocumentTree."),
+		output: DocumentOutputSchema.optional().describe("Where to write the resulting document. Omit entirely (or omit outputPath within it) to receive the bytes inline instead.")
+	}),
+	outputSchema: z.union([z.object({
+		path: z.string(),
+		byteLength: z.number()
+	}), z.object({
+		bytesBase64: z.string(),
+		byteLength: z.number(),
+		large: z.literal(true).optional()
+	})]),
+	async run({ source, targetFormat, output }) {
+		const bytes = await readSourceBytes(source);
+		const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+		let parsed;
+		try {
+			parsed = JSON.parse(text);
+		} catch (error) {
+			throw new Error(`'source' is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+		}
+		let result;
+		try {
+			result = documentFromJson(parsed);
+		} catch (error) {
+			if (error instanceof UnrecognizedDocumentSchemaError) throw new Error("'source' has no recognised $schema -- only a file carrying a real DocumentTree (e.g. written by a caller's own --dump-package-equivalent step) can be read back by this operation", { cause: error });
+			if (error instanceof z.ZodError) throw new Error(`'source' failed ${documentSchemaKindOf(parsed) ?? "document schema"} validation: ${error.message}`, { cause: error });
+			throw error;
+		}
+		if (result.kind !== "DocumentTree") throw new Error(`'source' is a ${result.kind}, not a DocumentTree -- only a file carrying a real DocumentTree (e.g. written by a caller's own --dump-package-equivalent step) can be read back by this operation`);
+		return resolveDocumentOutput(buildDocumentBytes(result.value, targetFormat), output ?? {});
+	}
+});
+const metadataReadOperation = defineOperationWithoutOutputSchema({
+	name: "metadata_read",
+	title: "Read document metadata",
+	description: "Reads a document's own title/author/subject/keywords/creator/producer/created-and-modified-timestamp metadata. Works across every supported format, including xlsx (read via a throwaway xlsx-to-pdf preview, since documents.js has no dedicated xlsx metadata reader of its own) and odf (a standalone formula document).",
+	inputSchema: z.object({ source: DocumentInputSchema.describe("The document to read metadata from.") }),
+	async run({ source }) {
+		const { bytes, format } = await resolveDocumentInput(source);
+		return readDocumentMetadata(format, bytes);
+	}
+});
+const ResolvedDocumentOutputSchema = z.union([z.object({
+	path: z.string(),
+	byteLength: z.number()
+}), z.object({
+	bytesBase64: z.string(),
+	byteLength: z.number(),
+	large: z.literal(true).optional()
+})]);
+const metadataWriteOperation = defineOperation({
+	name: "metadata_write",
+	title: "Write document metadata",
+	description: "Patches a document's own title/author/subject/keywords, leaving every other field and every other flag as-is. Does not convert format -- the source document's own format and targetFormat must match (or both be 'pdf'); odf (a standalone formula document) is rejected outright as either a source or a target, since it has no write path back out at all. Convert the document to a different format first (e.g. with a documents.js conversion operation) if metadata needs to be set on the result of a format change.",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe("The document to patch metadata on."),
+		targetFormat: DocumentFormatSchema.describe("The format to write the patched document back out as -- must match the source document's own format (or both be 'pdf'). metadata_write never converts format."),
+		output: DocumentOutputSchema.optional().describe("Where to write the patched document. Omit entirely to receive the bytes inline, base64-encoded."),
+		setTitle: z.string().optional().describe("Set the title field. Omit to leave it exactly as the source document already has it."),
+		setAuthor: z.string().optional().describe("Set the author field. Omit to leave it exactly as the source document already has it."),
+		setSubject: z.string().optional().describe("Set the subject field. Omit to leave it exactly as the source document already has it."),
+		setKeywords: z.array(z.string()).optional().describe("Set the keywords field. Omit to leave it exactly as the source document already has it.")
+	}),
+	outputSchema: ResolvedDocumentOutputSchema,
+	async run({ source, targetFormat, output, setTitle, setAuthor, setSubject, setKeywords }) {
+		const { bytes, format } = await resolveDocumentInput(source);
+		return resolveDocumentOutput(setDocumentMetadata(format, targetFormat, bytes, {
+			title: setTitle,
+			author: setAuthor,
+			subject: setSubject,
+			keywords: setKeywords
+		}), output ?? {});
+	}
+});
+//#endregion
+//#region src/operations/odb.ts
+const ODB_SOURCE_DESCRIPTION = ".odb database to read. 'path' points at the .odb file on disk -- its extension is never used to infer a document format, since documents.js deliberately excludes 'odb' from DocumentFormat (an embedded database front end has no single natural target format -- tables, saved queries, and reports are three unrelated output shapes -- see that package's own README). 'bytesBase64' carries the .odb bytes inline; its 'format' field is required by the shared hybrid input shape but unused by every odb operation.";
+async function resolveOdbBytes(source) {
+	if ("path" in source) {
+		const buffer = await readFile(source.path);
+		return new Uint8Array(buffer);
+	}
+	return base64ToBytes(source.bytesBase64);
+}
+/** Resolves an .odb DocumentInput straight through to a decoded Package (via documents.js's own decodeOdbPackage) -- the shape every read (as opposed to export) odb operation needs. */
+async function resolveOdbPackage(source) {
+	return decodeOdbPackage(await resolveOdbBytes(source));
+}
+/** Resolves a saved query's own SQL text by name against the .odb's own db:queries (read via readOdbInventory) -- odb_query's own equivalent of document-cli's resolveQuerySql, for the case where the caller named a saved query rather than supplying SQL directly. Throws, naming every available query, when the name doesn't resolve. */
+function resolveSavedQuerySql(pkg, name) {
+	const inventory = readOdbInventory(pkg);
+	const saved = inventory.queries.find((candidate) => candidate.name === name);
+	if (saved === void 0) {
+		const available = inventory.queries.map((candidate) => candidate.name);
+		throw new Error(`This .odb declares no saved query named "${name}".${available.length === 0 ? "" : ` Available: ${available.join(", ")}.`}`);
+	}
+	return saved.command;
+}
+/** Classifies odb_query's own sql/query pair before any package is read: exactly one of the two must be given. Throws for either "both given" or "neither given". Kept as a pure, synchronous check (no Package involved) so both variables narrow cleanly through ordinary control flow, rather than needing a cross-variable inference TypeScript can't derive from two separate `!== undefined` checks. */
+function classifyQueryInput(sql, query) {
+	if (sql !== void 0 && query !== void 0) throw new Error("Provide \"sql\" or \"query\", not both.");
+	if (sql !== void 0) return {
+		kind: "literal",
+		sql
+	};
+	if (query !== void 0) return {
+		kind: "saved",
+		name: query
+	};
+	throw new Error("Provide either \"sql\" (a literal SELECT statement) or \"query\" (the name of one of this .odb's own saved queries).");
+}
+const OdbSourceInputSchema = z.object({ source: DocumentInputSchema.describe(ODB_SOURCE_DESCRIPTION) });
+const odbTablesOperation = defineOperationWithoutOutputSchema({
+	name: "odb_tables",
+	title: "List .odb tables",
+	description: "Lists every table an embedded .odb database declares -- column names, types, and row data -- across every storage tier documents.js supports (HSQLDB TEXT/CACHED/BINARY script formats, Firebird gbak backups).",
+	inputSchema: OdbSourceInputSchema,
+	async run({ source }) {
+		return readOdbTables(await resolveOdbPackage(source));
+	}
+});
+const odbFormsOperation = defineOperationWithoutOutputSchema({
+	name: "odb_forms",
+	title: "List .odb forms",
+	description: "Lists every form an .odb database declares, with each form's own data source and field-bound controls.",
+	inputSchema: OdbSourceInputSchema,
+	async run({ source }) {
+		return readOdbForms(await resolveOdbPackage(source));
+	}
+});
+const odbReportsOperation = defineOperationWithoutOutputSchema({
+	name: "odb_reports",
+	title: "List .odb reports",
+	description: "Lists every report an .odb database declares, with each report's own data-source command, band/group structure, and rpt: formula expressions.",
+	inputSchema: OdbSourceInputSchema,
+	async run({ source }) {
+		return readOdbReports(await resolveOdbPackage(source));
+	}
+});
+const odbQueryOperation = defineOperationWithoutOutputSchema({
+	name: "odb_query",
+	title: "Query an .odb database",
+	description: "Runs a bounded SELECT (with optional JOINs of any kind, table aliases, a derived table in FROM, and IN/EXISTS subqueries) over an embedded .odb database's own extracted tables, given directly as SQL or by naming one of the database's saved queries. No database engine is involved -- the query runs in memory over the same tables odb_tables would return, against a closed grammar (SELECT/FROM/JOIN [INNER|LEFT [OUTER]|RIGHT [OUTER]|FULL [OUTER]|CROSS|NATURAL] ... [ON|USING]/WHERE/GROUP BY/ORDER BY, with an optional [AS] alias on any table, WHERE and ON also accepting [NOT] IN (SELECT ...) and [NOT] EXISTS (SELECT ...) -- no column aliases); an unsupported construct is reported as an error naming it, never silently ignored.",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe(ODB_SOURCE_DESCRIPTION),
+		sql: z.string().describe("A literal SELECT statement to run. Mutually exclusive with \"query\".").optional(),
+		query: z.string().describe("The name of one of the .odb's own saved queries to run. Mutually exclusive with \"sql\".").optional()
+	}),
+	async run({ source, sql, query }) {
+		const spec = classifyQueryInput(sql, query);
+		const pkg = await resolveOdbPackage(source);
+		const resolvedSql = spec.kind === "literal" ? spec.sql : resolveSavedQuerySql(pkg, spec.name);
+		return evaluateSelect(parseSelect(resolvedSql), readOdbTables(pkg));
+	}
+});
+const odbToCsvOperation = defineOperationWithoutOutputSchema({
+	name: "odb_to_csv",
+	title: "Export one .odb table to CSV",
+	description: "Extracts exactly one named table from an embedded .odb database as CSV bytes. The table name is required whenever the database declares more than one table.",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe(ODB_SOURCE_DESCRIPTION),
+		table: z.string().describe("The table to export -- required when the .odb declares more than one table.").optional(),
+		output: DocumentOutputSchema.optional().describe("Where to write the resulting CSV. Omit entirely (or omit outputPath within it) to receive the bytes inline instead.")
+	}),
+	async run({ source, table, output }, context) {
+		const bytes = await resolveOdbBytes(source);
+		return resolveDocumentOutput(odbToCsv(bytes, {
+			signal: context?.signal,
+			table
+		}), output ?? {});
+	}
+});
+const odbToXlsxOperation = defineOperationWithoutOutputSchema({
+	name: "odb_to_xlsx",
+	title: "Export .odb tables to xlsx",
+	description: "Extracts every table an embedded .odb database declares into one xlsx workbook, one sheet per table.",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe(ODB_SOURCE_DESCRIPTION),
+		output: DocumentOutputSchema.optional().describe("Where to write the resulting xlsx workbook. Omit entirely (or omit outputPath within it) to receive the bytes inline instead.")
+	}),
+	async run({ source, output }, context) {
+		const bytes = await resolveOdbBytes(source);
+		return resolveDocumentOutput(odbToXlsx(bytes, { signal: context?.signal }), output ?? {});
+	}
+});
+//#endregion
+//#region src/operations/odb-render-report.ts
+const OdbRenderReportTargetFormatSchema = z.enum([
+	"docx",
+	"odt",
+	"pdf"
+]);
+const OdbRenderReportInputSchema = z.object({
+	source: DocumentInputSchema.describe(".odb database to render a report from. 'path' points at the .odb file on disk -- its extension is never used to infer a document format, since documents.js deliberately excludes 'odb' from DocumentFormat (an embedded database front end has no single natural target format -- tables, saved queries, and reports are three unrelated output shapes -- see that package's own README). 'bytesBase64' carries the .odb bytes inline; its 'format' field is required by the shared hybrid input shape but unused by this operation."),
+	report: z.string().optional().describe("The name of the report to render. Required only when the .odb declares more than one report -- omitting it when exactly one is declared renders that one automatically."),
+	targetFormat: OdbRenderReportTargetFormatSchema.describe("The format to render the report into."),
+	output: DocumentOutputSchema.optional().describe("Where to write the rendered report. Omit entirely (or omit outputPath within it) to receive the bytes inline instead."),
+	fonts: z.array(FontInputSchema).optional().describe("Extra font faces to make available, for a family the rendered report's own text otherwise falls back on. Only consulted when targetFormat is 'pdf' -- docx and odt output is genuine editable text with no font-embedding step of its own, so fonts is ignored for those two targets.")
+});
+const MathDiagnosticSchema = z.object({
+	kind: z.enum(["unsupported-element", "approximated-element"]),
+	detail: z.string(),
+	sourcePath: z.string().optional()
+});
+const FontSubstitutionSchema = z.object({
+	requestedFamily: z.string(),
+	requestedBold: z.boolean(),
+	requestedItalic: z.boolean(),
+	reason: z.enum(["missing-face", "vendored-substitute"]),
+	resolvedFamily: z.string()
+});
+const CharSubstitutionSchema = z.object({
+	from: z.string(),
+	to: z.string(),
+	pageIndex: z.number()
+});
+const diagnosticsShape = {
+	mathDiagnostics: z.array(MathDiagnosticSchema),
+	fontSubstitutions: z.array(FontSubstitutionSchema),
+	charSubstitutions: z.array(CharSubstitutionSchema)
+};
+const OdbRenderReportOutputSchema = z.union([z.object({
+	path: z.string(),
+	byteLength: z.number(),
+	...diagnosticsShape
+}), z.object({
+	bytesBase64: z.string(),
+	byteLength: z.number(),
+	large: z.literal(true).optional(),
+	...diagnosticsShape
+})]);
+const odbRenderReportOperation = defineOperation({
+	name: "odb_render_report",
+	title: "Render .odb report",
+	description: "Resolves one of an .odb database's own reports -- its data-bound command run through the bounded SQL engine, its rpt: formulas evaluated, its bands laid out -- and renders the result to docx, odt, or pdf.",
+	inputSchema: OdbRenderReportInputSchema,
+	outputSchema: OdbRenderReportOutputSchema,
+	async run({ source, report, targetFormat, output, fonts }, context) {
+		const signal = context?.signal;
+		const inputBytes = await resolveOdbBytes(source);
+		const pkg = decodeOdbPackage(inputBytes);
+		const content = readOdbReportContent(pkg, { report });
+		const mathDiagnostics = [];
+		const recordMathDiagnostic = (diagnostic, diagnosticContext) => {
+			mathDiagnostics.push({
+				kind: diagnostic.kind,
+				detail: diagnostic.detail,
+				sourcePath: diagnosticContext.sourcePath
+			});
+		};
+		const fontSubstitutions = [];
+		const charSubstitutions = [];
+		let bytes;
+		if (targetFormat === "docx") bytes = odbReportToDocx(content, {
+			signal,
+			onMathDiagnostic: recordMathDiagnostic
+		});
+		else if (targetFormat === "odt") bytes = odbReportToOdt(content, { signal });
+		else bytes = odbReportToPdf(content, {
+			signal,
+			fonts: fonts?.map((font) => ({
+				family: font.family,
+				bold: font.bold,
+				italic: font.italic,
+				bytes: base64ToBytes(font.bytesBase64)
+			})),
+			onFontSubstitution: (substitution) => fontSubstitutions.push(substitution),
+			onSubstitution: (substitution, substitutionContext) => {
+				charSubstitutions.push({
+					from: substitution.from,
+					to: substitution.to,
+					pageIndex: substitutionContext.pageIndex
+				});
+			},
+			onMathDiagnostic: recordMathDiagnostic
+		});
+		return {
+			...await resolveDocumentOutput(bytes, output ?? {}),
+			mathDiagnostics,
+			fontSubstitutions,
+			charSubstitutions
+		};
+	}
+});
+//#endregion
+//#region src/operations/odm.ts
+const OdmMasterSourceSchema = z.union([z.object({ path: z.string().describe("Filesystem path to the .odm master document to convert.") }), z.object({ bytesBase64: z.string().describe("Base64-encoded .odm master document bytes.") })]);
+async function resolveOdmMasterBytes(source) {
+	if ("path" in source) return new Uint8Array(await readFile(source.path));
+	return base64ToBytes(source.bytesBase64);
+}
+const OdmChapterInputSchema = z.object({
+	href: z.string().describe("The chapter's own text:section-source href as declared inside the .odm master document (e.g. '../chapter1.odt')."),
+	source: DocumentInputSchema.describe("The chapter document's own bytes -- always read as odt, regardless of the format this hybrid input declares.")
+});
+const OdmToPdfInputSchema = z.object({
+	source: OdmMasterSourceSchema.describe("The .odm master document to convert."),
+	chapters: z.array(OdmChapterInputSchema).default([]).describe("Explicit href -> chapter document overrides. Checked before chaptersDir for a given href."),
+	chaptersDir: z.string().optional().describe("Directory to search for each unresolved chapter href, matched by the href's own basename. Checked after chapters."),
+	output: DocumentOutputSchema.default({}).describe("Where to write the resulting PDF. Omit to receive the bytes inline, base64-encoded.")
+});
+const OdmToPdfOutputSchema = z.union([z.object({
+	path: z.string(),
+	byteLength: z.number()
+}), z.object({
+	bytesBase64: z.string(),
+	byteLength: z.number(),
+	large: z.literal(true).optional()
+})]);
+const odmToPdfOperation = defineOperation({
+	name: "odm_to_pdf",
+	title: "Convert ODM master document to PDF",
+	description: "Converts a .odm (ODF master document) to PDF. A .odm never carries its own chapters' content inline -- every text:section is a bare external reference to a standalone .odt file -- so each chapter the master document declares must resolve through `chapters` (an explicit href -> document override) and/or `chaptersDir` (a directory searched by the href's own basename), checked in that order. A chapter left unresolved by both fails the whole conversion, naming every unresolved href.",
+	inputSchema: OdmToPdfInputSchema,
+	outputSchema: OdmToPdfOutputSchema,
+	async run({ source, chapters, chaptersDir, output }) {
+		const masterBytes = await resolveOdmMasterBytes(source);
+		const overrides = /* @__PURE__ */ new Map();
+		for (const chapter of chapters) {
+			const { bytes: chapterBytes } = await resolveDocumentInput(chapter.source);
+			overrides.set(chapter.href, chapterBytes);
+		}
+		const resolveSubDocument = (href) => {
+			const overrideBytes = overrides.get(href);
+			if (overrideBytes !== void 0) return overrideBytes;
+			if (chaptersDir === void 0) return;
+			const candidate = join(chaptersDir, basename(href));
+			if (!existsSync(candidate)) return;
+			return new Uint8Array(readFileSync(candidate));
+		};
+		return resolveDocumentOutput(odmToPdf(masterBytes, { resolveSubDocument }), output);
+	}
+});
+//#endregion
+//#region src/operations/outline.ts
+function leafKind(leaf) {
+	if ("kind" in leaf) return leaf.kind;
+	if ("mathml" in leaf) return "formula";
+	return "embeddedObject";
+}
+function toOutlineJson(children) {
+	return children.map((child) => isOutlineNode(child) ? {
+		text: child.text,
+		level: child.level,
+		children: toOutlineJson(child.children)
+	} : {
+		kind: leafKind(child),
+		text: outlineLeafText(child)
+	});
+}
+const outlineDocumentOperation = defineOperationWithoutOutputSchema({
+	name: "outline_document",
+	title: "Outline document",
+	description: "Projects a document's table of contents as a structured outline: reads the source's own native DocumentTree directly (documents.js's readNativeDocumentTree -- no bridging conversion, no discarded output bytes) and runs document-outline.js's buildOutline over it. Groups carry { text, level, children } (a heading's, list item's, slide's, sheet's, or page's own label plus nested children); leaves carry { kind, text }.",
+	inputSchema: z.object({ source: DocumentInputSchema.describe("The document to outline.") }),
+	async run({ source }, context) {
+		const signal = context?.signal;
+		const { bytes, format } = await resolveDocumentInput(source, { signal });
+		const tree = readNativeDocumentTree(format, bytes, { signal });
+		return {
+			sourceFormat: format,
+			kind: tree.kind,
+			outline: toOutlineJson(buildOutline(tree))
+		};
+	}
+});
+//#endregion
+//#region src/operations/pdf-inspect.ts
+function buildItemKindHistogram(items) {
+	const histogram = /* @__PURE__ */ new Map();
+	for (const item of items) histogram.set(item.kind, (histogram.get(item.kind) ?? 0) + 1);
+	return histogram;
+}
+function countImagesByFormat(images) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const asset of Object.values(images)) counts.set(asset.format, (counts.get(asset.format) ?? 0) + 1);
+	return counts;
+}
+const pdfInspectOperation = defineOperationWithoutOutputSchema({
+	name: "pdf_inspect",
+	title: "Inspect PDF",
+	description: "Parses a PDF (documents.js's readPdf) and reports a summary: page count, each page's own size and item-kind histogram, document metadata, and embedded image formats. Pass full: true to return the entire parsed LayoutDocument instead of a summary.",
+	inputSchema: z.object({
+		source: DocumentInputSchema.describe("The PDF document to inspect."),
+		full: z.boolean().optional().describe("When true, return the entire parsed LayoutDocument instead of a summary. Defaults to false.")
+	}),
+	async run({ source, full }, context) {
+		const signal = context?.signal;
+		const { bytes, format } = await resolveDocumentInput(source, { signal });
+		if (format !== "pdf") throw new Error(`pdf_inspect requires a PDF document, received a "${format}" document instead.`);
+		const layout = readPdf(bytes, { signal });
+		if (full === true) return layout;
+		return {
+			pageCount: layout.pages.length,
+			pages: layout.pages.map((page) => ({
+				widthPt: page.widthPt,
+				heightPt: page.heightPt,
+				itemKinds: Object.fromEntries(buildItemKindHistogram(page.items))
+			})),
+			metadata: layout.metadata,
+			imagesByFormat: Object.fromEntries(countImagesByFormat(layout.images))
+		};
+	}
+});
+//#endregion
+//#region src/registry.ts
+/**
+* Every document operation this package defines, one entry per MCP tool/CLI command/REST route -- "the same registry as the MCP" a consumer that needs to enumerate every operation (rather than importing one by name) reaches for: an MCP server registers each entry as a tool, a REST server adds one route per entry, and a CLI can validate its own parsed flags against an entry's inputSchema before dispatching to its run().
+*/
+const DOCUMENT_OPERATIONS = [
+	convertDocumentOperation,
+	listDocumentConversionsOperation,
+	metadataReadOperation,
+	metadataWriteOperation,
+	documentCreateOperation,
+	documentAppendParagraphsOperation,
+	fontsOperation,
+	describeFontFileOperation,
+	docxExtrasOperation,
+	fromPackageOperation,
+	outlineDocumentOperation,
+	pdfInspectOperation,
+	computeFormulaOperation,
+	odmToPdfOperation,
+	odbTablesOperation,
+	odbFormsOperation,
+	odbReportsOperation,
+	odbQueryOperation,
+	odbToCsvOperation,
+	odbToXlsxOperation,
+	odbRenderReportOperation
+];
+//#endregion
+export { ComputeFormulaOutputSchema, ConvertDocumentOutputSchema, DOCUMENT_OPERATIONS, DocumentInputSchema, DocumentOutputSchema, FontInputSchema, LARGE_RESULT_THRESHOLD_BYTES, ListDocumentConversionsOutputSchema, OdbRenderReportOutputSchema, OdmToPdfOutputSchema, computeFormulaOperation, convertDocumentOperation, defineOperation, defineOperationWithoutOutputSchema, describeFontFileOperation, documentAppendParagraphsOperation, documentCreateOperation, docxExtrasOperation, fontsOperation, fromPackageOperation, inferFormatFromExtension, listDocumentConversionsOperation, metadataReadOperation, metadataWriteOperation, odbFormsOperation, odbQueryOperation, odbRenderReportOperation, odbReportsOperation, odbTablesOperation, odbToCsvOperation, odbToXlsxOperation, odmToPdfOperation, outlineDocumentOperation, pdfInspectOperation, resolveDocumentInput, resolveDocumentOutput, resolveOdbBytes };