@nhtio/adk 1.20260609.0 → 1.20260610.0

package/batteries/media/builder.d.ts

@@ -0,0 +1,245 @@
+/**
+ * The chainable, thenable media builder — the implementor-facing front-end that compiles to
+ * the same {@link MediaPlan} as the pipe string and JSON ops.
+ *
+ * @remarks
+ * Internal sibling of the `@nhtio/adk/batteries/media` entry. The knex lessons applied:
+ * `mp(input)` opens a fresh immutable builder; every verb returns a new builder; awaiting the
+ * builder executes the chain (no `.execute()`). Domain verbs hang off typed namespaces
+ * (`.sheet`, `.slides`, `.image`, `.audio`); shared transforms live on the root.
+ *
+ * Each verb method appends an op and revalidates lazily — the full plan validates (verb table,
+ * arg schemas, engine narrowing) when the chain executes, so building is cheap and the same
+ * validator serves all three front-ends.
+ */
+import type { PlanResult, StepPayload } from "./runtime";
+import type { MediaOp, MediaArgValue } from "./plan";
+/** The function a builder calls to execute its accumulated ops. Bound by the pipeline. */
+export type ChainExecutor = (ops: MediaOp[]) => Promise<PlanResult>;
+/** Options accepted by image resize. */
+export interface ResizeOptions {
+    /** Target width in pixels. */
+    width?: number;
+    /** Target height in pixels. */
+    height?: number;
+    /** Resize fit mode (default cover). */
+    fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+}
+/** A cell update for `sheet.updateCells`. */
+export interface CellUpdate {
+    /** A1-notation address, e.g. `B2`. Alternative to row/col. */
+    address?: string;
+    /** One-based row index. Pair with `col`. */
+    row?: number;
+    /** One-based column index, or a column letter. Pair with `row`. */
+    col?: number | string;
+    /** The value to set. A leading `=` writes a formula. */
+    value: string | number | boolean | null;
+}
+/** How other media are referenced from builder verbs: an id string or `{ mediaId }`. */
+export type MediaChainRef = string | {
+    mediaId: string;
+};
+/**
+ * The chainable builder. Immutable — every verb returns a new instance sharing the executor.
+ * Thenable — `await` runs the chain and resolves to the terminal step's natural type.
+ */
+export declare class MediaChain implements PromiseLike<unknown> {
+    #private;
+    constructor(exec: ChainExecutor, ops?: MediaOp[]);
+    /** Convert to another format (requires a convert engine). */
+    convert(to: string): MediaChain;
+    /** Keep only the listed 1-based pages. */
+    select(options: {
+        pages: number[];
+    }): MediaChain;
+    /** Split by page (optionally grouped `[[start,end], …]`). Terminal: resolves to media list. */
+    split(options?: {
+        by?: 'page' | 'section';
+        ranges?: number[][];
+    }): MediaChain;
+    /** Merge other media into this one, in order. */
+    merge(...others: MediaChainRef[]): MediaChain;
+    /** Reorder pages by 1-based index. */
+    reorder(order: number[]): MediaChain;
+    /** Redact matching text (literals or RegExp). */
+    redact(options: {
+        match: Array<string | RegExp> | string | RegExp;
+        replace?: string;
+    }): MediaChain;
+    /** Remove potentially unsafe embedded content. */
+    sanitize(): MediaChain;
+    /** Normalize structure/encoding. */
+    normalize(): MediaChain;
+    /** Replace the first occurrence of anchor text. */
+    updateText(anchor: string, replace: string): MediaChain;
+    /** Compare against another media. Terminal: resolves to a structured diff. */
+    diff(other: MediaChainRef): MediaChain;
+    /** Apply a unified-diff patch. */
+    applyPatch(patch: string, options?: {
+        with?: MediaChainRef[];
+    }): MediaChain;
+    /** Extract text (routes by format; OCR engine used when needed). Terminal: resolves to text. */
+    extractText(options?: {
+        ocr?: 'off' | 'auto' | 'force';
+        ocrOut?: 'txt' | 'hocr' | 'json';
+        lang?: string[];
+    }): MediaChain;
+    /** Extract metadata. Terminal: resolves to a metadata object. */
+    extractMetadata(): MediaChain;
+    /** Extract embedded assets. Terminal: resolves to a media list. */
+    extractAssets(options?: {
+        types?: Array<'image' | 'font' | 'attachment' | 'all'>;
+    }): MediaChain;
+    /** Chunk extracted text. Terminal: resolves to a chunk array. */
+    chunk(options?: {
+        strategy?: 'sentence' | 'paragraph' | 'fixed';
+        size?: number;
+        overlap?: number;
+    }): MediaChain;
+    /** Spreadsheet mutations. */
+    get sheet(): SheetNamespace;
+    /** Presentation mutations. */
+    get slides(): SlidesNamespace;
+    /** Image transforms. */
+    get image(): ImageNamespace;
+    /** Audio operations. */
+    get audio(): AudioNamespace;
+    /** The accumulated ops (a copy). */
+    toOps(): MediaOp[];
+    /** The canonical pipe form of the accumulated chain. */
+    toPipe(): string;
+    /** Internal — used by namespaces to append. */
+    withOp(verb: string, args: Record<string, MediaArgValue>): MediaChain;
+    /** Thenable: awaiting the chain executes it. */
+    then<TResult1 = unknown, TResult2 = never>(onfulfilled?: ((value: unknown) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+    /** Execute and return the raw {@link PlanResult} (no unwrapping). */
+    run(): Promise<PlanResult>;
+}
+/** `sheet.*` verbs, mirrored from the verb table. */
+export declare class SheetNamespace {
+    #private;
+    constructor(chain: MediaChain);
+    /** Insert rows. */
+    addRows(rows: Array<Array<string | number | boolean | null>>, options?: {
+        sheet?: string | number;
+        before?: number;
+        after?: number;
+    }): MediaChain;
+    /** Insert columns. */
+    addColumns(options: {
+        sheet?: string | number;
+        headers?: string[];
+        columns?: Array<{
+            header: string;
+            values?: Array<string | number | boolean | null>;
+        }>;
+        before?: number;
+        after?: number;
+    }): MediaChain;
+    /** Update cells. */
+    updateCells(updates: CellUpdate[], options?: {
+        sheet?: string | number;
+    }): MediaChain;
+    /** Delete rows by 1-based index. */
+    deleteRows(rows: number[], options?: {
+        sheet?: string | number;
+    }): MediaChain;
+    /** Delete columns by 1-based index. */
+    deleteColumns(columns: number[], options?: {
+        sheet?: string | number;
+    }): MediaChain;
+    /** Rename a worksheet (name-targeted). */
+    renameSheet(sheet: string, to: string): MediaChain;
+    /** Add a worksheet. */
+    addSheet(name: string, options?: {
+        at?: number;
+    }): MediaChain;
+    /** Remove a worksheet (name-targeted). */
+    removeSheet(sheet: string): MediaChain;
+    /** Reorder worksheets by names and/or 1-based indices. */
+    reorderSheets(order: Array<string | number>): MediaChain;
+    /** Table transforms by header name. */
+    transformTable(options: {
+        sheet?: string | number;
+        headerRow?: number;
+        select?: string[];
+        drop?: string[];
+        rename?: Array<{
+            from: string;
+            to: string;
+        }>;
+    }): MediaChain;
+}
+/** `slides.*` verbs. */
+export declare class SlidesNamespace {
+    #private;
+    constructor(chain: MediaChain);
+    /** Add a slide. */
+    add(options?: {
+        at?: number;
+        title?: string;
+        layout?: string;
+    }): MediaChain;
+    /** Update text on a slide. */
+    updateText(text: string, options?: {
+        slide?: string | number;
+        placeholder?: string;
+    }): MediaChain;
+    /** Update table cells on a slide. */
+    updateTable(updates: Array<{
+        row: number;
+        col: number;
+        value: string;
+    }>, options?: {
+        slide?: string | number;
+    }): MediaChain;
+    /** Replace an image on a slide with another media. */
+    updateImage(withMedia: MediaChainRef, options?: {
+        slide?: string | number;
+        placeholder?: string;
+    }): MediaChain;
+    /** Update chart data on a slide. */
+    updateChart(data: unknown[][], options?: {
+        slide?: string | number;
+    }): MediaChain;
+    /** Delete slides by 1-based index. */
+    delete(slides: number[]): MediaChain;
+    /** Reorder slides. */
+    reorder(order: number[]): MediaChain;
+    /** Duplicate a slide. */
+    duplicate(slide: number, options?: {
+        at?: number;
+    }): MediaChain;
+}
+/** `image.*` verbs (the runtime fuses adjacent image steps into one engine pass). */
+export declare class ImageNamespace {
+    #private;
+    constructor(chain: MediaChain);
+    /** Resize. */
+    resize(options: ResizeOptions): MediaChain;
+    /** Re-encode to another format. */
+    format(to: string, options?: {
+        quality?: number;
+        stripMetadata?: boolean;
+    }): MediaChain;
+    /** Rotate clockwise. */
+    rotate(deg: 90 | 180 | 270): MediaChain;
+    /** Flip. */
+    flip(axis: 'horizontal' | 'vertical' | 'both'): MediaChain;
+    /** Strip EXIF/ICC metadata. */
+    stripMetadata(): MediaChain;
+}
+/** `audio.*` verbs. */
+export declare class AudioNamespace {
+    #private;
+    constructor(chain: MediaChain);
+    /** Transcribe speech. Terminal: resolves to text (or srt/vtt/json per `out`). */
+    transcribe(options?: {
+        language?: string;
+        out?: 'txt' | 'srt' | 'vtt' | 'json';
+        translate?: boolean;
+    }): MediaChain;
+}
+/** The input shapes `mp(...)` accepts. */
+export type ChainInput = StepPayload;

package/batteries/media/contracts.cjs

@@ -0,0 +1,119 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
+require("../../guards.cjs");
+//#region src/batteries/media/contracts.ts
+/**
+* Generic engine contracts for the media pipeline battery — the seams every implementation
+* (bundled or BYO) plugs into.
+*
+* @module @nhtio/adk/batteries/media/contracts
+*
+* @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.
+*
+* 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).
+* Bundled engines stay cheap to resolve: their heavy peer dependencies load lazily inside
+* the capability methods, on first actual use.
+*
+* All contracts are duck-typed: validation guards check structure, not class identity, so a
+* consumer can implement an interface from scratch or adapt an existing client. Contracts are
+* enforced at runtime — construction validates every engine and every declared capability and
+* throws `E_INVALID_MEDIA_PIPELINE_CONFIG` naming the offending index when a value fails.
+*
+* Two further contracts exist so that even "run a binary" and "give a binary a file" are
+* movable seams rather than Node assumptions:
+*
+* - {@link BinaryExecutor} — how an invocation runs. The bundled `execa_executor` wraps execa;
+*   a browser/remote/sandbox executor satisfies the same contract.
+* - {@link ScratchWorkspace} — bytes ⇄ executor-visible paths. A sibling of `ByteStore`, NOT a
+*   `ByteStore`: byte stores promise in-process readers, while binaries are foreign processes
+*   that need real paths. The bundled `fs_workspace` uses `node:fs/promises` via an async
+*   resolver; any implementation whose paths the chosen executor can see is valid — that
+*   compatibility is the consumer's composition decision.
+*/
+/**
+* The virtual MIME type for decoded mono PCM audio — the intermediate between an audio
+* container and a transcription. Bytes are little-endian Float32 samples in `[-1, 1]`;
+* a {@link ConvertOutput} carrying PCM must set `meta.sampleRate` (Hz).
+*/
+var PCM_MIME = "audio/x-adk-pcm";
+/**
+* Pack PCM samples into transport bytes for a {@link ConvertOutput}.
+*
+* @remarks
+* A `Float32Array` view over arbitrary `Uint8Array` bytes requires 4-byte alignment, which
+* sliced buffers do not guarantee — this helper (and {@link bytesToPcm}) copy-normalize so
+* neither side has to think about alignment.
+*
+* @param pcm - Mono PCM samples in `[-1, 1]`.
+* @returns The samples as little-endian Float32 bytes.
+*/
+var pcmToBytes = (pcm) => {
+	const copy = new Float32Array(pcm);
+	return new Uint8Array(copy.buffer, 0, copy.byteLength);
+};
+/**
+* Read PCM samples back out of transport bytes.
+*
+* @param bytes - Little-endian Float32 bytes (as produced by {@link pcmToBytes}).
+* @returns The mono PCM samples.
+*/
+var bytesToPcm = (bytes) => {
+	const aligned = new Uint8Array(bytes.length);
+	aligned.set(bytes);
+	return new Float32Array(aligned.buffer, 0, Math.floor(bytes.length / 4));
+};
+var hasFns = (value, names) => require_tool_registry.isObject(value) && names.every((n) => typeof value[n] === "function");
+var isStringArray = (value) => Array.isArray(value) && value.every((v) => typeof v === "string");
+/** `true` when `value` structurally implements {@link BinaryExecutor}. */
+var implementsBinaryExecutor = (value) => hasFns(value, ["exec"]);
+/** `true` when `value` structurally implements {@link ScratchWorkspace}. */
+var implementsScratchWorkspace = (value) => hasFns(value, [
+	"materialize",
+	"read",
+	"dir",
+	"list",
+	"dispose"
+]);
+/** `true` when `value` structurally implements {@link ConvertCapability}. */
+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 MediaEngine}: a string id plus at least
+* one well-formed capability entry. Every declared entry must pass its capability guard.
+*/
+var implementsMediaEngine = (value) => {
+	if (!require_tool_registry.isObject(value)) return false;
+	const engine = value;
+	if (typeof engine.id !== "string" || engine.id.length === 0) return false;
+	const converts = engine.converts;
+	const mutates = engine.mutates;
+	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;
+};
+//#endregion
+exports.PCM_MIME = PCM_MIME;
+exports.bytesToPcm = bytesToPcm;
+exports.implementsBinaryExecutor = implementsBinaryExecutor;
+exports.implementsConvertCapability = implementsConvertCapability;
+exports.implementsMediaEngine = implementsMediaEngine;
+exports.implementsMutateCapability = implementsMutateCapability;
+exports.implementsScratchWorkspace = implementsScratchWorkspace;
+exports.pcmToBytes = pcmToBytes;
+
+//# sourceMappingURL=contracts.cjs.map

package/batteries/media/contracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.cjs","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,sBAAA,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,sBAAA,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"}