@0m0g1/griot 0.1.3 → 0.1.4

package/README.md

@@ -1,179 +1,374 @@
 # Griot
 
-A self-contained block-based rich text editor and renderer.  
-Built for structured historical document authoring — works standalone or embedded inside a larger app.
+A lightweight, extensible block editor and viewer for the web. Inspired by Notion, but built with plain JavaScript and zero dependencies. Griot provides a rich editing experience with:
+
+- **Block-based editing** – paragraphs, headings, lists, callouts, code blocks, images, video, audio, tables, dividers, timeline references, book citations, and more.
+- **Inline formatting** – bold, italic, underline, strikethrough, inline code, highlights, colored text, links, images, and custom event/cite chips.
+- **Slash commands** – type `/` to insert any block.
+- **Floating format toolbar** – appears when you select text.
+- **Undo/redo** – with a built‑in history stack.
+- **Read‑only viewer** – render the same document without editing controls.
+- **Immutable document operations** – every change produces a new document object.
+- **Schema‑driven** – all block types are defined in a single schema; easy to extend.
 
 ---
 
-## Install
+## Installation
 
 ```bash
-# Copy src/ into your project, or:
-npm install griot   # (once published)
+npm install griot
 ```
 
-```js
-import '@0m0g1/griot/css';                         // styles
-import { Editor, Viewer, createDocument } from 'griot';
+Or include it directly via ES module:
+
+```html
+<script type="module">
+  import { Editor, Viewer } from './path/to/griot.js';
+  // ...
+</script>
 ```
 
 ---
 
-## Quick start
+## Quick Start
 
 ### Editor
 
-```js
-import { Editor, createDocument } from 'griot';
-import '@0m0g1/griot/css';
-
-const doc = createDocument('My Article');
-
-const editor = new Editor(document.querySelector('#editor'), {
-  doc,
-  books: [],                         // optional: parsed books for citations
-  onChange(updatedDoc) {
-    localStorage.setItem('draft', JSON.stringify(updatedDoc));
-  },
-  onEventClick(eventId) {
-    // e.g. AppShell.handleSelectItemById(eventId)
-    console.log('Open timeline event:', eventId);
-  },
-  onCiteClick(blockId) {
-    // scroll viewer to that block
-    viewer.setHighlight(blockId);
-  },
-  onRequestBookPicker(blockId, callback) {
-    // Open your SourcePicker UI, then call:
-    // callback({ bookId, unitId, quote, note })
-  },
-});
+```html
+<div id="editor-container"></div>
+<script type="module">
+  import { Editor, createDocument } from 'griot';
+
+  const container = document.getElementById('editor-container');
+  const doc = createDocument([
+    { id: 'b1', type: 'heading', text: 'Hello World', meta: { level: 1 } },
+    { id: 'b2', type: 'paragraph', text: 'This is **editable** content.' },
+  ]);
+
+  const editor = new Editor(container, {
+    doc,
+    books: [],                     // optional, for book citations
+    onChange: (newDoc) => {
+      console.log('Document changed:', newDoc);
+    },
+    onEventClick: (eventId) => {
+      console.log('Event clicked:', eventId);
+    },
+    onCiteClick: (blockId) => {
+      console.log('Citation clicked:', blockId);
+    },
+    onRequestBookPicker: (blockId, callback) => {
+      // Open your own book picker UI, then call callback with selection
+      callback({ bookId: 'book1', unitId: 'unit1', quote: '', note: '' });
+    }
+  });
+
+  // Later, if you need to replace the document:
+  editor.setDoc(newDoc);
+</script>
 ```
 
 ### Viewer
 
