@wow-two-beta/ui-vue 0.0.4 → 0.0.6

package/dist/foundation/workers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/foundation/workers/WorkerSupport.ts","../../../src/foundation/workers/WorkerProtocol.ts","../../../src/foundation/workers/WorkerClient.ts","../../../src/foundation/workers/WorkerHost.ts","../../../src/foundation/workers/UseWorker.ts","../../../src/foundation/workers/RunInWorker.ts"],"sourcesContent":["// The capability probe for this slice, isolated in its own module so the client, the host, the hook, and\n// `runInWorker` all share ONE definition of \"can this runtime spawn a worker\".\n//\n// It exists because this package ships into SSR frameworks. `Worker` is a browser global with no Node\n// counterpart under that name (Node's lives behind `node:worker_threads`), so a module-level\n// `new Worker(...)` anywhere in this slice would be a hard crash the moment a server renders a page that\n// imports it. The rule this module enforces: NOTHING here touches `Worker` outside a function body, and\n// every entry point probes first and answers `unsupported` rather than throwing.\n//\n// `typeof Worker` rather than `'Worker' in globalThis`: `typeof` on an undeclared identifier is the one\n// read that cannot raise a `ReferenceError`, which matters for bundles evaluated before a DOM shim is\n// installed. The `globalThis` form would also work today, but the `typeof` form is the one that stays\n// correct if this ever runs as a classic script.\n\n/**\n * Reports whether the current runtime can construct a `Worker`.\n *\n * `false` under SSR and in Node's test environment. Call it before anything that would construct one —\n * every entry point in this slice already does, so this is for a consumer branching its own UI.\n */\nexport function isWorkerSupported(): boolean {\n  return typeof Worker === 'function';\n}\n\n/**\n * Reports whether the runtime can build a worker from a `Blob` URL — the strictly stronger requirement\n * behind {@link runInWorker}, which needs `Blob` and `URL.createObjectURL` on top of `Worker`.\n *\n * Separate from {@link isWorkerSupported} because the two can genuinely diverge: a locked-down CSP with\n * no `worker-src blob:` leaves `Worker` fully functional while making the blob route unusable.\n */\nexport function isBlobWorkerSupported(): boolean {\n  return (\n    isWorkerSupported() &&\n    typeof Blob === 'function' &&\n    typeof URL !== 'undefined' &&\n    typeof URL.createObjectURL === 'function' &&\n    typeof URL.revokeObjectURL === 'function'\n  );\n}\n","// The wire format both halves of the RPC agree on, kept in one dependency-free module so the client and\n// the host can never drift apart, and so the parts worth testing without a browser (id allocation, the\n// shape guards) are testable in the node project.\n//\n// TWO DECISIONS HERE ARE NOT OBVIOUS.\n//\n// 1. EVERY MESSAGE CARRIES A CHANNEL TAG. A `Worker` is a single shared `postMessage` pipe, not a private\n//    one: the same worker may also carry a consumer's own hand-written traffic, a bundler's HMR ping, or\n//    another library's protocol. Without a tag, a guard keyed only on `typeof id === 'number'` would\n//    happily adopt a foreign message and resolve — or worse, reject — an unrelated call. So both guards\n//    demand the tag first, and anything unrecognized is IGNORED rather than treated as an error: a message\n//    that isn't ours is not a protocol violation, it is someone else's message.\n//\n// 2. SUCCESS AND FAILURE ARE SPLIT BY AN EXPLICIT `ok` FLAG, not by probing for an `error` key. `undefined`\n//    is a legitimate result — a handler returning nothing must still resolve, not be misread as a failure\n//    because its `result` member is absent after a structured-clone round trip. The boolean makes the\n//    union genuinely discriminated and keeps `void` methods working.\n//\n// The error side of the wire is a `SerializedError` from `foundation/errors`, not an `Error`: structured\n// clone drops `stack` and the subclass, so an `Error` posted directly arrives as a bare object with only\n// `message` intact. `serializeError` flattens it to plain JSON-safe members (including the `cause` chain)\n// and the client feeds that back through `toError` on the far side.\n\nimport type { SerializedError } from '../errors';\n\n/**\n * Tags every message belonging to this protocol. A namespaced literal rather than a `Symbol`, because a\n * `Symbol` does not survive structured clone and would arrive as `undefined` on the far thread.\n */\nexport const WorkerMessageChannel = '@wow-two-beta/worker-rpc';\n\n/** Names the channel tag's type — used to type the envelopes without restating the literal. */\nexport type WorkerMessageChannel = typeof WorkerMessageChannel;\n\n/** Describes a call travelling from the client to the worker. */\nexport interface WorkerRequestMessage {\n  /** The protocol tag — always {@link WorkerMessageChannel}. */\n  readonly channel: WorkerMessageChannel;\n\n  /** The envelope discriminant, distinguishing a request from a reply on the same pipe. */\n  readonly kind: 'request';\n\n  /** The correlation id the reply must echo back. Unique per client, monotonic. */\n  readonly id: number;\n\n  /** The handler name to dispatch to on the worker side. */\n  readonly method: string;\n\n  /** The positional arguments, structured-cloned (or transferred) to the worker. */\n  readonly args: readonly unknown[];\n}\n\n/** Describes a reply carrying a handler's resolved value. */\nexport interface WorkerSuccessMessage {\n  /** The protocol tag — always {@link WorkerMessageChannel}. */\n  readonly channel: WorkerMessageChannel;\n\n  /** The envelope discriminant. */\n  readonly kind: 'response';\n\n  /** The correlation id echoed from the request this answers. */\n  readonly id: number;\n\n  /** The success discriminant. */\n  readonly ok: true;\n\n  /** The handler's resolved value. Legitimately `undefined` for a `void` method. */\n  readonly result: unknown;\n}\n\n/** Describes a reply carrying a handler's failure. */\nexport interface WorkerFailureMessage {\n  /** The protocol tag — always {@link WorkerMessageChannel}. */\n  readonly channel: WorkerMessageChannel;\n\n  /** The envelope discriminant. */\n  readonly kind: 'response';\n\n  /** The correlation id echoed from the request this answers. */\n  readonly id: number;\n\n  /** The failure discriminant. */\n  readonly ok: false;\n\n  /** The JSON-safe projection of the thrown value, rehydrated by `toError` on the client. */\n  readonly error: SerializedError;\n}\n\n/** Describes either half of a reply — the union the client switches on. */\nexport type WorkerResponseMessage = WorkerSuccessMessage | WorkerFailureMessage;\n\n/** Narrows an `unknown` to a non-null object so members can be read without a `TypeError`. */\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n\n/**\n * Recognizes a request envelope arriving on the worker side.\n *\n * Deliberately total and silent: a message failing this check is ignored by the host, because the pipe is\n * shared and a foreign message must not be answered with a protocol error addressed to nobody.\n */\nexport function isWorkerRequestMessage(value: unknown): value is WorkerRequestMessage {\n  if (!isRecord(value)) return false;\n  return (\n    value['channel'] === WorkerMessageChannel &&\n    value['kind'] === 'request' &&\n    typeof value['id'] === 'number' &&\n    typeof value['method'] === 'string' &&\n    Array.isArray(value['args'])\n  );\n}\n\n/**\n * Recognizes a reply envelope arriving on the client side.\n *\n * Note it does NOT require a `result` member on the success branch — absent and `undefined` are the same\n * thing after a clone, and a `void` handler must still resolve its call.\n */\nexport function isWorkerResponseMessage(value: unknown): value is WorkerResponseMessage {\n  if (!isRecord(value)) return false;\n  if (value['channel'] !== WorkerMessageChannel || value['kind'] !== 'response') return false;\n  if (typeof value['id'] !== 'number') return false;\n\n  const ok = value['ok'];\n  if (ok === true) return true;\n  return ok === false && isRecord(value['error']);\n}\n\n/** Builds a request envelope. */\nexport function createRequestMessage(id: number, method: string, args: readonly unknown[]): WorkerRequestMessage {\n  return { channel: WorkerMessageChannel, kind: 'request', id, method, args };\n}\n\n/** Builds a success reply. */\nexport function createSuccessMessage(id: number, result: unknown): WorkerSuccessMessage {\n  return { channel: WorkerMessageChannel, kind: 'response', id, ok: true, result };\n}\n\n/** Builds a failure reply. */\nexport function createFailureMessage(id: number, error: SerializedError): WorkerFailureMessage {\n  return { channel: WorkerMessageChannel, kind: 'response', id, ok: false, error };\n}\n\n/**\n * Creates a per-client monotonic id source, starting at `1` so a falsy `0` never identifies a real call.\n *\n * Per-client rather than module-global on purpose: two clients over two workers each keep their own\n * sequence, so ids stay small and readable in a log, and one client's traffic can never be confused with\n * another's. No wrap handling — exhausting `Number.MAX_SAFE_INTEGER` at a million calls a second would\n * take roughly 285 years, so a counter reset is dead code that could only ever hide a bug.\n */\nexport function createRequestIdAllocator(): () => number {\n  let previous = 0;\n  return () => {\n    previous += 1;\n    return previous;\n  };\n}\n","// The main-thread half of the RPC: turns a `Worker`'s fire-and-forget `postMessage` pipe into typed,\n// awaitable method calls.\n//\n// THE CENTRAL DESIGN CONSTRAINT — WHY THERE IS A MAP INSTEAD OF A LISTENER PER CALL.\n// The tempting implementation is: post the request, attach a one-shot `message` listener, resolve from it,\n// remove it. That reads cleanly and is WRONG, because `postMessage` gives no ordering guarantee between a\n// request and its reply. A worker whose handlers are async — a `fetch`, an IndexedDB read, anything\n// awaited — finishes them in completion order, not arrival order. So issue `slow()` then `fast()` and the\n// replies come back `fast`, `slow`. A one-shot listener resolves the FIRST reply it sees, so `slow()`\n// receives `fast()`'s value with the right type and a plausible-looking value, and `fast()` receives\n// `slow()`'s. Nothing throws. There is no stack trace. The two results are simply swapped, and the bug\n// only appears once two calls overlap — which in development, with one call at a time, they never do.\n//\n// The fix is the only fix: correlate explicitly. Every request carries a monotonic id, ONE permanent\n// listener owns the pipe, and it routes each reply to the pending entry that id names. The out-of-order\n// case is covered by a test that makes the worker answer the second request first.\n//\n// LEAK DISCIPLINE. The pending map is the one place this class can leak, since an entry holds a promise's\n// resolve/reject closures alive forever. Every exit path removes its entry through the same `settle` call:\n// a reply, a timeout, a worker-level error, and `terminate`. A late reply arriving after its entry is gone\n// is dropped silently — it is the expected consequence of a timeout, not an error to report.\n//\n// TIMEOUTS ARE NOT DRIVEN FROM `foundation/resilience`, and that is deliberate rather than an oversight:\n// that slice models RETRIES over HTTP statuses (`computeRetryDelay`, `shouldRetry(policy, count, status)`)\n// and has no timeout primitive to reuse. A per-call deadline over a stateful pipe is a different shape —\n// there is no status to classify and a retry would re-run a handler that may not be idempotent. Retrying a\n// worker call is the consumer's decision, and a consumer that wants one can wrap `call` with that slice's\n// helpers.\n//\n// ERROR ATTRIBUTION SPLITS IN TWO, because the two failures carry different amounts of information:\n//  - a handler that throws is caught INSIDE the worker and replied to with its own id, so exactly one call\n//    rejects and its siblings are untouched;\n//  - an `ErrorEvent` on the worker itself (a script that failed to parse, a top-level throw) carries NO\n//    id — nothing identifies which call, if any, provoked it, and the worker is generally unusable\n//    afterwards. Rejecting only a guess would strand the rest, so every in-flight call rejects.\n// An `ErrorEvent` is also not an `Error` — it is an event with `message` / `filename` / `lineno` and an\n// `error` member that is `null` for a cross-origin script. That is precisely what `toError` is for.\n\nimport { toError } from '../errors';\n\nimport {\n  createRequestIdAllocator,\n  createRequestMessage,\n  isWorkerResponseMessage,\n  type WorkerResponseMessage,\n} from './WorkerProtocol';\n\n/**\n * Constrains an RPC contract to methods only — used as `TApi extends WorkerApiOf<TApi>`.\n *\n * The self-reference is not decoration, it is the only form a plain `interface` satisfies. The obvious\n * spelling, `TApi extends Record<string, Fn>`, silently rejects every `interface`: TypeScript grants an\n * implicit index signature to type ALIASES and inferred object literals but never to an interface, so\n * `interface MathApi { add(a: number, b: number): number }` — the shape this slice's own documentation\n * recommends, and the one a consumer sharing a contract between two files will reach for — fails the\n * constraint with a message about a missing index signature that says nothing about what to do. Mapping\n * over `keyof TApi` asks the same question (is every member callable?) without ever requiring one.\n *\n * `never[]` in the parameter position is the standard \"any function is assignable here\" trick: parameters\n * are contravariant, so it accepts every signature while `Parameters<TApi[TMethod]>` still reads a\n * concrete contract's own argument types exactly.\n */\nexport type WorkerApiOf<TApi> = { [TMethod in keyof TApi]: (...args: never[]) => unknown };\n\n/** Tunes a single call. */\nexport interface WorkerCallOptions {\n  /**\n   * The deadline in milliseconds. Rejects with an `Error` named `TimeoutError` — the same name\n   * `AbortSignal.timeout()` uses, so `isTimeoutError` from `foundation/errors` recognizes it. Overrides\n   * the client-level default; omit (or pass a non-positive value) for no deadline.\n   */\n  readonly timeoutMs?: number;\n\n  /**\n   * The objects to transfer rather than clone — an `ArrayBuffer`, `MessagePort`, `ImageBitmap`, or\n   * `OffscreenCanvas` reachable from `args`.\n   *\n   * A transferred object is NEUTERED in the sender: after the call, the caller's own `ArrayBuffer` has\n   * `byteLength === 0` and reading it throws. This is the single most surprising thing about the API and\n   * is the price of the move — see the `withTransfer` docs for the full note.\n   */\n  readonly transfer?: readonly Transferable[];\n}\n\n/** Tunes a client. */\nexport interface WorkerClientOptions {\n  /** The default deadline in milliseconds applied to every call that does not set its own. Omit for none. */\n  readonly timeoutMs?: number;\n\n  /**\n   * Called with the normalized error when the WORKER ITSELF fails — an `ErrorEvent` or a `messageerror`,\n   * neither of which names a call. The seam for logging a broken worker; a per-call failure never reaches\n   * it, since that rejects the call instead. A throw from this callback is swallowed.\n   */\n  readonly onError?: (error: Error) => void;\n}\n\n/** The typed handle over one worker. */\nexport interface WorkerClient<TApi extends WorkerApiOf<TApi>> {\n  /**\n   * Calls `method` on the worker and resolves with its reply. Rejects if the handler throws, the deadline\n   * elapses, the worker dies, or {@link WorkerClient.terminate} is called while this is in flight.\n   */\n  call<TMethod extends keyof TApi & string>(\n    method: TMethod,\n    ...args: Parameters<TApi[TMethod]>\n  ): Promise<Awaited<ReturnType<TApi[TMethod]>>>;\n\n  /** Calls `method` with per-call options — a deadline, a transfer list, or both. Otherwise identical to {@link WorkerClient.call}. */\n  callWith<TMethod extends keyof TApi & string>(\n    options: WorkerCallOptions,\n    method: TMethod,\n    ...args: Parameters<TApi[TMethod]>\n  ): Promise<Awaited<ReturnType<TApi[TMethod]>>>;\n\n  /** The number of calls awaiting a reply — the observable that proves an exit path cleaned up after itself. */\n  readonly pendingCount: number;\n\n  /** Whether {@link WorkerClient.terminate} has run. A terminated client rejects every further call rather than hanging. */\n  readonly terminated: boolean;\n\n  /**\n   * Kills the worker and rejects every in-flight call. Idempotent.\n   *\n   * The rejection is the point: a terminated worker will never reply, so leaving those promises pending\n   * would hang each awaiting caller forever with no error to catch.\n   */\n  terminate(): void;\n}\n\n/** Holds the two closures and the timer belonging to one awaited call. */\ninterface PendingCall {\n  /** The method name — carried only so a timeout / termination message can name what was lost. */\n  readonly method: string;\n\n  /** Settles the caller's promise with the worker's reply. */\n  readonly resolve: (value: unknown) => void;\n\n  /** Fails the caller's promise. */\n  readonly reject: (error: Error) => void;\n\n  /** The deadline timer, cleared on every exit path so a settled call cannot fire one later. */\n  timer?: ReturnType<typeof setTimeout>;\n}\n\n/** Builds the `TimeoutError`-named error a lapsed deadline rejects with, so `isTimeoutError` recognizes it. */\nfunction createTimeoutError(method: string, timeoutMs: number): Error {\n  const error = new Error(`Worker call \\`${method}\\` timed out after ${timeoutMs}ms`);\n  error.name = 'TimeoutError';\n  return error;\n}\n\n/**\n * Wraps a `Worker` in a typed request/response client.\n *\n * The worker must run {@link exposeWorkerApi} (or speak the same envelope). `TApi` is the shared contract:\n * declare it once, use it here and to type the handler map on the worker side.\n *\n * ```ts\n * interface MathApi { add(a: number, b: number): number }\n * const client = createWorkerClient<MathApi>(new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' }));\n * await client.call('add', 2, 3); // 5\n * ```\n *\n * Takes an already-constructed `Worker` rather than a factory so it stays usable with any worker the\n * consumer's bundler produced, and so nothing in this module ever touches the `Worker` constructor — which\n * is what keeps it importable under SSR.\n */\nexport function createWorkerClient<TApi extends WorkerApiOf<TApi>>(\n  worker: Worker,\n  options?: WorkerClientOptions,\n): WorkerClient<TApi> {\n  const pendingCalls = new Map<number, PendingCall>();\n  const nextRequestId = createRequestIdAllocator();\n  let terminated = false;\n\n  /** Removes a pending entry and cancels its timer — the single exit path every settle route goes through. */\n  function settle(id: number): PendingCall | undefined {\n    const pending = pendingCalls.get(id);\n    if (pending === undefined) return undefined;\n    if (pending.timer !== undefined) clearTimeout(pending.timer);\n    pendingCalls.delete(id);\n    return pending;\n  }\n\n  /** Fails every in-flight call — used where the failure names no single call (worker death, termination). */\n  function rejectAll(toFailure: (pending: PendingCall) => Error): void {\n    for (const id of [...pendingCalls.keys()]) {\n      const pending = settle(id);\n      if (pending !== undefined) pending.reject(toFailure(pending));\n    }\n  }\n\n  /** Hands the consumer a worker-level failure without letting their reporter's own throw escape. */\n  function report(error: Error): void {\n    if (options?.onError === undefined) return;\n    try {\n      options.onError(error);\n    } catch {\n      // The consumer's reporter failed. The calls have already been rejected, which is the guarantee that\n      // matters; a second failure here would replace a real error with an unrelated one.\n    }\n  }\n\n  /** Routes one reply to the call its id names. */\n  function handleMessage(event: MessageEvent<unknown>): void {\n    const message: unknown = event.data;\n    // Not our envelope — the pipe is shared, so someone else's message is not an error.\n    if (!isWorkerResponseMessage(message)) return;\n\n    const pending = settle(message.id);\n    // Already settled by a timeout or a `terminate`. A late reply is the expected tail of those paths.\n    if (pending === undefined) return;\n\n    const reply: WorkerResponseMessage = message;\n    if (reply.ok) pending.resolve(reply.result);\n    else pending.reject(toError(reply.error));\n  }\n\n  /** Fails everything in flight when the worker itself dies, since no id attributes the failure. */\n  function handleError(event: ErrorEvent): void {\n    // `event.error` is `null` for a cross-origin script, leaving `message` as the only signal — an\n    // `ErrorEvent` is not an `Error`, which is exactly why this goes through `toError`.\n    const failure = toError(event.error ?? event.message ?? 'Worker error');\n    rejectAll(() => failure);\n    report(failure);\n  }\n\n  /** Fails everything in flight when a reply could not be deserialized — the payload, and its id, are lost. */\n  function handleMessageError(): void {\n    const failure = new Error('Worker sent a message that could not be deserialized');\n    rejectAll(() => failure);\n    report(failure);\n  }\n\n  worker.addEventListener('message', handleMessage);\n  worker.addEventListener('error', handleError);\n  worker.addEventListener('messageerror', handleMessageError);\n\n  /** Posts one request and returns the promise its reply will settle. Untyped at this level — the wire has no types. */\n  function invoke(callOptions: WorkerCallOptions, method: string, args: readonly unknown[]): Promise<unknown> {\n    if (terminated) {\n      return Promise.reject(new Error(`Worker call \\`${method}\\` rejected: the client is terminated`));\n    }\n\n    const id = nextRequestId();\n\n    return new Promise<unknown>((resolve, reject) => {\n      const pending: PendingCall = { method, resolve, reject };\n      pendingCalls.set(id, pending);\n\n      const timeoutMs = callOptions.timeoutMs ?? options?.timeoutMs;\n      if (timeoutMs !== undefined && timeoutMs > 0 && Number.isFinite(timeoutMs)) {\n        pending.timer = setTimeout(() => {\n          // `settle` first: the entry must be gone before the caller is rejected, or a timeout would leave\n          // the map holding a settled promise's closures for as long as the client lives.\n          if (settle(id) !== undefined) reject(createTimeoutError(method, timeoutMs));\n        }, timeoutMs);\n      }\n\n      try {\n        const request = createRequestMessage(id, method, args);\n        const transfer = callOptions.transfer;\n        if (transfer !== undefined && transfer.length > 0) worker.postMessage(request, [...transfer]);\n        else worker.postMessage(request);\n      } catch (error) {\n        // `postMessage` throws synchronously on a non-cloneable argument (a function, a DOM node, a class\n        // instance with methods) and on an already-detached buffer. Rejecting the call keeps every failure\n        // on the promise, so a caller never has to both `await` and wrap the call in a `try`.\n        if (settle(id) !== undefined) reject(toError(error));\n      }\n    });\n  }\n\n  function terminate(): void {\n    if (terminated) return;\n    terminated = true;\n\n    rejectAll((pending) => new Error(`Worker call \\`${pending.method}\\` rejected: the worker was terminated`));\n\n    worker.removeEventListener('message', handleMessage);\n    worker.removeEventListener('error', handleError);\n    worker.removeEventListener('messageerror', handleMessageError);\n    worker.terminate();\n  }\n\n  return {\n    call<TMethod extends keyof TApi & string>(method: TMethod, ...args: Parameters<TApi[TMethod]>) {\n      // The one cast in this module, and an unavoidable one: a structured-clone pipe carries no type\n      // information, so the contract `TApi` asserts is checked at the call site and trusted here.\n      return invoke({}, method, args as readonly unknown[]) as Promise<Awaited<ReturnType<TApi[TMethod]>>>;\n    },\n    callWith<TMethod extends keyof TApi & string>(\n      callOptions: WorkerCallOptions,\n      method: TMethod,\n      ...args: Parameters<TApi[TMethod]>\n    ) {\n      return invoke(callOptions, method, args as readonly unknown[]) as Promise<\n        Awaited<ReturnType<TApi[TMethod]>>\n      >;\n    },\n    get pendingCount() {\n      return pendingCalls.size;\n    },\n    get terminated() {\n      return terminated;\n    },\n    terminate,\n  };\n}\n","// The worker-thread half of the RPC. Goal: a worker entry file is three lines.\n//\n//   import { exposeWorkerApi } from '@wow-two-beta/ui/foundation/workers';\n//   const handlers = { add: (a: number, b: number) => a + b };\n//   exposeWorkerApi(handlers);\n//\n// THE SCOPE IS STRUCTURALLY TYPED, NOT `DedicatedWorkerGlobalScope`. That type ships in TypeScript's\n// `webworker` lib, and this package compiles under `[\"ES2022\", \"DOM\", \"DOM.Iterable\"]` — pulling in\n// `webworker` alongside `DOM` is not an option, since the two declare conflicting globals (`self`,\n// `postMessage`, `location`) and the merge fails outright. A minimal structural `WorkerScope` describes\n// exactly the three members used and typechecks under either lib. It also makes the host injectable, which\n// is what lets a test drive both halves without a real worker.\n//\n// THE DEFAULT SCOPE IS RESOLVED, NOT ASSUMED. `globalThis` in a window is a `Window`, whose `postMessage`\n// has a different signature (`targetOrigin`) — so the default is probed for the two members it needs and\n// yields `null` when absent. Calling this on the main thread or under SSR therefore registers nothing and\n// returns a no-op disposer instead of throwing. Importing a worker module from the main thread is a\n// routine accident (a barrel re-export, a bundler pulling it into the wrong chunk); it should be inert,\n// not fatal.\n//\n// EVERY FAILURE PATH MUST STILL POST A REPLY. A handler that throws, a method that does not exist, a\n// rejected promise, and even a RESULT THAT WILL NOT CLONE all have to produce a `{ id, error }` message,\n// because the client's pending entry is keyed on that id and only a reply (or its deadline) releases it.\n// The non-cloneable result is the subtle one: posting the success throws inside the host, and without the\n// second try/catch around it the call would hang until its timeout — or forever, if it has none.\n\nimport { serializeError } from '../errors';\n\nimport type { WorkerApiOf } from './WorkerClient';\nimport { createFailureMessage, createSuccessMessage, isWorkerRequestMessage } from './WorkerProtocol';\n\n/**\n * Describes the parts of a worker's global scope this module uses. Structural so it typechecks without the\n * `webworker` lib, and so a test can pass a stand-in.\n */\nexport interface WorkerScope {\n  /** Subscribes to inbound messages. */\n  addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;\n\n  /** Unsubscribes a previously registered listener. */\n  removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;\n\n  /** Posts a reply back to the main thread, optionally transferring ownership of objects reachable from it. */\n  postMessage(message: unknown, transfer?: Transferable[]): void;\n}\n\n/** Constrains a handler map: method name → implementation, sync or async. */\nexport type WorkerHandlerMap = Record<string, (...args: never[]) => unknown>;\n\n/**\n * Projects a client-side contract into the handler map that satisfies it — the optional annotation for a\n * consumer who wants the compiler to hold both halves of the RPC to one interface.\n *\n * ```ts\n * const handlers: WorkerHandlersOf<MathApi> = { add: (a, b) => a + b };\n * exposeWorkerApi(handlers);\n * ```\n *\n * Each handler may return the value, a promise of it, or that value wrapped by {@link withTransfer} — all\n * three arrive at the client as the plain value.\n */\nexport type WorkerHandlersOf<TApi extends WorkerApiOf<TApi>> = {\n  readonly [TMethod in keyof TApi]: (\n    ...args: Parameters<TApi[TMethod]>\n  ) =>\n    | Awaited<ReturnType<TApi[TMethod]>>\n    | Promise<Awaited<ReturnType<TApi[TMethod]>>>\n    | WorkerTransfer<Awaited<ReturnType<TApi[TMethod]>>>\n    | Promise<WorkerTransfer<Awaited<ReturnType<TApi[TMethod]>>>>;\n};\n\n/**\n * Brands a {@link WorkerTransfer} wrapper. Exported only because the declaration emit needs the symbol to\n * be nameable; it is an implementation detail, not something to reference. The wrapper is unwrapped before\n * the reply is posted, so this symbol never crosses a thread boundary.\n */\nexport const WorkerTransferMarker = Symbol('@wow-two-beta/worker-transfer');\n\n/** Wraps a handler's return value together with the objects to move rather than copy. Built by {@link withTransfer}. */\nexport interface WorkerTransfer<TValue> {\n  /** The brand. */\n  readonly [WorkerTransferMarker]: true;\n\n  /** The value the client will receive — the wrapper itself is stripped before posting. */\n  readonly value: TValue;\n\n  /** The objects whose ownership moves to the main thread. */\n  readonly transfer: readonly Transferable[];\n}\n\n/**\n * Marks a handler's result for transfer instead of a structured-clone copy — the return-path counterpart\n * of `WorkerCallOptions.transfer`.\n *\n * ```ts\n * const handlers = {\n *   render: (size: number) => {\n *     const pixels = new ArrayBuffer(size);\n *     return withTransfer(pixels, [pixels]); // moved, not copied\n *   },\n * };\n * ```\n *\n * THE TRANSFERRED OBJECT IS NEUTERED IN THE SENDER. This is the single most surprising thing about the\n * whole API and it is not a bug: transfer is a MOVE. Once posted, the worker's own `pixels` has\n * `byteLength === 0` and any read of it throws — the memory now belongs to the receiving thread. So\n * transfer only a buffer you are done with, and never one you also returned a view over or kept in a\n * cache. The payoff is that a 100 MB buffer costs a pointer hand-off instead of a 100 MB copy, which for\n * a large payload is the difference between a frame and a stall.\n *\n * The same neutering hits the CALLER when transferring into the worker via `callWith({ transfer })`: after\n * that call the caller's `ArrayBuffer` is the empty one.\n */\nexport function withTransfer<TValue>(value: TValue, transfer: readonly Transferable[]): WorkerTransfer<TValue> {\n  return { [WorkerTransferMarker]: true, value, transfer };\n}\n\n/** Recognizes the wrapper so the host can strip it before replying. */\nfunction isWorkerTransfer(value: unknown): value is WorkerTransfer<unknown> {\n  if (typeof value !== 'object' || value === null) return false;\n  return (value as Partial<WorkerTransfer<unknown>>)[WorkerTransferMarker] === true;\n}\n\n/** Probes `globalThis` for a usable worker scope, yielding `null` on the main thread and under SSR. */\nfunction resolveDefaultScope(): WorkerScope | null {\n  const candidate = globalThis as unknown as Partial<WorkerScope>;\n  return typeof candidate.addEventListener === 'function' &&\n    typeof candidate.removeEventListener === 'function' &&\n    typeof candidate.postMessage === 'function'\n    ? (candidate as WorkerScope)\n    : null;\n}\n\n/**\n * Registers `handlers` as the worker's RPC surface and returns a disposer that unregisters them.\n *\n * Dispatch is by method name; an unknown method rejects that one call rather than killing the worker. A\n * handler may be sync or async — the result is awaited either way — and may wrap its return value in\n * {@link withTransfer} to move a large buffer instead of copying it.\n *\n * Never throws, including when there is no worker scope (main thread, SSR), where it registers nothing and\n * the returned disposer is a no-op.\n */\nexport function exposeWorkerApi<THandlers extends WorkerHandlerMap>(\n  handlers: THandlers,\n  scope: WorkerScope | null = resolveDefaultScope(),\n): () => void {\n  if (scope === null) return () => undefined;\n  const target = scope;\n\n  /** Runs one request to completion and posts exactly one reply. */\n  async function dispatch(event: MessageEvent): Promise<void> {\n    const request: unknown = event.data;\n    // Not our envelope — the pipe is shared, so stay silent rather than answering a message we do not own.\n    if (!isWorkerRequestMessage(request)) return;\n\n    try {\n      // OWN properties only. A bare `handlers[method]` walks the prototype chain, so a request for\n      // `toString` / `valueOf` / `constructor` finds a real function and would be dispatched — answering\n      // `'[object Object]'` to a method the worker never exposed, or invoking `Object`. The method name\n      // arrives from another thread and is untrusted input; the surface is exactly what the map declares.\n      const handler = Object.prototype.hasOwnProperty.call(handlers, request.method)\n        ? handlers[request.method]\n        : undefined;\n      if (typeof handler !== 'function') throw new Error(`Unknown worker method \\`${request.method}\\``);\n\n      // The handler map's `never[]` parameters make it unassignable at a call site by construction — the\n      // wire is untyped, so the arguments are trusted here and checked by `TApi` on the client.\n      const invoke = handler as (...args: readonly unknown[]) => unknown;\n      const outcome: unknown = await invoke(...request.args);\n\n      const value = isWorkerTransfer(outcome) ? outcome.value : outcome;\n      const transfer = isWorkerTransfer(outcome) ? [...outcome.transfer] : undefined;\n\n      // This `postMessage` is inside the try on purpose. It throws when the result will not structured-clone\n      // (a function, a DOM node, a class instance carrying methods) or when a transferred object is already\n      // detached — and the caller's pending entry outlives that throw, so the failure below is what releases\n      // it. Without this, such a call hangs until its deadline, or forever when it has none.\n      target.postMessage(createSuccessMessage(request.id, value), transfer);\n    } catch (error) {\n      target.postMessage(createFailureMessage(request.id, serializeError(error)));\n    }\n  }\n\n  /** Bridges the sync listener signature to the async dispatcher; `dispatch` never rejects, so nothing escapes. */\n  function listener(event: MessageEvent): void {\n    void dispatch(event);\n  }\n\n  target.addEventListener('message', listener);\n  return () => {\n    target.removeEventListener('message', listener);\n  };\n}\n","// The Vue binding: ties one worker's lifetime to one scope's, so a mounted component owns a worker and a\n// disposed one does not.\n//\n// TERMINATION ON TEARDOWN IS THE WHOLE POINT. A `Worker` is an OS thread with its own JS heap; it is not\n// garbage-collected when the last reference to it drops, because the thread itself is a root. A component\n// that creates one and navigates away leaks a live thread for the rest of the session, and a list that\n// mounts one per row leaks one per row. So `onScopeDispose` calls `client.terminate()` — which also rejects\n// every in-flight call, releasing any `await` still parked on the torn-down component.\n//\n// THE FACTORY IS CALLED ONCE, IN `onMounted`. A component's `setup` runs once, so the original's\n// factory-in-a-ref indirection has nothing to protect against here — the factory a consumer passes is the\n// one and only. The natural call site is still an inline arrow:\n//\n//   const { client } = useWorker(() => new Worker(url, { type: 'module' }));\n//\n// and the worker is created exactly once per mount. The cost is unchanged: changing what the factory would\n// return later does NOT swap the worker. Remount to swap — a `key` on the component, which is the honest\n// idiom for \"this is a different resource now\".\n//\n// SSR: the worker is created in `onMounted`, which does not run on the server, so nothing here can touch the\n// `Worker` constructor during a server render. `client` is therefore `null` on the server and until mount,\n// non-null from the first mount onward. `supported` is likewise set in `onMounted` rather than read at setup\n// — reading a browser capability at setup time is exactly what produces a hydration mismatch, where the\n// server's `false` and the client's `true` disagree on the first pass.\n\nimport { onMounted, onScopeDispose, shallowRef, type ShallowRef } from 'vue';\n\nimport { createWorkerClient, type WorkerApiOf, type WorkerClient, type WorkerClientOptions } from './WorkerClient';\nimport { isWorkerSupported } from './WorkerSupport';\n\n/** What {@link useWorker} returns. */\nexport interface UseWorkerResult<TApi extends WorkerApiOf<TApi>> {\n  /**\n   * The typed client, or `null` before mount and in any runtime without `Worker`.\n   *\n   * Guard on it (`client.value?.call(...)`) rather than asserting: the `null` window is real until mount, so\n   * an effect or event handler firing before the worker exists must have a defined answer.\n   */\n  readonly client: Readonly<ShallowRef<WorkerClient<TApi> | null>>;\n\n  /**\n   * Whether this runtime can spawn a worker, as determined after mount. `false` during SSR and until mount —\n   * before then it is not yet knowable, and claiming otherwise at setup time would desync hydration.\n   */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n}\n\n/**\n * Owns a worker for the lifetime of the calling scope: created on mount, terminated on disposal.\n *\n * ```ts\n * const { client } = useWorker<MathApi>(() => new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' }));\n * const sum = await client.value?.call('add', 2, 3);\n * ```\n *\n * The factory is invoked once per mount, so an inline arrow is the expected call shape.\n */\nexport function useWorker<TApi extends WorkerApiOf<TApi>>(\n  factory: () => Worker,\n  options?: WorkerClientOptions,\n): UseWorkerResult<TApi> {\n  const client = shallowRef<WorkerClient<TApi> | null>(null);\n  const supported = shallowRef(false);\n\n  onMounted(() => {\n    if (!isWorkerSupported()) {\n      client.value = null;\n      supported.value = false;\n      return;\n    }\n\n    client.value = createWorkerClient<TApi>(factory(), options);\n    supported.value = true;\n  });\n\n  onScopeDispose(() => {\n    // Rejects everything in flight as well as killing the thread — an `await` left over from the torn-down\n    // component gets an error instead of hanging forever.\n    client.value?.terminate();\n    client.value = null;\n    supported.value = false;\n  });\n\n  return { client, supported };\n}\n","// One-shot offloading: run a self-contained function on another thread without authoring a worker file,\n// wiring it into the bundler, or keeping a thread alive afterwards. For the one expensive pure computation\n// that would otherwise block a frame — a hash over a large buffer, a sort of a hundred thousand rows,\n// parsing a big CSV.\n//\n// THE FUNCTION IS STRINGIFIED, SO IT CANNOT CLOSE OVER ANYTHING. This is the constraint that makes or\n// breaks every use of this helper, and it fails at RUNTIME, inside the other thread, with a bare\n// `ReferenceError` naming a variable that is plainly in scope at the call site:\n//\n//   const factor = 2;\n//   await runInWorker((n: number) => n * factor, [21]);   // ✗ ReferenceError: factor is not defined\n//   await runInWorker((n: number, f: number) => n * f, [21, 2]); // ✓ everything arrives through args\n//\n// `Function.prototype.toString` returns source text, not a closure. The text is embedded in a `Blob` and\n// evaluated in a scope that shares nothing with the module it was written in — no captured variables, no\n// imports, no `document`, no Vue. Everything the function needs must arrive through `args`, and `args`\n// must survive structured clone. The same rule voids TypeScript's help here: the compiler happily\n// typechecks the captured variable it is about to strip.\n//\n// The mirror-image trap is the METHOD SHORTHAND. `({ work(n) { ... } }).work.toString()` yields\n// `work(n) { ... }`, which is not a valid expression even wrapped in parentheses, and the worker dies on a\n// syntax error. Pass a function expression or an arrow.\n//\n// THE BLOB URL IS REVOKED IN A `finally`. Each `createObjectURL` pins its blob in memory until revoked,\n// and a revoke skipped on the failure path is a leak that only shows up in the runs that already went\n// wrong. The worker is terminated there too, on every path.\n//\n// The result is a discriminated union rather than a throw, matching `foundation/share`'s idiom: an\n// unsupported runtime (SSR, or a CSP without `worker-src blob:`) is a fact to branch on, not an exception,\n// and it must be distinguishable from the function itself failing.\n\nimport { toError } from '../errors';\n\nimport { isBlobWorkerSupported } from './WorkerSupport';\n\n/** The outcome of a {@link runInWorker} attempt. */\nexport type RunInWorkerResult<TValue> =\n  | {\n      /** The function ran on the worker thread and returned. */\n      readonly status: 'ok';\n      /** The value it returned, structured-cloned back. */\n      readonly value: TValue;\n    }\n  | {\n      /** No `Worker`, `Blob`, or `URL.createObjectURL` here — SSR, or a CSP blocking `blob:` workers. Nothing ran. */\n      readonly status: 'unsupported';\n    }\n  | {\n      /** The function threw, the worker failed to start, or the deadline elapsed. */\n      readonly status: 'failed';\n      /** The normalized failure — the worker's own error where one crossed the boundary. */\n      readonly error: Error;\n    };\n\n/** Tunes a {@link runInWorker} call. */\nexport interface RunInWorkerOptions {\n  /** The deadline in milliseconds. On lapse the worker is terminated and the result is `failed` with a `TimeoutError`. Omit for none. */\n  readonly timeoutMs?: number;\n\n  /**\n   * The objects to transfer into the worker instead of cloning. Each is NEUTERED in the caller: an\n   * `ArrayBuffer` passed here has `byteLength === 0` once the call returns.\n   */\n  readonly transfer?: readonly Transferable[];\n}\n\n/**\n * Builds the worker source. Bespoke rather than reusing `exposeWorkerApi`, and necessarily so: a `Blob`\n * worker has no module resolution, so it cannot import this package — the protocol has to be inlined, and\n * a one-shot call needs no id correlation because exactly one request is ever in flight.\n *\n * Written in plain ES5-ish JS with no optional chaining, since the text is evaluated verbatim by whatever\n * engine the browser gives the worker rather than passing through this package's build.\n */\nfunction buildWorkerSource(functionSource: string): string {\n  return `self.onmessage = function (event) {\n  Promise.resolve()\n    .then(function () {\n      var fn = (${functionSource});\n      return fn.apply(null, event.data);\n    })\n    .then(function (value) {\n      self.postMessage({ ok: true, value: value });\n    })\n    .catch(function (error) {\n      var shape = { name: 'Error', message: 'Worker function failed' };\n      if (error && typeof error === 'object') {\n        if (typeof error.name === 'string') shape.name = error.name;\n        if (typeof error.message === 'string') shape.message = error.message;\n        if (typeof error.stack === 'string') shape.stack = error.stack;\n      } else if (typeof error === 'string') {\n        shape.message = error;\n      }\n      self.postMessage({ ok: false, error: shape });\n    });\n};`;\n}\n\n/** Narrows an inbound reply from the one-shot worker. */\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n\n/**\n * Runs `fn` on a throwaway worker thread and resolves with its result.\n *\n * ```ts\n * const result = await runInWorker((rows: number[]) => rows.reduce((a, b) => a + b, 0), [bigArray]);\n * if (result.status === 'ok') console.log(result.value);\n * ```\n *\n * `fn` MUST be self-contained — it is stringified, so it captures nothing from the scope it was written\n * in, and it may not be a method shorthand. Every input arrives through `args`, and both `args` and the\n * return value must survive structured clone. See the module header for the full rationale.\n *\n * Never throws: an unsupported runtime, a failed start, a thrown function, and a lapsed deadline all\n * resolve to a {@link RunInWorkerResult}. The worker is terminated and the blob URL revoked on every path.\n */\nexport async function runInWorker<TArgs extends readonly unknown[], TValue>(\n  fn: (...args: TArgs) => TValue | Promise<TValue>,\n  args: TArgs,\n  options?: RunInWorkerOptions,\n): Promise<RunInWorkerResult<TValue>> {\n  if (!isBlobWorkerSupported()) return { status: 'unsupported' };\n\n  let url: string | undefined;\n  let worker: Worker | undefined;\n\n  try {\n    url = URL.createObjectURL(new Blob([buildWorkerSource(fn.toString())], { type: 'text/javascript' }));\n    const instance = new Worker(url);\n    worker = instance;\n\n    const value = await new Promise<TValue>((resolve, reject) => {\n      let timer: ReturnType<typeof setTimeout> | undefined;\n\n      /** Cancels the deadline so a settled run cannot be failed by its own timer afterwards. */\n      const done = (): void => {\n        if (timer !== undefined) clearTimeout(timer);\n      };\n\n      const { timeoutMs } = options ?? {};\n      if (timeoutMs !== undefined && timeoutMs > 0 && Number.isFinite(timeoutMs)) {\n        timer = setTimeout(() => {\n          const error = new Error(`Worker function timed out after ${timeoutMs}ms`);\n          // Named for `isTimeoutError` in `foundation/errors`, matching `AbortSignal.timeout()`.\n          error.name = 'TimeoutError';\n          reject(error);\n        }, timeoutMs);\n      }\n\n      instance.addEventListener('message', (event: MessageEvent<unknown>) => {\n        done();\n        const reply: unknown = event.data;\n        if (!isRecord(reply)) {\n          reject(new Error('Worker sent an unrecognized reply'));\n          return;\n        }\n        if (reply['ok'] === true) {\n          resolve(reply['value'] as TValue);\n          return;\n        }\n        reject(toError(reply['error']));\n      });\n\n      // A worker that fails to start (a syntax error from a method shorthand, a CSP refusal) reports here\n      // as an `ErrorEvent`, which is not an `Error` — hence `toError` over the `message` fallback.\n      instance.addEventListener('error', (event: ErrorEvent) => {\n        done();\n        reject(toError(event.error ?? event.message ?? 'Worker failed to start'));\n      });\n\n      const transfer = options?.transfer;\n      if (transfer !== undefined && transfer.length > 0) instance.postMessage(args, [...transfer]);\n      else instance.postMessage(args);\n    });\n\n    return { status: 'ok', value };\n  } catch (error) {\n    return { status: 'failed', error: toError(error) };\n  } finally {\n    worker?.terminate();\n    // Revoked on every path, including the ones that already failed — an un-revoked URL pins its blob for\n    // the life of the document.\n    if (url !== undefined) URL.revokeObjectURL(url);\n  }\n}\n"],"names":["isRecord"],"mappings":";;;AAoBO,SAAS,oBAA6B;AAC3C,SAAO,OAAO,WAAW;AAC3B;AASO,SAAS,wBAAiC;AAC/C,SACE,kBAAA,KACA,OAAO,SAAS,cAChB,OAAO,QAAQ,eACf,OAAO,IAAI,oBAAoB,cAC/B,OAAO,IAAI,oBAAoB;AAEnC;ACVO,MAAM,uBAAuB;AA+DpC,SAASA,WAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU;AAChD;AAQO,SAAS,uBAAuB,OAA+C;AACpF,MAAI,CAACA,WAAS,KAAK,EAAG,QAAO;AAC7B,SACE,MAAM,SAAS,MAAM,wBACrB,MAAM,MAAM,MAAM,aAClB,OAAO,MAAM,IAAI,MAAM,YACvB,OAAO,MAAM,QAAQ,MAAM,YAC3B,MAAM,QAAQ,MAAM,MAAM,CAAC;AAE/B;AAQO,SAAS,wBAAwB,OAAgD;AACtF,MAAI,CAACA,WAAS,KAAK,EAAG,QAAO;AAC7B,MAAI,MAAM,SAAS,MAAM,wBAAwB,MAAM,MAAM,MAAM,WAAY,QAAO;AACtF,MAAI,OAAO,MAAM,IAAI,MAAM,SAAU,QAAO;AAE5C,QAAM,KAAK,MAAM,IAAI;AACrB,MAAI,OAAO,KAAM,QAAO;AACxB,SAAO,OAAO,SAASA,WAAS,MAAM,OAAO,CAAC;AAChD;AAGO,SAAS,qBAAqB,IAAY,QAAgB,MAAgD;AAC/G,SAAO,EAAE,SAAS,sBAAsB,MAAM,WAAW,IAAI,QAAQ,KAAA;AACvE;AAGO,SAAS,qBAAqB,IAAY,QAAuC;AACtF,SAAO,EAAE,SAAS,sBAAsB,MAAM,YAAY,IAAI,IAAI,MAAM,OAAA;AAC1E;AAGO,SAAS,qBAAqB,IAAY,OAA8C;AAC7F,SAAO,EAAE,SAAS,sBAAsB,MAAM,YAAY,IAAI,IAAI,OAAO,MAAA;AAC3E;AAUO,SAAS,2BAAyC;AACvD,MAAI,WAAW;AACf,SAAO,MAAM;AACX,gBAAY;AACZ,WAAO;AAAA,EACT;AACF;ACZA,SAAS,mBAAmB,QAAgB,WAA0B;AACpE,QAAM,QAAQ,IAAI,MAAM,iBAAiB,MAAM,sBAAsB,SAAS,IAAI;AAClF,QAAM,OAAO;AACb,SAAO;AACT;AAkBO,SAAS,mBACd,QACA,SACoB;AACpB,QAAM,mCAAmB,IAAA;AACzB,QAAM,gBAAgB,yBAAA;AACtB,MAAI,aAAa;AAGjB,WAAS,OAAO,IAAqC;AACnD,UAAM,UAAU,aAAa,IAAI,EAAE;AACnC,QAAI,YAAY,OAAW,QAAO;AAClC,QAAI,QAAQ,UAAU,OAAW,cAAa,QAAQ,KAAK;AAC3D,iBAAa,OAAO,EAAE;AACtB,WAAO;AAAA,EACT;AAGA,WAAS,UAAU,WAAkD;AACnE,eAAW,MAAM,CAAC,GAAG,aAAa,KAAA,CAAM,GAAG;AACzC,YAAM,UAAU,OAAO,EAAE;AACzB,UAAI,YAAY,OAAW,SAAQ,OAAO,UAAU,OAAO,CAAC;AAAA,IAC9D;AAAA,EACF;AAGA,WAAS,OAAO,OAAoB;AAClC,QAAI,SAAS,YAAY,OAAW;AACpC,QAAI;AACF,cAAQ,QAAQ,KAAK;AAAA,IACvB,QAAQ;AAAA,IAGR;AAAA,EACF;AAGA,WAAS,cAAc,OAAoC;AACzD,UAAM,UAAmB,MAAM;AAE/B,QAAI,CAAC,wBAAwB,OAAO,EAAG;AAEvC,UAAM,UAAU,OAAO,QAAQ,EAAE;AAEjC,QAAI,YAAY,OAAW;AAE3B,UAAM,QAA+B;AACrC,QAAI,MAAM,GAAI,SAAQ,QAAQ,MAAM,MAAM;AAAA,QACrC,SAAQ,OAAO,QAAQ,MAAM,KAAK,CAAC;AAAA,EAC1C;AAGA,WAAS,YAAY,OAAyB;AAG5C,UAAM,UAAU,QAAQ,MAAM,SAAS,MAAM,WAAW,cAAc;AACtE,cAAU,MAAM,OAAO;AACvB,WAAO,OAAO;AAAA,EAChB;AAGA,WAAS,qBAA2B;AAClC,UAAM,UAAU,IAAI,MAAM,sDAAsD;AAChF,cAAU,MAAM,OAAO;AACvB,WAAO,OAAO;AAAA,EAChB;AAEA,SAAO,iBAAiB,WAAW,aAAa;AAChD,SAAO,iBAAiB,SAAS,WAAW;AAC5C,SAAO,iBAAiB,gBAAgB,kBAAkB;AAG1D,WAAS,OAAO,aAAgC,QAAgB,MAA4C;AAC1G,QAAI,YAAY;AACd,aAAO,QAAQ,OAAO,IAAI,MAAM,iBAAiB,MAAM,uCAAuC,CAAC;AAAA,IACjG;AAEA,UAAM,KAAK,cAAA;AAEX,WAAO,IAAI,QAAiB,CAAC,SAAS,WAAW;AAC/C,YAAM,UAAuB,EAAE,QAAQ,SAAS,OAAA;AAChD,mBAAa,IAAI,IAAI,OAAO;AAE5B,YAAM,YAAY,YAAY,aAAa,SAAS;AACpD,UAAI,cAAc,UAAa,YAAY,KAAK,OAAO,SAAS,SAAS,GAAG;AAC1E,gBAAQ,QAAQ,WAAW,MAAM;AAG/B,cAAI,OAAO,EAAE,MAAM,eAAkB,mBAAmB,QAAQ,SAAS,CAAC;AAAA,QAC5E,GAAG,SAAS;AAAA,MACd;AAEA,UAAI;AACF,cAAM,UAAU,qBAAqB,IAAI,QAAQ,IAAI;AACrD,cAAM,WAAW,YAAY;AAC7B,YAAI,aAAa,UAAa,SAAS,SAAS,EAAG,QAAO,YAAY,SAAS,CAAC,GAAG,QAAQ,CAAC;AAAA,YACvF,QAAO,YAAY,OAAO;AAAA,MACjC,SAAS,OAAO;AAId,YAAI,OAAO,EAAE,MAAM,OAAW,QAAO,QAAQ,KAAK,CAAC;AAAA,MACrD;AAAA,IACF,CAAC;AAAA,EACH;AAEA,WAAS,YAAkB;AACzB,QAAI,WAAY;AAChB,iBAAa;AAEb,cAAU,CAAC,YAAY,IAAI,MAAM,iBAAiB,QAAQ,MAAM,wCAAwC,CAAC;AAEzG,WAAO,oBAAoB,WAAW,aAAa;AACnD,WAAO,oBAAoB,SAAS,WAAW;AAC/C,WAAO,oBAAoB,gBAAgB,kBAAkB;AAC7D,WAAO,UAAA;AAAA,EACT;AAEA,SAAO;AAAA,IACL,KAA0C,WAAoB,MAAiC;AAG7F,aAAO,OAAO,CAAA,GAAI,QAAQ,IAA0B;AAAA,IACtD;AAAA,IACA,SACE,aACA,WACG,MACH;AACA,aAAO,OAAO,aAAa,QAAQ,IAA0B;AAAA,IAG/D;AAAA,IACA,IAAI,eAAe;AACjB,aAAO,aAAa;AAAA,IACtB;AAAA,IACA,IAAI,aAAa;AACf,aAAO;AAAA,IACT;AAAA,IACA;AAAA,EAAA;AAEJ;ACzOO,MAAM,uBAAuB,OAAO,+BAA+B;AAqCnE,SAAS,aAAqB,OAAe,UAA2D;AAC7G,SAAO,EAAE,CAAC,oBAAoB,GAAG,MAAM,OAAO,SAAA;AAChD;AAGA,SAAS,iBAAiB,OAAkD;AAC1E,MAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;AACxD,SAAQ,MAA2C,oBAAoB,MAAM;AAC/E;AAGA,SAAS,sBAA0C;AACjD,QAAM,YAAY;AAClB,SAAO,OAAO,UAAU,qBAAqB,cAC3C,OAAO,UAAU,wBAAwB,cACzC,OAAO,UAAU,gBAAgB,aAC9B,YACD;AACN;AAYO,SAAS,gBACd,UACA,QAA4B,uBAChB;AACZ,MAAI,UAAU,KAAM,QAAO,MAAM;AACjC,QAAM,SAAS;AAGf,iBAAe,SAAS,OAAoC;AAC1D,UAAM,UAAmB,MAAM;AAE/B,QAAI,CAAC,uBAAuB,OAAO,EAAG;AAEtC,QAAI;AAKF,YAAM,UAAU,OAAO,UAAU,eAAe,KAAK,UAAU,QAAQ,MAAM,IACzE,SAAS,QAAQ,MAAM,IACvB;AACJ,UAAI,OAAO,YAAY,WAAY,OAAM,IAAI,MAAM,2BAA2B,QAAQ,MAAM,IAAI;AAIhG,YAAM,SAAS;AACf,YAAM,UAAmB,MAAM,OAAO,GAAG,QAAQ,IAAI;AAErD,YAAM,QAAQ,iBAAiB,OAAO,IAAI,QAAQ,QAAQ;AAC1D,YAAM,WAAW,iBAAiB,OAAO,IAAI,CAAC,GAAG,QAAQ,QAAQ,IAAI;AAMrE,aAAO,YAAY,qBAAqB,QAAQ,IAAI,KAAK,GAAG,QAAQ;AAAA,IACtE,SAAS,OAAO;AACd,aAAO,YAAY,qBAAqB,QAAQ,IAAI,eAAe,KAAK,CAAC,CAAC;AAAA,IAC5E;AAAA,EACF;AAGA,WAAS,SAAS,OAA2B;AAC3C,SAAK,SAAS,KAAK;AAAA,EACrB;AAEA,SAAO,iBAAiB,WAAW,QAAQ;AAC3C,SAAO,MAAM;AACX,WAAO,oBAAoB,WAAW,QAAQ;AAAA,EAChD;AACF;ACxIO,SAAS,UACd,SACA,SACuB;AACvB,QAAM,SAAS,WAAsC,IAAI;AACzD,QAAM,YAAY,WAAW,KAAK;AAElC,YAAU,MAAM;AACd,QAAI,CAAC,qBAAqB;AACxB,aAAO,QAAQ;AACf,gBAAU,QAAQ;AAClB;AAAA,IACF;AAEA,WAAO,QAAQ,mBAAyB,QAAA,GAAW,OAAO;AAC1D,cAAU,QAAQ;AAAA,EACpB,CAAC;AAED,iBAAe,MAAM;AAGnB,WAAO,OAAO,UAAA;AACd,WAAO,QAAQ;AACf,cAAU,QAAQ;AAAA,EACpB,CAAC;AAED,SAAO,EAAE,QAAQ,UAAA;AACnB;ACVA,SAAS,kBAAkB,gBAAgC;AACzD,SAAO;AAAA;AAAA;AAAA,kBAGS,cAAc;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAkBhC;AAGA,SAAS,SAAS,OAAkD;AAClE,SAAO,OAAO,UAAU,YAAY,UAAU;AAChD;AAiBA,eAAsB,YACpB,IACA,MACA,SACoC;AACpC,MAAI,CAAC,sBAAA,EAAyB,QAAO,EAAE,QAAQ,cAAA;AAE/C,MAAI;AACJ,MAAI;AAEJ,MAAI;AACF,UAAM,IAAI,gBAAgB,IAAI,KAAK,CAAC,kBAAkB,GAAG,SAAA,CAAU,CAAC,GAAG,EAAE,MAAM,kBAAA,CAAmB,CAAC;AACnG,UAAM,WAAW,IAAI,OAAO,GAAG;AAC/B,aAAS;AAET,UAAM,QAAQ,MAAM,IAAI,QAAgB,CAAC,SAAS,WAAW;AAC3D,UAAI;AAGJ,YAAM,OAAO,MAAY;AACvB,YAAI,UAAU,OAAW,cAAa,KAAK;AAAA,MAC7C;AAEA,YAAM,EAAE,cAAc,WAAW,CAAA;AACjC,UAAI,cAAc,UAAa,YAAY,KAAK,OAAO,SAAS,SAAS,GAAG;AAC1E,gBAAQ,WAAW,MAAM;AACvB,gBAAM,QAAQ,IAAI,MAAM,mCAAmC,SAAS,IAAI;AAExE,gBAAM,OAAO;AACb,iBAAO,KAAK;AAAA,QACd,GAAG,SAAS;AAAA,MACd;AAEA,eAAS,iBAAiB,WAAW,CAAC,UAAiC;AACrE,aAAA;AACA,cAAM,QAAiB,MAAM;AAC7B,YAAI,CAAC,SAAS,KAAK,GAAG;AACpB,iBAAO,IAAI,MAAM,mCAAmC,CAAC;AACrD;AAAA,QACF;AACA,YAAI,MAAM,IAAI,MAAM,MAAM;AACxB,kBAAQ,MAAM,OAAO,CAAW;AAChC;AAAA,QACF;AACA,eAAO,QAAQ,MAAM,OAAO,CAAC,CAAC;AAAA,MAChC,CAAC;AAID,eAAS,iBAAiB,SAAS,CAAC,UAAsB;AACxD,aAAA;AACA,eAAO,QAAQ,MAAM,SAAS,MAAM,WAAW,wBAAwB,CAAC;AAAA,MAC1E,CAAC;AAED,YAAM,WAAW,SAAS;AAC1B,UAAI,aAAa,UAAa,SAAS,SAAS,EAAG,UAAS,YAAY,MAAM,CAAC,GAAG,QAAQ,CAAC;AAAA,UACtF,UAAS,YAAY,IAAI;AAAA,IAChC,CAAC;AAED,WAAO,EAAE,QAAQ,MAAM,MAAA;AAAA,EACzB,SAAS,OAAO;AACd,WAAO,EAAE,QAAQ,UAAU,OAAO,QAAQ,KAAK,EAAA;AAAA,EACjD,UAAA;AACE,YAAQ,UAAA;AAGR,QAAI,QAAQ,OAAW,KAAI,gBAAgB,GAAG;AAAA,EAChD;AACF;"}
+{"version":3,"file":"index.js","sources":["../../../src/foundation/workers/WorkerSupport.ts","../../../src/foundation/workers/WorkerProtocol.ts","../../../src/foundation/workers/WorkerClient.ts","../../../src/foundation/workers/WorkerHost.ts","../../../src/foundation/workers/UseWorker.ts","../../../src/foundation/workers/RunInWorker.ts","../../../src/foundation/workers/WorkerRunFailureCode.ts"],"sourcesContent":["// The capability probe for this slice, isolated in its own module so the client, the host, the hook, and\n// `runInWorker` all share ONE definition of \"can this runtime spawn a worker\".\n//\n// It exists because this package ships into SSR frameworks. `Worker` is a browser global with no Node\n// counterpart under that name (Node's lives behind `node:worker_threads`), so a module-level\n// `new Worker(...)` anywhere in this slice would be a hard crash the moment a server renders a page that\n// imports it. The rule this module enforces: NOTHING here touches `Worker` outside a function body, and\n// every entry point probes first and answers `unsupported` rather than throwing.\n//\n// `typeof Worker` rather than `'Worker' in globalThis`: `typeof` on an undeclared identifier is the one\n// read that cannot raise a `ReferenceError`, which matters for bundles evaluated before a DOM shim is\n// installed. The `globalThis` form would also work today, but the `typeof` form is the one that stays\n// correct if this ever runs as a classic script.\n\n/**\n * Reports whether the current runtime can construct a `Worker`.\n *\n * `false` under SSR and in Node's test environment. Call it before anything that would construct one —\n * every entry point in this slice already does, so this is for a consumer branching its own UI.\n */\nexport function isWorkerSupported(): boolean {\n  return typeof Worker === 'function';\n}\n\n/**\n * Reports whether the runtime can build a worker from a `Blob` URL — the strictly stronger requirement\n * behind {@link runInWorker}, which needs `Blob` and `URL.createObjectURL` on top of `Worker`.\n *\n * Separate from {@link isWorkerSupported} because the two can genuinely diverge: a locked-down CSP with\n * no `worker-src blob:` leaves `Worker` fully functional while making the blob route unusable.\n */\nexport function isBlobWorkerSupported(): boolean {\n  return (\n    isWorkerSupported() &&\n    typeof Blob === 'function' &&\n    typeof URL !== 'undefined' &&\n    typeof URL.createObjectURL === 'function' &&\n    typeof URL.revokeObjectURL === 'function'\n  );\n}\n","// The wire format both halves of the RPC agree on, kept in one dependency-free module so the client and\n// the host can never drift apart, and so the parts worth testing without a browser (id allocation, the\n// shape guards) are testable in the node project.\n//\n// TWO DECISIONS HERE ARE NOT OBVIOUS.\n//\n// 1. EVERY MESSAGE CARRIES A CHANNEL TAG. A `Worker` is a single shared `postMessage` pipe, not a private\n//    one: the same worker may also carry a consumer's own hand-written traffic, a bundler's HMR ping, or\n//    another library's protocol. Without a tag, a guard keyed only on `typeof id === 'number'` would\n//    happily adopt a foreign message and resolve — or worse, reject — an unrelated call. So both guards\n//    demand the tag first, and anything unrecognized is IGNORED rather than treated as an error: a message\n//    that isn't ours is not a protocol violation, it is someone else's message.\n//\n// 2. SUCCESS AND FAILURE ARE SPLIT BY AN EXPLICIT `ok` FLAG, not by probing for an `error` key. `undefined`\n//    is a legitimate result — a handler returning nothing must still resolve, not be misread as a failure\n//    because its `result` member is absent after a structured-clone round trip. The boolean makes the\n//    union genuinely discriminated and keeps `void` methods working.\n//\n// The error side of the wire is a `SerializedError` from `foundation/errors`, not an `Error`: structured\n// clone drops `stack` and the subclass, so an `Error` posted directly arrives as a bare object with only\n// `message` intact. `serializeError` flattens it to plain JSON-safe members (including the `cause` chain)\n// and the client feeds that back through `toError` on the far side.\n\nimport type { SerializedError } from '../errors';\n\n/**\n * Tags every message belonging to this protocol. A namespaced literal rather than a `Symbol`, because a\n * `Symbol` does not survive structured clone and would arrive as `undefined` on the far thread.\n */\nexport const WorkerMessageChannel = '@wow-two-beta/worker-rpc';\n\n/** Names the channel tag's type — used to type the envelopes without restating the literal. */\nexport type WorkerMessageChannel = typeof WorkerMessageChannel;\n\n/** Describes a call travelling from the client to the worker. */\nexport interface WorkerRequestMessage {\n  /** The protocol tag — always {@link WorkerMessageChannel}. */\n  readonly channel: WorkerMessageChannel;\n\n  /** The envelope discriminant, distinguishing a request from a reply on the same pipe. */\n  readonly kind: 'request';\n\n  /** The correlation id the reply must echo back. Unique per client, monotonic. */\n  readonly id: number;\n\n  /** The handler name to dispatch to on the worker side. */\n  readonly method: string;\n\n  /** The positional arguments, structured-cloned (or transferred) to the worker. */\n  readonly args: ReadonlyArray<unknown>;\n}\n\n/** Describes a reply carrying a handler's resolved value. */\nexport interface WorkerSuccessMessage {\n  /** The protocol tag — always {@link WorkerMessageChannel}. */\n  readonly channel: WorkerMessageChannel;\n\n  /** The envelope discriminant. */\n  readonly kind: 'response';\n\n  /** The correlation id echoed from the request this answers. */\n  readonly id: number;\n\n  /** The success discriminant. */\n  readonly ok: true;\n\n  /** The handler's resolved value. Legitimately `undefined` for a `void` method. */\n  readonly result: unknown;\n}\n\n/** Describes a reply carrying a handler's failure. */\nexport interface WorkerFailureMessage {\n  /** The protocol tag — always {@link WorkerMessageChannel}. */\n  readonly channel: WorkerMessageChannel;\n\n  /** The envelope discriminant. */\n  readonly kind: 'response';\n\n  /** The correlation id echoed from the request this answers. */\n  readonly id: number;\n\n  /** The failure discriminant. */\n  readonly ok: false;\n\n  /** The JSON-safe projection of the thrown value, rehydrated by `toError` on the client. */\n  readonly error: SerializedError;\n}\n\n/** Describes either half of a reply — the union the client switches on. */\nexport type WorkerResponseMessage = WorkerSuccessMessage | WorkerFailureMessage;\n\n/** Narrows an `unknown` to a non-null object so members can be read without a `TypeError`. */\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n\n/**\n * Recognizes a request envelope arriving on the worker side.\n *\n * Deliberately total and silent: a message failing this check is ignored by the host, because the pipe is\n * shared and a foreign message must not be answered with a protocol error addressed to nobody.\n */\nexport function isWorkerRequestMessage(value: unknown): value is WorkerRequestMessage {\n  if (!isRecord(value)) return false;\n  return (\n    value['channel'] === WorkerMessageChannel &&\n    value['kind'] === 'request' &&\n    typeof value['id'] === 'number' &&\n    typeof value['method'] === 'string' &&\n    Array.isArray(value['args'])\n  );\n}\n\n/**\n * Recognizes a reply envelope arriving on the client side.\n *\n * Note it does NOT require a `result` member on the success branch — absent and `undefined` are the same\n * thing after a clone, and a `void` handler must still resolve its call.\n */\nexport function isWorkerResponseMessage(value: unknown): value is WorkerResponseMessage {\n  if (!isRecord(value)) return false;\n  if (value['channel'] !== WorkerMessageChannel || value['kind'] !== 'response') return false;\n  if (typeof value['id'] !== 'number') return false;\n\n  const ok = value['ok'];\n  if (ok === true) return true;\n  return ok === false && isRecord(value['error']);\n}\n\n/** Builds a request envelope. */\nexport function createRequestMessage(id: number, method: string, args: ReadonlyArray<unknown>): WorkerRequestMessage {\n  return { channel: WorkerMessageChannel, kind: 'request', id, method, args };\n}\n\n/** Builds a success reply. */\nexport function createSuccessMessage(id: number, result: unknown): WorkerSuccessMessage {\n  return { channel: WorkerMessageChannel, kind: 'response', id, ok: true, result };\n}\n\n/** Builds a failure reply. */\nexport function createFailureMessage(id: number, error: SerializedError): WorkerFailureMessage {\n  return { channel: WorkerMessageChannel, kind: 'response', id, ok: false, error };\n}\n\n/**\n * Creates a per-client monotonic id source, starting at `1` so a falsy `0` never identifies a real call.\n *\n * Per-client rather than module-global on purpose: two clients over two workers each keep their own\n * sequence, so ids stay small and readable in a log, and one client's traffic can never be confused with\n * another's. No wrap handling — exhausting `Number.MAX_SAFE_INTEGER` at a million calls a second would\n * take roughly 285 years, so a counter reset is dead code that could only ever hide a bug.\n */\nexport function createRequestIdAllocator(): () => number {\n  let previous = 0;\n  return () => {\n    previous += 1;\n    return previous;\n  };\n}\n","// The main-thread half of the RPC: turns a `Worker`'s fire-and-forget `postMessage` pipe into typed,\n// awaitable method calls.\n//\n// THE CENTRAL DESIGN CONSTRAINT — WHY THERE IS A MAP INSTEAD OF A LISTENER PER CALL.\n// The tempting implementation is: post the request, attach a one-shot `message` listener, resolve from it,\n// remove it. That reads cleanly and is WRONG, because `postMessage` gives no ordering guarantee between a\n// request and its reply. A worker whose handlers are async — a `fetch`, an IndexedDB read, anything\n// awaited — finishes them in completion order, not arrival order. So issue `slow()` then `fast()` and the\n// replies come back `fast`, `slow`. A one-shot listener resolves the FIRST reply it sees, so `slow()`\n// receives `fast()`'s value with the right type and a plausible-looking value, and `fast()` receives\n// `slow()`'s. Nothing throws. There is no stack trace. The two results are simply swapped, and the bug\n// only appears once two calls overlap — which in development, with one call at a time, they never do.\n//\n// The fix is the only fix: correlate explicitly. Every request carries a monotonic id, ONE permanent\n// listener owns the pipe, and it routes each reply to the pending entry that id names. The out-of-order\n// case is covered by a test that makes the worker answer the second request first.\n//\n// LEAK DISCIPLINE. The pending map is the one place this class can leak, since an entry holds a promise's\n// resolve/reject closures alive forever. Every exit path removes its entry through the same `settle` call:\n// a reply, a timeout, a worker-level error, and `terminate`. A late reply arriving after its entry is gone\n// is dropped silently — it is the expected consequence of a timeout, not an error to report.\n//\n// TIMEOUTS ARE NOT DRIVEN FROM `foundation/resilience`, and that is deliberate rather than an oversight:\n// that slice models RETRIES over HTTP statuses (`computeRetryDelay`, `shouldRetry(policy, count, status)`)\n// and has no timeout primitive to reuse. A per-call deadline over a stateful pipe is a different shape —\n// there is no status to classify and a retry would re-run a handler that may not be idempotent. Retrying a\n// worker call is the consumer's decision, and a consumer that wants one can wrap `call` with that slice's\n// helpers.\n//\n// ERROR ATTRIBUTION SPLITS IN TWO, because the two failures carry different amounts of information:\n//  - a handler that throws is caught INSIDE the worker and replied to with its own id, so exactly one call\n//    rejects and its siblings are untouched;\n//  - an `ErrorEvent` on the worker itself (a script that failed to parse, a top-level throw) carries NO\n//    id — nothing identifies which call, if any, provoked it, and the worker is generally unusable\n//    afterwards. Rejecting only a guess would strand the rest, so every in-flight call rejects.\n// An `ErrorEvent` is also not an `Error` — it is an event with `message` / `filename` / `lineno` and an\n// `error` member that is `null` for a cross-origin script. That is precisely what `toError` is for.\n\nimport { toError } from '../errors';\n\nimport {\n  createRequestIdAllocator,\n  createRequestMessage,\n  isWorkerResponseMessage,\n  type WorkerResponseMessage,\n} from './WorkerProtocol';\n\n/**\n * Constrains an RPC contract to methods only — used as `TApi extends WorkerApiOf<TApi>`.\n *\n * The self-reference is not decoration, it is the only form a plain `interface` satisfies. The obvious\n * spelling, `TApi extends Record<string, Fn>`, silently rejects every `interface`: TypeScript grants an\n * implicit index signature to type ALIASES and inferred object literals but never to an interface, so\n * `interface MathApi { add(a: number, b: number): number }` — the shape this slice's own documentation\n * recommends, and the one a consumer sharing a contract between two files will reach for — fails the\n * constraint with a message about a missing index signature that says nothing about what to do. Mapping\n * over `keyof TApi` asks the same question (is every member callable?) without ever requiring one.\n *\n * `never[]` in the parameter position is the standard \"any function is assignable here\" trick: parameters\n * are contravariant, so it accepts every signature while `Parameters<TApi[TMethod]>` still reads a\n * concrete contract's own argument types exactly.\n */\nexport type WorkerApiOf<TApi> = { [TMethod in keyof TApi]: (...args: never[]) => unknown };\n\n/** Tunes a single call. */\nexport interface WorkerCallOptions {\n  /**\n   * The deadline in milliseconds. Rejects with an `Error` named `TimeoutError` — the same name\n   * `AbortSignal.timeout()` uses, so `isTimeoutError` from `foundation/errors` recognizes it. Overrides\n   * the client-level default; omit (or pass a non-positive value) for no deadline.\n   */\n  readonly timeoutMs?: number;\n\n  /**\n   * The objects to transfer rather than clone — an `ArrayBuffer`, `MessagePort`, `ImageBitmap`, or\n   * `OffscreenCanvas` reachable from `args`.\n   *\n   * A transferred object is NEUTERED in the sender: after the call, the caller's own `ArrayBuffer` has\n   * `byteLength === 0` and reading it throws. This is the single most surprising thing about the API and\n   * is the price of the move — see the `withTransfer` docs for the full note.\n   */\n  readonly transfer?: ReadonlyArray<Transferable>;\n}\n\n/** Tunes a client. */\nexport interface WorkerClientOptions {\n  /** The default deadline in milliseconds applied to every call that does not set its own. Omit for none. */\n  readonly timeoutMs?: number;\n\n  /**\n   * Called with the normalized error when the WORKER ITSELF fails — an `ErrorEvent` or a `messageerror`,\n   * neither of which names a call. The seam for logging a broken worker; a per-call failure never reaches\n   * it, since that rejects the call instead. A throw from this callback is swallowed.\n   */\n  readonly onError?: (error: Error) => void;\n}\n\n/** The typed handle over one worker. */\nexport interface WorkerClient<TApi extends WorkerApiOf<TApi>> {\n  /**\n   * Calls `method` on the worker and resolves with its reply. Rejects if the handler throws, the deadline\n   * elapses, the worker dies, or {@link WorkerClient.terminate} is called while this is in flight.\n   */\n  call<TMethod extends keyof TApi & string>(\n    method: TMethod,\n    ...args: Parameters<TApi[TMethod]>\n  ): Promise<Awaited<ReturnType<TApi[TMethod]>>>;\n\n  /**\n   * Calls `method` with per-call options — a deadline, a transfer list, or both. Otherwise identical to\n   * {@link WorkerClient.call}.\n   */\n  callWith<TMethod extends keyof TApi & string>(\n    options: WorkerCallOptions,\n    method: TMethod,\n    ...args: Parameters<TApi[TMethod]>\n  ): Promise<Awaited<ReturnType<TApi[TMethod]>>>;\n\n  /** The number of calls awaiting a reply — the observable that proves an exit path cleaned up after itself. */\n  readonly pendingCount: number;\n\n  /** Whether {@link WorkerClient.terminate} has run. A terminated client rejects further calls rather than hanging. */\n  readonly terminated: boolean;\n\n  /**\n   * Kills the worker and rejects every in-flight call. Idempotent.\n   *\n   * The rejection is the point: a terminated worker will never reply, so leaving those promises pending\n   * would hang each awaiting caller forever with no error to catch.\n   */\n  terminate(): void;\n}\n\n/** Holds the two closures and the timer belonging to one awaited call. */\ninterface PendingCall {\n  /** The method name — carried only so a timeout / termination message can name what was lost. */\n  readonly method: string;\n\n  /** Settles the caller's promise with the worker's reply. */\n  readonly resolve: (value: unknown) => void;\n\n  /** Fails the caller's promise. */\n  readonly reject: (error: Error) => void;\n\n  /** The deadline timer, cleared on every exit path so a settled call cannot fire one later. */\n  timer?: ReturnType<typeof setTimeout>;\n}\n\n/** Builds the `TimeoutError`-named error a lapsed deadline rejects with, so `isTimeoutError` recognizes it. */\nfunction createTimeoutError(method: string, timeoutMs: number): Error {\n  const error = new Error(`Worker call \\`${method}\\` timed out after ${timeoutMs}ms`);\n  error.name = 'TimeoutError';\n  return error;\n}\n\n/**\n * Wraps a `Worker` in a typed request/response client.\n *\n * The worker must run {@link exposeWorkerApi} (or speak the same envelope). `TApi` is the shared contract:\n * declare it once, use it here and to type the handler map on the worker side.\n *\n * Takes an already-constructed `Worker` rather than a factory so it stays usable with any worker the\n * consumer's bundler produced, and so nothing in this module ever touches the `Worker` constructor — which\n * is what keeps it importable under SSR.\n */\nexport function createWorkerClient<TApi extends WorkerApiOf<TApi>>(\n  worker: Worker,\n  options?: WorkerClientOptions,\n): WorkerClient<TApi> {\n  const pendingCalls = new Map<number, PendingCall>();\n  const nextRequestId = createRequestIdAllocator();\n  let terminated = false;\n\n  /** Removes a pending entry and cancels its timer — the single exit path every settle route goes through. */\n  function settle(id: number): PendingCall | undefined {\n    const pending = pendingCalls.get(id);\n    if (pending === undefined) return undefined;\n    if (pending.timer !== undefined) clearTimeout(pending.timer);\n    pendingCalls.delete(id);\n    return pending;\n  }\n\n  /** Fails every in-flight call — used where the failure names no single call (worker death, termination). */\n  function rejectAll(toFailure: (pending: PendingCall) => Error): void {\n    for (const id of [...pendingCalls.keys()]) {\n      const pending = settle(id);\n      if (pending !== undefined) pending.reject(toFailure(pending));\n    }\n  }\n\n  /** Hands the consumer a worker-level failure without letting their reporter's own throw escape. */\n  function report(error: Error): void {\n    if (options?.onError === undefined) return;\n    try {\n      options.onError(error);\n    } catch {\n      // The consumer's reporter failed. The calls have already been rejected, which is the guarantee that\n      // matters; a second failure here would replace a real error with an unrelated one.\n    }\n  }\n\n  /** Routes one reply to the call its id names. */\n  function handleMessage(event: MessageEvent<unknown>): void {\n    const message: unknown = event.data;\n    // Not our envelope — the pipe is shared, so someone else's message is not an error.\n    if (!isWorkerResponseMessage(message)) return;\n\n    const pending = settle(message.id);\n    // Already settled by a timeout or a `terminate`. A late reply is the expected tail of those paths.\n    if (pending === undefined) return;\n\n    const reply: WorkerResponseMessage = message;\n    if (reply.ok) pending.resolve(reply.result);\n    else pending.reject(toError(reply.error));\n  }\n\n  /** Fails everything in flight when the worker itself dies, since no id attributes the failure. */\n  function handleError(event: ErrorEvent): void {\n    // `event.error` is `null` for a cross-origin script, leaving `message` as the only signal — an\n    // `ErrorEvent` is not an `Error`, which is exactly why this goes through `toError`.\n    const failure = toError(event.error ?? event.message ?? 'Worker error');\n    rejectAll(() => failure);\n    report(failure);\n  }\n\n  /** Fails everything in flight when a reply could not be deserialized — the payload, and its id, are lost. */\n  function handleMessageError(): void {\n    const failure = new Error('Worker sent a message that could not be deserialized');\n    rejectAll(() => failure);\n    report(failure);\n  }\n\n  worker.addEventListener('message', handleMessage);\n  worker.addEventListener('error', handleError);\n  worker.addEventListener('messageerror', handleMessageError);\n\n  /** Posts one request and returns the promise its reply will settle. Untyped — the wire has no types. */\n  function invoke(callOptions: WorkerCallOptions, method: string, args: ReadonlyArray<unknown>): Promise<unknown> {\n    if (terminated) {\n      return Promise.reject(new Error(`Worker call \\`${method}\\` rejected: the client is terminated`));\n    }\n\n    const id = nextRequestId();\n\n    return new Promise<unknown>((resolve, reject) => {\n      const pending: PendingCall = { method, resolve, reject };\n      pendingCalls.set(id, pending);\n\n      const timeoutMs = callOptions.timeoutMs ?? options?.timeoutMs;\n      if (timeoutMs !== undefined && timeoutMs > 0 && Number.isFinite(timeoutMs)) {\n        pending.timer = setTimeout(() => {\n          // `settle` first: the entry must be gone before the caller is rejected, or a timeout would leave\n          // the map holding a settled promise's closures for as long as the client lives.\n          if (settle(id) !== undefined) reject(createTimeoutError(method, timeoutMs));\n        }, timeoutMs);\n      }\n\n      try {\n        const request = createRequestMessage(id, method, args);\n        const transfer = callOptions.transfer;\n        if (transfer !== undefined && transfer.length > 0) worker.postMessage(request, [...transfer]);\n        else worker.postMessage(request);\n      } catch (error) {\n        // `postMessage` throws synchronously on a non-cloneable argument (a function, a DOM node, a class\n        // instance with methods) and on an already-detached buffer. Rejecting the call keeps every failure\n        // on the promise, so a caller never has to both `await` and wrap the call in a `try`.\n        if (settle(id) !== undefined) reject(toError(error));\n      }\n    });\n  }\n\n  function terminate(): void {\n    if (terminated) return;\n    terminated = true;\n\n    rejectAll((pending) => new Error(`Worker call \\`${pending.method}\\` rejected: the worker was terminated`));\n\n    worker.removeEventListener('message', handleMessage);\n    worker.removeEventListener('error', handleError);\n    worker.removeEventListener('messageerror', handleMessageError);\n    worker.terminate();\n  }\n\n  return {\n    call<TMethod extends keyof TApi & string>(method: TMethod, ...args: Parameters<TApi[TMethod]>) {\n      // The one cast in this module, and an unavoidable one: a structured-clone pipe carries no type\n      // information, so the contract `TApi` asserts is checked at the call site and trusted here.\n      return invoke({}, method, args as readonly unknown[]) as Promise<Awaited<ReturnType<TApi[TMethod]>>>;\n    },\n    callWith<TMethod extends keyof TApi & string>(\n      callOptions: WorkerCallOptions,\n      method: TMethod,\n      ...args: Parameters<TApi[TMethod]>\n    ) {\n      return invoke(callOptions, method, args as readonly unknown[]) as Promise<Awaited<ReturnType<TApi[TMethod]>>>;\n    },\n    get pendingCount() {\n      return pendingCalls.size;\n    },\n    get terminated() {\n      return terminated;\n    },\n    terminate,\n  };\n}\n","// The worker-thread half of the RPC. Goal: a worker entry file is three lines.\n//\n//   import { exposeWorkerApi } from '@wow-two-beta/ui/foundation/workers';\n//   const handlers = { add: (a: number, b: number) => a + b };\n//   exposeWorkerApi(handlers);\n//\n// THE SCOPE IS STRUCTURALLY TYPED, NOT `DedicatedWorkerGlobalScope`. That type ships in TypeScript's\n// `webworker` lib, and this package compiles under `[\"ES2022\", \"DOM\", \"DOM.Iterable\"]` — pulling in\n// `webworker` alongside `DOM` is not an option, since the two declare conflicting globals (`self`,\n// `postMessage`, `location`) and the merge fails outright. A minimal structural `WorkerScope` describes\n// exactly the three members used and typechecks under either lib. It also makes the host injectable, which\n// is what lets a test drive both halves without a real worker.\n//\n// THE DEFAULT SCOPE IS RESOLVED, NOT ASSUMED. `globalThis` in a window is a `Window`, whose `postMessage`\n// has a different signature (`targetOrigin`) — so the default is probed for the two members it needs and\n// yields `null` when absent. Calling this on the main thread or under SSR therefore registers nothing and\n// returns a no-op disposer instead of throwing. Importing a worker module from the main thread is a\n// routine accident (a barrel re-export, a bundler pulling it into the wrong chunk); it should be inert,\n// not fatal.\n//\n// EVERY FAILURE PATH MUST STILL POST A REPLY. A handler that throws, a method that does not exist, a\n// rejected promise, and even a RESULT THAT WILL NOT CLONE all have to produce a `{ id, error }` message,\n// because the client's pending entry is keyed on that id and only a reply (or its deadline) releases it.\n// The non-cloneable result is the subtle one: posting the success throws inside the host, and without the\n// second try/catch around it the call would hang until its timeout — or forever, if it has none.\n\nimport { serializeError } from '../errors';\n\nimport type { WorkerApiOf } from './WorkerClient';\nimport { createFailureMessage, createSuccessMessage, isWorkerRequestMessage } from './WorkerProtocol';\n\n/**\n * Describes the parts of a worker's global scope this module uses. Structural so it typechecks without the\n * `webworker` lib, and so a test can pass a stand-in.\n */\nexport interface WorkerScope {\n  /** Subscribes to inbound messages. */\n  addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;\n\n  /** Unsubscribes a previously registered listener. */\n  removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;\n\n  /** Posts a reply back to the main thread, optionally transferring ownership of objects reachable from it. */\n  postMessage(message: unknown, transfer?: ReadonlyArray<Transferable>): void;\n}\n\n/** Constrains a handler map: method name → implementation, sync or async. */\nexport type WorkerHandlerMap = Record<string, (...args: never[]) => unknown>;\n\n/**\n * Projects a client-side contract into the handler map that satisfies it — the optional annotation for a\n * consumer who wants the compiler to hold both halves of the RPC to one interface.\n *\n * ```ts\n * const handlers: WorkerHandlersOf<MathApi> = { add: (a, b) => a + b };\n * exposeWorkerApi(handlers);\n * ```\n *\n * Each handler may return the value, a promise of it, or that value wrapped by {@link withTransfer} — all\n * three arrive at the client as the plain value.\n */\nexport type WorkerHandlersOf<TApi extends WorkerApiOf<TApi>> = {\n  readonly [TMethod in keyof TApi]: (\n    ...args: Parameters<TApi[TMethod]>\n  ) =>\n    | Awaited<ReturnType<TApi[TMethod]>>\n    | Promise<Awaited<ReturnType<TApi[TMethod]>>>\n    | WorkerTransfer<Awaited<ReturnType<TApi[TMethod]>>>\n    | Promise<WorkerTransfer<Awaited<ReturnType<TApi[TMethod]>>>>;\n};\n\n/**\n * Brands a {@link WorkerTransfer} wrapper. Exported only because the declaration emit needs the symbol to\n * be nameable; it is an implementation detail, not something to reference. The wrapper is unwrapped before\n * the reply is posted, so this symbol never crosses a thread boundary.\n */\nexport const WorkerTransferMarker = Symbol('@wow-two-beta/worker-transfer');\n\n/** Wraps a handler's return value together with the objects to move rather than copy. Built by {@link withTransfer}. */\nexport interface WorkerTransfer<TValue> {\n  /** The brand. */\n  readonly [WorkerTransferMarker]: true;\n\n  /** The value the client will receive — the wrapper itself is stripped before posting. */\n  readonly value: TValue;\n\n  /** The objects whose ownership moves to the main thread. */\n  readonly transfer: ReadonlyArray<Transferable>;\n}\n\n/**\n * Marks a handler's result for transfer instead of a structured-clone copy — the return-path counterpart\n * of `WorkerCallOptions.transfer`.\n *\n * ```ts\n * const handlers = {\n *   render: (size: number) => {\n *     const pixels = new ArrayBuffer(size);\n *     return withTransfer(pixels, [pixels]); // moved, not copied\n *   },\n * };\n * ```\n *\n * THE TRANSFERRED OBJECT IS NEUTERED IN THE SENDER. This is the single most surprising thing about the\n * whole API and it is not a bug: transfer is a MOVE. Once posted, the worker's own `pixels` has\n * `byteLength === 0` and any read of it throws — the memory now belongs to the receiving thread. So\n * transfer only a buffer you are done with, and never one you also returned a view over or kept in a\n * cache. The payoff is that a 100 MB buffer costs a pointer hand-off instead of a 100 MB copy, which for\n * a large payload is the difference between a frame and a stall.\n *\n * The same neutering hits the CALLER when transferring into the worker via `callWith({ transfer })`: after\n * that call the caller's `ArrayBuffer` is the empty one.\n */\nexport function withTransfer<TValue>(value: TValue, transfer: ReadonlyArray<Transferable>): WorkerTransfer<TValue> {\n  return { [WorkerTransferMarker]: true, value, transfer };\n}\n\n/** Recognizes the wrapper so the host can strip it before replying. */\nfunction isWorkerTransfer(value: unknown): value is WorkerTransfer<unknown> {\n  if (typeof value !== 'object' || value === null) return false;\n  return (value as Partial<WorkerTransfer<unknown>>)[WorkerTransferMarker] === true;\n}\n\n/** Probes `globalThis` for a usable worker scope, yielding `null` on the main thread and under SSR. */\nfunction resolveDefaultScope(): WorkerScope | null {\n  const candidate = globalThis as unknown as Partial<WorkerScope>;\n  return typeof candidate.addEventListener === 'function' &&\n    typeof candidate.removeEventListener === 'function' &&\n    typeof candidate.postMessage === 'function'\n    ? (candidate as WorkerScope)\n    : null;\n}\n\n/**\n * Registers `handlers` as the worker's RPC surface and returns a disposer that unregisters them.\n *\n * Dispatch is by method name; an unknown method rejects that one call rather than killing the worker. A\n * handler may be sync or async — the result is awaited either way — and may wrap its return value in\n * {@link withTransfer} to move a large buffer instead of copying it.\n *\n * Never throws, including when there is no worker scope (main thread, SSR), where it registers nothing and\n * the returned disposer is a no-op.\n */\nexport function exposeWorkerApi<THandlers extends WorkerHandlerMap>(\n  handlers: THandlers,\n  scope: WorkerScope | null = resolveDefaultScope(),\n): () => void {\n  if (scope === null) return () => undefined;\n  const target = scope;\n\n  /** Runs one request to completion and posts exactly one reply. */\n  async function dispatch(event: MessageEvent): Promise<void> {\n    const request: unknown = event.data;\n    // Not our envelope — the pipe is shared, so stay silent rather than answering a message we do not own.\n    if (!isWorkerRequestMessage(request)) return;\n\n    try {\n      // OWN properties only. A bare `handlers[method]` walks the prototype chain, so a request for\n      // `toString` / `valueOf` / `constructor` finds a real function and would be dispatched — answering\n      // `'[object Object]'` to a method the worker never exposed, or invoking `Object`. The method name\n      // arrives from another thread and is untrusted input; the surface is exactly what the map declares.\n      const handler = Object.prototype.hasOwnProperty.call(handlers, request.method)\n        ? handlers[request.method]\n        : undefined;\n      if (typeof handler !== 'function') throw new Error(`Unknown worker method \\`${request.method}\\``);\n\n      // The handler map's `never[]` parameters make it unassignable at a call site by construction — the\n      // wire is untyped, so the arguments are trusted here and checked by `TApi` on the client.\n      const invoke = handler as (...args: ReadonlyArray<unknown>) => unknown;\n      const outcome: unknown = await invoke(...request.args);\n\n      const value = isWorkerTransfer(outcome) ? outcome.value : outcome;\n      const transfer = isWorkerTransfer(outcome) ? [...outcome.transfer] : undefined;\n\n      // This `postMessage` is inside the try on purpose. It throws when the result will not structured-clone\n      // (a function, a DOM node, a class instance carrying methods) or when a transferred object is already\n      // detached — and the caller's pending entry outlives that throw, so the failure below is what releases\n      // it. Without this, such a call hangs until its deadline, or forever when it has none.\n      target.postMessage(createSuccessMessage(request.id, value), transfer);\n    } catch (error) {\n      target.postMessage(createFailureMessage(request.id, serializeError(error)));\n    }\n  }\n\n  /** Bridges the sync listener signature to the async dispatcher; `dispatch` never rejects, so nothing escapes. */\n  function listener(event: MessageEvent): void {\n    void dispatch(event);\n  }\n\n  target.addEventListener('message', listener);\n  return () => {\n    target.removeEventListener('message', listener);\n  };\n}\n","// The Vue binding: ties one worker's lifetime to one scope's, so a mounted component owns a worker and a\n// disposed one does not.\n//\n// TERMINATION ON TEARDOWN IS THE WHOLE POINT. A `Worker` is an OS thread with its own JS heap; it is not\n// garbage-collected when the last reference to it drops, because the thread itself is a root. A component\n// that creates one and navigates away leaks a live thread for the rest of the session, and a list that\n// mounts one per row leaks one per row. So `onScopeDispose` calls `client.terminate()` — which also rejects\n// every in-flight call, releasing any `await` still parked on the torn-down component.\n//\n// THE FACTORY IS CALLED ONCE, IN `onMounted`. A component's `setup` runs once, so the original's\n// factory-in-a-ref indirection has nothing to protect against here — the factory a consumer passes is the\n// one and only. The natural call site is still an inline arrow:\n//\n//   const { client } = useWorker(() => new Worker(url, { type: 'module' }));\n//\n// and the worker is created exactly once per mount. The cost is unchanged: changing what the factory would\n// return later does NOT swap the worker. Remount to swap — a `key` on the component, which is the honest\n// idiom for \"this is a different resource now\".\n//\n// SSR: the worker is created in `onMounted`, which does not run on the server, so nothing here can touch the\n// `Worker` constructor during a server render. `client` is therefore `null` on the server and until mount,\n// non-null from the first mount onward. `supported` is likewise set in `onMounted` rather than read at setup\n// — reading a browser capability at setup time is exactly what produces a hydration mismatch, where the\n// server's `false` and the client's `true` disagree on the first pass.\n\nimport { onMounted, onScopeDispose, shallowRef, type ShallowRef } from 'vue';\n\nimport { createWorkerClient, type WorkerApiOf, type WorkerClient, type WorkerClientOptions } from './WorkerClient';\nimport { isWorkerSupported } from './WorkerSupport';\n\n/** What {@link useWorker} returns. */\nexport interface UseWorkerControls<TApi extends WorkerApiOf<TApi>> {\n  /**\n   * The typed client, or `null` before mount and in any runtime without `Worker`.\n   *\n   * Guard on it (`client.value?.call(...)`) rather than asserting: the `null` window is real until mount, so\n   * an effect or event handler firing before the worker exists must have a defined answer.\n   */\n  readonly client: Readonly<ShallowRef<WorkerClient<TApi> | null>>;\n\n  /**\n   * Whether this runtime can spawn a worker, as determined after mount. `false` during SSR and until mount —\n   * before then it is not yet knowable, and claiming otherwise at setup time would desync hydration.\n   */\n  readonly supported: Readonly<ShallowRef<boolean>>;\n}\n\n/**\n * Owns a worker for the lifetime of the calling scope: created on mount, terminated on disposal.\n *\n * The factory is invoked once per mount, so an inline arrow is the expected call shape.\n */\nexport function useWorker<TApi extends WorkerApiOf<TApi>>(\n  factory: () => Worker,\n  options?: WorkerClientOptions,\n): UseWorkerControls<TApi> {\n  const client = shallowRef<WorkerClient<TApi> | null>(null);\n  const supported = shallowRef(false);\n\n  onMounted(() => {\n    if (!isWorkerSupported()) {\n      client.value = null;\n      supported.value = false;\n      return;\n    }\n\n    client.value = createWorkerClient<TApi>(factory(), options);\n    supported.value = true;\n  });\n\n  onScopeDispose(() => {\n    // Rejects everything in flight as well as killing the thread — an `await` left over from the torn-down\n    // component gets an error instead of hanging forever.\n    client.value?.terminate();\n    client.value = null;\n    supported.value = false;\n  });\n\n  return { client, supported };\n}\n","import type { WorkerRunResult } from './models/WorkerRunResult';\n\n// One-shot offloading: run a self-contained function on another thread without authoring a worker file,\n// wiring it into the bundler, or keeping a thread alive afterwards. For the one expensive pure computation\n// that would otherwise block a frame — a hash over a large buffer, a sort of a hundred thousand rows,\n// parsing a big CSV.\n//\n// THE FUNCTION IS STRINGIFIED, SO IT CANNOT CLOSE OVER ANYTHING. This is the constraint that makes or\n// breaks every use of this helper, and it fails at RUNTIME, inside the other thread, with a bare\n// `ReferenceError` naming a variable that is plainly in scope at the call site:\n//\n//   const factor = 2;\n//   await runInWorker((n: number) => n * factor, [21]);   // ✗ ReferenceError: factor is not defined\n//   await runInWorker((n: number, f: number) => n * f, [21, 2]); // ✓ everything arrives through args\n//\n// `Function.prototype.toString` returns source text, not a closure. The text is embedded in a `Blob` and\n// evaluated in a scope that shares nothing with the module it was written in — no captured variables, no\n// imports, no `document`, no Vue. Everything the function needs must arrive through `args`, and `args`\n// must survive structured clone. The same rule voids TypeScript's help here: the compiler happily\n// typechecks the captured variable it is about to strip.\n//\n// The mirror-image trap is the METHOD SHORTHAND. `({ work(n) { ... } }).work.toString()` yields\n// `work(n) { ... }`, which is not a valid expression even wrapped in parentheses, and the worker dies on a\n// syntax error. Pass a function expression or an arrow.\n//\n// THE BLOB URL IS REVOKED IN A `finally`. Each `createObjectURL` pins its blob in memory until revoked,\n// and a revoke skipped on the failure path is a leak that only shows up in the runs that already went\n// wrong. The worker is terminated there too, on every path.\n//\n// The result is a discriminated union rather than a throw, matching `foundation/share`'s idiom: an\n// unsupported runtime (SSR, or a CSP without `worker-src blob:`) is a fact to branch on, not an exception,\n// and it must be distinguishable from the function itself failing.\n\nimport { toError } from '../errors';\n\nimport { isBlobWorkerSupported } from './WorkerSupport';\nexport type { WorkerRunFailure } from './models/WorkerRunFailure';\nexport type { WorkerRunResult } from './models/WorkerRunResult';\n\n/** Tunes a {@link runInWorker} call. */\nexport interface RunInWorkerOptions {\n  /** Deadline (ms), omit for none. On lapse the worker is terminated and the result is `failed` (`TimeoutError`). */\n  readonly timeoutMs?: number;\n\n  /**\n   * The objects to transfer into the worker instead of cloning. Each is NEUTERED in the caller: an\n   * `ArrayBuffer` passed here has `byteLength === 0` once the call returns.\n   */\n  readonly transfer?: ReadonlyArray<Transferable>;\n}\n\n/**\n * Builds the worker source. Bespoke rather than reusing `exposeWorkerApi`, and necessarily so: a `Blob`\n * worker has no module resolution, so it cannot import this package — the protocol has to be inlined, and\n * a one-shot call needs no id correlation because exactly one request is ever in flight.\n *\n * Written in plain ES5-ish JS with no optional chaining, since the text is evaluated verbatim by whatever\n * engine the browser gives the worker rather than passing through this package's build.\n */\nfunction buildWorkerSource(functionSource: string): string {\n  return `self.onmessage = function (event) {\n  Promise.resolve()\n    .then(function () {\n      var fn = (${functionSource});\n      return fn.apply(null, event.data);\n    })\n    .then(function (value) {\n      self.postMessage({ ok: true, value: value });\n    })\n    .catch(function (error) {\n      var shape = { name: 'Error', message: 'Worker function failed' };\n      if (error && typeof error === 'object') {\n        if (typeof error.name === 'string') shape.name = error.name;\n        if (typeof error.message === 'string') shape.message = error.message;\n        if (typeof error.stack === 'string') shape.stack = error.stack;\n      } else if (typeof error === 'string') {\n        shape.message = error;\n      }\n      self.postMessage({ ok: false, error: shape });\n    });\n};`;\n}\n\n/** Narrows an inbound reply from the one-shot worker. */\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n\n/**\n * Runs `fn` on a throwaway worker thread and resolves with its result.\n *\n * ```ts\n * const result = await runInWorker((rows: number[]) => rows.reduce((a, b) => a + b, 0), [bigArray]);\n * if (result.ok) console.log(result.value);\n * ```\n *\n * `fn` MUST be self-contained — it is stringified, so it captures nothing from the scope it was written\n * in, and it may not be a method shorthand. Every input arrives through `args`, and both `args` and the\n * return value must survive structured clone. See the module header for the full rationale.\n *\n * Never throws: an unsupported runtime, a failed start, a thrown function, and a lapsed deadline all\n * resolve to a {@link WorkerRunResult}. The worker is terminated and the blob URL revoked on every path.\n */\nexport async function runInWorker<TArgs extends readonly unknown[], TValue>(\n  fn: (...args: TArgs) => TValue | Promise<TValue>,\n  args: TArgs,\n  options?: RunInWorkerOptions,\n): Promise<WorkerRunResult<TValue>> {\n  if (!isBlobWorkerSupported()) return { ok: false, failure: { status: 'unsupported' } };\n\n  let url: string | undefined;\n  let worker: Worker | undefined;\n  let timer: ReturnType<typeof setTimeout> | undefined;\n\n  try {\n    url = URL.createObjectURL(new Blob([buildWorkerSource(fn.toString())], { type: 'text/javascript' }));\n    const instance = new Worker(url);\n    worker = instance;\n\n    const value = await new Promise<TValue>((resolve, reject) => {\n      /** Cancels the deadline so a settled run cannot be failed by its own timer afterwards. */\n      const done = (): void => {\n        if (timer !== undefined) clearTimeout(timer);\n      };\n\n      const { timeoutMs } = options ?? {};\n      if (timeoutMs !== undefined && timeoutMs > 0 && Number.isFinite(timeoutMs)) {\n        timer = setTimeout(() => {\n          const error = new Error(`Worker function timed out after ${timeoutMs}ms`);\n          // Named for `isTimeoutError` in `foundation/errors`, matching `AbortSignal.timeout()`.\n          error.name = 'TimeoutError';\n          reject(error);\n        }, timeoutMs);\n      }\n\n      instance.addEventListener('message', (event: MessageEvent<unknown>) => {\n        done();\n        const reply: unknown = event.data;\n        if (!isRecord(reply)) {\n          reject(new Error('Worker sent an unrecognized reply'));\n          return;\n        }\n        if (reply['ok'] === true) {\n          resolve(reply['value'] as TValue);\n          return;\n        }\n        reject(toError(reply['error']));\n      });\n\n      // A worker that fails to start (a syntax error from a method shorthand, a CSP refusal) reports here\n      // as an `ErrorEvent`, which is not an `Error` — hence `toError` over the `message` fallback.\n      instance.addEventListener('error', (event: ErrorEvent) => {\n        done();\n        reject(toError(event.error ?? event.message ?? 'Worker failed to start'));\n      });\n\n      instance.addEventListener('messageerror', () => {\n        done();\n        reject(new Error('Worker reply could not be deserialized'));\n      });\n      const transfer = options?.transfer;\n      if (transfer !== undefined && transfer.length > 0) instance.postMessage(args, [...transfer]);\n      else instance.postMessage(args);\n    });\n\n    return { ok: true, value };\n  } catch (error) {\n    return { ok: false, failure: { status: 'failed', error: toError(error) } };\n  } finally {\n    if (timer !== undefined) clearTimeout(timer);\n    worker?.terminate();\n    // Revoked on every path, including the ones that already failed — an un-revoked URL pins its blob for\n    // the life of the document.\n    if (url !== undefined) URL.revokeObjectURL(url);\n  }\n}\n","/** Closed failure vocabulary for WorkerRunFailure. */\nexport const WorkerRunFailureCode = {\n  Unsupported: 'unsupported',\n  Failed: 'failed',\n} as const;\n\nexport type WorkerRunFailureCode = (typeof WorkerRunFailureCode)[keyof typeof WorkerRunFailureCode];\n"],"names":["isRecord"],"mappings":"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"}

