@interncom/diplomatic 0.3.3 → 0.3.4

package/dist/web/openClient.d.ts

@@ -13,6 +13,16 @@ import type { IClient, IStore } from "./types";
  * (built as `worker.mjs` in the published package). It must run as a
  * **module** worker (`type: "module"`).
  *
+ * ## Handshake (race-safe)
+ *
+ * The worker posts an unsolicited `{ kind: "ready" }` after init. Apps often
+ * construct the Worker at module load (or before `openDiplomaticClient` finishes
+ * opening IndexedDB), so that event can fire before the library sets
+ * `onmessage`. **That is fine:** connect also probes with a request/response
+ * `ping`. The worker holds commands until init completes, so the probe succeeds
+ * even if `ready` was dropped. Do **not** reimplement message buffering in the
+ * app unless you need it for other reasons.
+ *
  * ## Vite (recommended for SPA templates)
  *
  * ```ts
@@ -23,6 +33,7 @@ import type { IClient, IStore } from "./types";
  *
  * `?worker` makes Vite emit a real worker asset and a constructor. Create the
  * instance once (module scope or `useMemo`/`useRef`) — not on every render.
+ * Early construction is supported; the handshake recovers if `ready` is missed.
  *
  * ## webpack / Rollup / esbuild / Parcel (`new URL` + import.meta.url)
  *

package/dist/web/react/useClient.d.ts

@@ -19,11 +19,16 @@ type UseClientBase = {
  *   import DiplomaticWorker from "@interncom/diplomatic/worker?worker";
  *   const syncWorker = new DiplomaticWorker();
  *   useClient({ worker: syncWorker, seed, host });
+ *
+ * Handshake is race-safe (ready event and/or probe ping). See
+ * `openDiplomaticClient` for bundler recipes and handshake notes.
  */
 export type UseClientWorkerOptions = UseClientBase & {
     /**
      * App-constructed sync Worker. Create once (module scope or useMemo/useRef),
-     * not each render. See `openDiplomaticClient` for instantiation recipes.
+     * not each render. Early construction before `useClient` opens IDB is OK —
+     * the library does not require catching the unsolicited `ready` event.
+     * See `openDiplomaticClient` for instantiation recipes.
      */
     worker: Worker;
     store?: never;

package/dist/web/worker/client.d.ts

@@ -8,11 +8,19 @@ import type { IClient, IDiplomaticClientState, IDiplomaticClientXferState, IHost
  *
  * Provide a live `Worker` — the library never constructs one. See
  * `openDiplomaticClient` for bundler/CDN instantiation recipes.
+ *
+ * Handshake is race-safe: the worker posts unsolicited `{ kind: "ready" }`, but
+ * connect also probes with `ping`. Early construction (module scope) is fine even
+ * if `ready` fired before `onmessage` was set — the ping still succeeds once the
+ * worker has finished init (cmds are held until then on the worker side).
  */
 export type WorkerClientOptions = {
     /** Already-constructed module Worker running `@interncom/diplomatic/worker`. */
     worker: Worker;
-    /** Max wait for worker `ready` (default 15s). Failures throw; no fallback. */
+    /**
+     * Max wait for handshake (`ready` event or probe ping; default 15s).
+     * Failures throw; no fallback.
+     */
     readyTimeoutMs?: number;
     clock?: IClock;
     /**
@@ -48,8 +56,19 @@ export declare class WorkerClient implements IClient<URL> {
      * Attach to an app-provided Worker. `store` is the shared protocol IDB (main
      * connection) used for local msg writes; worker opens its own connection.
      * Throws if the worker never becomes ready — does not fall back to main thread.
+     *
+     * Handshake: wait for unsolicited `ready` **or** a successful probe `ping`.
+     * The probe covers the common case where the app started the Worker early and
+     * `ready` was dropped before this thread set `onmessage`.
      */
     static connect(state: IStateManager, store: IStore<URL>, opts: WorkerClientOptions): Promise<WorkerClient>;
+    /** Resolve the ready barrier (idempotent). */
+    private markReady;
+    /**
+     * Active handshake: post ping without waiting for the ready event.
+     * On pong, mark ready so connect can proceed even if `ready` was missed.
+     */
+    private probeReady;
     /** Lightweight RPC check after connect. */
     ping(): Promise<void>;
     /** Terminate the worker (drops protocol DB connection in that thread). */

package/dist/web/worker/runtime.d.ts

@@ -4,8 +4,14 @@ export type PostFn = (msg: WorkerEvent, transfer?: Transferable[]) => void;
 export declare class WorkerRuntime {
     private client;
     private post;
+    /** Resolves when init finishes (success or failure). Cmds wait on this. */
+    private whenReady;
+    private resolveReady;
+    private rejectReady;
     constructor(post: PostFn);
     init(): Promise<void>;
+    private markReady;
+    private failReady;
     private requireClient;
     private emitClientState;
     private emitXferState;