@nhtio/adk 0.1.0-master-e6c58205 → 0.1.0-master-89b47bec

package/batteries/media/engines/exceljs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceljs.cjs","names":[],"sources":["../../../../src/batteries/media/engines/exceljs.ts"],"sourcesContent":["/**\n * The ExcelJS-backed workbook {@link @nhtio/adk/batteries/media/contracts!MediaEngine}: the\n * fidelity-preserving structural editor for xlsx, plus in-process blank-workbook generation.\n *\n * @module @nhtio/adk/batteries/media/engines/exceljs\n *\n * @remarks\n * ExcelJS models the parts of a workbook that matter to humans — fonts, fills, comments,\n * merged ranges, data validations — and carries them through a read→edit→write cycle intact.\n * That is this engine's whole reason to exist: the `sheet.*` verbs mutate workbooks users\n * hand us, and an edit that strips the user's formatting as a side effect is corruption with\n * good intentions. Compose this engine FIRST in the engines array when fidelity matters; the\n * sheetjs engine edits a far wider read matrix (ODS, XLS, NUMBERS, …) but SheetJS Community\n * Edition strips styling in the process.\n *\n * Capabilities:\n *\n * - **generate**: `EMPTY_MIME` → xlsx (a blank workbook with one `Sheet1` — every sheet step\n *   expects at least one worksheet).\n * - **edit**: the ten `sheet.*` structural ops over xlsx, styling preserved.\n *\n * `exceljs` is an optional peer dependency, lazily imported on first actual use. Cross-env by\n * construction: no `node:*` imports, `Uint8Array` in and out (ExcelJS ships a browser build\n * via its `browser` field).\n */\n\nimport { MIME } from '../formats'\nimport { EMPTY_MIME } from '../contracts'\nimport { isError } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { default as ExcelJSNS } from 'exceljs'\nimport type {\n  MediaEngine,\n  ConvertRequest,\n  ConvertResult,\n  EditRequest,\n  EditResult,\n  EditSummary,\n} from '../contracts'\n\ntype ExcelJSModule = typeof ExcelJSNS\n\n/** Options for {@link exceljsEngine}. */\nexport interface ExceljsEngineOptions {\n  /** Override the module resolution (tests / custom builds). Default: `import('exceljs')`. */\n  exceljs?: () => ExcelJSModule | Promise<ExcelJSModule>\n}\n\n/** The structural ops this engine edits (same names the verb table uses). */\nconst SHEET_OPS: readonly string[] = [\n  'sheet.add_rows',\n  'sheet.add_columns',\n  'sheet.update_cells',\n  'sheet.delete_rows',\n  'sheet.delete_columns',\n  'sheet.rename_sheet',\n  'sheet.add_sheet',\n  'sheet.remove_sheet',\n  'sheet.reorder_sheets',\n  'sheet.transform_table',\n]\n\n/**\n * Construct the ExcelJS-backed workbook engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const exceljsEngine = (options: ExceljsEngineOptions = {}): MediaEngine => {\n  let modPromise: Promise<ExcelJSModule> | undefined\n  const getExcel = (): Promise<ExcelJSModule> => {\n    modPromise ??= Promise.resolve(\n      options.exceljs\n        ? options.exceljs()\n        : import('exceljs').then((m) => ('default' in m ? m.default : m) as ExcelJSModule)\n    ).catch((err) => {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `the exceljs engine could not load its peer dependency \"exceljs\": ${detail} — install it (pnpm add exceljs)`,\n      ])\n    })\n    return modPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    if (request.to !== 'xlsx') {\n      throw new Error(`exceljs generates \"xlsx\" only; requested \"${request.to}\"`)\n    }\n    const ExcelJS = await getExcel()\n    const wb = new ExcelJS.Workbook()\n    wb.addWorksheet('Sheet1')\n    const bytes = new Uint8Array(await wb.xlsx.writeBuffer())\n    return { outputs: [{ bytes, mimeType: MIME.XLSX }] }\n  }\n\n  const edit = async (request: EditRequest): Promise<EditResult> => {\n    const ExcelJS = await getExcel()\n    const wb = new ExcelJS.Workbook()\n    try {\n      await wb.xlsx.load(\n        request.bytes.buffer.slice(\n          request.bytes.byteOffset,\n          request.bytes.byteOffset + request.bytes.byteLength\n        ) as ArrayBuffer\n      )\n    } catch (err) {\n      const detail = isError(err) ? err.message : String(err)\n      throw new Error(`could not open the spreadsheet: ${detail}`)\n    }\n    const summary = applyEdit(wb, request.op, request.args)\n    const bytes = new Uint8Array(await wb.xlsx.writeBuffer())\n    return { bytes, mimeType: MIME.XLSX, summary }\n  }\n\n  return {\n    id: 'exceljs',\n    converts: [{ from: [EMPTY_MIME], to: ['xlsx'], convert }],\n    edits: [{ over: [MIME.XLSX], ops: SHEET_OPS, edit }],\n  }\n}\n\n// ── op implementations (moved from steps/sheet.ts; styling-preserving by library) ───────────\n\n/** Resolve the target worksheet from the frozen `sheet=` rule (bare number=index, string=name). */\nconst resolveSheet = (wb: ExcelJSNS.Workbook, sheetArg: unknown): ExcelJSNS.Worksheet => {\n  if (sheetArg === undefined || sheetArg === null) {\n    const first = wb.worksheets[0]\n    if (!first) throw new Error('the workbook has no worksheets')\n    return first\n  }\n  // Frozen 0.11: bare number targets by 1-based index; quoted string targets by name.\n  if (typeof sheetArg === 'number') {\n    const byIndex = wb.worksheets[sheetArg - 1]\n    if (byIndex) return byIndex\n    const byName = wb.getWorksheet(String(sheetArg))\n    if (byName) {\n      throw new Error(\n        `no sheet at index ${sheetArg}, but a sheet NAMED \"${sheetArg}\" exists — quote it: sheet=\"${sheetArg}\"`\n      )\n    }\n    throw new Error(\n      `sheet index ${sheetArg} is out of range (1-based; the workbook has ${wb.worksheets.length})`\n    )\n  }\n  const ws = wb.getWorksheet(sheetArg as string)\n  if (!ws) {\n    const names = wb.worksheets.map((w) => `\"${w.name}\"`).join(', ')\n    throw new Error(`no sheet named \"${String(sheetArg)}\". Sheets: ${names}`)\n  }\n  return ws\n}\n\nconst columnLetterToNumber = (col: string): number => {\n  let n = 0\n  for (const ch of col.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64)\n  return n\n}\n\ntype CellValue = string | number | boolean | null\n\nconst asCellValue = (value: unknown): ExcelJSNS.CellValue => {\n  if (value === null) return null\n  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {\n    return value\n  }\n  throw new Error(`cell values must be string, number, boolean, or null; got ${typeof value}`)\n}\n\n/** Apply one structural op to the workbook in place; returns the change summary. */\nconst applyEdit = (\n  wb: ExcelJSNS.Workbook,\n  op: string,\n  args: Record<string, unknown>\n): EditSummary => {\n  switch (op) {\n    case 'sheet.add_rows': {\n      const rows = args.rows\n      if (!Array.isArray(rows) || rows.length === 0 || !rows.every(Array.isArray)) {\n        throw new Error(`rows must be a non-empty JSON array of arrays, e.g. rows='[[\"a\",1]]'`)\n      }\n      const before = args.before as number | undefined\n      const after = args.after as number | undefined\n      const ws = resolveSheet(wb, args.sheet)\n      const insertAt =\n        before !== undefined ? before : after !== undefined ? after + 1 : ws.rowCount + 1\n      const cellRows = (rows as unknown[][]).map((r) => r.map(asCellValue))\n      ws.spliceRows(insertAt, 0, ...cellRows)\n      return { added: cellRows.length }\n    }\n    case 'sheet.add_columns': {\n      const headers = args.headers as string[] | undefined\n      const columns: Array<{ header: string; values?: CellValue[] }> | undefined =\n        (args.columns as Array<{ header: string; values?: CellValue[] }> | undefined) ??\n        headers?.map((header) => ({ header }) as { header: string; values?: CellValue[] })\n      if (!Array.isArray(columns) || columns.length === 0) {\n        throw new Error(`provide headers=a,b or columns='[{\"header\":\"X\",\"values\":[1]}]'`)\n      }\n      const before = args.before as number | undefined\n      const after = args.after as number | undefined\n      const ws = resolveSheet(wb, args.sheet)\n      const insertAt =\n        before !== undefined ? before : after !== undefined ? after + 1 : ws.columnCount + 1\n      for (const [i, col] of columns.entries()) {\n        if (typeof col?.header !== 'string') throw new Error('every column needs a string header')\n        ws.spliceColumns(insertAt + i, 0, [col.header, ...(col.values ?? []).map(asCellValue)])\n      }\n      return { added: columns.length }\n    }\n    case 'sheet.update_cells': {\n      const updates = args.updates\n      if (!Array.isArray(updates) || updates.length === 0) {\n        throw new Error(\n          `updates must be a non-empty JSON array, e.g. updates='[{\"address\":\"B2\",\"value\":3}]'`\n        )\n      }\n      const ws = resolveSheet(wb, args.sheet)\n      let modified = 0\n      for (const raw of updates as Array<Record<string, unknown>>) {\n        const address = raw.address as string | undefined\n        const row = raw.row as number | undefined\n        const col = raw.col as number | string | undefined\n        let cell: ExcelJSNS.Cell\n        if (address) {\n          cell = ws.getCell(address)\n        } else if (row !== undefined && col !== undefined) {\n          cell =\n            typeof col === 'string'\n              ? ws.getCell(row, columnLetterToNumber(col))\n              : ws.getCell(row, col)\n        } else {\n          throw new Error('each update needs address, or both row and col')\n        }\n        const value = raw.value\n        if (typeof value === 'string' && value.startsWith('=')) {\n          cell.value = { formula: value.slice(1) } as ExcelJSNS.CellValue\n        } else {\n          cell.value = asCellValue(value)\n        }\n        modified += 1\n      }\n      return { modified }\n    }\n    case 'sheet.delete_rows': {\n      const rows = args.rows as number[]\n      const ws = resolveSheet(wb, args.sheet)\n      for (const r of [...rows].sort((a, b) => b - a)) ws.spliceRows(r, 1)\n      return { removed: rows.length }\n    }\n    case 'sheet.delete_columns': {\n      const columns = args.columns as number[]\n      const ws = resolveSheet(wb, args.sheet)\n      for (const c of [...columns].sort((a, b) => b - a)) ws.spliceColumns(c, 1)\n      return { removed: columns.length }\n    }\n    case 'sheet.rename_sheet': {\n      const sheet = args.sheet as string\n      const to = args.to as string\n      const ws = wb.getWorksheet(sheet)\n      if (!ws) {\n        const names = wb.worksheets.map((w) => `\"${w.name}\"`).join(', ')\n        throw new Error(`rename targets a sheet NAME; no sheet named \"${sheet}\". Sheets: ${names}`)\n      }\n      ws.name = to\n      return { modified: 1 }\n    }\n    case 'sheet.add_sheet': {\n      const name = args.name as string\n      const at = args.at as number | undefined\n      if (wb.getWorksheet(name)) throw new Error(`a sheet named \"${name}\" already exists`)\n      const ws = wb.addWorksheet(name)\n      if (at !== undefined) {\n        const all = wb.worksheets\n        const wsIdx = all.indexOf(ws)\n        if (wsIdx !== at - 1) {\n          all.forEach((w, i) => {\n            ;(w as unknown as { orderNo: number }).orderNo =\n              w === ws ? at : i + 1 >= at && i < wsIdx ? i + 2 : i + 1\n          })\n        }\n      }\n      return { added: 1 }\n    }\n    case 'sheet.remove_sheet': {\n      const sheet = args.sheet as string\n      const ws = wb.getWorksheet(sheet)\n      if (!ws) {\n        const names = wb.worksheets.map((w) => `\"${w.name}\"`).join(', ')\n        throw new Error(`remove targets a sheet NAME; no sheet named \"${sheet}\". Sheets: ${names}`)\n      }\n      wb.removeWorksheet(ws.id)\n      return { removed: 1 }\n    }\n    case 'sheet.reorder_sheets': {\n      const order = args.order\n      if (!Array.isArray(order) || order.length === 0) {\n        throw new Error(`order must be a JSON array of names/indices, e.g. order='[\"Summary\",2]'`)\n      }\n      const refs = order as Array<string | number>\n      if (refs.length !== wb.worksheets.length) {\n        throw new Error(\n          `order must include every worksheet exactly once (the workbook has ${wb.worksheets.length})`\n        )\n      }\n      const reordered: ExcelJSNS.Worksheet[] = []\n      const seen = new Set<number>()\n      for (const ref of refs) {\n        const ws = typeof ref === 'number' ? wb.worksheets[ref - 1] : wb.getWorksheet(ref)\n        if (!ws) throw new Error(`sheet not found: ${String(ref)}`)\n        if (seen.has(ws.id)) throw new Error(`duplicate sheet reference: ${String(ref)}`)\n        seen.add(ws.id)\n        reordered.push(ws)\n      }\n      // ExcelJS serializes by orderNo; the worksheets getter returns a sorted clone.\n      reordered.forEach((ws, i) => {\n        ;(ws as unknown as { orderNo: number }).orderNo = i + 1\n      })\n      return { modified: reordered.length }\n    }\n    case 'sheet.transform_table': {\n      const headerRow = (args.header_row as number | undefined) ?? 1\n      const rename = args.rename as Array<{ from: string; to: string }> | undefined\n      const select = args.select as string[] | undefined\n      const drop = args.drop as string[] | undefined\n      const ws = resolveSheet(wb, args.sheet)\n      let modified = 0\n      const headerMap = new Map<string, number>()\n      ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {\n        if (typeof cell.value === 'string') headerMap.set(cell.value, colNumber)\n      })\n      if (rename) {\n        for (const { from, to } of rename) {\n          const colNum = headerMap.get(from)\n          if (colNum !== undefined) {\n            ws.getRow(headerRow).getCell(colNum).value = to\n            headerMap.delete(from)\n            headerMap.set(to, colNum)\n            modified += 1\n          }\n        }\n      }\n      if (drop) {\n        const cols = drop\n          .map((name) => headerMap.get(name))\n          .filter((n): n is number => n !== undefined)\n          .sort((a, b) => b - a)\n        for (const col of cols) {\n          ws.spliceColumns(col, 1)\n          modified += 1\n        }\n      }\n      if (select) {\n        const keep = new Set(select)\n        const cols: number[] = []\n        ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {\n          if (typeof cell.value === 'string' && !keep.has(cell.value)) cols.push(colNumber)\n        })\n        cols.sort((a, b) => b - a)\n        for (const col of cols) {\n          ws.spliceColumns(col, 1)\n          modified += 1\n        }\n      }\n      return { modified }\n    }\n    default:\n      throw new Error(`exceljs does not implement edit op \"${op}\"`)\n  }\n}\n"],"mappings":"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"}

package/batteries/media/engines/exceljs.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The ExcelJS-backed workbook {@link @nhtio/adk/batteries/media/contracts!MediaEngine}: the
+ * fidelity-preserving structural editor for xlsx, plus in-process blank-workbook generation.
+ *
+ * @module @nhtio/adk/batteries/media/engines/exceljs
+ *
+ * @remarks
+ * ExcelJS models the parts of a workbook that matter to humans — fonts, fills, comments,
+ * merged ranges, data validations — and carries them through a read→edit→write cycle intact.
+ * That is this engine's whole reason to exist: the `sheet.*` verbs mutate workbooks users
+ * hand us, and an edit that strips the user's formatting as a side effect is corruption with
+ * good intentions. Compose this engine FIRST in the engines array when fidelity matters; the
+ * sheetjs engine edits a far wider read matrix (ODS, XLS, NUMBERS, …) but SheetJS Community
+ * Edition strips styling in the process.
+ *
+ * Capabilities:
+ *
+ * - **generate**: `EMPTY_MIME` → xlsx (a blank workbook with one `Sheet1` — every sheet step
+ *   expects at least one worksheet).
+ * - **edit**: the ten `sheet.*` structural ops over xlsx, styling preserved.
+ *
+ * `exceljs` is an optional peer dependency, lazily imported on first actual use. Cross-env by
+ * construction: no `node:*` imports, `Uint8Array` in and out (ExcelJS ships a browser build
+ * via its `browser` field).
+ */
+import type { default as ExcelJSNS } from 'exceljs';
+import type { MediaEngine } from "../contracts";
+type ExcelJSModule = typeof ExcelJSNS;
+/** Options for {@link exceljsEngine}. */
+export interface ExceljsEngineOptions {
+    /** Override the module resolution (tests / custom builds). Default: `import('exceljs')`. */
+    exceljs?: () => ExcelJSModule | Promise<ExcelJSModule>;
+}
+/**
+ * Construct the ExcelJS-backed workbook engine.
+ *
+ * @param options - Optional module resolver override.
+ * @returns The engine.
+ */
+export declare const exceljsEngine: (options?: ExceljsEngineOptions) => MediaEngine;
+export {};

package/batteries/media/engines/exceljs.mjs

@@ -0,0 +1,288 @@
+import { o as isError } from "../../../tool_registry-CZ55mIti.mjs";
+import "../../../guards.mjs";
+import { EMPTY_MIME } from "../contracts.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4Ofs.mjs";
+import { n as MIME } from "../../../formats-CCylUHZw.mjs";
+//#region src/batteries/media/engines/exceljs.ts
+/**
+* The ExcelJS-backed workbook {@link @nhtio/adk/batteries/media/contracts!MediaEngine}: the
+* fidelity-preserving structural editor for xlsx, plus in-process blank-workbook generation.
+*
+* @module @nhtio/adk/batteries/media/engines/exceljs
+*
+* @remarks
+* ExcelJS models the parts of a workbook that matter to humans — fonts, fills, comments,
+* merged ranges, data validations — and carries them through a read→edit→write cycle intact.
+* That is this engine's whole reason to exist: the `sheet.*` verbs mutate workbooks users
+* hand us, and an edit that strips the user's formatting as a side effect is corruption with
+* good intentions. Compose this engine FIRST in the engines array when fidelity matters; the
+* sheetjs engine edits a far wider read matrix (ODS, XLS, NUMBERS, …) but SheetJS Community
+* Edition strips styling in the process.
+*
+* Capabilities:
+*
+* - **generate**: `EMPTY_MIME` → xlsx (a blank workbook with one `Sheet1` — every sheet step
+*   expects at least one worksheet).
+* - **edit**: the ten `sheet.*` structural ops over xlsx, styling preserved.
+*
+* `exceljs` is an optional peer dependency, lazily imported on first actual use. Cross-env by
+* construction: no `node:*` imports, `Uint8Array` in and out (ExcelJS ships a browser build
+* via its `browser` field).
+*/
+/** The structural ops this engine edits (same names the verb table uses). */
+var SHEET_OPS = [
+	"sheet.add_rows",
+	"sheet.add_columns",
+	"sheet.update_cells",
+	"sheet.delete_rows",
+	"sheet.delete_columns",
+	"sheet.rename_sheet",
+	"sheet.add_sheet",
+	"sheet.remove_sheet",
+	"sheet.reorder_sheets",
+	"sheet.transform_table"
+];
+/**
+* Construct the ExcelJS-backed workbook engine.
+*
+* @param options - Optional module resolver override.
+* @returns The engine.
+*/
+var exceljsEngine = (options = {}) => {
+	let modPromise;
+	const getExcel = () => {
+		modPromise ??= Promise.resolve(options.exceljs ? options.exceljs() : import("exceljs").then((m) => "default" in m ? m.default : m)).catch((err) => {
+			throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`the exceljs engine could not load its peer dependency "exceljs": ${isError(err) ? err.message : String(err)} — install it (pnpm add exceljs)`]);
+		});
+		return modPromise;
+	};
+	const convert = async (request) => {
+		if (request.to !== "xlsx") throw new Error(`exceljs generates "xlsx" only; requested "${request.to}"`);
+		const wb = new (await (getExcel())).Workbook();
+		wb.addWorksheet("Sheet1");
+		return { outputs: [{
+			bytes: new Uint8Array(await wb.xlsx.writeBuffer()),
+			mimeType: MIME.XLSX
+		}] };
+	};
+	const edit = async (request) => {
+		const wb = new (await (getExcel())).Workbook();
+		try {
+			await wb.xlsx.load(request.bytes.buffer.slice(request.bytes.byteOffset, request.bytes.byteOffset + request.bytes.byteLength));
+		} catch (err) {
+			const detail = isError(err) ? err.message : String(err);
+			throw new Error(`could not open the spreadsheet: ${detail}`);
+		}
+		const summary = applyEdit(wb, request.op, request.args);
+		return {
+			bytes: new Uint8Array(await wb.xlsx.writeBuffer()),
+			mimeType: MIME.XLSX,
+			summary
+		};
+	};
+	return {
+		id: "exceljs",
+		converts: [{
+			from: [EMPTY_MIME],
+			to: ["xlsx"],
+			convert
+		}],
+		edits: [{
+			over: [MIME.XLSX],
+			ops: SHEET_OPS,
+			edit
+		}]
+	};
+};
+/** Resolve the target worksheet from the frozen `sheet=` rule (bare number=index, string=name). */
+var resolveSheet = (wb, sheetArg) => {
+	if (sheetArg === void 0 || sheetArg === null) {
+		const first = wb.worksheets[0];
+		if (!first) throw new Error("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))) throw new Error(`no sheet at index ${sheetArg}, but a sheet NAMED "${sheetArg}" exists — quote it: sheet="${sheetArg}"`);
+		throw new Error(`sheet index ${sheetArg} is out of range (1-based; the workbook has ${wb.worksheets.length})`);
+	}
+	const ws = wb.getWorksheet(sheetArg);
+	if (!ws) {
+		const names = wb.worksheets.map((w) => `"${w.name}"`).join(", ");
+		throw new Error(`no sheet named "${String(sheetArg)}". Sheets: ${names}`);
+	}
+	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 = (value) => {
+	if (value === null) return null;
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+	throw new Error(`cell values must be string, number, boolean, or null; got ${typeof value}`);
+};
+/** Apply one structural op to the workbook in place; returns the change summary. */
+var applyEdit = (wb, op, args) => {
+	switch (op) {
+		case "sheet.add_rows": {
+			const rows = args.rows;
+			if (!Array.isArray(rows) || rows.length === 0 || !rows.every(Array.isArray)) throw new Error(`rows must be a non-empty JSON array of arrays, e.g. rows='[["a",1]]'`);
+			const before = args.before;
+			const after = args.after;
+			const ws = resolveSheet(wb, args.sheet);
+			const insertAt = before !== void 0 ? before : after !== void 0 ? after + 1 : ws.rowCount + 1;
+			const cellRows = rows.map((r) => r.map(asCellValue));
+			ws.spliceRows(insertAt, 0, ...cellRows);
+			return { added: cellRows.length };
+		}
+		case "sheet.add_columns": {
+			const headers = args.headers;
+			const columns = args.columns ?? headers?.map((header) => ({ header }));
+			if (!Array.isArray(columns) || columns.length === 0) throw new Error(`provide headers=a,b or columns='[{"header":"X","values":[1]}]'`);
+			const before = args.before;
+			const after = args.after;
+			const ws = resolveSheet(wb, args.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") throw new Error("every column needs a string header");
+				ws.spliceColumns(insertAt + i, 0, [col.header, ...(col.values ?? []).map(asCellValue)]);
+			}
+			return { added: columns.length };
+		}
+		case "sheet.update_cells": {
+			const updates = args.updates;
+			if (!Array.isArray(updates) || updates.length === 0) throw new Error(`updates must be a non-empty JSON array, e.g. updates='[{"address":"B2","value":3}]'`);
+			const ws = resolveSheet(wb, args.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 throw new Error("each update needs address, or both row and col");
+				const value = raw.value;
+				if (typeof value === "string" && value.startsWith("=")) cell.value = { formula: value.slice(1) };
+				else cell.value = asCellValue(value);
+				modified += 1;
+			}
+			return { modified };
+		}
+		case "sheet.delete_rows": {
+			const rows = args.rows;
+			const ws = resolveSheet(wb, args.sheet);
+			for (const r of [...rows].sort((a, b) => b - a)) ws.spliceRows(r, 1);
+			return { removed: rows.length };
+		}
+		case "sheet.delete_columns": {
+			const columns = args.columns;
+			const ws = resolveSheet(wb, args.sheet);
+			for (const c of [...columns].sort((a, b) => b - a)) ws.spliceColumns(c, 1);
+			return { removed: columns.length };
+		}
+		case "sheet.rename_sheet": {
+			const sheet = args.sheet;
+			const to = args.to;
+			const ws = wb.getWorksheet(sheet);
+			if (!ws) {
+				const names = wb.worksheets.map((w) => `"${w.name}"`).join(", ");
+				throw new Error(`rename targets a sheet NAME; no sheet named "${sheet}". Sheets: ${names}`);
+			}
+			ws.name = to;
+			return { modified: 1 };
+		}
+		case "sheet.add_sheet": {
+			const name = args.name;
+			const at = args.at;
+			if (wb.getWorksheet(name)) throw new Error(`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 };
+		}
+		case "sheet.remove_sheet": {
+			const sheet = args.sheet;
+			const ws = wb.getWorksheet(sheet);
+			if (!ws) {
+				const names = wb.worksheets.map((w) => `"${w.name}"`).join(", ");
+				throw new Error(`remove targets a sheet NAME; no sheet named "${sheet}". Sheets: ${names}`);
+			}
+			wb.removeWorksheet(ws.id);
+			return { removed: 1 };
+		}
+		case "sheet.reorder_sheets": {
+			const order = args.order;
+			if (!Array.isArray(order) || order.length === 0) throw new Error(`order must be a JSON array of names/indices, e.g. order='["Summary",2]'`);
+			const refs = order;
+			if (refs.length !== wb.worksheets.length) throw new Error(`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) throw new Error(`sheet not found: ${String(ref)}`);
+				if (seen.has(ws.id)) throw new Error(`duplicate sheet reference: ${String(ref)}`);
+				seen.add(ws.id);
+				reordered.push(ws);
+			}
+			reordered.forEach((ws, i) => {
+				ws.orderNo = i + 1;
+			});
+			return { modified: reordered.length };
+		}
+		case "sheet.transform_table": {
+			const headerRow = args.header_row ?? 1;
+			const rename = args.rename;
+			const select = args.select;
+			const drop = args.drop;
+			const ws = resolveSheet(wb, args.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 };
+		}
+		default: throw new Error(`exceljs does not implement edit op "${op}"`);
+	}
+};
+//#endregion
+export { exceljsEngine };
+
+//# sourceMappingURL=exceljs.mjs.map

package/batteries/media/engines/exceljs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceljs.mjs","names":[],"sources":["../../../../src/batteries/media/engines/exceljs.ts"],"sourcesContent":["/**\n * The ExcelJS-backed workbook {@link @nhtio/adk/batteries/media/contracts!MediaEngine}: the\n * fidelity-preserving structural editor for xlsx, plus in-process blank-workbook generation.\n *\n * @module @nhtio/adk/batteries/media/engines/exceljs\n *\n * @remarks\n * ExcelJS models the parts of a workbook that matter to humans — fonts, fills, comments,\n * merged ranges, data validations — and carries them through a read→edit→write cycle intact.\n * That is this engine's whole reason to exist: the `sheet.*` verbs mutate workbooks users\n * hand us, and an edit that strips the user's formatting as a side effect is corruption with\n * good intentions. Compose this engine FIRST in the engines array when fidelity matters; the\n * sheetjs engine edits a far wider read matrix (ODS, XLS, NUMBERS, …) but SheetJS Community\n * Edition strips styling in the process.\n *\n * Capabilities:\n *\n * - **generate**: `EMPTY_MIME` → xlsx (a blank workbook with one `Sheet1` — every sheet step\n *   expects at least one worksheet).\n * - **edit**: the ten `sheet.*` structural ops over xlsx, styling preserved.\n *\n * `exceljs` is an optional peer dependency, lazily imported on first actual use. Cross-env by\n * construction: no `node:*` imports, `Uint8Array` in and out (ExcelJS ships a browser build\n * via its `browser` field).\n */\n\nimport { MIME } from '../formats'\nimport { EMPTY_MIME } from '../contracts'\nimport { isError } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { default as ExcelJSNS } from 'exceljs'\nimport type {\n  MediaEngine,\n  ConvertRequest,\n  ConvertResult,\n  EditRequest,\n  EditResult,\n  EditSummary,\n} from '../contracts'\n\ntype ExcelJSModule = typeof ExcelJSNS\n\n/** Options for {@link exceljsEngine}. */\nexport interface ExceljsEngineOptions {\n  /** Override the module resolution (tests / custom builds). Default: `import('exceljs')`. */\n  exceljs?: () => ExcelJSModule | Promise<ExcelJSModule>\n}\n\n/** The structural ops this engine edits (same names the verb table uses). */\nconst SHEET_OPS: readonly string[] = [\n  'sheet.add_rows',\n  'sheet.add_columns',\n  'sheet.update_cells',\n  'sheet.delete_rows',\n  'sheet.delete_columns',\n  'sheet.rename_sheet',\n  'sheet.add_sheet',\n  'sheet.remove_sheet',\n  'sheet.reorder_sheets',\n  'sheet.transform_table',\n]\n\n/**\n * Construct the ExcelJS-backed workbook engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const exceljsEngine = (options: ExceljsEngineOptions = {}): MediaEngine => {\n  let modPromise: Promise<ExcelJSModule> | undefined\n  const getExcel = (): Promise<ExcelJSModule> => {\n    modPromise ??= Promise.resolve(\n      options.exceljs\n        ? options.exceljs()\n        : import('exceljs').then((m) => ('default' in m ? m.default : m) as ExcelJSModule)\n    ).catch((err) => {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `the exceljs engine could not load its peer dependency \"exceljs\": ${detail} — install it (pnpm add exceljs)`,\n      ])\n    })\n    return modPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    if (request.to !== 'xlsx') {\n      throw new Error(`exceljs generates \"xlsx\" only; requested \"${request.to}\"`)\n    }\n    const ExcelJS = await getExcel()\n    const wb = new ExcelJS.Workbook()\n    wb.addWorksheet('Sheet1')\n    const bytes = new Uint8Array(await wb.xlsx.writeBuffer())\n    return { outputs: [{ bytes, mimeType: MIME.XLSX }] }\n  }\n\n  const edit = async (request: EditRequest): Promise<EditResult> => {\n    const ExcelJS = await getExcel()\n    const wb = new ExcelJS.Workbook()\n    try {\n      await wb.xlsx.load(\n        request.bytes.buffer.slice(\n          request.bytes.byteOffset,\n          request.bytes.byteOffset + request.bytes.byteLength\n        ) as ArrayBuffer\n      )\n    } catch (err) {\n      const detail = isError(err) ? err.message : String(err)\n      throw new Error(`could not open the spreadsheet: ${detail}`)\n    }\n    const summary = applyEdit(wb, request.op, request.args)\n    const bytes = new Uint8Array(await wb.xlsx.writeBuffer())\n    return { bytes, mimeType: MIME.XLSX, summary }\n  }\n\n  return {\n    id: 'exceljs',\n    converts: [{ from: [EMPTY_MIME], to: ['xlsx'], convert }],\n    edits: [{ over: [MIME.XLSX], ops: SHEET_OPS, edit }],\n  }\n}\n\n// ── op implementations (moved from steps/sheet.ts; styling-preserving by library) ───────────\n\n/** Resolve the target worksheet from the frozen `sheet=` rule (bare number=index, string=name). */\nconst resolveSheet = (wb: ExcelJSNS.Workbook, sheetArg: unknown): ExcelJSNS.Worksheet => {\n  if (sheetArg === undefined || sheetArg === null) {\n    const first = wb.worksheets[0]\n    if (!first) throw new Error('the workbook has no worksheets')\n    return first\n  }\n  // Frozen 0.11: bare number targets by 1-based index; quoted string targets by name.\n  if (typeof sheetArg === 'number') {\n    const byIndex = wb.worksheets[sheetArg - 1]\n    if (byIndex) return byIndex\n    const byName = wb.getWorksheet(String(sheetArg))\n    if (byName) {\n      throw new Error(\n        `no sheet at index ${sheetArg}, but a sheet NAMED \"${sheetArg}\" exists — quote it: sheet=\"${sheetArg}\"`\n      )\n    }\n    throw new Error(\n      `sheet index ${sheetArg} is out of range (1-based; the workbook has ${wb.worksheets.length})`\n    )\n  }\n  const ws = wb.getWorksheet(sheetArg as string)\n  if (!ws) {\n    const names = wb.worksheets.map((w) => `\"${w.name}\"`).join(', ')\n    throw new Error(`no sheet named \"${String(sheetArg)}\". Sheets: ${names}`)\n  }\n  return ws\n}\n\nconst columnLetterToNumber = (col: string): number => {\n  let n = 0\n  for (const ch of col.toUpperCase()) n = n * 26 + (ch.charCodeAt(0) - 64)\n  return n\n}\n\ntype CellValue = string | number | boolean | null\n\nconst asCellValue = (value: unknown): ExcelJSNS.CellValue => {\n  if (value === null) return null\n  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {\n    return value\n  }\n  throw new Error(`cell values must be string, number, boolean, or null; got ${typeof value}`)\n}\n\n/** Apply one structural op to the workbook in place; returns the change summary. */\nconst applyEdit = (\n  wb: ExcelJSNS.Workbook,\n  op: string,\n  args: Record<string, unknown>\n): EditSummary => {\n  switch (op) {\n    case 'sheet.add_rows': {\n      const rows = args.rows\n      if (!Array.isArray(rows) || rows.length === 0 || !rows.every(Array.isArray)) {\n        throw new Error(`rows must be a non-empty JSON array of arrays, e.g. rows='[[\"a\",1]]'`)\n      }\n      const before = args.before as number | undefined\n      const after = args.after as number | undefined\n      const ws = resolveSheet(wb, args.sheet)\n      const insertAt =\n        before !== undefined ? before : after !== undefined ? after + 1 : ws.rowCount + 1\n      const cellRows = (rows as unknown[][]).map((r) => r.map(asCellValue))\n      ws.spliceRows(insertAt, 0, ...cellRows)\n      return { added: cellRows.length }\n    }\n    case 'sheet.add_columns': {\n      const headers = args.headers as string[] | undefined\n      const columns: Array<{ header: string; values?: CellValue[] }> | undefined =\n        (args.columns as Array<{ header: string; values?: CellValue[] }> | undefined) ??\n        headers?.map((header) => ({ header }) as { header: string; values?: CellValue[] })\n      if (!Array.isArray(columns) || columns.length === 0) {\n        throw new Error(`provide headers=a,b or columns='[{\"header\":\"X\",\"values\":[1]}]'`)\n      }\n      const before = args.before as number | undefined\n      const after = args.after as number | undefined\n      const ws = resolveSheet(wb, args.sheet)\n      const insertAt =\n        before !== undefined ? before : after !== undefined ? after + 1 : ws.columnCount + 1\n      for (const [i, col] of columns.entries()) {\n        if (typeof col?.header !== 'string') throw new Error('every column needs a string header')\n        ws.spliceColumns(insertAt + i, 0, [col.header, ...(col.values ?? []).map(asCellValue)])\n      }\n      return { added: columns.length }\n    }\n    case 'sheet.update_cells': {\n      const updates = args.updates\n      if (!Array.isArray(updates) || updates.length === 0) {\n        throw new Error(\n          `updates must be a non-empty JSON array, e.g. updates='[{\"address\":\"B2\",\"value\":3}]'`\n        )\n      }\n      const ws = resolveSheet(wb, args.sheet)\n      let modified = 0\n      for (const raw of updates as Array<Record<string, unknown>>) {\n        const address = raw.address as string | undefined\n        const row = raw.row as number | undefined\n        const col = raw.col as number | string | undefined\n        let cell: ExcelJSNS.Cell\n        if (address) {\n          cell = ws.getCell(address)\n        } else if (row !== undefined && col !== undefined) {\n          cell =\n            typeof col === 'string'\n              ? ws.getCell(row, columnLetterToNumber(col))\n              : ws.getCell(row, col)\n        } else {\n          throw new Error('each update needs address, or both row and col')\n        }\n        const value = raw.value\n        if (typeof value === 'string' && value.startsWith('=')) {\n          cell.value = { formula: value.slice(1) } as ExcelJSNS.CellValue\n        } else {\n          cell.value = asCellValue(value)\n        }\n        modified += 1\n      }\n      return { modified }\n    }\n    case 'sheet.delete_rows': {\n      const rows = args.rows as number[]\n      const ws = resolveSheet(wb, args.sheet)\n      for (const r of [...rows].sort((a, b) => b - a)) ws.spliceRows(r, 1)\n      return { removed: rows.length }\n    }\n    case 'sheet.delete_columns': {\n      const columns = args.columns as number[]\n      const ws = resolveSheet(wb, args.sheet)\n      for (const c of [...columns].sort((a, b) => b - a)) ws.spliceColumns(c, 1)\n      return { removed: columns.length }\n    }\n    case 'sheet.rename_sheet': {\n      const sheet = args.sheet as string\n      const to = args.to as string\n      const ws = wb.getWorksheet(sheet)\n      if (!ws) {\n        const names = wb.worksheets.map((w) => `\"${w.name}\"`).join(', ')\n        throw new Error(`rename targets a sheet NAME; no sheet named \"${sheet}\". Sheets: ${names}`)\n      }\n      ws.name = to\n      return { modified: 1 }\n    }\n    case 'sheet.add_sheet': {\n      const name = args.name as string\n      const at = args.at as number | undefined\n      if (wb.getWorksheet(name)) throw new Error(`a sheet named \"${name}\" already exists`)\n      const ws = wb.addWorksheet(name)\n      if (at !== undefined) {\n        const all = wb.worksheets\n        const wsIdx = all.indexOf(ws)\n        if (wsIdx !== at - 1) {\n          all.forEach((w, i) => {\n            ;(w as unknown as { orderNo: number }).orderNo =\n              w === ws ? at : i + 1 >= at && i < wsIdx ? i + 2 : i + 1\n          })\n        }\n      }\n      return { added: 1 }\n    }\n    case 'sheet.remove_sheet': {\n      const sheet = args.sheet as string\n      const ws = wb.getWorksheet(sheet)\n      if (!ws) {\n        const names = wb.worksheets.map((w) => `\"${w.name}\"`).join(', ')\n        throw new Error(`remove targets a sheet NAME; no sheet named \"${sheet}\". Sheets: ${names}`)\n      }\n      wb.removeWorksheet(ws.id)\n      return { removed: 1 }\n    }\n    case 'sheet.reorder_sheets': {\n      const order = args.order\n      if (!Array.isArray(order) || order.length === 0) {\n        throw new Error(`order must be a JSON array of names/indices, e.g. order='[\"Summary\",2]'`)\n      }\n      const refs = order as Array<string | number>\n      if (refs.length !== wb.worksheets.length) {\n        throw new Error(\n          `order must include every worksheet exactly once (the workbook has ${wb.worksheets.length})`\n        )\n      }\n      const reordered: ExcelJSNS.Worksheet[] = []\n      const seen = new Set<number>()\n      for (const ref of refs) {\n        const ws = typeof ref === 'number' ? wb.worksheets[ref - 1] : wb.getWorksheet(ref)\n        if (!ws) throw new Error(`sheet not found: ${String(ref)}`)\n        if (seen.has(ws.id)) throw new Error(`duplicate sheet reference: ${String(ref)}`)\n        seen.add(ws.id)\n        reordered.push(ws)\n      }\n      // ExcelJS serializes by orderNo; the worksheets getter returns a sorted clone.\n      reordered.forEach((ws, i) => {\n        ;(ws as unknown as { orderNo: number }).orderNo = i + 1\n      })\n      return { modified: reordered.length }\n    }\n    case 'sheet.transform_table': {\n      const headerRow = (args.header_row as number | undefined) ?? 1\n      const rename = args.rename as Array<{ from: string; to: string }> | undefined\n      const select = args.select as string[] | undefined\n      const drop = args.drop as string[] | undefined\n      const ws = resolveSheet(wb, args.sheet)\n      let modified = 0\n      const headerMap = new Map<string, number>()\n      ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {\n        if (typeof cell.value === 'string') headerMap.set(cell.value, colNumber)\n      })\n      if (rename) {\n        for (const { from, to } of rename) {\n          const colNum = headerMap.get(from)\n          if (colNum !== undefined) {\n            ws.getRow(headerRow).getCell(colNum).value = to\n            headerMap.delete(from)\n            headerMap.set(to, colNum)\n            modified += 1\n          }\n        }\n      }\n      if (drop) {\n        const cols = drop\n          .map((name) => headerMap.get(name))\n          .filter((n): n is number => n !== undefined)\n          .sort((a, b) => b - a)\n        for (const col of cols) {\n          ws.spliceColumns(col, 1)\n          modified += 1\n        }\n      }\n      if (select) {\n        const keep = new Set(select)\n        const cols: number[] = []\n        ws.getRow(headerRow).eachCell({ includeEmpty: false }, (cell, colNumber) => {\n          if (typeof cell.value === 'string' && !keep.has(cell.value)) cols.push(colNumber)\n        })\n        cols.sort((a, b) => b - a)\n        for (const col of cols) {\n          ws.spliceColumns(col, 1)\n          modified += 1\n        }\n      }\n      return { modified }\n    }\n    default:\n      throw new Error(`exceljs does not implement edit op \"${op}\"`)\n  }\n}\n"],"mappings":"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"}

package/batteries/media/engines/execa_executor.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Cek0wNdY.js");
-const require_tool_registry = require("../../../tool_registry-BdKlPuHS.js");
+const require_tool_registry = require("../../../tool_registry-DwZ6pzN4.js");
 require("../../../guards.cjs");
 const require_exceptions = require("../../../exceptions-D79HIKeX.js");
 //#region src/batteries/media/engines/execa_executor.ts

package/batteries/media/engines/execa_executor.mjs

@@ -1,4 +1,4 @@
-import { c as isObject, o as isError } from "../../../tool_registry-BaLUIzWz.mjs";
+import { c as isObject, o as isError } from "../../../tool_registry-CZ55mIti.mjs";
 import "../../../guards.mjs";
 import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4Ofs.mjs";
 //#region src/batteries/media/engines/execa_executor.ts

package/batteries/media/engines/fs_workspace.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Cek0wNdY.js");
-const require_tool_registry = require("../../../tool_registry-BdKlPuHS.js");
+const require_tool_registry = require("../../../tool_registry-DwZ6pzN4.js");
 require("../../../guards.cjs");
 const require_exceptions = require("../../../exceptions-D79HIKeX.js");
 //#region src/batteries/media/engines/fs_workspace.ts

package/batteries/media/engines/fs_workspace.mjs

@@ -1,4 +1,4 @@
-import { o as isError, s as isInstanceOf } from "../../../tool_registry-BaLUIzWz.mjs";
+import { o as isError, s as isInstanceOf } from "../../../tool_registry-CZ55mIti.mjs";
 import "../../../guards.mjs";
 import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4Ofs.mjs";
 //#region src/batteries/media/engines/fs_workspace.ts

package/batteries/media/engines/jimp.cjs

@@ -1,7 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Cek0wNdY.js");
-const require_tool_registry = require("../../../tool_registry-BdKlPuHS.js");
+const require_tool_registry = require("../../../tool_registry-DwZ6pzN4.js");
 require("../../../guards.cjs");
+const require_batteries_media_contracts = require("../contracts.cjs");
 const require_exceptions = require("../../../exceptions-D79HIKeX.js");
 //#region src/batteries/media/engines/jimp.ts
 /**
@@ -14,7 +15,9 @@ const require_exceptions = require("../../../exceptions-D79HIKeX.js");
 * The local-by-default raster engine: runs anywhere TypeScript runs. Declares one mutate
 * capability over png/jpeg/bmp/gif/tiff with resize (cover/contain approximations), rotate,
 * flip, quality, and metadata stripping (Jimp re-encodes pixels, so EXIF never survives —
-* `strip_metadata` is inherently satisfied). For webp/avif output or native-speed processing,
+* `strip_metadata` is inherently satisfied), plus a generation edge: `EMPTY_MIME` → a blank
+* 1024×1024 white canvas in any supported encoding (resize in the same statement —
+* `empty:png | image resize width=64`). For webp/avif output or native-speed processing,
 * compose a sharp-backed engine instead — the capability declaration is the seam.
 *
 * `jimp` is an optional peer dependency, lazily imported on first actual use (constructing
@@ -85,8 +88,27 @@ var jimpEngine = (options = {}) => {
 			mimeType
 		};
 	};
+	const convert = async (request) => {
+		const mimeType = MIME_BY_FORMAT[request.to];
+		if (!mimeType) throw new Error(`jimp cannot generate "${request.to}"; supported: ${SUPPORTED_OUTPUT.join(", ")}`);
+		const { Jimp } = await getJimp();
+		const buffer = await new Jimp({
+			width: 1024,
+			height: 1024,
+			color: 4294967295
+		}).getBuffer(mimeType);
+		return { outputs: [{
+			bytes: new Uint8Array(buffer),
+			mimeType
+		}] };
+	};
 	return {
 		id: "jimp",
+		converts: [{
+			from: [require_batteries_media_contracts.EMPTY_MIME],
+			to: SUPPORTED_OUTPUT,
+			convert
+		}],
 		mutates: [{
 			over: [
 				"image/png",

package/batteries/media/engines/jimp.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"jimp.cjs","names":[],"sources":["../../../../src/batteries/media/engines/jimp.ts"],"sourcesContent":["/**\n * A cross-environment image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by Jimp (pure JavaScript — no native bindings, no binaries).\n *\n * @module @nhtio/adk/batteries/media/engines/jimp\n *\n * @remarks\n * The local-by-default raster engine: runs anywhere TypeScript runs. Declares one mutate\n * capability over png/jpeg/bmp/gif/tiff with resize (cover/contain approximations), rotate,\n * flip, quality, and metadata stripping (Jimp re-encodes pixels, so EXIF never survives —\n * `strip_metadata` is inherently satisfied). For webp/avif output or native-speed processing,\n * compose a sharp-backed engine instead — the capability declaration is the seam.\n *\n * `jimp` is an optional peer dependency, lazily imported on first actual use (constructing\n * the engine — and therefore the pipeline — never loads it).\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type * as JimpNS from 'jimp'\nimport type { MediaEngine, MutateRequest, EngineBytesResult } from '../contracts'\n\ntype JimpModule = typeof JimpNS\n\n/** Options for {@link jimpEngine}. */\nexport interface JimpEngineOptions {\n  /** Override the module resolution (tests / custom builds). Default: `import('jimp')`. */\n  jimp?: () => JimpModule | Promise<JimpModule>\n}\n\nconst SUPPORTED_OUTPUT = ['png', 'jpg', 'jpeg', 'bmp', 'gif', 'tiff'] as const\n\nconst MIME_BY_FORMAT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  bmp: 'image/bmp',\n  gif: 'image/gif',\n  tiff: 'image/tiff',\n}\n\n/**\n * Construct the Jimp-backed image engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const jimpEngine = (options: JimpEngineOptions = {}): MediaEngine => {\n  let modPromise: Promise<JimpModule> | undefined\n  const getJimp = (): Promise<JimpModule> => {\n    modPromise ??= Promise.resolve(options.jimp ? options.jimp() : import('jimp')).catch((err) => {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `the jimp engine could not load its peer dependency \"jimp\": ${detail} — install it (pnpm add jimp)`,\n      ])\n    })\n    return modPromise\n  }\n\n  const mutate = async (request: MutateRequest): Promise<EngineBytesResult> => {\n    const { Jimp } = await getJimp()\n    const image = await Jimp.read(\n      request.bytes.buffer.slice(\n        request.bytes.byteOffset,\n        request.bytes.byteOffset + request.bytes.byteLength\n      ) as ArrayBuffer\n    )\n\n    if (request.resize) {\n      const { width, height, fit } = request.resize\n      if (width !== undefined && height !== undefined) {\n        if (fit === 'cover') image.cover({ w: width, h: height })\n        else if (fit === 'contain') image.contain({ w: width, h: height })\n        else image.resize({ w: width, h: height })\n      } else if (width !== undefined) {\n        image.resize({ w: width })\n      } else if (height !== undefined) {\n        image.resize({ h: height })\n      }\n    }\n    if (request.rotate) {\n      image.rotate(request.rotate)\n    }\n    if (request.flip) {\n      image.flip({\n        horizontal: request.flip.horizontal === true,\n        vertical: request.flip.vertical === true,\n      })\n    }\n\n    const targetFormat = request.format?.to ?? mimeToFormat(request.mimeType)\n    const mimeType = MIME_BY_FORMAT[targetFormat]\n    if (!mimeType) {\n      throw new Error(\n        `jimp cannot encode \"${targetFormat}\"; supported: ${SUPPORTED_OUTPUT.join(', ')} (compose a sharp engine for webp/avif)`\n      )\n    }\n    const quality = request.format?.quality\n    const buffer =\n      mimeType === 'image/jpeg' && quality !== undefined\n        ? await image.getBuffer('image/jpeg', { quality })\n        : await image.getBuffer(mimeType as 'image/png')\n    return { bytes: new Uint8Array(buffer), mimeType }\n  }\n\n  return {\n    id: 'jimp',\n    mutates: [\n      {\n        over: ['image/png', 'image/jpeg', 'image/bmp', 'image/gif', 'image/tiff'],\n        ops: ['resize', 'rotate', 'flip', 'strip_metadata'],\n        encodes: SUPPORTED_OUTPUT,\n        mutate,\n      },\n    ],\n  }\n}\n\nconst mimeToFormat = (mimeType: string): string => {\n  const sub = mimeType.toLowerCase().split(';')[0].trim().split('/')[1] ?? 'png'\n  return sub === 'jpeg' ? 'jpg' : sub\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA8BA,IAAM,mBAAmB;CAAC;CAAO;CAAO;CAAQ;CAAO;CAAO;AAAM;AAEpE,IAAM,iBAAyC;CAC7C,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,KAAK;CACL,MAAM;AACR;;;;;;;AAQA,IAAa,cAAc,UAA6B,CAAC,MAAmB;CAC1E,IAAI;CACJ,MAAM,gBAAqC;EACzC,eAAe,QAAQ,QAAQ,QAAQ,OAAO,QAAQ,KAAK,IAAI,OAAO,OAAO,EAAE,OAAO,QAAQ;GAE5F,MAAM,IAAI,mBAAA,gCAAgC,CACxC,8DAFa,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiB,8BACvE,CAAC;EACH,CAAC;EACD,OAAO;CACT;CAEA,MAAM,SAAS,OAAO,YAAuD;EAC3E,MAAM,EAAE,SAAS,MAAM,QAAQ;EAC/B,MAAM,QAAQ,MAAM,KAAK,KACvB,QAAQ,MAAM,OAAO,MACnB,QAAQ,MAAM,YACd,QAAQ,MAAM,aAAa,QAAQ,MAAM,UAC3C,CACF;EAEA,IAAI,QAAQ,QAAQ;GAClB,MAAM,EAAE,OAAO,QAAQ,QAAQ,QAAQ;GACvC,IAAI,UAAU,KAAA,KAAa,WAAW,KAAA,GACpC,IAAI,QAAQ,SAAS,MAAM,MAAM;IAAE,GAAG;IAAO,GAAG;GAAO,CAAC;QACnD,IAAI,QAAQ,WAAW,MAAM,QAAQ;IAAE,GAAG;IAAO,GAAG;GAAO,CAAC;QAC5D,MAAM,OAAO;IAAE,GAAG;IAAO,GAAG;GAAO,CAAC;QACpC,IAAI,UAAU,KAAA,GACnB,MAAM,OAAO,EAAE,GAAG,MAAM,CAAC;QACpB,IAAI,WAAW,KAAA,GACpB,MAAM,OAAO,EAAE,GAAG,OAAO,CAAC;EAE9B;EACA,IAAI,QAAQ,QACV,MAAM,OAAO,QAAQ,MAAM;EAE7B,IAAI,QAAQ,MACV,MAAM,KAAK;GACT,YAAY,QAAQ,KAAK,eAAe;GACxC,UAAU,QAAQ,KAAK,aAAa;EACtC,CAAC;EAGH,MAAM,eAAe,QAAQ,QAAQ,MAAM,aAAa,QAAQ,QAAQ;EACxE,MAAM,WAAW,eAAe;EAChC,IAAI,CAAC,UACH,MAAM,IAAI,MACR,uBAAuB,aAAa,gBAAgB,iBAAiB,KAAK,IAAI,EAAE,wCAClF;EAEF,MAAM,UAAU,QAAQ,QAAQ;EAChC,MAAM,SACJ,aAAa,gBAAgB,YAAY,KAAA,IACrC,MAAM,MAAM,UAAU,cAAc,EAAE,QAAQ,CAAC,IAC/C,MAAM,MAAM,UAAU,QAAuB;EACnD,OAAO;GAAE,OAAO,IAAI,WAAW,MAAM;GAAG;EAAS;CACnD;CAEA,OAAO;EACL,IAAI;EACJ,SAAS,CACP;GACE,MAAM;IAAC;IAAa;IAAc;IAAa;IAAa;GAAY;GACxE,KAAK;IAAC;IAAU;IAAU;IAAQ;GAAgB;GAClD,SAAS;GACT;EACF,CACF;CACF;AACF;AAEA,IAAM,gBAAgB,aAA6B;CACjD,MAAM,MAAM,SAAS,YAAY,EAAE,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,GAAG,EAAE,MAAM;CACzE,OAAO,QAAQ,SAAS,QAAQ;AAClC"}
+{"version":3,"file":"jimp.cjs","names":[],"sources":["../../../../src/batteries/media/engines/jimp.ts"],"sourcesContent":["/**\n * A cross-environment image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by Jimp (pure JavaScript — no native bindings, no binaries).\n *\n * @module @nhtio/adk/batteries/media/engines/jimp\n *\n * @remarks\n * The local-by-default raster engine: runs anywhere TypeScript runs. Declares one mutate\n * capability over png/jpeg/bmp/gif/tiff with resize (cover/contain approximations), rotate,\n * flip, quality, and metadata stripping (Jimp re-encodes pixels, so EXIF never survives —\n * `strip_metadata` is inherently satisfied), plus a generation edge: `EMPTY_MIME` → a blank\n * 1024×1024 white canvas in any supported encoding (resize in the same statement —\n * `empty:png | image resize width=64`). For webp/avif output or native-speed processing,\n * compose a sharp-backed engine instead — the capability declaration is the seam.\n *\n * `jimp` is an optional peer dependency, lazily imported on first actual use (constructing\n * the engine — and therefore the pipeline — never loads it).\n */\n\nimport { EMPTY_MIME } from '../contracts'\nimport { isError } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type * as JimpNS from 'jimp'\nimport type {\n  MediaEngine,\n  MutateRequest,\n  EngineBytesResult,\n  ConvertRequest,\n  ConvertResult,\n} from '../contracts'\n\ntype JimpModule = typeof JimpNS\n\n/** Options for {@link jimpEngine}. */\nexport interface JimpEngineOptions {\n  /** Override the module resolution (tests / custom builds). Default: `import('jimp')`. */\n  jimp?: () => JimpModule | Promise<JimpModule>\n}\n\nconst SUPPORTED_OUTPUT = ['png', 'jpg', 'jpeg', 'bmp', 'gif', 'tiff'] as const\n\nconst MIME_BY_FORMAT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  bmp: 'image/bmp',\n  gif: 'image/gif',\n  tiff: 'image/tiff',\n}\n\n/**\n * Construct the Jimp-backed image engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const jimpEngine = (options: JimpEngineOptions = {}): MediaEngine => {\n  let modPromise: Promise<JimpModule> | undefined\n  const getJimp = (): Promise<JimpModule> => {\n    modPromise ??= Promise.resolve(options.jimp ? options.jimp() : import('jimp')).catch((err) => {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `the jimp engine could not load its peer dependency \"jimp\": ${detail} — install it (pnpm add jimp)`,\n      ])\n    })\n    return modPromise\n  }\n\n  const mutate = async (request: MutateRequest): Promise<EngineBytesResult> => {\n    const { Jimp } = await getJimp()\n    const image = await Jimp.read(\n      request.bytes.buffer.slice(\n        request.bytes.byteOffset,\n        request.bytes.byteOffset + request.bytes.byteLength\n      ) as ArrayBuffer\n    )\n\n    if (request.resize) {\n      const { width, height, fit } = request.resize\n      if (width !== undefined && height !== undefined) {\n        if (fit === 'cover') image.cover({ w: width, h: height })\n        else if (fit === 'contain') image.contain({ w: width, h: height })\n        else image.resize({ w: width, h: height })\n      } else if (width !== undefined) {\n        image.resize({ w: width })\n      } else if (height !== undefined) {\n        image.resize({ h: height })\n      }\n    }\n    if (request.rotate) {\n      image.rotate(request.rotate)\n    }\n    if (request.flip) {\n      image.flip({\n        horizontal: request.flip.horizontal === true,\n        vertical: request.flip.vertical === true,\n      })\n    }\n\n    const targetFormat = request.format?.to ?? mimeToFormat(request.mimeType)\n    const mimeType = MIME_BY_FORMAT[targetFormat]\n    if (!mimeType) {\n      throw new Error(\n        `jimp cannot encode \"${targetFormat}\"; supported: ${SUPPORTED_OUTPUT.join(', ')} (compose a sharp engine for webp/avif)`\n      )\n    }\n    const quality = request.format?.quality\n    const buffer =\n      mimeType === 'image/jpeg' && quality !== undefined\n        ? await image.getBuffer('image/jpeg', { quality })\n        : await image.getBuffer(mimeType as 'image/png')\n    return { bytes: new Uint8Array(buffer), mimeType }\n  }\n\n  // Generation: a blank 1024×1024 white canvas, encoded to the requested format.\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const mimeType = MIME_BY_FORMAT[request.to]\n    if (!mimeType) {\n      throw new Error(\n        `jimp cannot generate \"${request.to}\"; supported: ${SUPPORTED_OUTPUT.join(', ')}`\n      )\n    }\n    const { Jimp } = await getJimp()\n    const image = new Jimp({ width: 1024, height: 1024, color: 0xffffffff })\n    const buffer = await image.getBuffer(mimeType as 'image/png')\n    return { outputs: [{ bytes: new Uint8Array(buffer), mimeType }] }\n  }\n\n  return {\n    id: 'jimp',\n    converts: [{ from: [EMPTY_MIME], to: SUPPORTED_OUTPUT, convert }],\n    mutates: [\n      {\n        over: ['image/png', 'image/jpeg', 'image/bmp', 'image/gif', 'image/tiff'],\n        ops: ['resize', 'rotate', 'flip', 'strip_metadata'],\n        encodes: SUPPORTED_OUTPUT,\n        mutate,\n      },\n    ],\n  }\n}\n\nconst mimeToFormat = (mimeType: string): string => {\n  const sub = mimeType.toLowerCase().split(';')[0].trim().split('/')[1] ?? 'png'\n  return sub === 'jpeg' ? 'jpg' : sub\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAM,mBAAmB;CAAC;CAAO;CAAO;CAAQ;CAAO;CAAO;AAAM;AAEpE,IAAM,iBAAyC;CAC7C,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACL,KAAK;CACL,MAAM;AACR;;;;;;;AAQA,IAAa,cAAc,UAA6B,CAAC,MAAmB;CAC1E,IAAI;CACJ,MAAM,gBAAqC;EACzC,eAAe,QAAQ,QAAQ,QAAQ,OAAO,QAAQ,KAAK,IAAI,OAAO,OAAO,EAAE,OAAO,QAAQ;GAE5F,MAAM,IAAI,mBAAA,gCAAgC,CACxC,8DAFa,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiB,8BACvE,CAAC;EACH,CAAC;EACD,OAAO;CACT;CAEA,MAAM,SAAS,OAAO,YAAuD;EAC3E,MAAM,EAAE,SAAS,MAAM,QAAQ;EAC/B,MAAM,QAAQ,MAAM,KAAK,KACvB,QAAQ,MAAM,OAAO,MACnB,QAAQ,MAAM,YACd,QAAQ,MAAM,aAAa,QAAQ,MAAM,UAC3C,CACF;EAEA,IAAI,QAAQ,QAAQ;GAClB,MAAM,EAAE,OAAO,QAAQ,QAAQ,QAAQ;GACvC,IAAI,UAAU,KAAA,KAAa,WAAW,KAAA,GACpC,IAAI,QAAQ,SAAS,MAAM,MAAM;IAAE,GAAG;IAAO,GAAG;GAAO,CAAC;QACnD,IAAI,QAAQ,WAAW,MAAM,QAAQ;IAAE,GAAG;IAAO,GAAG;GAAO,CAAC;QAC5D,MAAM,OAAO;IAAE,GAAG;IAAO,GAAG;GAAO,CAAC;QACpC,IAAI,UAAU,KAAA,GACnB,MAAM,OAAO,EAAE,GAAG,MAAM,CAAC;QACpB,IAAI,WAAW,KAAA,GACpB,MAAM,OAAO,EAAE,GAAG,OAAO,CAAC;EAE9B;EACA,IAAI,QAAQ,QACV,MAAM,OAAO,QAAQ,MAAM;EAE7B,IAAI,QAAQ,MACV,MAAM,KAAK;GACT,YAAY,QAAQ,KAAK,eAAe;GACxC,UAAU,QAAQ,KAAK,aAAa;EACtC,CAAC;EAGH,MAAM,eAAe,QAAQ,QAAQ,MAAM,aAAa,QAAQ,QAAQ;EACxE,MAAM,WAAW,eAAe;EAChC,IAAI,CAAC,UACH,MAAM,IAAI,MACR,uBAAuB,aAAa,gBAAgB,iBAAiB,KAAK,IAAI,EAAE,wCAClF;EAEF,MAAM,UAAU,QAAQ,QAAQ;EAChC,MAAM,SACJ,aAAa,gBAAgB,YAAY,KAAA,IACrC,MAAM,MAAM,UAAU,cAAc,EAAE,QAAQ,CAAC,IAC/C,MAAM,MAAM,UAAU,QAAuB;EACnD,OAAO;GAAE,OAAO,IAAI,WAAW,MAAM;GAAG;EAAS;CACnD;CAGA,MAAM,UAAU,OAAO,YAAoD;EACzE,MAAM,WAAW,eAAe,QAAQ;EACxC,IAAI,CAAC,UACH,MAAM,IAAI,MACR,yBAAyB,QAAQ,GAAG,gBAAgB,iBAAiB,KAAK,IAAI,GAChF;EAEF,MAAM,EAAE,SAAS,MAAM,QAAQ;EAE/B,MAAM,SAAS,MAAM,IADH,KAAK;GAAE,OAAO;GAAM,QAAQ;GAAM,OAAO;EAAW,CACjD,EAAM,UAAU,QAAuB;EAC5D,OAAO,EAAE,SAAS,CAAC;GAAE,OAAO,IAAI,WAAW,MAAM;GAAG;EAAS,CAAC,EAAE;CAClE;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CAAC;GAAE,MAAM,CAAC,kCAAA,UAAU;GAAG,IAAI;GAAkB;EAAQ,CAAC;EAChE,SAAS,CACP;GACE,MAAM;IAAC;IAAa;IAAc;IAAa;IAAa;GAAY;GACxE,KAAK;IAAC;IAAU;IAAU;IAAQ;GAAgB;GAClD,SAAS;GACT;EACF,CACF;CACF;AACF;AAEA,IAAM,gBAAgB,aAA6B;CACjD,MAAM,MAAM,SAAS,YAAY,EAAE,MAAM,GAAG,EAAE,GAAG,KAAK,EAAE,MAAM,GAAG,EAAE,MAAM;CACzE,OAAO,QAAQ,SAAS,QAAQ;AAClC"}

package/batteries/media/engines/jimp.d.ts

@@ -8,7 +8,9 @@
  * The local-by-default raster engine: runs anywhere TypeScript runs. Declares one mutate
  * capability over png/jpeg/bmp/gif/tiff with resize (cover/contain approximations), rotate,
  * flip, quality, and metadata stripping (Jimp re-encodes pixels, so EXIF never survives —
- * `strip_metadata` is inherently satisfied). For webp/avif output or native-speed processing,
+ * `strip_metadata` is inherently satisfied), plus a generation edge: `EMPTY_MIME` → a blank
+ * 1024×1024 white canvas in any supported encoding (resize in the same statement —
+ * `empty:png | image resize width=64`). For webp/avif output or native-speed processing,
  * compose a sharp-backed engine instead — the capability declaration is the seam.
  *
  * `jimp` is an optional peer dependency, lazily imported on first actual use (constructing

package/batteries/media/engines/jimp.mjs

@@ -1,5 +1,6 @@
-import { o as isError } from "../../../tool_registry-BaLUIzWz.mjs";
+import { o as isError } from "../../../tool_registry-CZ55mIti.mjs";
 import "../../../guards.mjs";
+import { EMPTY_MIME } from "../contracts.mjs";
 import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4Ofs.mjs";
 //#region src/batteries/media/engines/jimp.ts
 /**
@@ -12,7 +13,9 @@ import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4O
 * The local-by-default raster engine: runs anywhere TypeScript runs. Declares one mutate
 * capability over png/jpeg/bmp/gif/tiff with resize (cover/contain approximations), rotate,
 * flip, quality, and metadata stripping (Jimp re-encodes pixels, so EXIF never survives —
-* `strip_metadata` is inherently satisfied). For webp/avif output or native-speed processing,
+* `strip_metadata` is inherently satisfied), plus a generation edge: `EMPTY_MIME` → a blank
+* 1024×1024 white canvas in any supported encoding (resize in the same statement —
+* `empty:png | image resize width=64`). For webp/avif output or native-speed processing,
 * compose a sharp-backed engine instead — the capability declaration is the seam.
 *
 * `jimp` is an optional peer dependency, lazily imported on first actual use (constructing
@@ -83,8 +86,27 @@ var jimpEngine = (options = {}) => {
 			mimeType
 		};
 	};
+	const convert = async (request) => {
+		const mimeType = MIME_BY_FORMAT[request.to];
+		if (!mimeType) throw new Error(`jimp cannot generate "${request.to}"; supported: ${SUPPORTED_OUTPUT.join(", ")}`);
+		const { Jimp } = await getJimp();
+		const buffer = await new Jimp({
+			width: 1024,
+			height: 1024,
+			color: 4294967295
+		}).getBuffer(mimeType);
+		return { outputs: [{
+			bytes: new Uint8Array(buffer),
+			mimeType
+		}] };
+	};
 	return {
 		id: "jimp",
+		converts: [{
+			from: [EMPTY_MIME],
+			to: SUPPORTED_OUTPUT,
+			convert
+		}],
 		mutates: [{
 			over: [
 				"image/png",