@mmstack/worker 21.0.0

package/fesm2022/mmstack-worker-host.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmstack-worker-host.mjs","sources":["../../../../packages/worker/host/src/lib/microtask-driver.ts","../../../../packages/worker/host/src/lib/create-worker-host.ts","../../../../packages/worker/host/src/lib/worker-store-context.ts","../../../../packages/worker/host/src/index.ts","../../../../packages/worker/host/src/mmstack-worker-host.ts"],"sourcesContent":["import { createWatch } from '@angular/core/primitives/signals';\nimport type { OpLogDriver } from '@mmstack/primitives';\n\n/**\n * An injector-free {@link OpLogDriver} for `@mmstack/primitives` `opLog`. Schedules the emission\n * reaction on the microtask queue via `createWatch` (Angular's renderer-independent watch\n * primitive) instead of an `effect`, so an opLog can run where there is no Angular injector: the\n * worker side of the worker-graph, whose store has no application tick driving it.\n *\n * This lives in `@mmstack/worker/host` rather than in primitives on purpose. `createWatch` is a\n * lower-tier signals-primitives export; keeping it out of `@mmstack/primitives` lets that package\n * back-port to older Angular majors that may not export it. The worker package tracks a newer\n * Angular where `createWatch` is available.\n *\n * Batching is per-microtask rather than per-app-tick; the worker protocol orders by\n * `(origin, version)`, never tick alignment, so that is safe.\n */\nexport function microtaskOpLogDriver(): OpLogDriver {\n  return (run) => {\n    let scheduled = false;\n    // run reads the source (tracking) and flushes; it never writes signals, so allowSignalWrites=false\n    const watch = createWatch(\n      () => run(),\n      (w) => {\n        if (scheduled) return;\n        scheduled = true;\n        queueMicrotask(() => {\n          scheduled = false;\n          w.run(); // no-op if the watch is not dirty\n        });\n      },\n      false,\n    );\n    watch.notify(); // bootstrap: schedule the first run to establish the source dependency\n    return { destroy: () => watch.destroy() };\n  };\n}\n","import {\n  isDevMode,\n  untracked,\n  type ResourceStatus,\n  type Signal,\n  type WritableSignal,\n} from '@angular/core';\nimport { createWatch } from '@angular/core/primitives/signals';\nimport { applyOps, opLog, type OpLog } from '@mmstack/primitives';\nimport {\n  generateId,\n  PROTO_VERSION,\n  serializeError,\n  type HasSchema,\n  type SignalValueOf,\n  type WorkerEnvelope,\n  type WorkerPortLike,\n  type WorkerSchema,\n} from '@mmstack/worker/protocol';\nimport { microtaskOpLogDriver } from './microtask-driver';\n\n/** A named unit of compute a worker exposes (rung 1). `ctx.signal` aborts when the caller cancels. */\nexport type WorkerTaskHandler<I = any, O = any> = (\n  input: I,\n  ctx: { readonly signal: AbortSignal },\n) => O | Promise<O>;\n\n/** A published derivation: a plain signal, or a status-bearing one (a `latest()`) for pending propagation. */\nexport type PublishedSource<T> =\n  | Signal<T>\n  | (Signal<T | undefined> & { readonly status: Signal<ResourceStatus> });\n\nexport type CreateWorkerHostOptions = {\n  /**\n   * Store subtrees this worker OWNS — the single writer. Keys are the wire identifiers. Typed as\n   * the plain writable-signal interface (any copy-on-write `WritableSignal<object>` qualifies, per\n   * `opLog`); a concrete `store<T>` satisfies it without the mapped-store variance friction that\n   * `WritableSignalStore<any>` would introduce.\n   */\n  readonly stores?: Record<string, WritableSignal<any>>;\n  /**\n   * Read-only DERIVED subtrees the worker PUBLISHES (rung 3) — a `Signal<T>` (e.g. a `computed` or\n   * `projection`) or a status-bearing async derivation (a `latest()`). Main-thread `workerStore`s\n   * mirror them like owned stores but cannot write; a status-bearing entry also propagates its\n   * pending/error to the replica, so an in-flight worker computation shows as pending on the main\n   * thread.\n   */\n  readonly published?: Record<string, PublishedSource<any>>;\n  /** Named tasks callable from the main thread (rung 1). */\n  readonly tasks?: Record<string, WorkerTaskHandler>;\n  /**\n   * Transport to serve on. Defaults to the worker global scope (`self`) when running in a real\n   * Worker, so `my.worker.ts` never touches `self`. Pass an explicit port for tests (a\n   * `MessageChannel` port) or a SharedWorker fan-in.\n   */\n  readonly port?: WorkerPortLike;\n};\n\nexport type WorkerHost<M extends WorkerSchema = WorkerSchema> = HasSchema<M> & {\n  /** This host's transport identity — the `origin` of every store batch it emits. */\n  readonly hostId: string;\n  /** Serve an additional transport (multi-client / tests). Returns a disconnect handle. */\n  connect(port: WorkerPortLike): () => void;\n  /**\n   * Synchronously emit any pending owned-store changes to subscribers NOW, instead of waiting for\n   * the microtask driver. Makes the mirror deterministic (tests call it before asserting) and is\n   * the honest settle point before applying a routed write (phase 4). No-op when nothing is pending.\n   */\n  flush(): void;\n  /** Stop every owned opLog and drop all connections. */\n  dispose(): void;\n};\n\ntype Connection = {\n  readonly port: WorkerPortLike;\n  clientId: string | null;\n  readonly stores: Set<string>;\n  /** In-flight named-task runs for THIS client, keyed by its runId (client runIds aren't global). */\n  readonly taskRuns: Map<number, AbortController>;\n};\n\ntype Subtree = {\n  /** Untracked read of the current root value (for snapshots). */\n  readonly read: () => unknown;\n  readonly log: OpLog<any>;\n  /** The version of the last batch emitted — a fresh subscriber's snapshot carries it. */\n  version: number;\n  /** The writable store for an OWNED subtree; `null` for a PUBLISHED (read-only) one. */\n  readonly writable: WritableSignal<any> | null;\n};\n\n/** Maps an Angular ResourceStatus to the wire status; only the states the protocol carries. */\nfunction toRemoteStatus(\n  s: ResourceStatus,\n): 'idle' | 'loading' | 'reloading' | 'resolved' | 'error' {\n  return s === 'idle' || s === 'loading' || s === 'reloading' || s === 'error'\n    ? s\n    : 'resolved';\n}\n\n/**\n * Dev-only guard: a store value that is not structured-clonable (a function, a class instance, an\n * `opaque()` value) throws a bare `DataCloneError` from `postMessage` with no context. Catch it\n * before it hits the wire and name the store, so the fix is obvious. Stripped in production.\n */\nfunction devAssertCloneable(value: unknown, what: string): void {\n  if (!isDevMode()) return;\n  try {\n    structuredClone(value);\n  } catch (err) {\n    throw new Error(\n      `[@mmstack/worker] ${what} holds a value that cannot be sent across the worker boundary. ` +\n        `Synced state must be structured-clonable: functions, class instances, and opaque() values ` +\n        `do not serialize. Keep it to plain JSON-like data.`,\n      { cause: err },\n    );\n  }\n}\n\nfunction isWorkerGlobal(g: unknown): g is WorkerPortLike {\n  const scope = (globalThis as { WorkerGlobalScope?: unknown })\n    .WorkerGlobalScope;\n  return (\n    typeof scope === 'function' &&\n    g instanceof (scope as new () => unknown) &&\n    typeof (g as { postMessage?: unknown }).postMessage === 'function'\n  );\n}\n\n/**\n * The worker-side runtime: owns store subtrees, hosts tasks, and mirrors owned state to every\n * connected client as op batches. Plain functions + signals — NO Angular DI (there is none in a\n * worker); each owned store is observed by a real {@link opLog} driven off the microtask queue.\n *\n * ```ts\n * // my.worker.ts\n * const todos = store<Todo[]>([], workerStoreContext());\n * createWorkerHost({ stores: { todos } });   // serves `self` by default\n * ```\n */\nexport function createWorkerHost<\n  S extends Record<string, WritableSignal<any>> = Record<string, never>,\n  P extends Record<string, PublishedSource<any>> = Record<string, never>,\n  T extends Record<string, WorkerTaskHandler> = Record<string, never>,\n>(options: {\n  readonly stores?: S;\n  readonly published?: P;\n  readonly tasks?: T;\n  readonly port?: WorkerPortLike;\n}): WorkerHost<{\n  readonly stores: { [K in keyof S]: SignalValueOf<S[K]> };\n  readonly published: { [K in keyof P]: SignalValueOf<P[K]> };\n  readonly tasks: T;\n}> {\n  const hostId = generateId();\n  // the S/P/T generics drive the RETURN type only; the body works over loose records\n  const sources = (options.stores ?? {}) as Record<string, WritableSignal<any>>;\n  const publishedSources = (options.published ?? {}) as Record<\n    string,\n    PublishedSource<any>\n  >;\n  const tasks = (options.tasks ?? {}) as Record<string, WorkerTaskHandler>;\n  const taskNames = Object.keys(tasks);\n  const storeKeys = Object.keys(sources);\n  const publishedKeys = Object.keys(publishedSources);\n\n  const subtrees = new Map<string, Subtree>();\n  const connections = new Set<Connection>();\n  // current wire status of each status-bearing published entry, read at subscribe time so a late\n  // subscriber sees an in-flight computation as pending instead of waiting for the next transition\n  const publishedStatus = new Map<\n    string,\n    () => 'idle' | 'loading' | 'reloading' | 'resolved' | 'error'\n  >();\n  const statusWatches: { destroy(): void }[] = [];\n\n  const fanout = (store: string, message: WorkerEnvelope) => {\n    for (const conn of Array.from(connections))\n      if (conn.stores.has(store)) conn.port.postMessage(message);\n  };\n\n  // observe a signal's value → snapshot/ops. Owned stores also route writes; published are read-only.\n  // Applied remote writes ride this same emission, echo-free (the owner is the single sequencer).\n  const observe = (\n    key: string,\n    src: Signal<unknown>,\n    writable: WritableSignal<any> | null,\n  ): void => {\n    const entry: Subtree = {\n      read: () => untracked(src),\n      log: null as unknown as OpLog<any>,\n      version: 0,\n      writable,\n    };\n    (entry as { log: OpLog<any> }).log = opLog(\n      // a published (read-only) signal is only ever READ by the log — apply() is never called on it\n      src as unknown as WritableSignal<any>,\n      { driver: microtaskOpLogDriver(), origin: hostId },\n    );\n    entry.log.subscribe((batch) => {\n      entry.version = batch.version;\n      devAssertCloneable(batch, `store '${key}' update`);\n      fanout(key, { type: 'store:ops', store: key, batch });\n    });\n    subtrees.set(key, entry);\n  };\n\n  for (const key of storeKeys) observe(key, sources[key], sources[key]);\n\n  for (const key of publishedKeys) {\n    const src = publishedSources[key];\n    observe(key, src as Signal<unknown>, null);\n    // rung 3: a status-bearing derivation (a latest()) propagates its pending/error to replicas\n    const statusSig = (src as { status?: Signal<ResourceStatus> }).status;\n    if (statusSig) {\n      publishedStatus.set(key, () => toRemoteStatus(untracked(statusSig)));\n      let scheduled = false;\n      let last: ResourceStatus | null = null;\n      const w = createWatch(\n        () => {\n          const s = statusSig();\n          if (s === last) return;\n          last = s;\n          fanout(key, {\n            type: 'store:status',\n            store: key,\n            status: toRemoteStatus(s),\n          });\n        },\n        (watch) => {\n          if (scheduled) return;\n          scheduled = true;\n          queueMicrotask(() => {\n            scheduled = false;\n            watch.run();\n          });\n        },\n        false,\n      );\n      w.notify();\n      statusWatches.push(w);\n    }\n  }\n\n  const runTask = (\n    conn: Connection,\n    runId: number,\n    handler: WorkerTaskHandler,\n    input: unknown,\n  ): void => {\n    const ac = new AbortController();\n    conn.taskRuns.set(runId, ac);\n    Promise.resolve()\n      .then(() => handler(input, { signal: ac.signal }))\n      .then(\n        (value) => {\n          if (ac.signal.aborted)\n            conn.port.postMessage({ type: 'task:aborted', runId });\n          else conn.port.postMessage({ type: 'task:ok', runId, value });\n        },\n        (err) => {\n          if (ac.signal.aborted)\n            conn.port.postMessage({ type: 'task:aborted', runId });\n          else\n            conn.port.postMessage({\n              type: 'task:error',\n              runId,\n              error: serializeError(err),\n            });\n        },\n      )\n      .finally(() => {\n        if (conn.taskRuns.get(runId) === ac) conn.taskRuns.delete(runId);\n      });\n  };\n\n  const handle = (conn: Connection, msg: WorkerEnvelope): void => {\n    switch (msg.type) {\n      case 'hello': {\n        conn.clientId = msg.clientId;\n        conn.port.postMessage({\n          type: 'ready',\n          proto: PROTO_VERSION,\n          hostId,\n          stores: storeKeys,\n          published: publishedKeys,\n          tasks: taskNames,\n        });\n        return;\n      }\n      case 'store:subscribe': {\n        const sub = subtrees.get(msg.store);\n        if (!sub) return; // unknown store — silently ignore (a client typo, not fatal)\n        // synchronous: read snapshot + version and register the client in one turn — no batch can\n        // interleave in a single-threaded worker, so every later op carries version > this one\n        conn.stores.add(msg.store);\n        const snapshot = sub.read();\n        devAssertCloneable(snapshot, `store '${msg.store}' snapshot`);\n        conn.port.postMessage({\n          type: 'store:snapshot',\n          store: msg.store,\n          version: sub.version,\n          value: snapshot,\n        });\n        // a status-bearing published entry also reports its CURRENT status, so a subscriber\n        // arriving mid-computation shows pending now, not on the next transition\n        const currentStatus = publishedStatus.get(msg.store);\n        if (currentStatus)\n          conn.port.postMessage({\n            type: 'store:status',\n            store: msg.store,\n            status: currentStatus(),\n          });\n        return;\n      }\n      case 'store:unsubscribe': {\n        conn.stores.delete(msg.store);\n        return;\n      }\n      case 'task:run': {\n        const handler = tasks[msg.task];\n        if (!handler) {\n          conn.port.postMessage({\n            type: 'task:error',\n            runId: msg.runId,\n            error: serializeError(\n              new Error(`[@mmstack/worker] unknown task: ${msg.task}`),\n            ),\n          });\n          return;\n        }\n        runTask(conn, msg.runId, handler, msg.input);\n        return;\n      }\n      case 'task:abort': {\n        conn.taskRuns.get(msg.runId)?.abort();\n        conn.taskRuns.delete(msg.runId);\n        return;\n      }\n      case 'store:write': {\n        const sub = subtrees.get(msg.store);\n        if (!sub || !sub.writable) {\n          conn.port.postMessage({\n            type: 'store:write:error',\n            store: msg.store,\n            writeId: msg.writeId,\n            error: serializeError(\n              new Error(\n                sub\n                  ? `[@mmstack/worker] store is read-only (published): ${msg.store}`\n                  : `[@mmstack/worker] unknown store: ${msg.store}`,\n              ),\n            ),\n          });\n          return;\n        }\n        try {\n          // the owner is the single sequencer: apply the routed ops through the store root, then\n          // FLUSH so its opLog emits ONE authoritative owner-origin batch (fanned to every client,\n          // the writer included — the echo that IS the write's confirmation). No baseline-advance\n          // trick: this is a genuine owner write, indistinguishable from the worker writing itself.\n          sub.writable.set(applyOps(sub.read(), msg.ops));\n          sub.log.flush();\n          conn.port.postMessage({\n            type: 'store:write:ack',\n            store: msg.store,\n            writeId: msg.writeId,\n            version: sub.version,\n          });\n        } catch (err) {\n          conn.port.postMessage({\n            type: 'store:write:error',\n            store: msg.store,\n            writeId: msg.writeId,\n            error: serializeError(err),\n          });\n        }\n        return;\n      }\n    }\n  };\n\n  const connect = (port: WorkerPortLike): (() => void) => {\n    const conn: Connection = {\n      port,\n      clientId: null,\n      stores: new Set(),\n      taskRuns: new Map(),\n    };\n    connections.add(conn);\n    // assigning onmessage starts a MessagePort; a Worker/self delivers the same way\n    port.onmessage = (ev) => handle(conn, ev.data as WorkerEnvelope);\n    return () => {\n      connections.delete(conn);\n      port.onmessage = null; // a disconnected client must not keep invoking tasks/writes\n      for (const ac of conn.taskRuns.values()) ac.abort();\n      conn.taskRuns.clear();\n    };\n  };\n\n  const defaultPort: WorkerPortLike | undefined =\n    options.port ??\n    (isWorkerGlobal(globalThis)\n      ? (globalThis as unknown as WorkerPortLike)\n      : undefined);\n  if (defaultPort) connect(defaultPort);\n\n  return {\n    hostId,\n    connect,\n    flush() {\n      for (const { log } of subtrees.values()) log.flush();\n    },\n    dispose() {\n      for (const { log } of subtrees.values()) log.destroy();\n      for (const w of statusWatches) w.destroy();\n      connections.clear();\n    },\n  };\n}\n","import { createStoreContext, type toStoreOptions } from '@mmstack/primitives';\n\n// Memoized at THIS module's scope. `@mmstack/worker/host` only ever loads inside a worker, so a\n// module-scope singleton here is a per-thread singleton — the worker equivalent of an app's root\n// injector (providedIn: 'root'). All stores in the worker share it; it is the graph's single\n// proxy-identity + GC-coordination point.\nlet context: toStoreOptions | undefined;\n\n/**\n * The one shared store context for this worker — pass it to every `store`/`toStore` you create in\n * the worker so they share proxy identity and cleanup, exactly as `providedIn: 'root'` shares one\n * cache across an app's stores.\n *\n * ```ts\n * // my.worker.ts\n * const todos = store<Todo[]>([], workerStoreContext());\n * const filter = store({ q: '' }, workerStoreContext()); // same context\n * ```\n */\nexport function workerStoreContext(): toStoreOptions {\n  return (context ??= createStoreContext());\n}\n","// shared wire types, re-exported so worker code imports only from '@mmstack/worker/host'\nexport * from '@mmstack/worker/protocol';\n\nexport {\n  createWorkerHost,\n  type CreateWorkerHostOptions,\n  type WorkerHost,\n  type WorkerTaskHandler,\n} from './lib/create-worker-host';\nexport { microtaskOpLogDriver } from './lib/microtask-driver';\nexport { workerStoreContext } from './lib/worker-store-context';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/fesm2022/mmstack-worker-protocol.mjs

@@ -0,0 +1,78 @@
+/** Wire-protocol version, negotiated in the hello/ready handshake. Bump on breaking envelope change. */
+const PROTO_VERSION = 1;
+
+function stringify(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Renders any thrown value (Error or otherwise) into a {@link SerializedError}, chaining `cause`. */
+function serializeError(err) {
+    if (err instanceof Error) {
+        return {
+            name: err.name,
+            message: err.message,
+            stack: err.stack,
+            cause: err.cause !== undefined ? serializeError(err.cause) : undefined,
+        };
+    }
+    return { name: 'Error', message: stringify(err) };
+}
+/** Rebuilds a real `Error` (name/message/stack/cause chain preserved) from a {@link SerializedError}. */
+function deserializeError(e) {
+    const err = new Error(e.message);
+    err.name = e.name;
+    if (e.stack !== undefined)
+        err.stack = e.stack;
+    if (e.cause !== undefined)
+        err.cause = deserializeError(e.cause);
+    return err;
+}
+
+/** A short unique id for host/client identity on a shared transport. */
+function generateId() {
+    if (globalThis.crypto?.randomUUID)
+        return globalThis.crypto.randomUUID();
+    return Math.random().toString(36).slice(2);
+}
+
+/** Closes a port by whichever teardown method it exposes. */
+function closePort(port) {
+    port.terminate?.();
+    port.close?.();
+}
+// values whose reachable Transferables should be MOVED (detached at the sender) rather than cloned
+const TRANSFERABLES = new WeakMap();
+/**
+ * Marks `value` so that, when it is sent over a {@link WorkerPortLike}, the listed `Transferable`s
+ * (e.g. an `ArrayBuffer`) are moved rather than structure-cloned — zero-copy, but detached at the
+ * sender. Comlink-idiom. v1 honors this on task input/output only; store traffic always clones (a
+ * moved buffer inside a replicated tree would detach the owner's copy).
+ *
+ * ```ts
+ * const buf = new Float64Array(1e6);
+ * workerResource(() => transfer({ buf }, [buf.buffer]), { worker, task: 'process' });
+ * ```
+ */
+function transfer(value, transferables) {
+    TRANSFERABLES.set(value, transferables);
+    return value;
+}
+/** @internal Reads back the Transferables registered on a value via {@link transfer}, if any. */
+function takeTransferables(value) {
+    if (value !== null && typeof value === 'object')
+        return TRANSFERABLES.get(value);
+    return undefined;
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { PROTO_VERSION, closePort, deserializeError, generateId, serializeError, takeTransferables, transfer };
+//# sourceMappingURL=mmstack-worker-protocol.mjs.map

package/fesm2022/mmstack-worker-protocol.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mmstack-worker-protocol.mjs","sources":["../../../../packages/worker/protocol/src/lib/envelope.ts","../../../../packages/worker/protocol/src/lib/error.ts","../../../../packages/worker/protocol/src/lib/id.ts","../../../../packages/worker/protocol/src/lib/port.ts","../../../../packages/worker/protocol/src/mmstack-worker-protocol.ts"],"sourcesContent":["import type { OpBatch, StoreOp } from '@mmstack/primitives';\nimport type { SerializedError } from './error';\n\n/** Wire-protocol version, negotiated in the hello/ready handshake. Bump on breaking envelope change. */\nexport const PROTO_VERSION = 1;\nexport type ProtoVersion = typeof PROTO_VERSION;\n\n/** The status a remote (worker-owned) computation reports across the boundary — the rung-3 seam. */\nexport type RemoteStatus =\n  | 'idle'\n  | 'loading'\n  | 'reloading'\n  | 'resolved'\n  | 'error';\n\n/**\n * Every message exchanged over a {@link WorkerPortLike}. One discriminated union shared by the\n * main-thread client and the worker host (and, later, `@mmstack/mesh`), so the two sides can never\n * drift. Grouped: lifecycle · tasks (rung 1) · stores (rung 2) · remote status (rung 3).\n */\nexport type WorkerEnvelope =\n  // ── lifecycle ────────────────────────────────────────────────────────────\n  | { type: 'hello'; proto: ProtoVersion; clientId: string }\n  | {\n      type: 'ready';\n      proto: ProtoVersion;\n      hostId: string;\n      stores: readonly string[];\n      published: readonly string[];\n      tasks: readonly string[];\n    }\n  | { type: 'fatal'; error: SerializedError }\n  // ── rung 1: tasks ────────────────────────────────────────────────────────\n  | { type: 'task:run'; runId: number; task: string; input: unknown }\n  | { type: 'task:abort'; runId: number }\n  | { type: 'task:ok'; runId: number; value: unknown }\n  | { type: 'task:error'; runId: number; error: SerializedError }\n  // terminal ack for an aborted run — a non-cooperative handler settles eventually, and this\n  // (rather than task:ok/task:error) is what its late settlement reports back as\n  | { type: 'task:aborted'; runId: number }\n  // ── rung 2: stores ───────────────────────────────────────────────────────\n  | { type: 'store:subscribe'; store: string; clientId: string }\n  | { type: 'store:snapshot'; store: string; version: number; value: unknown }\n  | { type: 'store:ops'; store: string; batch: OpBatch }\n  | {\n      type: 'store:write';\n      store: string;\n      writeId: number;\n      clientId: string;\n      ops: readonly StoreOp[];\n    }\n  | { type: 'store:write:ack'; store: string; writeId: number; version: number }\n  | { type: 'store:write:error'; store: string; writeId: number; error: SerializedError }\n  | { type: 'store:unsubscribe'; store: string; clientId: string }\n  // ── rung 3: remote status ────────────────────────────────────────────────\n  | { type: 'store:status'; store: string; status: RemoteStatus; error?: SerializedError };\n\n/** Narrows a raw message to a specific envelope variant by its `type`. */\nexport type EnvelopeOf<K extends WorkerEnvelope['type']> = Extract<\n  WorkerEnvelope,\n  { type: K }\n>;\n","/**\n * A structured-clone-safe rendering of an `Error` for cross-thread propagation. A worker throw\n * can't cross `postMessage` as an `Error` (methods/prototype are lost), so tasks and store writes\n * serialize failures into this shape and the receiving side rebuilds a real `Error`.\n */\nexport type SerializedError = {\n  name: string;\n  message: string;\n  stack?: string;\n  cause?: SerializedError;\n};\n\nfunction stringify(value: unknown): string {\n  if (typeof value === 'string') return value;\n  try {\n    return JSON.stringify(value) ?? String(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/** Renders any thrown value (Error or otherwise) into a {@link SerializedError}, chaining `cause`. */\nexport function serializeError(err: unknown): SerializedError {\n  if (err instanceof Error) {\n    return {\n      name: err.name,\n      message: err.message,\n      stack: err.stack,\n      cause: err.cause !== undefined ? serializeError(err.cause) : undefined,\n    };\n  }\n  return { name: 'Error', message: stringify(err) };\n}\n\n/** Rebuilds a real `Error` (name/message/stack/cause chain preserved) from a {@link SerializedError}. */\nexport function deserializeError(e: SerializedError): Error {\n  const err = new Error(e.message);\n  err.name = e.name;\n  if (e.stack !== undefined) err.stack = e.stack;\n  if (e.cause !== undefined) err.cause = deserializeError(e.cause);\n  return err;\n}\n","/** A short unique id for host/client identity on a shared transport. */\nexport function generateId(): string {\n  if (globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();\n  return Math.random().toString(36).slice(2);\n}\n","/**\n * The minimal structural transport the worker protocol rides on — the intersection of a `Worker`,\n * a `MessagePort`, and a `BroadcastChannel`. Modeled on `@mmstack/resource`'s `MutationSyncChannel`:\n * anything with `postMessage` + assignable `onmessage` qualifies, so a `MessageChannel` port-pair\n * works in tests with zero adapters and a future `@mmstack/mesh` can slot a WS/RTC channel behind\n * the same type.\n */\nexport type WorkerPortLike = {\n  postMessage(message: unknown, transfer?: Transferable[]): void;\n  // `ev` is intentionally `any`: a real `Worker`/`MessagePort` types this as `(ev: MessageEvent)`,\n  // and under `strictFunctionTypes` only an `any`-typed event param keeps those assignable to this\n  // shape cast-free (a `{ data }` param fails the contravariance check). Read `ev.data` and narrow\n  // it to a `WorkerEnvelope` at the handler.\n  onmessage: ((ev: any) => void) | null;\n  /** `Worker` has `terminate()`, `MessagePort`/`BroadcastChannel` have `close()` — either, both optional. */\n  terminate?(): void;\n  close?(): void;\n};\n\n/** Closes a port by whichever teardown method it exposes. */\nexport function closePort(port: WorkerPortLike): void {\n  port.terminate?.();\n  port.close?.();\n}\n\n// values whose reachable Transferables should be MOVED (detached at the sender) rather than cloned\nconst TRANSFERABLES = new WeakMap<object, Transferable[]>();\n\n/**\n * Marks `value` so that, when it is sent over a {@link WorkerPortLike}, the listed `Transferable`s\n * (e.g. an `ArrayBuffer`) are moved rather than structure-cloned — zero-copy, but detached at the\n * sender. Comlink-idiom. v1 honors this on task input/output only; store traffic always clones (a\n * moved buffer inside a replicated tree would detach the owner's copy).\n *\n * ```ts\n * const buf = new Float64Array(1e6);\n * workerResource(() => transfer({ buf }, [buf.buffer]), { worker, task: 'process' });\n * ```\n */\nexport function transfer<T extends object>(value: T, transferables: Transferable[]): T {\n  TRANSFERABLES.set(value, transferables);\n  return value;\n}\n\n/** @internal Reads back the Transferables registered on a value via {@link transfer}, if any. */\nexport function takeTransferables(value: unknown): Transferable[] | undefined {\n  if (value !== null && typeof value === 'object')\n    return TRANSFERABLES.get(value as object);\n  return undefined;\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"AAGA;AACO,MAAM,aAAa,GAAG;;ACQ7B,SAAS,SAAS,CAAC,KAAc,EAAA;IAC/B,IAAI,OAAO,KAAK,KAAK,QAAQ;AAAE,QAAA,OAAO,KAAK;AAC3C,IAAA,IAAI;QACF,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC;IAC/C;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB;AACF;AAEA;AACM,SAAU,cAAc,CAAC,GAAY,EAAA;AACzC,IAAA,IAAI,GAAG,YAAY,KAAK,EAAE;QACxB,OAAO;YACL,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,KAAK,EAAE,GAAG,CAAC,KAAK;AAChB,YAAA,KAAK,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,GAAG,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,SAAS;SACvE;IACH;AACA,IAAA,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE;AACnD;AAEA;AACM,SAAU,gBAAgB,CAAC,CAAkB,EAAA;IACjD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC;AAChC,IAAA,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI;AACjB,IAAA,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;AAAE,QAAA,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK;AAC9C,IAAA,IAAI,CAAC,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,gBAAgB,CAAC,CAAC,CAAC,KAAK,CAAC;AAChE,IAAA,OAAO,GAAG;AACZ;;ACzCA;SACgB,UAAU,GAAA;AACxB,IAAA,IAAI,UAAU,CAAC,MAAM,EAAE,UAAU;AAAE,QAAA,OAAO,UAAU,CAAC,MAAM,CAAC,UAAU,EAAE;AACxE,IAAA,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5C;;ACeA;AACM,SAAU,SAAS,CAAC,IAAoB,EAAA;AAC5C,IAAA,IAAI,CAAC,SAAS,IAAI;AAClB,IAAA,IAAI,CAAC,KAAK,IAAI;AAChB;AAEA;AACA,MAAM,aAAa,GAAG,IAAI,OAAO,EAA0B;AAE3D;;;;;;;;;;AAUG;AACG,SAAU,QAAQ,CAAmB,KAAQ,EAAE,aAA6B,EAAA;AAChF,IAAA,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC;AACvC,IAAA,OAAO,KAAK;AACd;AAEA;AACM,SAAU,iBAAiB,CAAC,KAAc,EAAA;AAC9C,IAAA,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;AAC7C,QAAA,OAAO,aAAa,CAAC,GAAG,CAAC,KAAe,CAAC;AAC3C,IAAA,OAAO,SAAS;AAClB;;ACjDA;;AAEG;;;;"}

package/fesm2022/mmstack-worker.mjs

@@ -0,0 +1,494 @@
+import { generateId, deserializeError, closePort, takeTransferables } from '@mmstack/worker/protocol';
+export * from '@mmstack/worker/protocol';
+import { inject, Injector, runInInjectionContext, PLATFORM_ID, signal, DestroyRef, computed, effect, untracked } from '@angular/core';
+import { injectTransitionScope, toStore, applyOps, diffOps } from '@mmstack/primitives';
+
+/** Thrown into a task/write promise when it is aborted. `name` is `'AbortError'` (DOM convention). */
+class WorkerAbortError extends Error {
+    constructor(message = 'The worker task was aborted') {
+        super(message);
+        this.name = 'AbortError';
+    }
+}
+/** Thrown into pending tasks/writes when the worker crashes. `name` is `'WorkerCrashedError'`. */
+class WorkerCrashedError extends Error {
+    constructor(message = 'The worker crashed') {
+        super(message);
+        this.name = 'WorkerCrashedError';
+    }
+}
+/**
+ * Connects the main thread to a worker over a {@link WorkerPortLike} the caller provides via `spawn`
+ * — typically `() => new Worker(new URL('./my.worker', import.meta.url), { type: 'module' })` (the
+ * URL literal must live in APP code so the bundler emits the worker chunk). Performs the hello/ready
+ * handshake, exposes `connected`/`manifest`, routes named-task runs, and (via internal seams)
+ * carries the store-replication traffic for {@link workerStore}. On crash it respawns with backoff
+ * when `restart: 'auto'`.
+ */
+function connectWorker(spawn, opt) {
+    const injector = opt?.injector ?? inject(Injector);
+    return runInInjectionContext(injector, () => build$2(spawn, opt));
+}
+function build$2(spawn, opt) {
+    const isServer = inject(PLATFORM_ID) === 'server';
+    const clientId = generateId();
+    const connected = signal(false, ...(ngDevMode ? [{ debugName: "connected" }] : /* istanbul ignore next */ []));
+    const manifest = signal(null, ...(ngDevMode ? [{ debugName: "manifest" }] : /* istanbul ignore next */ []));
+    const taskPending = new Map();
+    const storeHandlers = new Set();
+    const readyHooks = new Set();
+    const disconnectHooks = new Set();
+    const restart = opt?.restart ?? 'auto';
+    const restartDelay = opt?.restartDelay ?? ((n) => Math.min(30_000, 1000 * 2 ** n));
+    let attempt = 0;
+    let runIdSeq = 0;
+    let destroyed = false;
+    let crashed = false; // between a crash and the next successful handshake
+    let port = null;
+    const send = (msg, transfer) => {
+        if (port)
+            port.postMessage(msg, transfer); // no-op on the server / between crash and respawn
+    };
+    const onMessage = (msg) => {
+        switch (msg.type) {
+            case 'ready':
+                attempt = 0; // a successful handshake resets the backoff
+                crashed = false;
+                manifest.set({
+                    hostId: msg.hostId,
+                    stores: msg.stores,
+                    published: msg.published,
+                    tasks: msg.tasks,
+                });
+                connected.set(true);
+                for (const hook of readyHooks)
+                    hook();
+                return;
+            case 'task:ok': {
+                const p = taskPending.get(msg.runId);
+                if (p) {
+                    taskPending.delete(msg.runId);
+                    p.resolve(msg.value);
+                }
+                return;
+            }
+            case 'task:error': {
+                const p = taskPending.get(msg.runId);
+                if (p) {
+                    taskPending.delete(msg.runId);
+                    p.reject(deserializeError(msg.error));
+                }
+                return;
+            }
+            case 'task:aborted':
+                taskPending.delete(msg.runId); // caller already rejected at abort
+                return;
+            default:
+                // store:* traffic → replicas
+                for (const h of storeHandlers)
+                    h(msg);
+        }
+    };
+    const handleCrash = () => {
+        if (destroyed)
+            return;
+        crashed = true;
+        connected.set(false);
+        // in-flight tasks can't survive a crash; store replicas hold their value and re-hydrate on reconnect
+        for (const [, p] of taskPending)
+            p.reject(new WorkerCrashedError());
+        taskPending.clear();
+        for (const fn of disconnectHooks)
+            fn();
+        if (restart === 'manual')
+            return;
+        const delay = restartDelay(attempt++);
+        setTimeout(() => {
+            if (!destroyed)
+                openPort();
+        }, delay);
+    };
+    const openPort = () => {
+        // terminate the previous worker before respawning, so a transient/manual restart never orphans
+        // a live thread (a genuine crash already killed it; terminate() is then a harmless no-op)
+        if (port)
+            closePort(port);
+        port = spawn();
+        port.onmessage = (ev) => onMessage(ev.data);
+        // duck-typed crash detection via property setters (NOT addEventListener — that perturbs a node
+        // MessagePort's onmessage delivery). A real `Worker` has onerror; onmessageerror where present.
+        const evt = port;
+        if ('onerror' in evt)
+            evt.onerror = handleCrash;
+        if ('onmessageerror' in evt)
+            evt.onmessageerror = handleCrash;
+        send({ type: 'hello', proto: 1, clientId });
+    };
+    // no workers on the server — connected stays false, runTask rejects, replicas render their default
+    if (!isServer)
+        openPort();
+    inject(DestroyRef).onDestroy(() => teardown());
+    const teardown = () => {
+        destroyed = true;
+        connected.set(false);
+        for (const [, p] of taskPending)
+            p.reject(new WorkerAbortError('worker connection destroyed'));
+        taskPending.clear();
+        // same contract as a crash: anything pending on the connection (replica writes) settles NOW
+        // rather than dangling — a destroyed port can never deliver the echo that would resolve them
+        for (const fn of disconnectHooks)
+            fn();
+        if (port)
+            closePort(port);
+    };
+    return {
+        connected,
+        manifest,
+        clientId,
+        runTask(task, input, o) {
+            if (isServer)
+                return Promise.reject(new WorkerCrashedError('no worker on the server'));
+            if (destroyed)
+                return Promise.reject(new WorkerAbortError('worker connection destroyed'));
+            // between a crash and the respawned handshake the port is dead — a message posted into it
+            // vanishes and the promise would never settle. Reject honestly; the caller retries/reloads.
+            // (Before the FIRST handshake this is false: a starting worker buffers messages, so we send.)
+            if (crashed)
+                return Promise.reject(new WorkerCrashedError('worker is restarting'));
+            if (o?.signal?.aborted)
+                return Promise.reject(new WorkerAbortError());
+            const runId = ++runIdSeq;
+            return new Promise((resolve, reject) => {
+                taskPending.set(runId, { resolve, reject });
+                send({ type: 'task:run', runId, task, input }, o?.transfer ?? takeTransferables(input));
+                o?.signal?.addEventListener('abort', () => {
+                    if (!taskPending.has(runId))
+                        return;
+                    taskPending.delete(runId);
+                    send({ type: 'task:abort', runId });
+                    reject(new WorkerAbortError());
+                }, { once: true });
+            });
+        },
+        destroy: teardown,
+        _send: send,
+        _subscribe(handler) {
+            storeHandlers.add(handler);
+            return () => storeHandlers.delete(handler);
+        },
+        _onReady(fn) {
+            readyHooks.add(fn);
+            return () => readyHooks.delete(fn);
+        },
+        _onDisconnect(fn) {
+            disconnectHooks.add(fn);
+            return () => disconnectHooks.delete(fn);
+        },
+    };
+}
+
+/** Returned from a paused `params` fn to HOLD (keep the current value/status, run nothing). */
+const PAUSED = Symbol('@mmstack/worker:PAUSED');
+/**
+ * Runs a named task on a connected worker, exposed with the standard resource surface so heavy
+ * compute makes the UI *pending*, not *frozen*. `params` reactively derives the input; latest-wins
+ * (a changed input supersedes and aborts the in-flight run); the result surfaces as
+ * `value`/`status`/`error`, and — with `register` — participates in transition scopes. No-ops on the
+ * server.
+ */
+function workerResource(params, options) {
+    const injector = options.injector ?? inject(Injector);
+    return runInInjectionContext(injector, () => build$1(params, options));
+}
+function build$1(params, options) {
+    const isServer = inject(PLATFORM_ID) === 'server';
+    const keepPrevious = options.keepPrevious ?? true;
+    const userEqual = options.equal;
+    const { worker, task } = options;
+    const runTask = (input, signal) => worker.runTask(task, input, { signal });
+    const value = signal(options.defaultValue, { ...(ngDevMode ? { debugName: "value" } : /* istanbul ignore next */ {}), equal: userEqual
+            ? (a, b) => (a === undefined || b === undefined ? a === b : userEqual(a, b))
+            : undefined });
+    const status = signal('idle', ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
+    const error = signal(undefined, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    const isLoading = computed(() => {
+        const s = status();
+        return s === 'loading' || s === 'reloading';
+    }, ...(ngDevMode ? [{ debugName: "isLoading" }] : /* istanbul ignore next */ []));
+    const hasValue = () => value() !== undefined;
+    let epoch = 0;
+    let inFlight = null;
+    let lastInput;
+    let hasRun = false;
+    const start = (input) => {
+        const myEpoch = ++epoch;
+        inFlight?.abort();
+        const ac = new AbortController();
+        inFlight = ac;
+        lastInput = input;
+        hasRun = true;
+        status.set(keepPrevious && value() !== undefined ? 'reloading' : 'loading');
+        error.set(undefined);
+        runTask(input, ac.signal).then((result) => {
+            if (inFlight === ac)
+                inFlight = null;
+            if (myEpoch !== epoch)
+                return; // superseded — discard
+            value.set(result);
+            status.set('resolved');
+        }, (err) => {
+            if (inFlight === ac)
+                inFlight = null;
+            if (myEpoch !== epoch)
+                return;
+            if (err instanceof WorkerAbortError || err?.name === 'AbortError')
+                return;
+            error.set(err);
+            status.set('error');
+        });
+    };
+    const input = computed(() => params({ paused: PAUSED }), ...(ngDevMode ? [{ debugName: "input" }] : /* istanbul ignore next */ []));
+    const ref = effect(() => {
+        const i = input();
+        if (isServer || i === PAUSED)
+            return; // server: never run · paused: hold
+        if (i === undefined)
+            return; // disabled — keep current value/status
+        // dedup: a resume to the same input (e.g. after a pause) does not re-run
+        if (Object.is(i, lastInput) && hasRun && untracked(status) !== 'error')
+            return;
+        untracked(() => start(i));
+    }, ...(ngDevMode ? [{ debugName: "ref" }] : /* istanbul ignore next */ []));
+    inject(DestroyRef).onDestroy(() => {
+        epoch++;
+        inFlight?.abort();
+    });
+    const self = {
+        value,
+        status,
+        error,
+        isLoading,
+        hasValue,
+        reload: () => {
+            const i = untracked(input);
+            if (isServer || i === PAUSED || i === undefined)
+                return;
+            start(i);
+        },
+        abort: () => {
+            if (!inFlight)
+                return; // nothing in flight (a scope's abortPending must not disturb a settled value)
+            epoch++;
+            inFlight.abort();
+            inFlight = null;
+            status.set('local'); // value kept
+        },
+        destroy: () => {
+            epoch++;
+            inFlight?.abort();
+            ref.destroy();
+        },
+    };
+    if (options.register) {
+        const scope = injectTransitionScope();
+        scope.add(self, { suspends: options.register === 'suspend' });
+        inject(DestroyRef).onDestroy(() => scope.remove(self));
+    }
+    return self;
+}
+
+function workerStore(worker, key, opt) {
+    const injector = opt?.injector ?? inject(Injector);
+    return runInInjectionContext(injector, () => build(worker, key, opt));
+}
+function build(worker, key, opt) {
+    const injector = inject(Injector); // captured for use in write() (called outside injection context)
+    const root = signal(opt?.defaultValue, ...(ngDevMode ? [{ debugName: "root" }] : /* istanbul ignore next */ []));
+    // shape-adaptive: the store reflects `root` even as it goes undefined → object on first snapshot
+    const replica = toStore(root, {
+        injector,
+    });
+    const status = signal('loading', ...(ngDevMode ? [{ debugName: "status" }] : /* istanbul ignore next */ []));
+    const error = signal(undefined, ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    const isLoading = computed(() => {
+        const s = status();
+        return s === 'loading' || s === 'reloading';
+    }, ...(ngDevMode ? [{ debugName: "isLoading" }] : /* istanbul ignore next */ []));
+    let hasSnapshot = false;
+    let resyncing = false; // awaiting a fresh snapshot after a detected gap
+    let lastVersion = 0;
+    let writeSeq = 0;
+    const writePending = new Map();
+    const hasValue = () => hasSnapshot;
+    // resolve any write whose acked authoritative version has now been applied to this replica
+    const settleWrites = () => {
+        for (const [id, p] of writePending) {
+            if (p.version !== null && lastVersion >= p.version) {
+                writePending.delete(id);
+                p.resolve();
+            }
+        }
+    };
+    const onStoreMessage = (msg) => {
+        if (!('store' in msg) || msg.store !== key)
+            return;
+        switch (msg.type) {
+            case 'store:snapshot': {
+                root.set(msg.value);
+                lastVersion = msg.version;
+                hasSnapshot = true;
+                resyncing = false; // a fresh snapshot ends any resync
+                status.set('resolved');
+                error.set(undefined);
+                settleWrites();
+                return;
+            }
+            case 'store:ops': {
+                if (!hasSnapshot || resyncing)
+                    return; // pre-hydration, or dropping until a fresh snapshot
+                if (msg.batch.version <= lastVersion)
+                    return; // stale/duplicate (at-least-once transport)
+                if (msg.batch.version > lastVersion + 1) {
+                    // GAP: a batch was lost — re-hydrate from a fresh snapshot rather than apply out of order
+                    resync();
+                    return;
+                }
+                root.set(applyOps(untracked(root), msg.batch.ops));
+                lastVersion = msg.batch.version;
+                settleWrites();
+                return;
+            }
+            case 'store:write:ack': {
+                const p = writePending.get(msg.writeId);
+                if (!p)
+                    return;
+                if (lastVersion >= msg.version) {
+                    writePending.delete(msg.writeId);
+                    p.resolve(); // the authoritative batch already landed (FIFO: ops precede the ack)
+                }
+                else {
+                    p.version = msg.version; // resolve once a batch reaches this version
+                }
+                return;
+            }
+            case 'store:write:error': {
+                const p = writePending.get(msg.writeId);
+                if (p) {
+                    writePending.delete(msg.writeId);
+                    p.reject(deserializeError(msg.error));
+                }
+                return;
+            }
+            case 'store:status': {
+                // rung 3: a published derivation's remote status → this replica's status, so an in-flight
+                // worker computation shows as pending on the main thread (holding the last value)
+                switch (msg.status) {
+                    case 'error':
+                        error.set(msg.error ? deserializeError(msg.error) : new Error('remote computation error'));
+                        status.set('error');
+                        return;
+                    case 'loading':
+                    case 'reloading':
+                        error.set(undefined);
+                        status.set(hasSnapshot ? 'reloading' : 'loading'); // hold the value while recomputing
+                        return;
+                    case 'resolved':
+                        error.set(undefined);
+                        if (hasSnapshot)
+                            status.set('resolved');
+                        return;
+                    default:
+                        return;
+                }
+            }
+        }
+    };
+    const subscribe = () => {
+        if (hasSnapshot)
+            status.set('reloading'); // holding stale while the fresh snapshot lands
+        worker._send({ type: 'store:subscribe', store: key, clientId: worker.clientId });
+    };
+    // a lost batch left a version gap — hold the stale value and re-subscribe for a fresh snapshot
+    const resync = () => {
+        resyncing = true;
+        status.set('reloading');
+        worker._send({ type: 'store:subscribe', store: key, clientId: worker.clientId });
+    };
+    const unsub = worker._subscribe(onStoreMessage);
+    // subscribe on each `ready` — the first connection and every auto-restart re-hydration; if the
+    // connection is ALREADY up (created post-handshake), `_onReady` won't fire, so subscribe now
+    const offReady = worker._onReady(subscribe);
+    if (untracked(worker.connected))
+        subscribe();
+    // a crash can't be delivered — pending writes reject (the caller holds the value + recipe to retry)
+    const offDisconnect = worker._onDisconnect(() => {
+        for (const [, p] of writePending)
+            p.reject(new WorkerCrashedError());
+        writePending.clear();
+    });
+    const self = {
+        store: replica,
+        value: root.asReadonly(),
+        status,
+        error,
+        isLoading,
+        connected: worker.connected,
+        hasValue,
+        write: (recipe) => {
+            const base = untracked(root);
+            if (base === undefined)
+                return Promise.reject(new Error('[@mmstack/worker] cannot write before the replica has hydrated'));
+            // hydrated but disconnected = the worker crashed (or is restarting) — a write posted now
+            // vanishes into a dead port and its echo can never arrive. Reject; the caller retries.
+            if (!untracked(worker.connected))
+                return Promise.reject(new WorkerCrashedError('worker is not connected'));
+            // fork-diff: a scratch store seeded with the CURRENT value (same ref → copy-on-write keeps
+            // untouched subtrees shared), so diffOps against the base is O(changed paths)
+            const scratch = signal(base, ...(ngDevMode ? [{ debugName: "scratch" }] : /* istanbul ignore next */ []));
+            const scratchStore = toStore(scratch, {
+                injector,
+            });
+            recipe(scratchStore);
+            const ops = diffOps(base, untracked(scratch));
+            if (!ops.length)
+                return Promise.resolve();
+            const writeId = ++writeSeq;
+            return new Promise((resolve, reject) => {
+                writePending.set(writeId, { resolve, reject, version: null });
+                worker._send({
+                    type: 'store:write',
+                    store: key,
+                    writeId,
+                    clientId: worker.clientId,
+                    ops,
+                });
+            });
+        },
+        destroy: () => {
+            unsub();
+            offReady();
+            offDisconnect();
+            // acks can no longer be received — settle any in-flight write instead of dangling it
+            for (const [, p] of writePending)
+                p.reject(new WorkerAbortError('worker store destroyed'));
+            writePending.clear();
+            worker._send({ type: 'store:unsubscribe', store: key, clientId: worker.clientId });
+        },
+    };
+    inject(DestroyRef).onDestroy(() => self.destroy());
+    if (opt?.register) {
+        const scope = injectTransitionScope();
+        scope.add(self, { suspends: opt.register === 'suspend' });
+        inject(DestroyRef).onDestroy(() => scope.remove(self));
+    }
+    return self;
+}
+
+// shared wire types, re-exported so main-thread consumers import only from '@mmstack/worker'
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { PAUSED, WorkerAbortError, WorkerCrashedError, connectWorker, workerResource, workerStore };
+//# sourceMappingURL=mmstack-worker.mjs.map