@lunora/client 1.0.0-alpha.3 → 1.0.0-alpha.5

package/dist/packem_shared/{LunoraClient-UiULzH_1.mjs → LunoraClient-BPQx0T7W.mjs}

@@ -1,17 +1,32 @@
+import { S as SubscriptionRegistry, s as stableStringify } from './subscription-C1Jy7HiF.mjs';
 import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 import { isMutationDelta, applyDelta } from './applyDelta-4jFGTPA3.mjs';
 import { createLocalStore } from './createLocalStore-DSUfoLqY.mjs';
-import { OfflineQueue, nextId, reportPersistenceError } from './OfflineQueue-D5p_QgF_.mjs';
+import { OfflineQueue, nextId, reportPersistenceError } from './OfflineQueue-D-ASeqL7.mjs';
 import { queryCacheKey } from './createInMemoryQueryCache-B1PQ9Twl.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
-import { SubscriptionRegistry } from './SubscriptionRegistry-B-Qx_Gux.mjs';
 
 const RPC_PATH = "/_lunora/rpc";
 const WS_PATH = "/_lunora/ws";
 const bucketQuery = (bucket) => bucket === void 0 || bucket === "" ? "" : `&bucket=${encodeURIComponent(bucket)}`;
+const rollbackOptimistic = (optimisticRollbacks) => {
+  for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
+    optimisticRollbacks[index]?.();
+  }
+};
+const applyRowOpsToView = (rows, ops) => {
+  for (const op of ops) {
+    if (op.op === "delete") {
+      rows.delete(op.key);
+    } else if (op.value !== void 0) {
+      rows.set(op.key, op.value);
+    }
+  }
+};
 const WS_KEEPALIVE_PING = "lunora-ping";
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+const DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
 const QUERY_CACHE_DEBOUNCE_MS = 250;
 const MAX_PENDING_STREAMS = 64;
 const SHARD_TRAFFIC_PATH = "/_lunora/admin/shard-traffic";
@@ -63,22 +78,6 @@ const AUTH_REMOVE_MEMBER_PATH = "/_lunora/admin/auth/organizations/members/remov
 const AUTH_CANCEL_INVITATION_PATH = "/_lunora/admin/auth/organizations/invitations/cancel";
 const DEFAULT_AUTH_BASE_PATH = "/api/auth";
 const GET_SESSION_PATH = "/get-session";
