@lyfie/luthor 2.1.0 → 2.3.0

package/README.md

@@ -1,555 +1,320 @@
-# Luthor Presets
+# @lyfie/luthor
 
-**Batteries-included presets and plug-and-play configurations for the Luthor editor**
+Plug-and-play React editor preset package built on top of `@lyfie/luthor-headless`.
 
-This package provides ready-to-use editor presets built on top of [@lyfie/luthor-headless](../headless/README.md). All Lexical dependencies are included - no additional installations required.
+## Package responsibility
 
-[![npm version](https://badge.fury.io/js/%40lyfie%2Fluthor.svg)](https://badge.fury.io/js/%40lyfie%2Fluthor)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
----
-
-## Why Use This Package?
-
-### ✅ Zero Configuration Hassle
-- All Lexical packages bundled as dependencies
-- No peer dependency warnings
-- No version conflicts to resolve
-
-### 🎮 Ready-to-Use Editors
-- Multiple presets for different use cases
-- Pre-built toolbar components
-- Styled and themed out of the box
-
-### 🔧 Still Fully Customizable
-- Extend or modify any preset
-- Access all luthor-headless features
-- Build on top of presets with your own extensions
-
----
+- Owns preset UX/composition and plug-and-play defaults.
+- Reuses headless behavior APIs instead of re-implementing Lexical semantics.
+- Exposes headless namespace for advanced users who need lower-level control.
 
 ## Installation
 
-Install both the headless package and this preset package:
-
 ```bash
-npm install @lyfie/luthor-headless
-npm install @lyfie/luthor
+pnpm add @lyfie/luthor react react-dom
 ```
 
-**That's it!** All required Lexical packages are automatically installed as dependencies of `@lyfie/luthor`.
-
-### What Gets Installed
-
-When you install `@lyfie/luthor`, npm automatically installs:
-- `@lyfie/luthor-headless` (the core editor)
-- `lexical` (the Lexical framework)
-- All `@lexical/*` packages (code, html, link, list, markdown, react, rich-text, selection, table, utils)
-
-These satisfy the peer dependencies of luthor-headless, so you don't need to install anything else.
-
-### Peer Dependencies
-
-Only React remains as a peer dependency (which you already have in your project):
-- `react` (^18.0.0 or ^19.0.0)
-- `react-dom` (^18.0.0 or ^19.0.0)
-
----
-
 ## Quick Start
 
-### Using the Extensive Editor (Recommended)
-
-The fastest way to get a full-featured editor:
-
 ```tsx
 import { ExtensiveEditor } from "@lyfie/luthor";
-import type { ExtensiveEditorRef } from "@lyfie/luthor";
-import { useRef } from "react";
-
-function App() {
-  const editorRef = useRef<ExtensiveEditorRef>(null);
-
-  const handleSave = () => {
-    const html = editorRef.current?.getHTML();
-    const markdown = editorRef.current?.getMarkdown();
-    console.log({ html, markdown });
-  };
-
-  return (
-    <div>
-      <ExtensiveEditor
-        ref={editorRef}
-        placeholder="Start writing..."
-        onReady={(methods) => {
-          console.log("Editor ready!", methods);
-        }}
-      />
-      <button onClick={handleSave}>Save Content</button>
-    </div>
-  );
+import "@lyfie/luthor/styles.css";
+
+export function App() {
+  return <ExtensiveEditor placeholder="Start writing..." />;
 }
 ```
 
-This gives you:
-- ✅ Full-featured toolbar
-- ✅ All formatting options (bold, italic, underline, etc.)
-- ✅ Lists, tables, images, links
-- ✅ Code blocks with syntax highlighting
-- ✅ HTML/Markdown export
-- ✅ Dark mode support
-- ✅ Command palette (Cmd+K / Ctrl+K)
-
-### Using Preset Definitions
+## What This Package Exposes
 
-For more control over the editor setup:
+- Preset editor component: `ExtensiveEditor`
+- Additional preset editors: `SimpleTextEditor`, `RichTextBoxEditor`, `ChatWindowEditor`, `EmailComposeEditor`, `MDTextEditor`, `NotionLikeEditor`, `HeadlessEditorPreset`, `NotesEditor`
+- Preset builder helpers: `extensivePreset`, `createExtensivePreset`, `presetRegistry`
+- Extension composition helpers: `createExtensiveExtensions`, `extensiveExtensions`
+- Feature flag helpers: `resolveFeatureFlags`, `isFeatureEnabled`, `DEFAULT_FEATURE_FLAGS`
+- Core UI + command utilities: `Toolbar`, `FloatingToolbar`, `generateCommands`, `registerKeyboardShortcuts`, and more
+- Full headless passthrough namespace: `headless`
 
 ```tsx
-import { createEditorSystem, RichText } from "@lyfie/luthor-headless";
-import { extensiveExtensions } from "@lyfie/luthor";
-
-const { Provider, useEditor } = createEditorSystem<typeof extensiveExtensions>();
-
-function MyToolbar() {
-  const { commands, activeStates } = useEditor();
-  
-  return (
-    <div className="my-custom-toolbar">
-      <button onClick={() => commands.toggleBold()}>
-        Bold
-      </button>
-      {/* Add your custom UI */}
-    </div>
-  );
-}
+import { headless } from "@lyfie/luthor";
 
-function App() {
-  return (
-    <Provider extensions={extensiveExtensions}>
-      <MyToolbar />
-      <RichText placeholder="Start writing..." />
-    </Provider>
-  );
-}
+const { createEditorSystem, richTextExtension, boldExtension } = headless;
 ```
 
----
-
-## Available Presets
-
-All presets are exported with their configurations and can be used as starting points:
-
-### 1. **Minimal** - `minimalPreset`
-Lightweight editor for short text and basic formatting.
-- Bold, italic, link
-- Perfect for comments or short descriptions
-
-### 2. **Classic** - `classicPreset`
-Traditional rich text editor feel.
-- Standard formatting toolbar
-- Good for general content editing
-
-### 3. **Blog** - `blogPreset`
-Optimized for blog post writing.
-- Headings, images, quotes
-- Clean reading experience
-
-### 4. **CMS** - `cmsPreset`
-Content management system focused.
-- Advanced formatting options
-- Image handling with alignment
-- Tables for structured content
-
-### 5. **Docs** - `docsPreset`
-Documentation and technical writing.
-- Code blocks with syntax highlighting
-- Tables and lists
-- Markdown export
-
-### 6. **Chat** - `chatPreset`
-Lightweight for messaging interfaces.
-- Minimal formatting
-- Emoji and mentions (with custom extensions)
-
-### 7. **Email** - `emailPreset`
-Email composition focused.
-- Safe HTML output
-- Link handling
-- Simple formatting
+## Preset Catalog
+
+- `ExtensiveEditor`: full-feature visual/jsonb preset.
+- `SimpleTextEditor`: plain-text locked preset.
+- `RichTextBoxEditor`: inline formatting + list preset with optional compact toolbar.
+- `ChatWindowEditor`: chat composer with send action row.
+- `EmailComposeEditor`: compose shell (To/CC/BCC/Subject) + rich body.
+- `MDTextEditor`: visual/markdown mode switching.
+- `NotionLikeEditor`: slash-first + draggable defaults.
+- `HeadlessEditorPreset`: minimal plain-control reference.
+- `NotesEditor`: note-taking shell with title/actions callbacks.
+
+## ExtensiveEditor API
+
+### Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `className` | `string` | `undefined` | Appended to wrapper root. |
+| `variantClassName` | `string` | `undefined` | Extra preset variant class on wrapper. |
+| `onReady` | `(methods: ExtensiveEditorRef) => void` | `undefined` | Called when editor methods are ready. |
+| `initialTheme` | `"light" \| "dark"` | `"light"` | Initial visual theme mode. |
+| `theme` | `Partial<LuthorTheme>` | `undefined` | Theme class/style overrides merged with default theme. |
+| `defaultContent` | `string` | `undefined` | If provided, injected as initial content (JSON parsed or plain text converted to JSONB). |
+| `showDefaultContent` | `boolean` | `true` | If `true` and `defaultContent` is not provided, loads built-in welcome content. |
+| `placeholder` | `string \| { visual?: string; jsonb?: string }` | `"Write anything..."` | String applies to visual mode; object lets you set visual and JSONB placeholders separately. |
+| `initialMode` | `"visual" \| "jsonb"` | `"visual"` | Initial open mode; clamped to `availableModes`. |
+| `availableModes` | `readonly ("visual" \| "jsonb")[]` | `["visual", "jsonb"]` | Visible mode tabs and allowed switching targets. |
+| `toolbarLayout` | `ToolbarLayout` | `TRADITIONAL_TOOLBAR_LAYOUT` | Custom toolbar sections/items order. |
+| `toolbarVisibility` | `Partial<Record<ToolbarItemType, boolean>>` | `undefined` | Per-item hide/show map. Unsupported items are auto-hidden. |
+| `toolbarPosition` | `"top" \| "bottom"` | `"top"` | Renders toolbar above or below visual editor. |
+| `toolbarAlignment` | `"left" \| "center" \| "right"` | `"left"` | Horizontal toolbar alignment class. |
+| `toolbarClassName` | `string` | `undefined` | Extra class for toolbar root (`.luthor-toolbar`). |
+| `toolbarStyleVars` | `ToolbarStyleVars` | `undefined` | Inline `--luthor-toolbar-*` CSS variable overrides. |
+| `isToolbarEnabled` | `boolean` | `true` | Hides toolbar UI only; keyboard/commands still exist unless feature-flagged off. |
+| `quoteClassName` | `string` | `undefined` | Appended to quote node class. |
+| `quoteStyleVars` | `QuoteStyleVars` | `undefined` | Inline `--luthor-quote-*` CSS variable overrides. |
+| `defaultSettings` | `DefaultSettings` | `undefined` | High-level style token API for common color settings. |
+| `editorThemeOverrides` | `LuthorEditorThemeOverrides` | `undefined` | Inline editor-wide `--luthor-*` token overrides. |
+| `fontFamilyOptions` | `readonly FontFamilyOption[]` | preset defaults | Sanitized: duplicates removed, invalid tokens removed, `default` auto-added if missing. |
+| `fontSizeOptions` | `readonly FontSizeOption[]` | preset defaults | Sanitized similarly to font family options. |
+| `minimumDefaultLineHeight` | `string \| number` | `1.5` | Sets the editor default line height and the minimum selectable/accepted line-height floor for the line-height feature; minimum accepted value is `1.0`. |
+| `lineHeightOptions` | `readonly LineHeightOption[]` | preset defaults | Uses unitless ratios (`"1.5"`) for non-default values; minimum allowed is `1.0`. |
+| `scaleByRatio` | `boolean` | `false` | Image resize behavior (`true` = keep ratio by default, Shift unlocks). |
+| `headingOptions` | `readonly ("h1"\|"h2"\|"h3"\|"h4"\|"h5"\|"h6")[]` | all headings | Invalid/duplicate entries are removed. |
+| `paragraphLabel` | `string` | `"Paragraph"` behavior | Label for paragraph entry in block format menu/commands. |
+| `syncHeadingOptionsWithCommands` | `boolean` | `true` | Syncs heading command generation with `headingOptions`. |
+| `slashCommandVisibility` | `SlashCommandVisibility` | `undefined` | Slash command filter using allowlist/denylist or enabled-ID selection array form. |
+| `shortcutConfig` | `ShortcutConfig` | `undefined` | Per-instance command shortcut config (disable/remap, collision and native conflict prevention). |
+| `commandPaletteShortcutOnly` | `boolean` | `false` | When `true`, command palette only shows commands that have a visible keyboard shortcut. |
+| `isDraggableBoxEnabled` | `boolean` | `undefined` | Shortcut for enabling/disabling draggable block UI (maps into `featureFlags.draggableBlock`). |
+| `featureFlags` | `Partial<Record<FeatureFlag, boolean>>` | all `true` | Central capability switchboard; affects extensions, toolbar, commands, shortcuts. |
+| `syntaxHighlighting` | `"auto" \| "disabled"` | extension default (`"auto"`) | Code block syntax highlighting strategy. |
+| `codeHighlightProvider` | `CodeHighlightProvider \| null` | `undefined` | Injected highlight provider instance. |
+| `loadCodeHighlightProvider` | `() => Promise<CodeHighlightProvider \| null>` | `undefined` | Lazy async provider loader. |
+| `maxAutoDetectCodeLength` | `number` | `12000` in code intelligence extension | Guard for auto language detection input size. |
+| `isCopyAllowed` | `boolean` | `true` | Enables/disables code block copy button and command path. |
+| `languageOptions` | `readonly string[] \| { mode?: "append"\|"replace"; values: readonly string[] }` | default language catalog | Controls visible code language options. |
+
+### Ref Methods
+
+```ts
+type ExtensiveEditorRef = {
+  injectJSONB: (content: string) => void;
+  getJSONB: () => string;
+};
+```
 
-### 8. **Markdown** - `markdownPreset`
-Markdown-first editing.
-- Markdown shortcuts
-- Preview mode
-- Clean export
+## Valid Argument Sets
 
-### 9. **Code** - `codePreset`
-Code snippet editor.
-- Syntax highlighting
-- Multiple language support
-- Line numbers
+### `ToolbarItemType`
 
-### 10. **Default** - `defaultPreset`
-Balanced general-purpose editor.
-- Good starting point for customization
+`"fontFamily"`, `"fontSize"`, `"lineHeight"`, `"textColor"`, `"textHighlight"`, `"bold"`, `"italic"`, `"underline"`, `"strikethrough"`, `"subscript"`, `"superscript"`, `"code"`, `"link"`, `"blockFormat"`, `"quote"`, `"alignLeft"`, `"alignCenter"`, `"alignRight"`, `"alignJustify"`, `"codeBlock"`, `"unorderedList"`, `"orderedList"`, `"checkList"`, `"indentList"`, `"outdentList"`, `"horizontalRule"`, `"table"`, `"image"`, `"emoji"`, `"embed"`, `"undo"`, `"redo"`, `"commandPalette"`, `"themeToggle"`.
 
-### 11. **Extensive** - `extensivePreset` + `ExtensiveEditor`
-Full-featured editor with everything.
-- All extensions included
-- Complete toolbar
-- Pre-built component
+### `FeatureFlag`
 
----
+`"bold"`, `"italic"`, `"underline"`, `"strikethrough"`, `"fontFamily"`, `"fontSize"`, `"lineHeight"`, `"textColor"`, `"textHighlight"`, `"subscript"`, `"superscript"`, `"link"`, `"horizontalRule"`, `"table"`, `"list"`, `"history"`, `"image"`, `"blockFormat"`, `"code"`, `"codeIntelligence"`, `"codeFormat"`, `"tabIndent"`, `"enterKeyBehavior"`, `"iframeEmbed"`, `"youTubeEmbed"`, `"floatingToolbar"`, `"contextMenu"`, `"commandPalette"`, `"slashCommand"`, `"emoji"`, `"draggableBlock"`, `"customNode"`, `"themeToggle"`.
 
-## Usage Examples
+## Usage Recipes
 
-### Example 1: Using Preset Registry
+### 1) Minimal with defaults
 
 ```tsx
-import { presetRegistry } from "@lyfie/luthor";
-
-// Get a preset by ID
-const blogPreset = presetRegistry.blog;
-const minimalPreset = presetRegistry.minimal;
+import { ExtensiveEditor } from "@lyfie/luthor";
+import "@lyfie/luthor/styles.css";
 
-console.log(blogPreset.label); // "Blog"
-console.log(blogPreset.toolbar); // ["heading", "bold", "italic", ...]
+export function App() {
+  return <ExtensiveEditor />;
+}
 ```
 
-### Example 2: Customizing a Preset
+### 2) Placeholder per mode + restricted modes
 
 ```tsx
-import { defaultPreset } from "@lyfie/luthor";
-import { createEditorSystem } from "@lyfie/luthor-headless";
-
-// Clone and customize
-const myPreset = {
-  ...defaultPreset,
-  id: "my-custom",
-  label: "My Custom Editor",
-  toolbar: ["bold", "italic", "link"], // Override toolbar
-  config: {
-    ...defaultPreset.config,
-    placeholder: "Write your story...",
-  },
-};
+<ExtensiveEditor
+  initialMode="visual"
+  availableModes={["visual", "jsonb"]}
+  placeholder={{
+    visual: "Write release notes...",
+    jsonb: "Paste JSONB...",
+  }}
+/>
 ```
 
-### Example 3: Building with Extensions
+### 3) Feature-gated editor (product tiers)
 
 ```tsx
-import { extensiveExtensions } from "@lyfie/luthor";
-import { createEditorSystem, RichText } from "@lyfie/luthor-headless";
-
-const { Provider, useEditor } = createEditorSystem<typeof extensiveExtensions>();
-
-function Editor() {
-  const { commands } = useEditor();
-  
-  return (
-    <div>
-      <button onClick={() => commands.toggleBold()}>Bold</button>
-      <button onClick={() => commands.insertTable({ rows: 3, cols: 3 })}>
-        Insert Table
-      </button>
-      <RichText />
-    </div>
-  );
-}
-
-function App() {
-  return (
-    <Provider extensions={extensiveExtensions}>
-      <Editor />
-    </Provider>
-  );
-}
+<ExtensiveEditor
+  featureFlags={{
+    image: false,
+    iframeEmbed: false,
+    youTubeEmbed: false,
+    emoji: false,
+    commandPalette: false,
+  }}
+  toolbarVisibility={{
+    embed: false,
+    image: false,
+    emoji: false,
+  }}
+/>
 ```
 
-### Example 4: Export/Import Content
+### 4) Slash command allowlist
 
 ```tsx
-import { ExtensiveEditor } from "@lyfie/luthor";
-import type { ExtensiveEditorRef } from "@lyfie/luthor";
-import { useRef, useState } from "react";
-
-function App() {
-  const editorRef = useRef<ExtensiveEditorRef>(null);
-  const [savedContent, setSavedContent] = useState("");
-
-  const handleExport = () => {
-    const html = editorRef.current?.getHTML();
-    const markdown = editorRef.current?.getMarkdown();
-    setSavedContent(html || "");
-    console.log({ html, markdown });
-  };
-
-  const handleImport = () => {
-    editorRef.current?.injectHTML(savedContent);
-    // or
-    editorRef.current?.injectMarkdown("# Hello\n\nMarkdown content");
-  };
-
-  return (
-    <div>
-      <ExtensiveEditor ref={editorRef} />
-      <button onClick={handleExport}>Export</button>
-      <button onClick={handleImport}>Import</button>
-    </div>
-  );
-}
+<ExtensiveEditor
+  slashCommandVisibility={{
+    allowlist: [
+      "block.paragraph",
+      "block.heading1",
+      "block.heading2",
+      "insert.table",
+    ],
+    denylist: ["insert.image"],
+  }}
+/>
 ```
 
----
-
-## API Reference
-
-### ExtensiveEditor Component
+### 5) Code language list replacement
 
 ```tsx
-import { ExtensiveEditor } from "@lyfie/luthor";
-import type { ExtensiveEditorRef, ExtensiveEditorProps } from "@lyfie/luthor";
+<ExtensiveEditor
+  languageOptions={{
+    mode: "replace",
+    values: ["plaintext", "typescript", "javascript", "markdown", "sql"],
+  }}
+  syntaxHighlighting="auto"
+  maxAutoDetectCodeLength={10000}
+/>
 ```
 
-**Props:**
-```typescript
-interface ExtensiveEditorProps {
-  placeholder?: string;           // Placeholder text
-  className?: string;             // CSS class for container
-  onReady?: (ref: ExtensiveEditorRef) => void;  // Called when editor is ready
-}
-```
+Optional: use highlight.js stylesheet for richer code colors
 
-**Ref Methods:**
-```typescript
-interface ExtensiveEditorRef {
-  injectMarkdown: (content: string) => void;  // Import markdown
-  injectHTML: (content: string) => void;      // Import HTML
-  getMarkdown: () => string;                  // Export as markdown
-  getHTML: () => string;                      // Export as HTML
-}
+```bash
+pnpm add highlight.js
 ```
 
-### Preset Registry
-
 ```tsx
-import { presetRegistry } from "@lyfie/luthor";
-import type { EditorPreset } from "@lyfie/luthor";
-```
+import { ExtensiveEditor } from "@lyfie/luthor";
+import "@lyfie/luthor/styles.css";
+import "highlight.js/styles/github.css"; // any highlight.js theme
 
-**Type:**
-```typescript
-interface EditorPreset {
-  id: string;                           // Unique preset ID
-  label: string;                        // Display name
-  description?: string;                 // Preset description
-  extensions?: Extension[];             // Included extensions
-  config?: EditorConfig;                // Editor configuration
-  theme?: LuthorTheme;                 // Custom theme
-  toolbar?: string[];                   // Toolbar items
-  components?: Record<string, unknown>; // Custom components
-  css?: string;                         // CSS file path
+export function App() {
+  return <ExtensiveEditor syntaxHighlighting="auto" />;
 }
 ```
 
-**Available Presets:**
-- `presetRegistry.minimal`
-- `presetRegistry.classic`
-- `presetRegistry.blog`
-- `presetRegistry.cms`
-- `presetRegistry.docs`
-- `presetRegistry.chat`
-- `presetRegistry.email`
-- `presetRegistry.markdown`
-- `presetRegistry.code`
-- `presetRegistry.default`
-- `presetRegistry.extensive`
-
-### Extension Sets
-
-```tsx
-import { extensiveExtensions } from "@lyfie/luthor";
-```
-
-Pre-configured extension arrays that can be used with luthor-headless:
-
-```typescript
-const extensions = extensiveExtensions as const;
-const { Provider } = createEditorSystem<typeof extensions>();
-```
-
----
-
-## Comparison: Headless vs Luthor
-
-| Feature | @lyfie/luthor-headless | @lyfie/luthor |
-|---------|----------------------|---------------|
-| **Installation** | Manual Lexical deps | Zero additional deps |
-| **Bundle Size** | Minimal | Includes all Lexical |
-| **Setup Time** | More configuration | Instant |
-| **Flexibility** | Maximum control | Pre-configured |
-| **Use Case** | Custom editors | Quick implementation |
-| **UI Components** | Build your own | ExtensiveEditor included |
-| **Presets** | None | 11 ready-to-use |
-| **Dependencies** | Peer deps | Bundled deps |
-
-**Choose luthor-headless when:**
-- Building completely custom UI
-- Need minimal bundle size
-- Want control over Lexical versions
-- Have specific dependency requirements
-
-**Choose @lyfie/luthor when:**
-- Want to start quickly
-- Need a working editor ASAP
-- Don't want to manage dependencies
-- Want ready-to-use components
-
-[📖 Learn more about luthor-headless](../headless/README.md)
-
----
+What happens:
 
-## Advanced Usage
+- Luthor does not auto-detect code language anymore. Language comes from the selected code language option.
+- Language options are normalized through Lexical/Prism aliases (`md` -> `markdown`, `js` -> `javascript` family, `ts` -> `typescript`).
+- Only Prism-supported loaded languages are accepted. Unsupported values (for example `yaml` without Prism YAML grammar loaded) fall back to plain text.
+- `plaintext` uses plain fallback syntax styling.
+- Non-plaintext languages emit `hljs-*` token classes.
+- If a highlight.js stylesheet is loaded, those `hljs-*` tokens use highlight.js colors.
+- Without highlight.js stylesheet, code uses the built-in muted/plain fallback.
 
-### Creating Custom Presets
+### 6) Per-instance shortcut remap/disable
 
 ```tsx
-import type { EditorPreset } from "@lyfie/luthor";
-import { 
-  boldExtension, 
-  italicExtension, 
-  linkExtension 
-} from "@lyfie/luthor-headless";
-
-const myCustomPreset: EditorPreset = {
-  id: "my-custom",
-  label: "My Custom Editor",
-  description: "A tailored editor for my use case",
-  extensions: [boldExtension, italicExtension, linkExtension],
-  config: {
-    placeholder: "Start typing...",
-    editable: true,
-  },
-  toolbar: ["bold", "italic", "link"],
-};
+<ExtensiveEditor
+  shortcutConfig={{
+    disabledCommandIds: ["format.italic"],
+    bindings: {
+      "format.bold": { key: "m", ctrlKey: true },
+      "palette.show": [
+        { key: "k", ctrlKey: true, shiftKey: true },
+      ],
+    },
+  }}
+/>
 ```
 
-### Extending Existing Presets
+### 7) Command palette shortcut-only mode
 
 ```tsx
-import { defaultPreset } from "@lyfie/luthor";
-import { myCustomExtension } from "./my-extension";
-
-const enhancedPreset: EditorPreset = {
-  ...defaultPreset,
-  id: "enhanced-default",
-  extensions: [
-    ...(defaultPreset.extensions || []),
-    myCustomExtension,
-  ],
-  toolbar: [
-    ...(defaultPreset.toolbar || []),
-    "myCustomCommand",
-  ],
-};
+<ExtensiveEditor commandPaletteShortcutOnly />
 ```
 
-### Accessing Luthor-Headless Features
-
-Since `@lyfie/luthor` depends on `@lyfie/luthor-headless`, you have access to all headless features:
+### 8) Style token overrides
 
 ```tsx
-import { createEditorSystem, RichText } from "@lyfie/luthor-headless";
-import { extensiveExtensions } from "@lyfie/luthor";
-
-const { Provider, useEditor } = createEditorSystem<typeof extensiveExtensions>();
-
-// Use all luthor-headless APIs
-function MyEditor() {
-  const { commands, activeStates, lexical } = useEditor();
-  
-  // Access Lexical editor instance
-  lexical?.update(() => {
-    // Direct Lexical operations
-  });
-  
-  return <RichText />;
-}
+<ExtensiveEditor
+  editorThemeOverrides={{
+    "--luthor-bg": "#fffaf2",
+    "--luthor-fg": "#431407",
+    "--luthor-accent": "#c2410c",
+  }}
+  toolbarStyleVars={{
+    "--luthor-toolbar-button-active-bg": "#ea580c",
+    "--luthor-toolbar-button-active-fg": "#ffffff",
+  }}
+  quoteStyleVars={{
+    "--luthor-quote-bg": "#fff7ed",
+    "--luthor-quote-fg": "#7c2d12",
+    "--luthor-quote-border": "#ea580c",
+  }}
+/>
 ```
 
----
-
-## TypeScript Support
+### 9) Emoji library auto-detection (works in `apps/demo`)
 
-Fully typed with TypeScript. All exports include type definitions:
+Install emoji-mart data in the app:
 
-```typescript
-import type {
-  EditorPreset,
-  ExtensiveEditorRef,
-  ExtensiveEditorProps,
-  ExtensiveEditorMode,
-} from "@lyfie/luthor";
+```bash
+pnpm add -F demo @emoji-mart/data
 ```
 
----
-
-## Styling
-
-The `ExtensiveEditor` component includes default styles. To customize:
+Then use `ExtensiveEditor` normally:
 
 ```tsx
 import { ExtensiveEditor } from "@lyfie/luthor";
+import "@lyfie/luthor/styles.css";
 
-// Add custom class
-<ExtensiveEditor className="my-editor" />
-```
-
-```css
-/* Override default styles */
-.my-editor {
-  --luthor-bg: #ffffff;
-  --luthor-text: #000000;
-  --luthor-border: #e5e5e5;
-}
-
-/* Dark mode */
-.my-editor.dark {
-  --luthor-bg: #1a1a1a;
-  --luthor-text: #ffffff;
-  --luthor-border: #333333;
+export function App() {
+  return <ExtensiveEditor />;
 }
 ```
 
----
-
-## Migration from Headless
+What happens:
 
-If you're using luthor-headless and want to switch:
-
-**Before:**
-```bash
-npm install @lyfie/luthor-headless
-npm install lexical @lexical/react @lexical/html # ... many packages
-```
+- `:shortcode` suggestions and resolution use the detected emoji-mart dataset.
+- Emoji toolbar dropdown uses the detected emoji-mart catalog.
+- If the library is not installed/available, it automatically falls back to the built-in emoji list.
 
-**After:**
-```bash
-npm install @lyfie/luthor-headless
-npm install @lyfie/luthor
-# Remove individual @lexical/* packages if desired
-```
+## Notes and Nuances
 
-Your code doesn't need to change! All luthor-headless APIs work the same way.
+- `featureFlags` are authoritative. If a feature is disabled, related toolbar items and commands are removed/no-op even if you attempt to show them.
+- `slashCommandVisibility` keeps original command ordering; it only filters visibility.
+- `shortcutConfig.disabledCommandIds` removes commands from keyboard handling and command UIs for that editor instance.
+- `shortcutConfig` drops duplicate bindings by default and blocks native editable conflicts by default.
+- `commandPaletteShortcutOnly` is optional; by default command palette can include command items without shortcuts.
+- `languageOptions` normalizes aliases (for example `js` becomes `javascript`) and rejects duplicates after normalization.
+- Emoji suggestions/tooling auto-detect external emoji-mart data when available, and otherwise use the built-in default emoji catalog.
+- `defaultSettings` is style-only; behavior is controlled by explicit props (for example `featureFlags`, `availableModes`).
+- `isToolbarEnabled={false}` hides toolbar UI, but editor shortcuts/features still work unless disabled via `featureFlags`.
 
----
+## Which Package Should I Use?
 
-## Examples
+- Use `@lyfie/luthor` for fast onboarding and polished defaults.
+- Use `@lyfie/luthor-headless` for full extension/UI control.
 
-Check out the [demo site](https://luthor.lyfie.app/demo) for live examples of all presets.
+## Documentation
 
----
+- Monorepo docs index: [../../documentation/index.md](../../documentation/index.md)
+- Headless package README: [../headless/README.md](../headless/README.md)
+- User docs: [../../documentation/user/luthor/getting-started.md](../../documentation/user/luthor/getting-started.md)
+- Developer docs: [../../documentation/developer/luthor/architecture.md](../../documentation/developer/luthor/architecture.md)
 
-**Built with ❤️ by the Luthor Team**
+## Workspace Development
 
-MIT License - Use it however you want.
+```bash
+pnpm --filter @lyfie/luthor dev
+pnpm --filter @lyfie/luthor build
+pnpm --filter @lyfie/luthor lint
+```