package/dist/foundation/workers/models/WorkerRunFailure.d.ts

@@ -0,0 +1,8 @@
+import { WorkerRunFailureCode } from '../WorkerRunFailureCode';
+/** Expected reasons the operation could not produce its requested value. */
+export type WorkerRunFailure = {
+    readonly status: typeof WorkerRunFailureCode.Unsupported;
+} | {
+    readonly status: typeof WorkerRunFailureCode.Failed;
+    readonly error: Error;
+};

package/dist/foundation/workers/models/WorkerRunResult.d.ts

@@ -0,0 +1,3 @@
+import { Result } from '../../results';
+import { WorkerRunFailure } from './WorkerRunFailure';
+export type WorkerRunResult<TValue> = Result<TValue, WorkerRunFailure>;

package/dist/index.css

@@ -1,4 +1,7 @@
-@import "tailwindcss";
+@import 'tailwindcss';
+
+/* Include the package's own classes when this stylesheet is consumed from node_modules. */
+@source './';
 
 /* Dark mode variant — apply by toggling `.dark` on <html> or <body>. */
 @custom-variant dark (&:where(.dark, .dark *));
@@ -78,9 +81,8 @@
   --color-muted: #f4f4f5;
   /* 4.66:1 on muted, 5.12:1 on white (was #71717a = 4.39 on muted — AA miss) */
   --color-muted-foreground: #6d6d76;
