@ecsplico/editor 0.0.0-stage → 1.0.0

package/docs/usage.md

@@ -0,0 +1,1071 @@
+# Usage guide
+
+Per-feature sections follow the order in which features entered the package. Every symbol below is exported from the named entry (see the [README](../README.md#public-exports)); every snippet uses public package imports only. Each feature has a framework-free entry (`@ecsplico/editor/<x>`: `<x>FeatureCore(ui)`, models), a Vue entry (`/<x>/vue`) and a React entry (`/<x>/react`); the snippets below show the Vue binding, the React binding has the same names ([integration guide §1](./integration.md#per-feature-entries-framework-free-vue-react)). The Vue examples need `<UApp>`, the React ones `EditorContextProvider` and a mounted `Toaster` ([Advanced editor in React](#advanced-editor-in-react)).
+
+- [Simple editor in plain Vue](#simple-editor-in-plain-vue)
+- [Simple editor in React](#simple-editor-in-react)
+- [Advanced editor in React](#advanced-editor-in-react)
+- [Media, mentions and transcript features](#media-mentions-and-transcript-features)
+- [Authors and comments](#authors-and-comments)
+- [Themes (Obsidian)](#themes-obsidian)
+- [Composites and the settings UI](#composites-and-the-settings-ui)
+- [File import into composites](#file-import-into-composites)
+- [AI on a core editor](#ai-on-a-core-editor)
+- [AI integrations: composite AI and transcript AI](#ai-integrations-composite-ai-and-transcript-ai)
+- [Reference: AI surfaces, agent operations and composite fences](#reference-ai-surfaces-agent-operations-and-composite-fences)
+- [File browser](#file-browser)
+- [Advanced Nuxt example](#advanced-nuxt-example)
+
+---
+
+## Simple editor in plain Vue
+
+`SimpleEditor` is the core feature alone: bold/italic/underline/strike/code/link, headings, lists, quotes, code blocks, horizontal rule, undo/redo. No backend requests, no Yjs, no feature code. The runnable reference is [`examples/vue-simple`](../../../examples/vue-simple); start it with `bun run --cwd examples/vue-simple dev` (port 3040). Its sample picker loads five demo documents — „Start“, „Formatierung“ (marks, lists, quote, code block, rule), „Gliederung“ (three outline levels), „Hinweise“ (the own „Hinweis“ block) and „Ungültig (Baustein-JSON)“ (advanced JSON, rejected through `contentError`) — beside the toolbar and outline, with the JSON and Markdown of the document next to the editor. The `/hinweis` entry and the callout behind it are an own block added through the `extensions` and `slashCommands` props; the [extending guide](./extending.md) shows how, and how to go further with a full feature.
+
+### Setup
+
+Starting a new app from nothing? The files below plus these three are all that [`examples/vue-simple`](../../../examples/vue-simple) has:
+
+- `package.json` dependencies: `@ecsplico/editor` (`workspace:*` inside this repository), `vue`, `@nuxt/ui`, `tailwindcss`, `@iconify-json/lucide`, `@tiptap/core`, `@tiptap/pm`, `@tiptap/vue-3`, `yjs`, `@hocuspocus/provider`; dev dependencies `vite`, `@vitejs/plugin-vue`, `typescript`, `vue-tsc`; scripts `dev` (`vite`), `build` (`vite build`), `typecheck` (`vue-tsc --noEmit -p tsconfig.json`). Use the exact version ranges of the example's [`package.json`](../../../examples/vue-simple/package.json).
+- `index.html` with `<div id="app"></div>` and `<script type="module" src="/src/main.ts"></script>`.
+- `tsconfig.json` with `moduleResolution: "Bundler"`, `types: ["vite/client"]`, `strict`, `verbatimModuleSyntax` and `include: ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]` (see the example's [`tsconfig.json`](../../../examples/vue-simple/tsconfig.json)).
+
+Optional: Nuxt UI resolves `i-lucide-*` icons at build time, but a workspace library lies outside the Vite root it scans, so without the extra config the page fetches the toolbar's icons from the Iconify API at runtime. The example's [`vite.config.ts`](../../../examples/vue-simple/vite.config.ts) collects the library's icon names into `ui({ icon: { clientBundle: { scan: true, icons } } })` to bundle them.
+
+`vite.config.ts` — Nuxt UI's Vite plugin without a router:
+
+```ts
+import ui from '@nuxt/ui/vite'
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+
+export default defineConfig({ plugins: [vue(), ui({ router: false })] })
+```
+
+`main.ts` — Nuxt UI and the editor context. `createEditor()` (from the Vue layer, `@ecsplico/editor/vue`) owns the settings of this app and is required by every editor component:
+
+```ts
+import ui from '@nuxt/ui/vue-plugin'
+import { createEditor } from '@ecsplico/editor/vue'
+import { createApp } from 'vue'
+import App from './App.vue'
+import './style.css'
+
+createApp(App).use(ui).use(createEditor()).mount('#app')
+```
+
+`createEditor()` is local-only by default: the settings live in `localStorage` (`tiptap-editor:settings`), the settings endpoints are never called. `createEditor({ settings: { remote: true } })` additionally loads and saves them through `GET`/`PUT /api/editor/settings`; `createEditor({ fetch })` swaps the HTTP client of all features. `createEditor({ locale: 'en' })` switches every string the editor renders to English (default `'de'`), `createEditor({ messages: { 'toolbar.bold': 'Strong' } })` overrides single messages; see [Language](./llms.md#language). Components read `useEditorI18n()` (`{ t, locale }`); the Nuxt module takes the same two options as `tiptapEditor: { locale, messages }`.
+
+`createEditor()` is a thin Vue plugin. The headless core (`@ecsplico/editor/core`) imports no Vue: `createEditorContext(options)` returns the framework-free context with the same options, whose `settings` is a store (`get()`, `set(value)`, `update(recipe)`, `subscribe(listener)`) and whose `ready` and `synced` are read-only stores. `createEditor()` creates that context, provides it to the app and disposes it on unmount; Vue components read the settings through `useEditorSettings()` (reactive refs) from `@ecsplico/editor/vue`.
+
+`style.css` — Tailwind, Nuxt UI, then the core CSS, and let Tailwind scan the library:
+
+```css
+@import "tailwindcss";
+@import "@nuxt/ui";
+@import "@ecsplico/editor/styles/core.css";
+@source "../../../packages/editor/src";
+```
+
+`App.vue` wraps everything in `<UApp>` (overlays, tooltips, toasts).
+
+### Mount the editor
+
+```vue
+<script setup lang="ts">
+import { ref, shallowRef } from 'vue'
+import type { Editor, JSONContent } from '@tiptap/core'
+import { SimpleEditor } from '@ecsplico/editor/vue/simple'
+import { EditorToolbar } from '@ecsplico/editor/vue'
+import { EditorOutline } from '@ecsplico/editor/outline/vue'
+
+const editor = shallowRef<Editor>()
+const content = ref<JSONContent>({ type: 'doc', content: [{ type: 'paragraph' }] })
+</script>
+
+<template>
+  <UApp>
+    <EditorToolbar :editor="editor" />
+    <SimpleEditor v-model="content" @ready="editor = $event" />
+    <EditorOutline :editor="editor" />
+  </UApp>
+</template>
+```
+
+### Props and events of `SimpleEditor`
+
+| Name | Kind | Meaning |
+|---|---|---|
+| `modelValue` / `update:modelValue` | prop / event | TipTap JSON document (`v-model`). Emitted after every user edit. |
+| `editable` | prop, default `true` | Read-only mode when `false`; reactive. |
+| `metadata` | prop | Host lists (`EditorMetadata`); reactive. The simple editor has no built-in lists. |
+| `abilities` | prop | `Partial<AbilitiesOptions>`, deep-merged into the ability defaults; read once at setup. |
+| `extensions` | prop | Extra TipTap extensions added after the built-in ones; read once at setup. An own block goes here, see the [extending guide](./extending.md#path-a-extensions-and-slashcommands). |
+| `slashCommands` | prop | `(defaults: SlashCommandItem[]) => SlashCommandItem[]`; absent = no `/` menu. Read once at setup. |
+| `ready` | event | `(editor: Editor)` once the instance exists. |
+| `metadataCreate` | event | `(list: string, item: MetadataItem)` when the user creates a metadata item. |
+| `contentError` | event | `(error: Error)` when JSON does not fit the simple schema. |
+| `editor` | exposed | `ref` of the component exposes the live `Editor` (`simple.value?.editor`). |
+
+`SimpleEditor` has `inheritAttrs: false` and accepts exactly these props. It does not take `blockActions`, `upload`, `documentId`, `collaboration`, `sidebarOpen` or `settingsUi`: those belong to features the simple editor does not contain.
+
+### JSON `v-model`, `ready` and the editor ref
+
+The editor owns its document and undo history; `v-model` mirrors it as JSON. Keep the instance from `ready` in a `shallowRef` (a deep `ref` would wrap the TipTap instance in a Vue proxy). Alternatively use a template ref: `const simple = useTemplateRef('simple')` then `simple.value?.editor`.
+
+### External replacement
+
+Assigning a new object to the model replaces the document **without an update event** (the editor calls `setContent(json, { emitUpdate: false })`), so `update:modelValue` does not fire and an edit counter does not move. The JSON the editor emitted itself and the host hands back unchanged is recognised and ignored, so the usual `v-model` round trip does not reset the caret or the undo history.
+
+```ts
+content.value = sampleDocument // loads; no echo
+```
+
+### Rejected content: `contentError`
+
+The simple schema is not a lossy view of advanced JSON. Initial and external JSON is checked against the installed schema; a document with unknown node or mark types (for example `{ type: 'doc', content: [{ type: 'composite' }] }`) is rejected: `contentError` fires with the reason and the **last valid document stays** (an empty document when the initial JSON was invalid). Nothing is flattened or silently dropped. The `v-model` value is the host's own state, so move it back when you want it to follow the editor:
+
+```ts
+function onContentError(error: Error) {
+  message.value = error.message
+  content.value = lastValid // the editor kept it; make the model say so
+}
+```
+
+`examples/vue-simple/src/App.vue` does exactly this for its „Ungültig (Baustein-JSON)“ sample: the alert shows the reason, the model and the picker move back to the previous sample.
+
+### Metadata
+
+`metadata` supplies named lists (`EditorMetadata`): a static array or a search function `(q: MetadataQuery) => items | Promise<items>`. The simple editor has no built-in `@`/`#` suggestion sources, so the lists are only read by extensions you add through `extensions` (they search the registry that `metadata` fills); `metadataCreate` reports items created there. Types: `MetadataItem`, `MetadataSource`, `MetadataQuery`, `EditorMetadata` (from `@ecsplico/editor/core`, also type-only from the package root).
+
+### Custom `/` commands via the transformer
+
+The simple editor ships no slash commands and no `/` menu. Passing `slashCommands` turns the menu on with the commands you return:
+
+```vue
+<script setup lang="ts">
+import type { SlashCommandItem } from '@ecsplico/editor/core'
+
+function slashCommands(defaults: SlashCommandItem[]): SlashCommandItem[] {
+  return [
+    ...defaults,
+    {
+      id: 'date',
+      label: 'Datum',
+      icon: 'i-lucide-calendar',
+      run: editor => editor.chain().focus().insertContent(new Date().toLocaleDateString('de-DE')).run(),
+    },
+  ]
+}
+</script>
+
+<template>
+  <SimpleEditor v-model="content" :slash-commands="slashCommands" />
+</template>
+```
+
+`id` is what the user types after `/`; the query matches it or the label as a prefix, case-insensitively. `run` is called after the `/query` text is deleted. The playground in `examples/vue-simple/src/App.vue` registers two such commands: `/datum` (the snippet above with the id `datum`) and `/hinweis`, which wraps the paragraph at the caret in a callout with `run: editor => editor.chain().focus().setCallout('info').run()`. Entries without `ability` are listed wherever the `/` menu opens; give a command an `ability` to limit it ([extending guide](./extending.md#slashcommands)).
+
+### Toolbar and outline outside the editor
+
+`EditorToolbar` and `EditorOutline` are siblings, not children: they work on exactly the editor you pass, never on a global “active” editor. Two editors on one page therefore need two `ready` handlers and two toolbars.
+
+- `EditorToolbar` — props `editor?: Editor`, `preset?: EditorPreset`. Without an editor it renders the groups of `preset` disabled (pass `simpleEditor()` from `@ecsplico/editor/presets/simple` to see the toolbar before the editor is ready); with an editor it uses the preset registered for that instance.
+- `EditorOutline` (`@ecsplico/editor/outline/vue`; the React version, same prop, is `@ecsplico/editor/outline/react`) — prop `editor?: Editor`. Nested headings in a tree; clicking one selects and reveals it and flashes the block (the document is never changed). A missing or destroyed editor renders an empty outline. The same extraction is available as `headingOutline(doc)` and `revealBlockInEditor` from `@ecsplico/editor/outline`.
+
+```vue
+<EditorToolbar :editor="editorA" />
+<SimpleEditor @ready="editorA = $event" />
+<EditorOutline :editor="editorA" />
+
+<EditorToolbar :editor="editorB" />
+<SimpleEditor @ready="editorB = $event" />
+<EditorOutline :editor="editorB" />
+```
+
+### Fixed at mount: remount with `key`
+
+The preset (and with it the schema), `abilities`, `extensions` and `slashCommands` are read once when the component is set up. To change any of them, or to switch to a different document identity, remount the editor:
+
+```vue
+<SimpleEditor :key="documentId" v-model="content" @ready="editor = $event" />
+```
+
+`editable`, `metadata` and the model stay reactive without a remount. After a remount a new `ready` event delivers the new instance; the old one is destroyed by its surface, and the toolbar and outline detach from it when you pass the new editor.
+
+### Check the isolation yourself
+
+`bun run check:editor-entries` proves the simple bundle contains no feature, AI SDK, Yjs, y-tiptap, Hocuspocus, Nuxt or server modules by inspecting the emitted chunks' module IDs. Fixtures live in `packages/editor/checks/fixtures/`; add a folder and a rule entry in `packages/editor/checks/entries.ts` to prove your own entry.
+
+---
+
+## Simple editor in React
+
+The React layer (`@ecsplico/editor/react`, shadcn/ui on Radix and Tailwind 4) renders the same framework-free core as the Vue layer: the simple editor, `EditorToolbar`, the settings panel and modal, and the `@`, `#` and `/` suggestion popups. It uses no Vue, Nuxt UI or Nuxt module. The runnable reference is [`examples/react-simple`](../../../examples/react-simple); start it with `bun run --cwd examples/react-simple dev` (port 3041). It has the same sample picker, read-only toggle, host `/datum` command and JSON and Markdown panes as the Vue example, plus `@` mentions.
+
+**More than the simple editor:** every advanced feature has a React binding as well (`./<x>/react`: media, transcript, composites, authors, comments, AI, collaboration, block UI, themes, the outline and the file browser), and `advancedEditor()` / `AdvancedEditor` from `@ecsplico/editor/react/advanced` compose them all; see [Advanced editor in React](#advanced-editor-in-react). `coreFeature()`, `mentionsFeature()`, `simpleEditor()` and the three integrations have no components and work in both layers; a React preset is `defineEditor({ features })` over features from `./<x>/react` and such component-free features.
+
+### Setup
+
+- `package.json` dependencies: `@ecsplico/editor` (`workspace:*` inside this repository), `react`, `react-dom`, `@tiptap/core`, `@tiptap/pm`, `@tiptap/react`, `@iconify/react`, `@iconify-json/lucide`, `tailwindcss`, `tw-animate-css`, `yjs`, `@hocuspocus/provider` (the last two as in the [README](../README.md#prerequisites): source-shipped shared types reference them); dev dependencies `vite`, `@tailwindcss/vite`, `@vitejs/plugin-react`, `typescript`, `@types/react`, `@types/react-dom`. Use the exact version ranges of the example's [`package.json`](../../../examples/react-simple/package.json).
+- `index.html` with `<div id="app"></div>` and `<script type="module" src="/src/main.tsx"></script>`.
+- `tsconfig.json` with `jsx: "react-jsx"`, `moduleResolution: "Bundler"`, `strict` and `include: ["src"]` (see the example's [`tsconfig.json`](../../../examples/react-simple/tsconfig.json)).
+
+`vite.config.ts`:
+
+```ts
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import { defineConfig } from 'vite'
+
+export default defineConfig({ plugins: [react(), tailwindcss()] })
+```
+
+`index.css` — Tailwind, the animation utilities the shadcn dialog, dropdown and tooltip use, the library sheets, and a `@source` so Tailwind generates the utility classes the library's React sources use:
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+/* ui-vars.css maps the shadcn tokens (--primary, --background, …) to the --ui-* variables the feature sheets read. */
+@import "@ecsplico/editor/react/styles/ui-vars.css";
+@import "@ecsplico/editor/styles/core.css";
+@import "@ecsplico/editor/styles/mentions.css"; /* the sheet of each feature you use */
+
+@source "../../../packages/editor/src/react"; /* relative path from this CSS file to the package's src/react */
+
+/* The shadcn theme block follows: @custom-variant dark, @theme inline, :root and .dark tokens, @layer base.
+   `bunx shadcn@latest init` generates it; examples/react-simple/src/index.css has a complete copy. */
+```
+
+`main.tsx` — icons and the editor context. The toolbar and menus render `i-lucide-*` names through `@iconify/react`; preloading the collection means the page makes no request to the Iconify API. The host owns the context from `createEditorContext()` (`@ecsplico/editor/core`) and every React component of the library reads it from `EditorContextProvider`; the provider never disposes it, call `context.dispose()` yourself when the context outlives your app. `createEditorContext` takes the same options as the Vue `createEditor` (local-only settings by default, `{ settings: { remote: true } }` for `GET`/`PUT /api/editor/settings`, `{ fetch }`):
+
+```tsx
+import lucide from '@iconify-json/lucide/icons.json'
+import { addCollection } from '@iconify/react'
+import { createEditorContext } from '@ecsplico/editor/core'
+import { EditorContextProvider } from '@ecsplico/editor/react'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { App } from './App'
+import './index.css'
+
+addCollection(lucide)
+const context = createEditorContext()
+
+createRoot(document.getElementById('app')!).render(
+  <StrictMode>
+    <EditorContextProvider context={context}>
+      <App />
+    </EditorContextProvider>
+  </StrictMode>,
+)
+```
+
+Notices of app-level models (for example the AI model profiles) go through the context's notifier. The simple editor raises none, so `createEditorContext()` is enough here; hosts of features pass `createEditorContext({ notify: reactNotifier })` and mount sonner's `Toaster` once (both from `@ecsplico/editor/react`, see [Advanced editor in React](#advanced-editor-in-react)).
+
+### Mount the editor
+
+`EditorSurface` takes a preset; `EditorToolbar` is a sibling that works on the editor you pass it (from `onReady`), never on a global active editor. The toolbar renders the groups of the preset registered for that editor; without an editor it shows `preset` disabled.
+
+```tsx
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { mentionsFeature } from '@ecsplico/editor/mentions'
+import { EditorSurface, EditorToolbar } from '@ecsplico/editor/react'
+import type { Editor, JSONContent } from '@tiptap/core'
+import { useState } from 'react'
+
+// Module constants: the preset, `metadata`, `abilities`, `extensions` and `slashCommands` are read once at mount.
+const preset = defineEditor({ features: [coreFeature(), mentionsFeature()] })
+const metadata = { mentions: [{ id: 'u1', label: 'Ada Lovelace' }, { id: 'u2', label: 'Alan Turing' }] }
+
+export function App() {
+  const [editor, setEditor] = useState<Editor | null>(null)
+  const [content, setContent] = useState<JSONContent>({ type: 'doc', content: [{ type: 'paragraph' }] })
+
+  return (
+    <>
+      <EditorToolbar editor={editor ?? undefined} preset={preset} />
+      <EditorSurface
+        preset={preset}
+        metadata={metadata}
+        value={content}
+        onChange={setContent}
+        onReady={setEditor}
+        onContentError={error => console.warn(error.message)}
+      />
+    </>
+  )
+}
+```
+
+Typing `@Ad` opens the mention popup with the `mentions` list. A list the host does not supply (here `hashtags`) comes from `/api/editor/tags` through the context's HTTP client, and only once the `#` popup is used. The simple editor itself ships no `/` commands; pass `slashCommands={defaults => [...defaults, ...]}` (a module function) to turn the `/` menu on.
+
+### The one-liner: `SimpleEditor`
+
+Without own features, `SimpleEditor` from `@ecsplico/editor/react/simple` mounts the simple preset (core feature only) on an `EditorSurface`. The toolbar takes its groups from the editor it is given; `preset` only renders it disabled while there is no editor yet:
+
+```tsx
+import { EditorToolbar } from '@ecsplico/editor/react'
+import { SimpleEditor } from '@ecsplico/editor/react/simple'
+import type { Editor } from '@tiptap/core'
+import { useState } from 'react'
+
+export function App() {
+  const [editor, setEditor] = useState<Editor | null>(null)
+  return (
+    <>
+      <EditorToolbar editor={editor ?? undefined} />
+      <SimpleEditor onReady={setEditor} />
+    </>
+  )
+}
+```
+
+### Props of `EditorSurface` and `SimpleEditor`
+
+| Name | Meaning |
+|---|---|
+| `preset` | `EditorSurface` only: `defineEditor({ features })` (a `ReactPreset`); fixed at mount, remount with `key` to change it. `SimpleEditor` has the simple preset built in. |
+| `value` / `onChange` | TipTap JSON document and its edits. A new object replaces the document without an `onChange`; the JSON the editor emitted itself and the host hands back unchanged is ignored, so the round trip keeps caret and undo history. |
+| `editable` | Read-only when `false` (default `true`); reactive. |
+| `metadata` | Host lists (`EditorMetadata`); reactive, pass a constant. |
+| `abilities`, `extensions`, `slashCommands` | As in the Vue props table above; read once at mount. |
+| `onReady` | `(editor: Editor)` once the instance exists and its chrome is registered. |
+| `onMetadataCreate` | `(list: string, item: MetadataItem)` when the user creates a metadata item. |
+| `onContentError` | `(error: Error)` when JSON does not fit the schema; the last valid document stays. |
+| `settingsUi` | `EditorSurface` only: `'internal'` (default) mounts the settings modal inside the surface; `'external'` calls `onSettingsOpen(tab?)` and the host renders `EditorSettingsPanel` or `EditorSettingsModal` (`preset`, `open`, `onOpenChange`, `tab`, `onTabChange`). Not shown when the preset has no settings tab. |
+| ref | `{ editor }` (`SimpleEditor`) and `{ editor, openSettings(tab?) }` (`EditorSurface`, type `EditorSurfaceHandle`). |
+
+`EditorSurface` also takes `collaboration`, `blockActions`, `documentId`, `upload`, `sidebarOpen`/`onSidebarOpenChange` and `commentsOpen`/`onCommentsOpenChange` for the features that use them (collaboration, block UI, media, AI, comments); the simple editor does not. A `content-error` and the settings tabs behave as in Vue; features contribute React tab components as `settingsTabs: [{ id, label, component }]`, rendered with `SettingsSection` from the same entry.
+
+### Settings in React
+
+`useEditorSettings()` (from `@ecsplico/editor/react`) reads the app's settings from the context: `{ settings, update, set, ready, synced }`, where `settings` is the current `EditorSettings`, `update(draft => { … })` mutates a copy and stores it, and `set(value)` replaces it. `useStore(store)` subscribes a component to any `ReadonlyStore` of the core. Persistence is the same as in Vue: `localStorage` key `tiptap-editor:settings`, optionally synced per account.
+
+---
+
+## Advanced editor in React
+
+`AdvancedEditor` from `@ecsplico/editor/react/advanced` is the React counterpart of the Vue `AdvancedEditor`: an `EditorSurface` over `advancedEditor()`, which lists every feature and integration of `ADVANCED_FEATURE_IDS` (`core`, `media`, `transcript`, `composites`, `mentions`, `authors`, `comments`, `ai`, `collab`, `block-ui`, `composite-media`, `composite-ai`, `transcript-ai`, `themes`) with its React binding, in the same schema order as the Vue surface. It uses no Vue, Nuxt UI or Nuxt module. The runnable reference is [`examples/react-advanced`](../../../examples/react-advanced) (`bun run --cwd examples/react-advanced dev`, port 3043): the React counterpart of the Nuxt document page. It reuses the Nuxt app's documents, session and collaboration socket through the Vite proxy (`/api`, `/collab`), so start the Nuxt app first (`bun run dev`, port 3031).
+
+**Setup** is the [simple React setup](#setup) plus three things:
+
+- **Styles.** Replace the three library imports by one: `@import "@ecsplico/editor/react/styles/advanced.css";` after `tailwindcss` and `tw-animate-css` (it imports `ui-vars.css`, `core.css`, every feature sheet and `themes.css` last, plus the bridge that lets an Obsidian theme restyle the shadcn tokens). Keep the `@source` for the library's `src` and the shadcn theme block; `examples/react-advanced/src/index.css` has a complete copy.
+- **Notices.** Create the context with `createEditorContext({ notify: reactNotifier })` and render sonner's `<Toaster />` once inside the provider (both exported by `@ecsplico/editor/react`). Features send `Notice`s to the surface's notifier (import problems, AI rate limits, comment errors, „Dokument gelöscht“ with undo in the tree); without `<Toaster />` none is visible.
+- **Dependencies.** The simple setup's list plus `sonner` (the `Toaster` and the notice seam), `yjs` and `@hocuspocus/provider` for collaboration; use the exact version ranges of the [example's `package.json`](../../../examples/react-advanced/package.json).
+
+`main.tsx`:
+
+```tsx
+import lucide from '@iconify-json/lucide/icons.json'
+import { addCollection } from '@iconify/react'
+import { createEditorContext } from '@ecsplico/editor/core'
+import { EditorContextProvider, reactNotifier, Toaster } from '@ecsplico/editor/react'
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { App } from './App'
+import './index.css'
+
+addCollection(lucide)
+// `remote: true` syncs the settings with the host's `/api/editor/settings`; drop it for local-only settings.
+const context = createEditorContext({ settings: { remote: true }, notify: reactNotifier })
+
+createRoot(document.getElementById('app')!).render(
+  <StrictMode>
+    <EditorContextProvider context={context}>
+      <App />
+      <Toaster />
+    </EditorContextProvider>
+  </StrictMode>,
+)
+```
+
+**The page.** Build the preset once with `advancedEditor()` and pass it to every chrome component beside the editor; the editor mounts its own, equal one. `AdvancedEditor` takes the surface's props except `preset`, plus `compositeKinds` (read once at mount):
+
+```tsx
+import { AiSidebar } from '@ecsplico/editor/ai/react'
+import { CommentsMargin } from '@ecsplico/editor/comments/react'
+import { CompositeInspector } from '@ecsplico/editor/composites/react'
+import type { CollaborationSession } from '@ecsplico/editor/core'
+import { EditorSettingsModal, EditorToolbar } from '@ecsplico/editor/react'
+import { AdvancedEditor, advancedEditor } from '@ecsplico/editor/react/advanced'
+import type { Editor } from '@tiptap/core'
+import { useState } from 'react'
+
+export function Page({ id, session }: { id: string, session: CollaborationSession }) {
+  const [editor, setEditor] = useState<Editor>()
+  const [preset] = useState(() => advancedEditor())
+  const [scrollEl, setScrollEl] = useState<HTMLElement | null>(null)
+  const [settingsOpen, setSettingsOpen] = useState(false)
+  const [sidebarOpen, setSidebarOpen] = useState(false)
+  const [commentsOpen, setCommentsOpen] = useState(false)
+
+  return (
+    <>
+      <EditorToolbar editor={editor} preset={preset} />
+      <main ref={setScrollEl} className="relative flex min-h-0 flex-1 overflow-auto">
+        <AdvancedEditor
+          key={id}
+          collaboration={session}
+          documentId={id}
+          settingsUi="external"
+          sidebarOpen={sidebarOpen}
+          onSidebarOpenChange={setSidebarOpen}
+          commentsOpen={commentsOpen}
+          onCommentsOpenChange={setCommentsOpen}
+          onReady={setEditor}
+          onSettingsOpen={() => setSettingsOpen(true)}
+        />
+        <CommentsMargin editor={editor} container={scrollEl} open={commentsOpen} />
+      </main>
+      <CompositeInspector editor={editor} />
+      <AiSidebar editor={editor} open={sidebarOpen} onOpenChange={setSidebarOpen} />
+      <EditorSettingsModal preset={preset} open={settingsOpen} onOpenChange={setSettingsOpen} />
+    </>
+  )
+}
+```
+
+Notes:
+
+- **Collaboration.** The `session` is `{ ydoc, provider, user }` (`CollaborationSession` from `@ecsplico/editor/core`): create the `Y.Doc` and the `HocuspocusProvider` in an effect (so StrictMode's double mount leaves exactly one provider), destroy the provider in its cleanup, and key the editor by document so a new document is a new Y.Doc ([integration guide §6](./integration.md#6-collaboration-on-the-client)). Without `collaboration` pass `value`/`onChange` for a standalone editor (the collaboration and comments features then contribute nothing).
+- **Beside the editor.** `EditorToolbar`, `EditorSettingsModal`/`EditorSettingsPanel`, `CommentsMargin`, `CompositeTable`, `CompositeInspector`, `AiSidebar`, `EditorOutline` and `DocumentTree` are components you place; each takes the `editor` from `onReady` (or the `preset`). `useEditorUi(editor)` returns the chrome of a ready editor (`openSettings(tab?)`, `toggleSidebar()`, `toggleComments()`, `commentsOpen`) for your own buttons.
+- **Own features.** Build on the same list: `defineEditor({ features: [...advancedEditor().features, myFeature()] })` for an `EditorSurface`, as in the Vue playground.
+- **The file browser** is [`DocumentTree` from `@ecsplico/editor/tree/react`](#file-browser) over a `DocumentStore`; the example wires it to the host's `/api`.
+- **Backend.** The same as for the Vue advanced editor: `/collab/:id`, the AI endpoints, assets, users/tags and themes of the Nuxt module and a host adapter ([integration guide](./integration.md)). A React app with its own server brings the same routes.
+
+---
+
+## Media, mentions and transcript features
+
+Three independent features extend the core editor. Each is one factory you add to `defineEditor({ features })` next to `coreFeature()`; none needs composites, AI or Yjs, and none imports the others (`bun run check:editor-entries` proves it per feature).
+
+```vue
+<script setup lang="ts">
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { EditorSurface, EditorToolbar } from '@ecsplico/editor/vue'
+import { mediaFeature } from '@ecsplico/editor/media/vue'
+import { mentionsFeature } from '@ecsplico/editor/mentions'
+import { transcriptFeature } from '@ecsplico/editor/transcript/vue'
+import type { Editor } from '@tiptap/vue-3'
+import { shallowRef } from 'vue'
+
+const preset = defineEditor({ features: [coreFeature(), mediaFeature(), mentionsFeature(), transcriptFeature()] })
+const editor = shallowRef<Editor>()
+</script>
+
+<template>
+  <EditorToolbar :editor="editor" />
+  <EditorSurface v-model="content" :preset="preset" @ready="editor = $event" />
+</template>
+```
+
+Import the feature CSS after `tailwindcss`, `@nuxt/ui` and `core.css`:
+
+```css
+@import "@ecsplico/editor/styles/media.css";
+@import "@ecsplico/editor/styles/mentions.css";
+@import "@ecsplico/editor/styles/transcript.css";
+```
+
+### Dependency setup
+
+Installing the package brings the feature dependencies; nothing else is required in the consumer beyond the peers listed in the [README](../README.md#prerequisites).
+
+| Feature | Entry | Vue-free schema entry | Runtime dependencies it adds | Needs a backend |
+|---|---|---|---|---|
+| Media | `@ecsplico/editor/media` (framework-free), `/media/vue`, `/media/react` | `@ecsplico/editor/media/schema` | `@tiptap/extension-image`, `@tiptap/extension-file-handler` | only for uploads (see below); a `upload` function replaces it |
+| Mentions | `@ecsplico/editor/mentions` | `@ecsplico/editor/mentions/schema` | `@tiptap/extension-mention`, `@tiptap/suggestion` | only for the built-in lists (see below); host lists replace them |
+| Transcript | `@ecsplico/editor/transcript` (framework-free), `/transcript/vue`, `/transcript/react` | `@ecsplico/editor/transcript/schema` | none beyond core | no |
+
+The `/schema` entries import no Vue, no node view and no feature factory. A server that validates or seeds documents builds the matching schema from them:
+
+```ts
+import { getSchema } from '@tiptap/core'
+import { coreSchemaExtensions } from '@ecsplico/editor/core/schema'
+import { mediaSchemaExtensions } from '@ecsplico/editor/media/schema'
+import { mentionsSchemaExtensions } from '@ecsplico/editor/mentions/schema'
+import { transcriptSchemaExtensions } from '@ecsplico/editor/transcript/schema'
+
+const schema = getSchema([...coreSchemaExtensions(), ...mediaSchemaExtensions(), ...mentionsSchemaExtensions(), ...transcriptSchemaExtensions()])
+```
+
+The schema entries also export the helpers servers need: `MEDIA_TYPES`, `MAX_MEDIA_BYTES`, `mediaKindOf`, `assetUrl`, `assetRefOf`, `ASSET_NAME`, `ASSET_DOCUMENT_ID`, `SCRATCH_DOCUMENT_ID` (media), `mentionsFromText`, `mentionUsersIn`, `tagsFromText`, `collectTagNames`, `normalizeTagName` (mentions), `speakerParagraphsToSegments`, `lastSpeaker`, `speakersIn` (transcript).
+
+### Upload
+
+`mediaFeature()` adds image, audio, video and file blocks, drop/paste of files, toolbar buttons (Bild, Audio-Datei, Video, Aufnahme), the matching `/` commands and the audio recorder modal. Every path ends in one function, `editor.storage.media.upload(file): Promise<{ url: string }>`, chosen when the surface is set up:
+
+1. the surface's `upload` prop (`(file: File) => Promise<{ url: string }>`), if given — use it to store files wherever you like (S3, a data URL, …); the returned `url` becomes the block's `src`;
+2. otherwise `POST /api/editor/assets/<documentId>` with a `multipart/form-data` body (field `file`) through the context's HTTP client; `documentId` is the surface's prop, default `scratch`. The response must be `{ url }`.
+
+```vue
+<EditorSurface :preset="preset" :upload="file => storeSomewhere(file).then(url => ({ url }))" />
+```
+
+Accepted types and size limits are `MEDIA_TYPES` and `MAX_MEDIA_BYTES` (Vue-free, from `@ecsplico/editor/media/schema`): images up to 5 MB (png, jpeg, gif, webp), audio 50 MB, video 200 MB, and any other type up to 50 MB as a downloadable file block. A server endpoint should validate against the same constants; the Nuxt module's `/api/editor/assets/*` routes do. A failed upload shows a toast (`Import fehlgeschlagen`) and inserts nothing.
+
+**File import.** Drop, paste, the toolbar and `/` commands all call `editor.storage.media.importFiles(editor, files, pos?)`; `useFileImport()` (from `@ecsplico/editor/media/vue` or `/media/react`; call it in `setup` / while rendering: it binds the notifier of `editor`'s surface when you pass the editor, else the app's: a Nuxt UI toast on Vue and a sonner toast on React unless the host's `notify` says otherwise) returns the same `importFiles` for your own buttons; the framework-free model is `fileImport(notify, t)` from `@ecsplico/editor/media` (`t` is the editor context's translator). Text and Markdown files (`.md`, `.markdown`, `.txt`, at most 2 MB) are read and parsed through the editor's block pipeline (Markdown parse, then `normalize` — mention/tag chips —, `segment` — speaker lines —, `structure`); every other file is uploaded and appears as its media or file block. The resulting blocks pass through the pipeline's `wrapImport` stage, which is the identity unless another feature wraps imports, and are inserted as they are at the drop position (anchored while uploads run, so editing meanwhile does not shift it) or at the selection. Files are imported sequentially; a failed file is reported and skipped.
+
+The recorder (`AudioRecorderModal`) is mounted by `EditorSurface` as a feature overlay. In a custom layout without `EditorSurface`, render `<AudioRecorderModal :editor="editor" />` yourself (exported from `@ecsplico/editor/media/vue`, or `/media/react`) and open it with `openAudioRecorder(editor)`. It records through `MediaRecorder` (needs HTTPS or localhost and microphone permission) and imports the result like any file. The recording model itself is framework-free: `createAudioRecorder()` from `@ecsplico/editor/media` (a store with `start`, `stop`, `cancel`, `dispose`).
+
+### Metadata
+
+The mentions feature reads two named lists, the transcript feature one; hosts replace any of them through the `metadata` prop (`EditorMetadata`, see [Metadata](#metadata) above). Lists the host does not supply fall back to the feature's built-in source; the fallback is only searched when a suggestion popup is actually used.
+
+| List | Used by | Built-in source when the host supplies none |
+|---|---|---|
+| `mentions` | `@` popup, `normalize` stage | `GET /api/editor/users?q=<query>` → `{ id, username, color }[]` (through the context's HTTP client) |
+| `hashtags` | `#` popup | `GET /api/editor/tags?q=<normalized query>` → `string[]` |
+| `speakers` | speaker field of a segment | speakers already in the document (no backend) |
+
+A backend-free app passes its own lists and never calls those endpoints:
+
+```vue
+<EditorSurface
+  :preset="preset"
+  :metadata="{
+    mentions: [{ id: 'u1', label: 'anna', color: '#e11d48' }],
+    hashtags: q => searchTags(q.query),
+  }"
+  @metadata-create="(list, item) => persist(list, item)"
+/>
+```
+
+Mentions are `@username` chips tinted with the item's `color` (a `#rgb`/`#rrggbb` value; anything else is dropped). Tags are `#tag` chips; the typed name is normalized (`normalizeTagName`: lowercase, spaces → `-`, letters/digits/`-`/`_` only, at most 64 characters), and the popup offers „#name erstellen“ when it is not in the list — picking it emits `metadataCreate('hashtags', { id, label })`.
+
+**Pipeline stages.** The mentions feature contributes the `normalize` stage: `@name` / `#tag` in Markdown that is imported from a file or written by AI turns into chips when the name matches a user already in the document or in the `mentions` list, or a tag already in the document. Without the feature installed, those stay plain text. The transcript feature contributes the `segment` stage: a paragraph that starts with a bold `**Name:**` followed by text becomes a speaker segment (a bare `**Aufgaben:**` label stays a paragraph). Both stages run for imported files and for AI results.
+
+### Transcript
+
+`transcriptFeature()` adds the speaker segment block: a „Sprecherblock“ toolbar button (Mod-Shift-S), Enter inside a segment splits it keeping the speaker, a speaker field with suggestions from the `speakers` list, the „Sprecherzeile“ entry in the „Umwandeln in …“ menus (paragraphs, headings, lists, quotes and code blocks become segments carrying the last speaker; segments convert back into any core target), and Markdown `**Name:** text` export. A segment holds only inline text: headings, lists, quotes, code blocks, media and composites are revoked inside it.
+
+## Authors and comments
+
+Both features belong to the advanced editor (not the simple one) and need a collaborative surface for the user's identity: `:collaboration="{ ydoc, provider, user: { id, name, color } }"` (`AuthorIdentity`). Entries: `@ecsplico/editor/authors/vue` or `/authors/react` (the framework-free `/authors` and `/authors/schema` hold the model), `@ecsplico/editor/comments/vue` or `/comments/react` (framework-free `/comments`, `/comments/schema`); CSS `styles/authors.css` and `styles/comments.css` (after `core.css`; the Nuxt module adds them).
+
+```ts
+import { authorsFeature } from '@ecsplico/editor/authors/vue'
+import { collabFeature } from '@ecsplico/editor/collab/vue'
+import { commentsFeature } from '@ecsplico/editor/comments/vue'
+const preset = defineEditor({ features: [coreFeature(), collabFeature(), authorsFeature(), commentsFeature()] })
+```
+
+On React the same list comes from `/authors/react`, `/collab/react` and `/comments/react`, and `collaboration` is a prop of the same name.
+
+**`authorsFeature()`** (no dependency, inert without a user)
+
+- Every inserted text run carries an `author` mark `{ id, name, color }` (persisted, invisible, not in Markdown). Text typed inside someone else's run takes the typist's mark; remote edits and Yjs undo/redo keep the original author. `documentAuthors(doc)` lists the authors with their character counts; `currentAuthor(editor)` is the user the editor writes as.
+- The colouring mode is a per-user preference: `editing.authorColors` (off by default) and `editing.authorColorStyle` (`'background'` tint or `'text'` colour). It is set in the „Autorenfarben“ settings tab and in the toolbar's palette button, whose popover also holds a legend of the document's authors (`AuthorColorsPanel`).
+
+**`commentsFeature({ model? })`** (requires `collab` unless `model` is given)
+
+- `model: (getEditor) => CommentsModel` backs the comments with the host's own data (REST threads, a database) instead of the Y.Doc: the feature then requires no `collab`, the `Comments` plugin reads the user, the thread ids and the ranges from `model.state` (a snapshot with `available`, `canComment`, `user`, `threads`, `ranges`, …), and `useComments(editor)` resolves the model of the editor's surface (`commentsModelOf(ctx)`; the factory runs once for the plugin and once per hook consumer, so share state outside it). `CommentsSnapshot.canComment` gates the selection bubble: the default model says `available` and editable, a host model may allow readers. `CommentsModel`, `CommentsSnapshot`, `CommentsActions`, `DocRange` are exported from `/comments`.
+
+- Select text and choose „Kommentar“ in the selection bubble; others reply, anyone resolves or reopens a thread („Erledigt“ threads lose their highlight), authors edit or delete their own comments. A thread whose text was deleted stays as orphan („Textstelle gelöscht“). Threads live in the Y.Doc map `comments` (`createCommentsModel(getEditor)` is the framework-free model; `useComments(editor)` is the thin Vue hook, returning the `CommentsStore`, and the React binding has the same hook), the range is the `comment` mark (the schema mark is always registered, so stored marks round-trip even without the feature's UI).
+- `editing.commentsLayout` (`'margin'` default, `'inline'`) is a per-user setting in the „Kommentare“ settings tab:
+  - `margin` („Randspalte“): cards beside the commented text. The host places `CommentsMargin` (props `editor`, `container`, `open`) inside the editor's scroll container (`relative flex`, editor wrapper `min-w-0 flex-1`) and binds `v-model:comments-open` on the surface (React: `commentsOpen`/`onCommentsOpenChange`). The toolbar's „Kommentare“ button and `Mod-Shift-m` toggle it; opening it closes the AI sidebar and vice versa.
+  - `inline`: `CommentsPopover` (mounted by the feature as an overlay) opens at the commented text; the toolbar's `CommentsListMenu` lists all threads with the open count. Esc closes the popover.
+- Without collaboration the toolbar button is disabled with an explanation. Switching the layout closes any open thread or draft.
+
+```vue
+<div ref="scrollEl" class="relative flex overflow-auto">
+  <div class="min-w-0 flex-1">
+    <AdvancedEditor v-model:comments-open="commentsOpen" :collaboration="{ ydoc, provider, user: { id, name, color } }" />
+  </div>
+  <CommentsMargin :editor="editor" :container="scrollEl" :open="commentsOpen" />
+</div>
+```
+
+React, same layout:
+
+```tsx
+<main ref={setScrollEl} className="relative flex overflow-auto">
+  <div className="min-w-0 flex-1">
+    <AdvancedEditor commentsOpen={commentsOpen} onCommentsOpenChange={setCommentsOpen} collaboration={{ ydoc, provider, user: { id, name, color } }} />
+  </div>
+  <CommentsMargin editor={editor} container={scrollEl} open={commentsOpen} />
+</main>
+```
+
+`bun run check:editor-entries` proves the isolation with the `authors` and `comments` fixtures; the marks are part of the server schema snapshot.
+
+## Themes (Obsidian)
+
+`themesFeature()` (`@ecsplico/editor/themes/vue` or `/themes/react`, part of `advancedEditor()`; the simple editor stays backend-free) renders an [Obsidian](https://obsidian.md) theme (`theme.css` plus `manifest.json`) on the **whole app**: dashboard, navbars, toolbars, the settings panel, modals and the editor content. `<html>` carries `obsidian-theme theme-dark` or `obsidian-theme theme-light` according to `html.dark` (Nuxt colour mode, or your own `dark` class on React; without a `dark`/`light` class the system preference), observed live, so toggling the mode switches the palette without a reload. Every Nuxt UI `--ui-*` token (on React the shadcn tokens, through `themes-bridge.css` in `advanced.css`) is bridged to the theme's variables, so components follow without per-component CSS; the chrome uses the theme's interface font (the page's root font size stays untouched) and the editor content its text font. „Standard“ is the plain Nuxt UI (or shadcn) look. Builtin themes: Nord, Things, Minimal, Catppuccin, Border, Blue Topaz and Tokyo Night. The runtime starts with the first mounted editor surface (the feature's `setup` hook), so a page without a surface is not themed.
+
+**Choosing a theme.** `themesFeature()` contributes the settings tab **„Darstellung“** (`SettingsAppearanceTab`, id `appearance`, shown by `EditorSettingsPanel`/`EditorSettingsModal` like any tab; the simple editor has none). Its select lists „Standard“ plus every theme of `GET /api/editor/themes`, labelled `name – author`; the choice is `appearance.theme`, applies to the whole app at once and persists with the other settings (per browser, and to the server when remote settings are on). The app's navbars carry a `<UColorModeButton />` that toggles light/dark for the app and the theme together. Programmatically:
+
+```ts
+// `PUT /api/editor/settings` with `appearance: { theme: 'nord' }`, or in the browser console (settings are stored per browser until synced):
+const key = 'tiptap-editor:settings'
+localStorage.setItem(key, JSON.stringify({ ...JSON.parse(localStorage.getItem(key) ?? '{}'), appearance: { theme: 'nord' } }))
+// `null` (the default) is the standard look.
+```
+
+Setup: `@ecsplico/editor/styles/themes.css` after `core.css` and the feature sheets (the Nuxt module adds it last; React hosts of the advanced editor get it, with the shadcn bridge, from `react/styles/advanced.css`), and an adapter with `listThemes`/`loadTheme` ([integration guide §3](./integration.md#3-editoradapter-auth-and-storage)) serving `GET /api/editor/themes` and `GET /api/editor/themes/:id`. A custom list of features uses `themesFeature()` from `/themes/vue` or `/themes/react` (call the Vue one during component setup); the framework-free `themesFeatureCore(ui)`, `startObsidianTheme(ctx)` (the runtime; returns its release), `scopeThemeCss(css, scope?)` and the Vue-free `ThemeRecord`/`THEME_ID`/`themeManifestSchema` (`/themes/schema`) are exported for hosts.
+
+**How it works.** The runtime (one per app, shared by every editor on the page; started by the feature's `setup` hook and reference-counted, so it starts as soon as the first surface mounts; on Vue it then lives until the Vue app unmounts, also on pages without an editor, on React until the last surface that started it unmounts) reads `appearance.theme`, fetches the stylesheet through the app's `fetch` and scopes it with `scopeThemeCss`: `body`, `:root` and `html` rules become the scope element (`body.theme-dark` → `.obsidian-theme.theme-dark`), `.theme-dark`/`.theme-light` rules the scope element with that class, Obsidian's content-root classes (`.markdown-rendered`, `.markdown-preview-view`, `.markdown-source-view`, `.cm-s-obsidian`, …) `.tiptap`, everything else becomes a descendant selector; every emitted selector starts with `.obsidian-theme`. The scope element is `<html>`: the runtime toggles `obsidian-theme` and `theme-dark`/`theme-light` on `document.documentElement` (client side only; the first server-rendered paint shows the standard look). The result sits in one `<style data-tiptap-theme>` in `<head>` (removed again for `null`) and is cached per theme for the session. `@font-face`, `@keyframes`, `@media`, `@supports` and `@layer` survive.
+
+**What is mapped.** `styles/themes.css` defines Obsidian's variables with defaults (a theme overrides them) and maps them onto the whole app and the editor content:
+
+| Element | Obsidian variables |
+|---|---|
+| Root `<html>` (background, text colour, interface font; no font size) | `--background-primary`, `--text-normal`, `--font-interface` |
+| `.tiptap` (text font and size, line height, caret) and `::selection` | `--font-text`, `--font-text-size`, `--line-height-normal`, `--caret-color`, `--text-selection` |
+| `p`, `h1`–`h6` | `--p-spacing`, `--hN-size`/`-weight`/`-color`/`-line-height`/`-font`/`-variant`/`-style`, `--heading-spacing` |
+| `strong`, `em`, `s`, `u` | `--font-weight` + `--bold-modifier`, `--bold-color`, `--italic-color` |
+| Links | `--link-color`, `--link-color-hover`, `--link-external-color`, `--link-decoration` |
+| `code`, `pre` | `--code-background`, `--code-normal`, `--code-size`, `--code-radius`, `--font-monospace`, `--code-white-space` |
+| `blockquote`, `hr` | `--blockquote-*`, `--hr-color`, `--hr-thickness` |
+| Lists, placeholder | `--list-indent`, `--list-marker-color`, `--list-spacing`, `--text-faint` |
+| `.tag`, `.mention` | `--tag-*`, `--text-accent`, `--background-modifier-hover` |
+| `.composite`, `.media-block`, `img` | `--embed-border-start`, `--embed-background`, `--radius-s` |
+| Every package feature stylesheet (authors, comments, transcript, composites, media, mentions) | follows through the Nuxt UI tokens, which the bridge points at Obsidian's: `--ui-text` → `--text-normal`, `--ui-bg` → `--background-primary`, `--ui-border` → `--background-modifier-border`, `--ui-primary` → `--interactive-accent`, `--ui-warning`/`--ui-error`/`--ui-success`/`--ui-info` → `--color-orange`/`red`/`green`/`blue`, `--font-mono` → `--font-monospace` |
+| Host callout (`.callout[data-tone]`, [`app/editor/callout/callout.css`](../../../app/editor/callout/callout.css)) | `--callout-info`, `--callout-warning`, … as RGB triplets (`rgba(var(--callout-color), 0.1)` background), `--callout-radius`, `--callout-padding`; the host owns this mapping for its own blocks |
+
+Cascade: the bridge is part of `@layer components`; the scoped theme is injected **unlayered**, so its rules beat the bridge and `core.css`. Selecting „Standard“ (`null`) removes the style element and the three classes from `<html>`; the app then looks as before.
+
+**Add a builtin theme (host).** In this repository a folder `server/themes/<id>/` with `manifest.json` (`name`, optional `version`, `author`, `authorUrl`; the folder name must match the `THEME_ID` pattern `^[a-z0-9][a-z0-9-]{0,63}$`), `theme.css` and the theme's `LICENSE` is a builtin: `server/utils/themes.ts` reads the folder once per process and `GET /api/editor/themes` marks it `builtin: true`. Seeded builtins (all MIT): Nord (`nord`), Things (`things`), Minimal (`minimal`), Catppuccin (`catppuccin`), Border (`border`), Blue Topaz (`blue-topaz`) and Tokyo Night (`tokyo-night`). Another host implements the adapter methods (`listThemes`/`loadTheme`, plus `storeTheme`/`removeTheme` for uploads) over its own storage.
+
+**Upload and delete.** The „Darstellung“ tab has a row **„Theme hochladen“** with two file inputs, `theme.css` (required) and `manifest.json` (optional), and an upload button; below it the **Theme-Bibliothek** lists every theme with name, version and author. A successful upload joins the library for every user, is selected for the uploader and shows the toast „Theme „X“ hochgeladen“. Uploads carry a trash button (`DELETE`; deleting the selected theme resets `appearance.theme` to `null`, „Standard“); builtins carry the badge „mitgeliefert“ and no delete button. Failures appear as toasts with the server's German message.
+
+| Route | Request | Answers |
+|---|---|---|
+| `POST /api/editor/themes` | multipart: `css` (File, required), `manifest` (File, optional), `name` (string, optional) | `201` + `ThemeRecord` (`builtin: false`); `400` missing `css`, „Ungültiges manifest.json“, or CSS that is not UTF-8 text or starts with markup (`<script`, `<?xml` within the first 512 bytes); `413` „Theme ist größer als 2 MB“ |
+| `DELETE /api/editor/themes/:id` | – | `204`; `404` unknown id; `403` „Mitgelieferte Themes können nicht gelöscht werden“ for builtins; `400` for an id that does not fit `THEME_ID` |
+
+Both routes authenticate like the read routes and answer `501` when the adapter lacks `storeTheme`/`removeTheme`. **Limits:** `theme.css` up to 2 MB (`MAX_THEME_BYTES`); the manifest is parsed with `themeManifestSchema` (`name` 1–120 characters; `version`, `author`, `authorUrl` optional). The name comes from the manifest, else the `name` field, else the CSS file's base name; the id is its slug (`[^a-z0-9]+` → `-`, at most 64 characters), made unique with `-2`, `-3` … against the library. In this repository uploads persist under `.data/themes/<id>/` (`manifest.json`, `theme.css`; Nitro storage mount `themes`) and survive restarts; the adapter methods `storeTheme(record, css)` and `removeTheme(id)` are the seam for another host's storage ([integration guide §3](./integration.md#3-editoradapter-auth-and-storage)).
+
+**Failures.** A theme that cannot be loaded (deleted, network error, adapter without theme methods) falls back to the standard look for the session with a console warning (`tiptap-editor: Theme „<id>“ konnte nicht geladen werden …`); the stored setting is not changed. An id that does not fit `THEME_ID` is rejected by the settings schema.
+
+**Limits.**
+
+- Rules for Obsidian's own chrome (`.workspace*`, `.nav-*`, `.cm-line`, the sidebar, tabs, status bar) are scoped like the rest and match nothing in the app; they do no harm. The app chrome follows the theme through the Nuxt UI tokens only, not through an emulation of Obsidian's DOM.
+- Obsidian sets body classes depending on settings and plugins (`is-mobile`, `is-translucent`, …); only `theme-dark`/`theme-light` are set on `<html>`, so rules that need other body classes do not apply (Catppuccin and Minimal fall back to their default palettes).
+- `@import` is dropped (a theme never triggers remote requests); fonts must come as `@font-face` in the file, as the builtins do. Imported stylesheets and remote fonts are lost.
+- Theme CSS is user-supplied and unlayered: a rule like `.obsidian-theme * { display: none }` breaks the app for whoever selected that theme. Themes are chosen per user.
+- A theme's own `body { font-size }` rule lands on `<html>` after scoping and rescales `rem`, as Obsidian applies it to `body`; the bridge itself sets no root font size.
+- Scoping needs `CSSStyleSheet.replaceSync` (Chrome 73+, Firefox 101+, Safari 16.4+). Selectors are rewritten from the browser's serialized `selectorText`, so quotes and spacing are normalised; the meaning is unchanged.
+
+`bun run check:editor-entries` proves the isolation with the `themes` fixture.
+
+## Composites and the settings UI
+
+`compositeFeature()` adds composites („Bausteine“): structured blocks with a title, description, tags, kind-specific meta fields and a body that may hold more blocks and composites. It needs no AI, media, transcript or Yjs code (`bun run check:editor-entries` proves it with the `composites` fixture), and it adds no dependency beyond the core peers.
+
+```vue
+<script setup lang="ts">
+import { compositeFeature } from '@ecsplico/editor/composites/vue'
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { EditorSettingsPanel, EditorSurface, EditorToolbar } from '@ecsplico/editor/vue'
+import type { Editor } from '@tiptap/vue-3'
+import { shallowRef } from 'vue'
+
+const preset = defineEditor({ features: [coreFeature(), compositeFeature()] })
+const editor = shallowRef<Editor>()
+const tab = shallowRef<string>()
+</script>
+
+<template>
+  <EditorToolbar :editor="editor" />
+  <EditorSurface v-model="content" :preset="preset" settings-ui="external" @ready="editor = $event" @settings-open="tab = $event ?? tab" />
+  <EditorSettingsPanel v-model:tab="tab" :preset="preset" />
+</template>
+```
+
+Import the feature CSS after `tailwindcss`, `@nuxt/ui` and `core.css`:
+
+```css
+@import "@ecsplico/editor/styles/composites.css";
+```
+
+On React the feature is `compositeFeature()` from `@ecsplico/editor/composites/react`, with the same components (`CompositeTable`, `CompositeInspector`, `CompositeView`, `CompositeDetails`, `CompositeFieldEditor`, ...) and hooks (`useCompositeRows`, `useCompositeAnchors`); the framework-free `@ecsplico/editor/composites` holds `compositeFeatureCore(ui, options)`, the nodes, conversions, fences and the models behind the hooks (`createCompositeRows`, `observeCompositeAnchors`). `EditorToolbar`, `EditorSurface` and the settings components come from `@ecsplico/editor/react` ([simple React setup](#simple-editor-in-react)).
+
+### What the feature contributes
+
+- **Nodes and node views:** `composite` (attributes `kind`, `meta`) with its title, description and tags children. The title, description and tags are *chrome*: they cannot be selected, dragged, deleted or duplicated apart from their composite. Stored documents with the old `metaVisible` attribute still load; the attribute is dropped.
+- **Toolbar group:** insert a composite of the default kind, „In Baustein umwandeln“ (kind menu for the block at the caret) and „Gliederung umwandeln“ (headings ↔ composites, the preferred structure's direction first; the last entry opens the settings when some feature contributes a tab).
+- **`/` commands, block actions and overlay:** one insert command per kind, the heading ↔ composite conversions, the composite-specific hover action (export of a `document` composite) and the chip/details-popover overlay ([below](#chips-and-details-popover)).
+- **Conversion providers** (below), **Markdown `:::` fences** for import (`::: kind {meta}`, `## title`, `> description`, `Tags: #a #b`, body, `:::`; nested fences close with the same bare `:::`; a fence of a kind that is not registered stays an `opaqueFence` and is written back verbatim) and export, **legacy migration** (`section` blocks of old documents become composites; also available as `migrateLegacyContent`), and the `structure` pipeline stage that turns Markdown headings into composites or composites into headings according to the preferred structure.
+- **Settings tab `editing`:** the preferred structure (headings or composites), the scope of „Gliederung umwandeln“ without a selection, the root of a file browser's tree and the default kind of new composites. The values live in the shared settings model, so every panel and editor of the app sees the same choice.
+
+Kinds are data. `compositeFeature({ kinds })` replaces the built-in `defaultCompositeKinds(ctx.t)` (section, task, ...; labelled in the context's language); a kind has `id`, `label`, `icon`, `titlePlaceholder`, `descriptionPlaceholder` and `fields` (`text`, `textarea`, `date`, `number`, `select`). `compositeKindsOf(editor)` returns the editor's own list and an unknown `kind` id falls back to the `section` presentation under its own label.
+
+### Chips and details popover
+
+The feature mounts one overlay (`CompositeChrome`) beside the editor, so every composite looks the same in every host:
+
+- **Chips on the title line.** The kind's `status` field (a `select`) shows as a status chip; its dropdown changes the value. Every tag is a `#tag` chip with a `×` that appears on hover or focus, and a `+` chip opens a tags editor (the same suggestions as the `#` list). Kinds without a status field show only the tags.
+- **Details popover.** The kind icon on the composite's left border opens a popover (about 18rem wide, scaling and fading in from the icon within ~160 ms; no animation with `prefers-reduced-motion`). At the top is the node type as a dropdown of all kinds (icon and label, no label above it), below it every field of the kind except the status (the chip edits it) and the summary. `Escape` or a click outside closes it, unless a dropdown inside is open (that one takes its own `Escape` first).
+- **The icon is the drag handle.** In an editable editor, dragging the kind icon moves the composite (the cursor is a grab hand): the composite becomes the selection and is dragged like with the standard drag handle, so dropping it elsewhere in the editor moves it with its content (`Alt` copies). A click without movement opens the popover. Composites show no standard drag handle; blocks without a kind icon keep theirs.
+- **Icon visibility.** The settings value `blocks.kindIcon` is `'always'` (default) or `'hover'`. With `'hover'` the icon is invisible (120 ms fade) until the composite or its chips are hovered, its popover is open or the icon has keyboard focus; a nested composite's hover also reveals the icons of the composites around it. The invisible icon stays focusable and clickable, and dragging it works as soon as the pointer reaches it.
+- **Changing the type** asks first. Choosing another kind shows an inline warning in the popover instead of applying it: „Art wirklich ändern? Beim Wechsel zu „<Kind>“ gehen diese Angaben verloren:“ followed by the field values the new kind does not declare (`setCompositeKind` keeps only the meta keys of the new kind), or just „Art wirklich ändern?“ when nothing would be lost. „Ändern“ runs `setCompositeKind` for the composite resolved at that moment, „Abbrechen“ keeps the kind.
+- **Read-only editors.** Chips and popover render without edit affordances: no status menu, no `×`/`+`, the type as plain text instead of the dropdown, disabled fields, the summary as plain text. The icon still opens the popover but cannot be dragged.
+- **Layout.** The chips on the title line run on to the editor's right edge; nothing reserves a margin column. The composite node view's own description and tags rows stay in the document as data, but `composites.css` hides them: chips and popover are their only editors. The description is the *summary* in the popover.
+
+The hover bar of `BlockAction`s is right-aligned 8px inside the editor's right edge for every block and is hidden while the editor is read-only.
+
+### Headings ↔ composites
+
+`convertHeadingsToComposites({ recursive, scope, kind })` and `convertCompositesToHeadings({ recursive, scope })` are editor commands; `convertBlockTo(target)` converts one block. Every conversion runs in a single transaction, so **one undo step** reverses it and redo restores it:
+
+```ts
+editor.commands.convertHeadingsToComposites({ recursive: true, scope: 'document', kind: 'section' })
+editor.commands.undo() // back to the headings, in one step
+editor.commands.convertBlockTo({ type: 'composite', kind: 'task' }, pos)
+editor.commands.convertCompositesToHeadings({ recursive: false, scope: 'heading' })
+```
+
+Flattening keeps description, tags and meta fields as text below the heading, so nothing is lost silently; a document title above the headings stays as is.
+
+### Conversion providers
+
+The „Umwandeln in …“ menus and `convertBlockTo` run over the conversion providers of the preset's features. A provider is inert data: `targets(editor, node)` (what it offers for `node`), `parseTarget(id)` (the target an id names, or `null`), `label(target)`, `convert(state, $start, target)` and optionally `handlesSource(node)`.
+
+- The **owner** of a target is the first provider, in feature order, whose `parseTarget` parses its id. It supplies the label and, unless another provider claims the source block, executes the conversion.
+- A provider that returns true from **`handlesSource(node)`** claims every conversion of such source blocks. The composite feature uses it for composites: converting a composite into a paragraph, heading, list, quote or code block is executed by the composite provider (it unwraps the composite), while `composite:<kind>` targets are owned by its second provider (wrap a block, a heading with its section or switch kind).
+- `coreFeature()`'s provider declines every target that is not a core target, so features can add targets without interfering with it.
+- A target id advertised by two providers for the same block throws (`the conversion target "paragraph" is advertised by more than one provider`) instead of silently picking one.
+
+A feature of your own adds targets the same way: `defineEditor({ features: [coreFeature(), { id: 'mine', conversions: [myProvider] }] })`.
+
+### Vue-free schema entry
+
+`@ecsplico/editor/composites/schema` imports no Vue, node view or feature factory. A server that validates or seeds documents builds its schema from it:
+
+```ts
+import { getSchema } from '@tiptap/core'
+import { coreSchemaExtensions } from '@ecsplico/editor/core/schema'
+import { compositeSchemaExtensions } from '@ecsplico/editor/composites/schema'
+
+const schema = getSchema([...coreSchemaExtensions(), ...compositeSchemaExtensions({ kinds })])
+```
+
+It also exports the pure helpers: `defaultCompositeKinds`, `compositeKind`, `compositeJSON`, `compositeConversions`, `convertCompositeBlocks`, `blocksFromMarkdown`, `splitCompositeFences`, `compositeFence`, `groupHeadingsIntoComposites`, `flattenCompositesToHeadings`, `headingGroupRange`, `compositeChromeBlocks`, `structureCompositeBlocks` and `migrateLegacyContent`. `@ecsplico/editor/composites` (framework-free) re-exports them next to the node views (`Composite`, `CompositeTags`), `Structure`/`structureOf`, the framework-free rows and anchors models (`createCompositeRows`, `observeCompositeAnchors`), `compositeFeatureCore(ui)` and the helpers below. The bindings are `@ecsplico/editor/composites/vue` (`compositeFeature()`, `CompositeTable`, `CompositeInspector`, `SettingsEditingTab`, `useCompositeRows`, `useCompositeAnchors`, ...) and `@ecsplico/editor/composites/react` (the same names as React components and hooks; `CompositeTable` and `CompositeInspector` take `editor` and are placed beside the editor, `CompositeTable` has `onSelect`, `CompositeInspector` a `document` node and `documentFocused`).
+
+### Outline and Markdown export helpers
+
+- `compositeOutline(doc, hiddenKinds)` reads the document as a tree of composites (`OutlineNode`: key, id, position, kind, title, summary flag, children); composites of a hidden kind drop out and their descendants move up. `canMoveBlockInto(editor, id, targetId)` and `moveBlockInto(editor, id, targetId)` move a block to the end of a composite's body (or the document with `null`) in one transaction.
+- `headingsMarkdown(editor, blocks, level)` exports blocks as Markdown with every composite turned into a heading (the outermost at `level`) followed by its description, tags and body; `documentCompositeMarkdown(editor, node)` does the same for one composite as a document, `markdownFileName(node)` names the file and `downloadText(filename, text)` offers it as a download.
+
+The heading-only outline of a plain editor stays `@ecsplico/editor/outline` (`headingOutline`, `revealBlockInEditor`); its component is `EditorOutline` from `/outline/vue` or `/outline/react`.
+
+### Metadata table and properties panel
+
+Two components show the composites' metadata beside an editor. Both take the editor from the surface's `ready` event as a prop, follow it when it changes, and render their empty state without one.
+
+- `CompositeTable` (prop `editor?: Editor`; event `select(row)`) lists every composite as a sortable, filterable table: Baustein (indented by nesting), Art, one column per meta field of the kinds in the document (select values show their option label, dates are formatted; `textarea` fields get no column), Tags and whether a summary exists. Above it: text search over title, summary and tags, kind and tag chips, one select per `select` field (for example Status), a reset and a row count. A header click sorts ascending, descending, then not at all. The table does not change the document; `select` hands the host the clicked row, so the host can switch back to the text and call `revealBlockInEditor(editor, row)` from `/outline`.
+- `CompositeInspector` (props `editor?: Editor`, `documentFocused?: boolean`; slot `document`) is a side panel that shows one section at a time, chosen by where the caret is. The „Dokument“ section shows before the editor was ever focused, while the caret is in editor text outside any Baustein, and while the host's document input is focused; the „Baustein“ section shows while the caret is in a Baustein (also after opening a row from `CompositeTable`). Clicking into the panel never switches sections, and there is no empty state. Pass `documentFocused` as `true` while your document-level input (e.g. the title field) has the focus: the panel then switches to „Dokument“ and stays there after the input blurs, until the caret returns to the editor. A summary draft typed in the panel is committed when it switches away from „Baustein“. The „Dokument“ section starts with the host's `document` slot (the library knows nothing about titles, folders or dates of your storage), followed by what the document itself says: composites per kind and how many have a summary, all tags, all mentions. The „Baustein“ section edits the composite under the caret: kind, summary (as text; formatting on the unchanged text stays, a summary with mentions or tags is read-only there and edited in the document), tags with suggestions and creation, one input per meta field, and the summary state. Every edit is one editor transaction, so it reaches collaborators and undo like any other edit. A summary typed in the panel is written only while the document still holds the text the draft started from; when a collaborator changed it meanwhile, their text wins and is loaded into the panel. A read-only editor (`EditorSurface`'s `editable`) disables the controls. Give the panel its width and border through `class`. Host rows in the slot match its layout with `<dl class="grid grid-cols-[6.5rem_minmax(0,1fr)] items-start gap-x-3 gap-y-2">`, `dt.min-h-6.leading-6.text-muted` and `dd.min-h-6.leading-6.text-highlighted`.
+
+```vue
+<CompositeTable v-if="view === 'table'" :editor="editor" @select="openRow" />
+<CompositeInspector :editor="editor" class="w-80 border-l border-default">
+  <template #document>
+    <MyDocumentFacts />
+  </template>
+</CompositeInspector>
+```
+
+Own views read the same model: `useCompositeRows(editor)` returns `rows` (`CompositeRow`: key, id, position, kind with label and icon, title, summary text and whether it is text only, tags, `meta`, the kind's fields, depth), `tags`, `kinds` (with counts), `mentions` and `focused` (the composite under the caret), re-read once per frame after a document change. `setCompositeMetaField(editor, row, key, value)`, `setCompositeTags(editor, row, tags)` and `setCompositeDescription(editor, row, text, expected?)` write in one transaction and find the composite again by its block ID, so a row read before a remote change stays usable. `setCompositeDescription` stores `compositeDescriptionText(text)` (one line), replacing only the changed span so marks on the rest stay; it returns `false` instead of dropping a mention or tag in the summary, or, with `expected`, when the summary no longer holds that text. `compositeRows(doc, kinds)` is the same read without Vue.
+
+### Settings panel and modal
+
+Features contribute settings *tabs* (`settingsTabs: ctx => [{ id, label: ctx.t('…'), icon?, component, props? }]`, a factory over the app context so labels follow its language); the UI that shows them is core and decoupled from any one feature:
+
+- `EditorSettingsPanel` (props `preset`, `contentClass?`; `v-model:tab`) renders one tab per contributed tab, wherever you place it. With **no tab** it renders nothing.
+- `EditorSettingsModal` (props `preset`; `v-model:open`, `v-model:tab`) is the same panel in a popup: a Nuxt UI modal titled „Einstellungen“ (`settings.title`; "Settings" with `locale: 'en'`) with a fixed width (`42rem` from the `sm` breakpoint), a blurred, dimmed backdrop, the panel in a scroll area of fixed height (`h-[32rem]`) and a „Schließen“ footer; the description says whether the values apply to the account or to this browser (`synced`). With no tab it renders nothing.
+- `EditorSurface` takes **`settingsUi`**: `'internal'` (default) mounts the modal itself and opens it from the toolbar's settings entry; `'external'` mounts nothing and emits **`settingsOpen(tab?)`** instead, so the host opens its own settings page, drawer or panel, or places an `EditorSettingsModal` itself (the playground does; the example above sets the shown tab from the event). Without any contributed tab the surface neither opens nor emits, and the toolbar's settings entry is hidden.
+- The values are shared app settings (`useEditorSettings()`): several panels and editors edit the same preferences, stored per account when a server is configured and per browser otherwise. Another feature's tab (for example the AI tab) appears in the same panel as soon as its feature is part of the preset.
+
+## File import into composites
+
+`compositeMediaFeature()` from `@ecsplico/editor/integrations/composite-media` connects two features that know nothing of each other: with it, every imported file lands wrapped in a `document` composite. It `requires` `composites` and `media` (`defineEditor` throws when either is missing); neither of them imports it, so `core + media` and `core + composites` bundles stay free of it (`bun run check:editor-entries` proves it with the `media`, `composites` and `composite-media` fixtures).
+
+```ts
+import { compositeFeature } from '@ecsplico/editor/composites/vue'
+import { compositeMediaFeature } from '@ecsplico/editor/integrations/composite-media'
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { mediaFeature } from '@ecsplico/editor/media/vue'
+
+const preset = defineEditor({ features: [coreFeature(), mediaFeature(), compositeFeature(), compositeMediaFeature()] })
+```
+
+Install it after `composites` and `media`; its CSS is the two feature stylesheets (`media.css`, `composites.css`).
+
+- **Wrapping.** It contributes the `wrapImport` pipeline stage. The blocks of every imported file — the parsed text or Markdown, or the uploaded image, audio, video or file block — go into one `document` composite. The title is the file name without its last extension (the whole name for `.env`); the meta fields hold `filename`, `mimeType` (the file's, else `text/markdown` for text and `application/octet-stream`), `size` and the import date; the details popover shows them. Drop, paste, the toolbar's media buttons, the `/` commands and the audio recorder all import through `editor.storage.media.importFiles`, so they all wrap. Without the integration the blocks are inserted as they are.
+- **Action.** It adds the `/` command „Datei importieren“ (`/datei`, available where composites may be inserted) that picks any files and imports them at the caret. Slash entries follow the feature order, so it is listed after the media entries when installed after `media`.
+- **Not included.** Summaries and transcription of imported documents need AI and belong to the AI integrations, not here.
+
+`wrapImport` allows one contributor: installing a second feature that contributes it throws, like every singleton pipeline hook.
+
+## AI on a core editor
+
+`aiFeature()` adds the AI features to a core editor: selection menu (rewrite tasks such as shorter/formal/translate and free prompts), the `/ai` command and a „KI" toolbar group, in-document review of rewrites (accept/reject per change), ghost autocomplete while typing (Tab accepts, Esc dismisses), model profiles and the `ai` settings tab. The sidebar (document chat and block generation) and the quick model switch are components you place yourself. It needs no composites, transcript, media, mentions or Yjs; `bun run check:editor-entries` proves it with a `core + ai` fixture.
+
+```vue
+<script setup lang="ts">
+import { aiFeature, AiReviewBar, AiSidebar, ModelQuickSwitch } from '@ecsplico/editor/ai/vue'
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { EditorSurface, EditorToolbar } from '@ecsplico/editor/vue'
+import type { Editor } from '@tiptap/vue-3'
+import { shallowRef } from 'vue'
+
+const preset = defineEditor({ features: [coreFeature(), aiFeature()] })
+const editor = shallowRef<Editor>()
+const sidebarOpen = shallowRef(false)
+</script>
+
+<template>
+  <EditorToolbar :editor="editor" />
+  <div class="flex">
+    <EditorSurface v-model="content" v-model:sidebar-open="sidebarOpen" :preset="preset" class="flex-1" @ready="editor = $event" />
+    <AiSidebar v-model:open="sidebarOpen" :editor="editor" class="w-[380px]" />
+  </div>
+</template>
+```
+
+`aiFeature()` needs no component setup: the model profiles come from the app's editor context (`createEditor()` installed as a Vue plugin; `createEditorContext()` on React), and its notices (rate limits, import problems) go to the surface's notifier. The React binding is `aiFeature()` from `@ecsplico/editor/ai/react` with the same components and hooks (`useAiAssistant`, `useDocumentChat`, `useModelProfiles`); the framework-free `@ecsplico/editor/ai` holds `aiFeatureCore(ui)` and the models behind the hooks (`createAiAssistant`, `modelProfiles`). Import the CSS after `core.css`:
+
+```css
+@import "@ecsplico/editor/styles/ai.css";
+```
+
+Components: `AiSidebar` (`editor`; `v-model:open`), `ModelQuickSwitch` (`slot`, optional `size` and `editor`; the choice applies to the whole slot; `editor` makes „Modelle verwalten…" open that editor's settings when the switch sits outside an `EditorSurface`), `AiReviewBar` (`editor`). `AiSelectionMenu` and `AiReviewBar` are overlays the surface mounts for the feature; they are exported for hosts that render their own editor chrome.
+
+### Backend contract and configuration
+
+The feature talks to four endpoints through the context's `fetch` (default `ofetch`, same origin). You provide them; the Nuxt app's server routes in `packages/editor/src/nuxt/runtime/server/api/ai` are the reference implementation and import the shared protocol from the package:
+
+| Endpoint | Purpose |
+|---|---|
+| `GET /api/ai/models` | `{ presets: ModelProfile[], slots: Record<ModelSlot, string> }` — server model presets (no keys) and the default preset per slot (`complete`, `rewrite`, `generate`) |
+| `POST /api/ai/generate` | SSE (`delta` / `done` / `error`) for selection tasks and block generation |
+| `POST /api/ai/chat` | SSE for the sidebar's document chat with edit operations |
+| `POST /api/ai/complete` | `{ text }` continuation for ghost autocomplete |
+
+The framework-free protocol (`AI_TASKS`, `AiTask`, `AiInput`, `ModelRef`, `ModelProfile`, `modelRefSchema`, `aiBlockSchema`, `AGENT_OP_TYPES`, `checkAgentOps`, `CHAT_LIMITS`, `AI_COMPLETE_LIMITS`, `AI_LIMITS`, …) is exported from `@ecsplico/editor/ai` (and `/ai/protocol`), so a server may import the same constants and Zod schemas. A 429 from any endpoint shows one German „zu viele Anfragen" toast instead of an error.
+
+Public AI configuration is inert data passed to `createEditor`:
+
+```ts
+app.use(createEditor({ ai: { slots: { complete: 'flashLite', rewrite: 'sonnet', generate: 'sonnet' }, transcription: false } }))
+```
+
+`slots` are the default preset ids per model slot until the user chooses one in the `ai` settings tab (stored in `settings.ai.slots`). API keys never reach the client: user-added profiles with their own endpoint/key are kept in this browser's `localStorage` only. In Nuxt the module's `tiptapEditor.ai` options (presets, slots, rate limit) and the env keys `NUXT_TIPTAP_EDITOR_AI_API_KEY` / `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY` supply the server side.
+
+### Extending what AI knows about the document
+
+By default the AI sees a flat document with no custom block kinds and no host blocks. Features adjust that through three optional hooks on `EditorFeature`:
+
+- `aiContext: (editor) => ({ kinds?, blocks?, structure? })` — what the model may build and how. It is **additive**: any number of features may contribute. `defineEditor` merges the contributions, concatenating `kinds` and `blocks` in feature order; `structure` (the preferred structure for generated content, `'flat'` | `'composite'`) may be set by one feature only. A block `id` described by two features, or a second feature setting `structure`, throws when the merged context is read (`aiContextOf(editor)`, which returns `{ kinds, blocks, structure }`), not when `defineEditor` runs.
+  - `kinds` — the composite block kinds the model may build. The composites feature contributes them.
+  - `blocks` — host blocks as `AiBlock { id, label, description, syntax, example }` (exported from `@ecsplico/editor/core`): `id` is the node type name and the `convert` target id, `label` the German name, `description` its purpose and allowed content, `syntax` the Markdown form with placeholders in angle brackets, `example` one complete example. The document chat and the generate tasks (sidebar and selection menu) list them in the system prompt and send them with the request, so the model can write them; the chat offers a block as `convert` target when a registered conversion provider parses its id. See [Extending guide: AI](./extending.md#ai) for the callout's contribution.
+- `formatAiResult: (editor, markdown, heading?) => string` — formats an AI result's Markdown (with the optional task heading) before the generic parse/normalize/structure pipeline. Without a contributor the result gets the normalized heading (`withHeading`); the `composite-ai` integration (below) contributes the composite-structure form. At most one feature may contribute it; `defineEditor` throws on a second one.
+- `aiBlockData: ({ editor, node, pos, signal }) => AiBlockDatum[] | Promise<AiBlockDatum[]>` — material a feature supplies for one Baustein before „Baustein füllen (KI)“ asks the model (`AiBlockDatum { label, text }`; the three types are exported from `@ecsplico/editor/core`). It is **additive**: every contributor runs for the Baustein in parallel, and `defineEditor` concatenates their entries in feature order (`aiBlockDataOf(editor)` returns the merged provider; without contributors it resolves to no data). The library only collects: the fetch, the ranking and what the entries mean belong to your feature. `signal` aborts when the editor is destroyed. A contributor that throws or rejects cancels the fill with the notice „Daten für den Baustein fehlen“, and no generate request is sent. The playground's `epikriseFeature()` (`app/editor/epikrise/feature.ts`) fetches two example paragraphs from its own route for the Epikrise kind.
+
+AI results are parsed with `parseBlocks(editor, markdown)`: inline replacements use the pre-segmentation `parsed` content, block insertion uses `blocks`.
+
+### Positions and collaboration
+
+Selection menu, sidebar and review capture ranges as document anchors. Without an `anchorResolver` anchors map through local transactions only, and the review writes with a `closeHistory` step so rewriting does not merge into typing. A collaboration feature contributes an `AnchorResolver` that keeps anchors valid across remote edits and wraps the review's undo step; the AI feature imports no Yjs code either way.
+
+## AI integrations: composite AI and transcript AI
+
+`aiFeature()` knows neither composites nor transcripts. Two integration features connect it to them; each imports only the features it names, no parent feature imports the integration, so `core + ai`, `core + composites` and `core + transcript` bundles stay free of them (`bun run check:editor-entries`: fixtures `composite-ai` and `transcript-ai` allow exactly their features plus the integration, and the `ai`, `composites` and `transcript` fixtures forbid any integration module).
+
+| Factory (`@ecsplico/editor/integrations/…`) | `requires` | Contributes |
+|---|---|---|
+| `composite-ai` → `compositeAiFeature()` | `composites`, `ai`, `media` | block actions „Baustein füllen (KI)“ (kinds with `ai`), „Zusammenfassung erzeugen (KI)“ and „Transkribieren (KI)“; the single `formatAiResult` |
+| `transcript-ai` → `transcriptAiFeature()` | `transcript`, `ai` | block action „Transkript bereinigen (KI)“ and the same row in the AI selection menu |
+
+```ts
+import { aiFeature } from '@ecsplico/editor/ai/vue'
+import { compositeFeature } from '@ecsplico/editor/composites/vue'
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { compositeAiFeature } from '@ecsplico/editor/integrations/composite-ai'
+import { compositeMediaFeature } from '@ecsplico/editor/integrations/composite-media'
+import { transcriptAiFeature } from '@ecsplico/editor/integrations/transcript-ai'
+import { mediaFeature } from '@ecsplico/editor/media/vue'
+import { mentionsFeature } from '@ecsplico/editor/mentions'
+import { transcriptFeature } from '@ecsplico/editor/transcript/vue'
+
+// The integrations are framework-free and fit both surfaces; on React take the bindings from `/<x>/react`.
+const preset = defineEditor({
+  features: [
+    coreFeature(), mediaFeature(), transcriptFeature(), compositeFeature(), mentionsFeature(), aiFeature(),
+    compositeMediaFeature(), compositeAiFeature(), transcriptAiFeature(),
+  ],
+})
+```
+
+Install each integration after the features it requires (the order of the list is the order of toolbar/menu entries; actions carry their own `order`). `defineEditor` throws `feature "composite-ai" requires "ai", which is not installed` (likewise for `composites`, `media`, and for `transcript-ai` without `transcript` or `ai`) — it never installs a missing dependency. `bun run check:editor-composition` loads the real modules and asserts every one of these rejections, the accepted full composition and the single-`formatAiResult` rule. CSS: the stylesheets of the features in the preset (`core.css`, `media.css`, `composites.css`, `transcript.css`, `ai.css`); the integrations bring none.
+
+**`compositeAiFeature()`**
+
+- **Fill a Baustein.** „Baustein füllen (KI)“ appears on a composite whose kind has an `ai` configuration (`CompositeKind.ai`). It sends the Baustein's brief (`compositeAiBrief(editor, pos)`: kind and `purpose`, titles of the enclosing composites as `path`, title, description, non-empty field values with `select` option labels, the instruction — a non-empty `meta[ai.instructionsField]` replaces `ai.instructions` — and the `skeleton` with `{key}` replaced by `meta[key]`, the current body as Markdown) plus the document as context to the task `fill-block` (`generate` slot, `POST /api/ai/generate`, rejected with 400 „Baustein fehlt“ without `block`). The result opens the in-document diff review over the Baustein's body; title and fields stay untouched. `fill-block` is offered nowhere else (`blockTasks()` skips tasks with `needsBlock`).
+- **Material from features.** Before the request, `fillComposite` runs the preset's merged `aiBlockData` for the Baustein (above). The entries travel as `block.data` in order, at most 10, each `text` cut to `AI_LIMITS.block.data` (20000) characters; the task prompt prints each as `<label>:` followed by the quoted text.
+- **Composite summary.** „Zusammenfassung erzeugen (KI)“ appears on a composite whose body has text (or, for an audio/video `document`, a `meta.transcript`). It streams a `summarize` task (`rewrite` model slot) from `POST /api/ai/generate` and replaces the composite's description with it; the details popover shows it as the summary. The description is anchored when the request starts, so edits made while it streams do not misplace the result.
+- **Media transcription.** „Transkribieren (KI)“ appears on a `document` composite holding an audio/video asset, only when the app's public AI configuration has `transcription: true` (`createEditor({ ai: { transcription } })`). It calls `POST /api/ai/transcribe` with the asset reference (`{ documentId, name }`) through the context's `fetch` and stores the text in `meta.transcript`. Your server provides the endpoint; the Nuxt app's route in `packages/editor/src/nuxt/runtime/server/api/ai` is the reference.
+- **Composite-structure AI results.** With the `composite` structure setting, an AI result that carries a heading (sidebar „block generation“, selection/menu tasks with a heading) is formatted as a `section` composite fence (`::: section` with the heading and the result inside), so the generic pipeline inserts it as a section composite. In flat structure, or without a heading, the result is unchanged from the base AI behaviour. The feature is the preset's only `formatAiResult` contributor — the base AI feature stays composite-free.
+- **Exports** (`@ecsplico/editor/integrations/composite-ai`): `compositeAiFeature`, `fillComposite(editor, pos, fetch, modelRef, notify, t)`, `summarizeComposite(editor, pos, fetch, modelRef, notify, t)`, `transcribeDocument(editor, pos, fetch, notify, t)`, `compositeSourceText`, `mediaAssetOf`, `COMPOSITE_BODY_START`. Notices go through the surface's `notify` in the language of `t` (`ctx.t`), the model through `modelProfiles(app)`.
+
+**`transcriptAiFeature()`**
+
+- **Transcript cleanup.** „Transkript bereinigen (KI)“ is a block action on a speaker segment or a block (composite, quote, list) holding segments, and „Transkript bereinigen“ is a row of the AI selection menu over a selection that overlaps segments. It sends `{ id, speaker, text }` per segment to `POST /api/ai/transcript-cleanup` and opens the cleaned texts as an in-document AI review, one change per segment. The model returns only new texts keyed by block ID, so speakers, order and segment count cannot change; over-long, stale and unusable segments are skipped with a German notice. Without `transcriptAiFeature()` neither the action nor the menu row exists.
+- **Server contract.** `@ecsplico/editor/integrations/transcript-ai/protocol` is Vue-free and server-importable: `TRANSCRIPT_CLEANUP_LIMITS`, `transcriptCleanupRequestSchema`, `transcriptCleanupMessages`, `transcriptCleanupChunks`, `parseTranscriptCleanup` and the request/response types. Your endpoint validates the request with the schema, cleans in chunks and answers `{ cleaned: [{ id, text }], failed }`.
+- **Exports** (`@ecsplico/editor/integrations/transcript-ai`): `transcriptAiFeature` (its `setup` teardown aborts a running cleanup), `createTranscriptCleanup(modelRef, fetch, notify, t)` → `{ running, cleanup, abort }`, `hasTranscriptSegments`.
+- Speaker-aware transformations that normalization already covers — `**Name:** text` lines becoming segments in imported or AI-written Markdown — stay with the `transcript` feature's `segment` stage; the integration adds only the cleanup.
+
+## Reference: AI surfaces, agent operations and composite fences
+
+### In-block AI versus block generation
+
+- **In-block AI** (`rewrite` slot) works on text inside one block or a selection and is applied through the review diff: the selection tasks, the composite summary and transcript cleanup. Ghost autocomplete is in-block too but has its own `complete` slot.
+- **Block generation** (`generate` slot) produces, replaces, converts or removes whole blocks: the tasks `generate`, `continue` and `transcript-*`, plus the chat agent operations. `fill-block` (block action „Baustein füllen (KI)“) is a `generate`-slot task too, but only reachable through that action.
+
+| Surface | What | Slot | Route |
+|---|---|---|---|
+| Ghost autocomplete (`ai.autocomplete` setting) | Inline continuation while typing | `complete` | `POST /api/ai/complete` |
+| `AiSelectionMenu`, selection mode | `reformulate`, `fix`, `shorter`, `formal`, `casual`, `translate`, `summarize` and the free prompt `custom` | `rewrite` | `POST /api/ai/generate` |
+| `AiSelectionMenu`, caret mode (`/ai`) | `continue` („Weiterschreiben“) and the free prompt `generate` | `generate` | `POST /api/ai/generate` |
+| `AiSidebar` quick actions | `blockTasks()` without the caret tasks: `generate`, `transcript-summary`, `transcript-minutes`, `transcript-action-items` | `generate` | `POST /api/ai/generate` |
+| `AiSidebar` chat agent | Answers with citations, proposes operations (below) | `generate` | `POST /api/ai/chat` |
+| Composite summary (block action, `composite-ai`) | Task `summarize` over the composite body → description | `rewrite` | `POST /api/ai/generate` |
+| Fill a Baustein (block action, `composite-ai`) | Task `fill-block` over the Baustein's brief → body, as review | `generate` | `POST /api/ai/generate` |
+| Transcript cleanup (block action, `transcript-ai`) | Cleans transcript segment texts | `rewrite` | `POST /api/ai/transcript-cleanup` |
+| Document transcription (block action, `composite-ai`) | Speech-to-text of an audio/video `document` → `meta.transcript`; „Zusammenfassung erzeugen (KI)“ then summarises the transcript when the body holds no text | none (transcription endpoint) | `POST /api/ai/transcribe` |
+
+A task's slot comes from `AiTask.slot` (`AI_TASKS`); `ModelQuickSwitch` in the selection menu and the sidebar changes the slot's profile in place. Inserted generation results (sidebar quick actions, `/ai` at the caret, agent `add` operations) go through the preset's `structure` stage: with the composites feature and the `blocks.structure` setting `'composite'`, headings are grouped into nested `section` composites, with `'flat'` composites are flattened into headings starting at `##`. A change of the setting applies to the next insertion. Rewrites (`replace-selection`, agent `update`) are never restructured.
+
+### Chat agent operations
+
+The model proposes edits through the `edit_document` tool. The server checks them (`checkAgentOps`, `@ecsplico/editor/ai/protocol`) and streams the valid ones as an `ops` event: `{ ops: AgentOp[], dropped: AgentOpProblem[], retries }`. Each operation gets a conversation-wide `op: 'op<n>'` id.
+
+| Type | Fields | Effect |
+|---|---|---|
+| `add` | `afterId: string \| null`, `markdown` | Insert block(s) after `afterId` (in the document or its composite body). `null` = document start, not allowed with a selection scope. |
+| `update` | `id`, `markdown` | Replace block `id`. A single paragraph, or one block of the same type and attributes, is diffed within the block. On a composite, a `::: kind` fence (exactly one composite) replaces the whole composite; unfenced markdown replaces only its body. |
+| `delete` | `id` | Remove the block (or the smallest list item, list or quote that would be invalid without it). |
+| `convert` | `id`, `to` | Change the block type, keeping the content. `to` is one of the request's `targets`: the targets the installed conversion providers advertise (`paragraph`, `heading1`–`heading3`, `bulletList`, `orderedList`, `blockquote`, `codeBlock`, plus `transcriptSegment` and `composite:<kind>` with those features). |
+
+Validation problems (`AgentOpProblemReason`): `unknown` (the id isn't in the document), `scope` (the id is outside the selection), `field` (a field is missing or invalid, e.g. empty `markdown` or more than `AGENT_LIMITS.markdown` = 8000 characters), `duplicate` (the same block is updated, converted or deleted twice), `limit` (more than `AGENT_LIMITS.ops` = 50 operations), `target` (`to` isn't among the request's `targets`). On problems the model is asked to retry, up to `AGENT_LIMITS.retries` = 2 times. Whatever is still invalid after that, or left out of a corrected list, is reported in `dropped`.
+
+**Review flow.** The client re-checks each operation against the scope the request was sent with and shows valid ones as in-document review changes the user accepts or rejects. An operation that can't be shown gets an outcome instead: `blocked`, `missing`, `unchanged`, `overlap` or `empty`. Every operation's outcome (`accepted`, `rejected`, `partial`, `invalid`, `pending`, …) is sent back as `feedback` with the next user message.
+
+**Document text** (`documentChatText(editor)`): one line per block, `[<id>] <markdown on one line>`. List and quote markers form the prefix (`- `, `1. `, `> `). A composite is a header line `[<id>] ::: kind {meta} | Title | Description | Tags: #a #b` (meta only when non-empty, empty parts omitted), followed by its body lines indented by two spaces and a closing line `  :::` without an id. The text is truncated at `CHAT_LIMITS.document` = 120000 characters.
+
+### Composite Markdown fence format
+
+```
+::: kind {meta-json}
+## Title
+> Description
+Tags: #a #b
+body blocks…
+:::
+```
+
+- The meta JSON is written only when it is non-empty (`::: section`). The parser requires a JSON object; otherwise the line stays plain text.
+- Fences nest. Every closer is a bare `:::` and closes the innermost open fence. An opener without a matching closer stays plain text.
+- Inner text: the first `#`…`######` heading becomes the title, a blockquote directly after it the description, a `Tags:` line the tags (lower-cased, de-duplicated), the rest the body (recursively). A missing title gives an empty title; an empty body gives one empty paragraph.
+- Known kind: `meta` keeps only that kind's field keys. Unknown kind: the id and meta are kept as given and the view falls back to the `section` presentation.
+
+Used by `editor.getMarkdown()` (the composite nodes' `renderMarkdown`), by AI results applied through the composites feature's `parseMarkdown` stage (`blocksFromMarkdown`; task results with a heading are wrapped in a `section` fence in `'composite'` structure, else titled with `##`, by the `composite-ai` integration's `formatAiResult`) and by the agent's `add`/`update` Markdown and system prompt.
+
+```
+::: task {"status":"doing","due":"2026-11-01"}
+## Angebot schreiben
+> Für Kunde Müller
+Tags: #vertrieb
+- Preise prüfen
+- Entwurf an Ben
+:::
+```
+
+### Stored settings
+
+`EditorSettings` (`@ecsplico/editor/settings`) is one version-1 JSON object shared by all editors of an app: `editing.{headingConversionScope ('container'), authorColors (false), authorColorStyle ('background'), commentsLayout ('margin')}`, `ai.{autocomplete (false), slots ({}), translateLanguage ('Englisch')}`, `blocks.{defaultKind ('section'), structure ('composite'), treeRoot ('folders'), kindIcon ('always'; 'hover' shows the composites' kind icon only on hover, focus or open details), dragHandle ('hover'; 'always' shows the drag handle of blocks without kind icon permanently)}` and `appearance.{theme (null)}` (the Obsidian theme id, `null` = standard look; see [Themes (Obsidian)](#themes-obsidian)). `parseEditorSettings(input)` deep-merges any input over those defaults (unknown keys dropped, invalid values replaced; a stored `blocks.metaVisibleDefault` of an older version is just dropped) and migrates the legacy flat per-browser shape `{ headingConversionScope }`; `PUT /api/editor/settings` instead requires the complete, valid shape (`editorSettingsSchema`). Settings tabs are contributed by features (`editing` by composites, `authors` and `comments` by their features, `ai` by AI, `appearance` by themes), so a preset without a contributing feature has no settings UI. A tab only edits its own fields; the other sections are written back unchanged, which is why one account can use a simple and an advanced editor without erasing the other's preferences.
+
+## File browser
+
+`DocumentTree` is the document drawer: folders and documents of *your* storage, with create, rename, move (drag and drop), delete with undo, per-item kind filters and the outline of the open document. It exists for both surfaces: `@ecsplico/editor/tree/vue` (Nuxt UI) and `@ecsplico/editor/tree/react` (shadcn/ui; needs `EditorContextProvider` and a mounted `Toaster`). The framework-free `@ecsplico/editor/tree` holds the `DocumentStore` contract and the view-state model (`createTreeView`, `treeView(context)`, `TreeViewModel`) that both components and their `useTreeView()` hooks sit on. It needs the settings context (`createEditor()` / `createEditorContext()`), the composites and media features' code (it reads the composite outline and imports files) and a `DocumentStore` that you implement over your storage and router; it does no HTTP or routing of its own.
+
+```vue
+<script setup lang="ts">
+import { DocumentTree } from '@ecsplico/editor/tree/vue'
+import type { DocumentStore } from '@ecsplico/editor/tree'
+import type { Editor } from '@tiptap/core'
+
+defineProps<{ store: DocumentStore, editor: Editor | undefined }>()
+const selectedFolder = defineModel<string>('selectedFolder', { default: '' })
+</script>
+
+<template>
+  <DocumentTree v-model:selected-folder="selectedFolder" :store="store" :editor="editor">
+    <template #document-actions="{ id }"><!-- optional host buttons per document --></template>
+  </DocumentTree>
+</template>
+```
+
+React, with the same `store` and a controlled folder:
+
+```tsx
+import type { DocumentStore } from '@ecsplico/editor/tree'
+import { DocumentTree } from '@ecsplico/editor/tree/react'
+import type { Editor } from '@tiptap/core'
+import { useState } from 'react'
+
+export function Drawer({ store, editor }: { store: DocumentStore, editor: Editor | undefined }) {
+  const [selectedFolder, setSelectedFolder] = useState('')
+  return (
+    <DocumentTree
+      store={store}
+      editor={editor}
+      selectedFolder={selectedFolder}
+      onSelectedFolderChange={setSelectedFolder}
+      documentActions={({ id }) => null /* optional host buttons per document */}
+    />
+  )
+}
+```
+
+- `editor` is the open page's editor (`undefined` when no document is open); take it from your page through a shared composable, as `useActiveEditor()` does in the Nuxt app.
+- `v-model:selectedFolder` (React: `selectedFolder` / `onSelectedFolderChange`, uncontrolled when omitted) is where new documents, new folders and your own import actions go. Bind the same state in your import button (the Nuxt app binds it in the layout and passes it to `AppDocumentTree`). The Vue `document-actions` slot is `documentActions` on React.
+- Place `DocumentTree` anywhere (a sidebar, a drawer); several can coexist, sharing one filter state per app (`useTreeView()` from `/tree/vue` returns the refs `nodeFilters` and `expanded`, from `/tree/react` the plain values, both with the framework-free `model`).
+- The outline entries under the open document follow the settings: composites in the preferred structure (a *virtual root* when `blocks.treeRoot` is `'file'`), headings otherwise.
+
+The full `DocumentStore` contract (loading states, mutation refresh, delete with undo, folder rules, name validation, who reports failures) and the runnable implementation are in the [integration guide](./integration.md#10-the-file-browser-and-documentstore); the host implementation is [`app/composables/useDocumentStore.ts`](../../../app/composables/useDocumentStore.ts).
+
+## Advanced Nuxt example
+
+The repository's Nuxt app is the runnable advanced reference: documents with real-time collaboration, the file drawer, AI, and a playground with two independent editors. It has no login: a visitor acts as one of the demo users `anna`, `ben` and `bernd` (`shared/utils/demo-users.ts`), starts as `anna` and switches in the user menu top right („Benutzer wechseln“, which reloads the page under the new user). Start it with `bun run dev` (port 3031); it needs `NUXT_SESSION_PASSWORD` (at least 32 characters, for the `nuxt-auth-utils` session cookie) and, for AI, the API key variables below in `.env`.
+
+**Walkthrough**
+
+1. Open `http://localhost:3031/`; you are `anna` and land on the home page: the file drawer on the left lists the documents and the folders, the main area reads „Kein Dokument ausgewählt“.
+2. Press „Neues Dokument“ (in the main area, or „Hinzufügen“ → „Neues Dokument“ on a drawer row) to create a document; the app opens `/documents/<id>` and the new document appears in the drawer. In the drawer you can also create folders, drag documents and folders between folders, rename, filter and delete with undo ([File browser](#file-browser)); each document row has an export button that downloads a `.cdoc` package.
+3. Type. Use the toolbar, the `/` menu, the drag handles and the hover block actions; the AI sidebar (the toolbar's AI button or `Mod-Shift-k`) and the settings cog in the header open their host-placed UI.
+4. Open the same URL in a second browser tab, or as another user in a second browser (or a private window) where you switch to `ben` in the user menu; the session cookie is per browser, so tabs of one browser share the user. Text and carets appear in both within a moment and the header badge reads „Synchronisiert“; each tab keeps its own undo history. Text carries its author (switch the colouring on with the toolbar's palette button), and a selection can be commented („Kommentar“, `Mod-Shift-m` for the margin) with replies, resolve and reopen visible to both.
+5. Optional: open `/playground` for two standalone editors with separate JSON and Markdown output, toolbars, sidebars and settings popups (`EditorSettingsModal`, opened from the pane's cog). The first select in the page header picks the editor that fills the page; the other one stays mounted, so its document, undo history and AI conversation survive the switch. Each starts from the first of its own samples; the second select in the page header („Beispiel“) loads another sample into the editor shown. **Editor A** (`AdvancedEditor` with host props) offers „Überblick“ (mention and tag chips, a task, a section with a nested note and a custom „Entscheidung“ composite, speaker segments, an image and a file block), „Gliederung“, „Transkript“ and „Leer“; hover a block for the host's „In Konsole loggen“ action and type `/datum` or `/decision`. **Editor B** (`EditorSurface` on the advanced features plus an own feature) starts with „Hinweise“: the toolbar has a „Hinweis“ button next to „Sprecherblock“ (`Mod-Shift-h`, also `/hinweis`), hovering a callout opens „Art des Hinweises“ to switch its tone, „Umwandeln in …“ offers „Hinweis“ on text blocks and turns a callout back into a core block, and „Markdown einfügen“ imports a heading, a `!!! warning` callout and a paragraph through the block pipeline. Open the settings popup and pick „Darstellung“ to try the themes: the whole app, header and drawer included, switches look.
+
+**Where each part lives**
+
+| Part | File |
+|---|---|
+| Collaborative page: `AdvancedEditor` with a `HocuspocusProvider` session, toolbar and `AiSidebar` placed by the page, editor-owned settings modal (`settingsUi` default `'internal'`), a „Text \| Tabelle“ switch to `CompositeTable` (a row returns to the text and reveals its Baustein) and a docked `CompositeInspector` with the page's own document facts in its `document` slot ([`DocumentProperties.vue`](../../../app/components/DocumentProperties.vue)) | [`app/pages/documents/[id].vue`](../../../app/pages/documents/[id].vue) |
+| Standalone page, Editor A: an `AdvancedEditor` with `settings-ui="external"` (the settings popup is placed by the pane below), custom composite kind, metadata, ability, block action and `/` command | [`app/pages/playground.vue`](../../../app/pages/playground.vue) |
+| Standalone page, Editor B: `defineEditor({ features: [...advancedEditor().features, calloutFeature()] })` mounted with `EditorSurface`, and the `abilities` prop `{ root: [...ROOT_ABILITIES, CALLOUT_ABILITY] }` that grants the callout's own ability | [`app/pages/playground.vue`](../../../app/pages/playground.vue) |
+| One playground pane, filling the page body (header with toolbar, switches and the `EditorSettingsModal` the editor's `settingsOpen` event opens, JSON and Markdown output; the AI sidebar comes in through a slot) and its state (`createPane`, `loadSample`, `showSettings`, `refreshMarkdown`) | [`app/components/PlaygroundPane.vue`](../../../app/components/PlaygroundPane.vue), [`app/editor/playground-pane.ts`](../../../app/editor/playground-pane.ts) |
+| Demo documents of both editors and the Markdown for „Markdown einfügen“ | [`app/editor/samples.ts`](../../../app/editor/samples.ts), assets [`public/demo/diagramm.svg`](../../../public/demo/diagramm.svg) and [`protokoll.txt`](../../../public/demo/protokoll.txt) |
+| The own block as a feature: node, node view, styles, feature (toolbar, `/`, hover menu, conversion) and conversion provider; walked through in the [extending guide](./extending.md) | [`app/editor/callout/`](../../../app/editor/callout): `node.ts`, `CalloutView.vue`, `index.ts`, `callout.css`, `feature.ts`, `convert.ts` |
+| Module registration (`@ecsplico/editor/nuxt`) | [`nuxt.config.ts`](../../../nuxt.config.ts) |
+| Adapter plugin: `setEditorAdapter` with sessions, document store, Yjs state, assets and per-user settings | [`server/plugins/editor-adapter.ts`](../../../server/plugins/editor-adapter.ts) |
+| Store adapter: documents, Yjs state, assets, settings, users on the file system | [`server/utils/documents.ts`](../../../server/utils/documents.ts), [`state.ts`](../../../server/utils/state.ts), [`assets.ts`](../../../server/utils/assets.ts), [`settings.ts`](../../../server/utils/settings.ts), [`users.ts`](../../../server/utils/users.ts) |
+| File drawer: `DocumentTree` over the host's `DocumentStore` (routes, `$fetch`, toasts, delete-with-undo), selected folder held by the layout | [`app/layouts/default.vue`](../../../app/layouts/default.vue), [`app/components/AppDocumentTree.vue`](../../../app/components/AppDocumentTree.vue), [`app/composables/useDocumentStore.ts`](../../../app/composables/useDocumentStore.ts) (the `.cdoc` export button comes in through the `document-actions` slot; the format stays in the host) |
+
+The page and its components import only public entries: `AdvancedEditor` and `advancedEditor` from `@ecsplico/editor/vue/advanced`, `EditorToolbar`, `EditorSettingsModal`, `EditorSurface` and `useEditorUi` from `@ecsplico/editor/vue`, `defineEditor` and `parseBlocks` from `@ecsplico/editor/core`, `ROOT_ABILITIES` from `@ecsplico/editor/core/schema`, `AiSidebar` from `@ecsplico/editor/ai/vue`, `CommentsMargin` from `@ecsplico/editor/comments/vue`, `CompositeTable`/`CompositeInspector` from `@ecsplico/editor/composites/vue`, `defaultCompositeKinds` from `@ecsplico/editor/composites`, `DocumentTree` from `@ecsplico/editor/tree/vue` (the `DocumentStore` type from `@ecsplico/editor/tree`). The callout files add `commandItem`, `ConversionProvider` and the conversion helpers from `@ecsplico/editor/core`. The app-level editor context (settings sync, fetch, public AI configuration) comes from the Nuxt module, no per-page setup. The React counterpart of the document page is [`examples/react-advanced`](../../../examples/react-advanced) ([Advanced editor in React](#advanced-editor-in-react)).
+
+**Optional AI configuration.** The editor works without AI credentials; AI requests then fail with the server's message. Keys come from the environment only (see [AI configuration and secrets](./integration.md#5-ai-configuration-and-secrets)): `NUXT_TIPTAP_EDITOR_AI_API_KEY` (shared fallback for every preset), `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY` (one preset; `flashLite` → `NUXT_TIPTAP_EDITOR_AI_PRESETS_FLASH_LITE_API_KEY`) and `NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY` (only with `ai.transcription` configured).
+
+**Two editors in one page.** Every component placed beside an editor names it: `EditorToolbar :editor`, `AiSidebar :editor`, `useEditorUi(() => editor)`. Each editor (`AdvancedEditor` or `EditorSurface`) registers its chrome (settings routing, sidebar toggle, block actions) under its own Tiptap instance, so editor B's toolbar never formats editor A and `openSettings` reaches the settings popup of the editor that asked. Only the values in the popups are shared; they are the app's settings, saved once for the account. External content replacement (picking a sample) emits no update event, so the page refreshes the Markdown output itself once the editor took the new content (`loadSample` in `app/editor/playground-pane.ts`).