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

playground/frontend/app/SocketContext1.ts

@@ -0,0 +1,8 @@
+"use client";
+
+import type { HocuspocusProviderWebsocket } from "@hocuspocus/provider";
+import { createContext } from "react";
+
+export const SocketContext1 = createContext<HocuspocusProviderWebsocket | null>(
+	null,
+);

playground/frontend/app/SocketContext2.ts

@@ -0,0 +1,8 @@
+"use client";
+
+import type { HocuspocusProviderWebsocket } from "@hocuspocus/provider";
+import { createContext } from "react";
+
+export const SocketContext2 = createContext<HocuspocusProviderWebsocket | null>(
+	null,
+);

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>
+			</>
+		);
+	}
+}

playground/frontend/app/globals.css

@@ -0,0 +1,124 @@
+@import "tailwindcss";
+
+:root {
+	--background: #ffffff;
+	--foreground: #171717;
+}
+
+@theme inline {
+	--color-background: var(--background);
+	--color-foreground: var(--foreground);
+	--font-sans: var(--font-geist-sans);
+	--font-mono: var(--font-geist-mono);
+}
+
+@media (prefers-color-scheme: dark) {
+	:root {
+		--background: #0a0a0a;
+		--foreground: #ededed;
+	}
+}
+
+body {
+	background: var(--background);
+	color: var(--foreground);
+	font-family: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI",
+		sans-serif;
+	font-feature-settings: "cv02", "cv03", "cv04", "cv11";
+	line-height: 1.6;
+}
+
+/* Modern editor styles */
+.tiptap {
+	:first-child {
+		margin-top: 0;
+	}
+
+	/* Placeholder styling */
+	p.is-editor-empty:first-child::before {
+		color: rgb(148 163 184);
+		content: attr(data-placeholder);
+		float: left;
+		height: 0;
+		pointer-events: none;
+		font-style: italic;
+	}
+
+	p {
+		word-break: break-word;
+		line-height: 1.8;
+	}
+
+	/* Improved focus styles */
+	&:focus {
+		outline: none;
+		box-shadow: 0 0 0 2px rgb(59 130 246 / 0.1);
+	}
+
+	/* Better typography */
+	h1,
+	h2,
+	h3,
+	h4,
+	h5,
+	h6 {
+		font-weight: 600;
+		color: rgb(15 23 42);
+	}
+
+	@media (prefers-color-scheme: dark) {
+		h1,
+		h2,
+		h3,
+		h4,
+		h5,
+		h6 {
+			color: rgb(248 250 252);
+		}
+		p.is-editor-empty:first-child::before {
+			color: rgb(100 116 139);
+		}
+	}
+
+	/* Modern collaboration cursor */
+	.collaboration-carets__caret {
+		border-left: 2px solid currentColor;
+		border-right: 2px solid currentColor;
+		margin-left: -1px;
+		margin-right: -1px;
+		pointer-events: none;
+		position: relative;
+		word-break: normal;
+		animation: blink 1s infinite;
+	}
+
+	/* Smooth blinking animation */
+	@keyframes blink {
+		0%,
+		50% {
+			opacity: 1;
+		}
+		51%,
+		100% {
+			opacity: 0.3;
+		}
+	}
+
+	/* Modern username label */
+	.collaboration-carets__label {
+		border-radius: 6px 6px 6px 2px;
+		color: white;
+		font-size: 11px;
+		font-style: normal;
+		font-weight: 500;
+		left: -1px;
+		line-height: normal;
+		padding: 0.25rem 0.5rem;
+		position: absolute;
+		top: -1.8em;
+		user-select: none;
+		white-space: nowrap;
+		box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+		backdrop-filter: blur(4px);
+	}
+}

playground/frontend/app/layout.tsx

