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

package/batteries/media/contracts.d.ts

@@ -7,12 +7,15 @@
  * @remarks
  * Engines are seams, not policies. An engine is a self-declaring capability provider: it
  * states exactly which transforms it supports — {@link ConvertCapability} edges (input MIME
- * patterns to output format tokens) and {@link MutateCapability} groups (same-format content
- * transforms) — and the pipeline dispatches against those declarations. There are only two
- * capability shapes because there are only two things a media engine ever does: change the
- * format, or change the content. OCR is a convert (image to text). Transcription is a convert
- * (PCM to text). Decoding audio is a convert (container to PCM). Resizing is a mutate. A new
- * capability is a new edge in the data, never a new contract.
+ * patterns to output format tokens), {@link MutateCapability} groups (same-format content
+ * transforms), and {@link EditCapability} groups (structural document operations) — and the
+ * pipeline dispatches against those declarations. There are only three capability shapes
+ * because there are only three things a media engine ever does: change the format, change the
+ * content, or restructure the document. OCR is a convert (image to text). Transcription is a
+ * convert (PCM to text). Decoding audio is a convert (container to PCM). Generating a blank
+ * file is a convert (from {@link EMPTY_MIME} — the source format happens to be nothing).
+ * Resizing is a mutate. Inserting a worksheet row is an edit. A new capability is a new edge
+ * in the data, never a new contract.
  *
  * Engines are supplied to `createMediaPipeline` as a flat ordered array and resolved eagerly
  * at construction (declarations drive verb narrowing, so they must be known up front).
@@ -133,6 +136,22 @@ export type MimePattern = string;
  * a {@link ConvertOutput} carrying PCM must set `meta.sampleRate` (Hz).
  */
 export declare const PCM_MIME = "audio/x-adk-pcm";
+/**
+ * The virtual source MIME type for media generation — the single seam through which new media
+ * comes into existence. An engine that can mint a blank/seed file declares
+ * `converts: [{ from: [EMPTY_MIME], to: [...] }]` and receives a {@link ConvertRequest} with
+ * zero bytes; the format token in `to` names what gets created.
+ *
+ * @remarks
+ * Generating an .xlsx, a blank canvas, or a second of silence IS media generation — it is
+ * *deterministic* generation (same inputs, same bytes). *Model-based semantic* generation
+ * (diffusion, TTS) is the same edge with different machinery: a BYO engine declares
+ * `from: [EMPTY_MIME]` and consumes a prompt from `request.options`. Both kinds ride one
+ * declaration shape, which is exactly why this is a MIME and not a special API. `EMPTY_MIME`
+ * can never become a conversion intermediate: no engine declares `to: 'empty'`, so the
+ * pathfinder only ever sees it as a source.
+ */
+export declare const EMPTY_MIME = "application/x-adk-empty";
 /**
  * Pack PCM samples into transport bytes for a {@link ConvertOutput}.
  *
@@ -294,6 +313,63 @@ export interface MutateCapability {
      */
     mutate(request: MutateRequest): Promise<EngineBytesResult>;
 }
+/**
+ * A structural document operation handed to an {@link EditCapability}: one named op with its
+ * verb-table args, applied to in-memory bytes. Unlike the fused {@link MutateRequest} (which
+ * folds adjacent image transforms into one decode/encode), edits run one op per request — a
+ * worksheet splice is not a pixel pass and gains nothing from fusion.
+ */
+export interface EditRequest {
+    /** The input bytes. */
+    bytes: Uint8Array;
+    /** The input MIME type. */
+    mimeType: string;
+    /** The operation name, namespaced as in the verb table (`sheet.update_cells`, …). */
+    op: string;
+    /** The op's arguments, in the verb table's declared shapes. */
+    args: Record<string, unknown>;
+    /** Abort signal threaded from the pipeline execution. */
+    signal?: AbortSignal;
+}
+/** Counts an edit reports back for result summaries. */
+export interface EditSummary {
+    /** Items added (rows, columns, sheets…). */
+    added?: number;
+    /** Items removed. */
+    removed?: number;
+    /** Items modified. */
+    modified?: number;
+    /** Non-fatal notes surfaced to the model. */
+    warnings?: string[];
+}
+/** The settled result of an edit: the restructured bytes plus optional change counts. */
+export interface EditResult extends EngineBytesResult {
+    /** Change counts for result summaries. */
+    summary?: EditSummary;
+}
+/**
+ * A structural document-editing capability group: every op in `ops` is applicable to every
+ * input matching `over`.
+ *
+ * @remarks
+ * Two engines may declare the same ops over the same patterns with different fidelity — e.g.
+ * an ExcelJS-backed editor preserves styling while a SheetJS CE-backed one strips it. The
+ * registry does not rank fidelity; supply order (or selection middleware) decides, which makes
+ * the trade-off the consumer's visible composition decision.
+ */
+export interface EditCapability {
+    /** Input patterns this block edits. */
+    over: readonly MimePattern[];
+    /** Operation names supported (`sheet.update_cells`, `sheet.add_rows`, …). */
+    ops: readonly string[];
+    /**
+     * Apply one structural operation.
+     *
+     * @param request - The op, its args, and the input bytes.
+     * @returns The restructured bytes plus optional change counts.
+     */
+    edit(request: EditRequest): Promise<EditResult>;
+}
 /**
  * A self-declaring media engine: an id for error messages plus the capabilities it provides.
  * At least one capability entry is required.
@@ -305,6 +381,8 @@ export interface MediaEngine {
     readonly converts?: readonly ConvertCapability[];
     /** Same-format content-transform capability groups. */
     readonly mutates?: readonly MutateCapability[];
+    /** Structural document-editing capability groups. */
+    readonly edits?: readonly EditCapability[];
 }
 /** `true` when `value` structurally implements {@link BinaryExecutor}. */
 export declare const implementsBinaryExecutor: (value: unknown) => value is BinaryExecutor;
@@ -314,6 +392,8 @@ export declare const implementsScratchWorkspace: (value: unknown) => value is Sc
 export declare const implementsConvertCapability: (value: unknown) => value is ConvertCapability;
 /** `true` when `value` structurally implements {@link MutateCapability}. */
 export declare const implementsMutateCapability: (value: unknown) => value is MutateCapability;
+/** `true` when `value` structurally implements {@link EditCapability}. */
+export declare const implementsEditCapability: (value: unknown) => value is EditCapability;
 /**
  * `true` when `value` structurally implements {@link MediaEngine}: a string id plus at least
  * one well-formed capability entry. Every declared entry must pass its capability guard.

package/batteries/media/contracts.mjs

@@ -1,4 +1,4 @@
-import { c as isObject } from "../../tool_registry-BaLUIzWz.mjs";
+import { c as isObject } from "../../tool_registry-CZ55mIti.mjs";
 import "../../guards.mjs";
 //#region src/batteries/media/contracts.ts
 /**
@@ -10,12 +10,15 @@ import "../../guards.mjs";
 * @remarks
 * Engines are seams, not policies. An engine is a self-declaring capability provider: it
 * states exactly which transforms it supports — {@link ConvertCapability} edges (input MIME
-* patterns to output format tokens) and {@link MutateCapability} groups (same-format content
-* transforms) — and the pipeline dispatches against those declarations. There are only two
-* capability shapes because there are only two things a media engine ever does: change the
-* format, or change the content. OCR is a convert (image to text). Transcription is a convert
-* (PCM to text). Decoding audio is a convert (container to PCM). Resizing is a mutate. A new
-* capability is a new edge in the data, never a new contract.
+* patterns to output format tokens), {@link MutateCapability} groups (same-format content
+* transforms), and {@link EditCapability} groups (structural document operations) — and the
+* pipeline dispatches against those declarations. There are only three capability shapes
+* because there are only three things a media engine ever does: change the format, change the
+* content, or restructure the document. OCR is a convert (image to text). Transcription is a
+* convert (PCM to text). Decoding audio is a convert (container to PCM). Generating a blank
+* file is a convert (from {@link EMPTY_MIME} — the source format happens to be nothing).
+* Resizing is a mutate. Inserting a worksheet row is an edit. A new capability is a new edge
+* in the data, never a new contract.
 *
 * Engines are supplied to `createMediaPipeline` as a flat ordered array and resolved eagerly
 * at construction (declarations drive verb narrowing, so they must be known up front).
@@ -45,6 +48,22 @@ import "../../guards.mjs";
 */
 var PCM_MIME = "audio/x-adk-pcm";
 /**
+* The virtual source MIME type for media generation — the single seam through which new media
+* comes into existence. An engine that can mint a blank/seed file declares
+* `converts: [{ from: [EMPTY_MIME], to: [...] }]` and receives a {@link ConvertRequest} with
+* zero bytes; the format token in `to` names what gets created.
+*
+* @remarks
+* Generating an .xlsx, a blank canvas, or a second of silence IS media generation — it is
+* *deterministic* generation (same inputs, same bytes). *Model-based semantic* generation
+* (diffusion, TTS) is the same edge with different machinery: a BYO engine declares
+* `from: [EMPTY_MIME]` and consumes a prompt from `request.options`. Both kinds ride one
+* declaration shape, which is exactly why this is a MIME and not a special API. `EMPTY_MIME`
+* can never become a conversion intermediate: no engine declares `to: 'empty'`, so the
+* pathfinder only ever sees it as a source.
+*/
+var EMPTY_MIME = "application/x-adk-empty";
+/**
 * Pack PCM samples into transport bytes for a {@link ConvertOutput}.
 *
 * @remarks
@@ -86,6 +105,8 @@ var implementsScratchWorkspace = (value) => hasFns(value, [
 var implementsConvertCapability = (value) => hasFns(value, ["convert"]) && isStringArray(value.from) && isStringArray(value.to);
 /** `true` when `value` structurally implements {@link MutateCapability}. */
 var implementsMutateCapability = (value) => hasFns(value, ["mutate"]) && isStringArray(value.over) && isStringArray(value.ops) && isStringArray(value.encodes);
