@pilotiq/tiptap 3.10.5 → 3.10.6

package/boost/guidelines.md

@@ -0,0 +1,268 @@
+# @pilotiq/tiptap
+
+## Overview
+
+Tiptap rich-text adapter for `@pilotiq/pilotiq`. Adds a `RichTextField` to the form-field catalog with always-on toolbar, selection-anchored floating toolbar, slash menu (`/`), draggable blocks, mention/merge-tag chips, and a custom-block API for embedding inline forms inside a document.
+
+Separate package because Tiptap's extension set is modular and not every app needs long-form content. Mirrors `@pilotiq/codemirror` — small adapter, opt-in registration.
+
+## Setup
+
+```bash
+pnpm add @pilotiq/tiptap \
+  @tiptap/core @tiptap/pm @tiptap/react @tiptap/starter-kit @tiptap/suggestion \
+  @tiptap/extension-link @tiptap/extension-placeholder \
+  @tiptap/extension-underline @tiptap/extension-subscript @tiptap/extension-superscript \
+  @tiptap/extension-text-align @tiptap/extension-text-style @tiptap/extension-color \
+  @tiptap/extension-highlight @tiptap/extension-image @tiptap/extension-table \
+  @tiptap/extension-details
+```
+
+Register the plugin on the panel:
+
+```ts
+// app/Pilotiq/AdminPanel.ts
+import { Pilotiq } from '@pilotiq/pilotiq'
+import { tiptap } from '@pilotiq/tiptap'
+
+export const adminPanel = Pilotiq.make('Admin')
+  .path('/admin')
+  .plugins([
+    tiptap(),
+  ])
+```
+
+The plugin form is sugar over `registerTiptap()` — it runs on both server and client through the panel module. Without registration, `RichTextField` form fields render as nothing because `SchemaRenderer` can't find a renderer for `fieldType: 'richtext'`.
+
+## Key Patterns
+
+### Basic usage
+
+```ts
+import { RichTextField } from '@pilotiq/tiptap'
+
+Resource.make('Article').form((form) => form.schema([
+  TextField.make('title').required(),
+  RichTextField.make('body')
+    .label('Body')
+    .placeholder('Start writing…')
+    .required(),
+]))
+```
+
+The field stores Tiptap JSON by default. Use `.storage('html')` for serialized HTML if your column type is text-only.
+
+### Custom blocks
+
+`Block` defines a reusable embed — a card with its own form schema. Users insert via the slash menu (`/`), edit via the side panel.
+
+```ts
+import { Block, RichTextField } from '@pilotiq/tiptap'
+import { TextField, TextareaField, SelectField, FileUpload } from '@pilotiq/pilotiq'
+
+RichTextField.make('body')
+  .blocks([
+    Block.make('callout')
+      .label('Callout')
+      .icon('💡')                              // emoji or @pilotiq/pilotiq icon registry name
+      .schema([
+        SelectField.make('variant').options({ info: 'Info', warning: 'Warning', danger: 'Danger' }),
+        TextField.make('title').required(),
+        TextareaField.make('content').required(),
+      ]),
+
+    Block.make('youtube')
+      .label('YouTube embed')
+      .icon('youtube')
+      .schema([
+        TextField.make('url').required().placeholder('https://www.youtube.com/watch?v=…'),
+      ]),
+
+    Block.make('cta')
+      .label('Call to action')
+      .icon('zap')
+      .schema([
+        TextField.make('heading').required(),
+        TextField.make('label').default('Learn more'),
+        TextField.make('href').required(),
+      ]),
+  ])
+```
+
+Behavior:
+
+- Inserting a block via `/` opens the side panel with the block's `.schema([…])` mounted as a real pilotiq form.
+- Edits write back into the block's `attrs.blockData` on every keystroke — no save button.
+- The side panel uses `<FormFields>` from `@pilotiq/pilotiq/react`, so every field type from `pilotiq-fields` works (TextField / SelectField / Toggle / Repeater / Builder / FileUpload / etc.).
+- `Mod-E` (Cmd/Ctrl-E) on a selected block opens its side panel. `ESC` closes.
+
+The block name (`'callout'`, `'youtube'`, `'cta'`) is the discriminator — **never use `'block'` as a name**, it collides with ProseMirror's schema GROUP and breaks `contentMatchAt`. The framework's built-in node is `pilotiqBlock` so user-supplied names are safe.
+
+### Toolbar customization
+
+```ts
+RichTextField.make('body')
+  .toolbarButtons([
+    ['bold', 'italic', 'underline', 'strike', 'link'],
+    ['h2', 'h3'],
+    ['textColor', 'highlight'],
+    ['bulletList', 'orderedList'],
+    ['attachFiles', 'table', 'details', 'grid', 'gridDelete'],
+    ['undo', 'redo'],
+  ])
+```
+
+Or use the incremental setters against the defaults:
+
+```ts
+RichTextField.make('body')
+  .enableToolbarButtons(['lead', 'small'])      // append to last group
+  .disableToolbarButtons(['table'])              // drop from every group
+```
+
+Default layout:
+
+```
+[
+  ['bold', 'italic', 'underline', 'strike', 'subscript', 'superscript', 'link'],
+  ['h2', 'h3'],
+  ['alignStart', 'alignCenter', 'alignEnd'],
+  ['blockquote', 'codeBlock', 'bulletList', 'orderedList'],
+  ['undo', 'redo'],
+]
+```
+
+Recognized button ids:
+
+```
+Inline marks   bold italic underline strike subscript superscript code lead small
+Headings       paragraph h1 h2 h3 h4 h5 h6
+Alignment      alignStart alignCenter alignEnd alignJustify
+Block prims    blockquote codeBlock bulletList orderedList horizontalRule
+Style          textColor highlight clearFormatting
+Files          attachFiles
+Tables         table tableAddColumnBefore tableAddColumnAfter tableDeleteColumn
+               tableAddRowBefore tableAddRowAfter tableDeleteRow
+               tableMergeCells tableSplitCell tableDelete
+               tableToggleHeaderRow tableToggleHeaderCell
+Disclosure     details
+Layout         grid gridDelete
+Editing        link undo redo
+```
+
+Unknown ids are silently dropped — the union is intentionally forward-compatible.
+
+Hide the toolbar entirely with `.toolbar(false)`. Disable the floating selection toolbar with `.floatingToolbar(false)`. Disable the slash menu with `.slashCommand(false)`.
+
+### Merge tags
+
+```ts
+RichTextField.make('body')
+  .mergeTags(['firstName', 'lastName', 'company', 'unsubscribeUrl'])
+```
+
+Each id appears under the **Merge tags** group of the slash menu and inserts a `{{ firstName }}` chip in the editor. On the server, the chip serializes verbatim as `{{ firstName }}` text — your render-time substitution handles the replacement.
+
+### Mentions
+
+```ts
+import { RichTextField, MentionProvider } from '@pilotiq/tiptap'
+
+RichTextField.make('body')
+  .mentions([
+    MentionProvider.make('@')
+      .items([
+        { id: 'alice', label: 'Alice', subtitle: 'Engineering' },
+        { id: 'bob',   label: 'Bob',   subtitle: 'Design' },
+      ]),
+
+    MentionProvider.make('#')
+      .itemsUsing(async (query, ctx) => {
+        const tags = await Tag.query()
+          .where('name', 'LIKE', `%${query}%`)
+          .paginate(1, 10)
+        return tags.data.map(t => ({ id: t.slug, label: t.name }))
+      }),
+  ])
+```
+
+Static items render immediately. Async items POST to a per-form `_mentions/:provider` endpoint with the typed query and the form's render context. Async resolvers see the current user + record + parent (when inside a `Repeater` / `Builder` row).
+
+The chip serializes as `@alice` / `#performance` in HTML output and as a node attr in JSON. Your display layer chooses how to resolve / link the chip.
+
+### File attachments
+
+`attachFiles` toolbar button uploads via the panel's registered `UploadAdapter`:
+
+```ts
+RichTextField.make('body')
+  .fileAttachmentsAcceptedFileTypes(['image/*', 'application/pdf'])
+  .fileAttachmentsMaxSize(5 * 1024 * 1024)       // 5 MB cap
+  .fileAttachmentsDirectory('articles')          // sub-directory hint
+  .fileAttachmentsVisibility('public')           // adapter-dependent
+  .resizableImages()                              // drag-handle resize on images
+```
+
+The upload route also enforces `maxSize` server-side (tampered client can't bypass). Without an `UploadAdapter` registered on the panel, the `attachFiles` button silently hides — wire one with `panel.uploads({ adapter: localUpload(...) })`.
+
+### Storage format
+
+```ts
+RichTextField.make('body')
+  .storage('json')        // default: Tiptap JSON document
+  .storage('html')        // serialized HTML string
+```
+
+Use JSON for editor-round-trip fidelity (lossless across save/load). Use HTML when the column is plain `TEXT` and you don't need the editor to read it back perfectly (the editor parses HTML back but loses some node-level attrs).
+
+### Server-side rendering
+
+For display surfaces (`TextEntry`, `Column` with `.markdown()` / `.html()`), use the pure renderer:
+
+```ts
+import { renderRichTextToHtml } from '@pilotiq/tiptap'
+
+const html = renderRichTextToHtml(article.body)
+//   safe to call from any server context — no DOM, no Tiptap runtime
+```
+
+The renderer is a pure function in `src/render.ts` with zero Tiptap runtime deps — usable in workers, edge functions, etc.
+
+### Floating toolbar + slash menu
+
+These are on by default. The floating toolbar mounts on text selection with the most-used inline marks (bold / italic / link / clearFormatting); the slash menu opens cursor-anchored on `/` with groups: **Insert**, **Style**, **Format**, **Merge tags** (when set), plus any user `blocks([…])`.
+
+Both can be disabled per field:
+
+```ts
+RichTextField.make('body')
+  .floatingToolbar(false)
+  .slashCommand(false)
+```
+
+### Collab mode
+
+When the host panel's `collab` slot is wired (via `@pilotiq-pro/collab`), `RichTextField` automatically participates in record-room collaborative editing — peers see each other's cursors, edits merge via Y.js CRDT, no opt-in needed on the field itself. The pro package handles the awareness + sync wiring.
+
+## Common Pitfalls
+
+- **Forgetting `registerTiptap()` / `.plugins([tiptap()])`** — `RichTextField` form fields render as nothing because `SchemaRenderer` can't find a renderer for `fieldType: 'richtext'`. The plugin form is the recommended path; register from `AdminPanel.ts` (loads on both server + client).
+- **`Block.make('block')` collides with PM's schema GROUP** — never use the literal name `'block'`. Any other name is fine.
+- **Drag handles missing the snap-back-to-origin three steps** — if you're writing a custom block with external drag UX, the drop handler must `setNodeSelection(pos)` AND set `view.dragging` AND call `serializeForClipboard`. Missing any of the three is the snap-back bug.
+- **Mentions inside a `Repeater` / `Builder` row** need the form-state URL stamper to recognize the row-relative dotted path. The framework handles `items.0.body` (Repeater) and `blocks.0.data.body` (Builder) automatically; non-standard nesting needs manual `tagRichTextMentionUrls` walker extension.
+- **`storage('html')` loses some node-level attrs on round-trip.** HTML doesn't preserve the full Tiptap JSON node tree — custom block attrs survive (they serialize to `data-*` attributes) but ordering of marks in edge cases can change. Use `'json'` if perfect round-trip matters.
+- **`@pilotiq/tiptap` peer dep** — the package declares `@pilotiq/pilotiq` as a peer with the literal range `">=0.7.0 <1.0.0"` (not `workspace:^`). Pre-1.0 caret on workspace:^ would break on every pilotiq minor bump. devDep stays on `workspace:^` for local resolution.
+- **Tiptap module identity** — `@tiptap/core` and `@tiptap/pm` keep state on module-level singletons. Multiple copies break the editor. Add them to `resolve.dedupe` in your Vite config: `dedupe: ['@tiptap/core', '@tiptap/pm', '@tiptap/react']`.
+
+## Key Imports
+
+```ts
+import {
+  RichTextField,              // the form field
+  Block,                      // custom block primitive
+  MentionProvider,            // mention dropdown source
+  registerTiptap,             // installs the renderer (alternative to .plugins([tiptap()]))
+  renderRichTextToHtml,       // pure server-side JSON → HTML serializer
+  tiptap,                     // plugin factory for .plugins([])
+} from '@pilotiq/tiptap'
+```

package/boost/skills/pilotiq-tiptap-blocks/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: pilotiq-tiptap-blocks
+description: Custom blocks, slash menu, mentions, and toolbar customization for @pilotiq/tiptap's RichTextField — the side-panel form-in-block UX plus the pitfalls that bite when you customize beyond defaults
+license: MIT
+appliesTo:
+  - '@pilotiq/tiptap'
+trigger: defining `Block.make(...)` types for a `RichTextField`, wiring mentions / merge tags, customizing the toolbar, or touching slash-menu / drag-handle behavior
+skip: just using `RichTextField.make('body').required()` with defaults — the always-loaded `boost/guidelines.md` already covers the basic surface
+metadata:
+  author: pilotiq
+---
+
+# Pilotiq Tiptap Blocks
+
+## When to use this skill
+
+Load when you're:
+
+- Defining `Block.make(...)` types so users can insert form-driven embeds (callouts, YouTube embeds, CTAs, media cards) into a `RichTextField`
+- Wiring `MentionProvider`s — especially the async `itemsUsing` variant that hits the DB
+- Customizing the toolbar layout (`toolbarButtons`, `enableToolbarButtons`, `disableToolbarButtons`) or hiding chrome (`toolbar(false)`, `floatingToolbar(false)`, `slashCommand(false)`)
+- Debugging slash-menu keyboard behavior, drag-handle snap-back, or side-panel keyboard shortcuts (`Mod-E` / `Esc` / focus trap)
+- Opting into the non-default block primitives — `details` (collapsible), `grid` (2/3-column), `lead` / `small` size marks
+
+For just the basic `RichTextField.make('body').required().placeholder(...)` surface — the always-loaded `boost/guidelines.md` covers it. Server-side HTML rendering (`renderRichTextToHtml`) is in guidelines too.
+
+## Quick Reference
+
+| Task | Open |
+|---|---|
+| Custom blocks — `Block.make().schema([…])` form-in-block embeds, side panel UX, keyboard shortcuts (`Mod-E` / `Esc`), field-type coverage inside blocks | `rules/custom-blocks.md` |
+| Slash menu, mentions, merge tags — `MentionProvider` (static + async), `{{ merge_tag }}` chips, slash-menu groups | `rules/slash-menu-and-mentions.md` |
+| Toolbar customization + opt-in primitives — toolbar groups, `lead` / `small` / `details` / `grid`, drag-handle gotcha, node-naming pitfalls | `rules/toolbar-and-extensibility.md` |
+
+## Key concepts (load once)
+
+- **A `Block` is a form embedded in a document.** `Block.make('callout').schema([TextField, …])` registers a slash-menu entry; inserting it stamps a `pilotiqBlock` node with `attrs.blockType='callout'` + `attrs.blockData={}`; clicking **Edit** (or `Mod-E` on a selected block) opens the right-docked side panel with that schema mounted as a real pilotiq form. Edits write back into `attrs.blockData` on every keystroke — no save button.
+- **The side panel uses every pilotiq field renderer.** TagsInput / KeyValue / FileUpload (JSON-encoded), Repeater / Builder (dotted-path nested), markdown (raw source), all primitives — they all work inside a block schema because the panel snapshots `new FormData(formEl)` → `parseFormDataToNested` → per-fieldType coerce, no `FormStateProvider` mount required.
+- **Block names are discriminators.** `Block.make('callout')` registers under that string; `BlockNodeView` and `BlockSidePanel` look up the active block by that name against `RichTextField.toMeta().blocks`. **Never name a block `'block'`** — it collides with ProseMirror's schema GROUP and breaks `contentMatchAt`. Any other name is fine; the framework's own node is `pilotiqBlock` so user names are safe.
+- **Toolbar ids are forward-compatible.** Unknown ids in `.toolbarButtons([...])` are silently dropped — adding a new button id later won't break existing field configs. The recognized id union is documented in `boost/guidelines.md` (`Recognized button ids` block).
+- **`Mod-E` / `Esc` / focus trap / width memory all ship.** Mod-E opens the panel for a selected block; Esc closes; Tab/Shift-Tab cycles within (soft trap — outside clicks still work); width persists to `localStorage` under `pilotiq.tiptap.sidePanel.width` clamped `[240, 600]`.
+- **Slash menu listens capture-phase.** So does the mention menu. The side panel's Esc listener is bubble-phase + `stopPropagation` inside menus — so pressing Esc inside an open slash menu only closes the menu, not the panel.
+- **Async mentions inside Repeater / Builder rows work out of the box.** The dispatcher parses `items.0.body` (Repeater) and `blocks.0.data.body` (Builder) dotted paths and looks the leaf up against the row template. Non-standard nesting (Repeater-inside-Repeater) needs manual `tagRichTextMentionUrls` walker extension.
+
+## Examples
+
+- `playground/app/Pilotiq/Articles/Schemas/ArticleForm.ts` — `RichTextField.make('body')` with `.blocks([…])`, `.mergeTags([…])`, and a couple `MentionProvider`s.
+- `playground/app/Pilotiq/pages/BuilderDemo.ts` — heterogeneous Builder using Tiptap blocks alongside other field types.

package/boost/skills/pilotiq-tiptap-blocks/rules/custom-blocks.md

@@ -0,0 +1,90 @@
+# Custom Blocks
+
+A `Block` is a reusable, form-driven embed inside a `RichTextField` document. Users insert one via the slash menu (`/`), see an inline summary card in the editor, and edit its data in a right-docked side panel that mounts the block's schema as a real pilotiq form.
+
+This is **the** primitive that sets `@pilotiq/tiptap` apart from a plain rich-text editor — long-form documents become composable surfaces (callouts, embeds, CTAs, structured media) without leaving the form.
+
+## Defining a block
+
+```ts
+import { Block, RichTextField } from '@pilotiq/tiptap'
+import { TextField, TextareaField, SelectField } from '@pilotiq/pilotiq'
+
+Block.make('callout')                              // discriminator — see "Naming"
+  .label('Callout')                                // slash-menu display label
+  .icon('💡')                                      // emoji OR pilotiq icon registry name
+  .schema([
+    SelectField.make('variant').options({
+      info: 'Info',
+      warning: 'Warning',
+      danger: 'Danger',
+    }).default('info'),
+    TextField.make('title').required(),
+    TextareaField.make('content').required(),
+  ])
+```
+
+Attach to a field:
+
+```ts
+RichTextField.make('body')
+  .blocks([
+    calloutBlock,
+    youtubeBlock,
+    ctaBlock,
+  ])
+```
+
+Each block appears under its own slash-menu entry below the **Insert / Style / Format / Merge tags** built-in groups. The order in `.blocks([…])` is the order in the menu.
+
+## Naming — pick anything but `'block'`
+
+The block name is the discriminator stored in `attrs.blockType`. Both `BlockNodeView` and `BlockSidePanel` look up the active block against `RichTextField.toMeta().blocks` by that string.
+
+**Never use `'block'`.** Tiptap's underlying ProseMirror schema reserves the name `'block'` as a *schema GROUP* — defining a node with that name breaks `contentMatchAt` and silently corrupts the editor's content matching. Any other identifier is safe; the framework's own node type is `pilotiqBlock` so it can't collide with user blocks.
+
+Use kebab-case or camelCase: `'callout'`, `'youtube-embed'`, `'productCard'` all fine. Don't change a block's name after data exists in production — old documents will render through the unknown-block fallback path (a placeholder card preserving `attrs.blockData` verbatim — config rollbacks never lose content, but the user can't edit until the name is restored or the data is migrated).
+
+## How the side panel works
+
+When the user clicks the **Edit** button on a `BlockNodeView` (or hits `Mod-E` with a block selected):
+
+1. `BlockNodeView` calls `extension.options.onEdit(getPos())` — the callback was plumbed in via `BlockNodeExtension.configure({ onEdit })`. Tiptap mounts NodeViews in a separate React tree, so `useContext` doesn't cross that boundary — the bridge has to ride extension options.
+2. The host (`TiptapEditor`) opens `<BlockSidePanel>`, keyed on `pos:blockType` so swapping blocks fully remounts.
+3. The panel renders `<FormFields elements={block.schema} values={initialBlockData} />` inside a `<form>` — same renderers pilotiq uses everywhere else.
+4. A container-level `onChange`/`onInput` handler snapshots the **entire form**: `new FormData(formEl)` → `parseFormDataToNested(...)` (rebuilds nested arrays/objects from dotted-path inputs like `items.0.title`) → `coerceBlockValues(raw, schema)` (per-fieldType JSON parse / boolean / number coerce).
+5. The coerced object dispatches as `state.tr.setNodeMarkup(pos, null, { blockType, blockData })` directly through the editor view — every keystroke updates the document.
+6. The panel listens to every editor `transaction` and remaps its tracked `pos` so concurrent edits elsewhere in the doc don't desync. If the node disappears at the mapped pos (different type, or null), the panel closes itself.
+
+## Field-type coverage inside a block
+
+Everything in pilotiq's field catalog works inside a block. Each field serializes through hidden inputs in the form DOM, which `parseFormDataToNested` + per-fieldType coerce captures.
+
+- **Primitives:** text, textarea, select, radio, toggleButtons, date, dateTime, email, color, number, slider, toggle, checkbox.
+- **JSON-encoded:** tagsInput (`string[]`), checkboxList (`string[]`), keyValue (`Record<string, unknown>`), fileUpload (URL string, or `string[]` when `.multiple()`).
+- **Plain text:** markdown (raw markdown source — server-renders via `marked` if you display it through a `Markdown` element).
+- **Nested array fields:** repeater (array of subschema rows; each row's children coerce recursively against `field.template`) and builder (heterogeneous `{type, data}` rows; `row.data` coerces against the block matching `row.type` from `field.blocks[]`; unknown block types pass through verbatim).
+
+`coerceBlockValues(raw, schema)` is exported from `@pilotiq/tiptap` for testing — a pure helper with no DOM, no React.
+
+## Keyboard, focus, and width
+
+These all ship out of the box — don't try to wire them yourself:
+
+- **`Mod-E`** (Cmd+E on macOS / Ctrl+E elsewhere) — when the current selection is a `NodeSelection` on a `pilotiqBlock`, opens its side panel. Wired via `BlockNodeExtension.addKeyboardShortcuts()`. Returns `false` (yields to browser default) when no block is selected, so Safari's *Use Selection for Find* still works in plain text.
+- **`Esc`** closes the panel via a bubble-phase `document` listener. Slash and mention menus listen capture-phase + `stopPropagation`, so `Esc` inside an open slash menu only closes the menu — never bubbles down to the panel.
+- **Focus management.** On open, the previously focused element is captured and the first focusable inside the panel is focused. While the panel is mounted, `Tab` / `Shift+Tab` cycles within the panel's focusables (soft trap — clicks elsewhere still work). On close, the previously focused element is re-focused.
+- **Width memory.** The panel has a 1-px hover-highlighted left-edge resize handle and persists its width to `localStorage` under `pilotiq.tiptap.sidePanel.width`, clamped `[240, 600]` (default 320). The pure helper `clampPanelWidth(value)` is exported for tests; it falls back to the default for `null` / `undefined` / empty-string / non-finite values, otherwise clamps numeric strings + numbers into range.
+
+## Common authoring mistakes
+
+- **Forgetting `.schema([…])`** — a block with no schema renders as a card with no editable fields. Always declare at least one field, even if it's just `TextField.make('content')`.
+- **Reusing field names across blocks.** Each block has its own isolated schema — `Block.make('a').schema([TextField.make('title')])` and `Block.make('b').schema([TextField.make('title')])` are completely independent. Inside a single block, `name` collisions break the form like anywhere else.
+- **Mutating `blockData` directly from outside the side panel** — don't. The panel is the single writer (via `setNodeMarkup`). If you need to programmatically update a block's data, dispatch a Tiptap transaction.
+- **Async work inside a field's `live()` hook in a block.** It works, but every keystroke fires a partial-resolve to the panel's enclosing form `stateUrl`. Heavy DB queries should debounce (`.live({ debounce: 300 })`). The panel re-mounts the field on the response — keep the round-trip fast.
+
+## See also
+
+- `slash-menu-and-mentions.md` — how blocks appear in the slash menu alongside built-ins, mentions, and merge tags.
+- `toolbar-and-extensibility.md` — toolbar customization, drag-handle gotcha, opt-in primitives (`details`, `grid`, `lead` / `small`).
+- Pilotiq side: [[pilotiq-fields]] (`pilotiq-fields/rules/field-catalog.md`) for the inner-field types you can use inside `Block.schema([…])`.

package/boost/skills/pilotiq-tiptap-blocks/rules/slash-menu-and-mentions.md

@@ -0,0 +1,101 @@
+# Slash Menu, Mentions, and Merge Tags
+
+Three closely-related surfaces share the same editor real estate — the cursor-anchored popover menu. Slash menu opens on `/`; mention dropdowns open on a configurable trigger char (`@`, `#`, etc.); merge tags surface as a *group within* the slash menu rather than their own dropdown.
+
+## Slash menu (`/`)
+
+Type `/` at the start of a line (or in an otherwise-empty inline position) to open the slash menu. The menu groups, in order:
+
+1. **Insert** — paragraph, headings, lists, code block, blockquote, horizontal rule, plus opt-in primitives (`details`, `Two-column grid`, `Three-column grid`) when enabled in toolbar/slash config.
+2. **Style** — text-size marks (`lead`, `small`), text color, highlight (when those buttons are in the active toolbar).
+3. **Format** — alignment options (when alignment buttons are in the toolbar).
+4. **Merge tags** — every id in `.mergeTags([…])`. Selecting one inserts a `{{ id }}` chip.
+5. **User blocks** — one entry per `Block` in `.blocks([…])`, in declaration order. Each shows the block's `.icon(…)` + `.label(…)`.
+
+Disable the slash menu per-field:
+
+```ts
+RichTextField.make('body').slashCommand(false)
+```
+
+### Slash menu internals (relevant when debugging)
+
+- `SlashCommandExtension.ts` registers a Tiptap `Suggestion` plugin that listens on document-level **capture-phase** key events. Capture-phase is intentional — it has to win against any bubble-phase handlers in surrounding code (including the side panel's `Esc` listener — see `custom-blocks.md` § Keyboard).
+- The menu mounts as a Base UI Popover anchored to a virtual element at the caret position. Cursor anchoring means the menu follows the user's typing position even mid-line, but it also means autoplacement / flip logic can collide with other Base UI popovers — see [[feedback-baseui-popover-cursor-anchor]] for the established pattern.
+- Items derive from `extension.options.blocks` plus the framework's built-ins. The blocks array is plumbed at editor mount and updated when the field's meta changes.
+
+## Mentions (`@`, `#`, custom triggers)
+
+`MentionProvider` powers @-mention dropdowns. Each provider has a single trigger char and a static or async item resolver:
+
+```ts
+import { RichTextField, MentionProvider } from '@pilotiq/tiptap'
+
+RichTextField.make('body')
+  .mentions([
+    MentionProvider.make('@')
+      .items([
+        { id: 'alice', label: 'Alice', subtitle: 'Engineering' },
+        { id: 'bob',   label: 'Bob',   subtitle: 'Design' },
+      ]),
+
+    MentionProvider.make('#')
+      .itemsUsing(async (query, ctx) => {
+        const tags = await Tag.query()
+          .where('name', 'LIKE', `%${query}%`)
+          .paginate(1, 10)
+        return tags.data.map(t => ({ id: t.slug, label: t.name }))
+      }),
+  ])
+```
+
+### Item shape
+
+```ts
+{
+  id:        string         // required — what serializes in the chip
+  label:     string         // required — what the user sees
+  subtitle?: string         // optional — second line in the dropdown
+  icon?:     string         // optional — pilotiq icon registry name
+}
+```
+
+The chip serializes to HTML as `@alice` / `#performance` text (the literal trigger + id) and to JSON as a node attr — your render-time substitution layer chooses how to resolve the chip (link, badge, lookup, etc).
+
+### Static vs async
+
+- **`.items([…])`** — synchronous, renders immediately when the trigger char is typed. Best for small, static sets (status labels, sentiment markers).
+- **`.itemsUsing(async (query, ctx) => …)`** — POSTs to a per-form `_mentions/:provider` endpoint with the typed query string and the form's render context. Async resolvers see `ctx.user`, `ctx.record`, `ctx.parent` (when inside a `Repeater` / `Builder` row), so you can scope results to the current panel/record/row.
+
+Async items go through `pageData.findRichTextFieldByName(form, dottedName)` to resolve which `MentionProvider` matches the request. The dotted path the editor posts is row-relative when the field is inside an array row (`items.0.body` for Repeater, `blocks.0.data.body` for Builder). The dispatcher walks the appropriate template — both shapes are first-class.
+
+### Mentions inside Repeater / Builder rows
+
+Works out of the box for the standard nesting. The stamper (`tagRichTextMentionUrls`) walks Builder block schemas explicitly because `BuilderField.getChildren()` returns `undefined` to keep generic field walkers from treating heterogeneous rows as flat children — see [[project-pilotiq-builder]] for the broader walker pattern.
+
+**Non-standard nesting** (Repeater-inside-Repeater, custom container) needs a manual `tagRichTextMentionUrls` walker extension — there's no automatic depth recursion yet. Confirm a request works end-to-end by submitting a mention from inside the nested row and checking the network panel for a 200 on the `_mentions/:provider` endpoint.
+
+## Merge tags (`{{ id }}`)
+
+For server-side substitution placeholders — typically email templates, document templates, transactional content where you write text like `Hi {{ firstName }}` and the rendering layer substitutes at send time:
+
+```ts
+RichTextField.make('body')
+  .mergeTags(['firstName', 'lastName', 'company', 'unsubscribeUrl'])
+```
+
+Each id surfaces under the **Merge tags** group of the slash menu and inserts a `{{ id }}` chip. The chip serializes verbatim as `{{ firstName }}` literal text in HTML output — your downstream substitution (mail send, doc generation) handles the actual replacement.
+
+Difference from mentions: merge tags are a fixed set known at form-definition time, no DB lookup, no user search. Use mentions when the set is dynamic (users, tags, records); use merge tags when it's a closed enum of template variables.
+
+## Pitfalls
+
+- **Async mention failures** — if `itemsUsing` throws, the dropdown shows an empty result silently. Wrap risky DB calls in try/catch and return `[]` on error if you'd rather not surface server logs to the user; or let the request 500 and the dropdown will degrade gracefully.
+- **Trigger char collision** — `@` and `#` are common; `:` collides with emoji shortcodes if you also wire those upstream. Pick something unambiguous when adding custom triggers (`+` for assignees, `&` for accounts).
+- **`mentions([…])` resets on every meta resolve** — providers are recreated server-side every time the form re-resolves. Don't store mutable state inside a `MentionProvider` instance; treat it as a value object.
+- **Capture-phase keys.** If you mount your own keyboard handler near the editor and it doesn't fire when the slash or mention menu is open, that's by design — the menus stop propagation on capture. To handle keys that pass through, listen on the editor's `view.dom` directly rather than at `document`.
+
+## See also
+
+- `custom-blocks.md` — how `Block.make(...)` entries land in the slash menu's user-blocks section.
+- `toolbar-and-extensibility.md` — how toolbar config affects which Style / Format groups appear in the slash menu (slash entries are derived from active toolbar buttons).