@mp-lb/mdkit 0.3.2 → 0.3.4

package/src/styles.css

@@ -40,20 +40,53 @@
   --mp-lb-mdkit-accent-foreground: var(--primary-foreground, #ffffff);
   --mp-lb-mdkit-link: #4f46e5;
   --mp-lb-mdkit-font-family: inherit;
-  --mp-lb-mdkit-font-size: 1rem;
-  --mp-lb-mdkit-line-height: 1.55;
-  --mp-lb-mdkit-surface-padding: 1rem;
-  --mp-lb-mdkit-block-gap: 0.72em;
-  --mp-lb-mdkit-tight-gap: 0.35em;
-  --mp-lb-mdkit-section-gap: 1.25em;
+  --mp-lb-mdkit-font-size: 16px;
+  --mp-lb-mdkit-line-height: 24px;
+  --mp-lb-mdkit-surface-padding: 0px;
+  --mp-lb-mdkit-document-margin-block: clamp(1.5rem, 6vh, 4rem);
+  --mp-lb-mdkit-document-margin-inline: clamp(1rem, 4vw, 3rem);
+  --mp-lb-mdkit-fixed-width-edge-padding: clamp(1rem, 3vw, 2rem);
+  --mp-lb-mdkit-fixed-width-inline-padding: max(
+    var(--mp-lb-mdkit-fixed-width-edge-padding),
+    calc(50% - 36rem)
+  );
+  --mp-lb-mdkit-fixed-width-document-inline-padding: max(
+    var(--mp-lb-mdkit-document-margin-inline),
+    calc(50% - 36rem)
+  );
+  --mp-lb-mdkit-block-gap: 1px;
+  --mp-lb-mdkit-tight-gap: 1px;
+  --mp-lb-mdkit-section-gap: 1px;
   --mp-lb-mdkit-list-item-gap: 0.125rem;
-  --mp-lb-mdkit-heading-font-weight: 650;
-  --mp-lb-mdkit-heading-1-size: 1.5rem;
-  --mp-lb-mdkit-heading-2-size: 1.25rem;
-  --mp-lb-mdkit-heading-3-size: 1.125rem;
+  --mp-lb-mdkit-heading-1-size: 40px;
+  --mp-lb-mdkit-heading-1-weight: 700;
+  --mp-lb-mdkit-heading-1-line-height: 44px;
+  --mp-lb-mdkit-heading-1-margin-top: 50px;
+  --mp-lb-mdkit-heading-1-margin-bottom: 4px;
+  --mp-lb-mdkit-heading-2-size: 30px;
+  --mp-lb-mdkit-heading-2-weight: 600;
+  --mp-lb-mdkit-heading-2-line-height: 39px;
+  --mp-lb-mdkit-heading-2-margin-top: 32px;
+  --mp-lb-mdkit-heading-2-margin-bottom: 4px;
+  --mp-lb-mdkit-heading-3-size: 24px;
+  --mp-lb-mdkit-heading-3-weight: 600;
+  --mp-lb-mdkit-heading-3-line-height: 32px;
+  --mp-lb-mdkit-heading-3-margin-top: 22px;
+  --mp-lb-mdkit-heading-3-margin-bottom: 1px;
+  --mp-lb-mdkit-heading-4-size: 20px;
+  --mp-lb-mdkit-heading-4-line-height: 26px;
+  --mp-lb-mdkit-heading-4-margin-top: 16px;
+  --mp-lb-mdkit-heading-5-size: 18px;
+  --mp-lb-mdkit-heading-5-line-height: 22px;
+  --mp-lb-mdkit-heading-5-margin-top: 14px;
+  --mp-lb-mdkit-heading-6-size: 16px;
+  --mp-lb-mdkit-heading-6-line-height: 20px;
+  --mp-lb-mdkit-heading-6-margin-top: 12px;
+  --mp-lb-mdkit-heading-minor-weight: 600;
+  --mp-lb-mdkit-block-padding: 3px 2px;
   --mp-lb-mdkit-code-background: var(--mp-lb-mdkit-muted);
   --mp-lb-mdkit-code-radius: 0.35rem;
-  --mp-lb-mdkit-code-block-radius: 0.75rem;
+  --mp-lb-mdkit-code-block-radius: 0.375rem;
   --mp-lb-mdkit-code-font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
     monospace;
   --mp-lb-mdkit-quote-border-color: var(--mp-lb-mdkit-border);
@@ -136,6 +169,20 @@
   padding: var(--mp-lb-mdkit-surface-padding);
 }
 
