@edv4h/usketch-plugin-sync-ywebsocket 1.1.0

package/dist/sync-status-tracker.js

@@ -0,0 +1,163 @@
+export class SyncStatusTracker {
+    snapshot = {
+        state: "loading",
+        shapeCount: 0,
+        lastSyncedAt: null,
+        firstServerSyncAt: null,
+        error: null,
+        unconfirmedShapeIds: [],
+    };
+    listeners = new Set();
+    // Local sources of truth for divergence calculation. Kept private so callers
+    // can only mutate via the dedicated methods below.
+    shapeIds = new Set();
+    confirmedShapeIds = new Set();
+    // Batch mode: while > 0, mutators skip notification and a single notify is
+    // fired when the batch closes. Used by yws-sync to combine `noteShapeAdded`
+    // + `update({ shapeCount, lastSyncedAt })` into one render per mutation.
+    batchDepth = 0;
+    batchDirty = false;
+    getSnapshot() {
+        return this.snapshot;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * 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) {
+        this.snapshot = { ...this.snapshot, ...partial };
+        this.notify();
+    }
+    /**
+     * 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) {
+        this.confirmedShapeIds.clear();
+        for (const id of ids)
+            this.confirmedShapeIds.add(id);
+        // Ensure shapeIds is a superset (ids that exist server-side must exist
+        // locally too — they were just merged into our doc).
+        for (const id of this.confirmedShapeIds)
+            this.shapeIds.add(id);
+        this.markFirstServerSyncObservedInternal();
+        this.recompute();
+    }
+    /**
+     * 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() {
+        if (this.snapshot.firstServerSyncAt !== null)
+            return;
+        this.markFirstServerSyncObservedInternal();
+        this.notify();
+    }
+    markFirstServerSyncObservedInternal() {
+        if (this.snapshot.firstServerSyncAt === null) {
+            this.snapshot = { ...this.snapshot, firstServerSyncAt: Date.now() };
+        }
+    }
+    /**
+     * 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, source) {
+        this.shapeIds.add(id);
+        if (source === "remote") {
+            this.confirmedShapeIds.add(id);
+        }
+        this.recompute();
+    }
+    /**
+     * 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, source) {
+        for (const id of ids) {
+            this.shapeIds.add(id);
+            if (source === "remote") {
+                this.confirmedShapeIds.add(id);
+            }
+        }
+        this.recompute();
+    }
+    noteShapeRemoved(id) {
+        this.shapeIds.delete(id);
+        this.confirmedShapeIds.delete(id);
+        this.recompute();
+    }
+    recompute() {
+        const unconfirmed = [];
+        for (const id of this.shapeIds) {
+            if (!this.confirmedShapeIds.has(id))
+                unconfirmed.push(id);
+        }
+        this.snapshot = {
+            ...this.snapshot,
+            shapeCount: this.shapeIds.size,
+            unconfirmedShapeIds: unconfirmed,
+        };
+        this.notify();
+    }
+    /**
+     * 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(fn) {
+        this.batchDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            this.batchDepth--;
+            if (this.batchDepth === 0 && this.batchDirty) {
+                this.batchDirty = false;
+                this.notify();
+            }
+        }
+    }
+    notify() {
+        if (this.batchDepth > 0) {
+            this.batchDirty = true;
+            return;
+        }
+        for (const listener of this.listeners)
+            listener();
+    }
+}
+//# sourceMappingURL=sync-status-tracker.js.map

package/dist/sync-status-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-status-tracker.js","sourceRoot":"","sources":["../src/sync-status-tracker.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,91 @@
+import type { WsConnectionStatus, WsProviderHandle } from "@edv4h/usketch-sync";
+import type * as Y from "yjs";
+import type { SyncStatusTracker } from "./sync-status-tracker.js";
+export interface ConnectionParams {
+    /** URL query params to attach on each connection attempt. */
+    params?: Record<string, string>;
+}
+export interface ResolveParamsContext {
+    /**
+     * Backoff attempt counter — 0 on the first connect, increments with each
+     * failed reconnect cycle, and resets to 0 whenever an `onCloseCode` handler
+     * returns `"retry"` (explicit retries skip the backoff ramp).
+     */
+    attempt: number;
+    /** Optional close code from the previous disconnect (if any). */
+    previousCloseCode?: number;
+    /** Optional close reason from the previous disconnect (if any). */
+    previousCloseReason?: string;
+}
+export interface YwebsocketSyncOptions {
+    /** Base URL of the y-websocket server (e.g. "wss://yws.example.com"). */
+    url: string;
+    /** Room name — the document identifier on the server. */
+    roomName: string;
+    /**
+     * The Yjs map key that stores shapes. Defaults to `"shapes"`.
+     * Use this when connecting to a server that expects a different key (e.g. weboard uses `"map"`).
+     */
+    shapesMapKey?: string;
+    /**
+     * Resolve URL query params on each connection attempt.
+     * Called before every connect/reconnect — return freshly refreshed query params
+     * or tokens here. If omitted, no query params are attached.
+     */
+    resolveParams?: (ctx: ResolveParamsContext) => Promise<ConnectionParams> | ConnectionParams;
+    /**
+     * Custom close-code handler. Called whenever the underlying socket closes.
+     * Return `"retry"` to trigger an immediate reconnect (bypassing backoff),
+     * `"stop"` to give up and leave the provider disconnected,
+     * or `undefined` to fall through to the default backoff retry.
+     */
+    onCloseCode?: (code: number, reason: string) => "retry" | "stop" | undefined;
+    /**
+     * Disconnect automatically after this many milliseconds of inactivity.
+     * The timer resets on local store mutations, when the socket reports `connected`,
+     * and when `resume()` is called. Set to `0` (or omit) to disable.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Explicitly opt in/out of the initial `connect` call.
+     * Defaults to `true` — the provider connects on creation.
+     */
+    autoConnect?: boolean;
+    /**
+     * Provide an existing Y.Doc to sync. If omitted, a new Y.Doc is created.
+     * Weboard's migration path can pass in a pre-existing Y.Doc that already holds legacy state.
+     */
+    doc?: Y.Doc;
+    /**
+     * WebSocket constructor polyfill (for Node test environments).
+     * In the browser, this is picked up from `globalThis.WebSocket` automatically.
+     */
+    WebSocketPolyfill?: typeof WebSocket;
+}
+export interface YwebsocketSyncHandle {
+    /** The Y.Doc being synced. */
+    doc: Y.Doc;
+    /** Observable sync status (loading/synced/disconnected/error). */
+    status: SyncStatusTracker;
+    /**
+     * Resolves when the first server sync completes, when `resolveParams` fails the
+     * initial attempt, when `onCloseCode` returns `"stop"`, or on `destroy()`.
+     * Resolves, never rejects — inspect `status.getSnapshot()` for the latest state
+     * (in particular `state === "error"` / `"disconnected"`) to detect failure modes.
+     */
+    whenSynced: Promise<void>;
+    /**
+     * WsProviderHandle-compatible adapter. Plug this into `@edv4h/usketch-plugin-presence-cursor`
+     * (and similar plugins) that accept a `WsProviderHandle`.
+     * Broadcast / partition APIs are no-ops (y-websocket has no equivalent).
+     */
+    wsProvider: WsProviderHandle;
+    /** Manually disconnect. The provider stays disconnected until `resume()` is called. */
+    disconnect(): void;
+    /** Reconnect after a manual `disconnect()` or an idle timeout. */
+    resume(): void;
+    /** Tear down all resources — removes listeners, destroys provider and awareness. */
+    destroy(): void;
+}
+export type { WsConnectionStatus };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAC;AAC9B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAChC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACpC;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mEAAmE;IACnE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACrC,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,gBAAgB,CAAC,GAAG,gBAAgB,CAAC;IAE5F;;;;;OAKG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAE7E;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC;IAEZ;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACpC,8BAA8B;IAC9B,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC;IACX,kEAAkE;IAClE,MAAM,EAAE,iBAAiB,CAAC;IAC1B;;;;;OAKG;IACH,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1B;;;;OAIG;IACH,UAAU,EAAE,gBAAgB,CAAC;IAE7B,uFAAuF;IACvF,UAAU,IAAI,IAAI,CAAC;IACnB,kEAAkE;IAClE,MAAM,IAAI,IAAI,CAAC;IAEf,oFAAoF;IACpF,OAAO,IAAI,IAAI,CAAC;CAChB;AAED,YAAY,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/unconfirmed-overlay.d.ts

