snapshot of https://github.com/ueberdosis/hocuspocus.git @ cf3cfa355b4d3bb61c6b6c80071f71783e32470e (2026-09-15)

playground/frontend/app/articles/[slug]/ArticleEditor.tsx

@@ -0,0 +1,174 @@
+"use client";
+
+import { SocketContext1 } from "@/app/SocketContext1";
+import { SocketContext2 } from "@/app/SocketContext2";
+import CollaborationStatus from "@/app/articles/[slug]/CollaborationStatus";
+import CollaborativeEditor from "@/app/articles/[slug]/CollaborativeEditor";
+import {
+	HocuspocusProvider,
+	HocuspocusProviderWebsocket,
+} from "@hocuspocus/provider";
+// import { TiptapCollabProvider } from "@tiptap-cloud/provider";
+import { useContext, useEffect, useState } from "react";
+
+export default function ArticleEditor({ slug }: { slug: string }) {
+	const socket1 = useContext(SocketContext1);
+	const socket2 = useContext(SocketContext2);
+
+	const [provider1, setProvider1] = useState<HocuspocusProvider>();
+	const [provider2, setProvider2] = useState<HocuspocusProvider>();
+
+	useEffect(() => {
+		if (!socket1 || !socket2) return;
+
+		// Create separate providers for each editor
+		const _p1 = new HocuspocusProvider({
+			websocketProvider: socket1,
+			name: slug,
+			onOpen: (data) => console.log("Editor 1 onOpen!", data),
+			onClose: (data) => console.log("Editor 1 onClose!", data),
+			onAuthenticated: (data) => console.log("Editor 1 onAuthenticated!", data),
+			onAuthenticationFailed: (data) =>
+				console.log("Editor 1 onAuthenticationFailed", data),
+			onUnsyncedChanges: (data) =>
+				console.log("Editor 1 onUnsyncedChanges", data),
+			onStatus(data) {
+				console.log("editor 1 onStatus", data);
+			},
+		});
+
+		const _p2 = new HocuspocusProvider({
+			websocketProvider: socket2,
+			name: slug,
+			onOpen: (data) => console.log("Editor 2 onOpen!", data),
+			onClose: (data) => console.log("Editor 2 onClose!", data),
+			onAuthenticated: (data) => console.log("Editor 2 onAuthenticated!", data),
+			onAuthenticationFailed: (data) =>
+				console.log("Editor 2 onAuthenticationFailed", data),
+			onUnsyncedChanges: (data) =>
+				console.log("Editor 2 onUnsyncedChanges", data),
+			onStatus(data) {
+				console.log("editor 2 onStatus", data);
+			},
+		});
+
+		setProvider1(_p1);
+		setProvider2(_p2);
+
+		return () => {
+			_p1.destroy();
+			_p2.destroy();
+		};
+	}, [socket1, socket2, slug]);
+
+	if (!provider1 || !provider2) {
+		return <></>;
+	}
+
+	// you need to attach here, to make sure the connection gets properly established due to React strict-mode re-run of hooks
+	provider1.attach();
+	provider2.attach();
+
+	return (
+		<div className="flex flex-col min-h-screen">
+			{/* Header */}
+			<header className="bg-white/80 dark:bg-slate-900/80 backdrop-blur-sm border-b border-slate-200 dark:border-slate-700">
+				<div className="px-8 py-6">
+					<div className="flex items-center justify-between">
+						<div>
+							<h1 className="text-2xl font-bold text-slate-900 dark:text-white">
+								Article #{slug}
+							</h1>
+							<p className="text-slate-600 dark:text-slate-400 mt-1">
+								Real-time collaborative editing - Two editors demonstrating sync
+							</p>
+						</div>
+					</div>
+				</div>
+			</header>
+
+			{/* Main content */}
+			<main className="flex-1 p-8">
+				<div className="max-w-7xl mx-auto space-y-6">
+					{/* Editors side by side */}
+					<div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+						{/* Editor 1 */}
+						<div className="space-y-4">
+							<div className="flex items-center justify-between">
+								<h2 className="text-lg font-semibold text-slate-900 dark:text-white">
+									Editor 1
+								</h2>
+								<span className="text-sm text-slate-500 dark:text-slate-400">
+									Independent WebSocket connection
+								</span>
+							</div>
+
+							{/* Status Panel 1 */}
+							<CollaborationStatus provider={provider1} />
+
+							{/* Editor 1 */}
+							<div className="bg-white/30 dark:bg-slate-900/30 backdrop-blur-sm rounded-2xl p-6 border border-slate-200 dark:border-slate-700 shadow-xl">
+								<CollaborativeEditor slug={slug} provider={provider1} />
+							</div>
+						</div>
+
+						{/* Editor 2 */}
+						<div className="space-y-4">
+							<div className="flex items-center justify-between">
+								<h2 className="text-lg font-semibold text-slate-900 dark:text-white">
+									Editor 2
+								</h2>
+								<span className="text-sm text-slate-500 dark:text-slate-400">
+									Independent WebSocket connection
+								</span>
+							</div>
+
+							{/* Status Panel 2 */}
+							<CollaborationStatus provider={provider2} />
+
+							{/* Editor 2 */}
+							<div className="bg-white/30 dark:bg-slate-900/30 backdrop-blur-sm rounded-2xl p-6 border border-slate-200 dark:border-slate-700 shadow-xl">
+								<CollaborativeEditor slug={slug} provider={provider2} />
+							</div>
+						</div>
+					</div>
+
+					{/* Info panel */}
+					<div className="bg-blue-50/50 dark:bg-blue-900/20 backdrop-blur-sm rounded-xl border border-blue-200 dark:border-blue-700 p-6">
+						<div className="flex items-start space-x-3">
+							<div className="flex-shrink-0">
+								<div className="w-8 h-8 bg-blue-100 dark:bg-blue-900/40 rounded-full flex items-center justify-center">
+									<svg
+										className="w-4 h-4 text-blue-600 dark:text-blue-400"
+										fill="none"
+										stroke="currentColor"
+										viewBox="0 0 24 24"
+									>
+										<path
+											strokeLinecap="round"
+											strokeLinejoin="round"
+											strokeWidth={2}
+											d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z"
+										/>
+									</svg>
+								</div>
+							</div>
+							<div>
+								<h3 className="text-sm font-medium text-blue-900 dark:text-blue-100">
+									Real-time Collaboration Demo
+								</h3>
+								<p className="text-sm text-blue-700 dark:text-blue-300 mt-1">
+									Both editors are connected to the same document but use
+									separate WebSocket connections. Changes made in one editor
+									will appear in the other in real-time. Try typing in either
+									editor or use the connection controls to test synchronization
+									behavior.
+								</p>
+							</div>
+						</div>
+					</div>
+				</div>
+			</main>
+		</div>
+	);
+}

