@zuilib/text-editor 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog — @zuilib/text-editor
+
+## 0.3.0
+
+- **Custom toolbars**
+  - `toolbar` prop accepts a render function receiving the default groups
+    (`format`, `insert`, `history`) so you can add your own buttons
+  - Compound components: `MarkdownEditor.Root` / `.Content` / `.Toolbar` /
+    `.Outline` plus `.FormatButtons` / `.InsertButtons` / `.HistoryButtons` /
+    `.ToolbarButton` / `.ToolbarDivider` — place the toolbar anywhere under
+    `Root`
+  - `useMarkdownEditor()` headless hook: `editor`, `activeFormats`,
+    `toggleFormat`, `insertTable`, `insertDrawing`, `undo`/`redo`
+- Undo/redo buttons (`HistoryButtons`; in the default toolbar via the
+  function form only — default toolbar layout unchanged)
+- Internal: `LexicalComposer` is now mounted in `edit-raw` mode too, so
+  hooks keep working across mode switches
+
+## 0.2.1
+
+- `DRAWING_FORMAT.md`: authoritative spec of the ```drawing JSON payload,
+  written for programmatic/LLM consumption; ships in the npm package
+- New export `DRAWING_DATA_JSON_SCHEMA` (JSON Schema draft-07) for
+  validating or structured-output-generating drawing payloads
+- New exports `parseDrawingData` / `serializeDrawingData`
+- This changelog; README overhaul
+
+## 0.2.0
+
+- **Outline** (`outline` prop, default off): docked, collapsible
+  table-of-contents sidebar — live heading list, click-to-scroll, current
+  section highlighted
+- **Section folding** (`foldable` prop, default on): collapse everything
+  under a heading via a gutter chevron; view-layer only (markdown
+  untouched); auto-expands if the cursor enters a folded section
+
+## 0.1.0
+
+- **Tables**: GFM pipe tables round-trip through markdown; artifact-style
+  rendering; in-place editing via Lexical `TablePlugin`; new peer deps
+  `@lexical/table` and `@lexical/utils`
+- **Toolbar** (`toolbar` prop, default on): inline formatting, insert
+  table, insert drawing
+- **Drawing canvas**: Excalidraw-style diagrams embedded as ```drawing
+  fenced JSON blocks — see `DRAWING_FORMAT.md`
+  - Shapes: rectangle, ellipse, triangle, pentagon, arrow, line, text
+  - Boxes are cards with three attached text slots (label / content /
+    footer) that move, resize, and wrap with the shape
+  - Connectors bind to boxes and track them; one-way or two-way arrows;
+    midpoint labels; straight, elbow, or waypoint-routed paths
+  - Stroke/fill palettes; dark mode via canvas color inversion
+- Round-trip test suite (`pnpm test`)
+
+## 0.0.2 and earlier
+
+- Markdown editor wrapping Lexical: `edit-md` / `edit-raw` / `view` modes,
+  markdown shortcuts, checklists, fenced code highlighting, YAML
+  frontmatter block, controlled `value`/`onChange`

package/DRAWING_FORMAT.md