@@ -0,0 +1,70 @@
+import Link from "next/link";
+import "./globals.css";
+
+export default function RootLayout({
+	children,
+}: Readonly<{
+	children: React.ReactNode;
+}>) {
+	return (
+		<html lang="en">
+			<body className="min-h-screen bg-gradient-to-br from-slate-50 to-blue-50 dark:from-slate-900 dark:to-slate-800">
+				<div className="flex min-h-screen">
+					{/* Sidebar */}
+					<div className="w-64 bg-white/80 dark:bg-slate-900/80 backdrop-blur-sm border-r border-slate-200 dark:border-slate-700 shadow-sm">
+						<div className="p-6">
+							<div className="mb-8">
+								<Link href="/" className="flex items-center space-x-2 text-slate-900 dark:text-white hover:text-blue-600 dark:hover:text-blue-400 transition-colors">
+									<div className="w-8 h-8 bg-gradient-to-br from-blue-500 to-purple-600 rounded-lg flex items-center justify-center">
+										<span className="text-white font-bold text-sm">H</span>
+									</div>
+									<span className="font-semibold">Hocuspocus</span>
+								</Link>
+							</div>
+
+							<nav className="space-y-6">
+								<div>
+									<h2 className="text-xs font-semibold text-slate-500 dark:text-slate-400 uppercase tracking-wider mb-3">Classic Provider</h2>
+									<ul className="space-y-2">
+										{[1, 2, 3, 4].map((num) => (
+											<li key={num}>
+												<Link
+													href={`/articles/${num}`}
+													className="flex items-center px-3 py-2 text-sm font-medium text-slate-700 dark:text-slate-300 rounded-lg hover:bg-slate-100 dark:hover:bg-slate-800 hover:text-blue-600 dark:hover:text-blue-400 transition-all duration-200"
+												>
+													<div className="w-2 h-2 bg-slate-400 dark:bg-slate-500 rounded-full mr-3"></div>
+													Article {num}
+												</Link>
+											</li>
+										))}
+									</ul>
+								</div>
+								<div>
+									<h2 className="text-xs font-semibold text-slate-500 dark:text-slate-400 uppercase tracking-wider mb-3">React Provider</h2>
+									<ul className="space-y-2">
+										{[1, 2, 3, 4].map((num) => (
+											<li key={num}>
+												<Link
+													href={`/react-provider/${num}`}
+													className="flex items-center px-3 py-2 text-sm font-medium text-slate-700 dark:text-slate-300 rounded-lg hover:bg-slate-100 dark:hover:bg-slate-800 hover:text-purple-600 dark:hover:text-purple-400 transition-all duration-200"
+												>
+													<div className="w-2 h-2 bg-purple-400 dark:bg-purple-500 rounded-full mr-3"></div>
+													Article {num}
+												</Link>
+											</li>
+										))}
+									</ul>
+								</div>
+							</nav>
+						</div>
+					</div>
+
+					{/* Main content */}
+					<div className="flex-1 overflow-hidden">
+						{children}
+					</div>
+				</div>
+			</body>
+		</html>
+	);
+}

playground/frontend/app/page.tsx