-```js
-import { Viewer } from 'griot';
+```html
+<div id="viewer-container"></div>
+<script type="module">
+  import { Viewer } from 'griot';
+
+  const container = document.getElementById('viewer-container');
+  const viewer = new Viewer(container, {
+    doc: myDocument,
+    books: myBooks,
+    onEventClick: (eventId) => { /* ... */ },
+    onCiteClick: (blockId) => { /* ... */ },
+    highlightBlockId: 'b2'      // optional initial highlight
+  });
+
+  // Highlight and scroll to a block
+  viewer.setHighlight('b1');
+</script>
+```
 
-const viewer = new Viewer(document.querySelector('#viewer'), {
-  doc,
-  books: [],
-  onEventClick(eventId) {
-    console.log('Open event:', eventId);
-  },
-});
+---
 
-// Jump to a block (e.g. from a timeline citation)
-viewer.setHighlight('b_abc123');
+## Concepts
+
+### Document
+
+A Griot document is a plain object with an `id` and an array of blocks:
+
+```typescript
+interface Document {
+  id: string;
+  blocks: Block[];
+}
 ```
 
----
+### Block
+
+Every block has at least `id`, `type`, and optionally `text` and `meta`. The `text` field is only present for block types that contain editable text (e.g. paragraphs, headings). All other block types store their data in `meta`.
+
+```typescript
+interface Block {
+  id: string;
+  type: string;
+  text?: string | null;
+  meta: Record<string, any>;
+}
+```
+
+### Inline Markup
+
+Within text blocks, you can use lightweight syntax:
+
+| Syntax | Result |
+|---|---|
+| `**bold**` | **bold** |
+| `*italic*` | *italic* |
+| `__underline__` | underline |
+| `~~strikethrough~~` | ~~strikethrough~~ |
+| `` `code` `` | `code` |
+| `==highlight==` | highlight |
+| `{#ff0000:red text}` or `{blue:text}` | colored text |
+| `[link text](https://example.com)` | link |
+| `![alt text](image.jpg)` | image |
+| `[[event:eventId\|label]]` | clickable chip → `onEventClick` |
+| `[[cite:blockId\|label]]` | clickable chip → `onCiteClick` |
+
+The inline parser is fully independent and can be used separately: `tokenizeInline()`, `renderInlineToDOM()`, `renderInlineToHTML()`.
+
+### Block Schema
+
+All block types are defined in `BlockSchema.js`. Each definition includes category, label, icon, slash label, whether it has text, default meta, and placeholder. You can extend the schema by adding new entries.
 
-## Block types
+### History
 
-| Type | Icon | Text field | Notes |
-|---|---|---|---|
-| `paragraph` | ¶ | ✓ | Inline syntax supported |
-| `heading` | H | ✓ | `meta.level` 1–6 |
-| `blockquote` | ❝ | ✓ | Inline syntax supported |
-| `callout` | 💡 | ✓ | `meta.icon` for the emoji |
-| `code` | </> | ✓ | No inline parsing. `meta.language` for highlight |
-| `divider` | — | — | Horizontal rule |
-| `image` | 🖼 | — | `meta.src`, `meta.alt`, `meta.caption` |
-| `timeline_ref` | ⏱ | — | `meta.eventId`, `meta.eventTitle`, `meta.note` |
-| `book_citation` | 📖 | — | `meta.bookId`, `meta.unitId`, `meta.quote`, `meta.note` |
+The `History` class provides a simple linear undo/redo stack. The editor uses it internally; you can also use it standalone.
 
 ---
 
-## Inline syntax
+## API Reference
 
-Works inside any block with `hasInline: true` (paragraph, blockquote, callout, note fields):
+The public API is exposed through the main entry point (`griot.js`). Below are the most important exports.
 
-```
-**bold**
-*italic*
-`inline code`
-[link text](https://example.com)
-[[event:rome_founding|The Founding of Rome]]   → timeline event chip
-[[cite:b_abc123|See Chapter 2]]                → citation cross-reference
+### Core
+
+| Export | Description |
+|---|---|
+| `createBlock(type, overrides?)` | Create a new block with a unique id. |
+| `cloneBlock(block, newId = true)` | Deep clone a block. |
+| `isTextBlock(block)` | Check if a block stores a text string. |
+| `isValidBlock(block)` | Minimal structural check. |
+| `anchorId(blockId)` | Generate the DOM id used for a block element. |
+| `scrollToBlock(blockId, behavior = 'smooth')` | Scroll to a block's element. |
+| `TEXT_TYPES` | Set of block types that have a text field. |
+| `ALL_TYPES` | Array of all known block type names. |
+
+### Document Operations
+
+All functions are immutable – they return a new document.
+
+| Export | Description |
+|---|---|
+| `createDocument(blocks?)` | Create a new document (with at least one paragraph). |
+| `toJSON(doc)` / `fromJSON(json)` | Serialize / deserialize. |
+| `getBlock(doc, id)` | Find a block by id. |
+| `getBlockIndex(doc, id)` | Get index of a block. |
+| `getBlockBefore(doc, id)` / `getBlockAfter(doc, id)` | Adjacent blocks. |
+| `updateBlock(doc, id, patch)` | Update text and/or meta. |
+| `insertBlockAfter(doc, afterId, newBlock)` | Insert block. |
+| `insertBlockBefore(doc, beforeId, newBlock)` | Insert block. |
+| `removeBlock(doc, id)` | Delete a block. |
+| `moveBlock(doc, fromIdx, toIdx)` | Reorder blocks. |
+| `splitBlock(doc, blockId, offset)` | Split a text block at offset. |
+| `mergeBlockWithPrev(doc, blockId)` | Merge block into previous one. |
+
+### Inline Parsing & Rendering
+
+| Export | Description |
+|---|---|
+| `tokenizeInline(text)` | Return an array of token objects. |
+| `renderInlineToDOM(text, callbacks?)` | Render tokens into a DocumentFragment. |
+| `renderInlineToHTML(text)` | Render tokens into an HTML string. |
+| `escHtml(str)` / `escAttr(str)` | Escape helpers. |
+| `TOKEN` | Enum of token types. |
+
+### Block Rendering (for Viewer or custom use)
+
+| Export | Description |
+|---|---|
+| `renderBlock(block, options)` | Render a single block to a DOM element. Used by Viewer. |
+| `getBlockDef(type)` | Get the schema definition for a block type. |
+| `getAllTypes()` | All registered block type names. |
+| `getTypesByCategory(category)` | Filter types by category. |
+| `defaultMeta(type)` | Get default meta for a type. |
+| `resolveYouTube(src)` / `resolveVimeo` / `resolveSpotify` / `resolveSoundCloud` | Extract embed URLs from various sources. |
+
+### Editor Classes
+
+| Export | Description |
+|---|---|
+| `Editor` | Main editor class. See constructor options below. |
+| `FormatToolbar` | Floating formatting toolbar (used internally, but can be used standalone). |
+| `SlashMenu` | Slash command menu (used internally). |
+| `DropHandler` | Handles drag & drop of files/images (not yet shown, but exported). |
+
+**Editor constructor options:**
+
+```typescript
+{
+  doc: Document;                       // initial document
+  books?: Book[];                      // array of book objects for citations
+  onChange?: (doc: Document) => void;  // called after every change (debounced)
+  onEventClick?: (eventId: string) => void;
+  onCiteClick?: (blockId: string) => void;
+  onRequestBookPicker?: (blockId: string, callback: (selection) => void) => void;
+}
 ```
 
----
+**Editor methods:**
 
-## Document format (`.griot.json`)
+- `setDoc(doc)` – replace the document.
+- `setBooks(books)` – update the book list.
+- `focus(blockId)` – focus a specific block.
+- `destroy()` – clean up.
 
-```json
+### Viewer
+
+| Export | Description |
+|---|---|
+| `Viewer` | Read‑only renderer. |
+
+**Viewer constructor options:**
+
+```typescript
 {
-  "version": 1,
-  "id": "doc_abc",
-  "title": "The Fall of Rome",
-  "createdAt": "2025-01-01T00:00:00.000Z",
-  "updatedAt": "2025-01-01T00:00:00.000Z",
-  "blocks": [
-    { "id": "b_1", "type": "heading",   "text": "The Fall of Rome",  "meta": { "level": 1 } },
-    { "id": "b_2", "type": "paragraph", "text": "In **476 CE** the last emperor [[event:fall_of_rome|was deposed]].", "meta": {} },
-    { "id": "b_3", "type": "book_citation", "text": null, "meta": {
-        "bookId": "book_xyz", "unitId": "unit_abc",
-        "quote": "The barbarians had long served in Roman armies.",
-        "note": "Essential context for understanding the transition."
-    }}
-  ]
+  doc?: Document;
+  books?: Book[];
+  onEventClick?: (eventId: string) => void;
+  onCiteClick?: (blockId: string) => void;
+  highlightBlockId?: string;           // initial highlight
 }
 ```
 
+**Viewer methods:**
+
+- `setDoc(doc)`
+- `setBooks(books)`
+- `setHighlight(blockId, options?)` – scroll to and briefly highlight a block.
+- `destroy()`
+
+### Keyboard Helpers
+
+| Export | Description |
+|---|---|
+| `attachKeyboardHandler(el, blockId, callbacks)` | Attach editor keyboard shortcuts to a contenteditable element. |
+| `getCursorOffset(el)` / `setCursorOffset(el, offset)` | Get/set caret position by character offset. |
+| `getSelectionOffsets(el)` | Get start/end offsets of current selection. |
+| `focusAtEnd(el)` / `focusAtStart(el)` | Move caret to end/start. |
+
+### History
+
+```javascript
+import { History } from 'griot';
+
+const history = new History(initialDoc);
+history.push(newDoc);
+history.undo();  // returns previous document
+history.redo();
+history.current; // current document
+```
+
 ---
 
-## Deep-link anchors
+## Styling
 
-Every rendered block gets `id="griot-{blockId}"` in the DOM.
+Griot includes no CSS by design – you can style it to match your application. All elements have semantic class names prefixed with `griot-`. For a quick start, you can copy the example styles from the test page or browse the class names used in the source.
 
-```js
-import { anchorId, scrollToBlock } from 'griot';
+**Minimal recommended styles:**
 
-// Get the DOM id for a block
-anchorId('b_abc123')          // → "griot-b_abc123"
+- Make `.griot-editor-block__input[contenteditable]` look like a normal block.
+- Add basic spacing and borders.
+- Style the floating toolbar and slash menu as floating cards.
 
-// Scroll to a block (viewer or editor)
-scrollToBlock('b_abc123');
-scrollToBlock('b_abc123', 'instant');
+---
+
+## Examples
+
+### Basic Editor with Slash Menu and Toolbar
+
+The editor includes the slash menu and format toolbar automatically. Just instantiate it.
+
+### Using the Viewer with Highlight
+
+```javascript
+const viewer = new Viewer(container, { doc });
+viewer.setHighlight('some-block-id');
+```
+
+### Custom Book Picker
+
+When a `book_citation` block is added, the editor calls `onRequestBookPicker`. Implement your own modal or dropdown:
+
+```javascript
+onRequestBookPicker: (blockId, callback) => {
+  const book = prompt('Enter book ID:');
+  const unit = prompt('Enter unit ID:');
+  callback({ bookId: book, unitId: unit, quote: '', note: '' });
+}
 ```
 
-This is the contract for timeline → article navigation:  
-store `{ docId, blockId }` on a citation, then call `scrollToBlock(blockId)` when the timeline jumps to it.
+### Using Inline Renderer Standalone
+
+```javascript
+import { renderInlineToDOM } from 'griot';
+
+const text = 'This is **bold** and [a link](https://example.com).';
+const fragment = renderInlineToDOM(text, {
+  onEventClick: (id) => console.log(id),
+  onCiteClick: (id) => console.log(id)
+});
+document.getElementById('output').appendChild(fragment);
+```
 
 ---
 
-## API reference
+## Extending
 
-### `Editor`
-| Method | Description |
-|---|---|
-| `new Editor(el, options)` | Mount editor into `el` |
-| `editor.doc` | Current document (read-only) |
-| `editor.setDoc(doc)` | Replace document |
-| `editor.setBooks(books)` | Update available books |
-| `editor.focus(blockId)` | Focus a specific block |
-| `editor.destroy()` | Unmount and clean up |
-
-### `Viewer`
-| Method | Description |
-|---|---|
-| `new Viewer(el, options)` | Mount viewer into `el` |
-| `viewer.setDoc(doc)` | Replace document |
-| `viewer.setBooks(books)` | Update available books |
-| `viewer.setHighlight(blockId)` | Scroll to + briefly highlight a block |
-| `viewer.destroy()` | Unmount and clean up |
-
-### Document helpers
-```js
-createDocument(title)
-createBlock(type, overrides)
-updateBlock(doc, blockId, patch)
-insertBlockAfter(doc, blockId, newBlock)
-removeBlock(doc, blockId)
-splitBlock(doc, blockId, offset)         // returns [newDoc, newBlockId]
-mergeBlockWithPrev(doc, blockId)         // returns [newDoc, prevId, offset]
-moveBlock(doc, fromIndex, toIndex)
-toJSON(doc)
-fromJSON(jsonStringOrObject)
+### Adding a New Block Type
+
+1. Add an entry in `BlockSchema.js` (or patch the schema at runtime).
+2. Add a rendering case in `BlockRenderer.js`.
+3. If the block has a special editor UI, add a case in `Editor._buildSpecialBlockUI()`.
+4. (Optional) Add support in the slash menu – it reads from the schema automatically.
+
+### Custom Inline Syntax
+
+Modify `InlineLexer.js` by adding a new rule. Then update `InlineRenderer.js` to render the new token type.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/yourname/griot.git  
+cd griot
+npm install
+npm run dev   # serves test page at localhost:5000 (or similar)
 ```
+
+The source is organised as:
+
+- `src/core/` – block primitives, document operations, history.
+- `src/blocks/` – block schema and renderer.
+- `src/inline/` – inline lexer and renderer.
+- `src/editor/` – editor UI, keyboard handling, slash menu, toolbar.
+- `src/viewer/` – read-only renderer.
+
+All public exports are aggregated in `src/griot.js`.
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0m0g1/griot",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "A self-contained block-based rich text editor and renderer built for historical document authoring.",
   "type": "module",
   "main": "./src/Griot.js",

package/src/Griot.js

@@ -1,32 +1,26 @@
 // ─── Griot.js ─────────────────────────────────────────────────────────────────
-// Public facade. Import from here — never from internal modules directly.
+// Public facade. Import from here only — never from internal modules directly.
 //
-// Named exports cover every public surface:
-//
-//   Classes
-//     Editor, Viewer
-//
-//   Document model
-//     createDocument, createBlock, cloneBlock
-//     updateBlock, insertBlockAfter, insertBlockBefore,
-//     removeBlock, splitBlock, mergeBlockWithPrev, moveBlock,
-//     getBlock, getBlockIndex, toJSON, fromJSON
-//
-//   Block helpers
-//     anchorId, scrollToBlock, isTextBlock
-//
-//   Inline
-//     tokenizeInline, renderInlineToDOM, renderInlineToHTML, TOKEN
-//
-//   Schema
-//     getBlockDef, getAllTypes, defaultMeta, BlockSchema
+//   Classes       Editor, Viewer, FormatToolbar, SlashMenu, DropHandler
+//   Document      createDocument, createBlock, cloneBlock
+//                 updateBlock, insertBlockAfter, insertBlockBefore,
+//                 removeBlock, moveBlock, splitBlock, mergeBlockWithPrev,
+//                 getBlock, getBlockIndex, getBlockBefore, getBlockAfter,
+//                 toJSON, fromJSON
+//   Block         anchorId, scrollToBlock, isTextBlock, isValidBlock
+//                 TEXT_TYPES, ALL_TYPES
+//   Inline        tokenizeInline, renderInlineToDOM, renderInlineToHTML,
+//                 escHtml, escAttr, TOKEN
+//   Schema        getBlockDef, getAllTypes, getTypesByCategory,
+//                 defaultMeta, BlockSchema
+//   Keyboard      attachKeyboardHandler, getCursorOffset, getSelectionOffsets,
+//                 setCursorOffset, focusAtEnd, focusAtStart
+//   URL helpers   resolveYouTube, resolveVimeo, resolveSpotify, resolveSoundCloud
 // ─────────────────────────────────────────────────────────────────────────────
 
-// Core
 export {
   createBlock, cloneBlock, isTextBlock, isValidBlock,
-  anchorId, scrollToBlock,
-  TEXT_TYPES, ALL_TYPES,
+  anchorId, scrollToBlock, TEXT_TYPES, ALL_TYPES,
 } from './core/Block.js';
 
 export {
@@ -38,17 +32,21 @@ export {
 
 export { History } from './core/History.js';
 
-// Inline
-export { tokenizeInline, TOKEN } from './inline/InlineLexer.js';
-export {
-  renderInlineToDOM, renderInlineToHTML, escHtml, escAttr,
-} from './inline/InlineRenderer.js';
+export { tokenizeInline, TOKEN }               from './inline/InlineLexer.js';
+export { renderInlineToDOM, renderInlineToHTML, escHtml, escAttr } from './inline/InlineRenderer.js';
 
-// Blocks
-export { getBlockDef, getAllTypes, defaultMeta }    from './blocks/BlockSchema.js';
-export { default as BlockSchema }                  from './blocks/BlockSchema.js';
-export { renderBlock }                             from './blocks/BlockRenderer.js';
+export { getBlockDef, getAllTypes, getTypesByCategory, defaultMeta } from './blocks/BlockSchema.js';
+export { default as BlockSchema }               from './blocks/BlockSchema.js';
+export { renderBlock, resolveYouTube, resolveVimeo, resolveSpotify, resolveSoundCloud } from './blocks/BlockRenderer.js';
+
+export { Editor }         from './editor/Editor.js';
+export { FormatToolbar }  from './editor/FormatToolbar.js';
+export { SlashMenu }      from './editor/SlashMenu.js';
+export { DropHandler }    from './editor/DropHandler.js';
+export {
+  attachKeyboardHandler,
+  getCursorOffset, getSelectionOffsets, setCursorOffset,
+  focusAtEnd, focusAtStart,
+} from './editor/Keyboard.js';
 
-// Editor / Viewer
-export { Editor }  from './editor/Editor.js';
-export { Viewer }  from './viewer/Viewer.js';
+export { Viewer } from './viewer/Viewer.js';

package/src/blocks/BlockRenderer.js

@@ -1,46 +1,48 @@
 // ─── BlockRenderer.js ─────────────────────────────────────────────────────────
-// Renders a single block to a DOM element.
-// Used by both Viewer (read-only) and Editor (preview layer).
+// Renders a single block → DOM element.
+// Used by Viewer (read-only) and Editor preview layer.
 //
 // Options:
-//   books         — array of parsed book objects (for book_citation)
-//   onEventClick  — (eventId) => void
-//   onCiteClick   — (blockId) => void
-//   editable      — if true, skips event listeners (Editor manages them)
+//   books        — array of book objects
+//   onEventClick — (eventId) => void
+//   onCiteClick  — (blockId) => void
 // ─────────────────────────────────────────────────────────────────────────────
 
-import { anchorId }                             from '../core/Block.js';
+import { anchorId }                                               from '../core/Block.js';
 import { renderInlineToDOM, renderInlineToHTML, escHtml, escAttr } from '../inline/InlineRenderer.js';
-import { getBlockDef }                          from './BlockSchema.js';
+import { getBlockDef }                                            from './BlockSchema.js';
 
-// ─── Public entry point ───────────────────────────────────────────────────────
-export function renderBlock(block, { books = [], onEventClick, onCiteClick } = {}) {
-  const el = _render(block, { books, onEventClick, onCiteClick });
+const LAYOUT_OPTIONS = ['grid','masonry','carousel','strip'];
+
+// ─── Public ───────────────────────────────────────────────────────────────────
+
+export function renderBlock(block, opts = {}) {
+  const el = _render(block, opts);
   if (el) {
-    el.id = anchorId(block.id);
-    el.dataset.blockId = block.id;
+    el.id                = anchorId(block.id);
+    el.dataset.blockId   = block.id;
     el.dataset.blockType = block.type;
   }
   return el;
 }
 
-// ─── Internal ─────────────────────────────────────────────────────────────────
-function inlineDOM(text, opts) {
-  return renderInlineToDOM(text, {
-    onEventClick: opts.onEventClick,
-    onCiteClick:  opts.onCiteClick,
-  });
+// ─── Dispatcher ───────────────────────────────────────────────────────────────
+
+function il(text, opts) {
+  return renderInlineToDOM(text, { onEventClick: opts.onEventClick, onCiteClick: opts.onCiteClick });
 }
 
 function _render(block, opts) {
-  const { text, meta = {}, type } = block;
+  const { text = '', meta = {}, type } = block;
 
   switch (type) {
 
+    // ── Text ──────────────────────────────────────────────────────────────────
+
     case 'paragraph': {
       const el = document.createElement('p');
       el.className = 'griot-block griot-paragraph';
-      if (text) el.appendChild(inlineDOM(text, opts));
+      if (text) el.appendChild(il(text, opts));
       return el;
     }
 
@@ -55,70 +57,185 @@ function _render(block, opts) {
     case 'blockquote': {
       const el = document.createElement('blockquote');
       el.className = 'griot-block griot-blockquote';
-      if (text) el.appendChild(inlineDOM(text, opts));
+      if (text) el.appendChild(il(text, opts));
       return el;
     }
 
-    case 'callout': {
-      const el    = document.createElement('div');
-      const icon  = document.createElement('span');
-      const body  = document.createElement('div');
-      el.className   = 'griot-block griot-callout';
+    case 'callout':
+    case 'callout_warning':
+    case 'callout_tip':
+    case 'callout_danger': {
+      const ICONS = { callout:'💡', callout_warning:'⚠️', callout_tip:'✅', callout_danger:'🚨' };
+      const el   = document.createElement('div');
+      const icon = document.createElement('span');
+      const body = document.createElement('div');
+      el.className   = `griot-block griot-callout griot-callout--${type.replace('callout_','') || 'info'}`;
       icon.className = 'griot-callout__icon';
       body.className = 'griot-callout__body';
-      icon.textContent = meta.icon ?? '💡';
-      if (text) body.appendChild(inlineDOM(text, opts));
-      el.appendChild(icon);
-      el.appendChild(body);
+      icon.textContent = meta.icon ?? ICONS[type] ?? '💡';
+      if (text) body.appendChild(il(text, opts));
+      el.append(icon, body);
       return el;
     }
 
     case 'code': {
       const pre  = document.createElement('pre');
       const code = document.createElement('code');
-      pre.className  = 'griot-block griot-code';
-      if (meta.language) code.className = `language-${meta.language}`;
+      pre.className = 'griot-block griot-code';
+      if (meta.language) { pre.dataset.language = meta.language; code.className = `language-${meta.language}`; }
       code.textContent = text ?? '';
       pre.appendChild(code);
       return pre;
     }
 
-    case 'divider': {
-      const el = document.createElement('hr');
-      el.className = 'griot-block griot-divider';
+    case 'list_ul':
+    case 'list_ol': {
+      const tag = type === 'list_ul' ? 'ul' : 'ol';
+      const el  = document.createElement(tag);
+      el.className = `griot-block griot-list griot-list--${tag}`;
+      for (const item of (text ?? '').split('\n').filter(l => l.trim())) {
+        const li = document.createElement('li');
+        li.appendChild(il(item, opts));
+        el.appendChild(li);
+      }
       return el;
     }
 
+    // ── Media ─────────────────────────────────────────────────────────────────
+
     case 'image': {
-      const figure  = document.createElement('figure');
-      const img     = document.createElement('img');
-      figure.className = 'griot-block griot-image';
-      img.src = meta.src ?? '';
-      img.alt = meta.alt ?? '';
-      figure.appendChild(img);
-      if (meta.caption) {
-        const cap = document.createElement('figcaption');
-        cap.textContent = meta.caption;
-        figure.appendChild(cap);
+      const fig = document.createElement('figure');
+      fig.className = `griot-block griot-image griot-image--${meta.width ?? 'full'}`;
+      if (meta.uploading) {
+        const sp = document.createElement('div');
+        sp.className = 'griot-media-uploading';
+        sp.textContent = 'Uploading…';
+        fig.appendChild(sp);
+      } else if (meta.src) {
+        const img = document.createElement('img');
+        img.src = meta.src; img.alt = meta.alt ?? '';
+        fig.appendChild(img);
+        if (meta.caption) {
+          const cap = document.createElement('figcaption');
+          cap.textContent = meta.caption;
+          fig.appendChild(cap);
+        }
+      }
+      return fig;
+    }
+
+    case 'video': {
+      const fig = document.createElement('figure');
+      fig.className = 'griot-block griot-video';
+      const embed = meta.embedUrl ?? _ytEmbed(meta.src) ?? _vimeoEmbed(meta.src);
+      if (embed) {
+        const iframe = document.createElement('iframe');
+        iframe.src = embed; iframe.className = 'griot-video__iframe';
+        iframe.frameBorder = '0';
+        iframe.allow = 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture';
+        iframe.allowFullscreen = true;
+        fig.appendChild(iframe);
+      } else if (meta.src) {
+        const v = document.createElement('video');
+        v.src = meta.src; v.controls = true; v.className = 'griot-video__native';
+        fig.appendChild(v);
+      }
+      if (meta.caption) { const c = document.createElement('figcaption'); c.textContent = meta.caption; fig.appendChild(c); }
+      return fig;
+    }
+
+    case 'audio': {
+      const fig = document.createElement('figure');
+      fig.className = 'griot-block griot-audio';
+      const embed = meta.embedUrl ?? _spotifyEmbed(meta.src) ?? _scEmbed(meta.src);
+      if (embed) {
+        const iframe = document.createElement('iframe');
+        iframe.src = embed; iframe.className = 'griot-audio__iframe';
+        iframe.frameBorder = '0';
+        iframe.allow = 'autoplay; clipboard-write; encrypted-media; fullscreen';
+        fig.appendChild(iframe);
+      } else if (meta.src) {
+        const a = document.createElement('audio');
+        a.src = meta.src; a.controls = true; a.className = 'griot-audio__native';
+        fig.appendChild(a);
       }
-      return figure;
+      if (meta.caption) { const c = document.createElement('figcaption'); c.textContent = meta.caption; fig.appendChild(c); }
+      return fig;
+    }
+
+    case 'gallery': {
+      return _renderGallery(meta.items ?? [], meta.layout ?? 'grid', opts);
+    }
+
+    case 'embed': {
+      const fig = document.createElement('figure');
+      fig.className = 'griot-block griot-embed';
+      if (meta.src) {
+        const iframe = document.createElement('iframe');
+        iframe.src = meta.src;
+        iframe.style.height = `${meta.height ?? 400}px`;
+        iframe.className = 'griot-embed__iframe';
+        iframe.frameBorder = '0';
+        iframe.allow = 'autoplay; fullscreen; picture-in-picture; clipboard-write; encrypted-media';
+        iframe.allowFullscreen = true;
+        fig.appendChild(iframe);
+      }
+      if (meta.caption) { const c = document.createElement('figcaption'); c.textContent = meta.caption; fig.appendChild(c); }
+      return fig;
+    }
+
+    // ── Structure ─────────────────────────────────────────────────────────────
+
+    case 'table': {
+      const headers  = Array.isArray(meta.headers) ? meta.headers : [];
+      const rows     = Array.isArray(meta.rows)    ? meta.rows    : [];
+      const colCount = Math.max(headers.length, ...rows.map(r => r.length), 1);
+      const wrap  = document.createElement('div');
+      wrap.className = 'griot-block griot-table-wrap';
+      const table = document.createElement('table');
+      table.className = 'griot-table';
+      if (headers.length) {
+        const thead = document.createElement('thead');
+        const tr    = document.createElement('tr');
+        for (let ci = 0; ci < colCount; ci++) {
+          const th = document.createElement('th');
+          th.appendChild(il(headers[ci] ?? '', opts));
+          tr.appendChild(th);
+        }
+        thead.appendChild(tr); table.appendChild(thead);
+      }
+      const tbody = document.createElement('tbody');
+      for (const row of rows) {
+        const tr = document.createElement('tr');
+        for (let ci = 0; ci < colCount; ci++) {
+          const td = document.createElement('td');
+          td.appendChild(il(row[ci] ?? '', opts));
+          tr.appendChild(td);
+        }
+        tbody.appendChild(tr);
+      }
+      table.appendChild(tbody); wrap.appendChild(table);
+      return wrap;
+    }
+
+    case 'divider': {
+      const el = document.createElement('hr');
+      el.className = 'griot-block griot-divider';
+      return el;
     }
 
     case 'timeline_ref': {
       const el = document.createElement('div');
       el.className = 'griot-block griot-timeline-ref';
       if (meta.eventId && opts.onEventClick) {
-        el.setAttribute('role', 'button');
-        el.tabIndex = 0;
+        el.setAttribute('role','button'); el.tabIndex = 0;
         el.addEventListener('click', () => opts.onEventClick(meta.eventId));
-        el.addEventListener('keydown', (e) => {
-          if (e.key === 'Enter' || e.key === ' ') opts.onEventClick(meta.eventId);
-        });
+        el.addEventListener('keydown', e => { if (e.key==='Enter'||e.key===' ') opts.onEventClick(meta.eventId); });
       }
       el.innerHTML = `
         <span class="griot-timeline-ref__icon">⏱</span>
         <div class="griot-timeline-ref__body">
-          <div class="griot-timeline-ref__title">${escHtml(meta.eventTitle || 'Timeline Event')}</div>
+          <div class="griot-timeline-ref__title">${escHtml(meta.eventTitle||'Timeline Event')}</div>
           ${meta.note ? `<div class="griot-timeline-ref__note">${escHtml(meta.note)}</div>` : ''}
         </div>
         ${meta.eventId ? '<span class="griot-timeline-ref__arrow">→</span>' : ''}
@@ -133,69 +250,99 @@ function _render(block, opts) {
     default: {
       const el = document.createElement('p');
       el.className = 'griot-block griot-paragraph';
-      el.textContent = text ?? '';
+      if (text) el.appendChild(il(text, opts));
       return el;
     }
   }
 }
 
