@nhtio/adk 1.20260607.2 → 1.20260609.0

package/batteries/storage/opfs.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"opfs.cjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  readonly kind: 'file'\n  readonly name: string\n  getFile(): Promise<OpfsFile>\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  readonly kind: 'directory'\n  readonly name: string\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  readonly size: number\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  text(): Promise<string>\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"opfs.cjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  /** Discriminant: always `'file'`. */\n  readonly kind: 'file'\n  /** The entry's name. */\n  readonly name: string\n  /** Resolve a readable {@link OpfsFile} snapshot of the handle's contents. */\n  getFile(): Promise<OpfsFile>\n  /** Open a writable stream that replaces the file's contents. */\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  /** Discriminant: always `'directory'`. */\n  readonly kind: 'directory'\n  /** The directory's name. */\n  readonly name: string\n  /** Resolve a child file handle, optionally creating it. */\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  /** Resolve a child directory handle, optionally creating it. */\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  /** Remove a child entry, optionally recursively. */\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  /** Append/write a chunk to the stream. */\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  /** Flush and close the stream, committing the written contents. */\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  /** Byte length of the blob. */\n  readonly size: number\n  /** Return a sub-range of the blob as a new blob. */\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  /** Read the blob's contents as text. */\n  text(): Promise<string>\n  /** Open a readable byte stream over the blob. */\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  /** The file's name. */\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  /** Acquire a reader over the stream. */\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  /** Read the next chunk, or signal end-of-stream with `done: true`. */\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  /** Release the reader's lock on the stream. */\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":"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"}

package/batteries/storage/opfs.mjs

