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

package/docs/rest.md

@@ -0,0 +1,98 @@
+# REST Backend
+
+Use REST when you want the quick-start frontend without tRPC. The editor,
+toolbar, conflict panel, checkpoint panel, and collaboration hook are the same.
+The difference is the backend transport.
+
+If your backend uses Fastify, mdkit can register the REST routes for you. If you
+use another server framework, implement the same endpoint shape shown below.
+
+## Frontend Wiring
+
+Use the connected frontend from the [Quick Start](./index.md#frontend-with-trpc).
+Keep the same component structure, but change the transport-specific pieces:
+
+- replace the tRPC adapter with `createMdKitRestAdapter`, using a REST base URL
+  such as `${apiUrl}/mdkit`
+- point collaboration at `${apiUrl.replace(/^http/, "ws")}/mdkit/collaboration`
+- point the restore callback at `POST /mdkit/versions/:versionId/restore`
+
+`createMdKitRestAdapter` covers current-document reads, writes, resync,
+checkpoint listing, and checkpoint detail reads. Restore is separate because it
+is not part of `MdKitDocumentAdapter` yet.
+
+## Fastify Backend
+
+```ts
+import cors from "@fastify/cors";
+import websocket from "@fastify/websocket";
+import { Database } from "@hocuspocus/extension-database";
+import { Server } from "@hocuspocus/server";
+import Fastify from "fastify";
+import { CheckpointPolicy } from "@mp-lb/mdkit/core";
+import {
+  createMdKitBackend,
+  type MdKitBackendStore,
+} from "@mp-lb/mdkit/server";
+import { registerMdKitFastify } from "@mp-lb/mdkit/fastify";
+
+const app = Fastify();
+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),
+    }),
+  ],
+});
+
+await app.register(cors, { origin: true });
+await app.register(websocket);
+
+await registerMdKitFastify(app, {
+  prefix: "/mdkit",
+  store: mdkit,
+});
+
+app.get("/mdkit/collaboration", { websocket: true }, (socket, request) => {
+  collaboration.handleConnection(socket, request.raw, {});
+});
+
+app.addHook("onClose", async () => {
+  await collaboration.destroy();
+});
+
+await app.listen({ port: Number(process.env.PORT ?? 4312) });
+```
+
+The store object is still your application boundary. It connects mdkit's REST
+routes to your database and owns metadata, permissions, tenancy, and durable
+Yjs storage. Mdkit applies the checkpoint policy and calls your store's
+checkpoint creation method when needed. See
+[`createMdKitBackend`](./api.md#createmdkitbackend).
+
+## Endpoint Shape
+
+If you are not using Fastify, implement these routes with your server framework:
+
+| Method | Path | Behavior |
+| --- | --- | --- |
+| `GET` | `/mdkit/documents?documentId=...` | Read the current document. |
+| `PUT` | `/mdkit/documents?documentId=...` | Write current content with `baseVersion`. |
+| `POST` | `/mdkit/documents/resync?documentId=...` | Force a fresh current-document read. |
+| `GET` | `/mdkit/versions?documentId=...` | List checkpoints as `{ versions }`. |
+| `GET` | `/mdkit/versions/:versionId?documentId=...` | Read one checkpoint. |
+| `POST` | `/mdkit/versions/:versionId/restore?documentId=...` | Restore one checkpoint. |
+
+The REST frontend adapter expects the same JSON shapes as
+`MdKitDocumentAdapter`. Write conflicts should return the conflict body with
+HTTP `409`; the adapter treats that as a successful mdkit response so the editor
+can show the conflict workflow.

package/docs/shadcn.md

@@ -20,10 +20,10 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { Textarea } from "@/components/ui/textarea";
 ```
 
-That means the workflow component can own polished app UI: toolbar, version
+That means the workflow component can own polished app UI: toolbar, checkpoint
 history dialog, conflict dialog, tabs, buttons, and layout. The underlying state
-still comes from the mdkit hooks. The recommended transport for this path is the
-tRPC adapter from `@mp-lb/mdkit/trpc/client`.
+still comes from the mdkit hooks. The recommended transport for this path is
+the tRPC adapter from `@mp-lb/mdkit/trpc/client`.
 
 ## Intended Shape
 
@@ -48,16 +48,19 @@ export function EditorScreen() {
   const adapter = createMdKitTrpcAdapter({ client });
   const document = useMdKitDocument({ adapter, documentId });
   const versions = useMdKitDocumentVersions({ adapter, documentId });
+
   const collaboration = useMdKitCollaboration({
     collaborator,
     documentId,
     endpoint: hocuspocusEndpoint,
   });
+
   const restoreVersion = async (version) => {
     await client.restoreDocumentVersion.mutate({
       documentId,
       versionId: version.id,
     });
+
     await document.resync();
     await versions.refresh();
   };

package/docs/styling.md

@@ -196,7 +196,7 @@ Example:
 - `.mp-lb-mdkit-conflict-panel`: root element
 - `.mp-lb-mdkit-conflict-panel-content`: title, explanatory text, and metadata
 - `.mp-lb-mdkit-conflict-panel-error`: error text
-- `.mp-lb-mdkit-conflict-panel-meta`: remote version metadata
+- `.mp-lb-mdkit-conflict-panel-meta`: remote revision metadata
 - `.mp-lb-mdkit-conflict-panel-preview`: preview area
 - `.mp-lb-mdkit-conflict-panel-tabs`: preview tab list
 - `.mp-lb-mdkit-conflict-panel-tab`: preview tab button
@@ -206,22 +206,23 @@ Example:
 
 The preview tabs also use `aria-selected` for state-aware styling.
 
-### Version History Panel
+### Checkpoint History Panel
 
-`VersionHistoryPanel` renders a version list, selected version preview, restore
-action, and empty/error states.
+`VersionHistoryPanel` renders checkpoint history: a checkpoint list, selected
+checkpoint preview, restore action, and empty/error states. The component and
+CSS class names keep `version-history` for current API compatibility.
 
 - `.mp-lb-mdkit-version-history-panel`: root element
 - `.mp-lb-mdkit-version-history-header`: panel header
 - `.mp-lb-mdkit-version-history-title`: panel title
 - `.mp-lb-mdkit-version-history-subtitle`: panel subtitle
 - `.mp-lb-mdkit-version-history-layout`: list and preview layout
-- `.mp-lb-mdkit-version-history-list`: version list
-- `.mp-lb-mdkit-version-history-item`: version list item button
-- `.mp-lb-mdkit-version-history-item-active`: selected version list item
+- `.mp-lb-mdkit-version-history-list`: checkpoint list
+- `.mp-lb-mdkit-version-history-item`: checkpoint list item button
+- `.mp-lb-mdkit-version-history-item-active`: selected checkpoint list item
 - `.mp-lb-mdkit-version-history-item-title`: list item title
-- `.mp-lb-mdkit-version-history-item-meta`: list item or selected version metadata
-- `.mp-lb-mdkit-version-history-preview`: selected version preview area
+- `.mp-lb-mdkit-version-history-item-meta`: list item or selected checkpoint metadata
+- `.mp-lb-mdkit-version-history-preview`: selected checkpoint preview area
 - `.mp-lb-mdkit-version-history-preview-header`: preview header
 - `.mp-lb-mdkit-version-history-preview-title`: preview title
 - `.mp-lb-mdkit-version-history-code`: markdown preview code block
@@ -232,7 +233,7 @@ action, and empty/error states.
 
 ### Shared Panel Actions
 
-Conflict and version panels share generic action classes:
+Conflict and checkpoint panels share generic action classes:
 
 - `.mp-lb-mdkit-panel-primary-action`: primary action button
 - `.mp-lb-mdkit-panel-secondary-action`: secondary action button

package/docs/use-cases.md

@@ -0,0 +1,148 @@
+# Use Cases
+
+MDKit is designed as independent layers. Use only the pieces your product
+needs:
+
+| Layers | Behavior |
+| --- | --- |
+| Editor only | Controlled markdown editor. No backend, checkpoints, or collaboration. |
+| Editor + storage | Autosave, current-document reads/writes, and conflict handling. |
+| Editor + storage + checkpoints | Autosave plus meaningful history and restore. |
+| Editor + storage + collaboration | Live collaboration plus canonical markdown snapshots. |
+| Full stack | Storage, checkpoints, restore, collaboration, and permissions. |
+
+## Core Model
+
+MDKit treats historical document state as checkpoint history.
+
+A checkpoint is an immutable markdown snapshot with metadata. Version-per-write
+is not a separate architecture; it is the checkpoint policy where every
+successful write creates a checkpoint. No history is the checkpoint
+policy where checkpoint creation is disabled.
+
+That gives MDKit one history abstraction:
+
+- autosave writes the canonical current markdown document
+- checkpoint rules decide when current content becomes user-facing history
+- history UI lists, previews, and restores checkpoints
+
+## Checkpoint Policies
+
+### Never
+
+The app stores one current markdown document. The document still has an opaque
+revision token for conflict detection, but no user-facing history.
+
+### Always
+
+Every successful write creates a checkpoint. This is useful for deliberate
+manual-save products, but it is usually too noisy for autosave because
+autosave writes can be tiny implementation details.
+
+### Manual
+
+Manual checkpoints are created by explicit user or product actions such as Save
+checkpoint, publish, approve, or mark milestone.
+
+### Smart
+
+Autosave keeps the current document durable. A smart checkpoint policy decides
+when a change is meaningful enough to become history. Practical policies use
+values such as edit distance, elapsed time since the last checkpoint, author,
+and write context.
+
+```ts
+const policy = CheckpointPolicy.smart({
+  minEditDistance: 250,
+  minIntervalMs: 5 * 60_000,
+});
+```
+
+Use a custom function when the built-in policy is not enough:
+
+```ts
+const policy = CheckpointPolicy.function(
+  ({
+    currentContent,
+    editDistance,
+    previousCheckpointContent,
+    timeSinceLastCheckpointMs,
+  }) =>
+    editDistance > 500 ||
+    timeSinceLastCheckpointMs > 10 * 60_000 ||
+    currentContent.startsWith("# Published") !==
+      previousCheckpointContent?.startsWith("# Published"),
+);
+```
+
+The function receives both computed values and raw document content, so products
+can use mdkit's edit-distance calculation or compute their own comparison.
+
+## Canonical Data
+
+The canonical current document is markdown plus metadata:
+
+- `documentId`
+- `content`
+- `revision`
+- `updatedAt`
+- optional caller-owned metadata
+
+`revision` is an opaque concurrency token. It is not the same thing as a
+checkpoint id.
+
+Checkpoints are immutable markdown snapshots:
+
+- `checkpointId`
+- `documentId`
+- `content`
+- `createdAt`
+- `sourceRevision`
+- optional caller-owned metadata
+
+The application owns product metadata, authorship, permissions, tenancy, and
+audit data. MDKit should pass that data through without inspecting it.
+
+## Restore
+
+The safest restore flow preserves current work before replacing it:
+
+- read the checkpoint being restored
+- checkpoint the current document if it is not already represented
+- update the canonical current document to the restored content
+- create a new current revision
+- reset collaboration state if collaboration is enabled
+
+The restored checkpoint remains immutable. Products can choose whether restore
+also creates a restore checkpoint at the top of history.
+
+## Collaboration
+
+Yjs state is the live collaboration state. Markdown remains the canonical
+snapshot format for current-document storage and checkpoint history.
+
+The opinionated collaboration flow is:
+
+- seed an empty collaboration room from canonical markdown
+- persist Yjs state through application-owned durable storage connected to the
+  collaboration server
+- snapshot active Yjs state to markdown before updating canonical storage or
+  creating a checkpoint
+- on restore, replace canonical markdown and reset/reseed collaboration state
+
+Correctness is more important than preserving cursor continuity. A restore may
+close or reset active collaboration sessions.
+
+## API Direction
+
+The current package already exposes the editor, storage hooks, checkpoint-list
+hooks, base panels, tRPC/REST helpers, and markdown/Yjs conversion helpers.
+
+Future backend helpers should add:
+
+- checkpoint policy helpers for `never`, `always`, `smart`, and custom
+  functions
+- first-class checkpoint creation
+- restore as a frontend/backend workflow
+- generic metadata/context passthrough
+- collaboration helpers for markdown/Yjs seeding, snapshotting, and reset

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mp-lb/mdkit",
-  "version": "0.2.3-main.20.1",
+  "version": "0.2.3-main.21.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -29,6 +29,11 @@
       "import": "./dist/fastify.js",
       "types": "./dist/fastify.d.ts"
     },
+    "./server": {
+      "source": "./src/server.ts",
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    },
     "./trpc": {
       "source": "./src/trpc.ts",
       "import": "./dist/trpc.js",