@edv4h/usketch-plugin-sync-ywebsocket 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EdV4H
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# @edv4h/usketch-plugin-sync-ywebsocket
+
+Bridge a uSketch app to any [y-websocket](https://github.com/yjs/y-websocket) server. Wraps `WebsocketProvider` and exposes a `WsProviderHandle`-compatible adapter so it plugs directly into plugins like `@edv4h/usketch-plugin-presence-cursor`.
+
+Designed for teams that already run a y-websocket backend (or need to migrate off another realtime engine) and want to keep their sync layer while adopting uSketch on the client.
+
+## Install
+
+```sh
+pnpm add @edv4h/usketch-plugin-sync-ywebsocket
+```
+
+## Basic usage
+
+`getWsProvider()` is only valid *after* the sync plugin's `setup()` has run. Since
+`createApp` calls `setup()` in plugin order, the recommended pattern is to defer
+the `wsProvider` lookup into a thin wrapper plugin that runs after the sync
+plugin. This keeps everything inside a single `createApp` call:
+
+```ts
+import { createApp } from "@edv4h/usketch-core";
+import { createBoardStore } from "@edv4h/usketch-store";
+import type { UsketchPlugin } from "@edv4h/usketch-shared";
+import { createPresenceCursorPlugin } from "@edv4h/usketch-plugin-presence-cursor";
+import { createYwebsocketSyncPlugin, type YwebsocketSyncPlugin } from "@edv4h/usketch-plugin-sync-ywebsocket";
+
+const syncPlugin = createYwebsocketSyncPlugin({
+  url: "wss://yws.example.com",
+  roomName: "board-123",
+});
+
+// Wrap presence-cursor so the provider is read at setup time, when syncPlugin.setup
+// has already run (plugins are set up in order).
+function presenceCursorWithSync(
+  sync: YwebsocketSyncPlugin,
+  opts: { userId: string; userName: string },
+): UsketchPlugin {
+  let inner: UsketchPlugin | null = null;
+  return {
+    id: "usketch-plugin-presence-cursor",
+    name: "Presence Cursor",
+    async setup(ctx) {
+      inner = createPresenceCursorPlugin({
+        wsProvider: sync.getWsProvider(),
+        userId: opts.userId,
+        userName: opts.userName,
+      });
+      await inner.setup(ctx);
+    },
+    teardown() {
+      inner?.teardown?.();
+    },
+  };
+}
+
+const app = await createApp({
+  store: createBoardStore(),
+  plugins: [
+    syncPlugin,
+    presenceCursorWithSync(syncPlugin, { userId: "alice", userName: "Alice" }),
+  ],
+});
+```
+
+This pattern generalizes to any plugin that needs a `WsProviderHandle`: wrap it
+in a small factory that reads `sync.getWsProvider()` inside its own `setup()`.
+
+## Options
+
+```ts
+createYwebsocketSyncPlugin({
+  url,                    // ws(s):// base URL of the y-websocket server
+  roomName,               // server-side document identifier
+  shapesMapKey,           // optional — defaults to "shapes" (weboard uses "map")
+  resolveParams,          // async/sync callback to supply URL query params on each connect
+  onCloseCode,            // classify close codes: "retry" | "stop" | undefined (default backoff)
+  idleTimeoutMs,          // 0 (off) — disconnect after this many ms of inactivity
+  autoConnect,            // default true — connect on plugin setup
+  doc,                    // optional — bring your own Y.Doc (useful for mid-life migrations)
+  WebSocketPolyfill,      // optional — Node test environments only
+});
+```
+
+### Resolving auth tokens on each connect
+
+`resolveParams` is called before every connect and reconnect. Use it to hand back freshly refreshed tokens so the server sees a valid credential on reconnect:
+
+```ts
+createYwebsocketSyncPlugin({
+  url: "wss://yws.example.com",
+  roomName: "board-123",
+  async resolveParams({ attempt, previousCloseCode }) {
+    // Force a fresh token if the previous connection was rejected for auth.
+    const forceRefresh = previousCloseCode === 4003 || previousCloseCode === 4004;
+    const token = await cognitoSession.getAccessToken({ forceRefresh });
+    return {
+      params: {
+        token: token.jwt,
+        employeeId: String(token.employeeId),
+        companyId: String(token.companyId),
+      },
+    };
+  },
+  onCloseCode(code) {
+    if (code === 4003 || code === 4004) return "retry"; // immediate retry; resolveParams will fetch a fresh token
+    return undefined; // fall through to exponential backoff
+  },
+});
+```
+
+### Idle disconnect
+
+Set `idleTimeoutMs` to disconnect after inactivity (no local board edits / store mutations). The timer also resets whenever the socket reports `connected` or `resume()` is called. Call `handle.resume()` to reconnect on the next user interaction.
+
+```ts
+const plugin = createYwebsocketSyncPlugin({
+  url: "wss://yws.example.com",
+  roomName: "board-123",
+  idleTimeoutMs: 5 * 60 * 1000, // 5 minutes
+});
+
+// Later, in an interaction handler:
+plugin.getHandle().resume();
+```
+
+## Advanced: accessing the handle
+
+```ts
+const handle = syncPlugin.getHandle();
+handle.disconnect();       // manual disconnect; stays disconnected
+handle.resume();           // reconnect after a disconnect/idle
+handle.status.subscribe(() => console.log(handle.status.getSnapshot()));
+handle.doc;                // the underlying Y.Doc
+handle.whenSynced;         // promise that resolves on first server sync
+handle.wsProvider;         // WsProviderHandle adapter (same as getWsProvider())
+```
+
+## WsProviderHandle compatibility
+
+`handle.wsProvider` implements the `WsProviderHandle` contract from `@edv4h/usketch-sync` so plugins that consume `WsProviderHandle` work out of the box:
+
+| member              | supported                                 |
+| ------------------- | ----------------------------------------- |
+| `connected`         | yes                                        |
+| `awareness`         | yes (always — shared across reconnects)    |
+| `onStatusChange`    | yes                                        |
+| `onBroadcast`       | listeners accepted; never emits (no-op)    |
+| `broadcast`         | no-op — y-websocket has no side-channel    |
+| `requestPartition`  | no-op — y-websocket has no partitions      |
+| `onPartitionMeta`   | no-op — y-websocket has no partitions      |
+| `destroy`           | yes                                        |
+
+If you need broadcast / partition semantics, stay on `@edv4h/usketch-sync`'s `createWsProvider()` with a uSketch-native server.
+
+## License
+
+MIT

package/dist/divergence-tracker.d.ts

@@ -0,0 +1,40 @@
+import type { BoardStore } from "@edv4h/usketch-shared";
+import type * as Y from "yjs";
+import { SyncStatusTracker } from "./sync-status-tracker.js";
+/**
+ * Standalone divergence tracker for apps that wire IDB sync + WsProvider
+ * **manually** (rather than via `createYwebsocketSyncPlugin`). It watches the
+ * store, the Y.Map of shapes, and the WebSocket connection, then exposes a
+ * `SyncStatusTracker` whose `unconfirmedShapeIds` reflects shapes that exist
+ * locally but the server hasn't acknowledged.
+ *
+ * Why this exists: the full plugin embeds y-websocket's `provider.on("sync")`
+ * event for the "first server sync" stamp, but `@edv4h/usketch-sync`'s
+ * `createWsProvider` doesn't expose that signal. We approximate by stamping
+ * `firstServerSyncAt` on the first remote-origin Y.Doc update, which is the
+ * earliest moment we can be sure the server has talked back to us.
+ */
+export interface DivergenceTrackerOptions {
+    store: BoardStore;
+    doc: Y.Doc;
+    shapesMap: Y.Map<Record<string, unknown>>;
+    /** Subscribe to socket-level connection state (`"connected"` / `"connecting"` / `"disconnected"`). */
+    onConnectionStatusChange: (handler: (status: string) => void) => () => void;
+    /**
+     * Grace period (ms) to wait after the socket reaches `"connected"` before
+     * concluding "first sync completed" if no remote Y.Doc update has arrived.
+     * The y-websocket SYNC_STEP1/STEP2 round-trip is normally fast, so even an
+     * empty server (no shapes to push) will resolve well under a second. We
+     * pick a generous default to avoid false positives on slow networks.
+     *
+     * Defaults to 2000ms. Set to 0 to disable the timer-based fallback (only
+     * the first remote update will stamp).
+     */
+    emptyServerGraceMs?: number;
+}
+export interface DivergenceTrackerHandle {
+    status: SyncStatusTracker;
+    destroy: () => void;
+}
+export declare function createDivergenceTracker(opts: DivergenceTrackerOptions): DivergenceTrackerHandle;
+//# sourceMappingURL=divergence-tracker.d.ts.map

package/dist/divergence-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence-tracker.d.ts","sourceRoot":"","sources":["../src/divergence-tracker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAC;AAC9B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,wBAAwB;IACxC,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACX,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1C,sGAAsG;IACtG,wBAAwB,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;IAC5E;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACvC,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,wBAAwB,GAAG,uBAAuB,CAwI/F"}

package/dist/divergence-tracker.js

@@ -0,0 +1,134 @@
+import { SyncStatusTracker } from "./sync-status-tracker.js";
+export function createDivergenceTracker(opts) {
+    const { store, doc, shapesMap, onConnectionStatusChange, emptyServerGraceMs = 2000 } = opts;
+    const status = new SyncStatusTracker();
+    let currentWsStatus = "disconnected";
+    let serverSynced = false;
+    // Timer that fires `markServerSynced()` if `connected` persists for
+    // `emptyServerGraceMs` without any remote Y.Doc update. Covers the
+    // "empty server / no history" case where a remote update never comes.
+    let emptyServerTimer = null;
+    function clearEmptyServerTimer() {
+        if (emptyServerTimer !== null) {
+            clearTimeout(emptyServerTimer);
+            emptyServerTimer = null;
+        }
+    }
+    function markServerSynced() {
+        if (serverSynced)
+            return;
+        serverSynced = true;
+        clearEmptyServerTimer();
+        status.batch(() => {
+            status.markFirstServerSyncObserved();
+            if (currentWsStatus === "connected") {
+                status.update({ state: "synced" });
+            }
+        });
+    }
+    // 1. Connection state — drives the "is local add already confirmed?" decision
+    //    in the store mutation handler below, and is mirrored onto the snapshot
+    //    `state` field so consumers (e.g. Debug HUD's Persistence indicator)
+    //    show the right thing.
+    const offStatus = onConnectionStatusChange((next) => {
+        currentWsStatus = next;
+        // Mirror transport state into the snapshot using the same mapping the
+        // full ywebsocket plugin uses: socket-level "connected" maps to
+        // "syncing" until the first remote update arrives, then "synced".
+        const mappedState = next === "connected"
+            ? serverSynced
+                ? "synced"
+                : "syncing"
+            : next === "connecting"
+                ? "connecting"
+                : next === "disconnected"
+                    ? "disconnected"
+                    : "error";
+        status.update({
+            state: mappedState,
+            error: next === "failed" ? "connection failed" : null,
+        });
+        // Empty-server fallback: when we connect but the server has nothing to
+        // push (new room, lost history), `doc.on("update")` never fires. Start
+        // a timer so `firstServerSyncAt` is still stamped after the SYNC round-
+        // trip has had time to complete. `emptyServerGraceMs: 0` opts out.
+        if (next === "connected" && !serverSynced && emptyServerGraceMs > 0) {
+            clearEmptyServerTimer();
+            emptyServerTimer = setTimeout(markServerSynced, emptyServerGraceMs);
+        }
+        else if (next !== "connected") {
+            // Drop the timer if we got disconnected before the grace expired.
+            clearEmptyServerTimer();
+        }
+    });
+    // 2. Initial load: every shape already in the Y.Map (typically restored from
+    //    IndexedDB) is "local-only" until the server confirms.
+    if (shapesMap.size > 0) {
+        const initialIds = [];
+        for (const id of shapesMap.keys())
+            initialIds.push(id);
+        status.noteShapesLoaded(initialIds, "local");
+    }
+    // 3. Local mutations from the store — online → confirmed (broadcast goes
+    //    out immediately), offline → unconfirmed.
+    const offMutation = store.onMutation((event) => {
+        const payload = event.payload;
+        if (!payload?.id)
+            return;
+        status.batch(() => {
+            if (event.type === "shape:added") {
+                const isOnline = currentWsStatus === "connected";
+                status.noteShapeAdded(payload.id, isOnline ? "remote" : "local");
+            }
+            else if (event.type === "shape:removed") {
+                status.noteShapeRemoved(payload.id);
+            }
+            status.update({ shapeCount: shapesMap.size, lastSyncedAt: Date.now() });
+        });
+    });
+    // 4. Y.Map observe — for remote-origin additions (server pushed a shape
+    //    we didn't have, or another peer added one).
+    const observer = (events) => {
+        const isLocalTxn = events.transaction.local;
+        status.batch(() => {
+            for (const [key, change] of events.changes.keys) {
+                if (change.action === "add" && !isLocalTxn) {
+                    // Remote add → confirmed by server.
+                    status.noteShapeAdded(key, "remote");
+                }
+                else if (change.action === "delete") {
+                    status.noteShapeRemoved(key);
+                }
+            }
+            status.update({ shapeCount: shapesMap.size, lastSyncedAt: Date.now() });
+        });
+    };
+    shapesMap.observe(observer);
+    // 5. First remote-origin doc update marks the server as "synced with us".
+    //    We deliberately DO NOT bulk-confirm `shapesMap.keys()` here — that
+    //    would silently mark every IndexedDB-restored shape as "the server
+    //    knows about it", which is exactly what we want to NOT assume (the
+    //    whole point of this overlay is to surface phantom/orphaned shapes).
+    //    Instead, the Y.Map observer above marks individual remote-origin
+    //    additions as confirmed via `noteShapeAdded(key, "remote")`. Anything
+    //    the server didn't push to us during this session stays unconfirmed.
+    //
+    //    Note: an "empty" server sync (no shapes to push) won't trigger this
+    //    handler — the `emptyServerTimer` started above is the fallback that
+    //    catches that case.
+    function onDocUpdate(_update, origin) {
+        if (origin !== "remote")
+            return;
+        markServerSynced();
+    }
+    doc.on("update", onDocUpdate);
+    function destroy() {
+        clearEmptyServerTimer();
+        offStatus();
+        offMutation();
+        shapesMap.unobserve(observer);
+        doc.off("update", onDocUpdate);
+    }
+    return { status, destroy };
+}
+//# sourceMappingURL=divergence-tracker.js.map

package/dist/divergence-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence-tracker.js","sourceRoot":"","sources":["../src/divergence-tracker.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAuC7D,MAAM,UAAU,uBAAuB,CAAC,IAA8B;IACrE,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,wBAAwB,EAAE,kBAAkB,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAC5F,MAAM,MAAM,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAEvC,IAAI,eAAe,GAAG,cAAc,CAAC;IACrC,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,oEAAoE;IACpE,mEAAmE;IACnE,sEAAsE;IACtE,IAAI,gBAAgB,GAAyC,IAAI,CAAC;IAElE,SAAS,qBAAqB;QAC7B,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;YAC/B,YAAY,CAAC,gBAAgB,CAAC,CAAC;YAC/B,gBAAgB,GAAG,IAAI,CAAC;QACzB,CAAC;IACF,CAAC;IAED,SAAS,gBAAgB;QACxB,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QACpB,qBAAqB,EAAE,CAAC;QACxB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;YACjB,MAAM,CAAC,2BAA2B,EAAE,CAAC;YACrC,IAAI,eAAe,KAAK,WAAW,EAAE,CAAC;gBACrC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;YACpC,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,8EAA8E;IAC9E,4EAA4E;IAC5E,yEAAyE;IACzE,2BAA2B;IAC3B,MAAM,SAAS,GAAG,wBAAwB,CAAC,CAAC,IAAI,EAAE,EAAE;QACnD,eAAe,GAAG,IAAI,CAAC;QACvB,sEAAsE;QACtE,gEAAgE;QAChE,kEAAkE;QAClE,MAAM,WAAW,GAChB,IAAI,KAAK,WAAW;YACnB,CAAC,CAAC,YAAY;gBACb,CAAC,CAAC,QAAQ;gBACV,CAAC,CAAC,SAAS;YACZ,CAAC,CAAC,IAAI,KAAK,YAAY;gBACtB,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,IAAI,KAAK,cAAc;oBACxB,CAAC,CAAC,cAAc;oBAChB,CAAC,CAAC,OAAO,CAAC;QACd,MAAM,CAAC,MAAM,CAAC;YACb,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI;SACrD,CAAC,CAAC;QAEH,uEAAuE;QACvE,uEAAuE;QACvE,wEAAwE;QACxE,mEAAmE;QACnE,IAAI,IAAI,KAAK,WAAW,IAAI,CAAC,YAAY,IAAI,kBAAkB,GAAG,CAAC,EAAE,CAAC;YACrE,qBAAqB,EAAE,CAAC;YACxB,gBAAgB,GAAG,UAAU,CAAC,gBAAgB,EAAE,kBAAkB,CAAC,CAAC;QACrE,CAAC;aAAM,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;YACjC,kEAAkE;YAClE,qBAAqB,EAAE,CAAC;QACzB,CAAC;IACF,CAAC,CAAC,CAAC;IAEH,6EAA6E;IAC7E,2DAA2D;IAC3D,IAAI,SAAS,CAAC,IAAI,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,UAAU,GAAa,EAAE,CAAC;QAChC,KAAK,MAAM,EAAE,IAAI,SAAS,CAAC,IAAI,EAAE;YAAE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvD,MAAM,CAAC,gBAAgB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,yEAAyE;IACzE,8CAA8C;IAC9C,MAAM,WAAW,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9C,MAAM,OAAO,GAAG,KAAK,CAAC,OAAsC,CAAC;QAC7D,IAAI,CAAC,OAAO,EAAE,EAAE;YAAE,OAAO;QACzB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;YACjB,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBAClC,MAAM,QAAQ,GAAG,eAAe,KAAK,WAAW,CAAC;gBACjD,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,EAAY,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;YAC5E,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;gBAC3C,MAAM,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAY,CAAC,CAAC;YAC/C,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,wEAAwE;IACxE,iDAAiD;IACjD,MAAM,QAAQ,GAAG,CAAC,MAA4C,EAAQ,EAAE;QACvE,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE;YACjB,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;gBACjD,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;oBAC5C,oCAAoC;oBACpC,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;gBACtC,CAAC;qBAAM,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBACvC,MAAM,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;gBAC9B,CAAC;YACF,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC;IACF,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE5B,0EAA0E;IAC1E,wEAAwE;IACxE,uEAAuE;IACvE,uEAAuE;IACvE,yEAAyE;IACzE,sEAAsE;IACtE,0EAA0E;IAC1E,yEAAyE;IACzE,EAAE;IACF,yEAAyE;IACzE,yEAAyE;IACzE,wBAAwB;IACxB,SAAS,WAAW,CAAC,OAAmB,EAAE,MAAe;QACxD,IAAI,MAAM,KAAK,QAAQ;YAAE,OAAO;QAChC,gBAAgB,EAAE,CAAC;IACpB,CAAC;IACD,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAE9B,SAAS,OAAO;QACf,qBAAqB,EAAE,CAAC;QACxB,SAAS,EAAE,CAAC;QACZ,WAAW,EAAE,CAAC;QACd,SAAS,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC9B,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAChC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createDivergenceTracker, type DivergenceTrackerHandle, type DivergenceTrackerOptions, } from "./divergence-tracker.js";
+export { createYwebsocketSyncPlugin, type YwebsocketSyncPlugin } from "./plugin.js";
+export { type SyncState, type SyncStatusSnapshot, SyncStatusTracker, } from "./sync-status-tracker.js";
+export type { ConnectionParams, ResolveParamsContext, WsConnectionStatus, YwebsocketSyncHandle, YwebsocketSyncOptions, } from "./types.js";
+export { UnconfirmedOverlay } from "./unconfirmed-overlay.js";
+export { createYwebsocketSync } from "./yws-sync.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACN,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,0BAA0B,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACpF,OAAO,EACN,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,iBAAiB,GACjB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACX,gBAAgB,EAChB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,GACrB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+// Standalone helpers for apps that wire IDB sync + WsProvider manually
+// (rather than via `createYwebsocketSyncPlugin`). `createDivergenceTracker`
+// produces a SyncStatusTracker driven by a Y.Doc + WsProvider, and
+// `<UnconfirmedOverlay />` renders the SVG badge layer.
+export { createDivergenceTracker, } from "./divergence-tracker.js";
+export { createYwebsocketSyncPlugin } from "./plugin.js";
+export { SyncStatusTracker, } from "./sync-status-tracker.js";
+export { UnconfirmedOverlay } from "./unconfirmed-overlay.js";
+export { createYwebsocketSync } from "./yws-sync.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,4EAA4E;AAC5E,mEAAmE;AACnE,wDAAwD;AACxD,OAAO,EACN,uBAAuB,GAGvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,0BAA0B,EAA6B,MAAM,aAAa,CAAC;AACpF,OAAO,EAGN,iBAAiB,GACjB,MAAM,0BAA0B,CAAC;AAQlC,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,18 @@
+import type { UsketchPlugin } from "@edv4h/usketch-shared";
+import type { WsProviderHandle } from "@edv4h/usketch-sync";
+import type { YwebsocketSyncHandle, YwebsocketSyncOptions } from "./types.js";
+export interface YwebsocketSyncPlugin extends UsketchPlugin {
+    /**
+     * Returns the underlying `WsProviderHandle` for consumption by other plugins
+     * (e.g. `@edv4h/usketch-plugin-presence-cursor`).
+     *
+     * Only valid *after* the plugin's `setup()` has run. See the README for the
+     * recommended pattern (wrap the dependent plugin so it reads the provider
+     * from inside its own `setup()`).
+     */
+    getWsProvider(): WsProviderHandle;
+    /** Access the full sync handle — status, Y.Doc, disconnect/resume/destroy. */
+    getHandle(): YwebsocketSyncHandle;
+}
+export declare function createYwebsocketSyncPlugin(options: YwebsocketSyncOptions): YwebsocketSyncPlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAI9E,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IAC1D;;;;;;;OAOG;IACH,aAAa,IAAI,gBAAgB,CAAC;IAClC,8EAA8E;IAC9E,SAAS,IAAI,oBAAoB,CAAC;CAClC;AAID,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CAmE/F"}