+// ─── Gallery renderer ─────────────────────────────────────────────────────────
+
+function _renderGallery(items, layout, opts) {
+  const wrap = document.createElement('div');
+  wrap.className = `griot-block griot-gallery griot-gallery--${LAYOUT_OPTIONS.includes(layout)?layout:'grid'}`;
+
+  if (!items.length) {
+    wrap.innerHTML = `<div class="griot-gallery__empty">No images yet</div>`;
+    return wrap;
+  }
+
+  for (const [i, item] of items.entries()) {
+    const el  = document.createElement('div');
+    el.className = 'griot-gallery__item';
+    const img = document.createElement('img');
+    img.src = item.src ?? item.url ?? '';
+    img.alt = item.alt ?? item.alt_text ?? '';
+    img.loading = 'lazy';
+    el.appendChild(img);
+    if (item.caption) {
+      const cap = document.createElement('p');
+      cap.className = 'griot-gallery__caption';
+      cap.textContent = item.caption;
+      el.appendChild(cap);
+    }
+    wrap.appendChild(el);
+  }
+  return wrap;
+}
+
+// ─── Citation renderer ────────────────────────────────────────────────────────
+
 function _renderCitation(block, opts) {
   const { meta = {} } = block;
   const wrap = document.createElement('figure');
   wrap.className = 'griot-block griot-citation';
 
-  if (!meta.bookId) {
-    wrap.innerHTML = `<div class="griot-citation__empty">📖 No source selected yet</div>`;
-    return wrap;
-  }
+  if (!meta.bookId) { wrap.innerHTML = `<div class="griot-citation__empty">📖 No source selected yet</div>`; return wrap; }
 
   const book = (opts.books ?? []).find(b => b.id === meta.bookId);
   const unit = book?.units?.find(u => u.id === meta.unitId);
-
-  if (!book || !unit) {
-    wrap.innerHTML = `<div class="griot-citation__missing">📖 Source not found — book may have been removed</div>`;
-    return wrap;
-  }
+  if (!book || !unit) { wrap.innerHTML = `<div class="griot-citation__missing">📖 Source not found</div>`; return wrap; }
 
   const inner = document.createElement('div');
   inner.className = 'griot-citation__inner';
-
-  // Header
-  const hdr = document.createElement('div');
-  hdr.className = 'griot-citation__header';
-  hdr.innerHTML = `
-    <span class="griot-citation__book-icon">📖</span>
-    <span class="griot-citation__book-title">${escHtml(book.title)}</span>
-    ${book.author ? `<span class="griot-citation__author">${escHtml(book.author)}</span>` : ''}
-    <span class="griot-citation__unit">${escHtml(unit.label)}</span>
+  inner.innerHTML = `
+    <div class="griot-citation__header">
+      <span class="griot-citation__book-icon">📖</span>
+      <span class="griot-citation__book-title">${escHtml(book.title)}</span>
+      ${book.author ? `<span class="griot-citation__author">${escHtml(book.author)}</span>` : ''}
+      <span class="griot-citation__unit">${escHtml(unit.label)}</span>
+    </div>
+    ${meta.quote ? `<blockquote class="griot-citation__quote">${escHtml(meta.quote)}</blockquote>` : ''}
   `;
-  inner.appendChild(hdr);
-
-  // Quote
-  if (meta.quote) {
-    const q = document.createElement('blockquote');
-    q.className = 'griot-citation__quote';
-    q.textContent = meta.quote;
-    inner.appendChild(q);
-  }
-
-  // Note (supports inline syntax)
   if (meta.note) {
     const note = document.createElement('div');
     note.className = 'griot-citation__note';
-    note.appendChild(inlineDOM(meta.note, opts));
+    note.appendChild(renderInlineToDOM(meta.note, opts));
     inner.appendChild(note);
   }
-
   wrap.appendChild(inner);
+  return wrap;
+}
 
-  // Content preview
-  if (unit.content) {
-    const preview = document.createElement('div');
-    preview.className = 'griot-citation__preview';
-    preview.textContent = unit.content.slice(0, 180) + (unit.content.length > 180 ? '…' : '');
-    wrap.appendChild(preview);
-  }
+// ─── Embed URL helpers ────────────────────────────────────────────────────────
 
-  return wrap;
+function _ytEmbed(src) {
+  if (!src) return null;
+  const m = src.match(/(?:youtu\.be\/|youtube\.com\/(?:watch\?v=|shorts\/|embed\/))([a-zA-Z0-9_-]{11})/);
+  return m ? `https://www.youtube.com/embed/${m[1]}?rel=0` : null;
+}
+function _vimeoEmbed(src) {
+  if (!src) return null;
+  const m = src.match(/vimeo\.com\/(\d+)/);
+  return m ? `https://player.vimeo.com/video/${m[1]}` : null;
 }