-const compareEntryKeys = ([a], [b]) => {
-  if (a < b) {
-    return -1;
-  }
-  return a > b ? 1 : 0;
-};
-const stableStringify = (value) => {
-  if (value === null || typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
-  }
-  const entries = Object.entries(value).toSorted(compareEntryKeys);
-  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
-};
 const deriveWsUrl = (url) => {
   if (url.startsWith("https://")) {
     return `wss://${url.slice("https://".length)}`;
@@ -152,6 +151,14 @@ const buildSubscriptionError = (message) => {
   const messageText = (typeof message.message === "string" ? message.message : void 0) ?? nestedMessage ?? "subscription error";
   return { message: messageText, ...code === void 0 ? {} : { code } };
 };
+const fanSubscriptionError = (callbacks, error) => {
+  for (const errorCallback of callbacks) {
+    try {
+      errorCallback(error);
+    } catch {
+    }
+  }
+};
 const sharedDecoder = new TextDecoder();
 const decodeServerFrame = (raw) => {
   if (typeof raw === "string") {
@@ -174,6 +181,8 @@ const sendOn = (conn, message) => {
   }
 };
 class LunoraClient {
+  /** Hard cap on concurrently-buffered pokes — a backstop that reclaims buffers abandoned by a mid-poke disconnect (no `pokeEnd`). Far above any real concurrent-in-flight count. */
+  static MAX_POKE_BUFFERS = 256;
   url;
   wsUrl;
   wsToken;
@@ -183,9 +192,30 @@ class LunoraClient {
   WebSocketImpl;
   bookmark;
   reconnectOptions;
+  /** WS connect timeout (ms); `0` disables it. See {@link LunoraClientOptions.connectTimeoutMs}. */
+  connectTimeoutMs;
   /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
   heartbeatIntervalMs;
   offlineQueue;
+  /**
+   * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
+   * set, offline writes are delegated here and the built-in {@link OfflineQueue}
+   * is bypassed, so a db app has exactly one durable write path.
+   */
+  outbox;
+  /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
+  clientId;
+  /**
+   * Highest custom-mutator watermark the server has echoed for this client,
+   * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
+   * `__client_watermark` per shard. `callMutator` bumps it from every
+   * ack; the `@lunora/db` mutator runtime seeds its `clientSeq` generator from
+   * it so a reload (which resets the in-memory counter) never reissues a stale
+   * sequence the server would silently swallow as a replay.
+   */
+  clientWatermarks = /* @__PURE__ */ new Map();
+  /** Monotonic per-client mutation counter backing the server `__client_watermark`. */
+  outboxMutationCounter = 0;
   onPersistenceError;
   persistence;
   /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
@@ -265,6 +295,11 @@ class LunoraClient {
    * calls `.cancel()` or the iterator is garbage-collected.
    */
   streams = /* @__PURE__ */ new Map();
+  /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  shapeSubscriptions = /* @__PURE__ */ new Map();
+  /** In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by `pokeId`. */
+  pokeBuffers = /* @__PURE__ */ new Map();
+  nextShapeId = 0;
   constructor(options) {
     this.url = options.url;
     this.wsUrl = options.wsUrl ?? joinUrl(deriveWsUrl(options.url), WS_PATH);
@@ -276,11 +311,14 @@ class LunoraClient {
     this.bookmark = options.bookmarkStorage ?? createInMemoryBookmarkStorage();
     this.reconnectOptions = options.reconnect;
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     this.defaultConnectionContext = options.connectionContext;
     this.persistence = options.persistence;
     this.queryCache = options.queryCache === false ? void 0 : options.queryCache;
     this.onPersistenceError = options.offlineQueue?.onPersistenceError;
     this.offlineQueue = new OfflineQueue(options.offlineQueue, options.persistence);
+    this.outbox = options.outbox;
+    this.clientId = options.clientId ?? `client-${nextId()}`;
     if (this.persistence) {
       queueMicrotask(() => {
         this.hydratePersistedQueue().catch(() => void 0);
@@ -319,6 +357,67 @@ class LunoraClient {
   getAuthToken() {
     return this.authToken;
   }
+  /**
+   * The current identity fingerprint (the same stamp queued offline writes
+   * carry). Exposed so a durable {@link OutboxSink}'s replay handler — which
+   * owns its own at-least-once replay outside the built-in `OfflineQueue` —
+   * can drop a persisted write whose captured `identity` no longer matches the
+   * signed-in user, the guard the queue path applies in `flushOfflineQueue`.
+   */
+  currentIdentity() {
+    return this.identityFingerprint();
+  }
+  /** This client's stable identifier — the watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientIdentifier() {
+    return this.clientId;
+  }
+  /**
+   * The highest custom-mutator watermark the server has echoed for this client
+   * on the given shard (0 if none yet). The `@lunora/db` mutator runtime seeds
+   * its `clientSeq` generator from this so a reload never reissues a sequence
+   * the server has already applied (which it would swallow as a replay, silently
+   * dropping the write).
+   */
+  confirmedMutationWatermark(shardKey) {
+    return this.clientWatermarks.get(shardKey ?? "") ?? 0;
+  }
+  /**
+   * Push a custom mutator to its authoritative server impl over the watermark
+   * protocol (Phase 4): the request carries `x-lunora-client-id` + a monotonic
+   * `x-lunora-client-seq`, so the DO runs it exactly once and advances this
+   * client's `__client_watermark`.
+   *
+   * Returns the server `result` plus `applied`: `true` when the DO ran this push
+   * as the next-in-order mutation, `false` when it was a replay ack (`clientSeq`
+   * was at or below the stored watermark — e.g. a stale sequence after a reload).
+   * A `false` verdict tells the caller to reissue above the now-known watermark
+   * (echoed into {@link confirmedMutationWatermark}) rather than treat the benign
+   * ack as a confirmed write. Every ack — applied or not — bumps the watermark.
+   *
+   * This is the online transport for `@lunora/db`'s client-mutator runtime; the
+   * optimistic overlay + durable-outbox concerns live in that runtime, not here.
+   */
+  async callMutator(functionPath, args, options) {
+    const clientSeq = options?.clientSeq;
+    if (clientSeq !== void 0 && (!Number.isInteger(clientSeq) || clientSeq <= 0)) {
+      throw new Error(`callMutator: clientSeq must be a positive integer, got ${String(clientSeq)}`);
+    }
+    const bucket = options?.shardKey ?? "";
+    let ackWatermark;
+    const result = await this.rpc(functionPath, args, options?.shardKey, {
+      captureBookmark: true,
+      clientId: this.clientId,
+      clientSeq,
+      onMutationAck: (lastMutationId) => {
+        ackWatermark = lastMutationId;
+      }
+    });
+    if (ackWatermark !== void 0 && ackWatermark > (this.clientWatermarks.get(bucket) ?? 0)) {
+      this.clientWatermarks.set(bucket, ackWatermark);
+    }
+    const applied = ackWatermark === void 0 || ackWatermark === clientSeq;
+    return { applied, result };
+  }
   /**
    * Subscribe to auth-token changes. Returns an unsubscribe function. The
    * listener is NOT invoked on registration — use {@link getAuthToken} for
@@ -578,7 +677,7 @@ class LunoraClient {
       throw new Error("LunoraClient is closed");
     }
     const argsRecord = args;
-    const mutationId = nextId();
+    const mutationId = options.mutationId ?? nextId();
     const optimisticRollbacks = this.applyOptimisticUpdates(function_.__lunoraRef, argsRecord, options.shardKey, options.optimistic);
     if (options.optimisticUpdate) {
       this.applyOptimisticUpdate(options.optimisticUpdate, args, options.shardKey, optimisticRollbacks);
@@ -592,40 +691,12 @@ class LunoraClient {
     const shouldQueueOffline = this.WebSocketImpl !== void 0 && connectedGate;
     const midReconnect = wsState === "connecting" && connectedGate;
     if (wsState !== "open" && !hasSocket && shouldQueueOffline || midReconnect) {
-      const issuingIdentity = this.identityFingerprint();
-      return new Promise((resolve, reject) => {
-        const entry = {
-          args: argsRecord,
-          functionPath: function_.__lunoraRef,
-          // Reuse the call's idempotency key as the queue id so the
-          // replay carries the same `x-lunora-mutation-id` the server
-          // dedups on.
-          id: mutationId,
-          // Persist the stamp alongside the record so a hydrated write
-          // can only replay under the identity that queued it.
-          identity: issuingIdentity,
-          reject: (error) => {
-            this.queuedIdentities.delete(mutationId);
-            for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
-              optimisticRollbacks[index]?.();
-            }
-            reject(error instanceof Error ? error : new Error(String(error)));
-          },
-          resolve,
-          shardKey: options.shardKey
-        };
-        this.offlineQueue.enqueue(entry);
-        if (entry.id !== void 0) {
-          this.queuedIdentities.set(entry.id, issuingIdentity);
-        }
-      });
+      return this.enqueueOfflineMutation(function_, argsRecord, options.shardKey, mutationId, optimisticRollbacks);
     }
     try {
       return await this.rpc(function_.__lunoraRef, argsRecord, options.shardKey, { captureBookmark: true, mutationId });
     } catch (error) {
-      for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
-        optimisticRollbacks[index]?.();
-      }
+      rollbackOptimistic(optimisticRollbacks);
       throw error;
     }
   }
@@ -739,8 +810,12 @@ class LunoraClient {
    * List a workflow's instances via the admin Workflows proxy
    * (`/_lunora/admin/workflows/instances`) — the Cloudflare control-plane data
    * the `Workflow` binding can't expose. Requires the worker to be built with a
-   * `workflowsClient` (Cloudflare account id + API token); otherwise the proxy
-   * responds 501 and this rejects. `name` is the deployed workflow name.
+   * `workflowsClient` (Cloudflare account id + API token). When one isn't
+   * configured this does NOT reject: the proxy returns a `200 { configured:
+   * false }` sentinel, so the result resolves with `configured === false` and an
+   * empty `instances` list — callers should branch on that flag rather than
+   * try/catch. (The instance-detail / status endpoints still reject with 501.)
+   * `name` is the deployed workflow name.
    */
   async listWorkflowInstances(options) {
     if (this.closed) {
@@ -757,7 +832,13 @@ class LunoraClient {
       query.set("perPage", String(options.perPage));
     }
     const body = await this.adminFetch(`${WORKFLOWS_INSTANCES_PATH}?${query.toString()}`, "GET");
-    return { instances: body.instances ?? [], page: body.page ?? 1, perPage: body.perPage ?? options.perPage ?? 0, totalCount: body.totalCount };
+    return {
+      configured: body.configured,
+      instances: body.instances ?? [],
+      page: body.page ?? 1,
+      perPage: body.perPage ?? options.perPage ?? 0,
+      totalCount: body.totalCount
+    };
   }
   /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
   async getWorkflowInstance(options) {
@@ -1293,12 +1374,52 @@ class LunoraClient {
         const conn = this.getConnection(subscriptionState.shardKey);
         const ok = conn ? sendOn(conn, { id: subscriptionState.id, type: "unsubscribe" }) : false;
         if (!ok && conn) {
-          conn.pendingUnsubscribes.push(subscriptionState.id);
+          conn.pendingUnsubscribes.push({ id: subscriptionState.id, type: "unsubscribe" });
         }
         this.subscriptions.remove(subscriptionState);
       }
     };
   }
+  /**
+   * Subscribe to a declarative **shape** — server-side partial replication
+   * scoped by `shardBy` + the shape's predicate + RLS. The parallel to
+   * {@link subscribe} for the poke protocol: the client sends the shape *name* +
+   * validated `args` (never a `where` the client could forge), the server seeds
+   * the current membership as an insert-poke and streams live membership diffs.
+   * Each applied poke materializes the shape's rowset and invokes `callback`.
+   *
+   * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
+   * (name, args): the server resolves them under the socket's verified identity,
+   * so every call gets its own id + view. The returned function unsubscribes.
+   */
+  subscribeShape(shape, callback, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    this.nextShapeId += 1;
+    const id = `shape_${this.nextShapeId.toString()}`;
+    const state = {
+      args: shape.args,
+      callbacks: /* @__PURE__ */ new Set([callback]),
+      errorCallbacks: options.onError ? /* @__PURE__ */ new Set([options.onError]) : /* @__PURE__ */ new Set(),
+      id,
+      name: shape.name,
+      onCheckpoint: options.onCheckpoint,
+      rows: /* @__PURE__ */ new Map(),
+      shardKey: options.shardKey
+    };
+    this.shapeSubscriptions.set(id, state);
+    this.ensureSocket(options.shardKey);
+    this.sendShapeSubscribeIfOpen(state);
+    return () => {
+      this.shapeSubscriptions.delete(id);
+      const conn = this.getConnection(state.shardKey);
+      const ok = conn ? sendOn(conn, { id, type: "shape_unsubscribe" }) : false;
+      if (!ok && conn) {
+        conn.pendingUnsubscribes.push({ id, type: "shape_unsubscribe" });
+      }
+    };
+  }
   /**
    * Open a streaming query. The function reference must be a
    * `kind:"stream"` registration (built with `c.query.input(...).stream(...)`);
@@ -1375,6 +1496,10 @@ class LunoraClient {
         clearTimeout(conn.reconnectTimer);
         conn.reconnectTimer = void 0;
       }
+      if (conn.connectTimer !== void 0) {
+        clearTimeout(conn.connectTimer);
+        conn.connectTimer = void 0;
+      }
       this.stopHeartbeat(conn);
       if (conn.socket) {
         try {
@@ -1398,8 +1523,66 @@ class LunoraClient {
     this.statusListeners.clear();
     this.tokenExpiredListeners.clear();
     this.whisperHandlers.clear();
+    this.shapeSubscriptions.clear();
+    this.pokeBuffers.clear();
   }
   // --- Internals ----------------------------------------------------------
+  /**
+   * Persist a mutation that can't go out on the wire right now (offline, or
+   * mid-reconnect after a prior connect). The optimistic update has already
+   * been applied by `mutation`; this only chooses the durable write path and
+   * rolls the optimistic write back if persistence is rejected.
+   *
+   * Two paths: when an `outbox` sink is wired (the `@lunora/db` executor) it
+   * owns persistence + at-least-once replay, so we delegate and return
+   * optimistically (confirmation rides the synced view). Otherwise the
+   * built-in `OfflineQueue` resolves/rejects the returned promise on replay.
+   */
+  async enqueueOfflineMutation(function_, argsRecord, shardKey, mutationId, optimisticRollbacks) {
+    const issuingIdentity = this.identityFingerprint();
+    if (this.outbox) {
+      this.outboxMutationCounter += 1;
+      const outboxMutationId = this.outboxMutationCounter;
+      try {
+        await this.outbox.enqueue({
+          args: argsRecord,
+          clientId: this.clientId,
+          functionPath: function_.__lunoraRef,
+          idempotencyKey: `${this.clientId}:${String(outboxMutationId)}`,
+          identity: issuingIdentity,
+          mutationId: outboxMutationId,
+          shardKey
+        });
+      } catch (error) {
+        rollbackOptimistic(optimisticRollbacks);
+        throw error instanceof Error ? error : new Error(String(error));
+      }
+      return void 0;
+    }
+    return new Promise((resolve, reject) => {
+      const entry = {
+        args: argsRecord,
+        functionPath: function_.__lunoraRef,
+        // Reuse the call's idempotency key as the queue id so the replay
+        // carries the same `x-lunora-mutation-id` the server dedups on.
+        id: mutationId,
+        // Persist the stamp alongside the record so a hydrated write can
+        // only replay under the identity that queued it.
+        identity: issuingIdentity,
+        reject: (error) => {
+          this.queuedIdentities.delete(mutationId);
+          rollbackOptimistic(optimisticRollbacks);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        },
+        resolve,
+        shardKey
+      };
+      this.offlineQueue.enqueue(entry);
+      if (entry.id !== void 0) {
+        this.queuedIdentities.set(entry.id, issuingIdentity);
+      }
+    });
+  }
   /**
    * Restore offline mutations persisted in a prior session and open a socket
    * for each shard they target so they flush once the WS reconnects. Failures
@@ -1564,6 +1747,7 @@ class LunoraClient {
     let conn = this.connections.get(key);
     if (!conn) {
       conn = {
+        connectTimer: void 0,
         heartbeatTimer: void 0,
         pendingUnsubscribes: [],
         reconnect: createReconnect(this.reconnectOptions),
@@ -1607,6 +1791,12 @@ class LunoraClient {
     if (flags.mutationId) {
       headers["x-lunora-mutation-id"] = flags.mutationId;
     }
+    if (flags.clientId !== void 0) {
+      headers["x-lunora-client-id"] = flags.clientId;
+    }
+    if (flags.clientSeq !== void 0) {
+      headers["x-lunora-client-seq"] = flags.clientSeq.toString();
+    }
     if (flags.attachBookmark) {
       const bookmark = this.bookmark.get();
       if (bookmark) {
@@ -1647,6 +1837,7 @@ class LunoraClient {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
       throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
     }
+    flags.onMutationAck?.(body.lastMutationId);
     return body.result;
   }
   /**
@@ -1737,11 +1928,27 @@ class LunoraClient {
   sendConnectEnvelope(conn) {
     const context = this.effectiveConnectionContext(connectionKey(conn.shardKey));
     sendOn(conn, {
+      // Lets the server scope this connection's `__client_watermark` so
+      // custom-mutator pokes can echo this client's `lastMutationId`.
+      clientId: this.clientId,
       id: "connect",
       type: "connect",
       ...context === void 0 ? {} : { context }
     });
   }
+  /**
+   * Re-send every shape subscription bound to `shardKey` over its (now open)
+   * socket. Each frame carries the shape's last applied checkpoint, so the
+   * server resumes from it — or re-seeds when the cursor fell below CDC
+   * retention or the epoch forked.
+   */
+  resendShapeSubscriptions(shardKey) {
+    for (const state of this.shapeSubscriptions.values()) {
+      if (connectionKey(state.shardKey) === connectionKey(shardKey)) {
+        this.sendShapeSubscribeIfOpen(state);
+      }
+    }
+  }
   ensureSocket(shardKey) {
     if (this.closed || this.WebSocketImpl === void 0) {
       return;
@@ -1754,7 +1961,27 @@ class LunoraClient {
     this.emitConnectionStatus();
     const socket = new this.WebSocketImpl(this.wsUrlFor(shardKey));
     conn.socket = socket;
+    if (this.connectTimeoutMs > 0) {
+      conn.connectTimer = setTimeout(() => {
+        conn.connectTimer = void 0;
+        if (conn.socket !== socket || conn.wsState !== "connecting") {
+          return;
+        }
+        try {
+          socket.close();
+        } catch {
+        }
+        this.handleDisconnect(conn);
+      }, this.connectTimeoutMs);
+    }
     socket.addEventListener("open", () => {
+      if (conn.socket !== socket) {
+        return;
+      }
+      if (conn.connectTimer !== void 0) {
+        clearTimeout(conn.connectTimer);
+        conn.connectTimer = void 0;
+      }
       conn.wsState = "open";
       conn.wasEverConnected = true;
       conn.reconnect.reset();
@@ -1766,11 +1993,12 @@ class LunoraClient {
           this.sendSubscribeIfOpen(state);
         }
       }
+      this.resendShapeSubscriptions(shardKey);
       if (conn.pendingUnsubscribes.length > 0) {
         const pending = conn.pendingUnsubscribes;
         conn.pendingUnsubscribes = [];
-        for (const id of pending) {
-          sendOn(conn, { id, type: "unsubscribe" });
+        for (const { id, type } of pending) {
+          sendOn(conn, { id, type });
         }
       }
       if (conn.pendingStreams && conn.pendingStreams.length > 0) {
@@ -1793,12 +2021,18 @@ class LunoraClient {
       this.handleServerMessage(event.data, shardKey);
     });
     socket.addEventListener("close", (event) => {
+      if (conn.socket !== socket) {
+        return;
+      }
       if (event?.code === 4001) {
         this.notifyTokenExpired();
       }
       this.handleDisconnect(conn);
     });
     socket.addEventListener("error", () => {
+      if (conn.socket !== socket) {
+        return;
+      }
       if (conn.wsState === "connecting" || conn.wsState === "open") {
         this.handleDisconnect(conn);
       }
@@ -1812,6 +2046,10 @@ class LunoraClient {
       return;
     }
     this.stopHeartbeat(conn);
+    if (conn.connectTimer !== void 0) {
+      clearTimeout(conn.connectTimer);
+      conn.connectTimer = void 0;
+    }
     conn.socket = void 0;
     conn.wsState = "idle";
     this.emitConnectionStatus();
@@ -1885,6 +2123,21 @@ class LunoraClient {
       type: "subscribe"
     });
   }
+  sendShapeSubscribeIfOpen(state) {
+    const conn = this.getConnection(state.shardKey);
+    if (conn?.wsState !== "open") {
+      return;
+    }
+    sendOn(conn, {
+      id: state.id,
+      shape: { name: state.name, ...state.args === void 0 ? {} : { args: state.args } },
+      type: "shape_subscribe",
+      // Resume from the last applied checkpoint when we hold one; a cold
+      // subscribe omits it and the server seeds the full membership.
+      ...state.serverCursor === void 0 ? {} : { sinceCheckpoint: state.serverCursor },
+      ...state.serverEpoch === void 0 ? {} : { sinceEpoch: state.serverEpoch }
+    });
+  }
   handleServerMessage(raw, shardKey) {
     const text = decodeServerFrame(raw);
     if (text === void 0) {
@@ -1923,6 +2176,18 @@ class LunoraClient {
         this.handleErrorMessage(message);
         break;
       }
+      case "pokeEnd": {
+        this.handlePokeEnd(message);
+        break;
+      }
+      case "pokePart": {
+        this.handlePokePart(message);
+        break;
+      }
+      case "pokeStart": {
+        this.handlePokeStart(message);
+        break;
+      }
       case "resume": {
         this.handleResumeMessage(message);
         break;
@@ -1948,12 +2213,79 @@ class LunoraClient {
     }
     const state = id === void 0 ? void 0 : this.subscriptions.getById(id);
     if (state) {
-      const error = buildSubscriptionError(message);
-      for (const errorCallback of state.errorCallbacks) {
-        try {
-          errorCallback(error);
-        } catch {
-        }
+      fanSubscriptionError(state.errorCallbacks, buildSubscriptionError(message));
+      return;
+    }
+    const shapeState = id === void 0 ? void 0 : this.shapeSubscriptions.get(id);
+    if (shapeState) {
+      fanSubscriptionError(shapeState.errorCallbacks, buildSubscriptionError(message));
+    }
+  }
+  handlePokeStart(message) {
+    if (this.pokeBuffers.size >= LunoraClient.MAX_POKE_BUFFERS) {
+      const oldest = this.pokeBuffers.keys().next().value;
+      if (oldest !== void 0) {
+        this.pokeBuffers.delete(oldest);
+      }
+    }
+    this.pokeBuffers.set(message.pokeId, { baseCheckpoint: message.baseCheckpoint, epoch: message.epoch, lastMutationId: /* @__PURE__ */ new Map(), parts: /* @__PURE__ */ new Map() });
+  }
+  handlePokePart(message) {
+    const buffer = this.pokeBuffers.get(message.pokeId);
+    if (!buffer) {
+      return;
+    }
+    const existing = buffer.parts.get(message.shapeId) ?? [];
+    existing.push(...message.rowsPatch);
+    buffer.parts.set(message.shapeId, existing);
+    if (message.lastMutationId !== void 0) {
+      buffer.lastMutationId.set(message.shapeId, message.lastMutationId);
+    }
+  }
+  handlePokeEnd(message) {
+    const buffer = this.pokeBuffers.get(message.pokeId);
+    if (!buffer) {
+      return;
+    }
+    this.pokeBuffers.delete(message.pokeId);
+    for (const [shapeId, ops] of buffer.parts) {
+      const state = this.shapeSubscriptions.get(shapeId);
+      if (!state) {
+        continue;
+      }
+      const epochForked = buffer.epoch !== void 0 && state.serverEpoch !== void 0 && buffer.epoch !== state.serverEpoch;
+      const baseDiverged = buffer.baseCheckpoint !== void 0 && state.serverCursor !== void 0 && state.serverCursor !== buffer.baseCheckpoint;
+      if (epochForked || baseDiverged) {
+        state.rows.clear();
+        state.serverCursor = void 0;
+        state.serverEpoch = void 0;
+        this.emitShapeRows(state);
+        this.sendShapeSubscribeIfOpen(state);
+        continue;
+      }
+      applyRowOpsToView(state.rows, ops);
+      if (message.checkpoint !== void 0) {
+        state.serverCursor = message.checkpoint;
+      }
+      if (message.epoch !== void 0) {
+        state.serverEpoch = message.epoch;
+      }
+      const watermark = buffer.lastMutationId.get(shapeId);
+      if (watermark !== void 0) {
+        state.lastMutationId = watermark;
+      }
+      this.emitShapeRows(state);
+      state.onCheckpoint?.({ checkpoint: state.serverCursor, mutationId: state.lastMutationId });
+    }
+  }
+  /** Materialize a shape's keyed view to an array and invoke its callbacks. */
+  // eslint-disable-next-line class-methods-use-this -- a pure state→callback fan-out kept beside the shape-subscription pipeline it serves.
+  emitShapeRows(state) {
+    const rows = [...state.rows.values()];
+    for (const shapeCallback of state.callbacks) {
+      try {
+        shapeCallback(rows);
+      } catch {
       }
     }
   }

package/dist/packem_shared/{OfflineQueue-D5p_QgF_.mjs → OfflineQueue-D-ASeqL7.mjs}

@@ -4,7 +4,11 @@ const nextId = () => {
     return crypto.randomUUID();
   }
   idCounter += 1;
-  return `m_${Date.now().toString(36)}_${idCounter.toString(36)}`;
+  const entropy = typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function" ? [...crypto.getRandomValues(new Uint8Array(8))].map((byte) => byte.toString(16).padStart(2, "0")).join("") : (
+    // eslint-disable-next-line sonarjs/pseudo-random -- non-cryptographic uniqueness entropy, not a security token; only reached when neither crypto.randomUUID nor crypto.getRandomValues exists
+    Math.random().toString(16).slice(2, 12)
+  );
+  return `m_${Date.now().toString(36)}_${idCounter.toString(36)}_${entropy}`;
 };
 const reportPersistenceError = (handler, operation, error, mutationId) => {
   if (handler) {

package/dist/packem_shared/SubscriptionRegistry-Dn-7k7eo.mjs

@@ -0,0 +1 @@
+export { S as SubscriptionRegistry } from './subscription-C1Jy7HiF.mjs';