@lyfie/luthor-headless 2.2.0 → 2.3.0

package/README.md

@@ -1,255 +1,671 @@
-# Luthor-Headless
+# @lyfie/luthor-headless
 
-**Type-safe rich text editor for React developers**
+Type-safe, headless rich text editor system for React, built on Lexical.
 
-Built on Meta's Lexical. Headless, extensible, and production-ready.
+## Package responsibility
 
-[![npm version](https://badge.fury.io/js/%40luthor%2Feditor.svg)](https://badge.fury.io/js/%40luthor%2Feditor)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+- Owns Lexical-derived behavior and extension runtime semantics.
+- Designed to stay lightweight with optional integrations that degrade gracefully.
+- Preset UX belongs in `@lyfie/luthor`.
 
-**[🚀 Demo](https://luthor.lyfie.app/demo)** • **[📖 Documentation](https://luthor.lyfie.app/docs)** • **[⚡ Playground](https://stackblitz.com/edit/vitejs-vite-bpg2kpze?file=src%2FEditor.tsx)**
-
-![Luthor Editor](https://github.com/user-attachments/assets/ec547406-0ab0-4e69-b9d7-ccd050adf78a)
-
----
-
-## Why Luthor?
-
-Rich text editors shouldn't be a nightmare. Luthor makes building them delightful:
-
-- **🔒 Type-safe everything** - Commands and states inferred from your extensions. No runtime surprises.
-- **🎨 Headless & flexible** - Build any UI you want. Style it your way.
-- **🧩 Modular extensions** - Add only what you need, when you need it.
-- **⚡ Production features** - HTML/Markdown export, image handling, tables, undo/redo.
-- **⚛️ React-first** - Hooks, components, and patterns you already know.
-
-```tsx
-// Your extensions define your API - TypeScript knows everything ✨
-const extensions = [boldExtension, listExtension, imageExtension] as const;
-const { Provider, useEditor } = createEditorSystem<typeof extensions>();
-
-function MyEditor() {
-  const { commands, activeStates } = useEditor();
-
-  // TypeScript autocompletes and validates these
-  commands.toggleBold();        // ✅ Available
-  commands.toggleUnorderedList(); // ✅ Available
-  commands.insertImage();       // ✅ Available
-  commands.nonExistent();       // ❌ TypeScript error
-}
-```
-
-## Quick Start
-
-### Installation
-
-Luthor-Headless is designed to be lightweight with Lexical packages as **peer dependencies**.
+## Installation
 
 ```bash
-# npm
-npm install @lyfie/luthor-headless
-
-# pnpm
-pnpm add @lyfie/luthor-headless
+pnpm add @lyfie/luthor-headless lexical @lexical/code @lexical/html @lexical/link @lexical/list @lexical/markdown @lexical/react @lexical/rich-text @lexical/selection @lexical/table @lexical/utils react react-dom
 ```
 
-Install the required Lexical peer dependencies:
+Optional syntax highlighting provider:
 
 ```bash
-# npm
-npm install lexical @lexical/react @lexical/html @lexical/markdown @lexical/list @lexical/rich-text @lexical/selection @lexical/utils @lexical/code @lexical/link @lexical/table
-
-# pnpm
-pnpm add lexical @lexical/react @lexical/html @lexical/markdown @lexical/list @lexical/rich-text @lexical/selection @lexical/utils @lexical/code @lexical/link @lexical/table
+pnpm add highlight.js
 ```
 
-> **💡 Want a simpler setup?** Check out [@lyfie/luthor](../luthor/README.md) which bundles all Lexical dependencies for you.
-
-### Basic Usage
+Optional emoji catalog provider:
 
 ```bash
-# npm
-npm install @lyfie/luthor-headless
-
-# pnpm
-pnpm add @lyfie/luthor-headless
+pnpm add @emoji-mart/data
 ```
 
-Install the Lexical peer dependencies:
+Optional package behavior:
 
-```bash
-# npm
-npm install lexical @lexical/react @lexical/html @lexical/markdown @lexical/list @lexical/rich-text @lexical/selection @lexical/utils @lexical/code @lexical/link @lexical/table
+- Without `highlight.js`, code blocks use built-in fallback token styling.
+- Without `@emoji-mart/data`, emoji features use the built-in lightweight catalog.
+- Both optional packages are fail-safe and do not block editor startup.
 
-# pnpm
-pnpm add lexical @lexical/react @lexical/html @lexical/markdown @lexical/list @lexical/rich-text @lexical/selection @lexical/utils @lexical/code @lexical/link @lexical/table
-```
+## Quick Start
 
 ```tsx
 import {
   createEditorSystem,
+  RichText,
+  richTextExtension,
   boldExtension,
   italicExtension,
-  listExtension,
-  RichText,
 } from "@lyfie/luthor-headless";
 
-const extensions = [boldExtension, italicExtension, listExtension] as const;
+const extensions = [richTextExtension, boldExtension, italicExtension] as const;
 const { Provider, useEditor } = createEditorSystem<typeof extensions>();
 
 function Toolbar() {
   const { commands, activeStates } = useEditor();
+
   return (
-    <div className="toolbar">
-      <button
-        onClick={() => commands.toggleBold()}
-        className={activeStates.bold ? "active" : ""}
-      >
+    <div>
+      <button onClick={() => commands.toggleBold()} aria-pressed={activeStates.bold}>
         Bold
       </button>
-      <button
-        onClick={() => commands.toggleItalic()}
-        className={activeStates.italic ? "active" : ""}
-      >
+      <button onClick={() => commands.toggleItalic()} aria-pressed={activeStates.italic}>
         Italic
       </button>
-      <button onClick={() => commands.toggleUnorderedList()}>
-        Bullet List
-      </button>
-    </div>
-  );
-}
-
-function Editor() {
-  return (
-    <div className="editor-container">
-      <Toolbar />
-      <RichText placeholder="Start writing..." />
     </div>
   );
 }
 
-export default function App() {
+export function Editor() {
   return (
     <Provider extensions={extensions}>
-      <Editor />
+      <Toolbar />
+      <RichText placeholder="Write here..." />
     </Provider>
   );
 }
 ```
 
-**That's it.** You now have a fully functional, type-safe rich text editor.
+## Core API
 
-## Installation Options
+### `createEditorSystem<Exts>()`
 
-### Option 1: Headless Package (This Package)
+Returns:
 
-For maximum control and flexibility:
+- `Provider(props)`
+- `useEditor()`
 
-```bash
-# npm
-npm install @lyfie/luthor-headless
-npm install lexical @lexical/react @lexical/html @lexical/markdown @lexical/list @lexical/rich-text @lexical/selection @lexical/utils @lexical/code @lexical/link @lexical/table
+`Provider` props:
+
+- `extensions: Exts` (required)
+- `children: ReactNode` (required)
+- `config?: EditorConfig`
+
+`EditorConfig`:
+
+- `theme?: EditorThemeClasses`
+- any additional keys are allowed and can be consumed by extensions/components
+
+### `useEditor()` context
+
+Returns strongly typed surface based on `extensions`:
+
+- `commands`
+- `activeStates`
+- `stateQueries`
+- `hasExtension(name)`
+- `export.toJSON()`
+- `import.fromJSON(json)`
+- `lexical` / `editor`
+- `plugins`
+- listener helpers (`registerUpdate`, `registerPaste`)
+
+## RichText Component API
+
+`RichText` and `RichTextExtension` use the same prop shape:
+
+- `contentEditable?: ReactElement`
+- `placeholder?: ReactElement | string`
+- `className?: string`
+- `classNames?: { container?: string; contentEditable?: string; placeholder?: string }`
+- `styles?: { container?: CSSProperties; contentEditable?: CSSProperties; placeholder?: CSSProperties }`
+- `errorBoundary?: ComponentType<{ children: JSX.Element; onError: (error: Error) => void }>`
+
+## Theme Utilities
+
+- `defaultLuthorTheme`
+- `mergeThemes(baseTheme, overrideTheme)`
+- `isLuthorTheme(value)`
+- `LUTHOR_EDITOR_THEME_TOKENS`
+- `createEditorThemeStyleVars(overrides)`
+
+`LuthorEditorThemeOverrides` is a token map with keys from `LUTHOR_EDITOR_THEME_TOKENS` and string values.
+
+## Markdown Bridge API
+
+Headless now exposes lightweight markdown bridge helpers:
+
+- `markdownToJSONB(markdown: string): JsonbDocument`
+- `jsonbToMarkdown(input: unknown): string`
+
+These are intended as conversion primitives for preset mode-switch UIs (for example `MDTextEditor` in `@lyfie/luthor`).
+
+## Base Extension Config
+
+All extension configs support `BaseExtensionConfig`:
+
+- `showInToolbar?: boolean`
+- `category?: ExtensionCategory[]`
+- `position?: "before" | "after"`
+- `initPriority?: number`
+
+## Built-in Extensions
+
+### Text Formatting
+
+- `boldExtension`
+- `italicExtension`
+- `underlineExtension`
+- `strikethroughExtension`
+- `subscriptExtension`
+- `superscriptExtension`
+- `codeFormatExtension` (inline code mark)
+
+These are toggle-style text-format extensions and do not require custom config.
+
+### Link Extension (`LinkExtension`, `linkExtension`)
+
+`LinkConfig`:
+
+- `autoLinkText?: boolean`
+- `autoLinkUrls?: boolean`
+- `linkSelectedTextOnPaste?: boolean`
+- `validateUrl?: (url: string) => boolean`
+- `clickableLinks?: boolean`
+- `openLinksInNewTab?: boolean`
+
+Commands:
+
+- `insertLink(url?, text?)`
+- `updateLink(url, rel?, target?)`
+- `removeLink()`
+- `getCurrentLink()`
+- `getLinkByKey(linkNodeKey)`
+- `updateLinkByKey(linkNodeKey, url, rel?, target?)`
+- `removeLinkByKey(linkNodeKey)`
+
+Note: set `autoLinkUrls` explicitly in your config for unambiguous paste-link behavior.
+
+### Typography Selectors
+
+#### `FontFamilyExtension`
+
+`FontFamilyOption`:
+
+- `value: string`
+- `label: string`
+- `fontFamily: string`
+- `cssImportUrl?: string`
+
+`FontFamilyConfig`:
+
+- `options: readonly FontFamilyOption[]`
+- `cssLoadStrategy: "none" | "preload-all" | "on-demand"`
+
+Nuances:
+
+- Invalid/duplicate option values are sanitized out.
+- `default` option is auto-inserted when omitted.
+
+#### `FontSizeExtension`
+
+`FontSizeOption`:
+
+- `value: string`
+- `label: string`
+- `fontSize: string`
+
+`FontSizeConfig`:
+
+- `options: readonly FontSizeOption[]`
+
+Nuances:
+
+- Invalid/duplicate option values are sanitized out.
+- `default` option is auto-inserted when omitted.
+
+#### `LineHeightExtension`
+
+`LineHeightOption`:
+
+- `value: string`
+- `label: string`
+- `lineHeight: string`
+
+`LineHeightConfig`:
+
+- `options: readonly LineHeightOption[]`
+- `defaultLineHeight?: string` (default `"1.5"`)
+
+Nuances:
+
+- `value: "default"` maps to `defaultLineHeight` (or `"1.5"` when not configured).
+- Non-default entries should use numeric ratios `>= 1.0` (`"1"`, `"1.5"`, `"2"`).
+- Line height is applied at block level (TinyMCE-style): selecting text inside a block updates that whole block.
+
+#### `TextColorExtension`
+
+`TextColorOption`:
+
+- `value: string`
+- `label: string`
+- `color: string`
+
+`TextColorConfig`:
+
+- `options: readonly TextColorOption[]`
+
+Nuances:
+
+- `setTextColor` accepts configured option values and valid CSS colors.
+
+#### `TextHighlightExtension`
+
+`TextHighlightOption`:
+
+- `value: string`
+- `label: string`
+- `backgroundColor: string`
 
-# pnpm
-pnpm add @lyfie/luthor-headless
-pnpm add lexical @lexical/react @lexical/html @lexical/markdown @lexical/list @lexical/rich-text @lexical/selection @lexical/utils @lexical/code @lexical/link @lexical/table
+`TextHighlightConfig`:
+
+- `options: readonly TextHighlightOption[]`
+
+Nuances:
+
+- `setTextHighlight` accepts configured option values and valid CSS colors.
+- Highlight styling also patches padding/box-decoration style helpers for clean rendering.
+
+### Block/Structure Extensions
+
+#### `blockFormatExtension`
+
+Commands include paragraph/heading/quote toggles and alignment helpers. No custom config required.
+
+#### `listExtension`
+
+Commands include unordered/ordered/check list toggles and indentation commands. No custom config required.
+
+#### `horizontalRuleExtension`
+
+Commands include horizontal rule insertion. No custom config required.
+
+### Code Extensions
+
+#### `CodeExtension`
+
+`CodeExtensionConfig`:
+
+- `syntaxHighlighting?: "auto" | "disabled"`
+- `tokenizer?: CodeTokenizer | null`
+- `provider?: CodeHighlightProvider | null`
+- `loadProvider?: () => Promise<CodeHighlightProvider | null>`
+
+Usage (manual language selection + plaintext fallback):
+
+```tsx
+import {
+  codeExtension,
+  codeIntelligenceExtension,
+} from "@lyfie/luthor-headless";
+
+const extensions = [
+  codeExtension.configure({
+    syntaxHighlighting: "auto", // default
+  }),
+  codeIntelligenceExtension,
+] as const;
 ```
 
-**Use this when:**
-- You want complete control over Lexical versions
-- Building a custom editor UI from scratch
-- Need minimum bundle size
-- Want to manage dependencies yourself
+- `CodeIntelligenceExtension` no longer auto-detects code languages.
+- Selecting `plaintext` keeps code tokens in the plaintext fallback theme (`plain`).
+- Selecting any non-plaintext language switches token classes to the `hljs-*` namespace.
+- Language values are alias-normalized (`md` -> `markdown`, `ts` -> `typescript`, `js` -> `javascript` family).
+- Only Prism-supported loaded languages are accepted. Unsupported values are treated as plaintext.
+- If your app loads a highlight.js stylesheet, those `hljs-*` token colors are applied automatically.
+- Without a highlight.js stylesheet, code remains muted/plain fallback.
 
-### Option 2: Full Package (Recommended for Quick Start)
+`CodeHighlightProvider` shape:
 
-For a batteries-included experience:
+- `highlightAuto?(code, languageSubset?)`
+- `tokenizer?: CodeTokenizer | null`
+- `getTokenizer?: () => CodeTokenizer | null | Promise<CodeTokenizer | null>`
 
-```bash
-# npm
-npm install @lyfie/luthor-headless @lyfie/luthor
+#### `CodeIntelligenceExtension`
+
+`CodeLanguageOptionsConfig`:
+
+- `mode?: "append" | "replace"`
+- `values: readonly string[]`
+
+`CodeIntelligenceConfig`:
+
+- `provider?: CodeHighlightProvider | null`
+- `loadProvider?: () => Promise<CodeHighlightProvider | null>`
+- `maxAutoDetectLength?: number` (default `12000`)
+- `isCopyAllowed?: boolean` (default `true`)
+- `languageOptions?: readonly string[] | CodeLanguageOptionsConfig`
+
+Commands:
+
+- `setCodeLanguage(language)`
+- `autoDetectCodeLanguage()`
+- `getCurrentCodeLanguage()`
+- `getCodeLanguageOptions()`
+- `copySelectedCodeBlock()`
+
+Nuances:
+
+- Array form for `languageOptions` is equivalent to `{ mode: "append", values }`.
+- Aliases are normalized.
+- Duplicate normalized languages throw.
+
+### History and Input Behavior
+
+- `historyExtension`: undo/redo commands and canUndo/canRedo state.
+- `tabIndentExtension`: tab/shift-tab indent behavior.
+- `enterKeyBehaviorExtension`: enter behavior normalization (quotes/code/table transitions). No extra config.
+
+### Table Extension (`TableExtension`, `tableExtension`)
+
+`TableConfig`:
+
+- `rows?: number`
+- `columns?: number`
+- `includeHeaders?: boolean`
+- `enableContextMenu?: boolean`
+- `contextMenuItems?: ContextMenuItem[] | ((commands: TableCommands) => ContextMenuItem[])`
+- `contextMenuRenderer?: ContextMenuRenderer`
+- `contextMenuExtension?: typeof contextMenuExtension`
+- `tableBubbleRenderer?: (props: TableBubbleRenderProps) => ReactNode`
+
+`TableBubbleRenderProps`:
+
+- `headersEnabled: boolean`
+- `setHeadersEnabled(enabled)`
+- `actions`: row/column insert/delete + delete table actions
+
+Defaults:
+
+- `rows: 3`
+- `columns: 3`
+- `includeHeaders: false`
+- `enableContextMenu: true`
+
+### Media Extensions
+
+#### Image (`ImageExtension`, `imageExtension`)
+
+`ImageExtensionConfig`:
+
+- `uploadHandler?: (file: File) => Promise<string>`
+- `defaultAlignment?: "left" | "right" | "center" | "none"`
+- `classNames?: Partial<Record<Alignment | "wrapper" | "caption", string>>`
+- `styles?: Partial<Record<Alignment | "wrapper" | "caption", CSSProperties>>`
+- `customRenderer?: ComponentType<ImageComponentProps>`
+- `resizable?: boolean` (default `true`)
+- `scaleByRatio?: boolean` (default `false`)
+- `pasteListener?: { insert: boolean; replace: boolean }` (default both `true`)
+- `debug?: boolean` (default `false`)
+- `forceUpload?: boolean` (default `false`)
+
+#### Iframe (`IframeEmbedExtension`, `iframeEmbedExtension`)
+
+`IframeEmbedConfig`:
+
+- `defaultWidth?: number` (default `640`)
+- `defaultHeight?: number` (default `360`)
+- `defaultAlignment?: "left" | "center" | "right"` (default `"center"`)
+
+#### YouTube (`YouTubeEmbedExtension`, `youTubeEmbedExtension`)
+
+`YouTubeEmbedConfig`:
+
+- `defaultWidth?: number` (default `640`)
+- `defaultHeight?: number` (default `480`)
+- `defaultAlignment?: "left" | "center" | "right"` (default `"center"`)
+- `allowFullscreen?: boolean` (default `true`)
+- `autoplay?: boolean` (default `false`)
+- `controls?: boolean` (default `true`)
+- `nocookie?: boolean` (default `true`)
+- `rel?: number` (default `1`)
+
+### Command UI Extensions
 
-# pnpm
-pnpm add @lyfie/luthor-headless @lyfie/luthor
+#### Slash Command (`SlashCommandExtension`, `slashCommandExtension`)
 
-# That's it! All Lexical dependencies included
+`SlashCommandItem`:
+
+- `id`, `label`, `action`
+- optional: `description`, `keywords`, `category`, `icon`, `shortcut`
+
+`SlashCommandConfig`:
+
+- `trigger?: string` (default `"/"`)
+- `offset?: { x: number; y: number }` (default `{ x: 0, y: 8 }`)
+- `items?: readonly SlashCommandItem[]`
+
+Commands:
+
+- `registerSlashCommand(item)`
+- `unregisterSlashCommand(id)`
+- `setSlashCommands(items)`
+- `closeSlashMenu()`
+- `executeSlashCommand(id)`
+
+#### Command Palette (`CommandPaletteExtension`, `commandPaletteExtension`)
+
+`CommandPaletteItem`:
+
+- `id`, `label`, `action`
+- optional: `description`, `keywords`, `category`, `icon`, `shortcut`
+
+Commands:
+
+- `showCommandPalette()`
+- `hideCommandPalette()`
+- `registerCommand(item)`
+- `unregisterCommand(id)`
+
+#### Emoji (`EmojiExtension`, `emojiExtension`)
+
+`EmojiCatalogItem`:
+
+- `emoji`, `label`, `shortcodes`
+- optional `keywords`
+
+`EmojiConfig`:
+
+- `trigger?: string` (default `":"`)
+- `maxSuggestions?: number` (default `8`)
+- `maxQueryLength?: number` (default `32`)
+- `autoReplaceSymbols?: boolean` (default `true`)
+- `symbolReplacements?: Record<string, string>`
+- `catalog?: EmojiCatalogItem[]`
+- `catalogAdapter?: { search(query, options?), resolveShortcode(shortcode), getAll() }`
+- `autoDetectExternalCatalog?: boolean` (default `true`, auto-detects emoji-mart data if available)
+- `offset?: { x: number; y: number }` (default `{ x: 0, y: 8 }`)
+
+Commands:
+
+- `insertEmoji(emoji)`
+- `executeEmojiSuggestion(emoji)`
+- `closeEmojiSuggestions()`
+- `getEmojiSuggestions(query?)`
+- `getEmojiCatalog()`
+- `resolveEmojiShortcode(shortcode)`
+- `setEmojiCatalog(catalog)`
+- `setEmojiCatalogAdapter(adapter)`
+- `getEmojiCatalogAdapter()`
+
+Behavior:
+
+- If no custom catalog/adapter is provided, emoji will auto-detect emoji-mart data when available.
+- If nothing is detected, it falls back to the built-in lightweight catalog.
+
+Usage (including `apps/demo`):
+
+```bash
+pnpm add -F demo @emoji-mart/data
 ```
 
-**Use this when:**
-- You want ready-to-use editor presets
-- Don't want to manage Lexical dependencies
-- Need a working editor quickly
-- Want plug-and-play components
+- No editor config changes are required.
+- After install, typing `:shortcode` and opening the emoji toolbar picker will use the detected emoji-mart catalog.
+- If `@emoji-mart/data` is not installed (or not available globally), behavior stays on the built-in fallback catalog.
+
+### Context/Overlay Extensions
+
+#### Context Menu (`ContextMenuExtension`, `contextMenuExtension`)
 
-[📖 See @lyfie/luthor documentation](../luthor/README.md)
+`ContextMenuConfig`:
 
-## Features
+- `defaultRenderer?: ContextMenuRenderer`
+- `preventDefault?: boolean`
+- `theme?: { container?: string; item?: string; itemDisabled?: string }`
+- `styles?: { container?: CSSProperties; item?: CSSProperties; itemDisabled?: CSSProperties }`
 
-### 🎨 Built-in Extensions (25+)
-- **Text Formatting**: Bold, italic, underline, strikethrough, inline code
-- **Structure**: Headings, lists (with nesting), quotes, horizontal rules
-- **Rich Content**: Tables, images (upload/paste/alignment), links, code blocks
-- **Advanced**: History (undo/redo), command palette, floating toolbar, context menus
+Commands:
 
-### 🎯 Smart List Handling
-- Toggle lists with intelligent nesting behavior
-- Context-aware toolbar (indent/outdent appear when needed)
-- Nested lists without keyboard shortcuts
-- Clean UX that matches modern editors
+- `registerProvider(provider)`
+- `unregisterProvider(id)`
+- `showContextMenu({ items, position, renderer? })`
+- `hideContextMenu()`
 
-### 📤 Export & Import
-- **HTML** with semantic markup
-- **Markdown** with GitHub Flavored syntax
-- **JSON** for structured data
-- Custom transformers for specialized formats
+`ContextMenuProvider`:
 
-### 🎨 Theming & Styling
-- CSS classes or Tailwind utilities
-- Custom themes for consistent styling
-- Dark mode support
-- Accessible by default
+- `id`
+- `priority?`
+- `canHandle(context)`
+- `getItems(context)`
+- `renderer?`
 
-## Real World Usage
+#### Floating Toolbar (`FloatingToolbarExtension`, `floatingToolbarExtension`)
 
-Luthor powers editors in:
-- Content management systems
-- Documentation platforms
-- Blog editors
-- Note-taking applications
-- Comment systems
-- Collaborative writing tools
+`FloatingConfig<TCommands, TStates>`:
 
-## Community & Support
+- `render(props)`
+- `getCommands?(): TCommands`
+- `getActiveStates?(): TStates`
+- `anchorElem?: HTMLElement`
+- `debounceMs?: number` (default `100`)
+- `offset?: { x: number; y: number }` (default `{ x: 0, y: 8 }`)
+- `positionStrategy?: "above" | "below" | "auto"` (default `"below"`)
+- `theme?: { container?: string; button?: string; buttonActive?: string }`
+- `toolbarDimensions?: { width: number; height: number }`
 
-- **[💬 Discord](https://discord.gg/RAMYSDRag7)** - Get help, share ideas
-- **[🐛 GitHub Issues](https://github.com/lyfie-app/luthor/issues)** - Bug reports, feature requests
-- **[💭 Discussions](https://github.com/lyfie-app/luthor/discussions)** - Questions, showcase your projects
+#### Draggable Blocks (`DraggableBlockExtension`, `draggableBlockExtension`)
 
-## Contributing
+`DraggableConfig`:
 
-We welcome contributions! Whether you:
-- Find and report bugs
-- Suggest new features
-- Contribute code or documentation
-- Share projects built with Luthor
-- Star the repo to show support
+- `anchorElem?: HTMLElement`
+- `showAddButton?: boolean`
+- `buttonStackPosition?: "left" | "right"`
+- `enableTextSelectionDrag?: boolean`
+- `offsetLeft?: number`
+- `offsetRight?: number`
+- `theme?: { handle?, handleActive?, blockDragging?, dropIndicator?, addButton?, buttonStack? }`
+- `styles?: { handle?, handleActive?, blockDragging?, dropIndicator?, addButton?, buttonStack? }`
+- `handleRenderer?(props)`
+- `buttonsRenderer?(props)`
+- `dropIndicatorRenderer?(props)`
 
-Check our [Contributing Guide](./CONTRIBUTING.md) to get started.
+Default behavior includes draggable handle, add button, and left-side controls.
 
-## Support This Project
+### Custom Nodes
 
-Luthor is free and open source, built by developers for developers. If it's helping you build better editors, consider supporting its development:
+`createCustomNodeExtension(config)` lets you define a full custom node extension.
 
-- **⭐ Star this repository** to show your support
-- **💝 [Sponsor the project](https://github.com/sponsors/rahulnsanand)** to help with maintenance and new features
-- **📢 Share Luthor** with other developers
+`CustomNodeConfig` includes:
 
-Your support keeps this project alive and helps us build better tools for the React community.
+- `nodeType: string`
+- `isContainer?: boolean`
+- `defaultPayload?: Record<string, any>`
+- `initialChildren?: () => SerializedLexicalNode[]`
+- `render?` or `jsx?`
+- DOM import/export hooks (`createDOM`, `updateDOM`, `importDOM`, `exportDOM`)
+- `commands?(editor)`
+- `stateQueries?(editor)`
 
----
+Returns:
 
-**Built with ❤️ by [Rahul NS Anand](https://github.com/rahulnsanand)**
+- `extension`
+- `$createCustomNode(payload?)`
+- `jsxToDOM(jsxElement)`
 
-MIT License - Use it however you want.</content>
+## Complete Extension Example
 
+```tsx
+import {
+  createEditorSystem,
+  RichText,
+  richTextExtension,
+  historyExtension,
+  boldExtension,
+  italicExtension,
+  linkExtension,
+  listExtension,
+  blockFormatExtension,
+  tableExtension,
+  imageExtension,
+  slashCommandExtension,
+  commandPaletteExtension,
+  codeExtension,
+  codeIntelligenceExtension,
+} from "@lyfie/luthor-headless";
+
+const extensions = [
+  richTextExtension,
+  historyExtension,
+  boldExtension,
+  italicExtension,
+  linkExtension.configure({
+    autoLinkText: true,
+    autoLinkUrls: true,
+    linkSelectedTextOnPaste: true,
+  }),
+  listExtension,
+  blockFormatExtension,
+  tableExtension.configure({
+    rows: 3,
+    columns: 4,
+    includeHeaders: true,
+  }),
+  imageExtension.configure({
+    resizable: true,
+    scaleByRatio: true,
+  }),
+  codeExtension.configure({
+    syntaxHighlighting: "auto",
+  }),
+  codeIntelligenceExtension.configure({
+    maxAutoDetectLength: 12000,
+    isCopyAllowed: true,
+    languageOptions: {
+      mode: "append",
+      values: ["sql", "yaml"],
+    },
+  }),
+  slashCommandExtension,
+  commandPaletteExtension,
+] as const;
+
+const { Provider } = createEditorSystem<typeof extensions>();
+
+export function Editor() {
+  return (
+    <Provider extensions={extensions}>
+      <RichText placeholder="Write here..." />
+    </Provider>
+  );
+}
+```
+
+## Documentation
+
+- Monorepo docs index: [../../documentation/index.md](../../documentation/index.md)
+- User docs: [../../documentation/user/headless/getting-started.md](../../documentation/user/headless/getting-started.md)
+- Developer docs: [../../documentation/developer/headless/architecture.md](../../documentation/developer/headless/architecture.md)
+- Luthor preset package README: [../luthor/README.md](../luthor/README.md)
+
+## Workspace Development
+
+```bash
+pnpm --filter @lyfie/luthor-headless dev
+pnpm --filter @lyfie/luthor-headless build
+pnpm --filter @lyfie/luthor-headless lint
+```