-  /* 4.63:1 on white (was #a1a1aa = 2.56 — AA miss); still lighter than muted-fg.
-     Known gap: on muted bg this is 4.2:1 — prefer muted-foreground there. */
-  --color-subtle-foreground: #74747d;
+  /* Small text and placeholders meet 4.5:1 on background, card, popover and muted. */
+  --color-subtle-foreground: oklch(54.5% 0.0137 285.9);
   --color-card: #ffffff;
   --color-card-foreground: #18181b;
   --color-popover: #ffffff;
@@ -90,41 +92,41 @@
 
   /* Borders & focus */
   --color-border: #e4e4e7;
-  --color-border-strong: #d4d4d8;
-  --color-input: #d4d4d8;
+  --color-border-strong: oklch(64.3% 0.0055 286.3);
+  --color-input: oklch(64.3% 0.0055 286.3);
   --color-ring: #3b82f6;
 
   /* Brand (primary) */
   --color-primary: #2563eb;
   --color-primary-foreground: #ffffff;
   --color-primary-soft: #dbeafe;
-  --color-primary-soft-foreground: #1d4ed8;
+  --color-primary-soft-foreground: oklch(46.1% 0.2172 264.4);
 
   /* Severity solids + softs */
   --color-destructive: #dc2626;
   --color-destructive-foreground: #ffffff;
   --color-destructive-soft: #fef2f2;
