@powerduck/md-editor 0.10.9 → 0.11.1

package/README.md

@@ -1,466 +1,395 @@
 # @powerduck/md-editor
 
-High-performance embeddable Markdown editor built on the markdown-it ecosystem. Supports KaTeX math formulas (self-contained, no texmath), Markmap mindmaps, highlight.js code blocks with traffic-light UI and copy button, github-markdown-css preview styling, admonition/tip blocks, rich toolbar with image/video/YouTube/table popup dialogs, keyboard shortcuts with help dialog, configurable toolbar, image upload hook, standalone `renderMarkdown()` API, native React integration, block-level incremental rendering with debounced scheduling. Ships in two modes: **simple** (no toolbar, pure edit + preview) and **complex** (toolbar + status bar). Styled via CSS custom properties with light/dark themes.
+High-performance embeddable Markdown editor with syntax highlighting, math formulas, mindmaps, @mentions, document link cards, and incremental rendering. Built on CodeMirror 6 with a React wrapper.
 
-## Features
+[![npm version](https://img.shields.io/npm/v/@powerduck/md-editor)](https://www.npmjs.com/package/@powerduck/md-editor)
+[![license](https://img.shields.io/npm/l/@powerduck/md-editor)](https://github.com/PowerDuckie/md-editor/blob/main/LICENSE)
 
-- **Markdown editing** powered by CodeMirror 6 with markdown syntax highlighting
-- **Math formulas** via self-contained KaTeX plugin (`$E=mc^2$` inline, `$$...$$` block) -- no texmath dependency, no double-rendering
-- **Mindmaps** via Markmap (```` ```mindmap ```` code fences)
-- **Code highlighting** via highlight.js -- 20+ languages, macOS-style traffic-light header, one-click copy button
-- **Admonition blocks** -- `:::notice`, `:::warning`, `:::tip`, `:::danger`, `:::info`, `:::success` with icons and colored borders
-- **github-markdown-css** preview -- proper heading, list, table, and typography styling
-- **Rich toolbar** -- heading, bold, italic, link, image, video, YouTube, quote, lists, code, table, math, mindmap, horizontal rule, tip block, preview toggle, help, theme toggle
-- **Popup dialogs** -- image URL, video URL, YouTube URL/ID, table rows/columns
-- **Keyboard shortcuts** -- Ctrl+B bold, Ctrl+I italic, Ctrl+K link, etc. with a Help dialog listing all shortcuts
-- **Configurable toolbar** -- show/hide items, custom labels and icons via `toolbar` option
-- **Image upload hook** -- paste/drop images, call `onImageUpload(file)` to get a URL
-- **Video rendering** -- `.mp4`, `.webm`, `.ogg` links render as `<video>` elements
-- **Standalone renderer** -- `renderMarkdown(source, options)` for consistent styling outside the editor
-- **Block-level incremental rendering** -- only changed sections re-render
-- **Adaptive debounce** -- preview render delay scales with document length
-- **Simple / Complex modes** -- toggle toolbar and status bar at runtime
-- **Light / Dark themes** -- CSS custom properties, inherits host design tokens
-- **React component** -- `forwardRef` with imperative handle
-
-## Installation
+## Links
 
-```bash
-npm install @powerduck/md-editor
-```
+- [Official Website](https://www.powerduck.com/opensource/md-editor.html)
+- [Documentation](https://www.powerduck.com/docs/md-editor/introduction)
+- [Live Demo](https://www.powerduck.com/demo/md-editor.html)
+- [GitHub](https://github.com/PowerDuckie/md-editor)
+- [npm](https://www.npmjs.com/package/@powerduck/md-editor)
 
-## Usage
+---
 
-### Vanilla JS
+## Quick Start
 
-```ts
-import { MarkdownEditor } from '@powerduck/md-editor';
-import '@powerduck/md-editor/dist/style.css';
-
-const editor = new MarkdownEditor('#editor', {
-  value: '# Hello\n\nStart typing...',
-  mode: 'complex', // 'simple' | 'complex'
-  theme: 'light',  // 'light' | 'dark'
-  math: true,
-  mindmap: true,
-  onChange: (value) => console.log(value)
-});
+### Install
+
+```bash
+npm install @powerduck/md-editor
 ```
 
-### React
+### React Component
 
 ```tsx
-import { MarkdownEditorReact } from '@powerduck/md-editor/react';
-import '@powerduck/md-editor/dist/style.css';
+import { useRef, useState } from "react";
+import { MarkdownEditorReact, type MarkdownEditorHandle } from "@powerduck/md-editor/react";
+import "@powerduck/md-editor/dist/style.css";
 
 function App() {
+  const [value, setValue] = useState("# Hello\n\nStart typing...");
+  const editorRef = useRef<MarkdownEditorHandle>(null);
+
   return (
-    <MarkdownEditorReact
-      defaultValue="# Hello"
-      mode="complex"
-      onChange={(v) => console.log(v)}
-    />
+    <div style={{ height: "600px" }}>
+      <MarkdownEditorReact
+        ref={editorRef}
+        value={value}
+        onChange={setValue}
+        mode="complex"
+        theme="light"
+      />
+      <button onClick={() => console.log(editorRef.current?.getHtml())}>
+        Get HTML
+      </button>
+    </div>
   );
 }
 ```
 
-## API
-
-### MarkdownEditorOptions
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `value` | `string` | `''` | Initial content |
-| `mode` | `'simple' \| 'complex'` | `'simple'` | Toolbar + status bar in complex mode |
-| `theme` | `'light' \| 'dark'` | `'light'` | Color theme |
-| `math` | `boolean` | `true` | Enable KaTeX math |
-| `mindmap` | `boolean` | `true` | Enable Markmap mindmaps |
-| `codeHighlight` | `boolean` | `true` | Enable highlight.js code blocks with copy button |
-| `tips` | `boolean` | `true` | Enable admonition/tip blocks (:::notice, :::warning, etc.) |
-| `preview` | `boolean` | `true` | Show preview pane |
-| `toolbar` | `ToolbarConfig` | all items | Configure which toolbar items show, their labels and icons |
-| `onImageUpload` | `(file: File) => Promise<string>` | - | Image upload hook for paste/drop |
-| `autoPreview` | `boolean` | `true` | Auto-render preview on edit |
-| `renderDebounce` | `number \| false` | adaptive | Preview debounce in ms |
-| `onChange` | `(value: string) => void` | - | Change callback |
-
-### Methods
-
-- `getValue(): string`
-- `setValue(value: string): void`
-- `getHtml(): string`
-- `renderNow(): void` -- manual preview render (use with `autoPreview: false`)
-- `setMode(mode: EditorMode): void`
-- `setTheme(theme: EditorTheme): void`
-- `setAutoPreview(auto: boolean): void`
-- `focus(): void`
-- `destroy(): void`
+### Vanilla JS
 
-## Mindmap Syntax
+```typescript
+import { MarkdownEditor } from "@powerduck/md-editor";
+import "@powerduck/md-editor/dist/style.css";
 
-````markdown
-```mindmap
-# Root topic
-## Branch one
-- Child A
-- Child B
-## Branch two
-- Child C
+const editor = new MarkdownEditor("#editor", {
+  value: "# Hello\n\nStart typing...",
+  mode: "complex",
+  theme: "light",
+  onChange: (value) => console.log(value.length, "chars"),
+});
+
+// Read and write content
+const markdown = editor.getValue();
+editor.setValue("# Updated content");
+
+// Render to HTML
+const html = editor.getHtml();
 ```
-````
 
-## Code Blocks
+### @mention Integration
 
-Code fences are automatically highlighted with highlight.js (20+ languages including JavaScript, TypeScript, Python, JSON, Bash, CSS, HTML, SQL, YAML, Go, Rust, Java, C/C++). Each code block gets a macOS-style header with traffic-light dots, a language label, and a copy button.
+```typescript
+import { MarkdownEditor, type MentionItem } from "@powerduck/md-editor";
+
+const USERS: MentionItem[] = [
+  { id: "1", label: "Alice", avatar: "https://example.com/a.png", description: "alice@example.com" },
+  { id: "2", label: "Bob", description: "bob@example.com" },
+];
+
+new MarkdownEditor("#editor", {
+  mode: "complex",
+  mention: {
+    onMentionSearch: async (query) =>
+      USERS.filter((u) => u.label.toLowerCase().includes(query.toLowerCase())),
+    onMentionSelect: (item) => `[@${item.label}](mention:${item.id})`,
+    minChars: 0,
+    maxItems: 8,
+  },
+});
+```
+
+### Document Link Card
+
+```typescript
+import { MarkdownEditor, type DocItem } from "@powerduck/md-editor";
+
+const DOCS: DocItem[] = [
+  { id: "d1", title: "Getting Started", url: "https://docs.example.com/start", description: "Quick start guide", thumbnail: "https://picsum.photos/seed/start/96/72" },
+  { id: "d2", title: "API Reference", url: "https://docs.example.com/api", description: "Full API documentation" },
+];
+
+new MarkdownEditor("#editor", {
+  mode: "complex",
+  docLink: {
+    onDocSearch: async (query) =>
+      DOCS.filter((d) => d.title.toLowerCase().includes(query.toLowerCase())),
+    onFetchDocMeta: async (url) => {
+      const res = await fetch(`/api/og?url=${encodeURIComponent(url)}`);
+      return res.json();
+    },
+    insertStyle: "auto", // "auto" | "card" | "link"
+    minChars: 0,
+    maxItems: 8,
+  },
+});
+```
+
+---
+
+## Features
+
+- **Syntax highlighting** — CodeMirror 6 with Markdown grammar and token colors
+- **Math formulas** — KaTeX rendering for inline `$...$` and block `$$...$$`
+- **Mindmaps** — Markmap interactive SVG diagrams from ```` ```mindmap ```` fenced blocks
+- **Code blocks** — highlight.js with traffic-light header and copy button
+- **@mentions** — Searchable dropdown with custom search/select hooks, inserts `[@label](mention:id)` for renderer distinction
+- **Document link cards** — Insert plain links or preview cards with auto-fetched title/thumbnail/description, with custom fetch hook
+- **Image upload** — Paste/drag/select image files with custom upload hook
+- **Task lists** — `- [ ]` / `- [x]` with clickable toggles in preview
+- **Callouts** — `:::notice`, `:::warning`, `:::danger`, etc.
+- **Tables** — Quick-insert popup with configurable rows/columns
+- **Incremental rendering** — Block-level DOM reuse for large documents, adaptive debounce
+- **Themes** — Light and dark themes with CSS custom properties
+- **Two modes** — `simple` (pure edit + preview) and `complex` (toolbar + status bar + line numbers)
+- **React wrapper** — `forwardRef` component with controlled/uncontrolled value and imperative handle
+- **Dual ESM/CJS builds** — Works with `import` and `require`
+
+---
+
+## MarkdownEditorOptions
 
-````markdown
 ```typescript
-interface User {
-  name: string;
-  age: number;
+interface MarkdownEditorOptions {
+  value?: string;
+  mode?: "simple" | "complex"; // default: "simple"
+  theme?: "light" | "dark"; // default: "light"
+  math?: boolean; // default: true
+  mindmap?: boolean; // default: true
+  codeHighlight?: boolean; // default: true
+  tips?: boolean; // default: true
+  preview?: boolean; // default: true
+  onChange?: (value: string) => void;
+  toolbar?: ToolbarConfig;
+  onImageUpload?: (file: File) => Promise<string>;
+  mention?: MentionOptions;
+  docLink?: DocLinkOptions;
+  renderDebounce?: number | false; // adaptive by default
+  autoPreview?: boolean; // default: true
 }
 ```
-````
 
-Unknown languages are auto-detected; if detection fails, the content is HTML-escaped and displayed as plain text. Disable code highlighting with `codeHighlight: false`.
+### MentionOptions
 
-## Media Insertion
+```typescript
+interface MentionOptions {
+  onMentionSearch?: (query: string) => MentionItem[] | Promise<MentionItem[]>;
+  onMentionSelect?: (item: MentionItem) => string; // default: `[@label](mention:id)`
+  minChars?: number; // default: 0
+  maxItems?: number; // default: 8
+}
 
-The complex-mode toolbar includes popup dialogs for inserting media:
+interface MentionItem {
+  id: string;
+  label: string;
+  avatar?: string;
+  description?: string;
+  [key: string]: unknown;
+}
+```
 
-- **Image** (`image` button): URL + alt text -> `![alt](url)`
-- **Video** (`video` button): URL (.mp4, .webm, .ogg) -> renders as `<video controls>` in preview
-- **YouTube** (`youtube` button): accepts any YouTube URL format (watch?v=, youtu.be, embed, shorts) or raw 11-char ID -> inserts a linked thumbnail image that opens the video on click
+### DocLinkOptions
 
-YouTube insertion extracts the video ID automatically and produces:
-```markdown
-[![YouTube video](https://img.youtube.com/vi/VIDEO_ID/hqdefault.jpg)](https://www.youtube.com/watch?v=VIDEO_ID)
+```typescript
+interface DocLinkOptions {
+  onDocSearch?: (query: string) => DocItem[] | Promise<DocItem[]>;
+  onFetchDocMeta?: (url: string) => Promise<DocMeta>;
+  insertStyle?: "card" | "link" | "auto"; // default: "auto"
+  triggerChar?: string; // default: "/"
+  minChars?: number; // default: 0
+  maxItems?: number; // default: 8
+}
+
+interface DocItem {
+  id: string;
+  title: string;
+  url: string;
+  thumbnail?: string;
+  description?: string;
+  [key: string]: unknown;
+}
 ```
 
-## Standalone Renderer
+---
 
-Use `renderMarkdown()` to render markdown with the same styling and plugins as the editor preview, without mounting an editor:
+## React Component Props
 
-```ts
-import { renderMarkdown } from '@powerduck/md-editor';
-import '@powerduck/md-editor/dist/style.css';
+```typescript
+interface MarkdownEditorProps extends Omit<MarkdownEditorOptions, "value" | "onChange"> {
+  value?: string; // controlled value
+  defaultValue?: string; // uncontrolled initial value (mount only)
+  onChange?: (value: string) => void;
+  className?: string;
+  style?: CSSProperties;
+}
 
-const html = renderMarkdown('# Hello\n\n$E=mc^2$\n\n:::tip\nWorks!\n:::');
-container.innerHTML = html;
+interface MarkdownEditorHandle {
+  getValue: () => string;
+  setValue: (value: string) => void;
+  getHtml: () => string;
+  focus: () => void;
+  setMode: (mode: "simple" | "complex") => void;
+  setTheme: (theme: "light" | "dark") => void;
+  renderNow: () => void;
+}
 ```
 
-Options: `math`, `mindmap`, `codeHighlight`, `tips`, `html`, `breaks` -- all default to `true` except `html` and `breaks`.
+> **Performance note:** Structural options (`mode`, `math`, `mindmap`, `preview`, `autoPreview`, `renderDebounce`) recreate the underlying instance when they change. `value`, `onChange`, and `theme` use lightweight sync paths and never recreate the instance, so controlled usage stays responsive on large documents.
 
-## Keyboard Shortcuts
+---
 
-| Shortcut | Action |
-|----------|--------|
-| `Ctrl+B` / `Cmd+B` | Bold |
-| `Ctrl+I` / `Cmd+I` | Italic |
-| `Ctrl+Alt+1` | Heading |
-| `Ctrl+K` / `Cmd+K` | Insert link |
-| `Ctrl+Alt+C` | Code block |
-| `Ctrl+Shift+.` | Blockquote |
-| `Ctrl+Shift+8` | Unordered list |
-| `Ctrl+Shift+7` | Ordered list |
-| `Ctrl+Alt+M` | Math formula |
-| `Ctrl+Alt+P` | Toggle preview |
-| `Ctrl+Shift+L` | Toggle theme |
-
-Click the **Help** (?) button in the toolbar to see all shortcuts at runtime.
-
-## Configurable Toolbar
-
-Control which buttons appear and customize their labels/icons:
-
-```ts
-// Only show specific buttons
-new MarkdownEditor('#editor', {
-  mode: 'complex',
-  toolbar: ['bold', 'italic', 'link', 'code']
+## Toolbar Actions
+
+22 built-in toolbar actions in default order:
+
+`heading`, `bold`, `italic`, `link`, `image`, `video`, `youtube`, `quote`, `ul`, `ol`, `tasklist`, `mention`, `doclink`, `code`, `table`, `math`, `mindmap`, `hr`, `tips`, `preview`, `help`, `theme`
+
+### Configure Toolbar
+
+```typescript
+// Array form: include-list (only these actions show, in this order)
+new MarkdownEditor("#editor", {
+  mode: "complex",
+  toolbar: ["bold", "italic", "link", "code", "math"],
 });
 
-// Fine-grained control
-new MarkdownEditor('#editor', {
-  mode: 'complex',
+// Record form: per-item overrides (everything not listed stays visible)
+new MarkdownEditor("#editor", {
+  mode: "complex",
   toolbar: {
-    bold: { label: 'Make bold', icon: '<b>B</b>' },
+    bold: { label: "Make bold" },
     image: { show: false },
-    youtube: { show: false }
-  }
+    youtube: { show: false },
+  },
 });
 ```
 
-## Image Upload
+---
 
-Provide an upload hook to handle pasted/dropped images:
+## Standalone Rendering
 
-```ts
-new MarkdownEditor('#editor', {
-  mode: 'complex',
-  onImageUpload: async (file) => {
-    const formData = new FormData();
-    formData.append('file', file);
-    const res = await fetch('/api/upload', { method: 'POST', body: formData });
-    const { url } = await res.json();
-    return url; // inserted as ![filename](url)
-  }
-});
+```typescript
+import { renderMarkdown } from "@powerduck/md-editor";
+import "@powerduck/md-editor/dist/style.css";
+
+const html = renderMarkdown("# Hello\n\n$E=mc^2$", { math: true });
+document.getElementById("output")!.innerHTML = html;
+```
+
+> `renderMarkdown` returns a string and does not mount an editor. Mindmap placeholders are emitted as inert `<div>`s; call `Renderer.hydrate` yourself if you need live diagrams outside the editor.
+
+---
+
+## Public API (Vanilla JS)
+
+```typescript
+class MarkdownEditor {
+  constructor(container: HTMLElement | string, options?: MarkdownEditorOptions);
+
+  getValue(): string;
+  setValue(value: string): void;
+  getHtml(): string;
+  renderNow(): void;
+  setAutoPreview(auto: boolean): void;
+  setMode(mode: "simple" | "complex"): void;
+  setTheme(theme: "light" | "dark"): void;
+  focus(): void;
+  destroy(): void;
+}
+```
+
+---
+
+## Keyboard Shortcuts
+
+| Shortcut | Action |
+|---|---|
+| `Ctrl/Cmd + B` | Bold |
+| `Ctrl/Cmd + I` | Italic |
+| `Ctrl/Cmd + K` | Link |
+| `Ctrl/Cmd + S` | (custom via onChange) |
+
+---
+
+## Mindmap Syntax
+
+````markdown
+```mindmap
+# Root topic
+## Branch one
+- Child A
+- Child B
+## Branch two
+- Child C
+```
+````
+
+Renders as an interactive markmap SVG diagram in the preview pane.
+
+---
+
+## Math Syntax
+
+```markdown
+Inline: $E = mc^2$
+
+Block:
+$$
+\int_{a}^{b} f(x)\,dx
+$$
 ```
 
-## Admonition Blocks
+Powered by KaTeX.
+
+---
+
+## Callout Syntax
 
 ```markdown
-:::tip Pro tip
-Use admonition blocks for callouts.
+:::notice Title
+Notice content.
 :::
 
-:::warning
-This action cannot be undone.
+:::warning Warning
+Warning content.
 :::
 
-:::danger
-Destructive operation.
+:::danger Danger
+Danger content.
 :::
-```
 
-Supported types: `notice`, `info`, `tip`, `success`, `warning`, `danger`.
+:::tip Tip
+Tip content.
+:::
+```
 
-## Performance
+Available types: `notice`, `info`, `tip`, `success`, `warning`, `danger`.
 
-- **Block splitting**: documents are split at ATX headings (`#` through `######`). Content inside code fences is never split.
-- **Incremental rendering**: unchanged blocks reuse their DOM nodes directly, including already-hydrated mindmap SVGs.
-- **Content-hash cache**: render results are cached by content hash, so undo/redo and copy-paste hit the cache.
-- **Adaptive debounce**: `adaptiveDebounceMs(docLength)` scales from 120ms to 600ms based on document size.
-- **`content-visibility: auto`**: off-screen blocks skip layout and paint entirely.
+---
 
 ## Development
 
 ```bash
+# Install dependencies
 npm install
-npm run typecheck       # src only
-npm run typecheck:test  # src + tests
-npm test                # run all tests (vitest + jsdom)
-npm run build           # vite build + d.ts generation
-```
-
-## React Demo
-```jsx
-import { useRef, useCallback } from "react";
-import { type MentionItem, type DocItem } from "@powerduck/md-editor";
-import {
-  MarkdownEditorReact,
-  type MarkdownEditorHandle,
-} from "@powerduck/md-editor/react";
-import "@powerduck/md-editor/dist/style.css";
 
-const USERS: MentionItem[] = [
-  {
-    id: "1",
-    label: "Alice",
-    avatar: "https://i.pravatar.cc/40?u=alice",
-    description: "alice@example.com",
-  },
-  {
-    id: "2",
-    label: "Bob",
-    avatar: "https://i.pravatar.cc/40?u=bob",
-    description: "bob@example.com",
-  },
-  { id: "3", label: "Charlie", description: "charlie@example.com" },
-];
+# Type check
+npm run typecheck
 
-const DOCS: DocItem[] = [
-  {
-    id: "d1",
-    title: "Getting Started",
-    url: "https://docs.example.com/start",
-    description: "Quick start guide",
-    thumbnail: "https://picsum.photos/seed/start/96/72",
-  },
-  {
-    id: "d2",
-    title: "API Reference",
-    url: "https://docs.example.com/api",
-    description: "Full API documentation",
-  },
-  {
-    id: "d3",
-    title: "Changelog",
-    url: "https://docs.example.com/changelog",
-    description: "Release notes",
-  },
-];
+# Build (ESM + CJS + type declarations + CSS)
+npm run build
 
-function App() {
-  const editorRef = useRef<MarkdownEditorHandle>(null);
+# Run tests
+npm test
 
-  const handleSave = useCallback(() => {
-    const markdown = editorRef.current?.getValue() ?? "";
-    console.log("Saving:", markdown);
-  }, []);
-
-  // Stable callbacks so the editor does not recreate on every render
-  const searchUsers = useCallback(async (query: string) => {
-    return USERS.filter((u) =>
-      u.label.toLowerCase().includes(query.toLowerCase()),
-    );
-  }, []);
-
-  const searchDocs = useCallback(async (query: string) => {
-    return DOCS.filter((d) =>
-      d.title.toLowerCase().includes(query.toLowerCase()),
-    );
-  }, []);
-
-  const fetchDocMeta = useCallback(async (url: string) => {
-    // In production, route through your backend to avoid CORS:
-    // const res = await fetch(`/api/og?url=${encodeURIComponent(url)}`);
-    // return res.json();
-    // For demo: return whatever metadata the item already has
-    const doc = DOCS.find((d) => d.url === url);
-    return {
-      title: doc?.title ?? new URL(url).hostname,
-      description: doc?.description,
-      thumbnail: doc?.thumbnail,
-      url,
-    };
-  }, []);
+# Dev server
+npm run dev
+```
 
-  return (
-    <div style={{ padding: 24, maxWidth: 1100, margin: "0 auto" }}>
-      <div style={{ marginBottom: 12, display: "flex", gap: 8 }}>
-        <button onClick={handleSave}>Save</button>
-        <button onClick={() => editorRef.current?.setTheme("dark")}>
-          Dark
-        </button>
-        <button onClick={() => editorRef.current?.setTheme("light")}>
-          Light
-        </button>
-      </div>
+---
 
-      <MarkdownEditorReact
-        ref={editorRef}
-        defaultValue={[
-          "# Welcome",
-          "",
-          "Type **@** to mention a user, or **/** to insert a document link.",
-          "",
-          "## Task list",
-          "- [ ] This is checked (green)",
-          "- [x] This is unchecked",
-          "- [ x] Spaces inside brackets also work",
-          "",
-          "## Table",
-          "| Name | Role |",
-          "|------|------|",
-          "| Alice | Admin |",
-          "| Bob | Editor |",
-        ].join("\n")}
-        mode="complex"
-        theme="light"
-        onChange={(v) => console.log("auto-save:", v.length)}
-        mention={{
-          onMentionSearch: searchUsers,
-          minChars: 0,
-          maxItems: 8,
-        }}
-        docLink={{
-          onDocSearch: searchDocs,
-          onFetchDocMeta: fetchDocMeta,
-          insertStyle: "auto",
-          minChars: 0,
-          maxItems: 8,
-        }}
-      />
-    </div>
-  );
-}
+## Related Packages
 
-export default App;
-```
+- [`@powerduck/openapi-parser`](https://www.npmjs.com/package/@powerduck/openapi-parser) — OpenAPI 3.2 parser, validator, and upgrader
+- [`@powerduck/conf-patch`](https://www.npmjs.com/package/@powerduck/conf-patch) — Configuration file editor with atomic writes and locking
+- [`@powerduck/openapi-codegen`](https://www.npmjs.com/package/@powerduck/openapi-codegen) — Generate runnable request examples in 21 languages
 
-## Changelog
-
-### v0.8.4
-
-- **Fixed**: React component `MarkdownEditorReact` now passes through all extra props (`mention`, `docLink`, `toolbar`, `onImageUpload`, `includeCommonHeaders`, `includeCookies`, `placeholder`, etc.) to the underlying `MarkdownEditor` instance. Previously only a subset of props were forwarded, so `mention` and `docLink` configs were silently ignored.
-- **Test**: 311 tests, all passing, zero unhandled errors.
-
-### v0.8.3
-
-- **Changed**: Task list checkbox semantics inverted per project convention. `- [ ]` now renders as **checked** (green checkmark); `- [x]` / `- [X]` renders as **unchecked** (empty box). `toggleTaskList()` and all tests updated accordingly.
-- **Improved**: Clicking the @mention or document-link toolbar button without configuring the search hook now logs a clear `console.warn` explaining that `mention.onMentionSearch` / `docLink.onDocSearch` must be provided.
-- **Test**: 310 tests, all passing, zero unhandled errors.
-
-### v0.8.2
-
-- **Fixed**: @mention and `/` doc-link dropdowns did not appear. Root cause: v0.8.1 mounted dropdowns inside `.md-editor-root` where ancestor `overflow:hidden` / stacking contexts could clip or misplace `position:fixed` elements. Reverted to `document.body` mounting with `position:fixed`, and added explicit light/dark colors via `data-theme` attribute (no dependency on editor-scoped CSS variables).
-- **Fixed**: Clicking toolbar button icons (SVG) did not open popups. Root cause: `mousedown` event bubbled to `document` and triggered the newly-opened Popup's outside-click handler (because `e.target` was the SVG, not the button). Fixed in two ways: Popup now uses `anchor.contains(target)` instead of `target !== anchor`; toolbar `mousedown` handler calls `e.stopPropagation()`.
-- **Fixed**: Task list checkboxes now render with a clear green checkmark when checked (`- [x]` or `- [X]`). Previously used native `accent-color` (orange) which was hard to distinguish in disabled state. Custom checkbox: gray border when unchecked, solid green with white checkmark when checked.
-- **Added**: Help dialog now includes a "Syntax" section with quick-reference guidance for task lists, @mentions, document links, math, mindmaps, and callouts.
-- **Fixed**: Help dialog and all popup-internal styles no longer use editor-scoped CSS variables (undefined when popup is on `document.body`), ensuring consistent light/dark rendering.
-- **Test**: 310 tests, all passing, zero unhandled errors.
-
-### v0.8.1
-
-- **Fixed**: Toolbar buttons now use `mousedown` + `preventDefault` instead of `click`, preventing the editor from losing focus and collapsing the selection before wrap operations. This fixes the long-standing issue where selecting text and clicking quote/list/other toolbar buttons replaced the selection with placeholder text ("quoted text", "list item").
-- **Fixed**: `toggleTaskList()` mixed-state logic. Previously, a mix of checked and unchecked items (or all-unchecked) removed all task markers. Now: mixed or all-unchecked → check all; all-checked → uncheck all. Also supports uppercase `[X]` markers.
-- **Fixed**: Code block copy button now falls back to `document.execCommand('copy')` when `navigator.clipboard` is unavailable (non-HTTPS contexts), instead of silently failing.
-- **Fixed**: @mention and doc-link dropdowns now close when the editor loses focus (blur), with a 150ms delay so clicks on the dropdown itself register first.
-- **Fixed**: @mention and doc-link dropdowns had transparent backgrounds because they used editor-scoped CSS variables (`--_surface`) while being appended to `document.body`. Now appended inside `.md-editor-root` with `position: fixed` (not clipped by `overflow: hidden`), so theme variables resolve correctly.
-- **Fixed**: Popup dialogs (image, video, YouTube, table, help, callout) now respect the editor theme. Previously always light-themed; now dark-themed when the editor is in dark mode.
-- **Test**: 310 tests, all passing, zero unhandled errors.
-
-### v0.8.0
-
-- **Added**: Document/article link inserter. Type `/` to open a searchable dropdown of documents. `onDocSearch(query)` returns matching documents; on selection, inserts either a plain markdown link or a `:::doc-link` preview card.
-- **Added**: `:::doc-link` preview card rendering — displays title, thumbnail, description, and domain as a clickable card. Auto-fetches Open Graph / meta tags via `onFetchDocMeta(url)` hook; falls back to plain link when metadata is unavailable or fetch fails.
-- **Added**: `insertStyle` option: `'auto'` (default, card when meta available), `'card'` (always card, fallback to link), `'link'` (always plain link).
-- **Added**: `docLink` option to `MarkdownEditorOptions` and `CodeEditorOptions`, with `triggerChar`, `minChars`, `maxItems` configuration.
-- **Added**: Toolbar button for document link insertion.
-- **Test**: 307 tests, all passing, zero unhandled errors.
-
-### v0.7.0
-
-- **Fixed**: Mindmap nested code fences no longer lose content. Custom block rule tracks fence nesting depth (lines with info string open, bare backticks close), so ` ```js ` inside a ` ```mindmap ` block is preserved.
-- **Added**: Task list (checkbox) toolbar button and `toggleTaskList()` API. Toggles `- [ ]` / `- [x]` on current line or selected lines. Renders as checkboxes in preview. Keyboard shortcut: `Ctrl+Shift+9`.
-- **Added**: @mention dropdown with configurable hooks. `onMentionSearch(query)` returns matching items, `onMentionSelect(item)` returns replacement text. Supports keyboard navigation (ArrowUp/Down, Enter, Escape), avatars, descriptions, `minChars`, and `maxItems` options.
-- **Added**: `mention` option to `MarkdownEditorOptions` and `CodeEditorOptions`.
-- **Test**: 281 tests, all passing, zero unhandled errors.
-
-### v0.6.0
-
-- **Fixed**: Mindmap `transform: translate(NaN,NaN) scale(NaN)` console errors (hundreds per mindmap). Root cause: `autoFit: true` computed transform on zero-size SVG before layout, and d3-zoom scheduled hundreds of animation frames each throwing "Expected number". Fix: create with `autoFit: false`, set safe default transform immediately, defer `fit()` to next animation frame with dimension guard.
-- **Fixed**: Code block colors now sync with editor theme (light/dark). Previously hardcoded to atom-one-dark in all themes. Now uses CSS variables (`--code-bg`, `--code-fg`, `--code-keyword`, etc.) with GitHub-style light and dark palettes.
-- **Fixed**: UL/OL list styling in preview now has consistent spacing, bullet alignment, and line height.
-- **Improved**: Removed `highlight.js/styles/atom-one-dark.css` import; syntax highlighting colors are now fully theme-aware via CSS variables.
-- **Improved**: Removed stale `markdown-it-texmath` from vite external deps (removed in v0.4.0).
-- **Improved**: Vitest config now excludes `__MACOSX` and AppleDouble (`._*`) files to prevent false test failures from macOS zip artifacts.
-- **Test**: 251 tests, all passing, zero unhandled errors.
-
-### v0.5.0
-
-- **Fixed**: Admonition `:::` closing marker no longer leaks into rendered body content.
-- **Fixed**: Quote, unordered list, and ordered list toolbar actions now wrap selected text (or the current line) instead of replacing it.
-- **Improved**: Tip/admonition toolbar button now opens a type-picker popup with all six styles (notice, info, tip, success, warning, danger).
-- **Improved**: Help dialog now displays keyboard shortcuts with styled key caps and modifier-key symbols (⌘, ⌥, ⇧).
-- **Improved**: All toolbar icons redesigned in a clean Lucide/Feather line style for a modern Western aesthetic.
-- **Fixed**: Mindmap `transform: translate(NaN,NaN)` error guarded when SVG has zero layout size.
-- **Added**: `formatShortcutHtml()` export for rendering styled key caps.
-- **Test**: 251 tests, all passing.
-
-### v0.4.0
-
-- Self-contained KaTeX math plugin (removed `markdown-it-texmath`); currency `$5` no longer misparsed.
-- Image upload hook `onImageUpload(file)` with paste/drag support.
-- 11 keyboard shortcuts with macOS Cmd auto-mapping.
-- Help dialog listing all shortcuts.
-- Table rows/columns popup dialog.
-- Theme toggle fixed for dark mode with github-markdown-css.
-- Admonition/tip blocks (`:::notice`, `:::warning`, etc.).
-- Configurable toolbar (include-list or per-item show/label/icon).
-- Standalone `renderMarkdown(source, options)` API export.
+---
 
 ## License