@nhtio/adk 1.20260609.0 → 1.20260610.0

package/batteries/media/engines/jimp.cjs

@@ -0,0 +1,116 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+require("../../../guards.cjs");
+const require_exceptions = require("../../../exceptions-CQi_lNs1.js");
+//#region src/batteries/media/engines/jimp.ts
+/**
+* A cross-environment image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by Jimp (pure JavaScript — no native bindings, no binaries).
+*
+* @module @nhtio/adk/batteries/media/engines/jimp
+*
+* @remarks
+* 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,
+* 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
+* the engine — and therefore the pipeline — never loads it).
+*/
+var SUPPORTED_OUTPUT = [
+	"png",
+	"jpg",
+	"jpeg",
+	"bmp",
+	"gif",
+	"tiff"
+];
+var MIME_BY_FORMAT = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	bmp: "image/bmp",
+	gif: "image/gif",
+	tiff: "image/tiff"
+};
+/**
+* Construct the Jimp-backed image engine.
+*
+* @param options - Optional module resolver override.
+* @returns The engine.
+*/
+var jimpEngine = (options = {}) => {
+	let modPromise;
+	const getJimp = () => {
+		modPromise ??= Promise.resolve(options.jimp ? options.jimp() : import("jimp")).catch((err) => {
+			throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`the jimp engine could not load its peer dependency "jimp": ${require_tool_registry.isError(err) ? err.message : String(err)} — install it (pnpm add jimp)`]);
+		});
+		return modPromise;
+	};
+	const mutate = async (request) => {
+		const { Jimp } = await getJimp();
+		const image = await Jimp.read(request.bytes.buffer.slice(request.bytes.byteOffset, request.bytes.byteOffset + request.bytes.byteLength));
+		if (request.resize) {
+			const { width, height, fit } = request.resize;
+			if (width !== void 0 && height !== void 0) if (fit === "cover") image.cover({
+				w: width,
+				h: height
+			});
+			else if (fit === "contain") image.contain({
+				w: width,
+				h: height
+			});
+			else image.resize({
+				w: width,
+				h: height
+			});
+			else if (width !== void 0) image.resize({ w: width });
+			else if (height !== void 0) image.resize({ h: height });
+		}
+		if (request.rotate) image.rotate(request.rotate);
+		if (request.flip) image.flip({
+			horizontal: request.flip.horizontal === true,
+			vertical: request.flip.vertical === true
+		});
+		const targetFormat = request.format?.to ?? mimeToFormat(request.mimeType);
+		const mimeType = MIME_BY_FORMAT[targetFormat];
+		if (!mimeType) throw new Error(`jimp cannot encode "${targetFormat}"; supported: ${SUPPORTED_OUTPUT.join(", ")} (compose a sharp engine for webp/avif)`);
+		const quality = request.format?.quality;
+		const buffer = mimeType === "image/jpeg" && quality !== void 0 ? await image.getBuffer("image/jpeg", { quality }) : await image.getBuffer(mimeType);
+		return {
+			bytes: new Uint8Array(buffer),
+			mimeType
+		};
+	};
+	return {
+		id: "jimp",
+		mutates: [{
+			over: [
+				"image/png",
+				"image/jpeg",
+				"image/bmp",
+				"image/gif",
+				"image/tiff"
+			],
+			ops: [
+				"resize",
+				"rotate",
+				"flip",
+				"strip_metadata"
+			],
+			encodes: SUPPORTED_OUTPUT,
+			mutate
+		}]
+	};
+};
+var mimeToFormat = (mimeType) => {
+	const sub = mimeType.toLowerCase().split(";")[0].trim().split("/")[1] ?? "png";
+	return sub === "jpeg" ? "jpg" : sub;
+};
+//#endregion
+exports.jimpEngine = jimpEngine;
+
+//# sourceMappingURL=jimp.cjs.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,32 @@
+/**
+ * A cross-environment image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+ * backed by Jimp (pure JavaScript — no native bindings, no binaries).
+ *
+ * @module @nhtio/adk/batteries/media/engines/jimp
+ *
+ * @remarks
+ * 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,
+ * 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
+ * the engine — and therefore the pipeline — never loads it).
+ */
+import type * as JimpNS from 'jimp';
+import type { MediaEngine } from "../contracts";
+type JimpModule = typeof JimpNS;
+/** Options for {@link jimpEngine}. */
+export interface JimpEngineOptions {
+    /** Override the module resolution (tests / custom builds). Default: `import('jimp')`. */
+    jimp?: () => JimpModule | Promise<JimpModule>;
+}
+/**
+ * Construct the Jimp-backed image engine.
+ *
+ * @param options - Optional module resolver override.
+ * @returns The engine.
+ */
+export declare const jimpEngine: (options?: JimpEngineOptions) => MediaEngine;
+export {};