+function _spotifyEmbed(src) {
+  if (!src) return null;
+  const m = src.match(/open\.spotify\.com\/(track|album|playlist|episode)\/([a-zA-Z0-9]+)/);
+  return m ? `https://open.spotify.com/embed/${m[1]}/${m[2]}` : null;
+}
+function _scEmbed(src) {
+  if (!src) return null;
+  if (src.includes('soundcloud.com/'))
+    return `https://w.soundcloud.com/player/?url=${encodeURIComponent(src)}&color=%236366f1&auto_play=false&hide_related=true&show_comments=false`;
+  return null;
+}
+
+// Export helpers for editor use
+export { _ytEmbed as resolveYouTube, _vimeoEmbed as resolveVimeo, _spotifyEmbed as resolveSpotify, _scEmbed as resolveSoundCloud };

package/src/blocks/BlockSchema.js

@@ -1,24 +1,37 @@
 // ─── BlockSchema.js ───────────────────────────────────────────────────────────
+// Single source of truth for all block types
+// Fields: category, label, icon, slashLabel, hasText, hasInline, defaultMeta, placeholder
+// ─────────────────────────────────────────────────────────────────────────────
+
 const SCHEMA = {
-  paragraph:       { label: 'Paragraph',      icon: '¶',   hasText: true,  hasInline: true,  defaultMeta: {},                                              placeholder: 'Write something… **bold** *italic* `code` ==highlight== [[event:id|label]]' },
-  heading:         { label: 'Heading',         icon: 'H',   hasText: true,  hasInline: false, defaultMeta: { level: 2 },                                    placeholder: 'Heading…' },
-  blockquote:      { label: 'Quote',           icon: '❝',   hasText: true,  hasInline: true,  defaultMeta: {},                                              placeholder: 'Quote…' },
-  callout:         { label: 'Callout',         icon: '💡',  hasText: true,  hasInline: true,  defaultMeta: { icon: '💡' },                                  placeholder: 'Callout text…' },
-  callout_warning: { label: 'Warning',         icon: '⚠️',  hasText: true,  hasInline: true,  defaultMeta: { icon: '⚠️' },                                  placeholder: 'Warning message…' },
-  callout_tip:     { label: 'Tip',             icon: '✅',  hasText: true,  hasInline: true,  defaultMeta: { icon: '✅' },                                  placeholder: 'Tip or note…' },
-  callout_danger:  { label: 'Danger',          icon: '🚨',  hasText: true,  hasInline: true,  defaultMeta: { icon: '🚨' },                                  placeholder: 'Critical warning…' },
-  code:            { label: 'Code',            icon: '</>',  hasText: true,  hasInline: false, defaultMeta: { language: '' },                               placeholder: '// code…' },
-  list_ul:         { label: 'Bullet List',     icon: '•',   hasText: true,  hasInline: false, defaultMeta: {},                                              placeholder: 'Item 1\nItem 2\nItem 3' },
-  list_ol:         { label: 'Numbered List',   icon: '1.',  hasText: true,  hasInline: false, defaultMeta: {},                                              placeholder: 'First item\nSecond item' },
-  table:           { label: 'Table',           icon: '⊞',   hasText: false, hasInline: false, defaultMeta: { headers: ['Column 1', 'Column 2'], rows: [['', '']] }, placeholder: null },
-  divider:         { label: 'Divider',         icon: '—',   hasText: false, hasInline: false, defaultMeta: {},                                              placeholder: null },
-  image:           { label: 'Image',           icon: '🖼',  hasText: false, hasInline: false, defaultMeta: { src: '', alt: '', caption: '' },               placeholder: null },
-  video:           { label: 'Video',           icon: '▶',   hasText: false, hasInline: false, defaultMeta: { src: '', caption: '' },                        placeholder: null },
-  timeline_ref:    { label: 'Timeline Event',  icon: '⏱',  hasText: false, hasInline: false, defaultMeta: { eventId: '', eventTitle: '', note: '' },        placeholder: null },
-  book_citation:   { label: 'Book Citation',   icon: '📖',  hasText: false, hasInline: false, defaultMeta: { bookId: '', unitId: '', quote: '', note: '' }, placeholder: null },
+  paragraph:       { category:'text', label:'Paragraph', icon:'¶',  slashLabel:'Text',           hasText:true,  hasInline:true,  defaultMeta:{},                                              placeholder:'Write something… **bold** *italic* `code` ==highlight==' },
+  heading:         { category:'text', label:'Heading', icon:'H',    slashLabel:'Heading',        hasText:true,  hasInline:false, defaultMeta:{ level:2 },                                    placeholder:'Heading…' },
+  blockquote:      { category:'text', label:'Quote', icon:'❝',      slashLabel:'Quote',          hasText:true,  hasInline:true,  defaultMeta:{},                                              placeholder:'Quote…' },
+  callout:         { category:'text', label:'Callout', icon:'💡',   slashLabel:'Callout',        hasText:true,  hasInline:true,  defaultMeta:{ icon:'💡' },                                  placeholder:'Callout text…' },
+  callout_warning: { category:'text', label:'Warning', icon:'⚠️',   slashLabel:'Warning',        hasText:true,  hasInline:true,  defaultMeta:{ icon:'⚠️' },                                  placeholder:'Warning message…' },
+  callout_tip:     { category:'text', label:'Tip', icon:'✅',       slashLabel:'Tip',            hasText:true,  hasInline:true,  defaultMeta:{ icon:'✅' },                                  placeholder:'Tip or note…' },
+  callout_danger:  { category:'text', label:'Danger', icon:'🚨',    slashLabel:'Danger',         hasText:true,  hasInline:true,  defaultMeta:{ icon:'🚨' },                                  placeholder:'Critical warning…' },
+  code:            { category:'text', label:'Code', icon:'</>',     slashLabel:'Code block',     hasText:true,  hasInline:false, defaultMeta:{ language:'' },                               placeholder:'// code…' },
+  list_ul:         { category:'text', label:'Bullet List', icon:'•', slashLabel:'Bullet list',   hasText:true,  hasInline:false, defaultMeta:{},                                              placeholder:'Item 1\nItem 2\nItem 3' },
+  list_ol:         { category:'text', label:'Numbered List', icon:'1.', slashLabel:'Numbered list', hasText:true, hasInline:false, defaultMeta:{},                                           placeholder:'First item\nSecond item' },
+
+  image:           { category:'media', label:'Image', icon:'🖼',    slashLabel:'Image',          hasText:false, hasInline:false, defaultMeta:{ src:'', alt:'', caption:'', width:'full' }, placeholder:null },
+  video:           { category:'media', label:'Video', icon:'▶',     slashLabel:'Video',          hasText:false, hasInline:false, defaultMeta:{ src:'', caption:'', embedUrl:null, platform:null }, placeholder:null },
+  audio:           { category:'media', label:'Audio', icon:'🎵',    slashLabel:'Audio',          hasText:false, hasInline:false, defaultMeta:{ src:'', caption:'', embedUrl:null, platform:null }, placeholder:null },
+  gallery:         { category:'media', label:'Gallery', icon:'▦',   slashLabel:'Gallery',        hasText:false, hasInline:false, defaultMeta:{ items:[], layout:'grid' },                  placeholder:null },
+
+  embed:           { category:'embed', label:'Embed', icon:'⬡',     slashLabel:'Embed / iframe', hasText:false, hasInline:false, defaultMeta:{ src:'', height:400, caption:'' },            placeholder:null },
+
+  table:           { category:'structure', label:'Table', icon:'⊞', slashLabel:'Table',          hasText:false, hasInline:false, defaultMeta:{ headers:['Column 1','Column 2'], rows:[['','']] }, placeholder:null },
+  divider:         { category:'structure', label:'Divider', icon:'—', slashLabel:'Divider',     hasText:false, hasInline:false, defaultMeta:{},                                              placeholder:null },
+
+  timeline_ref:    { category:'structure', label:'Timeline Event', icon:'⏱', slashLabel:'Timeline event', hasText:false, hasInline:false, defaultMeta:{ eventId:'', eventTitle:'', note:'' }, placeholder:null },
+  book_citation:   { category:'structure', label:'Book Citation', icon:'📖', slashLabel:'Book citation', hasText:false, hasInline:false, defaultMeta:{ bookId:'', unitId:'', quote:'', note:'' }, placeholder:null },
 };
 