package/dist/plugin.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { UnconfirmedOverlay } from "./unconfirmed-overlay.js";
+import { createYwebsocketSync } from "./yws-sync.js";
+const UNCONFIRMED_OVERLAY_LAYER_ID = "unconfirmed-shapes-overlay";
+export function createYwebsocketSyncPlugin(options) {
+    let handle = null;
+    let unregisterOverlay = null;
+    const plugin = {
+        id: "usketch-plugin-sync-ywebsocket",
+        name: "Realtime Sync (y-websocket)",
+        async setup(ctx) {
+            handle = createYwebsocketSync(ctx.store, options);
+            globalThis.__usketchSyncStatus = handle.status;
+            // Diagnostic overlay: draws a red badge on shapes that exist locally
+            // but haven't been confirmed by the server. Sits between standard
+            // shapes (default order) and the debug HUD (9999).
+            const overlayHandle = handle;
+            ctx.layers.register({
+                id: UNCONFIRMED_OVERLAY_LAYER_ID,
+                order: 250,
+                fixed: true,
+                render: (renderCtx) => (_jsx(UnconfirmedOverlay, { store: ctx.store, shapes: ctx.shapes, viewport: renderCtx.viewport, syncStatus: overlayHandle.status })),
+            });
+            unregisterOverlay = () => ctx.layers.unregister(UNCONFIRMED_OVERLAY_LAYER_ID);
+            // When `autoConnect: false`, `connect()` is never called, so awaiting
+            // `whenSynced` here would hang the entire plugin setup chain. Skip it
+            // and let the caller drive connection via `handle.resume()`.
+            if (options.autoConnect !== false) {
+                await handle.whenSynced;
+            }
+        },
+        teardown() {
+            unregisterOverlay?.();
+            unregisterOverlay = null;
+            handle?.destroy();
+            delete globalThis.__usketchSyncStatus;
+            handle = null;
+        },
+        getWsProvider() {
+            if (!handle) {
+                throw new Error("[usketch-plugin-sync-ywebsocket] getWsProvider() called before setup(); register the plugin with createApp() first, or call getWsProvider() from inside another plugin's setup().");
+            }
+            return handle.wsProvider;
+        },
+        getHandle() {
+            if (!handle) {
+                throw new Error("[usketch-plugin-sync-ywebsocket] getHandle() called before setup(); register the plugin with createApp() first, or call getHandle() from inside another plugin's setup().");
+            }
+            return handle;
+        },
+    };
+    return plugin;
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.tsx"],"names":[],"mappings":";AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAgBrD,MAAM,4BAA4B,GAAG,4BAA4B,CAAC;AAElE,MAAM,UAAU,0BAA0B,CAAC,OAA8B;IACxE,IAAI,MAAM,GAAgC,IAAI,CAAC;IAC/C,IAAI,iBAAiB,GAAwB,IAAI,CAAC;IAElD,MAAM,MAAM,GAAyB;QACpC,EAAE,EAAE,gCAAgC;QACpC,IAAI,EAAE,6BAA6B;QAEnC,KAAK,CAAC,KAAK,CAAC,GAAG;YACd,MAAM,GAAG,oBAAoB,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YACjD,UAAsC,CAAC,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;YAE5E,qEAAqE;YACrE,kEAAkE;YAClE,mDAAmD;YACnD,MAAM,aAAa,GAAG,MAAM,CAAC;YAC7B,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC;gBACnB,EAAE,EAAE,4BAA4B;gBAChC,KAAK,EAAE,GAAG;gBACV,KAAK,EAAE,IAAI;gBACX,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,CACtB,KAAC,kBAAkB,IAClB,KAAK,EAAE,GAAG,CAAC,KAAK,EAChB,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,QAAQ,EAAE,SAAS,CAAC,QAAQ,EAC5B,UAAU,EAAE,aAAa,CAAC,MAAM,GAC/B,CACF;aACD,CAAC,CAAC;YACH,iBAAiB,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,4BAA4B,CAAC,CAAC;YAE9E,sEAAsE;YACtE,sEAAsE;YACtE,6DAA6D;YAC7D,IAAI,OAAO,CAAC,WAAW,KAAK,KAAK,EAAE,CAAC;gBACnC,MAAM,MAAM,CAAC,UAAU,CAAC;YACzB,CAAC;QACF,CAAC;QAED,QAAQ;YACP,iBAAiB,EAAE,EAAE,CAAC;YACtB,iBAAiB,GAAG,IAAI,CAAC;YACzB,MAAM,EAAE,OAAO,EAAE,CAAC;YAClB,OAAQ,UAAsC,CAAC,mBAAmB,CAAC;YACnE,MAAM,GAAG,IAAI,CAAC;QACf,CAAC;QAED,aAAa;YACZ,IAAI,CAAC,MAAM,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACd,mLAAmL,CACnL,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC,UAAU,CAAC;QAC1B,CAAC;QAED,SAAS;YACR,IAAI,CAAC,MAAM,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CACd,2KAA2K,CAC3K,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC;QACf,CAAC;KACD,CAAC;IAEF,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/sync-status-tracker.d.ts

@@ -0,0 +1,112 @@
+export type SyncState = "loading" | "connecting" | "synced" | "syncing" | "disconnected" | "error";
+export interface SyncStatusSnapshot {
+    state: SyncState;
+    shapeCount: number;
+    /**
+     * Timestamp of the most recent activity that touched the snapshot — local
+     * mutations and server syncs alike. Useful for "last activity" displays
+     * but NOT a reliable indicator that the server has acknowledged anything.
+     * For divergence gating use `firstServerSyncAt` instead.
+     */
+    lastSyncedAt: number | null;
+    /**
+     * Timestamp of the first successful `setConfirmedFromServer(...)` call
+     * (i.e. the first `provider.on("sync", true)` event). Stays `null` until
+     * the server has actually merged its state with us. Set once and never
+     * cleared: a later disconnection should still allow consumers to surface
+     * divergence (offline edits accumulate exactly when the user needs the
+     * warning).
+     */
+    firstServerSyncAt: number | null;
+    error: string | null;
+    /**
+     * Shape IDs present in the local Y.Doc that the server has NOT confirmed.
+     *
+     * Populated by `noteShapeAdded(id, "local")` (a shape created locally that
+     * hasn't been seen by the server yet) and by `noteShapesLoaded(...)` for
+     * pre-connection IndexedDB restoration. Becomes accurate only **after** the
+     * first `setConfirmedFromServer(...)` (`sync` event with `isSynced: true`):
+     * before that, every shape from a persisted Y.Doc looks "local-only" because
+     * we genuinely don't know what the server holds yet.
+     *
+     * Consumers should gate divergence UI on `firstServerSyncAt !== null` so
+     * the warning isn't surfaced during the initial `loading` / `connecting`
+     * phase (every cold start would otherwise look full of "unconfirmed"
+     * shapes). Once that first server sync has happened, the gate stays open
+     * even across later disconnections.
+     */
+    unconfirmedShapeIds: readonly string[];
+}
+export declare class SyncStatusTracker {
+    private snapshot;
+    private listeners;
+    private readonly shapeIds;
+    private readonly confirmedShapeIds;
+    private batchDepth;
+    private batchDirty;
+    getSnapshot(): SyncStatusSnapshot;
+    subscribe(listener: () => void): () => void;
+    /**
+     * Update the "free-form" snapshot fields (state / shapeCount / lastSyncedAt
+     * / error). The divergence-tracking fields (`unconfirmedShapeIds` and
+     * `firstServerSyncAt`) are intentionally excluded so callers can't bypass
+     * the dedicated APIs and break the invariant that `firstServerSyncAt` is
+     * stamped exactly once on the first server sync.
+     *
+     * @internal
+     */
+    update(partial: Partial<Omit<SyncStatusSnapshot, "unconfirmedShapeIds" | "firstServerSyncAt">>): void;
+    /**
+     * Replace the "server-confirmed" set with the given IDs. Use this only when
+     * you have authoritative knowledge of which IDs the server has acknowledged
+     * — typically from y-websocket's `provider.on("sync")` event, where the
+     * Y.Map post-merge represents the union of (server view ∪ our uploads), so
+     * every current key IS confirmed.
+     *
+     * Do **not** call this with `shapesMap.keys()` if your transport can't tell
+     * you which keys originated from the server: that would silently confirm
+     * orphaned IndexedDB shapes the server never had, defeating the divergence
+     * detection. Use `markFirstServerSyncObserved()` + the `noteShapeAdded(...,
+     * "remote")` per-key path instead.
+     *
+     * Also stamps `firstServerSyncAt` on the first call so consumers can gate
+     * divergence UI on "have we ever heard back from the server?".
+     */
+    setConfirmedFromServer(ids: Iterable<string>): void;
+    /**
+     * Stamp `firstServerSyncAt` on the first call without touching the
+     * confirmed set. For transports that can't atomically tell you which
+     * shape IDs the server already knew at sync time (e.g. raw `WsProvider`
+     * without an `onSync` event), this is the right hook: the per-key
+     * `noteShapeAdded(id, "remote")` calls from the Y.Map observer fill in
+     * the confirmed set incrementally.
+     */
+    markFirstServerSyncObserved(): void;
+    private markFirstServerSyncObservedInternal;
+    /**
+     * Note a shape addition. `source = "remote"` means the shape arrived via the
+     * Yjs provider (server origin), so it's already confirmed. `source = "local"`
+     * means we created it client-side and the server has yet to acknowledge.
+     */
+    noteShapeAdded(id: string, source: "local" | "remote"): void;
+    /**
+     * Bulk variant of `noteShapeAdded` for initial load. Avoids the O(n²)
+     * cost of calling the single-shape mutator in a loop (each call would
+     * re-scan `shapeIds` and notify subscribers). Recompute and notify
+     * happen once after all IDs are ingested.
+     */
+    noteShapesLoaded(ids: Iterable<string>, source: "local" | "remote"): void;
+    noteShapeRemoved(id: string): void;
+    private recompute;
+    /**
+     * Combine multiple mutator calls into a single notification. Useful when
+     * the caller wants to e.g. `noteShapeAdded(...)` and `update({ shapeCount })`
+     * back-to-back without paying for two re-renders.
+     *
+     * Re-entrant: nested calls are tolerated, the listeners fire once when the
+     * outermost batch closes.
+     */
+    batch<T>(fn: () => T): T;
+    private notify;
+}
+//# sourceMappingURL=sync-status-tracker.d.ts.map

package/dist/sync-status-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-status-tracker.d.ts","sourceRoot":"","sources":["../src/sync-status-tracker.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,OAAO,CAAC;AAEnG,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B;;;;;;;OAOG;IACH,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;;;;;;;;;OAeG;IACH,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAOd;IACF,OAAO,CAAC,SAAS,CAAyB;IAG1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IAIvD,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,UAAU,CAAS;IAE3B,WAAW,IAAI,kBAAkB;IAIjC,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAO3C;;;;;;;;OAQG;IACH,MAAM,CACL,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,qBAAqB,GAAG,mBAAmB,CAAC,CAAC,GACrF,IAAI;IAKP;;;;;;;;;;;;;;;OAeG;IACH,sBAAsB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI;IAUnD;;;;;;;OAOG;IACH,2BAA2B,IAAI,IAAI;IAMnC,OAAO,CAAC,mCAAmC;IAM3C;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI;IAQ5D;;;;;OAKG;IACH,gBAAgB,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,IAAI;IAUzE,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMlC,OAAO,CAAC,SAAS;IAajB;;;;;;;OAOG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAaxB,OAAO,CAAC,MAAM;CAOd"}