package/batteries/media/engines/jimp.mjs

@@ -0,0 +1,114 @@
+import { o as isError } from "../../../tool_registry-791Vrjtf.mjs";
+import "../../../guards.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/engines/jimp.ts
+/**
+* A cross-environment image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by Jimp (pure JavaScript — no native bindings, no binaries).
+*
+* @module @nhtio/adk/batteries/media/engines/jimp
+*
+* @remarks
+* 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,
+* 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
+* the engine — and therefore the pipeline — never loads it).
+*/
+var SUPPORTED_OUTPUT = [
+	"png",
+	"jpg",
+	"jpeg",
+	"bmp",
+	"gif",
+	"tiff"
+];
+var MIME_BY_FORMAT = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	bmp: "image/bmp",
+	gif: "image/gif",
+	tiff: "image/tiff"
+};
+/**
+* Construct the Jimp-backed image engine.
+*
+* @param options - Optional module resolver override.
+* @returns The engine.
+*/
+var jimpEngine = (options = {}) => {
+	let modPromise;
+	const getJimp = () => {
+		modPromise ??= Promise.resolve(options.jimp ? options.jimp() : import("jimp")).catch((err) => {
+			throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`the jimp engine could not load its peer dependency "jimp": ${isError(err) ? err.message : String(err)} — install it (pnpm add jimp)`]);
+		});
+		return modPromise;
+	};
+	const mutate = async (request) => {
+		const { Jimp } = await getJimp();
+		const image = await Jimp.read(request.bytes.buffer.slice(request.bytes.byteOffset, request.bytes.byteOffset + request.bytes.byteLength));
+		if (request.resize) {
+			const { width, height, fit } = request.resize;
+			if (width !== void 0 && height !== void 0) if (fit === "cover") image.cover({
+				w: width,
+				h: height
+			});
+			else if (fit === "contain") image.contain({
+				w: width,
+				h: height
+			});
+			else image.resize({
+				w: width,
+				h: height
+			});
+			else if (width !== void 0) image.resize({ w: width });
+			else if (height !== void 0) image.resize({ h: height });
+		}
+		if (request.rotate) image.rotate(request.rotate);
+		if (request.flip) image.flip({
+			horizontal: request.flip.horizontal === true,
+			vertical: request.flip.vertical === true
+		});
+		const targetFormat = request.format?.to ?? mimeToFormat(request.mimeType);
+		const mimeType = MIME_BY_FORMAT[targetFormat];
+		if (!mimeType) throw new Error(`jimp cannot encode "${targetFormat}"; supported: ${SUPPORTED_OUTPUT.join(", ")} (compose a sharp engine for webp/avif)`);
+		const quality = request.format?.quality;
+		const buffer = mimeType === "image/jpeg" && quality !== void 0 ? await image.getBuffer("image/jpeg", { quality }) : await image.getBuffer(mimeType);
+		return {
+			bytes: new Uint8Array(buffer),
+			mimeType
+		};
+	};
+	return {
+		id: "jimp",
+		mutates: [{
+			over: [
+				"image/png",
+				"image/jpeg",
+				"image/bmp",
+				"image/gif",
+				"image/tiff"
+			],
+			ops: [
+				"resize",
+				"rotate",
+				"flip",
+				"strip_metadata"
+			],
+			encodes: SUPPORTED_OUTPUT,
+			mutate
+		}]
+	};
+};
+var mimeToFormat = (mimeType) => {
+	const sub = mimeType.toLowerCase().split(";")[0].trim().split("/")[1] ?? "png";
+	return sub === "jpeg" ? "jpg" : sub;
+};
+//#endregion
+export { jimpEngine };
+
+//# sourceMappingURL=jimp.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"jimp.mjs","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,gCAAgC,CACxC,8DAFa,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"}

package/batteries/media/engines/sharp.cjs

