@ecsplico/editor 0.0.0-stage → 2.0.0

package/docs/integration.md

@@ -0,0 +1,537 @@
+# Integration guide: feature composition, settings, file browser, server, collaboration, AI and migration
+
+How a host composes the editor from features, where settings and view state live, how the file browser plugs into the host's document storage, how a Nuxt/Nitro host connects the editor package to its sessions and AI providers, how two browsers collaborate on one document, how a server validates stored content without any UI code, and how to migrate from the former `#tiptap-editor` Nuxt module. Client-only editors (the [simple editor](./usage.md), media, AI with a host backend of your own) need only §1, §11 and §13.
+
+## Contents
+
+1. [Feature composition and entries](#1-feature-composition-and-entries)
+2. [Register the Nuxt module](#2-register-the-nuxt-module)
+3. [`EditorAdapter`: auth and storage](#3-editoradapter-auth-and-storage)
+4. [Server routes and authentication](#4-server-routes-and-authentication)
+5. [AI configuration and secrets](#5-ai-configuration-and-secrets)
+6. [Collaboration on the client](#6-collaboration-on-the-client)
+7. [Block UI (drag handle, hover actions)](#7-block-ui-drag-handle-hover-actions)
+8. [Vue-free advanced schema for servers](#8-vue-free-advanced-schema-for-servers)
+9. [Production](#9-production)
+10. [The file browser and `DocumentStore`](#10-the-file-browser-and-documentstore)
+11. [Settings persistence and app lifetime](#11-settings-persistence-and-app-lifetime)
+12. [Migrating from `#tiptap-editor`](#12-migrating-from-tiptap-editor)
+13. [Dependency rules and bundle proof](#13-dependency-rules-and-bundle-proof)
+
+## 1. Feature composition and entries
+
+| Entry | Side | Contents |
+|---|---|---|
+| `@ecsplico/editor/nuxt` | build | The Nuxt module (`defineNuxtModule`, config key `tiptapEditor`). Registers the Nitro scan dir, the client context plugin, AI runtime config, `build.transpile`, the `ui.css` Tailwind `@source`, Nitro `externals.inline` and `experimental.websocket`. |
+| `@ecsplico/editor/server` | server | Framework-free (no Nuxt, h3, Nitro, Vue or React): `createCollabServer({ adapter, schemaExtensions, hooks })` → `{ hocuspocus, handleConnection, forgetDocument, liveContent, contentChanged, stats, close }`, `createAiModels({ presets, apiKey, slots, transcription })`, `createRateLimiter({ max, windowMs })`, `EditorAdapter`, `HttpError`. Also the process-wide registry the Nuxt module and Nitro hosts use: `setEditorAdapter`, `forgetCollabDocument`, `liveContent`, `collabContentChanged`, `collabStats`; it shares module instances with the package's own routes. |
+| `@ecsplico/editor/server/handlers` | server | One handler per editor/AI route, `(ctx, request) => Promise<HandlerResponse>` (`usersGet`, `tagsGet`, `settingsGet/Put`, `assetGet/Post`, `themesGet`, `themeGet/Post/Delete`, `modelsGet`, `chatPost`, `generatePost`, `completePost`, `transcribePost`, `transcriptCleanupPost`) and the zod schemas of their bodies (`chatBodySchema`, …). Map any HTTP server's request onto `HandlerRequest` and send the `HandlerResponse`; `HttpError` carries the status. |
+| `@ecsplico/editor/server/node` | server (Node) | `listenCollab(collab, { port, host })`: a Node HTTP server that serves a `createCollabServer` over websockets, for a plain script (needs the `crossws` dependency; Node only). |
+| `@ecsplico/editor/collab`, `/collab/vue`, `/collab/react` | browser | framework-free `collabFeatureCore(ui?)`, `yjsAnchorResolver`; `collabFeature()` per surface |
+| `@ecsplico/editor/block-ui`, `/block-ui/vue`, `/block-ui/react` | browser | framework-free `blockUiFeatureCore(ui)`, `blockActionsFor`, `effectiveTarget`; `blockUiFeature()`, `BlockUi`, `BlockActionsOverlay` per surface |
+| `@ecsplico/editor/authors`, `/authors/vue`, `/authors/react` | browser | framework-free `authorsFeatureCore(ui)`, `currentAuthor`, `documentAuthors`; `authorsFeature()` plus `AuthorColorsButton`, `AuthorColorsPanel`, `SettingsAuthorsTab` per surface (see the [usage guide](./usage.md#authors-and-comments)) |
+| `@ecsplico/editor/comments`, `/comments/vue`, `/comments/react` | browser | framework-free `commentsFeatureCore(ui, { model? })`, `createCommentsModel`; `commentsFeature({ model? })` (requires `collab` unless a host `model` backs it), `useComments`, `CommentsMargin`, `CommentsPopover`, `CommentsListMenu`, … per surface |
+| `@ecsplico/editor/themes`, `/themes/vue`, `/themes/react` | browser | framework-free `themesFeatureCore(ui)`, `startObsidianTheme`, `scopeThemeCss`, `THEME_SCOPE_CLASS`; `themesFeature()` (site-wide Obsidian themes; see the [usage guide](./usage.md#themes-obsidian)) and `SettingsAppearanceTab` per surface; Vue-free in `/themes/schema`: `ThemeRecord`, `THEME_ID`, `MAX_THEME_BYTES`, `themeManifestSchema` |
+| `@ecsplico/editor/schema/advanced` | anywhere | Vue-free `advancedSchemaExtensions()`; imports no Vue, UI or browser code |
+| `@ecsplico/editor/styles/collab.css`, `/block-ui.css`, `/authors.css`, `/comments.css`, `/themes.css` | browser | Remote carets, block-range selection, author colouring, comment highlights and cards, the Obsidian variable bridge. The Nuxt module adds every feature stylesheet to `css` (`themes.css` last). |
+
+The server logic (`src/server/`) runs in any Node process: `createCollabServer`, `createAiModels`, `createRateLimiter` and the route handlers take their adapter and configuration explicitly. The Nuxt module is a thin wrapper: the file-based Nitro routes in `src/nuxt/runtime/server/` parse the request, call the handler of `@ecsplico/editor/server/handlers` and send its answer; the collab route and plugins mount one `createCollabServer` kept by `setEditorAdapter`/`configureEditorServer`. A plain script needs no Nitro at all:
+
+```ts
+import { createCollabServer } from '@ecsplico/editor/server'
+import { listenCollab } from '@ecsplico/editor/server/node'
+
+const collab = createCollabServer({ adapter }) // adapter.authenticate({ headers, token }) decides who may connect
+const { url, close } = await listenCollab(collab, { port: 4000 })
+// browser: new HocuspocusProvider({ url, name: documentId, document, token })
+```
+
+### Per-feature entries: framework-free, Vue, React
+
+Every feature that has a UI is split in the same four entries, so a host takes exactly the layers it uses:
+
+| Entry | Contents | May import |
+|---|---|---|
+| `./<x>` | The feature's logic: `<x>FeatureCore(ui)`, the **models** (`create*`, `*Model`: framework-free stores such as `createCommentsModel`, `createCompositeRows`, `createAiAssistant`, `createDocumentChat`, `modelProfiles(app)`), Tiptap extensions and plugins, helpers | Tiptap/ProseMirror, `/core`, `/settings`; no `vue`, `react`, `@nuxt/ui` or `sonner` |
+| `./<x>/vue` | `<x>Feature(): VueFeature`, the feature's Vue components and node views, thin Vue **hooks** (`useComments`, `useCompositeRows`, `useAiAssistant`, `useModelProfiles`, `useFileImport`, …) over the models | `vue`, `@tiptap/vue-3`, Nuxt UI; never `react` |
+| `./<x>/react` | `<x>Feature(): ReactFeature`, the React components (shadcn/ui) and node views, the React hooks over the same models | `react`, `@tiptap/react`, Radix, `sonner`; never `vue` |
+| `./<x>/schema` | Node/mark specs, protocol schemas and limits for servers and validators | no UI, no DOM |
+
+Entries that exist per feature: `media`, `transcript`, `composites`, `authors`, `comments`, `ai`, `collab`, `block-ui`, `themes` (with `/schema` where the feature owns document nodes or a protocol), `outline` and `tree` (`/vue`, `/react`, no `Core(ui)`). `mentions` is framework-free alone (`mentionsFeature(): EditorFeature<never>`, usable in both layers). The three integrations (`integrations/composite-media`, `composite-ai`, `transcript-ai`) are framework-free alone too: they only wire other features' models, so `compositeMediaFeature()`, `compositeAiFeature()` and `transcriptAiFeature()` fit a Vue and a React preset unchanged.
+
+- **The UI binding contract.** `features/<x>/feature.ts` exports `<x>FeatureCore<C>(ui: <X>Ui<C>): EditorFeature<C>`: all feature behaviour (extensions, commands, toolbar items, slash commands, settings tabs, conversions) with the UI left open as the typed interface `<X>Ui<C>` (for example `CommentsUi`: `toolbarButton`, `overlay`, `settingsTab`; `MediaUi`: `recorderModal`, `nodeViews`). `C` is the framework's component type. `./<x>/vue` fills it with Vue components, `./<x>/react` with React components; a host writing its own chrome (another UI kit, a test) calls `<x>FeatureCore(ui)` with its own components. `EditorFeature<never>` means “no components at all”: such a feature (`coreFeature()`, `mentionsFeature()`, the integrations) is accepted by both presets.
+- **Notices.** Features never import a toast library. A user-facing message is a `Notice` (`{ id?, title, description?, kind?, icon?, duration? }`) sent to a `Notifier` (`(notice) => void`, optional `dismiss(id)`; `silentNotifier` drops everything), from `/core`. A feature reads it as `ctx.notify` in its factories (`FeatureContext.notify`), app-level models (model profiles, the rate-limit notice) as `EditorContext.notify`, set with `createEditorContext({ notify })`. Vue: `vueNotifier(useToast())` shows Nuxt UI toasts (the page needs `<UApp>`); `createEditor()` installs a *queued* notifier (`createQueuedNotifier()`) that holds notices raised before the first `EditorSurface` exists and shows them through that surface's `useToast()`. React: `reactNotifier` shows sonner toasts; pass it as `createEditorContext({ notify: reactNotifier })` and mount sonner's `Toaster` (re-exported from `@ecsplico/editor/react`) once per page, otherwise no notice is visible. `id` replaces a visible toast, `duration: 0` keeps it until replaced or dismissed.
+- **`setup` and teardown.** A feature's `setup(ctx)` runs once per mounted surface and may return a teardown function that the surface runs when it unmounts. Per-app runtimes dedupe inside and hand back a release: `startObsidianTheme(ctx)` is reference-counted per app, so the React `themesFeature()` removes the theme when the last surface that started it unmounts, while the Vue `themesFeature()` (call it during component setup) keeps it for the life of the Vue app through the `lifetime` hook of `ThemesUi`, because the theme styles the whole site. Run own per-app side effects there instead of in a component.
+- **Models versus hooks.** State and logic are framework-free `createStore` stores (from `/core`: `createStore`, `derived`, `ReadonlyStore`) inside the models; the hooks only subscribe: React `useStore(store)` (from `/react`), Vue `useStoreRef(store)` (a readonly ref, from `/vue`; `useWritableStoreRef(store)` for two-way refs, `trackedStore(store)` for a store whose `get()` Vue tracks, `storeFromRef(ref)` the other way round), all from the one `vue/store-ref` module, used inside the thin `use*` hooks of the feature. Notices follow one policy on both surfaces: `notifierOf(editor, app)` (from `/core`) picks the editor's surface notifier, else the app context's, when a notice is shown; `useNotifier(editor?)` (from `/vue` and `/react`) is its hook form, so a host that passes `createEditor({ notify })` / `createEditorContext({ notify })` receives every notice of the hooks, including the AI rate-limit notice (`useAiAssistant(editor?)`, `useDocumentChat(editor?)`, `useFileImport(editor?)`). A host that wants a different framework (or a script) uses the model directly.
+
+### Feature composition
+
+An editor is a list of features. Every feature is imported from its own entry, so a feature you do not import is not in your bundle:
+
+```ts
+import { compositeFeature } from '@ecsplico/editor/composites/vue'
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { compositeMediaFeature } from '@ecsplico/editor/integrations/composite-media'
+import { mediaFeature } from '@ecsplico/editor/media/vue'
+
+// Order = order of toolbar groups, menu entries and the schema.
+const preset = defineEditor({ features: [coreFeature(), mediaFeature(), compositeFeature(), compositeMediaFeature()] })
+```
+
+- `defineEditor` checks `requires`: an integration listed without the features it connects (`commentsFeature()` needs `collab`; `compositeMediaFeature()` needs `composites` and `media`; `compositeAiFeature()` needs `composites`, `ai`, `media`; `transcriptAiFeature()` needs `transcript`, `ai`) throws at composition time. `bun run check:editor-composition` keeps that behavior.
+- Own blocks and features: see the [extending guide](./extending.md).
+- Prebuilt compositions: `simpleEditor()` (`@ecsplico/editor/presets/simple`, core only) and, per surface, `advancedEditor({ compositeKinds? })` from `@ecsplico/editor/vue/advanced` or `@ecsplico/editor/react/advanced` (every feature and the three integrations with that surface's bindings, in `ADVANCED_FEATURE_IDS` order). `@ecsplico/editor/presets/advanced` is the framework-free assembly behind both (`ADVANCED_FEATURE_IDS`, `advancedEditorCore(bound, options)`, `AdvancedFeatures<C>`, `AdvancedEditorOptions`): a UI layer binds only the UI-bound features (media, transcript, composites, authors, comments, AI, collab, block UI, themes), the framework-free ones (core, mentions, composite-media, composite-AI, transcript-AI) are added there once; it contains no component and is not a preset to mount. `SimpleEditor` (`/vue/simple`, `/react/simple`) and `AdvancedEditor` (`/vue/advanced`, `/react/advanced`) are the matching components.
+- Both surfaces take the same features: a React preset is `defineEditor({ features: [coreFeature(), mediaFeature(), commentsFeature(), …] })` with the factories from `./<x>/react`, a Vue one with those from `./<x>/vue`. Mixing is a type error (`VueFeature` is `EditorFeature<Component>`, `ReactFeature` is `EditorFeature<ComponentType<{ editor: Editor }>>`); only `EditorFeature<never>` features (`coreFeature()`, `mentionsFeature()` and the integrations) fit either ([usage guide](./usage.md#simple-editor-in-react)).
+- The preset, and with it the schema, collaboration mode and slash commands, is read once when the surface mounts. Change it by remounting with a new `key`. A simple editor cannot safely edit advanced JSON: unknown nodes are rejected through `contentError` ([usage guide](./usage.md#rejected-content-contenterror)).
+- Components that belong *beside* an editor are separate exports and take the editor (or the preset) as a prop. Vue: `EditorToolbar`, `EditorSettingsPanel`, `EditorSettingsModal` (`/vue`), `EditorOutline` (`/outline/vue`), `CompositeTable`, `CompositeInspector` (`/composites/vue`), `AiSidebar` (`/ai/vue`), `CommentsMargin` (`/comments/vue`), `DocumentTree` (`/tree/vue`).
+- The React equivalents have the same names and props style: `EditorToolbar`, `EditorSettingsPanel`, `EditorSettingsModal` from `@ecsplico/editor/react`; `EditorOutline` from `/outline/react`; `CompositeTable`, `CompositeInspector` from `/composites/react`; `AiSidebar` from `/ai/react`; `CommentsMargin` from `/comments/react`; `DocumentTree` from `/tree/react`. The host mounts sonner's `Toaster` once.
+- A feature can run per-app side effects from every surface's setup without touching the surface markup: its `setup: (ctx) => void | (() => void)` contribution is called by `EditorSurface` for each mounted surface and its returned teardown when the surface unmounts (`themesFeature()` starts its theme runtime this way; the runtime dedupes per app and puts `obsidian-theme theme-dark|theme-light` on `<html>` so the whole app follows the theme; see [Per-feature entries](#per-feature-entries-framework-free-vue-react) for its lifetime on each surface).
+
+### Browser entries versus schema and server entries
+
+| Kind | Entries | May import |
+|---|---|---|
+| Browser, with Vue and Nuxt UI | `/vue`, `/vue/simple`, `/vue/advanced`, `/<feature>/vue` (`/media`, `/transcript`, `/authors`, `/comments`, `/composites`, `/ai`, `/collab`, `/block-ui`, `/themes`, `/outline`, `/tree`) | everything above them in the rules of [§13](#13-dependency-rules-and-bundle-proof); never React |
+| Browser, with React and shadcn/ui | `/react`, `/react/simple`, `/react/advanced`, `/<feature>/react` (the same features) | the same rules; never Vue, `@tiptap/vue-3` or Nuxt UI |
+| Browser, framework-free | `/core` (`defineEditor`, `createEditorContext`, the settings store, `createStore`, the notice seam, the suggestion renderer seam, descriptors such as `EditorFeature<C>` and `MenuItem`), `/<feature>` (`<x>FeatureCore(ui)`, the models), `/mentions`, `/integrations/*`, `/presets/*` | Tiptap/ProseMirror, `/core` and `/settings` only (plus Yjs/AI SDK where the feature needs them); no `vue`, `@tiptap/vue-3`, `@nuxt/ui`, `react` or `sonner` module |
+| Server-safe schema and protocol, usable in Node | `/core/schema`, `/schema/simple`, `/schema/advanced`, `/media/schema`, `/mentions/schema`, `/transcript/schema`, `/authors/schema`, `/comments/schema`, `/composites/schema`, `/themes/schema`, `/tree/types`, `/settings`, `/ai/protocol`, `/integrations/transcript-ai/protocol` | no UI framework, no DOM globals or feature factories |
+| Server | `/server`, `/nuxt` | Nitro/Nuxt build code; never imported by browser code |
+
+Servers and validators build their ProseMirror schema from the framework-free schema entries (`getSchema(advancedSchemaExtensions())`), never from a browser entry.
+
+## 2. Register the Nuxt module
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  // @nuxt/ui first: the editor module patches its generated `ui.css` template.
+  modules: ['@nuxt/ui', '@ecsplico/editor/nuxt'],
+  tiptapEditor: { ai: { /* see §5 */ } },
+})
+```
+
+Add `"@ecsplico/editor"` to the host's dependencies (`workspace:*` in this repository, the registry version elsewhere). The package ships built ESM (`dist`); the module puts it into `build.transpile` for the client and Nitro's `externals.inline` for the server so the runtime files in `dist/nuxt/runtime` (they import `h3` and `nitropack/runtime` for the server and `#app` for the client explicitly) are compiled by the host. `h3` and `nitropack` are optional peers: a Nuxt app already provides them; only a strictly isolated install (pnpm without hoisting) may need them listed next to the package.
+
+The module registers exactly one client plugin (`editor-context-nuxt-ui.client.ts`, which hands `nuxtUiKit()` to the context; the module has no `kit` option): it installs the editor context with account-synced settings and the public AI configuration. It auto-registers no component or composable: import everything from the package entries.
+
+Without a registered adapter every route throws „tiptap-editor: setEditorAdapter() wurde in keinem Nitro-Plugin aufgerufen“.
+
+## 3. `EditorAdapter`: auth and storage
+
+**Who owns what.** The package owns the routes, the Hocuspocus server, rate limiting and the wire formats; the host owns *identity* (sessions, sign-in, which user may open which document) and *storage* (where documents, Yjs state, assets, settings and themes live). Both enter through the one adapter below. The package never reads cookies or touches files itself; `authenticate` returns the user (or `null`), the storage methods persist what they are given. In this repository `server/plugins/editor-adapter.ts` wires the adapter to `nuxt-auth-utils` sessions and the file system under `.data/`. The app has no login: `server/middleware/demo-session.ts` signs every `/api/` request whose session is not one of the demo users `anna`, `ben` or `bernd` (`shared/utils/demo-users.ts`) in as `anna`, and `POST /api/auth/switch` (`server/api/auth/switch.post.ts`) switches the session to another demo user. Both are host code; the package only sees what `authenticate` returns.
+
+The single seam between the package and the host. Register it in a Nitro plugin:
+
+```ts
+// server/plugins/editor-adapter.ts
+import { setEditorAdapter } from '@ecsplico/editor/server'
+
+export default defineNitroPlugin(() => {
+  setEditorAdapter({
+    // Without a session cookie h3 throws outside a main handler: map that to `null`.
+    authenticate: request => getUserSession({ headers: request.headers, context: {} }).then(s => s.user ?? null, () => null),
+    loadContent: async id => (await getDocument(id))?.content ?? null,
+    async storeContent(id, content) {
+      const existing = await getDocument(id)
+      if (!existing) return // deleted while a store was pending
+      await putDocument({ ...existing, content, updatedAt: new Date().toISOString() })
+    },
+    listUsers: async () => (await listUsers()).map(toSessionUser),
+    listContents: async () => (await listAllDocuments()).map(({ id, content }) => ({ id, content })),
+    loadState, storeState, removeState, storeAsset, loadAsset,
+    loadSettings: user => getUserSettings((user as User).id),
+    storeSettings: (user, settings) => putUserSettings((user as User).id, settings),
+    listThemes,
+    loadTheme,
+    storeTheme,
+    removeTheme,
+  })
+})
+```
+
+| Method | Signature | Called | Must return |
+|---|---|---|---|
+| `authenticate` | `(request: { headers: Headers, token?: string }) => Promise<object \| null>` | Collab websocket (Hocuspocus `onAuthenticate`; `token` is the client's `collaboration.token`, absent for HTTP routes and token-less clients); first in every API route that needs a user | The user, or `null` (→ 401). The value becomes the Hocuspocus connection context's `user`, the `user` argument of the settings methods and the rate-limit key (`id`, else `username`, else its JSON). |
+| `loadContent` | `(id) => Promise<JSONContent \| null>` | `onLoadDocument`, when no usable Yjs state exists (new, legacy or restored document) | TipTap JSON to seed the Y.Doc from; `null` = the document does not exist (connection closed) |
+| `storeContent` | `(id, content) => Promise<void>` | `onStoreDocument` (debounced after edits, and on shutdown via the Nitro `close` hook) | Mirrors the JSON; tolerate ids deleted meanwhile |
+| `listUsers` | `() => Promise<MentionUser[]>` (`{ id, username, color }`) | `GET /api/editor/users`, `POST /api/ai/generate` for tasks that need users | Every user that can be `@`-mentioned, no credentials |
+| `listContents` | `() => Promise<{ id, content }[]>` | `GET /api/editor/tags` | Stored JSON of every document |
+| `loadState` | `(id) => Promise<Uint8Array \| null>` | `onLoadDocument` | The bytes `storeState` received, unchanged (the Yjs update behind a content-version prefix; state from earlier releases is a raw update and loads as version `null`); `null` = none yet |
+| `storeState` | `(id, state) => Promise<void>` | `onStoreDocument`, and right after a Y.Doc was seeded or block IDs were backfilled | Persist; tolerate deleted ids |
+| `removeState` | `(id) => Promise<void>` | `forgetCollabDocument`, and `onLoadDocument` when the stored state is stale (`contentVersion`) | Drop the state of a deleted or rewritten document |
+| `authorize?` | `(user, id) => Promise<{ readOnly: boolean } \| null>` | Hocuspocus `onConnect`, with the object `authenticate` returned | `null` rejects the connection (permission denied); `{ readOnly: true }` lets it sync but applies none of its edits. Omit: every authenticated user may edit every document |
+| `contentVersion?` | `(id) => Promise<string \| null>` | `onLoadDocument`; right after every `storeContent`; before every store of an open document | Opaque version of the stored content (mtime, hash, revision; no NUL character), `null` = unknown. A stored state with another version is discarded and the document is re-seeded from `loadContent`; an open document whose version moved is merged with `loadContent` on its next store instead of being written back. Omit: state is never discarded |
+| `schemaExtensions?` | `() => AnyExtension[]` | First collab access (once per adapter) | Vue-free TipTap node/mark extensions of the host, appended to `advancedSchemaExtensions()` in the collab schema |
+| `storeAsset` | `(id, asset: AssetRecord & { data: Buffer }) => Promise<void>` | `POST /api/editor/assets/:id` | Persist the file under `asset.name` with its record. `id` is a document id or `scratch`; it need not name an existing document. |
+| `loadAsset` | `(id, name) => Promise<{ record, data } \| null>` | `GET /api/editor/assets/:id/:name` | The stored file; `null` → 404 |
+| `loadSettings?` | `(user) => Promise<unknown \| null>` | `GET /api/editor/settings` | Stored settings (normalized by the route), `null` = none yet |
+| `storeSettings?` | `(user, settings) => Promise<void>` | `PUT /api/editor/settings` | Persist the validated settings |
+| `listThemes?` | `() => Promise<ThemeRecord[]>` | `GET /api/editor/themes` | The shared theme library (`{ id, name, version?, author?, authorUrl?, builtin }`), host-seeded themes marked `builtin: true` |
+| `loadTheme?` | `(id) => Promise<{ record, css } \| null>` | `GET /api/editor/themes/:id` | The theme's `theme.css` text with its record; `null` → 404 |
+| `storeTheme?` | `(record: Omit<ThemeRecord, 'builtin'>, css) => Promise<void>` | `POST /api/editor/themes` | Persist an uploaded theme. The route has already validated the content and chosen a unique `record.id`. |
+| `removeTheme?` | `(id) => Promise<boolean>` | `DELETE /api/editor/themes/:id` | Delete an upload; `false` = unknown id or builtin (the route has checked `listThemes()` first and answers 403 / 404 itself) |
+
+| `languageModel?` | `(ref: ModelRef, user) => Promise<LanguageModel \| null>` | Every AI endpoint (`/api/ai/{generate,chat,complete,transcript-cleanup}`), before the runtime-config presets | The AI SDK language model for `ref` (`{ preset }` or a user profile's endpoint/model/key), so the host's own providers serve the editor. `user` is what `authenticate` returned. `null` falls through to the presets (400 for an unknown preset) |
+| `listModels?` | `(user) => Promise<ModelProfile[] \| null>` | `GET /api/ai/models` | The models offered to `user`, replacing the preset list (list them with `source: 'preset'` and the `id` that `languageModel` receives as `{ preset: id }`). `null` lists the runtime-config presets |
+
+Omit both settings methods to keep settings in the browser only (`GET` answers 204, `PUT` 501; the client falls back to `localStorage`).
+
+The theme methods are optional too: an adapter without them answers the theme routes with 501 and the `themes` feature falls back to the standard look (a console warning, the stored setting stays). `storeTheme` and `removeTheme` are only needed for uploads; without them the upload and delete routes answer 501 while builtins stay selectable. `ThemeRecord` and the `THEME_ID` pattern come from the Vue-free `@ecsplico/editor/themes/schema`. The demo host keeps builtins in `server/themes/<id>/{manifest.json,theme.css}` (git-tracked, read-only) and uploads in the Nitro storage mount `themes` (`.data/themes/<id>/{manifest.json,theme.css}`, configured in `nuxt.config.ts`), so uploads survive restarts; `listThemes` returns builtins and then uploads, `loadTheme` checks builtins first, `removeTheme` refuses builtins.
+
+### Deleting a document
+
+Call `forgetCollabDocument(id)` before removing the JSON (`server/api/documents/[id].delete.ts`): it tells connected clients the document is gone (stateless message `deleted`), closes their connections, drops the Yjs state through `removeState` and blocks a pending store from writing it back. `liveContent(id)` returns the current content of a document that is open in Hocuspocus (unsaved edits included), `null` when nobody has it open.
+
+### Content rewritten behind the editor's back
+
+When something other than the editor writes a document's content (an agent rewrites the file), call `collabContentChanged(id)` (or `collab.contentChanged(id)` on your own `createCollabServer`) after the write. If the document is open, the server merges the new content into it right away as a diff-update: connected clients see an ordinary edit, unchanged blocks keep their Yjs items, nobody reconnects. It is a no-op when nobody has the document open or the version did not move. It needs `contentVersion`: without it a rewrite cannot be told from the server's own writes. Without the call an open document picks the rewrite up only on its next store (the next edit or the last client leaving).
+
+### What the collab server does on load
+
+1. A stored Yjs state without `section*` node names is used; blocks without an ID get one assigned **on the server**, before any client syncs, and the state is persisted at once (so a backfill after a restart cannot assign other IDs than clients already hold).
+2. Otherwise (no state, a legacy state containing the old `section` node, or a restored document) the Y.Doc is seeded from `loadContent`, migrated by `migrateLegacyContent` (`section*` → `composite*`) and given block IDs, then persisted immediately.
+
+## 4. Server routes and authentication
+
+Every route authenticates through `adapter.authenticate`; the package guards its own routes and expects no host middleware (the demo's session middleware only makes sure a session exists; it is not what protects the routes). A `null` user answers 401 „Nicht angemeldet“ on API routes. The websocket upgrade of `/collab/:id` succeeds first by default, and a socket whose user is `null` is closed with code 4401 right after; with the module option `collab.authenticateUpgrade` the upgrade itself is refused with HTTP 401 (see [Auth notes](#auth-notes)).
+
+| Method | Path | Purpose |
+|---|---|---|
+| WS | `/collab/:id` | Hocuspocus sync; the document name comes from the provider's `name`. Yjs state is the source of truth; JSON is mirrored via `storeContent`. |
+| GET | `/api/ai/models` | Presets without keys + default slots (not rate limited) |
+| POST | `/api/ai/complete` | Ghost text: `{ before, model }` → `{ text }` |
+| POST | `/api/ai/generate` | Task run → SSE `delta` / `done` / `error` |
+| POST | `/api/ai/chat` | Document chat/agent → SSE `delta`, `ops`, `done`, `error` |
+| POST | `/api/ai/transcript-cleanup` | `{ segments, model }` → `{ cleaned, failed }` |
+| POST | `/api/ai/transcribe` | `{ documentId, name }` → `{ text }`; 501 without `ai.transcription` |
+| GET | `/api/editor/users?q=` | `@` popup: up to 20 users |
+| GET | `/api/editor/tags?q=` | `#` popup: up to 20 tags in use |
+| GET / PUT | `/api/editor/settings` | Per-user settings (table below) |
+| POST | `/api/editor/assets/:id` | Multipart `file` → `{ url, name }`; 413 above `MAX_MEDIA_BYTES` |
+| GET | `/api/editor/assets/:id/:name` | Serves an asset with its stored `Content-Type`, single byte-range support; 404 when unknown |
+| GET | `/api/editor/themes` | The theme library as `ThemeRecord[]`; 501 when the adapter has no `listThemes` |
+| GET | `/api/editor/themes/:id` | The theme's stylesheet as `text/css`; 400 for a malformed id, 404 when unknown, 501 when the adapter has no `loadTheme` |
+| POST | `/api/editor/themes` | Multipart `css` (file, required), `manifest` (file, optional Obsidian `manifest.json`), `name` (string, optional) → `201` with the new `ThemeRecord` (`builtin: false`). The name is `manifest.name`, else `name`, else the CSS file's base name; the id is its slug (`a-z0-9` and `-`, at most 64 characters), made unique with `-2`, `-3` … against the library. Limits: CSS up to `MAX_THEME_BYTES` (2 MB, `413` „Theme ist größer als 2 MB“), manifest up to 64 KB and parseable by `themeManifestSchema` (`400` „Ungültiges manifest.json“); `400` for a missing or empty `css`, for content that is not UTF-8 text (invalid UTF-8, NUL bytes) and for markup (`<script` or `<?xml` in the first 512 bytes); `501` when the adapter lacks `listThemes` or `storeTheme` |
+| DELETE | `/api/editor/themes/:id` | Deletes an uploaded theme (`204`); `400` for a malformed id, `404` when unknown, `403` „Mitgelieferte Themes können nicht gelöscht werden“ for a builtin, `501` when the adapter lacks `listThemes` or `removeTheme` |
+
+The AI routes are rate limited per user (sliding window, in memory, per process): exceeding it answers 429 „Zu viele KI-Anfragen, bitte kurz warten“ with `Retry-After`.
+
+`/api/editor/settings`:
+
+| Request | Status |
+|---|---|
+| `GET`/`PUT` without a user | 401 |
+| `GET`, adapter has no `loadSettings` | 204 (client stays on `localStorage`) |
+| `GET`, nothing stored | 200 with body `null` (client uploads its local settings) |
+| `GET`, stored | 200, `EditorSettings` normalized by `parseEditorSettings` |
+| `PUT`, adapter has no `storeSettings` | 501 |
+| `PUT`, body is no complete valid `EditorSettings` | 400 |
+| `PUT`, ok | 204 |
+
+### Auth notes
+
+- **Websocket authentication (default).** The upgrade to `/collab/:id` always succeeds (HTTP 101). Hocuspocus then authenticates the connection from the upgrade request's headers, so the session cookie authenticates the socket like any same-origin request, and from the client's `token`: clients that cannot send cookies pass `token` to the `collaboration` prop (a string or an async function; it becomes the `HocuspocusProvider` `token`) and `authenticate` receives it as `request.token` next to the headers. A client without a user gets a permission-denied answer and its socket is closed with code 4401 (not an HTTP 401).
+- **Rejecting at the upgrade (`collab.authenticateUpgrade: true`).** The route calls `authenticate({ headers })` (no `token`) before the upgrade; a `null` user answers HTTP 401 and no websocket is opened, otherwise the user is passed to the connection and not authenticated a second time. Use it when every client authenticates by cookie or other request headers; a client that identifies itself only by `collaboration.token` cannot connect then, because the token is only sent after the socket is open. `authorize` still runs per document in both modes.
+- Document-level authorization (who may open which document) is the host's decision: `authenticate` returns the user, and `authorize(user, id)` decides per document on connect (`null` rejects, `{ readOnly: true }` makes the connection read-only). Without `authorize` the websocket route passes any authenticated user to Hocuspocus for any document name.
+- Asset URLs are guarded too; media elements send the session cookie.
+
+## 5. AI configuration and secrets
+
+Config key `tiptapEditor`:
+
+| Option | Type | Default |
+|---|---|---|
+| `locale` | `'de' \| 'en'`: language of every string the editor renders; passed to the client context plugin (`createEditor({ locale })`) | `'de'` |
+| `messages` | `Partial<Record<MessageKey, string>>`: overrides of single messages by key (JSON-serialisable) | none |
+| `ai.presets` | `Record<string, { label, endpoint, model, apiKey? }>`: server model presets keyed by preset id (camelCase). `endpoint` is any OpenAI-compatible chat-completions base URL. | `sonnet`, `flashLite` (OpenRouter) |
+| `ai.slots` | `Record<'complete' \| 'rewrite' \| 'generate', string>`: default preset per slot. The `complete` model must support assistant prefill. | `{ complete: 'flashLite', rewrite: 'sonnet', generate: 'sonnet' }` |
+| `ai.rateLimit` | `{ max, windowMs }` per user, shared by all AI endpoints | `{ max: 30, windowMs: 60000 }` |
+| `ai.transcription` | `{ endpoint, model, apiKey? }`: OpenAI-compatible `POST <endpoint>/audio/transcriptions` | absent: action hidden, endpoint answers 501 |
+| `collab.authenticateUpgrade` | `boolean`: authenticate the `/collab/:id` upgrade and refuse it with HTTP 401 (see [Auth notes](#auth-notes)); env `NUXT_TIPTAP_EDITOR_COLLAB_AUTHENTICATE_UPGRADE` | `false`: upgrade first, close with 4401 |
+
+**Keys come from the environment only.** Never put a key into `nuxt.config.ts` (it ends up in the build output).
+
+| Variable | Sets |
+|---|---|
+| `NUXT_TIPTAP_EDITOR_AI_API_KEY` | `ai.apiKey`: shared fallback for every preset without its own key |
+| `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY` | `ai.presets.<id>.apiKey`; `<ID>` is the preset id in upper snake case (`flashLite` → `NUXT_TIPTAP_EDITOR_AI_PRESETS_FLASH_LITE_API_KEY`) |
+| `NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY` | `ai.transcription.apiKey` (only effective when `ai.transcription` is set) |
+
+**Host models through the adapter.** An adapter with `languageModel(ref, user)` is asked first for every model reference; a returned model is used as is (no preset, no key needed), `null` falls through to the presets above. `listModels(user)` decides what `GET /api/ai/models` offers (return `null` to list the presets). Host-driven agent chats are the counterpart on the client: `createAgentOpReview({ notify, t })` from `@ecsplico/editor/ai` shows agent edit operations from any transport as in-document hunks (`propose`), follows the user's decisions (`state`, `decide`, `reveal`) and reads them back for the agent (`feedback()` yields each decision once); `createAiSidebarFlow({ send, assistant, notify, editor })` takes the host's `send(question, scope)` instead of a `chat`.
+
+A preset resolves its key as `preset.apiKey || ai.apiKey`. A missing key answers 500 naming both variables before any stream starts; an unknown preset id answers 400; upstream failures answer 502.
+
+Where the secrets live: `runtimeConfig.tiptapEditor.ai` is server-only. The browser only ever receives `public.tiptapEditor.ai = { slots, transcription: boolean }` and, through `GET /api/ai/models`, preset profiles **without** keys. A user-defined profile (kept in the browser's `localStorage`, key `tiptap-editor:model-profiles`) sends its own key with each request; the server forwards it and never stores it.
+
+## 6. Collaboration on the client
+
+Collaboration is a feature, not a mode: the preset contains `collabFeature()`, and the surface is mounted with a session.
+
+```vue
+<script setup lang="ts">
+import { HocuspocusProvider } from '@hocuspocus/provider'
+import { collabFeature } from '@ecsplico/editor/collab/vue'
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { EditorSurface } from '@ecsplico/editor/vue'
+import * as Y from 'yjs'
+
+const preset = defineEditor({ features: [coreFeature(), collabFeature()] })
+const ydoc = new Y.Doc()
+const provider = new HocuspocusProvider({
+  url: `${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/collab/${id}`,
+  name: id,
+  document: ydoc,
+})
+onBeforeUnmount(() => provider.destroy())
+</script>
+
+<template>
+  <EditorSurface :preset="preset" :collaboration="{ ydoc, provider, user: { id: 'u1', name: 'Ada', color: '#3b82f6' } }" />
+</template>
+```
+
+React is the same with `@ecsplico/editor/collab/react` and the React `EditorSurface`; the Y.Doc and provider are created once per document id and destroyed in an effect cleanup:
+
+```tsx
+import { HocuspocusProvider } from '@hocuspocus/provider'
+import { collabFeature } from '@ecsplico/editor/collab/react'
+import { coreFeature, defineEditor } from '@ecsplico/editor/core'
+import { EditorSurface } from '@ecsplico/editor/react'
+import { useEffect, useMemo, useState } from 'react'
+import * as Y from 'yjs'
+
+const preset = defineEditor({ features: [coreFeature(), collabFeature()] })
+
+function CollaborativeEditor({ id }: { id: string }) {
+  const [session, setSession] = useState<{ ydoc: Y.Doc, provider: HocuspocusProvider } | null>(null)
+  useEffect(() => {
+    const ydoc = new Y.Doc()
+    const provider = new HocuspocusProvider({ url: `${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/collab/${id}`, name: id, document: ydoc })
+    setSession({ ydoc, provider })
+    return () => { provider.destroy(); setSession(null) }
+  }, [id])
+  const collaboration = useMemo(() => session && { ...session, user: { id: 'u1', name: 'Ada', color: '#3b82f6' } }, [session])
+  return collaboration ? <EditorSurface key={id} preset={preset} collaboration={collaboration} /> : null
+}
+```
+
+- The Y.Doc is the document: there is no `v-model`. Core turns its own undo history off; the Collaboration extension brings a **per-client** undo/redo (`Mod-z`, `Mod-y`, `Shift-Mod-z`), so undo never reverts another user's edits.
+- `provider` adds remote carets (`CollaborationCaret`, labelled with `user`); without it the Y.Doc is edited locally only. `user` is an `AuthorIdentity` (`{ id, name, color }`, the app's stable user id): the optional `authors` and `comments` features attribute text and comments to it, see [Authors and comments](#authors-and-comments).
+- Without a `collaboration` prop `collabFeature()` contributes no extension: the editor behaves like a standalone one with JSON `v-model`.
+- Supplying `collaboration` to a preset **without** `collabFeature()` is a setup error: the surface throws „`collaboration` needs a preset with the collaboration feature“.
+- The mode is fixed at mount. Remount (change `key`) when the document changes, so Y.Doc, provider and editor never bleed between documents.
+- Include `@ecsplico/editor/styles/collab.css` (the Nuxt module adds it) for the caret styles.
+
+### Authors and comments
+
+Two optional features build on the session's `user`; the advanced editor contains both.
+
+- `authorsFeature()` marks every text run the user inserts with an `author` mark (`{ id, name, color }`; one author per run, remote changes and Yjs undo/redo keep the original author's mark). Without `collaboration.user` it attributes nothing, so standalone editors write unmarked text. Colouring is a per-user preference (`editing.authorColors`, `editing.authorColorStyle`).
+- `commentsFeature()` (requires `collab`) stores comment threads in the Y.Doc, in a `Y.Map` named `comments`; the commented range is a `comment` mark. Threads therefore sync live and persist with the document, but they are **not** part of the JSON/Markdown adapter content. Without a Y.Doc and a `collaboration.user` the UI says „Kommentare gibt es nur in gemeinsam bearbeiteten Dokumenten.“ and nothing can be written.
+- Both marks are in `advancedSchemaExtensions()`, so the server's Yjs↔JSON conversion keeps them. They have no Markdown form: Markdown export, imports and the AI context ignore them (`DocumentMarkdown`).
+- Surface contract: `v-model:comments-open` (Vue `EditorSurface`/`AdvancedEditor`) or `commentsOpen`/`onCommentsOpenChange` (React) is the open state of the margin column, which the host renders with `CommentsMargin` inside the editor's scroll container; `useEditorUi().toggleComments()` and `Mod-Shift-m` toggle it, and it excludes the AI sidebar.
+
+### Positions that survive concurrent edits
+
+`collabFeature()` supplies `DocAnchors` with `yjsAnchorResolver`: ranges captured through `captureRange` (AI reviews, ghost text, chat ops, the selection menu) are stored as Yjs relative positions and re-resolved after every remote change and undo/redo. Without the collab feature anchors map through local transactions only.
+
+The resolver binds to the Yjs types of the editor's own Y.Doc. The package pins one `yjs` instance as a peer dependency: install a single copy in the host, or Yjs warns „already imported“ and `instanceof` checks fail.
+
+### Matching schemas: who owns the document
+
+The Yjs document is only valid if every participant uses the same schema.
+
+- The **server** builds `collabSchema()` from `advancedSchemaExtensions()` plus the adapter's `schemaExtensions()` (the package's collab route) and migrates and validates seeded content with it.
+- The **client** must mount a preset with the same schema: `advancedEditor()`/`AdvancedEditor`, or your own preset whose features contribute the same nodes and marks (media, transcript, composites, mentions, authors and comments marks, block IDs). Custom `compositeKinds` are storage, not schema, so they may differ per client.
+- The host owns the *document lifecycle*: create the `Y.Doc` and the `HocuspocusProvider` when the page mounts, destroy the provider on unmount (`onBeforeUnmount(() => provider.destroy())`), and call `forgetCollabDocument(id)` on the server before deleting a document (see [§3](#deleting-a-document)). The library never creates a provider for you.
+- A plain-Vue or React app brings its own Hocuspocus server, builds its schema from `/schema/advanced` and sets the Collaboration `field` to `default`. A host block of your own (see the [extending guide](./extending.md#collaboration-and-the-server-schema)) belongs to that schema too: return its framework-free node from the adapter's `schemaExtensions()` (`schemaExtensions: () => [YourNode]`), which the package's collab route appends to `advancedSchemaExtensions()`; a custom server builds `getSchema([...advancedSchemaExtensions(), YourNode])` itself.
+
+## 7. Block UI (drag handle, hover actions)
+
+```ts
+import { blockUiFeature } from '@ecsplico/editor/block-ui/vue' // or '@ecsplico/editor/block-ui/react'
+const preset = defineEditor({ features: [coreFeature(), blockUiFeature()] })
+```
+
+`blockUiFeature()` adds the drag handle on the hovered block's left, hover targeting, the `BlockActionsOverlay` (the features' and the host's block actions) on the block's top line at the editor's right edge, and block-range selection (`Mod`+drag, `Shift`+`↑`/`↓`). It is opt-in: the simple editor never includes it. The drag handle's upstream package imports `@tiptap/extension-collaboration` and `y-tiptap`, so a preset with block UI bundles that support code even without a live session.
+
+Which blocks have which handle follows the settings and the block:
+
+- **Blocks with a kind icon** (composites, see [Composites](./usage.md#chips-and-details-popover)) have no standard handle: their icon is the handle. Dragging it selects the composite and moves it like the standard handle does; a click without movement opens the details popover.
+- **`blocks.dragHandle: 'hover'`** (default): one handle follows the hovered block.
+- **`blocks.dragHandle: 'always'`**: the hover handle is replaced by one permanent handle per eligible block, each at the position the hover handle would take for that block (right edge on the block's left edge, centred on its first text line; list items left of their bullet). Eligible are the blocks the hover handle can target at any depth: paragraphs, headings, lists' items, quotes, code blocks, media, tables and the blocks inside quotes, list items and table cells. Not eligible: composite chrome (title, description, tags), table rows and cells themselves, list wrappers, the first block of a list item (the item has the handle), and blocks with a kind icon. A nested block whose handle would cover its container's handle on the same line (the first block of a quote) has none; the container's handle moves it. Only blocks within one screen of the viewport render a handle. Both modes are hidden while the editor is read-only.
+
+`startBlockDrag(editor, event, pos)` (`@ecsplico/editor/core`) starts such a drag from any element outside the editor's DOM: call it from the element's `dragstart`.
+
+## 8. Vue-free advanced schema for servers
+
+```ts
+import { getSchema } from '@tiptap/core'
+import { advancedSchemaExtensions } from '@ecsplico/editor/schema/advanced'
+
+const schema = getSchema(advancedSchemaExtensions())
+schema.nodeFromJSON(stored).check() // validate stored documents, run migrations, convert Yjs ↔ ProseMirror
+```
+
+`advancedSchemaExtensions()` is the node/mark set of the advanced editor in the exact order the browser editor uses: StarterKit (history off), `StrikeX`, media, transcript segment, composite family, mention/tag, the `author` and `comment` marks, `BlockId` and the node flags. It imports no Vue, React, Nuxt UI or browser globals and runs under plain Node; `bun run check:editor-entries` bundles it for Node and executes it, and compares the node/mark names, attributes and content expressions against a snapshot. Use `@ecsplico/editor/schema/simple` for servers that only handle simple documents.
+
+The package's collab server builds `collabSchema()` from this entry plus the adapter's `schemaExtensions()` (`src/server/collab.ts`, `createCollabServer`); a custom Hocuspocus server (e.g. for a plain-Vue or React app) does the same and sets the Collaboration `field` to `default`.
+
+## 9. Production
+
+```sh
+bun run build                       # nuxt build
+PORT=3200 node .output/server/index.mjs
+```
+
+- The module compiles the package source into the Nitro bundle (`externals.inline`) and enables `experimental.websocket` for the `/collab/:id` route. Verified with `node .output/server/index.mjs`: unauthenticated `GET /api/editor/settings` → 401, authenticated → 200; an unauthenticated websocket upgrade to `/collab/:id` gets 101 and is closed with 4401 (with `collab.authenticateUpgrade: true`: HTTP 401 at the upgrade), an authenticated provider syncs the document in both modes.
+- Secrets and the session password are runtime environment variables of the server process (`NUXT_SESSION_PASSWORD` for `nuxt-auth-utils`, the `NUXT_TIPTAP_EDITOR_AI_*` keys above), not build-time values.
+- Persistent data (documents, Yjs state, assets, settings) lives wherever the host's adapter puts it; Nitro storage mounts used by the adapter must be configured for production (`nitro.storage` with a real driver on read-only deployments).
+- The shutdown plugin (`plugins/collab.ts`) flushes pending debounced Yjs stores from Nitro's `close` hook.
+
+## 10. The file browser and `DocumentStore`
+
+`DocumentTree` (`@ecsplico/editor/tree/vue` or `@ecsplico/editor/tree/react`) is the file drawer: a „Dokumente“ root with folders and documents, create/rename/move/delete, drag and drop, kind filters per item, and the open document's outline (headings of a simple document, or the composites tree in the preferred structure) listed under it. It knows nothing about routing, HTTP or toasts of the host: the host passes a `DocumentStore`. The store contract, the types and the view-state model live in the framework-free `@ecsplico/editor/tree`; the two components are thin renderings of the same model. The tree's own messages (delete with undo) are notices: Vue needs `<UApp>`, React needs `EditorContextProvider` and a mounted `Toaster`.
+
+```vue
+<script setup lang="ts">
+import { DocumentTree } from '@ecsplico/editor/tree/vue'
+
+const selectedFolder = defineModel<string>('selectedFolder', { default: '' })
+const store = useDocumentStore()   // host: see app/composables/useDocumentStore.ts
+const editor = useActiveEditor()   // host: the open page's editor, or undefined
+</script>
+
+<template>
+  <DocumentTree v-model:selected-folder="selectedFolder" :store="store" :editor="editor">
+    <template #document-actions="{ id, title }"><!-- host buttons next to a document's delete button --></template>
+  </DocumentTree>
+</template>
+```
+
+Vue props: `store` (required) and `editor` (`Editor | undefined`, required). `v-model:selectedFolder` is the folder (path, `''` = root) that new documents, new folders and host import actions go to; the tree resets it to `''` when that folder is deleted or moved away. The slot `document-actions` receives `{ id, title }`. The runnable adapter is [`app/components/AppDocumentTree.vue`](../../../app/components/AppDocumentTree.vue); the layout holds `selectedFolder` and binds it with `v-model:selected-folder`.
+
+React, same behaviour, props instead of model and slot:
+
+```tsx
+import { DocumentTree } from '@ecsplico/editor/tree/react'
+
+const [selectedFolder, setSelectedFolder] = useState('')
+
+<DocumentTree
+  store={store}
+  editor={editor}
+  selectedFolder={selectedFolder}
+  onSelectedFolderChange={setSelectedFolder}
+  documentActions={doc => <button type="button">{/* host buttons next to a document's delete button, for doc.id / doc.title */}</button>}
+/>
+```
+
+`store` and `editor` are required (`editor` may be `undefined`); `selectedFolder`/`onSelectedFolderChange` are optional (the tree keeps the folder itself when `selectedFolder` is omitted); `documentActions` is a render function receiving `{ id, title }`; `className` styles the root. The runnable adapter of a `DocumentStore` over the host's `/api` is `examples/react-advanced/src/App.tsx`.
+
+### `DocumentStore`
+
+```ts
+interface DocumentStore {
+  tree: ReadonlyStore<TreeFolder | null | undefined>               // undefined = loading, null = loading failed
+  documents: ReadonlyStore<readonly DocumentSummary[] | undefined> // undefined = loading
+  activeId: ReadonlyStore<string | undefined>
+  open(id: string): Promise<void>
+  create(title?: string, folder?: string): Promise<{ id: string }>
+  move(id: string, folder: string): Promise<void>
+  remove(id: string, folder: string): Promise<{ title: string, restore: () => Promise<{ id: string }> }>
+  createFolder(path: string): Promise<void>
+  moveFolder(path: string, to: string): Promise<void>   // `to` is the complete new path: moves and renames
+  removeFolder(path: string): Promise<void>
+  validateName(name: string, siblings: readonly string[]): string | null
+}
+```
+
+The observable values are `ReadonlyStore`s (`createStore` from `@ecsplico/editor/core`), so the same store drives both components. A Vue host that keeps refs adapts them with `storeFromRef(ref)` and `useStoreRef(storeOrGetter)` from `@ecsplico/editor/vue`; a React host holds its data in its own state or data layer and publishes it with `createStore`.
+
+`TreeFolder` is `{ type: 'folder', name, path, folders, documents }` (the root is named „Dokumente“, `path` is `''`), `DocumentSummary` is `{ id, title, updatedAt, folder }`; both are exported from `/tree`. A server that builds the `/api/tree` response imports the same types from `@ecsplico/editor/tree/types` (the `/tree` entry also carries the store and the view model, which a server's typecheck should not pull in); this repository's `server/utils/documents.ts` does.
+
+Semantics every implementation must keep:
+
+- **Failure ownership.** The host reports failures (its toast, its wording) and then *rejects*. `DocumentTree` shows no second message; it only stops the flow it was running (for example it keeps the folder-name input open or does not expand a folder).
+- **Refresh.** Every mutation resolves only after both `tree` and `documents` show its result, so the tree can select and expand the new item right away.
+- **Loading.** While `tree` is `undefined` the tree shows „Lädt...“, for `null` „Dokumente konnten nicht geladen werden“; the virtual root (below) is not affected by either.
+- **`create`** returns the new document's ID. Omitted title and folder mean the host's default title and the root.
+- **`remove` with undo.** The tree shows the notification „Dokument gelöscht“ (description: the title) with a „Rückgängig“ action built from the resolved value. The implementation must (1) leave the document first when it is the open one and wait for its page to be torn down, so the collaboration provider is destroyed before the server forgets the document, (2) snapshot title and content, (3) delete, and (4) return `restore`, which creates a **new** document (new ID) with the old title in `folder` and writes the JSON content back. Assets, IDs and collaboration history are not restored; the tree opens the restored document by its new ID. If `restore` rejects, the host has already reported it.
+- **Folders.** Paths are `/`-joined segments. `removeFolder` must reject for a non-empty folder (the host's server says „Ordner ist nicht leer“); the tree itself refuses to drop a folder onto itself or a descendant and never calls `moveFolder` for it. A selected folder that no longer exists falls back to the root.
+- **`validateName(name, siblings)`** returns a German error message or `null`; `siblings` are the names already taken in the target folder. The tree shows the message inline under the input (on create and rename) and only submits valid names. The host passes its server's rules (here `fileNameError` from `shared/utils/file-name.ts`) so client and server never disagree.
+- **`open(id)`** navigates the host to the document; `activeId` follows the host's route.
+
+### Filters, virtual root, outline
+
+- Filters hide kinds below a tree item (per item key); they persist in `localStorage` under `tip-tree:node-filters`. The view state is a framework-free model: `createTreeView()` builds one (`nodeFilters`, `expanded`, `expand`, `setKindHidden`, `clearFilter`, `clearAllFilters`, `followFolderMove`), `treeView(context)` returns the one of an `EditorContext`'s app, and `useTreeView()` (`/tree/vue`: `nodeFilters` and `expanded` as refs; `/tree/react`: as plain values that re-render the component) reads it, so several trees of one app share it (see [§11](#11-settings-persistence-and-app-lifetime)).
+- The settings value `blocks.treeRoot` is `'folders'` (default: folders with their documents, the open document is an entry among them) or `'file'`. With `'file'`, an open document in composite structure (`blocks.structure === 'composite'`) is the *virtual root* of the tree: its composites are the nested items and dragging one moves the block (`moveBlockInto`). With no open document or the headings structure the tree shows the folders instead. Switching it in the settings panel re-roots the tree immediately.
+- The outline of the open document is read from `editor` (composites in composite structure, headings otherwise) and refreshed, debounced, on `update`. `DocumentTree` re-subscribes when the `editor` prop changes and removes its listener when the editor changes or the tree unmounts, so switching documents never leaves a stale listener on the previous editor.
+
+### Not in the library
+
+Storage, routing, authentication, toasts, and the host's own file formats. In this repository the `.cdoc` (package) export stays in the host: the document row's export link comes in through `document-actions` (`app/components/AppDocumentTree.vue`).
+
+## 11. Settings persistence and app lifetime
+
+- **One settings object per app.** `app.use(createEditor())` (`createEditor` from `@ecsplico/editor/vue`; the Nuxt module does it in a client plugin) provides the context; it wraps the framework-free `createEditorContext()` from `/core`, whose `settings` is a store (`get`, `set`, `update`, `subscribe`). The settings are one versioned JSON object (`EditorSettings`, version 1) that every editor, panel and tree of the app shares. A simple editor and a preset without a feature never prune the settings of features it does not install; unknown-to-this-bundle values stay in the stored JSON. `createEditor()` defaults the app's notifier to a queued Vue notifier; pass `notify` to replace it.
+- **React.** `<EditorContextProvider context={createEditorContext({ notify: reactNotifier })}>` (`EditorContextProvider`, `reactNotifier` and `Toaster` from `@ecsplico/editor/react`, `createEditorContext` from `/core`) provides the same context to a React tree. The host creates it and owns it: the provider never disposes it, call `context.dispose()` when it outlives the app. `useEditorSettings()` returns `{ settings, update, set, ready, synced }`. Without `notify` the context drops app-level notices (`silentNotifier`).
+- **Local storage.** The settings are read from `localStorage` (`tiptap-editor:settings`) at install time and written back on every change; unreadable or blocked storage falls back to the defaults for the session.
+- **Account settings (Nuxt).** The Nuxt plugin installs `createEditor({ settings: { remote: true } })`. On the first `useEditorSettings()` the client asks `GET /api/editor/settings` (only once an editor-side component needs the settings, not at install time): `200` replaces the local values (`synced`), `204` (the adapter keeps none) and `401`/network errors keep the local ones; an account without stored settings uploads this browser's. Afterwards every change is sent with a debounced `PUT` (500 ms). The status codes are listed in [§4](#4-server-routes-and-authentication). A plain-Vue or React app passes `{ settings: { remote: true } }` to `createEditor()` / `createEditorContext()` only when its server implements the same two endpoints (`examples/react-advanced` reaches the Nuxt host's through its proxy), otherwise it stays local.
+- **View state of the tree.** The tree's filters and expanded keys are the framework-free `TreeViewModel` of the app's context (`treeView(context)`); `useTreeView()` of `/tree/vue` and `/tree/react` returns them. Filters persist (`tip-tree:node-filters`), expansion lasts for the session. The model belongs to the app context (cached per context, nothing is global to the process), and a model that is dropped takes its subscription with it.
+
+## 12. Migrating from `#tiptap-editor`
+
+The former Nuxt module `modules/tiptap-editor` (alias `#tiptap-editor`, auto-imported components, composables and utils, one server directory) is gone. Nothing is auto-imported and no alias remains: import from the entries below.
+
+1. `nuxt.config.ts`: replace `'./modules/tiptap-editor'` with `'@ecsplico/editor/nuxt'` (after `'@nuxt/ui'`). The `tiptapEditor` options keep their shape and defaults. Add `"@ecsplico/editor": "workspace:*"` to the host's dependencies.
+2. Replace auto-imported components and composables by explicit imports:
+
+| Before (auto-import or `#tiptap-editor`) | After |
+|---|---|
+| `DocumentEditor` | `AdvancedEditor` from `@ecsplico/editor/vue/advanced` (same props and events; plus `settings-ui`, see the [usage guide](./usage.md)); on React `@ecsplico/editor/react/advanced` |
+| `EditorToolbar`, `EditorSettingsModal`, `useEditorSettings`, `useEditorUi`, `useEditorContext` | `@ecsplico/editor/vue` (the toolbar takes `:editor`, the panel `:preset`) |
+| `AiSidebar`, `AiReviewBar`, `AiSelectionMenu`, `ModelQuickSwitch`, `useAiAssistant`, `useDocumentChat`, `useModelProfiles` | `@ecsplico/editor/ai/vue` (`/ai/react` on React; the framework-free models `modelProfiles`, `createAiAssistant`, `createDocumentChat` in `@ecsplico/editor/ai`) |
+| `useFileImport`, `AudioRecorderModal`, `useAudioRecorder`, `pickFiles` | `@ecsplico/editor/media/vue` (`/media/react` on React); `pickFiles` and the framework-free models in `@ecsplico/editor/media` |
+| `createTranscriptCleanup`, `hasTranscriptSegments` | `@ecsplico/editor/integrations/transcript-ai` |
+| `defaultCompositeKinds(t)`, `CompositeKind`, `headingsMarkdown`, `compositeOutline`, `moveBlockInto`, `compositeJSON`, markdown fence helpers, `CompositeTable`, `CompositeInspector`, `useCompositeRows`, `setComposite*` writers | `@ecsplico/editor/composites` (framework-free), `/composites/vue` or `/composites/react` for the components and `useCompositeRows` (schema subset: `/composites/schema`) |
+| `headingOutline`, `revealBlockInEditor` (framework-free), `EditorOutline` (`/outline/vue`, `/outline/react`) | `@ecsplico/editor/outline` |
+| `EMPTY_EDITOR_CONTENT`, `ABILITY`, `Ability`, `findBlockById`, block ID helpers | `@ecsplico/editor/core/schema` |
+| `fetchErrorMessage`, `downloadText`, abilities helpers (`abilitiesAtSelection`, `hasAbility`) | `@ecsplico/editor/core` |
+| `DocumentTree`, `useTreeView`, `TreeFolder`, `DocumentSummary` (were host files and host shared types) | `DocumentTree`, `useTreeView` from `@ecsplico/editor/tree/vue` (or `/tree/react`); `DocumentStore`, `TreeFolder`, `DocumentSummary` from `@ecsplico/editor/tree` (the host's `DocumentStore` implementation stays in the app; the host's ref-based store becomes stores with `storeFromRef` from `@ecsplico/editor/vue`) |
+| `setEditorAdapter`, `forgetCollabDocument`, `liveContent`, `EditorAdapter` (Nitro, previously auto-imported) | `@ecsplico/editor/server` |
+| Server schema / migration imports of the old shared directory | `@ecsplico/editor/schema/advanced`, `/composites/schema`, `/media/schema`, … |
+
+3. Collaboration, block UI and the integrations are now features. `AdvancedEditor` includes them; a custom preset adds `collabFeature()`, `blockUiFeature()` and the integrations explicitly. Features report user-facing messages through the surface's `Notifier` (`ctx.notify`, [§1](#per-feature-entries-framework-free-vue-react)), so host code no longer hands toast objects to feature functions.
+4. Search the host for `#tiptap-editor`, `modules/tiptap-editor` and for symbols that used to resolve without an import (`useEditorSettings`, `useFileImport`, `ABILITY`, `fileNameError`'s neighbors…); `nuxt typecheck` reports every unresolved one.
+5. Styles: the Nuxt module adds every feature stylesheet; a plain-Vue app imports `core.css` plus the feature CSS it uses ([README](../README.md#css-and-ui-provider-requirements)).
+
+Stored data needs no migration: document JSON, Yjs state, `tiptap-editor:settings`, `tiptap-editor:model-profiles` and `tip-tree:node-filters` keep their keys and shapes. Legacy `section` nodes are still migrated on load (`migrateLegacyContent`).
+
+## 13. Dependency rules and bundle proof
+
+Imports inside `packages/editor/src` follow one direction; the entry checks enforce them on the emitted bundles.
+
+| Layer | May import | Must not import |
+|---|---|---|
+| `core`, `settings` | each other, external packages other than `vue`, `@tiptap/vue-3`, `@nuxt/ui`, `react`, `sonner` | those, `vue/`, `react/`, any feature, integration, `outline`, `tree`, preset, `nuxt`, `server` |
+| `vue` (`src/vue`: `EditorSurface`, `EditorToolbar`, settings components, `createEditor`, `useEditorUi`, `vueSuggestionRenderer`, the queued notifier; `SimpleEditor`/`AdvancedEditor` also the preset they mount) | `core`, `settings`, Vue, `@tiptap/vue-3`, Nuxt UI | `react`, `nuxt`, `server` |
+| `react` (`src/react`: `EditorSurface`, `EditorToolbar`, settings components, `EditorContextProvider`, `reactSuggestionRenderer`, `reactNotifier`, vendored shadcn primitives in `ui/`; `SimpleEditor`/`AdvancedEditor` also the preset they mount) | `core`, `settings`, React, `@tiptap/react`, Radix, sonner, `@iconify/react`, framework-free features and presets | `vue`, `@tiptap/vue-3`, Nuxt UI, `nuxt`, `server` |
+| `outline`, `outline/vue`, `outline/react` | `core` (and its layer) | `tree`, composites, any feature |
+| features (`media`, `mentions`, `transcript`, `authors`, `comments`, `composites`, `ai`, `collab`, `block-ui`, `themes`): `features/<x>/{index,feature,model…}.ts` | `core`, `settings`, their own `schema`/`protocol`; no UI framework | another feature (by implementation), integrations, `tree`, `vue`, `react`, `nuxt`, `server` |
+| feature bindings (`features/<x>/vue.ts` + `vue/` components, `features/<x>/react.ts` + `react/` components) | the feature's framework-free files, `core`, `settings`, and that framework's layer (`vue` or `react`) | the other framework, other features' implementations, `nuxt`, `server` |
+| integrations | the features they connect (framework-free feature entries, or only their schema) | other integrations' internals, a UI framework, `nuxt`, `server` |
+| `tree` (`index`, `tree-view-model`, `store`; `vue.ts`; `react.ts`) | `core`, `outline`, `composites`, `media` (the bindings also their framework's layer) | AI, collab, transcript, mentions, block-ui, integrations; the other framework |
+| presets (`presets/advanced` framework-free; `vue/advanced-preset.ts`, `react/advanced-preset.ts` bind it) | everything they compose | `nuxt`, `server` |
+| `nuxt`, `server` | Nitro/Nuxt, framework-free schema entries | browser components |
+
+Simple and advanced bundles are separate: the `simple` bundle contains no feature implementation, integration, tree, AI SDK, Yjs, y-tiptap, Hocuspocus, Nuxt or server module; a feature fixture contains core, settings and that feature only. The `core-headless` fixture builds an editor from `/core` alone (`createEditorContext`, `coreFeature()`, `mentionsFeature()`) and fails on any `vue`, `@vue`, `@tiptap/vue-3`, `@nuxt/ui` or `react` module; the `headless-<x>` fixtures do the same for the framework-free entry of each feature, integration and the tree.
+
+The React fixtures (`react-simple`, `<x>-react`, `tree-react`, `outline-react`, `advanced-react`) mount their React binding with its toolbar and fail on any `vue`, `@vue`, `@tiptap/vue-3`, `@nuxt/ui`, `src/vue` or `.vue` module; the Vue fixtures fail on `react-dom`, `sonner` and `src/react`. `advanced-react` mounts the complete `AdvancedEditor` (`/react/advanced`) and requires every feature and integration binding, so no `.vue` file can slip into the React bundle unnoticed.
+
+```sh
+bun run typecheck:editor        # vue-tsc over packages/editor (no Nuxt globals; catches imports a plain Vue app cannot resolve)
+bun run check:editor-entries    # one production Vite build per fixture + Node bundle of /schema/advanced
+bun run check:editor-composition
+```
+
+`check:editor-entries` collects the module IDs of every emitted chunk (including dynamic ones) and fails on a forbidden module, on a source module outside the fixture's allow-list, or on a missing required module. To check your own composition, add `packages/editor/checks/fixtures/<name>/` (an `index.html` plus `main.ts`/`main.tsx` that mounts the surface with its toolbar, so unused factories cannot be tree-shaken away) and one `FIXTURES` entry with `forbid`, `require` and `allowSource` patterns (and `plugins: 'react'` for a React fixture) in `packages/editor/checks/entries.ts`. Fixtures exist for `simple`, each feature (Vue, `-react` and `headless-` variants), each integration, `tree`, `tree-react`, `headless-tree`, `advanced`, `advanced-react`, the headless core (`core-headless`), the React simple editor (`react-simple`) and the Node schema.