@mp-lb/mdkit 0.3.2 → 0.3.3

package/docs/collaboration-persistence.md

@@ -1,147 +0,0 @@
-# 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

@@ -1,341 +0,0 @@
-# Quick Start
-
-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, 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
-```
-
-Import the stylesheet once if you want reset-resistant markdown defaults and
-generic fallback styling for the base panels:
-
-```ts
-import "@mp-lb/mdkit/styles.css";
-```
-
-See [Styling](./styling.md) for reset handling, dark mode, fonts, sizing, and
-custom panel styles.
-
-## Basic Editor
-
-`MdKitEditor` is the textarea-like entry point. It has no persistence, no
-checkpoint history, and no collaboration. You own the `value` and `onChange`
-state.
-
-```tsx
-import { useState } from "react";
-import { MdKitEditor } from "@mp-lb/mdkit";
-import "@mp-lb/mdkit/styles.css";
-
-export function MarkdownEditorExample() {
-  const [markdown, setMarkdown] = useState("# Hello markdown");
-  return <MdKitEditor value={markdown} onChange={setMarkdown} />;
-}
-```
-
-Use this when you want a local editor, a form field, or a debug surface.
-
-## Read-only View
-
-`MdKitView` renders markdown with the same package stylesheet, CSS variables,
-and `fillHeight` sizing contract as `MdKitEditor`, but it does not mount Tiptap
-or ProseMirror.
-
-```tsx
-import { MdKitView } from "@mp-lb/mdkit";
-import "@mp-lb/mdkit/styles.css";
-
-export function MarkdownPreview({ markdown }: { markdown: string }) {
-  return <MdKitView fillHeight value={markdown} />;
-}
-```
-
-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 checkpoint browsing and restore
-- `useMdKitCollaboration` for Hocuspocus/Yjs collaboration
-- `MdKitDocumentToolbar`, `VersionHistoryPanel`, and `MdKitConflictPanel` for
-  a complete base-panel UI
-
-The TypeScript-first path is tRPC. REST is also supported for high-compatibility
-backends and non-TypeScript stacks.
-
-### Frontend With tRPC
-
-```tsx
-import { useMemo, useState } from "react";
-import {
-  MdKitConflictPanel,
-  MdKitDocumentToolbar,
-  MdKitEditor,
-  VersionHistoryPanel,
-  useMdKitCollaboration,
-  useMdKitDocument,
-  useMdKitDocumentVersions,
-  type MdKitDocumentVersionDetail,
-} from "@mp-lb/mdkit";
-import { createMdKitTrpcAdapter } from "@mp-lb/mdkit/trpc/client";
-import { createTRPCProxyClient, httpBatchLink } from "@trpc/client";
-import type { AppRouter } from "./server";
-
-const documentId = "docs/example.md";
-
-export function ConnectedMarkdownEditor({
-  apiUrl,
-}: {
-  apiUrl: string;
-}) {
-  const [versionHistoryOpen, setVersionHistoryOpen] = useState(false);
-  const [conflictOpen, setConflictOpen] = useState(false);
-
-  const trpc = useMemo(
-    () =>
-      createTRPCProxyClient<AppRouter>({
-        links: [httpBatchLink({ url: `${apiUrl}/trpc` })],
-      }),
-    [apiUrl],
-  );
-
-  const adapter = useMemo(
-    () => createMdKitTrpcAdapter({ client: trpc.mdkit }),
-    [trpc],
-  );
-  const document = useMdKitDocument({
-    adapter,
-    debounceMs: 1000,
-    documentId,
-  });
-  const versions = useMdKitDocumentVersions({ adapter, documentId });
-
-  const collaboration = useMdKitCollaboration({
-    collaborator: { id: "user-1", name: "Ada" },
-    documentId,
-    endpoint: `${apiUrl.replace(/^http/, "ws")}/collaboration`,
-  });
-
-  const restoreVersion = async (version: MdKitDocumentVersionDetail) => {
-    await trpc.mdkit.restoreDocumentVersion.mutate({
-      documentId,
-      versionId: version.id,
-    });
-
-    await document.resync();
-    await versions.refresh();
-  };
-
-  return (
-    <>
-      <MdKitDocumentToolbar
-        collaboration={collaboration}
-        document={document}
-        versions={versions}
-        onOpenConflict={() => setConflictOpen(true)}
-        onOpenVersionHistory={() => setVersionHistoryOpen(true)}
-      />
-
-      <MdKitEditor
-        collaboration={collaboration}
-        fillHeight
-        readOnly={document.conflict}
-        value={document.value}
-        onChange={document.setContent}
-        onFocusChange={document.setFocused}
-      />
-
-      {versionHistoryOpen ? (
-        <div role="dialog" aria-label="Version history">
-          <VersionHistoryPanel
-            controller={versions}
-            onRestoreVersion={restoreVersion}
-          />
-        </div>
-      ) : null}
-
-      {document.conflict && conflictOpen ? (
-        <div role="dialog" aria-label="Resolve conflict">
-          <MdKitConflictPanel document={document} />
-        </div>
-      ) : null}
-    </>
-  );
-}
-```
-
-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
-
-The backend starts with a store object. Replace `createYourDocumentStore()` with
-Postgres, MongoDB, Redis, files, or any other durable storage. Your store
-implements the [`MdKitBackendStore`](./api.md#mdkitbackendstore) interface:
-read/write the current document, create/read checkpoints, restore a checkpoint,
-and optionally persist collaboration state.
-The mdkit backend helper applies checkpoint policy and turns those primitives
-into tRPC or REST procedures. Application-owned metadata, auth, permissions,
-tenancy, and durable Yjs storage stay in your code; see
-[Permissions](./permissions.md).
-
-### Backend With tRPC
-
-```ts
-import { createHTTPServer } from "@trpc/server/adapters/standalone";
-import { Database } from "@hocuspocus/extension-database";
-import { Server } from "@hocuspocus/server";
-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 store: MdKitBackendStore = createYourDocumentStore();
-
-const mdkit = createMdKitBackend({
-  store,
-  checkpointPolicy: CheckpointPolicy.smart(),
-});
-
-const collaboration = Server.configure({
-  extensions: [
-    new Database({
-      fetch: ({ documentName }) => mdkit.readCollaborationState(documentName),
-      store: ({ documentName, state }) =>
-        mdkit.writeCollaborationState(documentName, state),
-    }),
-  ],
-});
-
-const appRouter = t.router({
-  mdkit: createMdKitTrpcRouter(mdkit),
-  // otherRouters: ...
-});
-
-export type AppRouter = typeof appRouter;
-
-const server = createHTTPServer({
-  basePath: "/trpc",
-  router: appRouter,
-});
-
-const collaborationSockets = new WebSocketServer({ noServer: true });
-
-collaborationSockets.on("connection", (socket, request) => {
-  collaboration.handleConnection(socket, request, {});
-});
-
-server.on("upgrade", (request, socket, head) => {
-  if (!request.url?.startsWith("/collaboration")) {
-    socket.destroy();
-    return;
-  }
-
-  collaborationSockets.handleUpgrade(request, socket, head, (websocket) => {
-    collaborationSockets.emit("connection", websocket, request);
-  });
-});
-
-server.listen(Number(process.env.PORT ?? 4312));
-```
-
-**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).
-
-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.
-
-### REST
-
-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.
-
-See [REST Backend](./rest.md) for the backend route shape and the small
-frontend transport changes.
-
-### Checkpoints
-
-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, 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?
-
-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
-any React app. If you want a fully custom UI, use `useMdKitDocument`,
-`useMdKitDocumentVersions`, and `useMdKitCollaboration` directly and render your
-own controls.

package/docs/permissions.md

@@ -1,139 +0,0 @@
-# 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.