@mp-lb/mdkit 0.2.3-main.21.1 → 0.2.4-main.25.1

package/dist/collaboration/useMdKitCollaboration.js

@@ -1,6 +1,50 @@
-import { useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
 import { HocuspocusProvider } from "@hocuspocus/provider";
 import * as Y from "yjs";
+const isCollaborationDebugEnabled = () => {
+    if (globalThis.__MDKIT_COLLAB_DEBUG__ ===
+        true) {
+        return true;
+    }
+    if (typeof window === "undefined") {
+        return false;
+    }
+    try {
+        return window.localStorage.getItem("mdkit:collab-debug") === "true";
+    }
+    catch {
+        return false;
+    }
+};
+const stringifyDebugDetails = (details) => {
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(details, (_key, value) => {
+            if (typeof value === "bigint") {
+                return value.toString();
+            }
+            if (!value || typeof value !== "object") {
+                return value;
+            }
+            if (seen.has(value)) {
+                return "[Circular]";
+            }
+            seen.add(value);
+            return value;
+        });
+    }
+    catch (error) {
+        return JSON.stringify({
+            serializationError: error instanceof Error ? error.message : "Unable to serialize details",
+        });
+    }
+};
+const debugCollaboration = (event, details) => {
+    if (!isCollaborationDebugEnabled()) {
+        return;
+    }
+    console.info(`MDKIT_COLLAB_DEBUG ${event} ${stringifyDebugDetails(details)}`);
+};
 const createColorFromId = (id) => {
     let hash = 0;
     for (let index = 0; index < id.length; index += 1) {
@@ -9,13 +53,84 @@ const createColorFromId = (id) => {
     }
     return `hsl(${Math.abs(hash) % 360}, 85%, 55%)`;
 };
+const parsePresence = (clientId, state, localClientId) => {
+    if (!state || typeof state !== "object") {
+        return null;
+    }
+    const user = "user" in state ? state.user : state;
+    if (!user || typeof user !== "object") {
+        return null;
+    }
+    const { color, id, imageUrl, name } = user;
+    if (typeof name !== "string") {
+        return null;
+    }
+    return {
+        clientId,
+        color: typeof color === "string"
+            ? color
+            : createColorFromId(typeof id === "string" ? id : String(clientId)),
+        id: typeof id === "string" ? id : String(clientId),
+        imageUrl: typeof imageUrl === "string" ? imageUrl : undefined,
+        isLocal: clientId === localClientId,
+        name,
+    };
+};
+const summarizeAwarenessState = (clientId, state) => {
+    if (!state || typeof state !== "object") {
+        return {
+            clientId,
+            hasState: false,
+        };
+    }
+    const user = "user" in state ? state.user : state;
+    return {
+        clientId,
+        hasCursor: "cursor" in state,
+        hasState: true,
+        hasUser: !!user,
+        user,
+    };
+};
+const summarizeParticipants = (participants) => participants.map((participant) => ({
+    clientId: participant.clientId,
+    id: participant.id,
+    isLocal: participant.isLocal,
+    name: participant.name,
+}));
+const areParticipantsEqual = (left, right) => left.length === right.length &&
+    left.every((leftParticipant, index) => {
+        const rightParticipant = right[index];
+        return (rightParticipant &&
+            leftParticipant.clientId === rightParticipant.clientId &&
+            leftParticipant.color === rightParticipant.color &&
+            leftParticipant.id === rightParticipant.id &&
+            leftParticipant.imageUrl === rightParticipant.imageUrl &&
+            leftParticipant.isLocal === rightParticipant.isLocal &&
+            leftParticipant.name === rightParticipant.name);
+    });
+const setProviderUser = (provider, collaborator) => {
+    provider.setAwarenessField("user", {
+        color: collaborator.color,
+        id: collaborator.id,
+        imageUrl: collaborator.imageUrl || undefined,
+        name: collaborator.name,
+    });
+};
 export const useMdKitCollaboration = (options) => {
     const { collaborator, documentId, enabled = true, endpoint, getToken, resolveRoomName, } = options;
     const [status, setStatus] = useState("disconnected");
+    const [participants, setParticipants] = useState([]);
+    const [provider, setProvider] = useState(null);
     const normalizedCollaborator = useMemo(() => ({
         ...collaborator,
         color: collaborator.color || createColorFromId(collaborator.id),
-    }), [collaborator]);
+    }), [
+        collaborator.color,
+        collaborator.id,
+        collaborator.imageUrl,
+        collaborator.name,
+    ]);
     const roomName = useMemo(() => {
         if (!documentId) {
             return "";
@@ -26,53 +141,223 @@ export const useMdKitCollaboration = (options) => {
         void roomName;
         return new Y.Doc();
     }, [roomName]);
-    const provider = useMemo(() => {
+    const setNextParticipants = useCallback((nextParticipants, source) => {
+        setParticipants((currentParticipants) => areParticipantsEqual(currentParticipants, nextParticipants)
+            ? currentParticipants
+            : (() => {
+                debugCollaboration("participants_update", {
+                    nextParticipants: summarizeParticipants(nextParticipants),
+                    previousParticipants: summarizeParticipants(currentParticipants),
+                    roomName,
+                    source,
+                });
+                return nextParticipants;
+            })());
+    }, [roomName]);
+    const updateParticipantsFromProvider = useCallback((nextProvider, source) => {
+        const awareness = nextProvider?.awareness;
+        if (!awareness) {
+            debugCollaboration("awareness_missing", {
+                roomName,
+                source,
+            });
+            setNextParticipants([], source);
+            return;
+        }
+        const rawStates = Array.from(awareness.getStates());
+        const nextParticipants = rawStates
+            .map(([clientId, state]) => parsePresence(clientId, state, ydoc.clientID))
+            .filter((presence) => Boolean(presence));
+        debugCollaboration("awareness_map_read", {
+            localClientId: ydoc.clientID,
+            parsedParticipants: summarizeParticipants(nextParticipants),
+            rawStates: rawStates.map(([clientId, state]) => summarizeAwarenessState(clientId, state)),
+            roomName,
+            source,
+        });
+        setNextParticipants(nextParticipants, source);
+    }, [roomName, setNextParticipants, ydoc.clientID]);
+    useEffect(() => {
         if (!enabled || !documentId || !endpoint) {
-            return null;
+            debugCollaboration("provider_skipped", {
+                documentId,
+                enabled,
+                endpoint,
+                roomName,
+            });
+            setProvider(null);
+            setStatus("disconnected");
+            setNextParticipants([], "provider_skipped");
+            return;
         }
-        return new HocuspocusProvider({
+        debugCollaboration("provider_create", {
+            collaborator: normalizedCollaborator,
+            documentId,
+            endpoint,
+            localClientId: ydoc.clientID,
+            roomName,
+        });
+        let nextProvider = null;
+        nextProvider = new HocuspocusProvider({
             document: ydoc,
             name: roomName,
-            onConnect: () => setStatus("connected"),
-            onDisconnect: () => setStatus("disconnected"),
+            onConnect: () => {
+                if (nextProvider) {
+                    setProviderUser(nextProvider, normalizedCollaborator);
+                }
+                debugCollaboration("provider_connect", {
+                    localClientId: ydoc.clientID,
+                    roomName,
+                });
+                setStatus("connected");
+                globalThis.setTimeout(() => {
+                    updateParticipantsFromProvider(nextProvider, "provider_connect");
+                }, 0);
+            },
+            onDisconnect: () => {
+                debugCollaboration("provider_disconnect", {
+                    localClientId: ydoc.clientID,
+                    roomName,
+                });
+                setStatus("disconnected");
+            },
             onStatus: ({ status: nextStatus }) => {
+                debugCollaboration("provider_status", {
+                    localClientId: ydoc.clientID,
+                    roomName,
+                    status: nextStatus,
+                });
                 if (nextStatus === "connecting") {
                     setStatus("connecting");
                 }
             },
+            onAwarenessChange: ({ states }) => {
+                debugCollaboration("provider_awareness_change", {
+                    localClientId: ydoc.clientID,
+                    rawStates: states,
+                    roomName,
+                });
+                updateParticipantsFromProvider(nextProvider, "provider_awareness_change");
+            },
             token: async () => {
                 const token = getToken ? await getToken() : null;
-                return token || "";
+                debugCollaboration("provider_token", {
+                    hasToken: !!token,
+                    roomName,
+                    source: getToken ? "custom" : "default",
+                });
+                return token || "notoken";
             },
             url: endpoint,
         });
-    }, [documentId, enabled, endpoint, getToken, roomName, ydoc]);
+        setProvider(nextProvider);
+        setStatus("connecting");
+        return () => {
+            nextProvider?.destroy();
+            nextProvider = null;
+            setProvider(null);
+            setStatus("disconnected");
+            setNextParticipants([], "provider_destroy");
+        };
+    }, [
+        documentId,
+        enabled,
+        endpoint,
+        getToken,
+        normalizedCollaborator,
+        roomName,
+        setNextParticipants,
+        updateParticipantsFromProvider,
+        ydoc,
+    ]);
+    useEffect(() => {
+        debugCollaboration("session_options", {
+            collaborator: normalizedCollaborator,
+            documentId,
+            enabled,
+            endpoint,
+            localClientId: ydoc.clientID,
+            roomName,
+        });
+    }, [
+        documentId,
+        enabled,
+        endpoint,
+        normalizedCollaborator,
+        roomName,
+        ydoc.clientID,
+    ]);
+    useEffect(() => {
+        debugCollaboration("session_state", {
+            isCollaborating: participants.some((participant) => !participant.isLocal),
+            participants: summarizeParticipants(participants),
+            roomName,
+            status: provider ? status : "disconnected",
+        });
+    }, [participants, provider, roomName, status]);
     useEffect(() => {
         if (!provider) {
             return;
         }
+        debugCollaboration("awareness_set_user", {
+            localClientId: ydoc.clientID,
+            roomName,
+            user: {
+                color: normalizedCollaborator.color,
+                id: normalizedCollaborator.id,
+                imageUrl: normalizedCollaborator.imageUrl || undefined,
+                name: normalizedCollaborator.name,
+            },
+        });
+        setProviderUser(provider, normalizedCollaborator);
+        updateParticipantsFromProvider(provider, "awareness_set_user");
+    }, [
+        normalizedCollaborator,
+        provider,
+        roomName,
+        updateParticipantsFromProvider,
+        ydoc.clientID,
+    ]);
+    useEffect(() => {
+        const awareness = provider?.awareness;
+        if (!awareness) {
+            debugCollaboration("awareness_effect_missing", {
+                roomName,
+            });
+            setNextParticipants([], "awareness_effect_missing");
+            return;
+        }
+        const handleAwarenessChange = () => updateParticipantsFromProvider(provider, "awareness_change_event");
+        awareness.on("change", handleAwarenessChange);
+        updateParticipantsFromProvider(provider, "awareness_change_subscribe");
         return () => {
-            provider.destroy();
+            awareness.off("change", handleAwarenessChange);
         };
-    }, [provider]);
+    }, [provider, roomName, setNextParticipants, updateParticipantsFromProvider]);
     useEffect(() => {
         if (!provider) {
             return;
         }
-        provider.setAwarenessField("user", {
-            color: normalizedCollaborator.color,
-            id: normalizedCollaborator.id,
-            imageUrl: normalizedCollaborator.imageUrl || undefined,
-            name: normalizedCollaborator.name,
-        });
-    }, [normalizedCollaborator, provider]);
+        const handleProviderAwareness = () => updateParticipantsFromProvider(provider, "provider_awareness_event");
+        provider.on("awarenessChange", handleProviderAwareness);
+        provider.on("awarenessUpdate", handleProviderAwareness);
+        updateParticipantsFromProvider(provider, "provider_awareness_subscribe");
+        return () => {
+            provider.off("awarenessChange", handleProviderAwareness);
+            provider.off("awarenessUpdate", handleProviderAwareness);
+        };
+    }, [provider, updateParticipantsFromProvider]);
     return useMemo(() => {
         if (!enabled || !documentId || !endpoint) {
             return null;
         }
+        const otherParticipants = participants.filter((participant) => !participant.isLocal);
         return {
             collaborator: normalizedCollaborator,
             document: ydoc,
+            isCollaborating: otherParticipants.length > 0,
+            otherParticipants,
+            participants,
             provider,
             roomName,
             status: provider ? status : "disconnected",
@@ -82,6 +367,7 @@ export const useMdKitCollaboration = (options) => {
         enabled,
         endpoint,
         normalizedCollaborator,
+        participants,
         provider,
         roomName,
         status,

package/dist/document/MdKitDocumentToolbar.js

@@ -9,6 +9,7 @@ const formatUpdatedAt = (updatedAt) => {
 };
 export const MdKitDocumentToolbar = ({ className, collaboration, document, onOpenConflict, onOpenVersionHistory, showConflictActions = false, versions, }) => {
     const [pendingAction, setPendingAction] = useState(null);
+    const otherCollaboratorCount = collaboration?.otherParticipants.length ?? 0;
     const runAction = async (name, action) => {
         setPendingAction(name);
         try {
@@ -19,6 +20,7 @@ export const MdKitDocumentToolbar = ({ className, collaboration, document, onOpe
         }
     };
     const hasVersionHistory = versions?.hasVersioning ?? false;
+    const hasActiveCollaborators = collaboration?.isCollaborating ?? false;
     const isBusy = pendingAction !== null || document.saveStatus === "saving";
     const status = document.conflict
         ? "Conflict"
@@ -33,16 +35,12 @@ export const MdKitDocumentToolbar = ({ className, collaboration, document, onOpe
                         : document.saveStatus === "saved"
                             ? "Saved"
                             : "Idle";
-    return (_jsxs("div", { className: joinClassNames("mp-lb-mdkit-document-toolbar", className), "data-conflict": document.conflict ? "true" : undefined, "data-dirty": document.isDirty ? "true" : undefined, "data-save-status": document.saveStatus, "data-status": status.toLowerCase().replace(/\s+/g, "-"), children: [_jsxs("div", { className: "mp-lb-mdkit-document-toolbar-status", children: [_jsx("strong", { children: status }), _jsx("span", { children: formatUpdatedAt(document.updatedAt) }), _jsxs("span", { children: ["Collaboration ", collaboration ? collaboration.status : "off"] })] }), document.error && !document.conflict ? (_jsx("div", { className: "mp-lb-mdkit-document-toolbar-error", children: document.error })) : null, _jsxs("div", { className: "mp-lb-mdkit-document-toolbar-actions", children: [_jsx("button", { type: "button", disabled: isBusy ||
-                            document.conflict ||
-                            !hasVersionHistory ||
-                            versions?.isLoading ||
-                            !onOpenVersionHistory, onClick: () => void runAction("versions", async () => {
+    return (_jsxs("div", { className: joinClassNames("mp-lb-mdkit-document-toolbar", className), "data-conflict": document.conflict ? "true" : undefined, "data-dirty": document.isDirty ? "true" : undefined, "data-save-status": document.saveStatus, "data-status": status.toLowerCase().replace(/\s+/g, "-"), children: [_jsxs("div", { className: "mp-lb-mdkit-document-toolbar-status", children: [_jsx("strong", { children: status }), _jsx("span", { children: formatUpdatedAt(document.updatedAt) }), hasActiveCollaborators ? (_jsxs("span", { children: [otherCollaboratorCount + 1, " collaborators"] })) : null] }), document.error && !document.conflict ? (_jsx("div", { className: "mp-lb-mdkit-document-toolbar-error", children: document.error })) : null, _jsxs("div", { className: "mp-lb-mdkit-document-toolbar-actions", children: [hasVersionHistory && onOpenVersionHistory ? (_jsx("button", { type: "button", disabled: isBusy || document.conflict || versions?.isLoading, onClick: () => void runAction("versions", async () => {
                             await versions?.refresh();
-                            await onOpenVersionHistory?.();
+                            await onOpenVersionHistory();
                         }), children: versions?.isLoading
                             ? "Loading versions..."
-                            : `Version ${String(document.version ?? "none")}` }), document.conflict && onOpenConflict ? (_jsx("button", { type: "button", className: "mp-lb-mdkit-document-toolbar-conflict-trigger", disabled: isBusy, onClick: () => void runAction("conflict", async () => {
+                            : `Version ${String(document.version ?? "none")}` })) : null, document.conflict && onOpenConflict ? (_jsx("button", { type: "button", className: "mp-lb-mdkit-document-toolbar-conflict-trigger", disabled: isBusy, onClick: () => void runAction("conflict", async () => {
                             await onOpenConflict();
                         }), children: "Resolve conflict" })) : null] }), document.conflict && showConflictActions ? (_jsxs("div", { className: "mp-lb-mdkit-document-toolbar-conflict", children: [_jsx("span", { children: "Remote changes conflict with local edits." }), _jsx("button", { type: "button", disabled: isBusy, onClick: () => void runAction("reload", document.resync), children: "Keep remote" }), _jsx("button", { type: "button", disabled: isBusy, onClick: () => void runAction("overwrite", document.forceSave), children: "Keep local" })] })) : null] }));
 };

package/dist/document/documentTypes.d.ts

@@ -48,9 +48,16 @@ export type MdKitCollaborationParticipant = {
     color?: string;
     imageUrl?: string;
 };
+export type MdKitCollaborationPresence = MdKitCollaborationParticipant & {
+    clientId: number;
+    isLocal: boolean;
+};
 export type MdKitCollaborationSession = {
     collaborator: MdKitCollaborationParticipant;
     document: Y.Doc;
+    isCollaborating: boolean;
+    otherParticipants: MdKitCollaborationPresence[];
+    participants: MdKitCollaborationPresence[];
     provider: HocuspocusProvider | null;
     roomName: string;
     status: MdKitCollaborationStatus;

package/dist/markdown/TiptapMarkdownSurface.js

@@ -72,6 +72,8 @@ export const TiptapMarkdownSurface = (props) => {
     const collaborationDocument = collaboration?.document ?? null;
     const collaborationProvider = collaboration?.provider ?? null;
     const collaborationUserColor = collaboration?.collaborator.color ?? "";
+    const collaborationUserId = collaboration?.collaborator.id ?? "";
+    const collaborationUserImageUrl = collaboration?.collaborator.imageUrl ?? "";
     const collaborationUserName = collaboration?.collaborator.name ?? "";
     const hasCollaboration = !!collaborationDocument;
     useEffect(() => {
@@ -103,11 +105,19 @@ export const TiptapMarkdownSurface = (props) => {
                 }),
                 user: {
                     color: collaborationUserColor,
+                    id: collaborationUserId,
+                    imageUrl: collaborationUserImageUrl || undefined,
                     name: collaborationUserName,
                 },
             }),
         ]
-        : [], [collaborationProvider, collaborationUserColor, collaborationUserName]);
+        : [], [
+        collaborationProvider,
+        collaborationUserColor,
+        collaborationUserId,
+        collaborationUserImageUrl,
+        collaborationUserName,
+    ]);
     const editor = useEditor({
         content: hasCollaboration
             ? undefined

package/dist/versioning/useMdKitDocumentVersions.d.ts

@@ -2,6 +2,7 @@ import type { MdKitDocumentAdapter, MdKitDocumentVersionDetail, MdKitDocumentVer
 export type UseMdKitDocumentVersionsOptions = {
     adapter: Pick<MdKitDocumentAdapter, "listDocumentVersions" | "readDocumentVersion">;
     documentId: string | null;
+    enabled?: boolean;
 };
 export type MdKitDocumentVersionsController = {
     error: string | null;

package/dist/versioning/useMdKitDocumentVersions.js

@@ -1,14 +1,14 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
 export const useMdKitDocumentVersions = (options) => {
-    const { adapter, documentId } = options;
+    const { adapter, documentId, enabled = true } = options;
     const [versions, setVersions] = useState([]);
     const [selectedVersionId, setSelectedVersionId] = useState(null);
     const [selectedVersion, setSelectedVersion] = useState(null);
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
-    const hasVersioning = !!adapter.listDocumentVersions && !!adapter.readDocumentVersion;
+    const hasVersioning = enabled && !!adapter.listDocumentVersions && !!adapter.readDocumentVersion;
     const refresh = useCallback(async () => {
-        if (!documentId || !adapter.listDocumentVersions) {
+        if (!hasVersioning || !documentId || !adapter.listDocumentVersions) {
             setVersions([]);
             setSelectedVersionId(null);
             setSelectedVersion(null);
@@ -34,9 +34,9 @@ export const useMdKitDocumentVersions = (options) => {
         finally {
             setIsLoading(false);
         }
-    }, [adapter, documentId]);
+    }, [adapter, documentId, hasVersioning]);
     const openVersion = useCallback(async (versionId) => {
-        if (!documentId || !adapter.readDocumentVersion) {
+        if (!hasVersioning || !documentId || !adapter.readDocumentVersion) {
             return;
         }
         setSelectedVersionId(versionId);
@@ -60,7 +60,7 @@ export const useMdKitDocumentVersions = (options) => {
         finally {
             setIsLoading(false);
         }
-    }, [adapter, documentId]);
+    }, [adapter, documentId, hasVersioning]);
     useEffect(() => {
         setSelectedVersionId(null);
         setSelectedVersion(null);

package/docs/index.md

@@ -177,8 +177,9 @@ and build your own workflow components.
 
 The backend starts with a store object. Replace `createYourDocumentStore()` with
 Postgres, MongoDB, Redis, files, or any other durable storage. Your store
-implements database primitives: read/write the current document, create/read
-checkpoints, restore a checkpoint, and optionally persist collaboration state.
+implements the [`MdKitBackendStore`](./api.md#mdkitbackendstore) interface:
+read/write the current document, create/read checkpoints, restore a checkpoint,
+and optionally persist collaboration state.
 The mdkit backend helper applies checkpoint policy and turns those primitives
 into tRPC or REST procedures. Application-owned metadata, auth, permissions,
 tenancy, and durable Yjs storage stay in your code; see

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mp-lb/mdkit",
-  "version": "0.2.3-main.21.1",
+  "version": "0.2.4-main.25.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",