@@ -0,0 +1,76 @@
+export default function Home() {
+	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">
+					<h1 className="text-3xl font-bold bg-gradient-to-r from-blue-600 to-purple-600 bg-clip-text text-transparent">
+						Hocuspocus v3 Playground
+					</h1>
+					<p className="text-slate-600 dark:text-slate-400 mt-2">
+						Real-time collaborative editor demo
+					</p>
+				</div>
+			</header>
+
+			{/* Main content */}
+			<main className="flex-1 p-8">
+				<div className="max-w-4xl mx-auto">
+					{/* Welcome card */}
+					<div className="bg-white/80 dark:bg-slate-900/80 backdrop-blur-sm rounded-2xl border border-slate-200 dark:border-slate-700 shadow-xl p-8 mb-8">
+						<div className="flex items-center mb-6">
+							<div className="w-12 h-12 bg-gradient-to-br from-green-400 to-blue-500 rounded-xl flex items-center justify-center mr-4">
+								<span className="text-white text-xl">🚀</span>
+							</div>
+							<h2 className="text-2xl font-bold text-slate-900 dark:text-white">Welcome!</h2>
+						</div>
+						<p className="text-slate-700 dark:text-slate-300 text-lg leading-relaxed mb-6">
+							This demo showcases how to use a shared WebSocket connection to load multiple documents with real-time collaboration.
+						</p>
+						<div className="bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-lg p-4">
+							<p className="text-blue-800 dark:text-blue-200 font-medium">
+								💡 Tip: Open a second tab or window and experience collaborative editing in real-time!
+							</p>
+						</div>
+					</div>
+
+					{/* Features grid */}
+					<div className="grid md:grid-cols-2 gap-6 mb-8">
+						<div className="bg-white/80 dark:bg-slate-900/80 backdrop-blur-sm rounded-xl border border-slate-200 dark:border-slate-700 p-6">
+							<div className="w-10 h-10 bg-gradient-to-br from-purple-500 to-pink-500 rounded-lg flex items-center justify-center mb-4">
+								<span className="text-white text-lg">🔌</span>
+							</div>
+							<h3 className="font-semibold text-slate-900 dark:text-white mb-2">Smart Connection</h3>
+							<p className="text-slate-600 dark:text-slate-400 text-sm">
+								WebSocket connection opens when you enter article routes and closes when you leave.
+							</p>
+						</div>
+
+						<div className="bg-white/80 dark:bg-slate-900/80 backdrop-blur-sm rounded-xl border border-slate-200 dark:border-slate-700 p-6">
+							<div className="w-10 h-10 bg-gradient-to-br from-amber-500 to-orange-500 rounded-lg flex items-center justify-center mb-4">
+								<span className="text-white text-lg">📄</span>
+							</div>
+							<h3 className="font-semibold text-slate-900 dark:text-white mb-2">On-Demand Loading</h3>
+							<p className="text-slate-600 dark:text-slate-400 text-sm">
+								Documents are fetched as needed via the shared connection for optimal performance.
+							</p>
+						</div>
+					</div>
+
+					{/* Debug info */}
+					<div className="bg-slate-50 dark:bg-slate-800/50 rounded-xl border border-slate-200 dark:border-slate-700 p-6">
+						<div className="flex items-center mb-3">
+							<div className="w-8 h-8 bg-gradient-to-br from-slate-500 to-slate-600 rounded-lg flex items-center justify-center mr-3">
+								<span className="text-white text-sm">🔍</span>
+							</div>
+							<h3 className="font-semibold text-slate-700 dark:text-slate-300">Developer Console</h3>
+						</div>
+						<p className="text-slate-600 dark:text-slate-400 text-sm">
+							Open your browser's developer console to see detailed connection and synchronization information.
+						</p>
+					</div>
+				</div>
+			</main>
+		</div>
+	);
+}

playground/frontend/app/react-provider/[slug]/ArticleEditor.tsx