-  --color-destructive-soft-foreground: #b91c1c;
+  --color-destructive-soft-foreground: oklch(45.8% 0.1873 27.5);
 
   --color-success: #16a34a;
-  --color-success-foreground: #ffffff;
+  --color-success-foreground: oklch(27.3% 0 89.9);
   --color-success-soft: #f0fdf4;
-  --color-success-soft-foreground: #15803d;
+  --color-success-soft-foreground: oklch(45.5% 0.1254 150.1);
 
   --color-warning: #f59e0b;
-  --color-warning-foreground: #78350f;
+  --color-warning-foreground: oklch(39.7% 0.1054 45.9);
   --color-warning-soft: #fffbeb;
-  --color-warning-soft-foreground: #b45309;
+  --color-warning-soft-foreground: oklch(50.8% 0.1366 49);
 
   /* info-700: 5.36:1 with white fg AND as text on white (info-600 = 3.68 — AA miss) */
   --color-info: #0e7490;
   --color-info-foreground: #ffffff;
   --color-info-soft: #ecfeff;
-  --color-info-soft-foreground: #0e7490;
+  --color-info-soft-foreground: oklch(44.1% 0.0822 223.1);
 
   /* Accent (secondary "pop" — teal). Emphasis distinct from primary: active/On, highlights, badges. */
   --color-accent: #0d9488;