@@ -0,0 +1,149 @@
+# The `drawing` block format
+
+`@zuilib/text-editor` documents are plain markdown. Diagrams are embedded as
+a fenced code block with the language `drawing`, containing a single JSON
+object:
+
+````md
+```drawing
+{"version":1,"height":320,"shapes":[ ... ]}
+```
+````
+
+This document is the authoritative spec of that JSON payload. It is written
+so it can be handed to a program or an LLM that needs to **generate or edit
+drawings**. A machine-readable JSON Schema of the same rules is exported
+from the package as `DRAWING_DATA_JSON_SCHEMA`.
+
+Malformed payloads never crash the editor: anything that fails validation
+degrades to an empty canvas (invalid shapes are dropped individually).
+
+## Coordinate system
+
+- Origin `(0,0)` is the canvas's top-left; x grows right, y grows down.
+- Units are CSS pixels.
+- The canvas is as wide as the editor (fluid). Keep shapes within roughly
+  x ∈ [0, 700] to be safe on typical layouts.
+- `height` is the canvas height in pixels (minimum 80; 300–400 is typical).
+
+## Top-level object
+
+| Field     | Type      | Notes                                   |
+|-----------|-----------|-----------------------------------------|
+| `version` | `1`       | Literal `1`                             |
+| `height`  | `number`  | Canvas height in px                     |
+| `shapes`  | `Shape[]` | Render order: later shapes draw on top  |
+
+## Shape object
+
+All shapes share these required fields:
+
+| Field         | Type     | Meaning                                                            |
+|---------------|----------|--------------------------------------------------------------------|
+| `id`          | `string` | Unique within the drawing; bindings reference it                   |
+| `type`        | `string` | `rect` \| `ellipse` \| `triangle` \| `pentagon` \| `arrow` \| `line` \| `text` |
+| `x`, `y`      | `number` | Boxes/text: top-left of the bounding box. Connectors: start point. |
+| `w`, `h`      | `number` | Boxes/text: size (non-negative). Connectors: delta to the end point (`end = (x+w, y+h)`; may be negative). |
+| `stroke`      | `string` | CSS color of the outline and of all text on the shape              |
+| `fill`        | `string` | CSS color of the interior; `"transparent"` for none                |
+| `strokeWidth` | `number` | Use `2`                                                            |
+
+### Boxes (`rect`, `ellipse`, `triangle`, `pentagon`) — "cards"
+
+Boxes are card-like: they can carry up to three text slots that render
+inside the shape and move/resize/wrap with it:
+
+| Field    | Renders as                                    |
+|----------|-----------------------------------------------|
+| `label`  | Small bold heading at the top of the box      |
+| `text`   | Main content, centered                        |
+| `footer` | Small dim line at the bottom                  |
+
+Text wraps automatically to the box width; `\n` forces a line break.
+Triangles are apex-up isoceles; pentagons are apex-up, inscribed in the
+bounding box. Prefer these slots over floating `text` shapes — slot text is
+attached to the card.
+
+### `text` — free-floating annotation
+
+`text` holds the content. `w`/`h` are advisory (the editor recomputes them
+from the content); position is the top-left of the first line. Use only for
+annotations that belong to no box (the editor deletes a text shape when its
+content is emptied).
+
+### Connectors (`arrow`, `line`)
+
+Geometry: from `(x, y)` to `(x+w, y+h)`. `arrow` has a head at the end;
+`line` has none.
+
+| Field           | Type       | Meaning                                                                 |
+|-----------------|------------|-------------------------------------------------------------------------|
+| `text`          | `string`   | Label rendered at the path midpoint on a small backing plate            |
+| `bidirectional` | `boolean`  | Arrows only: heads on both ends                                         |
+| `startBinding`  | `string`   | id of the box the start attaches to                                     |
+| `endBinding`    | `string`   | id of the box the end attaches to                                       |
+| `routing`       | `"elbow"`  | Orthogonal auto-routing with up to two right-angle bends                |
+| `elbow`         | `number`   | 0–1: middle-segment position along the span (default 0.5)               |
+| `waypoints`     | `Point[]`  | Explicit intermediate path points (`{x,y}`), ordered start→end          |
+
+**Bindings.** When `startBinding`/`endBinding` name a box id, the editor
+re-anchors that endpoint onto the box's border (aimed at the other end, with
+a small gap) and keeps it attached as the box moves. Generated endpoints
+therefore only need to be approximately right — place them near the intended
+boxes and the resolver snaps them. Don't bind both ends of one connector to
+the same box. Bindings to ids that don't exist are silently dropped.
+
+**Routing.** Omit `routing` for a straight (possibly diagonal) connector.
+`"elbow"` renders an orthogonal path: it runs along the dominant axis, turns
+through a perpendicular middle segment (positioned by `elbow`), and turns
+again. If `waypoints` is non-empty it defines the path (`start → waypoints…
+→ end`) and `routing`/`elbow` are ignored. Waypoints are absolute canvas
+coordinates; align consecutive points on x or y to get right angles.
+
+## Recommended colors
+
+Any CSS color works; the editor's palette (dark-mode safe — the canvas
+inverts colors Excalidraw-style in dark themes):
+
+- Strokes: `#1e1e1e` (default), `#e03131` red, `#2f9e44` green, `#1971c2` blue, `#f08c00` orange
+- Fills: `transparent`, `#ffc9c9`, `#b2f2bb`, `#a5d8ff`, `#ffec99`
+
+Pair a colored stroke with its pastel fill (`#1971c2` + `#a5d8ff`, etc.).
+
+## Examples
+
+Two bound cards with a labeled arrow:
+
+````md
+```drawing
+{"version":1,"height":260,"shapes":[
+  {"id":"web","type":"rect","x":40,"y":70,"w":170,"h":100,"stroke":"#1971c2","fill":"#a5d8ff","strokeWidth":2,"label":"CLIENT","text":"Web App","footer":"React"},
+  {"id":"api","type":"rect","x":330,"y":70,"w":170,"h":100,"stroke":"#2f9e44","fill":"#b2f2bb","strokeWidth":2,"label":"SERVICE","text":"API","footer":"Kotlin"},
+  {"id":"e1","type":"arrow","x":216,"y":120,"w":108,"h":0,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":"web","endBinding":"api","text":"REST"}
+]}
+```
+````
+
+An elbow arrow and a hand-routed multi-bend line:
+
+````md
+```drawing
+{"version":1,"height":300,"shapes":[
+  {"id":"a","type":"rect","x":40,"y":40,"w":150,"h":80,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"text":"A"},
+  {"id":"b","type":"ellipse","x":420,"y":180,"w":150,"h":80,"stroke":"#e03131","fill":"#ffc9c9","strokeWidth":2,"text":"B"},
+  {"id":"e1","type":"arrow","x":196,"y":80,"w":224,"h":140,"stroke":"#1e1e1e","fill":"transparent","strokeWidth":2,"startBinding":"a","endBinding":"b","routing":"elbow"},
+  {"id":"e2","type":"line","x":115,"y":126,"w":380,"h":54,"stroke":"#1971c2","fill":"transparent","strokeWidth":2,"startBinding":"a","endBinding":"b","waypoints":[{"x":115,"y":260},{"x":495,"y":260}]}
+]}
+```
+````
+
+## Generation checklist
+
+1. One JSON object, single ```drawing fence, no comments or trailing commas.
+2. Every `id` unique; every binding references an existing box id.
+3. Boxes ≥ 120×70 when they carry text slots; leave ~60px between cards for
+   connectors and labels.
+4. Box text goes in `label`/`text`/`footer` — not in floating `text` shapes.
+5. Connectors between cards should bind both ends; approximate endpoints are
+   fine (the editor snaps them to borders).
+6. `height` large enough to contain every shape plus ~20px margin.

package/README.md

@@ -1,30 +1,30 @@
 # @zuilib/text-editor
 
-Markdown editor for ZUI built on [Lexical](https://lexical.dev/): rich editing with shortcuts, raw markdown mode, read-only view, checklists, fenced code highlighting, GFM tables, and an embedded drawing canvas for diagrams.
-
-## When to use
-
-- Notes, comments, or docs fields stored as **markdown strings**
-- Controlled `value` / `onChange` integration with forms or autosave
-- WYSIWYG-style editing without leaving markdown as the source of truth
-
-## Prerequisites
-
-Peer dependencies (install in the consuming app):
-
-| Package | Version |
-|---------|---------|
-| `react`, `react-dom` | `^18.0.0 \|\| ^19.0.0` |
-| `lexical` | `^0.35.0` |
-| `@lexical/react` | `^0.35.0` |
-| `@lexical/markdown` | `^0.35.0` |
-| `@lexical/rich-text` | `^0.35.0` |
-| `@lexical/code` | `^0.35.0` |
-| `@lexical/list` | `^0.35.0` |
-| `@lexical/link` | `^0.35.0` |
-| `@lexical/table` | `^0.35.0` |
-| `@lexical/utils` | `^0.35.0` |
-| `@zuilib/core` | workspace / published — import core styles |
+A markdown editor for ZUI built on [Lexical](https://lexical.dev/). Plain
+markdown in, plain markdown out — with an artifact-style editing experience
+on top: rich tables, an embedded Excalidraw-style diagram canvas, a
+document outline, and collapsible sections.
+
+**Features**
+
+- **Three modes**: rich WYSIWYG (`edit-md`), raw markdown (`edit-raw`),
+  read-only render (`view`) — all driven by one controlled `value` string
+- **Markdown shortcuts** while typing: headings, lists, checklists,
+  blockquotes, links, fenced code (with syntax highlighting), tables
+- **Tables**: GFM pipe tables, edited in place (tab between cells, ranges,
+  inline formatting), styled like Claude artifacts
+- **Diagrams**: a drawing canvas embedded in the document — cards with
+  attached text slots, bound arrows that follow their cards, elbow and
+  multi-waypoint routing, labels, color palettes, dark mode
+- **Outline**: optional table-of-contents sidebar with click-to-scroll and
+  current-section highlight
+- **Section folding**: collapse everything under a heading, view-layer only
+- **Toolbar**: inline formatting plus insert-table / insert-drawing
+- YAML **frontmatter** block support (`---` at the top)
+
+Everything round-trips through the markdown string: tables as GFM,
+diagrams as ` ```drawing ` fenced JSON ([format spec](./DRAWING_FORMAT.md)),
+frontmatter as `---` blocks. Feature history: [CHANGELOG](./CHANGELOG.md).
 
 ## Installation
 