@@ -0,0 +1,21 @@
+import type { BoardStore, ShapeRegistry, Viewport } from "@edv4h/usketch-shared";
+import type { SyncStatusTracker } from "./sync-status-tracker.js";
+interface UnconfirmedOverlayProps {
+    store: BoardStore;
+    shapes: ShapeRegistry;
+    viewport: Viewport;
+    syncStatus: SyncStatusTracker;
+}
+/**
+ * SVG overlay that draws a small red exclamation badge on the top-right corner
+ * of any shape whose ID appears in `syncStatus.getSnapshot().unconfirmedShapeIds`
+ * — i.e. shapes that exist in the local Y.Doc but the server hasn't
+ * acknowledged. The debug HUD uses the `⚠` glyph; here we render a circle +
+ * `!` so the badge stays legible at small zoom levels where multi-codepoint
+ * emoji distort.
+ *
+ * This is purely diagnostic; clicks pass through to the underlying shape.
+ */
+export declare function UnconfirmedOverlay({ store, shapes, viewport, syncStatus, }: UnconfirmedOverlayProps): import("react/jsx-runtime").JSX.Element | null;
+export {};
+//# sourceMappingURL=unconfirmed-overlay.d.ts.map

package/dist/unconfirmed-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unconfirmed-overlay.d.ts","sourceRoot":"","sources":["../src/unconfirmed-overlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,UAAU,uBAAuB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,aAAa,CAAC;IACtB,QAAQ,EAAE,QAAQ,CAAC;IACnB,UAAU,EAAE,iBAAiB,CAAC;CAC9B;AAMD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EAClC,KAAK,EACL,MAAM,EACN,QAAQ,EACR,UAAU,GACV,EAAE,uBAAuB,kDAqCzB"}