+.mp-lb-mdkit-markdown-editor-document-margins .mp-lb-mdkit-editor-surface {
+  padding-block: var(--mp-lb-mdkit-document-margin-block);
+  padding-inline: var(--mp-lb-mdkit-document-margin-inline);
+}
+
+.mp-lb-mdkit-markdown-editor-fixed-width .mp-lb-mdkit-editor-surface {
+  padding-inline: var(--mp-lb-mdkit-fixed-width-inline-padding);
+}
+
+.mp-lb-mdkit-markdown-editor-fixed-width.mp-lb-mdkit-markdown-editor-document-margins
+  .mp-lb-mdkit-editor-surface {
+  padding-inline: var(--mp-lb-mdkit-fixed-width-document-inline-padding);
+}
+
 .mp-lb-mdkit-search-panel {
   position: sticky;
   z-index: 5;
@@ -314,9 +361,17 @@
 }
 
 .mp-lb-mdkit-tiptap {
+  position: relative;
+  display: flex;
+  flex-direction: column;
   width: 100%;
   outline: none;
   line-height: var(--mp-lb-mdkit-line-height);
+  white-space: pre-wrap;
+  white-space: break-spaces;
+  word-wrap: break-word;
+  font-variant-ligatures: none;
+  font-feature-settings: "liga" 0;
 }
 
 .mp-lb-mdkit-markdown-editor-fill-height .mp-lb-mdkit-tiptap {
@@ -325,6 +380,13 @@
   flex: 1 1 auto;
 }
 
+.mp-lb-mdkit-markdown-editor-fill-height.mp-lb-mdkit-markdown-editor-document-margins
+  .mp-lb-mdkit-tiptap::after {
+  content: "";
+  display: block;
+  flex: 0 0 var(--mp-lb-mdkit-document-margin-block);
+}
+
 .mp-lb-mdkit-markdown-view.mp-lb-mdkit-markdown-editor-fill-height
   .mp-lb-mdkit-editor-shell {
   height: auto;
@@ -345,66 +407,72 @@
   flex: 0 0 auto;
 }
 
-.mp-lb-mdkit-tiptap
-  :is(p, h1, h2, h3, h4, h5, h6, ul, ol, blockquote, pre, table) {
-  margin: 0;
-}
-
-.mp-lb-mdkit-tiptap > * + * {
-  margin-top: var(--mp-lb-mdkit-block-gap);
-}
-
 .mp-lb-mdkit-tiptap h1,
 .mp-lb-mdkit-tiptap h2,
 .mp-lb-mdkit-tiptap h3,
 .mp-lb-mdkit-tiptap h4,
 .mp-lb-mdkit-tiptap h5,
 .mp-lb-mdkit-tiptap h6 {
-  font-weight: var(--mp-lb-mdkit-heading-font-weight);
+  padding: var(--mp-lb-mdkit-block-padding);
 }
 
 .mp-lb-mdkit-tiptap h1 {
+  margin: var(--mp-lb-mdkit-heading-1-margin-top) 0
+    var(--mp-lb-mdkit-heading-1-margin-bottom);
   font-size: var(--mp-lb-mdkit-heading-1-size);
-  line-height: 1.25;
+  font-weight: var(--mp-lb-mdkit-heading-1-weight);
+  line-height: var(--mp-lb-mdkit-heading-1-line-height);
 }
 
 .mp-lb-mdkit-tiptap h2 {
+  margin: var(--mp-lb-mdkit-heading-2-margin-top) 0
+    var(--mp-lb-mdkit-heading-2-margin-bottom);
   font-size: var(--mp-lb-mdkit-heading-2-size);
-  line-height: 1.3;
+  font-weight: var(--mp-lb-mdkit-heading-2-weight);
+  line-height: var(--mp-lb-mdkit-heading-2-line-height);
 }
 