@@ -0,0 +1,159 @@
+"use client";
+
+import {
+	HocuspocusProviderWebsocketComponent,
+	HocuspocusRoom,
+} from "@hocuspocus/provider-react";
+import React, { useCallback } from "react";
+import CollaborationStatus from "./CollaborationStatus";
+import CollaborativeEditor from "./CollaborativeEditor";
+import ConnectedUsers from "./ConnectedUsers";
+
+export default function ArticleEditor({ slug }: { slug: string }) {
+	const handleAuthFailed = useCallback(
+		(data: { reason: string }) => {
+			console.error(`[Editor 1] Auth failed for "${slug}":`, data.reason);
+		},
+		[slug],
+	);
+
+	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}
+								<span className="ml-3 text-sm font-medium text-purple-600 dark:text-purple-400 bg-purple-100 dark:bg-purple-900/30 px-2 py-1 rounded-full">
+									provider-react
+								</span>
+							</h1>
+							<p className="text-slate-600 dark:text-slate-400 mt-1">
+								Using @hocuspocus/provider-react hooks and components
+							</p>
+						</div>
+					</div>
+				</div>
+			</header>
+
+			{/* Main content */}
+			<main className="flex-1 p-8">
+				<div className="max-w-7xl mx-auto space-y-6">
+					{/* Two independent WebSocket connections, each with its own room */}
+					<div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
+						{/* Editor 1 — event handlers via HocuspocusRoom props */}
+						<HocuspocusProviderWebsocketComponent url="ws://localhost:8000">
+							<HocuspocusRoom
+								name={slug}
+								onAuthenticationFailed={handleAuthFailed}
+								onClose={(data) =>
+									console.log("[Editor 1] Connection closed:", data.event)
+								}
+								onSynced={(data) =>
+									console.log("[Editor 1] Synced:", data.state)
+								}
+							>
+								<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">
+											Event handlers via props
+										</span>
+									</div>
+
+									<CollaborationStatus />
+
+									<ConnectedUsers />
+
+									<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 />
+									</div>
+								</div>
+							</HocuspocusRoom>
+						</HocuspocusProviderWebsocketComponent>
+
+						{/* Editor 2 — event handlers via useHocuspocusEvent hook (see CollaborationStatus) */}
+						<HocuspocusProviderWebsocketComponent url="ws://localhost:8000">
+							<HocuspocusRoom name={slug}>
+								<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">
+											Event handlers via hook
+										</span>
+									</div>
+
+									<CollaborationStatus />
+
+									<ConnectedUsers />
+
+									<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 />
+									</div>
+								</div>
+							</HocuspocusRoom>
+						</HocuspocusProviderWebsocketComponent>
+					</div>
+
+					{/* Info panel */}
+					<div className="bg-purple-50/50 dark:bg-purple-900/20 backdrop-blur-sm rounded-xl border border-purple-200 dark:border-purple-700 p-6">
+						<div className="flex items-start space-x-3">
+							<div className="flex-shrink-0">
+								<div className="w-8 h-8 bg-purple-100 dark:bg-purple-900/40 rounded-full flex items-center justify-center">
+									<svg
+										className="w-4 h-4 text-purple-600 dark:text-purple-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-purple-900 dark:text-purple-100">
+									@hocuspocus/provider-react Demo
+								</h3>
+								<p className="text-sm text-purple-700 dark:text-purple-300 mt-1">
+									This demo uses the new React-specific package. Each editor is
+									wrapped in its own{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										HocuspocusProviderWebsocketComponent
+									</code>{" "}
+									(independent WebSocket) and{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										HocuspocusRoom
+									</code>
+									. Status is read via{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										useHocuspocusConnectionStatus()
+									</code>
+									,{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										useHocuspocusSyncStatus()
+									</code>
+									, and{" "}
+									<code className="bg-purple-200/50 dark:bg-purple-800/50 px-1 rounded">
+										useHocuspocusAwareness()
+									</code>{" "}
+									hooks &mdash; no manual event listeners needed.
+								</p>
+							</div>
+						</div>
+					</div>
+				</div>
+			</main>
+		</div>
+	);
+}

playground/frontend/app/react-provider/[slug]/CollaborationStatus.tsx

@@ -0,0 +1,155 @@
+"use client";
+
+import {
+	useHocuspocusConnectionStatus,
+	useHocuspocusEvent,
+	useHocuspocusProvider,
+	useHocuspocusSyncStatus,
+} from "@hocuspocus/provider-react";
+import { useState } from "react";
+
+const CollaborationStatus = () => {
+	const provider = useHocuspocusProvider();
+	const connectionStatus = useHocuspocusConnectionStatus();
+	const syncStatus = useHocuspocusSyncStatus();
+	const [unsyncedChanges, setUnsyncedChanges] = useState(0);
+
+	// Using the useHocuspocusEvent hook instead of manual provider.on/off
+	useHocuspocusEvent("unsyncedChanges", (data) => {
+		setUnsyncedChanges(data.number);
+	});
+
+	const getStatusColor = (status: string) => {
+		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 ${connectionStatus === "connected" ? "bg-green-500" : connectionStatus === "connecting" ? "bg-yellow-500" : "bg-red-500"}`}
+						/>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${getStatusColor(connectionStatus)}`}
+						>
+							{connectionStatus}
+						</span>
+					</div>
+					<div className="flex items-center space-x-2">
+						<div
+							className={`w-3 h-3 rounded-full ${syncStatus === "synced" ? "bg-green-500" : "bg-orange-500 animate-pulse"}`}
+						/>
+						<span
+							className={`px-2 py-1 rounded-full text-xs font-medium ${syncStatus === "synced" ? "bg-green-100 text-green-800 dark:bg-green-900/20 dark:text-green-400" : "bg-orange-100 text-orange-800 dark:bg-orange-900/20 dark:text-orange-400"}`}
+						>
+							{syncStatus}
+						</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"}`}
+						/>
+						<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={connectionStatus === "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={connectionStatus === "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={() => provider.detach()}
+						>
+							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={() => provider.attach()}
+						>
+							Attach
+						</button>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+};
+
+export default CollaborationStatus;

playground/frontend/app/react-provider/[slug]/CollaborativeEditor.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useHocuspocusProvider } from "@hocuspocus/provider-react";
+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 { useEffect, useRef } from "react";
+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 = () => {
+	const provider = useHocuspocusProvider();
+	const initializedRef = useRef(false);
+
+	useEffect(() => {
+		if (!initializedRef.current) {
+			Y.applyUpdate(provider.document, Uint8Array.from(initialContent));
+			initializedRef.current = true;
+		}
+	}, [provider.document]);
+
+	const editor = useEditor(
+		{
+			extensions: [
+				StarterKit.configure({
+					undoRedo: false,
+				}),
+				Collaboration.configure({
+					document: provider.document,
+				}),
+				CollaborationCaret.configure({
+					provider,
+				}),
+			],
+			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",
+				},
+			},
+		},
+		[provider.document],
+	);
+
+	return <EditorContent editor={editor} />;
+};
+
+export default CollaborativeEditor;