-  --color-accent-foreground: #ffffff;
+  --color-accent-foreground: oklch(22.9% 0 89.9);
   --color-accent-soft: #ccfbf1;
   --color-accent-soft-foreground: #115e59;
 
@@ -144,8 +146,8 @@
   --duration-fast: 150ms;
   --duration-base: 200ms;
   --duration-slow: 300ms;
-  --ease-out: cubic-bezier(0, 0, 0.2, 1);   /* enter — decelerate */
-  --ease-in: cubic-bezier(0.4, 0, 1, 1);    /* exit — accelerate */
+  --ease-out: cubic-bezier(0, 0, 0.2, 1); /* enter — decelerate */
+  --ease-in: cubic-bezier(0.4, 0, 1, 1); /* exit — accelerate */
   --ease-standard: cubic-bezier(0.4, 0, 0.2, 1);
   --animate-fade-in: fade-in var(--duration-base) var(--ease-out);
   --animate-fade-out: fade-out var(--duration-fast) var(--ease-in);
@@ -199,32 +201,32 @@
   --color-inverse-foreground: #09090b;
 
   --color-border: #27272a;
-  --color-border-strong: #3f3f46;
-  --color-input: #3f3f46;
+  --color-border-strong: oklch(50.6% 0.0119 285.8);
+  --color-input: oklch(50.6% 0.0119 285.8);
   --color-ring: #60a5fa;
 
   --color-primary: #3b82f6;