playground/frontend/app/articles/[slug]/CollaborationStatus.tsx

@@ -0,0 +1,184 @@
+import type {
+	HocuspocusProvider,
+	onStatusParameters,
+	onUnsyncedChangesParameters,
+} from "@hocuspocus/provider";
+import { useEffect, useState } from "react";
+
+const CollaborationStatus = (props: {
+	provider: HocuspocusProvider;
+}) => {
+	const { provider } = props;
+
+	const [unsyncedChanges, setUnsyncedChanges] = useState(0);
+	const [socketStatus, setSocketStatus] = useState<string | null>(null);
+	const [isAttached, _setAttached] = useState<boolean>(false);
+
+	useEffect(() => {
+		setSocketStatus(provider.configuration.websocketProvider.status);
+		_setAttached(provider.isAttached);
+
+		const handleUnsyncedChanges = (changes: onUnsyncedChangesParameters) => {
+			setUnsyncedChanges(changes.number);
+		};
+
+		const handleSocketStatus = (status: onStatusParameters) => {
+			setSocketStatus(status.status);
+		};
+
+		provider.on("unsyncedChanges", handleUnsyncedChanges);
+		provider.configuration.websocketProvider.on("status", handleSocketStatus);
+
+		return () => {
+			provider.off("unsyncedChanges", handleUnsyncedChanges);
+			provider.configuration.websocketProvider.off(
+				"status",
+				handleSocketStatus,
+			);
+		};
+	}, [provider]);
+
+	const updateAttached = (attach: boolean) => {
+		if (attach) {
+			provider.attach();
+		} else {
+			provider.detach();
+		}
+
+		_setAttached(provider.isAttached);
+	};
+
+	const getStatusColor = (status: string | null) => {
+		switch (status) {
+			case "connected":
+				return "bg-green-100 text-green-800 dark:bg-green-900/20 dark:text-green-400";
+			case "connecting":
+				return "bg-yellow-100 text-yellow-800 dark:bg-yellow-900/20 dark:text-yellow-400";
+			case "disconnected":
+				return "bg-red-100 text-red-800 dark:bg-red-900/20 dark:text-red-400";
+			default:
+				return "bg-slate-100 text-slate-800 dark:bg-slate-800 dark:text-slate-400";
+		}
+	};
+
+	const UNSYNCED_THRESHOLD = 10;
+
+	return (
+		<div className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm rounded-xl border border-slate-200 dark:border-slate-700 p-6">
+			{/* Alert banner when unsynced changes grow — indicates connection issues */}
+			{unsyncedChanges >= UNSYNCED_THRESHOLD && (
+				<div className="mb-4 p-3 bg-red-50 dark:bg-red-900/20 border border-red-200 dark:border-red-800 rounded-lg flex items-center space-x-3">
+					<div className="w-5 h-5 shrink-0 text-red-600 dark:text-red-400">
+						<svg fill="none" stroke="currentColor" viewBox="0 0 24 24">
+							<path
+								strokeLinecap="round"
+								strokeLinejoin="round"
+								strokeWidth={2}
+								d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z"
+							/>
+						</svg>
+					</div>
+					<div>
+						<p className="text-sm font-medium text-red-800 dark:text-red-200">
+							Connection issue detected
+						</p>
+						<p className="text-xs text-red-600 dark:text-red-400">
+							{unsyncedChanges} changes are waiting to sync. Your edits are
+							saved locally but not yet on the server.
+						</p>
+					</div>
+				</div>
+			)}
+
+			{/* Status indicators */}
+			<div className="flex items-center justify-between mb-6">
+				<h3 className="text-lg font-semibold text-slate-900 dark:text-white">
+					Connection Status
+				</h3>
+				<div className="flex items-center space-x-4">
+					<div className="flex items-center space-x-2">
+						<div
+							className={`w-3 h-3 rounded-full ${socketStatus === "connected" ? "bg-green-500" : socketStatus === "connecting" ? "bg-yellow-500" : "bg-red-500"}`}
+						></div>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${getStatusColor(socketStatus)}`}
+						>
+							{socketStatus || "Unknown"}
+						</span>
+					</div>
+					<div className="flex items-center space-x-2">
+						<div
+							className={`w-3 h-3 rounded-full ${provider.isAttached ? "bg-green-500" : "bg-red-500"}`}
+						></div>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${provider.isAttached ? "bg-green-100 text-green-800 dark:bg-green-900/20 dark:text-green-400" : "bg-red-100 text-red-800 dark:bg-red-900/20 dark:text-red-400"}`}
+						>
+							{isAttached ? "Attached" : "Detached"}
+						</span>
+					</div>
+					<div className="flex items-center space-x-2">
+						<div
+							className={`w-3 h-3 rounded-full ${unsyncedChanges >= UNSYNCED_THRESHOLD ? "bg-red-500 animate-pulse" : "bg-orange-500 animate-pulse"}`}
+						></div>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${unsyncedChanges >= UNSYNCED_THRESHOLD ? "bg-red-100 text-red-800 dark:bg-red-900/20 dark:text-red-400" : "bg-orange-100 text-orange-800 dark:bg-orange-900/20 dark:text-orange-400"}`}
+						>
+							{unsyncedChanges} unsynced
+						</span>
+					</div>
+				</div>
+			</div>
+
+			{/* Control buttons */}
+			<div className="grid grid-cols-2 gap-6">
+				<div className="space-y-3">
+					<h4 className="text-sm font-medium text-slate-700 dark:text-slate-300">
+						WebSocket Controls
+					</h4>
+					<div className="flex space-x-2">
+						<button
+							className="flex-1 px-3 py-2 bg-red-500 hover:bg-red-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() =>
+								provider.configuration.websocketProvider.disconnect()
+							}
+							disabled={socketStatus === "disconnected"}
+						>
+							Disconnect
+						</button>
+						<button
+							className="flex-1 px-3 py-2 bg-green-500 hover:bg-green-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() => provider.configuration.websocketProvider.connect()}
+							disabled={socketStatus === "connected"}
+						>
+							Connect
+						</button>
+					</div>
+				</div>
+
+				<div className="space-y-3">
+					<h4 className="text-sm font-medium text-slate-700 dark:text-slate-300">
+						Provider Controls
+					</h4>
+					<div className="flex space-x-2">
+						<button
+							className="flex-1 px-3 py-2 bg-orange-500 hover:bg-orange-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() => updateAttached(false)}
+							disabled={!isAttached}
+						>
+							Detach
+						</button>
+						<button
+							className="flex-1 px-3 py-2 bg-blue-500 hover:bg-blue-600 text-white text-sm font-medium rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
+							onClick={() => updateAttached(true)}
+							disabled={isAttached}
+						>
+							Attach
+						</button>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+};
+
+export default CollaborationStatus;

playground/frontend/app/articles/[slug]/CollaborativeEditor.tsx

@@ -0,0 +1,65 @@
+"use client";
+
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+import { Collaboration } from "@tiptap/extension-collaboration";
+import { CollaborationCaret } from "@tiptap/extension-collaboration-caret";
+import { EditorContent, useEditor } from "@tiptap/react";
+import { StarterKit } from "@tiptap/starter-kit";
+import * as Y from "yjs";
+
+const initialContent = [
+	1, 3, 223, 175, 255, 141, 2, 0, 7, 1, 7, 100, 101, 102, 97, 117, 108, 116, 3,
+	9, 112, 97, 114, 97, 103, 114, 97, 112, 104, 7, 0, 223, 175, 255, 141, 2, 0,
+	6, 4, 0, 223, 175, 255, 141, 2, 1, 17, 72, 101, 108, 108, 111, 32, 87, 111,
+	114, 108, 100, 33, 32, 240, 159, 140, 142, 0,
+];
+
+const CollaborativeEditor = (props: {
+	slug: string;
+	provider: HocuspocusProvider;
+}) => {
+	/**
+	 * if you want to load initial content to the editor, the safest way to do so is by applying an initial Yjs update.
+	 * Yjs updates can safely be applied multiple times, while using `setContent` or similar Tiptap commands may result in
+	 * duplicate content in the Tiptap editor.
+	 *
+	 * The easiest way to generate the Yjs update (`initialContent` above) is to do something like
+	 *
+	 * ```
+	 * console.log(Y.encodeStateAsUpdate(provider.props.document).toString())
+	 * ```
+	 *
+	 * after you have filled the editor with the desired content.
+	 */
+	Y.applyUpdate(props.provider.document, Uint8Array.from(initialContent));
+
+	const editor = useEditor(
+		{
+			extensions: [
+				// make sure to turn off the undo-redo extension when using collaboration
+				StarterKit.configure({
+          undoRedo: false,
+        }),
+				Collaboration.configure({
+					document: props.provider.document,
+				}),
+				CollaborationCaret.configure({
+					provider: props.provider,
+				}),
+			],
+			// immediatelyRender needs to be `false` when using SSR
+			immediatelyRender: false,
+			editorProps: {
+				attributes: {
+					class:
+						"prose prose-lg max-w-none focus:outline-none min-h-[500px] p-8 bg-white/50 dark:bg-slate-900/50 rounded-xl border border-slate-200 dark:border-slate-700 shadow-sm",
+				},
+			},
+		},
+		[props.provider.document],
+	);
+
+	return <EditorContent editor={editor} />;
+};
+
+export default CollaborativeEditor;

playground/frontend/app/articles/[slug]/page.tsx

@@ -0,0 +1,10 @@
+import ArticleEditor from "@/app/articles/[slug]/ArticleEditor";
+
+export default async function Home(props: {
+	params: Promise<{ slug: string }>;
+}) {
+	const params = await props.params;
+	const slug = params.slug;
+
+	return <ArticleEditor slug={slug} />;
+}

playground/frontend/app/articles/layout.tsx

@@ -0,0 +1,53 @@
+"use client";
+
+import { HocuspocusProviderWebsocket } from "@hocuspocus/provider";
+// import {
+// 	TiptapCollabProvider,
+// 	TiptapCollabProviderWebsocket,
+// } from "@tiptap-cloud/provider";
+import { useEffect, useState } from "react";
+import { SocketContext1 } from "@/app/SocketContext1";
+import { SocketContext2 } from "@/app/SocketContext2";
+
+export default function Layout({
+	children,
+}: Readonly<{
+	children: React.ReactNode;
+}>) {
+	const [socket1, setSocket1] = useState<HocuspocusProviderWebsocket | null>(
+		null,
+	);
+	const [socket2, setSocket2] = useState<HocuspocusProviderWebsocket | null>(
+		null,
+	);
+
+	useEffect(() => {
+		const newlyCreatedSocket1 = new HocuspocusProviderWebsocket({
+			url: "ws://localhost:8000",
+		});
+		const newlyCreatedSocket2 = new HocuspocusProviderWebsocket({
+			url: "ws://localhost:8000",
+		});
+		// const newlyCreatedSocket = new TiptapCollabProviderWebsocket({
+		// 	appId: "",
+		// });
+
+		setSocket1(newlyCreatedSocket1);
+		setSocket2(newlyCreatedSocket2);
+
+		return () => {
+			newlyCreatedSocket1?.destroy();
+			newlyCreatedSocket2?.destroy();
+		};
+	}, []);
+
+	if (socket1 && socket2) {
+		return (
+			<>
+				<SocketContext1 value={socket1}>
+					<SocketContext2 value={socket2}>{children}</SocketContext2>
+				</SocketContext1>
+			</>
+		);
+	}
+}