@mp-lb/mdkit 0.2.5 → 0.3.1

package/dist/markdown/yamlFrontMatter.js

@@ -0,0 +1,88 @@
+import { parseDocument } from "yaml";
+const delimiter = "---";
+const getLineEnd = (markdown, lineStart) => {
+    const newlineIndex = markdown.indexOf("\n", lineStart);
+    if (newlineIndex === -1) {
+        return {
+            contentEnd: markdown.length,
+            lineEnd: markdown.length,
+            newline: "",
+        };
+    }
+    const contentEnd = newlineIndex > lineStart && markdown[newlineIndex - 1] === "\r"
+        ? newlineIndex - 1
+        : newlineIndex;
+    return {
+        contentEnd,
+        lineEnd: newlineIndex + 1,
+        newline: markdown.slice(contentEnd, newlineIndex + 1),
+    };
+};
+const getNextBodyStart = (markdown, lineStart) => {
+    let bodyStart = lineStart;
+    while (bodyStart < markdown.length) {
+        const lineEnd = getLineEnd(markdown, bodyStart);
+        const line = markdown.slice(bodyStart, lineEnd.contentEnd);
+        if (!/^[ \t]*$/.test(line)) {
+            break;
+        }
+        bodyStart = lineEnd.lineEnd;
+    }
+    return bodyStart;
+};
+export const parseYamlFrontMatter = (yaml) => {
+    const document = parseDocument(yaml, { prettyErrors: false });
+    if (document.errors.length > 0) {
+        throw new Error(document.errors.map((error) => error.message).join("\n"));
+    }
+    return document.toJSON();
+};
+export const extractYamlFrontMatter = (markdown) => {
+    const openingLine = getLineEnd(markdown, 0);
+    if (markdown.slice(0, openingLine.contentEnd) !== delimiter) {
+        return { body: markdown, errors: [], frontMatter: null };
+    }
+    let lineStart = openingLine.lineEnd;
+    while (lineStart < markdown.length) {
+        const lineEnd = getLineEnd(markdown, lineStart);
+        const line = markdown.slice(lineStart, lineEnd.contentEnd);
+        if (line !== delimiter) {
+            lineStart = lineEnd.lineEnd;
+            continue;
+        }
+        const bodyStart = getNextBodyStart(markdown, lineEnd.lineEnd);
+        const raw = markdown.slice(0, bodyStart);
+        const yaml = markdown.slice(openingLine.lineEnd, lineStart);
+        const trailingWhitespace = markdown.slice(lineEnd.lineEnd, bodyStart);
+        try {
+            const data = parseYamlFrontMatter(yaml);
+            return {
+                body: markdown.slice(bodyStart),
+                errors: [],
+                frontMatter: {
+                    data,
+                    raw,
+                    trailingWhitespace,
+                    yaml,
+                },
+            };
+        }
+        catch (error) {
+            return {
+                body: markdown,
+                errors: [error instanceof Error ? error.message : String(error)],
+                frontMatter: null,
+            };
+        }
+    }
+    return { body: markdown, errors: [], frontMatter: null };
+};
+export const hasYamlFrontMatter = (markdown) => extractYamlFrontMatter(markdown).frontMatter !== null;
+export const removeYamlFrontMatter = (markdown) => extractYamlFrontMatter(markdown).body;
+export const prependYamlFrontMatter = (frontMatter, body) => {
+    if (!frontMatter) {
+        return body;
+    }
+    const raw = typeof frontMatter === "string" ? frontMatter : frontMatter.raw;
+    return `${raw}${body}`;
+};

package/dist/theme/editorTheme.js