package/dist/unconfirmed-overlay.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useSyncExternalStore } from "react";
+const BADGE_FILL = "#dc2626";
+const BADGE_RADIUS = 9;
+const BADGE_OFFSET = 4;
+/**
+ * SVG overlay that draws a small red exclamation badge on the top-right corner
+ * of any shape whose ID appears in `syncStatus.getSnapshot().unconfirmedShapeIds`
+ * — i.e. shapes that exist in the local Y.Doc but the server hasn't
+ * acknowledged. The debug HUD uses the `⚠` glyph; here we render a circle +
+ * `!` so the badge stays legible at small zoom levels where multi-codepoint
+ * emoji distort.
+ *
+ * This is purely diagnostic; clicks pass through to the underlying shape.
+ */
+export function UnconfirmedOverlay({ store, shapes, viewport, syncStatus, }) {
+    // Keep `subscribe` / `getSnapshot` identities stable across renders so that
+    // re-renders triggered by viewport changes don't churn through unsubscribe
+    // /resubscribe cycles. Dependent only on `syncStatus`, which is itself
+    // stable for the lifetime of the plugin.
+    const subscribe = useCallback((listener) => syncStatus.subscribe(listener), [syncStatus]);
+    const getSnapshot = useCallback(() => syncStatus.getSnapshot(), [syncStatus]);
+    const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+    // Only surface divergence after the server has confirmed us at least once.
+    // `firstServerSyncAt` is set exactly by `setConfirmedFromServer(...)` so
+    // it's the only field that means "we've actually heard back from the
+    // server" — `lastSyncedAt` also moves on local edits and would let warnings
+    // leak out during the initial connecting phase. Once set, the gate stays
+    // open across later disconnections so offline edits surface as divergence.
+    if (snapshot.firstServerSyncAt === null)
+        return null;
+    if (snapshot.unconfirmedShapeIds.length === 0)
+        return null;
+    return (_jsxs("svg", { style: {
+            position: "absolute",
+            inset: 0,
+            width: "100%",
+            height: "100%",
+            pointerEvents: "none",
+        }, children: [_jsx("title", { children: "\u30B5\u30FC\u30D0\u672A\u540C\u671F Shape" }), snapshot.unconfirmedShapeIds.map((id) => (_jsx(UnconfirmedBadge, { store: store, shapes: shapes, viewport: viewport, shapeId: id }, id)))] }));
+}
+function UnconfirmedBadge({ store, shapes, viewport, shapeId, }) {
+    const shape = store.getShape(shapeId);
+    if (!shape)
+        return null;
+    // Use the shape definition's bounds when available, falling back to the
+    // raw `x/y/width/height` for shapes without a registered type (e.g. legacy
+    // shape types that disappeared after a refactor — the very case this
+    // overlay was designed to surface).
+    const def = shapes.get(shape.type);
+    const bounds = def?.getBounds(shape) ?? {
+        x: shape.x,
+        y: shape.y,
+        width: shape.width,
+        height: shape.height,
+    };
+    const cx = (bounds.x + bounds.width) * viewport.zoom + viewport.x + BADGE_OFFSET;
+    const cy = bounds.y * viewport.zoom + viewport.y - BADGE_OFFSET;
+    return (_jsxs("g", { children: [_jsx("title", { children: `${shape.type} (${shapeId.slice(0, 8)}…) — サーバに存在しません` }), _jsx("circle", { cx: cx, cy: cy, r: BADGE_RADIUS, fill: BADGE_FILL }), _jsx("text", { x: cx, y: cy + 1, textAnchor: "middle", dominantBaseline: "middle", fontSize: 11, fontWeight: 700, fill: "#ffffff", style: { userSelect: "none" }, children: "!" })] }));
+}
+//# sourceMappingURL=unconfirmed-overlay.js.map

package/dist/unconfirmed-overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unconfirmed-overlay.js","sourceRoot":"","sources":["../src/unconfirmed-overlay.tsx"],"names":[],"mappings":"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"}

package/dist/yws-sync.d.ts

@@ -0,0 +1,4 @@
+import type { BoardStore } from "@edv4h/usketch-shared";
+import type { YwebsocketSyncHandle, YwebsocketSyncOptions } from "./types.js";
+export declare function createYwebsocketSync(store: BoardStore, options: YwebsocketSyncOptions): YwebsocketSyncHandle;
+//# sourceMappingURL=yws-sync.d.ts.map

package/dist/yws-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yws-sync.d.ts","sourceRoot":"","sources":["../src/yws-sync.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAa,MAAM,uBAAuB,CAAC;AAMnE,OAAO,KAAK,EAAwB,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAWpG,wBAAgB,oBAAoB,CACnC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,qBAAqB,GAC5B,oBAAoB,CAqgBtB"}