@nhtio/adk 1.20260609.0 → 1.20260610.0

package/batteries/media.mjs

@@ -0,0 +1,3009 @@
+import { c as isObject, o as isError, s as isInstanceOf } from "../tool_registry-791Vrjtf.mjs";
+import "../guards.mjs";
+import { PCM_MIME, bytesToPcm, implementsMediaEngine, pcmToBytes } from "./media/contracts.mjs";
+import { a as E_MEDIA_NOT_PIPE_EXPRESSIBLE, c as E_MEDIA_STEP_UNAVAILABLE, d as E_MEDIA_UNSUPPORTED_OP, i as E_MEDIA_MISSING_ARG, l as E_MEDIA_UNKNOWN_ARG, n as E_MEDIA_BAD_ARG, o as E_MEDIA_PIPE_SYNTAX, r as E_MEDIA_ENGINE_REQUIRED, s as E_MEDIA_STEP_FAILED, t as E_INVALID_MEDIA_PIPELINE_CONFIG, u as E_MEDIA_UNKNOWN_VERB } from "../exceptions-C7FSHEnV.mjs";
+import { a as VERBS, c as suggestVerbs, d as isMediaRef, f as isRegExpRef, i as FOLDED_VERBS, l as canonicalFlags, m as toPipe, n as validateOps, o as VERB_INDEX, p as toOps, r as validateSegments, s as foldVerb, t as availableVerbs, u as fromOps } from "../validate-DSZ3wicB.mjs";
+import { validator } from "@nhtio/validation";
+import { Middleware } from "@nhtio/middleware";
+import moo from "moo";
+//#region src/batteries/media/pipe.ts
+/**
+* The pipe-expression front-end: a moo lexer plus a hand-rolled recursive-descent parser that
+* compiles `select pages=2-5 | redact match=/…/ | convert to=pdf` into a {@link MediaPlan}.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. The grammar is frozen in the
+* design doc (section 0):
+*
+* - `pipeline := segment ('|' segment)*` ; `segment := verb arg*` ; `arg := IDENT '=' value` —
+*   named args only, no positionals (an IDENT followed by `=` is an arg; otherwise it is the
+*   verb's second word — 2-token lookahead, no verb table needed at parse time).
+* - Verb matching is separator-insensitive (`extract_text` ≡ `extract text` ≡ `extract.text`).
+* - Values: bareword idents, ints/floats, `a-b` ranges, comma lists, `true`/`false`, quoted
+*   strings (single or double), class-aware `/regex/flags` literals, `@id` media refs, and
+*   quoted-JSON structured payloads (a quoted string that the verb's arg schema declares as
+*   `json` is JSON-parsed).
+* - `#` line comments are tolerated (models add them; ignoring them is free robustness).
+* - Two error layers: syntactic ({@link E_MEDIA_PIPE_SYNTAX}, with line/col and a corrective
+*   exemplar) and semantic ({@link E_MEDIA_UNKNOWN_VERB} etc., produced by the validator in
+*   `validate.ts` — this module only parses to a raw AST and lowers to the plan).
+*
+* Parsing is deployment-independent: the full verb table drives folding, and engine narrowing
+* happens later in validation (frozen 0.3).
+*/
+/**
+* The moo ruleset. Order matters: first match wins, so `range` must precede `int`, `float`
+* precedes `int`, and `comment` precedes nothing it could shadow. String/regex bodies exclude
+* raw newlines (escape them); `ws` carries `lineBreaks` so spans stay accurate across lines.
+*/
+var lexer = moo.compile({
+	ws: {
+		match: /[ \t\r\n]+/,
+		lineBreaks: true
+	},
+	comment: /#[^\n]*/,
+	pipe: "|",
+	eq: "=",
+	comma: ",",
+	ref: /@[A-Za-z0-9_-]+/,
+	regex: /\/(?:\\.|\[(?:\\.|[^\]\\\n])*\]|[^/\\[\n])+\/[a-z]*/,
+	dstring: /"(?:\\.|[^"\\\n])*"/,
+	sstring: /'(?:\\.|[^'\\\n])*'/,
+	range: /\d+-\d+/,
+	float: /\d+\.\d+/,
+	int: /\d+/,
+	ident: /[A-Za-z_][A-Za-z0-9_.]*/,
+	dash: "-"
+});
+/** Tokenize, skipping ws/comments, surfacing lexer errors as syntax exceptions. */
+var tokenize = (input) => {
+	lexer.reset(input);
+	const out = [];
+	let tok;
+	try {
+		while (tok = lexer.next()) {
+			if (tok.type === "ws" || tok.type === "comment") continue;
+			out.push({
+				type: tok.type,
+				value: tok.value,
+				text: tok.text,
+				offset: tok.offset,
+				line: tok.line,
+				col: tok.col
+			});
+		}
+	} catch (err) {
+		throw new E_MEDIA_PIPE_SYNTAX([`${isError(err) ? err.message.split("\n")[0] : String(err)}. Values containing special characters must be quoted — write it like: name="my-value"`]);
+	}
+	return out;
+};
+var spanOf = (tok, length) => ({
+	offset: tok.offset,
+	line: tok.line,
+	col: tok.col,
+	length: length ?? tok.text.length
+});
+var unquote = (raw) => raw.slice(1, -1).replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\(["'\\/])/g, "$1");
+var fail$5 = (tok, message, exemplar) => {
+	throw new E_MEDIA_PIPE_SYNTAX([`${message}${tok ? ` at line ${tok.line}, col ${tok.col}` : " at end of input"}. Write it like: ${exemplar}`]);
+};
+var Parser = class {
+	#toks;
+	#pos = 0;
+	constructor(toks) {
+		this.#toks = toks;
+	}
+	#peek(ahead = 0) {
+		return this.#toks[this.#pos + ahead];
+	}
+	#next() {
+		return this.#toks[this.#pos++];
+	}
+	parsePipeline() {
+		const segments = [];
+		if (this.#toks.length === 0) fail$5(void 0, "empty pipe expression", "extract text | chunk by=sentence");
+		segments.push(this.#parseSegment());
+		while (this.#peek()?.type === "pipe") {
+			this.#next();
+			segments.push(this.#parseSegment());
+		}
+		const trailing = this.#peek();
+		if (trailing) fail$5(trailing, `unexpected "${trailing.text}" after a complete segment`, "segment | segment (segments are separated by |)");
+		return segments;
+	}
+	#parseSegment() {
+		const first = this.#peek();
+		if (!first || first.type !== "ident") fail$5(first, "expected a verb to start the segment", "convert to=pdf");
+		const head = this.#next();
+		const collected = [head.value];
+		const posAfterWord = [this.#pos];
+		while (collected.length < 3) {
+			if (this.#peek()?.type !== "ident" || this.#peek(1)?.type === "eq") break;
+			collected.push(this.#next().value);
+			posAfterWord.push(this.#pos);
+		}
+		let take = collected.length;
+		if (foldVerb(collected) === void 0) {
+			let prefix = collected.length - 1;
+			while (prefix >= 1 && foldVerb(collected.slice(0, prefix)) === void 0) prefix -= 1;
+			if (prefix >= 1) take = prefix;
+		}
+		const words = collected.slice(0, take);
+		this.#pos = posAfterWord[take - 1];
+		const folded = foldVerb(words);
+		const verbText = words.join(" ");
+		const args = /* @__PURE__ */ new Map();
+		for (;;) {
+			const tok = this.#peek();
+			if (!tok || tok.type === "pipe") break;
+			if (tok.type === "dash") fail$5(tok, "unexpected \"-\" — values containing dashes must be quoted", `${verbText} name="value-with-dashes"`);
+			if (tok.type !== "ident" || this.#peek(1)?.type !== "eq") fail$5(tok, `unexpected "${tok.text}" — args must be name=value`, `${verbText} name=value`);
+			const name = this.#next().value;
+			this.#next();
+			const value = this.#parseValue(verbText, name);
+			if (args.has(name)) fail$5(tok, `duplicate arg "${name}"`, `${verbText} ${name}=value (give each arg once)`);
+			args.set(name, value);
+		}
+		return {
+			verb: folded ?? verbText,
+			known: folded !== void 0,
+			args,
+			span: spanOf(head, verbText.length)
+		};
+	}
+	#parseValue(verbText, argName) {
+		const first = this.#parseScalar(verbText, argName);
+		if (this.#peek()?.type !== "comma") return first;
+		const items = [...asScalarList(first, verbText, argName)];
+		let quoted = first.quoted;
+		while (this.#peek()?.type === "comma") {
+			this.#next();
+			const next = this.#parseScalar(verbText, argName);
+			quoted = quoted || next.quoted;
+			items.push(...asScalarList(next, verbText, argName));
+		}
+		return {
+			value: items,
+			quoted,
+			span: first.span
+		};
+	}
+	#parseScalar(verbText, argName) {
+		const tok = this.#peek();
+		if (!tok) fail$5(tok, `missing value for "${argName}"`, `${verbText} ${argName}=value`);
+		const t = tok;
+		switch (t.type) {
+			case "int":
+				this.#next();
+				return {
+					value: Number(t.value),
+					quoted: false,
+					span: spanOf(t)
+				};
+			case "float":
+				this.#next();
+				return {
+					value: Number(t.value),
+					quoted: false,
+					span: spanOf(t)
+				};
+			case "range": {
+				this.#next();
+				const [lo, hi] = t.value.split("-").map(Number);
+				if (lo > hi) fail$5(t, `range ${t.value} is descending (start must be ≤ end)`, `${argName}=${hi}-${lo}`);
+				const nums = [];
+				for (let n = lo; n <= hi; n++) nums.push(n);
+				return {
+					value: nums,
+					quoted: false,
+					span: spanOf(t)
+				};
+			}
+			case "ident":
+				this.#next();
+				if (t.value === "true") return {
+					value: true,
+					quoted: false,
+					span: spanOf(t)
+				};
+				if (t.value === "false") return {
+					value: false,
+					quoted: false,
+					span: spanOf(t)
+				};
+				return {
+					value: t.value,
+					quoted: false,
+					span: spanOf(t)
+				};
+			case "dstring":
+			case "sstring":
+				this.#next();
+				return {
+					value: unquote(t.text),
+					quoted: true,
+					span: spanOf(t)
+				};
+			case "regex": {
+				this.#next();
+				const lastSlash = t.text.lastIndexOf("/");
+				const source = t.text.slice(1, lastSlash);
+				const flags = canonicalFlags(t.text.slice(lastSlash + 1));
+				try {
+					new RegExp(source, flags);
+				} catch (err) {
+					const detail = isError(err) ? err.message : String(err);
+					fail$5(t, `invalid regex ${t.text}: ${detail}`, `${argName}=/pattern/flags`);
+				}
+				return {
+					value: {
+						source,
+						flags
+					},
+					quoted: false,
+					span: spanOf(t)
+				};
+			}
+			case "ref":
+				this.#next();
+				return {
+					value: {
+						kind: "id",
+						id: t.value.slice(1)
+					},
+					quoted: false,
+					span: spanOf(t)
+				};
+			case "dash":
+				fail$5(t, "unexpected \"-\" in a bare value", `${argName}="value-with-dashes" (quote values containing dashes)`);
+				break;
+			default: fail$5(t, `unexpected "${t.text}"`, `${verbText} ${argName}=value`);
+		}
+		throw new E_MEDIA_PIPE_SYNTAX(["internal parser error"]);
+	}
+};
+var asScalarList = (raw, verbText, argName) => {
+	if (Array.isArray(raw.value)) return raw.value;
+	if (raw.value === null || typeof raw.value === "object") {
+		const v = raw.value;
+		if (isObject(v) && !Array.isArray(v) && !("source" in v) && !("kind" in v)) throw new E_MEDIA_PIPE_SYNTAX([`structured values cannot appear in a comma list for "${argName}" on "${verbText}"`]);
+	}
+	return [raw.value];
+};
+/**
+* Parse a pipe expression into raw, position-bearing segments.
+*
+* @remarks
+* Purely syntactic — verbs are fold-matched against the full verb table for canonicalization
+* but unknown verbs are NOT an error here (the validator reports them with did-you-mean and the
+* deployment's narrowed verb list). Use {@link parsePipe} for the validated path.
+*
+* @param input - The pipe expression.
+* @returns The raw segments.
+*/
+var parsePipeRaw = (input) => {
+	return new Parser(tokenize(input)).parsePipeline();
+};
+/**
+* Lower raw segments to an (unvalidated) {@link MediaPlan}. Quoted-JSON arg parsing and
+* type/enum checks happen in the validator, which consumes the raw segments — this lowering
+* exists for tooling that wants the structural plan without validation.
+*
+* @param segments - Output of {@link parsePipeRaw}.
+* @returns The structural plan (args carried as parsed, json args still strings).
+*/
+var lowerSegments = (segments) => ({ steps: segments.map((seg) => ({
+	verb: seg.verb,
+	args: Object.fromEntries(Array.from(seg.args.entries(), ([k, v]) => [k, v.value])),
+	span: seg.span
+})) });
+//#endregion
+//#region src/batteries/media/builder.ts
+/**
+* The chainable, thenable media builder — the implementor-facing front-end that compiles to
+* the same {@link MediaPlan} as the pipe string and JSON ops.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. The knex lessons applied:
+* `mp(input)` opens a fresh immutable builder; every verb returns a new builder; awaiting the
+* builder executes the chain (no `.execute()`). Domain verbs hang off typed namespaces
+* (`.sheet`, `.slides`, `.image`, `.audio`); shared transforms live on the root.
+*
+* Each verb method appends an op and revalidates lazily — the full plan validates (verb table,
+* arg schemas, engine narrowing) when the chain executes, so building is cheap and the same
+* validator serves all three front-ends.
+*/
+var refOf = (other) => typeof other === "string" ? {
+	kind: "id",
+	id: other
+} : {
+	kind: "id",
+	id: other.mediaId
+};
+/**
+* The chainable builder. Immutable — every verb returns a new instance sharing the executor.
+* Thenable — `await` runs the chain and resolves to the terminal step's natural type.
+*/
+var MediaChain = class MediaChain {
+	#ops;
+	#exec;
+	constructor(exec, ops = []) {
+		this.#exec = exec;
+		this.#ops = ops;
+	}
+	#with(verb, args) {
+		return new MediaChain(this.#exec, [...this.#ops, {
+			verb,
+			args
+		}]);
+	}
+	/** Convert to another format (requires a convert engine). */
+	convert(to) {
+		return this.#with("convert", { to });
+	}
+	/** Keep only the listed 1-based pages. */
+	select(options) {
+		return this.#with("select", { pages: options.pages });
+	}
+	/** Split by page (optionally grouped `[[start,end], …]`). Terminal: resolves to media list. */
+	split(options = {}) {
+		const args = {};
+		if (options.by) args.by = options.by;
+		if (options.ranges) args.ranges = options.ranges;
+		return this.#with("split", args);
+	}
+	/** Merge other media into this one, in order. */
+	merge(...others) {
+		return this.#with("merge", { with: others.map(refOf) });
+	}
+	/** Reorder pages by 1-based index. */
+	reorder(order) {
+		return this.#with("reorder", { order });
+	}
+	/** Redact matching text (literals or RegExp). */
+	redact(options) {
+		const args = { match: (Array.isArray(options.match) ? options.match : [options.match]).map((m) => typeof m === "string" ? m : {
+			source: m.source,
+			flags: Array.from(m.flags).sort().join("")
+		}) };
+		if (options.replace !== void 0) args.replace = options.replace;
+		return this.#with("redact", args);
+	}
+	/** Remove potentially unsafe embedded content. */
+	sanitize() {
+		return this.#with("sanitize", {});
+	}
+	/** Normalize structure/encoding. */
+	normalize() {
+		return this.#with("normalize", {});
+	}
+	/** Replace the first occurrence of anchor text. */
+	updateText(anchor, replace) {
+		return this.#with("update_text", {
+			anchor,
+			replace
+		});
+	}
+	/** Compare against another media. Terminal: resolves to a structured diff. */
+	diff(other) {
+		return this.#with("diff", { with: refOf(other) });
+	}
+	/** Apply a unified-diff patch. */
+	applyPatch(patch, options = {}) {
+		const args = { patch };
+		if (options.with) args.with = options.with.map(refOf);
+		return this.#with("apply_patch", args);
+	}
+	/** Extract text (routes by format; OCR engine used when needed). Terminal: resolves to text. */
+	extractText(options = {}) {
+		const args = {};
+		if (options.ocr) args.ocr = options.ocr;
+		if (options.ocrOut) args.ocr_out = options.ocrOut;
+		if (options.lang) args.lang = options.lang;
+		return this.#with("extract.text", args);
+	}
+	/** Extract metadata. Terminal: resolves to a metadata object. */
+	extractMetadata() {
+		return this.#with("extract.metadata", {});
+	}
+	/** Extract embedded assets. Terminal: resolves to a media list. */
+	extractAssets(options = {}) {
+		const args = {};
+		if (options.types) args.types = options.types;
+		return this.#with("extract.assets", args);
+	}
+	/** Chunk extracted text. Terminal: resolves to a chunk array. */
+	chunk(options = {}) {
+		const args = {};
+		if (options.strategy) args.by = options.strategy;
+		if (options.size !== void 0) args.size = options.size;
+		if (options.overlap !== void 0) args.overlap = options.overlap;
+		return this.#with("chunk", args);
+	}
+	/** Spreadsheet mutations. */
+	get sheet() {
+		return new SheetNamespace(this);
+	}
+	/** Presentation mutations. */
+	get slides() {
+		return new SlidesNamespace(this);
+	}
+	/** Image transforms. */
+	get image() {
+		return new ImageNamespace(this);
+	}
+	/** Audio operations. */
+	get audio() {
+		return new AudioNamespace(this);
+	}
+	/** The accumulated ops (a copy). */
+	toOps() {
+		return this.#ops.map((op) => ({
+			verb: op.verb,
+			args: { ...op.args }
+		}));
+	}
+	/** The canonical pipe form of the accumulated chain. */
+	toPipe() {
+		return toPipe({ steps: this.#ops.map((op) => ({
+			verb: op.verb,
+			args: op.args
+		})) });
+	}
+	/** Internal — used by namespaces to append. */
+	withOp(verb, args) {
+		return this.#with(verb, args);
+	}
+	/** Thenable: awaiting the chain executes it. */
+	then(onfulfilled, onrejected) {
+		return this.#exec(this.toOps()).then(unwrapResult).then(onfulfilled, onrejected);
+	}
+	/** Execute and return the raw {@link PlanResult} (no unwrapping). */
+	async run() {
+		return this.#exec(this.toOps());
+	}
+};
+/** Resolve a plan result to its natural awaited type. */
+var unwrapResult = (result) => {
+	if (result.kind === "media") return result.payload;
+	if (result.kind === "media-list") return result.payloads;
+	return result.data;
+};
+/** `sheet.*` verbs, mirrored from the verb table. */
+var SheetNamespace = class {
+	#chain;
+	constructor(chain) {
+		this.#chain = chain;
+	}
+	/** Insert rows. */
+	addRows(rows, options = {}) {
+		return this.#chain.withOp("sheet.add_rows", compact({
+			rows,
+			...targetArgs(options),
+			before: options.before,
+			after: options.after
+		}));
+	}
+	/** Insert columns. */
+	addColumns(options) {
+		return this.#chain.withOp("sheet.add_columns", compact({
+			...targetArgs(options),
+			headers: options.headers,
+			columns: options.columns,
+			before: options.before,
+			after: options.after
+		}));
+	}
+	/** Update cells. */
+	updateCells(updates, options = {}) {
+		return this.#chain.withOp("sheet.update_cells", compact({
+			updates,
+			...targetArgs(options)
+		}));
+	}
+	/** Delete rows by 1-based index. */
+	deleteRows(rows, options = {}) {
+		return this.#chain.withOp("sheet.delete_rows", compact({
+			rows,
+			...targetArgs(options)
+		}));
+	}
+	/** Delete columns by 1-based index. */
+	deleteColumns(columns, options = {}) {
+		return this.#chain.withOp("sheet.delete_columns", compact({
+			columns,
+			...targetArgs(options)
+		}));
+	}
+	/** Rename a worksheet (name-targeted). */
+	renameSheet(sheet, to) {
+		return this.#chain.withOp("sheet.rename_sheet", {
+			sheet,
+			to
+		});
+	}
+	/** Add a worksheet. */
+	addSheet(name, options = {}) {
+		return this.#chain.withOp("sheet.add_sheet", compact({
+			name,
+			at: options.at
+		}));
+	}
+	/** Remove a worksheet (name-targeted). */
+	removeSheet(sheet) {
+		return this.#chain.withOp("sheet.remove_sheet", { sheet });
+	}
+	/** Reorder worksheets by names and/or 1-based indices. */
+	reorderSheets(order) {
+		return this.#chain.withOp("sheet.reorder_sheets", { order });
+	}
+	/** Table transforms by header name. */
+	transformTable(options) {
+		return this.#chain.withOp("sheet.transform_table", compact({
+			...targetArgs(options),
+			header_row: options.headerRow,
+			select: options.select,
+			drop: options.drop,
+			rename: options.rename
+		}));
+	}
+};
+/** `slides.*` verbs. */
+var SlidesNamespace = class {
+	#chain;
+	constructor(chain) {
+		this.#chain = chain;
+	}
+	/** Add a slide. */
+	add(options = {}) {
+		return this.#chain.withOp("slides.add", compact({
+			at: options.at,
+			title: options.title,
+			layout: options.layout
+		}));
+	}
+	/** Update text on a slide. */
+	updateText(text, options = {}) {
+		return this.#chain.withOp("slides.update_text", compact({
+			text,
+			slide: slideArg(options.slide),
+			placeholder: options.placeholder
+		}));
+	}
+	/** Update table cells on a slide. */
+	updateTable(updates, options = {}) {
+		return this.#chain.withOp("slides.update_table", compact({
+			updates,
+			slide: slideArg(options.slide)
+		}));
+	}
+	/** Replace an image on a slide with another media. */
+	updateImage(withMedia, options = {}) {
+		return this.#chain.withOp("slides.update_image", compact({
+			with: refOf(withMedia),
+			slide: slideArg(options.slide),
+			placeholder: options.placeholder
+		}));
+	}
+	/** Update chart data on a slide. */
+	updateChart(data, options = {}) {
+		return this.#chain.withOp("slides.update_chart", compact({
+			data,
+			slide: slideArg(options.slide)
+		}));
+	}
+	/** Delete slides by 1-based index. */
+	delete(slides) {
+		return this.#chain.withOp("slides.delete", { slides });
+	}
+	/** Reorder slides. */
+	reorder(order) {
+		return this.#chain.withOp("slides.reorder", { order });
+	}
+	/** Duplicate a slide. */
+	duplicate(slide, options = {}) {
+		return this.#chain.withOp("slides.duplicate", compact({
+			slide,
+			at: options.at
+		}));
+	}
+};
+/** `image.*` verbs (the runtime fuses adjacent image steps into one engine pass). */
+var ImageNamespace = class {
+	#chain;
+	constructor(chain) {
+		this.#chain = chain;
+	}
+	/** Resize. */
+	resize(options) {
+		return this.#chain.withOp("image.resize", compact({
+			width: options.width,
+			height: options.height,
+			fit: options.fit
+		}));
+	}
+	/** Re-encode to another format. */
+	format(to, options = {}) {
+		return this.#chain.withOp("image.format", compact({
+			to,
+			quality: options.quality,
+			strip_metadata: options.stripMetadata
+		}));
+	}
+	/** Rotate clockwise. */
+	rotate(deg) {
+		return this.#chain.withOp("image.rotate", { deg: String(deg) });
+	}
+	/** Flip. */
+	flip(axis) {
+		return this.#chain.withOp("image.flip", { axis });
+	}
+	/** Strip EXIF/ICC metadata. */
+	stripMetadata() {
+		return this.#chain.withOp("image.strip_metadata", {});
+	}
+};
+/** `audio.*` verbs. */
+var AudioNamespace = class {
+	#chain;
+	constructor(chain) {
+		this.#chain = chain;
+	}
+	/** Transcribe speech. Terminal: resolves to text (or srt/vtt/json per `out`). */
+	transcribe(options = {}) {
+		return this.#chain.withOp("audio.transcribe", compact({
+			lang: options.language,
+			out: options.out,
+			translate: options.translate
+		}));
+	}
+};
+var targetArgs = (options) => options.sheet === void 0 ? {} : { sheet: options.sheet };
+var slideArg = (slide) => slide;
+var compact = (args) => {
+	const out = {};
+	for (const [k, v] of Object.entries(args)) if (v !== void 0) out[k] = v;
+	return out;
+};
+//#endregion
+//#region src/batteries/media/runtime.ts
+/**
+* The step runtime: executes a validated {@link MediaPlan} as an `@nhtio/middleware` onion,
+* one stage per step, with consumer interceptors wrapping every step.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. A fresh `Runner` is minted per
+* execution (middleware runners are single-use), so the same compiled chain can be awaited
+* repeatedly. Each step stage:
+*
+* 1. runs the consumer's `use` interceptors (the documented seam for DLP/AV scanning, caching
+*    via `shortCircuit(bytes)`, byte limits, and telemetry — the battery ships no built-in
+*    scanner/cache/limiter: those are policies, this is the seam), then
+* 2. dispatches to the verb's registered {@link StepImpl}, validating the output at the step
+*    boundary so a misbehaving engine produces a clear error instead of corrupt bytes.
+*
+* Steps stream bytes in memory; nothing touches disk except inside a binary engine's
+* `ScratchWorkspace`. Adjacent `image.*` steps are fused by the compiler before execution so
+* a resize→format→rotate chain costs a single decode/encode.
+*/
+/** Internal sentinel for {@link StepContext.shortCircuit}. */
+var SHORT_CIRCUIT = Symbol("adk.media.shortCircuit");
+var isShortCircuit = (value) => isObject(value) && value[SHORT_CIRCUIT] === true;
+/**
+* Execute a validated plan. Returns the final step's result; intermediate steps must produce
+* `media` results (the compiler guarantees non-terminal steps are media-shaped).
+*
+* @param plan - The validated plan.
+* @param options - Input payload, step registry, interceptors, engine access.
+* @returns The terminal step's result.
+*/
+var executePlan = async (plan, options) => {
+	const stash = /* @__PURE__ */ new Map();
+	let payload = options.input;
+	let result = {
+		kind: "media",
+		payload
+	};
+	for (let i = 0; i < plan.steps.length; i++) {
+		const step = plan.steps[i];
+		options.signal?.throwIfAborted();
+		const impl = options.steps.get(step.verb);
+		if (!impl) throw new E_MEDIA_STEP_UNAVAILABLE([step.verb]);
+		const ctx = {
+			plan,
+			stepIndex: i,
+			step,
+			payload,
+			signal: options.signal,
+			stash,
+			shortCircuit: (sc) => {
+				throw {
+					[SHORT_CIRCUIT]: true,
+					payload: sc
+				};
+			},
+			engines: options.engines,
+			resolveRef: options.resolveRef
+		};
+		try {
+			result = await runStep(ctx, impl, options.use);
+		} catch (err) {
+			if (isShortCircuit(err)) result = {
+				kind: "media",
+				payload: err.payload
+			};
+			else if (isError(err) && err.name.startsWith("E_MEDIA_")) throw err;
+			else {
+				const detail = isError(err) ? err.message : String(err);
+				throw new E_MEDIA_STEP_FAILED([step.verb, detail], { cause: err });
+			}
+		}
+		if (result.kind === "media") payload = result.payload;
+		else if (i < plan.steps.length - 1) if (result.kind === "data" && typeof result.asText === "string" && VERB_INDEX.get(step.verb)?.output === "text") {
+			payload = {
+				bytes: new TextEncoder().encode(result.asText),
+				mimeType: "text/plain",
+				filename: materializedName(payload.filename)
+			};
+			result = {
+				kind: "media",
+				payload
+			};
+		} else throw new E_MEDIA_STEP_FAILED([step.verb, "a non-terminal step produced a terminal result; only the last step may yield data or multiple media"]);
+	}
+	return result;
+};
+/** Run one step: interceptor onion (fresh runner) terminating in the implementation. */
+var runStep = async (ctx, impl, use) => {
+	if (use.length === 0) return validated(ctx, await impl(ctx));
+	const mw = new Middleware();
+	for (const fn of use) mw.add(fn);
+	let result;
+	let caught;
+	await mw.runner().errorHandler(async (error) => {
+		caught = error;
+	}).finalHandler(async () => {
+		result = validated(ctx, await impl(ctx));
+	}).run((fn, next) => Promise.resolve(fn(ctx, next)));
+	if (caught !== void 0) throw caught;
+	if (result === void 0) throw new E_MEDIA_STEP_FAILED([ctx.step.verb, "a step interceptor did not call next() and did not short-circuit"]);
+	return result;
+};
+/** Validate a step implementation's output shape at the boundary. */
+var validated = (ctx, result) => {
+	const bad = (msg) => {
+		throw new E_MEDIA_STEP_FAILED([ctx.step.verb, `implementation returned ${msg}`]);
+	};
+	const isBytes = (value) => isInstanceOf(value, "Uint8Array", Uint8Array);
+	if (result.kind === "media") {
+		if (!isBytes(result.payload?.bytes)) bad("a media result without bytes");
+		if (typeof result.payload.mimeType !== "string") bad("a media result without a mimeType");
+		return result;
+	}
+	if (result.kind === "media-list") {
+		if (!Array.isArray(result.payloads) || result.payloads.some((p) => !isBytes(p.bytes))) bad("a media-list result with invalid payloads");
+		return result;
+	}
+	if (result.kind === "data") return result;
+	return bad("an unknown result kind");
+};
+/** Filename for an R-step's materialized text payload. */
+var materializedName = (filename) => {
+	const dot = filename.lastIndexOf(".");
+	return `${dot > 0 ? filename.slice(0, dot) : filename}.txt`;
+};
+/** Convenience: read a step arg with a typed cast (validation already ran). */
+var argOf = (step, name) => step.args[name];
+//#endregion
+//#region src/batteries/media/formats.ts
+/** Well-known MIME constants used across the battery. */
+var MIME = {
+	DOCX: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+	XLSX: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+	PPTX: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+	ODT: "application/vnd.oasis.opendocument.text",
+	ODS: "application/vnd.oasis.opendocument.spreadsheet",
+	ODP: "application/vnd.oasis.opendocument.presentation",
+	PDF: "application/pdf",
+	DOC: "application/msword",
+	XLS: "application/vnd.ms-excel",
+	PPT: "application/vnd.ms-powerpoint",
+	PAGES: "application/x-iwork-pages-sffpages",
+	NUMBERS: "application/x-iwork-numbers-sffnumbers",
+	KEYNOTE: "application/x-iwork-keynote-sffkey",
+	TXT: "text/plain",
+	MD: "text/markdown",
+	CSV: "text/csv",
+	HTML: "text/html",
+	JSON: "application/json",
+	PNG: "image/png",
+	JPEG: "image/jpeg",
+	WEBP: "image/webp",
+	TIFF: "image/tiff",
+	AVIF: "image/avif",
+	WAV: "audio/wav",
+	MP3: "audio/mpeg"
+};
+/** Legacy Office MIME types (extraction only — mutation is rejected). */
+var LEGACY_OFFICE_MIMES = new Set([
+	MIME.DOC,
+	MIME.XLS,
+	MIME.PPT
+]);
+/** Apple iWork MIME types (extraction only — mutation is rejected). */
+var IWORK_MIMES = new Set([
+	MIME.PAGES,
+	MIME.NUMBERS,
+	MIME.KEYNOTE
+]);
+var SPREADSHEET_MIMES = new Set([
+	MIME.XLSX,
+	MIME.ODS,
+	MIME.XLS,
+	MIME.CSV
+]);
+var PRESENTATION_MIMES = new Set([
+	MIME.PPTX,
+	MIME.ODP,
+	MIME.PPT,
+	MIME.KEYNOTE
+]);
+var DOCUMENT_MIMES = new Set([
+	MIME.PDF,
+	MIME.DOCX,
+	MIME.ODT,
+	MIME.DOC,
+	MIME.PAGES,
+	MIME.TXT,
+	MIME.MD,
+	MIME.HTML,
+	MIME.JSON,
+	"application/rtf",
+	"text/rtf"
+]);
+/**
+* Classify a MIME type into the verb table's broad format family.
+*
+* @param mimeType - The media MIME type.
+* @returns The family used by verb-applicability checks.
+*/
+var familyOf = (mimeType) => {
+	const mime = mimeType.toLowerCase().split(";")[0].trim();
+	if (SPREADSHEET_MIMES.has(mime)) return "spreadsheet";
+	if (PRESENTATION_MIMES.has(mime)) return "presentation";
+	if (DOCUMENT_MIMES.has(mime)) return "document";
+	if (mime.startsWith("image/")) return "image";
+	if (mime.startsWith("audio/")) return "audio";
+	if (mime.startsWith("text/")) return "document";
+	return "document";
+};
+/**
+* Reason a mutation verb cannot run against this MIME type, or `undefined` when mutation is
+* allowed. Returns a reason string (not a throw) so callers compose model-actionable failures.
+*
+* @param mimeType - The media MIME type.
+* @returns A human-readable reason, or `undefined` when mutation is supported.
+*/
+var unsupportedForMutationReason = (mimeType) => {
+	const mime = mimeType.toLowerCase().split(";")[0].trim();
+	if (LEGACY_OFFICE_MIMES.has(mime)) return `legacy Office format (${mime}) supports extraction only — convert it first (e.g. convert to=docx)`;
+	if (IWORK_MIMES.has(mime)) return `Apple iWork format (${mime}) supports extraction only`;
+};
+/** A small extension → MIME lookup for filenames produced by transforms. */
+var EXT_TO_MIME = {
+	pdf: MIME.PDF,
+	docx: MIME.DOCX,
+	xlsx: MIME.XLSX,
+	pptx: MIME.PPTX,
+	odt: MIME.ODT,
+	ods: MIME.ODS,
+	odp: MIME.ODP,
+	doc: MIME.DOC,
+	xls: MIME.XLS,
+	ppt: MIME.PPT,
+	txt: MIME.TXT,
+	md: MIME.MD,
+	csv: MIME.CSV,
+	html: MIME.HTML,
+	json: MIME.JSON,
+	rtf: "application/rtf",
+	png: MIME.PNG,
+	jpg: MIME.JPEG,
+	jpeg: MIME.JPEG,
+	webp: MIME.WEBP,
+	tiff: MIME.TIFF,
+	avif: MIME.AVIF,
+	wav: MIME.WAV,
+	mp3: MIME.MP3
+};
+/**
+* Replace (or add) a filename's extension.
+*
+* @param filename - The original filename.
+* @param ext - The new extension, without the dot.
+* @returns The filename with the new extension.
+*/
+var replaceExtension = (filename, ext) => {
+	const dot = filename.lastIndexOf(".");
+	return `${dot > 0 ? filename.slice(0, dot) : filename}.${ext}`;
+};
+//#endregion
+//#region src/batteries/media/steps/text.ts
+/**
+* Pure text-shaped step implementations: chunking, plain-text extraction, text diff/patch,
+* and the text-mode redact/update_text paths.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. The split functions are ported
+* verbatim from the source server's `chunk_text` adapter (its green unit suite ports with
+* them). All implementations here operate on in-memory bytes and run in any environment.
+*/
+/** Split text on double-newline paragraph boundaries, with optional character overlap. */
+var splitParagraph = (text, overlap) => {
+	const blocks = text.split(/\n{2,}/).map((b) => b.trim()).filter(Boolean);
+	const chunks = [];
+	let pos = 0;
+	for (let i = 0; i < blocks.length; i++) {
+		const block = blocks[i];
+		const overlapText = i > 0 && overlap > 0 ? blocks.slice(Math.max(0, i - 1), i).join("\n\n").slice(-overlap) : "";
+		const chunkText = overlapText ? `${overlapText}\n\n${block}` : block;
+		chunks.push({
+			index: i,
+			text: chunkText,
+			char_start: pos,
+			char_end: pos + block.length
+		});
+		pos += block.length + 2;
+	}
+	return chunks;
+};
+/** Split text on sentence-ending punctuation, with optional character overlap. */
+var splitSentence = (text, overlap) => {
+	const sentences = text.match(/[^.!?]+[.!?](?:\s|$)|[^.!?]+$/g) ?? [text];
+	const chunks = [];
+	let pos = 0;
+	for (let i = 0; i < sentences.length; i++) {
+		const sentence = sentences[i].trim();
+		if (!sentence) continue;
+		const overlapText = i > 0 && overlap > 0 ? sentences.slice(Math.max(0, i - 1), i).join(" ").slice(-overlap) : "";
+		const chunkText = overlapText ? `${overlapText} ${sentence}` : sentence;
+		chunks.push({
+			index: chunks.length,
+			text: chunkText,
+			char_start: pos,
+			char_end: pos + sentence.length
+		});
+		pos += sentence.length + 1;
+	}
+	return chunks;
+};
+/** Split text into fixed-size character windows with optional overlap. */
+var splitFixed = (text, chunkSize, overlap) => {
+	const chunks = [];
+	const step = Math.max(1, chunkSize - overlap);
+	let i = 0;
+	let idx = 0;
+	while (i < text.length) {
+		const start = Math.max(0, i - overlap);
+		const end = i + chunkSize;
+		chunks.push({
+			index: idx++,
+			text: text.slice(start, end),
+			char_start: start,
+			char_end: Math.min(end, text.length)
+		});
+		i += step;
+	}
+	return chunks;
+};
+var decoder = new TextDecoder("utf-8", { fatal: false });
+var encoder = new TextEncoder();
+/** Decode payload bytes as UTF-8 text (UTF-16 BOM aware). */
+var decodeText = (bytes) => {
+	if (bytes.length >= 2) {
+		if (bytes[0] === 255 && bytes[1] === 254) return new TextDecoder("utf-16le").decode(bytes.subarray(2));
+		if (bytes[0] === 254 && bytes[1] === 255) return new TextDecoder("utf-16be").decode(bytes.subarray(2));
+	}
+	return decoder.decode(bytes).replace(/\r\n?/g, "\n");
+};
+var textPayload = (source, text, suffix) => ({
+	bytes: encoder.encode(text),
+	mimeType: MIME.TXT,
+	filename: replaceExtension(source.filename, suffix)
+});
+/** `chunk` — split text content into retrieval chunks (data result). */
+var chunkStep = async (ctx) => {
+	const by = argOf(ctx.step, "by") ?? "paragraph";
+	const size = argOf(ctx.step, "size") ?? 1e3;
+	const overlap = argOf(ctx.step, "overlap") ?? 0;
+	const text = decodeText(ctx.payload.bytes);
+	const chunks = by === "sentence" ? splitSentence(text, overlap) : by === "fixed" ? splitFixed(text, size, overlap) : splitParagraph(text, overlap);
+	return {
+		kind: "data",
+		data: chunks,
+		asText: JSON.stringify(chunks)
+	};
+};
+/**
+* `extract.text` — Phase 0 covers the native-text path (txt/md/csv/json/html). Document
+* formats (pdf/docx/…) and OCR routes are added by later phases; until then they fail with a
+* clear reason.
+*/
+var extractTextStep = async (ctx) => {
+	const family = familyOf(ctx.payload.mimeType);
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (!(mime.startsWith("text/") || mime === MIME.JSON || mime === MIME.MD || mime === MIME.CSV)) throw new E_MEDIA_STEP_FAILED(["extract.text", `extraction for ${family} media (${mime}) is not yet implemented in this build`]);
+	const text = decodeText(ctx.payload.bytes);
+	return {
+		kind: "data",
+		data: text,
+		asText: text
+	};
+};
+/** `extract.metadata` — Phase 0: size/MIME/filename basics (format-aware fields come later). */
+var extractMetadataStep = async (ctx) => {
+	const meta = {
+		filename: ctx.payload.filename,
+		mime_type: ctx.payload.mimeType,
+		size_bytes: ctx.payload.bytes.byteLength,
+		family: familyOf(ctx.payload.mimeType)
+	};
+	return {
+		kind: "data",
+		data: meta,
+		asText: JSON.stringify(meta)
+	};
+};
+var toPattern = (value) => {
+	if (typeof value === "string") return value;
+	const ref = value;
+	return new RegExp(ref.source, ref.flags.includes("g") ? ref.flags : `${ref.flags}g`);
+};
+var applyRedaction = (text, patterns, replacement) => {
+	let out = text;
+	for (const p of patterns) {
+		const pattern = toPattern(p);
+		out = typeof pattern === "string" ? out.split(pattern).join(replacement) : out.replace(pattern, replacement);
+	}
+	return out;
+};
+/** `redact` — Phase 0: the text-media path. Document-format in-place redaction lands later. */
+var redactStep = async (ctx) => {
+	if (!ctx.payload.mimeType.toLowerCase().startsWith("text/")) throw new E_MEDIA_STEP_FAILED(["redact", `redaction for ${ctx.payload.mimeType} is not yet implemented in this build`]);
+	const raw = ctx.step.args.match;
+	const patterns = Array.isArray(raw) ? raw : [raw];
+	const replacement = argOf(ctx.step, "replace") ?? "█";
+	const text = applyRedaction(decodeText(ctx.payload.bytes), patterns, replacement);
+	return {
+		kind: "media",
+		payload: textPayload(ctx.payload, text, "txt")
+	};
+};
+/** `update_text` — Phase 0: the text-media path. */
+var updateTextStep = async (ctx) => {
+	if (!ctx.payload.mimeType.toLowerCase().startsWith("text/")) throw new E_MEDIA_STEP_FAILED(["update_text", `text update for ${ctx.payload.mimeType} is not yet implemented in this build`]);
+	const anchor = argOf(ctx.step, "anchor");
+	const replace = argOf(ctx.step, "replace") ?? "";
+	const text = decodeText(ctx.payload.bytes);
+	if (!text.includes(anchor)) throw new E_MEDIA_STEP_FAILED(["update_text", `anchor text not found: "${anchor.slice(0, 80)}"`]);
+	const updated = text.replace(anchor, replace);
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes: encoder.encode(updated)
+		}
+	};
+};
+/** Build a unified diff between two texts using the `diff` peer (lazy import). */
+var unifiedDiff = async (aName, bName, a, b) => {
+	return (await import("diff")).createTwoFilesPatch(aName, bName, a, b);
+};
+/** `diff` — compare against another media (text-comparable formats in Phase 0). */
+var diffStep = async (ctx) => {
+	const ref = ctx.step.args.with;
+	if (ref.kind !== "id") throw new E_MEDIA_STEP_FAILED(["diff", "builder refs are not yet supported here"]);
+	const other = await ctx.resolveRef(ref.id);
+	const a = decodeText(ctx.payload.bytes);
+	const b = decodeText(other.bytes);
+	const patch = await unifiedDiff(ctx.payload.filename, other.filename, a, b);
+	return {
+		kind: "data",
+		data: {
+			patch,
+			changes: (await import("diff")).diffLines(a, b).map((part) => ({
+				added: part.added === true,
+				removed: part.removed === true,
+				count: part.count ?? 0,
+				value: part.value
+			}))
+		},
+		asText: patch
+	};
+};
+/** `apply_patch` — apply a unified diff to the media text. */
+var applyPatchStep = async (ctx) => {
+	const patch = argOf(ctx.step, "patch");
+	const text = decodeText(ctx.payload.bytes);
+	const result = (await import("diff")).applyPatch(text, patch);
+	if (result === false) throw new E_MEDIA_STEP_FAILED(["apply_patch", "the patch does not apply to this media content (context mismatch)"]);
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes: encoder.encode(result)
+		}
+	};
+};
+//#endregion
+//#region src/batteries/media/steps/doc.ts
+/**
+* Doc-domain step extensions: format-preserving text mutation for DOCX/PPTX, asset
+* extraction from OOXML/ODF archives and PDFs, and format conversion via the convert engine.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. Ported from the source server's
+* doc adapters; the format-dispatch contract follows the server's green e2e suite: DOCX and
+* PPTX redact/sanitize/normalize/update_text mutate text in place inside the container
+* (preserving the source format); text-like inputs mutate as text; PDF redact falls back to
+* text extraction (the server's PDF "visual annotation" path is content-stream-preserving and
+* out of scope here — the failure message says exactly that).
+*/
+var zipPromise$2;
+var jszip$2 = () => {
+	zipPromise$2 ??= import("jszip").then((m) => "default" in m ? m.default : m);
+	return zipPromise$2;
+};
+var fail$4 = (verb, message) => {
+	throw new E_MEDIA_STEP_FAILED([verb, message]);
+};
+var escapeXml$1 = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+var unescapeXml = (value) => value.replace(/&apos;/g, "'").replace(/&quot;/g, "\"").replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&");
+/**
+* Replace matches inside text nodes of OOXML, aggregating runs per paragraph so patterns
+* spanning split runs still match (Word splits text across `w:t` runs on formatting changes).
+*/
+var replaceInOoxml = (xml, paragraphTag, textTag, pattern, replacement) => {
+	let totalMatches = 0;
+	const pRegex = new RegExp(`<${paragraphTag}\\b[^>]*>[\\s\\S]*?</${paragraphTag}>`, "g");
+	return {
+		xml: xml.replace(pRegex, (pXml) => {
+			const tElements = [];
+			const tRegex = new RegExp(`<${textTag}(?:\\s[^>]*)?>([^<]*)</${textTag}>`, "g");
+			let tMatch;
+			while (tMatch = tRegex.exec(pXml)) tElements.push({
+				start: tMatch.index,
+				end: tMatch.index + tMatch[0].length,
+				content: unescapeXml(tMatch[1])
+			});
+			if (tElements.length === 0) return pXml;
+			const aggregated = tElements.map((t) => t.content).join("");
+			const p = new RegExp(pattern.source, pattern.flags);
+			const replaced = aggregated.replace(p, replacement);
+			if (replaced === aggregated) return pXml;
+			const counter = new RegExp(pattern.source, pattern.flags);
+			while (counter.exec(aggregated)) {
+				totalMatches += 1;
+				if (!counter.global) break;
+			}
+			let out = pXml;
+			for (let i = tElements.length - 1; i >= 0; i--) {
+				const el = tElements[i];
+				const space = textTag === "w:t" && i === 0 ? " xml:space=\"preserve\"" : "";
+				const content = i === 0 ? escapeXml$1(replaced) : "";
+				out = out.slice(0, el.start) + `<${textTag}${space}>${content}</${textTag}>` + out.slice(el.end);
+			}
+			return out;
+		}),
+		matchCount: totalMatches
+	};
+};
+/** Map text-node mutation over every relevant part of a DOCX or PPTX archive. */
+var mutateOoxmlText = async (ctx, verb, mutateXml) => {
+	const kind = ctx.payload.mimeType.toLowerCase().split(";")[0].trim() === MIME.DOCX ? "docx" : "pptx";
+	const JSZip = await jszip$2();
+	let zip;
+	try {
+		zip = await JSZip.loadAsync(ctx.payload.bytes);
+	} catch (err) {
+		fail$4(verb, `could not open the document container: ${isError(err) ? err.message : String(err)}`);
+		throw err;
+	}
+	const parts = kind === "docx" ? Object.keys(zip.files).filter((n) => /^word\/(document|header\d*|footer\d*)\.xml$/.test(n)) : Object.keys(zip.files).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n));
+	if (parts.length === 0) fail$4(verb, "the container has no text parts to mutate (corrupt file?)");
+	for (const part of parts) {
+		const xml = await zip.file(part).async("text");
+		const next = mutateXml(xml, kind);
+		if (next !== xml) zip.file(part, next);
+	}
+	const bytes = await zip.generateAsync({
+		type: "uint8array",
+		compression: "DEFLATE"
+	});
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes
+		}
+	};
+};
+var toGlobalRegex = (value) => {
+	if (typeof value === "string") {
+		const escaped = value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		return new RegExp(escaped, "g");
+	}
+	const ref = value;
+	return new RegExp(ref.source, ref.flags.includes("g") ? ref.flags : `${ref.flags}g`);
+};
+/** `redact` — format dispatch: text media → text path; DOCX/PPTX → in-place container edit. */
+var docRedactStep = async (ctx) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (mime.startsWith("text/")) return redactStep(ctx);
+	if (mime === MIME.DOCX || mime === MIME.PPTX) {
+		const raw = ctx.step.args.match;
+		const patterns = Array.isArray(raw) ? raw : [raw];
+		const replacement = argOf(ctx.step, "replace") ?? "█";
+		return mutateOoxmlText(ctx, "redact", (xml, kind) => {
+			let out = xml;
+			for (const p of patterns) out = replaceInOoxml(out, kind === "docx" ? "w:p" : "a:p", kind === "docx" ? "w:t" : "a:t", toGlobalRegex(p), replacement).xml;
+			return out;
+		});
+	}
+	fail$4("redact", `redaction for ${mime} is not supported in this build (text, DOCX, and PPTX are). For PDF, extract the text first: extract text | redact …`);
+	throw new Error("unreachable");
+};
+var BLOCKED_CONTROL = (code) => code >= 0 && code <= 8 || code === 11 || code === 12 || code >= 14 && code <= 31 || code === 127;
+var stripControlChars = (text) => {
+	let out = "";
+	for (const ch of text) {
+		if (BLOCKED_CONTROL(ch.charCodeAt(0))) continue;
+		out += ch;
+	}
+	return out;
+};
+var sanitizeTextNodes = (xml, textTag) => xml.replace(new RegExp(`<${textTag}(?:\\s[^>]*)?>([^<]*)</${textTag}>`, "g"), (full, content) => {
+	const cleaned = stripControlChars(unescapeXml(content));
+	if (cleaned === unescapeXml(content)) return full;
+	return full.replace(content, escapeXml$1(cleaned));
+});
+/** `sanitize` — strip blocked control characters from text nodes / text media. */
+var docSanitizeStep = async (ctx) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (mime.startsWith("text/")) {
+		const cleaned = stripControlChars(new TextDecoder().decode(ctx.payload.bytes));
+		return {
+			kind: "media",
+			payload: {
+				...ctx.payload,
+				bytes: new TextEncoder().encode(cleaned)
+			}
+		};
+	}
+	if (mime === MIME.DOCX || mime === MIME.PPTX) return mutateOoxmlText(ctx, "sanitize", (xml, kind) => sanitizeTextNodes(xml, kind === "docx" ? "w:t" : "a:t"));
+	fail$4("sanitize", `sanitize for ${mime} is not supported in this build (text, DOCX, PPTX are)`);
+	throw new Error("unreachable");
+};
+var normalizeText = (text) => text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/[\t ]+$/gm, "");
+/** `normalize` — CRLF→LF + trailing-whitespace removal in text nodes / text media. */
+var docNormalizeStep = async (ctx) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (mime.startsWith("text/")) {
+		const text = new TextDecoder().decode(ctx.payload.bytes);
+		return {
+			kind: "media",
+			payload: {
+				...ctx.payload,
+				bytes: new TextEncoder().encode(normalizeText(text))
+			}
+		};
+	}
+	if (mime === MIME.DOCX || mime === MIME.PPTX) return mutateOoxmlText(ctx, "normalize", (xml, kind) => {
+		const tag = kind === "docx" ? "w:t" : "a:t";
+		return xml.replace(new RegExp(`<${tag}(?:\\s[^>]*)?>([^<]*)</${tag}>`, "g"), (full, content) => {
+			const normalized = normalizeText(unescapeXml(content));
+			if (normalized === unescapeXml(content)) return full;
+			return full.replace(content, escapeXml$1(normalized));
+		});
+	});
+	fail$4("normalize", `normalize for ${mime} is not supported in this build (text, DOCX, PPTX are)`);
+	throw new Error("unreachable");
+};
+/** `update_text` — anchor replacement; DOCX/PPTX in-place, TARGET_NOT_FOUND when absent. */
+var docUpdateTextStep = async (ctx) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (mime.startsWith("text/")) return updateTextStep(ctx);
+	if (mime === MIME.DOCX || mime === MIME.PPTX) {
+		const anchor = argOf(ctx.step, "anchor");
+		const replace = argOf(ctx.step, "replace") ?? "";
+		let found = 0;
+		const result = await mutateOoxmlText(ctx, "update_text", (xml, kind) => {
+			if (found > 0) return xml;
+			const escaped = anchor.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+			const { xml: next, matchCount } = replaceInOoxml(xml, kind === "docx" ? "w:p" : "a:p", kind === "docx" ? "w:t" : "a:t", new RegExp(escaped), replace);
+			found += matchCount;
+			return next;
+		});
+		if (found === 0) fail$4("update_text", `anchor text not found: "${anchor.slice(0, 80)}"`);
+		return result;
+	}
+	fail$4("update_text", `text update for ${mime} is not supported (text, DOCX, PPTX are; PDF text is not reliably editable)`);
+	throw new Error("unreachable");
+};
+var ASSET_PATTERNS = {
+	image: /\.(png|jpe?g|gif|bmp|tiff?|emf|wmf|svg|webp)$/i,
+	font: /\.(ttf|otf|woff2?|odttf)$/i,
+	attachment: /\.(bin|ole|docx?|xlsx?|pptx?|pdf|txt|csv)$/i
+};
+var EXT_MIME = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	bmp: "image/bmp",
+	tif: "image/tiff",
+	tiff: "image/tiff",
+	svg: "image/svg+xml",
+	webp: "image/webp",
+	emf: "image/emf",
+	wmf: "image/wmf",
+	ttf: "font/ttf",
+	otf: "font/otf",
+	woff: "font/woff",
+	woff2: "font/woff2"
+};
+/**
+* `extract.assets` — enumerate embedded assets. OOXML/ODF archives are walked natively
+* (cross-env); PDF inputs use the pdfImages engine.
+*/
+var extractAssetsStep = async (ctx) => {
+	const verb = "extract assets";
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	const requested = ctx.step.args.types ?? ["all"];
+	const wantAll = requested.includes("all");
+	const want = (kind) => wantAll || requested.includes(kind);
+	if (mime === MIME.PDF) {
+		if (!want("image")) fail$4(verb, "PDF asset extraction currently supports images (types=image or all)");
+		if (!ctx.engines.hasConvert(mime, "images")) fail$4(verb, "PDF asset extraction requires an engine that converts application/pdf to \"images\", and none is configured. Do not retry this verb on PDFs in this deployment.");
+		const format = argOf(ctx.step, "format");
+		const result = await ctx.engines.convert({
+			bytes: ctx.payload.bytes,
+			mimeType: mime,
+			filename: ctx.payload.filename,
+			to: "images",
+			options: format ? { format } : void 0,
+			signal: ctx.signal
+		});
+		if (result.outputs.length === 0) fail$4(verb, "no embedded images were found in the PDF");
+		const wantedMime = format ? EXT_MIME[format] ?? `image/${format}` : void 0;
+		const payloads = [];
+		for (const [i, img] of result.outputs.entries()) {
+			let bytes = img.bytes;
+			let mimeType = img.mimeType;
+			if (wantedMime && mimeType.toLowerCase() !== wantedMime) {
+				const reencoded = await ctx.engines.mutate({
+					bytes,
+					mimeType,
+					format: { to: format },
+					signal: ctx.signal
+				});
+				bytes = reencoded.bytes;
+				mimeType = reencoded.mimeType;
+			}
+			payloads.push({
+				bytes,
+				mimeType,
+				filename: `asset-${i + 1}.${mimeType.split("/")[1]?.replace("jpeg", "jpg") ?? "bin"}`
+			});
+		}
+		return {
+			kind: "media-list",
+			payloads
+		};
+	}
+	if (![
+		MIME.DOCX,
+		MIME.XLSX,
+		MIME.PPTX,
+		MIME.ODT,
+		MIME.ODS,
+		MIME.ODP
+	].includes(mime)) fail$4(verb, `asset extraction for ${mime} is not supported (OOXML/ODF archives and PDF are)`);
+	const zip = await (await jszip$2()).loadAsync(ctx.payload.bytes);
+	const payloads = [];
+	for (const [name, entry] of Object.entries(zip.files)) {
+		if (entry.dir) continue;
+		const basename = name.split("/").pop() ?? name;
+		const matchKind = Object.entries(ASSET_PATTERNS).find(([, re]) => re.test(basename))?.[0];
+		if (!matchKind || !want(matchKind)) continue;
+		if (!/(^|\/)(media|embeddings|fonts|Pictures|ObjectReplacements)\//i.test(name)) continue;
+		const ext = basename.split(".").pop()?.toLowerCase() ?? "bin";
+		payloads.push({
+			bytes: await entry.async("uint8array"),
+			mimeType: EXT_MIME[ext] ?? "application/octet-stream",
+			filename: basename
+		});
+	}
+	if (payloads.length === 0) fail$4(verb, "no embedded assets matched the requested types");
+	return {
+		kind: "media-list",
+		payloads
+	};
+};
+/** `convert` — dispatch through the engine registry (direct edge or computed path). */
+var convertStep = async (ctx) => {
+	const verb = "convert";
+	const to = argOf(ctx.step, "to");
+	const supported = ctx.engines.convertTargets(ctx.payload.mimeType);
+	if (!supported.includes(to)) fail$4(verb, `no configured engine (or computed path) can produce "${to}" from ${ctx.payload.mimeType}; reachable targets: ${supported.join(", ") || "(none)"}`);
+	const output = (await ctx.engines.convert({
+		bytes: ctx.payload.bytes,
+		mimeType: ctx.payload.mimeType,
+		filename: ctx.payload.filename,
+		to,
+		signal: ctx.signal
+	})).outputs[0];
+	if (!output) fail$4(verb, "the conversion produced no output");
+	const dot = ctx.payload.filename.lastIndexOf(".");
+	const base = dot > 0 ? ctx.payload.filename.slice(0, dot) : ctx.payload.filename;
+	return {
+		kind: "media",
+		payload: {
+			bytes: output.bytes,
+			mimeType: output.mimeType,
+			filename: `${base}.${to}`
+		}
+	};
+};
+/** The doc step registry fragment (overrides the Phase 0 text-only redact/update_text). */
+var DOC_STEPS = [
+	["redact", docRedactStep],
+	["sanitize", docSanitizeStep],
+	["normalize", docNormalizeStep],
+	["update_text", docUpdateTextStep],
+	["extract.assets", extractAssetsStep],
+	["convert", convertStep]
+];
+//#endregion
+//#region src/batteries/media/steps/sheet.ts
+/**
+* `sheet.*` step implementations: ExcelJS workbook mutations on in-memory bytes.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. Ported from the source server's
+* sheet adapters (its green e2e suite informs the spec coverage). All ten mutations operate on
+* xlsx natively via ExcelJS (optional peer, lazily imported); ODS and legacy-xls inputs are
+* normalized to xlsx first through the configured `sheetNormalize` engine, degrading to a
+* readable failure when none is configured. Output is always xlsx.
+*/
+var excelPromise;
+var excel = () => {
+	excelPromise ??= import("exceljs").then((m) => "default" in m ? m.default : m);
+	return excelPromise;
+};
+var fail$3 = (verb, message) => {
+	throw new E_MEDIA_STEP_FAILED([verb, message]);
+};
+/** Acquire xlsx bytes for the step, converting ODS/xls to xlsx via the engine registry. */
+var acquireXlsx = async (ctx, verb) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (mime === MIME.XLSX) return ctx.payload.bytes;
+	const mutationBlock = unsupportedForMutationReason(mime);
+	if (mime === MIME.ODS || mime === MIME.XLS) {
+		if (!ctx.engines.hasConvert(mime, "xlsx")) fail$3(verb, `this input is ${mime} — an engine that converts it to xlsx is required first, and none is configured. Do not retry this verb on this media in this deployment.`);
+		const output = (await ctx.engines.convert({
+			bytes: ctx.payload.bytes,
+			mimeType: mime,
+			filename: ctx.payload.filename,
+			to: "xlsx",
+			signal: ctx.signal
+		})).outputs[0];
+		if (!output) fail$3(verb, "normalizing the workbook to xlsx produced no output");
+		return output.bytes;
+	}
+	if (mutationBlock) fail$3(verb, mutationBlock);
+	fail$3(verb, `sheet operations expect a spreadsheet; the media is ${mime}`);
+	throw new Error("unreachable");
+};
+/** The shared open → mutate → write-back lifecycle every sheet verb uses. */
+var withWorkbook = async (ctx, verb, mutate) => {
+	const xlsxBytes = await acquireXlsx(ctx, verb);
+	const wb = new (await (excel())).Workbook();
+	try {
+		await wb.xlsx.load(xlsxBytes.buffer.slice(xlsxBytes.byteOffset, xlsxBytes.byteOffset + xlsxBytes.byteLength));
+	} catch (err) {
+		fail$3(verb, `could not open the spreadsheet: ${isError(err) ? err.message : String(err)}`);
+	}
+	await mutate(wb);
+	return {
+		kind: "media",
+		payload: {
+			bytes: new Uint8Array(await wb.xlsx.writeBuffer()),
+			mimeType: MIME.XLSX,
+			filename: replaceExtension(ctx.payload.filename, "xlsx")
+		}
+	};
+};
+/** Resolve the target worksheet from the frozen `sheet=` rule (bare number=index, string=name). */
+var resolveSheet = (verb, wb, sheetArg) => {
+	if (sheetArg === void 0) {
+		const first = wb.worksheets[0];
+		if (!first) fail$3(verb, "the workbook has no worksheets");
+		return first;
+	}
+	if (typeof sheetArg === "number") {
+		const byIndex = wb.worksheets[sheetArg - 1];
+		if (byIndex) return byIndex;
+		if (wb.getWorksheet(String(sheetArg))) fail$3(verb, `no sheet at index ${sheetArg}, but a sheet NAMED "${sheetArg}" exists — quote it: sheet="${sheetArg}"`);
+		fail$3(verb, `sheet index ${sheetArg} is out of range (1-based; the workbook has ${wb.worksheets.length})`);
+	}
+	const ws = wb.getWorksheet(sheetArg);
+	if (!ws) fail$3(verb, `no sheet named "${sheetArg}". Sheets: ${wb.worksheets.map((w) => `"${w.name}"`).join(", ")}`);
+	return ws;
+};
+var columnLetterToNumber = (col) => {
+	let n = 0;
+	for (const ch of col.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64);
+	return n;
+};
+var asCellValue = (verb, value) => {
+	if (value === null) return null;
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	fail$3(verb, `cell values must be string, number, boolean, or null; got ${typeof value}`);
+	throw new Error("unreachable");
+};
+/** `sheet.add_rows` — insert rows before/after an index, or append. */
+var sheetAddRowsStep = async (ctx) => {
+	const verb = "sheet add_rows";
+	const rows = ctx.step.args.rows;
+	if (!Array.isArray(rows) || rows.length === 0 || !rows.every(Array.isArray)) fail$3(verb, `rows must be a non-empty JSON array of arrays, e.g. rows='[["a",1]]'`);
+	const before = argOf(ctx.step, "before");
+	const after = argOf(ctx.step, "after");
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
+		const insertAt = before !== void 0 ? before : after !== void 0 ? after + 1 : ws.rowCount + 1;
+		const cellRows = rows.map((r) => r.map((v) => asCellValue(verb, v)));
+		ws.spliceRows(insertAt, 0, ...cellRows);
+		return { added: cellRows.length };
+	});
+};
+/** `sheet.add_columns` — insert columns with headers or full descriptors. */
+var sheetAddColumnsStep = async (ctx) => {
+	const verb = "sheet add_columns";
+	const headers = ctx.step.args.headers;
+	const columns = ctx.step.args.columns ?? headers?.map((header) => ({ header }));
+	if (!Array.isArray(columns) || columns.length === 0) fail$3(verb, `provide headers=a,b or columns='[{"header":"X","values":[1]}]'`);
+	const before = argOf(ctx.step, "before");
+	const after = argOf(ctx.step, "after");
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
+		const insertAt = before !== void 0 ? before : after !== void 0 ? after + 1 : ws.columnCount + 1;
+		for (const [i, col] of columns.entries()) {
+			if (typeof col?.header !== "string") fail$3(verb, "every column needs a string header");
+			ws.spliceColumns(insertAt + i, 0, [col.header, ...(col.values ?? []).map((v) => asCellValue(verb, v))]);
+		}
+		return { added: columns.length };
+	});
+};
+/** `sheet.update_cells` — set cells by A1 address or row/col. Leading `=` writes a formula. */
+var sheetUpdateCellsStep = async (ctx) => {
+	const verb = "sheet update_cells";
+	const updates = ctx.step.args.updates;
+	if (!Array.isArray(updates) || updates.length === 0) fail$3(verb, `updates must be a non-empty JSON array, e.g. updates='[{"address":"B2","value":3}]'`);
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
+		let modified = 0;
+		for (const raw of updates) {
+			const address = raw.address;
+			const row = raw.row;
+			const col = raw.col;
+			let cell;
+			if (address) cell = ws.getCell(address);
+			else if (row !== void 0 && col !== void 0) cell = typeof col === "string" ? ws.getCell(row, columnLetterToNumber(col)) : ws.getCell(row, col);
+			else {
+				fail$3(verb, "each update needs address, or both row and col");
+				continue;
+			}
+			const value = raw.value;
+			if (typeof value === "string" && value.startsWith("=")) cell.value = { formula: value.slice(1) };
+			else cell.value = asCellValue(verb, value);
+			modified += 1;
+		}
+		return { modified };
+	});
+};
+/** `sheet.delete_rows` — delete 1-based rows (bottom-up so indices stay valid). */
+var sheetDeleteRowsStep = async (ctx) => {
+	const verb = "sheet delete_rows";
+	const rows = ctx.step.args.rows;
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
+		for (const r of [...rows].sort((a, b) => b - a)) ws.spliceRows(r, 1);
+		return { removed: rows.length };
+	});
+};
+/** `sheet.delete_columns` — delete 1-based columns. */
+var sheetDeleteColumnsStep = async (ctx) => {
+	const verb = "sheet delete_columns";
+	const columns = ctx.step.args.columns;
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
+		for (const c of [...columns].sort((a, b) => b - a)) ws.spliceColumns(c, 1);
+		return { removed: columns.length };
+	});
+};
+/** `sheet.rename_sheet` — rename by NAME (the server contract; index targeting is rejected). */
+var sheetRenameSheetStep = async (ctx) => {
+	const verb = "sheet rename_sheet";
+	const sheet = argOf(ctx.step, "sheet");
+	const to = argOf(ctx.step, "to");
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = wb.getWorksheet(sheet);
+		if (!ws) fail$3(verb, `rename targets a sheet NAME; no sheet named "${sheet}". Sheets: ${wb.worksheets.map((w) => `"${w.name}"`).join(", ")}`);
+		ws.name = to;
+		return { modified: 1 };
+	});
+};
+/** `sheet.add_sheet` — add a worksheet, optionally at a 1-based position. */
+var sheetAddSheetStep = async (ctx) => {
+	const verb = "sheet add_sheet";
+	const name = argOf(ctx.step, "name");
+	const at = argOf(ctx.step, "at");
+	return withWorkbook(ctx, verb, (wb) => {
+		if (wb.getWorksheet(name)) fail$3(verb, `a sheet named "${name}" already exists`);
+		const ws = wb.addWorksheet(name);
+		if (at !== void 0) {
+			const all = wb.worksheets;
+			const wsIdx = all.indexOf(ws);
+			if (wsIdx !== at - 1) all.forEach((w, i) => {
+				w.orderNo = w === ws ? at : i + 1 >= at && i < wsIdx ? i + 2 : i + 1;
+			});
+		}
+		return { added: 1 };
+	});
+};
+/** `sheet.remove_sheet` — remove by NAME (the server contract). */
+var sheetRemoveSheetStep = async (ctx) => {
+	const verb = "sheet remove_sheet";
+	const sheet = argOf(ctx.step, "sheet");
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = wb.getWorksheet(sheet);
+		if (!ws) fail$3(verb, `remove targets a sheet NAME; no sheet named "${sheet}". Sheets: ${wb.worksheets.map((w) => `"${w.name}"`).join(", ")}`);
+		wb.removeWorksheet(ws.id);
+		return { removed: 1 };
+	});
+};
+/** `sheet.reorder_sheets` — every sheet exactly once, by name or 1-based index. */
+var sheetReorderSheetsStep = async (ctx) => {
+	const verb = "sheet reorder_sheets";
+	const order = ctx.step.args.order;
+	if (!Array.isArray(order) || order.length === 0) fail$3(verb, `order must be a JSON array of names/indices, e.g. order='["Summary",2]'`);
+	return withWorkbook(ctx, verb, (wb) => {
+		const refs = order;
+		if (refs.length !== wb.worksheets.length) fail$3(verb, `order must include every worksheet exactly once (the workbook has ${wb.worksheets.length})`);
+		const reordered = [];
+		const seen = /* @__PURE__ */ new Set();
+		for (const ref of refs) {
+			const ws = typeof ref === "number" ? wb.worksheets[ref - 1] : wb.getWorksheet(ref);
+			if (!ws) fail$3(verb, `sheet not found: ${String(ref)}`);
+			if (seen.has(ws.id)) fail$3(verb, `duplicate sheet reference: ${String(ref)}`);
+			seen.add(ws.id);
+			reordered.push(ws);
+		}
+		reordered.forEach((ws, i) => {
+			ws.orderNo = i + 1;
+		});
+		return { modified: reordered.length };
+	});
+};
+/** `sheet.transform_table` — rename/select/drop columns by header name. */
+var sheetTransformTableStep = async (ctx) => {
+	const verb = "sheet transform_table";
+	const headerRow = argOf(ctx.step, "header_row") ?? 1;
+	const rename = ctx.step.args.rename;
+	const select = ctx.step.args.select;
+	const drop = ctx.step.args.drop;
+	return withWorkbook(ctx, verb, (wb) => {
+		const ws = resolveSheet(verb, wb, argOf(ctx.step, "sheet"));
+		let modified = 0;
+		const headerMap = /* @__PURE__ */ new Map();
+		ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {
+			if (typeof cell.value === "string") headerMap.set(cell.value, colNumber);
+		});
+		if (rename) for (const { from, to } of rename) {
+			const colNum = headerMap.get(from);
+			if (colNum !== void 0) {
+				ws.getRow(headerRow).getCell(colNum).value = to;
+				headerMap.delete(from);
+				headerMap.set(to, colNum);
+				modified += 1;
+			}
+		}
+		if (drop) {
+			const cols = drop.map((name) => headerMap.get(name)).filter((n) => n !== void 0).sort((a, b) => b - a);
+			for (const col of cols) {
+				ws.spliceColumns(col, 1);
+				modified += 1;
+			}
+		}
+		if (select) {
+			const keep = new Set(select);
+			const cols = [];
+			ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {
+				if (typeof cell.value === "string" && !keep.has(cell.value)) cols.push(colNumber);
+			});
+			cols.sort((a, b) => b - a);
+			for (const col of cols) {
+				ws.spliceColumns(col, 1);
+				modified += 1;
+			}
+		}
+		return { modified };
+	});
+};
+/** The sheet step registry fragment, keyed by canonical verb id. */
+var SHEET_STEPS = [
+	["sheet.add_rows", sheetAddRowsStep],
+	["sheet.add_columns", sheetAddColumnsStep],
+	["sheet.update_cells", sheetUpdateCellsStep],
+	["sheet.delete_rows", sheetDeleteRowsStep],
+	["sheet.delete_columns", sheetDeleteColumnsStep],
+	["sheet.rename_sheet", sheetRenameSheetStep],
+	["sheet.add_sheet", sheetAddSheetStep],
+	["sheet.remove_sheet", sheetRemoveSheetStep],
+	["sheet.reorder_sheets", sheetReorderSheetsStep],
+	["sheet.transform_table", sheetTransformTableStep]
+];
+//#endregion
+//#region src/batteries/media/steps/slides.ts
+/**
+* `slides.*` step implementations: native PPTX container mutation via JSZip + targeted XML
+* edits, on in-memory bytes.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. Ported from the source server's
+* slides adapters (regex-over-zip XML surgery — no XML parser dependency). PPTX is mutated
+* natively; ODP inputs are normalized to PPTX through the configured `convert` engine first,
+* degrading to a readable failure when none is configured. All implementations are
+* cross-environment (jszip operates on Uint8Array).
+*/
+var zipPromise$1;
+var jszip$1 = () => {
+	zipPromise$1 ??= import("jszip").then((m) => "default" in m ? m.default : m);
+	return zipPromise$1;
+};
+var SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide";
+var fail$2 = (verb, message) => {
+	throw new E_MEDIA_STEP_FAILED([verb, message]);
+};
+var escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+var escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Pure posix-style path resolution for zip entries (no node:path). */
+var resolveZipPath = (basePart, relTarget) => {
+	const parts = [...basePart.split("/").slice(0, -1), ...relTarget.split("/")];
+	const out = [];
+	for (const part of parts) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") out.pop();
+		else out.push(part);
+	}
+	return out.join("/");
+};
+var readZipText = async (verb, zip, path) => {
+	const file = zip.file(path);
+	if (!file) fail$2(verb, `the presentation is missing an expected part: ${path}`);
+	return file.async("text");
+};
+var parseRelationshipTarget = (relsXml, relId) => {
+	const re = new RegExp(`<Relationship\\b[^>]*Id="${escapeRegex(relId)}"[^>]*Target="([^"]+)"[^>]*>`, "i");
+	return relsXml.match(re)?.[1] ?? null;
+};
+var parsePresentation = async (verb, zip) => {
+	const presentationXml = await readZipText(verb, zip, "ppt/presentation.xml");
+	const relsXml = await readZipText(verb, zip, "ppt/_rels/presentation.xml.rels");
+	const sldIdListMatch = presentationXml.match(/<p:sldIdLst>([\s\S]*?)<\/p:sldIdLst>/);
+	if (!sldIdListMatch) fail$2(verb, "the presentation has no slide list (corrupt PPTX?)");
+	const sldIdTags = sldIdListMatch[1].match(/<p:sldId\b[^>]*\/>/g) ?? [];
+	const entries = [];
+	for (const tag of sldIdTags) {
+		const rid = tag.match(/r:id="([^"]+)"/)?.[1];
+		const idText = tag.match(/\bid="(\d+)"/)?.[1];
+		if (!rid || !idText) continue;
+		const target = parseRelationshipTarget(relsXml, rid);
+		if (!target) continue;
+		const slidePath = resolveZipPath("ppt/presentation.xml", target);
+		let title;
+		const slideFile = zip.file(slidePath);
+		if (slideFile) title = (await slideFile.async("text")).match(/<p:cSld\b[^>]*\bname="([^"]*)"/)?.[1];
+		entries.push({
+			rid,
+			slideId: Number(idText),
+			sldIdTag: tag,
+			target,
+			title
+		});
+	}
+	return {
+		presentationXml,
+		relsXml,
+		entries
+	};
+};
+var replaceSlideIdList = (presentationXml, tags) => presentationXml.replace(/<p:sldIdLst>[\s\S]*?<\/p:sldIdLst>/, `<p:sldIdLst>${tags.join("")}</p:sldIdLst>`);
+/** Resolve a slide by the frozen `slide=` rule: digits = 1-based index, otherwise title. */
+var resolveSlide = (verb, entries, slideArg) => {
+	if (slideArg === void 0) {
+		const first = entries[0];
+		if (!first) fail$2(verb, "the presentation has no slides");
+		return first;
+	}
+	if (typeof slideArg === "number") {
+		const found = entries[slideArg - 1];
+		if (!found) fail$2(verb, `slide index ${slideArg} is out of range (1-based; ${entries.length} slides)`);
+		return found;
+	}
+	const byTitle = entries.find((e) => e.title === slideArg);
+	if (!byTitle) fail$2(verb, `no slide titled "${slideArg}"`);
+	return byTitle;
+};
+var getMaxRidNumber = (relsXml) => {
+	let max = 0;
+	for (const match of relsXml.matchAll(/\bId="rId(\d+)"/g)) max = Math.max(max, Number(match[1]));
+	return max;
+};
+var getMaxSlideNumber = (zip) => {
+	let max = 0;
+	for (const name of Object.keys(zip.files)) {
+		const match = name.match(/^ppt\/slides\/slide(\d+)\.xml$/);
+		if (match) max = Math.max(max, Number(match[1]));
+	}
+	return max;
+};
+var getMaxSlideId = (entries) => entries.reduce((max, e) => Math.max(max, e.slideId), 255);
+var ensureSlideContentType = (contentTypesXml, slideNumber) => {
+	const partName = `/ppt/slides/slide${slideNumber}.xml`;
+	if (contentTypesXml.includes(`PartName="${partName}"`)) return contentTypesXml;
+	const override = `<Override PartName="${partName}" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>`;
+	return contentTypesXml.replace("</Types>", `${override}</Types>`);
+};
+var setSlideTitle = (slideXml, title) => {
+	if (/<p:cSld\b[^>]*\bname="[^"]*"/.test(slideXml)) return slideXml.replace(/(<p:cSld\b[^>]*\bname=")[^"]*(")/, `$1${escapeXml(title)}$2`);
+	return slideXml;
+};
+/** Acquire pptx bytes, converting ODP to PPTX via the engine registry. */
+var acquirePptx = async (ctx, verb) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	if (mime === MIME.PPTX) return ctx.payload.bytes;
+	if (mime === MIME.ODP) {
+		if (!ctx.engines.hasConvert(mime, "pptx")) fail$2(verb, "this input is ODP — an engine that converts it to PPTX is required first, and none is configured. Do not retry this verb on this media in this deployment.");
+		const output = (await ctx.engines.convert({
+			bytes: ctx.payload.bytes,
+			mimeType: mime,
+			filename: ctx.payload.filename,
+			to: "pptx",
+			signal: ctx.signal
+		})).outputs[0];
+		if (!output) fail$2(verb, "normalizing the presentation to PPTX produced no output");
+		return output.bytes;
+	}
+	const reason = unsupportedForMutationReason(mime);
+	if (reason) fail$2(verb, reason);
+	fail$2(verb, `slides operations expect a presentation; the media is ${mime}`);
+	throw new Error("unreachable");
+};
+var withPresentation = async (ctx, verb, mutate) => {
+	const bytes = await acquirePptx(ctx, verb);
+	const JSZip = await jszip$1();
+	let zip;
+	try {
+		zip = await JSZip.loadAsync(bytes);
+	} catch (err) {
+		fail$2(verb, `could not open the presentation: ${isError(err) ? err.message : String(err)}`);
+		throw err;
+	}
+	const parsed = await parsePresentation(verb, zip);
+	await mutate(zip, parsed);
+	return {
+		kind: "media",
+		payload: {
+			bytes: await zip.generateAsync({
+				type: "uint8array",
+				compression: "DEFLATE"
+			}),
+			mimeType: MIME.PPTX,
+			filename: replaceExtension(ctx.payload.filename, "pptx")
+		}
+	};
+};
+/** `slides.add` — clone the last slide as a template, optionally retitle/position it. */
+var slidesAddStep = async (ctx) => {
+	const verb = "slides add";
+	const at = argOf(ctx.step, "at");
+	const title = argOf(ctx.step, "title");
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		if (parsed.entries.length === 0) fail$2(verb, "the presentation has no slides to clone from");
+		const template = parsed.entries[parsed.entries.length - 1];
+		const templatePath = resolveZipPath("ppt/presentation.xml", template.target);
+		const templateXml = await readZipText(verb, zip, templatePath);
+		const newSlideNumber = getMaxSlideNumber(zip) + 1;
+		const newSlidePath = `ppt/slides/slide${newSlideNumber}.xml`;
+		zip.file(newSlidePath, title ? setSlideTitle(templateXml, title) : templateXml);
+		const templateNum = templatePath.match(/slide(\d+)\.xml$/)?.[1];
+		const templateRels = templateNum ? zip.file(`ppt/slides/_rels/slide${templateNum}.xml.rels`) : null;
+		if (templateRels) {
+			const relsXml = await templateRels.async("text");
+			zip.file(`ppt/slides/_rels/slide${newSlideNumber}.xml.rels`, relsXml.replace(/<Relationship\b[^>]*Type="[^"]*notesSlide"[^>]*\/>/g, ""));
+		}
+		const newRid = `rId${getMaxRidNumber(parsed.relsXml) + 1}`;
+		const newSldTag = `<p:sldId id="${getMaxSlideId(parsed.entries) + 1}" r:id="${newRid}"/>`;
+		const relNode = `<Relationship Id="${newRid}" Type="${SLIDE_REL_TYPE}" Target="slides/slide${newSlideNumber}.xml"/>`;
+		zip.file("ppt/_rels/presentation.xml.rels", parsed.relsXml.replace("</Relationships>", `${relNode}</Relationships>`));
+		const insertAt = at !== void 0 ? Math.min(Math.max(1, at), parsed.entries.length + 1) : parsed.entries.length + 1;
+		const tags = parsed.entries.map((e) => e.sldIdTag);
+		tags.splice(insertAt - 1, 0, newSldTag);
+		zip.file("ppt/presentation.xml", replaceSlideIdList(parsed.presentationXml, tags));
+		const contentTypes = await readZipText(verb, zip, "[Content_Types].xml");
+		zip.file("[Content_Types].xml", ensureSlideContentType(contentTypes, newSlideNumber));
+	});
+};
+/** `slides.update_text` — replace text in the first node or a named placeholder shape. */
+var slidesUpdateTextStep = async (ctx) => {
+	const verb = "slides update_text";
+	const text = argOf(ctx.step, "text");
+	const placeholder = argOf(ctx.step, "placeholder");
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		const slidePath = resolveZipPath("ppt/presentation.xml", resolveSlide(verb, parsed.entries, argOf(ctx.step, "slide")).target);
+		const slideXml = await readZipText(verb, zip, slidePath);
+		let updated = slideXml;
+		let changed = false;
+		if (placeholder) {
+			let placeholderFound = false;
+			updated = slideXml.replace(/<p:sp\b[\s\S]*?<\/p:sp>/g, (shapeXml) => {
+				if (!new RegExp(`<p:cNvPr\\b[^>]*\\bname="${escapeRegex(placeholder)}"[^>]*>`, "i").test(shapeXml)) return shapeXml;
+				placeholderFound = true;
+				return shapeXml.replace(/<a:t>[\s\S]*?<\/a:t>/, () => {
+					changed = true;
+					return `<a:t>${escapeXml(text)}</a:t>`;
+				});
+			});
+			if (!placeholderFound) fail$2(verb, `no placeholder named "${placeholder}" on the selected slide`);
+		} else updated = slideXml.replace(/<a:t>[\s\S]*?<\/a:t>/, () => {
+			changed = true;
+			return `<a:t>${escapeXml(text)}</a:t>`;
+		});
+		if (!changed) fail$2(verb, "no text node found on the selected slide");
+		zip.file(slidePath, updated);
+	});
+};
+/** `slides.update_table` — set table cell text by 1-based row/col. */
+var slidesUpdateTableStep = async (ctx) => {
+	const verb = "slides update_table";
+	const updates = ctx.step.args.updates;
+	if (!Array.isArray(updates) || updates.length === 0) fail$2(verb, `updates must be a JSON array: updates='[{"row":1,"col":2,"value":"x"}]'`);
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		const slidePath = resolveZipPath("ppt/presentation.xml", resolveSlide(verb, parsed.entries, argOf(ctx.step, "slide")).target);
+		let slideXml = await readZipText(verb, zip, slidePath);
+		const tableMatch = slideXml.match(/<a:tbl>[\s\S]*?<\/a:tbl>/);
+		if (!tableMatch) fail$2(verb, "no table found on the selected slide");
+		let tableXml = tableMatch[0];
+		const rowMatches = tableXml.match(/<a:tr\b[\s\S]*?<\/a:tr>/g) ?? [];
+		for (const raw of updates) {
+			const row = Number(raw.row);
+			const col = Number(raw.col);
+			const value = String(raw.value ?? "");
+			const rowIndex = row - 1;
+			const colIndex = col - 1;
+			if (rowIndex < 0 || colIndex < 0 || rowIndex >= rowMatches.length) fail$2(verb, `table cell out of range: r${row}c${col} (1-based)`);
+			const rowXml = rowMatches[rowIndex];
+			const cellMatches = rowXml.match(/<a:tc\b[\s\S]*?<\/a:tc>/g) ?? [];
+			if (colIndex >= cellMatches.length) fail$2(verb, `table cell out of range: r${row}c${col} (1-based)`);
+			const cellXml = cellMatches[colIndex];
+			if (!/<a:t>/.test(cellXml)) fail$2(verb, `cell r${row}c${col} has no text node`);
+			cellMatches[colIndex] = cellXml.replace(/<a:t>[\s\S]*?<\/a:t>/, `<a:t>${escapeXml(value)}</a:t>`);
+			rowMatches[rowIndex] = rowXml.replace(/<a:tc\b[\s\S]*?<\/a:tc>/g, () => cellMatches.shift());
+		}
+		tableXml = tableXml.replace(/<a:tr\b[\s\S]*?<\/a:tr>/g, () => rowMatches.shift());
+		slideXml = slideXml.replace(/<a:tbl>[\s\S]*?<\/a:tbl>/, tableXml);
+		zip.file(slidePath, slideXml);
+	});
+};
+/** `slides.update_image` — replace an image part's bytes with another media (`with=@id`). */
+var slidesUpdateImageStep = async (ctx) => {
+	const verb = "slides update_image";
+	const ref = ctx.step.args.with;
+	const placeholder = argOf(ctx.step, "placeholder");
+	if (ref.kind !== "id") fail$2(verb, "builder refs are not supported here; use an @id ref");
+	const replacement = await ctx.resolveRef(ref.id);
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		const slidePath = resolveZipPath("ppt/presentation.xml", resolveSlide(verb, parsed.entries, argOf(ctx.step, "slide")).target);
+		const slideXml = await readZipText(verb, zip, slidePath);
+		const slideNum = slidePath.match(/slide(\d+)\.xml$/)?.[1];
+		if (!slideNum) fail$2(verb, "unable to resolve the slide number (corrupt PPTX?)");
+		const relsPath = `ppt/slides/_rels/slide${slideNum}.xml.rels`;
+		const relsXml = await readZipText(verb, zip, relsPath);
+		let imagePartPath = null;
+		if (placeholder) {
+			for (const picXml of slideXml.match(/<p:pic\b[\s\S]*?<\/p:pic>/g) ?? []) {
+				if (!new RegExp(`<p:cNvPr\\b[^>]*\\bname="${escapeRegex(placeholder)}"[^>]*>`, "i").test(picXml)) continue;
+				const rid = picXml.match(/<a:blip\b[^>]*\br:embed="([^"]+)"/i)?.[1];
+				if (rid) {
+					const relTarget = parseRelationshipTarget(relsXml, rid);
+					if (relTarget) imagePartPath = resolveZipPath(relsPath, relTarget);
+				}
+				break;
+			}
+			if (!imagePartPath) fail$2(verb, `no image placeholder named "${placeholder}" on the selected slide`);
+		} else {
+			const fallback = relsXml.match(/<Relationship\b[^>]*Type="[^"]*\/image"[^>]*Target="([^"]+)"[^>]*>/i);
+			if (fallback) imagePartPath = resolveZipPath(relsPath, fallback[1]);
+		}
+		if (!imagePartPath) fail$2(verb, "no image relationship found on the selected slide");
+		zip.file(imagePartPath, replacement.bytes);
+	});
+};
+/** `slides.update_chart` — overwrite the chart's cached values in document order. */
+var slidesUpdateChartStep = async (ctx) => {
+	const verb = "slides update_chart";
+	const data = ctx.step.args.data;
+	if (!Array.isArray(data) || data.length === 0) fail$2(verb, `data must be a non-empty JSON array of arrays: data='[["Q1",10]]'`);
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		const slideNum = resolveZipPath("ppt/presentation.xml", resolveSlide(verb, parsed.entries, argOf(ctx.step, "slide")).target).match(/slide(\d+)\.xml$/)?.[1];
+		if (!slideNum) fail$2(verb, "unable to resolve the slide number (corrupt PPTX?)");
+		const relsPath = `ppt/slides/_rels/slide${slideNum}.xml.rels`;
+		const chartRel = (await readZipText(verb, zip, relsPath)).match(/<Relationship\b[^>]*Type="[^"]*\/chart"[^>]*Target="([^"]+)"[^>]*>/i);
+		if (!chartRel) fail$2(verb, "no chart found on the selected slide");
+		const chartPath = resolveZipPath(relsPath, chartRel[1]);
+		let chartXml = await readZipText(verb, zip, chartPath);
+		const values = data.flat().map((v) => String(v));
+		let replaced = 0;
+		chartXml = chartXml.replace(/<c:v>[\s\S]*?<\/c:v>/g, (full) => {
+			if (replaced >= values.length) return full;
+			const next = `<c:v>${escapeXml(values[replaced])}</c:v>`;
+			replaced += 1;
+			return next;
+		});
+		if (replaced === 0) fail$2(verb, "the chart has no cached values to update");
+		zip.file(chartPath, chartXml);
+	});
+};
+/** `slides.delete` — remove slides by 1-based index (cannot remove all). */
+var slidesDeleteStep = async (ctx) => {
+	const verb = "slides delete";
+	const slides = ctx.step.args.slides;
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		const unique = [...new Set(slides)];
+		for (const index of unique) if (!Number.isInteger(index) || index < 1 || index > parsed.entries.length) fail$2(verb, `slide index ${index} is out of range (1-based; ${parsed.entries.length} slides)`);
+		const toDelete = new Set(unique);
+		const kept = parsed.entries.filter((_, idx) => !toDelete.has(idx + 1));
+		if (kept.length === 0) fail$2(verb, "cannot delete every slide in the presentation");
+		zip.file("ppt/presentation.xml", replaceSlideIdList(parsed.presentationXml, kept.map((e) => e.sldIdTag)));
+		let relsXml = parsed.relsXml;
+		parsed.entries.forEach((entry, idx) => {
+			if (!toDelete.has(idx + 1)) return;
+			const targetPath = resolveZipPath("ppt/presentation.xml", entry.target);
+			zip.remove(targetPath);
+			const slideNum = targetPath.match(/slide(\d+)\.xml$/)?.[1];
+			if (slideNum) zip.remove(`ppt/slides/_rels/slide${slideNum}.xml.rels`);
+			relsXml = relsXml.replace(new RegExp(`<Relationship\\b[^>]*Id="${entry.rid}"[^>]*/>`, "g"), "");
+		});
+		zip.file("ppt/_rels/presentation.xml.rels", relsXml);
+	});
+};
+/** `slides.reorder` — every slide exactly once, by 1-based index. */
+var slidesReorderStep = async (ctx) => {
+	const verb = "slides reorder";
+	const order = ctx.step.args.order;
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		if (order.length !== parsed.entries.length) fail$2(verb, `order must list all ${parsed.entries.length} slides exactly once`);
+		const seen = /* @__PURE__ */ new Set();
+		const reordered = [];
+		for (const index of order) {
+			if (!Number.isInteger(index) || index < 1 || index > parsed.entries.length) fail$2(verb, `slide index ${index} is out of range (1-based)`);
+			if (seen.has(index)) fail$2(verb, `duplicate slide index: ${index}`);
+			seen.add(index);
+			reordered.push(parsed.entries[index - 1]);
+		}
+		zip.file("ppt/presentation.xml", replaceSlideIdList(parsed.presentationXml, reordered.map((e) => e.sldIdTag)));
+	});
+};
+/** `slides.duplicate` — copy a slide, optionally inserting at a position. */
+var slidesDuplicateStep = async (ctx) => {
+	const verb = "slides duplicate";
+	const slide = argOf(ctx.step, "slide");
+	const at = argOf(ctx.step, "at");
+	return withPresentation(ctx, verb, async (zip, parsed) => {
+		if (!Number.isInteger(slide) || slide < 1 || slide > parsed.entries.length) fail$2(verb, `slide index ${slide} is out of range (1-based; ${parsed.entries.length} slides)`);
+		const source = parsed.entries[slide - 1];
+		const sourcePath = resolveZipPath("ppt/presentation.xml", source.target);
+		const sourceXml = await readZipText(verb, zip, sourcePath);
+		const newSlideNumber = getMaxSlideNumber(zip) + 1;
+		zip.file(`ppt/slides/slide${newSlideNumber}.xml`, sourceXml);
+		const sourceNum = sourcePath.match(/slide(\d+)\.xml$/)?.[1];
+		if (sourceNum) {
+			const sourceRels = zip.file(`ppt/slides/_rels/slide${sourceNum}.xml.rels`);
+			if (sourceRels) {
+				const relsXml = await sourceRels.async("text");
+				zip.file(`ppt/slides/_rels/slide${newSlideNumber}.xml.rels`, relsXml.replace(/<Relationship\b[^>]*Type="[^"]*notesSlide"[^>]*\/>/g, ""));
+			}
+		}
+		const newRid = `rId${getMaxRidNumber(parsed.relsXml) + 1}`;
+		const newTag = `<p:sldId id="${getMaxSlideId(parsed.entries) + 1}" r:id="${newRid}"/>`;
+		const relNode = `<Relationship Id="${newRid}" Type="${SLIDE_REL_TYPE}" Target="slides/slide${newSlideNumber}.xml"/>`;
+		zip.file("ppt/_rels/presentation.xml.rels", parsed.relsXml.replace("</Relationships>", `${relNode}</Relationships>`));
+		const targetPos = at !== void 0 ? Math.min(Math.max(1, at), parsed.entries.length + 1) : slide + 1;
+		const tags = parsed.entries.map((e) => e.sldIdTag);
+		tags.splice(targetPos - 1, 0, newTag);
+		zip.file("ppt/presentation.xml", replaceSlideIdList(parsed.presentationXml, tags));
+		const contentTypes = await readZipText(verb, zip, "[Content_Types].xml");
+		zip.file("[Content_Types].xml", ensureSlideContentType(contentTypes, newSlideNumber));
+	});
+};
+/** The slides step registry fragment, keyed by canonical verb id. */
+var SLIDES_STEPS = [
+	["slides.add", slidesAddStep],
+	["slides.update_text", slidesUpdateTextStep],
+	["slides.update_table", slidesUpdateTableStep],
+	["slides.update_image", slidesUpdateImageStep],
+	["slides.update_chart", slidesUpdateChartStep],
+	["slides.delete", slidesDeleteStep],
+	["slides.reorder", slidesReorderStep],
+	["slides.duplicate", slidesDuplicateStep]
+];
+//#endregion
+//#region src/batteries/media/steps/ingest.ts
+/**
+* Ingest-depth step extensions: the unified `extract.text` format dispatch (PDF text layer,
+* DOCX via mammoth, XLSX via ExcelJS, ODT/ODS via ODF XML, PPTX via slide XML, images via the
+* OCR engine) and format-aware `extract.metadata`.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. Ported from the source server's
+* four extractors, collapsed into one verb that routes on the resolved media's format family
+* (the single biggest order-out-of-chaos win — the model says `extract text` and doesn't care
+* what the container is). OCR runs through the configured `ocr` engine when the input is an
+* image, or when a PDF has no text layer with `ocr=auto`, or always with `ocr=force`.
+*/
+var zipPromise;
+var jszip = () => {
+	zipPromise ??= import("jszip").then((m) => "default" in m ? m.default : m);
+	return zipPromise;
+};
+var fail$1 = (verb, message) => {
+	throw new E_MEDIA_STEP_FAILED([verb, message]);
+};
+var VERB = "extract text";
+var extractPdfText = async (ctx) => {
+	const { PDFParse } = await import("pdf-parse");
+	try {
+		return (await new PDFParse({ data: ctx.payload.bytes }).getText()).text ?? "";
+	} catch (err) {
+		fail$1(VERB, `could not read the PDF: ${isError(err) ? err.message : String(err)}`);
+		throw err;
+	}
+};
+var extractDocxText = async (ctx) => {
+	const mod = await import("mammoth");
+	const mammoth = "extractRawText" in mod ? mod : mod.default;
+	const bytes = ctx.payload.bytes;
+	const input = typeof globalThis.Buffer !== "undefined" ? { buffer: globalThis.Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength) } : { arrayBuffer: bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) };
+	return (await mammoth.extractRawText(input)).value;
+};
+var extractXlsxText = async (ctx) => {
+	const mod = await import("exceljs");
+	const wb = new ("default" in mod ? mod.default : mod).Workbook();
+	await wb.xlsx.load(ctx.payload.bytes.buffer.slice(ctx.payload.bytes.byteOffset, ctx.payload.bytes.byteOffset + ctx.payload.bytes.byteLength));
+	const lines = [];
+	for (const ws of wb.worksheets) {
+		lines.push(`# ${ws.name}`);
+		ws.eachRow({ includeEmpty: false }, (row) => {
+			const cells = [];
+			row.eachCell({ includeEmpty: false }, (cell) => {
+				cells.push(String(cell.value ?? ""));
+			});
+			lines.push(cells.join("	"));
+		});
+	}
+	return lines.join("\n");
+};
+/** ODF content.xml → visible text (ported transformation order). */
+var extractOdfXmlText = (xml) => xml.replace(/<\/text:p>/g, "\n").replace(/<\/text:h>/g, "\n").replace(/<\/table:table-row>/g, "\n").replace(/<text:tab[^>]*\/>/g, "	").replace(/<text:line-break[^>]*\/>/g, "\n").replace(/<[^>]+>/g, "").replace(/&apos;/g, "'").replace(/&quot;/g, "\"").replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&").replace(/[ \t]+/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+var extractOdfText = async (ctx) => {
+	const content = (await (await jszip()).loadAsync(ctx.payload.bytes)).file("content.xml");
+	if (!content) fail$1(VERB, "the ODF archive is missing content.xml (corrupt file?)");
+	return extractOdfXmlText(await content.async("text"));
+};
+var extractPptxText = async (ctx) => {
+	const zip = await (await jszip()).loadAsync(ctx.payload.bytes);
+	const slideNames = Object.keys(zip.files).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n)).sort((a, b) => {
+		return Number(a.match(/slide(\d+)/)?.[1] ?? 0) - Number(b.match(/slide(\d+)/)?.[1] ?? 0);
+	});
+	if (slideNames.length === 0) fail$1(VERB, "the presentation has no slides");
+	const parts = [];
+	for (const name of slideNames) {
+		const texts = ((await zip.file(name).async("text")).match(/<a:t>([^<]*)<\/a:t>/g) ?? []).map((t) => t.replace(/<[^>]+>/g, "").replace(/&apos;/g, "'").replace(/&quot;/g, "\"").replace(/&gt;/g, ">").replace(/&lt;/g, "<").replace(/&amp;/g, "&"));
+		parts.push(texts.join("\n"));
+	}
+	return parts.join("\n\n");
+};
+var runOcr = async (ctx) => {
+	const out = argOf(ctx.step, "ocr_out") ?? "txt";
+	if (!ctx.engines.hasConvert(ctx.payload.mimeType, out)) fail$1(VERB, `this input requires OCR, and no engine that converts ${ctx.payload.mimeType} to "${out}" is configured. Do not retry this verb on this media in this deployment.`);
+	const langArg = ctx.step.args.lang;
+	const languages = langArg === void 0 ? void 0 : Array.isArray(langArg) ? langArg : [langArg];
+	const output = (await ctx.engines.convert({
+		bytes: ctx.payload.bytes,
+		mimeType: ctx.payload.mimeType,
+		filename: ctx.payload.filename,
+		to: out,
+		options: { languages },
+		signal: ctx.signal
+	})).outputs[0];
+	if (!output) fail$1(VERB, "OCR produced no output");
+	return new TextDecoder().decode(output.bytes);
+};
+/**
+* `extract.text` — full format dispatch. Routes by MIME, with OCR engine fallback for images
+* and force-OCR for any input via `ocr=force`.
+*/
+var extractTextDeepStep = async (ctx) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	const ocrMode = argOf(ctx.step, "ocr") ?? "auto";
+	const asData = (text) => ({
+		kind: "data",
+		data: text,
+		asText: text
+	});
+	if (mime.startsWith("image/")) return asData(await runOcr(ctx));
+	if (ocrMode === "force") return asData(await runOcr(ctx));
+	if (mime === MIME.PDF) {
+		const text = await extractPdfText(ctx);
+		if (text.trim().length === 0 && ocrMode === "auto") {
+			if (!ctx.engines.hasConvert(mime, "txt")) fail$1(VERB, "this PDF has no text layer (scanned?). An engine that converts application/pdf to text (OCR) is required to read it, and none is configured. Do not retry this verb on this media in this deployment.");
+			return asData(await runOcr(ctx));
+		}
+		return asData(text);
+	}
+	if (mime === MIME.DOCX || mime === MIME.DOC) return asData(await extractDocxText(ctx));
+	if (mime === MIME.XLSX) return asData(await extractXlsxText(ctx));
+	if (mime === MIME.ODT || mime === MIME.ODS || mime === MIME.ODP) return asData(await extractOdfText(ctx));
+	if (mime === MIME.PPTX) return asData(await extractPptxText(ctx));
+	if (mime.startsWith("text/") || mime === MIME.JSON) return asData(decodeText(ctx.payload.bytes));
+	fail$1(VERB, `text extraction for ${mime} is not supported in this build. For PPT/legacy formats: convert to=pptx | extract text (requires a convert engine).`);
+	throw new Error("unreachable");
+};
+/** `extract.metadata` — format-aware metadata (page counts, sheet/slide inventories). */
+var extractMetadataDeepStep = async (ctx) => {
+	const mime = ctx.payload.mimeType.toLowerCase().split(";")[0].trim();
+	const meta = {
+		filename: ctx.payload.filename,
+		mime_type: ctx.payload.mimeType,
+		size_bytes: ctx.payload.bytes.byteLength,
+		family: familyOf(ctx.payload.mimeType)
+	};
+	try {
+		if (mime === MIME.PDF) {
+			const { PDFDocument } = await import("pdf-lib");
+			const doc = await PDFDocument.load(ctx.payload.bytes, { ignoreEncryption: true });
+			meta.page_count = doc.getPageCount();
+			meta.title = doc.getTitle() ?? void 0;
+			meta.author = doc.getAuthor() ?? void 0;
+		} else if (mime === MIME.XLSX) {
+			const mod = await import("exceljs");
+			const wb = new ("default" in mod ? mod.default : mod).Workbook();
+			await wb.xlsx.load(ctx.payload.bytes.buffer.slice(ctx.payload.bytes.byteOffset, ctx.payload.bytes.byteOffset + ctx.payload.bytes.byteLength));
+			meta.sheets = wb.worksheets.map((ws) => ({
+				name: ws.name,
+				rows: ws.rowCount
+			}));
+		} else if (mime === MIME.PPTX) {
+			const zip = await (await jszip()).loadAsync(ctx.payload.bytes);
+			meta.slide_count = Object.keys(zip.files).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n)).length;
+		}
+	} catch {}
+	return {
+		kind: "data",
+		data: meta,
+		asText: JSON.stringify(meta)
+	};
+};
+/** The ingest step registry fragment (overrides the Phase 0 native-text-only versions). */
+var INGEST_STEPS = [["extract.text", extractTextDeepStep], ["extract.metadata", extractMetadataDeepStep]];
+//#endregion
+//#region src/batteries/media/registry.ts
+/**
+* The engine registry: capability-filtered, middleware-arbitrated, ordered dispatch over the
+* pipeline's engine array.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry (re-exported through the barrel).
+* One selection rule everywhere: gather every engine whose declarations match the request
+* (capability filter), run the consumer's selection onion (stages may exclude or reorder
+* candidates, never add), then the first survivor in supply order wins.
+*
+* Convert dispatch additionally computes multi-hop paths: when no single engine declares a
+* direct edge for the requested (input, target) pair, a breadth-first search over the format
+* graph finds the shortest chain of hops (capped at {@link MAX_HOPS}), with supply order
+* breaking ties at equal length. Pathfinding explores capability declarations only — cheap
+* and synchronous; the selection onion runs once per executed hop with real bytes in hand.
+*/
+/** The maximum number of conversion hops a computed path may take. */
+var MAX_HOPS = 3;
+/**
+* Format tokens that are valid conversion endpoints but never intermediate path nodes.
+* Without this rule the pathfinder would happily route `docx → txt → …` (lossy garbage in,
+* garbage out) or auto-chain `audio → pcm → txt` (skipping the resample the transcription
+* step performs between those legs).
+*/
+var TERMINAL_TOKENS = new Set([
+	"txt",
+	"json",
+	"hocr",
+	"srt",
+	"vtt",
+	"md",
+	"csv",
+	"pcm",
+	"images"
+]);
+/** Normalize a MIME type for comparison (lowercase, parameters stripped). */
+var normalizeMime = (mimeType) => mimeType.toLowerCase().split(";")[0].trim();
+/** `true` when `mime` matches `pattern` (exact, or a `family/*` wildcard). */
+var matchesMime = (pattern, mime) => {
+	const p = pattern.toLowerCase();
+	if (p.endsWith("/*")) return mime.startsWith(p.slice(0, -1));
+	return p === mime;
+};
+/** `true` when any pattern in `patterns` matches `mime`. */
+var matchesAny = (patterns, mime) => patterns.some((p) => matchesMime(p, mime));
+/** The mutate operations requested by a fused request. */
+var requestedOps = (request) => {
+	const ops = [];
+	if (request.resize) ops.push("resize");
+	if (request.rotate !== void 0) ops.push("rotate");
+	if (request.flip) ops.push("flip");
+	if (request.stripMetadata) ops.push("strip_metadata");
+	return ops;
+};
+/**
+* Build the registry over a resolved, validated engine array.
+*
+* @param engines - The engines, in supply (priority) order.
+* @param selection - Optional selection-middleware stages arbitrating multi-candidate dispatches.
+* @returns The registry.
+*/
+var buildEngineRegistry = (engines, selection = []) => {
+	const convertCandidates = (fromMime, to) => {
+		const mime = normalizeMime(fromMime);
+		const out = [];
+		for (const engine of engines) for (const capability of engine.converts ?? []) if (capability.to.includes(to) && matchesAny(capability.from, mime)) {
+			out.push({
+				engine,
+				capability
+			});
+			break;
+		}
+		return out;
+	};
+	const mutateCandidates = (request) => {
+		const mime = normalizeMime(request.mimeType);
+		const ops = requestedOps(request);
+		const out = [];
+		for (const engine of engines) for (const capability of engine.mutates ?? []) {
+			if (!matchesAny(capability.over, mime)) continue;
+			if (!ops.every((op) => capability.ops.includes(op))) continue;
+			if (request.format && !capability.encodes.includes(request.format.to)) continue;
+			out.push({
+				engine,
+				capability
+			});
+			break;
+		}
+		return out;
+	};
+	const arbitrate = async (kind, request, candidates) => {
+		if (candidates.length === 0) return void 0;
+		if (selection.length === 0 || candidates.length === 1) return candidates[0];
+		const ctx = {
+			kind,
+			request,
+			candidates: candidates.map((c) => c.engine)
+		};
+		const mw = new Middleware();
+		for (const fn of selection) mw.add(fn);
+		let failed;
+		await mw.runner().errorHandler(async (error) => {
+			failed = error;
+		}).finalHandler(async () => {}).run((fn, next) => Promise.resolve(fn(ctx, next)));
+		if (failed !== void 0) throw failed;
+		for (const engine of ctx.candidates) {
+			const survivor = candidates.find((c) => c.engine === engine);
+			if (survivor) return survivor;
+		}
+	};
+	const findPath = (fromMime, target) => {
+		const start = normalizeMime(fromMime);
+		const queue = [{
+			mime: start,
+			path: []
+		}];
+		const visited = new Set([start]);
+		while (queue.length > 0) {
+			const { mime, path } = queue.shift();
+			if (path.length >= MAX_HOPS) continue;
+			if (convertCandidates(mime, target).length > 0) return [...path, {
+				fromMime: mime,
+				to: target
+			}];
+			for (const engine of engines) for (const capability of engine.converts ?? []) {
+				if (!matchesAny(capability.from, mime)) continue;
+				for (const to of capability.to) {
+					if (TERMINAL_TOKENS.has(to)) continue;
+					const nextMime = EXT_TO_MIME[to];
+					if (!nextMime || visited.has(nextMime)) continue;
+					visited.add(nextMime);
+					queue.push({
+						mime: nextMime,
+						path: [...path, {
+							fromMime: mime,
+							to
+						}]
+					});
+				}
+			}
+		}
+	};
+	const hasConvert = (from, to) => {
+		for (const engine of engines) for (const capability of engine.converts ?? []) {
+			if (from !== void 0 && !matchesAny(capability.from, normalizeMime(from))) continue;
+			if (to !== void 0 && !capability.to.includes(to)) continue;
+			return true;
+		}
+		return false;
+	};
+	const convertTargets = (fromMime) => {
+		const reachable = [];
+		const seen = /* @__PURE__ */ new Set();
+		let frontier = [normalizeMime(fromMime)];
+		const visitedMimes = new Set(frontier);
+		for (let hop = 0; hop < MAX_HOPS && frontier.length > 0; hop++) {
+			const next = [];
+			for (const mime of frontier) for (const engine of engines) for (const capability of engine.converts ?? []) {
+				if (!matchesAny(capability.from, mime)) continue;
+				for (const to of capability.to) {
+					if (!seen.has(to)) {
+						seen.add(to);
+						reachable.push(to);
+					}
+					if (TERMINAL_TOKENS.has(to)) continue;
+					const nextMime = EXT_TO_MIME[to];
+					if (nextMime && !visitedMimes.has(nextMime)) {
+						visitedMimes.add(nextMime);
+						next.push(nextMime);
+					}
+				}
+			}
+			frontier = next;
+		}
+		return reachable;
+	};
+	const ids = () => engines.map((e) => e.id).join(", ") || "(none)";
+	const convert = async (request) => {
+		const path = findPath(request.mimeType, request.to);
+		if (!path) {
+			const supported = convertTargets(request.mimeType);
+			throw new Error(`no configured engine (or computed path) can convert ${request.mimeType} to "${request.to}"; reachable targets: ${supported.join(", ") || "(none)"} (engines: ${ids()})`);
+		}
+		let bytes = request.bytes;
+		let mimeType = request.mimeType;
+		let result;
+		for (const hop of path) {
+			const candidates = convertCandidates(mimeType, hop.to);
+			const chosen = await arbitrate("convert", {
+				mimeType,
+				filename: request.filename,
+				bytes,
+				to: hop.to
+			}, candidates);
+			if (!chosen) throw new Error(`all engines capable of converting ${mimeType} to "${hop.to}" (${candidates.map((c) => c.engine.id).join(", ")}) were excluded by selection middleware`);
+			result = await chosen.capability.convert({
+				bytes,
+				mimeType,
+				filename: request.filename,
+				to: hop.to,
+				options: request.options,
+				signal: request.signal
+			});
+			const first = result.outputs[0];
+			if (!first) throw new Error(`engine "${chosen.engine.id}" converted ${mimeType} to "${hop.to}" but produced no outputs`);
+			bytes = first.bytes;
+			mimeType = first.mimeType;
+		}
+		return result;
+	};
+	const mutate = async (request) => {
+		const candidates = mutateCandidates(request);
+		if (candidates.length === 0) {
+			const allOps = /* @__PURE__ */ new Set();
+			const allEncodes = /* @__PURE__ */ new Set();
+			for (const engine of engines) for (const capability of engine.mutates ?? []) {
+				for (const op of capability.ops) allOps.add(op);
+				for (const enc of capability.encodes) allEncodes.add(enc);
+			}
+			const wanted = requestedOps(request).join(", ") || "(none)";
+			const encodeNote = request.format ? `; requested encoding "${request.format.to}" — declared encodings: ${[...allEncodes].join(", ") || "(none)"}. A different engine (e.g. sharp) may support it` : "";
+			throw new Error(`no configured engine can mutate ${request.mimeType} with ops [${wanted}]${encodeNote} (engines: ${ids()})`);
+		}
+		const chosen = await arbitrate("mutate", {
+			mimeType: request.mimeType,
+			filename: "",
+			bytes: request.bytes,
+			to: request.format?.to,
+			ops: requestedOps(request)
+		}, candidates);
+		if (!chosen) throw new Error(`all engines capable of this mutate (${candidates.map((c) => c.engine.id).join(", ")}) were excluded by selection middleware`);
+		return chosen.capability.mutate(request);
+	};
+	return {
+		engines,
+		hasConvert,
+		hasMutate: () => engines.some((e) => (e.mutates ?? []).length > 0),
+		convertTargets,
+		convert,
+		mutate
+	};
+};
+//#endregion
+//#region src/batteries/media/steps/image_audio.ts
+/**
+* `image.*` and `audio.*` step implementations: fused raster transforms via the
+* imageTransform engine, and transcription via the audioDecode + asr engines.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. The split image verbs
+* (`resize`/`format`/`rotate`/`flip`/`strip_metadata`) read pipe-naturally, and the runtime
+* fuses **adjacent** image steps into a single engine invocation so a resize→format→rotate
+* chain costs one decode/encode (frozen design 0.13). Fusion happens here at execution time:
+* each image step folds its args into a shared fused request stored on the execution stash;
+* the LAST image step in a run performs the engine call.
+*
+* Audio transcription composes two engines: `audioDecode` (container → mono PCM) and `asr`
+* (PCM → text/subtitles). A small pure resampler bridges arbitrary sample rates to the
+* 16 kHz mono Float32Array ASR engines expect.
+*/
+var fail = (verb, message) => {
+	throw new E_MEDIA_STEP_FAILED([verb, message]);
+};
+var IMAGE_VERBS = new Set([
+	"image.resize",
+	"image.format",
+	"image.rotate",
+	"image.flip",
+	"image.strip_metadata"
+]);
+var requireImage = (ctx, verb) => {
+	if (!ctx.payload.mimeType.toLowerCase().startsWith("image/")) fail(verb, `image operations expect an image; the media is ${ctx.payload.mimeType}`);
+};
+/** Fold this step's args into the fused request. */
+var foldImageStep = (ctx, fused) => {
+	const args = ctx.step.args;
+	switch (ctx.step.verb) {
+		case "image.resize": return {
+			...fused,
+			resize: {
+				width: args.width,
+				height: args.height,
+				fit: args.fit
+			}
+		};
+		case "image.format": return {
+			...fused,
+			format: {
+				to: args.to,
+				quality: args.quality
+			},
+			...args.strip_metadata !== void 0 ? { stripMetadata: args.strip_metadata } : {}
+		};
+		case "image.rotate": {
+			const deg = Number(args.deg);
+			const total = ((fused.rotate ?? 0) + deg) % 360;
+			return {
+				...fused,
+				rotate: total === 0 ? void 0 : total
+			};
+		}
+		case "image.flip": {
+			const axis = args.axis;
+			const flip = { ...fused.flip ?? {} };
+			if (axis === "horizontal" || axis === "both") flip.horizontal = !flip.horizontal;
+			if (axis === "vertical" || axis === "both") flip.vertical = !flip.vertical;
+			return {
+				...fused,
+				flip
+			};
+		}
+		case "image.strip_metadata": return {
+			...fused,
+			stripMetadata: true
+		};
+		default: return fused;
+	}
+};
+/** `true` when the NEXT step in the plan is also an image verb (so we defer the engine call). */
+var nextIsImageStep = (ctx) => {
+	const next = ctx.plan.steps[ctx.stepIndex + 1];
+	return next !== void 0 && IMAGE_VERBS.has(next.verb);
+};
+var FUSION_KEY = "media.image.fused";
+var imageStep = async (ctx) => {
+	const verb = ctx.step.verb.replace(/\./g, " ");
+	requireImage(ctx, verb);
+	const fused = foldImageStep(ctx, ctx.stash.get(FUSION_KEY) ?? {});
+	if (nextIsImageStep(ctx)) {
+		ctx.stash.set(FUSION_KEY, fused);
+		return {
+			kind: "media",
+			payload: ctx.payload
+		};
+	}
+	ctx.stash.delete(FUSION_KEY);
+	if (!ctx.engines.hasMutate()) fail(verb, "no image-mutating engine is configured. Do not retry image verbs in this deployment.");
+	const result = await ctx.engines.mutate({
+		...fused,
+		bytes: ctx.payload.bytes,
+		mimeType: ctx.payload.mimeType,
+		signal: ctx.signal
+	});
+	const ext = result.mimeType.split("/")[1]?.replace("jpeg", "jpg") ?? "bin";
+	const dot = ctx.payload.filename.lastIndexOf(".");
+	const base = dot > 0 ? ctx.payload.filename.slice(0, dot) : ctx.payload.filename;
+	return {
+		kind: "media",
+		payload: {
+			bytes: result.bytes,
+			mimeType: result.mimeType,
+			filename: `${base}.${ext}`
+		}
+	};
+};
+/** Downmix to mono and linearly resample to the target rate. Pure, cross-env. */
+var resampleTo = (pcm, fromRate, toRate) => {
+	if (fromRate === toRate) return pcm;
+	const ratio = fromRate / toRate;
+	const outLength = Math.floor(pcm.length / ratio);
+	const out = new Float32Array(outLength);
+	for (let i = 0; i < outLength; i++) {
+		const pos = i * ratio;
+		const left = Math.floor(pos);
+		const right = Math.min(left + 1, pcm.length - 1);
+		const frac = pos - left;
+		out[i] = pcm[left] * (1 - frac) + pcm[right] * frac;
+	}
+	return out;
+};
+var ASR_SAMPLE_RATE = 16e3;
+/**
+* `audio.transcribe` — an explicit two-stage composition: convert the container to PCM,
+* resample to 16 kHz mono, then convert the PCM to the requested text form. The registry
+* never auto-chains through PCM (it is a terminal token), precisely because this resample
+* leg must happen between the two converts.
+*/
+var audioTranscribeStep = async (ctx) => {
+	const verb = "audio transcribe";
+	if (!ctx.payload.mimeType.toLowerCase().startsWith("audio/")) fail(verb, `transcription expects audio; the media is ${ctx.payload.mimeType}`);
+	const out = argOf(ctx.step, "out") ?? "txt";
+	if (!ctx.engines.hasConvert(ctx.payload.mimeType, "pcm")) fail(verb, `no engine that decodes ${ctx.payload.mimeType} to PCM is configured. Do not retry this verb in this deployment.`);
+	if (!ctx.engines.hasConvert("audio/x-adk-pcm", out)) fail(verb, `no engine that transcribes PCM to "${out}" is configured. Do not retry this verb in this deployment.`);
+	const pcmOut = (await ctx.engines.convert({
+		bytes: ctx.payload.bytes,
+		mimeType: ctx.payload.mimeType,
+		filename: ctx.payload.filename,
+		to: "pcm",
+		signal: ctx.signal
+	})).outputs[0];
+	if (!pcmOut) fail(verb, "audio decoding produced no output");
+	const sourceRate = Number(pcmOut.meta?.sampleRate);
+	if (!Number.isFinite(sourceRate) || sourceRate <= 0) fail(verb, "the decode engine did not report meta.sampleRate on its PCM output");
+	const pcm = resampleTo(bytesToPcm(pcmOut.bytes), sourceRate, ASR_SAMPLE_RATE);
+	const final = (await ctx.engines.convert({
+		bytes: pcmToBytes(pcm),
+		mimeType: PCM_MIME,
+		filename: ctx.payload.filename,
+		to: out,
+		options: {
+			lang: argOf(ctx.step, "lang"),
+			translate: argOf(ctx.step, "translate")
+		},
+		signal: ctx.signal
+	})).outputs[0];
+	if (!final) fail(verb, "transcription produced no output");
+	const text = new TextDecoder().decode(final.bytes);
+	return {
+		kind: "data",
+		data: text,
+		asText: text
+	};
+};
+/** The image + audio step registry fragment. */
+var IMAGE_AUDIO_STEPS = [
+	["image.resize", imageStep],
+	["image.format", imageStep],
+	["image.rotate", imageStep],
+	["image.flip", imageStep],
+	["image.strip_metadata", imageStep],
+	["audio.transcribe", audioTranscribeStep]
+];
+//#endregion
+//#region src/batteries/media/steps/pages.ts
+/**
+* Pure page-operation step implementations for PDFs: select, split, merge, reorder.
+*
+* @remarks
+* Internal sibling of the `@nhtio/adk/batteries/media` entry. Implemented with `pdf-lib`
+* (optional peer, lazily imported) on in-memory bytes — no binaries, cross-environment.
+* Phase 0 covers PDF inputs; PPTX slide operations and DOCX section operations join in the
+* sheet/slides/doc phases, sharing these verb ids with format dispatch.
+*/
+var pdfLibPromise;
+var pdfLib = () => {
+	pdfLibPromise ??= import("pdf-lib");
+	return pdfLibPromise;
+};
+var requirePdf = (verb, payload) => {
+	if (payload.mimeType.toLowerCase().split(";")[0].trim() !== MIME.PDF) throw new E_MEDIA_STEP_FAILED([verb, `page operations for ${payload.mimeType} are not yet implemented in this build (PDF is supported)`]);
+};
+var loadPdf = async (verb, bytes) => {
+	const { PDFDocument } = await pdfLib();
+	try {
+		return await PDFDocument.load(bytes, { ignoreEncryption: false });
+	} catch (err) {
+		throw new E_MEDIA_STEP_FAILED([verb, `could not read the PDF: ${isError(err) ? err.message : String(err)}`], { cause: err });
+	}
+};
+var checkIndices = (verb, indices, pageCount) => {
+	for (const i of indices) if (i < 1 || i > pageCount) throw new E_MEDIA_STEP_FAILED([verb, `page ${i} is out of range — the document has ${pageCount} pages (pages are 1-based)`]);
+};
+/** `select` — keep only the listed 1-based pages, producing one document. */
+var selectStep = async (ctx) => {
+	requirePdf("select", ctx.payload);
+	const pages = argOf(ctx.step, "pages");
+	const source = await loadPdf("select", ctx.payload.bytes);
+	checkIndices("select", pages, source.getPageCount());
+	const { PDFDocument } = await pdfLib();
+	const out = await PDFDocument.create();
+	const copied = await out.copyPages(source, pages.map((p) => p - 1));
+	for (const page of copied) out.addPage(page);
+	const bytes = await out.save();
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes: new Uint8Array(bytes)
+		}
+	};
+};
+/** `split` — split into multiple documents by page (optionally grouped by JSON ranges). */
+var splitStep = async (ctx) => {
+	requirePdf("split", ctx.payload);
+	const by = argOf(ctx.step, "by") ?? "page";
+	if (by !== "page") throw new E_MEDIA_STEP_FAILED(["split", `split by=${by} is not yet implemented in this build (page is supported)`]);
+	const source = await loadPdf("split", ctx.payload.bytes);
+	const pageCount = source.getPageCount();
+	const rawRanges = ctx.step.args.ranges;
+	const groups = rawRanges !== void 0 ? rawRanges.map((pair) => {
+		if (!Array.isArray(pair) || pair.length !== 2) throw new E_MEDIA_STEP_FAILED(["split", `ranges must be [start,end] pairs, e.g. ranges='[[1,3],[5,7]]'`]);
+		const [start, end] = pair;
+		const pages = [];
+		for (let p = start; p <= end; p++) pages.push(p);
+		return pages;
+	}) : Array.from({ length: pageCount }, (_, i) => [i + 1]);
+	const { PDFDocument } = await pdfLib();
+	const payloads = [];
+	let part = 1;
+	for (const group of groups) {
+		checkIndices("split", group, pageCount);
+		const out = await PDFDocument.create();
+		const copied = await out.copyPages(source, group.map((p) => p - 1));
+		for (const page of copied) out.addPage(page);
+		const bytes = new Uint8Array(await out.save());
+		payloads.push({
+			bytes,
+			mimeType: MIME.PDF,
+			filename: replaceExtension(ctx.payload.filename, "").replace(/\.$/, "") + `.part${part}.pdf`
+		});
+		part += 1;
+	}
+	return {
+		kind: "media-list",
+		payloads
+	};
+};
+/** `merge` — append the referenced media's pages, in order. */
+var mergeStep = async (ctx) => {
+	requirePdf("merge", ctx.payload);
+	const raw = ctx.step.args.with;
+	const refs = Array.isArray(raw) ? raw : [raw];
+	const { PDFDocument } = await pdfLib();
+	const out = await PDFDocument.create();
+	const appendAll = async (doc) => {
+		const copied = await out.copyPages(doc, doc.getPageIndices());
+		for (const page of copied) out.addPage(page);
+	};
+	await appendAll(await loadPdf("merge", ctx.payload.bytes));
+	for (const ref of refs) {
+		if (ref.kind !== "id") throw new E_MEDIA_STEP_FAILED(["merge", "builder refs are not yet supported here"]);
+		const other = await ctx.resolveRef(ref.id);
+		requirePdf("merge", other);
+		await appendAll(await loadPdf("merge", other.bytes));
+	}
+	const bytes = new Uint8Array(await out.save());
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes
+		}
+	};
+};
+/** `reorder` — rebuild the document with pages in the given 1-based order. */
+var reorderStep = async (ctx) => {
+	requirePdf("reorder", ctx.payload);
+	const order = argOf(ctx.step, "order");
+	const source = await loadPdf("reorder", ctx.payload.bytes);
+	const pageCount = source.getPageCount();
+	checkIndices("reorder", order, pageCount);
+	if (order.length !== pageCount) throw new E_MEDIA_STEP_FAILED(["reorder", `order lists ${order.length} pages but the document has ${pageCount} — list every page exactly once`]);
+	const { PDFDocument } = await pdfLib();
+	const out = await PDFDocument.create();
+	const copied = await out.copyPages(source, order.map((p) => p - 1));
+	for (const page of copied) out.addPage(page);
+	const bytes = new Uint8Array(await out.save());
+	return {
+		kind: "media",
+		payload: {
+			...ctx.payload,
+			bytes
+		}
+	};
+};
+//#endregion
+//#region src/batteries/media/index.ts
+/**
+* A knex-inspired local media pipeline: one declarative plan, three front-ends (chainable
+* builder, pipe string, JSON ops), engines as composable seams.
+*
+* @module @nhtio/adk/batteries/media
+*
+* @remarks
+* Most implementations give you two ways to process media — ship it to an external API, or
+* flood the model's context window with the bytes. This battery is the third option: **full
+* control of media — local processing, no external APIs by default, cross-environment where
+* possible.** Your data stays in your application and infrastructure unless you deliberately
+* wire an engine that sends it elsewhere.
+*
+* The entry point is {@link createMediaPipeline}:
+*
+* ```ts
+* import { createMediaPipeline } from '@nhtio/adk/batteries/media'
+*
+* const mp = await createMediaPipeline({
+*   engines: [
+*     // an ordered array of self-declaring engines; resolvers run eagerly at construction,
+*     // but each engine's heavy peer dependency loads lazily on first actual use
+*     () => import('@nhtio/adk/batteries/media/engines/jimp').then((m) => m.jimpEngine()),
+*   ],
+* })
+*
+* // chainable builder (implementor DX)
+* const redacted = await mp(payload)
+*   .select({ pages: [2, 3] })
+*   .redact({ match: [/\d{3}-\d{2}-\d{4}/] })
+*
+* // pipe string (the LLM-facing DSL — same plan underneath)
+* const result = await mp.query(payload, 'select pages=2-3 | redact match=/\\d{3}-\\d{2}-\\d{4}/')
+* ```
+*
+* Media pipelines have no standard — every tool invented its own grammar. LLMs don't share one
+* mental model of that chaos, so the pipe DSL projects every operation onto the one
+* transformation idiom every model already groks: shell pipes with `key=value` args. The verbs
+* a deployment advertises narrow to the engines it configured; everything else fails loud with
+* a model-actionable message.
+*/
+var configSchema = validator.object({
+	engines: validator.array().items(validator.alternatives().try(validator.function(), validator.object().unknown(true))).optional(),
+	selection: validator.array().items(validator.function()).optional(),
+	use: validator.array().items(validator.function()).optional(),
+	resolveRef: validator.function().optional()
+}).unknown(false);
+/** The Phase 0 step registry: pure steps available in every deployment. */
+var PURE_STEPS = [
+	["select", selectStep],
+	["split", splitStep],
+	["merge", mergeStep],
+	["reorder", reorderStep],
+	["redact", redactStep],
+	["update_text", updateTextStep],
+	["diff", diffStep],
+	["apply_patch", applyPatchStep],
+	["extract.text", extractTextStep],
+	["extract.metadata", extractMetadataStep],
+	["chunk", chunkStep],
+	...SHEET_STEPS,
+	...SLIDES_STEPS,
+	...DOC_STEPS,
+	...INGEST_STEPS,
+	...IMAGE_AUDIO_STEPS
+];
+/** Resolve one engine entry: invoke a resolver, unwrap `{default}`, guard-check the result. */
+var resolveEngine = async (entry, index) => {
+	let value = entry;
+	if (typeof value === "function") {
+		try {
+			value = await value();
+		} catch (err) {
+			throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`engines[${index}] resolver failed: ${isError(err) ? err.message : String(err)}`]);
+		}
+		if (isObject(value) && "default" in value && !implementsMediaEngine(value)) value = value.default;
+	}
+	if (!implementsMediaEngine(value)) {
+		const candidate = value;
+		throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`engines[${index}]${isObject(value) && typeof candidate?.id === "string" ? ` ("${candidate.id}")` : ""} does not implement the MediaEngine contract (a string id plus at least one well-formed converts/mutates capability entry)`]);
+	}
+	return value;
+};
+/**
+* Create a media pipeline.
+*
+* @remarks
+* Config is validated eagerly, and so are the engines: every resolver in the array runs at
+* construction (capability declarations drive verb narrowing, so they must be known up
+* front), each result is contract-checked, and failures throw
+* `E_INVALID_MEDIA_PIPELINE_CONFIG` naming the offending index. Construction stays cheap —
+* bundled engine modules import their heavy peer dependencies lazily inside capability
+* methods, on first actual use.
+*
+* @param config - Engines, selection stages, step interceptors, and the media-ref resolver.
+* @returns The callable {@link MediaPipeline}.
+*/
+var createMediaPipeline = async (config = {}) => {
+	const { error } = configSchema.validate(config, { abortEarly: true });
+	if (error) throw new E_INVALID_MEDIA_PIPELINE_CONFIG([error.message]);
+	const use = config.use ?? [];
+	const resolveRef = config.resolveRef ?? (() => {
+		throw new E_INVALID_MEDIA_PIPELINE_CONFIG(["this chain references another media (@id) but no resolveRef was configured"]);
+	});
+	const registry = buildEngineRegistry(await Promise.all((config.engines ?? []).map(resolveEngine)), config.selection ?? []);
+	const steps = new Map(PURE_STEPS);
+	const run = async (input, plan, options) => {
+		const refResolver = options?.resolveRef ?? resolveRef;
+		return executePlan(plan, {
+			input,
+			steps,
+			use,
+			engines: registry,
+			resolveRef: async (id) => refResolver(id),
+			signal: options?.signal
+		});
+	};
+	const compile = (statement) => typeof statement === "string" ? validateSegments(parsePipeRaw(statement), { capabilities: registry }) : validateOps(statement, { capabilities: registry });
+	const callable = ((input) => {
+		return new MediaChain(async (ops) => {
+			return run(input, validateOps(ops, { capabilities: registry }));
+		});
+	});
+	Object.defineProperties(callable, {
+		query: { value: async (input, q, options) => {
+			return run(input, validateSegments(parsePipeRaw(q), { capabilities: registry }), options);
+		} },
+		ops: { value: async (input, ops, options) => {
+			return run(input, validateOps(ops, { capabilities: registry }), options);
+		} },
+		compile: { value: compile },
+		capabilities: { value: registry },
+		engines: { value: registry.engines }
+	});
+	return callable;
+};
+//#endregion
+export { EXT_TO_MIME, E_INVALID_MEDIA_PIPELINE_CONFIG, E_MEDIA_BAD_ARG, E_MEDIA_ENGINE_REQUIRED, E_MEDIA_MISSING_ARG, E_MEDIA_NOT_PIPE_EXPRESSIBLE, E_MEDIA_PIPE_SYNTAX, E_MEDIA_STEP_FAILED, E_MEDIA_STEP_UNAVAILABLE, E_MEDIA_UNKNOWN_ARG, E_MEDIA_UNKNOWN_VERB, E_MEDIA_UNSUPPORTED_OP, FOLDED_VERBS, MIME, MediaChain, PCM_MIME, VERBS, VERB_INDEX, availableVerbs, buildEngineRegistry, bytesToPcm, createMediaPipeline, familyOf, foldVerb, fromOps, implementsMediaEngine, isMediaRef, isRegExpRef, lowerSegments, parsePipeRaw, pcmToBytes, replaceExtension, suggestVerbs, toOps, toPipe, unsupportedForMutationReason, validateOps, validateSegments };
+
+//# sourceMappingURL=media.mjs.map