@ecsplico/editor 2.1.1 → 3.0.0

package/docs/llms.md

@@ -1,383 +0,0 @@
-# Guide for LLM coding agents
-
-Task-oriented orientation for an agent that integrates, extends or verifies `@ecsplico/editor`. It states the invariants and the shortest correct path; every detail lives in the linked guides, which you should open only for the task at hand. The code below is checked against the source (`packages/editor/package.json#exports`, `src/**/index.ts`).
-
-## What this package is
-
-- A Vue and React editor library on TipTap v3 (`@ecsplico/editor`, workspace package `packages/editor`), published as built ESM with `.d.ts` (`bun run build:editor` → `dist/`; the source maps embed the sources, `src` is not published). In this repository the `skaile-source` export condition points the demo app and the examples at `src`, so development needs no build. Consume it through Vite (`@vitejs/plugin-vue` with `@nuxt/ui/vite`, or `@vitejs/plugin-react` with `@tailwindcss/vite`) or Nuxt. Layers: framework-free `/core`, Vue (`/vue`, Nuxt UI) and React (`/react`, shadcn/ui). Every advanced feature has three entries: framework-free `/<x>` (logic, models and the UI binding contract), `/<x>/vue` and `/<x>/react`; both surfaces offer the simple editor, the advanced editor and every feature.
-- An editor is a **list of features** (`EditorFeature`) validated by `defineEditor` into an immutable `EditorPreset`, mounted by `EditorSurface`. Prebuilt presets: `simpleEditor()` (core only, no backend) and `advancedEditor()` (every feature plus the three integrations), each with a Vue and a React component (`SimpleEditor`, `AdvancedEditor`).
-- Toolbar, settings panel/modal, outline, AI sidebar and file browser are **separate components** you place beside an editor and give the editor (or the preset).
-- No runtime umbrella barrel and no global registration: importing an entry registers nothing. The root entry `@ecsplico/editor` is **type-only**.
-- UI strings render from catalogs in `de` (default) and `en`: `locale: 'de' | 'en'` and partial `messages` overrides on `createEditorContext` / `createEditor` / the module option, `ctx.t(key, params?)` in features, `useEditorI18n()` in components (see "Language" below). Server error messages are German developer messages; docs and identifiers are English.
-
-## Which entry to import
-
-Every entry is an explicit subpath of `package.json#exports`; a path that is not listed there does not resolve. Full inventory with every exported name: [README, Public exports](../README.md#public-exports).
-
-| You need | Import | Side |
-|---|---|---|
-| A ready simple editor component | `SimpleEditor` from `@ecsplico/editor/vue/simple` | browser |
-| A ready advanced editor component | `AdvancedEditor` from `@ecsplico/editor/vue/advanced` | browser |
-| A preset to pass to `EditorSurface`, `EditorToolbar`, `EditorSettingsPanel` | `simpleEditor` from `.../presets/simple`, `advancedEditor` from `.../vue/advanced` or `.../react/advanced` (the framework-free assembly behind the advanced one is `.../presets/advanced`: `advancedEditorCore`, `ADVANCED_FEATURE_IDS`) | browser |
-| Vue chrome: `createEditor` (mandatory Vue app context), `EditorSurface`, `EditorToolbar`, `EditorSettingsPanel`, `EditorSettingsModal`, `SettingsSection`, `useEditorSettings`, `useEditorUi` | `@ecsplico/editor/vue` | browser (Vue) |
-| React chrome: `EditorContextProvider` (mandatory React context from `createEditorContext()`), `EditorSurface`, `EditorToolbar`, `EditorSettingsPanel`, `EditorSettingsModal`, `SettingsSection`, `useEditorSettings`, `useEditorUi`, `Toaster`, `reactNotifier` | `@ecsplico/editor/react` | browser (React) |
-| A ready simple editor component for React | `SimpleEditor` from `@ecsplico/editor/react/simple` | browser (React) |
-| A ready advanced editor component for React | `AdvancedEditor`, `advancedEditor` from `@ecsplico/editor/react/advanced` (needs `EditorContextProvider` and `Toaster`) | browser (React) |
-| shadcn token mapping for the feature CSS (React hosts) | `@ecsplico/editor/react/styles/ui-vars.css`; for the advanced editor `@ecsplico/editor/react/styles/advanced.css` (token mapping, `core.css`, every feature sheet, `themes.css` and the theme bridge in one import) | browser (React) |
-| Framework-free core: `defineEditor`, `coreFeature`, `createEditorContext`, `commandItem`, `parseBlocks`, `createStore`, `Notifier`, extension-point types (`MenuItem`, `EditorFeature<C>`) | `@ecsplico/editor/core` | browser (no UI framework) |
-| One feature | `<x>FeatureCore(ui)`, models and types from `.../<x>`; the Vue binding `<x>Feature()` and components from `.../<x>/vue`; the React binding and components from `.../<x>/react`; `<x>` is `media`, `mentions` (framework-free only), `transcript`, `authors`, `comments`, `composites`, `ai`, `collab`, `block-ui`, `themes` | browser |
-| Markdown string as the document | `splitFrontmatter`, `joinFrontmatter`, `markdownToContent(editor, body, { policy })` → `{ content, diagnostics }` (raw HTML, unsafe URLs, unknown fences reported; `OpaqueFence` keeps unknown `::: kind` fences byte for byte), `contentToMarkdown(editor)`, `MarkdownClipboard` (paste/copy as Markdown), `createSourceMode({ getEditor })` (`state`, `enter`, `edit`, `commit` → false and editor untouched on a fatal diagnostic, `cancel`) from `.../markdown`; `MarkdownSurface` (`v-model` string, YAML frontmatter kept verbatim, props `policy` and `sourceMode`) from `.../markdown/vue` (React: `value`/`onChange`/`onDiagnostics`, prop `policy`, no source view, from `.../markdown/react`); GFM tables and task lists: `tablesFeature()` from `.../tables` (schema `.../tables/schema`, CSS `.../styles/tables.css`) | browser (`.../markdown`, `.../tables` also headless) |
-| Edit a code, YAML, JSON or text file | `CodeSurface` from `.../code/vue` (`v-model`, `editable`, `language`, `wordWrap`, emits `save`, `ready`) or `.../code/react` (`value`, `onChange`, `onSave`, `onReady`); framework-free `createCodeEditor`, `setReadOnly`, `setWordWrap`, `setLanguage`, `loadLanguage`, `setDocument`, `formatJsonInEditor`, `kindOf(path, mime?)`, `languageOf(path)` from `.../code`. Language packs are yours: `registerLanguage('yaml', async () => (await import('@codemirror/lang-yaml')).yaml())` once at startup, id from `languageOf(path)`. Theme = `--sk-*` tokens (`.../styles/tokens.css`). Needs `@codemirror/{state,view,language,commands,search}` and `@lezer/highlight` installed (optional peers); no ProseMirror/TipTap in the bundle | browser |
-| One surface for Markdown and code files | `DocumentSurface` from `.../document/vue` (`path`, `v-model`, `markdown` = props of `MarkdownSurface` incl. `preset`, `binary` slot) or `.../document/react` (`path`, `value`, `onChange`, `markdown`, `binary(path)`); chooses by `kindOf(path, mime)`; remount (`:key`/`key` = path) when the path changes. Reaches ProseMirror and CodeMirror both | browser |
-| An integration (framework-free, works on both surfaces) | `compositeMediaFeature`, `compositeAiFeature`, `transcriptAiFeature` from `.../integrations/composite-media`, `/composite-ai`, `/transcript-ai` | browser |
-| Heading outline, file browser | `EditorOutline` from `.../outline/vue` or `.../outline/react` (`headingOutline`, `revealBlockInEditor` from `.../outline`); `DocumentTree`, `useTreeView` from `.../tree/vue` or `.../tree/react`; `DocumentStore`, `createTreeView` from `.../tree` | browser |
-| Settings type, defaults, validation | `EditorSettings`, `EDITOR_SETTINGS_DEFAULTS`, `parseEditorSettings`, `editorSettingsSchema` from `.../settings` | anywhere |
-| ProseMirror schema for a server, validator or migration | `simpleSchemaExtensions` from `.../schema/simple`; `advancedSchemaExtensions` from `.../schema/advanced`; per-feature `.../<name>/schema`; base `coreSchemaExtensions`, `ROOT_ABILITIES`, `BlockId` helpers from `.../core/schema` | framework-free, Node-safe |
-| Nitro side: register the adapter, forget a deleted document | `setEditorAdapter`, `EditorAdapter`, `forgetCollabDocument`, `liveContent`, `collabStats` from `.../server` | Nitro only |
-| Server without Nitro: collab server, AI models, rate limiter, route handlers, websocket listener | `createCollabServer`, `createAiModels`, `createRateLimiter` from `.../server`; `chatPost`, `usersGet`, … and their body schemas from `.../server/handlers`; `listenCollab` from `.../server/node` | any Node process |
-| Store documents as JSON files | `createJsonAdapter({ dir, authenticate?, authorize?, users?, schemaExtensions? })` from `@ecsplico/editor/adapters/json` | Node |
-| Store documents in SQLite via drizzle (optional peer `drizzle-orm`) | `bootstrapEditorTables(db)`, `createDrizzleAdapter({ db, tables: editorTables() })` from `@ecsplico/editor/adapters/drizzle` | Node |
-| Edit a host's Markdown files | `createForgeAdapter({ content, state, schema, authenticate, … })` from `@ecsplico/editor/adapters/forge` | Node |
-| Mount the editor backend on Nitro (no Nuxt module) | `installEditorServer(nitroApp, { adapter, collab: {} \| false, ai?, rateLimit?, comments?: { store } })` from `@ecsplico/editor/server/nitro`, called from one Nitro plugin; needs `experimental: { websocket: true }` for `collab`; peer `h3` | Nitro only |
-| Bind a Vue editor surface to a document | `useEditorDocument(id, { fetch, collaboration?, user?, canComment? })` → `{ modelValue, ready, dirty, save, reload, error, collaboration, comments, editor, bind, dispose }` from `@ecsplico/editor/adapters/vue` | browser (Vue) |
-| Comment threads that survive edits | `captureAnchor`/`resolveAnchor`/`mapAnchor` from `.../anchors`; `createJsonCommentStore({ file })` from `.../comments/json`; `createDrizzleCommentStore({ db, tables: commentTables() })` from `.../comments/drizzle`; `handleCommentsRequest(store, { method, documentId, body })` from `.../comments/server`; `createRestCommentsModel({ fetch, documentId, user, canComment, getEditor })` from `.../comments/client` | `anchors`, `comments/client`: browser (no UI framework); the others: Node |
-| Nuxt module (config key `tiptapEditor`) | `@ecsplico/editor/nuxt` in `modules` | build |
-| CSS | `.../styles/core.css` (required) plus `/media.css`, `/mentions.css`, `/tables.css`, `/authors.css`, `/comments.css`, `/transcript.css`, `/composites.css`, `/ai.css`, `/collab.css`, `/block-ui.css`, `/themes.css` for the features you use | browser |
-
-Rules that follow from this table:
-
-- Import values from the subpath that owns them. The root entry `@ecsplico/editor` exports types only (`export type`), so `import { createEditor } from '@ecsplico/editor'` does not compile; use `@ecsplico/editor/vue` (Vue) or `@ecsplico/editor/react` (React). `/core` contains no `vue`, `@tiptap/vue-3`, `@nuxt/ui` or React module and no longer exports `createEditor`, `EditorSurface`, `EditorToolbar`, `EditorSettingsPanel`, `EditorSettingsModal`, `SettingsSection`, `useEditorSettings`, `useEditorUi`, `useEditorContext`: those come from `/vue` or `/react`. Feature entries follow the same rule: `/<x>` is framework-free, the components and the `<x>Feature()` binding live in `/<x>/vue` and `/<x>/react`. A React preset is `defineEditor({ features: [coreFeature(), mentionsFeature(), ...] })` with factories from `/<x>/react`; features with Vue components are not assignable to it.
-- Never import a browser entry from server code, and never import `/server` or `/nuxt` from browser code. Servers use the framework-free `schema`/`protocol`/`types` entries (`/ai/protocol`, `/integrations/transcript-ai/protocol`, `/tree/types`, `/settings`).
-
-## Minimal integration: Nuxt
-
-1. Install the package from npmjs (`npm install @ecsplico/editor`, no token needed) and the peers in the consuming app (`vue`, `@nuxt/ui`, `@tiptap/core`, `@tiptap/pm`, `@tiptap/vue-3`, `yjs`, `@hocuspocus/provider`, plus `tailwindcss` and `@iconify-json/lucide`). Inside this repository declare `"@ecsplico/editor": "workspace:*"`.
-2. Register the module **after** `@nuxt/ui` (it patches Nuxt UI's generated `ui.css` template and throws if that template is missing). The module adds every feature stylesheet to `css` (`themes.css` last), puts the package into `build.transpile` and Nitro's `externals.inline`, enables Nitro websockets, installs the client plugin `editor-context-nuxt-ui.client.ts` (`createEditor({ kit: nuxtUiKit(), settings: { remote: true } })`; the module has no `kit` option, the Vue binding is Nuxt UI) and scans the Nitro routes. It registers no component or composable.
-
-   ```ts
-   // nuxt.config.ts
-   export default defineNuxtConfig({
-     ssr: false, // TipTap renders on the client only
-     modules: ['@nuxt/ui', '@ecsplico/editor/nuxt'],
-     tiptapEditor: { ai: { /* optional; presets, slots, rateLimit, transcription: integration guide §5 */ }, collab: { authenticateUpgrade: false /* true: refuse an unauthenticated /collab upgrade with HTTP 401 (cookie hosts only) */ } },
-   })
-   ```
-
-3. Register an `EditorAdapter` in a Nitro plugin. Every package route calls `useEditorAdapter()`, which throws without a registered adapter. This one keeps everything in memory and lets any visitor in; replace `authenticate` and the storage with the host's ([integration guide §3](./integration.md#3-editoradapter-auth-and-storage) lists every method, the routes that call it and the required results):
-
-   ```ts
-   // server/plugins/editor-adapter.ts
-   import type { JSONContent } from '@tiptap/core'
-   import { type EditorAdapter, setEditorAdapter } from '@ecsplico/editor/server'
-
-   export default defineNitroPlugin(() => {
-     const contents = new Map<string, JSONContent>()
-     const states = new Map<string, Uint8Array>()
-     const assets = new Map<string, Parameters<EditorAdapter['storeAsset']>[1]>()
-     setEditorAdapter({
-       authenticate: async () => ({ id: 'demo', username: 'demo' }), // `null` = 401 on API routes; on /collab the socket is closed with 4401 (HTTP 401 at the upgrade with `collab.authenticateUpgrade`)
-       loadContent: async id => contents.get(id) ?? null,
-       storeContent: async (id, content) => { contents.set(id, content) },
-       listUsers: async () => [],
-       listContents: async () => [...contents].map(([id, content]) => ({ id, content })),
-       loadState: async id => states.get(id) ?? null,
-       storeState: async (id, state) => { states.set(id, state) },
-       removeState: async (id) => { states.delete(id) },
-       storeAsset: async (id, asset) => { assets.set(`${id}/${asset.name}`, asset) },
-       loadAsset: async (id, name) => {
-         const asset = assets.get(`${id}/${name}`)
-         if (!asset) return null
-         const { data, ...record } = asset
-         return { record, data }
-       },
-       // Omit loadSettings/storeSettings: settings stay in the browser (GET answers 204).
-       // Omit listThemes/loadTheme: the themes routes answer 501 and the standard look stays.
-     })
-   })
-   ```
-
-4. Mount the editor. `app.vue` must wrap pages in `<UApp>` (overlays, toasts, tooltips). The toolbar is a sibling that receives the editor from `ready`:
-
-   ```vue
-   <script setup lang="ts">
-   import type { Editor, JSONContent } from '@tiptap/vue-3'
-   import { AdvancedEditor } from '@ecsplico/editor/vue/advanced'
-   import { EditorToolbar } from '@ecsplico/editor/vue'
-   import { ref, shallowRef } from 'vue'
-
-   const content = ref<JSONContent>()
-   const editor = shallowRef<Editor>()
-   </script>
-
-   <template>
-     <EditorToolbar :editor="editor" />
-     <AdvancedEditor v-model="content" @ready="editor = $event" />
-   </template>
-   ```
-
-   Without a `collaboration` prop the editor is standalone (JSON `v-model`, own undo history). Collaboration is a mode fixed at mount: pass `:collaboration="{ ydoc, provider, user }"` (connect the provider to `/collab/:id`, [integration guide §6](./integration.md#6-collaboration-on-the-client)).
-
-`AdvancedEditor` pulls in every feature. For a smaller bundle use `SimpleEditor` or compose your own list (below). For the simple editor in plain Vue (no Nuxt, no backend) follow [usage guide, Simple editor in plain Vue](./usage.md#simple-editor-in-plain-vue); its pieces are:
-
-```ts
-// vite.config.ts: plugins: [vue(), ui({ router: false })]
-// main.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')
-```
-
-```css
-/* style.css: core.css AFTER Tailwind and Nuxt UI; @source lets Tailwind scan the library (path relative to this file) */
-@import "tailwindcss";
-@import "@nuxt/ui";
-@import "@ecsplico/editor/styles/core.css";
-@source "../../../packages/editor/src";
-```
-
-## Choosing a preset or features
-
-| Goal | Use |
-|---|---|
-| Rich text only, no backend, smallest bundle | `SimpleEditor` / `simpleEditor()` (feature `core`) |
-| Everything, Nuxt module as the backend | `AdvancedEditor` / `advancedEditor({ compositeKinds? })` |
-| Something in between, or the advanced set plus an own feature | `defineEditor({ features: [...] })` mounted with `EditorSurface` |
-
-Advanced list in schema order: `core`, `media`, `transcript`, `composites`, `mentions`, `authors`, `comments`, `ai`, `collab`, `block-ui`, `composite-media`, `composite-ai`, `transcript-ai`, `themes`.
-
-| Feature (factory, entries) | Needs (`requires`) | Backend |
-|---|---|---|
-| `coreFeature()` (`/core`) | none | none |
-| `mediaFeature()` (`/media/vue`, `/media/react`; `mediaFeatureCore` in `/media`) | none | uploads (`/api/editor/assets/:id`) or a host `upload` function |
-| `mentionsFeature()` (`/mentions`, no components: both surfaces) | none | `/api/editor/users`, `/api/editor/tags` or host `metadata` lists |
-| `transcriptFeature()` (`/transcript/vue`, `/transcript/react`) | none | none |
-| `authorsFeature()` (`/authors/vue`, `/authors/react`) | none | none (author comes from the collaboration session `user`) |
-| `collabFeature()` (`/collab/vue`, `/collab/react`) | none | `/collab/:id` websocket; active only when `collaboration` is passed to the surface |
-| `commentsFeature({ model? })` (`/comments/vue`, `/comments/react`) | `collab`, none with `model` | comments live in the Y.Doc, or in the host's `CommentsModel` (`model: getEditor => CommentsModel`) |
-| `compositeFeature({ kinds? })` (`/composites/vue`, `/composites/react`) | none | none (also mounts the composite overlay: status/tag chips on each title line and, on the kind icon, a popover with the type dropdown (warns before `setCompositeKind`, naming the field values that would be lost), the kind's fields and the summary; also read-only: type as text, fields disabled; enforces the kinds' accepted children, `CompositeKind.accepts`: an edit that nests a Baustein into one that does not accept its kind is refused with the notice `composites.nesting.title` („Verschachtelung nicht möglich“)) |
-| `aiFeature()` (`/ai/vue`, `/ai/react`; framework-free `aiFeatureCore` in `/ai`) | none | `/api/ai/{models,generate,chat,complete}` |
-| `blockUiFeature()` (`/block-ui/vue`, `/block-ui/react`) | none | none (drag handle, hover actions) |
-| `themesFeature()` (`/themes/vue`, `/themes/react`) | none | adapter `listThemes`/`loadTheme` |
-| `compositeMediaFeature()` (`/integrations/composite-media`, both surfaces) | `composites`, `media` | uploads |
-| `compositeAiFeature()` (`/integrations/composite-ai`, both surfaces) | `composites`, `ai`, `media` | AI plus `/api/ai/transcribe` |
-| `transcriptAiFeature()` (`/integrations/transcript-ai`, both surfaces) | `transcript`, `ai` | AI plus `/api/ai/transcript-cleanup` |
-
-```ts
-import { coreFeature, defineEditor } from '@ecsplico/editor/core'
-import { mediaFeature } from '@ecsplico/editor/media/vue' // or '/media/react' with a React surface
-import { mentionsFeature } from '@ecsplico/editor/mentions'
-
-// The models come from the app context, so no component setup is needed for the AI feature (themesFeature() of the Vue binding is the exception: call it in setup).
-const preset = defineEditor({ features: [coreFeature(), mediaFeature(), mentionsFeature()] })
-```
-
-```vue
-<EditorSurface v-model="content" :preset="preset" @ready="editor = $event" />
-```
-
-`defineEditor` keeps the given order (toolbar groups, menu entries, schema) and throws on a duplicate id, on a `requires` entry that is not in the list and on a second contributor of a singleton hook (`parseMarkdown`, `segment`, `structure`, `wrapImport`, `migrateContent`, `anchorResolver`, `formatAiResult`). It installs nothing for you. A Vue list takes the factories from `/<x>/vue`, a React list those from `/<x>/react`; mixing them is a type error (`VueFeature` is `EditorFeature<Component>`, `ReactFeature` is `EditorFeature<ComponentType<{ editor }>>`), while features without components (`coreFeature()`, `mentionsFeature()`, the integrations) fit both. A host that brings its own UI kit calls `<x>FeatureCore(ui)` with its own components ([integration guide §1](./integration.md#per-feature-entries-framework-free-vue-react)). When you use feature entries directly in a plain app, also import that feature's stylesheet. Per-feature usage: [usage guide](./usage.md); composition and entries: [integration guide §1](./integration.md#1-feature-composition-and-entries).
-
-## Contributing a custom feature
-
-A feature is an object whose optional members are the contribution points. Fill only what you need ([`EditorFeature`](../src/core/feature.ts)):
-
-| Member | Contributes |
-|---|---|
-| `extensions(ctx)` | TipTap extensions (nodes, marks, plugins) |
-| `toolbar(ctx)` | `ToolbarGroup[]`; groups of the same `id` from several features merge |
-| `blockActions(ctx)`, `slashCommands(ctx)` | hover actions (shown by `block-ui`), `/` menu rows |
-| `overlays` | framework components (`EditorFeature<C>`; Vue: `VueFeature`) mounted beside the content, receiving `{ editor }` |
-| `setup(ctx)` | per-surface side effect when the surface mounts (runtime, listener, `<head>` element); returns an optional **teardown** the surface runs when it unmounts |
-| `settingsTabs` | factory `(ctx: EditorContext) => SettingsTab<C>[]` for the tabs of `EditorSettingsPanel`/`EditorSettingsModal` (`SettingsTab<C>`: `label` is already translated, the `component` slot is the framework's component type) |
-| `metadataDefaults(ctx)` | built-in `@`/`#`-style lists |
-| `blocks`, `conversions` | block pipeline stages, „Umwandeln in …“ providers |
-| `anchorResolver`, `aiContext`, `formatAiResult` | collaboration positions, what AI knows about the document, AI result formatting |
-| `aiBlockData` | per-Baustein material for „Baustein füllen (KI)“ (additive; the host owns the fetch) |
-| `requires` | ids of features that must also be listed |
-
-```ts
-// notes/feature.ts
-import { commandItem } from '@ecsplico/editor/core'
-import type { VueFeature } from '@ecsplico/editor/vue'
-import SettingsNotesTab from './SettingsNotesTab.vue'
-
-export function notesFeature(): VueFeature {
-  return {
-    id: 'notes',
-    // requires: ['block-ui'], // fail at composition time when a dependency is missing
-    toolbar: () => [{
-      id: 'notes',
-      order: 100,
-      items: [
-        commandItem({
-          id: 'dash',
-          icon: 'i-lucide-minus',
-          label: 'Gedankenstrich',
-          command: chain => chain.insertContent('\u2013'),
-        }),
-      ],
-    }],
-    slashCommands: () => [{
-      id: 'strich',
-      label: 'Gedankenstrich',
-      icon: 'i-lucide-minus',
-      run: editor => editor.chain().focus().insertContent('\u2013').run(),
-    }],
-    // Runs in every mounted surface's setup and returns its teardown. Several surfaces of one app share state: dedupe per app
-    // inside and reference-count the release (the theme runtime keys a WeakSet by `ctx.settings`). Report problems with `ctx.notify({ title, kind })`.
-    setup: (ctx) => {
-      const onKey = (event: KeyboardEvent) => {
-        if (event.key === 'F2') ctx.ui.openSettings('notes')
-      }
-      document.addEventListener('keydown', onKey)
-      return () => document.removeEventListener('keydown', onKey)
-    },
-    // Tab ids must be unique across the preset; the panel renders nothing when no feature contributes a tab.
-    settingsTabs: ctx => [{ id: 'notes', label: ctx.t('notes.tab'), icon: 'i-lucide-notebook', component: SettingsNotesTab }],
-  }
-}
-```
-
-```vue
-<!-- notes/SettingsNotesTab.vue -->
-<script setup lang="ts">
-import USwitch from '@nuxt/ui/components/Switch.vue'
-import { SettingsSection } from '@ecsplico/editor/vue'
-import { ref } from 'vue'
-
-const shout = ref(false) // local state; see the settings note below for persisted values
-</script>
-
-<template>
-  <SettingsSection title="Notizen">
-    <div class="py-3">
-      <USwitch v-model="shout" label="Hervorheben" />
-    </div>
-  </SettingsSection>
-</template>
-```
-
-Compose it with the advanced list (or any list) and mount it with the same preset the toolbar and settings UI receive:
-
-```ts
-import { defineEditor } from '@ecsplico/editor/core'
-import { advancedEditor } from '@ecsplico/editor/vue/advanced'
-import { notesFeature } from './notes/feature'
-
-const preset = defineEditor({ features: [...advancedEditor().features, notesFeature()] })
-```
-
-Things that bite:
-
-- Items gated by an own `ability` (`commandItem({ ability })`, `SlashCommandItem.ability`, `BlockAction.ability`) stay inert until the ability exists at the caret. Grant custom abilities at root through the surface prop: `:abilities="{ root: [...ROOT_ABILITIES, MY_ABILITY] }"` (`ROOT_ABILITIES` from `/core/schema`).
-- 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.
-- A feature that adds a **node** must be known to every schema that touches the document. The Nuxt module's collab route builds its schema from `advancedSchemaExtensions()` plus the adapter's `schemaExtensions()`, so register the Vue-free node file there (`schemaExtensions: () => [YourNode]`, [extending guide, Collaboration and the server schema](./extending.md#collaboration-and-the-server-schema)); a custom Hocuspocus server builds `getSchema([...advancedSchemaExtensions(), YourNode])` itself. Standalone editors (JSON `v-model`) need none of this. `editorBlock: true` (via `NodeFlags`) gives an own node block IDs, also on the server.
-- A tab component can bind only to fields that exist in `EditorSettings`: `parseEditorSettings` drops unknown keys, so new keys are neither stored locally nor sent to the server. The tab component runs inside the app, so it can call `useEditorSettings()` (from `/vue`: `{ settings, ready, synced }` as refs; from `/react`: the same names as values).
-- Factories (`extensions`, `toolbar`, `slashCommands`, ...) receive the `FeatureContext`: `app`, `settings`, `metadata`, `ui`, `notify`, `fetch`, `ai`, `documentId`, `upload`, `collaboration`, `getEditor()`. `settings` is a framework-free store: read `ctx.settings.get()`, change it with `ctx.settings.update(s => { ... })` (or `set`), observe it with `ctx.settings.subscribe(listener)`. `ctx.notify({ id?, title, description?, kind?, icon?, duration? })` shows a user-facing notice (Nuxt UI toast or sonner toast, per surface; features never import a toast library). `ctx.app` is the app context that app-level models key on. Toolbar and block-action menus return core `MenuItem[]` (`type?: 'label' | 'separator'`, `label`, `description`, `icon`, `disabled`, `onSelect`). `getEditor()` is `undefined` while extensions are constructed; use it in event handlers only. Components in `overlays` and `component` toolbar items receive `{ editor }` as props.
-
-Complete worked example with node, node view, conversions and AI description: [extending guide, Path B](./extending.md#path-b-a-feature) and the runnable `app/editor/callout/`. Lighter path without a feature (`extensions` and `slashCommands` props): [extending guide, Path A](./extending.md#path-a-extensions-and-slashcommands).
-
-## Server side: `EditorAdapter`
-
-- The package owns the routes (`/collab/:id`, `/api/ai/*`, `/api/editor/{users,tags,settings,assets,themes}`), the Hocuspocus server, rate limiting and wire formats. The host owns identity and storage and passes both in through the single `EditorAdapter` registered with `setEditorAdapter` in a Nitro plugin.
-- Required methods: `authenticate`, `loadContent`, `storeContent`, `listUsers`, `listContents`, `loadState`, `storeState`, `removeState`, `storeAsset`, `loadAsset`. Optional: `authorize`, `contentVersion`, `schemaExtensions` (collab, below), `loadSettings`/`storeSettings` (omit both: settings stay in `localStorage`), `listThemes`/`loadTheme` (omit: themes routes answer 501), `storeTheme`/`removeTheme` (omit: upload and delete answer 501).
-- Optional AI hooks: `languageModel(ref, user)` supplies the AI SDK model for a model reference (consulted before the environment presets; `null` falls through, then 400), `listModels(user)` what `GET /api/ai/models` lists (`null` lists the presets). A host whose agent chat lives elsewhere drives the review UI with `createAgentOpReview({ notify, t })` from `/ai` (`propose`, `decide`, `reveal`, `feedback`, `end`) and passes `send` instead of `chat` to `createAiSidebarFlow`.
-- Model-facing agent texts of `/ai/protocol` (`checkAgentOps(raw, { …context, locale })`, `agentShownMessage(ops, dropped, { locale })`, `agentFeedbackText(feedback, { locale })`, `agentRetryMessage`, `agentOpSummary`) are German by default and English with `locale: 'en'`; the package's own `/api/ai/chat` prompts and results stay German.
-- A host that exposes the edit operations under its own tool name builds the retry result with `agentRetryMessage(problems, scoped, { locale, tool, partial })`, so the text tells the model to call `tool` (default `edit_document`) again rather than the editor's tool. Without `partial` the text says nothing was applied and asks for the whole corrected list (the package's own all-or-nothing retry); a host that already shows the valid operations passes `partial: true`, and the text asks only for corrected versions of the listed operations.
-- `authenticate` receives `{ headers, token }`: `token` is the client's `collaboration.token` (string or async function on the surface prop; `undefined` for HTTP routes and token-less clients). Without a session cookie `getUserSession` throws outside a main handler: map that to `null` (see `server/plugins/editor-adapter.ts` in this repository). `null` answers 401 on API routes. On `/collab/:id` the upgrade succeeds first (101) and an unauthenticated socket is closed with code 4401 afterwards; with the Nuxt module option `collab.authenticateUpgrade: true` the upgrade is authenticated from the headers alone and refused with HTTP 401 (clients that authenticate only by `collaboration.token` cannot connect then). Integration guide §4, Auth notes.
-- Authorization per document: `authorize(user, id)` runs in Hocuspocus `onConnect` with the object `authenticate` returned; `null` rejects the connection, `{ readOnly: true }` lets it sync but applies none of its edits. Without `authorize` any authenticated user may edit any document name.
-- `contentVersion(id)` (opaque string, e.g. mtime or hash) makes a document rewritten behind the editor's back safe: the server keeps the version next to the Yjs state (the bytes `storeState` receives carry a version prefix; state from earlier releases loads as version `null`). On load a differing version discards the state, calls `removeState` and re-seeds from `loadContent`; an open document is not written back over the rewrite but merged with it on its next store, or right away when the host calls `collabContentChanged(id)` after its write. The version is read right after every `storeContent`, so it must reflect that write.
-- `schemaExtensions()` returns the host's own Vue-free node and mark extensions; the collab server appends them to `advancedSchemaExtensions()` so they survive the JSON↔Yjs conversion. `collabStats()` returns `{ connections, documents }` of the running server.
-- Delete a document with `forgetCollabDocument(id)` **before** removing its JSON.
-- This repository has no login: `server/middleware/demo-session.ts` signs every `/api/` request into a demo user and `server/api/auth/switch.post.ts` switches the demo user. That is demo plumbing, not part of the package.
-- AI secrets come from environment variables only (`NUXT_TIPTAP_EDITOR_AI_API_KEY`, per-preset `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY`, `NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY`); preset ids must be camelCase. See [integration guide §5](./integration.md#5-ai-configuration-and-secrets).
-- Routes, status codes and the adapter table: [integration guide §3 and §4](./integration.md#3-editoradapter-auth-and-storage). Server-side schema for converting JSON and Yjs: [§8](./integration.md#8-vue-free-advanced-schema-for-servers).
-
-## Language
-
-- Every string the editor shows (toolbar, slash menu, hover actions, settings, AI task names, comments, notices) comes from the catalogs `src/i18n/{de,en}/*.ts`, keyed by stable dotted ids (`toolbar.bold`, `comments.tab`, `ai.task.translate.label`); `de` is the default and the source of the key set, `en` has exactly the same keys (a missing one is a type error). Catalog helpers are exported by `/core`: `createTranslator`, `CATALOGS`, `LOCALES`, `DEFAULT_LOCALE`, `isLocale`, `Locale`, `MessageKey`, `Messages`, `Translate`.
-- Choose the language once per app: `createEditorContext({ locale: 'en', messages: { 'toolbar.bold': 'Strong' } })` (React and framework-free hosts), `app.use(createEditor({ locale, messages }))` (Vue), or the Nuxt module options `tiptapEditor: { locale: 'en', messages: { … } }` (JSON-serialisable; forwarded to the client plugin). `messages` is a partial catalog applied on top of `locale`; `{name}` placeholders take `params`. An unknown locale throws. The locale is fixed for the life of the context: a host that switches languages at run time recreates the context (Vue: remount the app or key it; React: new `EditorContextProvider` value).
-- Features read `ctx.t` (`FeatureContext.t`, `EditorContext.t`, `ctx.locale`) in their factories: toolbar items, slash commands, block actions, conversion labels (`ConversionProvider.label(target, t)`) and `settingsTabs(ctx)` are built in the context's language. Components call `useEditorI18n()` (`/vue` and `/react`) and get `{ t, locale }`. A feature of your own adds its keys by passing its own strings or by extending the `messages` override; the shipped keys are the `MessageKey` union.
-- Setting values stored as ids (`'margin'`, `'Deutsch'`, `'flat'`, …) never change with the language: only their display label comes from the catalog (`*_KEYS` tables mapping an id to a key; `authorStyleItems(t)`, `defaultCompositeKinds(t)`).
-- Markdown: the source view of `MarkdownSurface` (aria label, Apply, Cancel; keys `markdown.source.*`; override through `messages`) and the `message` of every `MarkdownDiagnostic` (`markdown.diagnostic.*`) are in the context's language. `markdownToContent(editor, body, { policy, t })` and `createSourceMode({ getEditor, t })` take an explicit translator; without one they use the editor's registered surface, else the default locale.
-- `bun run check:editor-i18n` (`packages/editor/checks/i18n.ts`) fails when a user-facing literal (label/description/placeholder/aria/alt/title properties and attributes, JSX and template text, German words) appears in `src` outside `src/i18n`, or when a catalog key is unused or missing in `en`. Text that is not UI (model prompts, stored ids, developer errors) is marked `// i18n-ignore: <reason>`; the run lists every honoured pragma.
-
-## Settings and themes
-
-- Settings are one versioned JSON object (`EditorSettings`, `version: 1`: `editing`, `ai`, `blocks`, `appearance`) shared by every editor, panel and tree of one app. `createEditor()` (Vue plugin around the framework-free `createEditorContext()` from `/core`; React: `EditorContextProvider` around the same context) keeps it in `localStorage` (`tiptap-editor:settings`); `createEditor({ settings: { remote: true } })` (what the Nuxt plugin installs; React: `createEditorContext({ settings: { remote: true } })`) syncs it per account through `GET`/`PUT /api/editor/settings`. Read and edit it with `useEditorSettings()` (`/vue` or `/react`); in features use the `ctx.settings` store. Validate with `parseEditorSettings` (drops unknown keys, replaces invalid values) or `editorSettingsSchema`. [Integration guide §11](./integration.md#11-settings-persistence-and-app-lifetime).
-- Settings UI: tabs come from the features of a preset (`composites` `editing`, `ai`, `authors`, `comments`, `themes` `appearance`); the simple editor has none. `EditorSettingsPanel` (props `preset`, `contentClass?`, `v-model:tab`) places the tabs anywhere; `EditorSettingsModal` (props `preset`, `v-model:open`, `v-model:tab`) is the same panel in a fixed-width (`42rem`) popup with a blurred backdrop. Both render nothing when the preset has no tab.
-- **`settingsUi`** (prop of `EditorSurface` and `AdvancedEditor`): `'internal'` (default) mounts the modal inside the surface and the toolbar's settings entry opens it. `'external'` mounts nothing and emits `settingsOpen(tab?)`; the host then shows its own `EditorSettingsPanel` or `EditorSettingsModal` for the same `preset`:
-
-  ```vue
-  <script setup lang="ts">
-  import { EditorSettingsModal, EditorSurface } from '@ecsplico/editor/vue'
-  import { advancedEditor } from '@ecsplico/editor/vue/advanced'
-  import { ref } from 'vue'
-
-  const preset = advancedEditor() // in setup
-  const open = ref(false)
-  const tab = ref<string>()
-  </script>
-
-  <template>
-    <EditorSurface :preset="preset" settings-ui="external" @settings-open="(t) => { tab = t; open = true }" />
-    <EditorSettingsModal v-model:open="open" v-model:tab="tab" :preset="preset" />
-  </template>
-  ```
-
-- **Themes** (`themesFeature()`, part of `advancedEditor()` on both surfaces): the setting `appearance.theme` (`null` = standard look) names an Obsidian theme served by `GET /api/editor/themes/:id`. The feature's `setup` hook starts one runtime per app as soon as the first surface mounts (reference-counted, released by the teardown: on Vue it lives until the Vue app unmounts, on React until the last surface that started it unmounts), injects the scoped CSS as `<style data-tiptap-theme>` and sets `obsidian-theme theme-dark|theme-light` on `<html>` (following `html.dark`/`html.light`, else the system preference). `styles/themes.css` bridges Obsidian variables onto every `--ui-*` token (React: `react/styles/themes-bridge.css` onto the shadcn tokens), so the **whole site** is themed, not only the editor. Needs an adapter with `listThemes`/`loadTheme`. Builtin themes in this repository (`server/themes/<id>/`): `nord`, `things`, `minimal`, `catppuccin`, `border`, `blue-topaz`, `tokyo-night`. Details, mapping table, limits: [usage guide, Themes](./usage.md#themes-obsidian).
-
-## Pitfalls and invariants
-
-- **CSS order.** `core.css` after Tailwind and Nuxt UI, plus the CSS of every feature you use, `themes.css` last. Tailwind must see the library's classes (`@source` to `packages/editor/src` in plain Vue; the Nuxt module appends it to `ui.css` itself). Without this the editor renders unstyled or without utility classes.
-- **Editor context is mandatory.** `EditorSurface`, `SimpleEditor`, `AdvancedEditor` and `EditorToolbar` throw without `app.use(createEditor())` (the Nuxt module does this in its client plugin); the React components throw without `<EditorContextProvider context={createEditorContext()}>`, and the React host owns (disposes) that context.
-- **Notices.** Features send user-facing messages through `ctx.notify` / the context's `notify` (`Notifier`, `silentNotifier` drops them). Vue: the queued notifier hands them to Nuxt UI toasts once a surface mounted (needs `<UApp>`). React: pass `createEditorContext({ notify: reactNotifier })` and mount sonner's `<Toaster />` (exported by `/react`) once; without it no notice is visible.
-- **UI provider.** Wrap the page in `<UApp>`; plain Vue also needs `app.use(ui)` (`@nuxt/ui/vue-plugin`) and the `ui({ router: false })` Vite plugin.
-- **SSR.** Editors are client-only. Nuxt apps in this repository run `ssr: false`; with SSR enabled wrap editors in `<ClientOnly>`.
-- **Mount-time props.** The preset (schema, features), `collaboration`, `abilities`, `extensions`, `slashCommands`, `blockActions`, `compositeKinds`, `documentId`, `upload` are read once at setup. Change them by remounting with a new `key`. `editable`, `metadata` and the model stay reactive. Build presets in `<script setup>` (Vue) or a component/`useMemo` (React), not on every render.
-- **Stable props.** Pass `metadata`, `abilities` and `extensions` as constants; a new object per render replaces the lists each time.
-- **Schema match.** A simple editor rejects advanced JSON through the `contentError` event (the last valid document stays). `collaboration` needs a preset containing `collab`; `commentsFeature()` needs `collab`.
-- **Bundle isolation.** `core`/`settings` import no feature; a feature imports `core`, `settings` and its own `schema`/`protocol`, never another feature; integrations import only the features they connect; the `simple` bundle contains no feature code, Yjs, AI SDK, Nuxt or server modules. Keep it that way when adding code, and prove it with `check:editor-entries`. Rules: [integration guide §13](./integration.md#13-dependency-rules-and-bundle-proof).
-- **Entries.** Server code imports only framework-free entries (`/schema`, `/protocol`, `/types`, `/settings`) or `/server`. A new public entry needs an explicit `package.json#exports` row; there is no wildcard.
-- **Icons.** `i-lucide-*` names resolve at build time inside the Vite root; a workspace library lies outside it. Bundle them (see `examples/vue-simple/vite.config.ts`) to avoid Iconify API requests at runtime.
-- **React hosts.** CSS: Tailwind, `tw-animate-css`, then either `.../react/styles/ui-vars.css`, `core.css` and the feature sheets, or for the advanced editor the single `.../react/styles/advanced.css`; the shadcn theme block, and `@source` to `packages/editor/src`; icons: `addCollection(lucide)` from `@iconify/react` before rendering; `<Toaster />` for notices. The preset, `metadata`, `abilities`, `extensions` and `slashCommands` are mount-time: keep them module constants (new objects per render replace the lists). `editor` from `onReady` goes in `useState`, and `EditorToolbar` takes it as `editor`. Examples: [usage guide, Simple editor in React](./usage.md#simple-editor-in-react) and [Advanced editor in React](./usage.md#advanced-editor-in-react).
-- **Settings keys.** Only keys of `EditorSettings` persist; unknown ones are dropped on read and write.
-- **Design tokens.** `@ecsplico/editor/styles/tokens.css` declares the shared `--sk-*` variables (`--sk-bg`, `--sk-fg`, `--sk-muted`, `--sk-border`, `--sk-primary`, `--sk-primary-fg`, `--sk-success`, `--sk-warning`, `--sk-danger`, `--sk-radius`, `--sk-font`) under `:where(:root)` (dark values under `:where(.dark)`). Later UI work in this package reads `--sk-*`; map them once in the host.
-- **Module order.** `@nuxt/ui` before `@ecsplico/editor/nuxt` in `modules`.
-- **Adapters tier.** Entries under `adapters/`, `anchors`, `comments/{server,json,drizzle,client}` and `server/nitro` supply storage and wiring; they import no application code. Vue is reachable only from `./adapters/vue`, Nitro (`h3`) only from `./server/nitro`, `drizzle-orm` only from the two drizzle entries, React from none; `./adapters` is types only. `./adapters/react`, `./server/nest` and `./adapters/prisma` are reserved and not exported. The Nitro host and `useEditorDocument` speak one wire contract: `GET`/`PUT /api/editor/documents/:id` (TipTap JSON, 404 = missing, `PUT` 204 and only for adapters that manage documents), `GET`/`POST /api/editor/comments/:id` (`handleCommentsRequest`, which trusts its caller), `/collab/:id` (Hocuspocus; `collaboration.url` is `ws://host/collab`). Every route authenticates through `adapter.authenticate({ headers, token })`; `null` answers 401; the default outside production is an anonymous dev user, in production nobody. The JSON and forge adapters and the JSON comment store are single-node. Mount the surface with `:key="id"` and `v-if="doc.ready.value"`, bind with `v-bind="doc.bind.value"`. Runnable reference: `examples/vue-nitro-json` (`bun run proto:vue-nitro-json`, port 3046).
-
-## Verify
-
-Run from the repository root after `bun install` (on a clean checkout build `examples/vue-simple` once before the editor typecheck: it prepares the Nuxt UI theme aliases the typecheck needs):
-
-```sh
-bun run --cwd examples/vue-simple build       # once on a clean checkout
-bun run typecheck:editor                      # vue-tsc --noEmit -p packages/editor/tsconfig.json (src/nuxt excluded)
-bun run build:editor                          # tsdown: packages/editor/dist (ESM + .d.ts per export)
-bun run check:editor-entries                  # builds the editor, then one production build per fixture + module-graph isolation, then the schema snapshot
-bun run check:editor-composition              # defineEditor rejects missing `requires`; accepted compositions; one formatAiResult
-bun run test:editor                           # bun test: inspector model, AI selection flow, surface session on a mounted editor (happy-dom)
-bun run typecheck                             # nuxt typecheck of the demo app
-bun run --cwd examples/vue-simple typecheck   # plain Vue consumer
-bun run --cwd examples/react-simple typecheck # plain React consumer
-bun run --cwd examples/react-advanced typecheck # React consumer of every feature
-bun run dev                                   # Nuxt demo, http://localhost:3031
-bun run --cwd examples/vue-simple dev         # plain Vue example, http://localhost:3040
-bun run --cwd examples/react-simple dev       # plain React example, http://localhost:3041
-bun run --cwd examples/react-advanced dev     # React advanced example (proxies /api and /collab to the Nuxt demo), http://localhost:3043
-```
-
-After adding a feature, add a fixture folder `packages/editor/checks/fixtures/<name>/` (an `index.html` plus `main.ts`/`App.vue` — or `main.tsx` for a React fixture — that mounts the surface with its toolbar) and one entry in `FIXTURES` in `packages/editor/checks/entries.ts` with `forbid`, `require` and `allowSource` patterns; features get a `<name>`, a `<name>-react` and a framework-free `headless-<name>` fixture. `check:editor-entries` also fails when the advanced or simple schema differs from the committed snapshot (`checks/fixtures/schema-node/schema.snapshot.json`); regenerate it deliberately with `bun packages/editor/checks/schema.ts --update`.
-
-## Where to read next
-
-| Task | Guide |
-|---|---|
-| Plain Vue setup, `SimpleEditor` props and events, React setup (`EditorContextProvider`, `EditorSurface`, `EditorToolbar`, `SimpleEditor`, the advanced editor in React), media/mentions/transcript, authors and comments, themes, composites, AI, file browser, the demo app | [Usage guide](./usage.md) |
-| Own blocks and features (node, node view, toolbar, `/` command, conversions, AI description) | [Extending guide](./extending.md) |
-| Nuxt module, `EditorAdapter`, routes, auth, AI secrets, per-feature entries and the UI binding contract, notices and `setup` teardown, collaboration, schema for servers, `DocumentStore`, production, dependency rules | [Integration guide](./integration.md) |
-| Every exported name per entry | [README](../README.md) |