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

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

@@ -1 +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"}
+{"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), 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":"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"}

package/batteries/media/engines/sharp.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/sharp.ts
 /**
@@ -12,9 +13,11 @@ const require_exceptions = require("../../../exceptions-D79HIKeX.js");
 *
 * @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}.
+* and the full `fit` mode set, plus a generation edge — `EMPTY_MIME` → a blank 1024×1024
+* white canvas in any supported encoding (resize in the same statement). 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.
 */
@@ -82,6 +85,34 @@ var capabilityOf = (run) => ({
 	mutate: run
 });
 /**
+* Build the generation capability over a sharp source: `EMPTY_MIME` → a blank 1024×1024
+* white canvas (3 channels, so jpeg never trips on alpha) in any supported encoding.
+*/
+var blankCapability = (getSharp) => ({
+	from: [require_batteries_media_contracts.EMPTY_MIME],
+	to: SUPPORTED_OUTPUT,
+	convert: async (request) => {
+		const mimeType = MIME_BY_FORMAT[request.to];
+		if (!mimeType) throw new Error(`sharp cannot generate "${request.to}"; supported: ${SUPPORTED_OUTPUT.join(", ")}`);
+		const sharp = await getSharp();
+		const formatKey = request.to === "jpg" ? "jpeg" : request.to;
+		const buffer = await sharp({ create: {
+			width: 1024,
+			height: 1024,
+			channels: 3,
+			background: {
+				r: 255,
+				g: 255,
+				b: 255
+			}
+		} }).toFormat(formatKey).toBuffer();
+		return { outputs: [{
+			bytes: new Uint8Array(buffer),
+			mimeType
+		}] };
+	}
+});
+/**
 * Construct the sharp-backed image engine.
 *
 * @param options - Optional module resolver override.
@@ -95,6 +126,7 @@ var sharpEngine = (options = {}) => {
 	};
 	return {
 		id: "sharp",
+		converts: [blankCapability(getSharp)],
 		mutates: [capabilityOf(async (request) => runTransform(await getSharp(), request))]
 	};
 };
@@ -107,6 +139,7 @@ var sharpEngine = (options = {}) => {
 */
 var fromSharp = (sharp) => ({
 	id: "sharp",
+	converts: [blankCapability(async () => sharp)],
 	mutates: [capabilityOf(async (request) => runTransform(sharp, request))]
 });
 var mimeToFormat = (mimeType) => {

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

@@ -1 +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"}
+{"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, plus a generation edge — `EMPTY_MIME` → a blank 1024×1024\n * white canvas in any supported encoding (resize in the same statement). sharp is permanently\n * Node-only (native bindings); for a cross-environment engine compose the jimp implementation\n * instead — the capability declaration is the seam, and BYO instances adapt via\n * {@link fromSharp}.\n *\n * `sharp` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { EMPTY_MIME } from '../contracts'\nimport { isError } from '@nhtio/adk/guards'\nimport { default as SharpDefault } from 'sharp'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type {\n  MediaEngine,\n  MutateCapability,\n  MutateRequest,\n  EngineBytesResult,\n  ConvertCapability,\n  ConvertRequest,\n  ConvertResult,\n} 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 * Build the generation capability over a sharp source: `EMPTY_MIME` → a blank 1024×1024\n * white canvas (3 channels, so jpeg never trips on alpha) in any supported encoding.\n */\nconst blankCapability = (getSharp: () => Promise<SharpFn>): ConvertCapability => ({\n  from: [EMPTY_MIME],\n  to: SUPPORTED_OUTPUT,\n  convert: async (request: ConvertRequest): Promise<ConvertResult> => {\n    const mimeType = MIME_BY_FORMAT[request.to]\n    if (!mimeType) {\n      throw new Error(\n        `sharp cannot generate \"${request.to}\"; supported: ${SUPPORTED_OUTPUT.join(', ')}`\n      )\n    }\n    const sharp = await getSharp()\n    const formatKey = (request.to === 'jpg' ? 'jpeg' : request.to) as\n      | 'png'\n      | 'jpeg'\n      | 'webp'\n      | 'tiff'\n      | 'avif'\n      | 'gif'\n    const buffer = await sharp({\n      create: { width: 1024, height: 1024, channels: 3, background: { r: 255, g: 255, b: 255 } },\n    })\n      .toFormat(formatKey)\n      .toBuffer()\n    return { outputs: [{ bytes: new Uint8Array(buffer), mimeType }] }\n  },\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    converts: [blankCapability(getSharp)],\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  converts: [blankCapability(async () => 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":"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"}

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

@@ -6,9 +6,11 @@
  *
  * @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}.
