docs: reposition self-hosted collaboration guidance (#3277)

SuperDoc Yjs was being framed as the "recommended" / "official" self-hosted
package across the docs, examples README, and llms-full.txt. It is a minimal
reference server with no built-in auth, persistence, scaling, or observability.
Production teams should reach for established Yjs infrastructure.

This PR makes Hocuspocus the recommended self-hosted default, introduces YHub
as the advanced path for attribution and revision history (with beta and
licensing caveats), and reframes SuperDoc Yjs as a reference implementation.
It also marks the URL-managed provider path as deprecated in favor of the
supported provider-agnostic contract: modules.collaboration = { ydoc, provider }.

Drive-by fixes: remove the broken getActiveDocumentCount/getConnectionCount
health-check example (those methods do not exist), fix the package README's
broken default import and wrong class name in the Quick Start example, and
remove the hocuspocus.mdx Next Steps card that funneled Hocuspocus users back
to SuperDoc Yjs.

Author: caio-pizzol

apps/docs/editor/collaboration/overview.mdx

@@ -34,8 +34,9 @@ Collaboration is configured through `modules.collaboration` today, but it isn't
 
     | Option | Best For |
     |--------|----------|
-    | [SuperDoc Yjs](/guides/collaboration/superdoc-yjs) | Recommended: the official package |
-    | [Hocuspocus](/guides/collaboration/hocuspocus) | TipTap ecosystem users |
+    | [Hocuspocus](/guides/collaboration/hocuspocus) | Production self-hosted default. Mature, MIT, documented hooks and scaling. |
+    | [YHub](https://github.com/superdoc-dev/superdoc/tree/main/examples/editor/collaboration/backends/fastapi/yjs-hub) | Advanced: attribution and revision history. Beta, Node 22+, AGPL/proprietary. |
+    | [SuperDoc Yjs](/guides/collaboration/superdoc-yjs) | Minimal reference server. Not production infrastructure. |
 
   </Tab>
 </Tabs>

apps/docs/editor/collaboration/quickstart.mdx

@@ -257,9 +257,9 @@ const client = createClient({
   <Card
     title="Self-Hosted Option"
     icon="server"
-    href="/guides/collaboration/superdoc-yjs"
+    href="/guides/collaboration/hocuspocus"
   >
-    Run your own collaboration server
+    Run your own collaboration server with Hocuspocus
   </Card>
 
   <Card

apps/docs/guides/collaboration/hocuspocus.mdx

@@ -286,19 +286,19 @@ Server.configure({
 ## Next steps
 
 <CardGroup cols={2}>
-  <Card
-    title="SuperDoc Yjs"
-    icon="rocket"
-    href="/guides/collaboration/superdoc-yjs"
-  >
-    Try the official collaboration package
-  </Card>
-
   <Card
     title="Client Configuration"
     icon="settings"
     href="/editor/collaboration/configuration"
   >
     All SuperDoc collaboration options
   </Card>
+
+  <Card
+    title="Self-hosted overview"
+    icon="server"
+    href="/guides/collaboration/self-hosted-overview"
+  >
+    Compare Hocuspocus, YHub, and the SuperDoc Yjs reference server
+  </Card>
 </CardGroup>

apps/docs/guides/collaboration/self-hosted-overview.mdx

@@ -36,68 +36,62 @@ flowchart TB
 
 ## Choose your approach
 
+SuperDoc's collaboration is provider-agnostic: pass `{ ydoc, provider }` to `modules.collaboration` and the server choice is yours. We recommend established Yjs infrastructure for production deployments.
+
 | Option | Best For | Setup Time |
 |--------|----------|------------|
-| [SuperDoc Yjs](/guides/collaboration/superdoc-yjs) | New projects, recommended | 30 mins |
-| [Hocuspocus](/guides/collaboration/hocuspocus) | TipTap ecosystem users | 30 mins |
+| [Hocuspocus](/guides/collaboration/hocuspocus) | Production self-hosted default. Mature, MIT-licensed, with documented auth, persistence, and Redis scaling. | 30 mins |
+| [YHub](https://github.com/superdoc-dev/superdoc/tree/main/examples/editor/collaboration/backends/fastapi/yjs-hub) | Advanced self-hosted. YHub supports attribution, activity, revision history, and Redis+Postgres scaling. Beta, Node 22+, AGPL or proprietary licensing. | 1+ hour |
+| [SuperDoc Yjs](/guides/collaboration/superdoc-yjs) | Minimal reference server for prototypes and local dev. Not production infrastructure. | 30 mins |
 
 ## Quick comparison
 
 <Tabs>
-  <Tab title="SuperDoc Yjs">
-    **The official collaboration package**
+  <Tab title="Hocuspocus">
+    **Production self-hosted default**
 
-    - Purpose-built for SuperDoc
-    - Builder pattern API
-    - Auto-save with debounce
-    - Memory management
+    - Mature, MIT-licensed
+    - Documented auth, persistence, Redis scaling
+    - Rich extension ecosystem
 
     ```bash
-    npm install @superdoc-dev/superdoc-yjs-collaboration
+    npm install @hocuspocus/server @hocuspocus/provider
     ```
 
-    [Get Started](/guides/collaboration/superdoc-yjs)
+    [Get Started](/guides/collaboration/hocuspocus)
   </Tab>
 
-  <Tab title="Hocuspocus">
-    **TipTap's Yjs server**
+  <Tab title="YHub">
+    **Advanced: attribution and revision history**
 
-    - Mature, battle-tested
-    - Rich extension ecosystem
-    - Good if already using TipTap
+    - Built-in attribution, activity stream, changesets, rollback
+    - Redis + Postgres backing
+    - Beta, Node 22+, AGPL or proprietary
 
-    ```bash
-    npm install @hocuspocus/server
-    ```
+    Reach for YHub when revision history and identity attribution are central to your product. Validate license and beta status before committing.
 
-    [Get Started](/guides/collaboration/hocuspocus)
+    [See the example](https://github.com/superdoc-dev/superdoc/tree/main/examples/editor/collaboration/backends/fastapi/yjs-hub)
   </Tab>
 
-  </Tabs>
+  <Tab title="SuperDoc Yjs">
+    **Minimal reference server**
 
-## Client connection options
+    A small Yjs WebSocket server we ship for prototypes and local development. Not production infrastructure: no built-in auth, persistence, scaling, or observability. For production, use Hocuspocus or YHub.
 
-When self-hosting, you have two ways to connect SuperDoc:
+    ```bash
+    npm install @superdoc-dev/superdoc-yjs-collaboration
+    ```
 
-### Option 1: URL-based (SuperDoc manages provider)
+    [See the reference](/guides/collaboration/superdoc-yjs)
+  </Tab>
 
-SuperDoc creates and manages the WebSocket connection:
+  </Tabs>
 
-```javascript
-new SuperDoc({
-  selector: '#editor',
-  modules: {
-    collaboration: {
-      url: 'wss://your-server.com/doc',
-      token: 'auth-token'
-    }
-  }
-});
-```
+## Client connection options
 
-### Option 2: Provider-agnostic (You manage provider)
+The supported contract is provider-agnostic: you create the Yjs provider, SuperDoc plugs into it.
 
-You create the Yjs provider yourself:
+### Provider-agnostic (recommended)
 
 ```javascript
 import { HocuspocusProvider } from '@hocuspocus/provider';
@@ -118,9 +112,25 @@ new SuperDoc({
 });
 ```
 
-<Note>
-The provider-agnostic approach gives you more control but requires managing the provider lifecycle yourself.
-</Note>
+This shape works with any Yjs provider: `HocuspocusProvider`, `WebsocketProvider` from `y-websocket` (compatible with YHub and SuperDoc Yjs), `LiveblocksYjsProvider`, or your own.
+
+### URL-based (deprecated)
+
+<Warning>
+This path is deprecated. SuperDoc creates the provider internally and emits a console warning. Use the provider-agnostic shape above for new code.
+</Warning>
+
+```javascript
+new SuperDoc({
+  selector: '#editor',
+  modules: {
+    collaboration: {
+      url: 'wss://your-server.com/doc',
+      token: 'auth-token'
+    }
+  }
+});
+```
 
 ## Requirements
 
@@ -140,19 +150,27 @@ The provider-agnostic approach gives you more control but requires managing the
 
 <CardGroup cols={2}>
   <Card
-    title="SuperDoc Yjs"
-    icon="rocket"
-    href="/guides/collaboration/superdoc-yjs"
+    title="Hocuspocus"
+    icon="server"
+    href="/guides/collaboration/hocuspocus"
   >
-    Recommended - the official package
+    Production self-hosted default
   </Card>
 
   <Card
-    title="Hocuspocus"
-    icon="server"
-    href="/guides/collaboration/hocuspocus"
+    title="YHub example"
+    icon="layers"
+    href="https://github.com/superdoc-dev/superdoc/tree/main/examples/editor/collaboration/backends/fastapi/yjs-hub"
+  >
+    Advanced: attribution and revision history (beta)
+  </Card>
+
+  <Card
+    title="SuperDoc Yjs"
+    icon="flask-conical"
+    href="/guides/collaboration/superdoc-yjs"
   >
-    Alternative using TipTap's server
+    Minimal reference server for dev and prototypes
   </Card>
 
   <Card

apps/docs/guides/collaboration/superdoc-yjs.mdx

@@ -4,7 +4,11 @@ sidebarTitle: SuperDoc Yjs
 keywords: "superdoc collaboration server, yjs server, self-hosted, websocket"
 ---
 
-The official collaboration package for self-hosted deployments. Purpose-built for SuperDoc with a builder API.
+A minimal Yjs WebSocket server we ship as a reference implementation for prototypes and local development.
+
+<Warning>
+This package is not production infrastructure. It has no built-in auth, persistence, scaling, or observability beyond what you wire into the hooks. For production self-hosted collaboration, use [Hocuspocus](/guides/collaboration/hocuspocus) (recommended default) or [YHub](https://github.com/superdoc-dev/superdoc/tree/main/examples/editor/collaboration/backends/fastapi/yjs-hub) (when attribution and revision history are central). SuperDoc's collaboration contract is provider-agnostic: pass `{ ydoc, provider }` to `modules.collaboration` and the server choice is yours.
+</Warning>
 
 ## Installation
 
@@ -320,11 +324,7 @@ DATABASE_URL=postgres://user:pass@localhost/db
 
 ```typescript
 fastify.get('/health', (request, reply) => {
-  reply.send({
-    status: 'healthy',
-    documents: collaboration.getActiveDocumentCount(),
-    connections: collaboration.getConnectionCount()
-  });
+  reply.send({ status: 'healthy' });
 });
 ```
 

apps/docs/llms-full.txt

@@ -253,10 +253,11 @@ Three preset themes included: Google Docs, Microsoft Word, and Blueprint.
 
 ## Collaboration
 
-Real-time multiplayer editing using Yjs (CRDT). Providers supported:
+Real-time multiplayer editing using Yjs (CRDT). The supported integration contract is provider-agnostic: pass `{ ydoc, provider }` to `modules.collaboration` on the client. Server options:
 - Liveblocks (cloud)
-- SuperDoc Yjs server (self-hosted)
-- Hocuspocus (self-hosted)
+- Hocuspocus (recommended self-hosted default)
+- YHub (advanced self-hosted; beta; attribution and revision history use cases)
+- SuperDoc Yjs (minimal reference server, not production infrastructure)
 
 ---
 

examples/README.md

@@ -77,9 +77,10 @@ Realtime providers and backend setups for Yjs-based collaboration.
 
 | Example | Description |
 |---------|-------------|
-| [providers/superdoc-yjs](./editor/collaboration/providers/superdoc-yjs) | Self-hosted Yjs server (recommended) |
-| [providers/hocuspocus](./editor/collaboration/providers/hocuspocus) | Hocuspocus provider setup |
+| [providers/hocuspocus](./editor/collaboration/providers/hocuspocus) | Hocuspocus provider (recommended self-hosted default) |
 | [providers/liveblocks](./editor/collaboration/providers/liveblocks) | Liveblocks managed service |
+| [providers/superdoc-yjs](./editor/collaboration/providers/superdoc-yjs) | SuperDoc Yjs minimal reference server (not production infrastructure) |
+| [backends/fastapi/yjs-hub](./editor/collaboration/backends/fastapi/yjs-hub) | YHub server with attribution and activity stream (beta) |
 | [backends/node-sdk](./editor/collaboration/backends/node-sdk) | Server-side document operations alongside the realtime layer |
 | [backends/fastapi](./editor/collaboration/backends/fastapi) | Python FastAPI backend |
 

packages/collaboration-yjs/README.md

@@ -1,6 +1,8 @@
 # SuperDoc Yjs collaboration library
 
-`@superdoc-dev/superdoc-yjs-collaboration` is a library for integrating Yjs-based real-time collaborative editing into any Node.js WebSocket-enabled server framework. It is designed to work out-of-the-box for **SuperDoc**.
+`@superdoc-dev/superdoc-yjs-collaboration` is a minimal Yjs WebSocket server for SuperDoc, shipped as a reference implementation for prototypes and local development.
+
+> **Not production infrastructure.** No built-in auth, persistence, scaling, or observability beyond what you wire into the hooks. For production self-hosted collaboration, use [Hocuspocus](https://tiptap.dev/docs/hocuspocus) (recommended default) or [YHub](https://github.com/yjs/yhub) (when attribution and revision history are central). SuperDoc's collaboration contract is provider-agnostic: pass `{ ydoc, provider }` to `modules.collaboration` on the client and the server choice is yours.
 
 It provides:
 
@@ -66,7 +68,7 @@ Below is an example using Fastify, but you can adapt it to any server framework.
 import Fastify from 'fastify';
 import websocket from '@fastify/websocket';
 import { v4 as uuidv4 } from 'uuid';
-import SuperDocCollaboration from '@superdoc-dev/superdoc-yjs-collaboration';
+import { CollaborationBuilder } from '@superdoc-dev/superdoc-yjs-collaboration';
 
 const app = Fastify();
 app.register(websocket);
@@ -79,7 +81,7 @@ const onLoad = (params) => {}; // Load your document from persistence (ie: S3)
 const onAutoSave = (params) => {}; // Debounced onChange hook based on 'withDebounce' setting. Save to persistence.
 const onChange = (params) => {}; // On change hook. This gets triggered a lot!
 
-const service = new SuperDocCollaboration()
+const service = new CollaborationBuilder()
   .withName(`sdc-${uuidv4()}`)
   .withDebounce(500)
   .onAuthenticate(onAuthenticate)