@@ -1,13 +1,13 @@
 export const defaultMdKitEditorTheme = {
     background: "#ffffff",
-    blockGap: "0.75rem",
+    blockGap: "0.72em",
     border: "#d8dee8",
     codeBackground: "#eef1f4",
     codeRadius: "0.35rem",
     fontFamily: "inherit",
     fontSize: "16px",
     foreground: "#18212f",
-    lineHeight: "1.7",
+    lineHeight: "1.55",
     link: "#4f46e5",
     muted: "#eef1f4",
     mutedForeground: "#5b6472",
@@ -15,14 +15,14 @@ export const defaultMdKitEditorTheme = {
 };
 export const darkMdKitEditorTheme = {
     background: "#0b1220",
-    blockGap: "0.75rem",
+    blockGap: "0.72em",
     border: "#314158",
     codeBackground: "#111827",
     codeRadius: "0.35rem",
     fontFamily: "inherit",
     fontSize: "16px",
     foreground: "#e5edf7",
-    lineHeight: "1.7",
+    lineHeight: "1.55",
     link: "#38bdf8",
     muted: "#172033",
     mutedForeground: "#94a3b8",

package/dist/yjs/MdKitMarkdownYjs.d.ts

@@ -1,6 +1,7 @@
 import * as Y from "yjs";
 export type MdKitMarkdownYjsOptions = {
     fragmentName?: string;
+    ignoreYamlFrontMatter?: boolean;
 };
 export declare const replaceMdKitYjsMarkdown: (ydoc: Y.Doc, markdown: string, options?: MdKitMarkdownYjsOptions) => Uint8Array;
 export declare const markdownToMdKitYjs: (markdown: string, options?: MdKitMarkdownYjsOptions) => Uint8Array;

package/dist/yjs/MdKitMarkdownYjs.js

@@ -3,10 +3,14 @@ import { MarkdownManager } from "@tiptap/markdown";
 import { prosemirrorJSONToYXmlFragment, yXmlFragmentToProsemirrorJSON, } from "@tiptap/y-tiptap";
 import * as Y from "yjs";
 import { createMdKitTiptapExtensions } from "../markdown/createMdKitTiptapExtensions.js";
+import { extractYamlFrontMatter, prependYamlFrontMatter, } from "../markdown/yamlFrontMatter.js";
 import { normalizeMarkdownSerialization } from "../markdown/normalizeMarkdownSerialization.js";
 import { prepareMarkdownForEditorHydration } from "../markdown/prepareMarkdownForEditorHydration.js";
 const defaultMdKitYjsFragmentName = "default";
+const mdKitYjsMetadataMapName = "__mdkit";
+const frontMatterPrefixMetadataKey = "frontMatterPrefix";
 const getMdKitYjsFragmentName = (options) => options?.fragmentName ?? defaultMdKitYjsFragmentName;
+const getFrontMatterPrefixMetadataKey = (fragmentName) => `${fragmentName}:${frontMatterPrefixMetadataKey}`;
 const createMdKitMarkdownManager = () => new MarkdownManager({
     extensions: createMdKitTiptapExtensions(),
     markedOptions: {
@@ -17,10 +21,22 @@ const createMdKitProseMirrorSchema = () => getSchema(createMdKitTiptapExtensions
 const markdownToProseMirrorJson = (markdown) => createMdKitMarkdownManager().parse(prepareMarkdownForEditorHydration(markdown));
 const proseMirrorJsonToMarkdown = (json) => normalizeMarkdownSerialization(createMdKitMarkdownManager().serialize(json));
 export const replaceMdKitYjsMarkdown = (ydoc, markdown, options) => {
-    const fragment = ydoc.getXmlFragment(getMdKitYjsFragmentName(options));
+    const fragmentName = getMdKitYjsFragmentName(options);
+    const fragment = ydoc.getXmlFragment(fragmentName);
+    const metadata = ydoc.getMap(mdKitYjsMetadataMapName);
     const schema = createMdKitProseMirrorSchema();
-    const json = markdownToProseMirrorJson(markdown);
+    const frontMatter = options?.ignoreYamlFrontMatter
+        ? extractYamlFrontMatter(markdown)
+        : null;
+    const json = markdownToProseMirrorJson(frontMatter?.body ?? markdown);
+    const metadataKey = getFrontMatterPrefixMetadataKey(fragmentName);
     prosemirrorJSONToYXmlFragment(schema, json, fragment);
+    if (frontMatter?.frontMatter) {
+        metadata.set(metadataKey, frontMatter.frontMatter.raw);
+    }
+    else {
+        metadata.delete(metadataKey);
+    }
     return Y.encodeStateAsUpdate(ydoc);
 };
 export const markdownToMdKitYjs = (markdown, options) => {
@@ -30,8 +46,11 @@ export const markdownToMdKitYjs = (markdown, options) => {
 export const mdKitYjsToMarkdown = (yjsState, options) => {
     const ydoc = new Y.Doc();
     Y.applyUpdate(ydoc, yjsState);
-    const json = yXmlFragmentToProsemirrorJSON(ydoc.getXmlFragment(getMdKitYjsFragmentName(options)));
-    return proseMirrorJsonToMarkdown(json);
+    const fragmentName = getMdKitYjsFragmentName(options);
+    const json = yXmlFragmentToProsemirrorJSON(ydoc.getXmlFragment(fragmentName));
+    const metadata = ydoc.getMap(mdKitYjsMetadataMapName);
+    const frontMatterRaw = metadata.get(getFrontMatterPrefixMetadataKey(fragmentName)) ?? "";
+    return prependYamlFrontMatter(frontMatterRaw, proseMirrorJsonToMarkdown(json));
 };
 export const yjs = {
     markdownToMdKitYjs,

package/docs/.vitepress/config.ts

@@ -7,6 +7,7 @@ export default defineConfig({
   themeConfig: {
     nav: [
       { text: "Quick Start", link: "/" },
+      { text: "Plain Text", link: "/plain-text" },
       { text: "Styling", link: "/styling" },
       { text: "Shadcn", link: "/shadcn" },
       { text: "REST", link: "/rest" },
@@ -21,6 +22,7 @@ export default defineConfig({
         text: "Guide",
         items: [
           { text: "Quick Start", link: "/" },
+          { text: "Plain Text Editors", link: "/plain-text" },
           { text: "Styling", link: "/styling" },
           { text: "Shadcn Plugin", link: "/shadcn" },
           { text: "REST Backend", link: "/rest" },

package/docs/api.md

@@ -39,6 +39,7 @@ Local editing props:
 - `onChange?: (markdown: string) => void`
 - `onFocusChange?: (focused: boolean) => void`
 - `fillHeight?: boolean`
+- `search?: boolean`
 - `instanceKey?: string | number`
 - `className?: string`
 - `style?: CSSProperties`
@@ -50,6 +51,7 @@ Collaborative editing props:
 - `onChange?: (markdown: string) => void`
 - `onFocusChange?: (focused: boolean) => void`
 - `fillHeight?: boolean`
+- `search?: boolean`
 - `className?: string`
 - `style?: CSSProperties`
 
@@ -57,6 +59,10 @@ Collaborative editing props:
 keep blank space below the last line clickable so it focuses the cursor at the
 end. Leave it off when the host application owns sizing and scrolling.
 
+`search` opts the editor into the built-in document search panel. The panel is
+not rendered by default; when enabled, users open it with `Cmd+F` on macOS or
+`Ctrl+F` on Windows/Linux.
+
 The package stylesheet includes reset-resistant markdown rules for headings,
 lists, code blocks, blockquotes, and links. Styling is controlled with CSS
 variables on `.mp-lb-mdkit-markdown-editor`. See [Styling](./styling.md) for setup,

package/docs/index.md

@@ -113,7 +113,11 @@ export function ConnectedMarkdownEditor({
     () => createMdKitTrpcAdapter({ client: trpc.mdkit }),
     [trpc],
   );
-  const document = useMdKitDocument({ adapter, documentId });
+  const document = useMdKitDocument({
+    adapter,
+    debounceMs: 1000,
+    documentId,
+  });
   const versions = useMdKitDocumentVersions({ adapter, documentId });
 
   const collaboration = useMdKitCollaboration({

package/docs/plain-text.md

@@ -0,0 +1,131 @@
+# Plain Text Editors
+
+MDKit's connected workflow is not limited to `MdKitEditor`. The document hooks
+and backend adapters work with serialized text, so you can bring a plain text,
+code, JSON, or custom text editor and still use the same storage, autosave,
+checkpoint history, restore, and conflict handling.
+
+The one major exception is collaboration. Collaboration is currently a
+markdown/Tiptap capability because it depends on Yjs, ProseMirror, and the
+Tiptap collaboration extensions.
+
+## What Works
+
+Any editor can plug into the connected workflow if it behaves like a controlled
+text input:
+
+```tsx
+type TextEditorProps = {
+  value: string;
+  onChange(value: string): void;
+  onFocusChange?(focused: boolean): void;
+  readOnly?: boolean;
+};
+```
+
+That is enough for:
+
+- loading the current document
+- autosave
+- dirty state
+- conflict detection
+- force save
+- remote resync
+- checkpoint history
+- checkpoint restore
+
+The editor does not need to know about MDKit internals. It only needs to receive
+`document.value` and call `document.setContent`.
+
+## Example
+
+```tsx
+import {
+  MdKitConflictPanel,
+  MdKitDocumentToolbar,
+  VersionHistoryPanel,
+  useMdKitDocument,
+  useMdKitDocumentVersions,
+  type MdKitDocumentAdapter,
+} from "@mp-lb/mdkit";
+
+function PlainTextDocument({
+  adapter,
+  documentId,
+}: {
+  adapter: MdKitDocumentAdapter;
+  documentId: string;
+}) {
+  const document = useMdKitDocument({
+    adapter,
+    debounceMs: 1000,
+    documentId,
+  });
+  const versions = useMdKitDocumentVersions({ adapter, documentId });
+
+  return (
+    <>
+      <MdKitDocumentToolbar document={document} versions={versions} />
+
+      <textarea
+        readOnly={document.conflict}
+        value={document.value}
+        onBlur={() => document.setFocused(false)}
+        onChange={(event) => document.setContent(event.currentTarget.value)}
+        onFocus={() => document.setFocused(true)}
+      />
+
+      <MdKitConflictPanel document={document} />
+      <VersionHistoryPanel controller={versions} />
+    </>
+  );
+}
+```
+
+Use the same backend adapter you would use for markdown. The document content is
+still just `content: string`.
+
+## Backend Shape
+
+You do not need a separate backend for plain text documents. A single MDKit
+backend can expose:
+
+- document read/write
+- checkpoint list/read/restore
+- optional collaboration websocket routes
+- optional collaboration state persistence
+
+Plain text editors use the document and checkpoint APIs. Markdown collaborative
+editors additionally use the collaboration websocket and Yjs persistence.
+
+The underlying database layout is application-owned. It is reasonable to store
+markdown and plain text documents in the same documents table, or in separate
+tables if your product needs that. MDKit only requires a stable `documentId`,
+`content`, and an opaque revision token.
+
+## Collaboration Boundary
+
+Do not pass `useMdKitCollaboration` to a plain text editor. The current
+collaboration adapter is for `MdKitEditor` because that editor knows how to bind
+Tiptap to a Yjs document and render remote cursors.
+
+For plain text documents:
+
+- keep using `useMdKitDocument`
+- omit `useMdKitCollaboration`
+- omit collaboration UI
+- rely on optimistic conflicts and resync for multi-client safety
+
+If MDKit later adds a collaboration-capable CodeMirror, Monaco, or textarea
+adapter, that should be a new editor-specific capability. The generic text
+workflow does not need to change.
+
+## Testbench
+
+The testbench includes a connected stack named
+`Storage + checkpoints (plain text)`. It reuses the same checkpoints backend as
+the markdown stack, stores content under `docs/plain-text.txt`, and renders a
+controlled textarea instead of `MdKitEditor`.
+
+Use it to verify that plain text can autosave, create checkpoints, restore
+history, and avoid collaboration UI.

package/docs/shadcn.md

@@ -46,7 +46,11 @@ import { MdKitConnectedWorkflow } from "@/components/mdkit/mdkit-connected-workf
 export function EditorScreen() {
   const client = createMdKitTrpcClient({ url: "/trpc" });
   const adapter = createMdKitTrpcAdapter({ client });
-  const document = useMdKitDocument({ adapter, documentId });
+  const document = useMdKitDocument({
+    adapter,
+    debounceMs: 1000,
+    documentId,
+  });
   const versions = useMdKitDocumentVersions({ adapter, documentId });
 
   const collaboration = useMdKitCollaboration({

package/docs/styling.md

@@ -120,7 +120,8 @@ you need structural changes, component-specific spacing, or state styling.
 
 `MdKitEditor` renders the markdown editing surface and the selection bubble
 toolbar. The toolbar appears for non-empty text selections while the editor or
-toolbar has focus.
+toolbar has focus. The search panel appears only when `search` is enabled and
+the user opens it with the find keyboard shortcut.
 
 - `.mp-lb-mdkit-markdown-editor`: root element rendered by `MdKitEditor`
 - `.mp-lb-mdkit-markdown-editor-fill-height`: added to the root when
@@ -129,6 +130,10 @@ toolbar has focus.
 - `.mp-lb-mdkit-editor-surface`: scroll and background surface around the
   ProseMirror editor
 - `.mp-lb-mdkit-editor-empty`: loading or connecting placeholder
+- `.mp-lb-mdkit-search-panel`: optional document search panel
+- `.mp-lb-mdkit-search-input`: search text input
+- `.mp-lb-mdkit-search-status`: search result count
+- `.mp-lb-mdkit-search-button`: search navigation or close button
 - `.mp-lb-mdkit-tiptap`: ProseMirror editable element
 - `.mp-lb-mdkit-toolbar`: selection bubble toolbar
 - `.mp-lb-mdkit-toolbar-button`: toolbar button

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mp-lb/mdkit",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -94,6 +94,7 @@
     "lucide-react": "^0.554.0",
     "react-markdown": "10.1.0",
     "remark-gfm": "4.0.1",
+    "yaml": "2.9.0",
     "yjs": "^13.6.24",
     "zod": "^4.1.12"
   },