@@ -0,0 +1,120 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+require("../../../guards.cjs");
+const require_exceptions = require("../../../exceptions-CQi_lNs1.js");
+//#region src/batteries/media/engines/sharp.ts
+/**
+* A Node-native image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by sharp (libvips bindings — fast, full-format).
+*
+* @module @nhtio/adk/batteries/media/engines/sharp
+*
+* @remarks
+* The performance/fidelity engine for Node deployments: native speed plus webp/avif output
+* and the full `fit` mode set. sharp is permanently Node-only (native bindings); for a
+* cross-environment engine compose the jimp implementation instead — the capability
+* declaration is the seam, and BYO instances adapt via {@link fromSharp}.
+*
+* `sharp` is an optional peer dependency, lazily imported on first actual use.
+*/
+var SUPPORTED_OUTPUT = [
+	"png",
+	"jpg",
+	"jpeg",
+	"webp",
+	"tiff",
+	"avif",
+	"gif"
+];
+var MIME_BY_FORMAT = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	tiff: "image/tiff",
+	avif: "image/avif",
+	gif: "image/gif"
+};
+var resolveSharp = async (supplied) => {
+	try {
+		const mod = await (supplied ? supplied() : import("sharp"));
+		const fn = typeof mod === "function" ? mod : mod.default;
+		if (typeof fn !== "function") throw new Error("sharp did not resolve to a function");
+		return fn;
+	} catch (err) {
+		throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`the sharp engine could not load its peer dependency "sharp": ${require_tool_registry.isError(err) ? err.message : String(err)} — install it (pnpm add sharp); note sharp is Node-only`]);
+	}
+};
+/** Run a fused mutate request through a sharp instance function. */
+var runTransform = async (sharp, request) => {
+	let img = sharp(request.bytes);
+	if (request.rotate) img = img.rotate(request.rotate);
+	if (request.flip?.vertical) img = img.flip();
+	if (request.flip?.horizontal) img = img.flop();
+	if (request.resize && (request.resize.width !== void 0 || request.resize.height !== void 0)) img = img.resize({
+		width: request.resize.width,
+		height: request.resize.height,
+		fit: request.resize.fit ?? "cover"
+	});
+	const target = request.format?.to ?? mimeToFormat(request.mimeType);
+	const mimeType = MIME_BY_FORMAT[target];
+	if (!mimeType) throw new Error(`sharp cannot encode "${target}"; supported: ${SUPPORTED_OUTPUT.join(", ")}`);
+	const formatKey = target === "jpg" ? "jpeg" : target;
+	img = img.toFormat(formatKey, request.format?.quality !== void 0 ? { quality: request.format.quality } : {});
+	if (request.stripMetadata !== true) img = img.keepMetadata();
+	const buffer = await img.toBuffer();
+	return {
+		bytes: new Uint8Array(buffer),
+		mimeType
+	};
+};
+/** Build the single mutate capability over a sharp source. */
+var capabilityOf = (run) => ({
+	over: ["image/*"],
+	ops: [
+		"resize",
+		"rotate",
+		"flip",
+		"strip_metadata"
+	],
+	encodes: SUPPORTED_OUTPUT,
+	mutate: run
+});
+/**
+* Construct the sharp-backed image engine.
+*
+* @param options - Optional module resolver override.
+* @returns The engine.
+*/
+var sharpEngine = (options = {}) => {
+	let sharpPromise;
+	const getSharp = () => {
+		sharpPromise ??= resolveSharp(options.sharp);
+		return sharpPromise;
+	};
+	return {
+		id: "sharp",
+		mutates: [capabilityOf(async (request) => runTransform(await getSharp(), request))]
+	};
+};
+/**
+* Adapt an already-configured sharp module (your import, your build flags) to the engine
+* contract — the BYO transformer.
+*
+* @param sharp - The sharp function you imported.
+* @returns The engine.
+*/
+var fromSharp = (sharp) => ({
+	id: "sharp",
+	mutates: [capabilityOf(async (request) => runTransform(sharp, request))]
+});
+var mimeToFormat = (mimeType) => {
+	const sub = mimeType.toLowerCase().split(";")[0].trim().split("/")[1] ?? "png";
+	return sub === "jpeg" ? "jpg" : sub;
+};
+//#endregion
+exports.fromSharp = fromSharp;
+exports.sharpEngine = sharpEngine;
+
+//# sourceMappingURL=sharp.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharp.cjs","names":[],"sources":["../../../../src/batteries/media/engines/sharp.ts"],"sourcesContent":["/**\n * A Node-native image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by sharp (libvips bindings — fast, full-format).\n *\n * @module @nhtio/adk/batteries/media/engines/sharp\n *\n * @remarks\n * The performance/fidelity engine for Node deployments: native speed plus webp/avif output\n * and the full `fit` mode set. sharp is permanently Node-only (native bindings); for a\n * cross-environment engine compose the jimp implementation instead — the capability\n * declaration is the seam, and BYO instances adapt via {@link fromSharp}.\n *\n * `sharp` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { default as SharpDefault } from 'sharp'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { MediaEngine, MutateCapability, MutateRequest, EngineBytesResult } from '../contracts'\n\ntype SharpFn = typeof SharpDefault\n\n/** Options for {@link sharpEngine}. */\nexport interface SharpEngineOptions {\n  /** Override the module resolution (electron/custom builds). Default: `import('sharp')`. */\n  sharp?: () => SharpFn | { default: SharpFn } | Promise<SharpFn | { default: SharpFn }>\n}\n\nconst SUPPORTED_OUTPUT = ['png', 'jpg', 'jpeg', 'webp', 'tiff', 'avif', 'gif'] as const\n\nconst MIME_BY_FORMAT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  webp: 'image/webp',\n  tiff: 'image/tiff',\n  avif: 'image/avif',\n  gif: 'image/gif',\n}\n\nconst resolveSharp = async (supplied: SharpEngineOptions['sharp']): Promise<SharpFn> => {\n  try {\n    const mod = await (supplied ? supplied() : import('sharp'))\n    const fn = typeof mod === 'function' ? mod : (mod as { default: SharpFn }).default\n    if (typeof fn !== 'function') throw new Error('sharp did not resolve to a function')\n    return fn\n  } catch (err) {\n    const detail = isError(err) ? err.message : String(err)\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      `the sharp engine could not load its peer dependency \"sharp\": ${detail} — install it (pnpm add sharp); note sharp is Node-only`,\n    ])\n  }\n}\n\n/** Run a fused mutate request through a sharp instance function. */\nconst runTransform = async (sharp: SharpFn, request: MutateRequest): Promise<EngineBytesResult> => {\n  let img = sharp(request.bytes)\n  if (request.rotate) img = img.rotate(request.rotate)\n  if (request.flip?.vertical) img = img.flip()\n  if (request.flip?.horizontal) img = img.flop()\n  if (\n    request.resize &&\n    (request.resize.width !== undefined || request.resize.height !== undefined)\n  ) {\n    img = img.resize({\n      width: request.resize.width,\n      height: request.resize.height,\n      fit: request.resize.fit ?? 'cover',\n    })\n  }\n  const target = request.format?.to ?? mimeToFormat(request.mimeType)\n  const mimeType = MIME_BY_FORMAT[target]\n  if (!mimeType) {\n    throw new Error(`sharp cannot encode \"${target}\"; supported: ${SUPPORTED_OUTPUT.join(', ')}`)\n  }\n  const formatKey = (target === 'jpg' ? 'jpeg' : target) as\n    | 'png'\n    | 'jpeg'\n    | 'webp'\n    | 'tiff'\n    | 'avif'\n    | 'gif'\n  img = img.toFormat(\n    formatKey,\n    request.format?.quality !== undefined ? { quality: request.format.quality } : {}\n  )\n  if (request.stripMetadata !== true) {\n    // sharp strips metadata by default; keep it when NOT asked to strip.\n    img = img.keepMetadata()\n  }\n  const buffer = await img.toBuffer()\n  return { bytes: new Uint8Array(buffer), mimeType }\n}\n\n/** Build the single mutate capability over a sharp source. */\nconst capabilityOf = (\n  run: (request: MutateRequest) => Promise<EngineBytesResult>\n): MutateCapability => ({\n  over: ['image/*'],\n  ops: ['resize', 'rotate', 'flip', 'strip_metadata'],\n  encodes: SUPPORTED_OUTPUT,\n  mutate: run,\n})\n\n/**\n * Construct the sharp-backed image engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const sharpEngine = (options: SharpEngineOptions = {}): MediaEngine => {\n  let sharpPromise: Promise<SharpFn> | undefined\n  const getSharp = (): Promise<SharpFn> => {\n    sharpPromise ??= resolveSharp(options.sharp)\n    return sharpPromise\n  }\n  return {\n    id: 'sharp',\n    mutates: [capabilityOf(async (request) => runTransform(await getSharp(), request))],\n  }\n}\n\n/**\n * Adapt an already-configured sharp module (your import, your build flags) to the engine\n * contract — the BYO transformer.\n *\n * @param sharp - The sharp function you imported.\n * @returns The engine.\n */\nexport const fromSharp = (sharp: SharpFn): MediaEngine => ({\n  id: 'sharp',\n  mutates: [capabilityOf(async (request) => runTransform(sharp, request))],\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":";;;;;;;;;;;;;;;;;;;;AA4BA,IAAM,mBAAmB;CAAC;CAAO;CAAO;CAAQ;CAAQ;CAAQ;CAAQ;AAAK;AAE7E,IAAM,iBAAyC;CAC7C,KAAK;CACL,KAAK;CACL,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,KAAK;AACP;AAEA,IAAM,eAAe,OAAO,aAA4D;CACtF,IAAI;EACF,MAAM,MAAM,OAAO,WAAW,SAAS,IAAI,OAAO;EAClD,MAAM,KAAK,OAAO,QAAQ,aAAa,MAAO,IAA6B;EAC3E,IAAI,OAAO,OAAO,YAAY,MAAM,IAAI,MAAM,qCAAqC;EACnF,OAAO;CACT,SAAS,KAAK;EAEZ,MAAM,IAAI,mBAAA,gCAAgC,CACxC,gEAFa,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEmB,wDACzE,CAAC;CACH;AACF;;AAGA,IAAM,eAAe,OAAO,OAAgB,YAAuD;CACjG,IAAI,MAAM,MAAM,QAAQ,KAAK;CAC7B,IAAI,QAAQ,QAAQ,MAAM,IAAI,OAAO,QAAQ,MAAM;CACnD,IAAI,QAAQ,MAAM,UAAU,MAAM,IAAI,KAAK;CAC3C,IAAI,QAAQ,MAAM,YAAY,MAAM,IAAI,KAAK;CAC7C,IACE,QAAQ,WACP,QAAQ,OAAO,UAAU,KAAA,KAAa,QAAQ,OAAO,WAAW,KAAA,IAEjE,MAAM,IAAI,OAAO;EACf,OAAO,QAAQ,OAAO;EACtB,QAAQ,QAAQ,OAAO;EACvB,KAAK,QAAQ,OAAO,OAAO;CAC7B,CAAC;CAEH,MAAM,SAAS,QAAQ,QAAQ,MAAM,aAAa,QAAQ,QAAQ;CAClE,MAAM,WAAW,eAAe;CAChC,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,wBAAwB,OAAO,gBAAgB,iBAAiB,KAAK,IAAI,GAAG;CAE9F,MAAM,YAAa,WAAW,QAAQ,SAAS;CAO/C,MAAM,IAAI,SACR,WACA,QAAQ,QAAQ,YAAY,KAAA,IAAY,EAAE,SAAS,QAAQ,OAAO,QAAQ,IAAI,CAAC,CACjF;CACA,IAAI,QAAQ,kBAAkB,MAE5B,MAAM,IAAI,aAAa;CAEzB,MAAM,SAAS,MAAM,IAAI,SAAS;CAClC,OAAO;EAAE,OAAO,IAAI,WAAW,MAAM;EAAG;CAAS;AACnD;;AAGA,IAAM,gBACJ,SACsB;CACtB,MAAM,CAAC,SAAS;CAChB,KAAK;EAAC;EAAU;EAAU;EAAQ;CAAgB;CAClD,SAAS;CACT,QAAQ;AACV;;;;;;;AAQA,IAAa,eAAe,UAA8B,CAAC,MAAmB;CAC5E,IAAI;CACJ,MAAM,iBAAmC;EACvC,iBAAiB,aAAa,QAAQ,KAAK;EAC3C,OAAO;CACT;CACA,OAAO;EACL,IAAI;EACJ,SAAS,CAAC,aAAa,OAAO,YAAY,aAAa,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC;CACpF;AACF;;;;;;;;AASA,IAAa,aAAa,WAAiC;CACzD,IAAI;CACJ,SAAS,CAAC,aAAa,OAAO,YAAY,aAAa,OAAO,OAAO,CAAC,CAAC;AACzE;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/sharp.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A Node-native image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+ * backed by sharp (libvips bindings — fast, full-format).
+ *
+ * @module @nhtio/adk/batteries/media/engines/sharp
+ *
+ * @remarks
+ * The performance/fidelity engine for Node deployments: native speed plus webp/avif output
+ * and the full `fit` mode set. sharp is permanently Node-only (native bindings); for a
+ * cross-environment engine compose the jimp implementation instead — the capability
+ * declaration is the seam, and BYO instances adapt via {@link fromSharp}.
+ *
+ * `sharp` is an optional peer dependency, lazily imported on first actual use.
+ */
+import { default as SharpDefault } from 'sharp';
+import type { MediaEngine } from "../contracts";
+type SharpFn = typeof SharpDefault;
+/** Options for {@link sharpEngine}. */
+export interface SharpEngineOptions {
+    /** Override the module resolution (electron/custom builds). Default: `import('sharp')`. */
+    sharp?: () => SharpFn | {
+        default: SharpFn;
+    } | Promise<SharpFn | {
+        default: SharpFn;
+    }>;
+}
+/**
+ * Construct the sharp-backed image engine.
+ *
+ * @param options - Optional module resolver override.
+ * @returns The engine.
+ */
+export declare const sharpEngine: (options?: SharpEngineOptions) => MediaEngine;
+/**
+ * Adapt an already-configured sharp module (your import, your build flags) to the engine
+ * contract — the BYO transformer.
+ *
+ * @param sharp - The sharp function you imported.
+ * @returns The engine.
+ */
+export declare const fromSharp: (sharp: SharpFn) => MediaEngine;
+export {};

