@rcarls/rc-textarea 0.1.0 → 0.3.0

package/README.md

@@ -1,128 +1,24 @@
 # rc-textarea
 
-A WAI-ARIA compliant enhanced textarea web component built with [Lit 3](https://lit.dev) and [Parchment](https://github.com/quilljs/parchment). Uses a `contenteditable` div as its editing surface, enabling inline visual formatting (bold, italic, color, underlines) that is impossible with a plain `<textarea>`.
+Textarea wrapper with line decorations, gutter rendering, inline widgets, and plugin hooks.
 
-**rc-textarea is not a rich text editor.** The underlying value is always plain text. Decorations are applied visually only — entirely through the JavaScript API, not through user action.
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-textarea](https://richardcarls.github.io/rc-webcomponents/components/rc-textarea).
 
----
-
-## Table of Contents
-
-1. [Key Capabilities](#key-capabilities)
-2. [Architecture](#architecture)
-3. [Installation](#installation)
-4. [Basic Usage](#basic-usage)
-5. [Attributes & Properties](#attributes--properties)
-6. [Value Property](#value-property)
-7. [Events](#events)
-8. [CSS Customization](#css-customization)
-9. [Plugin API](#plugin-api)
-10. [Decoration Types](#decoration-types)
-11. [Pattern API](#pattern-api)
-12. [Plugin Helpers](#plugin-helpers)
-13. [Selection API](#selection-api)
-14. [Decoration Lifecycle](#decoration-lifecycle)
-15. [Undo / Redo](#undo--redo)
-16. [Keyboard Behavior](#keyboard-behavior)
-17. [Form Integration](#form-integration)
-18. [Accessibility](#accessibility)
-19. [Performance Considerations](#performance-considerations)
-20. [Troubleshooting](#troubleshooting)
+Made with [Lit](https://lit.dev) and [Parchment](https://github.com/quilljs/parchment).
 
 ---
 
-## Key Capabilities
+## Feature Highlights
 
-- **Mixed inline formatting** — bold, italic, color, background, underline styles on arbitrary character ranges
-- **Error-lens style line annotations** — end-of-line messages (like VS Code's error lens)
-- **Inline widgets** — non-editable DOM elements inserted at any character offset
-- **Regex pattern decorations** — auto-decorate text matching regular expressions
-- **Plugin API** — imperative decoration control + highlight.js / prism.js HTML compatibility bridge
-- **Line numbers, word wrap, auto-grow** — feature flags for common use cases
-- **Progressive enhancement** — wraps a native `<textarea>` for form submission; the textarea is hidden, the `contenteditable` div is the interaction surface
-- **Custom undo/redo** — DOM rebuilds invalidate the browser's native undo stack; the component maintains its own
-- **Accessible by default** — `role="textbox"`, `aria-multiline="true"`, spellcheck disabled, focus management
-
----
-
-## Architecture
-
-### DOM Structure
-
-```
-rc-textarea (LitElement shadow host, delegatesFocus=true)
-├── #root (flex container)
-│   ├── #gutter (line/list/custom gutter, optional)
-│   │   └── #gutter-cells (container for .gutter-cell spans, one per line)
-│   └── #editor-area (flex item, grows to fill)
-│       ├── #editor (contenteditable div — Parchment ScrollBlot root)
-│       │   └── .v2-line divs (one per logical line, V2BlockBlot)
-│       │       ├── text nodes (plain text content)
-│       │       ├── .v2-mark spans (V2InlineBlot — mark decorations)
-│       │       ├── .v2-widget spans (V2WidgetBlot — inline widgets, contenteditable=false)
-│       │       └── [data-message] attr (error-lens: used by ::after pseudo-element)
-│       └── <slot> (lightDOM textarea — hidden, form-only)
-```
-
-**Shadow DOM usage**: `delegatesFocus=true` ensures focus management works correctly. Line numbers are in the shadow DOM but read-only.
-
-### Editing Loop (Data Flow)
-
-1. **Browser handles edit** — User types/pastes/deletes text in the contenteditable div
-2. **`input` event fires** → `_onInput()` handler:
-   - Save DOM selection to plain-text offsets via `saveSelection()`
-   - Extract plain text via `extractEditorText()`
-   - Update `this._value`
-   - Dispatch `rc-textarea-change` event
-   - Map existing decorations through the text change via `mapDecorationsThroughChange()`
-   - Schedule RAF render pass
-3. **RAF render pass** → `_performRender()`:
-   - Extract plugin decorations
-   - Re-run patterns (rebuild all pattern decorations from regex)
-   - Ask plugin for new decorations (call `plugin.update()` or `plugin.highlight()`)
-   - Build `V2Document` from text + all decorations
-   - Tear down and fully rebuild the blot tree
-   - Restore DOM selection via `restoreSelection()`
-   - Update line number gutter if `lineNumbers=true`
-4. **Decorations stay in sync** — All existing decorations persist through edits (mapped to new offsets)
-
-**Key insight for LLM agents**: The blot tree is **rebuilt on every render frame**. This is necessary because decoration changes require DOM restructuring. The undo stack stores plain-text values, not DOM snapshots.
-
-### Parchment Integration
-
-- **`V2ScrollBlot`** wraps the `#editor` div and suppresses Parchment's `MutationObserver` (which would fight with our render loop)
-- **`V2BlockBlot`** represents a single line (`.v2-line` div)
-- **`V2InlineBlot`** represents a mark decoration (`.v2-mark` span)
-- **`V2WidgetBlot`** represents an inline widget (`.v2-widget` span, `contenteditable=false`)
-- **`V2Document`** class contains the build logic: `build(text, decorations) → BlotTree`
-
-The blot tree is **immutable** — each render creates a new tree from scratch, then the DOM is replaced.
-
-### Cursor Management
-
-Plain-text offsets are essential for:
-- Storing selection state across DOM rebuilds
-- Decoration `from`/`to` ranges
-- Plugin API (selection, cursor position)
-- Undo/redo stack
-
-**`selection.ts` module**:
-- `saveSelection()` — convert DOM range to plain-text offsets, skipping widget spans
-- `restoreSelection()` — convert plain-text offsets back to DOM range after rebuild
-
-### File Organization
-
-| File | Purpose |
-|------|---------|
-| `src/rc-textarea.ts` | Main LitElement: editing loop, plugin/pattern management, form wiring, undo/redo stack, gutter, event dispatch |
-| `src/document.ts` | `V2Document` class — builds Parchment tree from text + decorations; `extractEditorText()` reverse operation |
-| `src/blots.ts` | Parchment blot subclasses (`V2ScrollBlot`, `V2BlockBlot`, `V2InlineBlot`, `V2WidgetBlot`) + blot registry |
-| `src/selection.ts` | `saveSelection()` / `restoreSelection()` for plain-text ↔ DOM range conversion |
-| `src/decoration.ts` | `mapDecorationsThroughChange()` — map existing decorations through text edits; `isLargeChange()` heuristic |
-| `src/pattern-matcher.ts` | `matchPatternResults()` — run `TextPattern` array against text, return mark + line decorations |
-| `src/line-decorator.ts` | `createLineDecoratorPlugin()` factory — wraps per-line decoration logic in a full `RCTextareaPlugin` |
-| `src/types.ts` | All exported TypeScript interfaces and utility types |
-| `src/rc-textarea.styles.ts` | Component CSS (custom properties, parts, internal layout) |
+- **Mixed inline formatting** - bold, italic, color, background, and underline
+- **Imperative APIs** that behave well with reactive frameworks
+- **Error-lens style line annotations** that stay separate from text content
+- **Inline widgets** - color swatches, icons, tooltips or quick action buttons are possible
+- **Simple Pattern API** that auto-decorates text matching regular expressions
+- **Plugin API** - imperative decoration control + highlight.js / prism.js HTML compatibility bridge
+- **Line numbers, word wrap, auto-grow** - declarative features for common use cases
+- **Progressive enhancement** - wraps a native `<textarea>` for form submission, label association
+- **Undo/redo** - durable internally-tracked undo stack
 
 ---
 
@@ -130,411 +26,185 @@ Plain-text offsets are essential for:
 
 ```bash
 npm install @rcarls/rc-textarea
-# or
+```
+
+```bash
 yarn add @rcarls/rc-textarea
 ```
 
-Import to auto-register the custom element:
+Import the define entry to register `<rc-textarea>`:
 
 ```ts
-import '@rcarls/rc-textarea';
+import '@rcarls/rc-textarea/define';
 ```
 
-Or import the class for typed access:
+Import public types when you need typed access:
 
 ```ts
-import { RCTextarea } from '@rcarls/rc-textarea';
+import type { RCTextarea, RCTextareaPlugin } from '@rcarls/rc-textarea';
 ```
 
----
-
 ## Basic Usage
 
-Slot a native `<textarea>` as the direct child. It is hidden from view and used only for form wiring.
+Slot a native `<textarea>` as the direct child. It is hidden from view and used
+only for form wiring.
 
 ```html
-<rc-textarea>
-  <textarea name="body" rows="10" placeholder="Start typing…"></textarea>
+<label for="message">Message</label>
+
+<rc-textarea line-numbers word-wrap auto-grow>
+  <textarea id="message" name="message" rows="10" placeholder="Start typing..."></textarea>
 </rc-textarea>
 ```
 
-The component adopts the textarea's `name`, `required`, `disabled`, `maxlength`, `placeholder`, and initial `value`. Form submission reads the textarea's value, which is kept in sync by the component.
-
-### JavaScript access
+Use the `value` property for controlled updates, `defaultValue` for an initial uncontrolled
+value, and `rc-textarea-change` for user-originated changes.
 
 ```ts
 const editor = document.querySelector('rc-textarea');
 
-// Read current plain text
-console.log(editor.value);
-
-// Set programmatically
-editor.value = 'new content';
+editor.value = 'Programmatic updates are silent.';
 
-// Track changes
-editor.addEventListener('rc-textarea-change', (e) => {
-  console.log('New value:', e.detail.value);
+editor.addEventListener('rc-textarea-change', (event) => {
+  console.log(event.detail.value);
 });
 ```
 
----
-
-## Attributes & Properties
-
-All attributes reflect to properties. Use attributes in HTML or properties in JS.
-
-| Attribute | Property | Type | Default | Description |
-|-----------|----------|------|---------|-------------|
-| `line-numbers` | `lineNumbers` | `boolean` | `false` | Display line number gutter on the left |
-| `list-numbers` | `listNumbers` | `boolean` | `false` | Display a numbered list gutter (skips blank lines, resets counter) |
-| `gutter` | `gutter` | `boolean` | `false` | Show a gutter column without built-in content (plugins fill cells via `LineDecoration.gutterContent`) |
-| `word-wrap` | `wordWrap` | `boolean` | `false` | Enable word wrapping (default: scroll horizontally) |
-| `auto-grow` | `autoGrow` | `boolean` | `false` | Grow container height to fit content |
-| `read-only` | `readOnly` | `boolean` | `false` | Disable text editing; still selectable |
-| `label` | `label` | `string \| null` | `null` | Sets `aria-label` on the editor div |
-
-### Example
+When the user edits, the slotted textarea is kept in sync and dispatches a native bubbling
+`input` event. Submitting a form reads the textarea's plain-text value normally.
 
 ```html
-<rc-textarea 
-  id="code-editor" 
-  line-numbers 
-  word-wrap 
-  auto-grow
-  label="Code editor"
->
-  <textarea name="code" rows="20"></textarea>
-</rc-textarea>
-```
+<form>
+  <rc-textarea>
+    <textarea name="body" required maxlength="5000"></textarea>
+  </rc-textarea>
 
-```ts
-const editor = document.querySelector('#code-editor');
-console.log(editor.lineNumbers);  // true
-console.log(editor.wordWrap);     // true
+  <button type="submit">Send</button>
+</form>
 ```
 
----
+## Common Options
 
-## Value Property
+| Attribute      | Property      | Description                                                                         |
+| -------------- | ------------- | ----------------------------------------------------------------------------------- |
+| `line-numbers` | `lineNumbers` | Show sequential line numbers in the gutter.                                         |
+| `gutter`       | `gutter`      | Show an empty gutter that plugins can populate with `LineDecoration.gutterContent`. |
+| `word-wrap`    | `wordWrap`    | Wrap long lines instead of scrolling horizontally.                                  |
+| `auto-grow`    | `autoGrow`    | Let the field grow vertically with content.                                         |
+| `read-only`    | `readOnly`    | Render selectable, non-editable content.                                            |
 
-```ts
-const editor = document.querySelector('rc-textarea');
-
-// Read
-const plainText = editor.value;
-
-// Write — decorations are mapped through the change
-editor.value = 'hello world';
+`list-numbers` and `label` still exist for compatibility but are deprecated. Prefer a plugin
+with `LineDecoration.gutterContent` for sparse numbering, and put accessible names on the
+slotted textarea with `aria-label` or a real `<label for="...">`.
 
-// Write via textarea (if slotted)
-const textarea = editor.querySelector('textarea');
-textarea.value = 'test';
-editor.value = textarea.value;  // sync if needed
-```
-
-Setting `value` programmatically:
-1. Updates `this._value` and the slotted textarea
-2. Dispatches `rc-textarea-change` event
-3. Schedules a RAF render pass
-4. Existing decorations are **mapped through the change** (shifted, clamped, or cleared)
+The main JavaScript-only properties are:
 
----
+| Property                          | Type                       | Description                                                               |
+| --------------------------------- | -------------------------- | ------------------------------------------------------------------------- |
+| `value`                           | `string`                   | Current plain-text value. Host writes are silent.                         |
+| `defaultValue`                    | `string \| undefined`      | Initial uncontrolled value, used before `value` or textarea content wins. |
+| `plugin`                          | `RCTextareaPlugin \| null` | Declarative plugin hook for reactive frameworks.                          |
+| `decorations`                     | `DecorationInput[]`        | External decoration layer merged with plugin and pattern decorations.     |
+| `selectionStart` / `selectionEnd` | `number`                   | Current plain-text selection offsets.                                     |
 
 ## Events
 
-All events bubble and are composed (cross shadow boundary).
+All public events bubble and are composed.
 
-| Event | Detail | Fires when |
-|-------|--------|------------|
-| `rc-textarea-change` | `{ value: string }` | Text changes (input, paste, undo/redo, programmatic `value` set) |
-| `rc-textarea-focus` | (empty) | Editor receives focus |
-| `rc-textarea-blur` | (empty) | Editor loses focus |
-| `rc-textarea-select` | `{ selectionStart: number, selectionEnd: number }` | Selection changes (cursor move, click, keyboard nav) |
+| Event                | Detail                                             | Fires when                                         |
+| -------------------- | -------------------------------------------------- | -------------------------------------------------- |
+| `rc-textarea-change` | `{ value: string }`                                | User editing changes the plain-text value.         |
+| `rc-textarea-focus`  | none                                               | The editor receives focus.                         |
+| `rc-textarea-blur`   | none                                               | The editor loses focus.                            |
+| `rc-textarea-select` | `{ selectionStart: number, selectionEnd: number }` | The selection changes while the editor is focused. |
 
-### Example
+## Pattern Highlights
 
-```ts
-const editor = document.querySelector('rc-textarea');
-
-editor.addEventListener('rc-textarea-change', (e) => {
-  console.log('Text changed to:', e.detail.value);
-});
-
-editor.addEventListener('rc-textarea-select', (e) => {
-  const { selectionStart, selectionEnd } = e.detail;
-  console.log(`Selection: ${selectionStart}–${selectionEnd}`);
-});
+Use `addPattern()` for lightweight regex decoration without writing a plugin.
 
-editor.addEventListener('rc-textarea-focus', () => {
-  console.log('Editor focused');
+```ts
+const todoPatternId = editor.addPattern({
+  pattern: /\bTODO\b/g,
+  bold: true,
+  color: 'var(--editor-todo-color)',
 });
-```
-
----
 
-## CSS Customization
-
-### Custom Properties
-
-Set on the host element or any ancestor to style the editor.
-
-| Property | Default | Description |
-|----------|---------|-------------|
-| `--rc-textarea-font-family` | `monospace` | Font family for text and line numbers |
-| `--rc-textarea-font-size` | `1em` | Base font size |
-| `--rc-textarea-line-height` | `1.5` | Line height affects gutter alignment |
-| `--rc-textarea-padding` | `0.5em` | Inner padding of editor area |
-| `--rc-textarea-background` | `Field` | Editor background color (system color keyword) |
-| `--rc-textarea-color` | `FieldText` | Text color (system color keyword) |
-| `--rc-textarea-caret-color` | (auto) | Cursor/caret color |
-| `--rc-textarea-border` | `1px solid ButtonBorder` | Editor border (system color keyword) |
-| `--rc-textarea-border-radius` | `2px` | Corner rounding |
-| `--rc-textarea-focus-outline` | `2px solid AccentColor` | Focus ring (system color keyword) |
-| `--rc-textarea-active-line-bg` | `transparent` | Background of the line containing the cursor |
-| `--rc-textarea-gutter-color` | `GrayText` | Line number text color |
-| `--rc-textarea-gutter-bg` | `Canvas` | Gutter background |
-| `--rc-textarea-gutter-border` | `1px solid ButtonBorder` | Gutter right border |
-| `--rc-textarea-gutter-padding-inline-end` | `0.75em` | Gap between gutter numbers and editor content |
-
-### Example
-
-```css
-rc-textarea {
-  --rc-textarea-font-family: 'Fira Code', monospace;
-  --rc-textarea-font-size: 13px;
-  --rc-textarea-line-height: 1.6;
-  --rc-textarea-background: #1e1e2e;
-  --rc-textarea-color: #cdd6f4;
-  --rc-textarea-caret-color: #89b4fa;
-  --rc-textarea-border: 1px solid #313244;
-  --rc-textarea-border-radius: 4px;
-}
-```
-
-### CSS Parts
-
-Use `::part()` pseudo-element for advanced styling.
-
-| Part | Element | Supports |
-|------|---------|----------|
-| `root` | Outer flex container | All CSS |
-| `gutter` | Gutter outer div | All CSS |
-| `gutter-cells` | Inner container holding `.gutter-cell` spans | All CSS |
-| `editor-area` | Container wrapping editor + slot | All CSS |
-| `editor` | The `contenteditable` div | All CSS |
-
-### Example
-
-```css
-rc-textarea::part(editor) {
-  border-radius: 4px;
-  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
-}
-
-rc-textarea::part(gutter) {
-  background: #f5f5f5;
-  font-size: 0.9em;
-}
+editor.removePattern(todoPatternId);
+editor.clearPatterns();
 ```
 
-### Mark decoration styling
-
-Inline decorations are applied to `.v2-mark` spans. Inline styles handle standard properties (bold, italic, color, etc.). For custom classes:
+Patterns can also style named capture groups and add line diagnostics.
 
 ```ts
-let api: RCTextareaPluginAPI;
-editor.usePlugin({
-  mount(a) { api = a; },
-  update() {},
+editor.addPattern({
+  pattern: /^(?<key>\w[\w-]*):\s*(?<value>.+)$/gm,
+  captureGroups: {
+    key: { bold: true, color: 'var(--editor-key-color)' },
+    value: { color: 'var(--editor-value-color)' },
+  },
+  createLineDecoration: () => ({ className: 'config-line' }),
 });
-
-// Add decorations with a custom class
-api.setDecorations([
-  { type: 'mark', from: 5, to: 10, className: 'my-highlight' }
-]);
-
-// Style it in an adopted stylesheet
-api.adoptStyleSheet(`
-  .v2-mark.my-highlight { background: yellow; }
-`);
 ```
 
----
-
-## Plugin API
+See [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) for the complete decoration and plugin model.
 
-Plugins are the primary mechanism for applying decorations. A plugin receives a `RCTextareaPluginAPI` during `mount()` — **save this reference** to set decorations from outside the plugin lifecycle.
+## Markdown Plugin Package
 
-### Interface Overview
+Install the Markdown plugin package when you want Markdown-oriented decorations and preview
+HTML without writing your own parser bridge.
 
-```ts
-interface RCTextareaPlugin {
-  /** Called once when the plugin is registered. Store `api` here for external use. */
-  mount?(api: RCTextareaPluginAPI): void;
-  /** Called when the plugin is replaced or the element disconnects. */
-  destroy?(): void;
-  /**
-   * Display-layer value transform — called before `update`/`highlight` in
-   * read-only mode. Return a non-null string to substitute it as the rendered
-   * text. The underlying `element.value` is never modified.
-   */
-  transform?(value: string, api: RCTextareaPluginAPI): string | null | void;
-  /** Imperative decoration API — called on each value change. */
-  update?(value: string, api: RCTextareaPluginAPI): void | Promise<void>;
-  /**
-   * HTML-based compat — called on each value change.
-   * Return an HTML string (e.g. from hljs/prism); it will be parsed into
-   * mark decorations via `api.decorationsFromHtml()`.
-   */
-  highlight?(value: string, api: RCTextareaPluginAPI):
-    string | null | void | Promise<string | null | void>;
-}
+```bash
+npm install @rcarls/rc-textarea @rcarls/rc-textarea-plugin-markdown \
+  mdast-util-from-markdown micromark unist-util-visit
 ```
 
-At least one of `update` or `highlight` must be provided. `transform` is only
-called in read-only mode and is typically used to substitute scaled or formatted
-display text while preserving the raw underlying value.
-
-### PluginAPI Methods
-
-```ts
-interface RCTextareaPluginAPI {
-  readonly host: HTMLElement;           // rc-textarea element
-  readonly value: string;               // Current plain text
-  readonly selectionStart: number;      // Normalized selection start (≤ selectionEnd)
-  readonly selectionEnd: number;        // Normalized selection end (≥ selectionStart)
-
-  getCursorRect(): DOMRect | null;      // Cursor position in viewport coords (or null if not focused)
-  getWordAtCursor(): { word: string; from: number; to: number } | null;
-  onCursorMove(cb: (start: number, end: number) => void): () => void;
-
-  addDecoration(d: DecorationInput): string;        // Add single decoration, return ID
-  removeDecoration(id: string): void;               // Remove by ID
-  clearDecorations(): void;                         // Remove all plugin decorations
-  setDecorations(decorations: DecorationInput[]): void;  // Replace all with new set
-
-  scheduleUpdate(): void;               // Trigger render outside input events
-
-  adoptStyleSheet(sheetOrCssText: CSSStyleSheet | string): CSSStyleSheet;
-  removeStyleSheet(sheet: CSSStyleSheet): void;
-  decorationsFromHtml(html: string): Omit<MarkDecoration, 'id'>[];
-}
+```bash
+yarn add @rcarls/rc-textarea @rcarls/rc-textarea-plugin-markdown \
+  mdast-util-from-markdown micromark unist-util-visit
 ```
 
-### Mounting and Lifecycle
-
 ```ts
-const editor = document.querySelector('rc-textarea');
-
-let api: RCTextareaPluginAPI;
-
-editor.usePlugin({
-  mount(a) {
-    api = a;  // Save reference for external use
-    console.log('Plugin mounted');
-  },
-  update(value, a) {
-    // Called on each value change
-    const decorations = parseText(value);
-    a.setDecorations(decorations);
-  },
-  destroy() {
-    console.log('Plugin unmounting');
-  },
-});
-
-// From outside plugin lifecycle, using saved reference
-api.setDecorations([
-  { type: 'mark', from: 0, to: 5, bold: true }
-]);
-api.scheduleUpdate();
-```
+import '@rcarls/rc-textarea/define';
+import { createMarkdownPlugin } from '@rcarls/rc-textarea-plugin-markdown';
 
-### Example 1: Synchronous Imperative Plugin
+const editor = document.querySelector('rc-textarea');
+const markdown = createMarkdownPlugin();
 
-Manually find patterns and apply decorations:
+editor.usePlugin(markdown);
 
-```ts
-const markdownLitePlugin = {
-  update(value, api) {
-    const decorations = [];
-
-    // Bold: **text**
-    const boldRe = /\*\*(.+?)\*\*/g;
-    let m;
-    while ((m = boldRe.exec(value)) !== null) {
-      decorations.push({
-        type: 'mark',
-        from: m.index,
-        to: m.index + m[0].length,
-        bold: true
-      });
-    }
-
-    // Italic: *text*
-    const italicRe = /\*([^*]+)\*/g;
-    while ((m = italicRe.exec(value)) !== null) {
-      decorations.push({
-        type: 'mark',
-        from: m.index,
-        to: m.index + m[0].length,
-        italic: true
-      });
-    }
-
-    api.setDecorations(decorations);
-  },
-};
-
-editor.usePlugin(markdownLitePlugin);
+preview.innerHTML = markdown.getPreviewHtml(editor.value);
 ```
 
-### Example 2: Asynchronous Plugin (WASM / Web Worker)
+The package decorates common Markdown syntax using `mdast-util-from-markdown` and exposes
+`getMarkdownPreviewHtml()` / `plugin.getPreviewHtml()` for preview rendering.
 
-```ts
-editor.usePlugin({
-  async update(value, api) {
-    const decorations = await myWasmParser.tokenize(value);
-    api.setDecorations(decorations);
-  },
-});
-```
+## highlight.js And Prism Bridge
 
-Stale results are automatically discarded if a newer render starts before the promise resolves.
-
-### Example 3: highlight.js Integration
+`rc-textarea` can consume the HTML strings produced by highlighters that wrap token text in
+`<span class="...">...</span>` nodes. Return that HTML from `highlight()` or call
+`api.parseDecorationsFromHtml()` yourself inside `update()`.
 
 ```ts
 import hljs from 'highlight.js/lib/core';
 import javascript from 'highlight.js/lib/languages/javascript';
+
 hljs.registerLanguage('javascript', javascript);
 
 editor.usePlugin({
   mount(api) {
-    // Inject theme CSS into shadow root (hljs classes live inside)
     api.adoptStyleSheet(`
-      .hljs-keyword { color: #cba6f7; }
-      .hljs-string  { color: #a6e3a1; }
-      .hljs-number  { color: #fab387; }
-      .hljs-comment { color: #6c7086; font-style: italic; }
-      .hljs-title   { color: #89b4fa; font-weight: bold; }
-      .hljs-built_in { color: #89dceb; }
-      .hljs-literal { color: #f5c2e7; }
+      .hljs-keyword { color: var(--editor-syntax-keyword); font-weight: 600; }
+      .hljs-string { color: var(--editor-syntax-string); }
+      .hljs-comment { color: var(--editor-syntax-comment); font-style: italic; }
     `);
   },
-  highlight(value, api) {
-    // hljs.highlight returns HTML with span wrapping syntax tokens
-    const { value: html } = hljs.highlight(value, { language: 'javascript' });
-    // Convert HTML token markup to decorations
-    api.setDecorations(api.decorationsFromHtml(html));
+
+  highlight(value) {
+    return hljs.highlight(value, { language: 'javascript' }).value;
   },
 });
 ```
 
-**Important**: hljs token class spans live inside the shadow root. Light-DOM stylesheets cannot pierce the shadow boundary, so theme CSS must be injected via `api.adoptStyleSheet()`.
-
-### Example 4: Prism.js Integration
-
 ```ts
 import Prism from 'prismjs';
 import 'prismjs/components/prism-python';
@@ -542,770 +212,97 @@ import 'prismjs/components/prism-python';
 editor.usePlugin({
   mount(api) {
     api.adoptStyleSheet(`
-      .token.keyword { color: #66d9ef; font-weight: bold; }
-      .token.string  { color: #e6db74; }
-      .token.number  { color: #ae81ff; }
-      .token.comment { color: #75715e; font-style: italic; }
-      .token.function { color: #a1efe4; }
+      .token.keyword { color: var(--editor-syntax-keyword); font-weight: 600; }
+      .token.string { color: var(--editor-syntax-string); }
+      .token.comment { color: var(--editor-syntax-comment); font-style: italic; }
     `);
   },
-  highlight(value, api) {
-    const html = Prism.highlight(value, Prism.languages.python, 'python');
-    api.setDecorations(api.decorationsFromHtml(html));
-  },
-});
-```
-
-### Switching / Removing Plugins
-
-Only one plugin can be active at a time. Calling `usePlugin()` with a new plugin calls `destroy()` on the previous one.
-
-```ts
-editor.usePlugin(newPlugin);   // previous plugin is destroyed
-editor.removePlugin();         // current plugin destroyed, decorations cleared
-```
-
-### Accessing Slotted Textarea
 
-Plugins can read the textarea to access its attributes:
-
-```ts
-editor.usePlugin({
-  mount(api) {
-    const textarea = api.host.querySelector('textarea');
-    if (textarea) {
-      console.log('Form name:', textarea.name);
-      console.log('Max length:', textarea.maxLength);
-    }
+  highlight(value) {
+    return Prism.highlight(value, Prism.languages.python, 'python');
   },
 });
 ```
 
----
+For Lezer, Unified, and Shiki integrations, see `@rcarls/rc-textarea-adapters`.
 
-## Decoration Types
+## Theming
 
-Decorations are objects describing visual changes. All decorations are immutable after creation (API methods return new IDs or replace entire sets).
+`rc-textarea` is design-system neutral and uses CSS system colors by default. Theme it with broad tokens
+for the field, then add component tokens for editor-specific surfaces.
 
-### MarkDecoration — styled character range
+### Broad Theme Tokens
 
-A visual style applied to a contiguous range of characters. Inline styles are rendered directly; `className` adds an extra CSS class for complex styling.
+The component reads inherited tokens where possible:
 
-```ts
-interface MarkDecoration {
-  id: string;              // Auto-assigned — omit when passing to API
-  type: 'mark';
-  from: number;            // Inclusive start (0-based character offset into plain text)
-  to: number;              // Exclusive end
-  className?: string;      // CSS class added to the span
-  bold?: boolean;          // Inline: font-weight: bold
-  italic?: boolean;        // Inline: font-style: italic
-  color?: string;          // Inline: color (CSS color value)
-  background?: string;     // Inline: background-color
-  underline?: 'solid' | 'wavy' | 'dotted' | 'dashed';  // text-decoration-style
-  underlineColor?: string; // text-decoration-color
-  attributes?: Record<string, string>;  // Extra HTML attributes (data-*, title, etc.)
-}
-```
+| Token          | Use                                                          |
+| -------------- | ------------------------------------------------------------ |
+| `--rc-text`    | Fallback text color before `--rc-textarea-color`.            |
+| `color-scheme` | Inherited by the host so system colors match the page theme. |
 
-### LineDecoration — whole-line styling + error-lens annotation
+### Component Tokens
 
-Applied to an entire logical line. Adds a CSS class to the line div and optionally renders an error-lens message at the end.
-
-```ts
-interface LineDecoration {
-  id: string;
-  type: 'line';
-  line: number;                    // 1-based logical line number
-  className?: string;              // CSS class on the .v2-line div
-  message?: string;                // Error-lens text (rendered via ::after, not selectable)
-  messageClassName?: string;       // Space-separated class(es) set as data-message-class
-  attributes?: Record<string, string>;
-  gutterContent?: string | null;   // Override gutter cell text for this line:
-                                   //   string  — custom label (e.g. "!", "▶")
-                                   //   null    — force empty (suppress built-in content)
-                                   //   omitted — use the built-in mode default
-}
-```
-
-Error-lens messages are rendered via CSS `::after` pseudo-element — they do not appear in selection or clipboard.
+| Token                                     | Default                               | Use                                   |
+| ----------------------------------------- | ------------------------------------- | ------------------------------------- |
+| `--rc-textarea-font-family`               | `monospace`                           | Editor and gutter font family.        |
+| `--rc-textarea-font-size`                 | `1em`                                 | Editor and gutter font size.          |
+| `--rc-textarea-line-height`               | `1.5`                                 | Editor and gutter line height.        |
+| `--rc-textarea-padding`                   | `0.5em`                               | Editor and gutter padding.            |
+| `--rc-textarea-background`                | `Field`                               | Field background.                     |
+| `--rc-textarea-color`                     | `var(--rc-text, FieldText)`           | Field text color.                     |
+| `--rc-textarea-caret-color`               | `var(--rc-textarea-color, FieldText)` | Caret color.                          |
+| `--rc-textarea-border`                    | `1px solid ButtonBorder`              | Field border.                         |
+| `--rc-textarea-border-radius`             | `2px`                                 | Field corner radius.                  |
+| `--rc-textarea-focus-outline`             | `2px solid Highlight`                 | Focus ring.                           |
+| `--rc-textarea-active-line-bg`            | `transparent`                         | Active line background.               |
+| `--rc-textarea-gutter-bg`                 | `Canvas`                              | Gutter background.                    |
+| `--rc-textarea-gutter-color`              | `GrayText`                            | Gutter text color.                    |
+| `--rc-textarea-gutter-border`             | `1px solid ButtonBorder`              | Gutter separator.                     |
+| `--rc-textarea-gutter-padding-inline-end` | `0.75em`                              | Space between gutter labels and text. |
 
 ```css
-/* in an adopted stylesheet */
-.v2-line[data-message]::after {
-  content: attr(data-message);
-  margin-left: 1em;
-  color: #f38ba8;
-  font-style: italic;
-}
-```
-
-### WidgetDecoration — non-editable inline element
-
-A DOM element inserted at a character offset. Widgets are purely visual and do not appear in the plain text value.
-
-```ts
-interface WidgetDecoration {
-  id: string;
-  type: 'widget';
-  offset: number;           // Character offset — widget placed before/after this position
-  create(): HTMLElement;    // Factory called each render — must return a **new** element
-  side?: 'before' | 'after';  // Placement relative to character. Default: 'before'
-}
-```
-
-**Important**: `create()` is called on every render frame. Return a new element each time; do not reuse the same DOM node.
-
-```ts
-api.setDecorations([
-  {
-    type: 'widget',
-    offset: 5,
-    create() {
-      const el = document.createElement('span');
-      el.textContent = '👉';
-      el.style.color = '#fab387';
-      return el;
-    },
-  },
-]);
-```
-
-### DecorationInput (for API calls)
-
-When calling `api.addDecoration()`, `api.setDecorations()`, etc., omit the `id` field:
-
-```ts
-type DecorationInput = 
-  | Omit<MarkDecoration, 'id'>
-  | Omit<LineDecoration, 'id'>
-  | Omit<WidgetDecoration, 'id'>;
-```
-
----
-
-## Pattern API
-
-Patterns automatically apply decorations to all regex matches on every value change, without manual event handling.
-
-### Adding and Removing Patterns
-
-```ts
-const editor = document.querySelector('rc-textarea');
-
-// Boolean pattern — bold + orange all "TODO" occurrences
-const patternId = editor.addPattern({
-  pattern: /\bTODO\b/g,
-  bold: true,
-  color: '#fab387',
-});
-
-// Remove a specific pattern
-editor.removePattern(patternId);
-
-// Remove all patterns
-editor.clearPatterns();
-```
-
-### TextPattern Interface
-
-```ts
-interface TextPattern {
-  id: string;               // Auto-assigned — omit when calling addPattern()
-  pattern: RegExp;          // Global flag is added automatically if missing
-  className?: string;
-  bold?: boolean;
-  italic?: boolean;
-  color?: string;
-  background?: string;
-  underline?: 'solid' | 'wavy' | 'dotted' | 'dashed';
-  underlineColor?: string;
-  attributes?: Record<string, string>;
-
-  /**
-   * Per-named-capture-group styles. When set, one MarkDecoration is emitted
-   * per named group instead of one for the whole match. The 'd' flag
-   * (indices) is added to the pattern automatically.
-   * Unmatched optional groups are silently skipped.
-   */
-  captureGroups?: Record<string, MarkDecorationStyle>;
-
-  // Callback to generate a LineDecoration for matching lines
-  createLineDecoration?: (match: RegExpMatchArray) =>
-    | Omit<LineDecoration, 'id' | 'type' | 'line'>
-    | null;
+rc-textarea {
+  color-scheme: dark;
+  --rc-textarea-font-family: 'Fira Code', monospace;
+  --rc-textarea-font-size: 13px;
+  --rc-textarea-background: #1e1e2e;
+  --rc-textarea-color: #cdd6f4;
+  --rc-textarea-border: 1px solid #313244;
+  --rc-textarea-active-line-bg: rgb(255 255 255 / 0.06);
 }
-
-/** Subset of MarkDecoration properties used for styling (no id / from / to). */
-type MarkDecorationStyle = Pick<MarkDecoration,
-  'className' | 'bold' | 'italic' | 'color' | 'background' |
-  'underline' | 'underlineColor' | 'attributes'
->;
 ```
 
-### Example: Simple Pattern
+### Parts And Decoration Styles
 
-```ts
-// Red wavy underline for "FIXME"
-editor.addPattern({
-  pattern: /\bFIXME\b/g,
-  color: '#f38ba8',
-  underline: 'wavy',
-  underlineColor: '#f38ba8',
-});
-```
+The exposed CSS parts are `root`, `gutter`, `gutter-cells`, `editor-area`, and `editor`.
 
-### Example: Pattern with Error-Lens Annotation
-
-```ts
- editor.addPattern({
-  pattern: /\bFIXME\b/g,
-  bold: true,
-  color: '#f38ba8',
-  underline: 'wavy',
-  createLineDecoration: (match) => ({
-    className: 'fixme-line',
-    message: 'Review before release',
-    messageClassName: 'fixme-message',
-  }),
-});
-```
-
-Then style the message:
-
-```ts
-api.adoptStyleSheet(`
-  .v2-line[data-message-class~="fixme-message"]::after {
-    color: #f38ba8;
-    font-weight: bold;
-  }
-`);
-```
-
-### Example: Multi-line Regex (JavaScript comments)
-
-```ts
-editor.addPattern({
-  pattern: /\/\*[\s\S]*?\*\//g,
-  italic: true,
-  color: '#6c7086',
-  createLineDecoration: () => ({
-    message: '(comment)',
-    messageClassName: 'comment-marker',
-  }),
-});
-```
-
-### Example: Named Capture Groups (`captureGroups`)
-
-Use `captureGroups` to style different parts of a match independently without
-manual offset arithmetic. One `MarkDecoration` is emitted per named group;
-unmatched optional groups are skipped.
-
-```ts
-// key: value lines — key in purple, value in green
-editor.addPattern({
-  pattern: /^(?<key>\w[\w-]*):\s*(?<value>.+)$/gm,
-  captureGroups: {
-    key:   { bold: true, color: '#c792ea' },
-    value: { color: '#c3e88d' },
-  },
-});
-```
-
-```ts
-// Ingredient lines — quantity/measure bold, prep text muted
-editor.addPattern({
-  pattern: /^(?<qty>[\d\s\/\u215B-\u215E]+\s+\w+)\s+(?<name>[^,]+?)(?<prep>,\s+.+)?$/gm,
-  captureGroups: {
-    qty:  { bold: true },
-    name: { bold: true, color: 'var(--color-primary)' },
-    prep: { italic: true, color: 'var(--color-text-muted)' },
-  },
-});
-```
-
----
-
-## Plugin Helpers
-
-Two utilities are exported from the package to reduce plugin boilerplate.
-
-### `matchPatternResults(value, patterns)`
-
-Run a `TextPattern` array against `value` and return all matches as
-decoration objects — without registering the patterns on the editor element.
-Useful when a plugin needs to combine pattern-matched decorations with custom
-decorations in a single `api.setDecorations()` call.
-
-```ts
-import { matchPatternResults } from '@rcarls/rc-textarea';
-
-const KEYWORD_PATTERNS = [
-  { id: 'kw-function', pattern: /\bfunction\b/g, bold: true, color: '#c792ea' },
-  { id: 'kw-return',   pattern: /\breturn\b/g,   bold: true, color: '#89ddff' },
-];
-
-editor.usePlugin({
-  update(value, api) {
-    const { markDecorations, lineDecorations } =
-      matchPatternResults(value, KEYWORD_PATTERNS);
-
-    // Merge with custom diagnostics from a parser
-    const diagnostics = myParser.lint(value);
-
-    api.setDecorations([
-      ...markDecorations,
-      ...lineDecorations,
-      ...diagnostics,
-    ]);
-  },
-});
-```
-
-### `createLineDecoratorPlugin(decorator, options?)`
-
-Factory that wraps a `LineDecoratorPlugin` in a full `RCTextareaPlugin`. It handles:
-
-- CSS injection via `api.adoptStyleSheet` on `mount()`
-- `lineStart` offset bookkeeping — `decorateLine()` works with **line-relative** offsets (0 = start of the line), not absolute document offsets
-- Optional `watch` subscriptions that call `api.scheduleUpdate()` when external values change (framework-agnostic)
-- Cleanup of subscribers on `destroy()`
-
-```ts
-import { createLineDecoratorPlugin } from '@rcarls/rc-textarea';
-import type { LineDecoratorPlugin } from '@rcarls/rc-textarea';
-
-const KEYWORD_CSS = '.kw { font-weight: bold; color: #c792ea; }';
-
-const keywordDecorator: LineDecoratorPlugin = {
-  styles: KEYWORD_CSS,
-  decorateLine(line) {
-    const results = [];
-    for (const m of line.matchAll(/\bfunction\b/g)) {
-      results.push({
-        type: 'mark' as const,
-        from: m.index!,
-        to: m.index! + m[0].length,
-        className: 'kw',
-      });
-    }
-    return results;
-  },
-};
-
-editor.usePlugin(createLineDecoratorPlugin(keywordDecorator));
-```
-
-#### With `extraDecorations` (merging whole-document results)
-
-```ts
-editor.usePlugin(createLineDecoratorPlugin(
-  myLineDecorator,
-  {
-    extraDecorations: (value) => {
-      // e.g. whole-document diagnostics from a parser
-      return myParser.lint(value).map(d => ({
-        type: 'line' as const,
-        line: d.line,
-        message: d.message,
-        messageClassName: 'diagnostic-error',
-      }));
-    },
-  },
-));
-```
-
-#### With `watch` (react to external signal changes)
-
-`watch` is an array of subscriber setup functions — each receives an `onChange`
-callback and may return an optional cleanup function. This is
-intentionally framework-agnostic.
-
-```ts
-// Vanilla JS: subscribe to a custom event
-editor.usePlugin(createLineDecoratorPlugin(
-  myDecorator,
-  {
-    watch: [
-      (onChange) => {
-        window.addEventListener('theme-change', onChange);
-        return () => window.removeEventListener('theme-change', onChange);
-      },
-    ],
-  },
-));
-
-// Solid.js: pass reactive signals
-import { createEffect, on } from 'solid-js';
-
-editor.usePlugin(createLineDecoratorPlugin(
-  myDecorator,
-  {
-    watch: [
-      (cb) => createEffect(on(mySignal, cb, { defer: true })),
-    ],
-  },
-));
-```
-
----
-
-## Selection API
-
-The component tracks the current selection as plain-text offsets (not DOM nodes or ranges).
-
-### Getting Selection
-
-```ts
-interface RCTextareaPluginAPI {
-  readonly selectionStart: number;
-  readonly selectionEnd: number;
-  
-  getCursorRect(): DOMRect | null;
-  getWordAtCursor(): { word: string; from: number; to: number } | null;
-  onCursorMove(callback: (start: number, end: number) => void): () => void;
+```css
+rc-textarea::part(editor) {
+  tab-size: 2;
 }
 ```
 
-### Example: Tracking Cursor Moves
-
-```ts
-let unsub: () => void;
-
-editor.usePlugin({
-  mount(api) {
-    unsub = api.onCursorMove((start, end) => {
-      if (start === end) {
-        // Cursor is collapsed (no selection)
-        const word = api.getWordAtCursor();
-        if (word) {
-          console.log(`Cursor on word: "${word.word}" at ${word.from}–${word.to}`);
-        }
-      } else {
-        // Selection active
-        console.log(`Selection: ${start}–${end}`);
-      }
-    });
-  },
-  destroy() {
-    unsub?.();
-  },
-});
-```
-
-### Example: Anchoring Autocomplete Popup
-
-```ts
-editor.usePlugin({
-  mount(api) {
-    const unsub = api.onCursorMove(() => {
-      const rect = api.getCursorRect();
-      if (rect) {
-        const popup = document.querySelector('#autocomplete');
-        popup.style.left = rect.left + 'px';
-        popup.style.top = (rect.top + rect.height) + 'px';
-      }
-    });
-    return () => unsub?.();
-  },
-});
-```
-
----
-
-## Decoration Lifecycle
-
-Decorations undergo transformation as the text changes:
-
-### Mapping Decorations Through Changes
-
-When text is edited, existing plugin decorations are automatically adjusted:
-
-- **Before the edit region**: start/end offsets unchanged
-- **After the edit region**: start/end offsets shifted by the character delta
-- **Overlapping the edit region**: start/end clamped to edit boundaries
-- **Zero-width after clamping**: decoration is dropped
-
-### Large Change Heuristic
-
-If a change is detected as **"large"** (heuristic: `changeSize > 50 chars AND changeSize > 50% of document`), all plugin decorations are cleared to avoid mapping errors. This handles:
-
-- Paste of large text blocks
-- Select-all + type
-- Programmatic `value` set with very different content
-
-Pattern decorations are **always** fully recomputed on each change (regex is re-run).
-
-### Architecture Note for Agents
-
-Decoration mapping occurs in `mapDecorationsThroughChange()` (in `decoration.ts`). The function:
-1. Calls `findEdit()` to locate insertion/deletion boundaries
-2. Applies geometry transformation to each decoration
-3. Returns a new decoration map (old map is not mutated)
-
----
-
-## Undo / Redo
-
-The component maintains its own undo/redo stack because DOM rebuilds (which happen on every render frame) invalidate the browser's native contenteditable undo history.
-
-### Keyboard Shortcuts
-
-| Key | Action |
-|-----|--------|
-| `Ctrl+Z` / `Cmd+Z` | Undo |
-| `Ctrl+Y` / `Cmd+Y` / `Ctrl+Shift+Z` | Redo |
-
-### Stack Details
-
-- **Capacity**: 100 entries (MAX_UNDO)
-- **Stored per entry**: plain text value + cursor position (anchorOffset, focusOffset)
-- **Decorations**: not stored; recomputed from the restored value
-- **Granularity**: one entry per input event (or scheduled update)
-
-### Architecture
-
-The undo stack is stored in:
-```ts
-private _undoStack: UndoEntry[] = [];
-private _undoIndex = -1;  // Current position in stack
-```
-
-Each entry is created when text changes via input event. The stack is pruned to MAX_UNDO when full.
-
----
+Decoration elements are inside the shadow root. Use `api.adoptStyleSheet()` from a plugin to
+style custom classes such as `.my-highlight`, `.line[data-message]`, or token classes from a
+syntax highlighter.
 
 ## Keyboard Behavior
 
-| Key | Behavior |
-|-----|----------|
-| `Tab` | Insert `\t` character (does not move focus) |
-| `Ctrl/Cmd+Z` | Undo |
-| `Ctrl/Cmd+Y` / `Ctrl/Cmd+Shift+Z` | Redo |
-| `Paste` | HTML/rich text is stripped; only plain text is inserted |
-| `Enter` | Insert line break (`\n`) |
-
-### Paste Handling
-
-The component uses `input` event to detect and normalize pasted content. HTML markup is discarded; only plain text characters are inserted.
-
----
-
-## Form Integration
-
-The slotted `<textarea>` participates in form submission normally:
-
-1. **Hidden visually** — inline styles: `position: absolute; left: -9999px; opacity: 0; clip: rect(0 0 0 0)`
-2. **DOM remains** — slotted at the light DOM so form traversal finds it
-3. **Value synced** — component keeps textarea's value in sync with `this._value`
-4. **Attributes adopted** — `name`, `required`, `disabled`, `maxlength`, `placeholder` are read from textarea on mount
-5. **Submission** — form submission reads textarea's value directly
-
-### Example
-
-```html
-<form id="myform">
-  <rc-textarea>
-    <textarea 
-      name="body" 
-      required 
-      maxlength="5000"
-      placeholder="Enter your message…"
-    ></textarea>
-  </rc-textarea>
-  <button type="submit">Send</button>
-</form>
-```
-
-```ts
-document.getElementById('myform').addEventListener('submit', (e) => {
-  e.preventDefault();
-  const formData = new FormData(e.target);
-  console.log(formData.get('body'));  // Plain text value
-});
-```
-
----
-
-## Accessibility
-
-The component is designed with accessibility in mind:
-
-### ARIA Roles & Attributes
-
-- **`role="textbox"`** — identifies the editor as a text input
-- **`aria-multiline="true"`** — indicates multiline text support
-- **`aria-label`** — set via the `label` attribute (optional)
-- **`delegatesFocus=true`** — shadow DOM focus is delegated to the editable region
-
-### Keyboard Navigation
-
-- Tab and Shift+Tab focus/blur the editor normally
-- Arrow keys, Home/End, Ctrl+Arrow, etc. work natively
-- Screen readers can read selected text and cursor position
-
-### Visual Accessibility
-
-- High contrast by default (system colors)
-- `:focus-visible` indicator (can be styled via CSS custom property)
-- Line numbers are `aria-hidden="true"` (not part of screen reader navigation)
-
-### Spellcheck Disabled
-
-Spell checking is disabled to prevent vendor-specific squiggles from interfering with custom decorations. Set explicitly in the editor:
-
-```ts
-editor.spellcheck = false;
-editor.autocorrect = 'off';
-editor.autocapitalize = 'off';
-```
-
----
-
-## Performance Considerations
-
-### DOM Rebuild on Every Render
-
-The blot tree is **completely rebuilt** on each render frame (RAF-batched). This is necessary because:
-- Decoration changes require DOM restructuring
-- Plain-text ↔ DOM offset conversion requires a stable tree
-- Cursor restoration requires rebuilding after changes
-
-For documents **< 10,000 characters**, this is imperceptible. For very large documents, consider:
-- Truncating visible content (virtual scrolling)
-- Debouncing plugin updates
-- Using pattern decorations instead of plugin updates (patterns are optimized)
+| Key                               | Behavior                                                     |
+| --------------------------------- | ------------------------------------------------------------ |
+| `Tab`                             | Inserts `\t`.                                                |
+| `Ctrl/Cmd+Z`                      | Undo.                                                        |
+| `Ctrl/Cmd+Y` / `Ctrl/Cmd+Shift+Z` | Redo.                                                        |
+| `Paste`                           | Inserts plain text only and normalizes line endings to `\n`. |
+| `Enter`                           | Inserts a line break.                                        |
 
-### Decoration Density
+## More Detail
 
-Large numbers of overlapping decorations (e.g., 1000+ marks on a single line) will impact performance. Keep decoration counts reasonable:
-- Syntax highlighting: typically 10–100 marks per line
-- Error markers: typically 1–5 per line
-- Patterns: typically < 50 matches per line
-
-If density is high, profile with DevTools to identify bottlenecks.
-
-### Memory
-
-The undo/redo stack stores 100 entries of `{ value, anchorOffset, focusOffset }`. For a 10 KB document, this is ~1 MB. For very large documents, consider limiting undo depth or using an external undo manager.
-
----
-
-## Troubleshooting
-
-### Selection is lost after edit
-
-Normal behavior — selection is saved before render and restored after. If you're updating text and immediately reading `selectionStart`, use `onCursorMove()` or `setTimeout()` to wait for the next render frame.
-
-```ts
-editor.value = 'new text';
-// DON'T do this:
-console.log(editor.selectionStart);  // May be stale
-
-// DO this:
-await editor.updateComplete;
-const start = editor.value === 'new text' ? api.selectionStart : null;
-```
-
-### Decorations disappear after large paste
-
-If you paste a large block of text (> 50 chars and > 50% of document), plugin decorations are cleared by the "large change heuristic" to avoid mapping errors. Pattern decorations are reapplied. To preserve plugin decorations, update them in the plugin's `update()` method:
-
-```ts
-editor.usePlugin({
-  update(value, api) {
-    // Recompute decorations from the new value
-    const decs = parseText(value);
-    api.setDecorations(decs);
-  },
-});
-```
-
-### Other's DOM change events fire inside editor
-
-The component does not suppress mutation events on the editor. If you're listening for `MutationObserver` events on the editor element, you'll observe all blot tree rebuilds. To avoid this, listen outside the editor or throttle updates.
-
-### cursor doesn't stay at expected position
-
-Cursor restoration uses plain-text offsets. If decorations change (especially widgets, which take up no space in the value), the visual cursor position may shift. This is expected. Use `getCursorRect()` to anchor UI elements if precise positioning is critical.
-
-### Text is very long (> 100 KB), editor is slow
-
-The entire blot tree is rebuilt on each character input. For very large documents:
-- Profile with DevTools Performance tab to identify bottleneck
-- Consider truncating visible content (virtual scrolling)
-- Use `word-wrap: false` to reduce line breaks (fewer blots)
-- Limit undo depth: only keep last 10 entries instead of 100
-
-### Plugin's `highlight()` result is overwritten immediately
-
-If both `update()` and `highlight()` are provided, only one runs per render. The component runs `highlight()` if it returns a truthy value; otherwise, `update()` is called.
-
----
-
-## API Reference Summary
-
-### Properties
-
-| Property | Type | Default | Reflects |
-|----------|------|---------|----------|
-| `value` | `string` | `''` | N/A |
-| `lineNumbers` | `boolean` | `false` | Yes (*line-numbers* attr) |
-| `listNumbers` | `boolean` | `false` | Yes (*list-numbers* attr) |
-| `gutter` | `boolean` | `false` | Yes (*gutter* attr) |
-| `wordWrap` | `boolean` | `false` | Yes (*word-wrap* attr) |
-| `autoGrow` | `boolean` | `false` | Yes (*auto-grow* attr) |
-| `readOnly` | `boolean` | `false` | Yes (*read-only* attr) |
-| `label` | `string \| null` | `null` | No |
-| `selectionStart` | `number` | `0` | No (readonly) |
-| `selectionEnd` | `number` | `0` | No (readonly) |
-
-### Methods
-
-| Method | Signature | Returns |
-|--------|-----------|---------|
-| `usePlugin()` | `(plugin: RCTextareaPlugin) => void` | — |
-| `removePlugin()` | `() => void` | — |
-| `addPattern()` | `(pattern: Omit<TextPattern, 'id'>) => string` | Pattern ID |
-| `removePattern()` | `(id: string) => void` | — |
-| `clearPatterns()` | `() => void` | — |
-
-### Exported Helpers
-
-| Export | Kind | Description |
-| ------ | ---- | ----------- |
-| `matchPatternResults` | function | Run `TextPattern[]` against a string; returns `{ markDecorations, lineDecorations }` |
-| `createLineDecoratorPlugin` | function | Wrap a `LineDecoratorPlugin` in a full `RCTextareaPlugin` |
-| `MarkDecorationStyle` | type | Styling-only subset of `MarkDecoration` (used in `TextPattern.captureGroups`) |
-| `LineDecoratorPlugin` | interface | Per-line decorator with line-relative offsets |
-| `LineDecoratorPluginOptions` | interface | Options for `createLineDecoratorPlugin` |
-
-### Events
-
-| Event | Bubbles | Composed | Detail |
-|-------|---------|----------|--------|
-| `rc-textarea-change` | Yes | Yes | `{ value: string }` |
-| `rc-textarea-focus` | Yes | Yes | — |
-| `rc-textarea-blur` | Yes | Yes | — |
-| `rc-textarea-select` | Yes | Yes | `{ selectionStart: number, selectionEnd: number }` |
-
-### CSS Custom Properties
-
-All custom properties are listed in [CSS Customization](#css-customization).
-
-### CSS Parts
-
-All parts are listed in [CSS Customization](#css-customization).
-
----
-
-## Support & Contributing
-
-For issues, feature requests, or contributions, visit the [rc-webcomponents repository](https://github.com/richardcarls/rc-webcomponents).
-
----
+- [PLUGIN_AUTHORING.md](PLUGIN_AUTHORING.md) covers custom plugins, decoration types,
+  selection APIs, stylesheet injection, and parser/highlighter recipes.
+- [ARCHITECTURE.md](ARCHITECTURE.md) is an internal contributor reference for the rendering
+  loop, Parchment integration, selection mapping, and gutter synchronization.
 
 ## License
 
-[MIT](LICENSE) © Richard Carls
+[MIT](../../LICENSE)