-export function getBlockDef(type) { return SCHEMA[type] ?? SCHEMA.paragraph; }
-export function getAllTypes()      { return Object.keys(SCHEMA); }
-export function defaultMeta(type) { return { ...(SCHEMA[type]?.defaultMeta ?? {}) }; }
+export function getBlockDef(type)        { return SCHEMA[type] ?? SCHEMA.paragraph; }
+export function getAllTypes()            { return Object.keys(SCHEMA); }
+export function getTypesByCategory(cat)  { return Object.entries(SCHEMA).filter(([,d]) => d.category === cat).map(([t]) => t); }
+export function defaultMeta(type)        { return { ...(SCHEMA[type]?.defaultMeta ?? {}) }; }
+
 export default SCHEMA;

package/src/editor/SlashMenu.js

@@ -0,0 +1,197 @@
+// ─── SlashMenu.js ─────────────────────────────────────────────────────────────
+// Slash-command palette. Triggered when '/' is typed at the very start of
+// an empty block editable. Shows a searchable list of block types grouped
+// by category.  Selecting an item calls onSelect(type).
+//
+// Usage (inside Editor):
+//   const menu = new SlashMenu(editorContainerEl, onSelect);
+//   menu.show(anchorEl);   // position near anchorEl
+//   menu.hide();
+//   menu.destroy();
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { getAllTypes, getBlockDef, getTypesByCategory } from '../blocks/BlockSchema.js';
+
+const CATEGORIES = [
+  { key: 'text',      label: 'Text'      },
+  { key: 'media',     label: 'Media'     },
+  { key: 'embed',     label: 'Embed'     },
+  { key: 'structure', label: 'Structure' },
+];
+
+export class SlashMenu {
+  constructor(container, onSelect) {
+    this._container = container;
+    this._onSelect  = onSelect;
+    this._el        = null;
+    this._query     = '';
+    this._idx       = 0;
+    this._items     = [];   // filtered list of type strings
+    this._visible   = false;
+
+    this._build();
+  }
+
+  // ── Public ────────────────────────────────────────────────────────────────
+
+  /** Show menu anchored below anchorEl. */
+  show(anchorEl) {
+    this._query = '';
+    this._refresh();
+    this._visible = true;
+    this._el.style.display = 'block';
+    this._reposition(anchorEl);
+    this._el.querySelector('.griot-slash__search')?.focus();
+  }
+
+  /** Filter list to items matching query string (the text after '/'). */
+  filter(query) {
+    this._query = query;
+    this._refresh();
+    if (!this._items.length) { this.hide(); return; }
+    this._reposition(this._anchorEl);
+  }
+
+  hide() {
+    this._visible = false;
+    if (this._el) this._el.style.display = 'none';
+  }
+
+  get visible() { return this._visible; }
+
+  /** Handle keydown while slash menu is open. Returns true if consumed. */
+  handleKey(e) {
+    if (!this._visible) return false;
+    if (e.key === 'ArrowDown')  { e.preventDefault(); this._move(1);  return true; }
+    if (e.key === 'ArrowUp')    { e.preventDefault(); this._move(-1); return true; }
+    if (e.key === 'Enter')      { e.preventDefault(); this._select(); return true; }
+    if (e.key === 'Escape')     { e.preventDefault(); this.hide();    return true; }
+    return false;
+  }
+
+  destroy() {
+    this._el?.remove();
+    this._el = null;
+  }
+
+  // ── Build ─────────────────────────────────────────────────────────────────
+
+  _build() {
+    const el = document.createElement('div');
+    el.className = 'griot-slash';
+    el.setAttribute('role', 'listbox');
+    el.setAttribute('aria-label', 'Block type');
+
+    const search = document.createElement('input');
+    search.type = 'text';
+    search.className = 'griot-slash__search';
+    search.placeholder = 'Search blocks…';
+    search.addEventListener('input', () => { this._query = search.value; this._refresh(); });
+    search.addEventListener('keydown', e => { this.handleKey(e); });
+
+    const list = document.createElement('div');
+    list.className = 'griot-slash__list';
+
+    el.append(search, list);
+    document.body.appendChild(el);
+    this._el    = el;
+    this._list  = list;
+    this._search = search;
+
+    // Hide on outside click
+    this._onDocClick = (e) => { if (this._visible && !el.contains(e.target)) this.hide(); };
+    document.addEventListener('mousedown', this._onDocClick);
+  }
+
+  _refresh() {
+    const q      = this._query.toLowerCase().trim();
+    this._list.innerHTML = '';
+    this._items  = [];
+    this._idx    = 0;
+
+    const all    = getAllTypes();
+    const filtered = q
+      ? all.filter(t => {
+          const d = getBlockDef(t);
+          return d.slashLabel?.toLowerCase().includes(q) || t.includes(q) || d.label.toLowerCase().includes(q);
+        })
+      : all;
+
+    // Group by category when not searching
+    const groups = q
+      ? [{ key: 'results', label: 'Results', types: filtered }]
+      : CATEGORIES.map(c => ({ ...c, types: filtered.filter(t => getBlockDef(t).category === c.key) })).filter(g => g.types.length);
+
+    for (const group of groups) {
+      const hdr = document.createElement('div');
+      hdr.className = 'griot-slash__group';
+      hdr.textContent = group.label;
+      this._list.appendChild(hdr);
+
+      for (const type of group.types) {
+        const def = getBlockDef(type);
+        const idx = this._items.length;
+        this._items.push(type);
+
+        const item = document.createElement('div');
+        item.className = 'griot-slash__item';
+        item.setAttribute('role', 'option');
+        item.dataset.idx = idx;
+        item.innerHTML = `<span class="griot-slash__item-icon">${def.icon}</span><span class="griot-slash__item-label">${def.slashLabel ?? def.label}</span>`;
+
+        item.addEventListener('mousedown', (e) => {
+          e.preventDefault();
+          this._idx = idx;
+          this._select();
+        });
+        item.addEventListener('mouseover', () => { this._idx = idx; this._highlight(); });
+
+        this._list.appendChild(item);
+      }
+    }
+
+    this._highlight();
+  }
+
+  _highlight() {
+    for (const el of this._list.querySelectorAll('.griot-slash__item')) {
+      el.classList.toggle('is-active', Number(el.dataset.idx) === this._idx);
+    }
+    // Scroll into view
+    const active = this._list.querySelector('.griot-slash__item.is-active');
+    active?.scrollIntoView({ block: 'nearest' });
+  }
+
+  _move(dir) {
+    this._idx = Math.max(0, Math.min(this._items.length - 1, this._idx + dir));
+    this._highlight();
+  }
+
+  _select() {
+    const type = this._items[this._idx];
+    if (type) { this.hide(); this._onSelect(type); }
+  }
+
+  _reposition(anchorEl) {
+    this._anchorEl = anchorEl;
+    if (!anchorEl || !this._el) return;
+
+    requestAnimationFrame(() => {
+      const rect  = anchorEl.getBoundingClientRect();
+      const menuH = this._el.offsetHeight || 280;
+      let top  = rect.bottom + window.scrollY + 4;
+      let left = rect.left   + window.scrollX;
+
+      // Flip above if too close to bottom
+      if (rect.bottom + menuH + 8 > window.innerHeight) {
+        top = rect.top + window.scrollY - menuH - 4;
+      }
+      // Clamp left
+      left = Math.min(left, window.scrollX + window.innerWidth - 280 - 8);
+      left = Math.max(left, window.scrollX + 8);
+
+      this._el.style.top  = `${top}px`;
+      this._el.style.left = `${left}px`;
+    });
+  }
+}