+/** `true` when `value` structurally implements {@link EditCapability}. */
+var implementsEditCapability = (value) => hasFns(value, ["edit"]) && isStringArray(value.over) && isStringArray(value.ops);
 /**
 * `true` when `value` structurally implements {@link MediaEngine}: a string id plus at least
 * one well-formed capability entry. Every declared entry must pass its capability guard.
@@ -96,15 +117,22 @@ var implementsMediaEngine = (value) => {
 	if (typeof engine.id !== "string" || engine.id.length === 0) return false;
 	const converts = engine.converts;
 	const mutates = engine.mutates;
+	const edits = engine.edits;
 	if (converts !== void 0) {
 		if (!Array.isArray(converts) || !converts.every(implementsConvertCapability)) return false;
 	}
 	if (mutates !== void 0) {
 		if (!Array.isArray(mutates) || !mutates.every(implementsMutateCapability)) return false;
 	}
-	return (Array.isArray(converts) ? converts.length : 0) + (Array.isArray(mutates) ? mutates.length : 0) > 0;
+	if (edits !== void 0) {
+		if (!Array.isArray(edits) || !edits.every(implementsEditCapability)) return false;
+	}
+	const convertCount = Array.isArray(converts) ? converts.length : 0;
+	const mutateCount = Array.isArray(mutates) ? mutates.length : 0;
+	const editCount = Array.isArray(edits) ? edits.length : 0;
+	return convertCount + mutateCount + editCount > 0;
 };
 //#endregion
-export { PCM_MIME, bytesToPcm, implementsBinaryExecutor, implementsConvertCapability, implementsMediaEngine, implementsMutateCapability, implementsScratchWorkspace, pcmToBytes };
+export { EMPTY_MIME, PCM_MIME, bytesToPcm, implementsBinaryExecutor, implementsConvertCapability, implementsEditCapability, implementsMediaEngine, implementsMutateCapability, implementsScratchWorkspace, pcmToBytes };
 
 //# sourceMappingURL=contracts.mjs.map

package/batteries/media/contracts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"contracts.mjs","names":[],"sources":["../../../src/batteries/media/contracts.ts"],"sourcesContent":["/**\n * Generic engine contracts for the media pipeline battery — the seams every implementation\n * (bundled or BYO) plugs into.\n *\n * @module @nhtio/adk/batteries/media/contracts\n *\n * @remarks\n * Engines are seams, not policies. An engine is a self-declaring capability provider: it\n * states exactly which transforms it supports — {@link ConvertCapability} edges (input MIME\n * patterns to output format tokens) and {@link MutateCapability} groups (same-format content\n * transforms) — and the pipeline dispatches against those declarations. There are only two\n * capability shapes because there are only two things a media engine ever does: change the\n * format, or change the content. OCR is a convert (image to text). Transcription is a convert\n * (PCM to text). Decoding audio is a convert (container to PCM). Resizing is a mutate. A new\n * capability is a new edge in the data, never a new contract.\n *\n * Engines are supplied to `createMediaPipeline` as a flat ordered array and resolved eagerly\n * at construction (declarations drive verb narrowing, so they must be known up front).\n * Bundled engines stay cheap to resolve: their heavy peer dependencies load lazily inside\n * the capability methods, on first actual use.\n *\n * All contracts are duck-typed: validation guards check structure, not class identity, so a\n * consumer can implement an interface from scratch or adapt an existing client. Contracts are\n * enforced at runtime — construction validates every engine and every declared capability and\n * throws `E_INVALID_MEDIA_PIPELINE_CONFIG` naming the offending index when a value fails.\n *\n * Two further contracts exist so that even \"run a binary\" and \"give a binary a file\" are\n * movable seams rather than Node assumptions:\n *\n * - {@link BinaryExecutor} — how an invocation runs. The bundled `execa_executor` wraps execa;\n *   a browser/remote/sandbox executor satisfies the same contract.\n * - {@link ScratchWorkspace} — bytes ⇄ executor-visible paths. A sibling of `ByteStore`, NOT a\n *   `ByteStore`: byte stores promise in-process readers, while binaries are foreign processes\n *   that need real paths. The bundled `fs_workspace` uses `node:fs/promises` via an async\n *   resolver; any implementation whose paths the chosen executor can see is valid — that\n *   compatibility is the consumer's composition decision.\n */\n\nimport { isObject } from '@nhtio/adk/guards'\n\n// ── shared helper shapes ─────────────────────────────────────────────────────\n\n/**\n * A value-or-resolver: the canonical way to supply an engine. Resolvers may be sync or async\n * (dynamic import) and may resolve to the value directly or a `{ default: value }` module\n * namespace. Engine resolvers run eagerly at pipeline construction — the engine module itself\n * is cheap; heavy peer dependencies load lazily inside capability methods.\n */\nexport type EngineResolver<T = MediaEngine> =\n  | T\n  | (() => T | { default: T } | Promise<T | { default: T }>)\n\n/** Common result shape for engines that transform bytes to bytes. */\nexport interface EngineBytesResult {\n  /** The output bytes. */\n  bytes: Uint8Array\n  /** The output MIME type. */\n  mimeType: string\n}\n\n// ── process execution + scratch filesystem ──────────────────────────────────\n\n/** A single binary invocation handed to a {@link BinaryExecutor}. */\nexport interface BinaryInvocation {\n  /** The command to run (an absolute path or a name the executor can resolve). */\n  cmd: string\n  /** Arguments, exec-style (no shell interpolation). */\n  args: string[]\n  /** Wall-clock timeout in milliseconds. */\n  timeoutMs?: number\n  /** Abort signal to cancel the invocation. */\n  signal?: AbortSignal\n}\n\n/** The settled result of a {@link BinaryExecutor.exec} call. */\nexport interface BinaryExecResult {\n  /** The process exit code (or -1 when the process failed to start). */\n  exitCode: number\n  /** Captured standard output. */\n  stdout: string\n  /** Captured standard error. */\n  stderr: string\n  /** `true` when the invocation failed (non-zero exit, spawn failure, timeout, abort). */\n  failed: boolean\n}\n\n/**\n * Runs a binary invocation to completion. How and where it runs — local child process, remote\n * runner, sandbox, container, a browser-side WASI shim — is the implementation's business.\n */\nexport interface BinaryExecutor {\n  /**\n   * Run one invocation to completion and report the result. Implementations must not throw on\n   * non-zero exits — report via `failed`/`exitCode` so callers map failures to readable errors.\n   *\n   * @param invocation - The command, args, and limits to run.\n   * @returns The settled result.\n   */\n  exec(invocation: BinaryInvocation): Promise<BinaryExecResult>\n}\n\n/**\n * Bytes ⇄ executor-visible paths. The seam that lets binary-backed engines exchange files\n * with the process (or remote runner) that executes them.\n */\nexport interface ScratchWorkspace {\n  /**\n   * Write `bytes` into the workspace under `filename` and return the absolute path the\n   * paired executor can open.\n   *\n   * @param bytes - The content to materialize.\n   * @param filename - The basename to use (extension matters to format-sniffing binaries).\n   * @returns The absolute path.\n   */\n  materialize(bytes: Uint8Array, filename: string): Promise<string>\n  /**\n   * Read a file the executor produced inside the workspace.\n   *\n   * @param path - The absolute path to read.\n   * @returns The file bytes.\n   */\n  read(path: string): Promise<Uint8Array>\n  /** The workspace root directory, for `--outdir`-style binary arguments. */\n  dir(): string\n  /** List the files currently in the workspace root (basenames). */\n  list(): Promise<string[]>\n  /** Remove the workspace and everything in it. Engines call this in `finally`. */\n  dispose(): Promise<void>\n}\n\n/**\n * A factory for per-execution scratch workspaces. Engines mint one workspace per invocation\n * so concurrent executions never share a directory.\n */\nexport type ScratchWorkspaceFactory = () => ScratchWorkspace | Promise<ScratchWorkspace>\n\n// ── the format vocabulary ────────────────────────────────────────────────────\n\n/**\n * An input-matching pattern: an exact MIME type (`application/pdf`), a family wildcard\n * (`image/*`), or a virtual MIME such as {@link PCM_MIME}.\n */\nexport type MimePattern = string\n\n/**\n * The virtual MIME type for decoded mono PCM audio — the intermediate between an audio\n * container and a transcription. Bytes are little-endian Float32 samples in `[-1, 1]`;\n * a {@link ConvertOutput} carrying PCM must set `meta.sampleRate` (Hz).\n */\nexport const PCM_MIME = 'audio/x-adk-pcm'\n\n/**\n * Pack PCM samples into transport bytes for a {@link ConvertOutput}.\n *\n * @remarks\n * A `Float32Array` view over arbitrary `Uint8Array` bytes requires 4-byte alignment, which\n * sliced buffers do not guarantee — this helper (and {@link bytesToPcm}) copy-normalize so\n * neither side has to think about alignment.\n *\n * @param pcm - Mono PCM samples in `[-1, 1]`.\n * @returns The samples as little-endian Float32 bytes.\n */\nexport const pcmToBytes = (pcm: Float32Array): Uint8Array => {\n  const copy = new Float32Array(pcm)\n  return new Uint8Array(copy.buffer, 0, copy.byteLength)\n}\n\n/**\n * Read PCM samples back out of transport bytes.\n *\n * @param bytes - Little-endian Float32 bytes (as produced by {@link pcmToBytes}).\n * @returns The mono PCM samples.\n */\nexport const bytesToPcm = (bytes: Uint8Array): Float32Array => {\n  const aligned = new Uint8Array(bytes.length)\n  aligned.set(bytes)\n  return new Float32Array(aligned.buffer, 0, Math.floor(bytes.length / 4))\n}\n\n// ── convert options (typed, augmentable) ─────────────────────────────────────\n\n/** Options understood by OCR-flavored converts (`image/*` → `txt`/`hocr`/`json`). */\nexport interface OcrConvertOptions {\n  /** Recognition language hints (e.g. `['eng','deu']`). */\n  languages?: readonly string[]\n}\n\n/** Options understood by transcription-flavored converts ({@link PCM_MIME} → `txt`/`srt`/`vtt`/`json`). */\nexport interface AsrConvertOptions {\n  /** Source-language hint (BCP-47-ish). */\n  lang?: string\n  /** Translate the transcription to English. */\n  translate?: boolean\n}\n\n/** Options understood by embedded-image extraction converts (`application/pdf` → `images`). */\nexport interface ImagesConvertOptions {\n  /**\n   * Preferred output encoding token (`jpg`, `png`, …). An extractor that can emit it natively\n   * should; outputs in other encodings are re-encoded downstream by the requesting step.\n   */\n  format?: string\n}\n\n/**\n * The options bag carried by a {@link ConvertRequest} — one typed, augmentable interface\n * merging every documented convention.\n *\n * @remarks\n * Consumers add their own keys via declaration merging against this module:\n *\n * ```ts\n * declare module '@nhtio/adk/batteries/media/contracts' {\n *   interface ConvertOptions {\n *     watermark?: { text: string }\n *   }\n * }\n * ```\n *\n * Typo'd keys become excess-property compile errors at literal call sites; the runtime stays\n * open — engines must ignore keys they don't understand (multi-hop conversion forwards one\n * bag to every hop). The namespace is flat and globally merged, so BYO keys should be named\n * to avoid collisions (prefix by engine where ambiguous).\n */\nexport interface ConvertOptions\n  extends OcrConvertOptions, AsrConvertOptions, ImagesConvertOptions {}\n\n// ── the two capabilities ─────────────────────────────────────────────────────\n\n/** A format-changing request handed to a {@link ConvertCapability}. */\nexport interface ConvertRequest {\n  /** The input content bytes. */\n  bytes: Uint8Array\n  /** The input MIME type. */\n  mimeType: string\n  /** The input filename (extension informs format sniffing). */\n  filename: string\n  /** The target format token (`pdf`, `docx`, `txt`, `pcm`, `images`, …). */\n  to: string\n  /** Capability-specific options — see {@link ConvertOptions}. */\n  options?: ConvertOptions\n  /** Abort signal threaded from the pipeline execution. */\n  signal?: AbortSignal\n}\n\n/** One output of a convert — most converts yield exactly one; `images` yields many. */\nexport interface ConvertOutput {\n  /** The output bytes. */\n  bytes: Uint8Array\n  /** The output MIME type (honest — native encoding, no silent re-encode). */\n  mimeType: string\n  /** Output metadata (e.g. `{ sampleRate: 44100 }` on {@link PCM_MIME} outputs). */\n  meta?: Record<string, unknown>\n}\n\n/** The settled result of a convert. */\nexport interface ConvertResult {\n  /** The outputs, in source order. */\n  outputs: readonly ConvertOutput[]\n}\n\n/**\n * One uniform block of an engine's conversion matrix: every format token in `to` is\n * producible from every input matching `from`.\n *\n * @remarks\n * Declarations are plain data — the registry reads them without calling engine code. An\n * input-dependent matrix (LibreOffice: docx→pdf yes, docx→xlsx no, ods→xlsx yes) is expressed\n * as several capability groups, each a uniform from×to block.\n */\nexport interface ConvertCapability {\n  /** Input patterns this block accepts. */\n  from: readonly MimePattern[]\n  /** Format tokens producible from every `from` member. */\n  to: readonly string[]\n  /**\n   * Perform the conversion.\n   *\n   * @param request - The input bytes, target token, and options.\n   * @returns The conversion outputs.\n   */\n  convert(request: ConvertRequest): Promise<ConvertResult>\n}\n\n/**\n * A same-format content transform handed to a {@link MutateCapability} — the fused image\n * request: adjacent `image.*` steps fold into ONE request so a resize→rotate→format chain\n * costs a single decode/encode.\n */\nexport interface MutateRequest {\n  /** The input bytes. */\n  bytes: Uint8Array\n  /** The input MIME type. */\n  mimeType: string\n  /** Resize, when requested. */\n  resize?: {\n    width?: number\n    height?: number\n    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'\n  }\n  /** Clockwise rotation in degrees. */\n  rotate?: 90 | 180 | 270\n  /** Flip axes. */\n  flip?: { horizontal?: boolean; vertical?: boolean }\n  /** Remove EXIF/ICC metadata. */\n  stripMetadata?: boolean\n  /** Re-encode target, when requested (rides the same fused call). */\n  format?: { to: string; quality?: number }\n  /** Abort signal threaded from the pipeline execution. */\n  signal?: AbortSignal\n}\n\n/** A same-format content-transform capability group. */\nexport interface MutateCapability {\n  /** Input patterns this block mutates. */\n  over: readonly MimePattern[]\n  /** Content operations supported (`resize`, `rotate`, `flip`, `strip_metadata`). */\n  ops: readonly string[]\n  /** Format tokens reachable via `request.format` in the same fused call. */\n  encodes: readonly string[]\n  /**\n   * Apply the fused transform.\n   *\n   * @param request - The folded operations and input bytes.\n   * @returns The transformed bytes.\n   */\n  mutate(request: MutateRequest): Promise<EngineBytesResult>\n}\n\n/**\n * A self-declaring media engine: an id for error messages plus the capabilities it provides.\n * At least one capability entry is required.\n */\nexport interface MediaEngine {\n  /** Stable identifier used in config and dispatch error messages (`jimp`, `soffice`, …). */\n  readonly id: string\n  /** Format-changing capability groups. */\n  readonly converts?: readonly ConvertCapability[]\n  /** Same-format content-transform capability groups. */\n  readonly mutates?: readonly MutateCapability[]\n}\n\n// ── duck-typed guards ────────────────────────────────────────────────────────\n\nconst hasFns = (value: unknown, names: readonly string[]): boolean =>\n  isObject(value) && names.every((n) => typeof (value as Record<string, unknown>)[n] === 'function')\n\nconst isStringArray = (value: unknown): boolean =>\n  Array.isArray(value) && value.every((v) => typeof v === 'string')\n\n/** `true` when `value` structurally implements {@link BinaryExecutor}. */\nexport const implementsBinaryExecutor = (value: unknown): value is BinaryExecutor =>\n  hasFns(value, ['exec'])\n\n/** `true` when `value` structurally implements {@link ScratchWorkspace}. */\nexport const implementsScratchWorkspace = (value: unknown): value is ScratchWorkspace =>\n  hasFns(value, ['materialize', 'read', 'dir', 'list', 'dispose'])\n\n/** `true` when `value` structurally implements {@link ConvertCapability}. */\nexport const implementsConvertCapability = (value: unknown): value is ConvertCapability =>\n  hasFns(value, ['convert']) &&\n  isStringArray((value as ConvertCapability).from) &&\n  isStringArray((value as ConvertCapability).to)\n\n/** `true` when `value` structurally implements {@link MutateCapability}. */\nexport const implementsMutateCapability = (value: unknown): value is MutateCapability =>\n  hasFns(value, ['mutate']) &&\n  isStringArray((value as MutateCapability).over) &&\n  isStringArray((value as MutateCapability).ops) &&\n  isStringArray((value as MutateCapability).encodes)\n\n/**\n * `true` when `value` structurally implements {@link MediaEngine}: a string id plus at least\n * one well-formed capability entry. Every declared entry must pass its capability guard.\n */\nexport const implementsMediaEngine = (value: unknown): value is MediaEngine => {\n  if (!isObject(value)) return false\n  const engine = value as unknown as MediaEngine\n  if (typeof engine.id !== 'string' || engine.id.length === 0) return false\n  const converts = engine.converts\n  const mutates = engine.mutates\n  if (converts !== undefined) {\n    if (!Array.isArray(converts) || !converts.every(implementsConvertCapability)) return false\n  }\n  if (mutates !== undefined) {\n    if (!Array.isArray(mutates) || !mutates.every(implementsMutateCapability)) return false\n  }\n  const convertCount = Array.isArray(converts) ? converts.length : 0\n  const mutateCount = Array.isArray(mutates) ? mutates.length : 0\n  return convertCount + mutateCount > 0\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqJA,IAAa,WAAW;;;;;;;;;;;;AAaxB,IAAa,cAAc,QAAkC;CAC3D,MAAM,OAAO,IAAI,aAAa,GAAG;CACjC,OAAO,IAAI,WAAW,KAAK,QAAQ,GAAG,KAAK,UAAU;AACvD;;;;;;;AAQA,IAAa,cAAc,UAAoC;CAC7D,MAAM,UAAU,IAAI,WAAW,MAAM,MAAM;CAC3C,QAAQ,IAAI,KAAK;CACjB,OAAO,IAAI,aAAa,QAAQ,QAAQ,GAAG,KAAK,MAAM,MAAM,SAAS,CAAC,CAAC;AACzE;AAuKA,IAAM,UAAU,OAAgB,UAC9B,SAAS,KAAK,KAAK,MAAM,OAAO,MAAM,OAAQ,MAAkC,OAAO,UAAU;AAEnG,IAAM,iBAAiB,UACrB,MAAM,QAAQ,KAAK,KAAK,MAAM,OAAO,MAAM,OAAO,MAAM,QAAQ;;AAGlE,IAAa,4BAA4B,UACvC,OAAO,OAAO,CAAC,MAAM,CAAC;;AAGxB,IAAa,8BAA8B,UACzC,OAAO,OAAO;CAAC;CAAe;CAAQ;CAAO;CAAQ;AAAS,CAAC;;AAGjE,IAAa,+BAA+B,UAC1C,OAAO,OAAO,CAAC,SAAS,CAAC,KACzB,cAAe,MAA4B,IAAI,KAC/C,cAAe,MAA4B,EAAE;;AAG/C,IAAa,8BAA8B,UACzC,OAAO,OAAO,CAAC,QAAQ,CAAC,KACxB,cAAe,MAA2B,IAAI,KAC9C,cAAe,MAA2B,GAAG,KAC7C,cAAe,MAA2B,OAAO;;;;;AAMnD,IAAa,yBAAyB,UAAyC;CAC7E,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO;CAC7B,MAAM,SAAS;CACf,IAAI,OAAO,OAAO,OAAO,YAAY,OAAO,GAAG,WAAW,GAAG,OAAO;CACpE,MAAM,WAAW,OAAO;CACxB,MAAM,UAAU,OAAO;CACvB,IAAI,aAAa,KAAA;MACX,CAAC,MAAM,QAAQ,QAAQ,KAAK,CAAC,SAAS,MAAM,2BAA2B,GAAG,OAAO;CAAA;CAEvF,IAAI,YAAY,KAAA;MACV,CAAC,MAAM,QAAQ,OAAO,KAAK,CAAC,QAAQ,MAAM,0BAA0B,GAAG,OAAO;CAAA;CAIpF,QAFqB,MAAM,QAAQ,QAAQ,IAAI,SAAS,SAAS,MAC7C,MAAM,QAAQ,OAAO,IAAI,QAAQ,SAAS,KAC1B;AACtC"}
+{"version":3,"file":"contracts.mjs","names":[],"sources":["../../../src/batteries/media/contracts.ts"],"sourcesContent":["/**\n * Generic engine contracts for the media pipeline battery — the seams every implementation\n * (bundled or BYO) plugs into.\n *\n * @module @nhtio/adk/batteries/media/contracts\n *\n * @remarks\n * Engines are seams, not policies. An engine is a self-declaring capability provider: it\n * states exactly which transforms it supports — {@link ConvertCapability} edges (input MIME\n * patterns to output format tokens), {@link MutateCapability} groups (same-format content\n * transforms), and {@link EditCapability} groups (structural document operations) — and the\n * pipeline dispatches against those declarations. There are only three capability shapes\n * because there are only three things a media engine ever does: change the format, change the\n * content, or restructure the document. OCR is a convert (image to text). Transcription is a\n * convert (PCM to text). Decoding audio is a convert (container to PCM). Generating a blank\n * file is a convert (from {@link EMPTY_MIME} — the source format happens to be nothing).\n * Resizing is a mutate. Inserting a worksheet row is an edit. A new capability is a new edge\n * in the data, never a new contract.\n *\n * Engines are supplied to `createMediaPipeline` as a flat ordered array and resolved eagerly\n * at construction (declarations drive verb narrowing, so they must be known up front).\n * Bundled engines stay cheap to resolve: their heavy peer dependencies load lazily inside\n * the capability methods, on first actual use.\n *\n * All contracts are duck-typed: validation guards check structure, not class identity, so a\n * consumer can implement an interface from scratch or adapt an existing client. Contracts are\n * enforced at runtime — construction validates every engine and every declared capability and\n * throws `E_INVALID_MEDIA_PIPELINE_CONFIG` naming the offending index when a value fails.\n *\n * Two further contracts exist so that even \"run a binary\" and \"give a binary a file\" are\n * movable seams rather than Node assumptions:\n *\n * - {@link BinaryExecutor} — how an invocation runs. The bundled `execa_executor` wraps execa;\n *   a browser/remote/sandbox executor satisfies the same contract.\n * - {@link ScratchWorkspace} — bytes ⇄ executor-visible paths. A sibling of `ByteStore`, NOT a\n *   `ByteStore`: byte stores promise in-process readers, while binaries are foreign processes\n *   that need real paths. The bundled `fs_workspace` uses `node:fs/promises` via an async\n *   resolver; any implementation whose paths the chosen executor can see is valid — that\n *   compatibility is the consumer's composition decision.\n */\n\nimport { isObject } from '@nhtio/adk/guards'\n\n// ── shared helper shapes ─────────────────────────────────────────────────────\n\n/**\n * A value-or-resolver: the canonical way to supply an engine. Resolvers may be sync or async\n * (dynamic import) and may resolve to the value directly or a `{ default: value }` module\n * namespace. Engine resolvers run eagerly at pipeline construction — the engine module itself\n * is cheap; heavy peer dependencies load lazily inside capability methods.\n */\nexport type EngineResolver<T = MediaEngine> =\n  | T\n  | (() => T | { default: T } | Promise<T | { default: T }>)\n\n/** Common result shape for engines that transform bytes to bytes. */\nexport interface EngineBytesResult {\n  /** The output bytes. */\n  bytes: Uint8Array\n  /** The output MIME type. */\n  mimeType: string\n}\n\n// ── process execution + scratch filesystem ──────────────────────────────────\n\n/** A single binary invocation handed to a {@link BinaryExecutor}. */\nexport interface BinaryInvocation {\n  /** The command to run (an absolute path or a name the executor can resolve). */\n  cmd: string\n  /** Arguments, exec-style (no shell interpolation). */\n  args: string[]\n  /** Wall-clock timeout in milliseconds. */\n  timeoutMs?: number\n  /** Abort signal to cancel the invocation. */\n  signal?: AbortSignal\n}\n\n/** The settled result of a {@link BinaryExecutor.exec} call. */\nexport interface BinaryExecResult {\n  /** The process exit code (or -1 when the process failed to start). */\n  exitCode: number\n  /** Captured standard output. */\n  stdout: string\n  /** Captured standard error. */\n  stderr: string\n  /** `true` when the invocation failed (non-zero exit, spawn failure, timeout, abort). */\n  failed: boolean\n}\n\n/**\n * Runs a binary invocation to completion. How and where it runs — local child process, remote\n * runner, sandbox, container, a browser-side WASI shim — is the implementation's business.\n */\nexport interface BinaryExecutor {\n  /**\n   * Run one invocation to completion and report the result. Implementations must not throw on\n   * non-zero exits — report via `failed`/`exitCode` so callers map failures to readable errors.\n   *\n   * @param invocation - The command, args, and limits to run.\n   * @returns The settled result.\n   */\n  exec(invocation: BinaryInvocation): Promise<BinaryExecResult>\n}\n\n/**\n * Bytes ⇄ executor-visible paths. The seam that lets binary-backed engines exchange files\n * with the process (or remote runner) that executes them.\n */\nexport interface ScratchWorkspace {\n  /**\n   * Write `bytes` into the workspace under `filename` and return the absolute path the\n   * paired executor can open.\n   *\n   * @param bytes - The content to materialize.\n   * @param filename - The basename to use (extension matters to format-sniffing binaries).\n   * @returns The absolute path.\n   */\n  materialize(bytes: Uint8Array, filename: string): Promise<string>\n  /**\n   * Read a file the executor produced inside the workspace.\n   *\n   * @param path - The absolute path to read.\n   * @returns The file bytes.\n   */\n  read(path: string): Promise<Uint8Array>\n  /** The workspace root directory, for `--outdir`-style binary arguments. */\n  dir(): string\n  /** List the files currently in the workspace root (basenames). */\n  list(): Promise<string[]>\n  /** Remove the workspace and everything in it. Engines call this in `finally`. */\n  dispose(): Promise<void>\n}\n\n/**\n * A factory for per-execution scratch workspaces. Engines mint one workspace per invocation\n * so concurrent executions never share a directory.\n */\nexport type ScratchWorkspaceFactory = () => ScratchWorkspace | Promise<ScratchWorkspace>\n\n// ── the format vocabulary ────────────────────────────────────────────────────\n\n/**\n * An input-matching pattern: an exact MIME type (`application/pdf`), a family wildcard\n * (`image/*`), or a virtual MIME such as {@link PCM_MIME}.\n */\nexport type MimePattern = string\n\n/**\n * The virtual MIME type for decoded mono PCM audio — the intermediate between an audio\n * container and a transcription. Bytes are little-endian Float32 samples in `[-1, 1]`;\n * a {@link ConvertOutput} carrying PCM must set `meta.sampleRate` (Hz).\n */\nexport const PCM_MIME = 'audio/x-adk-pcm'\n\n/**\n * The virtual source MIME type for media generation — the single seam through which new media\n * comes into existence. An engine that can mint a blank/seed file declares\n * `converts: [{ from: [EMPTY_MIME], to: [...] }]` and receives a {@link ConvertRequest} with\n * zero bytes; the format token in `to` names what gets created.\n *\n * @remarks\n * Generating an .xlsx, a blank canvas, or a second of silence IS media generation — it is\n * *deterministic* generation (same inputs, same bytes). *Model-based semantic* generation\n * (diffusion, TTS) is the same edge with different machinery: a BYO engine declares\n * `from: [EMPTY_MIME]` and consumes a prompt from `request.options`. Both kinds ride one\n * declaration shape, which is exactly why this is a MIME and not a special API. `EMPTY_MIME`\n * can never become a conversion intermediate: no engine declares `to: 'empty'`, so the\n * pathfinder only ever sees it as a source.\n */\nexport const EMPTY_MIME = 'application/x-adk-empty'\n\n/**\n * Pack PCM samples into transport bytes for a {@link ConvertOutput}.\n *\n * @remarks\n * A `Float32Array` view over arbitrary `Uint8Array` bytes requires 4-byte alignment, which\n * sliced buffers do not guarantee — this helper (and {@link bytesToPcm}) copy-normalize so\n * neither side has to think about alignment.\n *\n * @param pcm - Mono PCM samples in `[-1, 1]`.\n * @returns The samples as little-endian Float32 bytes.\n */\nexport const pcmToBytes = (pcm: Float32Array): Uint8Array => {\n  const copy = new Float32Array(pcm)\n  return new Uint8Array(copy.buffer, 0, copy.byteLength)\n}\n\n/**\n * Read PCM samples back out of transport bytes.\n *\n * @param bytes - Little-endian Float32 bytes (as produced by {@link pcmToBytes}).\n * @returns The mono PCM samples.\n */\nexport const bytesToPcm = (bytes: Uint8Array): Float32Array => {\n  const aligned = new Uint8Array(bytes.length)\n  aligned.set(bytes)\n  return new Float32Array(aligned.buffer, 0, Math.floor(bytes.length / 4))\n}\n\n// ── convert options (typed, augmentable) ─────────────────────────────────────\n\n/** Options understood by OCR-flavored converts (`image/*` → `txt`/`hocr`/`json`). */\nexport interface OcrConvertOptions {\n  /** Recognition language hints (e.g. `['eng','deu']`). */\n  languages?: readonly string[]\n}\n\n/** Options understood by transcription-flavored converts ({@link PCM_MIME} → `txt`/`srt`/`vtt`/`json`). */\nexport interface AsrConvertOptions {\n  /** Source-language hint (BCP-47-ish). */\n  lang?: string\n  /** Translate the transcription to English. */\n  translate?: boolean\n}\n\n/** Options understood by embedded-image extraction converts (`application/pdf` → `images`). */\nexport interface ImagesConvertOptions {\n  /**\n   * Preferred output encoding token (`jpg`, `png`, …). An extractor that can emit it natively\n   * should; outputs in other encodings are re-encoded downstream by the requesting step.\n   */\n  format?: string\n}\n\n/**\n * The options bag carried by a {@link ConvertRequest} — one typed, augmentable interface\n * merging every documented convention.\n *\n * @remarks\n * Consumers add their own keys via declaration merging against this module:\n *\n * ```ts\n * declare module '@nhtio/adk/batteries/media/contracts' {\n *   interface ConvertOptions {\n *     watermark?: { text: string }\n *   }\n * }\n * ```\n *\n * Typo'd keys become excess-property compile errors at literal call sites; the runtime stays\n * open — engines must ignore keys they don't understand (multi-hop conversion forwards one\n * bag to every hop). The namespace is flat and globally merged, so BYO keys should be named\n * to avoid collisions (prefix by engine where ambiguous).\n */\nexport interface ConvertOptions\n  extends OcrConvertOptions, AsrConvertOptions, ImagesConvertOptions {}\n\n// ── the three capabilities ───────────────────────────────────────────────────\n\n/** A format-changing request handed to a {@link ConvertCapability}. */\nexport interface ConvertRequest {\n  /** The input content bytes. */\n  bytes: Uint8Array\n  /** The input MIME type. */\n  mimeType: string\n  /** The input filename (extension informs format sniffing). */\n  filename: string\n  /** The target format token (`pdf`, `docx`, `txt`, `pcm`, `images`, …). */\n  to: string\n  /** Capability-specific options — see {@link ConvertOptions}. */\n  options?: ConvertOptions\n  /** Abort signal threaded from the pipeline execution. */\n  signal?: AbortSignal\n}\n\n/** One output of a convert — most converts yield exactly one; `images` yields many. */\nexport interface ConvertOutput {\n  /** The output bytes. */\n  bytes: Uint8Array\n  /** The output MIME type (honest — native encoding, no silent re-encode). */\n  mimeType: string\n  /** Output metadata (e.g. `{ sampleRate: 44100 }` on {@link PCM_MIME} outputs). */\n  meta?: Record<string, unknown>\n}\n\n/** The settled result of a convert. */\nexport interface ConvertResult {\n  /** The outputs, in source order. */\n  outputs: readonly ConvertOutput[]\n}\n\n/**\n * One uniform block of an engine's conversion matrix: every format token in `to` is\n * producible from every input matching `from`.\n *\n * @remarks\n * Declarations are plain data — the registry reads them without calling engine code. An\n * input-dependent matrix (LibreOffice: docx→pdf yes, docx→xlsx no, ods→xlsx yes) is expressed\n * as several capability groups, each a uniform from×to block.\n */\nexport interface ConvertCapability {\n  /** Input patterns this block accepts. */\n  from: readonly MimePattern[]\n  /** Format tokens producible from every `from` member. */\n  to: readonly string[]\n  /**\n   * Perform the conversion.\n   *\n   * @param request - The input bytes, target token, and options.\n   * @returns The conversion outputs.\n   */\n  convert(request: ConvertRequest): Promise<ConvertResult>\n}\n\n/**\n * A same-format content transform handed to a {@link MutateCapability} — the fused image\n * request: adjacent `image.*` steps fold into ONE request so a resize→rotate→format chain\n * costs a single decode/encode.\n */\nexport interface MutateRequest {\n  /** The input bytes. */\n  bytes: Uint8Array\n  /** The input MIME type. */\n  mimeType: string\n  /** Resize, when requested. */\n  resize?: {\n    width?: number\n    height?: number\n    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside'\n  }\n  /** Clockwise rotation in degrees. */\n  rotate?: 90 | 180 | 270\n  /** Flip axes. */\n  flip?: { horizontal?: boolean; vertical?: boolean }\n  /** Remove EXIF/ICC metadata. */\n  stripMetadata?: boolean\n  /** Re-encode target, when requested (rides the same fused call). */\n  format?: { to: string; quality?: number }\n  /** Abort signal threaded from the pipeline execution. */\n  signal?: AbortSignal\n}\n\n/** A same-format content-transform capability group. */\nexport interface MutateCapability {\n  /** Input patterns this block mutates. */\n  over: readonly MimePattern[]\n  /** Content operations supported (`resize`, `rotate`, `flip`, `strip_metadata`). */\n  ops: readonly string[]\n  /** Format tokens reachable via `request.format` in the same fused call. */\n  encodes: readonly string[]\n  /**\n   * Apply the fused transform.\n   *\n   * @param request - The folded operations and input bytes.\n   * @returns The transformed bytes.\n   */\n  mutate(request: MutateRequest): Promise<EngineBytesResult>\n}\n\n/**\n * A structural document operation handed to an {@link EditCapability}: one named op with its\n * verb-table args, applied to in-memory bytes. Unlike the fused {@link MutateRequest} (which\n * folds adjacent image transforms into one decode/encode), edits run one op per request — a\n * worksheet splice is not a pixel pass and gains nothing from fusion.\n */\nexport interface EditRequest {\n  /** The input bytes. */\n  bytes: Uint8Array\n  /** The input MIME type. */\n  mimeType: string\n  /** The operation name, namespaced as in the verb table (`sheet.update_cells`, …). */\n  op: string\n  /** The op's arguments, in the verb table's declared shapes. */\n  args: Record<string, unknown>\n  /** Abort signal threaded from the pipeline execution. */\n  signal?: AbortSignal\n}\n\n/** Counts an edit reports back for result summaries. */\nexport interface EditSummary {\n  /** Items added (rows, columns, sheets…). */\n  added?: number\n  /** Items removed. */\n  removed?: number\n  /** Items modified. */\n  modified?: number\n  /** Non-fatal notes surfaced to the model. */\n  warnings?: string[]\n}\n\n/** The settled result of an edit: the restructured bytes plus optional change counts. */\nexport interface EditResult extends EngineBytesResult {\n  /** Change counts for result summaries. */\n  summary?: EditSummary\n}\n\n/**\n * A structural document-editing capability group: every op in `ops` is applicable to every\n * input matching `over`.\n *\n * @remarks\n * Two engines may declare the same ops over the same patterns with different fidelity — e.g.\n * an ExcelJS-backed editor preserves styling while a SheetJS CE-backed one strips it. The\n * registry does not rank fidelity; supply order (or selection middleware) decides, which makes\n * the trade-off the consumer's visible composition decision.\n */\nexport interface EditCapability {\n  /** Input patterns this block edits. */\n  over: readonly MimePattern[]\n  /** Operation names supported (`sheet.update_cells`, `sheet.add_rows`, …). */\n  ops: readonly string[]\n  /**\n   * Apply one structural operation.\n   *\n   * @param request - The op, its args, and the input bytes.\n   * @returns The restructured bytes plus optional change counts.\n   */\n  edit(request: EditRequest): Promise<EditResult>\n}\n\n/**\n * A self-declaring media engine: an id for error messages plus the capabilities it provides.\n * At least one capability entry is required.\n */\nexport interface MediaEngine {\n  /** Stable identifier used in config and dispatch error messages (`jimp`, `soffice`, …). */\n  readonly id: string\n  /** Format-changing capability groups. */\n  readonly converts?: readonly ConvertCapability[]\n  /** Same-format content-transform capability groups. */\n  readonly mutates?: readonly MutateCapability[]\n  /** Structural document-editing capability groups. */\n  readonly edits?: readonly EditCapability[]\n}\n\n// ── duck-typed guards ────────────────────────────────────────────────────────\n\nconst hasFns = (value: unknown, names: readonly string[]): boolean =>\n  isObject(value) && names.every((n) => typeof (value as Record<string, unknown>)[n] === 'function')\n\nconst isStringArray = (value: unknown): boolean =>\n  Array.isArray(value) && value.every((v) => typeof v === 'string')\n\n/** `true` when `value` structurally implements {@link BinaryExecutor}. */\nexport const implementsBinaryExecutor = (value: unknown): value is BinaryExecutor =>\n  hasFns(value, ['exec'])\n\n/** `true` when `value` structurally implements {@link ScratchWorkspace}. */\nexport const implementsScratchWorkspace = (value: unknown): value is ScratchWorkspace =>\n  hasFns(value, ['materialize', 'read', 'dir', 'list', 'dispose'])\n\n/** `true` when `value` structurally implements {@link ConvertCapability}. */\nexport const implementsConvertCapability = (value: unknown): value is ConvertCapability =>\n  hasFns(value, ['convert']) &&\n  isStringArray((value as ConvertCapability).from) &&\n  isStringArray((value as ConvertCapability).to)\n\n/** `true` when `value` structurally implements {@link MutateCapability}. */\nexport const implementsMutateCapability = (value: unknown): value is MutateCapability =>\n  hasFns(value, ['mutate']) &&\n  isStringArray((value as MutateCapability).over) &&\n  isStringArray((value as MutateCapability).ops) &&\n  isStringArray((value as MutateCapability).encodes)\n\n/** `true` when `value` structurally implements {@link EditCapability}. */\nexport const implementsEditCapability = (value: unknown): value is EditCapability =>\n  hasFns(value, ['edit']) &&\n  isStringArray((value as EditCapability).over) &&\n  isStringArray((value as EditCapability).ops)\n\n/**\n * `true` when `value` structurally implements {@link MediaEngine}: a string id plus at least\n * one well-formed capability entry. Every declared entry must pass its capability guard.\n */\nexport const implementsMediaEngine = (value: unknown): value is MediaEngine => {\n  if (!isObject(value)) return false\n  const engine = value as unknown as MediaEngine\n  if (typeof engine.id !== 'string' || engine.id.length === 0) return false\n  const converts = engine.converts\n  const mutates = engine.mutates\n  const edits = engine.edits\n  if (converts !== undefined) {\n    if (!Array.isArray(converts) || !converts.every(implementsConvertCapability)) return false\n  }\n  if (mutates !== undefined) {\n    if (!Array.isArray(mutates) || !mutates.every(implementsMutateCapability)) return false\n  }\n  if (edits !== undefined) {\n    if (!Array.isArray(edits) || !edits.every(implementsEditCapability)) return false\n  }\n  const convertCount = Array.isArray(converts) ? converts.length : 0\n  const mutateCount = Array.isArray(mutates) ? mutates.length : 0\n  const editCount = Array.isArray(edits) ? edits.length : 0\n  return convertCount + mutateCount + editCount > 0\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwJA,IAAa,WAAW;;;;;;;;;;;;;;;;AAiBxB,IAAa,aAAa;;;;;;;;;;;;AAa1B,IAAa,cAAc,QAAkC;CAC3D,MAAM,OAAO,IAAI,aAAa,GAAG;CACjC,OAAO,IAAI,WAAW,KAAK,QAAQ,GAAG,KAAK,UAAU;AACvD;;;;;;;AAQA,IAAa,cAAc,UAAoC;CAC7D,MAAM,UAAU,IAAI,WAAW,MAAM,MAAM;CAC3C,QAAQ,IAAI,KAAK;CACjB,OAAO,IAAI,aAAa,QAAQ,QAAQ,GAAG,KAAK,MAAM,MAAM,SAAS,CAAC,CAAC;AACzE;AAsOA,IAAM,UAAU,OAAgB,UAC9B,SAAS,KAAK,KAAK,MAAM,OAAO,MAAM,OAAQ,MAAkC,OAAO,UAAU;AAEnG,IAAM,iBAAiB,UACrB,MAAM,QAAQ,KAAK,KAAK,MAAM,OAAO,MAAM,OAAO,MAAM,QAAQ;;AAGlE,IAAa,4BAA4B,UACvC,OAAO,OAAO,CAAC,MAAM,CAAC;;AAGxB,IAAa,8BAA8B,UACzC,OAAO,OAAO;CAAC;CAAe;CAAQ;CAAO;CAAQ;AAAS,CAAC;;AAGjE,IAAa,+BAA+B,UAC1C,OAAO,OAAO,CAAC,SAAS,CAAC,KACzB,cAAe,MAA4B,IAAI,KAC/C,cAAe,MAA4B,EAAE;;AAG/C,IAAa,8BAA8B,UACzC,OAAO,OAAO,CAAC,QAAQ,CAAC,KACxB,cAAe,MAA2B,IAAI,KAC9C,cAAe,MAA2B,GAAG,KAC7C,cAAe,MAA2B,OAAO;;AAGnD,IAAa,4BAA4B,UACvC,OAAO,OAAO,CAAC,MAAM,CAAC,KACtB,cAAe,MAAyB,IAAI,KAC5C,cAAe,MAAyB,GAAG;;;;;AAM7C,IAAa,yBAAyB,UAAyC;CAC7E,IAAI,CAAC,SAAS,KAAK,GAAG,OAAO;CAC7B,MAAM,SAAS;CACf,IAAI,OAAO,OAAO,OAAO,YAAY,OAAO,GAAG,WAAW,GAAG,OAAO;CACpE,MAAM,WAAW,OAAO;CACxB,MAAM,UAAU,OAAO;CACvB,MAAM,QAAQ,OAAO;CACrB,IAAI,aAAa,KAAA;MACX,CAAC,MAAM,QAAQ,QAAQ,KAAK,CAAC,SAAS,MAAM,2BAA2B,GAAG,OAAO;CAAA;CAEvF,IAAI,YAAY,KAAA;MACV,CAAC,MAAM,QAAQ,OAAO,KAAK,CAAC,QAAQ,MAAM,0BAA0B,GAAG,OAAO;CAAA;CAEpF,IAAI,UAAU,KAAA;MACR,CAAC,MAAM,QAAQ,KAAK,KAAK,CAAC,MAAM,MAAM,wBAAwB,GAAG,OAAO;CAAA;CAE9E,MAAM,eAAe,MAAM,QAAQ,QAAQ,IAAI,SAAS,SAAS;CACjE,MAAM,cAAc,MAAM,QAAQ,OAAO,IAAI,QAAQ,SAAS;CAC9D,MAAM,YAAY,MAAM,QAAQ,KAAK,IAAI,MAAM,SAAS;CACxD,OAAO,eAAe,cAAc,YAAY;AAClD"}

package/batteries/media/engines/audio_decode.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_batteries_media_contracts = require("../contracts.cjs");
 const require_exceptions = require("../../../exceptions-D79HIKeX.js");
@@ -13,11 +13,15 @@ const require_exceptions = require("../../../exceptions-D79HIKeX.js");
 * @module @nhtio/adk/batteries/media/engines/audio_decode
 *
 * @remarks
-* Declares one convert capability: audio containers to the virtual `pcm` token (mp3 /
-* m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono. The PCM output reports the
-* SOURCE sample rate in `meta.sampleRate` — the pipeline's transcribe step resamples to the
-* 16 kHz transcription engines expect. For exotic containers, compose an ffmpeg-backed
-* engine instead; the capability declaration is the seam.
+* Declares two convert capabilities: audio containers to the virtual `pcm` token (mp3 /
+* m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono; and a generation edge —
+* `EMPTY_MIME` → wav. Audio bytes are just bytes in a documented envelope: the generated
+* seed is a canonical 44-byte RIFF/WAVE header plus one second of 16-bit mono silence at
+* 44100 Hz, written by a dependency-free helper (generation never loads the decode peer).
+* The PCM output reports the SOURCE sample rate in `meta.sampleRate` — the pipeline's
+* transcribe step resamples to the 16 kHz transcription engines expect. For exotic
+* containers, compose an ffmpeg-backed engine instead; the capability declaration is the
+* seam.
 *
 * `audio-decode` is an optional peer dependency, lazily imported on first actual use.
 */
@@ -30,6 +34,35 @@ var channelsOf = (buffer) => {
 	throw new Error("audio-decode returned an unrecognized buffer shape");
 };
 /**
+* Mint one second of 16-bit mono silence at 44100 Hz as a canonical RIFF/WAVE file — the
+* 44-byte header plus zeroed sample data. Pure bytes, zero dependencies.
+*/
+var makeSilentWav = () => {
+	const sampleRate = 44100;
+	const numSamples = sampleRate;
+	const bytesPerSample = 2;
+	const dataSize = numSamples * bytesPerSample;
+	const bytes = new Uint8Array(88244);
+	const view = new DataView(bytes.buffer);
+	const writeAscii = (offset, text) => {
+		for (let i = 0; i < text.length; i++) bytes[offset + i] = text.charCodeAt(i);
+	};
+	writeAscii(0, "RIFF");
+	view.setUint32(4, 88236, true);
+	writeAscii(8, "WAVE");
+	writeAscii(12, "fmt ");
+	view.setUint32(16, 16, true);
+	view.setUint16(20, 1, true);
+	view.setUint16(22, 1, true);
+	view.setUint32(24, sampleRate, true);
+	view.setUint32(28, sampleRate * bytesPerSample, true);
+	view.setUint16(32, bytesPerSample, true);
+	view.setUint16(34, 16, true);
+	writeAscii(36, "data");
+	view.setUint32(40, dataSize, true);
+	return bytes;
+};
+/**
 * Construct the audio-decode-backed engine.
 *
 * @param options - Optional module resolver override.
@@ -83,6 +116,13 @@ var audioDecodeEngine = (options = {}) => {
 			],
 			to: ["pcm"],
 			convert
+		}, {
+			from: [require_batteries_media_contracts.EMPTY_MIME],
+			to: ["wav"],
+			convert: async () => ({ outputs: [{
+				bytes: makeSilentWav(),
+				mimeType: "audio/wav"
+			}] })
 		}]
 	};
 };

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

@@ -1 +1 @@
-{"version":3,"file":"audio_decode.cjs","names":[],"sources":["../../../../src/batteries/media/engines/audio_decode.ts"],"sourcesContent":["/**\n * A cross-environment audio-decoding {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by the `audio-decode` package (pure JS/WASM codecs — no ffmpeg, no native bindings;\n * works in Node and browsers).\n *\n * @module @nhtio/adk/batteries/media/engines/audio_decode\n *\n * @remarks\n * Declares one convert capability: audio containers to the virtual `pcm` token (mp3 /\n * m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono. The PCM output reports the\n * SOURCE sample rate in `meta.sampleRate` — the pipeline's transcribe step resamples to the\n * 16 kHz transcription engines expect. For exotic containers, compose an ffmpeg-backed\n * engine instead; the capability declaration is the seam.\n *\n * `audio-decode` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { pcmToBytes, PCM_MIME } from '../contracts'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\n/**\n * The decoded shapes audio-decode resolves to. Some codecs return an AudioBuffer-compatible\n * object (`numberOfChannels` + `getChannelData`); others (e.g. the wav path in Node) return a\n * plain `{ channelData: Float32Array[], sampleRate }` record. The engine normalizes both.\n */\nexport interface AudioBufferLike {\n  /** Channel count when the AudioBuffer-compatible shape is returned. */\n  numberOfChannels?: number\n  /** Sample rate of the decoded audio, in Hz. Present on both shapes. */\n  sampleRate: number\n  /** Per-channel sample accessor on the AudioBuffer-compatible shape. */\n  getChannelData?(channel: number): Float32Array\n  /** Raw per-channel sample arrays on the plain-record shape. */\n  channelData?: Float32Array[]\n}\n\n/** The decode function shape the `audio-decode` package exports. */\nexport type AudioDecodeFn = (bytes: Uint8Array | ArrayBuffer) => Promise<AudioBufferLike>\n\nconst channelsOf = (buffer: AudioBufferLike): Float32Array[] => {\n  if (Array.isArray(buffer.channelData)) return buffer.channelData\n  if (typeof buffer.getChannelData === 'function') {\n    const count = buffer.numberOfChannels ?? 1\n    return Array.from({ length: count }, (_, c) => buffer.getChannelData!(c))\n  }\n  throw new Error('audio-decode returned an unrecognized buffer shape')\n}\n\n/** Options for {@link audioDecodeEngine}. */\nexport interface AudioDecodeEngineOptions {\n  /** Override the module resolution. Default: `import('audio-decode')`. */\n  audioDecode?: () =>\n    | AudioDecodeFn\n    | { default: AudioDecodeFn }\n    | Promise<AudioDecodeFn | { default: AudioDecodeFn }>\n}\n\n/**\n * Construct the audio-decode-backed engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const audioDecodeEngine = (options: AudioDecodeEngineOptions = {}): MediaEngine => {\n  let fnPromise: Promise<AudioDecodeFn> | undefined\n  const getDecode = (): Promise<AudioDecodeFn> => {\n    fnPromise ??= Promise.resolve(\n      options.audioDecode ? options.audioDecode() : import('audio-decode')\n    )\n      .then((mod) => {\n        const fn = typeof mod === 'function' ? mod : (mod as { default: AudioDecodeFn }).default\n        if (typeof fn !== 'function') {\n          throw new Error('audio-decode did not resolve to a decode function')\n        }\n        return fn\n      })\n      .catch((err) => {\n        const detail = isError(err) ? err.message : String(err)\n        throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n          `the audio-decode engine could not load its peer dependency \"audio-decode\": ${detail} — install it (pnpm add audio-decode)`,\n        ])\n      })\n    return fnPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const decode = await getDecode()\n    const buffer = await decode(request.bytes)\n    const channels = channelsOf(buffer)\n    let pcm: Float32Array\n    if (channels.length <= 1) {\n      pcm = channels[0]\n    } else {\n      // Downmix to mono by averaging channels.\n      const length = channels[0].length\n      const mono = new Float32Array(length)\n      for (const data of channels) {\n        for (let i = 0; i < length; i++) mono[i] += data[i] / channels.length\n      }\n      pcm = mono\n    }\n    return {\n      outputs: [\n        { bytes: pcmToBytes(pcm), mimeType: PCM_MIME, meta: { sampleRate: buffer.sampleRate } },\n      ],\n    }\n  }\n\n  return {\n    id: 'audio-decode',\n    converts: [\n      {\n        from: [\n          'audio/mpeg',\n          'audio/mp3',\n          'audio/mp4',\n          'audio/aac',\n          'audio/x-m4a',\n          'audio/ogg',\n          'audio/opus',\n          'audio/flac',\n          'audio/x-flac',\n          'audio/wav',\n          'audio/x-wav',\n          'audio/wave',\n        ],\n        to: ['pcm'],\n        convert,\n      },\n    ],\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyCA,IAAM,cAAc,WAA4C;CAC9D,IAAI,MAAM,QAAQ,OAAO,WAAW,GAAG,OAAO,OAAO;CACrD,IAAI,OAAO,OAAO,mBAAmB,YAAY;EAC/C,MAAM,QAAQ,OAAO,oBAAoB;EACzC,OAAO,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,MAAM,OAAO,eAAgB,CAAC,CAAC;CAC1E;CACA,MAAM,IAAI,MAAM,oDAAoD;AACtE;;;;;;;AAiBA,IAAa,qBAAqB,UAAoC,CAAC,MAAmB;CACxF,IAAI;CACJ,MAAM,kBAA0C;EAC9C,cAAc,QAAQ,QACpB,QAAQ,cAAc,QAAQ,YAAY,IAAI,OAAO,eACvD,EACG,MAAM,QAAQ;GACb,MAAM,KAAK,OAAO,QAAQ,aAAa,MAAO,IAAmC;GACjF,IAAI,OAAO,OAAO,YAChB,MAAM,IAAI,MAAM,mDAAmD;GAErE,OAAO;EACT,CAAC,EACA,OAAO,QAAQ;GAEd,MAAM,IAAI,mBAAA,gCAAgC,CACxC,8EAFa,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiC,sCACvF,CAAC;EACH,CAAC;EACH,OAAO;CACT;CAEA,MAAM,UAAU,OAAO,YAAoD;EAEzE,MAAM,SAAS,OAAM,MADA,UAAU,GACH,QAAQ,KAAK;EACzC,MAAM,WAAW,WAAW,MAAM;EAClC,IAAI;EACJ,IAAI,SAAS,UAAU,GACrB,MAAM,SAAS;OACV;GAEL,MAAM,SAAS,SAAS,GAAG;GAC3B,MAAM,OAAO,IAAI,aAAa,MAAM;GACpC,KAAK,MAAM,QAAQ,UACjB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,KAAK,MAAM,KAAK,KAAK,SAAS;GAEjE,MAAM;EACR;EACA,OAAO,EACL,SAAS,CACP;GAAE,OAAO,kCAAA,WAAW,GAAG;GAAG,UAAU,kCAAA;GAAU,MAAM,EAAE,YAAY,OAAO,WAAW;EAAE,CACxF,EACF;CACF;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CACR;GACE,MAAM;IACJ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;GACF;GACA,IAAI,CAAC,KAAK;GACV;EACF,CACF;CACF;AACF"}
+{"version":3,"file":"audio_decode.cjs","names":[],"sources":["../../../../src/batteries/media/engines/audio_decode.ts"],"sourcesContent":["/**\n * A cross-environment audio-decoding {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by the `audio-decode` package (pure JS/WASM codecs — no ffmpeg, no native bindings;\n * works in Node and browsers).\n *\n * @module @nhtio/adk/batteries/media/engines/audio_decode\n *\n * @remarks\n * Declares two convert capabilities: audio containers to the virtual `pcm` token (mp3 /\n * m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono; and a generation edge —\n * `EMPTY_MIME` → wav. Audio bytes are just bytes in a documented envelope: the generated\n * seed is a canonical 44-byte RIFF/WAVE header plus one second of 16-bit mono silence at\n * 44100 Hz, written by a dependency-free helper (generation never loads the decode peer).\n * The PCM output reports the SOURCE sample rate in `meta.sampleRate` — the pipeline's\n * transcribe step resamples to the 16 kHz transcription engines expect. For exotic\n * containers, compose an ffmpeg-backed engine instead; the capability declaration is the\n * seam.\n *\n * `audio-decode` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { pcmToBytes, PCM_MIME, EMPTY_MIME } from '../contracts'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\n/**\n * The decoded shapes audio-decode resolves to. Some codecs return an AudioBuffer-compatible\n * object (`numberOfChannels` + `getChannelData`); others (e.g. the wav path in Node) return a\n * plain `{ channelData: Float32Array[], sampleRate }` record. The engine normalizes both.\n */\nexport interface AudioBufferLike {\n  /** Channel count when the AudioBuffer-compatible shape is returned. */\n  numberOfChannels?: number\n  /** Sample rate of the decoded audio, in Hz. Present on both shapes. */\n  sampleRate: number\n  /** Per-channel sample accessor on the AudioBuffer-compatible shape. */\n  getChannelData?(channel: number): Float32Array\n  /** Raw per-channel sample arrays on the plain-record shape. */\n  channelData?: Float32Array[]\n}\n\n/** The decode function shape the `audio-decode` package exports. */\nexport type AudioDecodeFn = (bytes: Uint8Array | ArrayBuffer) => Promise<AudioBufferLike>\n\nconst channelsOf = (buffer: AudioBufferLike): Float32Array[] => {\n  if (Array.isArray(buffer.channelData)) return buffer.channelData\n  if (typeof buffer.getChannelData === 'function') {\n    const count = buffer.numberOfChannels ?? 1\n    return Array.from({ length: count }, (_, c) => buffer.getChannelData!(c))\n  }\n  throw new Error('audio-decode returned an unrecognized buffer shape')\n}\n\n/**\n * Mint one second of 16-bit mono silence at 44100 Hz as a canonical RIFF/WAVE file — the\n * 44-byte header plus zeroed sample data. Pure bytes, zero dependencies.\n */\nconst makeSilentWav = (): Uint8Array => {\n  const sampleRate = 44_100\n  const numSamples = sampleRate // 1 second\n  const bytesPerSample = 2 // 16-bit\n  const dataSize = numSamples * bytesPerSample\n  const bytes = new Uint8Array(44 + dataSize) // sample data stays zeroed = silence\n  const view = new DataView(bytes.buffer)\n  const writeAscii = (offset: number, text: string): void => {\n    for (let i = 0; i < text.length; i++) bytes[offset + i] = text.charCodeAt(i)\n  }\n  writeAscii(0, 'RIFF')\n  view.setUint32(4, 36 + dataSize, true)\n  writeAscii(8, 'WAVE')\n  writeAscii(12, 'fmt ')\n  view.setUint32(16, 16, true) // fmt chunk size\n  view.setUint16(20, 1, true) // PCM format\n  view.setUint16(22, 1, true) // mono\n  view.setUint32(24, sampleRate, true)\n  view.setUint32(28, sampleRate * bytesPerSample, true) // byte rate\n  view.setUint16(32, bytesPerSample, true) // block align\n  view.setUint16(34, 16, true) // bits per sample\n  writeAscii(36, 'data')\n  view.setUint32(40, dataSize, true)\n  return bytes\n}\n\n/** Options for {@link audioDecodeEngine}. */\nexport interface AudioDecodeEngineOptions {\n  /** Override the module resolution. Default: `import('audio-decode')`. */\n  audioDecode?: () =>\n    | AudioDecodeFn\n    | { default: AudioDecodeFn }\n    | Promise<AudioDecodeFn | { default: AudioDecodeFn }>\n}\n\n/**\n * Construct the audio-decode-backed engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const audioDecodeEngine = (options: AudioDecodeEngineOptions = {}): MediaEngine => {\n  let fnPromise: Promise<AudioDecodeFn> | undefined\n  const getDecode = (): Promise<AudioDecodeFn> => {\n    fnPromise ??= Promise.resolve(\n      options.audioDecode ? options.audioDecode() : import('audio-decode')\n    )\n      .then((mod) => {\n        const fn = typeof mod === 'function' ? mod : (mod as { default: AudioDecodeFn }).default\n        if (typeof fn !== 'function') {\n          throw new Error('audio-decode did not resolve to a decode function')\n        }\n        return fn\n      })\n      .catch((err) => {\n        const detail = isError(err) ? err.message : String(err)\n        throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n          `the audio-decode engine could not load its peer dependency \"audio-decode\": ${detail} — install it (pnpm add audio-decode)`,\n        ])\n      })\n    return fnPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const decode = await getDecode()\n    const buffer = await decode(request.bytes)\n    const channels = channelsOf(buffer)\n    let pcm: Float32Array\n    if (channels.length <= 1) {\n      pcm = channels[0]\n    } else {\n      // Downmix to mono by averaging channels.\n      const length = channels[0].length\n      const mono = new Float32Array(length)\n      for (const data of channels) {\n        for (let i = 0; i < length; i++) mono[i] += data[i] / channels.length\n      }\n      pcm = mono\n    }\n    return {\n      outputs: [\n        { bytes: pcmToBytes(pcm), mimeType: PCM_MIME, meta: { sampleRate: buffer.sampleRate } },\n      ],\n    }\n  }\n\n  return {\n    id: 'audio-decode',\n    converts: [\n      {\n        from: [\n          'audio/mpeg',\n          'audio/mp3',\n          'audio/mp4',\n          'audio/aac',\n          'audio/x-m4a',\n          'audio/ogg',\n          'audio/opus',\n          'audio/flac',\n          'audio/x-flac',\n          'audio/wav',\n          'audio/x-wav',\n          'audio/wave',\n        ],\n        to: ['pcm'],\n        convert,\n      },\n      {\n        // Generation: silence in the engine's own input envelope (never loads the peer).\n        from: [EMPTY_MIME],\n        to: ['wav'],\n        convert: async (): Promise<ConvertResult> => ({\n          outputs: [{ bytes: makeSilentWav(), mimeType: 'audio/wav' }],\n        }),\n      },\n    ],\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,IAAM,cAAc,WAA4C;CAC9D,IAAI,MAAM,QAAQ,OAAO,WAAW,GAAG,OAAO,OAAO;CACrD,IAAI,OAAO,OAAO,mBAAmB,YAAY;EAC/C,MAAM,QAAQ,OAAO,oBAAoB;EACzC,OAAO,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,MAAM,OAAO,eAAgB,CAAC,CAAC;CAC1E;CACA,MAAM,IAAI,MAAM,oDAAoD;AACtE;;;;;AAMA,IAAM,sBAAkC;CACtC,MAAM,aAAa;CACnB,MAAM,aAAa;CACnB,MAAM,iBAAiB;CACvB,MAAM,WAAW,aAAa;CAC9B,MAAM,QAAQ,IAAI,WAAW,KAAa;CAC1C,MAAM,OAAO,IAAI,SAAS,MAAM,MAAM;CACtC,MAAM,cAAc,QAAgB,SAAuB;EACzD,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,MAAM,SAAS,KAAK,KAAK,WAAW,CAAC;CAC7E;CACA,WAAW,GAAG,MAAM;CACpB,KAAK,UAAU,GAAG,OAAe,IAAI;CACrC,WAAW,GAAG,MAAM;CACpB,WAAW,IAAI,MAAM;CACrB,KAAK,UAAU,IAAI,IAAI,IAAI;CAC3B,KAAK,UAAU,IAAI,GAAG,IAAI;CAC1B,KAAK,UAAU,IAAI,GAAG,IAAI;CAC1B,KAAK,UAAU,IAAI,YAAY,IAAI;CACnC,KAAK,UAAU,IAAI,aAAa,gBAAgB,IAAI;CACpD,KAAK,UAAU,IAAI,gBAAgB,IAAI;CACvC,KAAK,UAAU,IAAI,IAAI,IAAI;CAC3B,WAAW,IAAI,MAAM;CACrB,KAAK,UAAU,IAAI,UAAU,IAAI;CACjC,OAAO;AACT;;;;;;;AAiBA,IAAa,qBAAqB,UAAoC,CAAC,MAAmB;CACxF,IAAI;CACJ,MAAM,kBAA0C;EAC9C,cAAc,QAAQ,QACpB,QAAQ,cAAc,QAAQ,YAAY,IAAI,OAAO,eACvD,EACG,MAAM,QAAQ;GACb,MAAM,KAAK,OAAO,QAAQ,aAAa,MAAO,IAAmC;GACjF,IAAI,OAAO,OAAO,YAChB,MAAM,IAAI,MAAM,mDAAmD;GAErE,OAAO;EACT,CAAC,EACA,OAAO,QAAQ;GAEd,MAAM,IAAI,mBAAA,gCAAgC,CACxC,8EAFa,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiC,sCACvF,CAAC;EACH,CAAC;EACH,OAAO;CACT;CAEA,MAAM,UAAU,OAAO,YAAoD;EAEzE,MAAM,SAAS,OAAM,MADA,UAAU,GACH,QAAQ,KAAK;EACzC,MAAM,WAAW,WAAW,MAAM;EAClC,IAAI;EACJ,IAAI,SAAS,UAAU,GACrB,MAAM,SAAS;OACV;GAEL,MAAM,SAAS,SAAS,GAAG;GAC3B,MAAM,OAAO,IAAI,aAAa,MAAM;GACpC,KAAK,MAAM,QAAQ,UACjB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,KAAK,MAAM,KAAK,KAAK,SAAS;GAEjE,MAAM;EACR;EACA,OAAO,EACL,SAAS,CACP;GAAE,OAAO,kCAAA,WAAW,GAAG;GAAG,UAAU,kCAAA;GAAU,MAAM,EAAE,YAAY,OAAO,WAAW;EAAE,CACxF,EACF;CACF;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CACR;GACE,MAAM;IACJ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;GACF;GACA,IAAI,CAAC,KAAK;GACV;EACF,GACA;GAEE,MAAM,CAAC,kCAAA,UAAU;GACjB,IAAI,CAAC,KAAK;GACV,SAAS,aAAqC,EAC5C,SAAS,CAAC;IAAE,OAAO,cAAc;IAAG,UAAU;GAAY,CAAC,EAC7D;EACF,CACF;CACF;AACF"}

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

@@ -6,11 +6,15 @@
  * @module @nhtio/adk/batteries/media/engines/audio_decode
  *
  * @remarks
- * Declares one convert capability: audio containers to the virtual `pcm` token (mp3 /
- * m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono. The PCM output reports the
- * SOURCE sample rate in `meta.sampleRate` — the pipeline's transcribe step resamples to the
- * 16 kHz transcription engines expect. For exotic containers, compose an ffmpeg-backed
- * engine instead; the capability declaration is the seam.
+ * Declares two convert capabilities: audio containers to the virtual `pcm` token (mp3 /
+ * m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono; and a generation edge —
+ * `EMPTY_MIME` → wav. Audio bytes are just bytes in a documented envelope: the generated
+ * seed is a canonical 44-byte RIFF/WAVE header plus one second of 16-bit mono silence at
+ * 44100 Hz, written by a dependency-free helper (generation never loads the decode peer).
+ * The PCM output reports the SOURCE sample rate in `meta.sampleRate` — the pipeline's
+ * transcribe step resamples to the 16 kHz transcription engines expect. For exotic
+ * containers, compose an ffmpeg-backed engine instead; the capability declaration is the
+ * seam.
  *
  * `audio-decode` is an optional peer dependency, lazily imported on first actual use.
  */

package/batteries/media/engines/audio_decode.mjs

@@ -1,6 +1,6 @@
-import { o as isError } from "../../../tool_registry-BaLUIzWz.mjs";
+import { o as isError } from "../../../tool_registry-CZ55mIti.mjs";
 import "../../../guards.mjs";
-import { PCM_MIME, pcmToBytes } from "../contracts.mjs";
+import { EMPTY_MIME, PCM_MIME, pcmToBytes } from "../contracts.mjs";
 import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4Ofs.mjs";
 //#region src/batteries/media/engines/audio_decode.ts
 /**
@@ -11,11 +11,15 @@ import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-BLTn4O
 * @module @nhtio/adk/batteries/media/engines/audio_decode
 *
 * @remarks
-* Declares one convert capability: audio containers to the virtual `pcm` token (mp3 /
-* m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono. The PCM output reports the
-* SOURCE sample rate in `meta.sampleRate` — the pipeline's transcribe step resamples to the
-* 16 kHz transcription engines expect. For exotic containers, compose an ffmpeg-backed
-* engine instead; the capability declaration is the seam.
+* Declares two convert capabilities: audio containers to the virtual `pcm` token (mp3 /
+* m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono; and a generation edge —
+* `EMPTY_MIME` → wav. Audio bytes are just bytes in a documented envelope: the generated
+* seed is a canonical 44-byte RIFF/WAVE header plus one second of 16-bit mono silence at
+* 44100 Hz, written by a dependency-free helper (generation never loads the decode peer).
+* The PCM output reports the SOURCE sample rate in `meta.sampleRate` — the pipeline's
+* transcribe step resamples to the 16 kHz transcription engines expect. For exotic
+* containers, compose an ffmpeg-backed engine instead; the capability declaration is the
+* seam.
 *
 * `audio-decode` is an optional peer dependency, lazily imported on first actual use.
 */
@@ -28,6 +32,35 @@ var channelsOf = (buffer) => {
 	throw new Error("audio-decode returned an unrecognized buffer shape");
 };
 /**
+* Mint one second of 16-bit mono silence at 44100 Hz as a canonical RIFF/WAVE file — the
+* 44-byte header plus zeroed sample data. Pure bytes, zero dependencies.
+*/
+var makeSilentWav = () => {
+	const sampleRate = 44100;
+	const numSamples = sampleRate;
+	const bytesPerSample = 2;
+	const dataSize = numSamples * bytesPerSample;
+	const bytes = new Uint8Array(88244);
+	const view = new DataView(bytes.buffer);
+	const writeAscii = (offset, text) => {
+		for (let i = 0; i < text.length; i++) bytes[offset + i] = text.charCodeAt(i);
+	};
+	writeAscii(0, "RIFF");
+	view.setUint32(4, 88236, true);
+	writeAscii(8, "WAVE");
+	writeAscii(12, "fmt ");
+	view.setUint32(16, 16, true);
+	view.setUint16(20, 1, true);
+	view.setUint16(22, 1, true);
+	view.setUint32(24, sampleRate, true);
+	view.setUint32(28, sampleRate * bytesPerSample, true);
+	view.setUint16(32, bytesPerSample, true);
+	view.setUint16(34, 16, true);
+	writeAscii(36, "data");
+	view.setUint32(40, dataSize, true);
+	return bytes;
+};
+/**
 * Construct the audio-decode-backed engine.
 *
 * @param options - Optional module resolver override.
@@ -81,6 +114,13 @@ var audioDecodeEngine = (options = {}) => {
 			],
 			to: ["pcm"],
 			convert
+		}, {
+			from: [EMPTY_MIME],
+			to: ["wav"],
+			convert: async () => ({ outputs: [{
+				bytes: makeSilentWav(),
+				mimeType: "audio/wav"
+			}] })
 		}]
 	};
 };

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

@@ -1 +1 @@
-{"version":3,"file":"audio_decode.mjs","names":[],"sources":["../../../../src/batteries/media/engines/audio_decode.ts"],"sourcesContent":["/**\n * A cross-environment audio-decoding {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by the `audio-decode` package (pure JS/WASM codecs — no ffmpeg, no native bindings;\n * works in Node and browsers).\n *\n * @module @nhtio/adk/batteries/media/engines/audio_decode\n *\n * @remarks\n * Declares one convert capability: audio containers to the virtual `pcm` token (mp3 /\n * m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono. The PCM output reports the\n * SOURCE sample rate in `meta.sampleRate` — the pipeline's transcribe step resamples to the\n * 16 kHz transcription engines expect. For exotic containers, compose an ffmpeg-backed\n * engine instead; the capability declaration is the seam.\n *\n * `audio-decode` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { pcmToBytes, PCM_MIME } from '../contracts'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\n/**\n * The decoded shapes audio-decode resolves to. Some codecs return an AudioBuffer-compatible\n * object (`numberOfChannels` + `getChannelData`); others (e.g. the wav path in Node) return a\n * plain `{ channelData: Float32Array[], sampleRate }` record. The engine normalizes both.\n */\nexport interface AudioBufferLike {\n  /** Channel count when the AudioBuffer-compatible shape is returned. */\n  numberOfChannels?: number\n  /** Sample rate of the decoded audio, in Hz. Present on both shapes. */\n  sampleRate: number\n  /** Per-channel sample accessor on the AudioBuffer-compatible shape. */\n  getChannelData?(channel: number): Float32Array\n  /** Raw per-channel sample arrays on the plain-record shape. */\n  channelData?: Float32Array[]\n}\n\n/** The decode function shape the `audio-decode` package exports. */\nexport type AudioDecodeFn = (bytes: Uint8Array | ArrayBuffer) => Promise<AudioBufferLike>\n\nconst channelsOf = (buffer: AudioBufferLike): Float32Array[] => {\n  if (Array.isArray(buffer.channelData)) return buffer.channelData\n  if (typeof buffer.getChannelData === 'function') {\n    const count = buffer.numberOfChannels ?? 1\n    return Array.from({ length: count }, (_, c) => buffer.getChannelData!(c))\n  }\n  throw new Error('audio-decode returned an unrecognized buffer shape')\n}\n\n/** Options for {@link audioDecodeEngine}. */\nexport interface AudioDecodeEngineOptions {\n  /** Override the module resolution. Default: `import('audio-decode')`. */\n  audioDecode?: () =>\n    | AudioDecodeFn\n    | { default: AudioDecodeFn }\n    | Promise<AudioDecodeFn | { default: AudioDecodeFn }>\n}\n\n/**\n * Construct the audio-decode-backed engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const audioDecodeEngine = (options: AudioDecodeEngineOptions = {}): MediaEngine => {\n  let fnPromise: Promise<AudioDecodeFn> | undefined\n  const getDecode = (): Promise<AudioDecodeFn> => {\n    fnPromise ??= Promise.resolve(\n      options.audioDecode ? options.audioDecode() : import('audio-decode')\n    )\n      .then((mod) => {\n        const fn = typeof mod === 'function' ? mod : (mod as { default: AudioDecodeFn }).default\n        if (typeof fn !== 'function') {\n          throw new Error('audio-decode did not resolve to a decode function')\n        }\n        return fn\n      })\n      .catch((err) => {\n        const detail = isError(err) ? err.message : String(err)\n        throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n          `the audio-decode engine could not load its peer dependency \"audio-decode\": ${detail} — install it (pnpm add audio-decode)`,\n        ])\n      })\n    return fnPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const decode = await getDecode()\n    const buffer = await decode(request.bytes)\n    const channels = channelsOf(buffer)\n    let pcm: Float32Array\n    if (channels.length <= 1) {\n      pcm = channels[0]\n    } else {\n      // Downmix to mono by averaging channels.\n      const length = channels[0].length\n      const mono = new Float32Array(length)\n      for (const data of channels) {\n        for (let i = 0; i < length; i++) mono[i] += data[i] / channels.length\n      }\n      pcm = mono\n    }\n    return {\n      outputs: [\n        { bytes: pcmToBytes(pcm), mimeType: PCM_MIME, meta: { sampleRate: buffer.sampleRate } },\n      ],\n    }\n  }\n\n  return {\n    id: 'audio-decode',\n    converts: [\n      {\n        from: [\n          'audio/mpeg',\n          'audio/mp3',\n          'audio/mp4',\n          'audio/aac',\n          'audio/x-m4a',\n          'audio/ogg',\n          'audio/opus',\n          'audio/flac',\n          'audio/x-flac',\n          'audio/wav',\n          'audio/x-wav',\n          'audio/wave',\n        ],\n        to: ['pcm'],\n        convert,\n      },\n    ],\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAyCA,IAAM,cAAc,WAA4C;CAC9D,IAAI,MAAM,QAAQ,OAAO,WAAW,GAAG,OAAO,OAAO;CACrD,IAAI,OAAO,OAAO,mBAAmB,YAAY;EAC/C,MAAM,QAAQ,OAAO,oBAAoB;EACzC,OAAO,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,MAAM,OAAO,eAAgB,CAAC,CAAC;CAC1E;CACA,MAAM,IAAI,MAAM,oDAAoD;AACtE;;;;;;;AAiBA,IAAa,qBAAqB,UAAoC,CAAC,MAAmB;CACxF,IAAI;CACJ,MAAM,kBAA0C;EAC9C,cAAc,QAAQ,QACpB,QAAQ,cAAc,QAAQ,YAAY,IAAI,OAAO,eACvD,EACG,MAAM,QAAQ;GACb,MAAM,KAAK,OAAO,QAAQ,aAAa,MAAO,IAAmC;GACjF,IAAI,OAAO,OAAO,YAChB,MAAM,IAAI,MAAM,mDAAmD;GAErE,OAAO;EACT,CAAC,EACA,OAAO,QAAQ;GAEd,MAAM,IAAI,gCAAgC,CACxC,8EAFa,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiC,sCACvF,CAAC;EACH,CAAC;EACH,OAAO;CACT;CAEA,MAAM,UAAU,OAAO,YAAoD;EAEzE,MAAM,SAAS,OAAM,MADA,UAAU,GACH,QAAQ,KAAK;EACzC,MAAM,WAAW,WAAW,MAAM;EAClC,IAAI;EACJ,IAAI,SAAS,UAAU,GACrB,MAAM,SAAS;OACV;GAEL,MAAM,SAAS,SAAS,GAAG;GAC3B,MAAM,OAAO,IAAI,aAAa,MAAM;GACpC,KAAK,MAAM,QAAQ,UACjB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,KAAK,MAAM,KAAK,KAAK,SAAS;GAEjE,MAAM;EACR;EACA,OAAO,EACL,SAAS,CACP;GAAE,OAAO,WAAW,GAAG;GAAG,UAAU;GAAU,MAAM,EAAE,YAAY,OAAO,WAAW;EAAE,CACxF,EACF;CACF;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CACR;GACE,MAAM;IACJ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;GACF;GACA,IAAI,CAAC,KAAK;GACV;EACF,CACF;CACF;AACF"}
+{"version":3,"file":"audio_decode.mjs","names":[],"sources":["../../../../src/batteries/media/engines/audio_decode.ts"],"sourcesContent":["/**\n * A cross-environment audio-decoding {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by the `audio-decode` package (pure JS/WASM codecs — no ffmpeg, no native bindings;\n * works in Node and browsers).\n *\n * @module @nhtio/adk/batteries/media/engines/audio_decode\n *\n * @remarks\n * Declares two convert capabilities: audio containers to the virtual `pcm` token (mp3 /\n * m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono; and a generation edge —\n * `EMPTY_MIME` → wav. Audio bytes are just bytes in a documented envelope: the generated\n * seed is a canonical 44-byte RIFF/WAVE header plus one second of 16-bit mono silence at\n * 44100 Hz, written by a dependency-free helper (generation never loads the decode peer).\n * The PCM output reports the SOURCE sample rate in `meta.sampleRate` — the pipeline's\n * transcribe step resamples to the 16 kHz transcription engines expect. For exotic\n * containers, compose an ffmpeg-backed engine instead; the capability declaration is the\n * seam.\n *\n * `audio-decode` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { pcmToBytes, PCM_MIME, EMPTY_MIME } from '../contracts'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\n/**\n * The decoded shapes audio-decode resolves to. Some codecs return an AudioBuffer-compatible\n * object (`numberOfChannels` + `getChannelData`); others (e.g. the wav path in Node) return a\n * plain `{ channelData: Float32Array[], sampleRate }` record. The engine normalizes both.\n */\nexport interface AudioBufferLike {\n  /** Channel count when the AudioBuffer-compatible shape is returned. */\n  numberOfChannels?: number\n  /** Sample rate of the decoded audio, in Hz. Present on both shapes. */\n  sampleRate: number\n  /** Per-channel sample accessor on the AudioBuffer-compatible shape. */\n  getChannelData?(channel: number): Float32Array\n  /** Raw per-channel sample arrays on the plain-record shape. */\n  channelData?: Float32Array[]\n}\n\n/** The decode function shape the `audio-decode` package exports. */\nexport type AudioDecodeFn = (bytes: Uint8Array | ArrayBuffer) => Promise<AudioBufferLike>\n\nconst channelsOf = (buffer: AudioBufferLike): Float32Array[] => {\n  if (Array.isArray(buffer.channelData)) return buffer.channelData\n  if (typeof buffer.getChannelData === 'function') {\n    const count = buffer.numberOfChannels ?? 1\n    return Array.from({ length: count }, (_, c) => buffer.getChannelData!(c))\n  }\n  throw new Error('audio-decode returned an unrecognized buffer shape')\n}\n\n/**\n * Mint one second of 16-bit mono silence at 44100 Hz as a canonical RIFF/WAVE file — the\n * 44-byte header plus zeroed sample data. Pure bytes, zero dependencies.\n */\nconst makeSilentWav = (): Uint8Array => {\n  const sampleRate = 44_100\n  const numSamples = sampleRate // 1 second\n  const bytesPerSample = 2 // 16-bit\n  const dataSize = numSamples * bytesPerSample\n  const bytes = new Uint8Array(44 + dataSize) // sample data stays zeroed = silence\n  const view = new DataView(bytes.buffer)\n  const writeAscii = (offset: number, text: string): void => {\n    for (let i = 0; i < text.length; i++) bytes[offset + i] = text.charCodeAt(i)\n  }\n  writeAscii(0, 'RIFF')\n  view.setUint32(4, 36 + dataSize, true)\n  writeAscii(8, 'WAVE')\n  writeAscii(12, 'fmt ')\n  view.setUint32(16, 16, true) // fmt chunk size\n  view.setUint16(20, 1, true) // PCM format\n  view.setUint16(22, 1, true) // mono\n  view.setUint32(24, sampleRate, true)\n  view.setUint32(28, sampleRate * bytesPerSample, true) // byte rate\n  view.setUint16(32, bytesPerSample, true) // block align\n  view.setUint16(34, 16, true) // bits per sample\n  writeAscii(36, 'data')\n  view.setUint32(40, dataSize, true)\n  return bytes\n}\n\n/** Options for {@link audioDecodeEngine}. */\nexport interface AudioDecodeEngineOptions {\n  /** Override the module resolution. Default: `import('audio-decode')`. */\n  audioDecode?: () =>\n    | AudioDecodeFn\n    | { default: AudioDecodeFn }\n    | Promise<AudioDecodeFn | { default: AudioDecodeFn }>\n}\n\n/**\n * Construct the audio-decode-backed engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const audioDecodeEngine = (options: AudioDecodeEngineOptions = {}): MediaEngine => {\n  let fnPromise: Promise<AudioDecodeFn> | undefined\n  const getDecode = (): Promise<AudioDecodeFn> => {\n    fnPromise ??= Promise.resolve(\n      options.audioDecode ? options.audioDecode() : import('audio-decode')\n    )\n      .then((mod) => {\n        const fn = typeof mod === 'function' ? mod : (mod as { default: AudioDecodeFn }).default\n        if (typeof fn !== 'function') {\n          throw new Error('audio-decode did not resolve to a decode function')\n        }\n        return fn\n      })\n      .catch((err) => {\n        const detail = isError(err) ? err.message : String(err)\n        throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n          `the audio-decode engine could not load its peer dependency \"audio-decode\": ${detail} — install it (pnpm add audio-decode)`,\n        ])\n      })\n    return fnPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const decode = await getDecode()\n    const buffer = await decode(request.bytes)\n    const channels = channelsOf(buffer)\n    let pcm: Float32Array\n    if (channels.length <= 1) {\n      pcm = channels[0]\n    } else {\n      // Downmix to mono by averaging channels.\n      const length = channels[0].length\n      const mono = new Float32Array(length)\n      for (const data of channels) {\n        for (let i = 0; i < length; i++) mono[i] += data[i] / channels.length\n      }\n      pcm = mono\n    }\n    return {\n      outputs: [\n        { bytes: pcmToBytes(pcm), mimeType: PCM_MIME, meta: { sampleRate: buffer.sampleRate } },\n      ],\n    }\n  }\n\n  return {\n    id: 'audio-decode',\n    converts: [\n      {\n        from: [\n          'audio/mpeg',\n          'audio/mp3',\n          'audio/mp4',\n          'audio/aac',\n          'audio/x-m4a',\n          'audio/ogg',\n          'audio/opus',\n          'audio/flac',\n          'audio/x-flac',\n          'audio/wav',\n          'audio/x-wav',\n          'audio/wave',\n        ],\n        to: ['pcm'],\n        convert,\n      },\n      {\n        // Generation: silence in the engine's own input envelope (never loads the peer).\n        from: [EMPTY_MIME],\n        to: ['wav'],\n        convert: async (): Promise<ConvertResult> => ({\n          outputs: [{ bytes: makeSilentWav(), mimeType: 'audio/wav' }],\n        }),\n      },\n    ],\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,IAAM,cAAc,WAA4C;CAC9D,IAAI,MAAM,QAAQ,OAAO,WAAW,GAAG,OAAO,OAAO;CACrD,IAAI,OAAO,OAAO,mBAAmB,YAAY;EAC/C,MAAM,QAAQ,OAAO,oBAAoB;EACzC,OAAO,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,MAAM,OAAO,eAAgB,CAAC,CAAC;CAC1E;CACA,MAAM,IAAI,MAAM,oDAAoD;AACtE;;;;;AAMA,IAAM,sBAAkC;CACtC,MAAM,aAAa;CACnB,MAAM,aAAa;CACnB,MAAM,iBAAiB;CACvB,MAAM,WAAW,aAAa;CAC9B,MAAM,QAAQ,IAAI,WAAW,KAAa;CAC1C,MAAM,OAAO,IAAI,SAAS,MAAM,MAAM;CACtC,MAAM,cAAc,QAAgB,SAAuB;EACzD,KAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK,MAAM,SAAS,KAAK,KAAK,WAAW,CAAC;CAC7E;CACA,WAAW,GAAG,MAAM;CACpB,KAAK,UAAU,GAAG,OAAe,IAAI;CACrC,WAAW,GAAG,MAAM;CACpB,WAAW,IAAI,MAAM;CACrB,KAAK,UAAU,IAAI,IAAI,IAAI;CAC3B,KAAK,UAAU,IAAI,GAAG,IAAI;CAC1B,KAAK,UAAU,IAAI,GAAG,IAAI;CAC1B,KAAK,UAAU,IAAI,YAAY,IAAI;CACnC,KAAK,UAAU,IAAI,aAAa,gBAAgB,IAAI;CACpD,KAAK,UAAU,IAAI,gBAAgB,IAAI;CACvC,KAAK,UAAU,IAAI,IAAI,IAAI;CAC3B,WAAW,IAAI,MAAM;CACrB,KAAK,UAAU,IAAI,UAAU,IAAI;CACjC,OAAO;AACT;;;;;;;AAiBA,IAAa,qBAAqB,UAAoC,CAAC,MAAmB;CACxF,IAAI;CACJ,MAAM,kBAA0C;EAC9C,cAAc,QAAQ,QACpB,QAAQ,cAAc,QAAQ,YAAY,IAAI,OAAO,eACvD,EACG,MAAM,QAAQ;GACb,MAAM,KAAK,OAAO,QAAQ,aAAa,MAAO,IAAmC;GACjF,IAAI,OAAO,OAAO,YAChB,MAAM,IAAI,MAAM,mDAAmD;GAErE,OAAO;EACT,CAAC,EACA,OAAO,QAAQ;GAEd,MAAM,IAAI,gCAAgC,CACxC,8EAFa,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiC,sCACvF,CAAC;EACH,CAAC;EACH,OAAO;CACT;CAEA,MAAM,UAAU,OAAO,YAAoD;EAEzE,MAAM,SAAS,OAAM,MADA,UAAU,GACH,QAAQ,KAAK;EACzC,MAAM,WAAW,WAAW,MAAM;EAClC,IAAI;EACJ,IAAI,SAAS,UAAU,GACrB,MAAM,SAAS;OACV;GAEL,MAAM,SAAS,SAAS,GAAG;GAC3B,MAAM,OAAO,IAAI,aAAa,MAAM;GACpC,KAAK,MAAM,QAAQ,UACjB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,KAAK,MAAM,KAAK,KAAK,SAAS;GAEjE,MAAM;EACR;EACA,OAAO,EACL,SAAS,CACP;GAAE,OAAO,WAAW,GAAG;GAAG,UAAU;GAAU,MAAM,EAAE,YAAY,OAAO,WAAW;EAAE,CACxF,EACF;CACF;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CACR;GACE,MAAM;IACJ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;GACF;GACA,IAAI,CAAC,KAAK;GACV;EACF,GACA;GAEE,MAAM,CAAC,UAAU;GACjB,IAAI,CAAC,KAAK;GACV,SAAS,aAAqC,EAC5C,SAAS,CAAC;IAAE,OAAO,cAAc;IAAG,UAAU;GAAY,CAAC,EAC7D;EACF,CACF;CACF;AACF"}