@@ -1,4 +1,4 @@
-import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 //#region src/batteries/storage/opfs/index.ts
 /**

package/batteries/storage/opfs.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"opfs.mjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  readonly kind: 'file'\n  readonly name: string\n  getFile(): Promise<OpfsFile>\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  readonly kind: 'directory'\n  readonly name: string\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  readonly size: number\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  text(): Promise<string>\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsJA,IAAM,iCAAiC,KAAK,OAAO;AAEnD,IAAM,KAAK;AAEX,IAAM,6BAA6B,MACjC,OAAO,MAAM,YAAY,OAAO,SAAS,CAAC,KAAK,KAAK;;;;;;;;;;;;AAoDtD,IAAM,sBAA+B;CACnC,IAAI,OAAO,sBAAsB,aAAa,OAAO;CAErD,OAAO,gBAAgB;AACzB;;;;;;;;;;;;;AAcA,IAAa,kBAAb,MAAa,gBAAuC;CAClD;CACA;CACA;CAEA,YAAY,QAAwB,OAA+B,CAAC,GAAG;EACrE,KAAKA,UAAU;EACf,MAAM,MAAM,KAAK,wBAAwB;EAEzC,IAAI,OAAO,QAAQ,YAAY,OAAO,MAAM,GAAG,KAAK,MAAM,GACxD,MAAM,IAAI,UACR,wFAAwF,OAAO,GAAG,GACpG;EAEF,KAAKC,aAAa;CACpB;;;;;;;;;;CAWA,OAAc,kBAAkB,OAA0C;EACxE,OAAO,aAAa,OAAO,mBAAmB,eAAe;CAC/D;CAEA,MAAM,KAAK,OAA4C;EACrD,MAAM,QAAQ,MAAM,KAAKC,MAAM;EAC/B,IAAI,MAAM,SAAS,SAAS,OAAO,MAAM,MAAM;EAC/C,IAAI,QAAQ,KAAK,SAAS,MAAM,QAAQ,SAAS,GAAG,OAAO,KAAA;EAC3D,OAAO,KAAKC,WAAW,MAAM,MAAM,MAAM,QAAQ,QAAQ,MAAM,QAAQ,QAAQ,EAAE;CACnF;CAEA,MAAM,aAA8B;EAElC,QAAO,MADa,KAAKD,MAAM,GAClB;CACf;CAEA,MAAM,YAA6B;EACjC,MAAM,QAAQ,MAAM,KAAKA,MAAM;EAC/B,OAAO,MAAM,SAAS,UAAU,MAAM,MAAM,SAAS,MAAM,QAAQ,SAAS;CAC9E;;;;;;;;;;CAWA,MAAM,UAA2B;EAC/B,MAAM,QAAQ,MAAM,KAAKA,MAAM;EAC/B,IAAI,MAAM,SAAS,SAAS,OAAO,MAAM;EACzC,OAAO,MAAM,KAAK,KAAK;CACzB;;;;;CAMA,QAA8B;EAC5B,IAAI,CAAC,KAAKE,QAAQ,KAAKA,SAAS,KAAKC,MAAM;EAC3C,OAAO,KAAKD;CACd;CAEA,MAAMC,QAA8B;EAClC,MAAM,OAAO,MAAM,KAAKL,QAAQ,QAAQ;EACxC,MAAM,QAAQ,KAAK;EACnB,IAAI,CAAC,0BAA0B,KAAK,GAClC,MAAM,IAAI,MAAM,4DAA4D,OAAO,KAAK,EAAE,EAAE;EAE9F,IAAI,QAAQ,KAAKC,YAAY;GAE3B,MAAM,UAAU,MAAM,KAAK,KAAK;GAEhC,OAAO;IAAE,MAAM;IAAS,OADV,YAAY,KAAK,CAAC,IAAI,QAAQ,MAAM,IAAI;IACvB;IAAO;GAAQ;EAChD;EAEA,OAAO,KAAKK,qBAAqB,MAAM,KAAK;CAC9C;CAEA,MAAMA,qBAAqB,MAAgB,OAAwC;EAEjF,IAAI,UAAU,GAAG,OAAO;GAAE,MAAM;GAAa;GAAM,SAAS,CAAC,CAAC;GAAG;EAAM;EAMvE,MAAM,UAAoB,CAAC,CAAC;EAC5B,IAAI,WAAW;EACf,IAAI,WAAW;EACf,MAAM,SAAS,KAAK,OAAO,EAAE,UAAU;EACvC,IAAI;GACF,SAAS;IACP,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;IAC1C,IAAI,MAAM;IACV,KAAK,MAAM,QAAQ,OAAO;KACxB;KACA,IAAI,SAAS,IAAI,QAAQ,KAAK,QAAQ;KACtC,WAAW;IACb;GACF;EACF,UAAU;GACR,OAAO,YAAY;EACrB;EAIA,IAAI,aAAa,IAAI,QAAQ,KAAK,QAAQ;OACrC,IAAI,QAAQ,QAAQ,SAAS,OAAO,UAAU,QAAQ,KAAK,QAAQ;EACxE,OAAO;GAAE,MAAM;GAAa;GAAM;GAAS;EAAM;CACnD;;;;;;;;;;;CAYA,MAAMH,WAAW,MAAgB,OAAe,KAA8B;EAC5E,IAAI,UAAU,KAAK,OAAO;EAE1B,MAAM,OAAO,MADC,KAAK,MAAM,OAAO,GACb,EAAM,KAAK;EAC9B,IAAI,KAAK,SAAS,KAAK,KAAK,WAAW,KAAK,SAAS,CAAC,MAAM,IAC1D,OAAO,KAAK,MAAM,GAAG,EAAE;EAEzB,OAAO;CACT;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkEA,IAAa,iBAAb,MAAa,eAAqC;CAChD;CACA;CACA;CACA;CAEA,YAAY,OAA8B,CAAC,GAAG;EAC5C,KAAKI,eAAe,KAAK,oBAAoB,UAAU,QAAQ,aAAa;EAC5E,KAAKC,UAAU,KAAK,aAAa;EACjC,KAAKC,oBAAoB,KAAK,wBAAwB;CACxD;;;;;;;;;;CAWA,OAAc,iBAAiB,OAAyC;EACtE,OAAO,aAAa,OAAO,kBAAkB,cAAc;CAC7D;;;;;;;;;;;;;;;CAgBA,MAAM,MACJ,QACA,OACA,MAC0B;EAC1B,MAAM,OAAO,KAAKC,QAAQ,MAAM;EAEhC,MAAM,SAAS,OAAM,MADF,KAAKC,SAAS,GACP,cAAc,MAAM,EAAE,QAAQ,KAAK,CAAC;EAC9D,IAAI,aAAa,OAAO,kBAAkB,cAAc,GACtD,IAAI,cAAc,GAChB,MAAM,KAAKC,0BAA0B,QAAQ,KAAK;OAElD,MAAM,KAAKC,wBAAwB,QAAQ,KAAK;OAE7C;GACL,MAAM,UAAU,OAAO,UAAU,WAAW,IAAI,YAAY,EAAE,OAAO,KAAK,IAAI;GAC9E,IAAI,cAAc,GAChB,MAAM,KAAKC,oBAAoB,QAAQ,OAAO;QAE9C,MAAM,KAAKC,kBAAkB,QAAQ,OAAO;EAEhD;EACA,OAAO,IAAI,gBAAgB,QAAQ,EACjC,sBAAsB,MAAM,wBAAwB,KAAKN,kBAC3D,CAAC;CACH;;;;;;;;;;;CAYA,MAAM,KAAK,QAAgB,MAAqE;EAC9F,MAAM,OAAO,KAAKC,QAAQ,MAAM;EAChC,MAAM,OAAO,MAAM,KAAKC,SAAS;EACjC,IAAI;EACJ,IAAI;GACF,SAAS,MAAM,KAAK,cAAc,IAAI;EACxC,SAAS,KAAK;GACZ,IAAI,KAAKK,iBAAiB,GAAG,GAAG,OAAO,KAAA;GACvC,MAAM;EACR;EACA,OAAO,IAAI,gBAAgB,QAAQ,EACjC,sBAAsB,MAAM,wBAAwB,KAAKP,kBAC3D,CAAC;CACH;;;;;;;CAQA,MAAM,OAAO,QAAkC;EAC7C,MAAM,OAAO,KAAKC,QAAQ,MAAM;EAChC,MAAM,OAAO,MAAM,KAAKC,SAAS;EACjC,IAAI;GACF,MAAM,KAAK,YAAY,IAAI;GAC3B,OAAO;EACT,SAAS,KAAK;GACZ,IAAI,KAAKK,iBAAiB,GAAG,GAAG,OAAO;GACvC,MAAM;EACR;CACF;;;;;;;CAQA,MAAM,IAAI,QAAkC;EAC1C,MAAM,OAAO,KAAKN,QAAQ,MAAM;EAChC,MAAM,OAAO,MAAM,KAAKC,SAAS;EACjC,IAAI;GACF,MAAM,KAAK,cAAc,IAAI;GAC7B,OAAO;EACT,SAAS,KAAK;GACZ,IAAI,KAAKK,iBAAiB,GAAG,GAAG,OAAO;GACvC,MAAM;EACR;CACF;;;;;;;;CASA,OAAO,QAAwB;EAC7B,OAAO,KAAKN,QAAQ,MAAM;CAC5B;CAEA,QAAQ,QAAwB;EAC9B,OAAO,KAAKF,UAAU;CACxB;CAEA,MAAMG,WAAyC;EAC7C,IAAI,CAAC,KAAKM,OAAO,KAAKA,QAAQ,MAAM,KAAKV,aAAa;EACtD,OAAO,KAAKU;CACd;CAEA,MAAMH,oBAAoB,QAAwB,SAAoC;EACpF,MAAM,OAAO,MAAO,OAAwC,uBAAuB;EACnF,IAAI;GACF,KAAK,SAAS,CAAC;GACf,KAAK,MAAM,SAAS,EAAE,IAAI,EAAE,CAAC;GAC7B,KAAK,MAAM;EACb,UAAU;GACR,KAAK,MAAM;EACb;CACF;CAEA,MAAMC,kBAAkB,QAAwB,SAAoC;EAClF,MAAM,WAAW,MAAM,OAAO,eAAe;EAC7C,IAAI;GACF,MAAM,SAAS,MAAM,OAAO;EAC9B,UAAU;GACR,MAAM,SAAS,MAAM;EACvB;CACF;CAEA,MAAMF,wBACJ,QACA,QACe;EACf,MAAM,WAAW,MAAM,OAAO,eAAe;EAC7C,IAAI;GACF,MAAM,SAAS,OAAO,UAAU;GAChC,IAAI;IACF,SAAS;KACP,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;KAC1C,IAAI,MAAM;KACV,IAAI,OAAO,MAAM,SAAS,MAAM,KAAK;IACvC;GACF,UAAU;IACR,OAAO,YAAY;GACrB;EACF,UAAU;GACR,MAAM,SAAS,MAAM;EACvB;CACF;CAEA,MAAMD,0BACJ,QACA,QACe;EACf,MAAM,OAAO,MAAO,OAAwC,uBAAuB;EACnF,IAAI;GACF,KAAK,SAAS,CAAC;GACf,IAAI,KAAK;GACT,MAAM,SAAS,OAAO,UAAU;GAChC,IAAI;IACF,SAAS;KACP,MAAM,EAAE,MAAM,UAAU,MAAM,OAAO,KAAK;KAC1C,IAAI,MAAM;KACV,IAAI,SAAS,MAAM,aAAa,GAAG;MACjC,KAAK,MAAM,OAAO,EAAE,GAAG,CAAC;MACxB,MAAM,MAAM;KACd;IACF;GACF,UAAU;IACR,OAAO,YAAY;GACrB;GACA,KAAK,MAAM;EACb,UAAU;GACR,KAAK,MAAM;EACb;CACF;CAEA,iBAAiB,KAAuB;EACtC,IAAI,QAAQ,QAAQ,OAAO,QAAQ,UAAU,OAAO;EAEpD,OADc,IAA2B,SACzB;CAClB;AACF"}
+{"version":3,"file":"opfs.mjs","names":["#handle","#threshold","#load","#readRange","#ready","#init","#buildStreamingIndex","#resolveRoot","#prefix","#defaultThreshold","#keyFor","#getRoot","#writeStreamViaSyncHandle","#writeStreamViaWritable","#writeViaSyncHandle","#writeViaWritable","#isNotFoundError","#root"],"sources":["../../../src/batteries/storage/opfs/index.ts"],"sourcesContent":["/**\n * Browser-only Origin Private File System storage for spooled artifacts.\n *\n * @module @nhtio/adk/batteries/storage/opfs\n *\n * @remarks\n * Opt-in **browser-only** storage battery backed by the\n * [Origin Private File System](https://developer.mozilla.org/docs/Web/API/File_System_API/Origin_private_file_system)\n * (OPFS). Provides {@link OpfsSpoolReader} (a {@link @nhtio/adk!SpoolReader} over a `OpfsFileHandle`)\n * and {@link OpfsSpoolStore} (a `write(callId, bytes) → reader` persistence layer that wraps an\n * OPFS directory).\n *\n * The reader has two modes selected lazily on first method invocation based on the size of the\n * underlying file:\n *\n * - **Eager mode** — when `file.size` is below `streamThresholdBytes` (default 10 MiB), the\n *   reader calls `file.text()` once, splits the content on `\\n`, and caches lines + byte count.\n *   All subsequent calls resolve from memory.\n * - **Streaming mode** — when `file.size` meets or exceeds the threshold, the reader streams the\n *   file once via `file.stream().getReader()` to build a line-offset index (`number[]` of byte\n *   offsets per line), then serves each `line(i)` request by slicing the underlying `Blob` —\n *   `Blob.slice(start, end).text()` decodes only the requested range, no head-of-file scan.\n *   Caps RAM at one index + one line buffer regardless of file size.\n *\n * The store auto-selects its write API by execution scope:\n *\n * - In **worker scopes** (`self instanceof WorkerGlobalScope`), it acquires a\n *   `FileSystemSyncAccessHandle` and writes synchronously. Sync handles are the only API\n *   available in workers and the fastest path for the spool-write hot path.\n * - On the **main thread**, it uses `OpfsFileHandle.createWritable()` and the async\n *   stream API. Sync access handles are not exposed on the main thread.\n *\n * This module assumes a browser-equivalent runtime — `navigator.storage`,\n * `OpfsFileHandle`, `TextEncoder`/`TextDecoder`, and `Blob` must all exist. It must not\n * be imported from Node code; do so and you will fail at resolve time when `navigator` is\n * referenced.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\n\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport type { SpoolReader, SpoolStore } from '@nhtio/adk/common'\n\n// The project's tsconfig limits `lib` to `ESNext`, so the DOM and File System Access types\n// referenced below are not in scope by default — neither `tsc --noEmit` nor the downstream dts\n// pipeline (api-extractor) can see them. Re-declare here the **minimum** surface this module\n// touches via a local handle-shape interface. Public API uses `OpfsFileHandle` /\n// `OpfsDirectoryHandle` instead of the DOM globals so the published `.d.ts` is self-contained\n// and consumers do not have to chase the lib graph.\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsFileHandle` interface that this module touches at runtime. Structurally compatible\n * with the DOM-lib `OpfsFileHandle` — at call sites you pass real OPFS handles directly.\n */\nexport interface OpfsFileHandle {\n  /** Discriminant: always `'file'`. */\n  readonly kind: 'file'\n  /** The entry's name. */\n  readonly name: string\n  /** Resolve a readable {@link OpfsFile} snapshot of the handle's contents. */\n  getFile(): Promise<OpfsFile>\n  /** Open a writable stream that replaces the file's contents. */\n  createWritable(): Promise<OpfsWritableFileStream>\n}\n\n/**\n * Minimal subset of the\n * [File System Access](https://developer.mozilla.org/docs/Web/API/File_System_API)\n * `OpfsDirectoryHandle` interface that this module touches at runtime. Structurally\n * compatible with the DOM-lib `OpfsDirectoryHandle` — at call sites you pass real OPFS\n * handles directly.\n */\nexport interface OpfsDirectoryHandle {\n  /** Discriminant: always `'directory'`. */\n  readonly kind: 'directory'\n  /** The directory's name. */\n  readonly name: string\n  /** Resolve a child file handle, optionally creating it. */\n  getFileHandle(name: string, options?: { create?: boolean }): Promise<OpfsFileHandle>\n  /** Resolve a child directory handle, optionally creating it. */\n  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<OpfsDirectoryHandle>\n  /** Remove a child entry, optionally recursively. */\n  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `FileSystemWritableFileStream` interface used by the OPFS battery's\n * main-thread write path.\n */\nexport interface OpfsWritableFileStream {\n  /** Append/write a chunk to the stream. */\n  write(data: Uint8Array | ArrayBufferView | ArrayBuffer | string): Promise<void>\n  /** Flush and close the stream, committing the written contents. */\n  close(): Promise<void>\n}\n\n/**\n * Minimal subset of the DOM `Blob` interface used by {@link OpfsSpoolReader} streaming-mode\n * random-access reads. Real OPFS handles return a `File` here; we narrow to the methods we\n * actually call.\n */\nexport interface OpfsBlob {\n  /** Byte length of the blob. */\n  readonly size: number\n  /** Return a sub-range of the blob as a new blob. */\n  slice(start?: number, end?: number, contentType?: string): OpfsBlob\n  /** Read the blob's contents as text. */\n  text(): Promise<string>\n  /** Open a readable byte stream over the blob. */\n  stream(): OpfsReadableStream\n}\n\n/**\n * Minimal subset of the DOM `File` interface used by {@link OpfsSpoolReader}.\n */\nexport interface OpfsFile extends OpfsBlob {\n  /** The file's name. */\n  readonly name: string\n}\n\n/**\n * Minimal subset of the DOM `ReadableStream<Uint8Array>` interface used by streaming-mode\n * index construction.\n */\nexport interface OpfsReadableStream {\n  /** Acquire a reader over the stream. */\n  getReader(): OpfsReadableStreamReader\n}\n\n/**\n * Minimal subset of the DOM `ReadableStreamDefaultReader<Uint8Array>` interface used by\n * streaming-mode index construction.\n */\nexport interface OpfsReadableStreamReader {\n  /** Read the next chunk, or signal end-of-stream with `done: true`. */\n  read(): Promise<{ done: false; value: Uint8Array } | { done: true; value: undefined }>\n  /** Release the reader's lock on the stream. */\n  releaseLock(): void\n}\n\ndeclare const navigator: {\n  storage: { getDirectory(): Promise<OpfsDirectoryHandle> }\n}\ndeclare class TextEncoder {\n  encode(input?: string): Uint8Array\n}\ndeclare const self: unknown\ndeclare const WorkerGlobalScope: { new (): unknown } | undefined\n\ninterface FileSystemSyncAccessHandle {\n  truncate(newSize: number): void\n  write(buffer: Uint8Array | ArrayBuffer | ArrayBufferView, options?: { at?: number }): number\n  flush(): void\n  close(): void\n}\ninterface OpfsFileHandleWithSyncAccess extends OpfsFileHandle {\n  createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>\n}\n\nconst DEFAULT_STREAM_THRESHOLD_BYTES = 10 * 1024 * 1024 // 10 MiB\n\nconst LF = 0x0a // '\\n'\n\nconst isNonNegativeFiniteNumber = (n: unknown): n is number =>\n  typeof n === 'number' && Number.isFinite(n) && n >= 0\n\n/**\n * Constructor options for {@link OpfsSpoolReader}.\n */\nexport interface OpfsSpoolReaderOptions {\n  /**\n   * Byte-length threshold that switches between eager and streaming modes.\n   *\n   * @remarks\n   * - Below the threshold → eager (whole-file in memory).\n   * - At or above the threshold → streaming (line-offset index + per-line slice reads).\n   *\n   * Set to `0` to force streaming mode; set to `Number.POSITIVE_INFINITY` to force eager mode.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\ninterface EagerState {\n  mode: 'eager'\n  lines: string[]\n  bytes: number\n  content: string\n}\n\ninterface StreamingState {\n  mode: 'streaming'\n  file: OpfsFile\n  /**\n   * Byte offsets where each line *starts*. Length equals lineCount + 1; the final entry equals\n   * the total byte length. So `offsets[i + 1] - offsets[i]` is the byte length of line `i`\n   * including any trailing `\\n`.\n   */\n  offsets: number[]\n  bytes: number\n}\n\ntype ReaderState = EagerState | StreamingState\n\n/**\n * Returns `true` when the current global scope is a Web Worker (`DedicatedWorkerGlobalScope`,\n * `SharedWorkerGlobalScope`, or `ServiceWorkerGlobalScope` all inherit from `WorkerGlobalScope`).\n *\n * @remarks\n * The check is needed at runtime because `FileSystemSyncAccessHandle` is only exposed in worker\n * scopes — calling it from the main thread throws. We pick the write strategy based on the\n * answer here.\n *\n * @internal\n */\nconst isWorkerScope = (): boolean => {\n  if (typeof WorkerGlobalScope === 'undefined') return false\n  // eslint-disable-next-line adk/use-is-instance-of -- native built-in narrowing on `self`; no cross-realm risk\n  return self instanceof WorkerGlobalScope\n}\n\n/**\n * Reads an OPFS-backed file as a {@link @nhtio/adk!SpoolReader}.\n *\n * @remarks\n * Constructor is **not** async — but the first method call awaits a private readiness promise\n * that fetches the underlying `File` (and in eager mode, its contents). Subsequent calls reuse\n * the cached state. This keeps construction call sites synchronous while still doing real I/O\n * lazily.\n *\n * All four `SpoolReader` methods on this reader return promises. The `SpoolReader` contract\n * supports both sync and async return; consumers of `SpooledArtifact` handle either.\n */\nexport class OpfsSpoolReader implements SpoolReader {\n  readonly #handle: OpfsFileHandle\n  readonly #threshold: number\n  #ready: Promise<ReaderState> | undefined\n\n  constructor(handle: OpfsFileHandle, opts: OpfsSpoolReaderOptions = {}) {\n    this.#handle = handle\n    const raw = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n    // Allow `Infinity` (forces eager) but reject anything non-finite-negative.\n    if (typeof raw !== 'number' || Number.isNaN(raw) || raw < 0) {\n      throw new TypeError(\n        `OpfsSpoolReader: streamThresholdBytes must be a non-negative number or Infinity, got ${String(raw)}`\n      )\n    }\n    this.#threshold = raw\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolReader} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolReader} instance.\n   */\n  public static isOpfsSpoolReader(value: unknown): value is OpfsSpoolReader {\n    return isInstanceOf(value, 'OpfsSpoolReader', OpfsSpoolReader)\n  }\n\n  async line(index: number): Promise<string | undefined> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.lines[index]\n    if (index < 0 || index >= state.offsets.length - 1) return undefined\n    return this.#readRange(state.file, state.offsets[index], state.offsets[index + 1])\n  }\n\n  async byteLength(): Promise<number> {\n    const state = await this.#load()\n    return state.bytes\n  }\n\n  async lineCount(): Promise<number> {\n    const state = await this.#load()\n    return state.mode === 'eager' ? state.lines.length : state.offsets.length - 1\n  }\n\n  /**\n   * Returns the full underlying content as a single decoded string, byte-faithful to the source.\n   *\n   * @remarks\n   * In **eager mode** the content is already cached at first-call load and this method is\n   * effectively a property access. In **streaming mode** there is no cache: the file is re-read\n   * (as a single `File.text()` call) on every invocation. Use `SpooledArtifact.asString()`\n   * judiciously on large streaming-mode artifacts.\n   */\n  async readAll(): Promise<string> {\n    const state = await this.#load()\n    if (state.mode === 'eager') return state.content\n    return state.file.text()\n  }\n\n  /**\n   * Lazily initialise the reader's mode-specific state. Called by every public method; the\n   * promise is cached so the work runs at most once.\n   */\n  #load(): Promise<ReaderState> {\n    if (!this.#ready) this.#ready = this.#init()\n    return this.#ready\n  }\n\n  async #init(): Promise<ReaderState> {\n    const file = await this.#handle.getFile()\n    const bytes = file.size\n    if (!isNonNegativeFiniteNumber(bytes)) {\n      throw new Error(`OpfsSpoolReader: file handle returned a non-finite size (${String(bytes)})`)\n    }\n    if (bytes < this.#threshold) {\n      // Eager — pull the whole thing into memory.\n      const content = await file.text()\n      const lines = content === '' ? [] : content.split('\\n')\n      return { mode: 'eager', lines, bytes, content }\n    }\n    // Streaming — build a line-offset index by scanning bytes once.\n    return this.#buildStreamingIndex(file, bytes)\n  }\n\n  async #buildStreamingIndex(file: OpfsFile, bytes: number): Promise<StreamingState> {\n    // Edge case first — an empty file is one offset (the EOF), zero lines.\n    if (bytes === 0) return { mode: 'streaming', file, offsets: [0], bytes }\n\n    // offsets[i] is the byte position where line `i` starts. offsets[lineCount] is one-past-end.\n    // For \"a\\nb\\nc\" → offsets=[0, 2, 4, 5] (3 lines).\n    // For \"a\\nb\\n\"  → offsets=[0, 2, 4, 4] (3 lines, last is the trailing empty line). This\n    // mirrors `String.prototype.split('\\n')` semantics so streaming and eager agree.\n    const offsets: number[] = [0]\n    let position = 0\n    let lastByte = -1\n    const reader = file.stream().getReader()\n    try {\n      for (;;) {\n        const { done, value } = await reader.read()\n        if (done) break\n        for (const byte of value) {\n          position++\n          if (byte === LF) offsets.push(position)\n          lastByte = byte\n        }\n      }\n    } finally {\n      reader.releaseLock()\n    }\n    // If the file ends on a newline, the byte after the LF is the start of an empty trailing\n    // line — record it. If it doesn't, the final line's end is the EOF and we need to push\n    // it so line(N-1) can read up to bytes.\n    if (lastByte === LF) offsets.push(position)\n    else if (offsets[offsets.length - 1] !== position) offsets.push(position)\n    return { mode: 'streaming', file, offsets, bytes }\n  }\n\n  /**\n   * Slices the byte range `[start, end)` from the backing file and returns it as a UTF-8\n   * string, stripping a trailing `\\n` if present.\n   *\n   * @remarks\n   * `Blob.slice` is O(1) metadata; `Blob.text()` only decodes the slice. The line-offset index\n   * brackets each line *with* its trailing LF (so `offsets[i+1]` points at the start of the\n   * next line) and the `SpoolReader` contract returns lines *without* their trailing newline,\n   * so we strip a single trailing LF if present.\n   */\n  async #readRange(file: OpfsFile, start: number, end: number): Promise<string> {\n    if (start === end) return ''\n    const slice = file.slice(start, end)\n    const text = await slice.text()\n    if (text.length > 0 && text.charCodeAt(text.length - 1) === LF) {\n      return text.slice(0, -1)\n    }\n    return text\n  }\n}\n\n/**\n * Constructor options for {@link OpfsSpoolStore}.\n */\nexport interface OpfsSpoolStoreOptions {\n  /**\n   * Optional thunk that resolves the {@link OpfsDirectoryHandle} used as the store root.\n   *\n   * @remarks\n   * When omitted, the store resolves the root via `navigator.storage.getDirectory()` on its\n   * first filesystem call. Override for tests (to point at a per-suite subdirectory) or to\n   * scope the store to a nested directory inside OPFS.\n   *\n   * The thunk is invoked at most once per store; the returned handle is memoised.\n   */\n  directory?: () => Promise<OpfsDirectoryHandle>\n\n  /**\n   * Optional filename prefix prepended to every `callId`.\n   *\n   * @remarks\n   * Prefix is a **filename prefix**, not a subdirectory — `keyPrefix: 'agent-runs/'` produces\n   * a file literally named `agent-runs/<callId>` at the root, not a nested directory. (OPFS\n   * filenames may not contain `/`, so use a non-`/` separator like `-` if you want a flat\n   * namespace.) This mirrors the `keyPrefix` semantics in the flydrive and in-memory batteries.\n   *\n   * @defaultValue `\"\"`\n   */\n  keyPrefix?: string\n\n  /**\n   * Default `streamThresholdBytes` for readers produced by `write()` and `read()`. Individual\n   * calls may override via their own `opts` argument.\n   *\n   * @defaultValue `10 * 1024 * 1024` (10 MiB)\n   */\n  streamThresholdBytes?: number\n}\n\n/**\n * \"Give bytes, get a reader\" persistence layer over an OPFS directory.\n *\n * @remarks\n * `write(callId, bytes)` resolves the root directory (lazily, on first call), opens or creates\n * the file named `keyPrefix + callId`, then writes via the API matching the current scope:\n * a `FileSystemSyncAccessHandle` in worker scopes, `OpfsFileHandle.createWritable()` on\n * the main thread. A fresh {@link OpfsSpoolReader} pointed at the same file is returned.\n *\n * `read(callId)` returns a reader without re-writing; `delete(callId)` removes the entry.\n *\n * The store is otherwise stateless — it owns no in-memory cache of writes. Multiple\n * `OpfsSpoolStore` instances sharing the same root directory and key prefix see the same data.\n *\n * @example\n * ```ts\n * import { OpfsSpoolStore } from '@nhtio/adk/batteries/storage/opfs'\n *\n * const store = new OpfsSpoolStore({ keyPrefix: 'agent-runs/' })\n *\n * const bytes = await tool.executor(ctx)(args)\n * const reader = await store.write(callId, bytes)\n * const Ctor = tool.artifactConstructor?.() ?? SpooledArtifact\n * const artifact = new Ctor(reader)\n * ```\n */\nexport class OpfsSpoolStore implements SpoolStore {\n  readonly #resolveRoot: () => Promise<OpfsDirectoryHandle>\n  readonly #prefix: string\n  readonly #defaultThreshold: number\n  #root: OpfsDirectoryHandle | undefined\n\n  constructor(opts: OpfsSpoolStoreOptions = {}) {\n    this.#resolveRoot = opts.directory ?? (() => navigator.storage.getDirectory())\n    this.#prefix = opts.keyPrefix ?? ''\n    this.#defaultThreshold = opts.streamThresholdBytes ?? DEFAULT_STREAM_THRESHOLD_BYTES\n  }\n\n  /**\n   * Returns `true` if `value` is an {@link OpfsSpoolStore} instance.\n   *\n   * @remarks\n   * Uses {@link @nhtio/adk!isInstanceOf} for cross-realm safety.\n   *\n   * @param value - The value to test.\n   * @returns `true` when `value` is an {@link OpfsSpoolStore} instance.\n   */\n  public static isOpfsSpoolStore(value: unknown): value is OpfsSpoolStore {\n    return isInstanceOf(value, 'OpfsSpoolStore', OpfsSpoolStore)\n  }\n\n  /**\n   * Persists `bytes` under `callId` and returns a reader bound to the stored key.\n   *\n   * @remarks\n   * `string` input is encoded as UTF-8; `Uint8Array` is stored byte-faithfully;\n   * `ReadableStream<Uint8Array>` is written incrementally — the stream is consumed chunk-by-chunk\n   * straight to OPFS without first materializing the whole payload in memory, which is the point\n   * of accepting a stream for a durable store.\n   *\n   * @param callId - Identifier used to retrieve the bytes via {@link OpfsSpoolStore.read}.\n   * @param bytes - The bytes to store, as a `string`, `Uint8Array`, or `ReadableStream<Uint8Array>`.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader} over the stored bytes.\n   */\n  async write(\n    callId: string,\n    bytes: string | Uint8Array | ReadableStream<Uint8Array>,\n    opts?: OpfsSpoolReaderOptions\n  ): Promise<OpfsSpoolReader> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    const handle = await root.getFileHandle(name, { create: true })\n    if (isInstanceOf(bytes, 'ReadableStream', ReadableStream)) {\n      if (isWorkerScope()) {\n        await this.#writeStreamViaSyncHandle(handle, bytes)\n      } else {\n        await this.#writeStreamViaWritable(handle, bytes)\n      }\n    } else {\n      const payload = typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes\n      if (isWorkerScope()) {\n        await this.#writeViaSyncHandle(handle, payload)\n      } else {\n        await this.#writeViaWritable(handle, payload)\n      }\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Returns a reader over the bytes previously written under `callId`.\n   *\n   * @remarks\n   * Returns `undefined` if the file does not exist.\n   *\n   * @param callId - Identifier supplied to a prior {@link OpfsSpoolStore.write} call.\n   * @param opts - Per-call override for `streamThresholdBytes`.\n   * @returns An {@link OpfsSpoolReader}, or `undefined` if the key is missing.\n   */\n  async read(callId: string, opts?: OpfsSpoolReaderOptions): Promise<OpfsSpoolReader | undefined> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    let handle: OpfsFileHandle\n    try {\n      handle = await root.getFileHandle(name)\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return undefined\n      throw err\n    }\n    return new OpfsSpoolReader(handle, {\n      streamThresholdBytes: opts?.streamThresholdBytes ?? this.#defaultThreshold,\n    })\n  }\n\n  /**\n   * Removes the entry under `callId`.\n   *\n   * @param callId - Identifier whose entry should be removed.\n   * @returns `true` if the entry existed and was removed; `false` if it didn't exist.\n   */\n  async delete(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.removeEntry(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns `true` if a file is present under `callId`.\n   *\n   * @param callId - Identifier to test.\n   * @returns `true` when the file exists, `false` otherwise.\n   */\n  async has(callId: string): Promise<boolean> {\n    const name = this.#keyFor(callId)\n    const root = await this.#getRoot()\n    try {\n      await root.getFileHandle(name)\n      return true\n    } catch (err) {\n      if (this.#isNotFoundError(err)) return false\n      throw err\n    }\n  }\n\n  /**\n   * Returns the full filename for a given `callId` (i.e. `keyPrefix + callId`).\n   *\n   * @remarks\n   * Useful for tests or for callers that want to interact with the underlying OPFS directory\n   * directly.\n   */\n  keyFor(callId: string): string {\n    return this.#keyFor(callId)\n  }\n\n  #keyFor(callId: string): string {\n    return this.#prefix + callId\n  }\n\n  async #getRoot(): Promise<OpfsDirectoryHandle> {\n    if (!this.#root) this.#root = await this.#resolveRoot()\n    return this.#root\n  }\n\n  async #writeViaSyncHandle(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      sync.write(payload, { at: 0 })\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  async #writeViaWritable(handle: OpfsFileHandle, payload: Uint8Array): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      await writable.write(payload)\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaWritable(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const writable = await handle.createWritable()\n    try {\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value) await writable.write(value)\n        }\n      } finally {\n        reader.releaseLock()\n      }\n    } finally {\n      await writable.close()\n    }\n  }\n\n  async #writeStreamViaSyncHandle(\n    handle: OpfsFileHandle,\n    stream: ReadableStream<Uint8Array>\n  ): Promise<void> {\n    const sync = await (handle as OpfsFileHandleWithSyncAccess).createSyncAccessHandle()\n    try {\n      sync.truncate(0)\n      let at = 0\n      const reader = stream.getReader()\n      try {\n        for (;;) {\n          const { done, value } = await reader.read()\n          if (done) break\n          if (value && value.byteLength > 0) {\n            sync.write(value, { at })\n            at += value.byteLength\n          }\n        }\n      } finally {\n        reader.releaseLock()\n      }\n      sync.flush()\n    } finally {\n      sync.close()\n    }\n  }\n\n  #isNotFoundError(err: unknown): boolean {\n    if (err === null || typeof err !== 'object') return false\n    const name = (err as { name?: unknown }).name\n    return name === 'NotFoundError'\n  }\n}\n"],"mappings":"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"}