-  --color-primary-foreground: #ffffff;
+  --color-primary-foreground: oklch(23.6% 0 89.9);
   --color-primary-soft: #1e3a8a;
   --color-primary-soft-foreground: #dbeafe;
 
   --color-destructive: #ef4444;
-  --color-destructive-foreground: #ffffff;
+  --color-destructive-foreground: oklch(22.7% 0 89.9);
   --color-destructive-soft: #7f1d1d;
   --color-destructive-soft-foreground: #fee2e2;
 
   --color-success: #22c55e;
-  --color-success-foreground: #ffffff;
+  --color-success-foreground: oklch(37.3% 0 89.9);
   --color-success-soft: #14532d;
   --color-success-soft-foreground: #dcfce7;
 
   --color-warning: #f59e0b;
-  --color-warning-foreground: #78350f;
+  --color-warning-foreground: oklch(39.7% 0.1054 45.9);
   --color-warning-soft: #78350f;
   --color-warning-soft-foreground: #fef3c7;
 
   --color-info: #06b6d4;
-  --color-info-foreground: #ffffff;
+  --color-info-foreground: oklch(35.7% 0 89.9);
   --color-info-soft: #164e63;
   --color-info-soft-foreground: #cffafe;
 
@@ -235,7 +237,8 @@
 }
 
 /* Body defaults so consumers get sane page colors out of the box. */