playground/frontend/app/react-provider/[slug]/ConnectedUsers.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useHocuspocusAwareness } from "@hocuspocus/provider-react";
+import { useEffect, useState } from "react";
+
+const colors = [
+	"bg-blue-500",
+	"bg-green-500",
+	"bg-purple-500",
+	"bg-pink-500",
+	"bg-amber-500",
+	"bg-cyan-500",
+	"bg-rose-500",
+	"bg-indigo-500",
+];
+
+const ConnectedUsers = () => {
+	const users = useHocuspocusAwareness();
+	const [mounted, setMounted] = useState(false);
+
+	useEffect(() => {
+		setMounted(true);
+	}, []);
+
+	return (
+		<div className="bg-white/60 dark:bg-slate-900/60 backdrop-blur-sm rounded-xl border border-slate-200 dark:border-slate-700 px-4 py-3">
+			<div className="flex items-center space-x-3">
+				<span className="text-xs font-medium text-slate-500 dark:text-slate-400 uppercase tracking-wider">
+					Users
+				</span>
+				{mounted && (
+					<>
+						<div className="flex -space-x-2">
+							{users.map((user, i) => (
+								<div
+									key={user.clientId}
+									className={`w-7 h-7 rounded-full ${colors[i % colors.length]} border-2 border-white dark:border-slate-900 flex items-center justify-center`}
+									title={`Client ${user.clientId}`}
+								>
+									<span className="text-white text-xs font-bold">
+										{String(user.clientId).slice(-2)}
+									</span>
+								</div>
+							))}
+						</div>
+						<span className="text-xs text-slate-500 dark:text-slate-400">
+							{users.length} connected
+						</span>
+					</>
+				)}
+			</div>
+		</div>
+	);
+};
+
+export default ConnectedUsers;

playground/frontend/app/react-provider/[slug]/page.tsx

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

playground/frontend/app/react-provider/layout.tsx

@@ -0,0 +1,7 @@
+export default function Layout({
+	children,
+}: Readonly<{
+	children: React.ReactNode;
+}>) {
+	return children;
+}