@mp-lb/mdkit 0.2.3-main.20.1 → 0.2.3-main.21.1

package/docs/collaboration-persistence.md

@@ -0,0 +1,147 @@
+# Collaboration Persistence
+
+`useMdKitCollaboration` connects `MdKitEditor` to Hocuspocus/Yjs. Mdkit handles
+the editor integration and markdown/Yjs conversion helpers, but your application
+owns where collaboration state is stored.
+
+## What Needs To Be Stored
+
+Hocuspocus collaboration state is Yjs binary state for one collaborative
+document. Store it as bytes in your database or object storage. Good fits
+include Postgres `bytea`, MongoDB `Binary`, S3/blob storage, or another durable
+store your backend already uses.
+
+You can keep this state in memory for a single-process app. That is simple and
+can be acceptable for small deployments, but it has important limits:
+
+- a server restart loses open collaboration state unless it was flushed
+  elsewhere
+- multiple backend instances do not share memory
+- collaborators can split across different instances unless your deployment
+  adds sticky routing, shared persistence, or Hocuspocus infrastructure for
+  multi-instance collaboration
+
+## Document Names Are Stable IDs
+
+Hocuspocus calls the collaboration key `documentName`. Treat that value as a
+stable unique document identifier, not as a mutable display name. It can be a
+document UUID, file id, or deterministic tenant/document key such as
+`tenantId:documentId`.
+
+On the client, mdkit passes `documentId` to Hocuspocus as the provider `name` by
+default. If your collaboration key needs tenancy or another namespace, derive it
+with `resolveRoomName`:
+
+```tsx
+const collaboration = useMdKitCollaboration({
+  collaborator: { id: user.id, name: user.name },
+  documentId,
+  endpoint: `${apiUrl.replace(/^http/, "ws")}/collaboration`,
+  getToken,
+  resolveRoomName: (documentId) => `${tenantId}:${documentId}`,
+});
+```
+
+The same resolved value is what Hocuspocus passes to its persistence callbacks
+as `documentName`.
+
+## Database Extension
+
+The usual integration is Hocuspocus' generic `Database` extension. Put your DB
+reads and writes inside `fetch` and `store`.
+
+```ts
+import { Database } from "@hocuspocus/extension-database";
+import { Server } from "@hocuspocus/server";
+import { CheckpointPolicy } from "@mp-lb/mdkit/core";
+import {
+  createMdKitBackend,
+  type MdKitBackendStore,
+} from "@mp-lb/mdkit/server";
+
+const mdkit = createMdKitBackend({
+  store: createYourDocumentStore(),
+  checkpointPolicy: CheckpointPolicy.smart(),
+});
+
+const collaboration = Server.configure({
+  extensions: [
+    new Database({
+      fetch: async ({ documentName }) => {
+        // Hocuspocus calls this documentName, but it should be a stable id.
+        return mdkit.readCollaborationState?.(documentName) ?? null;
+      },
+
+      store: async ({ documentName, state }) => {
+        await mdkit.writeCollaborationState?.(documentName, state);
+      },
+    }),
+  ],
+});
+```
+
+Your document store can back those mdkit methods with any database:
+
+```ts
+const createYourDocumentStore = (): MdKitBackendStore => ({
+  // Current markdown snapshot.
+  readDocument: (documentId) => db.documents.readCurrent(documentId),
+  writeDocument: (input) => db.documents.writeCurrent(input),
+
+  // Optional checkpoint history.
+  createCheckpoint: (input) => db.checkpoints.create(input),
+  getLatestCheckpoint: (documentId) => db.checkpoints.latest(documentId),
+  listDocumentVersions: (documentId) => db.checkpoints.list(documentId),
+  readDocumentVersion: (input) => db.checkpoints.read(input),
+
+  // Durable Yjs collaboration state.
+  readCollaborationState: async (documentName) => {
+    const row = await db.collaborationState.findByDocumentName(documentName);
+    return row?.yjsState ?? null;
+  },
+
+  writeCollaborationState: async (documentName, state) => {
+    await db.collaborationState.upsert({
+      documentName,
+      yjsState: state,
+      updatedAt: new Date().toISOString(),
+    });
+  },
+});
+```
+
+Store the `state` bytes exactly as Hocuspocus gives them to you, and return the
+same bytes from `fetch`. Do not convert the Yjs state to JSON and rebuild it on
+every connection; that creates new Yjs identities and can duplicate content when
+clients reconnect.
+
+## Seeding From Markdown
+
+The simplest flow is:
+
+1. Current markdown lives in your normal document table.
+2. Hocuspocus asks for Yjs state in `fetch`.
+3. If persisted Yjs state exists, return it.
+4. If no persisted Yjs state exists, seed the collaboration room from the
+   current markdown snapshot.
+5. After that first seed, persist and reuse the Yjs state.
+
+Mdkit exposes Yjs helpers for that seed/reset work:
+
+```ts
+import { yjs } from "@mp-lb/mdkit";
+
+const state = existingState ?? yjs.markdownToMdKitYjs(currentMarkdown);
+```
+
+If your app supports restore, import, or external full-document replacement,
+replace or reset the persisted collaboration state deliberately so the next
+collaboration session starts from the restored canonical markdown.
+
+## Hocuspocus Docs
+
+For the Hocuspocus side of the setup, see:
+
+- [Hocuspocus Database extension](https://tiptap.dev/docs/hocuspocus/server/extensions/database)
+- [Hocuspocus persistence guide](https://tiptap.dev/docs/hocuspocus/guides/persistence)
+- [Hocuspocus Redis extension](https://tiptap.dev/docs/hocuspocus/server/extensions/redis)

package/docs/index.md

@@ -2,9 +2,13 @@
 
 Markdown Editor Kit is a React package for teams that need more than a bare
 markdown editor widget. It starts with a controlled markdown editor that behaves
-like a textarea, then adds autosave, version history, conflict handling, and
+like a textarea, then adds autosave, checkpoint history, conflict handling, and
 collaboration through adapters.
 
+Use the pieces you need. `MdKitEditor` works without any backend, storage,
+checkpoint history, or collaboration. Persistence, checkpoint history, and
+collaboration are optional layers that can be added independently.
+
 ```bash
 pnpm add @mp-lb/mdkit
 ```
@@ -22,7 +26,8 @@ custom panel styles.
 ## Basic Editor
 
 `MdKitEditor` is the textarea-like entry point. It has no persistence, no
-version history, and no collaboration. You own the `value` and `onChange` state.
+checkpoint history, and no collaboration. You own the `value` and `onChange`
+state.
 
 ```tsx
 import { useState } from "react";
@@ -31,7 +36,6 @@ import "@mp-lb/mdkit/styles.css";
 
 export function MarkdownEditorExample() {
   const [markdown, setMarkdown] = useState("# Hello markdown");
-
   return <MdKitEditor value={markdown} onChange={setMarkdown} />;
 }
 ```
@@ -53,15 +57,15 @@ export function MarkdownPreview({ markdown }: { markdown: string }) {
 }
 ```
 
-Use this for document previews, restored-version views, or any readonly markdown
-surface that should visually match the editor.
+Use this for document previews, restored-checkpoint views, or any readonly
+markdown surface that should visually match the editor.
 
 ## Connected Editor
 
 The connected workflow combines:
 
 - `useMdKitDocument` for loading, autosave, dirty state, and conflict detection
-- `useMdKitDocumentVersions` for version browsing and restore
+- `useMdKitDocumentVersions` for checkpoint browsing and restore
 - `useMdKitCollaboration` for Hocuspocus/Yjs collaboration
 - `MdKitDocumentToolbar`, `VersionHistoryPanel`, and `MdKitConflictPanel` for
   a complete base-panel UI
@@ -83,10 +87,9 @@ import {
   useMdKitDocumentVersions,
   type MdKitDocumentVersionDetail,
 } from "@mp-lb/mdkit";
-import {
-  createMdKitTrpcAdapter,
-  createMdKitTrpcClient,
-} from "@mp-lb/mdkit/trpc/client";
+import { createMdKitTrpcAdapter } from "@mp-lb/mdkit/trpc/client";
+import { createTRPCProxyClient, httpBatchLink } from "@trpc/client";
+import type { AppRouter } from "./server";
 
 const documentId = "docs/example.md";
 
@@ -99,13 +102,20 @@ export function ConnectedMarkdownEditor({
   const [conflictOpen, setConflictOpen] = useState(false);
 
   const trpc = useMemo(
-    () => createMdKitTrpcClient({ url: `${apiUrl}/trpc` }),
+    () =>
+      createTRPCProxyClient<AppRouter>({
+        links: [httpBatchLink({ url: `${apiUrl}/trpc` })],
+      }),
     [apiUrl],
   );
-  const adapter = useMemo(() => createMdKitTrpcAdapter({ client: trpc }), [trpc]);
 
+  const adapter = useMemo(
+    () => createMdKitTrpcAdapter({ client: trpc.mdkit }),
+    [trpc],
+  );
   const document = useMdKitDocument({ adapter, documentId });
   const versions = useMdKitDocumentVersions({ adapter, documentId });
+
   const collaboration = useMdKitCollaboration({
     collaborator: { id: "user-1", name: "Ada" },
     documentId,
@@ -113,10 +123,11 @@ export function ConnectedMarkdownEditor({
   });
 
   const restoreVersion = async (version: MdKitDocumentVersionDetail) => {
-    await trpc.restoreDocumentVersion.mutate({
+    await trpc.mdkit.restoreDocumentVersion.mutate({
       documentId,
       versionId: version.id,
     });
+
     await document.resync();
     await versions.refresh();
   };
@@ -159,94 +170,119 @@ export function ConnectedMarkdownEditor({
 }
 ```
 
-The modal shells above are intentionally plain. Put `VersionHistoryPanel` and
-`MdKitConflictPanel` inside your own dialog, drawer, side panel, or editor
-replacement view. If your app uses shadcn/ui, see [Shadcn Plugin](./shadcn.md)
-for the source-installed workflow component.
+The base panels are starter UI; if they do not fit your product, keep the hooks
+and build your own workflow components.
+
+### Backend Store Contract
 
-### Backend With Fastify And tRPC
+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.
+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
+[Permissions](./permissions.md).
 
-The backend only needs a store object. Replace `createYourDocumentStore()` with
-Postgres, MongoDB, Redis, files, or any other durable storage.
+### Backend With tRPC
 
 ```ts
-import cors from "@fastify/cors";
-import websocket from "@fastify/websocket";
+import { createHTTPServer } from "@trpc/server/adapters/standalone";
 import { Database } from "@hocuspocus/extension-database";
 import { Server } from "@hocuspocus/server";
-import { fastifyTRPCPlugin } from "@trpc/server/adapters/fastify";
-import Fastify from "fastify";
+import { WebSocketServer } from "ws";
+import { CheckpointPolicy } from "@mp-lb/mdkit/core";
+import { t } from "./trpc";
+import {
+  createMdKitBackend,
+  type MdKitBackendStore,
+} from "@mp-lb/mdkit/server";
 import { createMdKitTrpcRouter } from "@mp-lb/mdkit/trpc/server";
 
-const app = Fastify();
-const store = createYourDocumentStore();
+const store: MdKitBackendStore = createYourDocumentStore();
+
+const mdkit = createMdKitBackend({
+  store,
+  checkpointPolicy: CheckpointPolicy.smart(),
+});
 
 const collaboration = Server.configure({
   extensions: [
     new Database({
-      fetch: ({ documentName }) => store.readCollaborationState(documentName),
+      fetch: ({ documentName }) => mdkit.readCollaborationState(documentName),
       store: ({ documentName, state }) =>
-        store.writeCollaborationState(documentName, state),
+        mdkit.writeCollaborationState(documentName, state),
     }),
   ],
 });
 
-await app.register(cors, { origin: true });
-await app.register(websocket);
+const appRouter = t.router({
+  mdkit: createMdKitTrpcRouter(mdkit),
+  // otherRouters: ...
+});
 
-await app.register(fastifyTRPCPlugin, {
-  prefix: "/trpc",
-  trpcOptions: {
-    router: createMdKitTrpcRouter(store),
-  },
+export type AppRouter = typeof appRouter;
+
+const server = createHTTPServer({
+  basePath: "/trpc",
+  router: appRouter,
 });
 
-app.get("/collaboration", { websocket: true }, (socket, request) => {
-  collaboration.handleConnection(socket, request.raw, {});
+const collaborationSockets = new WebSocketServer({ noServer: true });
+
+collaborationSockets.on("connection", (socket, request) => {
+  collaboration.handleConnection(socket, request, {});
 });
 
-await app.listen({ port: Number(process.env.PORT ?? 4312) });
-```
+server.on("upgrade", (request, socket, head) => {
+  if (!request.url?.startsWith("/collaboration")) {
+    socket.destroy();
+    return;
+  }
 
-The store object implements `MdKitTransportStore`: current document reads and
-writes, version list/read/restore, and optional collaboration state storage. See
-[API Reference](./api.md#transport-helpers).
+  collaborationSockets.handleUpgrade(request, socket, head, (websocket) => {
+    collaborationSockets.emit("connection", websocket, request);
+  });
+});
 
-### REST Compatibility
+server.listen(Number(process.env.PORT ?? 4312));
+```
 
-If you want REST instead of tRPC, use the REST frontend adapter:
+**Important:** if you enable collaboration, decide where Hocuspocus Yjs state is
+stored; in-memory state is simple but does not scale across backend instances.
+See [Collaboration Persistence](./collaboration-persistence.md).
 
-```tsx
-import { createMdKitRestAdapter } from "@mp-lb/mdkit";
+If the frontend runs on a different origin, put this server behind your app's
+dev proxy or add CORS handling around the tRPC handler. See
+[API Reference](./api.md#transport-helpers) for the full backend helper API.
 
-const adapter = createMdKitRestAdapter({
-  baseUrl: "https://api.example.com/mdkit",
-});
-```
+### REST
 
-On Fastify, register the matching REST endpoints:
+The quick start uses tRPC because it gives the connected editor a complete typed
+backend surface. REST is supported, but it is more verbose: the frontend adapter
+expects matching REST endpoints, and restore currently needs one explicit
+request from your UI.
 
-```ts
-import { registerMdKitFastify } from "@mp-lb/mdkit/fastify";
+See [REST Backend](./rest.md) for the backend route shape and the small
+frontend transport changes.
 
-await registerMdKitFastify(app, {
-  prefix: "/mdkit",
-  store,
-});
-```
+### Checkpoints
 
-The mdkit testbench uses this split deliberately: `Connected (panels)` uses the
-REST adapter, while `Connected (shadcn)` uses the tRPC adapter.
+Checkpoint policies decide when saved content becomes history. The backend
+example uses `CheckpointPolicy.smart()`, which applies mdkit's default
+autosave-friendly policy. See [Checkpoint Policy](./api.md#checkpoint-policy)
+for `never`, `always`, `smart`, and custom policy functions.
 
 ## Questions
 
 ### Do the backends need to know about each other?
 
-Storage, version history, and collaboration can stay separate. Storage stores
-the current markdown snapshot. Version history stores markdown snapshots.
-Hocuspocus stores live Yjs collaboration state. They only need glue if your
-product wants collaborative edits to automatically become saved markdown
-versions.
+Storage, checkpoint history, and collaboration can stay separate. Storage stores
+the current markdown snapshot. Checkpoint history stores immutable markdown
+snapshots. Hocuspocus hosts live Yjs collaboration state, and your application
+chooses whether and where to persist that state. These pieces need glue when
+your product wants collaborative edits to become canonical markdown or
+checkpoints.
 
 ### Does mdkit require tRPC or these exact REST endpoints?
 
@@ -254,6 +290,44 @@ No. The frontend hooks only need an `MdKitDocumentAdapter`. You can use REST,
 tRPC, GraphQL, server actions, IndexedDB, Rails, Go, or anything else as long as
 your adapter returns the documented shapes.
 
+### How do store callbacks access user or request context?
+
+In the tRPC quick-start path, `createMdKitTrpcRouter(mdkit)` is the simple
+version: create one mdkit backend around a store object, then mount the router.
+Use that when the store can enforce permissions and write metadata without
+per-request React editor context.
+
+If your store methods need the authenticated user, organization, request id,
+logger, or other trusted request state, create the store at your application
+request boundary and close over that context:
+
+```ts
+const createStoreForRequest = (ctx: AppContext): MdKitBackendStore => ({
+  readDocument: (documentId) =>
+    files.readCurrentMarkdown({ documentId, user: ctx.user }),
+
+  writeDocument: (input) =>
+    files.writeCurrentMarkdown({
+      ...input,
+      actorId: ctx.user.id,
+    }),
+
+  createCheckpoint: (input) =>
+    files.createMarkdownCheckpoint({
+      ...input,
+      actorId: ctx.user.id,
+    }),
+});
+```
+
+With tRPC, that means writing the mdkit procedures in your app router when you
+need request-scoped behavior, and calling `createMdKitBackend({
+store: createStoreForRequest(ctx), checkpointPolicy })` inside those
+procedures. With REST, use the same pattern inside your route handlers after
+you have authenticated the request. Mdkit does not need to understand your auth
+model; it only needs store callbacks that can read, write, and checkpoint the
+document.
+
 ### Do I have to use the base panels?
 
 No. The base panels are the fastest way to get a complete workflow working in

package/docs/permissions.md

@@ -0,0 +1,139 @@
+# Permissions
+
+MDKit should make connected editing secure without owning your application's
+auth system.
+
+The application owns authentication, user identity, tenancy, document ownership,
+roles, teams, audit logging, and permission policy. MDKit owns where permission
+checks happen in the document, checkpoint, restore, and collaboration
+lifecycle.
+
+## Permission Contract
+
+The proposed permission contract is one `can` function:
+
+```ts
+type MdKitPermissionAction = "read" | "write" | "restore";
+
+type MdKitPermissions<User = unknown, Document = unknown, Context = unknown> = {
+  can(
+    action: MdKitPermissionAction,
+    user: User,
+    document: Document,
+    context: Context,
+  ): Promise<boolean> | boolean;
+};
+```
+
+This is intentionally small. Products that do not need a separate restore
+permission can implement `restore` as equivalent to `write`.
+
+## Action Semantics
+
+`read` allows reading the current document and checkpoint history.
+
+`write` allows changing the current document, creating checkpoints, joining a
+collaboration room, and writing/snapshotting collaboration state. Collaboration
+requires `write`; MDKit does not need read-only collaboration in the initial
+permission model.
+
+`restore` allows restoring a checkpoint into the current document and resetting
+collaboration state as part of that restore.
+
+Permissions should be mandatory for the opinionated backend helper. A package
+can expose an explicit allow-all implementation for local development and
+applications that intentionally handle permissions outside MDKit:
+
+```ts
+export const mdKitDisablePermissions: MdKitPermissions = {
+  can: () => true,
+};
+```
+
+Disabling permission checks should be visible in code. It should not be the
+accidental default.
+
+## Collaboration Security
+
+Collaboration room names are not secrets. The server must authorize every room
+join.
+
+Joining a collaboration room is both read access and write access to the live
+Yjs document. Once connected, a client can receive live state and send Yjs
+updates unless the server rejects or constrains that connection. Storage
+callbacks alone are not enough because active Yjs state can be read or changed
+before a persistence callback runs.
+
+The join rule is:
+
+```ts
+can("write", user, document, context)
+```
+
+If permission fails, the WebSocket must be rejected before the client receives
+document state or sends accepted Yjs updates.
+
+## Enforcement Levels
+
+Applications should be able to choose how strictly collaboration permissions are
+enforced after a session joins.
+
+### Join Only
+
+Check `can("write")` when the user joins the collaboration room. This is simple
+and common. Tradeoff: if permissions are revoked mid-session, the active socket
+may keep editing until it disconnects, is closed, or is forced to reconnect.
+WebSocket ping timeouts are liveness checks, not permission expiry.
+
+### Per-Message Permission Check
+
+Check `can("write")` in Hocuspocus `beforeHandleMessage` before every incoming
+Yjs message is applied. This is closest to checking permissions before every
+HTTP write request. It can read from the database directly, but it may be too
+expensive for high-volume collaboration.
+
+### Per-Message Revocation Check
+
+Run full permission policy on join and permission-change operations, then check
+a cheap revocation source per packet: an in-memory set, cache entry, permission
+generation, or short-lived authorization record.
+
+This is the practical compromise for stricter apps. The revocation source must
+have the ordering guarantee the product needs. If a revocation request returns
+success before every collaboration server can observe the revoked state, the
+system has eventual revocation rather than strict post-response write
+prevention.
+
+## Hocuspocus Hooks
+
+Hocuspocus exposes the server hooks MDKit needs:
+
+- `onConnect` runs when a client first asks to connect to a document
+- `onAuthenticate` runs when authentication is enabled and receives the provider
+  token
+- `beforeHandleMessage` runs before an incoming collaboration message is applied
+  to the Yjs document
+
+`useMdKitCollaboration` already has a token hook. That token is not the
+permission policy; it is how the server identifies the user and request context
+before calling `can`.
+
+## Backend Helper Responsibilities
+
+An opinionated MDKit backend helper should call permissions at every server-side
+entry point:
+
+| Operation | Required Action |
+| --- | --- |
+| Read current document | `read` |
+| Write current document | `write` |
+| List checkpoints | `read` |
+| Read checkpoint | `read` |
+| Create checkpoint | `write` |
+| Restore checkpoint | `restore` |
+| Join collaboration | `write` |
+| Persist collaboration state from an authorized room | `write` |
+| Reset collaboration state during restore | `restore` |
+
+Frontend UI checks are convenience. Server-side checks are the security
+boundary.