-html, body {
+html,
+body {
   background-color: var(--color-background);
   color: var(--color-foreground);
 }
@@ -247,23 +250,131 @@ html, body {
   background-image: linear-gradient(180deg, rgb(255 255 255 / 0.05), transparent 55%);
 }
 .surface-glow {
-  background-image: radial-gradient(135% 135% at 100% 112%, color-mix(in srgb, var(--color-primary) 14%, transparent), transparent 52%);
+  background-image: radial-gradient(
+    135% 135% at 100% 112%,
+    color-mix(in srgb, var(--color-primary) 14%, transparent),
+    transparent 52%
+  );
 }
 
 /* Enter/exit primitives — paired with the `--animate-*` tokens above. Subtle (8px) slides for
  * popovers/menus/toasts; full-edge drawer/sheet slides use component-level translate utilities. */
-@keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
-@keyframes fade-out { from { opacity: 1; } to { opacity: 0; } }
-@keyframes pop-in { from { opacity: 0; transform: scale(0.96); } to { opacity: 1; transform: scale(1); } }
-@keyframes pop-out { from { opacity: 1; transform: scale(1); } to { opacity: 0; transform: scale(0.96); } }
-@keyframes slide-in-top { from { opacity: 0; transform: translateY(-8px); } to { opacity: 1; transform: translateY(0); } }
-@keyframes slide-out-top { from { opacity: 1; transform: translateY(0); } to { opacity: 0; transform: translateY(-8px); } }
-@keyframes slide-in-bottom { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }
-@keyframes slide-out-bottom { from { opacity: 1; transform: translateY(0); } to { opacity: 0; transform: translateY(8px); } }
-@keyframes slide-in-left { from { opacity: 0; transform: translateX(-8px); } to { opacity: 1; transform: translateX(0); } }
-@keyframes slide-out-left { from { opacity: 1; transform: translateX(0); } to { opacity: 0; transform: translateX(-8px); } }
-@keyframes slide-in-right { from { opacity: 0; transform: translateX(8px); } to { opacity: 1; transform: translateX(0); } }
-@keyframes slide-out-right { from { opacity: 1; transform: translateX(0); } to { opacity: 0; transform: translateX(8px); } }
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+@keyframes fade-out {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+@keyframes pop-in {
+  from {
+    opacity: 0;
+    transform: scale(0.96);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+@keyframes pop-out {
+  from {
+    opacity: 1;
+    transform: scale(1);
+  }
+  to {
+    opacity: 0;
+    transform: scale(0.96);
+  }
+}
+@keyframes slide-in-top {
+  from {
+    opacity: 0;
+    transform: translateY(-8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+@keyframes slide-out-top {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(-8px);
+  }
+}
+@keyframes slide-in-bottom {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+@keyframes slide-out-bottom {
+  from {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+}
+@keyframes slide-in-left {
+  from {
+    opacity: 0;
+    transform: translateX(-8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+@keyframes slide-out-left {
+  from {
+    opacity: 1;
+    transform: translateX(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateX(-8px);
+  }
+}
+@keyframes slide-in-right {
+  from {
+    opacity: 0;
+    transform: translateX(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+@keyframes slide-out-right {
+  from {
+    opacity: 1;
+    transform: translateX(0);
+  }
+  to {
+    opacity: 0;
+    transform: translateX(8px);
+  }
+}
 
 @keyframes indeterminate {
   0% {
@@ -275,7 +386,8 @@ html, body {
 }
 
 @keyframes gradient-shift {
-  0%, 100% {
+  0%,
+  100% {
     background-position: 0% 50%;
   }
   50% {
@@ -284,18 +396,32 @@ html, body {
 }
 
 @keyframes marquee-x {
-  from { transform: translateX(0); }
-  to { transform: translateX(-50%); }
+  from {
+    transform: translateX(0);
+  }
+  to {
+    transform: translateX(-50%);
+  }
 }
 
 @keyframes marquee-y {
-  from { transform: translateY(0); }
-  to { transform: translateY(-50%); }
+  from {
+    transform: translateY(0);
+  }
+  to {
+    transform: translateY(-50%);
+  }
 }
 
 @keyframes blink-caret {
-  0%, 49% { opacity: 1; }
-  50%, 100% { opacity: 0; }
+  0%,
+  49% {
+    opacity: 1;
+  }
+  50%,
+  100% {
+    opacity: 0;
+  }
 }
 
 /* Lib-wide reduced-motion safety net — honors `prefers-reduced-motion: reduce` for EVERY

package/dist/index.d.ts

@@ -1,5 +1,10 @@
-export * as utils from './foundation/utils';
-export * as hooks from './foundation/hooks';
+/** Convenience exports; optional vendor adapters remain available through dedicated subpaths. */
+export * as styles from './foundation/styles';
+export * as dom from './foundation/dom';
+export * as optionals from './foundation/optionals';
+export * as state from './foundation/state';
+export * as numbers from './foundation/numbers';
+export * as json from './foundation/json';
 export * as icons from './foundation/icons';
 export * as primitives from './foundation/primitives';
 export * as themes from './foundation/themes';