package/batteries/tools/color.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool = require("../../tool-CVyZkFC7.js");
-require("../../common-Cj8TaQ9U.js");
+const require_tool = require("../../tool-D5WGVIcI.js");
+require("../../common-DZl3ADJs.js");
 let _nhtio_validation = require("@nhtio/validation");
 //#region src/batteries/tools/color/index.ts
 /**
@@ -15,6 +15,7 @@ let _nhtio_validation = require("@nhtio/validation");
 */
 function hexToRgb(hex) {
 	const cleaned = hex.replace(/^#/, "");
+	if (!/^[0-9a-fA-F]+$/.test(cleaned)) return null;
 	let r;
 	let g;
 	let b;

package/batteries/tools/color.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"color.cjs","names":[],"sources":["../../../src/batteries/tools/color/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for color conversion and palette-oriented calculations.\n *\n * @module @nhtio/adk/batteries/tools/color\n *\n * @remarks\n * Pre-constructed bundled tools for the `color` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { validator } from '@nhtio/validation'\n\ntype RGB = { r: number; g: number; b: number }\ntype HSL = { h: number; s: number; l: number }\n\nfunction hexToRgb(hex: string): RGB | null {\n  const cleaned = hex.replace(/^#/, '')\n  let r: number\n  let g: number\n  let b: number\n\n  if (cleaned.length === 3) {\n    r = Number.parseInt(cleaned[0] + cleaned[0], 16)\n    g = Number.parseInt(cleaned[1] + cleaned[1], 16)\n    b = Number.parseInt(cleaned[2] + cleaned[2], 16)\n  } else if (cleaned.length === 6) {\n    r = Number.parseInt(cleaned.slice(0, 2), 16)\n    g = Number.parseInt(cleaned.slice(2, 4), 16)\n    b = Number.parseInt(cleaned.slice(4, 6), 16)\n  } else {\n    return null\n  }\n\n  if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) return null\n  return { r, g, b }\n}\n\nfunction parseRgbString(input: string): RGB | null {\n  const match = input.match(/^rgb\\(\\s*(\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)\\s*\\)$/i)\n  if (!match) return null\n  const r = Number.parseInt(match[1], 10)\n  const g = Number.parseInt(match[2], 10)\n  const b = Number.parseInt(match[3], 10)\n  if (r > 255 || g > 255 || b > 255) return null\n  return { r, g, b }\n}\n\nfunction parseHslString(input: string): HSL | null {\n  const match = input.match(/^hsl\\(\\s*(\\d+)\\s*,\\s*(\\d+)%?\\s*,\\s*(\\d+)%?\\s*\\)$/i)\n  if (!match) return null\n  return {\n    h: Number.parseInt(match[1], 10) % 360,\n    s: Math.min(100, Number.parseInt(match[2], 10)),\n    l: Math.min(100, Number.parseInt(match[3], 10)),\n  }\n}\n\nconst NAMED_COLORS: Record<string, string> = {\n  'black': '#000000',\n  'white': '#FFFFFF',\n  'transparent': '#FFFFFF',\n  'aqua': '#00FFFF',\n  'magenta': '#FF00FF',\n  'fuchsia': '#FF00FF',\n  'silver': '#C0C0C0',\n  'maroon': '#800000',\n  'olive': '#808000',\n  'navy': '#000080',\n  'coral': '#FF7F50',\n  'crimson': '#DC143C',\n  'gold': '#FFD700',\n  'ivory': '#FFFFF0',\n  'khaki': '#F0E68C',\n  'lavender': '#E6E6FA',\n  'plum': '#DDA0DD',\n  'salmon': '#FA8072',\n  'sienna': '#A0522D',\n  'tan': '#D2B48C',\n  'tomato': '#FF6347',\n  'turquoise': '#40E0D0',\n  'violet': '#EE82EE',\n  'wheat': '#F5DEB3',\n  'red': '#F44336',\n  'red-lighten-5': '#FFEBEE',\n  'red-lighten-4': '#FFCDD2',\n  'red-lighten-3': '#EF9A9A',\n  'red-lighten-2': '#E57373',\n  'red-lighten-1': '#EF5350',\n  'red-darken-1': '#E53935',\n  'red-darken-2': '#D32F2F',\n  'red-darken-3': '#C62828',\n  'red-darken-4': '#B71C1C',\n  'red-accent-1': '#FF8A80',\n  'red-accent-2': '#FF5252',\n  'red-accent-3': '#FF1744',\n  'red-accent-4': '#D50000',\n  'pink': '#E91E63',\n  'pink-lighten-5': '#FCE4EC',\n  'pink-lighten-4': '#F8BBD0',\n  'pink-lighten-3': '#F48FB1',\n  'pink-lighten-2': '#F06292',\n  'pink-lighten-1': '#EC407A',\n  'pink-darken-1': '#D81B60',\n  'pink-darken-2': '#C2185B',\n  'pink-darken-3': '#AD1457',\n  'pink-darken-4': '#880E4F',\n  'pink-accent-1': '#FF80AB',\n  'pink-accent-2': '#FF4081',\n  'pink-accent-3': '#F50057',\n  'pink-accent-4': '#C51162',\n  'purple': '#9C27B0',\n  'purple-lighten-5': '#F3E5F5',\n  'purple-lighten-4': '#E1BEE7',\n  'purple-lighten-3': '#CE93D8',\n  'purple-lighten-2': '#BA68C8',\n  'purple-lighten-1': '#AB47BC',\n  'purple-darken-1': '#8E24AA',\n  'purple-darken-2': '#7B1FA2',\n  'purple-darken-3': '#6A1B9A',\n  'purple-darken-4': '#4A148C',\n  'purple-accent-1': '#EA80FC',\n  'purple-accent-2': '#E040FB',\n  'purple-accent-3': '#D500F9',\n  'purple-accent-4': '#AA00FF',\n  'deep-purple': '#673AB7',\n  'deep-purple-lighten-5': '#EDE7F6',\n  'deep-purple-lighten-4': '#D1C4E9',\n  'deep-purple-lighten-3': '#B39DDB',\n  'deep-purple-lighten-2': '#9575CD',\n  'deep-purple-lighten-1': '#7E57C2',\n  'deep-purple-darken-1': '#5E35B1',\n  'deep-purple-darken-2': '#512DA8',\n  'deep-purple-darken-3': '#4527A0',\n  'deep-purple-darken-4': '#311B92',\n  'deep-purple-accent-1': '#B388FF',\n  'deep-purple-accent-2': '#7C4DFF',\n  'deep-purple-accent-3': '#651FFF',\n  'deep-purple-accent-4': '#6200EA',\n  'indigo': '#3F51B5',\n  'indigo-lighten-5': '#E8EAF6',\n  'indigo-lighten-4': '#C5CAE9',\n  'indigo-lighten-3': '#9FA8DA',\n  'indigo-lighten-2': '#7986CB',\n  'indigo-lighten-1': '#5C6BC0',\n  'indigo-darken-1': '#3949AB',\n  'indigo-darken-2': '#303F9F',\n  'indigo-darken-3': '#283593',\n  'indigo-darken-4': '#1A237E',\n  'indigo-accent-1': '#8C9EFF',\n  'indigo-accent-2': '#536DFE',\n  'indigo-accent-3': '#3D5AFE',\n  'indigo-accent-4': '#304FFE',\n  'blue': '#2196F3',\n  'blue-lighten-5': '#E3F2FD',\n  'blue-lighten-4': '#BBDEFB',\n  'blue-lighten-3': '#90CAF9',\n  'blue-lighten-2': '#64B5F6',\n  'blue-lighten-1': '#42A5F5',\n  'blue-darken-1': '#1E88E5',\n  'blue-darken-2': '#1976D2',\n  'blue-darken-3': '#1565C0',\n  'blue-darken-4': '#0D47A1',\n  'blue-accent-1': '#82B1FF',\n  'blue-accent-2': '#448AFF',\n  'blue-accent-3': '#2979FF',\n  'blue-accent-4': '#2962FF',\n  'light-blue': '#03A9F4',\n  'light-blue-lighten-5': '#E1F5FE',\n  'light-blue-lighten-4': '#B3E5FC',\n  'light-blue-lighten-3': '#81D4FA',\n  'light-blue-lighten-2': '#4FC3F7',\n  'light-blue-lighten-1': '#29B6F6',\n  'light-blue-darken-1': '#039BE5',\n  'light-blue-darken-2': '#0288D1',\n  'light-blue-darken-3': '#0277BD',\n  'light-blue-darken-4': '#01579B',\n  'light-blue-accent-1': '#80D8FF',\n  'light-blue-accent-2': '#40C4FF',\n  'light-blue-accent-3': '#00B0FF',\n  'light-blue-accent-4': '#0091EA',\n  'cyan': '#00BCD4',\n  'cyan-lighten-5': '#E0F7FA',\n  'cyan-lighten-4': '#B2EBF2',\n  'cyan-lighten-3': '#80DEEA',\n  'cyan-lighten-2': '#4DD0E1',\n  'cyan-lighten-1': '#26C6DA',\n  'cyan-darken-1': '#00ACC1',\n  'cyan-darken-2': '#0097A7',\n  'cyan-darken-3': '#00838F',\n  'cyan-darken-4': '#006064',\n  'cyan-accent-1': '#84FFFF',\n  'cyan-accent-2': '#18FFFF',\n  'cyan-accent-3': '#00E5FF',\n  'cyan-accent-4': '#00B8D4',\n  'teal': '#009688',\n  'teal-lighten-5': '#E0F2F1',\n  'teal-lighten-4': '#B2DFDB',\n  'teal-lighten-3': '#80CBC4',\n  'teal-lighten-2': '#4DB6AC',\n  'teal-lighten-1': '#26A69A',\n  'teal-darken-1': '#00897B',\n  'teal-darken-2': '#00796B',\n  'teal-darken-3': '#00695C',\n  'teal-darken-4': '#004D40',\n  'teal-accent-1': '#A7FFEB',\n  'teal-accent-2': '#64FFDA',\n  'teal-accent-3': '#1DE9B6',\n  'teal-accent-4': '#00BFA5',\n  'green': '#4CAF50',\n  'green-lighten-5': '#E8F5E9',\n  'green-lighten-4': '#C8E6C9',\n  'green-lighten-3': '#A5D6A7',\n  'green-lighten-2': '#81C784',\n  'green-lighten-1': '#66BB6A',\n  'green-darken-1': '#43A047',\n  'green-darken-2': '#388E3C',\n  'green-darken-3': '#2E7D32',\n  'green-darken-4': '#1B5E20',\n  'green-accent-1': '#B9F6CA',\n  'green-accent-2': '#69F0AE',\n  'green-accent-3': '#00E676',\n  'green-accent-4': '#00C853',\n  'light-green': '#8BC34A',\n  'light-green-lighten-5': '#F1F8E9',\n  'light-green-lighten-4': '#DCEDC8',\n  'light-green-lighten-3': '#C5E1A5',\n  'light-green-lighten-2': '#AED581',\n  'light-green-lighten-1': '#9CCC65',\n  'light-green-darken-1': '#7CB342',\n  'light-green-darken-2': '#689F38',\n  'light-green-darken-3': '#558B2F',\n  'light-green-darken-4': '#33691E',\n  'light-green-accent-1': '#CCFF90',\n  'light-green-accent-2': '#B2FF59',\n  'light-green-accent-3': '#76FF03',\n  'light-green-accent-4': '#64DD17',\n  'lime': '#CDDC39',\n  'lime-lighten-5': '#F9FBE7',\n  'lime-lighten-4': '#F0F4C3',\n  'lime-lighten-3': '#E6EE9C',\n  'lime-lighten-2': '#DCE775',\n  'lime-lighten-1': '#D4E157',\n  'lime-darken-1': '#C0CA33',\n  'lime-darken-2': '#AFB42B',\n  'lime-darken-3': '#9E9D24',\n  'lime-darken-4': '#827717',\n  'lime-accent-1': '#F4FF81',\n  'lime-accent-2': '#EEFF41',\n  'lime-accent-3': '#C6FF00',\n  'lime-accent-4': '#AEEA00',\n  'yellow': '#FFEB3B',\n  'yellow-lighten-5': '#FFFDE7',\n  'yellow-lighten-4': '#FFF9C4',\n  'yellow-lighten-3': '#FFF59D',\n  'yellow-lighten-2': '#FFF176',\n  'yellow-lighten-1': '#FFEE58',\n  'yellow-darken-1': '#FDD835',\n  'yellow-darken-2': '#FBC02D',\n  'yellow-darken-3': '#F9A825',\n  'yellow-darken-4': '#F57F17',\n  'yellow-accent-1': '#FFFF8D',\n  'yellow-accent-2': '#FFFF00',\n  'yellow-accent-3': '#FFEA00',\n  'yellow-accent-4': '#FFD600',\n  'amber': '#FFC107',\n  'amber-lighten-5': '#FFF8E1',\n  'amber-lighten-4': '#FFECB3',\n  'amber-lighten-3': '#FFE082',\n  'amber-lighten-2': '#FFD54F',\n  'amber-lighten-1': '#FFCA28',\n  'amber-darken-1': '#FFB300',\n  'amber-darken-2': '#FFA000',\n  'amber-darken-3': '#FF8F00',\n  'amber-darken-4': '#FF6F00',\n  'amber-accent-1': '#FFE57F',\n  'amber-accent-2': '#FFD740',\n  'amber-accent-3': '#FFC400',\n  'amber-accent-4': '#FFAB00',\n  'orange': '#FF9800',\n  'orange-lighten-5': '#FFF3E0',\n  'orange-lighten-4': '#FFE0B2',\n  'orange-lighten-3': '#FFCC80',\n  'orange-lighten-2': '#FFB74D',\n  'orange-lighten-1': '#FFA726',\n  'orange-darken-1': '#FB8C00',\n  'orange-darken-2': '#F57C00',\n  'orange-darken-3': '#EF6C00',\n  'orange-darken-4': '#E65100',\n  'orange-accent-1': '#FFD180',\n  'orange-accent-2': '#FFAB40',\n  'orange-accent-3': '#FF9100',\n  'orange-accent-4': '#FF6D00',\n  'deep-orange': '#FF5722',\n  'deep-orange-lighten-5': '#FBE9E7',\n  'deep-orange-lighten-4': '#FFCCBC',\n  'deep-orange-lighten-3': '#FFAB91',\n  'deep-orange-lighten-2': '#FF8A65',\n  'deep-orange-lighten-1': '#FF7043',\n  'deep-orange-darken-1': '#F4511E',\n  'deep-orange-darken-2': '#E64A19',\n  'deep-orange-darken-3': '#D84315',\n  'deep-orange-darken-4': '#BF360C',\n  'deep-orange-accent-1': '#FF9E80',\n  'deep-orange-accent-2': '#FF6E40',\n  'deep-orange-accent-3': '#FF3D00',\n  'deep-orange-accent-4': '#DD2C00',\n  'brown': '#795548',\n  'brown-lighten-5': '#EFEBE9',\n  'brown-lighten-4': '#D7CCC8',\n  'brown-lighten-3': '#BCAAA4',\n  'brown-lighten-2': '#A1887F',\n  'brown-lighten-1': '#8D6E63',\n  'brown-darken-1': '#6D4C41',\n  'brown-darken-2': '#5D4037',\n  'brown-darken-3': '#4E342E',\n  'brown-darken-4': '#3E2723',\n  'blue-grey': '#607D8B',\n  'blue-grey-lighten-5': '#ECEFF1',\n  'blue-grey-lighten-4': '#CFD8DC',\n  'blue-grey-lighten-3': '#B0BEC5',\n  'blue-grey-lighten-2': '#90A4AE',\n  'blue-grey-lighten-1': '#78909C',\n  'blue-grey-darken-1': '#546E7A',\n  'blue-grey-darken-2': '#455A64',\n  'blue-grey-darken-3': '#37474F',\n  'blue-grey-darken-4': '#263238',\n  'grey': '#9E9E9E',\n  'gray': '#9E9E9E',\n  'grey-lighten-5': '#FAFAFA',\n  'grey-lighten-4': '#F5F5F5',\n  'grey-lighten-3': '#EEEEEE',\n  'grey-lighten-2': '#E0E0E0',\n  'grey-lighten-1': '#BDBDBD',\n  'grey-darken-1': '#757575',\n  'grey-darken-2': '#616161',\n  'grey-darken-3': '#424242',\n  'grey-darken-4': '#212121',\n}\n\nfunction parseColor(input: string): RGB | null {\n  const trimmed = input.trim()\n  const lower = trimmed.toLowerCase()\n\n  if (NAMED_COLORS[lower]) {\n    return hexToRgb(NAMED_COLORS[lower])\n  }\n\n  if (trimmed.startsWith('#')) return hexToRgb(trimmed)\n  if (lower.startsWith('rgb(')) return parseRgbString(trimmed)\n  if (lower.startsWith('hsl(')) {\n    const hsl = parseHslString(trimmed)\n    return hsl ? hslToRgb(hsl) : null\n  }\n\n  return hexToRgb(trimmed)\n}\n\nfunction rgbToHex(rgb: RGB): string {\n  const toHex = (n: number) =>\n    Math.round(Math.max(0, Math.min(255, n)))\n      .toString(16)\n      .padStart(2, '0')\n  return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`\n}\n\nfunction rgbToHsl(rgb: RGB): HSL {\n  const r = rgb.r / 255\n  const g = rgb.g / 255\n  const b = rgb.b / 255\n\n  const max = Math.max(r, g, b)\n  const min = Math.min(r, g, b)\n  const l = (max + min) / 2\n\n  if (max === min) return { h: 0, s: 0, l: Math.round(l * 100) }\n\n  const d = max - min\n  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)\n\n  let h = 0\n  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6\n  else if (max === g) h = ((b - r) / d + 2) / 6\n  else h = ((r - g) / d + 4) / 6\n\n  return {\n    h: Math.round(h * 360),\n    s: Math.round(s * 100),\n    l: Math.round(l * 100),\n  }\n}\n\nfunction hslToRgb(hsl: HSL): RGB {\n  const h = hsl.h / 360\n  const s = hsl.s / 100\n  const l = hsl.l / 100\n\n  if (s === 0) {\n    const v = Math.round(l * 255)\n    return { r: v, g: v, b: v }\n  }\n\n  const hue2rgb = (p: number, q: number, t: number) => {\n    if (t < 0) t += 1\n    if (t > 1) t -= 1\n    if (t < 1 / 6) return p + (q - p) * 6 * t\n    if (t < 1 / 2) return q\n    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6\n    return p\n  }\n\n  const q = l < 0.5 ? l * (1 + s) : l + s - l * s\n  const p = 2 * l - q\n\n  return {\n    r: Math.round(hue2rgb(p, q, h + 1 / 3) * 255),\n    g: Math.round(hue2rgb(p, q, h) * 255),\n    b: Math.round(hue2rgb(p, q, h - 1 / 3) * 255),\n  }\n}\n\nfunction relativeLuminance(rgb: RGB): number {\n  const srgb = [rgb.r, rgb.g, rgb.b].map((c) => {\n    const s = c / 255\n    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)\n  })\n  return 0.2126 * srgb[0] + 0.7152 * srgb[1] + 0.0722 * srgb[2]\n}\n\nfunction contrastRatio(c1: RGB, c2: RGB): number {\n  const l1 = relativeLuminance(c1)\n  const l2 = relativeLuminance(c2)\n  const lighter = Math.max(l1, l2)\n  const darker = Math.min(l1, l2)\n  return (lighter + 0.05) / (darker + 0.05)\n}\n\nfunction rotateHue(hsl: HSL, degrees: number): HSL {\n  return { h: (hsl.h + degrees + 360) % 360, s: hsl.s, l: hsl.l }\n}\n\nfunction formatColor(rgb: RGB): string {\n  const hex = rgbToHex(rgb)\n  const hsl = rgbToHsl(rgb)\n  return `${hex} / rgb(${rgb.r}, ${rgb.g}, ${rgb.b}) / hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`\n}\n\n/**\n * Compute the WCAG 2.1 contrast ratio between two colours.\n *\n * @remarks\n * Accepts hex (`#rgb`, `#rrggbb`), `rgb()`, `hsl()`, or one of the CSS / Material Design named\n * colours. Reports the ratio and pass/fail against WCAG AA and AAA at both normal and large text\n * sizes. If the foreground/background combination fails AA Normal (4.5:1), the tool suggests\n * lightened or darkened variants that would pass.\n */\nexport const colorContrastTool = new Tool({\n  name: 'color_contrast',\n  description:\n    'Check the contrast ratio between two colors for WCAG accessibility compliance. Reports the contrast ratio and pass/fail for WCAG AA and AAA levels.',\n  inputSchema: validator.object({\n    foreground: validator\n      .string()\n      .required()\n      .description('Foreground color (hex, rgb(), hsl(), or named color).'),\n    background: validator\n      .string()\n      .required()\n      .description('Background color (hex, rgb(), hsl(), or named color).'),\n  }),\n  handler: async (args) => {\n    const { foreground, background } = args as { foreground: string; background: string }\n    const fg = parseColor(foreground)\n    const bg = parseColor(background)\n\n    if (!fg) return `Error: could not parse foreground color \"${foreground}\".`\n    if (!bg) return `Error: could not parse background color \"${background}\".`\n\n    const ratio = contrastRatio(fg, bg)\n    const rounded = Math.round(ratio * 100) / 100\n\n    const aaLargeText = ratio >= 3\n    const aaNormalText = ratio >= 4.5\n    const aaaLargeText = ratio >= 4.5\n    const aaaNormalText = ratio >= 7\n\n    const lines = [\n      `Foreground: ${formatColor(fg)}`,\n      `Background: ${formatColor(bg)}`,\n      `Contrast ratio: ${rounded}:1`,\n      '',\n      'WCAG 2.1 compliance:',\n      `  AA  Normal text (4.5:1): ${aaNormalText ? 'PASS' : 'FAIL'}`,\n      `  AA  Large text  (3.0:1): ${aaLargeText ? 'PASS' : 'FAIL'}`,\n      `  AAA Normal text (7.0:1): ${aaaNormalText ? 'PASS' : 'FAIL'}`,\n      `  AAA Large text  (4.5:1): ${aaaLargeText ? 'PASS' : 'FAIL'}`,\n    ]\n\n    if (!aaNormalText) {\n      const fgHsl = rgbToHsl(fg)\n      const bgHsl = rgbToHsl(bg)\n      const fgLighter = fgHsl.l > bgHsl.l\n\n      const suggestions: string[] = []\n      if (fgLighter) {\n        const lighter = hslToRgb({ ...fgHsl, l: Math.min(100, fgHsl.l + 15) })\n        const darkerBg = hslToRgb({ ...bgHsl, l: Math.max(0, bgHsl.l - 15) })\n        if (contrastRatio(lighter, bg) >= 4.5) {\n          suggestions.push(\n            `  Lighten foreground to ${rgbToHex(lighter)} (ratio: ${Math.round(contrastRatio(lighter, bg) * 100) / 100}:1)`\n          )\n        }\n        if (contrastRatio(fg, darkerBg) >= 4.5) {\n          suggestions.push(\n            `  Darken background to ${rgbToHex(darkerBg)} (ratio: ${Math.round(contrastRatio(fg, darkerBg) * 100) / 100}:1)`\n          )\n        }\n      } else {\n        const darker = hslToRgb({ ...fgHsl, l: Math.max(0, fgHsl.l - 15) })\n        const lighterBg = hslToRgb({ ...bgHsl, l: Math.min(100, bgHsl.l + 15) })\n        if (contrastRatio(darker, bg) >= 4.5) {\n          suggestions.push(\n            `  Darken foreground to ${rgbToHex(darker)} (ratio: ${Math.round(contrastRatio(darker, bg) * 100) / 100}:1)`\n          )\n        }\n        if (contrastRatio(fg, lighterBg) >= 4.5) {\n          suggestions.push(\n            `  Lighten background to ${rgbToHex(lighterBg)} (ratio: ${Math.round(contrastRatio(fg, lighterBg) * 100) / 100}:1)`\n          )\n        }\n      }\n\n      if (suggestions.length > 0) {\n        lines.push('', 'Suggestions to reach AA Normal (4.5:1):')\n        lines.push(...suggestions)\n      }\n    }\n\n    return lines.join('\\n')\n  },\n})\n\n/**\n * Generate a colour palette from a base colour using a named harmony.\n *\n * @remarks\n * Supported schemes: `complementary`, `analogous`, `triadic`, `split-complementary`,\n * `monochromatic`. Each entry reports its hex, rgb, and hsl forms, plus the contrast ratio\n * relative to the base colour.\n */\nexport const colorSchemeTool = new Tool({\n  name: 'color_scheme',\n  description:\n    'Generate a color palette from a base color. Supports complementary, analogous, triadic, split-complementary, and monochromatic schemes.',\n  inputSchema: validator.object({\n    color: validator\n      .string()\n      .required()\n      .description('Base color (hex, rgb(), hsl(), or named color).'),\n    scheme: validator\n      .string()\n      .valid('complementary', 'analogous', 'triadic', 'split-complementary', 'monochromatic')\n      .required()\n      .description('Type of color scheme to generate.'),\n  }),\n  handler: async (args) => {\n    const { color, scheme } = args as {\n      color: string\n      scheme: 'complementary' | 'analogous' | 'triadic' | 'split-complementary' | 'monochromatic'\n    }\n    const rgb = parseColor(color)\n    if (!rgb) return `Error: could not parse color \"${color}\".`\n\n    const hsl = rgbToHsl(rgb)\n    const palette: { label: string; rgb: RGB }[] = [{ label: 'Base', rgb }]\n\n    switch (scheme) {\n      case 'complementary':\n        palette.push({ label: 'Complement', rgb: hslToRgb(rotateHue(hsl, 180)) })\n        break\n\n      case 'analogous':\n        palette.push({ label: 'Analogous -30', rgb: hslToRgb(rotateHue(hsl, -30)) })\n        palette.push({ label: 'Analogous +30', rgb: hslToRgb(rotateHue(hsl, 30)) })\n        break\n\n      case 'triadic':\n        palette.push({ label: 'Triadic +120', rgb: hslToRgb(rotateHue(hsl, 120)) })\n        palette.push({ label: 'Triadic +240', rgb: hslToRgb(rotateHue(hsl, 240)) })\n        break\n\n      case 'split-complementary':\n        palette.push({ label: 'Split +150', rgb: hslToRgb(rotateHue(hsl, 150)) })\n        palette.push({ label: 'Split +210', rgb: hslToRgb(rotateHue(hsl, 210)) })\n        break\n\n      case 'monochromatic':\n        palette.push({ label: 'Light', rgb: hslToRgb({ ...hsl, l: Math.min(100, hsl.l + 20) }) })\n        palette.push({ label: 'Lighter', rgb: hslToRgb({ ...hsl, l: Math.min(100, hsl.l + 35) }) })\n        palette.push({ label: 'Dark', rgb: hslToRgb({ ...hsl, l: Math.max(0, hsl.l - 20) }) })\n        palette.push({ label: 'Darker', rgb: hslToRgb({ ...hsl, l: Math.max(0, hsl.l - 35) }) })\n        break\n    }\n\n    const lines = [`Color scheme: ${scheme}`, '']\n    for (const entry of palette) {\n      lines.push(`${entry.label}: ${formatColor(entry.rgb)}`)\n    }\n\n    if (palette.length > 1) {\n      lines.push('', 'Contrast ratios with base:')\n      for (const entry of palette.slice(1)) {\n        const ratio = Math.round(contrastRatio(rgb, entry.rgb) * 100) / 100\n        lines.push(`  ${entry.label}: ${ratio}:1`)\n      }\n    }\n\n    return lines.join('\\n')\n  },\n})\n\n/**\n * Lighten or darken a colour by a percentage of HSL lightness.\n *\n * @remarks\n * `amount` is clamped to `[1, 100]`; `steps` is clamped to `[1, 10]`. With `steps > 1` the tool\n * emits a ramp of progressively-adjusted colours, useful for generating tint/shade scales.\n */\nexport const colorAdjustTool = new Tool({\n  name: 'color_adjust',\n  description:\n    'Lighten or darken a color by a specified amount. Returns the adjusted color in hex, rgb, and hsl formats. Can generate multiple steps for a tint/shade scale.',\n  inputSchema: validator.object({\n    color: validator\n      .string()\n      .required()\n      .description('Color to adjust (hex, rgb(), hsl(), or named color).'),\n    action: validator\n      .string()\n      .valid('lighten', 'darken')\n      .required()\n      .description('Whether to lighten or darken the color.'),\n    amount: validator\n      .number()\n      .default(15)\n      .description('Amount to adjust per step (1-100, percentage of lightness). Default: 15.'),\n    steps: validator\n      .number()\n      .default(1)\n      .description('Generate multiple steps of adjustment (1-10). Default: 1.'),\n  }),\n  handler: async (args) => {\n    const {\n      color,\n      action,\n      amount: rawAmount,\n      steps: rawSteps,\n    } = args as {\n      color: string\n      action: 'lighten' | 'darken'\n      amount: number\n      steps: number\n    }\n    const rgb = parseColor(color)\n    if (!rgb) return `Error: could not parse color \"${color}\".`\n\n    const amount = Math.max(1, Math.min(100, rawAmount))\n    const steps = Math.max(1, Math.min(10, rawSteps))\n    const hsl = rgbToHsl(rgb)\n\n    const lines = [`Original: ${formatColor(rgb)}`]\n\n    for (let i = 1; i <= steps; i++) {\n      const delta = amount * i\n      const newL = action === 'lighten' ? Math.min(100, hsl.l + delta) : Math.max(0, hsl.l - delta)\n      const adjusted = hslToRgb({ ...hsl, l: newL })\n      const label =\n        steps === 1\n          ? `${action === 'lighten' ? 'Lightened' : 'Darkened'} (${delta}%)`\n          : `Step ${i} (${action} ${delta}%)`\n      lines.push(`${label}: ${formatColor(adjusted)}`)\n    }\n\n    return lines.join('\\n')\n  },\n})\n"],"mappings":"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"}
+{"version":3,"file":"color.cjs","names":[],"sources":["../../../src/batteries/tools/color/index.ts"],"sourcesContent":["/**\n * Pre-constructed tools for color conversion and palette-oriented calculations.\n *\n * @module @nhtio/adk/batteries/tools/color\n *\n * @remarks\n * Pre-constructed bundled tools for the `color` category. Import individually, the whole\n * category, or import every tool via `@nhtio/adk/batteries`.\n */\n\nimport { Tool } from '@nhtio/adk/common'\nimport { validator } from '@nhtio/validation'\n\ntype RGB = { r: number; g: number; b: number }\ntype HSL = { h: number; s: number; l: number }\n\nfunction hexToRgb(hex: string): RGB | null {\n  const cleaned = hex.replace(/^#/, '')\n  // Reject any non-hex character up front. `Number.parseInt('1Z', 16)` silently drops the trailing\n  // 'Z' and returns 1 (passing the NaN check below), so '#1Z2Z3Z' would otherwise be accepted as a\n  // bogus colour rgb(1, 2, 3).\n  if (!/^[0-9a-fA-F]+$/.test(cleaned)) return null\n\n  let r: number\n  let g: number\n  let b: number\n\n  if (cleaned.length === 3) {\n    r = Number.parseInt(cleaned[0] + cleaned[0], 16)\n    g = Number.parseInt(cleaned[1] + cleaned[1], 16)\n    b = Number.parseInt(cleaned[2] + cleaned[2], 16)\n  } else if (cleaned.length === 6) {\n    r = Number.parseInt(cleaned.slice(0, 2), 16)\n    g = Number.parseInt(cleaned.slice(2, 4), 16)\n    b = Number.parseInt(cleaned.slice(4, 6), 16)\n  } else {\n    return null\n  }\n\n  if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) return null\n  return { r, g, b }\n}\n\nfunction parseRgbString(input: string): RGB | null {\n  const match = input.match(/^rgb\\(\\s*(\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)\\s*\\)$/i)\n  if (!match) return null\n  const r = Number.parseInt(match[1], 10)\n  const g = Number.parseInt(match[2], 10)\n  const b = Number.parseInt(match[3], 10)\n  if (r > 255 || g > 255 || b > 255) return null\n  return { r, g, b }\n}\n\nfunction parseHslString(input: string): HSL | null {\n  const match = input.match(/^hsl\\(\\s*(\\d+)\\s*,\\s*(\\d+)%?\\s*,\\s*(\\d+)%?\\s*\\)$/i)\n  if (!match) return null\n  return {\n    h: Number.parseInt(match[1], 10) % 360,\n    s: Math.min(100, Number.parseInt(match[2], 10)),\n    l: Math.min(100, Number.parseInt(match[3], 10)),\n  }\n}\n\nconst NAMED_COLORS: Record<string, string> = {\n  'black': '#000000',\n  'white': '#FFFFFF',\n  'transparent': '#FFFFFF',\n  'aqua': '#00FFFF',\n  'magenta': '#FF00FF',\n  'fuchsia': '#FF00FF',\n  'silver': '#C0C0C0',\n  'maroon': '#800000',\n  'olive': '#808000',\n  'navy': '#000080',\n  'coral': '#FF7F50',\n  'crimson': '#DC143C',\n  'gold': '#FFD700',\n  'ivory': '#FFFFF0',\n  'khaki': '#F0E68C',\n  'lavender': '#E6E6FA',\n  'plum': '#DDA0DD',\n  'salmon': '#FA8072',\n  'sienna': '#A0522D',\n  'tan': '#D2B48C',\n  'tomato': '#FF6347',\n  'turquoise': '#40E0D0',\n  'violet': '#EE82EE',\n  'wheat': '#F5DEB3',\n  'red': '#F44336',\n  'red-lighten-5': '#FFEBEE',\n  'red-lighten-4': '#FFCDD2',\n  'red-lighten-3': '#EF9A9A',\n  'red-lighten-2': '#E57373',\n  'red-lighten-1': '#EF5350',\n  'red-darken-1': '#E53935',\n  'red-darken-2': '#D32F2F',\n  'red-darken-3': '#C62828',\n  'red-darken-4': '#B71C1C',\n  'red-accent-1': '#FF8A80',\n  'red-accent-2': '#FF5252',\n  'red-accent-3': '#FF1744',\n  'red-accent-4': '#D50000',\n  'pink': '#E91E63',\n  'pink-lighten-5': '#FCE4EC',\n  'pink-lighten-4': '#F8BBD0',\n  'pink-lighten-3': '#F48FB1',\n  'pink-lighten-2': '#F06292',\n  'pink-lighten-1': '#EC407A',\n  'pink-darken-1': '#D81B60',\n  'pink-darken-2': '#C2185B',\n  'pink-darken-3': '#AD1457',\n  'pink-darken-4': '#880E4F',\n  'pink-accent-1': '#FF80AB',\n  'pink-accent-2': '#FF4081',\n  'pink-accent-3': '#F50057',\n  'pink-accent-4': '#C51162',\n  'purple': '#9C27B0',\n  'purple-lighten-5': '#F3E5F5',\n  'purple-lighten-4': '#E1BEE7',\n  'purple-lighten-3': '#CE93D8',\n  'purple-lighten-2': '#BA68C8',\n  'purple-lighten-1': '#AB47BC',\n  'purple-darken-1': '#8E24AA',\n  'purple-darken-2': '#7B1FA2',\n  'purple-darken-3': '#6A1B9A',\n  'purple-darken-4': '#4A148C',\n  'purple-accent-1': '#EA80FC',\n  'purple-accent-2': '#E040FB',\n  'purple-accent-3': '#D500F9',\n  'purple-accent-4': '#AA00FF',\n  'deep-purple': '#673AB7',\n  'deep-purple-lighten-5': '#EDE7F6',\n  'deep-purple-lighten-4': '#D1C4E9',\n  'deep-purple-lighten-3': '#B39DDB',\n  'deep-purple-lighten-2': '#9575CD',\n  'deep-purple-lighten-1': '#7E57C2',\n  'deep-purple-darken-1': '#5E35B1',\n  'deep-purple-darken-2': '#512DA8',\n  'deep-purple-darken-3': '#4527A0',\n  'deep-purple-darken-4': '#311B92',\n  'deep-purple-accent-1': '#B388FF',\n  'deep-purple-accent-2': '#7C4DFF',\n  'deep-purple-accent-3': '#651FFF',\n  'deep-purple-accent-4': '#6200EA',\n  'indigo': '#3F51B5',\n  'indigo-lighten-5': '#E8EAF6',\n  'indigo-lighten-4': '#C5CAE9',\n  'indigo-lighten-3': '#9FA8DA',\n  'indigo-lighten-2': '#7986CB',\n  'indigo-lighten-1': '#5C6BC0',\n  'indigo-darken-1': '#3949AB',\n  'indigo-darken-2': '#303F9F',\n  'indigo-darken-3': '#283593',\n  'indigo-darken-4': '#1A237E',\n  'indigo-accent-1': '#8C9EFF',\n  'indigo-accent-2': '#536DFE',\n  'indigo-accent-3': '#3D5AFE',\n  'indigo-accent-4': '#304FFE',\n  'blue': '#2196F3',\n  'blue-lighten-5': '#E3F2FD',\n  'blue-lighten-4': '#BBDEFB',\n  'blue-lighten-3': '#90CAF9',\n  'blue-lighten-2': '#64B5F6',\n  'blue-lighten-1': '#42A5F5',\n  'blue-darken-1': '#1E88E5',\n  'blue-darken-2': '#1976D2',\n  'blue-darken-3': '#1565C0',\n  'blue-darken-4': '#0D47A1',\n  'blue-accent-1': '#82B1FF',\n  'blue-accent-2': '#448AFF',\n  'blue-accent-3': '#2979FF',\n  'blue-accent-4': '#2962FF',\n  'light-blue': '#03A9F4',\n  'light-blue-lighten-5': '#E1F5FE',\n  'light-blue-lighten-4': '#B3E5FC',\n  'light-blue-lighten-3': '#81D4FA',\n  'light-blue-lighten-2': '#4FC3F7',\n  'light-blue-lighten-1': '#29B6F6',\n  'light-blue-darken-1': '#039BE5',\n  'light-blue-darken-2': '#0288D1',\n  'light-blue-darken-3': '#0277BD',\n  'light-blue-darken-4': '#01579B',\n  'light-blue-accent-1': '#80D8FF',\n  'light-blue-accent-2': '#40C4FF',\n  'light-blue-accent-3': '#00B0FF',\n  'light-blue-accent-4': '#0091EA',\n  'cyan': '#00BCD4',\n  'cyan-lighten-5': '#E0F7FA',\n  'cyan-lighten-4': '#B2EBF2',\n  'cyan-lighten-3': '#80DEEA',\n  'cyan-lighten-2': '#4DD0E1',\n  'cyan-lighten-1': '#26C6DA',\n  'cyan-darken-1': '#00ACC1',\n  'cyan-darken-2': '#0097A7',\n  'cyan-darken-3': '#00838F',\n  'cyan-darken-4': '#006064',\n  'cyan-accent-1': '#84FFFF',\n  'cyan-accent-2': '#18FFFF',\n  'cyan-accent-3': '#00E5FF',\n  'cyan-accent-4': '#00B8D4',\n  'teal': '#009688',\n  'teal-lighten-5': '#E0F2F1',\n  'teal-lighten-4': '#B2DFDB',\n  'teal-lighten-3': '#80CBC4',\n  'teal-lighten-2': '#4DB6AC',\n  'teal-lighten-1': '#26A69A',\n  'teal-darken-1': '#00897B',\n  'teal-darken-2': '#00796B',\n  'teal-darken-3': '#00695C',\n  'teal-darken-4': '#004D40',\n  'teal-accent-1': '#A7FFEB',\n  'teal-accent-2': '#64FFDA',\n  'teal-accent-3': '#1DE9B6',\n  'teal-accent-4': '#00BFA5',\n  'green': '#4CAF50',\n  'green-lighten-5': '#E8F5E9',\n  'green-lighten-4': '#C8E6C9',\n  'green-lighten-3': '#A5D6A7',\n  'green-lighten-2': '#81C784',\n  'green-lighten-1': '#66BB6A',\n  'green-darken-1': '#43A047',\n  'green-darken-2': '#388E3C',\n  'green-darken-3': '#2E7D32',\n  'green-darken-4': '#1B5E20',\n  'green-accent-1': '#B9F6CA',\n  'green-accent-2': '#69F0AE',\n  'green-accent-3': '#00E676',\n  'green-accent-4': '#00C853',\n  'light-green': '#8BC34A',\n  'light-green-lighten-5': '#F1F8E9',\n  'light-green-lighten-4': '#DCEDC8',\n  'light-green-lighten-3': '#C5E1A5',\n  'light-green-lighten-2': '#AED581',\n  'light-green-lighten-1': '#9CCC65',\n  'light-green-darken-1': '#7CB342',\n  'light-green-darken-2': '#689F38',\n  'light-green-darken-3': '#558B2F',\n  'light-green-darken-4': '#33691E',\n  'light-green-accent-1': '#CCFF90',\n  'light-green-accent-2': '#B2FF59',\n  'light-green-accent-3': '#76FF03',\n  'light-green-accent-4': '#64DD17',\n  'lime': '#CDDC39',\n  'lime-lighten-5': '#F9FBE7',\n  'lime-lighten-4': '#F0F4C3',\n  'lime-lighten-3': '#E6EE9C',\n  'lime-lighten-2': '#DCE775',\n  'lime-lighten-1': '#D4E157',\n  'lime-darken-1': '#C0CA33',\n  'lime-darken-2': '#AFB42B',\n  'lime-darken-3': '#9E9D24',\n  'lime-darken-4': '#827717',\n  'lime-accent-1': '#F4FF81',\n  'lime-accent-2': '#EEFF41',\n  'lime-accent-3': '#C6FF00',\n  'lime-accent-4': '#AEEA00',\n  'yellow': '#FFEB3B',\n  'yellow-lighten-5': '#FFFDE7',\n  'yellow-lighten-4': '#FFF9C4',\n  'yellow-lighten-3': '#FFF59D',\n  'yellow-lighten-2': '#FFF176',\n  'yellow-lighten-1': '#FFEE58',\n  'yellow-darken-1': '#FDD835',\n  'yellow-darken-2': '#FBC02D',\n  'yellow-darken-3': '#F9A825',\n  'yellow-darken-4': '#F57F17',\n  'yellow-accent-1': '#FFFF8D',\n  'yellow-accent-2': '#FFFF00',\n  'yellow-accent-3': '#FFEA00',\n  'yellow-accent-4': '#FFD600',\n  'amber': '#FFC107',\n  'amber-lighten-5': '#FFF8E1',\n  'amber-lighten-4': '#FFECB3',\n  'amber-lighten-3': '#FFE082',\n  'amber-lighten-2': '#FFD54F',\n  'amber-lighten-1': '#FFCA28',\n  'amber-darken-1': '#FFB300',\n  'amber-darken-2': '#FFA000',\n  'amber-darken-3': '#FF8F00',\n  'amber-darken-4': '#FF6F00',\n  'amber-accent-1': '#FFE57F',\n  'amber-accent-2': '#FFD740',\n  'amber-accent-3': '#FFC400',\n  'amber-accent-4': '#FFAB00',\n  'orange': '#FF9800',\n  'orange-lighten-5': '#FFF3E0',\n  'orange-lighten-4': '#FFE0B2',\n  'orange-lighten-3': '#FFCC80',\n  'orange-lighten-2': '#FFB74D',\n  'orange-lighten-1': '#FFA726',\n  'orange-darken-1': '#FB8C00',\n  'orange-darken-2': '#F57C00',\n  'orange-darken-3': '#EF6C00',\n  'orange-darken-4': '#E65100',\n  'orange-accent-1': '#FFD180',\n  'orange-accent-2': '#FFAB40',\n  'orange-accent-3': '#FF9100',\n  'orange-accent-4': '#FF6D00',\n  'deep-orange': '#FF5722',\n  'deep-orange-lighten-5': '#FBE9E7',\n  'deep-orange-lighten-4': '#FFCCBC',\n  'deep-orange-lighten-3': '#FFAB91',\n  'deep-orange-lighten-2': '#FF8A65',\n  'deep-orange-lighten-1': '#FF7043',\n  'deep-orange-darken-1': '#F4511E',\n  'deep-orange-darken-2': '#E64A19',\n  'deep-orange-darken-3': '#D84315',\n  'deep-orange-darken-4': '#BF360C',\n  'deep-orange-accent-1': '#FF9E80',\n  'deep-orange-accent-2': '#FF6E40',\n  'deep-orange-accent-3': '#FF3D00',\n  'deep-orange-accent-4': '#DD2C00',\n  'brown': '#795548',\n  'brown-lighten-5': '#EFEBE9',\n  'brown-lighten-4': '#D7CCC8',\n  'brown-lighten-3': '#BCAAA4',\n  'brown-lighten-2': '#A1887F',\n  'brown-lighten-1': '#8D6E63',\n  'brown-darken-1': '#6D4C41',\n  'brown-darken-2': '#5D4037',\n  'brown-darken-3': '#4E342E',\n  'brown-darken-4': '#3E2723',\n  'blue-grey': '#607D8B',\n  'blue-grey-lighten-5': '#ECEFF1',\n  'blue-grey-lighten-4': '#CFD8DC',\n  'blue-grey-lighten-3': '#B0BEC5',\n  'blue-grey-lighten-2': '#90A4AE',\n  'blue-grey-lighten-1': '#78909C',\n  'blue-grey-darken-1': '#546E7A',\n  'blue-grey-darken-2': '#455A64',\n  'blue-grey-darken-3': '#37474F',\n  'blue-grey-darken-4': '#263238',\n  'grey': '#9E9E9E',\n  'gray': '#9E9E9E',\n  'grey-lighten-5': '#FAFAFA',\n  'grey-lighten-4': '#F5F5F5',\n  'grey-lighten-3': '#EEEEEE',\n  'grey-lighten-2': '#E0E0E0',\n  'grey-lighten-1': '#BDBDBD',\n  'grey-darken-1': '#757575',\n  'grey-darken-2': '#616161',\n  'grey-darken-3': '#424242',\n  'grey-darken-4': '#212121',\n}\n\nfunction parseColor(input: string): RGB | null {\n  const trimmed = input.trim()\n  const lower = trimmed.toLowerCase()\n\n  if (NAMED_COLORS[lower]) {\n    return hexToRgb(NAMED_COLORS[lower])\n  }\n\n  if (trimmed.startsWith('#')) return hexToRgb(trimmed)\n  if (lower.startsWith('rgb(')) return parseRgbString(trimmed)\n  if (lower.startsWith('hsl(')) {\n    const hsl = parseHslString(trimmed)\n    return hsl ? hslToRgb(hsl) : null\n  }\n\n  return hexToRgb(trimmed)\n}\n\nfunction rgbToHex(rgb: RGB): string {\n  const toHex = (n: number) =>\n    Math.round(Math.max(0, Math.min(255, n)))\n      .toString(16)\n      .padStart(2, '0')\n  return `#${toHex(rgb.r)}${toHex(rgb.g)}${toHex(rgb.b)}`\n}\n\nfunction rgbToHsl(rgb: RGB): HSL {\n  const r = rgb.r / 255\n  const g = rgb.g / 255\n  const b = rgb.b / 255\n\n  const max = Math.max(r, g, b)\n  const min = Math.min(r, g, b)\n  const l = (max + min) / 2\n\n  if (max === min) return { h: 0, s: 0, l: Math.round(l * 100) }\n\n  const d = max - min\n  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)\n\n  let h = 0\n  if (max === r) h = ((g - b) / d + (g < b ? 6 : 0)) / 6\n  else if (max === g) h = ((b - r) / d + 2) / 6\n  else h = ((r - g) / d + 4) / 6\n\n  return {\n    h: Math.round(h * 360),\n    s: Math.round(s * 100),\n    l: Math.round(l * 100),\n  }\n}\n\nfunction hslToRgb(hsl: HSL): RGB {\n  const h = hsl.h / 360\n  const s = hsl.s / 100\n  const l = hsl.l / 100\n\n  if (s === 0) {\n    const v = Math.round(l * 255)\n    return { r: v, g: v, b: v }\n  }\n\n  const hue2rgb = (p: number, q: number, t: number) => {\n    if (t < 0) t += 1\n    if (t > 1) t -= 1\n    if (t < 1 / 6) return p + (q - p) * 6 * t\n    if (t < 1 / 2) return q\n    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6\n    return p\n  }\n\n  const q = l < 0.5 ? l * (1 + s) : l + s - l * s\n  const p = 2 * l - q\n\n  return {\n    r: Math.round(hue2rgb(p, q, h + 1 / 3) * 255),\n    g: Math.round(hue2rgb(p, q, h) * 255),\n    b: Math.round(hue2rgb(p, q, h - 1 / 3) * 255),\n  }\n}\n\nfunction relativeLuminance(rgb: RGB): number {\n  const srgb = [rgb.r, rgb.g, rgb.b].map((c) => {\n    const s = c / 255\n    return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)\n  })\n  return 0.2126 * srgb[0] + 0.7152 * srgb[1] + 0.0722 * srgb[2]\n}\n\nfunction contrastRatio(c1: RGB, c2: RGB): number {\n  const l1 = relativeLuminance(c1)\n  const l2 = relativeLuminance(c2)\n  const lighter = Math.max(l1, l2)\n  const darker = Math.min(l1, l2)\n  return (lighter + 0.05) / (darker + 0.05)\n}\n\nfunction rotateHue(hsl: HSL, degrees: number): HSL {\n  return { h: (hsl.h + degrees + 360) % 360, s: hsl.s, l: hsl.l }\n}\n\nfunction formatColor(rgb: RGB): string {\n  const hex = rgbToHex(rgb)\n  const hsl = rgbToHsl(rgb)\n  return `${hex} / rgb(${rgb.r}, ${rgb.g}, ${rgb.b}) / hsl(${hsl.h}, ${hsl.s}%, ${hsl.l}%)`\n}\n\n/**\n * Compute the WCAG 2.1 contrast ratio between two colours.\n *\n * @remarks\n * Accepts hex (`#rgb`, `#rrggbb`), `rgb()`, `hsl()`, or one of the CSS / Material Design named\n * colours. Reports the ratio and pass/fail against WCAG AA and AAA at both normal and large text\n * sizes. If the foreground/background combination fails AA Normal (4.5:1), the tool suggests\n * lightened or darkened variants that would pass.\n */\nexport const colorContrastTool = new Tool({\n  name: 'color_contrast',\n  description:\n    'Check the contrast ratio between two colors for WCAG accessibility compliance. Reports the contrast ratio and pass/fail for WCAG AA and AAA levels.',\n  inputSchema: validator.object({\n    foreground: validator\n      .string()\n      .required()\n      .description('Foreground color (hex, rgb(), hsl(), or named color).'),\n    background: validator\n      .string()\n      .required()\n      .description('Background color (hex, rgb(), hsl(), or named color).'),\n  }),\n  handler: async (args) => {\n    const { foreground, background } = args as { foreground: string; background: string }\n    const fg = parseColor(foreground)\n    const bg = parseColor(background)\n\n    if (!fg) return `Error: could not parse foreground color \"${foreground}\".`\n    if (!bg) return `Error: could not parse background color \"${background}\".`\n\n    const ratio = contrastRatio(fg, bg)\n    const rounded = Math.round(ratio * 100) / 100\n\n    const aaLargeText = ratio >= 3\n    const aaNormalText = ratio >= 4.5\n    const aaaLargeText = ratio >= 4.5\n    const aaaNormalText = ratio >= 7\n\n    const lines = [\n      `Foreground: ${formatColor(fg)}`,\n      `Background: ${formatColor(bg)}`,\n      `Contrast ratio: ${rounded}:1`,\n      '',\n      'WCAG 2.1 compliance:',\n      `  AA  Normal text (4.5:1): ${aaNormalText ? 'PASS' : 'FAIL'}`,\n      `  AA  Large text  (3.0:1): ${aaLargeText ? 'PASS' : 'FAIL'}`,\n      `  AAA Normal text (7.0:1): ${aaaNormalText ? 'PASS' : 'FAIL'}`,\n      `  AAA Large text  (4.5:1): ${aaaLargeText ? 'PASS' : 'FAIL'}`,\n    ]\n\n    if (!aaNormalText) {\n      const fgHsl = rgbToHsl(fg)\n      const bgHsl = rgbToHsl(bg)\n      const fgLighter = fgHsl.l > bgHsl.l\n\n      const suggestions: string[] = []\n      if (fgLighter) {\n        const lighter = hslToRgb({ ...fgHsl, l: Math.min(100, fgHsl.l + 15) })\n        const darkerBg = hslToRgb({ ...bgHsl, l: Math.max(0, bgHsl.l - 15) })\n        if (contrastRatio(lighter, bg) >= 4.5) {\n          suggestions.push(\n            `  Lighten foreground to ${rgbToHex(lighter)} (ratio: ${Math.round(contrastRatio(lighter, bg) * 100) / 100}:1)`\n          )\n        }\n        if (contrastRatio(fg, darkerBg) >= 4.5) {\n          suggestions.push(\n            `  Darken background to ${rgbToHex(darkerBg)} (ratio: ${Math.round(contrastRatio(fg, darkerBg) * 100) / 100}:1)`\n          )\n        }\n      } else {\n        const darker = hslToRgb({ ...fgHsl, l: Math.max(0, fgHsl.l - 15) })\n        const lighterBg = hslToRgb({ ...bgHsl, l: Math.min(100, bgHsl.l + 15) })\n        if (contrastRatio(darker, bg) >= 4.5) {\n          suggestions.push(\n            `  Darken foreground to ${rgbToHex(darker)} (ratio: ${Math.round(contrastRatio(darker, bg) * 100) / 100}:1)`\n          )\n        }\n        if (contrastRatio(fg, lighterBg) >= 4.5) {\n          suggestions.push(\n            `  Lighten background to ${rgbToHex(lighterBg)} (ratio: ${Math.round(contrastRatio(fg, lighterBg) * 100) / 100}:1)`\n          )\n        }\n      }\n\n      if (suggestions.length > 0) {\n        lines.push('', 'Suggestions to reach AA Normal (4.5:1):')\n        lines.push(...suggestions)\n      }\n    }\n\n    return lines.join('\\n')\n  },\n})\n\n/**\n * Generate a colour palette from a base colour using a named harmony.\n *\n * @remarks\n * Supported schemes: `complementary`, `analogous`, `triadic`, `split-complementary`,\n * `monochromatic`. Each entry reports its hex, rgb, and hsl forms, plus the contrast ratio\n * relative to the base colour.\n */\nexport const colorSchemeTool = new Tool({\n  name: 'color_scheme',\n  description:\n    'Generate a color palette from a base color. Supports complementary, analogous, triadic, split-complementary, and monochromatic schemes.',\n  inputSchema: validator.object({\n    color: validator\n      .string()\n      .required()\n      .description('Base color (hex, rgb(), hsl(), or named color).'),\n    scheme: validator\n      .string()\n      .valid('complementary', 'analogous', 'triadic', 'split-complementary', 'monochromatic')\n      .required()\n      .description('Type of color scheme to generate.'),\n  }),\n  handler: async (args) => {\n    const { color, scheme } = args as {\n      color: string\n      scheme: 'complementary' | 'analogous' | 'triadic' | 'split-complementary' | 'monochromatic'\n    }\n    const rgb = parseColor(color)\n    if (!rgb) return `Error: could not parse color \"${color}\".`\n\n    const hsl = rgbToHsl(rgb)\n    const palette: { label: string; rgb: RGB }[] = [{ label: 'Base', rgb }]\n\n    switch (scheme) {\n      case 'complementary':\n        palette.push({ label: 'Complement', rgb: hslToRgb(rotateHue(hsl, 180)) })\n        break\n\n      case 'analogous':\n        palette.push({ label: 'Analogous -30', rgb: hslToRgb(rotateHue(hsl, -30)) })\n        palette.push({ label: 'Analogous +30', rgb: hslToRgb(rotateHue(hsl, 30)) })\n        break\n\n      case 'triadic':\n        palette.push({ label: 'Triadic +120', rgb: hslToRgb(rotateHue(hsl, 120)) })\n        palette.push({ label: 'Triadic +240', rgb: hslToRgb(rotateHue(hsl, 240)) })\n        break\n\n      case 'split-complementary':\n        palette.push({ label: 'Split +150', rgb: hslToRgb(rotateHue(hsl, 150)) })\n        palette.push({ label: 'Split +210', rgb: hslToRgb(rotateHue(hsl, 210)) })\n        break\n\n      case 'monochromatic':\n        palette.push({ label: 'Light', rgb: hslToRgb({ ...hsl, l: Math.min(100, hsl.l + 20) }) })\n        palette.push({ label: 'Lighter', rgb: hslToRgb({ ...hsl, l: Math.min(100, hsl.l + 35) }) })\n        palette.push({ label: 'Dark', rgb: hslToRgb({ ...hsl, l: Math.max(0, hsl.l - 20) }) })\n        palette.push({ label: 'Darker', rgb: hslToRgb({ ...hsl, l: Math.max(0, hsl.l - 35) }) })\n        break\n    }\n\n    const lines = [`Color scheme: ${scheme}`, '']\n    for (const entry of palette) {\n      lines.push(`${entry.label}: ${formatColor(entry.rgb)}`)\n    }\n\n    if (palette.length > 1) {\n      lines.push('', 'Contrast ratios with base:')\n      for (const entry of palette.slice(1)) {\n        const ratio = Math.round(contrastRatio(rgb, entry.rgb) * 100) / 100\n        lines.push(`  ${entry.label}: ${ratio}:1`)\n      }\n    }\n\n    return lines.join('\\n')\n  },\n})\n\n/**\n * Lighten or darken a colour by a percentage of HSL lightness.\n *\n * @remarks\n * `amount` is clamped to `[1, 100]`; `steps` is clamped to `[1, 10]`. With `steps > 1` the tool\n * emits a ramp of progressively-adjusted colours, useful for generating tint/shade scales.\n */\nexport const colorAdjustTool = new Tool({\n  name: 'color_adjust',\n  description:\n    'Lighten or darken a color by a specified amount. Returns the adjusted color in hex, rgb, and hsl formats. Can generate multiple steps for a tint/shade scale.',\n  inputSchema: validator.object({\n    color: validator\n      .string()\n      .required()\n      .description('Color to adjust (hex, rgb(), hsl(), or named color).'),\n    action: validator\n      .string()\n      .valid('lighten', 'darken')\n      .required()\n      .description('Whether to lighten or darken the color.'),\n    amount: validator\n      .number()\n      .default(15)\n      .description('Amount to adjust per step (1-100, percentage of lightness). Default: 15.'),\n    steps: validator\n      .number()\n      .default(1)\n      .description('Generate multiple steps of adjustment (1-10). Default: 1.'),\n  }),\n  handler: async (args) => {\n    const {\n      color,\n      action,\n      amount: rawAmount,\n      steps: rawSteps,\n    } = args as {\n      color: string\n      action: 'lighten' | 'darken'\n      amount: number\n      steps: number\n    }\n    const rgb = parseColor(color)\n    if (!rgb) return `Error: could not parse color \"${color}\".`\n\n    const amount = Math.max(1, Math.min(100, rawAmount))\n    const steps = Math.max(1, Math.min(10, rawSteps))\n    const hsl = rgbToHsl(rgb)\n\n    const lines = [`Original: ${formatColor(rgb)}`]\n\n    for (let i = 1; i <= steps; i++) {\n      const delta = amount * i\n      const newL = action === 'lighten' ? Math.min(100, hsl.l + delta) : Math.max(0, hsl.l - delta)\n      const adjusted = hslToRgb({ ...hsl, l: newL })\n      const label =\n        steps === 1\n          ? `${action === 'lighten' ? 'Lightened' : 'Darkened'} (${delta}%)`\n          : `Step ${i} (${action} ${delta}%)`\n      lines.push(`${label}: ${formatColor(adjusted)}`)\n    }\n\n    return lines.join('\\n')\n  },\n})\n"],"mappings":"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"}

package/batteries/tools/color.mjs

@@ -1,5 +1,5 @@
-import { t as Tool } from "../../tool-CMhaDRNd.mjs";
-import "../../common-BT0nfCi9.mjs";
+import { t as Tool } from "../../tool-wMYMVl60.mjs";
+import "../../common-DYDUi99O.mjs";
 import { validator } from "@nhtio/validation";
 //#region src/batteries/tools/color/index.ts
 /**
@@ -13,6 +13,7 @@ import { validator } from "@nhtio/validation";
 */
 function hexToRgb(hex) {
 	const cleaned = hex.replace(/^#/, "");
+	if (!/^[0-9a-fA-F]+$/.test(cleaned)) return null;
 	let r;
 	let g;
 	let b;