+ * and the full `fit` mode set, plus a generation edge — `EMPTY_MIME` → a blank 1024×1024
+ * white canvas in any supported encoding (resize in the same statement). 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.
  */

package/batteries/media/engines/sharp.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/sharp.ts
 /**
@@ -10,9 +11,11 @@ import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4O
 *
 * @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}.
+* and the full `fit` mode set, plus a generation edge — `EMPTY_MIME` → a blank 1024×1024
+* white canvas in any supported encoding (resize in the same statement). 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.
 */
@@ -80,6 +83,34 @@ var capabilityOf = (run) => ({
 	mutate: run
 });
 /**
+* Build the generation capability over a sharp source: `EMPTY_MIME` → a blank 1024×1024
+* white canvas (3 channels, so jpeg never trips on alpha) in any supported encoding.
+*/
+var blankCapability = (getSharp) => ({
+	from: [EMPTY_MIME],
+	to: SUPPORTED_OUTPUT,
+	convert: async (request) => {
+		const mimeType = MIME_BY_FORMAT[request.to];
+		if (!mimeType) throw new Error(`sharp cannot generate "${request.to}"; supported: ${SUPPORTED_OUTPUT.join(", ")}`);
+		const sharp = await getSharp();
+		const formatKey = request.to === "jpg" ? "jpeg" : request.to;
+		const buffer = await sharp({ create: {
+			width: 1024,
+			height: 1024,
+			channels: 3,
+			background: {
+				r: 255,
+				g: 255,
+				b: 255
+			}
+		} }).toFormat(formatKey).toBuffer();
+		return { outputs: [{
+			bytes: new Uint8Array(buffer),
+			mimeType
+		}] };
+	}
+});
+/**
 * Construct the sharp-backed image engine.
 *
 * @param options - Optional module resolver override.
@@ -93,6 +124,7 @@ var sharpEngine = (options = {}) => {
 	};
 	return {
 		id: "sharp",
+		converts: [blankCapability(getSharp)],
 		mutates: [capabilityOf(async (request) => runTransform(await getSharp(), request))]
 	};
 };
@@ -105,6 +137,7 @@ var sharpEngine = (options = {}) => {
 */
 var fromSharp = (sharp) => ({
 	id: "sharp",
+	converts: [blankCapability(async () => sharp)],
 	mutates: [capabilityOf(async (request) => runTransform(sharp, request))]
 });
 var mimeToFormat = (mimeType) => {

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

@@ -1 +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"}
+{"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, plus a generation edge — `EMPTY_MIME` → a blank 1024×1024\n * white canvas in any supported encoding (resize in the same statement). sharp is permanently\n * Node-only (native bindings); for a cross-environment engine compose the jimp implementation\n * instead — the capability declaration is the seam, and BYO instances adapt via\n * {@link fromSharp}.\n *\n * `sharp` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { EMPTY_MIME } from '../contracts'\nimport { isError } from '@nhtio/adk/guards'\nimport { default as SharpDefault } from 'sharp'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type {\n  MediaEngine,\n  MutateCapability,\n  MutateRequest,\n  EngineBytesResult,\n  ConvertCapability,\n  ConvertRequest,\n  ConvertResult,\n} 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 * Build the generation capability over a sharp source: `EMPTY_MIME` → a blank 1024×1024\n * white canvas (3 channels, so jpeg never trips on alpha) in any supported encoding.\n */\nconst blankCapability = (getSharp: () => Promise<SharpFn>): ConvertCapability => ({\n  from: [EMPTY_MIME],\n  to: SUPPORTED_OUTPUT,\n  convert: async (request: ConvertRequest): Promise<ConvertResult> => {\n    const mimeType = MIME_BY_FORMAT[request.to]\n    if (!mimeType) {\n      throw new Error(\n        `sharp cannot generate \"${request.to}\"; supported: ${SUPPORTED_OUTPUT.join(', ')}`\n      )\n    }\n    const sharp = await getSharp()\n    const formatKey = (request.to === 'jpg' ? 'jpeg' : request.to) as\n      | 'png'\n      | 'jpeg'\n      | 'webp'\n      | 'tiff'\n      | 'avif'\n      | 'gif'\n    const buffer = await sharp({\n      create: { width: 1024, height: 1024, channels: 3, background: { r: 255, g: 255, b: 255 } },\n    })\n      .toFormat(formatKey)\n      .toBuffer()\n    return { outputs: [{ bytes: new Uint8Array(buffer), mimeType }] }\n  },\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    converts: [blankCapability(getSharp)],\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  converts: [blankCapability(async () => 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":"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"}