-.mp-lb-mdkit-tiptap h3,
-.mp-lb-mdkit-tiptap h4,
-.mp-lb-mdkit-tiptap h5,
-.mp-lb-mdkit-tiptap h6 {
+.mp-lb-mdkit-tiptap h3 {
+  margin: var(--mp-lb-mdkit-heading-3-margin-top) 0
+    var(--mp-lb-mdkit-heading-3-margin-bottom);
   font-size: var(--mp-lb-mdkit-heading-3-size);
-  line-height: 1.35;
+  font-weight: var(--mp-lb-mdkit-heading-3-weight);
+  line-height: var(--mp-lb-mdkit-heading-3-line-height);
 }
 
-.mp-lb-mdkit-tiptap ul,
-.mp-lb-mdkit-tiptap ol {
-  margin: 0;
-  padding-left: 1.5rem;
+.mp-lb-mdkit-tiptap h4 {
+  margin: var(--mp-lb-mdkit-heading-4-margin-top) 0 1px;
+  font-size: var(--mp-lb-mdkit-heading-4-size);
+  font-weight: var(--mp-lb-mdkit-heading-minor-weight);
+  line-height: var(--mp-lb-mdkit-heading-4-line-height);
 }
 
-.mp-lb-mdkit-tiptap
-  > :is(h1, h2, h3)
-  + :is(p, ul, ol, blockquote, pre, table) {
-  margin-top: var(--mp-lb-mdkit-tight-gap);
+.mp-lb-mdkit-tiptap h5 {
+  margin: var(--mp-lb-mdkit-heading-5-margin-top) 0 1px;
+  font-size: var(--mp-lb-mdkit-heading-5-size);
+  font-weight: var(--mp-lb-mdkit-heading-minor-weight);
+  line-height: var(--mp-lb-mdkit-heading-5-line-height);
 }
 
-.mp-lb-mdkit-tiptap > p + p {
-  margin-top: var(--mp-lb-mdkit-block-gap);
+.mp-lb-mdkit-tiptap h6 {
+  margin: var(--mp-lb-mdkit-heading-6-margin-top) 0 1px;
+  font-size: var(--mp-lb-mdkit-heading-6-size);
+  font-weight: var(--mp-lb-mdkit-heading-minor-weight);
+  line-height: var(--mp-lb-mdkit-heading-6-line-height);
 }
 
-.mp-lb-mdkit-tiptap > :is(p, ul, ol) + :is(ul, ol, p) {
-  margin-top: var(--mp-lb-mdkit-tight-gap);
+.mp-lb-mdkit-tiptap p {
+  margin: 1px 0 0;
+  padding: var(--mp-lb-mdkit-block-padding);
+  font-size: var(--mp-lb-mdkit-font-size);
+  line-height: var(--mp-lb-mdkit-line-height);
 }
 
-.mp-lb-mdkit-tiptap
-  > :is(p, ul, ol, blockquote, pre, table, hr)
-  + :is(h1, h2, h3) {
-  margin-top: var(--mp-lb-mdkit-section-gap);
+.mp-lb-mdkit-tiptap ul,
+.mp-lb-mdkit-tiptap ol {
+  margin: 1px 0 0;
+  padding: var(--mp-lb-mdkit-block-padding);
+  padding-left: 1.5rem;
 }
 
 .mp-lb-mdkit-tiptap ul {
@@ -437,8 +505,8 @@
 }
 
 .mp-lb-mdkit-tiptap pre {
-  margin: 0;
-  padding: 0.75rem 0.875rem;
+  margin: 0.5rem 0;
+  padding: 2rem;
   overflow-x: auto;
   border: 1px solid var(--mp-lb-mdkit-border);
   border-radius: var(--mp-lb-mdkit-code-block-radius);
@@ -459,17 +527,28 @@
 }
 
 .mp-lb-mdkit-tiptap blockquote {
-  margin: 0;
-  padding-left: 0.875rem;
-  border-left: 3px solid var(--mp-lb-mdkit-quote-border-color);
+  position: relative;
+  margin: 4px 0;
+  padding-block: 3px;
+  padding-inline: 1em 2px;
+  border-left: 0;
   color: var(--mp-lb-mdkit-muted-foreground);
 }
 
+.mp-lb-mdkit-tiptap blockquote::before {
+  content: "";
+  position: absolute;
+  top: 2px;
+  bottom: 2px;
+  display: block;
+  border-inline-start: 0.25em solid var(--mp-lb-mdkit-quote-border-color);
+  inset-inline-start: 2px;
+}
+
 .mp-lb-mdkit-tiptap hr {
-  height: 1px;
-  border: 0;
-  background: var(--mp-lb-mdkit-border);
-  margin: var(--mp-lb-mdkit-section-gap) 0;
+  border-width: 1px 0 0;
+  color: var(--mp-lb-mdkit-border);
+  margin: 13px 0;
 }
 
 .mp-lb-mdkit-tiptap img {

package/src/theme/MdKitThemeEditor.tsx

@@ -0,0 +1,134 @@
+import type { MdKitEditorTheme } from "./editorTheme";
+
+export type MdKitThemeEditorProps = {
+  className?: string;
+  onChange: (theme: MdKitEditorTheme) => void;
+  onReset?: () => void;
+  theme: MdKitEditorTheme;
+};
+
+/**
+ * Optional controls for editing an {@link MdKitEditorTheme}. Intended for theme
+ * builders, docs, and debug tools rather than production editing surfaces.
+ */
+export const MdKitThemeEditor = ({
+  className,
+  onChange,
+  onReset,
+  theme,
+}: MdKitThemeEditorProps) => {
+  const updateTheme = (patch: Partial<MdKitEditorTheme>) => {
+    onChange({
+      ...theme,
+      ...patch,
+    });
+  };
+
+  return (
+    <div className={["mp-lb-mdkit-theme-editor", className].filter(Boolean).join(" ")}>
+      <label>
+        <span>Background</span>
+        <input
+          type="color"
+          value={theme.background}
+          onChange={(event) => updateTheme({ background: event.target.value })}
+        />
+      </label>
+      <label>
+        <span>Text</span>
+        <input
+          type="color"
+          value={theme.foreground}
+          onChange={(event) => updateTheme({ foreground: event.target.value })}
+        />
+      </label>
+      <label>
+        <span>Link</span>
+        <input
+          type="color"
+          value={theme.link}
+          onChange={(event) => updateTheme({ link: event.target.value })}
+        />
+      </label>
+      <label>
+        <span>Code</span>
+        <input
+          type="color"
+          value={theme.codeBackground}
+          onChange={(event) =>
+            updateTheme({
+              codeBackground: event.target.value,
+              muted: event.target.value,
+            })
+          }
+        />
+      </label>
+      <label>
+        <span>Font size</span>
+        <input
+          type="range"
+          min="13"
+          max="22"
+          value={Number.parseInt(theme.fontSize, 10)}
+          onChange={(event) =>
+            updateTheme({ fontSize: `${event.target.value}px` })
+          }
+        />
+      </label>
+      <label>
+        <span>Font</span>
+        <select
+          value={theme.fontFamily}
+          onChange={(event) => updateTheme({ fontFamily: event.target.value })}
+        >
+          <option value="inherit">App default</option>
+          <option value="ui-serif, Georgia, Cambria, serif">Serif</option>
+          <option value="ui-sans-serif, system-ui, sans-serif">Sans</option>
+          <option value="ui-monospace, SFMono-Regular, Menlo, monospace">
+            Mono
+          </option>
+        </select>
+      </label>
+      <label>
+        <span>Line height</span>
+        <input
+          type="range"
+          min="1.2"
+          max="2.2"
+          step="0.1"
+          value={theme.lineHeight}
+          onChange={(event) => updateTheme({ lineHeight: event.target.value })}
+        />
+      </label>
+      <label>
+        <span>Padding</span>
+        <input
+          type="range"
+          min="0"
+          max="32"
+          value={Number.parseInt(theme.surfacePadding, 10)}
+          onChange={(event) =>
+            updateTheme({ surfacePadding: `${event.target.value}px` })
+          }
+        />
+      </label>
+      <label>
+        <span>Code radius</span>
+        <input
+          type="range"
+          min="0"
+          max="16"
+          value={Number.parseInt(theme.codeRadius, 10)}
+          onChange={(event) =>
+            updateTheme({ codeRadius: `${event.target.value}px` })
+          }
+        />
+      </label>
+      {onReset ? (
+        <button type="button" onClick={onReset}>
+          Reset style
+        </button>
+      ) : null}
+    </div>
+  );
+};

package/src/theme/editorTheme.ts

@@ -0,0 +1,72 @@
+import type { CSSProperties } from "react";
+
+export type MdKitEditorTheme = {
+  background: string;
+  blockGap: string;
+  border: string;
+  codeBackground: string;
+  codeRadius: string;
+  fontFamily: string;
+  fontSize: string;
+  foreground: string;
+  lineHeight: string;
+  link: string;
+  muted: string;
+  mutedForeground: string;
+  surfacePadding: string;
+};
+
+export type MdKitEditorThemeStyle = CSSProperties &
+  Record<`--mp-lb-mdkit-${string}`, string>;
+
+export const defaultMdKitEditorTheme: MdKitEditorTheme = {
+  background: "#ffffff",
+  blockGap: "1px",
+  border: "#d8dee8",
+  codeBackground: "#eef1f4",
+  codeRadius: "0.375rem",
+  fontFamily: "inherit",
+  fontSize: "16px",
+  foreground: "#18212f",
+  lineHeight: "1.5",
+  link: "#4f46e5",
+  muted: "#eef1f4",
+  mutedForeground: "#5b6472",
+  surfacePadding: "32px",
+};
+
+export const darkMdKitEditorTheme: MdKitEditorTheme = {
+  background: "#0b1220",
+  blockGap: "1px",
+  border: "#314158",
+  codeBackground: "#111827",
+  codeRadius: "0.375rem",
+  fontFamily: "inherit",
+  fontSize: "16px",
+  foreground: "#e5edf7",
+  lineHeight: "1.5",
+  link: "#38bdf8",
+  muted: "#172033",
+  mutedForeground: "#94a3b8",
+  surfacePadding: "32px",
+};
+
+export const createMdKitEditorThemeStyle = (
+  theme: MdKitEditorTheme,
+): MdKitEditorThemeStyle => ({
+  "--mp-lb-mdkit-background": theme.background,
+  "--mp-lb-mdkit-block-gap": theme.blockGap,
+  "--mp-lb-mdkit-border": theme.border,
+  "--mp-lb-mdkit-code-background": theme.codeBackground,
+  "--mp-lb-mdkit-code-radius": theme.codeRadius,
+  "--mp-lb-mdkit-code-block-radius": theme.codeRadius,
+  "--mp-lb-mdkit-font-family": theme.fontFamily,
+  "--mp-lb-mdkit-font-size": theme.fontSize,
+  "--mp-lb-mdkit-foreground": theme.foreground,
+  "--mp-lb-mdkit-line-height": theme.lineHeight,
+  "--mp-lb-mdkit-link": theme.link,
+  "--mp-lb-mdkit-muted": theme.muted,
+  "--mp-lb-mdkit-muted-foreground": theme.mutedForeground,
+  "--mp-lb-mdkit-quote-border-color": theme.border,
+  "--mp-lb-mdkit-surface-padding": theme.surfacePadding,
+});

package/src/transport/backend.ts

@@ -0,0 +1,220 @@
+import type {
+  MdKitDocumentSnapshot,
+  MdKitDocumentVersionDetail,
+  MdKitDocumentVersionSummary,
+  MdKitDocumentVersionToken,
+  MdKitDocumentWriteInput,
+  MdKitDocumentWriteResult,
+} from "../document/documentTypes";
+import {
+  CheckpointPolicy,
+  measureMdKitEditDistance,
+  type MdKitCheckpointPolicy,
+} from "../core/checkpointPolicy";
+import type {
+  MdKitRestoreDocumentVersionInput,
+  MdKitTransportStore,
+} from "./store";
+
+export type MdKitCreateCheckpointInput = {
+  content: string;
+  documentId: string;
+  metadata?: unknown;
+  sourceRevision: MdKitDocumentVersionToken;
+};
+
+/**
+ * Application-owned persistence contract consumed by {@link createMdKitBackend}.
+ * Implement it with your database; mdkit calls `createCheckpoint` when the
+ * configured {@link CheckpointPolicy} triggers — the store never interprets the
+ * policy itself.
+ */
+export type MdKitBackendStore = {
+  createCheckpoint?(
+    input: MdKitCreateCheckpointInput,
+  ): Promise<MdKitDocumentVersionSummary> | MdKitDocumentVersionSummary;
+  getLatestCheckpoint?(
+    documentId: string,
+  ): Promise<MdKitDocumentVersionDetail | null> | MdKitDocumentVersionDetail | null;
+  listDocumentVersions?(
+    documentId: string,
+  ): Promise<MdKitDocumentVersionSummary[]> | MdKitDocumentVersionSummary[];
+  readCollaborationState?(
+    documentName: string,
+  ): Promise<Uint8Array | null> | Uint8Array | null;
+  readDocument(
+    documentId: string,
+  ): Promise<MdKitDocumentSnapshot> | MdKitDocumentSnapshot;
+  readDocumentVersion?(input: {
+    documentId: string;
+    versionId: string;
+  }):
+    | Promise<MdKitDocumentVersionDetail | null>
+    | MdKitDocumentVersionDetail
+    | null;
+  resyncDocument?(
+    documentId: string,
+  ): Promise<MdKitDocumentSnapshot> | MdKitDocumentSnapshot;
+  restoreDocumentVersion?(
+    input: MdKitRestoreDocumentVersionInput,
+  ): Promise<MdKitDocumentWriteResult> | MdKitDocumentWriteResult;
+  writeCollaborationState?(
+    documentName: string,
+    state: Uint8Array,
+  ): Promise<void> | void;
+  writeDocument(
+    input: MdKitDocumentWriteInput,
+  ): Promise<MdKitDocumentWriteResult> | MdKitDocumentWriteResult;
+};
+
+export type CreateMdKitBackendOptions = {
+  checkpointPolicy?: MdKitCheckpointPolicy;
+  store: MdKitBackendStore;
+};
+
+const timestampMs = (value: string | null | undefined) => {
+  if (!value) {
+    return null;
+  }
+
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+};
+
+const successfulWriteRevision = (result: MdKitDocumentWriteResult) =>
+  "conflict" in result ? null : result.version;
+
+const latestCheckpointFromList = async (
+  store: MdKitBackendStore,
+  documentId: string,
+) => {
+  const versions = await store.listDocumentVersions?.(documentId);
+  const latestSummary = versions?.at(-1);
+
+  if (!latestSummary || !store.readDocumentVersion) {
+    return null;
+  }
+
+  return store.readDocumentVersion({
+    documentId,
+    versionId: latestSummary.id,
+  });
+};
+
+const readLatestCheckpoint = async (
+  store: MdKitBackendStore,
+  documentId: string,
+) =>
+  (await store.getLatestCheckpoint?.(documentId)) ??
+  (await latestCheckpointFromList(store, documentId));
+
+const maybeCreateCheckpoint = async (
+  store: MdKitBackendStore,
+  policy: MdKitCheckpointPolicy,
+  input: MdKitDocumentWriteInput,
+  result: MdKitDocumentWriteResult,
+) => {
+  const sourceRevision = successfulWriteRevision(result);
+
+  if (!store.createCheckpoint || sourceRevision === null) {
+    return;
+  }
+
+  const previousCheckpoint = await readLatestCheckpoint(store, input.documentId);
+  const previousCheckpointContent = previousCheckpoint?.content ?? null;
+  const editDistance = measureMdKitEditDistance(
+    previousCheckpointContent ?? "",
+    input.content,
+  );
+  const checkpointTimestamp = timestampMs(previousCheckpoint?.createdAt);
+  const timeSinceLastCheckpointMs =
+    checkpointTimestamp === null ? null : Date.now() - checkpointTimestamp;
+  const shouldCheckpoint = await policy.shouldCheckpoint({
+    currentContent: input.content,
+    documentId: input.documentId,
+    editDistance,
+    previousCheckpoint,
+    previousCheckpointContent,
+    timeSinceLastCheckpointMs,
+    writeInput: input,
+    writeResult: result,
+  });
+
+  if (!shouldCheckpoint) {
+    return;
+  }
+
+  await store.createCheckpoint({
+    content: input.content,
+    documentId: input.documentId,
+    sourceRevision,
+  });
+};
+
+const restoreWithStorePrimitives = async (
+  store: MdKitBackendStore,
+  input: MdKitRestoreDocumentVersionInput,
+) => {
+  if (!store.readDocumentVersion) {
+    if (!store.restoreDocumentVersion) {
+      throw new Error("Version restore is not supported");
+    }
+
+    return store.restoreDocumentVersion(input);
+  }
+
+  const restoredVersion = await store.readDocumentVersion(input);
+
+  if (!restoredVersion) {
+    throw new Error(`Version not found: ${input.versionId}`);
+  }
+
+  const current = await store.readDocument(input.documentId);
+  const latestCheckpoint = await readLatestCheckpoint(store, input.documentId);
+
+  if (
+    store.createCheckpoint &&
+    latestCheckpoint?.content !== current.content
+  ) {
+    await store.createCheckpoint({
+      content: current.content,
+      documentId: input.documentId,
+      sourceRevision: current.version,
+    });
+  }
+
+  return store.writeDocument({
+    baseVersion: current.version,
+    content: restoredVersion.content,
+    documentId: input.documentId,
+    force: true,
+  });
+};
+
+/**
+ * Wraps an application {@link MdKitBackendStore} with checkpoint-policy
+ * orchestration, producing the transport-ready surface the Fastify and tRPC
+ * helpers mount. The store owns persistence, auth, and metadata; this owns
+ * checkpoint timing and restore ordering.
+ */
+export const createMdKitBackend = ({
+  checkpointPolicy = CheckpointPolicy.never(),
+  store,
+}: CreateMdKitBackendOptions): MdKitTransportStore => ({
+  listDocumentVersions: (documentId) =>
+    store.listDocumentVersions?.(documentId) ?? [],
+  readCollaborationState: (documentName) =>
+    store.readCollaborationState?.(documentName) ?? null,
+  readDocument: (documentId) => store.readDocument(documentId),
+  readDocumentVersion: (input) => store.readDocumentVersion?.(input) ?? null,
+  resyncDocument: (documentId) =>
+    (store.resyncDocument ?? store.readDocument)(documentId),
+  restoreDocumentVersion: (input) => restoreWithStorePrimitives(store, input),
+  writeCollaborationState: (documentName, state) =>
+    store.writeCollaborationState?.(documentName, state),
+  writeDocument: async (input) => {
+    const result = await store.writeDocument(input);
+    await maybeCreateCheckpoint(store, checkpointPolicy, input, result);
+    return result;
+  },
+});