@ecsplico/editor 0.0.0-stage → 2.0.0

package/docs/extending.md

@@ -0,0 +1,538 @@
+# Extending guide: own blocks
+
+How to add a block of your own to an editor of this package, using one running example: the **„Hinweis“ block** (`callout`, attribute `tone` = `info` | `warning` | `success`). The example exists twice on purpose, so each runnable app is self-contained; both copies are identical:
+
+| Copy | Files | Used by |
+|---|---|---|
+| Simple playground | [`examples/vue-simple/src/callout/`](../../../examples/vue-simple/src/callout) — `node.ts`, `CalloutView.vue`, `index.ts`, `callout.css` | Path A, wired in [`examples/vue-simple/src/App.vue`](../../../examples/vue-simple/src/App.vue) |
+| Advanced playground | [`app/editor/callout/`](../../../app/editor/callout) — the same four files plus `feature.ts` and `convert.ts` | Path B, Editor B of [`app/pages/playground.vue`](../../../app/pages/playground.vue) |
+
+Every snippet below is copied from these files. Start the apps with `bun run --cwd examples/vue-simple dev` (port 3040) and `bun run dev` (port 3031, page `/playground`, see the [usage guide](./usage.md#advanced-nuxt-example)). UI strings of the examples are German, the code and this guide are English.
+
+- [Two ways to add a block](#two-ways-to-add-a-block)
+- [Anatomy of a block the editor understands](#anatomy-of-a-block-the-editor-understands)
+- [Path A: `extensions` and `slashCommands`](#path-a-extensions-and-slashcommands)
+- [Path B: a feature](#path-b-a-feature)
+- [Beyond the browser](#beyond-the-browser)
+- [Checklist](#checklist)
+
+---
+
+## Two ways to add a block
+
+| | Path A: props | Path B: a feature |
+|---|---|---|
+| What you write | A TipTap node, plus a `slashCommands` function | An `EditorFeature` (`id`, `extensions`, `toolbar`, `slashCommands`, `blockActions`, `conversions`, …) |
+| Where it plugs in | The `extensions` and `slashCommands` props of `SimpleEditor`, `AdvancedEditor` or `EditorSurface` | A preset: `defineEditor({ features: [...] })` mounted with `EditorSurface` |
+| You get | The node in the schema, its commands, input rules and shortcuts, its Markdown form, a `/` menu entry, block IDs when the node declares `editorBlock` | Everything of Path A, plus a toolbar button, ability-gated `/` entries, hover actions, „Umwandeln in …“ targets and a `requires` check of the features it builds on |
+| You do not get | A toolbar button, hover actions, conversion targets: the toolbar renders what features contribute | — |
+| Runnable | Simple playground (`SimpleEditor` + `CalloutBlock`) | Advanced playground, Editor B (`advancedEditor().features` + `calloutFeature()`) |
+
+Both paths share the same node. Start with Path A; move to Path B when the block needs toolbar, hover or conversion. Props are read **once at setup** (`extensions`, `slashCommands`, `abilities`): pass constants, or remount with a new `key`.
+
+## Anatomy of a block the editor understands
+
+### The node
+
+`node.ts` is the complete, Vue-free definition: schema, commands, shortcut and Markdown form. It imports only `@tiptap/core` and the Vue-free `@ecsplico/editor/core/schema`, so a server can import it without loading a component.
+
+```ts
+import { mergeAttributes, Node } from '@tiptap/core'
+import { ABILITY } from '@ecsplico/editor/core/schema'
+
+// Vue-free and server-importable: the callout's schema, commands and Markdown form. The Vue node view is attached in
+// `index.ts`, so a server (`getSchema([...advancedSchemaExtensions(), Callout])`, or the simple schema) never loads a
+// component.
+
+export type Tone = 'info' | 'warning' | 'success'
+
+export const TONES: readonly { value: Tone, label: string, icon: string }[] = [
+  { value: 'info', label: 'Hinweis', icon: 'i-lucide-info' },
+  { value: 'warning', label: 'Warnung', icon: 'i-lucide-triangle-alert' },
+  { value: 'success', label: 'Erledigt', icon: 'i-lucide-circle-check' },
+]
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    callout: {
+      /** Wrap the selected blocks in a callout of `tone` (default `info`). */
+      setCallout: (tone?: Tone) => ReturnType
+      /** Wrap the selection in a callout, or lift it out when it already is inside one. */
+      toggleCallout: () => ReturnType
+      /** Change the tone of the callout around the selection. */
+      setCalloutTone: (tone: Tone) => ReturnType
+    }
+  }
+}
+
+export const Callout = Node.create({
+  name: 'callout',
+  group: 'block',
+  content: 'block+',
+  defining: true,
+  // Carries a block ID like a paragraph: block flash/reveal, paste de-duplication, the server's ID backfill.
+  editorBlock: true,
+  // A callout holds plain text blocks: no headings, composites, media, records or speaker lines inside it.
+  abilities: {
+    revokes: [ABILITY.headings, ABILITY.composite, ABILITY.media, ABILITY.record, ABILITY.transcript],
+  },
+  addAttributes: () => ({
+    tone: {
+      default: 'info',
+      parseHTML: el => el.getAttribute('data-tone') ?? 'info',
+      renderHTML: attrs => ({ 'data-tone': attrs.tone }),
+    },
+  }),
+  parseHTML: () => [{ tag: 'div[data-type="callout"]' }],
+  renderHTML: ({ HTMLAttributes }) => ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'callout' }), 0],
+
+  // Markdown: `!!! <tone>` followed by the body up to the next blank line. `:::` belongs to composites. The body blocks
+  // are joined by a single newline (without a separator `renderChildren` would glue them: „text- item“), so a body
+  // with several paragraphs reads back as one; a blank line would end the callout for the tokenizer below.
+  renderMarkdown: (node, h) => `!!! ${node.attrs?.tone ?? 'info'}\n${h.renderChildren(node.content ?? [], '\n')}`,
+  markdownTokenName: 'callout',
+  markdownTokenizer: {
+    name: 'callout',
+    level: 'block',
+    start: src => src.indexOf('!!! '),
+    tokenize(src, _tokens, lexer) {
+      const match = /^!!! (info|warning|success)\n([\s\S]+?)(?:\n{2,}|$)/.exec(src)
+      if (!match) return
+      return { type: 'callout', raw: match[0], tone: match[1], tokens: lexer.blockTokens(match[2]!) }
+    },
+  },
+  parseMarkdown: (token, h) => h.createNode('callout', { tone: typeof token.tone === 'string' ? token.tone : 'info' }, h.parseChildren(token.tokens ?? [])),
+
+  addCommands() {
+    return {
+      setCallout: tone => ({ commands }) => commands.wrapIn(this.name, { tone: tone ?? 'info' }),
+      toggleCallout: () => ({ editor, commands }) =>
+        editor.isActive(this.name) ? commands.lift(this.name) : commands.wrapIn(this.name, { tone: 'info' }),
+      setCalloutTone: tone => ({ commands }) => commands.updateAttributes(this.name, { tone }),
+    }
+  },
+  addKeyboardShortcuts() {
+    // Mod-Alt-c is the code block; Mod-Shift-s / -m / -k belong to the transcript, mention and tag features.
+    return { 'Mod-Shift-h': () => this.editor.commands.toggleCallout() }
+  },
+})
+```
+
+### Fields the library reads
+
+Besides the plain TipTap fields (`name`, `group`, `content`, `defining`, `addAttributes`, `parseHTML`/`renderHTML`, commands, shortcuts) the package reads these `NodeConfig` fields:
+
+| Field | Read by | Meaning |
+|---|---|---|
+| `editorBlock` | `NodeFlags` (copies it to the `NodeSpec`) in [`src/core/schema/node-flags.ts`](../src/core/schema/node-flags.ts), `BlockId` in [`block-ids.ts`](../src/core/schema/block-ids.ts) | The node is an addressable block: it gets the `id` attribute (rendered `data-id`) the built-in blocks have. Block IDs are what block flash and reveal look up (`findBlockById`), what paste de-duplication and the server's ID backfill (`assignBlockIds`) iterate, and what the AI chat addresses: a text block with an ID is a `[<id>] …` line of the chat's document view and can be updated, deleted, extended or converted by that ID, and quotes in answers link to it. **Built-in block types default to `true`** (`BLOCK_ID_TYPES`); every other node defaults to `false` and then has no `id` attribute. `isEditorBlock(node)` (from `@ecsplico/editor/core/schema`) reads the flag. |
+| `editorBlockContainer`, `editorChrome` | `NodeFlags`, block conversion and drag targeting | A *container* (the document, a composite) holds blocks that are individually convertible and draggable; *chrome* is fixed header rows of such a block. The callout declares neither: it is one block, its inner paragraphs are not offered separately. |
+| `abilities` | the `Abilities` extension (`AbilityRule`: `grants`, `revokes`, `own`) | What editing abilities hold inside the node. The callout revokes headings, composites, media, recording and speaker lines for its content. Ability ids are plain strings; host rules passed through the `abilities` prop replace a node's own rule (see [Path B](#composing-and-mounting) for granting a custom ability). |
+| `renderMarkdown`, `markdownTokenName`, `markdownTokenizer`, `parseMarkdown` | `@tiptap/markdown` | The Markdown form of the block, in both directions. |
+
+**Why `!!!`.** The Markdown form is the form the model reads and writes, and the one `getMarkdown()` exports (see [Beyond the browser](#ai)). Pick syntax that no other stage claims: `:::` fences belong to composites, `**Name:**` lines are turned into speaker segments by the transcript feature's `segment` stage.
+
+**Limitation of this example.** `renderMarkdown` joins the body blocks with `'\n'` and the tokenizer ends a callout at the first blank line. A callout with several paragraphs therefore exports without blank lines and re-imports as **one** paragraph. Keep callouts to one paragraph when the Markdown round trip matters, or extend the tokenizer.
+
+### Node view and styles
+
+The node view is attached in a second file, so `node.ts` stays free of Vue:
+
+```ts
+import type { NodeViewRenderer } from '@tiptap/core'
+import { VueNodeViewRenderer } from '@tiptap/vue-3'
+import CalloutView from './CalloutView.vue'
+import { Callout } from './node'
+
+export { Callout, TONES, type Tone } from './node'
+
+// The schema node plus its Vue node view; node.ts stays Vue-free so a server can import it on its own.
+export const CalloutBlock = Callout.extend({
+  // Explicit return type: keeps the declaration independent of the Vue view's inferred types.
+  addNodeView(): NodeViewRenderer {
+    return VueNodeViewRenderer(CalloutView)
+  },
+})
+```
+
+On a React surface the same second file attaches `ReactNodeViewRenderer(CalloutView)` from `@tiptap/react` instead; `node.ts` stays unchanged and framework-free.
+
+The view renders a non-editable header (tone icon and a `USelect`) above the editable body:
+
+```vue
+<script setup lang="ts">
+import { NodeViewContent, nodeViewProps, NodeViewWrapper } from '@tiptap/vue-3'
+import { computed } from 'vue'
+import { type Tone, TONES } from './node'
+
+const props = defineProps(nodeViewProps)
+
+const tone = computed(() => TONES.find(t => t.value === props.node.attrs.tone) ?? TONES[0])
+</script>
+
+<template>
+  <NodeViewWrapper as="div" class="callout" :data-tone="node.attrs.tone">
+    <div class="callout-header" contenteditable="false">
+      <UIcon :name="tone?.icon ?? 'i-lucide-info'" class="size-4 shrink-0" />
+      <USelect
+        :items="[...TONES]"
+        value-key="value"
+        label-key="label"
+        :model-value="node.attrs.tone"
+        size="xs"
+        variant="ghost"
+        :disabled="!editor.isEditable"
+        @update:model-value="(value: Tone) => updateAttributes({ tone: value })"
+      />
+    </div>
+    <NodeViewContent as="div" class="callout-body" />
+  </NodeViewWrapper>
+</template>
+```
+
+The styles are plain CSS with Nuxt UI's colour variables. Import them **after** the core stylesheet:
+
+```css
+.callout {
+  --callout-color: var(--ui-info);
+  border-left: 3px solid var(--callout-color);
+  border-radius: 0.375rem;
+  padding: 0.5rem 0.75rem;
+  margin: 0.5rem 0;
+  background: color-mix(in oklab, var(--callout-color) 8%, transparent);
+}
+```
+
+Simple playground, [`examples/vue-simple/src/style.css`](../../../examples/vue-simple/src/style.css):
+
+```css
+@import "tailwindcss";
+@import "@nuxt/ui";
+@import "@ecsplico/editor/styles/core.css";
+@import "./callout/callout.css";
+@source "../../../packages/editor/src";
+```
+
+Nuxt app, [`app/assets/css/main.css`](../../../app/assets/css/main.css):
+
+```css
+@import "../../editor/callout/callout.css";
+```
+
+The full stylesheet (tone variables per `[data-tone]`, header and body spacing) is [`callout.css`](../../../examples/vue-simple/src/callout/callout.css).
+
+## Path A: `extensions` and `slashCommands`
+
+The simple playground adds the node to a `SimpleEditor` with two props. The same props exist on `AdvancedEditor` and `EditorSurface`.
+
+```ts
+// Added to the simple schema through the `extensions` prop (constant: read once at setup).
+const extensions = [CalloutBlock]
+
+// Host commands of the `/` menu: the simple editor ships none.
+function slashCommands(defaults: SlashCommandItem[]): SlashCommandItem[] {
+  return [
+    ...defaults,
+    {
+      id: 'datum',
+      label: 'Datum',
+      icon: 'i-lucide-calendar',
+      run: editor => editor.chain().focus().insertContent(new Date().toLocaleDateString('de-DE')).run(),
+    },
+    {
+      id: 'hinweis',
+      label: 'Hinweis',
+      icon: 'i-lucide-info',
+      run: editor => editor.chain().focus().setCallout('info').run(),
+    },
+  ]
+}
+```
+
+```vue
+            <SimpleEditor
+              :model-value="content"
+              :editable="editable"
+              :extensions="extensions"
+              :slash-commands="slashCommands"
+              @ready="onReady"
+              @update:model-value="onUpdate"
+              @content-error="onContentError"
+            />
+```
+
+What the user gets:
+
+- Typing `/hinweis` Enter wraps the paragraph at the caret in an `info` callout; `Mod-Shift-h` toggles it (wrap, or lift out of the callout).
+- The tone `USelect` in the callout's header changes `attrs.tone`; the JSON pane then shows the new tone and the Markdown pane the matching `!!! success` line.
+- Nodes with `editorBlock: true` get an `id`: the JSON pane shows `editor.getJSON()` (not the `v-model` value) so you can see the IDs the editor adds.
+- The `/` entry has no `ability`, so it is listed wherever the `/` menu opens. A toolbar button needs Path B: the toolbar renders what features contribute and a prop cannot add to it.
+
+The simple editor rejects documents with unknown nodes, so the callout sample (`callouts` in [`samples.ts`](../../../examples/vue-simple/src/samples.ts)) loads only because `CalloutBlock` is in the schema. Content with `composite` still ends up in `contentError` ([usage guide](./usage.md#rejected-content-contenterror)).
+
+## Path B: a feature
+
+A feature is a bundle of contributions behind one `id`; the callout feature fills six of them. [`app/editor/callout/feature.ts`](../../../app/editor/callout/feature.ts) in full:
+
+```ts
+import { commandItem, type EditorFeature } from '@ecsplico/editor/core'
+import { calloutConversions } from './convert'
+import { CalloutBlock } from './index'
+import { TONES } from './node'
+
+/** The ability that gates the callout's toolbar button, `/` command and hover menu; grant it at root through the `abilities` prop. */
+export const CALLOUT_ABILITY = 'insert.callout'
+
+/**
+ * The callout as a full editor feature: node, toolbar button (merged into the `inserts` group beside „Sprecherblock“),
+ * `/hinweis`, a hover menu for the tone, the two-way „Umwandeln in …“ conversion and its description for the AI
+ * (`aiContext.blocks`), so chat and generate tasks can create, convert to and edit callouts.
+ */
+export function calloutFeature(): EditorFeature {
+  return {
+    id: 'callout',
+    extensions: () => [CalloutBlock],
+    toolbar: () => [{
+      id: 'inserts',
+      order: 50,
+      items: [
+        commandItem({
+          id: 'callout',
+          order: 15,
+          icon: 'i-lucide-info',
+          label: 'Hinweis',
+          kbds: ['meta', 'shift', 'h'],
+          ability: CALLOUT_ABILITY,
+          command: c => c.toggleCallout(),
+          isActive: e => e.isActive('callout'),
+        }),
+      ],
+    }],
+    slashCommands: () => [{
+      id: 'hinweis',
+      label: 'Hinweis',
+      icon: 'i-lucide-info',
+      ability: CALLOUT_ABILITY,
+      run: e => e.chain().focus().setCallout('info').run(),
+    }],
+    blockActions: () => [{
+      id: 'callout-tone',
+      label: 'Art des Hinweises',
+      icon: 'i-lucide-palette',
+      ability: CALLOUT_ABILITY,
+      order: 500,
+      isVisible: ({ node }) => node.type.name === 'callout',
+      menu: ({ editor, pos }) => TONES.map(tone => ({
+        label: tone.label,
+        icon: tone.icon,
+        onSelect: () => editor.chain().focus().setNodeSelection(pos).setCalloutTone(tone.value).run(),
+      })),
+    }],
+    conversions: [calloutConversions],
+    aiContext: () => ({
+      blocks: [{
+        id: 'callout',
+        label: 'Hinweis',
+        description: 'Ein farbig hervorgehobener Kasten für einen Hinweis (info), eine Warnung (warning) oder etwas Erledigtes (success). Enthält Absätze, Listen oder Zitate, keine Überschriften.',
+        syntax: '!!! <info|warning|success>\n<Inhalt, Blöcke durch einen Zeilenumbruch getrennt; eine Leerzeile beendet den Hinweis>',
+        example: '!!! warning\nBitte die Zahlen vor dem Versand prüfen.',
+      }],
+    }),
+  }
+}
+```
+
+Every contribution is a factory or descriptor; features only differ by which of them they fill (`EditorFeature` in [`src/core/feature.ts`](../src/core/feature.ts)). Nothing is registered globally. The descriptors are framework-free: the slots that hold a UI component (`overlays`, `SettingsTab.component`, `ToolbarItem.component`) are generic, `EditorFeature<C>` / `EditorPreset<C>`, where `C` is the framework's component type. A feature with Vue components is a `VueFeature` (`EditorFeature<Component>`, from `@ecsplico/editor/vue`), one with React components a `ReactFeature` (from `@ecsplico/editor/react`); the callout fills none of these slots, so it keeps the default `EditorFeature` and fits a Vue and a React list alike. The package's own features follow one split: `features/<x>/feature.ts` exports `<x>FeatureCore(ui)`, which fills every member with the logic and takes the components as a typed `<X>Ui<C>` object; `/<x>/vue` and `/<x>/react` call it with their components ([integration guide §1](./integration.md#per-feature-entries-framework-free-vue-react)). A feature of your own that needs components in both frameworks can use the same split.
+
+### `extensions`
+
+`extensions: () => [CalloutBlock]` adds the node (with its view) to the editor's schema. Feature extensions are added in feature order, before the `extensions` prop. The factory receives a `FeatureContext` (`app`, settings, metadata registry, `ui`, `notify`, `fetch`, `abilities`, …) that the callout does not need. `ctx.settings` is a framework-free store, not a Vue ref: read it with `ctx.settings.get()`, change it with `ctx.settings.update(s => { s.ai.autocomplete = !s.ai.autocomplete })` (or `set(value)`), react to changes with `ctx.settings.subscribe(listener)` (returns the unsubscribe function). `ctx.notify({ title, kind? })` shows a notice (a Nuxt UI or sonner toast, depending on the surface); features never import a toast library.
+
+### `toolbar`
+
+Return `ToolbarGroup`s; `EditorToolbar` (`@ecsplico/editor/vue` or `/react`) merges groups of the same `id` with `mergeToolbarGroups` (`@ecsplico/editor/core`): the **first** group of an id keeps its position and `order`, the items of all contributors are concatenated and sorted by `order`. The callout adds its button to the `inserts` group that the transcript feature (speaker button, `order: 10`) and the media feature (pickers, `order` 20–50) already fill, so `order: 15` puts „Hinweis“ between „Sprecherblock“ and the media buttons.
+
+`commandItem` builds a button from a command chain: it focuses the editor on click, runs `command`, and disables the button while `editor.can().chain()` says the command is impossible. `isActive` makes it a toggle. `ability` disables the button where the caret does not hold that ability (turning an active toggle off never needs it). `kbds` only labels the tooltip: the shortcut itself is the node's `addKeyboardShortcuts`.
+
+A toolbar item that opens a dropdown sets `menu: (editor) => MenuItem[]`. `MenuItem` is the core type (`@ecsplico/editor/core`), not Nuxt UI's `DropdownMenuItem`: `type?: 'label' | 'separator'`, `label`, `description`, `icon` (an Iconify name such as `i-lucide-heading-1`), `disabled` and `onSelect`. It carries no UI-framework type; the framework layer renders it.
+
+### `slashCommands`
+
+Entries of the `/` menu in feature order, run through the host's `slashCommands` transformer last. `ability` limits the entry to carets that hold it; unset means always listed. `run` is called after the `/query` text is deleted.
+
+### `blockActions`
+
+Hover actions on a block's top line at the editor's right edge, shown by an installed `block-ui` feature (`blockUiFeature()`; the advanced list has it). `ability` is checked on the block itself, `isVisible` narrows it further, `order` sorts feature actions (built-ins use their visual sequence; actions with a larger `order`, like the callout's 500, follow them; host `blockActions` props come last). With `menu` instead of `run` the action opens a dropdown; `menu` returns core `MenuItem[]` (`type?: 'label' | 'separator'`, `label`, `description`, `icon`, `disabled`, `onSelect`), as in the toolbar. The callout's lists the tones and applies one with `setCalloutTone` after selecting the block (`setNodeSelection(pos)`). The bar is hidden while the editor is read-only.
+
+### `conversions`
+
+„Umwandeln in …“ (hover menu, toolbar groups, the AI `convert` operation) runs through `ConversionProvider`s. [`convert.ts`](../../../app/editor/callout/convert.ts) in full:
+
+```ts
+import type { Node as PMNode } from '@tiptap/pm/model'
+import {
+  childrenOf,
+  type ConversionProvider,
+  CORE_TARGET_IDS,
+  convertCoreBlocks,
+  type ConvertTarget,
+  createConverter,
+  finishConversion,
+  isCoreSource,
+  parseCoreTarget,
+} from '@ecsplico/editor/core'
+
+const CALLOUT = 'callout'
+// A host block names itself with the inert `custom` target: `id` is the target id and the node type name.
+const TARGET: ConvertTarget = { type: 'custom', id: CALLOUT }
+/** The core targets a callout unwraps into. */
+const UNWRAP_TARGETS: readonly ConvertTarget[] = CORE_TARGET_IDS.flatMap(id => parseCoreTarget(id) ?? [])
+
+const isCallout = (node: PMNode) => node.type.name === CALLOUT
+
+/**
+ * Paragraphs, headings, code blocks, lists and quotes become a callout (the quote rule: textblocks turn into
+ * paragraphs, lists and quotes keep their blocks); a callout unwraps into every core target through the core engine.
+ * `handlesSource` makes this provider execute every conversion of a callout, the core provider has none for it.
+ */
+export const calloutConversions: ConversionProvider = {
+  handlesSource: isCallout,
+  targets: (_editor, node) => {
+    const { nodes } = node.type.schema
+    if (isCallout(node)) return UNWRAP_TARGETS.filter(target => nodes[target.type])
+    return isCoreSource(node) && nodes[CALLOUT] ? [TARGET] : []
+  },
+  parseTarget: id => id === CALLOUT ? TARGET : null,
+  label: target => target.type === 'custom' && target.id === CALLOUT ? { label: 'Hinweis', icon: 'i-lucide-info' } : null,
+  convert: (state, $start, target) => {
+    const node = $start.nodeAfter
+    const { schema } = state
+    if (!node) return null
+    let output: PMNode[] | null
+    if (isCallout(node)) {
+      const children = childrenOf(node)
+      output = convertCoreBlocks(schema, children, target) ?? children
+    }
+    else if (target.type === 'custom' && target.id === CALLOUT && schema.nodes[CALLOUT] && isCoreSource(node)) {
+      const quote = createConverter(schema).toQuote([node])[0]
+      output = quote ? [schema.nodes[CALLOUT].create({ tone: 'info' }, quote.content)] : null
+    }
+    else return null
+    const blocks = output && finishConversion([node], output)
+    return blocks ? { from: $start.pos, to: $start.pos + node.nodeSize, blocks } : null
+  },
+}
+```
+
+The rules a provider follows (`ConversionProvider` in [`src/core/feature.ts`](../src/core/feature.ts), engine in [`src/core/block-convert.ts`](../src/core/block-convert.ts) and [`convert.ts`](../src/core/convert.ts)):
+
+- **The `custom` target.** `ConvertTarget` is a closed union of inert descriptors; `{ type: 'custom', id, attrs? }` is the member for host blocks. `id` is both the target id (`convertTargetId`) and the node type name; `attrs`, when given, must match for a node to count as already being that target (`isCurrentTarget`). The core engine never executes a `custom` target.
+- **Ownership.** The provider whose `parseTarget(id)` returns the target owns it (labels through `label`, execution through `convert`). A target id offered by two providers throws; so does asking for the label of a target no provider owns.
+- **`handlesSource`.** The first provider that claims a source block executes *every* conversion of it. The callout claims callouts, so unwrapping into a paragraph or a list runs here, reusing the core engine (`convertCoreBlocks`). Without a claim, the target's owner executes.
+- **Helpers for your `convert`.** `createConverter(schema)`, `convertCoreBlocks`, `childrenOf`, `isCoreSource`, `CORE_TARGET_IDS`, `parseCoreTarget` and `finishConversion` (carries block IDs and checks the result) are exported from `@ecsplico/editor/core`. Return `null` for "not possible"; the result must fit its parent (`canReplace`), so a callout is only offered where one may stand. A composite is not converted into a callout: the callout provider offers targets only for core sources and callouts.
+- **One transaction.** A conversion is one undo step.
+
+### `aiContext`
+
+`aiContext: () => ({ blocks: [...] })` tells the model that the block exists, what it is for and how to write it. Contributions of all features add up; the fields, the merge rules and what chat and generate tasks do with them are described under [AI](#ai).
+
+### `aiBlockData`
+
+`aiBlockData: ({ editor, node, pos, signal }) => AiBlockDatum[] | Promise<AiBlockDatum[]>` supplies material for one Baustein (examples, a record) before „Baustein füllen (KI)“ asks the model. All contributions run in parallel and concatenate in feature order (`aiBlockDataOf(editor)`); one rejection cancels the fill with the notice „Daten für den Baustein fehlen“. The library only collects and caps (10 entries, `AI_LIMITS.block.data` characters each); the fetch belongs to the feature, and `signal` aborts it with the editor. See the Epikrise host feature in `app/editor/epikrise/feature.ts`, which fetches examples from `server/api/playground/epikrise-examples.get.ts` for one kind and returns `[]` for others.
+
+### `setup`
+
+`setup: (ctx) => void | (() => void)` runs when a surface mounts: `EditorSurface` (Vue and React) calls it once per mounted surface for every feature that has it, so a feature can start per-app side effects (a runtime, a document-level listener, a `<head>` element). The **teardown** it returns runs when that surface unmounts; do not rely on `onScopeDispose` or an effect cleanup, the framework layer owns that. It runs once per surface, so state shared by several surfaces of one app belongs in a per-app registry that dedupes inside and reference-counts its release (`startObsidianTheme(ctx)` keys per app, starts once and returns its idempotent release, so React's double mount in StrictMode leaves one runtime). `ctx.app` is the key for such a registry. The Vue `themesFeature()` additionally keeps the runtime for the life of the Vue app through its `lifetime` hook (the theme styles the whole site, so navigating to a page without an editor keeps it), the React one releases it with the last surface. `themesFeature()` puts `obsidian-theme theme-dark|theme-light` on `<html>`.
+
+### Composing and mounting
+
+The advanced list plus your feature; the same preset feeds the toolbar and the settings popup (`EditorSettingsModal :preset`), and the surface mounts it:
+
+```ts
+// The advanced feature list plus the host's own feature; the same preset feeds the toolbar and the settings panel.
+const presetB = defineEditor({ features: [...advancedEditor().features, calloutFeature()] })
+```
+
+```ts
+// The custom ability must be granted at document root, or the callout's toolbar button, `/hinweis` and hover menu stay hidden.
+const abilitiesB: Partial<AbilitiesOptions> = { root: [...ROOT_ABILITIES, CALLOUT_ABILITY] }
+```
+
+```vue
+          <EditorSurface
+            v-model="paneB.content"
+            v-model:sidebar-open="paneB.sidebarOpen"
+            :preset="presetB"
+            :abilities="abilitiesB"
+            settings-ui="external"
+            :editable="paneB.editable"
+            @ready="onReady(paneB, $event)"
+            @update:model-value="onUpdate(paneB, $event)"
+            @settings-open="showSettings(paneB, $event)"
+          />
+```
+
+- **Order is order.** `defineEditor` keeps the given order: toolbar groups, menu entries and the schema follow it. A feature that is not in the list contributes nothing; a smaller list works too (`defineEditor({ features: [coreFeature(), calloutFeature()] })`; add `blockUiFeature()` for the hover actions).
+- **Grant a custom ability.** Items gated by your own ability id are inert until the ability exists at the caret. Root abilities come from the `abilities` prop (`{ root: [...ROOT_ABILITIES, CALLOUT_ABILITY] }`, `ROOT_ABILITIES` from `@ecsplico/editor/core/schema`); per-node rules go in `rules`, or in the node's own `abilities`. Without the grant, Editor B's toolbar button is disabled and `/hinweis` and the hover menu are missing.
+- **Build the preset once.** Build it in `<script setup>` (or a React `useState`/`useMemo`): the preset is read once at mount, like every prop of the surface. Features need no component setup except the Vue `themesFeature()` (it hooks the Vue app's lifetime, so call `advancedEditor()` during component setup); `aiFeature()` takes its model profiles from the app context (`modelProfiles(ctx.app)`).
+- **`requires`.** Name features your feature builds on with `requires: ['block-ui']`: `defineEditor` throws at composition time (and `bun run check:editor-composition` keeps that behaviour) when one is missing, instead of a button silently not appearing. The callout does not declare it because it works without hover actions. The built-in examples: `commentsFeature()` requires `collab`; `compositeMediaFeature()` requires `composites` and `media`.
+- **Singletons.** At most one feature may contribute `anchorResolver`, `formatAiResult` or the single-contributor pipeline stages (`parseMarkdown`, `segment`, `structure`, `wrapImport`, `migrateContent`); a second contributor makes `defineEditor` throw. `normalize` stages chain. `aiContext` is not a singleton: contributions add up (see [AI](#ai)).
+- **Markdown import.** The page's „Markdown einfügen“ button shows the tokenizer working through the block pipeline: `parseBlocks(editor, markdown).blocks` returns TipTap JSON blocks, here with a `callout`.
+
+```ts
+/** Imports Markdown with the callout syntax through the editor's block pipeline (the tokenizer of `callout/node.ts`). */
+function insertCalloutMarkdown() {
+  const editor = paneB.editor
+  if (!editor) return
+  editor.chain().focus().insertContent(parseBlocks(editor, CALLOUT_MARKDOWN).blocks).run()
+}
+```
+
+## Beyond the browser
+
+### Collaboration and the server schema
+
+A Yjs document is valid only if every participant knows the same schema. The playgrounds' editors are standalone (JSON `v-model`); with a collaboration session the server must know your node, too.
+
+- The Nuxt module's collab route builds its schema from the advanced entry plus the adapter's `schemaExtensions()`: `getSchema([...advancedSchemaExtensions(), ...(adapter.schemaExtensions?.() ?? [])])` in [`src/nuxt/runtime/server/utils/collab.ts`](../src/nuxt/runtime/server/utils/collab.ts). Without `schemaExtensions`, a document that contains a `callout` is outside what that route can load: seeding from JSON (`collabSchema().nodeFromJSON`) and the load-time block-ID backfill (`yXmlFragmentToProsemirror(collabSchema(), …)`) both go through a schema without the node.
+- For documents with own blocks register the Vue-free node files in the adapter: `setEditorAdapter({ …, schemaExtensions: () => [Callout] })` (`Callout` from `callout/node.ts`, never `CalloutBlock`, so no Vue component loads). A plain-Vue or React app with **its own Hocuspocus server** builds the schema itself: `getSchema([...advancedSchemaExtensions(), Callout])`. Use the same Collaboration `field` as the client (`default`). See [Matching schemas](./integration.md#matching-schemas-who-owns-the-document) and [Vue-free advanced schema for servers](./integration.md#8-vue-free-advanced-schema-for-servers).
+- `editorBlock: true` works on the server too: `assignBlockIds` reads the flag from the schema, so your server backfills IDs for callouts exactly like for paragraphs.
+- The client mounts a preset that contributes the same node: `advancedEditor().features` plus `calloutFeature()`, together with `collabFeature()`'s session (`advancedEditor()` already has it).
+
+### AI
+
+AI features read and write Markdown, so `renderMarkdown`, `markdownTokenName`, `markdownTokenizer` and `parseMarkdown` of the node decide what the model sees and what it can create.
+
+- **What the model sees.** `editor.getMarkdown()` and every `editor.markdown.serialize(…)` (selection text, document context, summaries) use your `renderMarkdown`. The chat's document view lists *text blocks* as `[<block id>] <Markdown>` lines. A host block that wraps block content, like the callout, is listed as a header line with the block's own ID and its Markdown opener, `[<id>] !!! info`, and its body blocks follow two spaces further in, each as its own line with its own block ID.
+- **What the model can write.** AI results are parsed by the block pipeline (`parseBlocks`), so Markdown in your syntax becomes your node. The model knows the syntax only if you describe it in `aiContext.blocks` (below); the library does not guess it from `renderMarkdown`.
+- **Block IDs.** The callout is a wrapper block: the chat shows it as the header line `[<id>] !!! info` and addresses its inner paragraphs by their own IDs (built-in blocks, they carry IDs regardless). `add` after a body block inserts *inside* the callout. The callout's own ID also serves flash/reveal, paste de-duplication and the server backfill. A host node with inline content (`content: 'inline*'`) and `editorBlock: true` appears in the chat as a line of its own and can be updated, deleted, extended and converted by its ID.
+- **`aiContext` is additive.** A feature teaches the model about its blocks through `aiContext: (editor) => ({ kinds?, blocks?, structure? })`; any number of features may contribute. `defineEditor` merges the contributions: `kinds` and `blocks` are concatenated in feature order, `structure` (`'flat'` | `'composite'`) may come from one feature only. Two failures are reported when the merged context is read (the first time the chat, a generate task or `aiContextOf(editor)` asks), not when you call `defineEditor`: a block `id` described by two contributions, and two features that set `structure`. `aiContextOf(editor)` returns `{ kinds, blocks, structure }` (no kinds, no blocks, `'flat'` by default).
+- **`blocks`.** Each `AiBlock` (type exported from `@ecsplico/editor/core`) describes one host block: `id` is the node type name (`callout`) and doubles as the `convert` target id; `label` is its German name; `description` is one or two sentences on purpose and allowed content; `syntax` is the Markdown form with placeholders in angle brackets; `example` is one complete Markdown example. The callout contributes it like this (`app/editor/callout/feature.ts`):
+
+```ts
+aiContext: () => ({
+  blocks: [{
+    id: 'callout',
+    label: 'Hinweis',
+    description: 'Ein farbig hervorgehobener Kasten für einen Hinweis (info), eine Warnung (warning) oder etwas Erledigtes (success). Enthält Absätze, Listen oder Zitate, keine Überschriften.',
+    syntax: '!!! <info|warning|success>\n<Inhalt, Blöcke durch einen Zeilenumbruch getrennt; eine Leerzeile beendet den Hinweis>',
+    example: '!!! warning\nBitte die Zahlen vor dem Versand prüfen.',
+  }],
+}),
+```
+
+- **What the model does with `blocks`.** The chat lists the blocks in its system prompt and sends them with each request; the generate tasks (sidebar and selection menu) list them in their system prompt too, so a result may contain the block in your syntax and the block pipeline turns it into your node. `syntax` and `example` must match `renderMarkdown` and the tokenizer, or the result will not parse back into the node.
+- **`convert` targets.** The chat sends the model its list of `convert` targets: the core ids, the composite kinds of `aiContext.kinds`, and each `blocks` entry whose id a registered conversion provider parses (`conversions` with a `custom` target; the callout's does). A block without such a provider is not a `convert` target, but the model may still `add` or `update` it through Markdown in its syntax. „Umwandeln in Hinweis“ is therefore also an agent operation for the callout. A custom composite *kind* goes through the `compositeKinds` prop of `advancedEditor({ compositeKinds })`, not through your feature.
+
+## Checklist
+
+1. **Node.** `Node.create` in a Vue-free `node.ts`; `group`, `content`, attributes with `parseHTML`/`renderHTML`, commands and a free shortcut.
+2. **Block IDs.** `editorBlock: true` if AI operations, flash/reveal, paste de-duplication or the server ID backfill should reach it.
+3. **Abilities.** `abilities` on the node for what is allowed inside; for a custom ability id, grant it through the `abilities` prop (`root`).
+4. **Markdown.** `renderMarkdown`, `markdownTokenName`, `markdownTokenizer`, `parseMarkdown` with syntax no other stage claims; test the round trip (`getMarkdown()` → `parseBlocks`), including multi-block bodies.
+5. **View and CSS.** Node view in a separate `index.ts` (`Node.extend`), stylesheet imported after `core.css`.
+6. **Path A.** `extensions` (constant) and `slashCommands` props, nothing else needed.
+7. **Path B.** An `EditorFeature`: `extensions`, then `toolbar` (merge by group id, `commandItem`, `order`), `slashCommands` and `blockActions` with your `ability`, `conversions` with a `custom` target; `requires` for features you depend on.
+8. **Compose.** `defineEditor({ features: [...advancedEditor().features, yourFeature()] })` in setup (`advancedEditor` from `/vue/advanced` or `/react/advanced`); mount with `EditorSurface` and pass `abilities` for custom ability ids; add `blockUiFeature()` to a smaller list when you use hover actions.
+9. **Server.** When documents with your block are collaborative, return `YourNode` from the adapter's `schemaExtensions()` (the package's collab route appends it to `advancedSchemaExtensions()`), or build `getSchema([...advancedSchemaExtensions(), YourNode])` in your own Hocuspocus server.
+10. **AI.** Decide what the model should see (`renderMarkdown`) and write; describe the block in `aiContext.blocks` (`id`, `label`, `description`, `syntax`, `example`, matching your Markdown) — `aiContext` is additive, a block id may be described only once; add a `custom` conversion provider if the block should be a `convert` target.
+11. **Bundle proof.** If you ship the block in a package, add a fixture and a `FIXTURES` entry for `bun run check:editor-entries` ([integration guide §13](./integration.md#13-dependency-rules-and-bundle-proof)); `bun run check:editor-composition` covers `defineEditor` validation.