package/batteries/media/engines/sharp.mjs

@@ -0,0 +1,117 @@
+import { o as isError } from "../../../tool_registry-791Vrjtf.mjs";
+import "../../../guards.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/engines/sharp.ts
+/**
+* A Node-native image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by sharp (libvips bindings — fast, full-format).
+*
+* @module @nhtio/adk/batteries/media/engines/sharp
+*
+* @remarks
+* The performance/fidelity engine for Node deployments: native speed plus webp/avif output
+* and the full `fit` mode set. sharp is permanently Node-only (native bindings); for a
+* cross-environment engine compose the jimp implementation instead — the capability
+* declaration is the seam, and BYO instances adapt via {@link fromSharp}.
+*
+* `sharp` is an optional peer dependency, lazily imported on first actual use.
+*/
+var SUPPORTED_OUTPUT = [
+	"png",
+	"jpg",
+	"jpeg",
+	"webp",
+	"tiff",
+	"avif",
+	"gif"
+];
+var MIME_BY_FORMAT = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	tiff: "image/tiff",
+	avif: "image/avif",
+	gif: "image/gif"
+};
+var resolveSharp = async (supplied) => {
+	try {
+		const mod = await (supplied ? supplied() : import("sharp"));
+		const fn = typeof mod === "function" ? mod : mod.default;
+		if (typeof fn !== "function") throw new Error("sharp did not resolve to a function");
+		return fn;
+	} catch (err) {
+		throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`the sharp engine could not load its peer dependency "sharp": ${isError(err) ? err.message : String(err)} — install it (pnpm add sharp); note sharp is Node-only`]);
+	}
+};
+/** Run a fused mutate request through a sharp instance function. */
+var runTransform = async (sharp, request) => {
+	let img = sharp(request.bytes);
+	if (request.rotate) img = img.rotate(request.rotate);
+	if (request.flip?.vertical) img = img.flip();
+	if (request.flip?.horizontal) img = img.flop();
+	if (request.resize && (request.resize.width !== void 0 || request.resize.height !== void 0)) img = img.resize({
+		width: request.resize.width,
+		height: request.resize.height,
+		fit: request.resize.fit ?? "cover"
+	});
+	const target = request.format?.to ?? mimeToFormat(request.mimeType);
+	const mimeType = MIME_BY_FORMAT[target];
+	if (!mimeType) throw new Error(`sharp cannot encode "${target}"; supported: ${SUPPORTED_OUTPUT.join(", ")}`);
+	const formatKey = target === "jpg" ? "jpeg" : target;
+	img = img.toFormat(formatKey, request.format?.quality !== void 0 ? { quality: request.format.quality } : {});
+	if (request.stripMetadata !== true) img = img.keepMetadata();
+	const buffer = await img.toBuffer();
+	return {
+		bytes: new Uint8Array(buffer),
+		mimeType
+	};
+};
+/** Build the single mutate capability over a sharp source. */
+var capabilityOf = (run) => ({
+	over: ["image/*"],
+	ops: [
+		"resize",
+		"rotate",
+		"flip",
+		"strip_metadata"
+	],
+	encodes: SUPPORTED_OUTPUT,
+	mutate: run
+});
+/**
+* Construct the sharp-backed image engine.
+*
+* @param options - Optional module resolver override.
+* @returns The engine.
+*/
+var sharpEngine = (options = {}) => {
+	let sharpPromise;
+	const getSharp = () => {
+		sharpPromise ??= resolveSharp(options.sharp);
+		return sharpPromise;
+	};
+	return {
+		id: "sharp",
+		mutates: [capabilityOf(async (request) => runTransform(await getSharp(), request))]
+	};
+};
+/**
+* Adapt an already-configured sharp module (your import, your build flags) to the engine
+* contract — the BYO transformer.
+*
+* @param sharp - The sharp function you imported.
+* @returns The engine.
+*/
+var fromSharp = (sharp) => ({
+	id: "sharp",
+	mutates: [capabilityOf(async (request) => runTransform(sharp, request))]
+});
+var mimeToFormat = (mimeType) => {
+	const sub = mimeType.toLowerCase().split(";")[0].trim().split("/")[1] ?? "png";
+	return sub === "jpeg" ? "jpg" : sub;
+};
+//#endregion
+export { fromSharp, sharpEngine };
+
+//# sourceMappingURL=sharp.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sharp.mjs","names":[],"sources":["../../../../src/batteries/media/engines/sharp.ts"],"sourcesContent":["/**\n * A Node-native image {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by sharp (libvips bindings — fast, full-format).\n *\n * @module @nhtio/adk/batteries/media/engines/sharp\n *\n * @remarks\n * The performance/fidelity engine for Node deployments: native speed plus webp/avif output\n * and the full `fit` mode set. sharp is permanently Node-only (native bindings); for a\n * cross-environment engine compose the jimp implementation instead — the capability\n * declaration is the seam, and BYO instances adapt via {@link fromSharp}.\n *\n * `sharp` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { default as SharpDefault } from 'sharp'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { MediaEngine, MutateCapability, MutateRequest, EngineBytesResult } from '../contracts'\n\ntype SharpFn = typeof SharpDefault\n\n/** Options for {@link sharpEngine}. */\nexport interface SharpEngineOptions {\n  /** Override the module resolution (electron/custom builds). Default: `import('sharp')`. */\n  sharp?: () => SharpFn | { default: SharpFn } | Promise<SharpFn | { default: SharpFn }>\n}\n\nconst SUPPORTED_OUTPUT = ['png', 'jpg', 'jpeg', 'webp', 'tiff', 'avif', 'gif'] as const\n\nconst MIME_BY_FORMAT: Record<string, string> = {\n  png: 'image/png',\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  webp: 'image/webp',\n  tiff: 'image/tiff',\n  avif: 'image/avif',\n  gif: 'image/gif',\n}\n\nconst resolveSharp = async (supplied: SharpEngineOptions['sharp']): Promise<SharpFn> => {\n  try {\n    const mod = await (supplied ? supplied() : import('sharp'))\n    const fn = typeof mod === 'function' ? mod : (mod as { default: SharpFn }).default\n    if (typeof fn !== 'function') throw new Error('sharp did not resolve to a function')\n    return fn\n  } catch (err) {\n    const detail = isError(err) ? err.message : String(err)\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      `the sharp engine could not load its peer dependency \"sharp\": ${detail} — install it (pnpm add sharp); note sharp is Node-only`,\n    ])\n  }\n}\n\n/** Run a fused mutate request through a sharp instance function. */\nconst runTransform = async (sharp: SharpFn, request: MutateRequest): Promise<EngineBytesResult> => {\n  let img = sharp(request.bytes)\n  if (request.rotate) img = img.rotate(request.rotate)\n  if (request.flip?.vertical) img = img.flip()\n  if (request.flip?.horizontal) img = img.flop()\n  if (\n    request.resize &&\n    (request.resize.width !== undefined || request.resize.height !== undefined)\n  ) {\n    img = img.resize({\n      width: request.resize.width,\n      height: request.resize.height,\n      fit: request.resize.fit ?? 'cover',\n    })\n  }\n  const target = request.format?.to ?? mimeToFormat(request.mimeType)\n  const mimeType = MIME_BY_FORMAT[target]\n  if (!mimeType) {\n    throw new Error(`sharp cannot encode \"${target}\"; supported: ${SUPPORTED_OUTPUT.join(', ')}`)\n  }\n  const formatKey = (target === 'jpg' ? 'jpeg' : target) as\n    | 'png'\n    | 'jpeg'\n    | 'webp'\n    | 'tiff'\n    | 'avif'\n    | 'gif'\n  img = img.toFormat(\n    formatKey,\n    request.format?.quality !== undefined ? { quality: request.format.quality } : {}\n  )\n  if (request.stripMetadata !== true) {\n    // sharp strips metadata by default; keep it when NOT asked to strip.\n    img = img.keepMetadata()\n  }\n  const buffer = await img.toBuffer()\n  return { bytes: new Uint8Array(buffer), mimeType }\n}\n\n/** Build the single mutate capability over a sharp source. */\nconst capabilityOf = (\n  run: (request: MutateRequest) => Promise<EngineBytesResult>\n): MutateCapability => ({\n  over: ['image/*'],\n  ops: ['resize', 'rotate', 'flip', 'strip_metadata'],\n  encodes: SUPPORTED_OUTPUT,\n  mutate: run,\n})\n\n/**\n * Construct the sharp-backed image engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const sharpEngine = (options: SharpEngineOptions = {}): MediaEngine => {\n  let sharpPromise: Promise<SharpFn> | undefined\n  const getSharp = (): Promise<SharpFn> => {\n    sharpPromise ??= resolveSharp(options.sharp)\n    return sharpPromise\n  }\n  return {\n    id: 'sharp',\n    mutates: [capabilityOf(async (request) => runTransform(await getSharp(), request))],\n  }\n}\n\n/**\n * Adapt an already-configured sharp module (your import, your build flags) to the engine\n * contract — the BYO transformer.\n *\n * @param sharp - The sharp function you imported.\n * @returns The engine.\n */\nexport const fromSharp = (sharp: SharpFn): MediaEngine => ({\n  id: 'sharp',\n  mutates: [capabilityOf(async (request) => runTransform(sharp, request))],\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":";;;;;;;;;;;;;;;;;;AA4BA,IAAM,mBAAmB;CAAC;CAAO;CAAO;CAAQ;CAAQ;CAAQ;CAAQ;AAAK;AAE7E,IAAM,iBAAyC;CAC7C,KAAK;CACL,KAAK;CACL,MAAM;CACN,MAAM;CACN,MAAM;CACN,MAAM;CACN,KAAK;AACP;AAEA,IAAM,eAAe,OAAO,aAA4D;CACtF,IAAI;EACF,MAAM,MAAM,OAAO,WAAW,SAAS,IAAI,OAAO;EAClD,MAAM,KAAK,OAAO,QAAQ,aAAa,MAAO,IAA6B;EAC3E,IAAI,OAAO,OAAO,YAAY,MAAM,IAAI,MAAM,qCAAqC;EACnF,OAAO;CACT,SAAS,KAAK;EAEZ,MAAM,IAAI,gCAAgC,CACxC,gEAFa,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEmB,wDACzE,CAAC;CACH;AACF;;AAGA,IAAM,eAAe,OAAO,OAAgB,YAAuD;CACjG,IAAI,MAAM,MAAM,QAAQ,KAAK;CAC7B,IAAI,QAAQ,QAAQ,MAAM,IAAI,OAAO,QAAQ,MAAM;CACnD,IAAI,QAAQ,MAAM,UAAU,MAAM,IAAI,KAAK;CAC3C,IAAI,QAAQ,MAAM,YAAY,MAAM,IAAI,KAAK;CAC7C,IACE,QAAQ,WACP,QAAQ,OAAO,UAAU,KAAA,KAAa,QAAQ,OAAO,WAAW,KAAA,IAEjE,MAAM,IAAI,OAAO;EACf,OAAO,QAAQ,OAAO;EACtB,QAAQ,QAAQ,OAAO;EACvB,KAAK,QAAQ,OAAO,OAAO;CAC7B,CAAC;CAEH,MAAM,SAAS,QAAQ,QAAQ,MAAM,aAAa,QAAQ,QAAQ;CAClE,MAAM,WAAW,eAAe;CAChC,IAAI,CAAC,UACH,MAAM,IAAI,MAAM,wBAAwB,OAAO,gBAAgB,iBAAiB,KAAK,IAAI,GAAG;CAE9F,MAAM,YAAa,WAAW,QAAQ,SAAS;CAO/C,MAAM,IAAI,SACR,WACA,QAAQ,QAAQ,YAAY,KAAA,IAAY,EAAE,SAAS,QAAQ,OAAO,QAAQ,IAAI,CAAC,CACjF;CACA,IAAI,QAAQ,kBAAkB,MAE5B,MAAM,IAAI,aAAa;CAEzB,MAAM,SAAS,MAAM,IAAI,SAAS;CAClC,OAAO;EAAE,OAAO,IAAI,WAAW,MAAM;EAAG;CAAS;AACnD;;AAGA,IAAM,gBACJ,SACsB;CACtB,MAAM,CAAC,SAAS;CAChB,KAAK;EAAC;EAAU;EAAU;EAAQ;CAAgB;CAClD,SAAS;CACT,QAAQ;AACV;;;;;;;AAQA,IAAa,eAAe,UAA8B,CAAC,MAAmB;CAC5E,IAAI;CACJ,MAAM,iBAAmC;EACvC,iBAAiB,aAAa,QAAQ,KAAK;EAC3C,OAAO;CACT;CACA,OAAO;EACL,IAAI;EACJ,SAAS,CAAC,aAAa,OAAO,YAAY,aAAa,MAAM,SAAS,GAAG,OAAO,CAAC,CAAC;CACpF;AACF;;;;;;;;AASA,IAAa,aAAa,WAAiC;CACzD,IAAI;CACJ,SAAS,CAAC,aAAa,OAAO,YAAY,aAAa,OAAO,OAAO,CAAC,CAAC;AACzE;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"}