@@ -34,42 +34,8 @@ pnpm add @zuilib/text-editor @zuilib/core \
   @lexical/code @lexical/list @lexical/link @lexical/table @lexical/utils
 ```
 
-Monorepo:
-
-```json
-{
-  "dependencies": {
-    "@zuilib/text-editor": "workspace:*",
-    "@zuilib/core": "workspace:*",
-    "lexical": "^0.35.0",
-    "@lexical/react": "^0.35.0",
-    "@lexical/markdown": "^0.35.0",
-    "@lexical/rich-text": "^0.35.0",
-    "@lexical/code": "^0.35.0",
-    "@lexical/list": "^0.35.0",
-    "@lexical/link": "^0.35.0",
-    "@lexical/table": "^0.35.0",
-    "@lexical/utils": "^0.35.0"
-  }
-}
-```
-
-## Import rules
-
-| Rule | Detail |
-|------|--------|
-| **Named export** | `import { MarkdownEditor } from '@zuilib/text-editor'` |
-| **Types** | `import type { MarkdownEditorProps } from '@zuilib/text-editor'` |
-| **Styles** | `import '@zuilib/text-editor/styles.css'` and `@zuilib/core/styles.css` |
-| **Controlled** | Always pass `value` + `onChange` for persisted content |
-| **Mode switches** | Switching `edit-raw` → `edit-md` re-mounts Lexical with latest markdown (cursor-safe) |
-
-## Exports
-
-| Subpath | Exports |
-|---------|---------|
-| `@zuilib/text-editor` | `MarkdownEditor` (default re-exported as named), `MarkdownEditorProps` |
-| `@zuilib/text-editor/styles.css` | Editor chrome + Lexical theme classes |
+All `lexical`/`@lexical/*` packages are peer dependencies at `^0.35.0`;
+`react`/`react-dom` at `^18 || ^19`.
 
 ## Quick start
 
@@ -81,32 +47,12 @@ import { MarkdownEditor } from '@zuilib/text-editor'
 
 function Notes() {
   const [value, setValue] = useState('# Hello\n\n- [ ] Try checklists')
-
-  return (
-    <MarkdownEditor
-      value={value}
-      onChange={setValue}
-      placeholder="Start writing…"
-    />
-  )
+  return <MarkdownEditor value={value} onChange={setValue} outline />
 }
 ```
 
-## Modes
-
-| `mode` | UI | `onChange` |
-|--------|-----|------------|
-| `'edit-md'` (default) | Lexical rich editor + markdown shortcuts | Emits markdown string |
-| `'edit-raw'` | Plain `<textarea>` with markdown source | Emits markdown string |
-| `'view'` | Read-only rendered content | No editing (`onChange` unused) |
-
-```tsx
-<MarkdownEditor mode="edit-md" value={md} onChange={setMd} />
-<MarkdownEditor mode="edit-raw" value={md} onChange={setMd} />
-<MarkdownEditor mode="view" value={md} />
-```
-
-Toggle modes in parent state; the editor preserves content via an internal ref when remounting Lexical after raw editing.
+The component is controlled: pass `value` and persist what `onChange`
+emits. The emitted string is always plain markdown.
 
 ## Props (`MarkdownEditorProps`)
 
@@ -115,25 +61,29 @@ Toggle modes in parent state; the editor preserves content via an internal ref w
 | `value` | `string` | `''` | Markdown source (controlled) |
 | `onChange` | `(value: string) => void` | — | Called on every edit |
 | `mode` | `'edit-md' \| 'edit-raw' \| 'view'` | `'edit-md'` | Editing surface |
-| `placeholder` | `string` | `'Start writing...'` | Empty state hint |
+| `placeholder` | `string` | `'Start writing...'` | Empty-state hint |
 | `readOnly` | `boolean` | `false` | Disables editing in Lexical modes |
 | `autoFocus` | `boolean` | `false` | Focus on mount |
 | `className` | `string` | — | Root wrapper class |
-| `toolbar` | `boolean` | `true` | Formatting/insert toolbar in `edit-md` mode |
-| `outline` | `boolean` | `false` | Table-of-contents sidebar listing headings |
-| `foldable` | `boolean` | `true` | Collapse sections under their headings |
-
-## Markdown features
+| `toolbar` | `boolean \| (items) => ReactNode` | `true` | Formatting/insert toolbar (`edit-md`); function form customises it |
+| `outline` | `boolean` | `false` | Table-of-contents sidebar |
+| `foldable` | `boolean` | `true` | Collapse sections under headings |
 
-**Shortcuts (edit-md):** headings (`#`), lists, blockquote, links, fenced code (via `CodeBlockShortcutPlugin`), checklists (`- [ ]` via `ChecklistShortcutPlugin`), tables (`| a | b |`).
+### Modes
 
-**Built-in plugins:** history (undo/redo), lists, checklists, links, tables (`TablePlugin`), markdown sync (`MarkdownSyncPlugin`), code highlighting (`CodeHighlightPlugin`), toolbar (`ToolbarPlugin`).
+| `mode` | UI | Notes |
+|--------|-----|-------|
+| `'edit-md'` | Lexical rich editor | Shortcuts, toolbar, tables, canvas |
+| `'edit-raw'` | Plain `<textarea>` | Direct markdown source editing |
+| `'view'` | Read-only render | Outline/folding still work |
 
-**Not included:** file uploads, collaborative editing, or custom Lexical node registration — extend by forking or wrapping `MarkdownEditor`.
+Switching `edit-raw` → `edit-md` re-mounts Lexical with the latest text
+(cursor-safe).
 
 ## Tables
 
-GFM pipe tables round-trip through markdown and render artifact-style (rounded outer border, shaded header row, per-cell rules):
+Type a `| a | b |` row or use the toolbar's insert-table button. GFM
+round-trip:
 
 ```md
 | Metric | Q1 | Q2 |
@@ -141,72 +91,200 @@ GFM pipe tables round-trip through markdown and render artifact-style (rounded o
 | Revenue | $1.2M | $1.8M |
 ```
 
-Insert a 3×3 table from the toolbar, or type a `| a | b |` row. Tab/arrow navigation, cell selection, and row/column operations come from Lexical's `TablePlugin`. Inline formatting (`**bold**`, `*italic*`, `` `code` ``) works inside cells.
+Rendering is artifact-style (rounded outer border, shaded header row).
+Editing is in place: Tab/arrows between cells, cell range selection, inline
+formatting inside cells. Cell content is single-line in markdown; newlines
+are escaped as `\n`.
 
-## Drawing canvas
+## Toolbar & custom toolbars
 
-The toolbar's "Insert drawing" button embeds an Excalidraw-style canvas for simple diagrams: rectangles, ellipses, triangles, pentagons, arrows, lines, and text labels, with a stroke and fill color palette.
+In `edit-md` mode a toolbar offers inline formatting (bold, italic,
+strikethrough, inline code) plus **Insert table** and **Insert drawing**.
+Hide it with `toolbar={false}`.
 
-- Draw a shape by picking a tool and dragging; the tool returns to **Select** after each shape
-- Select to move, resize (corner handles), or re-point arrows/lines (endpoint handles)
-- Color swatches restyle the selected shape (or set defaults for the next one)
-- `Delete`/`Backspace` removes the selected shape; drag the bottom pill to resize the canvas
-- Boxes (rects/ellipses) have three built-in text slots that move with the shape: a bold **label** at the top, main **content** in the center, and a dimmer **footer** at the bottom. Double-click the top strip of a box to edit the label, the middle for content, the bottom strip for the footer (or click a selected box again, or press Enter for content). Clearing a slot removes it; the box stays.
-- **Arrows bind to boxes**: draw an arrow starting or ending on a box and it attaches to the box border — moving or resizing the box drags the arrow along. Endpoints re-anchor toward the other end automatically. Drag an endpoint off a box to detach it; drop it on another box to re-attach. Deleting a box releases its arrows.
-- A selected arrow shows a **direction toggle** in the toolbar: one-way (head at the end) or two-way (heads on both ends).
-- A selected connector also shows a **routing toggle**: straight (freely diagonal) or **elbow** — an orthogonal path with right-angle bends. The elbow's middle segment has a drag handle to reposition the bend; its position is stored as a fraction of the span so it stays put while bound boxes move.
-- **Waypoints** for arbitrary multi-segment paths: a selected connector shows dashed "+" handles at each segment midpoint — drag one to insert a bend point there. Waypoints snap to their neighbors' axes near-alignment so right angles are easy; drag freely for diagonals. Double-click a waypoint to remove it. Adding a point to an elbow connector converts its corners into editable waypoints. Selecting a routing mode from the toolbar clears waypoints.
-- **Arrows and lines can carry a label**: double-click the connector (or select it and press Enter) to edit text that rides the midpoint on a small backing plate, and moves as the connector moves.
-- The standalone **Text** tool is for free-floating annotations (e.g. labeling an arrow); double-click to edit
+### Extending the toolbar
 
-Drawings persist inside the markdown as a fenced block, so the document stays a plain string:
+Pass a function as `toolbar`. It receives the default button groups and
+returns the toolbar to render. Use `MarkdownEditor.ToolbarButton` for your
+own buttons so they match the built-ins and keep the editor selection when
+clicked.
 
-````md
-```drawing
-{"version":1,"height":320,"shapes":[...]}
+```tsx
+<MarkdownEditor
+  value={value}
+  onChange={setValue}
+  toolbar={(items) => (
+    <MarkdownEditor.Toolbar>
+      {items.format}
+      <MarkdownEditor.ToolbarDivider />
+      {items.insert}
+      <MarkdownEditor.ToolbarDivider />
+      {items.history}
+      <MarkdownEditor.ToolbarButton label="Save" onClick={save}>
+        💾
+      </MarkdownEditor.ToolbarButton>
+    </MarkdownEditor.Toolbar>
+  )}
+/>
 ```
-````
 
-In `view` mode (or `readOnly`) the canvas renders the shapes without any editing chrome.
+`MarkdownEditor.Toolbar` hides itself in `view` / `edit-raw` / `readOnly`.
+
+### Placing your own toolbar (compound components)
+
+When the toolbar must live somewhere else in your layout (an app bar, a
+panel header), compose the editor from its parts. Everything under
+`MarkdownEditor.Root` shares one editor instance, so the toolbar can sit
+anywhere in that subtree.
+
+```tsx
+<MarkdownEditor.Root value={value} onChange={setValue}>
+  <header className="app-bar">
+    <MarkdownEditor.Toolbar>
+      <MarkdownEditor.FormatButtons />
+      <MarkdownEditor.ToolbarDivider />
+      <MarkdownEditor.InsertButtons />
+    </MarkdownEditor.Toolbar>
+    <MyAppButtons />
+  </header>
+  <MarkdownEditor.Content placeholder="Write…">
+    <MarkdownEditor.Outline />
+  </MarkdownEditor.Content>
+</MarkdownEditor.Root>
+```
+
+| Part | Role |
+|------|------|
+| `Root` | Lexical composer + plugins. Takes `value`, `onChange`, `mode`, `readOnly`, `autoFocus`, `className` |
+| `Content` | The editable surface. Takes `placeholder`, `foldable`; children are docked sidebars |
+| `Toolbar` | Container; renders the default groups when empty |
+| `FormatButtons`, `InsertButtons`, `HistoryButtons` | Built-in groups |
+| `ToolbarButton`, `ToolbarDivider` | Primitives for your own items |
+| `Outline` | Table-of-contents sidebar |
+
+### Headless: `useMarkdownEditor()`
+
+For fully custom UI (e.g. buttons in your own design system), call the hook
+from any component rendered under `MarkdownEditor.Root`:
+
+```tsx
+function BoldButton() {
+  const { activeFormats, toggleFormat } = useMarkdownEditor()
+  return (
+    <MyButton pressed={activeFormats.has('bold')} onClick={() => toggleFormat('bold')}>
+      B
+    </MyButton>
+  )
+}
+```
+
+It returns `editor` (the Lexical instance), `activeFormats`,
+`toggleFormat`, `insertTable`, `insertDrawing`, `canUndo`, `canRedo`,
+`undo`, `redo`.
+
+## Diagrams (drawing canvas)
+
+The toolbar's insert-drawing button embeds a canvas; the drawing persists
+in the markdown as a ` ```drawing ` fenced JSON block, fully specified in
+**[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)**.
+
+- **Shapes**: rectangle, ellipse, triangle, pentagon, arrow, line, text —
+  with stroke/fill palettes. Draw by picking a tool and dragging.
+- **Cards**: every box carries three text slots that move, resize, and wrap
+  with it — a bold **label** on top, **content** in the center, a dim
+  **footer** at the bottom. Click a selected box (or double-click its
+  top/middle/bottom strip, or press Enter) to edit a slot.
+- **Bound connectors**: an arrow drawn from one card to another attaches to
+  both — moving a card moves its arrows, endpoints anchored to the border.
+  Drag an endpoint off/onto a card to detach/re-attach.
+- **Routing**: straight (diagonal) by default; toggle **elbow** for right
+  angles, or drag the dashed "+" handles on a selected connector to add any
+  number of **waypoints** (they snap to neighbors' axes for clean 90°
+  bends). One-way / two-way arrowhead toggle; midpoint **labels**.
+- **Canvas**: resizable height, dot grid, white surface that inverts
+  Excalidraw-style in dark mode (`.dark` ancestor class).
 
 ## Outline & section folding
 
-`outline` docks a collapsible table-of-contents sidebar on the right: it lists the document's headings live (indented by level), scrolls to a heading on click, and highlights the section currently in view. Pure UI — nothing is added to the document. Works in `edit-md` and `view` modes (not `edit-raw`).
+`outline` docks a collapsible table-of-contents sidebar: live heading list
+indented by level, click to scroll, current section highlighted. Not part
+of the document — pure UI. Available in `edit-md` and `view`.
 
-`foldable` (on by default) adds a chevron in the left gutter of every heading (visible on hover). Clicking it collapses the section — everything up to the next heading of the same or higher level — marked by a trailing `…` on the heading. Folding is view-layer only: the markdown string is unaffected, and fold state resets on remount. If the cursor enters a folded section (e.g. via arrow keys), it auto-expands so content can never be edited invisibly.
+`foldable` (default on) shows a chevron in the gutter of each heading on
+hover; clicking collapses the section (until the next heading of the same
+or higher level). Folding never changes the markdown; fold state resets on
+remount; a folded section auto-expands if the cursor enters it.
 
-## Form integration
+## For AI agents / programmatic authoring
+
+Documents are plain markdown, so LLMs can generate them — including
+diagrams:
 
-With `@zuilib/form`:
+- **[DRAWING_FORMAT.md](./DRAWING_FORMAT.md)** is the authoritative
+  ` ```drawing ` payload spec, written to be pasted into a prompt (ships in
+  the npm package next to this README).
+- `DRAWING_DATA_JSON_SCHEMA` (exported) is the same contract as JSON Schema
+  — use it to validate generated payloads or as a structured-output/tool
+  schema.
+- `parseDrawingData(json)` is the editor's own lenient parser (invalid
+  shapes drop out; never throws); `serializeDrawingData` is its inverse.
+- A ready-made Claude Code skill lives in the monorepo at
+  `.claude/skills/text-editor-documents/` — copy it into consuming repos so
+  agents there know the dialect.
+
+## Exports
+
+| Export | Purpose |
+|--------|---------|
+| `MarkdownEditor`, `MarkdownEditorProps` | The component; compound parts as statics (`.Root`, `.Content`, `.Toolbar`, …) |
+| `useMarkdownEditor`, `MarkdownEditorApi` | Headless editor hook |
+| `Toolbar`, `ToolbarButton`, `ToolbarDivider`, `FormatButtons`, `InsertButtons`, `HistoryButtons` | Toolbar primitives |
+| `@zuilib/text-editor/styles.css` | Editor chrome + theme styles (required) |
+| `TABLE` | GFM table markdown transformer |
+| `DRAWING`, `DrawingNode`, `$createDrawingNode`, `$isDrawingNode` | Drawing node + markdown transformer |
+| `FRONTMATTER`, `FrontmatterNode`, `$createFrontmatterNode`, `$isFrontmatterNode` | Frontmatter node + transformer |
+| `DrawingData`, `DrawingShape`, `DrawingShapeType` | Drawing payload types |
+| `parseDrawingData`, `serializeDrawingData` | Drawing payload (de)serialization |
+| `DRAWING_DATA_JSON_SCHEMA` | JSON Schema of the drawing payload |
+
+## Form integration
 
 ```tsx
 <FormField control={form.control} name="body">
   {({ field }) => (
-    <MarkdownEditor
-      value={field.value}
-      onChange={field.onChange}
-      mode="edit-md"
-    />
+    <MarkdownEditor value={field.value} onChange={field.onChange} />
   )}
 </FormField>
 ```
 
-Ensure both CSS entry points are loaded in the app layout.
+Load both CSS entry points (`@zuilib/core/styles.css`,
+`@zuilib/text-editor/styles.css`) in the app layout. Dark mode follows the
+ZUI convention: a `dark` class on `<html>`.
 
 ## Architecture notes (for extenders)
 
-- Source: `src/MarkdownEditor.tsx`, plugins under `src/plugins/`
-- Lexical namespace: `ZuiTextEditor`
-- Markdown import/export uses `@lexical/markdown` transformers (`CHECK_LIST` prioritized for import)
-- `edit-raw` bypasses Lexical; switching back to `edit-md` captures `latestValueRef` and bumps `mountKey` to avoid cursor jumps
+- Source: `src/EditorRoot.tsx` (composer + plugins), `src/EditorContent.tsx`,
+  `src/MarkdownEditor.tsx` (default composition), `src/useMarkdownEditor.ts`,
+  `src/components/Toolbar.tsx`; plugins in `src/plugins/`; drawing
+  canvas in `src/components/`; custom nodes in `src/nodes/`;
+  transformers in `src/transformers/`
+- Markdown import/export via `@lexical/markdown` transformers; order
+  matters: `FRONTMATTER` and `DRAWING` claim their blocks before `CODE`,
+  `CHECK_LIST` before `UNORDERED_LIST`
+- Drawing geometry (bindings resolver, elbow/waypoint paths, wrapping) is
+  pure and lives in `src/components/drawingGeometry.ts`
+- Tests: `pnpm test` runs a headless-Lexical markdown round-trip suite
+  (`tests/roundtrip.mjs`)
 
 ## Related packages
 
 - `@zuilib/core` — design tokens and base styles
 - `@zuilib/form` — react-hook-form wiring
 
-## Build (maintainers)
+## Build & release (maintainers)
 
 ```bash
-pnpm --filter @zuilib/text-editor build
+pnpm --filter @zuilib/text-editor build   # tsup → dist/
+pnpm --filter @zuilib/text-editor test    # round-trip suite
+pnpm --filter @zuilib/text-editor publish --access public
 ```