# Reading these docs as an agent

> Machine entry points of this site (llms.txt, markdown twins, sitemap, installable Agent Skill) and where an agent starts.

This site is written for people and for coding agents. Every page has a plain Markdown twin, the whole site is available as one file, and an Agent Skill packages the workflow for tools that support skills.

## Machine entry points

<table>
<thead>
  <tr>
    <th>
      What
    </th>
    
    <th>
      URL
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Index of every page with a one-line description
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/llms.txt" rel="nofollow">
        <code>
          /llms.txt
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Every page in one Markdown file
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/llms-full.txt" rel="nofollow">
        <code>
          /llms-full.txt
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Markdown twin of a page
    </td>
    
    <td>
      append <code>
        .md
      </code>
      
       to the page URL, or <code>
        GET /raw/<path>.md
      </code>
      
      , for example <a href="https://skaile-ai.github.io/forge-editor/raw/ai-agents/invariants.md" rel="nofollow">
        <code>
          /raw/ai-agents/invariants.md
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Sitemap as Markdown
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/sitemap.md" rel="nofollow">
        <code>
          /sitemap.md
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Agent Skill index
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/.well-known/skills/index.json" rel="nofollow">
        <code>
          /.well-known/skills/index.json
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      The skill itself
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/.well-known/skills/ecsplico-editor/SKILL.md" rel="nofollow">
        <code>
          /.well-known/skills/ecsplico-editor/SKILL.md
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

Install the skill into a skills-aware agent:

```sh
npx skills add https://skaile-ai.github.io/forge-editor
```

<note>

The site is static, so it has no MCP endpoint. The npm-side entry point is the [`README.md` of the package](https://github.com/skaile-ai/forge-editor/blob/main/packages/editor/README.md); it links back here.

</note>

## Where to start

Open only the page that matches the task. Every detail lives in the guides and the reference; these pages state the shortest correct path and the invariants.

<table>
<thead>
  <tr>
    <th>
      Task
    </th>
    
    <th>
      Page
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Add the editor to an app: pick the entry, the preset, the surface
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/ai-agents/integrate">
        Integrate the editor
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Add an own block or an own feature
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/ai-agents/extend">
        Add a block or feature
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Check what must stay true (CSS order, mandatory context, SSR, bundle isolation, entries)
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/ai-agents/invariants">
        Pitfalls and invariants
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Prove the change works
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/ai-agents/verify">
        Verify
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Look up an exported name
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/reference/exports">
        Public exports
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Look up a feature, its <code>
        requires
      </code>
      
       and its backend
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/reference/presets-and-features">
        Presets and features
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Contribute a custom feature (<code>
        EditorFeature
      </code>
      
       members)
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/reference/feature-contract">
        Feature contract
      </a>
    </td>
  </tr>
</tbody>
</table>


# Add a block or feature

> Agent playbook for adding an own block or feature to @skaile/forge-editor: an ordered checklist where each step links to the tutorial chapter that shows it.

Two ways to add a block: **Path A** passes `extensions` and a `commands` transformer to `SimpleEditor` (no feature object); **Path B** ships an `EditorFeature` that composes with any preset. The tutorial builds the same „Hinweis" callout both ways; follow the chapters in order and use this list as the checklist.

1. **Node.** `Node.create` in a Vue-free `node.ts`; `group`, `content`, attributes with `parseHTML`/`renderHTML`, commands and a free shortcut. [Tutorial: own block, path A](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a)
2. **Block IDs.** `editorBlock: true` if AI operations, flash/reveal, paste de-duplication or the server ID backfill should reach it. [Tutorial: own block, path A](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a)
3. **Abilities.** `abilities` on the node for what is allowed inside; for a custom ability id, grant it through the `abilities` prop (`root`). [Tutorial: own feature, path B](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b)
4. **Markdown.** `renderMarkdown`, `markdownTokenName`, `markdownTokenizer`, `parseMarkdown` with syntax no other stage claims; test the round trip (`getMarkdown()` → `parseBlocks`), including multi-block bodies. [Tutorial: own block, path A](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a)
5. **View and CSS.** Node view in a separate `index.ts` (`Node.extend`), stylesheet imported after `core.css`. [Tutorial: own block, path A](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a), CSS order: [CSS and UI-provider requirements](https://skaile-ai.github.io/forge-editor/reference/css-and-ui)
6. **Path A.** `extensions` (constant) and the `commands` transformer prop (a command with `slash: {}`), nothing else needed. [Tutorial: own block, path A](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a)
7. **Path B.** An `EditorFeature`: `extensions`, then `commands` (one `CommandDef` per command with `toolbar` and/or `slash` placement, `creates`, `ability`) and `toolbarGroups` if you need a new group, `blockActions` with your `ability`, `conversions` with a `custom` target; `requires` for features you depend on. [Tutorial: own feature, path B](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b), every member: [Feature contract](https://skaile-ai.github.io/forge-editor/reference/feature-contract)
8. **Compose.** `defineEditor({ features: [...advancedEditor().features, yourFeature()] })` in setup (`advancedEditor` from `/vue/advanced` or `/react/advanced`); mount with `EditorSurface` and pass `abilities` for custom ability ids; add `blockUiFeature()` to a smaller list when you use hover actions. [Tutorial: compose features](https://skaile-ai.github.io/forge-editor/tutorial/compose-features), [Tutorial: own feature, path B](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b)
9. **Server.** When documents with your block are collaborative, pass `YourNode` in the server's `schema` option (`provideEditorServer({ ports, schema: () => [...advancedSchemaExtensions(), YourNode] })`; the collab server uses it instead of `advancedSchemaExtensions()`), or build `getSchema([...advancedSchemaExtensions(), YourNode])` in your own Hocuspocus server. [Tutorial: backend and collaboration](https://skaile-ai.github.io/forge-editor/tutorial/backend-and-collaboration), [Vue-free schema for servers](https://skaile-ai.github.io/forge-editor/reference/advanced-schema)
10. **AI.** Decide what the model should see (`renderMarkdown`) and write; describe the block in `aiContext.blocks` (`id`, `label`, `description`, `syntax`, `example`, matching your Markdown); `aiContext` is additive, a block id may be described only once; add a `custom` conversion provider if the block should be a `convert` target. [Tutorial: AI](https://skaile-ai.github.io/forge-editor/tutorial/ai), [AI guide](https://skaile-ai.github.io/forge-editor/guides/ai)
11. **Bundle proof.** If you ship the block in a package, add a fixture and a `FIXTURES` entry for `bun run check:editor-entries` ([Dependency rules](https://skaile-ai.github.io/forge-editor/reference/dependency-rules)); `bun run check:editor-composition` covers `defineEditor` validation. [Verify](https://skaile-ai.github.io/forge-editor/ai-agents/verify)

Then check the [invariants](https://skaile-ai.github.io/forge-editor/ai-agents/invariants).


# Integrate the editor

> Agent playbook for adding @skaile/forge-editor to an app: choose the surface, then the entry to import, then follow the matching setup page.

## Choose the surface

Decide first which host the editor lands in. Each row links to the page that holds the ordered setup steps and the code; do not retype them from memory.

<table>
<thead>
  <tr>
    <th>
      Host
    </th>
    
    <th>
      Surface and entry
    </th>
    
    <th>
      Setup
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Nuxt app (editor plus backend)
    </td>
    
    <td>
      <code>
        AdvancedEditor
      </code>
      
       from <code>
        @skaile/forge-editor/vue/advanced
      </code>
      
      , module <code>
        @skaile/forge-editor/nuxt
      </code>
      
      , <code>
        EditorPorts
      </code>
      
       in a Nitro plugin
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/getting-started/quick-start-nuxt">
        Quick start: Nuxt
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Plain Vue 3 app (Vite), no backend
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
       from <code>
        @skaile/forge-editor/vue/simple
      </code>
      
      , <code>
        createEditor()
      </code>
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/getting-started/quick-start-vue">
        Quick start: Vue
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      React 19 app
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
       from <code>
        @skaile/forge-editor/react/simple
      </code>
      
       inside <code>
        EditorContextProvider
      </code>
      
      ; <code>
        AdvancedEditor
      </code>
      
       from <code>
        @skaile/forge-editor/react/advanced
      </code>
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/getting-started/quick-start-react">
        Quick start: React
      </a>
      
      , <a href="https://skaile-ai.github.io/forge-editor/guides/advanced-react">
        Advanced editor in React
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Framework-free (headless, server, validator)
    </td>
    
    <td>
      <code>
        /core
      </code>
      
      , the <code>
        <x>
      </code>
      
       entries without <code>
        /vue
      </code>
      
       or <code>
        /react
      </code>
      
      , <code>
        schema/*
      </code>
      
      , <code>
        /server
      </code>
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/reference/exports">
        Public exports
      </a>
    </td>
  </tr>
</tbody>
</table>

The Nuxt path in order: install the package and its peers ([Installation](https://skaile-ai.github.io/forge-editor/getting-started/installation)); register the module **after** `@nuxt/ui`; register `EditorPorts` in a Nitro plugin ([EditorPorts guide](https://skaile-ai.github.io/forge-editor/guides/editor-ports)); mount the editor inside `<UApp>` with the toolbar as a sibling that receives the editor from `ready`. The Nuxt module installs the client plugin with `createEditor`; plain Vue and React hosts create the context themselves.

`AdvancedEditor` pulls in every feature. For a smaller bundle use `SimpleEditor` or compose a list yourself.

## Choose a preset or features

Which preset or feature list fits the goal, and what each feature needs from the backend: [Composing an editor](https://skaile-ai.github.io/forge-editor/guides/composition) (decision table) and [Presets and features](https://skaile-ai.github.io/forge-editor/reference/presets-and-features) (every feature with `requires` and backend). Own features: [Add a block or feature](https://skaile-ai.github.io/forge-editor/ai-agents/extend).

## 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: [Public exports](https://skaile-ai.github.io/forge-editor/reference/exports).

<table>
<thead>
  <tr>
    <th>
      You need
    </th>
    
    <th>
      Import
    </th>
    
    <th>
      Side
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A ready simple editor component
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
       from <code>
        @skaile/forge-editor/vue/simple
      </code>
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      A ready advanced editor component
    </td>
    
    <td>
      <code>
        AdvancedEditor
      </code>
      
       from <code>
        @skaile/forge-editor/vue/advanced
      </code>
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      A preset to pass to <code>
        EditorSurface
      </code>
      
      , <code>
        EditorToolbar
      </code>
      
      , <code>
        EditorSettingsPanel
      </code>
    </td>
    
    <td>
      <code>
        simpleEditor
      </code>
      
       from <code>
        .../presets/compose
      </code>
      
       (framework-free, no ⌘K palette), <code>
        advancedEditor
      </code>
      
       / <code>
        composeEditor
      </code>
      
       from <code>
        .../vue/advanced
      </code>
      
       or <code>
        .../react/advanced
      </code>
      
       (the framework-free assembly behind them is <code>
        .../presets/compose
      </code>
      
      : <code>
        composeEditor(ui, options)
      </code>
      
      , <code>
        CONTENT
      </code>
      
      , <code>
        INTERACTION
      </code>
      
      , <code>
        AI
      </code>
      
      )
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      Vue chrome: <code>
        createEditor
      </code>
      
       (mandatory Vue app context), <code>
        EditorSurface
      </code>
      
      , <code>
        EditorToolbar
      </code>
      
      , <code>
        EditorSettingsPanel
      </code>
      
      , <code>
        EditorSettingsModal
      </code>
      
      , <code>
        EditorCommandPalette
      </code>
      
       (⌘K palette, the <code>
        core-ui
      </code>
      
       overlay), <code>
        SettingsSection
      </code>
      
      , <code>
        useEditorSettings
      </code>
      
      , <code>
        useEditorUi
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/vue
      </code>
    </td>
    
    <td>
      browser (Vue)
    </td>
  </tr>
  
  <tr>
    <td>
      React chrome: <code>
        EditorContextProvider
      </code>
      
       (mandatory React context from <code>
        createEditorContext()
      </code>
      
      ), <code>
        EditorSurface
      </code>
      
      , <code>
        EditorToolbar
      </code>
      
      , <code>
        EditorSettingsPanel
      </code>
      
      , <code>
        EditorSettingsModal
      </code>
      
      , <code>
        EditorCommandPalette
      </code>
      
       (⌘K palette, the <code>
        core-ui
      </code>
      
       overlay), <code>
        SettingsSection
      </code>
      
      , <code>
        useEditorSettings
      </code>
      
      , <code>
        useEditorUi
      </code>
      
      , <code>
        Toaster
      </code>
      
      , <code>
        reactNotifier
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/react
      </code>
    </td>
    
    <td>
      browser (React)
    </td>
  </tr>
  
  <tr>
    <td>
      A ready simple editor component for React
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
       from <code>
        @skaile/forge-editor/react/simple
      </code>
    </td>
    
    <td>
      browser (React)
    </td>
  </tr>
  
  <tr>
    <td>
      A ready advanced editor component for React
    </td>
    
    <td>
      <code>
        AdvancedEditor
      </code>
      
      , <code>
        advancedEditor
      </code>
      
       from <code>
        @skaile/forge-editor/react/advanced
      </code>
      
       (needs <code>
        EditorContextProvider
      </code>
      
       and <code>
        Toaster
      </code>
      
      )
    </td>
    
    <td>
      browser (React)
    </td>
  </tr>
  
  <tr>
    <td>
      shadcn token mapping for the feature CSS (React hosts)
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/react/styles/ui-vars.css
      </code>
      
      ; for the advanced editor <code>
        @skaile/forge-editor/react/styles/advanced.css
      </code>
      
       (token mapping, <code>
        core.css
      </code>
      
      , every feature sheet, <code>
        themes.css
      </code>
      
       and the theme bridge in one import)
    </td>
    
    <td>
      browser (React)
    </td>
  </tr>
  
  <tr>
    <td>
      Framework-free core: <code>
        defineEditor
      </code>
      
      , <code>
        coreContentFeature
      </code>
      
      , <code>
        coreUiFeature
      </code>
      
      , <code>
        createEditorContext
      </code>
      
      , <code>
        command
      </code>
      
      , <code>
        commandState
      </code>
      
      , <code>
        parseBlocks
      </code>
      
      , <code>
        createStore
      </code>
      
      , <code>
        Notifier
      </code>
      
      , extension-point types (<code>
        MenuItem
      </code>
      
      , <code>
        EditorFeature<C>
      </code>
      
      )
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
    </td>
    
    <td>
      browser (no UI framework)
    </td>
  </tr>
  
  <tr>
    <td>
      One feature
    </td>
    
    <td>
      <code>
        <x>FeatureCore(ui)
      </code>
      
      , models and types from <code>
        .../<x>
      </code>
      
      ; the Vue binding <code>
        <x>Feature()
      </code>
      
       and components from <code>
        .../<x>/vue
      </code>
      
      ; the React binding and components from <code>
        .../<x>/react
      </code>
      
      ; <code>
        <x>
      </code>
      
       is <code>
        media
      </code>
      
      , <code>
        mentions
      </code>
      
       (framework-free only), <code>
        transcript
      </code>
      
      , <code>
        authors
      </code>
      
      , <code>
        comments
      </code>
      
      , <code>
        composites
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        collab
      </code>
      
      , <code>
        block-ui
      </code>
      
      , <code>
        themes
      </code>
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      Markdown string as the document
    </td>
    
    <td>
      <code>
        splitFrontmatter
      </code>
      
      , <code>
        joinFrontmatter
      </code>
      
      , <code>
        markdownToContent(editor, body, { policy })
      </code>
      
       → <code>
        { content, diagnostics }
      </code>
      
       (raw HTML, unsafe URLs, unknown fences reported; <code>
        OpaqueFence
      </code>
      
       keeps unknown <code>
        ::: kind
      </code>
      
       fences byte for byte), <code>
        contentToMarkdown(editor)
      </code>
      
      , <code>
        MarkdownClipboard
      </code>
      
       (paste/copy as Markdown), <code>
        createSourceMode({ getEditor })
      </code>
      
       (<code>
        state
      </code>
      
      , <code>
        enter
      </code>
      
      , <code>
        edit
      </code>
      
      , <code>
        commit
      </code>
      
       → false and editor untouched on a fatal diagnostic, <code>
        cancel
      </code>
      
      ) from <code>
        .../markdown
      </code>
      
      ; <code>
        MarkdownSurface
      </code>
      
       (<code>
        v-model
      </code>
      
       string, YAML frontmatter kept verbatim, props <code>
        policy
      </code>
      
       and <code>
        sourceMode
      </code>
      
      ) from <code>
        .../markdown/vue
      </code>
      
       (React: <code>
        value
      </code>
      
      /<code>
        onChange
      </code>
      
      /<code>
        onDiagnostics
      </code>
      
      , prop <code>
        policy
      </code>
      
      , no source view, from <code>
        .../markdown/react
      </code>
      
      ); GFM tables and task lists: <code>
        tablesFeature()
      </code>
      
       from <code>
        .../tables
      </code>
      
       (schema <code>
        .../tables/schema
      </code>
      
      , CSS <code>
        .../styles/tables.css
      </code>
      
      )
    </td>
    
    <td>
      browser (<code>
        .../markdown
      </code>
      
      , <code>
        .../tables
      </code>
      
       also headless)
    </td>
  </tr>
  
  <tr>
    <td>
      Edit a code, YAML, JSON or text file
    </td>
    
    <td>
      <code>
        CodeSurface
      </code>
      
       from <code>
        .../code/vue
      </code>
      
       (<code>
        v-model
      </code>
      
      , <code>
        editable
      </code>
      
      , <code>
        language
      </code>
      
      , <code>
        wordWrap
      </code>
      
      , emits <code>
        save
      </code>
      
      , <code>
        ready
      </code>
      
      ) or <code>
        .../code/react
      </code>
      
       (<code>
        value
      </code>
      
      , <code>
        onChange
      </code>
      
      , <code>
        onSave
      </code>
      
      , <code>
        onReady
      </code>
      
      ); framework-free <code>
        createCodeEditor
      </code>
      
      , <code>
        setReadOnly
      </code>
      
      , <code>
        setWordWrap
      </code>
      
      , <code>
        setLanguage
      </code>
      
      , <code>
        loadLanguage
      </code>
      
      , <code>
        setDocument
      </code>
      
      , <code>
        formatJsonInEditor
      </code>
      
      , <code>
        kindOf(path, mime?)
      </code>
      
      , <code>
        languageOf(path)
      </code>
      
       from <code>
        .../code
      </code>
      
      . Language packs are yours: <code>
        registerLanguage('yaml', async () => (await import('@codemirror/lang-yaml')).yaml())
      </code>
      
       once at startup, id from <code>
        languageOf(path)
      </code>
      
      . Theme = <code>
        --sk-*
      </code>
      
       tokens (<code>
        .../styles/tokens.css
      </code>
      
      ). Needs <code>
        @codemirror/{state,view,language,commands,search}
      </code>
      
       and <code>
        @lezer/highlight
      </code>
      
       installed (optional peers); no ProseMirror/TipTap in the bundle
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      One surface for Markdown and code files
    </td>
    
    <td>
      <code>
        DocumentSurface
      </code>
      
       from <code>
        .../document/vue
      </code>
      
       (<code>
        path
      </code>
      
      , <code>
        v-model
      </code>
      
      , <code>
        markdown
      </code>
      
       = props of <code>
        MarkdownSurface
      </code>
      
       incl. <code>
        preset
      </code>
      
      , <code>
        binary
      </code>
      
       slot) or <code>
        .../document/react
      </code>
      
       (<code>
        path
      </code>
      
      , <code>
        value
      </code>
      
      , <code>
        onChange
      </code>
      
      , <code>
        markdown
      </code>
      
      , <code>
        binary(path)
      </code>
      
      ); chooses by <code>
        kindOf(path, mime)
      </code>
      
      ; remount (<code>
        :key
      </code>
      
      /<code>
        key
      </code>
      
       = path) when the path changes. Reaches ProseMirror and CodeMirror both
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      An integration (framework-free, works on both surfaces)
    </td>
    
    <td>
      <code>
        compositeMediaFeature
      </code>
      
      , <code>
        compositeAiFeature
      </code>
      
      , <code>
        transcriptAiFeature
      </code>
      
       from <code>
        .../integrations/composite-media
      </code>
      
      , <code>
        /composite-ai
      </code>
      
      , <code>
        /transcript-ai
      </code>
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      Heading outline, Document tree
    </td>
    
    <td>
      <code>
        EditorOutline
      </code>
      
       from <code>
        .../outline/vue
      </code>
      
       or <code>
        .../outline/react
      </code>
      
       (<code>
        headingOutline
      </code>
      
      , <code>
        revealBlockInEditor
      </code>
      
       from <code>
        .../outline
      </code>
      
      ); <code>
        DocumentTree
      </code>
      
      , <code>
        useTreeView
      </code>
      
       from <code>
        .../tree/vue
      </code>
      
       or <code>
        .../tree/react
      </code>
      
      ; <code>
        DocumentStore
      </code>
      
      , <code>
        createTreeView
      </code>
      
       from <code>
        .../tree
      </code>
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      Settings type, defaults, validation
    </td>
    
    <td>
      <code>
        EditorSettings
      </code>
      
      , <code>
        EDITOR_SETTINGS_DEFAULTS
      </code>
      
      , <code>
        parseEditorSettings
      </code>
      
      , <code>
        editorSettingsSchema
      </code>
      
       from <code>
        .../settings
      </code>
    </td>
    
    <td>
      anywhere
    </td>
  </tr>
  
  <tr>
    <td>
      ProseMirror schema for a server, validator or migration
    </td>
    
    <td>
      <code>
        simpleSchemaExtensions
      </code>
      
       from <code>
        .../schema/simple
      </code>
      
      ; <code>
        advancedSchemaExtensions
      </code>
      
       from <code>
        .../schema/advanced
      </code>
      
      ; per-feature <code>
        .../<name>/schema
      </code>
      
      ; base <code>
        coreSchemaExtensions
      </code>
      
      , <code>
        ROOT_ABILITIES
      </code>
      
      , <code>
        BlockId
      </code>
      
       helpers from <code>
        .../core/schema
      </code>
    </td>
    
    <td>
      framework-free, Node-safe
    </td>
  </tr>
  
  <tr>
    <td>
      Nitro side: register the ports, forget a deleted document
    </td>
    
    <td>
      <code>
        provideEditorServer
      </code>
      
      , <code>
        useEditorServer
      </code>
      
       (<code>
        .forgetDocument
      </code>
      
      , <code>
        .liveContent
      </code>
      
      , <code>
        .enforceRateLimit
      </code>
      
      , <code>
        .resolveModel
      </code>
      
      ) from <code>
        .../server/nitro
      </code>
      
      , <code>
        EditorPorts
      </code>
      
       from <code>
        .../server
      </code>
    </td>
    
    <td>
      Nitro only
    </td>
  </tr>
  
  <tr>
    <td>
      Server without Nitro: collab server, AI models, rate limiter, route handlers, websocket listener
    </td>
    
    <td>
      <code>
        createCollabServer
      </code>
      
      , <code>
        createAiModels
      </code>
      
      , <code>
        createRateLimiter
      </code>
      
       from <code>
        .../server
      </code>
      
      ; <code>
        chatPost
      </code>
      
      , <code>
        usersGet
      </code>
      
      , … and their body schemas from <code>
        .../server/handlers
      </code>
      
      ; <code>
        listenCollab
      </code>
      
       from <code>
        .../server/node
      </code>
    </td>
    
    <td>
      any Node process
    </td>
  </tr>
  
  <tr>
    <td>
      Store documents as JSON files
    </td>
    
    <td>
      <code>
        createJsonAdapter({ dir, authenticate?, authorize?, users? })
      </code>
      
       (an <code>
        EditorPorts
      </code>
      
       bundle) from <code>
        @skaile/forge-editor/adapters/json
      </code>
    </td>
    
    <td>
      Node
    </td>
  </tr>
  
  <tr>
    <td>
      Store documents in SQLite via drizzle (optional peer <code>
        drizzle-orm
      </code>
      
      )
    </td>
    
    <td>
      <code>
        bootstrapEditorTables(db)
      </code>
      
      , <code>
        createDrizzleAdapter({ db, tables: editorTables() })
      </code>
      
       from <code>
        @skaile/forge-editor/adapters/drizzle
      </code>
    </td>
    
    <td>
      Node
    </td>
  </tr>
  
  <tr>
    <td>
      Edit a host's Markdown files
    </td>
    
    <td>
      <code>
        createForgeAdapter({ content, state, schema, authenticate, … })
      </code>
      
       from <code>
        @skaile/forge-editor/adapters/forge
      </code>
    </td>
    
    <td>
      Node
    </td>
  </tr>
  
  <tr>
    <td>
      Mount the editor backend on Nitro (no Nuxt module)
    </td>
    
    <td>
      <code>
        installEditorServer(nitroApp, { ports, collab: {} | false, ai?, rateLimit? })
      </code>
      
       from <code>
        @skaile/forge-editor/server/nitro
      </code>
      
       (comments: <code>
        ports.comments
      </code>
      
      ), called from one Nitro plugin; needs <code>
        experimental: { websocket: true }
      </code>
      
       for <code>
        collab
      </code>
      
      ; peer <code>
        h3
      </code>
    </td>
    
    <td>
      Nitro only
    </td>
  </tr>
  
  <tr>
    <td>
      Bind an editor surface to a document
    </td>
    
    <td>
      <code>
        useEditorDocument(id, { backend?, collaboration?: boolean | { token? }, user?, canComment? })
      </code>
      
       → Vue: <code>
        { modelValue, ready, dirty, save, reload, error, collaboration, comments, editor, bind, dispose }
      </code>
      
       refs from <code>
        @skaile/forge-editor/adapters/vue
      </code>
      
      ; React: the same as plain values plus <code>
        onChange
      </code>
      
       from <code>
        @skaile/forge-editor/adapters/react
      </code>
      
      ; backend defaults to the editor context's (needs <code>
        createHttpBackend()
      </code>
      
       for collaboration and comments)
    </td>
    
    <td>
      browser
    </td>
  </tr>
  
  <tr>
    <td>
      Comment threads that survive edits
    </td>
    
    <td>
      <code>
        captureAnchor
      </code>
      
      /<code>
        resolveAnchor
      </code>
      
      /<code>
        mapAnchor
      </code>
      
       from <code>
        .../anchors
      </code>
      
      ; <code>
        createJsonCommentStore({ file })
      </code>
      
       from <code>
        .../comments/json
      </code>
      
      ; <code>
        createDrizzleCommentStore({ db, tables: commentTables() })
      </code>
      
       from <code>
        .../comments/drizzle
      </code>
      
      ; <code>
        handleCommentsRequest(store, { method, documentId, body })
      </code>
      
       from <code>
        .../comments/server
      </code>
      
      ; the browser side is <code>
        backend.comments(documentId, …)
      </code>
      
       of <code>
        createHttpBackend()
      </code>
      
       from <code>
        .../adapters/http
      </code>
    </td>
    
    <td>
      <code>
        anchors
      </code>
      
      : browser (no UI framework); the others: Node
    </td>
  </tr>
  
  <tr>
    <td>
      Nuxt module (config key <code>
        tiptapEditor
      </code>
      
      )
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/nuxt
      </code>
      
       in <code>
        modules
      </code>
    </td>
    
    <td>
      build
    </td>
  </tr>
  
  <tr>
    <td>
      One config for module, server and client
    </td>
    
    <td>
      <code>
        defineEditorConfig(input)
      </code>
      
      , <code>
        serverConfig(config)
      </code>
      
      , <code>
        publicConfig(config)
      </code>
      
       from <code>
        .../config
      </code>
      
       (defaults once; <code>
        installEditorServer(nitroApp, { ports, ...serverConfig(config) })
      </code>
      
      , <code>
        createEditor({ ...publicConfig(config) })
      </code>
      
      ; the Nuxt module options are its input)
    </td>
    
    <td>
      anywhere
    </td>
  </tr>
  
  <tr>
    <td>
      CSS
    </td>
    
    <td>
      <code>
        .../styles/core.css
      </code>
      
       (required) plus <code>
        /media.css
      </code>
      
      , <code>
        /mentions.css
      </code>
      
      , <code>
        /tables.css
      </code>
      
      , <code>
        /authors.css
      </code>
      
      , <code>
        /comments.css
      </code>
      
      , <code>
        /transcript.css
      </code>
      
      , <code>
        /composites.css
      </code>
      
      , <code>
        /ai.css
      </code>
      
      , <code>
        /collab.css
      </code>
      
      , <code>
        /block-ui.css
      </code>
      
      , <code>
        /themes.css
      </code>
      
       for the features you use
    </td>
    
    <td>
      browser
    </td>
  </tr>
</tbody>
</table>

Rules that follow from this table:

- Import values from the subpath that owns them. The root entry `@skaile/forge-editor` exports types only (`export type`), so `import { createEditor } from '@skaile/forge-editor'` does not compile; use `@skaile/forge-editor/vue` (Vue) or `@skaile/forge-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: [coreContentFeature(), coreUiFeature(), 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`).

## After the change

Check the [invariants](https://skaile-ai.github.io/forge-editor/ai-agents/invariants) and run the [verification commands](https://skaile-ai.github.io/forge-editor/ai-agents/verify).


# Pitfalls and invariants

> Rules that must stay true when integrating or changing @skaile/forge-editor: CSS order, mandatory context, SSR, mount-time props, bundle isolation, entries.

Check this list before and after every change to an integration. Each bullet is a failure that does not announce itself at compile time.

- **CSS order.** `core.css` after Tailwind and Nuxt UI, feature sheets after it, `themes.css` last, and `@source` so Tailwind sees the library. The exact order per host is in [CSS and UI-provider requirements](https://skaile-ai.github.io/forge-editor/reference/css-and-ui).
- **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`, `commands`, `blockActions`, `blockTypes`, `blockUi`, `coreContent`, `documentId` 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: [Dependency rules](https://skaile-ai.github.io/forge-editor/reference/dependency-rules).
- **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 the whole `dist` of the package (`node_modules/@skaile/forge-editor/dist`; `packages/editor/src` in this repository), never just `react`: the Features' components are in `features/*/react`; icons: `addCollection(lucide)` from `@iconify/react` before rendering; `<Toaster />` for notices. The preset, `metadata`, `abilities`, `extensions` and `commands` 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: [Quick start: React](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-react) and [Advanced editor in React](https://skaile-ai.github.io/forge-editor/guides/advanced-react).
- **Settings keys.** Only keys of `EditorSettings` persist; unknown ones are dropped on read and write.
- **Design tokens.** `@skaile/forge-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 `@skaile/forge-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`, React only from `./adapters/react` (and the framework layers), Nitro (`h3`) only from `./server/nitro`, `drizzle-orm` only from the two drizzle entries; `./adapters` is types only. `./server/nest` and `./adapters/prisma` are reserved and not exported. The Nitro host and the HTTP backend (`createHttpBackend`, which `useEditorDocument` reads documents, collaboration and comments through) 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). Every route authenticates through `ports.identity.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"` (React: `key={id}` and `doc.ready`), bind with `v-bind="doc.bind.value"` (React: `{...doc.bind}`). Runnable reference: `examples/vue-nitro-json` (`bun run proto:vue-nitro-json`, port 3046).


# Verify

> Which checks an agent runs after changing an @skaile/forge-editor integration or the package itself.

The full command list with what each command proves is in [Commands](https://skaile-ai.github.io/forge-editor/reference/commands). Run it 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.

## Rules

- After touching a package entry (a new export, a moved import): run `bun run check:editor-entries`. It builds the editor, makes one production build per fixture and proves the module-graph isolation and the schema snapshot.
- After adding or changing a user-facing string: run `bun run check:editor-i18n`. It fails on a literal in `src` outside `src/i18n` and on a catalog key that is unused or missing in `en`.
- After renaming or documenting a concept: run `bun run check:editor-legacy-names`. It fails on a former name of the block vocabulary (the glossary's `_Avoid_` terms and the removed API names) in the library sources, the app, the examples and the docs; the migration guide's tables, the glossary's `_Avoid_` lines and the changelog may name them.
- After changing `defineEditor`, a feature's `requires` or a composition: run `bun run check:editor-composition`.
- After any type-level change: run `bun run typecheck:editor`, and the typecheck of the consumer you touched (`bun run --cwd examples/vue-simple typecheck`, `examples/react-simple`, `examples/react-advanced`, or `bun run typecheck` for the Nuxt demo app).
- After adding a feature: add a fixture folder `packages/editor/checks/fixtures/<name>/` and one `FIXTURES` entry in `packages/editor/checks/entries.ts`; see [Commands](https://skaile-ai.github.io/forge-editor/reference/commands) and [Dependency rules](https://skaile-ai.github.io/forge-editor/reference/dependency-rules).
- After editing these docs or a source file they quote: run `bun run check:docs-snippets` (`bun run docs:snippets` rewrites stale blocks).


# Glossary

> Terms used across the documentation: editor composition, document, block, source, AI and panel vocabulary.

These terms name the concepts used in the documentation. `_Avoid_` lists words that mean something else here.

> **Migration note.** The documentation, the library and its English labels use this vocabulary. Persisted data written under older names loads through a migration and is never written back under them (see the Persisted names section of the migration guide). The `::: <Block type id>` fences did not change.

## Editor composition

**Feature**:<br />


A named contribution to an editor (blocks, toolbar entries, menus, settings, AI knowledge) that a Preset lists.<br />

*Avoid*: plugin, extension (an extension is a TipTap building block a Feature may contribute)

**Integration**:<br />


A Feature that exists only to connect two or more other Features (e.g. Typed blocks with AI, transcripts with AI).<br />

*Avoid*: bridge, glue feature

**Preset**:<br />


A validated, ordered list of Features that defines one kind of editor. Say Editor preset where a Model preset could be meant.<br />

*Avoid*: config, editor definition

**Surface**:<br />


The framework-specific place (Vue or React) where a Preset is mounted and edited.<br />

*Avoid*: editor component, view

**Surface session**:<br />


One mount of a Preset on a Surface, from mount to unmount; Feature setups are active exactly while it lives.<br />

*Avoid*: editor instance, mount

**UI binding**:<br />


The set of framework components a Feature needs on one Surface (overlays, settings tabs, node views).<br />

*Avoid*: adapter layer, renderer set

**Editor library**:<br />


The `@skaile/forge-editor` package: Features, Presets, Surfaces and the server ports, usable by any host.<br />

*Avoid*: the editor (ambiguous with a Surface), core

**Reference app**:<br />


The Nuxt app in this repo that hosts the Editor library and shows one complete setup.<br />

*Avoid*: the app, demo

**Host**:<br />


The application that mounts a Preset and supplies backend, UI kit, Block types and Host blocks.<br />

*Avoid*: client, consumer

## Document

**Document**:<br />


The stored, editable unit a user opens, names and moves; it holds Blocks but is not itself a Block.<br />

*Avoid*: page, file

**Block**:<br />


An independently addressable unit of a Document's content. A Block is either a Simple block or a Container block.<br />

*Avoid*: node (code name only), Baustein (legacy UI label for Typed block)

**Simple block**:<br />


A Block that holds no other Blocks, such as a paragraph, heading, list, quote, code block or media. The items of a list are part of the list, not Blocks of their own; block actions and drag act on the list. Simple is a classification of structure, not a Block type.<br />

*Avoid*: leaf, text block, hierarchical block (retired)

**Container block**:<br />


A Block that can hold other Blocks, each addressable, movable and convertible on its own. A Container block with no children yet stays a Container block. Container is a classification of structure, not a Block type; it maps to the container capability (`editorBlockContainer`).<br />

*Avoid*: group, wrapper, hierarchical block (retired)

**Typed block**:<br />


A Container block with a Block type: a title, description and tags followed by a body, with the properties and capabilities its Block type defines.<br />

*Avoid*: composite block (code name `composite`), Baustein (legacy UI label), section, card

**Host block**:<br />


A Block contributed by the Host rather than by the Editor library.<br />

*Avoid*: custom node

**Block type**:<br />


The domain type of a Typed block (e.g. Folder, Document, Task, Note, Recording, Rendition): its exact kind. It defines the block's Property definitions, its Accepted children, its Source media types and its AI brief; it is not a structural classification such as simple or container.<br />

*Avoid*: Baustein kind (legacy UI label), composite kind, node type, block feature (Feature is a composition term)

**Block capabilities**:<br />


What a Block supports: being a container, holding Source media, holding Derived blocks, holding Block references, carrying a Bibliographic record, carrying typed properties. The Block's structural role sets the base; its Block type adds or narrows capabilities. A capability is support, not content: a block that may hold a source need not hold one. Comments are not a capability: they attach to text, not to a Block.<br />

*Avoid*: block features, abilities

**Block actions**:<br />


The operations a user can run on one Block: standard actions every Block has (duplicate, delete, move, convert), actions a capability brings (transcribe a Source, derive a Rendition, cite a Bibliographic record) and actions a Block type brings (fill with AI). An action is offered only where the Block has the capabilities it needs and its place in the Document has the Ability it needs; one Ability can gate many actions.<br />

*Avoid*: commands (code name for the keyboard-level API), block menu (the rendering)

**Ability**:<br />


What may be done at one place in a Document, decided by the Blocks around it: each Block grants or revokes abilities for what it holds (no headings inside a code block, no text editing inside media), and the Host sets the starting set for a Surface session. Abilities gate what the editor offers there: toolbar and `/` entries, shortcuts and Markdown shortcuts, suggestions, AI help and Block actions. They decide what is offered, not what may be written: pasted, dropped and collaborators' edits are not checked, and they know nothing of users beyond the starting set the Host chooses. A capability says what a Block is, an Ability what may be done at a place, an action what the user runs.<br />

*Avoid*: permission, right, role, capability

**Block properties**:<br />


The values that describe a Block, e.g. title, status or language. A property is a concrete value, not the definition of what may be set.<br />

*Avoid*: attributes, metadata, fields

**Property definition**:<br />


The declaration of one property a Block may carry: key, label and value type (text, date, select, reference, bibliography, ...). One mechanism for every Block; Block types declare them, and today only Typed blocks store property values.<br />

*Avoid*: meta field, schema field

**Block contents**:<br />


The items a Block actually holds: nested Blocks and, where its capabilities allow, Source media, Derived blocks and references. Contents are what is present; capabilities are what is supported.<br />

*Avoid*: children (alone), payload

**Accepted children**:<br />


The Block types a Block type lets you nest inside it: a list of types, or all. The rule covers only Typed blocks inside Typed blocks, not paragraphs, lists or other Blocks. Without a setting, Folder and Document accept all and every other type accepts none. The Document tree and the editor apply the same rule to new moves; existing nesting is left alone.<br />

*Avoid*: allowed content, drop targets

**Document block type**:<br />


The built-in Block type, Document, for a document-like unit inside a structure of Typed blocks, such as an imported file; it is not the Document itself. It is an ordinary Block type: what it accepts, whether it can be exported and which imported files become one are settings of its capabilities, never a rule on its name.<br />

*Avoid*: document (alone, for the type)

**Structure mode**:<br />


The user's choice of how Documents are structured: Structure mode nests Typed blocks, Flat mode uses Markdown headings.<br />

*Avoid*: composite mode, heading mode

## Sources, derivation and references

**Source media**:<br />


The original image, audio, video or file kept as a media Block inside the Block that holds it.<br />

*Avoid*: attachment, asset, source (alone, when the holding block is meant)

**Source**:<br />


The capability of holding Source media. A Block type declares which media types its Source may be.<br />

*Avoid*: source block, source-bearing block, recording block (that is one Block type with the Source capability)

**Derivation**:<br />


The record a Derived block keeps of where it came from: the original Block, the method (transcription, OCR, AI description, ...), the model and the time. The link to the original stays with the Derived block; the original can list its Derived blocks.<br />

*Avoid*: provenance (the UI label), lineage, history

**Derived block**:<br />


A Block that carries a Derivation, whatever its Block type.<br />

*Avoid*: rendition (that is one Block type), child, copy

**Rendition**:<br />


The Block type for a readable version of a Source: transcript, full text or description. Shown as Readable rendition in the UI.<br />

*Avoid*: Lesefassung (legacy UI label), transcript (that is one method)

**Block reference**:<br />


A property value that points to another Block by its block ID; a Property definition may limit the target Block types.<br />

*Avoid*: link, pointer, relation

**Bibliographic record**:<br />


A CSL-JSON description of a publication that a Block carries; the Block's ID and title are not part of it.<br />

*Avoid*: citation, bib, metadata

**Basket**:<br />


One named colour group, defined by the Host, that a Typed block can be put into; not a saved filter.<br />

*Avoid*: Korb (legacy UI label), colour label, tag

## AI

**Model preset**:<br />


A server-defined endpoint and model configuration, identified by preset ID; its key stays on the server.<br />

*Avoid*: preset (alone, that is an Editor preset), server preset

**Model profile**:<br />


The client-visible model record (ID, label, endpoint, model) that comes from a Model preset or from the user; it never carries a key.<br />

*Avoid*: model config, connection

**Model reference**:<br />


The selector sent with an AI request: a Model preset ID, or an endpoint with model and its own key.<br />

*Avoid*: ref, model id

**Model role**:<br />


The category of AI work (complete, rewrite, generate) that settings assign a Model profile to.<br />

*Avoid*: slot (code name), task type

**AI brief**:<br />


What a Block type tells the model: its purpose, instructions and the AI content template.<br />

*Avoid*: prompt, kind ai

**AI content template**:<br />


The Markdown target text with placeholders that a Block type supplies when AI fills a Typed block of that type.<br />

*Avoid*: skeleton (code name), Vorlage (legacy UI label)

**Proposed change**:<br />


One change the model proposes to a Document (replace, blocks, insert or delete); it can contain several Review hunks.<br />

*Avoid*: edit, operation, diff

**Review hunk**:<br />


One reviewable difference of a Proposed change that the user accepts or rejects.<br />

*Avoid*: chunk, suggestion

**Review**:<br />


One round of deciding the Review hunks of a set of Proposed changes; it ends once every hunk is decided.<br />

*Avoid*: AI review (unless contrasted with a human review), approval

## Panels and menus

**Block inspector**:<br />


The panel that shows either the Document facts or the Typed block under the caret, and edits its summary, properties and tags.<br />

*Avoid*: details panel, settings panel

**Document facts**:<br />


The Document section of the Block inspector: the Document's own title, properties and tags.<br />

*Avoid*: document settings, document meta

**Selection menu**:<br />


The AI menu that runs a task on the selected text or at the caret and lets the user apply or discard the result. Labelled AI selection menu in the UI.<br />

*Avoid*: bubble menu (the rendering), AI popup

**Document tree**:<br />


The navigation panel listing folders, Documents and each Document's Typed blocks; it moves, renames and reveals them, filters by type and title, and shows why a drop is refused.<br />

*Avoid*: sidebar, file browser, outline (the Block outline is the part for one Document)

**Block outline**:<br />


The per-Document part of the Document tree: the hierarchy of a Document's Typed blocks, not every paragraph.<br />

*Avoid*: outline (alone), table of contents

**Comments margin**:<br />


The column beside the editor that shows each comment thread next to the text it comments on; the active thread sits exactly at its text and the other threads move out of its way. Resolved threads stay hidden until the user shows them.<br />

*Avoid*: comment sidebar, gutter

**Orphaned thread**:<br />


A comment thread whose commented text was deleted; the margin shows it greyed out at the place where the text was. When undo brings the text back, the thread is attached to it again.<br />

*Avoid*: dangling comment, lost comment

## Collaboration and appearance

**Author identity**:<br />


The writing user's ID, name and colour, used for remote carets, author marks and comments.<br />

*Avoid*: user, account

**Collaboration session**:<br />


The live connection of one Surface session to a Document's shared state.<br />

*Avoid*: room, socket

**Theme**:<br />


The appearance a user picks for the editor; Default appearance is the choice that applies no Theme.<br />

*Avoid*: Darstellung (legacy UI label), skin, style

**Design tokens**:<br />


The named CSS variables (`--sk-*`) the Editor library styles with; the Theme bridge maps them to the Host's UI variables.<br />

*Avoid*: CSS vars, palette

**UI kit**:<br />


The set of widgets (buttons, inputs, overlays) a Host supplies to the Editor library's chrome.<br />

*Avoid*: component library, design system


# Installation

> Requirements, peer dependencies and the npm install command for @skaile/forge-editor.

## Prerequisites

- Node ≥ 22 and [Bun](https://bun.sh) (the repository is a Bun workspace: `packages/*`, `examples/*`).
- A Vite- or Nuxt-based app (`@vitejs/plugin-vue` / `@vitejs/plugin-react`, or Nuxt). The published package is a **built ESM package**: every `exports` subpath resolves to `dist/**/*.js` with `.d.ts` (Vue SFCs are compiled, React `.tsx` is compiled to JSX-runtime JS), the CSS sheets are copied, and the source maps embed the sources (`src` itself is not published). Output is one module per source file, so entries stay tree-shakeable.
- Required peer dependencies (install them in the consuming app so the host and the library share one instance of each): `@tiptap/core`, `@tiptap/pm`, `yjs`, `@hocuspocus/provider`. Yjs and the provider are required peers because shared prop types in the `.d.ts` reference them; a simple-editor bundle does not contain their implementation (proven in the [bundle isolation proof](https://skaile-ai.github.io/forge-editor/reference/dependency-rules#bundle-isolation-proof)). Per layer (all optional peers): **Vue** `vue`, `@nuxt/ui`, `@tiptap/vue-3`; **React** `react`, `react-dom`, `@tiptap/react`, `@iconify/react`; **code surface** (`/code`) `@codemirror/state`, `@codemirror/view`, `@codemirror/language`, `@codemirror/commands`, `@codemirror/search`, `@lezer/highlight`, plus the `@codemirror/lang-*` packs you register (the package ships none).
- Tailwind CSS 4 (`tailwindcss`) for the Nuxt UI theme (Vue) or the shadcn classes (React), and the icon collection `@iconify-json/lucide`. React hosts also need `tw-animate-css` (enter/exit animations of the dialog, dropdown and tooltip).

## Install

From npmjs (public, no token and no `.npmrc` needed):

```sh
npm install @skaile/forge-editor      # or: bun add @skaile/forge-editor / pnpm add @skaile/forge-editor
```

Inside this repository the package is a workspace member, so consumers there declare `"@skaile/forge-editor": "workspace:*"`.

Next: set up [Nuxt](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-nuxt), [plain Vue](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-vue) or [React](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-react).


# Introduction

> What @skaile/forge-editor is: a Vue and React block editor library on TipTap v3, assembled from features.

## What it is

A Vue and React editor library on TipTap v3. Editors are assembled from **features**: the *simple* editor is the core features alone (formatting, headings, lists, quotes, code, undo/redo) and needs no backend, no Yjs and no feature code; the *advanced* editor composes every feature (media, mentions, transcripts, Typed blocks, authors, comments, AI, collaboration, block UI, site-wide Obsidian themes and their integrations) on both surfaces. The framework-free `./core` holds the feature model, and every feature's logic is framework-free too (`./<feature>`): a feature is built from a typed **UI binding** (`<x>FeatureCore(ui)`) that the Vue layer (`./<feature>/vue`, Nuxt UI chrome) and the React layer (`./<feature>/react`, shadcn/ui on Radix and Tailwind) fill with their components, node views and notice seam. Toolbar, settings panel and modal, Block outline, AI sidebar, Comments margin, Typed blocks table and Block inspector, and the Document tree are components you place anywhere beside an editor; both layers ship the simple editor (`./vue/simple`, `./react/simple`) and the advanced editor (`./vue/advanced`, `./react/advanced`).

A reference Nuxt app and the `@skaile/forge-editor` library it is built on: a block editor for structured documents (transcripts, minutes, reports) with AI assistance and collaboration, offered on a Vue and a React surface.

## How the pieces fit

- An editor is a **list of features** (`EditorFeature`) validated by `defineEditor` into an immutable `EditorPreset` and mounted by `EditorSurface`. `composeEditor({ content: 'basic' | 'rich', interaction: 'minimal' | 'full' | [], ai: boolean, backend?, add?, remove? })` builds one from three dimensions; a feature whose `requires` or backend capability is missing is dropped and listed in `omitted`. Prebuilt are the `SimpleEditor` and `AdvancedEditor` components (Vue and React), `advancedEditor()` (everything plus the three integrations) and the framework-free `simpleEditor()` (`core-content` + `core-ui`, no backend, no ⌘K palette) from `/presets/compose`. See [Feature composition](https://skaile-ai.github.io/forge-editor/guides/composition).
- Toolbar, settings panel and modal, Block outline, AI sidebar and Document tree are **separate components** you place beside an editor and give the editor (`:editor` from `ready`). The toolbar and settings components find the editor's preset through it; there is no `preset` prop.
- Every advanced feature has three entries: framework-free `/<x>` (logic, models and the UI binding contract), `/<x>/vue` and `/<x>/react`. Layers: framework-free `/core`, Vue (`/vue`, Nuxt UI) and React (`/react`, shadcn/ui). Importing an entry registers nothing globally, and the root entry `@skaile/forge-editor` is **type-only**. All entries are listed in the [exports reference](https://skaile-ai.github.io/forge-editor/reference/exports).
- The package is published as built ESM with `.d.ts` (the source maps embed the sources; `src` is not published). Consume it through Vite (`@vitejs/plugin-vue` with `@nuxt/ui/vite`, or `@vitejs/plugin-react` with `@tailwindcss/vite`) or Nuxt.
- 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 and `useEditorI18n()` in components (see [Language](https://skaile-ai.github.io/forge-editor/guides/language)). Server error messages are German developer messages; docs and identifiers are English.

The words used on these pages (Feature, Preset, Surface, Block, …) are defined in the [glossary](https://skaile-ai.github.io/forge-editor/getting-started/glossary).

## Where to start

<card-group>
<card icon="i-lucide-download" title="Install" to="https://skaile-ai.github.io/forge-editor/getting-started/installation">

Requirements, peer dependencies and the npm command.

</card>

<card icon="i-lucide-rocket" title="Quick start" to="https://skaile-ai.github.io/forge-editor/getting-started/quick-start-nuxt">

A working editor in Nuxt, plain Vue or React.

</card>

<card icon="i-lucide-graduation-cap" title="Tutorial" to="https://skaile-ai.github.io/forge-editor/tutorial/overview">

Build a meeting-notes editor step by step, including an own block.

</card>

<card icon="i-lucide-list" title="Exports reference" to="https://skaile-ai.github.io/forge-editor/reference/exports">

Every entry point of the package and what it exports.

</card>
</card-group>


# Quick start: Nuxt

> Register the Nuxt module, provide EditorPorts and mount the simple and the advanced editor in a Nuxt app.

Install the peers next to the package (`vue`, `@nuxt/ui`, `@tiptap/core`, `@tiptap/pm`, `@tiptap/vue-3`, `yjs`, `@hocuspocus/provider`, `tailwindcss`, `@iconify-json/lucide`; see [Installation](https://skaile-ai.github.io/forge-editor/getting-started/installation)), then follow the steps. Inside the repository declare `"@skaile/forge-editor": "workspace:*"` instead of the npm version.

<steps level="2">

## Register the module after `@nuxt/ui`

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false, // TipTap renders on the client only
  modules: ['@nuxt/ui', '@skaile/forge-editor/nuxt'],
  css: ['~/assets/main.css'],
})
```

The module patches Nuxt UI's generated `ui.css` template and throws if that template is missing, so `@nuxt/ui` must come first. It 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(), backend: createHttpBackend({ fetch: $fetch, probe: true }) })`; the module has no `kit` option, the Vue binding is Nuxt UI) and scans the Nitro routes. It registers no component or composable.

Module options live under the config key `tiptapEditor`:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  ssr: false, // TipTap renders on the client only
  modules: ['@nuxt/ui', '@skaile/forge-editor/nuxt'],
  tiptapEditor: { ai: { /* optional; presets (Model presets), roles (the default Model preset per Model role), rateLimit, transcription: see AI configuration */ }, collab: { authenticateUpgrade: false /* true: refuse an unauthenticated /collab upgrade with HTTP 401 (cookie hosts only) */ } },
})
```

The `ai` options are described in [AI configuration](https://skaile-ai.github.io/forge-editor/guides/ai-configuration).

## Add the stylesheet

```css
/* app/assets/main.css */
@import "tailwindcss";
@import "@nuxt/ui";
```

## Mount the simple editor

Wrap the app in `<UApp>` (`app/app.vue`: `<UApp><NuxtPage /></UApp>`) and mount an editor on a page (the simple editor needs no backend):

```vue
<script setup lang="ts">
import { SimpleEditor } from '@skaile/forge-editor/vue/simple'
import { ref } from 'vue'
const content = ref()
</script>

<template>
  <SimpleEditor v-model="content" />
</template>
```

## Register `EditorPorts`

The module's API routes call the host's `EditorPorts` (identity first, then one port per capability: `documents`, `collabState`, `directory`, `assets`, `settings`, `themes`, `models`, `comments`). Hand them to the module with `provideEditorServer({ ports })` in a Nitro plugin; the module installs the editor server at the first request, and without provided ports the client logs „Einstellungen konnten nicht geladen werden“ and every route answers 500. A route whose port you leave out answers 501. These minimal ports keep everything in memory and let any visitor in (replace `authenticate` and the storage with yours; [Server ports](https://skaile-ai.github.io/forge-editor/guides/editor-ports) lists every member, the routes that call it and the required results):

```ts [docs/snippets/minimal-ports.ts]
// server/plugins/editor-adapter.ts
import type { JSONContent } from '@tiptap/core'
import { type AssetStore } from '@skaile/forge-editor/server'
import { provideEditorServer } from '@skaile/forge-editor/server/nitro'

export default defineNitroPlugin(() => {
  const contents = new Map<string, JSONContent>()
  const states = new Map<string, Uint8Array>()
  const assets = new Map<string, Parameters<AssetStore['storeAsset']>[1]>()
  provideEditorServer({
    ports: {
      // `null` = 401 on API routes; on /collab the socket is closed with 4401 (HTTP 401 at the upgrade with `collab.authenticateUpgrade`)
      identity: { authenticate: async () => ({ id: 'demo', username: 'demo' }) },
      documents: {
        loadContent: async id => contents.get(id) ?? null,
        storeContent: async (id, content) => { contents.set(id, content) },
        listContents: async () => [...contents].map(([id, content]) => ({ id, content })),
      },
      collabState: {
        loadState: async id => states.get(id) ?? null,
        storeState: async (id, state) => { states.set(id, state) },
        removeState: async (id) => { states.delete(id) },
      },
      directory: { listUsers: async () => [] },
      assets: {
        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 `settings`: settings stay in the browser (GET answers 204).
      // Omit `themes`: the themes routes answer 501 and the standard look stays.
    },
  })
})
```

## Mount the advanced 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 '@skaile/forge-editor/vue/advanced'
import { EditorToolbar } from '@skaile/forge-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 }"` and connect the provider to `/collab/:id` ([Collaboration](https://skaile-ai.github.io/forge-editor/guides/collaboration)).

`AdvancedEditor` pulls in every feature. For a smaller bundle use `SimpleEditor` or compose your own list ([Feature composition](https://skaile-ai.github.io/forge-editor/guides/composition)). For the simple editor in plain Vue (no Nuxt, no backend) follow the [plain Vue quick start](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-vue).

</steps>

## Next steps

The advanced editor, every adapter method, collaboration and AI are covered in the guides: [Server ports](https://skaile-ai.github.io/forge-editor/guides/editor-ports), [Routes and authentication](https://skaile-ai.github.io/forge-editor/guides/routes-and-auth), [Collaboration](https://skaile-ai.github.io/forge-editor/guides/collaboration) and [AI configuration](https://skaile-ai.github.io/forge-editor/guides/ai-configuration). The [tutorial](https://skaile-ai.github.io/forge-editor/tutorial/overview) builds an editor from the simple editor up.


# Quick start: React

> Set up the simple editor in a Vite and React app: peers, Tailwind and shadcn tokens, EditorContextProvider, EditorSurface and SimpleEditor.

The React layer (`@skaile/forge-editor/react`, shadcn/ui on Radix and Tailwind 4) renders the same framework-free core as the Vue layer: the simple editor, `EditorToolbar`, the settings panel and modal, and the `@`, `#` and `/` suggestion popups. It uses no Vue, Nuxt UI or Nuxt module. The runnable reference is [`examples/react-simple`](https://github.com/skaile-ai/forge-editor/tree/main/examples/react-simple); start it with `bun run --cwd examples/react-simple dev` (port 3041). It has the same sample picker, read-only toggle, host `/datum` command and JSON and Markdown panes as the Vue example, plus `@` mentions.

**More than the simple editor:** every advanced feature has a React binding as well (`./<x>/react`: media, transcript, Typed blocks, authors, comments, AI, collaboration, block UI, themes, the Block outline and the Document tree), and `composeEditor(options)` / `advancedEditor()` / `AdvancedEditor` from `@skaile/forge-editor/react/advanced` compose them all; see [Advanced editor in React](https://skaile-ai.github.io/forge-editor/guides/advanced-react). `coreContentFeature()`, `coreUiFeature()`, `mentionsFeature()` and the three integrations have no components and work in both layers; a React preset is `defineEditor({ features })` over features from `./<x>/react` and such component-free features.

## Setup

- `package.json` dependencies: `@skaile/forge-editor` (`workspace:*` inside this repository), `react`, `react-dom`, `@tiptap/core`, `@tiptap/pm`, `@tiptap/react`, `@iconify/react`, `@iconify-json/lucide`, `tailwindcss`, `tw-animate-css`, `yjs`, `@hocuspocus/provider` (the last two as in the [README](https://skaile-ai.github.io/forge-editor/getting-started/installation): source-shipped shared types reference them); dev dependencies `vite`, `@tailwindcss/vite`, `@vitejs/plugin-react`, `typescript`, `@types/react`, `@types/react-dom`. Use the exact version ranges of the example's [`package.json`](https://github.com/skaile-ai/forge-editor/blob/main/examples/react-simple/package.json).
- `index.html` with `<div id="app"></div>` and `<script type="module" src="/src/main.tsx"></script>`.
- `tsconfig.json` with `jsx: "react-jsx"`, `moduleResolution: "Bundler"`, `strict` and `include: ["src"]` (see the example's [`tsconfig.json`](https://github.com/skaile-ai/forge-editor/blob/main/examples/react-simple/tsconfig.json)).

`vite.config.ts`:

```ts
import tailwindcss from '@tailwindcss/vite'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({ plugins: [react(), tailwindcss()] })
```

`index.css` — Tailwind, the animation utilities the shadcn dialog, dropdown and tooltip use, the library sheets, and a `@source` so Tailwind generates the utility classes the library's React code uses (Tailwind skips `node_modules` unless told otherwise):

```css
@import "tailwindcss";
@import "tw-animate-css";
/* ui-vars.css maps the shadcn tokens (--primary, --background, …) to the --ui-* variables the feature sheets read. */
@import "@skaile/forge-editor/react/styles/ui-vars.css";
@import "@skaile/forge-editor/styles/core.css";
@import "@skaile/forge-editor/styles/mentions.css"; /* the sheet of each feature you use */

@source "../node_modules/@skaile/forge-editor/dist"; /* relative path from this CSS file to the installed package's dist */

/* The shadcn theme block follows: @custom-variant dark, @theme inline, :root and .dark tokens, @layer base.
   `bunx shadcn@latest init` generates it; examples/react-simple/src/index.css has a complete copy. */
```

The `@source` covers the whole `dist`, not just `dist/react`: the Features' own React components (`features/*/react`, e.g. the image studio dialog), the surfaces (`document`, `markdown`, `code`), the outline and the tree sit beside it, and a host that scans only `dist/react` renders them without their layout classes. In this repository the examples point at the sibling's `src` (`../../../packages/editor/src`) instead.

`main.tsx` — icons and the editor context. The toolbar and menus render `i-lucide-*` names through `@iconify/react`; preloading the collection means the page makes no request to the Iconify API. The host owns the context from `createEditorContext()` (`@skaile/forge-editor/core`) and every React component of the library reads it from `EditorContextProvider`; the provider never disposes it, call `context.dispose()` yourself when the context outlives your app. `createEditorContext` takes the same options as the Vue `createEditor` (the default backend syncs the settings with `GET`/`PUT /api/editor/settings`; `{ backend: createMemoryBackend() }` keeps them local, `{ backend: createHttpBackend({ fetch }) }` brings your own HTTP client):

```tsx
import lucide from '@iconify-json/lucide/icons.json'
import { addCollection } from '@iconify/react'
import { createEditorContext } from '@skaile/forge-editor/core'
import { EditorContextProvider } from '@skaile/forge-editor/react'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { App } from './App'
import './index.css'

addCollection(lucide)
const context = createEditorContext()

createRoot(document.getElementById('app')!).render(
  <StrictMode>
    <EditorContextProvider context={context}>
      <App />
    </EditorContextProvider>
  </StrictMode>,
)
```

Notices of app-level models (for example the AI model profiles) go through the context's notifier. The simple editor raises none, so `createEditorContext()` is enough here; hosts of features pass `createEditorContext({ notify: reactNotifier })` and mount sonner's `Toaster` once (both from `@skaile/forge-editor/react`, see [Advanced editor in React](https://skaile-ai.github.io/forge-editor/guides/advanced-react)).

## Mount the editor

`EditorSurface` takes a preset; `EditorToolbar` is a sibling that works on the editor you pass it (from `onReady`), never on a global active editor. The toolbar renders the groups of the preset registered for that editor; without an editor it renders none.

```tsx
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { mentionsFeature } from '@skaile/forge-editor/mentions'
import { EditorSurface, EditorToolbar } from '@skaile/forge-editor/react'
import type { Editor, JSONContent } from '@tiptap/core'
import { useState } from 'react'

// Module constants: the preset, `metadata`, `abilities`, `extensions` and `commands` are read once at mount.
const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), mentionsFeature()] })
const metadata = { mentions: [{ id: 'u1', label: 'Ada Lovelace' }, { id: 'u2', label: 'Alan Turing' }] }

export function App() {
  const [editor, setEditor] = useState<Editor | null>(null)
  const [content, setContent] = useState<JSONContent>({ type: 'doc', content: [{ type: 'paragraph' }] })

  return (
    <>
      <EditorToolbar editor={editor ?? undefined} />
      <EditorSurface
        preset={preset}
        metadata={metadata}
        value={content}
        onChange={setContent}
        onReady={setEditor}
        onContentError={error => console.warn(error.message)}
      />
    </>
  )
}
```

Typing `@Ad` opens the mention popup with the `mentions` list. A list the host does not supply (here `hashtags`) comes from `/api/editor/tags` through the context's HTTP client, and only once the `#` popup is used. The simple editor's `/` menu lists the core blocks; pass `commands={defaults => [...defaults, ...]}` (a module function) to add own entries.

## The one-liner: `SimpleEditor`

Without own features, `SimpleEditor` from `@skaile/forge-editor/react/simple` builds the preset itself (`core-content` + `core-ui`, plus the features in its `add` prop) on an `EditorSurface`. The toolbar takes its groups from the editor it is given; the ref exposes `{ editor, openSettings, preset }`:

```tsx
import { EditorToolbar } from '@skaile/forge-editor/react'
import { SimpleEditor } from '@skaile/forge-editor/react/simple'
import type { Editor } from '@tiptap/core'
import { useState } from 'react'

export function App() {
  const [editor, setEditor] = useState<Editor | null>(null)
  return (
    <>
      <EditorToolbar editor={editor ?? undefined} />
      <SimpleEditor onReady={setEditor} />
    </>
  )
}
```

Try the React example here:

<demo-frame name="react-simple">



</demo-frame>

## Next steps

The [tutorial](https://skaile-ai.github.io/forge-editor/tutorial/react-surface) shows the same editor on the React surface. The advanced editor on React is covered in [Advanced editor in React](https://skaile-ai.github.io/forge-editor/guides/advanced-react); every entry is listed in the [exports reference](https://skaile-ai.github.io/forge-editor/reference/exports).


# Quick start: plain Vue

> Set up the simple editor in a Vite and Vue app: peers, Nuxt UI plugin, CSS and a mounted SimpleEditor with toolbar and outline.

`SimpleEditor` is the two core features alone (`core-content` and `core-ui`): bold/italic/underline/strike/code/link, headings, lists, quotes, code blocks, horizontal rule, undo/redo. No backend requests, no Yjs, no feature code. The runnable reference is [`examples/vue-simple`](https://github.com/skaile-ai/forge-editor/tree/main/examples/vue-simple); start it with `bun run --cwd examples/vue-simple dev` (port 3040). Its sample picker loads five demo documents — „Start“, „Formatierung“ (marks, lists, quote, code block, rule), „Gliederung“ (three outline levels), „Hinweise“ (the own „Hinweis“ block) and „Ungültig (Block-JSON)“ (advanced JSON, rejected through `contentError`) — beside the toolbar and outline, with the JSON and Markdown of the document next to the editor. The `/hinweis` entry and the callout behind it are an own block added through the `extensions` and `commands` props; the [tutorial](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a) shows how, and how to go further with a full feature.

## Setup

Starting a new app from nothing? The files below plus these three are all that [`examples/vue-simple`](https://github.com/skaile-ai/forge-editor/tree/main/examples/vue-simple) has:

- `package.json` dependencies: `@skaile/forge-editor` (`workspace:*` inside this repository), `vue`, `@nuxt/ui`, `tailwindcss`, `@iconify-json/lucide`, `@tiptap/core`, `@tiptap/pm`, `@tiptap/vue-3`, `yjs`, `@hocuspocus/provider`; dev dependencies `vite`, `@vitejs/plugin-vue`, `typescript`, `vue-tsc`; scripts `dev` (`vite`), `build` (`vite build`), `typecheck` (`vue-tsc --noEmit -p tsconfig.json`). Use the exact version ranges of the example's [`package.json`](https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-simple/package.json).
- `index.html` with `<div id="app"></div>` and `<script type="module" src="/src/main.ts"></script>`.
- `tsconfig.json` with `moduleResolution: "Bundler"`, `types: ["vite/client"]`, `strict`, `verbatimModuleSyntax` and `include: ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]` (see the example's [`tsconfig.json`](https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-simple/tsconfig.json)).

Optional: Nuxt UI resolves `i-lucide-*` icons at build time, but a workspace library lies outside the Vite root it scans, so without the extra config the page fetches the toolbar's icons from the Iconify API at runtime. The example's [`vite.config.ts`](https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-simple/vite.config.ts) collects the library's icon names into `ui({ icon: { clientBundle: { scan: true, icons } } })` to bundle them.

`vite.config.ts` — Nuxt UI's Vite plugin without a router:

```ts
import ui from '@nuxt/ui/vite'
import vue from '@vitejs/plugin-vue'
import { defineConfig } from 'vite'

export default defineConfig({ plugins: [vue(), ui({ router: false })] })
```

`main.ts` — Nuxt UI and the editor context. `createEditor()` (from the Vue layer, `@skaile/forge-editor/vue`) owns the settings of this app and is required by every editor component:

```ts
import ui from '@nuxt/ui/vue-plugin'
import { createEditor } from '@skaile/forge-editor/vue'
import { createApp } from 'vue'
import App from './App.vue'
import './style.css'

createApp(App).use(ui).use(createEditor()).mount('#app')
```

`createEditor()` loads and saves the settings per account through its backend: with the default backend (`createFetchBackend`, the HTTP routes of the Nuxt module over the platform `fetch`) the first `useEditorSettings()` asks `GET /api/editor/settings` and every change is sent with `PUT`. They are local-only (`localStorage`, `tiptap-editor:settings`) when the backend offers no `settings` capability: `createEditor({ backend: createMemoryBackend() })`. `createEditor({ backend })` swaps the whole data layer of all features (documents, uploads, mention lookups, settings, themes, AI); `createHttpBackend({ fetch })` (`@skaile/forge-editor/adapters/http`) lets a host hand in its own HTTP client such as Nuxt's `$fetch`. `createEditor({ locale: 'en' })` switches every string the editor renders to English (default `'de'`), `createEditor({ messages: { 'toolbar.bold': 'Strong' } })` overrides single messages; see [Language](https://skaile-ai.github.io/forge-editor/guides/language). Components read `useEditorI18n()` (`{ t, locale }`); the Nuxt module takes the same two options as `tiptapEditor: { locale, messages }`.

`createEditor()` is a thin Vue plugin. The headless core (`@skaile/forge-editor/core`) imports no Vue: `createEditorContext(options)` returns the framework-free context with the same options, whose `settings` is a store (`get()`, `set(value)`, `update(recipe)`, `subscribe(listener)`) and whose `ready` and `synced` are read-only stores. `createEditor()` creates that context, provides it to the app and disposes it on unmount; Vue components read the settings through `useEditorSettings()` (reactive refs) from `@skaile/forge-editor/vue`.

`style.css` — Tailwind, Nuxt UI, then the core CSS, and let Tailwind scan the library's whole `dist` (the Features' `features/*/components` sit beside `vue`; in this repository the examples scan the sibling's `src` instead):

```css
@import "tailwindcss";
@import "@nuxt/ui";
@import "@skaile/forge-editor/styles/core.css";
@source "../node_modules/@skaile/forge-editor/dist"; /* relative path from this CSS file to the installed package's dist */
```

`App.vue` wraps everything in `<UApp>` (overlays, tooltips, toasts).

## Mount the editor

```vue
<script setup lang="ts">
import { ref, shallowRef } from 'vue'
import type { Editor, JSONContent } from '@tiptap/core'
import { SimpleEditor } from '@skaile/forge-editor/vue/simple'
import { EditorToolbar } from '@skaile/forge-editor/vue'
import { EditorOutline } from '@skaile/forge-editor/outline/vue'

const editor = shallowRef<Editor>()
const content = ref<JSONContent>({ type: 'doc', content: [{ type: 'paragraph' }] })
</script>

<template>
  <UApp>
    <EditorToolbar :editor="editor" />
    <SimpleEditor v-model="content" @ready="editor = $event" />
    <EditorOutline :editor="editor" />
  </UApp>
</template>
```

Try it here: type, use the toolbar, switch to read-only and watch the JSON `v-model` and the outline.

<demo-simple-editor>



</demo-simple-editor>

## Next steps

The [tutorial](https://skaile-ai.github.io/forge-editor/tutorial/simple-editor) continues from this editor; the props and events of `SimpleEditor` are covered there. To add features such as mentions, media, tables and block UI, see [Compose features](https://skaile-ai.github.io/forge-editor/tutorial/compose-features).


# Kitchen sink: learning path

> Fifteen pages, basics first: structure, content blocks, JSON and Markdown, block actions and settings, then the building blocks, then the use cases, each with the code that builds it

The kitchen sink is the part of the repository's Nuxt app that teaches the framework by example. Start the app with `bun run dev` (port 3056; it needs `NUXT_SESSION_PASSWORD`, at least 32 characters, in `.env`), open `http://localhost:3056/kitchen-sink` and pick a card. The gallery has three tracks, and this guide has one section per page in the same order:

<table>
<thead>
  <tr>
    <th>
      Track
    </th>
    
    <th>
      Pages
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Basics: what a document is made of, how it is structured, stored and acted on
    </td>
    
    <td>
      <a href="#structure">
        Flat & Structure
      </a>
      
      , <a href="#blocks">
        Content blocks
      </a>
      
      , <a href="#json-and-markdown">
        JSON & Markdown
      </a>
      
      , <a href="#actions">
        Acting on blocks
      </a>
      
      , <a href="#settings">
        Editor settings
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Building blocks: one API of the library, shown on its own
    </td>
    
    <td>
      <a href="#simple">
        Simple
      </a>
      
      , <a href="#advanced">
        Advanced
      </a>
      
      , <a href="#surface">
        Surface
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Use cases: a planned application, built from the framework
    </td>
    
    <td>
      <a href="#minutes">
        Minutes
      </a>
      
      , <a href="#slides">
        Slides
      </a>
      
      , <a href="#databases">
        Databases
      </a>
      
      , <a href="#science">
        Science
      </a>
      
      , <a href="#podcast">
        Podcast
      </a>
      
      , <a href="#pkm">
        PKM
      </a>
      
      , <a href="#epikrise">
        Epikrise
      </a>
    </td>
  </tr>
</tbody>
</table>

Read a page in the browser and the matching section here side by side. Every page is one Vue file, `app/pages/kitchen-sink/<slug>.vue`, and the snippet in each section is that file's `<script setup>`, pulled from the repository by `bun run docs:snippets`.

**What every page has.** A header with the sample select (each page ships tuned sample documents and an empty one), the toolbar, an „editable“ switch, the settings button and the AI sidebar button. Settings open in a popup the page places itself (`settings-ui="external"`, see [Composites and the settings UI](https://skaile-ai.github.io/forge-editor/guides/composites)), the AI sidebar comes in through a slot ([AI](https://skaile-ai.github.io/forge-editor/guides/ai)). The body is the editor and a side panel on the right; the panel differs per page, and where it has nothing page-specific it shows the document as JSON and Markdown. **How it's built** (the code icon in the header) opens a drawer with the page's lessons and its own source text, and **Open in docs** leads to the section below.

**English editor chrome.** The rest of the app is German, the kitchen sink is English. `app/layouts/kitchen-sink.vue` provides a copy of the app's editor context with `locale: 'en'` and `t: createTranslator('en')`, so the toolbar, the `/` menu and `defaultBlockTypes(t)` read English under that layout while settings, backend and notifier stay the app's own ([Language](https://skaile-ai.github.io/forge-editor/guides/language)).

**Server hints.** Add-ons are imported straight into the pages that use them, so their block types, node views and inspector sections work in a plain `bun run dev`. What runs on the server (the render targets of slides, charts and Typst, speech synthesis, review records) depends on the `NUXT_PUBLIC_ADDONS_*` flags of `.env.example`. A page that demonstrates such a capability asks the backend for it (`ctx.backend.render?.targets()`, `ctx.backend.speech`) and shows a `ServerHint` card in its panel, naming the flag, when the server lacks it.

**One editor per page.** Every component placed beside an editor names it: `EditorToolbar :editor`, `AiSidebar :editor`, `CompositeInspector :editor`, `useEditorUi(() => editor)`. The editor registers its chrome (settings routing, sidebar toggle, block actions) under its own Tiptap instance. Content lives in the page as TipTap JSON behind `v-model`, with its own undo history; no document store, no websocket. External content replacement (picking a sample) emits no update event, so the page refreshes the Markdown output itself once the editor took the new content (`loadSample` in `app/editor/kitchen-sink/pane.ts`). Switching pages remounts the editor.

**Read in this order.** The five Basics pages first: Flat and Structure mode, the blocks a document is made of, the document as JSON and Markdown, the actions on its blocks and the settings every editor reads; every other page assumes them. Then the three editor shapes (Simple, Advanced, Surface), then the applications built from them. Epikrise comes last: it is the only page whose state lives on the server, where the review records are kept by block id.

## Structure

Flat mode and Structure mode, shown on one project brief written twice. The mode is the editor setting `blocks.structure` (`'flat'` or `'structured'`, default `'structured'`); it is one setting for the whole app, stored per user, not state of the page ([Settings](https://skaile-ai.github.io/forge-editor/guides/settings)).

- **The switch.** The Flat | Structure tabs in the header read and write `useEditorSettings().settings.value.blocks.structure`; the settings bridge deep-watches the ref and persists the change, so every editor of the app follows it. Users find the same choice in the settings popup under Editing.
- **What changes.** In Flat mode the toolbar offers Heading 1–3; in Structure mode it does not, and new sections are Typed blocks. The AI shapes its output the same way: Markdown headings in Flat mode, nested Typed blocks in Structure mode ([AI](https://skaile-ai.github.io/forge-editor/guides/ai)).
- **Two samples.** „Flat: project brief“ is headings with paragraphs and lists below them; its Markdown output has `##` headings. „Structure: the same brief“ is the same text as `section` Typed blocks (title, description, tags, body; „Out of scope“ nested inside „Scope“) plus one `task` with status, due date and assignee; its Markdown output wraps each block in a `::: section` fence ([Markdown and code](https://skaile-ai.github.io/forge-editor/guides/markdown-and-code)).
- **Converting.** The two header buttons run the composites feature's commands on the whole document: `convertHeadingsToComposites({ recursive: true, scope: 'document', kind })` groups every heading level into nested Typed blocks of the default Block type, `convertCompositesToHeadings({ recursive: true, scope: 'document' })` turns Typed blocks into headings of their nesting level, with description, tags and properties as text lines. The `/` menu has the same conversions for one level or all levels („Headings to Typed blocks“, „Typed blocks to headings“ and their nested variants), the toolbar's „Convert structure“ menu too. Converting changes the document, not the setting ([Composites and the settings UI](https://skaile-ai.github.io/forge-editor/guides/composites)).
- **No panel.** The page leaves the `panel` slot empty on purpose: the default JSON and Markdown output is where the difference shows.

```vue [app/pages/kitchen-sink/structure.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import type { StructureMode } from '@skaile/forge-editor/settings'
import { useEditorI18n, useEditorSettings } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_STRUCTURE } from '~/editor/kitchen-sink/samples/structure'
import source from './structure.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// Flat mode & Structure mode. The switch in the header is `blocks.structure`, the app's shared and persisted editor
// setting (the same one as settings → Editing), not state of this page: every editor of the app follows it. It decides
// what the toolbar offers (Heading 1-3 only in Flat mode) and how the AI shapes its output. The two buttons convert the
// whole document with the composites feature's commands; converting does not change the setting. No `panel` on purpose:
// the default JSON/Markdown output shows the difference, `##` headings against `::: section` fences.

// The built-in Block types put `typedBlock` into the schema, so `section` blocks and the conversion commands exist.
const { t } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t)]

const { settings } = useEditorSettings()
// The settings bridge deep-watches the ref and persists the change.
const mode = computed<StructureMode>({
  get: () => settings.value.blocks.structure,
  set: (value) => { settings.value.blocks.structure = value },
})
const modes = [{ label: 'Flat', value: 'flat' }, { label: 'Structure', value: 'structured' }]

const page = pageOf('structure')!
// Called in setup: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_STRUCTURE)

// Whole document, every heading level, no matter where the caret is (a non-empty selection narrows it).
const groupOptions = () => ({ recursive: true, scope: 'document' as const, kind: settings.value.blocks.defaultBlockType })
const flattenOptions = { recursive: true, scope: 'document' as const }
// `pane.content` is read so the checks re-run on every edit: the TipTap instance itself is not reactive.
const canGroup = computed(() => pane.content && pane.editable && !!pane.editor?.can().convertHeadingsToComposites(groupOptions()))
const canFlatten = computed(() => pane.content && pane.editable && !!pane.editor?.can().convertCompositesToHeadings(flattenOptions))
const group = () => pane.editor?.chain().focus().convertHeadingsToComposites(groupOptions()).run()
const flatten = () => pane.editor?.chain().focus().convertCompositesToHeadings(flattenOptions).run()
</script>
```

## Blocks

What a document is made of, in the words of the [glossary](https://skaile-ai.github.io/forge-editor/getting-started/glossary):

- **Document**: the stored unit a user opens; it holds Blocks but is not itself a Block.
- **Block**: an addressable unit of a Document's content, either a Simple block or a Container block.
- **Simple block**: holds no other Blocks: paragraph, heading, list, quote, code block, media. The items of a list belong to the list.
- **Container block**: holds other Blocks, each addressable and movable on its own.
- **Typed block**: a Container block with a Block type: title, description, tags, then a body of Blocks.
- **Block type**: the exact kind of a Typed block (Section, Task, Note, …); it defines the Property definitions, the Accepted children, the Source media types and the AI brief ([Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types)).
- **Block properties** and **Property definition**: the values a Block carries (status, due date) and the declaration of one of them (key, label, value type) ([Block properties and Property definitions](https://skaile-ai.github.io/forge-editor/guides/block-properties)).
- **Block capabilities**, **Block actions**, **Ability**: what a Block supports, what a user can run on it, and what may be done at one place in the Document ([Block capabilities, abilities and actions](https://skaile-ai.github.io/forge-editor/guides/block-capabilities)).

`defaultBlockTypes(t)` returns the twelve built-in Block types: `section`, `task`, `note`, `document`, `recording`, `paper`, `book`, `figure`, `rendition`, `collection`, `dataView` and `folder`, labelled in the editor's language. The page appends the host's own `decisionBlockType` (`app/editor/kitchen-sink/decision.ts`).

- **The tour sample.** „Block tour“ introduces each step with a paragraph: Simple blocks (paragraph, heading, list, quote, code block), a `section` Typed block with tags and a nested section, a `task` with properties next to a `note` without any (its Block type defines none), and the host's `decision` with its status.
- **Panel.** `CompositeInspector` shows the selected block: its Block type, title, description, tags and properties. `CompositeTable` lists every Typed block of the document as a row, with filters by Block type and tag. Both read the same editor ([Composites and the settings UI](https://skaile-ai.github.io/forge-editor/guides/composites)).

```vue [app/pages/kitchen-sink/blocks.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { CompositeInspector, CompositeTable } from '@skaile/forge-editor/composites/vue'
import { useEditorI18n } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { decisionBlockType } from '~/editor/kitchen-sink/decision'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_BLOCKS } from '~/editor/kitchen-sink/samples/blocks'
import source from './blocks.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// Content blocks: what a document is made of. The sample walks from Simple blocks (paragraph, heading, list, quote,
// code) to Container blocks and Typed blocks, then to Block types and their properties. The editor knows the built-in
// Block types plus the host's own `decision`; the panel shows two readers of the same document: the inspector for the
// selected block's properties and the table of every Typed block.

// The built-in Block types (labelled in the editor's language) plus the host's own.
const { t } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t), decisionBlockType]

const page = pageOf('blocks')!
// Called in setup: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_BLOCKS)
</script>
```

## JSON and Markdown

Document in, document out. The stored form of a document is TipTap JSON: the page hands it to the editor through `v-model` and gets every change back as JSON. The editor gives every block an `id` attribute when it loads the document; look for `attrs.id` in the JSON panel.

- **Markdown out.** `editor.getMarkdown()` writes the document as Markdown. Simple blocks and marks become plain Markdown (`**bold**`, `++underline++`, lists, quotes, fenced code); a Typed block becomes a `::: <kind>` fence with its properties as JSON, its title as `## …`, its description as a quote and its tags as a `Tags:` line. Markdown keeps a block id only where something in the document points at it ([Markdown and code](https://skaile-ai.github.io/forge-editor/guides/markdown-and-code)).
- **Markdown in.** `parseBlocks(editor, markdown)` from `@skaile/forge-editor/core` runs the block pipeline a file import uses: `parsed` is the whole document as JSON, `blocks` the blocks to insert at the caret. **Load Markdown** in the header replaces the document with `parsed` of a release note written as Markdown.
- **The round trip.** The panel writes the document as Markdown, reads it back and compares the result with the document, block ids and the trailing empty paragraph left out (`app/editor/kitchen-sink/round-trip.ts`). „Release note (JSON)“ comes back unchanged; „Lossy: author marks“ does not, because Markdown has no syntax for who wrote a text, and the panel names the first place that differs.
- **JSON the editor refuses.** „Invalid: unknown block“ holds a node the schema does not know. The editor keeps its last valid document and emits `contentError`; the page shows the message.

```vue [app/pages/kitchen-sink/json-markdown.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { parseBlocks } from '@skaile/forge-editor/core'
import { useEditorI18n } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, refreshMarkdown, showSettings } from '~/editor/kitchen-sink/pane'
import { roundTrip } from '~/editor/kitchen-sink/round-trip'
import { RELEASE_MARKDOWN, SAMPLES_JSON_MARKDOWN } from '~/editor/kitchen-sink/samples/json-markdown'
import source from './json-markdown.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// Document in, document out. The stored form is TipTap JSON behind `v-model`; Markdown is a second way in
// (`parseBlocks`, the block pipeline an import uses) and out (`editor.getMarkdown()`). The panel writes the document as
// Markdown, reads it back and compares the two, block ids left out. JSON the schema does not know is refused through
// `contentError`: the editor keeps its last valid document, and the page shows why.

const { t } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t)]

const page = pageOf('json-markdown')!
// Called in setup: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_JSON_MARKDOWN)

const contentError = ref<string | null>(null)
// `sync`: cleared the moment new content is handed in, before the editor checks it and possibly reports an error.
watch(() => pane.content, () => { contentError.value = null }, { flush: 'sync' })

/** Replaces the document with Markdown read through the block pipeline: `parsed` is the whole document as JSON. */
async function loadMarkdown() {
  const editor = pane.editor
  if (!editor) return
  pane.content = parseBlocks(editor, RELEASE_MARKDOWN).parsed
  await nextTick()
  refreshMarkdown(pane)
}

// `pane.markdown` is refreshed on every update, so the round trip follows the document.
const trip = computed(() => pane.editor && pane.markdown ? roundTrip(pane.editor, pane.markdown) : null)
</script>
```

## Actions

Commands and block actions are two ways to act on a document. A command (the `/` menu, the toolbar) inserts or formats at the caret; a block action acts on a block that is already there. The drag handle on the left of a block moves it.

- **Where block actions appear.** On the hover bar of the block under the pointer, on the toolbar of the block holding the selection, or both: `blockUi.actions` (`'hover'`, `'toolbar'` or `'both'`; [Block UI](https://skaile-ai.github.io/forge-editor/guides/block-ui)). The editor reads `blockUi` once, so the Hover/Toolbar/Both switch in the header remounts it with `:key`; the document stays in `v-model`.
- **Own actions.** `blockActions` adds the page's three: „Copy block id“ (`run`, `readOnly: true`, so it stays in a read-only editor), „Insert after“ (`menu`: a dropdown of a paragraph or a divider) and „Count blocks inside“ (`requires: ['container']`, `target: 'typedBlock'`: only on Typed blocks, and on the toolbar also while the caret is in such a block's body).
- **Who decides.** Whether an action is offered is decided per block: its `ability` at that place in the document, the Block capabilities it `requires`, and `readOnly` in a read-only editor ([Block capabilities, abilities and actions](https://skaile-ai.github.io/forge-editor/guides/block-capabilities)). The page's `abilities` rule revokes `block.delete` and `block.duplicate` inside every `blockquote`, so the quote's paragraph has no Delete and no Duplicate. Turn off „editable“ and only the reading actions are left.
- **Panel.** The action log lists the last runs of the page's own actions with the block they ran on, above the document as Markdown.

```vue [app/pages/kitchen-sink/actions.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import type { AbilitiesOptions, BlockAction, BlockActionContext, BlockActionSurface } from '@skaile/forge-editor/core'
import { ABILITY } from '@skaile/forge-editor/core/schema'
import { useEditorI18n } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_ACTIONS } from '~/editor/kitchen-sink/samples/actions'
import source from './actions.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// Acting on blocks. Commands (`/` menu, toolbar) insert; block actions act on a block that is there, on its hover bar,
// on the toolbar of the block holding the selection, or both (`blockUi`, read once at setup: the editor is remounted
// with `:key` when the surface changes, the document stays in `v-model`). Whether an action is offered is decided per
// block: its `ability` at that place in the document, the capabilities it `requires`, and `readOnly` in a read-only
// editor. The page's ability rule takes delete and duplicate away inside quotes; the panel logs every run.

const { t } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t)]

const page = pageOf('actions')!
// Called in setup: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_ACTIONS)

const surface = ref<BlockActionSurface | 'both'>('hover')
const surfaces = [{ label: 'Hover', value: 'hover' }, { label: 'Toolbar', value: 'toolbar' }, { label: 'Both', value: 'both' }]

// Inside a quote, its blocks may not be deleted or duplicated: the built-in actions with these abilities disappear there.
const abilities: Partial<AbilitiesOptions> = { rules: { blockquote: { revokes: [ABILITY.blockDelete, ABILITY.blockDuplicate] } } }

const log = ref<{ at: string, action: string, block: string }[]>([])
function record(action: string, { node }: BlockActionContext) {
  const block = node.attrs.blockType ? `${node.type.name} (${node.attrs.blockType})` : node.type.name
  log.value = [{ at: new Date().toLocaleTimeString('en-GB'), action, block }, ...log.value].slice(0, 8)
}

const toast = useToast()
const blockActions: BlockAction[] = [
  {
    // Reads only, so it stays on the bar of a read-only editor.
    id: 'copy-id',
    label: 'Copy block id',
    icon: 'i-lucide-fingerprint',
    readOnly: true,
    run: (ctx) => {
      void navigator.clipboard?.writeText(String(ctx.node.attrs.id ?? ''))
      toast.add({ title: 'Block id copied', description: String(ctx.node.attrs.id ?? 'no id'), icon: 'i-lucide-fingerprint' })
      record('Copy block id', ctx)
    },
  },
  {
    // A `menu` instead of `run`: a dropdown of the items it returns.
    id: 'insert-after',
    label: 'Insert after',
    icon: 'i-lucide-list-plus',
    menu: ctx => [
      { label: 'Paragraph', icon: 'i-lucide-pilcrow', onSelect: () => insertAfter(ctx, { type: 'paragraph' }, 'Insert paragraph') },
      { label: 'Divider', icon: 'i-lucide-minus', onSelect: () => insertAfter(ctx, { type: 'horizontalRule' }, 'Insert divider') },
    ],
  },
  {
    // Only on blocks that hold other blocks; on the toolbar also while the caret is inside such a block's body.
    id: 'count-children',
    label: 'Count blocks inside',
    icon: 'i-lucide-hash',
    requires: ['container'],
    target: 'typedBlock',
    readOnly: true,
    run: (ctx) => {
      let count = 0
      // Title, description and tags are the Typed block's chrome, not blocks of its body.
      ctx.node.forEach((child) => { if (!['typedBlockTitle', 'typedBlockDescription', 'typedBlockTags'].includes(child.type.name)) count++ })
      toast.add({ title: `${count} blocks inside`, icon: 'i-lucide-hash' })
      record('Count blocks inside', ctx)
    },
  },
]

function insertAfter(ctx: BlockActionContext, node: { type: string }, action: string) {
  ctx.editor.chain().focus().insertContentAt(ctx.pos + ctx.node.nodeSize, node).run()
  record(action, ctx)
}
</script>
```

## Settings

One settings object per app, read by every editor and stored per user ([Settings](https://skaile-ai.github.io/forge-editor/guides/settings)). `useEditorSettings()` returns it as a Vue ref with two flags: `ready` (the stored settings are usable) and `synced` (the account's settings from the server are in effect). Assigning to the ref persists the change; every editor of the app follows it, the Flat & Structure switch included.

- **Panel.** `EditorSettingsPanel` sits inline here instead of in the popup. Its tabs (Editing, Author colors, Comments, Theme, AI) are the ones the editor's features contribute; an editor without a feature has no tab for it. Below the panel: the live settings object as JSON, and the keys whose value differs from `EDITOR_SETTINGS_DEFAULTS`.
- **Reset.** The button in the header assigns `EDITOR_SETTINGS_DEFAULTS` back, the theme kept. It resets the settings of every editor of the app, not only of this page.
- **The tour sample.** „Settings tour“ has a place to try each Editing setting: headings for the „Convert structure“ scope, a Typed block for the block type icon and the drag handle, a long section for the split target size, and a task to type in with author colors on.

```vue [app/pages/kitchen-sink/settings.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { EDITOR_SETTINGS_DEFAULTS } from '@skaile/forge-editor/settings'
import { EditorSettingsPanel, useEditorI18n, useEditorSettings } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_SETTINGS } from '~/editor/kitchen-sink/samples/settings'
import source from './settings.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// Editor settings: one object per app (`useEditorSettings()`), stored per user, read by every editor. The panel places
// `EditorSettingsPanel` inline instead of the popup (its tabs are the ones the editor's features contribute) above the
// live settings object, the keys that differ from `EDITOR_SETTINGS_DEFAULTS`, and a reset. `ready` turns true when the
// stored settings are usable, `synced` when the account's settings from the server are in effect.

const { t } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t)]

const page = pageOf('settings')!
// Called in setup: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_SETTINGS)

const { settings, ready, synced } = useEditorSettings()
const tab = ref<string>()

type Sections = Record<string, Record<string, unknown>>
// `section.key` of every setting whose value is not the default one.
const changed = computed(() => Object.entries(EDITOR_SETTINGS_DEFAULTS as unknown as Sections)
  .filter(([, values]) => typeof values === 'object' && values !== null)
  .flatMap(([section, values]) => Object.keys(values)
    .filter(key => JSON.stringify((settings.value as unknown as Sections)[section]?.[key]) !== JSON.stringify(values[key]))
    .map(key => `${section}.${key}`)))

// Everything back to the defaults except the theme: the settings bridge deep-watches the ref and persists the change.
function reset() {
  settings.value = { ...structuredClone(EDITOR_SETTINGS_DEFAULTS), appearance: settings.value.appearance }
}
</script>
```

## Simple

The smallest editor, with the AI sidebar and the selection actions switched on.

- **SimpleEditor.** Core blocks only: marks, headings, lists, quotes, code ([Chapter 2: A simple editor](https://skaile-ai.github.io/forge-editor/tutorial/simple-editor)).
- **AI through add.** The simple bundle holds no catalog feature, so `aiFeature()` comes in through the `add` prop; it brings the AI sidebar and the selection actions ([AI](https://skaile-ai.github.io/forge-editor/guides/ai), [AI configuration and secrets](https://skaile-ai.github.io/forge-editor/guides/ai-configuration)).
- **The same page shell.** Sample select, settings popup and output panes are the ones of the bigger pages.

```vue [app/pages/kitchen-sink/simple.vue]
<script setup lang="ts">
import { SimpleEditor } from '@skaile/forge-editor/vue/simple'
import { aiFeature } from '@skaile/forge-editor/ai/vue'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_SIMPLE } from '~/editor/kitchen-sink/samples/simple'
import source from './simple.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// A standalone editor (TipTap JSON via v-model, own undo history, no websocket) built as a `SimpleEditor` with
// `add: [aiFeature()]`: core blocks plus the AI sidebar and selection actions. The settings popup is
// `settings-ui="external"`: the editor emits `settingsOpen`, `KitchenSinkPage` places `EditorSettingsModal`.
const page = pageOf('simple')!

// Called in setup: the AI/profile features of the compositions inject the app context.
const pane = createPane(page.title, SAMPLES_SIMPLE)
// The simple editor's bundle holds no catalog feature, so the AI feature comes in through `add`.
const add = [aiFeature()]
</script>
```

## Advanced

`AdvancedEditor` with its host props, one prop per extension point.

- **The preset.** `AdvancedEditor` is the advanced composition behind one component ([Feature composition and entries](https://skaile-ai.github.io/forge-editor/guides/composition)).
- **Own block type.** `blockTypes` is `defaultBlockTypes(t)` plus `decisionBlockType`; it shows in the `/` menu, the block badge and the toolbar's Typed block dropdown ([Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types)).
- **Own command and action.** `commands` receives the default `/` commands and returns them with `/date` appended; `blockActions` adds a hover action gated by the `block.delete` ability ([Block capabilities, abilities and actions](https://skaile-ai.github.io/forge-editor/guides/block-capabilities), [Block UI](https://skaile-ai.github.io/forge-editor/guides/block-ui)).
- **Abilities and metadata.** `abilities` revokes `ai.rewrite` inside bullet lists; `metadata` provides hashtags and speakers, and `@metadata-create` logs a newly created item.
- **Composition props.** `remove: ['tables']` leaves tables out of the composition and of the schema the samples must fit; `settings-ui="external"` makes the editor emit `settingsOpen` for the page to place the popup ([Composites and the settings UI](https://skaile-ai.github.io/forge-editor/guides/composites)).

```vue [app/pages/kitchen-sink/advanced.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import type { AbilitiesOptions, BlockAction, CommandDef, EditorMetadata, MetadataItem } from '@skaile/forge-editor/core'
import { useEditorI18n } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { decisionBlockType } from '~/editor/kitchen-sink/decision'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_ADVANCED } from '~/editor/kitchen-sink/samples/advanced'
import source from './advanced.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// A standalone AdvancedEditor (TipTap JSON via v-model, own undo history, no websocket) that shows the host extension
// points as plain props: metadata lists, an ability override, an own hover action, an own `/` command and an own Block
// type (offered in the `/` menu, the Block type badge and the toolbar's Typed block dropdown). `remove: ['tables']`
// leaves tables out of the composition, and out of the schema its samples must fit. The settings popup is
// `settings-ui="external"`: the editor emits `settingsOpen`, `KitchenSinkPage` places `EditorSettingsModal`.
const page = pageOf('advanced')!

// Constants, not template literals: a new `metadata` object on every re-render would replace the lists each time.
const metadata: EditorMetadata = {
  hashtags: [{ id: 'demo', label: 'demo' }, { id: 'reference', label: 'reference' }],
  speakers: [{ id: 'anna', label: 'Anna' }, { id: 'ben', label: 'Ben' }],
}
const abilities: Partial<AbilitiesOptions> = { rules: { bulletList: { revokes: ['ai.rewrite'] } } }
// Shown on every block that may be deleted, after the default hover actions.
const blockActions: BlockAction[] = [
  { id: 'log', label: 'Log to console', icon: 'i-lucide-terminal', ability: 'block.delete', run: ({ node }) => console.log(node.toJSON()) },
]
// Appended to the default `/` commands (incl. `/decision` from `blockTypes`); no `ability`: plain text may go wherever
// the `/` menu opens.
function withDateCommand(defaults: CommandDef[]): CommandDef[] {
  return [...defaults, { id: 'date', label: 'Insert date', icon: 'i-lucide-calendar', slash: {}, run: editor => editor.chain().focus().insertContent(new Date().toLocaleDateString('en-GB')).run() }]
}
// The built-in Block types (labelled in the editor's language) plus one of the host's own.
const { t } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t), decisionBlockType]
const remove = ['tables'] as const

function logCreated(list: string, item: MetadataItem) {
  console.log('create', list, item)
}

// Called in setup: the AI/profile features of the compositions inject the app context.
const pane = createPane(page.title, SAMPLES_ADVANCED)
</script>
```

## Surface

`EditorSurface` on an explicit composition, with a feature of your own.

- **A preset handed to the surface.** `advancedEditor({ blockTypes, add: [calloutFeature()] })` builds the advanced composition plus the host's feature; `EditorSurface` mounts it. Call it in `<script setup>`: some features hook the app's lifetime ([Feature composition and entries](https://skaile-ai.github.io/forge-editor/guides/composition)).
- **An own feature.** `app/editor/callout/` is a block of the host: node, node view, a toolbar button, the `/callout` command, a hover menu for the tone, „Convert to …“ in both directions and a description for the AI. The tutorial builds it step by step: [Chapter 5: Your own feature, path B](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b).
- **An own ability.** `CALLOUT_ABILITY` gates the callout's items; the `abilities` prop grants it at document root next to `ROOT_ABILITIES`.
- **Markdown.** „Insert Markdown“ runs `parseBlocks(editor, CALLOUT_MARKDOWN)` and inserts the result, which shows the callout's `!!!` syntax going through the block pipeline ([Markdown and code](https://skaile-ai.github.io/forge-editor/guides/markdown-and-code)).

```vue [app/pages/kitchen-sink/surface.vue]
<script setup lang="ts">
import { advancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { defaultBlockTypes } from '@skaile/forge-editor/composites'
import { type AbilitiesOptions, parseBlocks } from '@skaile/forge-editor/core'
import { ROOT_ABILITIES } from '@skaile/forge-editor/core/schema'
import { EditorSurface, useEditorI18n } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { CALLOUT_ABILITY, calloutFeature } from '~/editor/callout/feature'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { CALLOUT_MARKDOWN, SAMPLES_SURFACE } from '~/editor/kitchen-sink/samples/surface'
import source from './surface.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// A standalone editor (TipTap JSON via v-model, own undo history, no websocket) built as an `EditorSurface` on the
// advanced composition (`advancedEditor({ add })`) plus one own feature (`app/editor/callout`): a block of the host with
// toolbar button, `/` command, hover menu, "Convert to …" target and Markdown form. The settings popup is
// `settings-ui="external"`: the editor emits `settingsOpen`, `KitchenSinkPage` places `EditorSettingsModal`.
const page = pageOf('surface')!

// Called in setup: the AI/profile features of the compositions inject the app context.
// The advanced composition plus the host's own feature, handed to the surface as one preset.
const preset = advancedEditor({ blockTypes: defaultBlockTypes(useEditorI18n().t), add: [calloutFeature()] })
const pane = createPane(page.title, SAMPLES_SURFACE)
// The custom ability must be granted at document root, or the callout's toolbar button, `/callout` and hover menu stay hidden.
const abilities: Partial<AbilitiesOptions> = { root: [...ROOT_ABILITIES, CALLOUT_ABILITY] }

/** Imports Markdown with the callout syntax through the editor's block pipeline (the tokenizer of `callout/node.ts`). */
function insertCalloutMarkdown() {
  const editor = pane.editor
  if (!editor) return
  editor.chain().focus().insertContent(parseBlocks(editor, CALLOUT_MARKDOWN).blocks).run()
}
</script>
```

## Minutes

Meeting minutes from a transcript: the core scenario of the framework. The sample „Weekly sync“ has speaker segments, a task and a decision; „Status report“ has sections with nested notes.

- **Metadata lists.** The page passes `metadata` with `speakers` (the speaker picker of a transcript segment and the `@` menu) and `hashtags` (the `#` menu). Constants, not template literals: a new object on every render would replace the lists each time. See [Media, mentions and transcript features](https://skaile-ai.github.io/forge-editor/guides/media-mentions-transcript).
- **Transcript segments.** One paragraph per speaker turn, from the transcript feature of the advanced composition ([Feature composition and entries](https://skaile-ai.github.io/forge-editor/guides/composition)).
- **Typed blocks with properties.** `task` is a built-in Block type; `decision` is the host's own, defined as data in `app/editor/kitchen-sink/decision.ts` (a `status` select property) and appended to `defaultBlockTypes(t)` ([Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types), [Block properties and Property definitions](https://skaile-ai.github.io/forge-editor/guides/block-properties)).
- **Panel.** `EditorOutline` and `CompositeTable` read the same editor: the heading outline, and every Typed block as a row ([Composites and the settings UI](https://skaile-ai.github.io/forge-editor/guides/composites)).

```vue [app/pages/kitchen-sink/minutes.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { CompositeTable } from '@skaile/forge-editor/composites/vue'
import type { EditorMetadata } from '@skaile/forge-editor/core'
import { EditorOutline } from '@skaile/forge-editor/outline/vue'
import { useEditorI18n } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { decisionBlockType } from '~/editor/kitchen-sink/decision'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_MINUTES } from '~/editor/kitchen-sink/samples/minutes'
import source from './minutes.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// The core scenario: meeting minutes. The default advanced composition plus the host's metadata lists (the speakers
// of the transcript segments, the hashtags the `#` menu offers) and one own Block type, `decision`. The panel shows
// two views of the same document: the heading outline and the table of its Typed blocks.

// Constants, not template literals: a new `metadata` object on every re-render would replace the lists each time.
const metadata: EditorMetadata = {
  speakers: [{ id: 'anna', label: 'Anna' }, { id: 'ben', label: 'Ben' }, { id: 'clara', label: 'Clara' }],
  hashtags: [{ id: 'northlight', label: 'northlight' }, { id: 'decision', label: 'decision' }, { id: 'risk', label: 'risk' }],
}
// The built-in Block types (labelled in the editor's language) plus the host's own.
const { t } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t), decisionBlockType]

const page = pageOf('minutes')!
// Called in setup: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_MINUTES)
</script>
```

## Slides

A deck written as blocks, with a preview of each slide and render targets for reveal.js, PowerPoint and Marp.

- **Block types from an add-on.** `slideBlockTypes(locale)` from `@skaile/forge-editor-slides/client` adds `deck` and `slide`; the page appends them to `defaultBlockTypes(t)`. The „Kickoff deck“ sample has a deck with six slides in different layouts ([Slides: decks, slide layouts and exports](https://skaile-ai.github.io/forge-editor/guides/slides)).
- **A feature from the add-on.** `slidesFeature()` from `@skaile/forge-editor-slides/vue` is passed through `add`; it contributes the slide preview section of the inspector and the slide hover actions.
- **Transfer transforms.** `interaction` is `[...INTERACTION.full, 'transfer']` and `transfer.extraTransforms` is `slidesTransforms({ locale })`. The „Outline to deck“ sample is plain headings and bullets to drag into a deck with „Insert as slides“ ([Feature composition and entries](https://skaile-ai.github.io/forge-editor/guides/composition)).
- **Render targets.** Select the deck block, open its hover menu and choose „Render as…“. The targets live on the server; without `NUXT_PUBLIC_ADDONS_SLIDES=1` the panel shows a `ServerHint` ([Render: export a Block or a Document to a file](https://skaile-ai.github.io/forge-editor/guides/render)).

```vue [app/pages/kitchen-sink/slides.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { CompositeInspector } from '@skaile/forge-editor/composites/vue'
import { type FeatureId, INTERACTION } from '@skaile/forge-editor/presets/compose'
import type { TransferFeatureOptions } from '@skaile/forge-editor/transfer'
import { useEditorContext, useEditorI18n } from '@skaile/forge-editor/vue'
import { slideBlockTypes, slidesTransforms } from '@skaile/forge-editor-slides/client'
import { slidesFeature } from '@skaile/forge-editor-slides/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import ServerHint from '~/components/kitchen-sink/ServerHint.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_SLIDES } from '~/editor/kitchen-sink/samples/slides'
import source from './slides.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// The slides add-on on an AdvancedEditor: it brings two Block types (`deck`, `slide`), a host feature (the preview section in the
// inspector and the slide hover actions) and transfer transforms ("Insert as slides"). The page imports the add-on's `/client`
// and `/vue` entries directly, so the editor shows decks whatever `NUXT_PUBLIC_ADDONS_SLIDES` says; only the server render targets
// (reveal.js, PowerPoint, Marp) need that flag.
const page = pageOf('slides')!
const { t, locale } = useEditorI18n()
const ctx = useEditorContext()
// Called in setup, before the first await: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_SLIDES)

// Constants, not template literals: a new object on every re-render would replace the editor's options each time.
const blockTypes: BlockType[] = [...defaultBlockTypes(t), ...slideBlockTypes(locale)]
const interaction: FeatureId[] = [...INTERACTION.full, 'transfer']
const transfer: TransferFeatureOptions = { extraTransforms: slidesTransforms({ locale }) }
const features = [slidesFeature()]

// The renderer is a server port: without it (or without the slides targets) the "Render as…" menu has no deck formats.
const targets = await ctx.backend.render?.targets().catch(() => []) ?? []
const hasRender = targets.some(target => target.id === 'reveal-html')
</script>
```

## Databases

Tasks as rows, queried into tables, boards, collections and charts.

- **DataQuery.** A `dataView` block stores a query (`source`, `sorts`, `group`) and a layout; it holds no rows. The „Task tracker“ sample has eight `task` blocks, a table view sorted by due date and a board grouped by status ([Data views: a query shown as table, list or board](https://skaile-ai.github.io/forge-editor/guides/data-views), [Query: filter, sort, group and total Blocks](https://skaile-ai.github.io/forge-editor/guides/query)).
- **No index needed.** A data view or chart asks the backend's Block index and answers from the open document only when the backend has none. The standalone editor's blocks are in no index, so the page provides its editor a copy of the context whose backend has no `index`; everything else stays the app's ([Workspace: find, read, reference and embed Blocks across Documents](https://skaile-ai.github.io/forge-editor/guides/workspace)).
- **Collections.** The „Collection“ sample lists three tasks by block id; the sample gives those tasks fixed ids so the references resolve ([Collections: an ordered list of Blocks](https://skaile-ai.github.io/forge-editor/guides/collections)).
- **Charts.** `chartBlockTypes(locale)` and `chartNodeViews` come from the charts add-on's `/client` and `/vue` entries, so charts draw in the browser whatever `NUXT_PUBLIC_ADDONS_CHARTS` says; the flag adds the server's SVG export, and the panel shows a `ServerHint` without it ([Charts: bar, line, pie and scatter over a query](https://skaile-ai.github.io/forge-editor/guides/charts)).

```vue [app/pages/kitchen-sink/databases.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { CompositeTable } from '@skaile/forge-editor/composites/vue'
import { EDITOR_CONTEXT, useEditorContext, useEditorI18n } from '@skaile/forge-editor/vue'
import { chartBlockTypes } from '@skaile/forge-editor-charts/client'
import { chartNodeViews } from '@skaile/forge-editor-charts/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import ServerHint from '~/components/kitchen-sink/ServerHint.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_DATABASES } from '~/editor/kitchen-sink/samples/databases'
import source from './databases.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// Typed blocks as database rows. `task` blocks carry properties (status, due, assignee); the built-in `dataView` block shows a stored
// query as a table or a board, and the charts add-on's `chart` block draws one. The page imports the charts add-on's `/client`
// and `/vue` entries directly, whatever `NUXT_PUBLIC_ADDONS_CHARTS` says; only the server's chart export needs that flag.
const page = pageOf('databases')!
const { t, locale } = useEditorI18n()
const ctx = useEditorContext()
// A data view or chart asks the backend's Block index (every Document of the workspace) and answers from the open Document
// only when the backend has none. This editor is standalone: its Blocks are in no index, so the page hands its editor a
// backend without `index`, and the views show the sample's tasks. Everything else (render, AI, settings) stays the app's.
const { index: _workspaceIndex, ...localBackend } = ctx.backend
provide(EDITOR_CONTEXT, { ...ctx, backend: localBackend })
// Called in setup, before the first await: the AI/profile features of the composition inject the app context.
const pane = createPane(page.title, SAMPLES_DATABASES)

// Constant, not a template literal: a new array on every re-render would replace the editor's Block types each time.
const blockTypes: BlockType[] = [...defaultBlockTypes(t), ...chartBlockTypes(locale)]

// The renderer is a server port: without it (or without the chart target) a chart cannot be exported as SVG.
const targets = await ctx.backend.render?.targets().catch(() => []) ?? []
const hasChartExport = targets.some(target => target.id === 'chart-svg')
</script>
```

## Science

Papers with a bibliography, inline citations, quotes with source anchors and PDF output.

- **A bibliography in a property.** A `paper` block keeps one CSL-JSON item in `meta.bib` (two references are two blocks). The „Paper notes“ sample computes the citation keys with `bibtexKey` instead of writing them by hand ([Citations](https://skaile-ai.github.io/forge-editor/guides/citations)).
- **Cite nodes.** `cite` nodes (insert with `/cite` or type `[cite:`) name an entry by key and show a short label such as „(Vaswani et al. 2017)“, resolved against the bibliography ([Citations](https://skaile-ai.github.io/forge-editor/guides/citations)).
- **Quotes and source anchors.** `quoteBlockTypes(locale)` from `@skaile/forge-editor-pdf-viewer` adds the `quote` type, `pdfViewerFeature()` from its `/vue` entry the viewer in the inspector ([PDF viewer: passages, anchors and quotes](https://skaile-ai.github.io/forge-editor/guides/pdf-viewer)).
- **PDF output.** The `typst-pdf` render target is server-side. The page waits for `ctx.backend.ready`, lists the targets and shows a `ServerHint` for `NUXT_PUBLIC_ADDONS_TYPST` when it is missing ([Typst: render a Document as a PDF with citations](https://skaile-ai.github.io/forge-editor/guides/typst), [Render: export a Block or a Document to a file](https://skaile-ai.github.io/forge-editor/guides/render)).

```vue [app/pages/kitchen-sink/science.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { CompositeInspector } from '@skaile/forge-editor/composites/vue'
import { useEditorContext, useEditorI18n } from '@skaile/forge-editor/vue'
import { quoteBlockTypes } from '@skaile/forge-editor-pdf-viewer'
import { pdfViewerFeature } from '@skaile/forge-editor-pdf-viewer/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import ServerHint from '~/components/kitchen-sink/ServerHint.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_SCIENCE } from '~/editor/kitchen-sink/samples/science'
import source from './science.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// Scientific writing: the default composition plus the PDF-viewer add-on. A `paper` block keeps one CSL-JSON item in
// `meta.bib`; `cite` nodes (`/cite` or `[cite:`) name an entry by its key and show "(Vaswani et al. 2017)". `quoteBlockTypes`
// adds the `quote` kind (a passage of a PDF with a source anchor), `pdfViewerFeature` the viewer in the inspector. The
// "PDF (Typst)" render target lives on the server, so the page asks the backend whether it is there.
const page = pageOf('science')!
const pane = createPane(page.title, SAMPLES_SCIENCE)

const ctx = useEditorContext()
const { t, locale } = useEditorI18n()
const blockTypes: BlockType[] = [...defaultBlockTypes(t), ...quoteBlockTypes(locale)]
// The `/vue` entry's feature draws the viewer section of the inspector (the root entry has the framework-free core).
const add = [pdfViewerFeature()]

// `typst-pdf` is the id of `packages/editor-typst`'s render target (`NUXT_PUBLIC_ADDONS_TYPST=1` installs it on the server).
// `backend.ready` settles once the HTTP backend has dropped the capabilities the server lacks.
await ctx.backend.ready
const targets = (await ctx.backend.render?.targets().catch(() => [])) ?? []
const typstMissing = !targets.some(target => target.id === 'typst-pdf')
</script>
```

## Podcast

Recordings with their transcripts and a script, and speech synthesis and mixdown as block actions.

- **Recordings and renditions.** `recording` and `rendition` are built-in types; a transcript is a rendition nested in its recording. The „Episode“ sample has no audio file, since the page is about the structure ([Derive methods and the Derivation index](https://skaile-ai.github.io/forge-editor/guides/derive-methods), [Media, mentions and transcript features](https://skaile-ai.github.io/forge-editor/guides/media-mentions-transcript)).
- **Speaker segments.** `metadata.speakers` offers the two hosts in the speaker picker of each segment.
- **Audio actions.** `audioFeature({ mixdownMode: 'concat' })` from `@skaile/forge-editor-audio` adds two derive methods to the block actions: read a text block aloud into a new recording, and mix several recordings into one. Both record a Derivation, so a mixdown is marked outdated when one of its takes changes ([Audio: read aloud, mixdown and ElevenLabs](https://skaile-ai.github.io/forge-editor/guides/audio)).
- **Server ports.** Speech needs the server's `speech` port (`NUXT_PUBLIC_ADDONS_AUDIO=1` and `ELEVENLABS_API_KEY`; the mixdown needs ffmpeg). The page waits for `ctx.backend.ready`, tests `ctx.backend.speech` and shows a `ServerHint` ([Speech: text to audio, and subtitle files](https://skaile-ai.github.io/forge-editor/guides/speech)).

```vue [app/pages/kitchen-sink/podcast.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { CompositeInspector } from '@skaile/forge-editor/composites/vue'
import type { EditorMetadata } from '@skaile/forge-editor/core'
import { useEditorContext } from '@skaile/forge-editor/vue'
import { audioFeature } from '@skaile/forge-editor-audio'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import ServerHint from '~/components/kitchen-sink/ServerHint.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_PODCAST } from '~/editor/kitchen-sink/samples/podcast'
import source from './podcast.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// A podcast script: the built-in `recording` and `rendition` kinds (a transcript is a rendition nested in its recording) plus
// the audio add-on. `audioFeature` adds two derive methods to the block actions: read a text block aloud into a new recording
// (text to speech) and mix several recordings into one. Both record a Derivation, so the library marks a mixdown outdated when
// one of its takes changes. Speech needs the server's `speech` port, which the page looks up in the backend.
const page = pageOf('podcast')!
const pane = createPane(page.title, SAMPLES_PODCAST)

const ctx = useEditorContext()
// The hosts offered in the speaker picker of a transcript segment; a constant, so a re-render does not replace the list.
const metadata: EditorMetadata = {
  speakers: [{ id: 'anna', label: 'Anna' }, { id: 'ben', label: 'Ben' }],
}
const add = [audioFeature({ mixdownMode: 'concat' })]
// `backend.ready` settles once the HTTP backend has dropped the capabilities the server lacks (`speech` without the audio add-on).
await ctx.backend.ready
const speechMissing = !ctx.backend.speech
</script>
```

## PKM

A knowledge base in one document: a folder of tagged notes that link to each other.

- **Folders and notes.** `folder` and `note` are built-in Typed blocks; the „Vault“ sample nests notes in a folder ([Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types)).
- **Tags.** `metadata.hashtags` feeds the `#` menu ([Media, mentions and transcript features](https://skaile-ai.github.io/forge-editor/guides/media-mentions-transcript)).
- **References.** `[@` inserts a reference chip to another block of the same document; the sample gives its targets fixed ids ([Workspace: find, read, reference and embed Blocks across Documents](https://skaile-ai.github.io/forge-editor/guides/workspace)).
- **What the index adds.** The `explore` interaction (backlinks, related notes, the trail) is left out on purpose: it needs the workspace index, which a standalone editor does not have. [Explore](https://skaile-ai.github.io/forge-editor/guides/explore), [Edges](https://skaile-ai.github.io/forge-editor/guides/edges), [Graph](https://skaile-ai.github.io/forge-editor/guides/graph) and [Knowledge graph](https://skaile-ai.github.io/forge-editor/guides/knowledge-graph) show what a workspace adds.

```vue [app/pages/kitchen-sink/pkm.vue]
<script setup lang="ts">
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { CompositeTable } from '@skaile/forge-editor/composites/vue'
import type { EditorMetadata } from '@skaile/forge-editor/core'
import { EditorOutline } from '@skaile/forge-editor/outline/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_PKM } from '~/editor/kitchen-sink/samples/pkm'
import source from './pkm.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// A knowledge base in one document: a `folder` of `note` blocks, tags from the host's hashtag list and `[@` reference chips
// between the notes. The table beside the editor lists every Typed block with its tags, the outline the headings. Left out on
// purpose: the `explore` interaction (backlinks, search, related notes across documents) needs the workspace index, which a
// standalone editor does not have.
const page = pageOf('pkm')!
const pane = createPane(page.title, SAMPLES_PKM)

// A constant, so a re-render does not replace the list.
const metadata: EditorMetadata = {
  hashtags: [{ id: 'idea', label: 'idea' }, { id: 'source', label: 'source' }, { id: 'todo', label: 'todo' }],
}
</script>
```

## Epikrise

Epikrise comes last because it is the only page whose state lives on the server: the review records are kept by block id. A discharge report built from domain block types, each with its own AI brief and a review record per block.

- **Domain block types.** `EPIKRISE_KINDS` in `app/editor/epikrise/kinds.ts` are Block types as data: properties, placeholders and an `ai-brief` capability per kind. The UI labels are English; the `purpose` and `instructions` prompt texts stay German because the clinical sample is German ([Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types), [Block capabilities, abilities and actions](https://skaile-ai.github.io/forge-editor/guides/block-capabilities)).
- **AI brief and data.** The `ai-brief` config tells „Fill block (AI)“ what a block is for; `epikriseFeature()` supplies example paragraphs through `aiBlockData` for the reason-for-admission type ([AI](https://skaile-ai.github.io/forge-editor/guides/ai)).
- **Prüfung.** The page lists the `pruefung` capability on every Epikrise kind and on the built-in `section` type (editorial check, then medical check; the medical check locks the block), installs the feature with `with: ['pruefung']` and grants `ABILITY.pruefungRecord` at document root. `document-id="kitchen-sink-epikrise"` gives the server port an id to keep the records under, so they survive a reload; the panel states this ([Prüfung and Freigabestatus](https://skaile-ai.github.io/forge-editor/guides/pruefung)).
- **Panel.** `CompositeInspector` beside the editor shows the properties and details of the selected block.

```vue [app/pages/kitchen-sink/epikrise.vue]
<script setup lang="ts">
import { advancedEditor } from '@skaile/forge-editor/vue/advanced'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites'
import { CompositeInspector } from '@skaile/forge-editor/composites/vue'
import type { AbilitiesOptions, BlockTypeCapability } from '@skaile/forge-editor/core'
import { ABILITY, ROOT_ABILITIES } from '@skaile/forge-editor/core/schema'
import { EditorSurface, useEditorI18n } from '@skaile/forge-editor/vue'
import KitchenSinkPage from '~/components/kitchen-sink/KitchenSinkPage.vue'
import { epikriseFeature } from '~/editor/epikrise/feature'
import { EPIKRISE_KINDS } from '~/editor/epikrise/kinds'
import { pageOf } from '~/editor/kitchen-sink/pages'
import { createPane, paneReady, paneUpdated, showSettings } from '~/editor/kitchen-sink/pane'
import { SAMPLES_EPIKRISE } from '~/editor/kitchen-sink/samples/epikrise'
import source from './epikrise.vue?raw'

definePageMeta({ layout: 'kitchen-sink' })

// A clinical report with review. An `EditorSurface` on the advanced composition (`advancedEditor`) with the host's
// domain Block type (`aufnahme-anlass`, its AI brief and properties are data in `app/editor/epikrise/kinds.ts`), the
// host feature that supplies example paragraphs, and the opt-in `pruefung` feature. The page lists the `pruefung`
// capability on the reason for admission and on the built-in `section` type, so each part of the report has its own
// review; the server keeps the records per document.

// The Prüfung records are stored under this id by the server port, so they survive a reload.
const DOCUMENT_ID = 'kitchen-sink-epikrise'
// `pruefung.record` is not part of ROOT_ABILITIES: the host grants it at document root.
const abilities: Partial<AbilitiesOptions> = { root: [...ROOT_ABILITIES, ABILITY.pruefungRecord] }
// An editorial check, then a medical one (`chain`); the medical check locks the block until it changes or someone lifts
// the lock (`lock`). Kinds are host data, the server stores them as given. Listed here and not in `EPIKRISE_KINDS`: a
// capability no installed feature declares makes the editor throw, and only this page installs `pruefung`.
const review: BlockTypeCapability = { id: 'pruefung', config: { kinds: ['editorial', 'medical'], chain: true, lock: 'medical' } }
const reviewed = (type: BlockType): BlockType => ({ ...type, capabilities: [...type.capabilities, review] })

const { t } = useEditorI18n()
const page = pageOf('epikrise')!
// Called in setup: the AI/profile features of the composition inject the app context.
const preset = advancedEditor({
  blockTypes: [...defaultBlockTypes(t).map(type => type.id === 'section' ? reviewed(type) : type), ...EPIKRISE_KINDS.map(reviewed)],
  add: [epikriseFeature()],
  // `pruefung` is a catalog feature in no interaction level list: added on top of the bundle's `full` interaction.
  with: ['pruefung'],
})
const pane = createPane(page.title, SAMPLES_EPIKRISE)
</script>
```

## Beyond the kitchen sink

The kitchen sink keeps every page standalone, so some features are shown elsewhere in the app or only in their guide:

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      Where to see it
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Collaboration (<code>
        collaboration
      </code>
      
       prop, Hocuspocus session)
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/pages/documents/%5Bid%5D.vue" rel="nofollow">
        <code>
          app/pages/documents/[id].vue
        </code>
      </a>
      
      , <a href="https://skaile-ai.github.io/forge-editor/guides/collaboration">
        Collaboration
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Comments and authors (<code>
        CommentsMargin
      </code>
      
      , <code>
        v-model:comments-open
      </code>
      
      )
    </td>
    
    <td>
      the same document page, <a href="https://skaile-ai.github.io/forge-editor/guides/authors-and-comments">
        Authors and comments
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Explore and search (<code>
        explore
      </code>
      
      , <code>
        ExplorePanel
      </code>
      
      , <code>
        SearchPanel
      </code>
      
      )
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/layouts/default.vue" rel="nofollow">
        <code>
          app/layouts/default.vue
        </code>
      </a>
      
      , <a href="https://skaile-ai.github.io/forge-editor/guides/explore">
        Explore
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Templates (<code>
        templatesOf
      </code>
      
      , <code>
        TEMPLATES_FOLDER
      </code>
      
      )
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/pages/documents/index.vue" rel="nofollow">
        <code>
          app/pages/documents/index.vue
        </code>
      </a>
      
      , <a href="https://skaile-ai.github.io/forge-editor/guides/templates">
        Templates
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Themes (<code>
        appearance.theme
      </code>
      
      , the Theme tab)
    </td>
    
    <td>
      the settings popup of any page, <a href="https://skaile-ai.github.io/forge-editor/guides/themes">
        Themes
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      The editor-owned settings modal (<code>
        settings-ui="internal"
      </code>
      
      , the default; the kitchen sink places its settings itself with <code>
        settings-ui="external"
      </code>
      
      )
    </td>
    
    <td>
      the document page, <a href="https://skaile-ai.github.io/forge-editor/guides/settings">
        Settings
      </a>
      
      ; the settings object itself (<code>
        useEditorSettings
      </code>
      
      , <code>
        EDITOR_SETTINGS_DEFAULTS
      </code>
      
      , <code>
        EditorSettingsPanel
      </code>
      
      ) has its own page, <a href="#settings">
        Editor settings
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      UI kit (<code>
        createEditor({ kit })
      </code>
      
      ) and the module options
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/guides/nuxt-module">
        Nuxt module
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Export check
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/guides/export-check">
        Export check
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Obsidian vaults, image studio, graph, Typst
    </td>
    
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/guides/obsidian">
        Obsidian
      </a>
      
      , <a href="https://skaile-ai.github.io/forge-editor/guides/image-studio">
        Image studio
      </a>
      
      , <a href="https://skaile-ai.github.io/forge-editor/guides/graph">
        Graph
      </a>
      
      , <a href="https://skaile-ai.github.io/forge-editor/guides/typst">
        Typst
      </a>
    </td>
  </tr>
</tbody>
</table>

## The rest of the app

The repository's Nuxt app is the runnable advanced reference: documents with real-time collaboration, the file drawer, AI, and the kitchen sink above. It has no login: a visitor acts as one of the demo users `anna`, `ben` and `bernd` (`shared/utils/demo-users.ts`), starts as `anna` and switches in the user menu top right („Benutzer wechseln“, which reloads the page under the new user). Start it with `bun run dev` (port 3056); it needs `NUXT_SESSION_PASSWORD` (at least 32 characters, for the `nuxt-auth-utils` session cookie) and, for AI, the API key variables below in `.env`.

**Walkthrough**

1. Open `http://localhost:3056/`; you are `anna` and land on `/documents`, the app's home: the file drawer on the left lists the documents and the folders, the main area reads „Kein Dokument ausgewählt“. A fresh store (no `.data/documents` yet, or `NUXT_DOCUMENTS_DIR` pointing at a missing directory) starts with the folder „Blocktypen“: an overview and one document per set of block types (text blocks, inline elements and links, media and transcript, sections/tasks/notes, sources, collections/views/folders, the host's own Prüfabschnitt), each explaining its blocks on a working example. They are ordinary documents; to get them back, stop the server and remove the store directory.
2. Press „Neues Dokument“ (in the main area, or „Hinzufügen“ → „Neues Dokument“ on a drawer row) to create a document; the app opens `/documents/<id>` and the new document appears in the drawer. The drawer sorts the documents of a folder by title, numbers by value, and the folders by name; editing a document does not move it. In the drawer you can also create folders, drag documents and folders between folders, rename, filter and delete with undo ([Document tree](https://skaile-ai.github.io/forge-editor/guides/document-tree)); each document row has an export button that downloads a `.cdoc` package.
3. Type. Use the toolbar, the `/` menu, the drag handles and the hover block actions; the AI sidebar (the toolbar's AI button or `Mod-Shift-k`) and the settings cog in the header open their host-placed UI.
4. Open the same URL in a second browser tab, or as another user in a second browser (or a private window) where you switch to `ben` in the user menu; the session cookie is per browser, so tabs of one browser share the user. Text and carets appear in both within a moment and the header badge reads „Synchronisiert“; each tab keeps its own undo history. Text carries its author (switch the colouring on with the toolbar's palette button), and a selection can be commented („Kommentar“, `Mod-Shift-m` for the margin) with replies, resolve and reopen visible to both.
5. Optional: press „Kitchen sink“ at the top of the drawer (`/kitchen-sink`) for the gallery of the fifteen pages above, in three tracks: Basics, Building blocks, Use cases. The layout has no document tree: a navigation on the left lists the pages by track, a link back to „Dokumente“ and the standalone examples (`examples/*`, each its own dev server). Open the settings popup and pick the Theme tab („Theme“) to try the Themes: the whole app, header and navigation included, switches look.

**Optional AI configuration.** The editor works without AI credentials; AI requests then fail with the server's message. Keys come from the environment only (see [AI configuration and secrets](https://skaile-ai.github.io/forge-editor/guides/ai-configuration)): `NUXT_TIPTAP_EDITOR_AI_API_KEY` (shared fallback for every Model preset), `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY` (one Model preset; `flashLite` → `NUXT_TIPTAP_EDITOR_AI_PRESETS_FLASH_LITE_API_KEY`) and `NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY` (a Deepgram key; the host enables `ai.transcription` with Deepgram `nova-3` only when it is set, which makes “Create readable rendition” (English label) available on recordings).

## Where each part lives

<table>
<thead>
  <tr>
    <th>
      Part
    </th>
    
    <th>
      File
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Collaborative page: <code>
        AdvancedEditor
      </code>
      
       with a <code>
        HocuspocusProvider
      </code>
      
       session, toolbar and <code>
        AiSidebar
      </code>
      
       placed by the page, editor-owned settings modal (<code>
        settingsUi
      </code>
      
       default <code>
        'internal'
      </code>
      
      ), a „Text | Tabelle“ switch to <code>
        CompositeTable
      </code>
      
       (a row returns to the text and reveals its Typed block) and a docked <code>
        CompositeInspector
      </code>
      
       with the page's own Document facts in its <code>
        document
      </code>
      
       slot (<a href="https://github.com/skaile-ai/forge-editor/blob/main/app/components/DocumentProperties.vue" rel="nofollow">
        <code>
          DocumentProperties.vue
        </code>
      </a>
      
      )
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/pages/documents/%5Bid%5D.vue" rel="nofollow">
        <code>
          app/pages/documents/[id].vue
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      The fifteen pages: one Vue file each with its own editor, <code>
        v-model
      </code>
      
       content, panel and the source its „How it's built“ drawer shows
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/tree/main/app/pages/kitchen-sink" rel="nofollow">
        <code>
          app/pages/kitchen-sink/
        </code>
      </a>
      
      : <code>
        structure.vue
      </code>
      
      , <code>
        blocks.vue
      </code>
      
      , <code>
        json-markdown.vue
      </code>
      
      , <code>
        actions.vue
      </code>
      
      , <code>
        settings.vue
      </code>
      
      , <code>
        simple.vue
      </code>
      
      , <code>
        advanced.vue
      </code>
      
      , <code>
        surface.vue
      </code>
      
      , <code>
        minutes.vue
      </code>
      
      , <code>
        slides.vue
      </code>
      
      , <code>
        databases.vue
      </code>
      
      , <code>
        science.vue
      </code>
      
      , <code>
        podcast.vue
      </code>
      
      , <code>
        pkm.vue
      </code>
      
      , <code>
        epikrise.vue
      </code>
      
      ; <code>
        index.vue
      </code>
      
       is the gallery
    </td>
  </tr>
  
  <tr>
    <td>
      Page registry: slug, track, title, tagline, icon, accent, lessons and docs anchor of every page, read by the gallery, the layout's navigation and each page
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/editor/kitchen-sink/pages.ts" rel="nofollow">
        <code>
          app/editor/kitchen-sink/pages.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Shared page shell: header (sample select, toolbar, switches, settings, AI), the <code>
        panel
      </code>
      
      , <code>
        actions
      </code>
      
       and <code>
        sidebar
      </code>
      
       slots, the settings popup and the „How it's built“ drawer
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/components/kitchen-sink/KitchenSinkPage.vue" rel="nofollow">
        <code>
          app/components/kitchen-sink/KitchenSinkPage.vue
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Card for a capability that needs a server port or add-on flag this run lacks
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/components/kitchen-sink/ServerHint.vue" rel="nofollow">
        <code>
          app/components/kitchen-sink/ServerHint.vue
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Pane state (<code>
        createPane
      </code>
      
      , <code>
        loadSample
      </code>
      
      , <code>
        showSettings
      </code>
      
      , <code>
        refreshMarkdown
      </code>
      
      ) and the editor callbacks the pages share (<code>
        paneReady
      </code>
      
      , <code>
        paneUpdated
      </code>
      
      )
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/editor/kitchen-sink/pane.ts" rel="nofollow">
        <code>
          app/editor/kitchen-sink/pane.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Demo documents, one file per page, with the builders they share (<code>
        typed
      </code>
      
      , <code>
        heading
      </code>
      
      , <code>
        bullets
      </code>
      
      , <code>
        withId
      </code>
      
       for fixed block ids, …) and the Markdown for „Insert Markdown“ and „Load Markdown“
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/tree/main/app/editor/kitchen-sink/samples" rel="nofollow">
        <code>
          app/editor/kitchen-sink/samples/
        </code>
      </a>
      
      : <code>
        helpers.ts
      </code>
      
       (with <code>
        quote
      </code>
      
       and <code>
        codeBlock
      </code>
      
       for the block tour) and <code>
        <slug>.ts
      </code>
      
      , among them <code>
        structure.ts
      </code>
      
       (one brief, flat and structured), <code>
        blocks.ts
      </code>
      
       (the block tour) and <code>
        json-markdown.ts
      </code>
      
       (a release note as JSON and as Markdown, a lossy and an invalid document); the round-trip comparison of the JSON & Markdown page is <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/editor/kitchen-sink/round-trip.ts" rel="nofollow">
        <code>
          app/editor/kitchen-sink/round-trip.ts
        </code>
      </a>
      
      ; assets <a href="https://github.com/skaile-ai/forge-editor/blob/main/public/demo/diagramm.svg" rel="nofollow">
        <code>
          public/demo/diagramm.svg
        </code>
      </a>
      
       and <a href="https://github.com/skaile-ai/forge-editor/blob/main/public/demo/protokoll.txt" rel="nofollow">
        <code>
          protokoll.txt
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      The host's <code>
        decision
      </code>
      
       Block type, used by Content blocks, Minutes and Advanced
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/editor/kitchen-sink/decision.ts" rel="nofollow">
        <code>
          app/editor/kitchen-sink/decision.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Layout of the kitchen sink: navigation built from the registry, back to „Dokumente“, links to the standalone examples, and the English copy of the editor context
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/layouts/kitchen-sink.vue" rel="nofollow">
        <code>
          app/layouts/kitchen-sink.vue
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Accent colours, gallery and page-enter animations
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/assets/css/kitchen-sink.css" rel="nofollow">
        <code>
          app/assets/css/kitchen-sink.css
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      The own block as a feature: node, node view, styles, feature (toolbar, <code>
        /
      </code>
      
      , hover menu, conversion) and conversion provider; walked through in the <a href="https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b">
        tutorial
      </a>
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/tree/main/app/editor/callout" rel="nofollow">
        <code>
          app/editor/callout/
        </code>
      </a>
      
      : <code>
        node.ts
      </code>
      
      , <code>
        CalloutView.vue
      </code>
      
      , <code>
        index.ts
      </code>
      
      , <code>
        callout.css
      </code>
      
      , <code>
        feature.ts
      </code>
      
      , <code>
        convert.ts
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The Epikrise domain: Block types as data (properties, AI brief) and the host feature that supplies example paragraphs
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/editor/epikrise/kinds.ts" rel="nofollow">
        <code>
          app/editor/epikrise/kinds.ts
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/editor/epikrise/feature.ts" rel="nofollow">
        <code>
          feature.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Module registration (<code>
        @skaile/forge-editor/nuxt
      </code>
      
      )
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/nuxt.config.ts" rel="nofollow">
        <code>
          nuxt.config.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Ports plugin: <code>
        provideEditorServer
      </code>
      
       with sessions, document store, Yjs state, assets and per-user settings
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/plugins/editor-adapter.ts" rel="nofollow">
        <code>
          server/plugins/editor-adapter.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Store adapter: documents, Yjs state, assets, settings, users on the file system
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/utils/documents.ts" rel="nofollow">
        <code>
          server/utils/documents.ts
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/utils/state.ts" rel="nofollow">
        <code>
          state.ts
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/utils/assets.ts" rel="nofollow">
        <code>
          assets.ts
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/utils/settings.ts" rel="nofollow">
        <code>
          settings.ts
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/utils/users.ts" rel="nofollow">
        <code>
          users.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Showcase seeded into a fresh store: fixed document and block ids (so the documents can reference, embed and collect each other), one module per document, and the seeding step of <code>
        ensureStore
      </code>
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/tree/main/shared/showcase" rel="nofollow">
        <code>
          shared/showcase/
        </code>
      </a>
      
       (<code>
        ids.ts
      </code>
      
      , <code>
        build.ts
      </code>
      
      , <code>
        index.ts
      </code>
      
      , one <code>
        <slug>.ts
      </code>
      
       per document), <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/utils/showcase.ts" rel="nofollow">
        <code>
          server/utils/showcase.ts
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/server/utils/store-root.ts" rel="nofollow">
        <code>
          server/utils/store-root.ts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      File drawer: <code>
        DocumentTree
      </code>
      
       over the host's <code>
        DocumentStore
      </code>
      
       (routes, <code>
        $fetch
      </code>
      
      , toasts, delete-with-undo), selected folder held by the layout
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/layouts/default.vue" rel="nofollow">
        <code>
          app/layouts/default.vue
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/components/AppDocumentTree.vue" rel="nofollow">
        <code>
          app/components/AppDocumentTree.vue
        </code>
      </a>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/composables/useDocumentStore.ts" rel="nofollow">
        <code>
          app/composables/useDocumentStore.ts
        </code>
      </a>
      
       (the <code>
        .cdoc
      </code>
      
       export button comes in through the <code>
        document-actions
      </code>
      
       slot; the format stays in the host)
    </td>
  </tr>
</tbody>
</table>

The pages and their components import only public entries: `AdvancedEditor` and `advancedEditor` from `@skaile/forge-editor/vue/advanced`, `SimpleEditor` from `@skaile/forge-editor/vue/simple`, `EditorToolbar`, `EditorSettingsModal`, `EditorSettingsPanel`, `EditorSurface`, `useEditorUi`, `useEditorContext`, `useEditorSettings` and `useEditorI18n` from `@skaile/forge-editor/vue`, the `StructureMode` type and `EDITOR_SETTINGS_DEFAULTS` from `@skaile/forge-editor/settings`, `parseBlocks` and the `BlockAction`/`AbilitiesOptions` types from `@skaile/forge-editor/core`, `ROOT_ABILITIES` and `ABILITY` from `@skaile/forge-editor/core/schema`, `AiSidebar` from `@skaile/forge-editor/ai/vue`, `CommentsMargin` from `@skaile/forge-editor/comments/vue`, `CompositeTable`/`CompositeInspector` from `@skaile/forge-editor/composites/vue`, `defaultBlockTypes` from `@skaile/forge-editor/composites`, `EditorOutline` from `@skaile/forge-editor/outline/vue`, `DocumentTree` from `@skaile/forge-editor/tree/vue` (the `DocumentStore` type from `@skaile/forge-editor/tree`) and the add-ons' `/client` and `/vue` entries. The callout files add `command`, `ConversionProvider` and the conversion helpers from `@skaile/forge-editor/core`. The app-level editor context (settings sync, fetch, public AI configuration) comes from the Nuxt module, no per-page setup. The React counterpart of the document page is [`examples/react-advanced`](https://github.com/skaile-ai/forge-editor/tree/main/examples/react-advanced) ([Advanced editor in React](https://skaile-ai.github.io/forge-editor/guides/advanced-react)).

## Runnable examples

- **Plain Vue, no backend:** [`examples/vue-simple`](https://github.com/skaile-ai/forge-editor/tree/main/examples/vue-simple) — `SimpleEditor` with a sibling toolbar and heading outline, JSON `v-model`, read-only toggle, external replacement, host `/datum` command and an own block, the „Hinweis“ callout, added through the `extensions` and `commands` props (`/hinweis`, `Mod-Shift-h`, tone select, `!!!` Markdown form). A sample picker loads five demo documents (Start, Formatierung, Gliederung, Hinweise, and „Ungültig (Block-JSON)“, which the simple schema rejects through `contentError`); next to the editor the JSON (with block IDs) and the Markdown of the document are shown.
- **Plain React, no backend:** [`examples/react-simple`](https://github.com/skaile-ai/forge-editor/tree/main/examples/react-simple) — the same document picker, read-only toggle and JSON/Markdown panes with the React layer: `EditorToolbar` beside `EditorSurface` over `defineEditor({ features: [coreContentFeature(), coreUiFeature(), mentionsFeature()] })`, the host `/` commands, `@` mentions from `metadata`, and rejected content through `onContentError`. Vite, Tailwind 4 and shadcn tokens, no Nuxt UI.
- **Advanced, Nuxt:** this repository's application (`bun run dev`, port 3056) — collaborative documents under switchable demo users (no login: `server/middleware/demo-session.ts` signs every API request into a demo user, `server/api/auth/switch.post.ts` switches it; `app/pages/documents/[id].vue`), the file drawer with `DocumentTree` and a host `DocumentStore` (`app/components/AppDocumentTree.vue`, `app/composables/useDocumentStore.ts`), and the kitchen sink: fifteen standalone pages under their own layout without the document tree (`/kitchen-sink`, `app/pages/kitchen-sink/`), in three tracks: Basics (Flat and Structure mode, content blocks, JSON and Markdown, block actions, editor settings), Building blocks (`SimpleEditor` with AI, `AdvancedEditor` host props, `EditorSurface` with the callout feature in `app/editor/callout/`) and Use cases (minutes, slides, databases and charts, scientific writing, podcast, knowledge base, Epikrise review), all on the shared `KitchenSinkPage` shell. Each kitchen-sink page shows its own builtin Obsidian theme (`theme` of its registry entry, pinned by the layout with `pinObsidianTheme`; see [Themes](https://skaile-ai.github.io/forge-editor/guides/themes)). Everywhere else the Theme settings tab („Theme“) switches the whole site between the Default appearance („Standard“) and the fifteen builtin Obsidian themes (`server/themes/`: Nord, Things, Minimal, Catppuccin, Border, Blue Topaz, Tokyo Night, Flexoki, Cupertino, Prism, iA Writer, Shimmering Focus, Gruvbox, Rosé Pine, Solarized) or an uploaded one, served by the adapter in `server/plugins/editor-adapter.ts`. Walkthrough: see above. How to add a block of your own: the [tutorial](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b).
- **Advanced, React:** [`examples/react-advanced`](https://github.com/skaile-ai/forge-editor/tree/main/examples/react-advanced) (`bun run --cwd examples/react-advanced dev`, port 3043; needs the Nuxt app running, Vite proxies `/api` and `/collab` to it) — the React counterpart of the Nuxt document page: a document picker over the editor's `/api/editor/documents`, a collaborative `AdvancedEditor` over `HocuspocusProvider` as the demo session's user, `EditorToolbar`, `EditorSettingsModal`, `CommentsMargin`, `CompositeTable`/`CompositeInspector`, `EditorOutline`, `AiSidebar`, `DocumentTree` over an `/api` adapter of `DocumentStore`, and `Toaster`. Vite, Tailwind 4 and shadcn tokens, no Nuxt UI, no Vue.


# Advanced editor in React

> Mount the collaborative AdvancedEditor on React with the chrome components beside it, over the same backend as the Vue surface.

`AdvancedEditor` from `@skaile/forge-editor/react/advanced` is the React counterpart of the Vue `AdvancedEditor`: an `EditorSurface` over `composeEditor` of its `content`, `interaction`, `ai`, `add`, `remove` and `backend` props (defaults `{ content: 'rich', interaction: 'full', ai: true }`, i.e. `advancedEditor()`), which lists every feature and integration (`core-content`, `core-ui`, `media`, `transcript`, `composites`, `mentions`, `authors`, `comments`, `ai`, `collab`, `block-ui`, `composite-media`, `composite-ai`, `transcript-ai`, `themes`) with its React binding, in the same schema order as the Vue surface. It uses no Vue, Nuxt UI or Nuxt module. The runnable reference is [`examples/react-advanced`](https://github.com/skaile-ai/forge-editor/tree/main/examples/react-advanced) (`bun run --cwd examples/react-advanced dev`, port 3043): the React counterpart of the Nuxt document page. It reuses the Nuxt app's documents, session and collaboration socket through the Vite proxy (`/api`, `/collab`), so start the Nuxt app first (`bun run dev`, port 3056).

**Setup** is the [simple React setup](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-react#setup) plus three things:

- **Styles.** Replace the three library imports by one: `@import "@skaile/forge-editor/react/styles/advanced.css";` after `tailwindcss` and `tw-animate-css` (it imports `ui-vars.css`, `core.css`, every feature sheet and `themes.css` last, plus the bridge that lets an Obsidian theme restyle the shadcn tokens). Keep the `@source` for the library's whole `dist` (`src` in this repository, as the example does) and the shadcn theme block; `examples/react-advanced/src/index.css` has a complete copy.
- **Notices.** Create the context with `createEditorContext({ notify: reactNotifier })` and render sonner's `<Toaster />` once inside the provider (both exported by `@skaile/forge-editor/react`). Features send `Notice`s to the surface's notifier (import problems, AI rate limits, comment errors, „Dokument gelöscht“ with undo in the tree); without `<Toaster />` none is visible.
- **Dependencies.** The simple setup's list plus `sonner` (the `Toaster` and the notice seam), `yjs` and `@hocuspocus/provider` for collaboration; use the exact version ranges of the [example's `package.json`](https://github.com/skaile-ai/forge-editor/blob/main/examples/react-advanced/package.json).

`main.tsx`:

```tsx [examples/react-advanced/src/main.tsx]
import lucide from '@iconify-json/lucide/icons.json'
import { addCollection } from '@iconify/react'
import { createHttpBackend } from '@skaile/forge-editor/adapters/http'
import { createEditorContext } from '@skaile/forge-editor/core'
import { EditorContextProvider, reactNotifier, Toaster } from '@skaile/forge-editor/react'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { App } from './App'
import './index.css'

// Preload the icon set: the page makes no request to the Iconify API.
addCollection(lucide)

// The host owns the context; the provider never disposes it. The backend is the HTTP one (`/api/editor` over the Nuxt host,
// the collaboration websocket `/collab/<id>`); the backend offers `settings`, so they sync with the host's account store,
// notices of app-level models become sonner toasts.
const context = createEditorContext({ backend: createHttpBackend(), notify: reactNotifier })

createRoot(document.getElementById('app')!).render(
  <StrictMode>
    <EditorContextProvider context={context}>
      <App />
      <Toaster />
    </EditorContextProvider>
  </StrictMode>,
)
```

The example passes `createHttpBackend()` so settings sync with the host's `/api/editor/settings`; pass `createMemoryBackend()` for local-only settings.

**The page.** The chrome components beside the editor take the editor from `onReady` and find its preset through it. `AdvancedEditor` takes the surface's props except `preset`, plus the composition props (`content`, `interaction`, `ai`, `add`, `remove`, `backend`, `blockTypes`, `blockUi`, `coreContent`, read once at mount); `<AdvancedEditor remove={['tables']} ai={false} />` is the advanced editor without tables and AI:

```tsx
import { AiSidebar } from '@skaile/forge-editor/ai/react'
import { CommentsMargin } from '@skaile/forge-editor/comments/react'
import { CompositeInspector } from '@skaile/forge-editor/composites/react'
import type { CollaborationSession } from '@skaile/forge-editor/core'
import { EditorSettingsModal, EditorToolbar } from '@skaile/forge-editor/react'
import { AdvancedEditor } from '@skaile/forge-editor/react/advanced'
import type { Editor } from '@tiptap/core'
import { useState } from 'react'

export function Page({ id, session }: { id: string, session: CollaborationSession }) {
  const [editor, setEditor] = useState<Editor>()
  const [scrollEl, setScrollEl] = useState<HTMLElement | null>(null)
  const [settingsOpen, setSettingsOpen] = useState(false)
  const [sidebarOpen, setSidebarOpen] = useState(false)
  const [commentsOpen, setCommentsOpen] = useState(false)

  return (
    <>
      <EditorToolbar editor={editor} />
      <main ref={setScrollEl} className="relative flex min-h-0 flex-1 overflow-auto">
        <AdvancedEditor
          key={id}
          collaboration={session}
          documentId={id}
          settingsUi="external"
          sidebarOpen={sidebarOpen}
          onSidebarOpenChange={setSidebarOpen}
          commentsOpen={commentsOpen}
          onCommentsOpenChange={setCommentsOpen}
          onReady={setEditor}
          onSettingsOpen={() => setSettingsOpen(true)}
        />
        <CommentsMargin editor={editor} container={scrollEl} open={commentsOpen} />
      </main>
      <CompositeInspector editor={editor} />
      <AiSidebar editor={editor} open={sidebarOpen} onOpenChange={setSidebarOpen} />
      <EditorSettingsModal editor={editor} open={settingsOpen} onOpenChange={setSettingsOpen} />
    </>
  )
}
```

Notes:

- **Collaboration.** The `session` is `{ ydoc, provider, user }` (`CollaborationSession` from `@skaile/forge-editor/core`): create the `Y.Doc` and the `HocuspocusProvider` in an effect (so StrictMode's double mount leaves exactly one provider), destroy the provider in its cleanup, and key the editor by document so a new document is a new Y.Doc ([Collaboration on the client](https://skaile-ai.github.io/forge-editor/guides/collaboration)). Without `collaboration` pass `value`/`onChange` for a standalone editor (the collaboration and comments features then contribute nothing).
- **Beside the editor.** `EditorToolbar`, `EditorSettingsModal`/`EditorSettingsPanel`, `CommentsMargin`, `CompositeTable`, `CompositeInspector`, `AiSidebar`, `EditorOutline` and `DocumentTree` are components you place; each takes the `editor` from `onReady`. `useEditorUi(editor)` returns the chrome of a ready editor (`openSettings(tab?)`, `toggleSidebar()`, `toggleComments()`, `commentsOpen`, `togglePalette()`, `paletteOpen`) for your own buttons.
- **Own features.** Pass them as `add={[myFeature()]}` (appended after the catalog), or build the preset for an `EditorSurface` yourself: `advancedEditor({ add: [myFeature()] })`, as in the Nuxt app's kitchen sink (`app/pages/kitchen-sink/surface.vue`).
- **The file browser** is [`DocumentTree` from `@skaile/forge-editor/tree/react`](https://skaile-ai.github.io/forge-editor/guides/document-tree) over a `DocumentStore`; the example wires it to the host's `/api`.
- **Backend.** The same as for the Vue advanced editor: `/collab/:id`, the AI endpoints, assets, users/tags and themes of the Nuxt module and a host adapter ([Nuxt module](https://skaile-ai.github.io/forge-editor/guides/nuxt-module) and [EditorPorts](https://skaile-ai.github.io/forge-editor/guides/editor-ports)). A React app with its own server brings the same routes.


# AI

> Add AI to an editor: selection menu, sidebar, ghost text, backend endpoints, integrations with Typed blocks and transcripts, agent operations and fence formats.

## AI on a core editor

`aiFeature()` adds the AI features to a core editor: selection menu (rewrite tasks such as shorter/formal/translate and free prompts), the `/ai` command and a „KI" toolbar group, in-document review of rewrites (accept/reject per change), ghost autocomplete while typing (Tab accepts, Esc dismisses), model profiles and the `ai` settings tab. The sidebar (document chat and block generation, `AiSidebar` from `@skaile/forge-editor/ai/vue/chat`) and the quick model switch are components you place yourself; only the sidebar needs `@skaile/forge-chat`. `aiFeature()` and everything else in `/ai/vue` load without it. It needs no Typed blocks, transcript, media, mentions or Yjs; `bun run check:editor-entries` proves it with a `core + ai` fixture.

```vue
<script setup lang="ts">
import { aiFeature, AiReviewBar, ModelQuickSwitch } from '@skaile/forge-editor/ai/vue'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { EditorSurface, EditorToolbar } from '@skaile/forge-editor/vue'
import type { Editor } from '@tiptap/vue-3'
import { shallowRef } from 'vue'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), aiFeature()] })
const editor = shallowRef<Editor>()
const sidebarOpen = shallowRef(false)
</script>

<template>
  <EditorToolbar :editor="editor" />
  <div class="flex">
    <EditorSurface v-model="content" v-model:sidebar-open="sidebarOpen" :preset="preset" class="flex-1" @ready="editor = $event" />
    <AiSidebar v-model:open="sidebarOpen" :editor="editor" class="w-[380px]" />
  </div>
</template>
```

`aiFeature()` needs no component setup: the model profiles come from the app's editor context (`createEditor()` installed as a Vue plugin; `createEditorContext()` on React), and its notices (rate limits, import problems) go to the surface's notifier. The React binding is `aiFeature()` from `@skaile/forge-editor/ai/react` with the same components and hooks (`useAiAssistant`, `useDocumentChat`, `useModelProfiles`); the framework-free `@skaile/forge-editor/ai` holds `aiFeatureCore(ui)` and the models behind the hooks (`createAiAssistant`, `modelProfiles`). Import the CSS after `core.css`:

```css
@import "@skaile/forge-editor/styles/ai.css";
```

The Vue `AiSidebar` (`@skaile/forge-editor/ai/vue/chat`) renders on `@skaile/forge-chat` (its `ChatPanel`), an **optional peer** of the editor package: install it only when you place the sidebar. Importing `/ai/vue/chat` without it throws an error that names `@skaile/forge-chat` when the module loads unbundled (Node, SSR); in a bundled host (Vite, Nuxt) the bundler's own resolve error for `@skaile/forge-chat` appears first. The entry uses a top-level `await`, so the host's build target must be ES2022 or later. The chat resources belong to the host, not to `ai.css` or the editor's Nuxt module:

```css
@import "@skaile/forge-chat/styles/chat.css";
@source "../../../node_modules/@skaile/forge-chat/dist"; /* Tailwind skips node_modules; relative path from this CSS file */
```

In a Nuxt host also add `'@skaile/forge-chat/nuxt'` to `modules` after `'@nuxt/ui'`: it transpiles the package and lets Nuxt resolve its Nuxt UI components.

Components: `AiSidebar` (`editor`; `v-model:open`), `ModelQuickSwitch` (`slot`: the Model role, optional `size` and `editor`; the choice applies to the whole Model role; `editor` makes „Modelle verwalten…" open that editor's settings when the switch sits outside an `EditorSurface`), `AiReviewBar` (`editor`). `AiSelectionMenu` and `AiReviewBar` are overlays the surface mounts for the feature; they are exported for hosts that render their own editor chrome.

### Backend contract and configuration

The feature talks to its endpoints through the backend's `ai` port (`EditorContext.backend.ai`; the default HTTP backend calls the routes below, same origin; a host with another transport passes its own `EditorBackend`). You provide the endpoints; the handlers in `packages/editor/src/server/handlers/ai.ts` (mounted by `installEditorServer`, route table `packages/editor/src/server/routes.ts`) are the reference implementation and import the shared protocol from the package:

<table>
<thead>
  <tr>
    <th>
      Endpoint
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/ai/models
      </code>
    </td>
    
    <td>
      <code>
        { presets: ModelProfile[], roles: Record<ModelRole, string> }
      </code>
      
       — the server Model presets as Model profiles (no keys) and the default Model preset per Model role (<code>
        complete
      </code>
      
      , <code>
        rewrite
      </code>
      
      , <code>
        generate
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
    
    <td>
      SSE (<code>
        delta
      </code>
      
       / <code>
        done
      </code>
      
       / <code>
        error
      </code>
      
      ) for selection tasks and block generation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/ai/chat
      </code>
    </td>
    
    <td>
      SSE for the sidebar's document chat with edit operations
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/ai/complete
      </code>
    </td>
    
    <td>
      <code>
        { text }
      </code>
      
       continuation for ghost autocomplete
    </td>
  </tr>
</tbody>
</table>

The framework-free protocol (`AI_TASKS`, `AiTask`, `AiInput`, `ModelRef`, `ModelProfile`, `modelRefSchema`, `aiBlockSchema`, `AGENT_OP_TYPES`, `checkAgentOps`, `CHAT_LIMITS`, `AI_COMPLETE_LIMITS`, `AI_LIMITS`, …) is exported from `@skaile/forge-editor/ai` (and `/ai/protocol`), so a server may import the same constants and Zod schemas. A 429 from any endpoint shows one German „Zu viele KI-Anfragen, bitte kurz warten“ toast instead of an error.

Without a server these endpoints are replaced by `createDirectAi` (`@skaile/forge-editor/adapters/direct-ai`): an `ai` backend that runs `generate`, `complete`, `models` and `transcriptCleanup` against an OpenAI-compatible endpoint from the browser with the same protocol modules (`runGenerate`, `runCompletion`, `runTranscriptCleanup`). The key then lives in the page (the sentence below about keys holds for the server routes only), no rate limit applies, and the document chat and `extract` answer 501. See [Browser-direct AI](https://skaile-ai.github.io/forge-editor/guides/storage-adapters#browser-direct-ai).

Public AI configuration is inert data passed to `createEditor`:

```ts
app.use(createEditor({ ai: { roles: { complete: 'flashLite', rewrite: 'sonnet', generate: 'sonnet' }, transcription: false } }))
```

`roles` are the default Model preset IDs per Model role until the user chooses one in the `ai` settings tab (stored in `settings.ai.roles`). API keys never reach the client: user-added profiles with their own endpoint/key are kept in this browser's `localStorage` only. In Nuxt the module's `tiptapEditor.ai` options (Model presets, default Model preset per Model role, rate limit) and the env keys `NUXT_TIPTAP_EDITOR_AI_API_KEY` / `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY` supply the server side.

### Extending what AI knows about the document

By default the AI sees a flat document with no custom Block types and no Host blocks. Features adjust that through three optional hooks on `EditorFeature`:

- `aiContext: (editor) => ({ blockTypes?, blocks?, structure? })` — what the model may build and how. It is **additive**: any number of features may contribute. `defineEditor` merges the contributions, concatenating `blockTypes` and `blocks` in feature order; `structure` (the Structure mode for generated content, `'flat'` | `'structured'`) may be set by one feature only. A block `id` described by two features, or a second feature setting `structure`, throws when the merged context is read (`aiContextOf(editor)`, which returns `{ blockTypes, blocks, structure }`), not when `defineEditor` runs.

  - `blockTypes` — the Block types of Typed blocks the model may build (`AiContextBlockType`: `id`, `label`, `fields` as Property definitions, `purpose?`). The composites feature contributes them.
  - `blocks` — Host blocks as `AiBlock { id, label, description, syntax, example }` (exported from `@skaile/forge-editor/core`): `id` is the node type name and the `convert` target id, `label` the German name, `description` its purpose and allowed content, `syntax` the Markdown form with placeholders in angle brackets, `example` one complete example. The document chat and the generate tasks (sidebar and selection menu) list them in the system prompt and send them with the request, so the model can write them; the chat offers a block as `convert` target when a registered conversion provider parses its id. See [tutorial chapter on AI](https://skaile-ai.github.io/forge-editor/tutorial/ai) for the callout's contribution.
- `formatAiResult: (editor, markdown, heading?) => string` — formats an AI result's Markdown (with the optional task heading) before the generic parse/normalize/structure pipeline. Without a contributor the result gets the normalized heading (`withHeading`); the `composite-ai` integration (below) contributes the Typed block form for Structure mode. At most one feature may contribute it; `defineEditor` throws on a second one.
- `aiBlockData: ({ editor, node, pos, signal }) => AiBlockDatum[] | Promise<AiBlockDatum[]>` — material a feature supplies for one Typed block before „Block füllen (KI)“ asks the model (`AiBlockDatum { label, text }`; the three types are exported from `@skaile/forge-editor/core`). It is **additive**: every contributor runs for the Typed block in parallel, and `defineEditor` concatenates their entries in feature order (`aiBlockDataOf(editor)` returns the merged provider; without contributors it resolves to no data). The library only collects: the fetch, the ranking and what the entries mean belong to your feature. `signal` aborts when the editor is destroyed. A contributor that throws or rejects cancels the fill with the notice „Daten für den Block fehlen“, and no generate request is sent. The kitchen sink's `epikriseFeature()` (`app/editor/epikrise/feature.ts`, on `/kitchen-sink/epikrise`) fetches two example paragraphs from its own route for the reason-for-admission Block type.

AI results are parsed with `parseBlocks(editor, markdown)`: inline replacements use the pre-segmentation `parsed` content, block insertion uses `blocks`.

### Positions and collaboration

Selection menu, sidebar and review capture ranges as document anchors. Without an `anchorResolver` anchors map through local transactions only, and the review writes with a `closeHistory` step so rewriting does not merge into typing. A collaboration feature contributes an `AnchorResolver` that keeps anchors valid across remote edits and wraps the review's undo step; the AI feature imports no Yjs code either way.

## AI integrations: Typed block AI and transcript AI

`aiFeature()` knows neither Typed blocks nor transcripts. Two integration features connect it to them; each imports only the features it names, no parent feature imports the integration, so `core + ai`, `core + composites` and `core + transcript` bundles stay free of them (`bun run check:editor-entries`: fixtures `composite-ai` and `transcript-ai` allow exactly their features plus the integration, and the `ai`, `composites` and `transcript` fixtures forbid any integration module).

<table>
<thead>
  <tr>
    <th>
      Factory (<code>
        @skaile/forge-editor/integrations/…
      </code>
      
      )
    </th>
    
    <th>
      <code>
        requires
      </code>
    </th>
    
    <th>
      Contributes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        composite-ai
      </code>
      
       → <code>
        compositeAiFeature()
      </code>
    </td>
    
    <td>
      <code>
        composites
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        media
      </code>
    </td>
    
    <td>
      block actions „Block füllen (KI)“ (Block types with the <code>
        ai-brief
      </code>
      
       capability), „Zusammenfassung erzeugen (KI)“, “Create readable rendition” (English label), „Neu erzeugen (ersetzen)“, „Ableiten (KI)“, „Literaturangaben abrufen“, „Mit KI in Unterblöcke teilen“ / „Mit KI in Blöcke teilen“ and „Gliederung bereinigen (KI)“ (also a ⌘K command); the single <code>
        formatAiResult
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcript-ai
      </code>
      
       → <code>
        transcriptAiFeature()
      </code>
    </td>
    
    <td>
      <code>
        transcript
      </code>
      
      , <code>
        ai
      </code>
    </td>
    
    <td>
      block action „Transkript bereinigen (KI)“ and the same row in the AI selection menu
    </td>
  </tr>
</tbody>
</table>

```ts
import { aiFeature } from '@skaile/forge-editor/ai/vue'
import { compositeFeature } from '@skaile/forge-editor/composites/vue'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { compositeAiFeature } from '@skaile/forge-editor/integrations/composite-ai'
import { compositeMediaFeature } from '@skaile/forge-editor/integrations/composite-media'
import { transcriptAiFeature } from '@skaile/forge-editor/integrations/transcript-ai'
import { mediaFeature } from '@skaile/forge-editor/media/vue'
import { mentionsFeature } from '@skaile/forge-editor/mentions'
import { transcriptFeature } from '@skaile/forge-editor/transcript/vue'

// The integrations are framework-free and fit both surfaces; on React take the bindings from `/<x>/react`.
const preset = defineEditor({
  features: [
    coreContentFeature(), coreUiFeature(), mediaFeature(), transcriptFeature(), compositeFeature(), mentionsFeature(), aiFeature(),
    compositeMediaFeature(), compositeAiFeature(), transcriptAiFeature(),
  ],
})
```

Install each integration after the features it requires (the order of the list is the order of toolbar/menu entries; actions carry their own `order`). `defineEditor` throws `feature "composite-ai" requires "ai", which is not installed` (likewise for `composites`, `media`, and for `transcript-ai` without `transcript` or `ai`) — it never installs a missing dependency. `bun run check:editor-composition` loads the real modules and asserts every one of these rejections, the accepted full composition and the single-`formatAiResult` rule. CSS: the stylesheets of the features in the preset (`core.css`, `media.css`, `composites.css`, `transcript.css`, `ai.css`); the integrations bring none.

**compositeAiFeature()**

- **Fill a Typed block.** „Block füllen (KI)“ appears on a Typed block whose Block type has the `ai-brief` capability (its config is the AI brief, `BlockTypeAi`). It sends the block's brief (`compositeAiBrief(editor, pos)`: Block type and `purpose`, titles of the enclosing Typed blocks as `path`, title, description, non-empty property values with `select` option labels, the instruction — a non-empty `meta[ai.instructionsField]` replaces `ai.instructions` — and the AI content template (`ai.contentTemplate`) with `{key}` replaced by `meta[key]`, the current body as Markdown) plus the document as context to the task `fill-block` (`generate` Model role, `POST /api/ai/generate`, rejected with 400 when `block` is missing). The result opens the in-document diff review over the block's body; title and properties stay untouched. `fill-block` is offered nowhere else (`blockTasks()` skips tasks with `needsBlock`).
- **Material from features.** Before the request, `fillComposite` runs the Editor preset's merged `aiBlockData` for the Typed block (above). The entries travel as `block.data` in order, at most 10, each `text` cut to `AI_LIMITS.block.data` (20000) characters; the task prompt prints each as `<label>:` followed by the quoted text.
- **Typed block summary.** „Zusammenfassung erzeugen (KI)“ appears on a Typed block whose body has text (readable renditions included). It streams a `summarize` task (`rewrite` Model role) from `POST /api/ai/generate` and replaces the block's description with it; the details popover shows it as the summary. The description is anchored when the request starts, so edits made while it streams do not misplace the result.
- **Readable rendition.** “Create readable rendition” appears on a Typed block whose Block type has the `source` capability, i.e. holds a Source (the built-in `document`, `recording`, `paper`, `book`, `figure`) and whose Source media block (`audio|video|image|file` in the body, found by `sourceOf`) is a stored asset; for an audio/video source only when the app's public AI configuration has `transcription: true` (`createEditor({ ai: { transcription } })`). It calls `backend.ai.extract` (HTTP: `POST /api/ai/extract`, `method: 'auto'`, `bibliography` when the Block type has a `bibliography` property) and adds a Rendition block (Block type `rendition`) right after the Source media block: timestamped `transcriptSegment`s (with the transcript feature; else paragraphs) for a recording, the structured full text for a PDF (chapters become nested `section` Typed blocks in Structure mode; page boundaries become italic „S. N“ paragraphs), the description for an image. Its title is „Transkript“, „Volltext“, „Volltext (OCR)“ or „Beschreibung“, and `meta.derivation` records asset, method, the model that wrote the content (the speech-to-text model of a transcription, the chat model for OCR and a description, none for the PDF text layer), the asset hash (`inputHash`), the hash of the written body's Markdown (`outputHash`) and the stored raw output. Bibliographic data the server found fills an empty `meta.bib` (never its `title`) and an empty Typed block title; server `warnings` (`ocr-unavailable`, `ocr-truncated`, `crossref-unavailable`, `pages-truncated`, `bibliography-failed`) show as a notice. A second run adds another version. „Neu erzeugen (ersetzen)“ on an asset-derived readable rendition replaces it in place and keeps its block id; when its body was edited since (`outputHash` differs) a warning notice offers „Trotzdem ersetzen“ first. The Typed block is anchored through its description when the request starts, so edits while it runs do not misplace the result. Existing Typed blocks of type `document` with the former flat `meta.transcript` are migrated into such a Readable rendition child on load (also for documents with stored collaboration state). Your server provides the endpoint; `extractPost` in `packages/editor/src/server/handlers/ai.ts` is the reference.
- **Derive.** „Ableiten (KI)“ (a menu of every Block type with an AI brief, `derivableBlockTypesOf`) appears on a Typed block with a block ID (`isDerivableSource`) wherever a Typed block of that Block type may follow it (`canDeriveAfter`). It inserts a sibling Typed block, a Derived block, titled `<Block type>: <source title>` with `meta.derivation = { from: { block }, method: 'ai:<kind>', inputHash }`, generates its body from the source's Markdown with the `fill-block` brief (`generateCompositeBody`, the request part of `fillComposite`) and writes it directly; an empty or failed result removes the new Typed block again. On a Rendition block it produces a translation or a summary as a rendition of a rendition.
- **Literaturangaben abrufen.** The block action „Literaturangaben abrufen“ (and the bibliography editor's „DOI abrufen“, through the editor command `fetchCompositeBibliography`) appears on a Typed block whose Block type has a `bibliography` property and that has a DOI (`meta.doi` or `meta.bib.DOI`, read by `doiOf`) or a stored PDF source. It calls `backend.ai.extract` with `method: 'bibliography'` (Crossref by DOI, else model extraction from the first pages) and stores the CSL result in `meta.bib`; an empty Typed block title takes the work's title.
- **AI results in Structure mode.** With the `structured` structure setting (Structure mode), an AI result that carries a heading (sidebar „block generation“, selection/menu tasks with a heading) is formatted as a `section` fence (`::: section` with the heading and the result inside), so the generic pipeline inserts it as a `section` Typed block. In Flat mode (`flat`), or without a heading, the result is unchanged from the base AI behaviour. The feature is the preset's only `formatAiResult` contributor — the base AI feature stays free of Typed blocks.
- **Exports** (`@skaile/forge-editor/integrations/composite-ai`): `compositeAiFeature`, `fillComposite(editor, pos, flow)`, `generateCompositeBody(editor, pos, flow, signal)` (with `CompositeBodyResult`), `summarizeComposite(editor, pos, flow)` (`flow` is an `AiFlowContext`: `{ ai, modelRef, notify, t }`, exported too), `createRendition(editor, pos, flow, options?: RenditionOptions)` (`{ replace? }`), `regenerateRendition(editor, pos, flow)`, `canCreateRendition(editor, node, transcription)`, `canRegenerateRendition(editor, node, pos, transcription)`, `deriveComposite(editor, pos, kindId, flow)`, `canDeriveAfter`, `derivableBlockTypesOf`, `isDerivableSource`, `fetchBibliography(editor, pos, flow, documentId?)`, `canFetchBibliography`, `doiOf`, `compositeSourceText`, `COMPOSITE_BODY_START` (`ai` is `backend.ai`). Notices go through the surface's `notify` in the language of `t` (`ctx.t`), the model through `modelProfiles(app)`.
- **Splitting and outline cleanup.** `splitCompositeWithAi(editor, pos, mode, flow, { targetChars, defaultBlockType })` (`mode`: `'children'` or `'siblings'`; the model only inserts `##` headings, `bodyUnchanged` guards that the text is unchanged, `splitByInsertedHeadings` is the pure grouping) and `sanitizeOutline(editor, flow)` (the repaired outline in one transaction; `collectHeadings`, `parseOutlineResponse`, `applyOutline` are the pure parts, `OutlineHeading` and `OutlineEntry` the types). Both are exported from `@skaile/forge-editor/integrations/composite-ai` and explained, with the manual and length splits, in [Content tree mechanics](https://skaile-ai.github.io/forge-editor/guides/content-tree#splitting-a-typed-block). `writeDerivedBody` and `discardDerived` (the write-back of „Ableiten (KI)“) are exported too; the [transfer](https://skaile-ai.github.io/forge-editor/guides/content-tree#block-transfer) transforms reuse them.

**transcriptAiFeature()**

- **Transcript cleanup.** „Transkript bereinigen (KI)“ is a block action on a speaker segment or a block (Typed block, quote, list) holding segments, and „Transkript bereinigen“ is a row of the AI selection menu over a selection that overlaps segments. It sends `{ id, speaker, text }` per segment to `POST /api/ai/transcript-cleanup` and opens the cleaned texts as an in-document AI review, one change per segment. The model returns only new texts keyed by block ID, so speakers, order and segment count cannot change; over-long, stale and unusable segments are skipped with a German notice. Without `transcriptAiFeature()` neither the action nor the menu row exists.
- **Server contract.** `@skaile/forge-editor/integrations/transcript-ai/protocol` is Vue-free and server-importable: `TRANSCRIPT_CLEANUP_LIMITS`, `transcriptCleanupRequestSchema`, `transcriptCleanupMessages`, `transcriptCleanupChunks`, `parseTranscriptCleanup` and the request/response types. Your endpoint validates the request with the schema, cleans in chunks and answers `{ cleaned: [{ id, text }], failed }`.
- **Exports** (`@skaile/forge-editor/integrations/transcript-ai`): `transcriptAiFeature` (its `setup` teardown aborts a running cleanup), `createTranscriptCleanup(modelRef, ai, notify, t)` (`ai` is `backend.ai`) → `{ running, cleanup, abort }`, `hasTranscriptSegments`.
- Speaker-aware transformations that normalization already covers — `**Name:** text` lines becoming segments in imported or AI-written Markdown — stay with the `transcript` feature's `segment` stage; the integration adds only the cleanup.

## Reference: AI surfaces, agent operations and Typed block fences

### In-block AI versus block generation

- **In-block AI** (`rewrite` Model role) works on text inside one block or a selection and is applied through the review diff: the selection tasks, the Typed block summary and transcript cleanup. Ghost autocomplete is in-block too but has its own `complete` Model role.
- **Block generation** (`generate` Model role) produces, replaces, converts or removes whole blocks: the tasks `generate`, `continue` and `transcript-*`, plus the chat agent operations. `fill-block` (block action „Block füllen (KI)“) is a `generate` Model role task too, but only reachable through that action.

<table>
<thead>
  <tr>
    <th>
      Surface
    </th>
    
    <th>
      What
    </th>
    
    <th>
      Model role
    </th>
    
    <th>
      Route
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Ghost autocomplete (<code>
        ai.autocomplete
      </code>
      
       setting)
    </td>
    
    <td>
      Inline continuation while typing
    </td>
    
    <td>
      <code>
        complete
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/complete
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AiSelectionMenu
      </code>
      
      , selection mode
    </td>
    
    <td>
      <code>
        reformulate
      </code>
      
      , <code>
        fix
      </code>
      
      , <code>
        shorter
      </code>
      
      , <code>
        formal
      </code>
      
      , <code>
        casual
      </code>
      
      , <code>
        translate
      </code>
      
      , <code>
        summarize
      </code>
      
       and the free prompt <code>
        custom
      </code>
    </td>
    
    <td>
      <code>
        rewrite
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AiSelectionMenu
      </code>
      
      , caret mode (<code>
        /ai
      </code>
      
      )
    </td>
    
    <td>
      <code>
        continue
      </code>
      
       („Weiterschreiben“) and the free prompt <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AiSidebar
      </code>
      
       quick actions
    </td>
    
    <td>
      <code>
        blockTasks()
      </code>
      
       without the caret tasks: <code>
        generate
      </code>
      
      , <code>
        transcript-summary
      </code>
      
      , <code>
        transcript-minutes
      </code>
      
      , <code>
        transcript-action-items
      </code>
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AiSidebar
      </code>
      
       chat agent
    </td>
    
    <td>
      Answers with citations, proposes operations (below)
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/chat
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Typed block summary (block action, <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      Task <code>
        summarize
      </code>
      
       over the Typed block's body → description
    </td>
    
    <td>
      <code>
        rewrite
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Fill a Typed block (block action, <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      Task <code>
        fill-block
      </code>
      
       over the block's brief → body, as review
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Transcript cleanup (block action, <code>
        transcript-ai
      </code>
      
      )
    </td>
    
    <td>
      Cleans transcript segment texts
    </td>
    
    <td>
      <code>
        rewrite
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/transcript-cleanup
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Readable rendition (block actions, <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      Transcript with timestamps (audio/video), full text (PDF, OCR fallback) or description (image) of a Typed block that holds a Source → Rendition child with <code>
        meta.derivation
      </code>
    </td>
    
    <td>
      <code>
        generate
      </code>
      
       for OCR/description/bibliography, none for transcription and PDF text
    </td>
    
    <td>
      <code>
        POST /api/ai/extract
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Derive (block action, <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      Task <code>
        fill-block
      </code>
      
       over the source Typed block's Markdown → body of a new sibling Typed block with <code>
        meta.derivation
      </code>
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Literaturangaben abrufen (block action, <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      <code>
        extract
      </code>
      
       with <code>
        method: 'bibliography'
      </code>
      
      : Crossref by DOI, else model extraction from the first pages → <code>
        meta.bib
      </code>
    </td>
    
    <td>
      <code>
        generate
      </code>
      
       only for the model fallback
    </td>
    
    <td>
      <code>
        POST /api/ai/extract
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Split with AI (block actions, <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      Task <code>
        split-block
      </code>
      
       over the Typed block's body: the model inserts <code>
        ##
      </code>
      
       headings, the block is split at them
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Gliederung bereinigen (KI) (block action on headings and ⌘K, <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      Task <code>
        outline-sanitize
      </code>
      
       over the document's headings as JSON → the repaired outline
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Block transfer with Shift menu (<code>
        transferFeature
      </code>
      
      )
    </td>
    
    <td>
      Tasks <code>
        transfer-summary
      </code>
      
       and <code>
        transfer-bullets
      </code>
      
       over the dragged Typed block's Markdown → body of a new Typed block with <code>
        meta.derivation
      </code>
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
</tbody>
</table>

A task's Model role comes from `AiTask.slot` (`AI_TASKS`); `ModelQuickSwitch` in the selection menu and the sidebar changes the Model role's profile in place. Inserted generation results (sidebar quick actions, `/ai` at the caret, agent `add` operations) go through the Editor preset's `structure` stage: with the composites feature and the `blocks.structure` setting `'structured'` (Structure mode), headings are grouped into nested `section` Typed blocks; with `'flat'` (Flat mode) Typed blocks are flattened into headings starting at `##`. A change of the setting applies to the next insertion. Rewrites (`replace-selection`, agent `update`) are never restructured.

### Content tree tasks

Four tasks serve the [content tree mechanics](https://skaile-ai.github.io/forge-editor/guides/content-tree). They are in `AI_TASK_IDS` and `AI_TASKS`, all in the `generate` Model role, all with `AiTask.programmatic: true`: only a block action, a command or a drop sends them, and `blockTasks()` leaves them out of the sidebar's quick actions. Each has its own prompt; a Host configures nothing but the `generate` Model role's model.

<table>
<thead>
  <tr>
    <th>
      Task
    </th>
    
    <th>
      Sent by
    </th>
    
    <th>
      <code>
        selection
      </code>
    </th>
    
    <th>
      <code>
        prompt
      </code>
    </th>
    
    <th>
      Answer
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        split-block
      </code>
    </td>
    
    <td>
      <code>
        splitCompositeWithAi
      </code>
    </td>
    
    <td>
      the Typed block's body as Markdown
    </td>
    
    <td>
      the wanted section size in characters
    </td>
    
    <td>
      the same Markdown with <code>
        ##
      </code>
      
       headings inserted; any other change makes the split write nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        outline-sanitize
      </code>
    </td>
    
    <td>
      <code>
        sanitizeOutline
      </code>
    </td>
    
    <td>
      the document's headings as a JSON list <code>
        { i, level, text, chars }
      </code>
    </td>
    
    <td>
      empty
    </td>
    
    <td>
      a JSON list of the same length <code>
        { i, level, text }
      </code>
      
       (empty <code>
        text
      </code>
      
       removes the heading); anything else writes nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transfer-summary
      </code>
    </td>
    
    <td>
      <code>
        summaryTransform
      </code>
      
       (<code>
        integrations/composite-ai
      </code>
      
      )
    </td>
    
    <td>
      the dragged Typed block's Markdown (cut to <code>
        AI_LIMITS.selection
      </code>
      
      )
    </td>
    
    <td>
      empty
    </td>
    
    <td>
      a short Markdown summary, written into a new Typed block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transfer-bullets
      </code>
    </td>
    
    <td>
      <code>
        bulletsTransform
      </code>
    </td>
    
    <td>
      the same
    </td>
    
    <td>
      empty
    </td>
    
    <td>
      a Markdown list of the key statements, written into a new Typed block
    </td>
  </tr>
</tbody>
</table>

They run through the normal `POST /api/ai/generate` route and `createDirectAi` (no new endpoint); `transferRequest(payload, blocks, model, task)` builds the body of the two transfer tasks.

### Chat agent operations

The model proposes edits through the `edit_document` tool. The server checks them (`checkAgentOps`, `@skaile/forge-editor/ai/protocol`) and streams the valid ones as an `ops` event: `{ ops: AgentOp[], dropped: AgentOpProblem[], retries }`. Each operation gets a conversation-wide `op: 'op<n>'` id.

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Fields
    </th>
    
    <th>
      Effect
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        add
      </code>
    </td>
    
    <td>
      <code>
        afterId: string | null
      </code>
      
       (required), <code>
        markdown
      </code>
    </td>
    
    <td>
      Insert block(s) after <code>
        afterId
      </code>
      
       (in the document or a Typed block's body). <code>
        afterId
      </code>
      
       must be present: an explicit <code>
        null
      </code>
      
       is the document start (not allowed with a selection scope, where <code>
        afterId
      </code>
      
       must be a selected block); a forgotten key is rejected, it never becomes the start. Several <code>
        add
      </code>
      
      s after the same block are fine and keep the order of the answer.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        update
      </code>
    </td>
    
    <td>
      <code>
        id
      </code>
      
      , <code>
        markdown
      </code>
    </td>
    
    <td>
      Replace block <code>
        id
      </code>
      
      . A single paragraph, or one block of the same type and attributes, is diffed within the block. On a Typed block, a <code>
        ::: kind
      </code>
      
       fence (exactly one Typed block) replaces the whole Typed block; unfenced markdown replaces only its body.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        delete
      </code>
    </td>
    
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      Remove the block (or the smallest list item, list or quote that would be invalid without it).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        convert
      </code>
    </td>
    
    <td>
      <code>
        id
      </code>
      
      , <code>
        to
      </code>
    </td>
    
    <td>
      Change the type of the block, keeping the content. <code>
        to
      </code>
      
       is one of the request's <code>
        targets
      </code>
      
      : the targets the installed conversion providers advertise (<code>
        paragraph
      </code>
      
      , <code>
        heading1
      </code>
      
      –<code>
        heading3
      </code>
      
      , <code>
        bulletList
      </code>
      
      , <code>
        orderedList
      </code>
      
      , <code>
        blockquote
      </code>
      
      , <code>
        codeBlock
      </code>
      
      , plus <code>
        transcriptSegment
      </code>
      
       and <code>
        typedBlock:<block type id>
      </code>
      
       with those features).
    </td>
  </tr>
</tbody>
</table>

Validation problems (`AgentOpProblemReason`): `unknown` (the id isn't in the document), `scope` (the id is outside the selection, or an `add` at the document start with a selection scope), `field` (a field is missing or invalid, e.g. empty `markdown`, more than `AGENT_LIMITS.markdown` = 8000 characters, or an `add` without its `afterId` key), `duplicate` (the same block is updated, converted or deleted twice), `limit` (more than `AGENT_LIMITS.ops` = 50 operations), `target` (`to` isn't among the request's `targets`), `inside` (an operation on a block *inside* a block that another operation of the same list replaces (`update`) or deletes: the operation on the outer block wins; to change the inner block too, put the change into the outer `markdown`). Which blocks lie inside which is read from the indentation of the document text (`readBlockLines`). On problems the model is asked to retry (the retry text lists each problem and says that for `inside` the outer operation applies), up to `AGENT_LIMITS.retries` = 2 times. Whatever is still invalid after that, or left out of a corrected list, is reported in `dropped`.

**Review flow.** The client re-checks each operation against the scope the request was sent with and shows valid ones as in-document review changes the user accepts or rejects. An operation that can't be shown gets an outcome instead: `blocked` (outside the scope), `stale` (its block was deleted in the browser while the model was answering; „Block gelöscht“ in the chat), `missing`, `unchanged`, `overlap` or `empty` (`AGENT_OP_OUTCOMES`). Every operation's outcome (`accepted`, `rejected`, `partial`, `invalid`, `pending`, …) is sent back as `feedback` with the next user message; the model reads it as „Entscheidungen zu deinen letzten Vorschlägen: op1 (update Block X) nicht angezeigt: Block wurde inzwischen gelöscht; …“ (`agentFeedbackText`).

**Reading tools.** Besides `edit_document` the chat can call read-only tools a host registers (`tools: [...]` in `installEditorServer` or `provideEditorServer`, a `ToolProvider` each: `{ name, tool, handle(ctx, input) }`, `@skaile/forge-editor/server`). The server runs such a call itself, feeds the result back and lets the model answer again (at most 5 turns with up to 8 calls); every call reaches the client as a `tool` event `{ name, input, output }`, which the chat keeps on the assistant turn and sends back, so later messages replay the calls and results. The system prompt lists the registered tools. `createWorkspaceTools()` provides two: `find_blocks(query, limit?)` (Block index search over the Documents the user may read) and `read_block(documentId, blockId)` (one Block as Markdown). Both need the `index` port and stay inside the user's readable Documents; an unreadable or unknown address answers the same refusal. A Block of another Document is cited by naming its Document and block id, not with a `#block-` link (those resolve in the open document only). `edit_document` cannot be registered or replaced.

**Other Documents (change set).** An operation may carry `documentId` and then aims at another Document of the workspace (block IDs are unique per Document only); without it, or with the open Document's own ID, it targets the open Document. `edit_document` offers the field when the server has a `DocumentMutator` and the host provides the `changeSets` port (`EditorPorts.changeSets`, a `ChangeSetStore`; `createJsonAdapter` provides it on `.change-sets.json`), and only Documents the user may read **and** edit are accepted: the server checks the block IDs against each Document's current content (live content of an open one) and reports a Document it does not know or the user may not edit as an `AgentOpProblem` with reason `document`. Operations for the open Document go to the in-document review as before. The others are stored as a `ChangeSet` (`core/change-set.ts`: one hunk per operation, `pending` until decided) and streamed to the client as the SSE event `change-set`. The user reviews them per Document in the `ChangeSetPanel` (`@skaile/forge-editor/change-sets/vue`, `/react`), a hunk at a time or all of a Document: `GET /api/editor/change-sets`, `POST /api/editor/change-sets/:id/accept` and `…/reject` with `{ hunks: ['op3', …] }` (the port is `changeSets`). Accepting applies the hunk through the `DocumentMutator`, so it reaches an open Document as an ordinary edit and the Block index re-projects it; a hunk whose block is gone answers `409` and stays visible as `stale` with the server's message, a refusal with `403`, `404` or `422` as `invalid`. Decisions reach the model like the in-document review's: `AgentOpFeedback` with `documentId`, sent with the next message. Share one model between the chat and the panel: `useChangeSetModel({ backend })` and `<AiSidebar :change-sets="model">`.

**Document text** (`documentChatText(editor)`): one line per block, `[<id>] <markdown on one line>`. List and quote markers form the prefix (`- `, `1. `, `> `). A Typed block is a header line `[<id>] ::: kind {meta} | Title | Description | Tags: #a #b` (meta only when non-empty, empty parts omitted), followed by its body lines indented by two spaces and a closing line `  :::` without an id. A code block keeps its own lines: the first carries the id, the others start at the left edge. A table (`tablesFeature`) does the same with its pipe-table Markdown: one block under the table's id, no line per cell, so the model edits the table as a whole. The text is truncated at `CHAT_LIMITS.document` = 120000 characters (the notice is `TRUNCATED_LINE`). The format has one owner, `block-lines` of `@skaile/forge-editor/ai/protocol`: the writer helpers (`blockLine`, `compositeLineHeader`, …), `readBlockLines(text)` (the ids and which blocks lie inside which; lines inside fenced code are code, never block ids, so a code line like `[ghost] text` does not become one), `stripBlockLineEcho` / `stripListMarkerEcho` (remove a `[<id>] ` or list/quote marker prefix the model echoes into its Markdown) and the prompt texts (`BLOCK_LINE_INTRO`, `BLOCK_LINE_IDS_HINT`, …). The browser writes the text and the server reads it with the same module.

**The same loop in a host's own chat** (`@skaile/forge-editor/ai/actions`, optional peer `@skaile/forge-app-actions`). A host whose chat is not the editor's (a Nuxt app with an AI SDK route and forge-chat client tools) gets the agent operations as two forge actions: `documentActions({ editor: () => editor, review, scope?, targets? })` returns `doc.read` (the result of `documentChatText(editor)`) and `doc.propose_ops` (the `edit_document` input: `ops` with the same fields as the table above; the input schema is as loose as the server's tool, so the type, the limits and the block rules come from `checkAgentOps` and a bad operation never refuses the whole call). `review` is the host's `createAgentOpReview({ notify, t })`; `scope` returns the current `selectionScope(editor.state)` (default: the whole document) and `targets` lists the block types `convert` may use (default: none, so a `convert` is a `target` problem). The action runs in the browser: it checks the operations with `checkAgentOps` against the block lines of the document as it is now, gives the valid ones `op<n>` ids from the review's own counter (`nextOp`, `advanceOp`: the numbering continues across turns, and next to the editor's own document chat when both share the review: pass it as `review` to `createDocumentChat`, which then renumbers the operations of an answer when they arrive, in case another proposer took the ids its request was sent with), shows them with `review.propose` and returns `{ proposed, outcomes, problems, hint }`: `outcomes` has one `{ op, type, target, outcome }` per valid operation in input order (`outcome` is `pending` while it waits for the user, else why nothing is shown: `unchanged`, `missing`, `overlap`, `stale`, `empty`, `blocked`), `proposed` counts only the `pending` ones, and each problem's `index` is the 1-based position of the operation in the input. Operations that fail the check are not retried by the action: the `problems` go back to the model, which sends corrected operations. There is no approval dialog; the in-document review (`AiReviewBar`, with the `AiReview` extension in the editor) is the approval. The capability names are `app.doc.read` and `app.doc.propose_ops`; pass the actions to `useChatActions` of `@skaile/forge-app-actions/chat`.

### Typed block Markdown fence format

```text
::: kind {meta-json}
## Title
> Description
Tags: #a #b
body blocks…
:::
```

- The meta JSON is written only when it is non-empty (`::: section`). The parser requires a JSON object; otherwise the line stays plain text. A Typed block that a `reference` chip or `reference` property points at carries its block id in the opener, `::: kind #<block id> {meta}`; the parser restores it as the block id, other fences have no `#<id>`.
- Fences nest. Every closer is a bare `:::` and closes the innermost open fence. An opener without a matching closer stays plain text.
- Inner text: the first `#`…`######` heading becomes the title, a blockquote directly after it the description, a `Tags:` line the tags (lower-cased, de-duplicated), the rest the body (recursively). A missing title gives an empty title; an empty body gives one empty paragraph.
- Known Block type: `meta` keeps only that Block type's property keys, plus `derivation`, `bib`, `basket` and `titleHidden` (the Derivation, the Bibliographic record, the Basket and the hidden-title flag survive every Block type). Unknown Block type: the id and meta are kept as given and the view falls back to the `section` presentation.

Used by `editor.getMarkdown()` (the `typedBlock` node's `renderMarkdown`), by AI results applied through the composites feature's `parseMarkdown` stage (`blocksFromMarkdown`; task results with a heading are wrapped in a `section` fence in Structure mode (`'structured'`), else titled with `##`, by the `composite-ai` integration's `formatAiResult`) and by the agent's `add`/`update` Markdown and system prompt.

```text
::: task {"status":"doing","due":"2026-11-01"}
## Angebot schreiben
> Für Kunde Müller
Tags: #vertrieb
- Preise prüfen
- Entwurf an Ben
:::
```

### Stored settings

`EditorSettings` (`@skaile/forge-editor/settings`) is one version-2 JSON object shared by all editors of an app: `editing.{headingConversionScope ('container'), authorColors (false), authorColorStyle ('background'), commentsLayout ('margin')}`, `ai.{autocomplete (false), roles ({}), translateLanguage ('Englisch')}`, `blocks.{defaultBlockType ('section'), structure ('structured'), treeRoot ('folders'), blockTypeIcon ('always'; 'hover' shows the Typed blocks' Block type icon only on hover, focus or open details), dragHandle ('hover'; 'always' shows the drag handle of blocks without a Block type icon permanently), splitTargetChars (1500; target size of a split by length or with AI, 200 to 20000: `SPLIT_TARGET_CHARS_MIN`, `SPLIT_TARGET_CHARS_MAX`)}` and `appearance.{theme (null)}` (the Obsidian theme id, `null` = standard look; see [Themes (Obsidian)](https://skaile-ai.github.io/forge-editor/guides/themes)). `parseEditorSettings(input)` deep-merges any input over those defaults (unknown keys dropped, invalid values replaced; a stored `blocks.metaVisibleDefault` of an older version is just dropped) and migrates the legacy flat per-browser shape `{ headingConversionScope }`; `PUT /api/editor/settings` instead requires the complete, valid shape (`editorSettingsSchema`). Settings tabs are contributed by features (`editing` by composites, `authors` and `comments` by their features, `ai` by AI, `appearance` by themes), so a preset without a contributing feature has no settings UI. A tab only edits its own fields; the other sections are written back unchanged, which is why one account can use a simple and an advanced editor without erasing the other's preferences.


# AI configuration and secrets

> One configuration object for module options, server and browser, the Model presets and Model roles, and why API keys come from the environment only.

## Defining the configuration

One configuration, three views (`@skaile/forge-editor/config`, framework-free). `defineEditorConfig(input)` applies every default below once and returns the `EditorConfig`; `publicConfig(config)` is the part the browser may see (`locale`, `messages`, `ai: { roles, transcription: boolean }`, the `createEditor({ ...publicConfig })` options), `serverConfig(config)` the part the server needs, keys included (`ai: { presets, apiKey, slots, transcription? }`, `rateLimit`, `collab`: spread it into `installEditorServer(nitroApp, { ports, ...serverConfig(config) })`). The Nuxt module does exactly that: its options are `EditorConfigInput`, `runtimeConfig.tiptapEditor = serverConfig(config)` and `runtimeConfig.public.tiptapEditor = publicConfig(config)`, and the server plugin passes the runtime config on to `installEditorServer`. Every Model preset, the shared key and the transcription get an empty `apiKey` in the server view, so the `NUXT_TIPTAP_EDITOR_AI_*` variables below have a key to override. An unset value (`locale: process.env.EDITOR_LOCALE`) means the default.

```ts
import { defineEditorConfig, publicConfig, serverConfig } from '@skaile/forge-editor/config'

const config = defineEditorConfig({ locale: 'en', ai: { roles: { rewrite: 'flashLite' } } })
serverConfig(config) // { ai: { presets, apiKey: '', roles, … }, rateLimit: { max: 30, windowMs: 60000 }, collab: { authenticateUpgrade: false } }
publicConfig(config) // { locale: 'en', ai: { roles, transcription: false } }
```

## Options

Config key `tiptapEditor` (`EditorConfigInput`; a Model preset with the ID of a default overrides single fields of it):

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        locale
      </code>
    </td>
    
    <td>
      <code>
        'de' | 'en'
      </code>
      
      : language of every string the editor renders; passed to the client context plugin (<code>
        createEditor({ locale })
      </code>
      
      )
    </td>
    
    <td>
      <code>
        'de'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        messages
      </code>
    </td>
    
    <td>
      <code>
        Partial<Record<MessageKey, string>>
      </code>
      
      : overrides of single messages by key (JSON-serialisable)
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.presets
      </code>
    </td>
    
    <td>
      <code>
        Record<string, ModelPresetConfig>
      </code>
      
       (<code>
        { label, endpoint, model, apiKey? }
      </code>
      
      ): server Model presets keyed by preset ID (camelCase). <code>
        endpoint
      </code>
      
       is any OpenAI-compatible chat-completions base URL.
    </td>
    
    <td>
      <code>
        sonnet
      </code>
      
      , <code>
        flashLite
      </code>
      
       (OpenRouter)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.roles
      </code>
    </td>
    
    <td>
      <code>
        Record<ModelRole, string>
      </code>
      
       (<code>
        'complete' | 'rewrite' | 'generate'
      </code>
      
      ): default Model preset per Model role. The <code>
        complete
      </code>
      
       model must support assistant prefill.
    </td>
    
    <td>
      <code>
        { complete: 'flashLite', rewrite: 'sonnet', generate: 'sonnet' }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.rateLimit
      </code>
    </td>
    
    <td>
      <code>
        { max, windowMs }
      </code>
      
       per user, shared by all AI endpoints
    </td>
    
    <td>
      <code>
        { max: 30, windowMs: 60000 }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai.transcription
      </code>
    </td>
    
    <td>
      <code>
        { provider?, endpoint, model, apiKey?, language? }
      </code>
      
      : <code>
        provider
      </code>
      
       <code>
        'openai'
      </code>
      
       (default) = OpenAI-compatible <code>
        POST <endpoint>/audio/transcriptions
      </code>
      
       (<code>
        verbose_json
      </code>
      
       segments), <code>
        'deepgram'
      </code>
      
       = Deepgram <code>
        POST <endpoint>/listen
      </code>
      
       (<code>
        endpoint
      </code>
      
       <code>
        https://api.deepgram.com/v1
      </code>
      
      , <code>
        model
      </code>
      
       e.g. <code>
        nova-3
      </code>
      
      ; utterances become the segments). <code>
        language
      </code>
      
       (e.g. <code>
        'de'
      </code>
      
      ) fixes the spoken language; without it OpenAI guesses and Deepgram detects it
    </td>
    
    <td>
      absent: action hidden, endpoint answers 501
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collab.authenticateUpgrade
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
      
      : authenticate the <code>
        /collab/:id
      </code>
      
       upgrade and refuse it with HTTP 401 (see <a href="https://skaile-ai.github.io/forge-editor/guides/routes-and-auth#auth-notes">
        Auth notes
      </a>
      
      ); env <code>
        NUXT_TIPTAP_EDITOR_COLLAB_AUTHENTICATE_UPGRADE
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
      
      : upgrade first, close with 4401
    </td>
  </tr>
</tbody>
</table>

## Keys come from the environment only

Never put a key into `nuxt.config.ts` (it ends up in the build output).

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Sets
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        NUXT_TIPTAP_EDITOR_AI_API_KEY
      </code>
    </td>
    
    <td>
      <code>
        ai.apiKey
      </code>
      
      : shared fallback for every Model preset without its own key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY
      </code>
    </td>
    
    <td>
      <code>
        ai.presets.<id>.apiKey
      </code>
      
      ; <code>
        <ID>
      </code>
      
       is the preset ID in upper snake case (<code>
        flashLite
      </code>
      
       → <code>
        NUXT_TIPTAP_EDITOR_AI_PRESETS_FLASH_LITE_API_KEY
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY
      </code>
    </td>
    
    <td>
      <code>
        ai.transcription.apiKey
      </code>
      
       (only effective when <code>
        ai.transcription
      </code>
      
       is set)
    </td>
  </tr>
</tbody>
</table>

## Host models through the adapter

A model provider (`ModelProvider`, the `models` port) with `languageModel(ref, user)` is asked first for every Model reference; a returned model is used as is (no Model preset, no key needed), `null` falls through to the Model presets above. `listModels(user)` decides what `GET /api/ai/models` offers (return `null` to list the Model presets). Host-driven agent chats are the counterpart on the client: `createAgentOpReview({ notify, t })` from `@skaile/forge-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`.

## Key resolution and errors

A Model 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 = { roles, transcription: boolean }` and, through `GET /api/ai/models`, Model profiles of the Model presets **without** keys. A user-defined Model 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.


# Audio: read aloud, mixdown and ElevenLabs

> The add-on @skaile/forge-editor-audio: an ElevenLabs SpeechProvider, the derive methods audio-tts and audio-mixdown that make recording blocks with named Derivation inputs, and the render target audio-mixdown that mixes takes through ffmpeg.

The add-on `@skaile/forge-editor-audio` builds on the library's [speech port](https://skaile-ai.github.io/forge-editor/guides/speech) and [render port](https://skaile-ai.github.io/forge-editor/guides/render). It adds three things:

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Needs
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        createElevenLabsSpeech
      </code>
    </td>
    
    <td>
      a <code>
        SpeechProvider
      </code>
      
       over ElevenLabs: engine <code>
        elevenlabs
      </code>
      
       with the voices of the account
    </td>
    
    <td>
      an ElevenLabs API key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audioMixdownTarget
      </code>
    </td>
    
    <td>
      the render target <code>
        audio-mixdown
      </code>
      
       (<code>
        audio/mpeg
      </code>
      
      )
    </td>
    
    <td>
      <code>
        ffmpeg
      </code>
      
       on the <code>
        PATH
      </code>
      
       of the server, the <code>
        assets
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        audioFeature
      </code>
    </td>
    
    <td>
      the <a href="https://skaile-ai.github.io/forge-editor/guides/derive-methods">
        derive methods
      </a>
      
       <strong>
        „Als Sprache vorlesen“
      </strong>
      
       (<code>
        audio-tts
      </code>
      
      ) and <strong>
        „Mixdown erzeugen“
      </strong>
      
       (<code>
        audio-mixdown
      </code>
      
      )
    </td>
    
    <td>
      the <code>
        speech
      </code>
      
       and the <code>
        render
      </code>
      
       capability of the backend
    </td>
  </tr>
</tbody>
</table>

Both derive methods make a Typed block of the Block type `recording` and record its [Derivation](https://skaile-ai.github.io/forge-editor/guides/derive-methods) with **named inputs**. That is what lets the library tell when an input changed.

## Wire the server

```ts
import { createRenderer, markdownTarget } from '@skaile/forge-editor/adapters/render'
import { audioMixdownTarget, createElevenLabsSpeech } from '@skaile/forge-editor-audio/server'

// installEditorServer({ ports: { assets, speech, render } })
export const speech = createElevenLabsSpeech({ apiKey: process.env.ELEVENLABS_API_KEY! })
export const render = createRenderer([markdownTarget(), audioMixdownTarget({ assets })])
```

The server code is the `/server` entry (it starts `ffmpeg` through `node:child_process`); the root entry of the package is browser-safe and holds the Feature and the pure pieces of a Derivation, as in the other add-ons.

`assets` is the host's `AssetStore`: the target reads the takes' audio from it, and the render route stores the mixdown in it.

<table>
<thead>
  <tr>
    <th>
      Option of <code>
        createElevenLabsSpeech
      </code>
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        apiKey
      </code>
    </td>
    
    <td>
      sent as <code>
        xi-api-key
      </code>
      
      ; the key stays on the server
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        endpoint
      </code>
    </td>
    
    <td>
      base URL, default <code>
        https://api.elevenlabs.io
      </code>
      
      ; a regional host such as <code>
        https://api.eu.residency.elevenlabs.io
      </code>
      
       goes here
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        modelId
      </code>
    </td>
    
    <td>
      the speech model, default <code>
        eleven_multilingual_v2
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        voiceSettings
      </code>
    </td>
    
    <td>
      <code>
        voice_settings
      </code>
      
       of every synthesis (<code>
        stability
      </code>
      
      , <code>
        similarity_boost
      </code>
      
      , <code>
        style
      </code>
      
      , <code>
        speed
      </code>
      
      , <code>
        use_speaker_boost
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        id
      </code>
      
      , <code>
        label
      </code>
    </td>
    
    <td>
      the engine's id and label in <code>
        engines()
      </code>
      
       (default <code>
        elevenlabs
      </code>
      
      , <code>
        ElevenLabs
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        voiceCacheMs
      </code>
    </td>
    
    <td>
      how long the voice list is kept (default five minutes)
    </td>
  </tr>
</tbody>
</table>

`engines()` lists the voices of the account (`GET /v2/voices`, every page up to a limit). A voice's `lang` is the locale of its first verified language, else that language, else its `language` label, else `und`. `synthesize` posts the text to `/v1/text-to-speech/{voice_id}` as MP3 (`mp3_44100_128`) or WAV (`wav_24000`) and answers with the audio and the MIME type ElevenLabs sent. An engine or voice the account does not have is refused with `404` before any call. An error answer of ElevenLabs reaches the client with its own words (`ElevenLabs: 401 Invalid API key`). `transcribe` is not offered. The daily character budget of the speech route applies as for every provider.

## Wire the client

```ts
import { audioFeature } from '@skaile/forge-editor-audio'

// Add it to the preset after the composites feature (it requires it).
const audio = audioFeature({ voice: { engine: 'elevenlabs', voice: '<voice_id>' }, mixdownMode: 'concat' })
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        voice
      </code>
    </td>
    
    <td>
      the voice <code>
        audio-tts
      </code>
      
       reads with; absent, or not offered by the service: the first voice of the surface's language, else the first voice
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mixdownMode
      </code>
    </td>
    
    <td>
      <code>
        concat
      </code>
      
       (default, one after the other) or <code>
        overlay
      </code>
      
       (all at once, as long as the longest)
    </td>
  </tr>
</tbody>
</table>

The add-on carries its own small German and English tables for its notices (`audioTranslator(locale)`): the library's catalog is a closed set of keys.

## Read aloud: `audio-tts`

Offered on a Container block with a title whose body holds text, when the backend has a `speech` capability. The body is read as plain text, one paragraph per body block. The result is a `recording` block right after the text block, titled „Sprache: <title>

“, that holds the audio as its source. Its Derivation:

</title>



<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        method
      </code>
    </td>
    
    <td>
      <code>
        tts
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      the text block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inputs.text
      </code>
    </td>
    
    <td>
      the text block, with the hash of its body Markdown at the time it was read
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inputs.voice
      </code>
    </td>
    
    <td>
      <code>
        { asset: 'voice:<engine>/<voice>' }
      </code>
      
       with the hash of engine and voice; no block holds that asset, so the library reads the voice as unknown, never as changed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inputHash
      </code>
    </td>
    
    <td>
      <code>
        derivationFingerprint
      </code>
      
       of method and input hashes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        activity
      </code>
    </td>
    
    <td>
      <code>
        { id, agent: <engine>, at }
      </code>
    </td>
  </tr>
</tbody>
</table>

Edit the text block and the recording reads **veraltet**. Edit the recording's body and it reads **bearbeitet** (`outputHash` is sealed).

## Mixdown: `audio-mixdown`

Offered on a Container block with at least two **takes**: `recording` blocks among its direct children that hold stored audio or video, in document order. A recording that is itself a mixdown is no take, so a second mixdown in the same container does not mix the first one in again. The method renders the block through the target `audio-mixdown` and adds the result as the last `recording` child of the container, titled „Mixdown: <title>

“.

</title>



The Derivation names one input per take:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        method
      </code>
    </td>
    
    <td>
      <code>
        mixdown
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      the audio asset of the first take
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inputs
      </code>
    </td>
    
    <td>
      <code>
        take-1
      </code>
      
       … <code>
        take-n
      </code>
      
       in mixing order: <code>
        { from: { asset }, hash }
      </code>
      
      , <code>
        hash
      </code>
      
       being the <code>
        hash
      </code>
      
       the take's media block recorded (<code>
        ''
      </code>
      
       when it has none, which reads as unknown)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inputHash
      </code>
    </td>
    
    <td>
      <code>
        derivationFingerprint({ method: 'mixdown', inputs })
      </code>
    </td>
  </tr>
</tbody>
</table>

When the audio of a take is replaced, the hash of its media block changes and `derivationState` with an `inputHashOf` reports the mixdown as **stale**. The library's chrome, tree dot and row badge do this for every Derived block. When the first take is deleted the state is **missing**.

```ts
import { mixdownDerivation, takesOfNode } from '@skaile/forge-editor-audio'

const takes = takesOfNode(containerNode)
const derivation = mixdownDerivation({ takes, createdAt: new Date().toISOString(), activityId: crypto.randomUUID() })
```

### The render target

`audioMixdownTarget({ assets, label?, accepts?, ffmpeg? })` accepts `document`, `section` and `folder` by default. A render request holds the container's JSON, so the target finds the takes itself with the same rule as the client (`takesOf`). It refuses a take whose asset belongs to another Document (`foreign-take`), because a render may only read the assets of the Document the user is allowed to read. Request option `options.mode` is `overlay` or the default `concat`.

The block action **„Erzeugen als …“** of the library lists the target on every Block type it accepts, so a mixdown can also be started from there; the derive method adds the Derivation.

<table>
<thead>
  <tr>
    <th>
      Error code (<code>
        AudioError.code
      </code>
      
      )
    </th>
    
    <th>
      Cause
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ffmpeg-missing
      </code>
    </td>
    
    <td>
      no <code>
        ffmpeg
      </code>
      
       on the <code>
        PATH
      </code>
      
       (or at <code>
        ffmpeg
      </code>
      
       of the options)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ffmpeg-failed
      </code>
    </td>
    
    <td>
      ffmpeg exited with an error, for example an input that is no audio
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        too-few-takes
      </code>
    </td>
    
    <td>
      fewer than two takes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        take-missing
      </code>
    </td>
    
    <td>
      the audio of a take is not in the asset store
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        foreign-take
      </code>
    </td>
    
    <td>
      the audio of a take is stored with another Document
    </td>
  </tr>
</tbody>
</table>

Takes are user uploads, and ffmpeg recognises a format by its content, not its file name. Every input therefore gets `-format_whitelist` (`INPUT_FORMATS`: mp3, wav, ogg, flac, mov/mp4/m4a, matroska/webm, aac, aiff, ac3, amr, caf, asf) and `-protocol_whitelist file`: an HLS playlist, a concat script or a DASH manifest that names other files or URLs is refused with `ffmpeg-failed` instead of followed.

ffmpeg brings every input to 44.1 kHz stereo before it joins (`concat`) or sums (`amix`) them, and writes MP3 with `libmp3lame`. The inputs are written to a temporary directory that is removed again, also after a failure.


# Authors and comments

> Mark who wrote which text and let readers discuss selections in threads, with a margin or inline layout.

Both features belong to the advanced editor (not the simple one) and need a collaborative surface for the user's identity: `:collaboration="{ ydoc, provider, user: { id, name, color } }"` (`AuthorIdentity`). Entries: `@skaile/forge-editor/authors/vue` or `/authors/react` (the framework-free `/authors` and `/authors/schema` hold the model), `@skaile/forge-editor/comments/vue` or `/comments/react` (framework-free `/comments`, `/comments/schema`); CSS `styles/authors.css` and `styles/comments.css` (after `core.css`; the Nuxt module adds them).

```ts
import { authorsFeature } from '@skaile/forge-editor/authors/vue'
import { collabFeature } from '@skaile/forge-editor/collab/vue'
import { commentsFeature } from '@skaile/forge-editor/comments/vue'
const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), collabFeature(), authorsFeature(), commentsFeature()] })
```

On React the same list comes from `/authors/react`, `/collab/react` and `/comments/react`, and `collaboration` is a prop of the same name.

**authorsFeature()** (no dependency, inert without a user)

- Every inserted text run carries an `author` mark `{ id, name, color }` (persisted, invisible, not in Markdown). Text typed inside someone else's run takes the typist's mark; remote edits and Yjs undo/redo keep the original author. `documentAuthors(doc)` lists the authors with their character counts; `currentAuthor(editor)` is the user the editor writes as.
- The colouring mode is a per-user preference: `editing.authorColors` (off by default) and `editing.authorColorStyle` (`'background'` tint or `'text'` colour). It is set in the „Autorenfarben“ settings tab and in the toolbar's palette button, whose popover also holds a legend of the document's authors (`AuthorColorsPanel`).

**commentsFeature({ model? })** (requires `collab` unless `model` is given)

- `model: (getEditor) => CommentsModel` backs the comments with the host's own data (REST threads, a database) instead of the Y.Doc: the feature then requires no `collab`, the `Comments` plugin reads the user, the thread ids and the ranges from `model.state` (a snapshot with `available`, `canComment`, `user`, `threads`, `ranges`, …), and `useComments(editor)` resolves the model of the editor's surface (`commentsModelOf(ctx)`; the factory runs once for the plugin and once per hook consumer, so share state outside it). `CommentsSnapshot.canComment` gates the selection bubble: the default model says `available` and editable, a host model may allow readers. `CommentsModel`, `CommentsSnapshot`, `CommentsActions`, `DocRange` are exported from `/comments`.
- Select text and choose „Kommentar“ in the selection bubble; others reply, anyone resolves or reopens a thread („Erledigt“ threads lose their highlight), authors edit or delete their own comments. A thread whose text was deleted stays as orphan („Textstelle gelöscht“). Threads live in the Y.Doc map `comments` (`createCommentsModel(getEditor)` is the framework-free model; `useComments(editor)` is the thin Vue hook, returning the `CommentsStore`, and the React binding has the same hook), the range is the `comment` mark (the schema mark is always registered, so stored marks round-trip even without the feature's UI).
- `editing.commentsLayout` (`'margin'` default, `'inline'`) is a per-user setting in the „Kommentare“ settings tab:
  - `margin` („Randspalte“): cards beside the commented text. The host places `CommentsMargin` (props `editor`, `container`, `open`) inside the editor's scroll container (`relative flex`, editor wrapper `min-w-0 flex-1`) and binds `v-model:comments-open` on the surface (React: `commentsOpen`/`onCommentsOpenChange`). The toolbar's „Kommentare“ button and `Mod-Shift-m` toggle it; opening it closes the AI sidebar and vice versa.
  - Layout „Aktiver Faden“: the active thread (or the draft composer) is pinned exactly to the top of its text's line and shows in full; every other open thread is a one-line card (author, excerpt, reply count) that moves up or down out of its way, as close to its own line as its neighbours allow, never overlapping. Without an active thread the cards stack top-down at their lines. A click on a card activates it and reveals its text. Resolved threads are hidden behind the „Erledigt (n)“ toggle at the bottom of the column. A thread whose text was deleted stays as a greyed-out card at the deletion point, labelled „Text gelöscht“ (its position comes from the thread's anchor, a Yjs relative position kept in the Y.Map; a thread without one goes to the end); undoing the deletion attaches it to its text again. The rule is framework-free and testable on its own: `layoutMargin(entries, activeId, { gap, minTop })` maps measured cards (`MarginEntry`: id, line top or `null`, height) to tops, `marginCards(...)` builds the cards in document order, and `createMarginController(source)` does the measuring (`coordsAtPos`, card heights, one layout per animation frame); both `CommentsMargin` components only render it (all from `@skaile/forge-editor/comments`).
  - `inline`: `CommentsPopover` (mounted by the feature as an overlay) opens at the commented text; the toolbar's `CommentsListMenu` lists all threads with the open count. Esc closes the popover.
- Without collaboration the toolbar button is disabled with an explanation. Switching the layout closes any open thread or draft.

```vue
<div ref="scrollEl" class="relative flex overflow-auto">
  <div class="min-w-0 flex-1">
    <AdvancedEditor v-model:comments-open="commentsOpen" :collaboration="{ ydoc, provider, user: { id, name, color } }" />
  </div>
  <CommentsMargin :editor="editor" :container="scrollEl" :open="commentsOpen" />
</div>
```

React, same layout:

```tsx
<main ref={setScrollEl} className="relative flex overflow-auto">
  <div className="min-w-0 flex-1">
    <AdvancedEditor commentsOpen={commentsOpen} onCommentsOpenChange={setCommentsOpen} collaboration={{ ydoc, provider, user: { id, name, color } }} />
  </div>
  <CommentsMargin editor={editor} container={scrollEl} open={commentsOpen} />
</main>
```

`bun run check:editor-entries` proves the isolation with the `authors` and `comments` fixtures; the marks are part of the server schema snapshot.


# Block capabilities, abilities and actions

> Declare a Block capability in a host Feature, gate a Block action with requires and ability, see what abilities gate and let a Block type opt in.

A **Block capability** says what a Block supports: it is a Container block, it has a Source, it carries a Bibliographic record. It is code, and a Feature declares it. A [Block type](https://skaile-ai.github.io/forge-editor/guides/block-types) is data: it lists the capabilities its Typed blocks have and configures them. A **Block action** names the capabilities a Block must have (`requires`) and the ability its place in the document must have (`ability`).

Four words, four jobs:

<table>
<thead>
  <tr>
    <th>
      Word
    </th>
    
    <th>
      Question it answers
    </th>
    
    <th>
      Where it lives
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Block capability
    </td>
    
    <td>
      What is this Block?
    </td>
    
    <td>
      <code>
        EditorFeature.blockCapabilities
      </code>
      
       (code)
    </td>
  </tr>
  
  <tr>
    <td>
      Block type
    </td>
    
    <td>
      Which capabilities does a Typed block of this type have, and how are they set?
    </td>
    
    <td>
      a <code>
        BlockType
      </code>
      
       (data, JSON)
    </td>
  </tr>
  
  <tr>
    <td>
      Ability
    </td>
    
    <td>
      What is offered at this place in the document?
    </td>
    
    <td>
      <code>
        ABILITY
      </code>
      
       ids; the <code>
        abilities
      </code>
      
       rule of each node and the host's <code>
        abilities
      </code>
      
       prop
    </td>
  </tr>
  
  <tr>
    <td>
      Block action
    </td>
    
    <td>
      What can the user run on this Block?
    </td>
    
    <td>
      <code>
        EditorFeature.blockActions
      </code>
      
      , derive methods, the host's <code>
        blockActions
      </code>
    </td>
  </tr>
</tbody>
</table>

A capability describes and gates nothing by itself; an action gates on it through `requires`. It also never installs anything: the schema, the extensions and the node views stay with the Feature that owns the mechanism. A capability descriptor only tells the editor how to find out whether a Block has it, where its data lives and how to read it.

The library declares these capabilities: `container` and `title` are built in, the composites feature adds `properties`, `source`, `bibliography`, `basket`, `titleHidden`, `ai-brief`, `references`, `import`, `export` and `derived`. The [capability contract](https://skaile-ai.github.io/forge-editor/reference/block-capabilities) lists them with their config.

## Declare a capability

A host adds a capability as a Feature with `blockCapabilities`. The library's own `pruefung` Feature is the worked example: a Typed block has `pruefung` when its Block type lists it, and the Block type names the kinds of Prüfung it takes (`redaktionell`, `fachlich`). The same Feature adds the Block action „Prüfung eintragen“, which `requires` the capability. The snippet shows the shape of the shipped `pruefungCapability`; import it from `@skaile/forge-editor/pruefung` instead of declaring it again.

```ts [docs/snippets/pruefung-capability.ts]
import { z } from 'zod'
import type { BlockCapability } from '@skaile/forge-editor/core'
import { listsCapability } from '@skaile/forge-editor/core'

// The config a Block type gives. It is validated when the editor is created.
const pruefungConfig = z.strictObject({
  kinds: z.array(z.string().min(1)).min(1),
  chain: z.boolean().default(false),
  lock: z.string().min(1).optional(),
})
type PruefungConfig = z.infer<typeof pruefungConfig>

// The capability only describes: a Typed block has `pruefung` when its Block type lists it. This is the shape of the
// shipped `pruefungCapability` (`@skaile/forge-editor/pruefung`); the `pruefung` Feature owns the mechanism (records, hash, actions).
export const capability: BlockCapability = {
  id: 'pruefung',
  configSchema: pruefungConfig,
  appliesTo: (node, ctx) => listsCapability(ctx.blockTypeOf(node), 'pruefung'),
  read: (node, ctx) => ctx.configOf<PruefungConfig>(node, 'pruefung') ?? null,
}
```

The members of the descriptor:

- `id` is unique across the preset. Block types and `requires` entries name it. A Feature may not use the id of a built-in capability, and two Features may not declare the same id: `defineEditor` throws.
- `appliesTo(node, ctx)` decides whether `node` has the capability. `listsCapability(ctx.blockTypeOf(node), id)` answers "the Block type lists it". The result is memoised per node type and Block type id, so the predicate may read only the node type (its spec and flags), `ctx.blockTypeId` and the Block type's config (`ctx.configOf`). A capability that must read an attribute of the node itself sets `perNode: true` and keeps the check a constant-time attribute read (`derived` reads `meta.derivation` this way).
- `configSchema` is a zod schema for the config a Block type gives. Without it the capability takes no config and a Block type that gives one is refused.
- `read(node, ctx)` returns what the Block holds for the capability, or `null`: the Source media child, the Basket id, the Bibliographic record. It runs only for Blocks that have the capability and is not memoised.
- `storage` describes where the data lives (`metaKeys`, `childTypes`), so conversion, Markdown and copy can treat it the same way. It is descriptive only.

`appliesTo` answers "does a Block of this type support it". What a single Block holds is Block contents, and `read` returns it. Keep the two apart.

## Gate a Block action with `requires`

`BlockAction.requires` lists capability ids. The action is hidden on a Block that lacks one of them, and `blockActionsOf` throws when an id is declared by no Feature. It replaces node-name and Block-type-name checks in `isVisible`. `ability` is the second, independent gate: an action shows when the Block has every required capability **and** its place in the document has the ability ([Abilities](#abilities)). `blockTypes` limits an action to named Block types and is only for an action that is truly specific to a type; if the action is about what a Block can do, use `requires`.

## Abilities

An ability is a plain string id (`ABILITY` in `@skaile/forge-editor/core/schema`, or your own). Which abilities hold at a position follows from the nodes around it: the set starts with `abilities.root` (default `ROOT_ABILITIES`), then every ancestor from the outside in adds its `grants` and removes its `revokes`, and the innermost node finally adds its `own`. A code block revokes marks and headings, media and the title row revoke text editing, and a Typed block's `own` abilities (`composite.meta`, `composite.derive`, …) hold on the block itself, not on a paragraph inside it. A rule may be a function of the node, so it can read the node's attributes. Host rules passed through the `abilities` prop replace a node's own rule; the prop is read once at mount.

One ability gates many things. The editor checks it for:

<table>
<thead>
  <tr>
    <th>
      Item
    </th>
    
    <th>
      Field
    </th>
    
    <th>
      Effect where the ability is missing
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Toolbar and <code>
        /
      </code>
      
       entries
    </td>
    
    <td>
      <code>
        CommandDef.ability
      </code>
    </td>
    
    <td>
      disabled (toolbar) or not listed (<code>
        /
      </code>
      
       menu)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Mod-
      </code>
      
      /<code>
        Alt-
      </code>
      
       shortcuts and input rules of a node or mark type
    </td>
    
    <td>
      <code>
        TYPE_ABILITIES
      </code>
    </td>
    
    <td>
      the key is swallowed; the typed text stays literal
    </td>
  </tr>
  
  <tr>
    <td>
      Block actions and derive methods
    </td>
    
    <td>
      <code>
        BlockAction.ability
      </code>
      
      , <code>
        DeriveMethod.ability
      </code>
    </td>
    
    <td>
      hidden
    </td>
  </tr>
  
  <tr>
    <td>
      „Umwandeln in …“ targets
    </td>
    
    <td>
      <code>
        TYPE_ABILITIES
      </code>
      
       of the target type
    </td>
    
    <td>
      not offered
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @
      </code>
      
       mentions, block references, AI rewrite and autocomplete
    </td>
    
    <td>
      <code>
        insert.mention
      </code>
      
      , <code>
        insert.reference
      </code>
      
      , <code>
        ai.*
      </code>
    </td>
    
    <td>
      the popup, menu or ghost text does not open
    </td>
  </tr>
</tbody>
</table>

An ability decides what the editor **offers**, not what may be **written**. Pasted and dropped content, collaborators' changes and commands called from code are not checked, plain typing and Backspace have no ability, and the editor knows no users: a host that wants per-role abilities passes a different `abilities` prop per mount. To refuse a change, use a `transactionGuards` contribution ([Feature contract](https://skaile-ai.github.io/forge-editor/reference/feature-contract)); to make a whole document read-only for a user, use `authorize` ([Editor ports](https://skaile-ai.github.io/forge-editor/guides/editor-ports)).

## Let a Block type opt in

A Block type lists the capability with its config. The Block type goes through the `blockTypes` option of the composites feature ([Block types](https://skaile-ai.github.io/forge-editor/guides/block-types)).

```ts [docs/snippets/pruefung-preset.ts]
import { compositeFeature } from '@skaile/forge-editor/composites/vue'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites/schema'
import { coreContentFeature, coreUiFeature, createTranslator, defineEditor } from '@skaile/forge-editor/core'
import { pruefungFeature } from '@skaile/forge-editor/pruefung'

// A Block type opts into the capability and configures it.
const contract: BlockType = {
  id: 'contract',
  label: 'Vertrag',
  icon: 'i-lucide-file-signature',
  capabilities: [
    { id: 'container', config: { accepts: 'all' } },
    { id: 'pruefung', config: { kinds: ['redaktionell', 'fachlich'] } },
  ],
}

const blockTypes = [...defaultBlockTypes(createTranslator('de')), contract]

// A Block type that lists a capability no Feature declares throws when the editor is created; so does a block action that
// `requires` an undeclared id, when the actions are collected.
export const preset = defineEditor({
  features: [
    coreContentFeature(),
    coreUiFeature(),
    compositeFeature({ blockTypes }),
    pruefungFeature(),
  ],
})
```

A Block that does not have the capability gets no „Prüfung eintragen“ button. A Typed block of the type `contract` gets it, with the config `{ kinds: ['redaktionell', 'fachlich'] }` in `capabilityConfigOf`.

## Read a capability at runtime

All of these take the editor, because the answer depends on the editor's own Block types:

<table>
<thead>
  <tr>
    <th>
      Function
    </th>
    
    <th>
      Returns
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        capabilitiesOf(editor, node)
      </code>
    </td>
    
    <td>
      the ids of the capabilities <code>
        node
      </code>
      
       has (<code>
        ReadonlySet<string>
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilitiesAt(editor, pos)
      </code>
    </td>
    
    <td>
      the same for the Block at <code>
        pos
      </code>
      
      ; empty where no node starts
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilityConfigOf(editor, node, id)
      </code>
    </td>
    
    <td>
      the config the Block type gives the capability, or <code>
        undefined
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilityDataOf(editor, node, id)
      </code>
    </td>
    
    <td>
      what <code>
        read
      </code>
      
       returns, or <code>
        null
      </code>
      
       when the Block lacks the capability or holds nothing
    </td>
  </tr>
</tbody>
</table>

They are exported from `@skaile/forge-editor/core` and run without a framework. The preset keeps the merged registry as `preset.capabilities`; pass it to `parseBlockTypes` as `registry` when a Block type file must name your capabilities ([Block types](https://skaile-ai.github.io/forge-editor/guides/block-types#block-types-as-json)).

## Keep a capability small

A capability stays a descriptor plus a storage contract. If it needs a node, a node view or a settings tab, that belongs to a Feature (`extensions`, `overlays`, `settingsTabs`), and the capability only says that the Block has it. Blocks that are no Typed blocks can have a capability too, but a host block that wants `title` or `properties` must declare the chrome and the `meta` attribute itself: the capability tells the UI what to expect, not how to build the node.


# Block properties and Property definitions

> Define Block properties with Property definitions, give them to a Block type with the properties capability and read and write them.

A **Block property** is a value that a Block carries, such as a status, a due date or a link to another Block. A **Property definition** declares one: its key, its label and its value type. One definition type serves the whole editor: the `properties` capability, the Block inspector, the details popover, the table, the AI context and the server's chat schema all describe a Block property with it. The [Property definition contract](https://skaile-ai.github.io/forge-editor/reference/block-types#propertydefinition) lists the members.

## Define the properties of a Block type

A Block type lists the `properties` capability with `{ definitions }`. The example defines four Block properties for the Block type `decision` and sets one of them from code:

```ts [docs/snippets/block-properties.ts]
import type { BlockType, PropertiesConfig, PropertyDefinition } from '@skaile/forge-editor/composites/schema'
import { blockPropertiesAt, setBlockProperty } from '@skaile/forge-editor/composites'
import type { Editor } from '@tiptap/core'

// One Property definition per Block property: the key under which it is stored in `meta`, its label and its value type.
const definitions: PropertyDefinition[] = [
  { key: 'status', label: 'Status', type: 'select', options: [{ value: 'entwurf', label: 'Entwurf' }, { value: 'fertig', label: 'Fertig' }] },
  { key: 'topics', label: 'Themen', type: 'multiselect', options: [{ value: 'cost', label: 'Kosten' }, { value: 'risk', label: 'Risiko' }] },
  { key: 'owner', label: 'Zuständig', type: 'text' },
  { key: 'related', label: 'Verwandt', type: 'reference', targets: ['decision'] },
]

// The `properties` capability carries them; a Block type without it has no Block properties.
export const decision: BlockType = {
  id: 'decision',
  label: 'Entscheidung',
  icon: 'i-lucide-gavel',
  capabilities: [{ id: 'properties', config: { definitions } satisfies PropertiesConfig }],
}

/** Sets `status` on the block around the caret, in one transaction. False when no block there has Block properties. */
export function finishAtCaret(editor: Editor, blockTypes: readonly BlockType[]): boolean {
  const at = blockPropertiesAt(editor, editor.state.selection.$from, blockTypes)
  return at ? setBlockProperty(editor, at.properties, 'status', 'fertig') : false
}
```

A Block type without the `properties` capability has no Block properties: the Block inspector shows no section and the details popover shows no fields.

A `status` property says where a Block is in its work. It is no record that someone checked it: a checked state belongs in a Prüfung, which is pinned to the content of the Block and lives outside the document ([Prüfung](https://skaile-ai.github.io/forge-editor/guides/pruefung)).

<table>
<thead>
  <tr>
    <th>
      <code>
        PropertyDefinition
      </code>
      
       member
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
      
      , <code>
        label
      </code>
    </td>
    
    <td>
      the key under which the Block property is stored in <code>
        meta
      </code>
      
      , and its label
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      one of the value types below
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code>
        { value, label, group? }
      </code>
      
       choices of a <code>
        select
      </code>
      
      , <code>
        multiselect
      </code>
      
       or <code>
        status
      </code>
      
       property (required for <code>
        multiselect
      </code>
      
      ); <code>
        group
      </code>
      
       (<code>
        'todo' | 'doing' | 'done'
      </code>
      
      ) only on <code>
        status
      </code>
      
       options
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        targets
      </code>
    </td>
    
    <td>
      <code>
        reference
      </code>
      
       only: the Block type ids the Block reference may point to; absent = any Typed block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hidden
      </code>
    </td>
    
    <td>
      the property is stored and queried like any other, but the Block inspector, the details popover and the Block table do not show it: for a JSON value an own view edits (the query of a collection)
    </td>
  </tr>
</tbody>
</table>

The value types are the entries of `PROPERTY_TYPES` (`@skaile/forge-editor/core`):

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Stored value
    </th>
    
    <th>
      Notes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
      
      , <code>
        textarea
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      a <code>
        textarea
      </code>
      
       property gets no column in the Block table
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        date
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      formatted in the table
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      number
    </td>
    
    <td>
      a numeric string is converted; an empty value removes the key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        select
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      one of <code>
        options
      </code>
      
      . A <code>
        select
      </code>
      
       property with the key <code>
        status
      </code>
      
       also shows as the status chip on the title line
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        multiselect
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
    </td>
    
    <td>
      several of <code>
        options
      </code>
      
      , which are required
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reference
      </code>
    </td>
    
    <td>
      block ID
    </td>
    
    <td>
      a Block reference to a Typed block of the Document; <code>
        targets
      </code>
      
       limits the Block types. It implies the <code>
        references
      </code>
      
       capability
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bibliography
      </code>
    </td>
    
    <td>
      CSL-JSON item in <code>
        meta.bib
      </code>
    </td>
    
    <td>
      needs the <code>
        bibliography
      </code>
      
       capability; without it the definition drops out of the fields
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivation
      </code>
    </td>
    
    <td>
      the Derivation
    </td>
    
    <td>
      read-only
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checkbox
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
    
    <td>
      a switch; unchecked removes the key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        url
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      a link as text, edited in an <code>
        <input type="url">
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      one of <code>
        options
      </code>
      
       like <code>
        select
      </code>
      
      , whose options carry a <code>
        group
      </code>
      
       (<code>
        todo
      </code>
      
      , <code>
        doing
      </code>
      
      , <code>
        done
      </code>
      
      ). A property with the key <code>
        status
      </code>
      
       shows as the status chip on the title line; its icon and color follow the option's group
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reference-list
      </code>
    </td>
    
    <td>
      <code>
        BlockAddress[]
      </code>
    </td>
    
    <td>
      several Blocks (<code>
        { documentId, blockId }
      </code>
      
      ; <code>
        documentId
      </code>
      
       <code>
        ''
      </code>
      
       = this Document). The form lists them as removable chips and adds a Typed block of the Document from a select; entries that are no valid address are dropped (<code>
        blockAddressesOf
      </code>
      
      ), and the key is removed when none is left
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source-anchor
      </code>
    </td>
    
    <td>
      <code>
        SourceAnchor
      </code>
    </td>
    
    <td>
      a passage of a PDF: <code>
        { page, rects, quote: { exact, prefix?, suffix? } }
      </code>
      
       (<code>
        SourceAnchor
      </code>
      
      , <code>
        sourceAnchorOf
      </code>
      
      , <code>
        @skaile/forge-editor/core
      </code>
      
      ). Read-only in the form (page and quoted text); the add-on <code>
        @skaile/forge-editor-pdf-viewer
      </code>
      
       creates it from a text selection. <code>
        rects
      </code>
      
       are fractions (0 to 1) of the page; the value is kept only with a page of 1 or more and a non-empty <code>
        quote.exact
      </code>
      
      , otherwise the key is removed
    </td>
  </tr>
</tbody>
</table>

**multiselect properties.** A `multiselect` property stores its choices as a `string[]` under its key: `meta.topics = ['a', 'b']`. The details popover and the Block inspector show a multi-choice menu (a checkbox list in the React binding). An empty choice removes the key from `meta`, and entries that are not strings are dropped (`metaWithProperty`). Table cells, sort keys and the AI brief read the option labels joined by `, `, and the chat model is told to write a JSON list.

Do not declare a Property definition with a reserved `meta` key (`derivation`, `bib`, `basket`, `titleHidden`). Every Block type keeps those four itself ([Reserved meta keys](https://skaile-ai.github.io/forge-editor/guides/composites#reserved-meta-keys)). A key must not start with `$` either: `$title`, `$tags`, `$type`, `$id`, `$doc` and `$basket` are the pseudo-fields of a Block query, and the Block type config check rejects such a key.

## Property kinds

`PROPERTY_KINDS` (`@skaile/forge-editor/core`) holds one `PropertyKind` per entry of `PROPERTY_TYPES`: which filter operators apply (`ops`), the ordering key of a value (`sortKey`), the bucket it falls into when rows are grouped (`groupKey`), the aggregate functions that make sense (`aggregates`), the value as text (`text(value, definition, env)`, with `env: QueryEnv` carrying the locale and time zone), whether a cell truncates it (`longText`) and the column alignment (`align`). A query and a table read this registry instead of checking the type themselves. `statusGroupOf(definition, value)` gives the `todo`, `doing` or `done` group of a `status` value.

## Where the values live

Block properties live in the `meta` attribute of the node. Only the node of a Typed block has that attribute today, so only Typed blocks carry Block properties. The `properties` capability applies to any node that has a `meta` attribute and whose Block type lists it (`carriesProperties(node)`).

Storage is unchanged by the mechanism. In Markdown the values travel in the fence's meta JSON (`::: decision {"status":"open"}`). `changeBlockType`, conversions and the fence keep only the keys that the target Block type declares, plus the four reserved ones. A global `meta` attribute on every Block is not part of the editor: it would need a Markdown block-attribute syntax first, because the fences write `meta` only inside `::: kind {meta}`.

## The Block inspector and the other views

The Block inspector (`CompositeInspector`) shows a section „Blockeigenschaften“ (English: "Block properties") for any Block that has the `properties` capability, with one input per Property definition of its Block type. The „Dokument“ section stays the Document's own facts. The details popover, the [Block table](https://skaile-ai.github.io/forge-editor/guides/composites#block-table-and-block-inspector) and the AI brief read the same definitions. Every edit is one editor transaction, so it reaches collaborators and undo like any other edit. A Derived Block (any Block whose capabilities include `derived`) also shows its Derivation in the inspector as „Herkunft“ (English: "Origin"), with „Quelle fehlt“ ("Source missing") when the original is gone, whatever its Block type; a Block type with a `derivation` Property definition shows it once, through that definition. The model reads it as `state.derivation` (`InspectorDerivation`: `node`, `derivation`, `sourceMissing`; `null` when the Block is not Derived or the definition shows it).

An own view reads the Block properties at the caret from the framework-free model `createCompositeInspector(editor)` (`@skaile/forge-editor/composites`): `state.properties` is a `BlockProperties` (`id`, `pos`, `meta`, `definitions`), and `setField(definition, value)` writes one text value to it (the structured types `reference`, `bibliography`, `derivation`, `multiselect`, `checkbox`, `reference-list` and `source-anchor` have their own editors and are ignored). The functions below work without it:

<table>
<thead>
  <tr>
    <th>
      Function (<code>
        @skaile/forge-editor/composites
      </code>
      
      )
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        carriesProperties(node)
      </code>
    </td>
    
    <td>
      whether the node type has the <code>
        meta
      </code>
      
       attribute
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockPropertiesAt(editor, $pos, blockTypes)
      </code>
    </td>
    
    <td>
      the innermost Block around <code>
        $pos
      </code>
      
       that carries properties, with its node, or <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockPropertiesOf(node, pos, blockTypes, capabilities)
      </code>
    </td>
    
    <td>
      the <code>
        BlockProperties
      </code>
      
       of one node
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        propertyHostOf(doc, target)
      </code>
    </td>
    
    <td>
      finds the Block again by its block ID (or its position without an ID)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setBlockProperty(editor, target, key, value)
      </code>
    </td>
    
    <td>
      stores one value in one transaction; <code>
        false
      </code>
      
       when the Block is gone or carries no properties
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metaWithProperty(meta, definition, value)
      </code>
    </td>
    
    <td>
      the new <code>
        meta
      </code>
      
       object; an empty value removes the key
    </td>
  </tr>
</tbody>
</table>

`setBlockProperty` finds the Block again by its block ID, so a position read before a remote change stays usable. A key that the `fields` do not define is written as text. A table row (`CompositeRow`) carries the Property definitions of its Block type as `fields`.

**Under collaboration.** `meta` is one attribute of the Block, which Yjs syncs as a whole value; two users who each write their whole `meta` at the same moment would lose one key. In a collaboration session whose backend offers `collaboration.patchProperty` (the HTTP backend), `setBlockProperty` therefore sends the one key to `POST /api/editor/documents/:id/property`, the collaboration server writes it into the open document (`metaWithProperty`, one writer) and the sync delivers it to every client: nothing is written locally, and the call returns `true` when the Block exists. When the server refuses (the document is not open there, the user is read-only, the Block is unknown), the value is written locally and the editor shows the notice „Eigenschaft konnte nicht synchron gespeichert werden“. Writes by single-actor flows (derive, outline cleanup) stay whole-`meta` writes.


# Block types in code and JSON

> Define a Block type as data in code or in a JSON file, check it against the capability registry, and give the server the same list.

A **Block type** is what the `blockType` attribute of a [Typed block](https://skaile-ai.github.io/forge-editor/guides/composites) selects. It is data: an `id`, its presentation (`label`, `icon`, placeholders, `chrome`) and the [Block capabilities](https://skaile-ai.github.io/forge-editor/guides/block-capabilities) it lists, each with its config. A capability that the type does not list is absent from its Typed blocks: no Block properties section, no Basket menu, no Block action that `requires` it. No other field on the type switches a behaviour.

Because a Block type has no functions, a host can write it in code or keep it in a JSON file. The [Block type contract](https://skaile-ai.github.io/forge-editor/reference/block-types) lists every field.

## Block types in code

`compositeFeature({ blockTypes })` takes the list of Block types of the editor. It replaces the built-in `defaultBlockTypes(t)` (`section`, `task`, `note`, `folder`, `document`, ...; labelled in the language of `t`), so spread the built-in list to keep it.

```ts [docs/snippets/block-types-code.ts]
import { compositeFeature } from '@skaile/forge-editor/composites/vue'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites/schema'
import type { PropertiesConfig } from '@skaile/forge-editor/composites/schema'
import { coreContentFeature, coreUiFeature, createTranslator, defineEditor } from '@skaile/forge-editor/core'

const t = createTranslator('de')

const decisionProperties = {
  definitions: [
    { key: 'status', label: 'Status', type: 'select', options: [{ value: 'open', label: 'Offen' }, { value: 'done', label: 'Entschieden' }] },
    { key: 'owner', label: 'Zuständig', type: 'text' },
  ],
} satisfies PropertiesConfig

// A Block type is data: presentation plus the capabilities it lists, each with its config.
const decision: BlockType = {
  id: 'decision',
  label: 'Entscheidung',
  icon: 'i-lucide-gavel',
  titlePlaceholder: 'Was wird entschieden?',
  capabilities: [
    { id: 'container', config: { accepts: ['task', 'note'] } },
    { id: 'basket' },
    { id: 'titleHidden' },
    { id: 'properties', config: decisionProperties },
  ],
}

// `blockTypes` replaces the built-in list, so spread `defaultBlockTypes(t)` to keep the built-in types.
export const preset = defineEditor({
  features: [coreContentFeature(), coreUiFeature(), compositeFeature({ blockTypes: [...defaultBlockTypes(t), decision] })],
})
```

`capabilities` is a list of `{ id, config? }` entries. The config of each entry is checked against the `configSchema` of its capability when the editor is created: an unknown capability id, a capability listed twice, a duplicate Block type id or an invalid config throws and names the Block type and the capability. The built-in capabilities and their configs are in the [capability contract](https://skaile-ai.github.io/forge-editor/reference/block-capabilities#built-in-capabilities).

`blockTypesOf(editor)` returns the editor's own list. A `blockType` id that the list does not define shows with the presentation of `section` under its own id. A host Feature that adds Block types to the list of the preset uses `EditorFeature.blockTypes` ([Feature contract](https://skaile-ai.github.io/forge-editor/reference/feature-contract)); the lists of all Features concatenate in feature order and are validated together.

The pure accessors `propertiesOf(type)`, `sourceMediaOf(type)`, `aiBriefOf(type)` and `acceptsOf(type)` read a `BlockType` directly, without an editor; `blockTypeConfigOf(type, id)` (`@skaile/forge-editor/core`) reads the config of any capability. `capabilitiesOf(editor, node)` and `capabilityConfigOf(editor, node, id)` answer for a Block in an editor.

The tone, the chrome and the Accepted children of a Block type are described in [Typed blocks](https://skaile-ai.github.io/forge-editor/guides/composites#what-the-feature-contributes).

## Block types as JSON

A `BlockType` is plain data, so a host can keep its Block types in a JSON file (`BlockType[]`, one array) and load them when it creates the editor. This is the file of the reference app `examples/vue-two-pane`, which defines the Block type „Idee“ only there:

```json [examples/vue-two-pane/shared/block-types.json]
[
  {
    "id": "idea",
    "label": "Idee",
    "icon": "i-lucide-lightbulb",
    "titlePlaceholder": "Worum geht es bei der Idee?",
    "descriptionPlaceholder": "Ein Satz dazu, was die Idee bringt",
    "capabilities": [
      { "id": "container", "config": { "accepts": ["task", "note"] } },
      { "id": "basket" },
      { "id": "titleHidden" },
      {
        "id": "properties",
        "config": {
          "definitions": [
            {
              "key": "stage",
              "label": "Reifegrad",
              "type": "select",
              "options": [
                { "value": "spark", "label": "Funke" },
                { "value": "sketch", "label": "Skizze" },
                { "value": "plan", "label": "Plan" }
              ]
            },
            { "key": "impact", "label": "Wirkung (1–5)", "type": "number" },
            { "key": "champion", "label": "Ansprechperson", "type": "text" }
          ]
        }
      },
      { "id": "ai-brief", "config": { "purpose": "Eine Idee, die noch geprüft wird: der Inhalt hält Begründung, Varianten und offene Fragen; Aufgaben und Notizen darunter bereiten die Entscheidung vor." } },
      { "id": "export" }
    ]
  }
]
```

`parseBlockTypes(input, { registry? })` (`@skaile/forge-editor/composites` and `/composites/schema`, Vue-free) takes the text of the file or its parsed value and returns the `BlockType[]` that the `blockTypes` option takes. `mergeBlockTypes(base, extra)` layers the file over the built-in types: a type with a known id replaces that one in place, new types follow. The example keeps both calls in one module that the browser and the server import:

```ts [examples/vue-two-pane/shared/block-types.ts]
import { defaultBlockTypes, mergeBlockTypes, parseBlockTypes } from '@skaile/forge-editor/composites/schema'
import type { Translate } from '@skaile/forge-editor/core'
import file from './block-types.json'

// The Block types of this app: the library's built-in ones plus the ones `block-types.json` defines (the type „Idee“ exists
// only there). The browser (`composeEditor({ blockTypes })`) and the Nitro server (`installEditorServer({ blockTypes })`) both
// import this module, so the definitions live once. Parsing validates the file against the capabilities' config schemas; a
// mistake in it stops the server at start and the page at load, with the Block type, the capability and the path named.
const hostTypes = parseBlockTypes(file)

/** The built-in Block types in the language of `t`, with the types of `block-types.json` after them. */
export const blockTypesOf = (t: Translate) => mergeBlockTypes(defaultBlockTypes(t), hostTypes)
```

`blockTypesOf(t)` then goes to `composeEditor({ blockTypes })`, to `compositeFeature({ blockTypes })` or to the `blockTypes` prop of `AdvancedEditor`.

### What `parseBlockTypes` checks

Every entry is checked against the capability registry. By default that is the built-in capabilities and those of the composites feature. A host whose Features declare more capabilities passes `registry: preset.capabilities`.

- `id` (letters, digits, `_`, `-`), `label` and `icon` are required, and ids are unique.
- A capability that the registry does not know is refused.
- One capability may be listed once.
- Its `config` must pass the `configSchema` of the capability. A capability without a schema takes no config.

`parseBlockTypes` throws one `BlockTypeJsonError` for the whole file. `message` has one line per problem, and `issues` has the same as data (`index`, `typeId`, `capability`, `path`, `message`):

```text
Block type "idea": capability "teleport" config: unknown capability; no feature declares it (known: container, title, properties, ...)
Block type "idea": capability "properties" config, definitions[1].type: Invalid option: expected one of "text"|"textarea"|...
Block type "idea": id: duplicate Block type id (first defined by entry 0)
```

A mistake in the file stops the server at start and the page at load, with the Block type, the capability and the path named.

The file has one language, so labels, placeholders and Property definition labels in it are not translated; the built-in types still follow the editor's language. Icons are `i-lucide-*` names. A bundler that only ships the icons it finds in the sources of the app (Nuxt UI) needs the file scanned too (`examples/vue-two-pane/vite.config.ts`).

In the example, „Idee“ appears in the `/` menu as `/idea`, in the [Document tree](https://skaile-ai.github.io/forge-editor/guides/document-tree) and in the Block inspector. It has a Basket, the [Block properties](https://skaile-ai.github.io/forge-editor/guides/block-properties) Reifegrad, Wirkung and Ansprechperson, an AI brief and the „Exportieren“ action, and it accepts tasks and notes as nested Typed blocks.

## The server

The collaboration schema does not depend on Block types, because they are storage and not schema. Only the AI chat needs them on the server. Pass the same list to `installEditorServer(nitroApp, { ports, blockTypes })`:

```ts [examples/vue-two-pane/server/plugins/editor.ts]
import path from 'node:path'
import { createJsonAdapter } from '@skaile/forge-editor/adapters/json'
import { defineEditorConfig, serverConfig } from '@skaile/forge-editor/config'
import { createJsonCommentStore } from '@skaile/forge-editor/comments/json'
import { installEditorServer } from '@skaile/forge-editor/server/nitro'
import { defineNitroPlugin } from 'nitropack/runtime'
import { createTranslator } from '@skaile/forge-editor/core'
import { LOCAL_USER } from '../../shared/identity'
import { blockTypesOf } from '../../shared/block-types'
import { dataDir } from '../data-dir'

// The whole backend: documents as `<id>.json` (and the live collaboration state beside them) in one directory, comments
// in one JSON file, the editor's REST routes and the collaboration websocket on the Nitro app. The document index (titles
// and folders, which the JSON adapter does not keep) is served by `routes/api/two-pane-index.*`.
export default defineNitroPlugin((nitroApp) => {
  installEditorServer(nitroApp, {
    ports: {
      ...createJsonAdapter({
        dir: path.join(dataDir, 'documents'),
        // Everyone is the local user. Without this, the adapter signs in an anonymous dev user outside production only.
        authenticate: async () => ({ id: LOCAL_USER.id, username: LOCAL_USER.name, color: LOCAL_USER.color }),
      }),
      comments: createJsonCommentStore({ file: path.join(dataDir, 'comments.json') }),
    },
    // `ai` (presets, roles, rate limit) and `collab` come from the one editor config; the AI routes need a key (`AI_KEY`).
    ...serverConfig(defineEditorConfig({ ai: { apiKey: process.env.AI_KEY } })),
    // The same Block types as the browser (`shared/block-types.json` over the built-in ones): the AI chat describes them to the model itself.
    blockTypes: blockTypesOf(createTranslator()),
  })
})
```

- `EditorServerOptions.blockTypes` is the option of `installEditorServer`; `AiHandlerContext.blockTypes` is the same for hand-wired handlers, and a Nuxt host passes `provideEditorServer({ ports, blockTypes })`.
- `POST /api/ai/chat` then describes these types to the model (`aiBlockTypesOf(blockTypes)`: id, label, Block properties as fields, the `ai-brief` purpose) and ignores the `blockTypes` in the request. Import the same JSON and loader on both sides so the definitions live once.
- Without `blockTypes` the server takes the `blockTypes` of the client. The `convert` `targets` and the host `blocks` of the request still come from the client.
- The server describes the host's types in the language of the translator it built them with (German for `createTranslator()`).

`blockTypes` is storage on the server: it does not change the schema that the collaboration route builds.


# Block UI (drag handle, hover actions)

> Add the drag handle, hover targeting, block actions and block-range selection with blockUiFeature().

## Adding block UI

```ts
import { blockUiFeature } from '@skaile/forge-editor/block-ui/vue' // or '@skaile/forge-editor/block-ui/react'
const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), blockUiFeature()] })
```

`blockUiFeature()` adds the drag handle on the hovered block's left, hover targeting, the `BlockActionsOverlay` (the Block actions of the features and of the host) 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.

## Where block actions appear

`blockUiFeature({ actions })` (or `composeEditor({ …, blockUi: { actions } })`; `BlockUiOptions`) chooses the surfaces that render block actions:

<table>
<thead>
  <tr>
    <th>
      <code>
        actions
      </code>
    </th>
    
    <th>
      Surface
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        'hover'
      </code>
      
       (default)
    </td>
    
    <td>
      the bar of the block under the pointer, at the editor's right edge
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'toolbar'
      </code>
    </td>
    
    <td>
      the bar of the block holding the selection (a caret in the block, a node selection), shown at the block's corner as long as the selection stays in it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'both'
      </code>
    </td>
    
    <td>
      both; where the pointer hovers the selected block only the toolbar shows, so a block never has two bars
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'none'
      </code>
    </td>
    
    <td>
      no action bar; the drag handle, targeting and block-range selection stay
    </td>
  </tr>
</tbody>
</table>

The Block UI addresses the **outermost block** below the nearest block container (the document or a Typed block's body), resolved by `outerBlockAt($pos)` / `outerBlocksAt($pos)` from `@skaile/forge-editor/block-ui`. A list item or a quote paragraph is not a Block of its own: with the caret or the pointer in one, the hover bar, the toolbar actions and the drag handle (hover and permanent) address the whole list, nested lists included, or the whole quote. A paragraph in a Typed block's body is its own block, a Typed block's chrome (title, description, tags) stands for the Typed block, and a Typed block inside a Typed block is a block of its own. Block IDs are unchanged: nested paragraphs keep theirs, so AI proposals and comments on them still work.

The toolbar bar is the same `BlockActionsOverlay` with `surface="toolbar"` and `persistent`; its root carries the class `block-actions-toolbar` next to `block-actions`, so a host can style it apart from the hover bar. A caret in a Typed block's title, description or tags row addresses the Typed block; a selection across several top-level blocks has no toolbar. While the editor is read-only, both bars offer only the actions marked `readOnly` (see below).

Each Block action may narrow itself with `placement: 'hover' | 'toolbar' | 'both'` (default `'both'`); the built-in actions (convert, duplicate, delete, AI, Typed block summary) keep the default. Abilities are separate: an ability (`ABILITY`, such as `block.delete`) stays a permission ("can"), so removing `block.delete` hides the action on every surface, while `actions` and `placement` only choose where the allowed actions are offered. Hosts that used to strip `block.convert`, `block.duplicate` and `block.delete` abilities only to empty the hover bar can pass `actions: 'none'` (or `'toolbar'`) instead and keep the abilities, so `convertMenuItems` and the ⌘K palette are unaffected.

The toolbar addresses the innermost block, so with the caret in a paragraph of a Typed block's body the Typed block's own actions (split, merge, export, focus) would not be offered. An action that belongs to the Typed block declares `target: 'typedBlock'` (default `'block'`): on the toolbar it is then checked against and runs with the nearest Typed block around the selected block, or the block itself when that is a Typed block (`typedBlockAround(editor, target)` from `@skaile/forge-editor/block-ui`). `ability`, `requires`, `blockTypes` and `isVisible` see that Typed block, and `ctx.node` and `ctx.pos` are its own; with no Typed block around (a paragraph at the document root) the action is absent. With nested Typed blocks the innermost one wins. The bar still docks at the selected block's corner. The hover bar ignores `target`: hovering a Typed block's chrome already addresses the Typed block.

## Actions in a read-only editor

A Block action is hidden while the editor is read-only unless it sets `readOnly: true` ("offered in a read-only editor too", default `false`). `blockActionsFor(editor, target, actions, surface)` applies the rule, so the hover and the toolbar bar behave the same in the Vue and React overlays; the bar shows as soon as one action remains. Mark only actions that do not change the document: the built-in `composite-details` action („Details“, the info icon, hover bar) is the first one and opens the details popover of the Typed block, which renders read-only in such an editor. The drag handle stays hidden. `selectedBlockOf` still resolves the selected block in a read-only editor; an action that mutates is filtered out by the missing `readOnly` flag, so it needs no `isEditable` check of its own.

An action may also set `onHover(ctx, entering)`: the overlay calls it with `true` when the pointer enters the action's button and with `false` when it leaves, for example to highlight the block the action is about. It gets the same `ctx` as `run` (`BlockActionContext`) and works for `run` and `menu` actions alike.

## Handles per block

Which blocks have which handle follows the settings and the block:

- **Blocks with a Block type icon** (Typed blocks, see [Typed blocks](https://skaile-ai.github.io/forge-editor/guides/composites)) have no standard handle: their icon is the handle. Dragging it selects the Typed block 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). Eligible are the blocks the hover handle can target (see below) at any depth. Not eligible: Typed block chrome (title, description, tags), everything inside a list, quote or table (the list, quote or table is the block), and blocks with a Block type icon. A nested block whose handle would cover its container's handle on the same line 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.

## Blocks with icons of their own in the top-right corner

The hover bar sits at the editor's right edge, which a node view that draws its own icons there (status badges, a Block type or properties button) would have covered. Such a block marks those elements with the attribute `data-block-corner` (`BLOCK_CORNER_ATTR`, `blockCornerOf(dom)` from `@skaile/forge-editor/block-ui`): the bar docks immediately left of the leftmost marked element (4px gap) and is centred on the first one's row, so bar and icons read as one row. Marked elements inside a nested block's own node view (`[data-node-view-wrapper]`) belong to that block, hidden ones (no layout box) are ignored, and a block without marked elements keeps the placement at the editor's right edge. The overlay re-measures when a marked element resizes; Vue and React behave the same.

## Dragging from outside the editor

`startBlockDrag(editor, event, pos)` (`@skaile/forge-editor/core`) starts such a drag from any element outside the editor's DOM: call it from the element's `dragstart`.


# Charts: bar, line, pie and scatter over a query

> The add-on @skaile/forge-editor-charts: the Block type chart, its configuration and the query it derives, the pure Vega-Lite specification, the node view with a chart editor for Vue and React, and the render target chart-svg.

The add-on `@skaile/forge-editor-charts` draws charts from the Blocks of the workspace. A **chart** is a Typed block of the Block type `chart`. It stores its **configuration** only (`meta.chart`, a [Block property](https://skaile-ai.github.io/forge-editor/guides/block-properties) that has no form field); the numbers are the answer to a [query](https://skaile-ai.github.io/forge-editor/guides/data-views) whenever the chart is drawn, so a change of a task changes the chart.

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Where
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        chartBlockTypes(locale)
      </code>
    </td>
    
    <td>
      the Block type <code>
        chart
      </code>
    </td>
    
    <td>
      editor and server
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        toQuery(config)
      </code>
    </td>
    
    <td>
      the <code>
        DataQuery
      </code>
      
       a chart asks: its own query plus group and aggregates
    </td>
    
    <td>
      anywhere
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        toVegaLite(config, result)
      </code>
    </td>
    
    <td>
      the pure Vega-Lite specification of the chart
    </td>
    
    <td>
      anywhere
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        chartNodeViews
      </code>
    </td>
    
    <td>
      the node view that draws the chart and carries the chart editor
    </td>
    
    <td>
      editor (<code>
        /vue
      </code>
      
      , <code>
        /react
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        chartTargets({ answer })
      </code>
    </td>
    
    <td>
      the <a href="https://skaile-ai.github.io/forge-editor/guides/render">
        render target
      </a>
      
       <code>
        chart-svg
      </code>
    </td>
    
    <td>
      server
    </td>
  </tr>
</tbody>
</table>

## The configuration

```ts
interface ChartConfig {
  type: 'bar' | 'line' | 'pie' | 'scatter'
  /** Which Blocks the chart is drawn from (Block types, filter). */
  query: DataQuery
  /** The x axis (bar, line, scatter) or the slices (pie): a property key or a pseudo-field such as `$type`. */
  x: string
  /** What is measured: an aggregate of a field, named `as`. */
  series: { field?: string, fn: AggregateFn, as: string }[]
  color?: string
  stack?: boolean
}
```

`toQuery(config)` copies `config.query` and adds `group: { field: config.x, hideEmpty: true }`, one aggregate per series and a row limit, and selects only the fields the chart reads. The Block index answers the grouping (`backend.index.query`), so a backend that groups in the database sends only the rows the chart needs. A scatter chart has no grouping: it reads the rows. Each group has one point per series: `count` counts the rows, `sum`, `avg`, `min` and `max` read the numbers of `field`. Blocks without a value in the x field are left out of the chart.

The Block's own chart in the kitchen sink counts tasks per status:

```json
{ "type": "bar", "query": { "v": 1, "source": { "kind": "blocks", "blockType": "task" } }, "x": "status", "series": [{ "fn": "count", "as": "Anzahl" }] }
```

## The Vega-Lite specification

`toVegaLite(config, result)` returns a Vega-Lite 6 specification as a plain object. It is pure: the same configuration and answer give the same specification, and it carries no size. The data are the points in long form (`x`, `series`, `value`), so any number of series share one encoding. `bar` stacks several series (or puts them side by side with `stack: false`), `line` takes a time axis when every x value is a date and a number axis for numbers, `pie` shows the first series, `scatter` plots two numeric fields. A single series takes `color`; several take the palette and a legend. Both the node view (`vega-embed`) and the server target (`vega`) draw this one specification.

## Install and wire

```ts
import { defaultBlockTypes } from '@skaile/forge-editor/composites'
import { chartBlockTypes } from '@skaile/forge-editor-charts/client'
import { chartNodeViews } from '@skaile/forge-editor-charts/vue' // or '/react'

const editor = composeEditor({
  content: 'rich',
  blockTypes: [...defaultBlockTypes(t), ...chartBlockTypes('de')],
  // The node views by Block type id: a `chart` block draws its chart, every other type keeps its own view.
  blockNodeViews: chartNodeViews,
})
```

`blockNodeViews` is an option of the composites feature (`composeEditor`, `AdvancedEditor`, `ComposedSurface`): a node view per Block type id that replaces the standard Typed block view for that type. The title, the chrome and the content of the block stay; the view adds the chart.

```ts
import { createRenderer, markdownTarget } from '@skaile/forge-editor/adapters/render'
import { answerFromDocument, chartBlockTypes, chartTargets } from '@skaile/forge-editor-charts/server'

// installEditorServer({ ports: { render }, blockTypes })
const answer = answerFromDocument({ load: async id => (await getDocument(id))?.content ?? null, blockTypes: [...serverBlockTypes] })
export const render = createRenderer([markdownTarget(), ...chartTargets({ answer })])
```

The entry `@skaile/forge-editor-charts/client` reaches neither `vega` nor the render target; `vega-embed` loads when the first chart draws. The `/server` entry reaches no editor code and needs no DOM.

## In the editor

The node view asks `backend.index.query` (the Blocks of every Document the user may read) and, for a backend without it, answers the same query over the Blocks of the open Document. It asks again while the chart is visible: after a change of the block or of the Blocks (debounced), and every few seconds, because Blocks of other Documents change without the editor hearing of it. A query the Block index refuses shows its message instead of a chart.

An editable chart has a **Diagramm einstellen** button that opens the chart editor under the chart: the chart type, the x field, the series (aggregate, field, name), the colour, stacking, and the library's [query builder](https://skaile-ai.github.io/forge-editor/guides/data-views) for the Blocks the chart is drawn from. Every change writes `meta.chart` through `setBlockProperty`, one key, so collaborators' other properties survive.

## Render target

`chartTargets({ answer })` gives `chart-svg` for a Block of the type `chart`: the query is answered by `answer` (`answerFromDocument` reads the Blocks of the Document the render is for), the specification is compiled with `vega-lite`, and `vega` renders the SVG without a DOM or a canvas. The file is named after the chart's title. A render of any other block fails with a message the client shows.

## Strings

The add-on keeps its own small catalog in German and English (`CHARTS_MESSAGES`, `createChartsTranslator(locale, overrides)`), because the library's message keys are closed over the library's own strings. `chartBlockTypes(locale)` takes the language; the node view reads it from the editor context.

## In the demo app

The charts always draw on `/kitchen-sink/databases`: the page imports the add-on's `/client` (`chartBlockTypes`) and `/vue` (`chartNodeViews`) entries itself, whatever `NUXT_PUBLIC_ADDONS_CHARTS` says, and gives its editor a backend without a Block index, so the charts and the data views beside them answer from the open document. Its „Task tracker“ sample has eight tasks, two data views and two charts over them. `NUXT_PUBLIC_ADDONS_CHARTS=1` (see `.env.example`; a runtime flag, read by the server and the browser alike) adds the server's target `chart-svg`, the SVG export; without it the page shows a hint card. The documents under `/documents` load the Block type and the node view only with the flag on. See [Kitchen sink: learning path](https://skaile-ai.github.io/forge-editor/guides/advanced-nuxt-example#databases).


# Citations

> Cite a bibliography entry of the Document with the inline cite node: insert it with /zitat, read it as (Autor Jahr), and keep it through Markdown export and import.

A **Cite** is an inline node (`cite`) that names one Bibliographic record of the Document by its citation key. The Bibliographic record is the CSL-JSON in `meta.bib` of a Typed block (a `paper`, a `document`, a `report`). The Cite shows the short form of that record, `(Autor Jahr)`, and, when it has a locator, `(Autor Jahr, S. 12)`.

A Cite is not a reference chip. The reference chip (`[@<block id>]`) points at a Block and shows its title or short citation; a Cite points at a Bibliographic record and always reads as a citation in running text. Both nodes live in the `composites` schema, because the Markdown export needs them on the server too.

## Insert a citation

Type `/zitat` (in the slash menu: „Zitat einfügen“) or type `[cite:` by hand. A picker lists the bibliography entries of the open Document: every Typed block with `meta.bib` whose short citation, full citation or citation key contains what you typed. Choose one and the Cite is inserted, followed by a space.

The Cite has the attributes `key` and `locator`:

<table>
<thead>
  <tr>
    <th>
      Attribute
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      the citation key of the entry. It is the key that <code>
        bibtexOf
      </code>
      
       writes into the <code>
        .bib
      </code>
      
       entry: the first author's family name, the year and the first word of the title, in lowercase ASCII (<code>
        lecun2015deep
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        locator
      </code>
    </td>
    
    <td>
      the position inside the cited work (<code>
        S. 12
      </code>
      
      ); <code>
        null
      </code>
      
       cites the work as a whole
    </td>
  </tr>
</tbody>
</table>

The key is derived from the record. When two entries of one Document derive the same key, the first one in document order is the one a Cite resolves to.

## What the chip shows

The chip resolves its key against the entries of the Document on every change of the Document. It shows the short form from `citeShort` (`Doe 2024`, `Doe & Roe 2024`, `Doe et al. 2024`; the first 40 characters of the title when the entry has no author) and the full form from `citeFull` as its tooltip. If the author, the year or the title of the entry changes, the chip changes with it.

<table>
<thead>
  <tr>
    <th>
      Action
    </th>
    
    <th>
      Result
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Click
    </td>
    
    <td>
      reveals the bibliography entry in the Document
    </td>
  </tr>
  
  <tr>
    <td>
      Double click or right click
    </td>
    
    <td>
      opens a field for the locator („Stelle“) in an editable editor
    </td>
  </tr>
  
  <tr>
    <td>
      Key without an entry
    </td>
    
    <td>
      the chip shows <code>
        (key)
      </code>
      
      , greyed and struck through, with the tooltip „Literaturangabe nicht gefunden“
    </td>
  </tr>
</tbody>
</table>

## Markdown

A Cite is written as `[cite:<key>]` or, with a locator, `[cite:<key>, <locator>]`. A `]` inside the locator is written `\]`.

```md
Deep learning works [cite:lecun2015deep, S. 12] and has been replicated [cite:doe2020other].
```

The token is not Pandoc's `[@key]`: `[@` belongs to the reference chip and to mentions. `[cite:` parses straight back into the node when Markdown is imported, edited in source mode or written by an AI; there is no second step that checks the key. A key that names no entry is kept and shows as a gone chip.

The Block index text of a Block that holds a Cite contains `[cite:<key>]`, so a search for the key finds the Block.

## Framework bindings

The Vue and React `compositeFeature` give the node its view (`CiteView`, also exported from `@skaile/forge-editor/composites/vue` and `@skaile/forge-editor/composites/react`). A binding that supplies no `cite` node view (`CompositeNodeViews.cite` is optional) shows the static form `(key, locator)`. Servers build their schema with `compositeSchemaExtensions()`, which includes the node.

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        CiteNode
      </code>
      
      , <code>
        CITE_NODE
      </code>
      
      , <code>
        CITE_TRIGGER
      </code>
    </td>
    
    <td>
      the node, its name and the popup trigger <code>
        [cite:
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        citeMarkdown
      </code>
      
      , <code>
        citeAttrsOf
      </code>
    </td>
    
    <td>
      the Markdown form of a Cite and its typed attributes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        citeEntriesOf(doc)
      </code>
      
      , <code>
        resolveCite(editor, key)
      </code>
      
      , <code>
        citeText(label, locator)
      </code>
    </td>
    
    <td>
      the entries a Cite can name, what a Cite shows now, and the chip text
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        citeSuggestion(t)
      </code>
    </td>
    
    <td>
      the options of the <code>
        [cite:
      </code>
      
       popup
    </td>
  </tr>
</tbody>
</table>


# Collaboration on the client

> Collaboration is a feature: mount a surface with a Yjs session, per-client undo, authors and comments, positions that survive concurrent edits, and matching schemas.

## Mounting a session

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 '@skaile/forge-editor/collab/vue'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { EditorSurface } from '@skaile/forge-editor/vue'
import * as Y from 'yjs'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), 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 `@skaile/forge-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 '@skaile/forge-editor/collab/react'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { EditorSurface } from '@skaile/forge-editor/react'
import { useEffect, useMemo, useState } from 'react'
import * as Y from 'yjs'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), 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 `@skaile/forge-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. The column lays its cards out with the framework-free `layoutMargin` / `createMarginController` of `@skaile/forge-editor/comments`: the active thread sits exactly at its text's line, the others are one-line cards out of its way, resolved threads sit behind „Erledigt (n)“, and a thread whose text was deleted stays greyed out at the deletion point („Text gelöscht“) until undo re-attaches it ([Authors and comments guide](https://skaile-ai.github.io/forge-editor/guides/authors-and-comments)).

## 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 host's `schema` option of `createCollabServer`/`installEditorServer` (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, Typed blocks, mentions, authors and comments marks, block IDs). Custom `blockTypes` 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 `forgetDocument(id)` of the `EditorServer` handle on the server before deleting a document (see [Deleting a document](https://skaile-ai.github.io/forge-editor/guides/editor-ports#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 [Backend and collaboration](https://skaile-ai.github.io/forge-editor/tutorial/backend-and-collaboration)) belongs to that schema too: pass its framework-free node in the server's `schema` option (`schema: () => [...advancedSchemaExtensions(), YourNode]`); a custom server builds `getSchema([...advancedSchemaExtensions(), YourNode])` itself.


# Collections: an ordered list of Blocks

> The collection Block type: its items and stored query, the node view with reorder and „Aus Abfrage füllen“, the block action that adds a Block, and the Markdown export.

A **collection** is a [Typed block](https://skaile-ai.github.io/forge-editor/guides/composites) of the Block type `collection` that lists other Blocks, in an order the user sets. It points at its Blocks and holds none of them: removing an entry, or the collection, never touches the Block. A reading list, the Blocks of a chapter that live in several Documents, or the hits of a [query](https://skaile-ai.github.io/forge-editor/guides/query) a person curated are collections.

`defaultBlockTypes(t)` lists the type (label „Sammlung“ / "Collection", icon `i-lucide-list-checks`, capabilities `container` with `'all'`, the colour basket, `properties` and `export`), so a host that spreads the built-in list has it.

## What a collection stores

Two [Block properties](https://skaile-ai.github.io/forge-editor/guides/block-properties) in the Typed block's `meta`:

<table>
<thead>
  <tr>
    <th>
      Key
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        items
      </code>
    </td>
    
    <td>
      <code>
        reference-list
      </code>
    </td>
    
    <td>
      the entries, in order: <code>
        BlockAddress[]
      </code>
      
       (<code>
        { documentId, blockId }
      </code>
      
      ; <code>
        documentId
      </code>
      
       <code>
        ''
      </code>
      
       is a Block of this Document)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        text
      </code>
      
      , hidden
    </td>
    
    <td>
      an optional <code>
        DataQuery
      </code>
      
       as JSON text, for „Aus Abfrage füllen“; the properties form never shows it
    </td>
  </tr>
</tbody>
</table>

The framework-free functions in `@skaile/forge-editor/composites` read and build these values:

```ts
import { collectionItemsOf, collectionQueryOf, withCollectionItems } from '@skaile/forge-editor/composites'

collectionItemsOf(node)          // BlockAddress[]; entries that are no valid address are dropped
collectionQueryOf(node)          // DataQuery | null; null for no query, bad JSON or a query that names no Block type
withCollectionItems(node, items) // a copy of node's meta with `items` as its list; an empty list removes the key
```

`collectionQueryOf` checks only the shape (`v: 1`, a `blocks` source that names a Block type). Which fields exist is the job of `validateQuery`; the route answers `422` with the issues when the stored query is wrong.

Write the list through `setBlockProperty` (or `setCollectionItems(editor, blockId, items)`, which does that): it writes the one key, so two collaborators who edit different keys of the same block keep both changes.

## The view

Both bindings supply a node view for the collection (`CompositeNodeViews.collection`): the usual Typed block view with the entries below its content.

- Every entry is a reference pill with the title of its Block (an entry whose Block is gone shows „Block gelöscht“). A click reveals the Block in the open Document, or opens it in its own Document through the host's `openBlock`.
- Move up, move down and remove buttons appear beside an entry while the editor is editable.
- „Aus Abfrage füllen“ shows when the collection has a stored query and `backend.index.query` exists. It runs the query, appends the hits that are not listed yet in the order of the answer, and tells the user how many it added (a collection never lists itself). A failed query leaves the list as it is and says why.

The view is `features/composites/collection-model.ts` (`collectionViewOf`, `moveCollectionItem`, `removeCollectionItem`, `fillCollectionFromQuery`), shared by `CollectionView.vue` and `CollectionView.tsx`. A binding that renders no live content leaves `collection` out of `nodeViews`; the collection then renders as any Typed block and its entries stay in `meta.items`.

Both bindings pass `typedBlockViewOptions` (`@skaile/forge-editor/composites`) to the renderer of `typedBlock` and `collection`, so a block whose Block type changes gets the view of its new type. A host that builds its own `nodeViews` does the same:

```ts
compositeNodes({
  typedBlock: VueNodeViewRenderer(CompositeView, typedBlockViewOptions),
  collection: VueNodeViewRenderer(CollectionView, typedBlockViewOptions),
  reference: VueNodeViewRenderer(ReferenceView),
})
```

## Add a Block from anywhere

The block action `collection-add` („Zu Sammlung hinzufügen“, Ability `composite.meta`) is on every Typed block. Its menu lists the collections of the open Document by title (one that holds the Block already is disabled; the action is hidden when the Document has no other collection), and choosing one appends the Block's address.

## Markdown export

The Markdown form of a collection lists its entries as reference lines, one chip per paragraph, in the stored order:

```md
# Lesestoff

[@3f0c…]

[@doc-9#a41b…]
```

An entry in another Document carries the Document first (`[@<documentId>#<blockId>]`), the same form as a [reference chip](https://skaile-ai.github.io/forge-editor/guides/composites). `documentCompositeMarkdown`, `headingsMarkdown` and the `markdown` render target all go through `compositeChromeBlocks`, which appends `collectionItemBlocks(schema, node)` for a collection. The meta line leaves out hidden properties (the stored query) and `reference-list` properties, so neither shows as `[object Object]`.


# Composites and the settings UI

> Add Typed blocks with Block types, chips and property views, plus the settings panel and the file-import integration.

`compositeFeature()` adds Typed blocks: Container blocks with a Block type, a title, a description, tags, the Block properties their Block type defines and a body that may hold more blocks and Typed blocks. It needs no AI, media, transcript or Yjs code (`bun run check:editor-entries` proves it with the `composites` fixture), and it adds no dependency beyond the core peers.

```vue
<script setup lang="ts">
import { compositeFeature } from '@skaile/forge-editor/composites/vue'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { EditorSettingsPanel, EditorSurface, EditorToolbar } from '@skaile/forge-editor/vue'
import type { Editor } from '@tiptap/vue-3'
import { shallowRef } from 'vue'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), compositeFeature()] })
const editor = shallowRef<Editor>()
const tab = shallowRef<string>()
</script>

<template>
  <EditorToolbar :editor="editor" />
  <EditorSurface v-model="content" :preset="preset" settings-ui="external" @ready="editor = $event" @settings-open="tab = $event ?? tab" />
  <EditorSettingsPanel v-model:tab="tab" :editor="editor" />
</template>
```

Import the feature CSS after `tailwindcss`, `@nuxt/ui` and `core.css`:

```css
@import "@skaile/forge-editor/styles/composites.css";
```

On React the feature is `compositeFeature()` from `@skaile/forge-editor/composites/react`, with the same components (`CompositeTable`, `CompositeInspector`, `CompositeView`, `CompositeDetails`, `CompositeFieldEditor`, ...) and hooks (`useCompositeRows`, `useCompositeAnchors`); the framework-free `@skaile/forge-editor/composites` holds `compositeFeatureCore(ui, options)`, the nodes, conversions, fences and the models behind the hooks (`createCompositeRows`, `observeCompositeAnchors`). `EditorToolbar`, `EditorSurface` and the settings components come from `@skaile/forge-editor/react` ([simple React setup](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-react)).

## What the feature contributes

- **Nodes and node views:** `typedBlock` (attributes `blockType`, the id of the Block type, and `meta`, the Block properties) with its title, description and tags children. The title, description and tags are *chrome*: they cannot be selected, dragged, deleted or duplicated apart from their Typed block. Stored documents with the old `metaVisible` attribute still load; the attribute is dropped.
- **Toolbar group:** insert a Typed block of the default Block type, „In Block umwandeln“ (Block type menu for the block at the caret) and „Gliederung umwandeln“ (headings ↔ Typed blocks, the direction of the Structure mode first; the last entry opens the settings when some feature contributes a tab).
- **/ commands, block actions and overlay:** one insert command per Block type, the heading ↔ Typed block conversions, the Typed-block-specific hover action (Markdown export of a Typed block whose Block type lists the `export` capability, the built-in `document`) and the chip/details-popover overlay ([below](#chips-and-details-popover)).
- **Conversion providers** (below), **Markdown ::: fences** for import (`::: kind {meta}`, where `kind` is the Block type id, or `::: kind #<block id> {meta}`: a Typed block that a `reference` chip or `reference` property points at writes its block id after the Block type id, so `[@<id>]` references survive a Markdown round trip; other fences carry no id; `## title`, `> description`, `Tags: #a #b`, body, `:::`; nested fences close with the same bare `:::`; a fence of a Block type that is not registered stays an `opaqueFence` and is written back verbatim) and export, **legacy migration** (`section` blocks of old documents become Typed blocks; servers read stored content through `currentContent` of `@skaile/forge-editor/server`), and the `structure` pipeline stage that turns Markdown headings into Typed blocks or Typed blocks into headings according to the Structure mode (Structure mode nests Typed blocks, Flat mode uses headings).
The fences are an import/export format, not storage: the stored document JSON (Yjs in a collaborative session) is canonical, and a fence carries a block ID only for a referenced Typed block, so an external edit of exported Markdown gives the other blocks new IDs on import ([ADR-0001](https://github.com/skaile-ai/forge-editor/blob/main/docs/adr/0001-database-canonical-markdown-export.md)).
- **Typed blocks with a Source, and Derived blocks.** The Block types `document`, `recording` (audio/video), `paper` and `book` (PDF) and `figure` (image) list the `source` capability (config `{ media }`, a list of `SOURCE_MEDIA_TYPES`): the first `audio|video|image|file` block of their body is the Source media, which `sourceOf(composite, blockTypes)` returns with its asset reference and `hash`. A child Typed block of the `rendition` Block type (shown as “Readable rendition”) holds the readable form (transcript, full text, description) as a block tree. Any Typed block may carry `meta.derivation` (`Derivation`: `from` an asset or a block, `method`, `model`, `createdAt`, `inputHash`, `outputHash`, `output`) and is then a Derived block; `derivedChildrenOf(composite)` lists the Derived blocks in a Typed block's body, `derivationOf`, `derivationState` (`stale`: the source's `hash` or, for a block source, its Markdown hash differs from `inputHash`; `edited`: the body differs from `outputHash`) and `bodyMarkdown` read the record. A Derived block starts collapsed (chevron, caret expands it), carries an „abgeleitet“ badge, and its chrome shows „Quelle geändert“ for an asset source that changed; the details card additionally shows method, model, date, „bearbeitet“, „Quelle geändert“ for block sources and a link to the stored raw output. Existing Typed blocks (of any Block type) with the former `meta.transcript` property are migrated on load into such a Readable rendition (on load, in the Feature's `migrateContent` hook and in `currentContent` on the server; the stored property decides, not the Block type).
- **Bibliography and references.** The property types `bibliography` (`meta.bib` as CSL-JSON, `CslItem`, the Bibliographic record; form editor with „DOI abrufen“ and „BibTeX kopieren“; `bibOf`, `cslOf`, `citeShort`, `citeFull`, `bibtexOf`, `yearOf`), `reference` (a Block reference to a Typed block of the document, `PropertyDefinition.targets` limits the Block types) and `derivation` (read-only) extend the Property definitions of the `properties` capability (the `bibliography` capability gives the type the record, the `references` capability the `reference` chips); the block action „Literaturangabe exportieren (BibTeX)“ downloads a `.bib`. The inline `reference` chip (`ReferenceNode`) is inserted with `[@` or `/verweis`, shows the target's `citeShort` or title, takes a locator („Stelle“: `S. 12`, `3:07`) and reveals the target on click; with a locator `revealSource(editor, targetId, locator)` also seeks the source audio/video or opens the PDF viewer at that page. Markdown is `[@<block id>]` / `[@<block id>, <locator>]`; the details card lists backlinks („Verweise“, `compositeBacklinks`). Transcript segments carry `start`/`end` (seconds) and a `mm:ss` button that seeks the source (`seekSource`).
- **Citations.** The inline `cite` node (`CiteNode`) is inserted with `/zitat` or `[cite:`, names a bibliography entry of the Document by its BibTeX key, shows `(Autor Jahr)` and is written as `[cite:<key>, <locator>]` in Markdown ([Citations](https://skaile-ai.github.io/forge-editor/guides/citations)).
- **Settings tab editing:** the Structure mode (Structure mode or Flat mode), the scope of „Gliederung umwandeln“ without a selection, the root of a file browser's tree and the default Block type of new Typed blocks. The values live in the shared settings model, so every panel and editor of the app sees the same choice.
- **Baskets, hidden titles, focus and splitting.** `meta.basket` (a Basket from `compositeFeature({ baskets })`) and `meta.titleHidden` (title hidden) are reserved `meta` keys that every Block type keeps ([below](#reserved-meta-keys)); focus mode (`focusComposite`, block action „Fokussieren“, the focus chip) the split commands (`splitCompositeAtCaret`, `splitCompositeByLength` and their four block actions) and the merge command (`mergeCompositeWithNext`, block action „Mit nächstem zusammenführen“) are part of the feature. The setting `blocks.splitTargetChars` (default 1500) has a field „Zielgröße beim Teilen (Zeichen)“ in the „Bearbeiten“ tab. All of it is explained in [Content tree mechanics](https://skaile-ai.github.io/forge-editor/guides/content-tree).

Block types are data. `compositeFeature({ blockTypes })` replaces the built-in `defaultBlockTypes(ctx.t)` (section, task, ...; labelled in the context's language). A `BlockType` is an `id`, its presentation (`label`, `icon`, `titlePlaceholder`, `descriptionPlaceholder`, `chrome`) and `capabilities`: a list of `{ id, config? }` entries, one per [Block capability](https://skaile-ai.github.io/forge-editor/reference/feature-contract) the type supports. A capability the type does not list is absent from its Typed blocks: the Block inspector shows no properties, no Basket menu appears, the block actions that `require` it are not offered. No other field on the type switches a behaviour. `blockTypesOf(editor)` returns the editor's own list and an unknown `kind` id falls back to the `section` presentation under its own label.

```ts
const blockTypes: BlockType[] = [
  ...defaultBlockTypes(ctx.t),
  {
    id: 'decision',
    label: 'Entscheidung',
    icon: 'i-lucide-gavel',
    capabilities: [
      { id: 'basket' },
      { id: 'titleHidden' },
      { id: 'properties', config: { definitions: [{ key: 'status', label: 'Status', type: 'select', options: [{ value: 'open', label: 'Offen' }] }] } },
    ],
  },
]
```

<table>
<thead>
  <tr>
    <th>
      <code>
        BlockType
      </code>
      
       member
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      the Block type id, stored in the <code>
        blockType
      </code>
      
       attribute and written after <code>
        :::
      </code>
      
       in Markdown fences
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
      
      , <code>
        icon
      </code>
    </td>
    
    <td>
      name and icon in menus, the details popover and the <a href="https://skaile-ai.github.io/forge-editor/guides/document-tree">
        Document tree
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        titlePlaceholder
      </code>
      
      , <code>
        descriptionPlaceholder
      </code>
    </td>
    
    <td>
      placeholders of the empty title and description (the summary)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        chrome
      </code>
    </td>
    
    <td>
      <code>
        tags
      </code>
      
      , <code>
        tone
      </code>
      
      , <code>
        controls
      </code>
      
       (see <em>
        Chrome per Block type
      </em>
      
       below)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilities
      </code>
    </td>
    
    <td>
      the capabilities the type supports, each with its config. An unknown id or an invalid config throws when the editor is created
    </td>
  </tr>
</tbody>
</table>

<table>
<thead>
  <tr>
    <th>
      Capability (declared by)
    </th>
    
    <th>
      Config
    </th>
    
    <th>
      What it gives a Typed block of the type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        container
      </code>
      
       (built in)
    </td>
    
    <td>
      <code>
        { accepts?: readonly string[] | 'all', nestedAfterContent?: boolean, root?: boolean }
      </code>
    </td>
    
    <td>
      a body of its own; <code>
        accepts
      </code>
      
       names the Accepted children (see <em>
        Accepted children
      </em>
      
       below), <code>
        nestedAfterContent
      </code>
      
       keeps nested Typed blocks after the own content (see <em>
        Order of nested Typed blocks
      </em>
      
       below), <code>
        root: true
      </code>
      
       makes the type the Block type of the document tree's document rows (the built-in <code>
        document
      </code>
      
       sets it; <code>
        isRootBlockType(type)
      </code>
      
       reads it)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        properties
      </code>
      
       (composites)
    </td>
    
    <td>
      <code>
        { definitions: PropertyDefinition[] }
      </code>
    </td>
    
    <td>
      the Block properties stored in <code>
        meta
      </code>
      
      , shown in the details popover, the table and the Block inspector's Block properties section (any node with a <code>
        meta
      </code>
      
       attribute whose Block type lists the capability)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source
      </code>
      
       (composites)
    </td>
    
    <td>
      <code>
        { media: SourceMedia[] }
      </code>
    </td>
    
    <td>
      a Source: the first body child of one of these media types (<code>
        SOURCE_MEDIA_TYPES
      </code>
      
      ); needs <code>
        container
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bibliography
      </code>
      
       (composites)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      the Bibliographic record in <code>
        meta.bib
      </code>
      
       and the BibTeX export action
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        basket
      </code>
      
       (composites)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      the Basket menu and stripe (<code>
        meta.basket
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        titleHidden
      </code>
      
       (composites)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      the eye button in the chrome („Titel ausblenden“ / „Titel einblenden“) that sets and clears <code>
        meta.titleHidden
      </code>
      
      ; a type without it has no button (the flag is still kept)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai-brief
      </code>
      
       (composites; read by <code>
        composite-ai
      </code>
      
      )
    </td>
    
    <td>
      <code>
        BlockTypeAi
      </code>
    </td>
    
    <td>
      the AI brief: <code>
        purpose
      </code>
      
       goes into every AI request's block model; <code>
        instructions
      </code>
      
      , <code>
        instructionsField
      </code>
      
       (the key of a <code>
        textarea
      </code>
      
       property whose non-empty value replaces <code>
        instructions
      </code>
      
      ) and <code>
        contentTemplate
      </code>
      
       (the AI content template: Markdown target text whose <code>
        {key}
      </code>
      
       placeholders are replaced by the Typed block's <code>
        meta[key]
      </code>
      
      , unknown ones stay) are read only by the AI fill of a Typed block. Without it the AI fill is not offered for the type
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        references
      </code>
      
       (composites)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      the <code>
        reference
      </code>
      
       chips and the backlinks; implied by a <code>
        reference
      </code>
      
       property
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import
      </code>
      
       (composites; read by <code>
        composite-media
      </code>
      
      )
    </td>
    
    <td>
      <code>
        { media?: SourceMedia[] }
      </code>
    </td>
    
    <td>
      imported files land in a Typed block of the type: with <code>
        media
      </code>
      
      , those of that media type (the built-in <code>
        recording
      </code>
      
       takes audio and video, <code>
        figure
      </code>
      
       images); without, every file no other type takes (the built-in <code>
        document
      </code>
      
      ). Needs <code>
        container
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        export
      </code>
      
       (composites)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      the block action „Exportieren“ (<code>
        document-export
      </code>
      
      ): the Typed block's contents as a Markdown file
    </td>
  </tr>
</tbody>
</table>

**Order of nested Typed blocks.** `nestedAfterContent: true` in a Block type's `container` config (default `false`) says that the nested Typed blocks of a Typed block of this type follow its own content, and a merge keeps that order. `mergeCompositeWithNext` merging A = `[Ca, Na]` and B = `[Cb, Nb]` (C the leading blocks of the body that are not Typed blocks, N the rest from the first nested Typed block on) gives `[Ca, Cb, Na, Nb]` instead of `[Ca, Na, Cb, Nb]`; when A has no nested Typed blocks the content of B goes in at the end of A's content, ahead of Nb. A body that is one empty paragraph still adds nothing, the `accepts` check and the single undo step are unchanged. Block types without the flag merge as before.

Read them with `capabilitiesOf(editor, node)` / `capabilitiesAt(editor, pos)` (`@skaile/forge-editor/core`), `capabilityConfigOf(editor, node, id)` for the config and `capabilityDataOf(editor, node, id)` for the contents (the source child, the basket id, the record). The pure accessors `propertiesOf(type)`, `sourceMediaOf(type)`, `aiBriefOf(type)`, `acceptsOf(type)` read a `BlockType` directly; `blockTypeConfigOf(type, id)` and `listsCapability(type, id)` (`@skaile/forge-editor/core`) do the same for the config of any capability. A host that adds a Block type to the preset's list from another feature uses `EditorFeature.blockTypes` ([Feature contract](https://skaile-ai.github.io/forge-editor/reference/feature-contract)).

<table>
<thead>
  <tr>
    <th>
      <code>
        PropertyDefinition
      </code>
      
       member
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
      
      , <code>
        label
      </code>
    </td>
    
    <td>
      the key under which the Block property is stored in <code>
        meta
      </code>
      
      , and its label
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      one of the types above
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code>
        { value, label }
      </code>
      
       choices of a <code>
        select
      </code>
      
       or <code>
        multiselect
      </code>
      
       property (required for <code>
        multiselect
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        targets
      </code>
    </td>
    
    <td>
      <code>
        reference
      </code>
      
       only: the Block type ids the Block reference may point to; absent = any Typed block
    </td>
  </tr>
</tbody>
</table>

**multiselect properties.** A property of type `multiselect` holds several of its `options` (required, `{ value, label }` as for `select`) and stores them as a `string[]` under its key: `meta.topics = ['a', 'b']`. The details popover and the Block inspector show a multi-choice menu (a checkbox list in the React binding); an empty choice removes the key from `meta`, non-string entries are dropped (`metaWithProperty`). Table cells, sort keys and the AI brief read the option labels joined by `, `; the chat model is told to write a JSON list.

**Chrome per Block type.** `BlockType.chrome?: { tags?: boolean, tone?: string, controls?: boolean }` (default: everything shown) tunes the chrome of one Block type. `chrome: { tags: false }` hides the tag row of that type: no tag chips and no `+` chip on the title line, and no tags field in the Block inspector (`CompositeRow.tagsVisible` is `false`). The `typedBlockTags` node stays in the schema, empty, like for every Block type (the node itself is never shown: its row is data, see above). `chrome: { controls: false }` renders the chrome of that type as in a read-only editor although the editor is editable (`CompositeRow.controls`): no Basket menu, status menu, title-visibility (eye) button, tag removal or `+` chip, and no drag handle on the Block type icon; the details popover opens read-only, and „Mit nächstem zusammenführen“ (`mergeCompositeWithNext`) is refused when the Typed block or the one it would absorb has such a Block type, so the tree row button and the block action are gone. An existing Basket, status and tags still show as read-only chips. Use it for a Block type whose attributes a host guard refuses to change, so no button invites a click that is refused. Default `true`.

**Block type tone.** `chrome: { tone: 'var(--color-amber-600)' }` (any CSS colour or `var(...)`) sets a Block type apart: every Typed block of it gets `data-block-type-tone` and the inline variable `--sk-block-type-tone` on its wrapper, a tinted surface (`color-mix` of the tone at `--sk-block-type-tone-mix`, 8% light and 14% dark; override the token to change the strength) and a left border in the tone, and its rows in the [Document tree](https://skaile-ai.github.io/forge-editor/guides/document-tree) tint the Block type icon (`TreeItem.tone`). Block types without a tone look as before; a Basket stripe wins on the border. A host uses it to paint source text apart from its own content.

**Accepted children.** The `accepts` of a Block type's `container` config (`{ id: 'container', config: { accepts } }`; `readonly string[] | 'all'`) names the Block types a Block type accepts as nested Typed blocks: a list of Block type ids, or `'all'`. Without `container` or without `accepts`, a Block type accepts no Typed block; the built-in `section`, `folder`, `document`, `recording`, `paper`, `book`, `figure` and `rendition` list `container` with `'all'`, `task` and `note` accept no Typed block. A host list that defines its own `folder` or `document` type must give it `container` with `accepts: 'all'`. Paragraphs, lists and other content that is no Typed block are always allowed, and top-level Typed blocks have no parent. `acceptsChild(blockTypes, parentType, childType)` answers the question for a list of Block types (a parent type the list does not know accepts nothing). The rule is enforced in the editor by the `AcceptedChildren` extension, which `compositeFeature()` registers: every local edit that leaves the document with more Typed blocks nested in a Typed block that does not accept their Block type than before is refused — block drag, „In Block umwandeln“, the Block type switch of the details popover, paste, AI inserts and review acceptance, `moveBlockInto` — and the user gets the notice „Verschachtelung nicht möglich“ with „<Block type> nimmt keine <Block type> auf.“ (Block type labels, e.g. „Notiz nimmt keine Aufgabe auf.“). Only *new* violations are refused: a document that already nests against the rule stays as it is and can still be edited, and collaboration replays, undo/redo and loading a whole document are never blocked. The [Document tree](https://skaile-ai.github.io/forge-editor/guides/document-tree) applies the same rule to drops.

## Block types from a JSON file

A Block type is plain data, so a host can keep its Block types in a JSON file and load them with `parseBlockTypes` and `mergeBlockTypes`. The file is checked against the capability registry, the server takes the same list, and the example `examples/vue-two-pane` defines the Block type „Idee“ only in such a file. See [Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types) and the [Block type contract](https://skaile-ai.github.io/forge-editor/reference/block-types).

## Reserved meta keys

A Block type's `properties` capability decides which `meta` entries (Block properties) the details popover and the table show, and `changeBlockType`, conversions and the Markdown fence keep **only** the keys the target Block type declares, plus these four, which every Block type keeps and no Block type declares:

<table>
<thead>
  <tr>
    <th>
      <code>
        meta
      </code>
      
       key
    </th>
    
    <th>
      Constant
    </th>
    
    <th>
      Content
    </th>
    
    <th>
      Written by
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        derivation
      </code>
    </td>
    
    <td>
      <code>
        DERIVATION_KEY
      </code>
    </td>
    
    <td>
      provenance (<code>
        Derivation
      </code>
      
      )
    </td>
    
    <td>
      “Create readable rendition” (English label), „Ableiten (KI)“, <a href="https://skaile-ai.github.io/forge-editor/guides/content-tree#block-transfer">
        block transfer
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bib
      </code>
    </td>
    
    <td>
      <code>
        BIB_KEY
      </code>
    </td>
    
    <td>
      Bibliographic record (<code>
        CslItem
      </code>
      
      )
    </td>
    
    <td>
      the <code>
        bibliography
      </code>
      
       property, „Literaturangaben abrufen“
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        basket
      </code>
    </td>
    
    <td>
      <code>
        BASKET_KEY
      </code>
    </td>
    
    <td>
      id of the Typed block's Basket
    </td>
    
    <td>
      <code>
        setCompositeBasket(basket | null, pos?)
      </code>
      
      , the Basket button in the chrome
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        titleHidden
      </code>
    </td>
    
    <td>
      <code>
        TITLE_HIDDEN_KEY
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       while the title is hidden
    </td>
    
    <td>
      <code>
        setCompositeTitleHidden(hidden, pos?)
      </code>
      
      , the eye button in the chrome (Block types with the <code>
        titleHidden
      </code>
      
       capability), every split
    </td>
  </tr>
</tbody>
</table>

Do not declare a Property definition with one of these keys. In Markdown they travel in the fence's meta JSON (`::: section {"basket":"red","titleHidden":true}`).

**Baskets.** `compositeFeature({ baskets })` (or `composeEditor({ compositeBaskets })`) sets the Baskets a Typed block can be put in: `Basket` is `{ id, label, color }`, `color` any CSS colour; the default is `defaultBaskets(t)` (`red`, `orange`, `yellow`, `green`, `blue`; `BASKET_IDS`) coloured by the CSS variables `--sk-basket-<id>`, which a host overrides. `compositeBasketsOf(editor)` returns the editor's list, `basketOf(node)` the Basket of a `typedBlock` node (`null` without), `setCompositeBasket` refuses an unknown id (`false`) and removes the key with `null`. The chrome row has a Basket button (a coloured dot, “No basket” to clear), a Typed block in a Basket gets a coloured left stripe, and the [Document tree](https://skaile-ai.github.io/forge-editor/guides/document-tree#baskets-focus-and-foreign-drops) shows the dot on its row and filters by Basket.

**Hidden titles.** `meta.titleHidden` hides the title behind a thin strip that keeps the chrome row. When the caret enters a hidden title it shows for the rest of the editor session (`CompositeStorage.revealedTitles`); `titleHiddenOf(node)` reads the flag and `setCompositeTitleHidden(false, pos)` also ends the reveal. The eye button that hides and shows the title belongs to the `titleHidden` capability: a Block type that does not list it has no button (every built-in type lists it). Splitting a Typed block makes hidden titles for the generated parts; see [Content tree mechanics](https://skaile-ai.github.io/forge-editor/guides/content-tree#hidden-titles).

## Derive methods and the Derivation index

Transcription, summary, AI fill, AI derivation and bibliography fetch are derive methods: a Feature contributes them as `deriveMethods`, and the preset merges them into one registry. A Derived block records its Derivation in `meta.derivation`; `derivationIndexOf(doc)` finds the Derived blocks of an original, and a Derived block whose original was deleted shows „Quelle fehlt“ / "Source missing". See [Derive methods and the Derivation index](https://skaile-ai.github.io/forge-editor/guides/derive-methods) and the [Derive method contract](https://skaile-ai.github.io/forge-editor/reference/derive-methods).

## Chips and details popover

The feature mounts one overlay (`CompositeChrome`) beside the editor, so every Typed block looks the same in every host:

- **Chips on the title line.** The Block type's `status` property (a `select`) shows as a status chip; its dropdown changes the value. Every tag is a `#tag` chip with a `×` that appears on hover or focus, and a `+` chip opens a tags editor (the same suggestions as the `#` list). Block types without a status property show only the tags.
- **Details popover.** The Block type icon on the Typed block's left border opens a popover (about 18rem wide, scaling and fading in from the icon within ~160 ms; no animation with `prefers-reduced-motion`). At the top is the Block type as a dropdown of all Block types (icon and label, no label above it), below it every property of the Block type except the status (the chip edits it) and the summary. `Escape` or a click outside closes it, unless a dropdown inside is open (that one takes its own `Escape` first).
- **The icon is the drag handle.** In an editable editor, dragging the Block type icon moves the Typed block (the cursor is a grab hand): the Typed block becomes the selection and is dragged like with the standard drag handle, so dropping it elsewhere in the editor moves it with its content (`Alt` copies). A click without movement opens the popover. Typed blocks show no standard drag handle; blocks without a Block type icon keep theirs.
- **Icon visibility.** The settings value `blocks.blockTypeIcon` is `'always'` (default) or `'hover'`. With `'hover'` the icon is invisible (120 ms fade) until the Typed block or its chips are hovered, its popover is open or the icon has keyboard focus; a nested Typed block's hover also reveals the icons of the Typed blocks around it. The invisible icon stays focusable and clickable, and dragging it works as soon as the pointer reaches it.
- **Changing the Block type** asks first. Choosing another Block type shows an inline warning in the popover instead of applying it: „Blocktyp wirklich ändern? Beim Wechsel zu „<Block type>“ gehen diese Angaben verloren:“ followed by the property values the new Block type does not declare (`changeBlockType` keeps only the meta keys of the new Block type), or just „Blocktyp wirklich ändern?“ when nothing would be lost. „Ändern“ runs `changeBlockType` for the Typed block resolved at that moment, „Abbrechen“ keeps the Block type.
- **Read-only editors.** Chips and popover render without edit affordances: no status menu, no `×`/`+`, the Block type as plain text instead of the dropdown, disabled properties, the summary as plain text. The icon still opens the popover but cannot be dragged.
- **Layout.** The chips on the title line run on to the editor's right edge; nothing reserves a margin column. The `typedBlock` node view's own description and tags rows stay in the document as data, but `composites.css` hides them: chips and popover are their only editors. The description is the *summary* in the popover.

The hover bar of `BlockAction`s is right-aligned 8px inside the editor's right edge for every block and is hidden while the editor is read-only.

On the toolbar surface the Typed block actions (export, BibTeX, focus, the four splits and „Mit nächstem zusammenführen“) declare `target: 'typedBlock'`, so they stay on the toolbar while the caret is in a paragraph inside the Typed block; they address the nearest enclosing Typed block (see [Block UI](https://skaile-ai.github.io/forge-editor/guides/block-ui)).

## Headings ↔ Typed blocks

`convertHeadingsToComposites({ recursive, scope, kind })` and `convertCompositesToHeadings({ recursive, scope })` are editor commands; `convertBlockTo(target)` converts one block. Every conversion runs in a single transaction, so **one undo step** reverses it and redo restores it:

```ts
editor.commands.convertHeadingsToComposites({ recursive: true, scope: 'document', kind: 'section' })
editor.commands.undo() // back to the headings, in one step
editor.commands.convertBlockTo({ type: 'typedBlock', blockType: 'task' }, pos)
editor.commands.convertCompositesToHeadings({ recursive: false, scope: 'heading' })
```

Flattening keeps description, tags and Block properties as text below the heading, so nothing is lost silently; a document title above the headings stays as is.

## Conversion providers

The „Umwandeln in …“ menus and `convertBlockTo` run over the conversion providers of the preset's features. A provider is inert data: `targets(editor, node)` (what it offers for `node`), `parseTarget(id)` (the target an id names, or `null`), `label(target)`, `convert(state, $start, target)` and optionally `handlesSource(node)`.

- The **owner** of a target is the first provider, in feature order, whose `parseTarget` parses its id. It supplies the label and, unless another provider claims the source block, executes the conversion.
- A provider that returns true from **handlesSource(node)** claims every conversion of such source blocks. The composite feature uses it for Typed blocks: converting a Typed block into a paragraph, heading, list, quote or code block is executed by the composite provider (it unwraps the Typed block), while `typedBlock:<block type id>` targets are owned by its second provider (wrap a block, a heading with its section or switch the Block type).
- `coreContentFeature()`'s provider declines every target that is not a core target, so features can add targets without interfering with it.
- A target id advertised by two providers for the same block throws (`the conversion target "paragraph" is advertised by more than one provider`) instead of silently picking one.

A feature of your own adds targets the same way: `defineEditor({ features: [coreContentFeature(), coreUiFeature(), { id: 'mine', conversions: [myProvider] }] })`.

## Vue-free schema entry

`@skaile/forge-editor/composites/schema` imports no Vue, node view or feature factory. A server that validates or seeds documents builds its schema from it:

```ts
import { getSchema } from '@tiptap/core'
import { coreSchemaExtensions } from '@skaile/forge-editor/core/schema'
import { compositeSchemaExtensions } from '@skaile/forge-editor/composites/schema'

const schema = getSchema([...coreSchemaExtensions(), ...compositeSchemaExtensions({ blockTypes })])
```

It also exports the pure helpers: `defaultBlockTypes`, `blockTypeOf`, `acceptsChild`, `acceptsImport`, `importTypeOf`, `propertiesOf`, `setBlockProperty`, `metaWithProperty`, `blockPropertiesAt`, `carriesProperties`, `sourceMediaOf`, `aiBriefOf`, `aiBlockTypesOf`, `acceptsOf`, `isRootBlockType`, `parseBlockTypes`, `mergeBlockTypes` (with `BlockTypeJsonError`, see *Block types from a JSON file*), `compositeConversions`, `convertCompositeBlocks`, `blocksFromMarkdown`, `compositeFence`, `groupHeadingsIntoComposites`, `flattenCompositesToHeadings`, `headingGroupRange`, `compositeChromeBlocks` and `structureBlocks`. `@skaile/forge-editor/composites` (framework-free) re-exports them next to the node views (`Composite`, `CompositeTags`), `Structure`/`structureOf`, the framework-free rows and anchors models (`createCompositeRows`, `observeCompositeAnchors`), `compositeFeatureCore(ui)` and the helpers below. The bindings are `@skaile/forge-editor/composites/vue` (`compositeFeature()`, `CompositeTable`, `CompositeInspector`, `SettingsEditingTab`, `useCompositeRows`, `useCompositeAnchors`, ...) and `@skaile/forge-editor/composites/react` (the same names as React components and hooks; `CompositeTable` and `CompositeInspector` take `editor` and are placed beside the editor, `CompositeTable` has `onSelect`, `CompositeInspector` a `document` node and `documentFocused`).

Helpers for Source media, Derived blocks, bibliography and references (also in `@skaile/forge-editor/composites/schema` unless noted): `SOURCE_MEDIA_TYPES`, `sourceOf`, `bodyMarkdown`; the Derivation helpers `derivedChildrenOf`, `DERIVATION_KEY`, `derivationOf`, `derivationState`, `derivationIndexOf`, `derivedOf` and `derivationOriginOf` (exported from `@skaile/forge-editor/core` only; `derivationState(doc, derivedPos, bodyHash, documentId?)` takes the document and the position of the Derived block); `CSL_TYPES`, `cslTypeOptions`, `bibOf`, `cslOf`, `citeShort`, `citeFull`, `bibtexOf`, `yearOf`; `ReferenceNode`, `referencesFromText`, `normalizeReferences`, `compositeIdsOf` (schema entry only), `referenceMarkdown`. Only `@skaile/forge-editor/composites` adds `referenceSuggestion`, `referenceLabel`, `compositeBacklinks`, `revealSource`, `seekSource`, `parseLocator` and the `SourceReveal` extension. `sha256Hex` (`@skaile/forge-editor/core`) is the hash behind `inputHash`/`outputHash`.

## Block outline and Markdown export helpers

- `documentOutline(doc, untitled, capabilitiesOf?, documentId?)` is the model of the Block outline: the headings and Typed blocks of the document as one tree in document order (`DocumentOutlineEntry`: a `DocumentOutlineBlock` with a `kind`, or a `DocumentOutlineHeading` with `level` and `text`); a heading nests under the nearest shallower heading before it, a Typed block under the heading it follows, and the headings in a Typed block's body start their own levels below it. `compositeOutline(doc, hiddenKinds, untitled)` reads only the Typed blocks as a tree (`OutlineNode`: key, id, position, kind, title, `labelFromBody`, summary flag, children); a Typed block without a title gets the text of the first heading of its own body, else the start of the first text of its own body (60 characters, then „…“), else the `untitled` argument, and `labelFromBody` is `true` for the first two; Typed blocks of a hidden Block type drop out and their descendants move up. `moveIntoVerdict(editor, id, targetId, t)` says whether block `id` may move into the Typed block `targetId` (`null` = the end of the document): a `MoveVerdict`, `{ ok: true }` or `{ ok: false, reason }` with a short sentence in the language of `t` (the editor's translator) (the block or the target no longer exists, the target is no Typed block, a block into itself or into a Typed block it contains, or the target's Block type does not accept the block's Block type, see *Accepted children*). A block that is no Typed block may move into any Typed block unless it holds Typed blocks of a refused Block type; moving a block to the end of the Typed block it already sits in is never refused. `canMoveBlockInto(editor, id, targetId)` is `moveIntoVerdict(...).ok`. `moveBlockInto(editor, id, targetId)` moves the block to the end of a Typed block's body (or the document with `null`) in one transaction and returns whether the document changed (`false`: refused by the verdict or by the editor).
- `headingsMarkdown(editor, blocks, level)` exports blocks as Markdown with every Typed block turned into a heading (the outermost at `level`) followed by its description, tags and body; `documentCompositeMarkdown(editor, node)` does the same for one Typed block as a document, `markdownFileName(node)` names the file and `downloadText(filename, text)` offers it as a download.

The heading-only outline of a plain editor stays `@skaile/forge-editor/outline` (`headingOutline`, `revealBlockInEditor`); its component is `EditorOutline` from `/outline/vue` or `/outline/react`.

## Block table and Block inspector

Two components show the Block properties of the Typed blocks beside an editor. Both take the editor from the surface's `ready` event as a prop, follow it when it changes, and render their empty state without one.

- `CompositeTable` (prop `editor?: Editor`; event `select(row)`) lists every Typed block as a sortable, filterable table: Typed block (indented by nesting), Block type, one column per property of the Block types in the document (select values show their option label, dates are formatted; `textarea` properties get no column), Tags and whether a summary exists. Above it: text search over title, summary and tags, Block type and tag chips, one select per `select` property (for example Status), a reset and a row count. A header click sorts ascending, descending, then not at all. The table does not change the document; `select` hands the host the clicked row, so the host can switch back to the text and call `revealBlockInEditor(editor, row)` from `/outline`.
- `CompositeInspector` (props `editor?: Editor`, `documentFocused?: boolean`; slot `document`) is the Block inspector: a side panel that shows one section at a time, chosen by where the caret is. The Document facts section („Dokument“) shows before the editor was ever focused, while the caret is in editor text outside any Typed block, and while the host's document input is focused; the Typed block section („Block“) shows while the caret is in a Typed block (also after opening a row from `CompositeTable`). Clicking into the panel never switches sections, and there is no empty state. Pass `documentFocused` as `true` while your document-level input (e.g. the title field) has the focus: the panel then switches to „Dokument“ and stays there after the input blurs, until the caret returns to the editor. A summary draft typed in the panel is committed when it switches away from „Block“. The „Dokument“ section starts with the host's `document` slot (the library knows nothing about titles, folders or dates of your storage), followed by what the document itself says: Typed blocks per Block type and how many have a summary, all tags, all mentions. The „Block“ section edits the Typed block under the caret: Block type, summary (as text; formatting on the unchanged text stays, a summary with mentions or tags is read-only there and edited in the document), tags with suggestions and creation, one input per Block property, and the summary state. Every edit is one editor transaction, so it reaches collaborators and undo like any other edit. A summary typed in the panel is written only while the document still holds the text the draft started from; when a collaborator changed it meanwhile, their text wins and is loaded into the panel. A read-only editor (`EditorSurface`'s `editable`) disables the controls. Give the panel its width and border through `class`. Host rows in the slot match its layout with `<dl class="grid grid-cols-[6.5rem_minmax(0,1fr)] items-start gap-x-3 gap-y-2">`, `dt.min-h-6.leading-6.text-muted` and `dd.min-h-6.leading-6.text-highlighted`. The Block properties section (heading „Blockeigenschaften“ / "Block properties") lists the Property definitions that the `properties` capability gives the block under the caret, for any block that carries `meta` values; the model exposes it as `state.properties` (`BlockProperties`: `id`, `pos`, `meta`, `definitions`) and `setField` writes to it. The Document facts section stays the Document's own facts.

```vue
<CompositeTable v-if="view === 'table'" :editor="editor" @select="openRow" />
<CompositeInspector :editor="editor" class="w-80 border-l border-default">
  <template #document>
    <MyDocumentFacts />
  </template>
</CompositeInspector>
```

Own views read the same model: `useCompositeRows(editor)` returns `rows` (`CompositeRow`: key, id, position, `kind` with label and icon (the Block type), title, summary text and whether it is text only, tags, `meta`, the Block type's Property definitions (`definitions`), `tagsVisible`, depth), `tags`, `kinds` (the Block types with counts), `mentions` and `focused` (the Typed block under the caret), re-read once per frame after a document change. `setBlockProperty(editor, row, key, value)`, `setCompositeTags(editor, row, tags)` and `setCompositeDescription(editor, row, text, expected?)` write in one transaction and find the Typed block again by its block ID, so a row read before a remote change stays usable. `setCompositeDescription` stores `compositeDescriptionText(text)` (one line), replacing only the changed span so marks on the rest stay; it returns `false` instead of dropping a mention or tag in the summary, or, with `expected`, when the summary no longer holds that text. `compositeRows(doc, kinds)` is the same read without Vue.

## Settings panel and modal

Features contribute settings *tabs* (`settingsTabs: ctx => [{ id, label: ctx.t('…'), icon?, component, props? }]`, a factory over the app context so labels follow its language); the UI that shows them is core and decoupled from any one feature:

- `EditorSettingsPanel` (props `editor`, `contentClass?`; `v-model:tab`) renders one tab per tab contributed by the preset registered for that editor, wherever you place it. With **no tab** (or no editor) it renders nothing.
- `EditorSettingsModal` (props `editor`; `v-model:open`, `v-model:tab`) is the same panel in a popup: a Nuxt UI modal titled „Einstellungen“ (`settings.title`; "Settings" with `locale: 'en'`) with a fixed width (`42rem` from the `sm` breakpoint), a blurred, dimmed backdrop, the panel in a scroll area of fixed height (`h-[32rem]`) and a „Schließen“ footer; the description says whether the values apply to the account or to this browser (`synced`). With no tab it renders nothing.
- `EditorSurface` takes **settingsUi**: `'internal'` (default) mounts the modal itself and opens it from the toolbar's settings entry; `'external'` mounts nothing and emits **settingsOpen(tab?)** instead, so the host opens its own settings page, drawer or panel, or places an `EditorSettingsModal` itself (every page of the Nuxt app's kitchen sink does, see [Kitchen sink: learning path](https://skaile-ai.github.io/forge-editor/guides/advanced-nuxt-example); the example above sets the shown tab from the event). Without any contributed tab the surface neither opens nor emits, and the toolbar's settings entry is hidden.
- The values are shared app settings (`useEditorSettings()`): several panels and editors edit the same preferences, stored per account when a server is configured and per browser otherwise. Another feature's tab (for example the AI tab) appears in the same panel as soon as its feature is part of the preset.

## File import into Typed blocks

`compositeMediaFeature()` from `@skaile/forge-editor/integrations/composite-media` connects two features that know nothing of each other: with it, every imported file lands wrapped in a Typed block of the Block type whose `import` capability takes it (by default a `document`). It `requires` `composites` and `media` (`defineEditor` throws when either is missing); neither of them imports it, so `core + media` and `core + composites` bundles stay free of it (`bun run check:editor-entries` proves it with the `media`, `composites` and `composite-media` fixtures).

```ts
import { compositeFeature } from '@skaile/forge-editor/composites/vue'
import { compositeMediaFeature } from '@skaile/forge-editor/integrations/composite-media'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { mediaFeature } from '@skaile/forge-editor/media/vue'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), mediaFeature(), compositeFeature(), compositeMediaFeature()] })
```

Install it after `composites` and `media`; its CSS is the two feature stylesheets (`media.css`, `composites.css`).

- **Wrapping.** It contributes a wrapping importer (`importers`, `accepts: ['*']`, see [Importers](./34.importers)). The blocks of every imported file — the parsed text or Markdown, the transcript of a subtitle file, the references of a BibTeX file, or the uploaded image, audio, video or file block — go into one Typed block whose Block type is the first one whose `import` capability names the file's media (`importTypeOf(blockTypes, media)`), else the first that lists `import` without media: with the built-in types audio and video become a `recording`, images a `figure`, everything else (PDFs, office files, text and Markdown) a `document`. A Block type list without such a catch-all leaves the other files unwrapped, and a host type that is called `document`, `recording` or `figure` takes files only when it lists `import`. The title is the file name without its last extension (the whole name for `.env`); the Block properties hold the file's own properties first (the frontmatter of a Markdown file), then `filename`, `mimeType` (the file's, else `text/markdown` for text and `application/octet-stream`), `size` and the import date, which win on a clash; the details popover shows them. Drop, paste, the toolbar's media buttons, the `/` commands and the audio recorder all import through `editor.storage.media.importFiles`, so they all wrap. A plan that is Typed blocks already and has no properties (the transcript of a `.vtt`, the entries of a `.bib`) is not wrapped again. Without the integration the blocks are inserted as they are.
- **Actions.** It adds the `/` command „Datei importieren“ (`/datei`, available where Typed blocks may be inserted) that picks any files and imports them at the caret. Slash entries follow the feature order, so it is listed after the media entries when installed after `media`. The block action „Quelle ersetzen“ (on Typed blocks of a Block type with a Source, `sourceOf`) picks a file of the Source media's type, uploads it and rewrites `src`, `hash`, `mimeType`, `title` and `size` of the existing Source media block; block ids stay, so references and Derived blocks keep resolving (Derived blocks turn stale by hash comparison).
- **Not included.** Summaries and transcription of imported documents need AI and belong to the AI integrations, not here.

Importers are additive: two features may both contribute some, and a second wrapping importer wraps the plan of the first. Only the importer ids must be unique.


# Feature composition and entries

> Compose an editor from features and presets, pick the right entries, and choose the integration depth from no data layer to a Nuxt server.

## Dimensions and integration depth

An editor is composed from three **dimensions** of features (`composeEditor` of `@skaile/forge-editor/vue/advanced` or `/react/advanced`; framework-free core in `@skaile/forge-editor/presets/compose`). The **backend** (`EditorBackend`; capabilities `documents`, `collaboration`, `assets`, `users`, `tags`, `settings`, `themes`, `ai`, `comments`) is a separate decision: it only prunes features whose capability it lacks, reported in `omitted`.

<table>
<thead>
  <tr>
    <th>
      Dimension
    </th>
    
    <th>
      Levels (or a list of feature ids)
    </th>
    
    <th>
      Features
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        content
      </code>
      
      : nodes, marks, structure; the server schema derives from it
    </td>
    
    <td>
      <code>
        'basic'
      </code>
      
       = <code>
        core-content
      </code>
      
      ; <code>
        'rich'
      </code>
      
       = <code>
        core-content
      </code>
      
      , <code>
        media
      </code>
      
      , <code>
        transcript
      </code>
      
      , <code>
        composites
      </code>
      
      , <code>
        mentions
      </code>
      
      , <code>
        authors
      </code>
      
      , <code>
        tables
      </code>
      
      , <code>
        composite-media
      </code>
    </td>
    
    <td>
      <code>
        core-content
      </code>
      
       is always installed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        interaction
      </code>
      
      : editing UX without schema
    </td>
    
    <td>
      <code>
        'minimal'
      </code>
      
       = <code>
        core-ui
      </code>
      
      ; <code>
        'full'
      </code>
      
       = <code>
        core-ui
      </code>
      
      , <code>
        collab
      </code>
      
      , <code>
        comments
      </code>
      
      , <code>
        block-ui
      </code>
      
      , <code>
        themes
      </code>
      
      ; <code>
        []
      </code>
      
       = none (a viewer)
    </td>
    
    <td>
      <code>
        core-ui
      </code>
      
       is prepended to every non-empty list
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
      
      , or <code>
        true
      </code>
      
       = <code>
        ai
      </code>
      
       plus <code>
        composite-ai
      </code>
      
       (iff <code>
        composites
      </code>
      
      ) and <code>
        transcript-ai
      </code>
      
       (iff <code>
        transcript
      </code>
      
      )
    </td>
    
    <td>
      an integration whose <code>
        requires
      </code>
      
       are missing lands in <code>
        omitted
      </code>
    </td>
  </tr>
</tbody>
</table>

`add` appends host features after the catalog; `remove` drops catalog features and everything that `requires` them. Examples: viewer `composeEditor({ content: 'rich', interaction: [], ai: false })`; advanced without AI `composeEditor({ content: 'rich', interaction: 'full', ai: false })`; simple plus tables `composeEditor({ content: ['tables'], interaction: 'minimal', ai: false })`.

`transfer` (drag a Typed block from one editor or tree into another, with the copy transform and, with `ai: true`, the summary and bullet transforms of `integrations/composite-ai`) is in no level list, so a host opts in with `interaction: [...INTERACTION.full, 'transfer']` and configures it with `transfer: { transforms?, defaultTransform? }` ([Content tree mechanics](https://skaile-ai.github.io/forge-editor/guides/content-tree#block-transfer)). `compositeBaskets` replaces the built-in colour Baskets like `blockTypes` replaces the Block types ([Baskets](https://skaile-ai.github.io/forge-editor/guides/content-tree#baskets)).

`core-content` is configurable: `composeEditor({ content: 'basic', interaction: 'minimal', ai: false, coreContent: { headings: { levels: [1, 2] }, rule: false } })` (or `coreContentFeature(options)` in a hand-built preset) drops optional StarterKit structures from the editor. Options (`CoreContentOptions`): `headings: false | { levels }`, `lists: false` (bullet and ordered lists with their items), `blockquote: false`, `codeBlock: false`, `rule: false`; everything is on by default. A dropped structure is not in the schema, so the same options object also shapes the server schema (`schemaExtensionsOf(preset.features)`, or `coreContentSchemaExtensions(options)` from `@skaile/forge-editor/core/schema` for a schema built by hand); pass the same options on both sides. Commands that create a dropped node (toolbar button, `/` entry, ⌘K row) are hidden, not greyed out, and its shortcuts do not exist. A heading level outside `levels` hides just that level's command. Abilities are untouched: they stay a permission, not a schema switch. Content that holds a dropped structure (Markdown with `# Titel` and `headings: false`, stored JSON with a `heading` node) has no node type to land in: do not pass such documents to an editor with that option.

`block-ui` chooses where block actions appear: `composeEditor({ content: 'rich', interaction: 'full', ai: false, blockUi: { actions: 'both' } })` (or `blockUiFeature({ actions })` in a hand-built preset). `actions` (`BlockUiOptions`) is `'hover'` (default: the bar of the block under the pointer), `'toolbar'` (the bar of the block holding the selection, shown at its corner as soon as the caret is in it), `'both'` (one bar per block: where the pointer hovers the selected block only the toolbar shows) or `'none'` (drag handle and block targeting only, no action bar). Each action can narrow itself with `placement: 'hover' | 'toolbar' | 'both'` (default `'both'`). Abilities are not touched: an ability stays a permission ("can"), `blockUi.actions` only chooses where the allowed actions are offered. The toolbar bar carries the class `block-actions-toolbar` for host styling.

The catalog behind these dimensions is one table of rows in `presets/catalog`: one row per feature with its dimension, the level lists that hold it and whether a UI layer binds it (`ui`), and `presets/compose` adds how each is built from the `composeEditor` options. Its key order is the canonical order (content, interaction, AI), which the composed feature list and the toolbar order follow (the schema order is the explicit `SCHEMA_IDS` list of `presets/schema-ids`, a leaf the server's `schema/advanced` reads without the catalog); `CONTENT`, `INTERACTION` and `AI` are derived from it. Adding a catalog feature takes one row there, plus its id in `presets/schema-ids` when it has a schema; every entry that holds a part of it is keyed by the rows or that list, so a missing part (the builder, a `schema` source, the Vue, React or test binding of a `ui` row) fails to compile, and `UiBindings<C>` follows the `ui` rows. A framework-free feature without schema needs nothing else.

<table>
<thead>
  <tr>
    <th>
      Integration depth
    </th>
    
    <th>
      What the host runs
    </th>
    
    <th>
      Client call
    </th>
    
    <th>
      Server
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <strong>
        No data layer
      </strong>
    </td>
    
    <td>
      nothing; the browser keeps the data
    </td>
    
    <td>
      <code>
        app.use(createEditor({ backend: createMemoryBackend({ documents, users, tags }) }))
      </code>
      
       (<code>
        @skaile/forge-editor/adapters/memory
      </code>
      
      ), then <code>
        composeEditor({ content: 'rich', interaction: 'full', ai: true, backend })
      </code>
      
      : <code>
        collab
      </code>
      
      , <code>
        comments
      </code>
      
      , <code>
        themes
      </code>
      
      , <code>
        ai
      </code>
      
       and its integrations are omitted automatically
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Nuxt, built-in
      </strong>
    </td>
    
    <td>
      the Nuxt module with an <code>
        EditorPorts
      </code>
      
       bundle
    </td>
    
    <td>
      module <code>
        @skaile/forge-editor/nuxt
      </code>
      
       (config key <code>
        tiptapEditor
      </code>
      
      ); the plugin installs <code>
        createHttpBackend({ probe: true })
      </code>
      
      ; <code>
        <AdvancedEditor />
      </code>
      
       or <code>
        composeEditor({ …, backend })
      </code>
    </td>
    
    <td>
      <code>
        provideEditorServer({ ports: createJsonAdapter({ … }) })
      </code>
      
       (or <code>
        createDrizzleAdapter
      </code>
      
      , <code>
        createForgeAdapter
      </code>
      
      ) in a Nitro plugin, <a href="https://skaile-ai.github.io/forge-editor/guides/editor-ports">
        <code>
          EditorPorts
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <strong>
        Nuxt, external data layer
      </strong>
    </td>
    
    <td>
      the Nuxt module with ports of your own over the external system
    </td>
    
    <td>
      same as the previous row
    </td>
    
    <td>
      <code>
        provideEditorServer({ ports: { identity, documents, assets, … } })
      </code>
      
      : implement only the ports the external system serves; the probe omits the rest on the client
    </td>
  </tr>
</tbody>
</table>

No Directus (or other CMS) adapter ships with the package: the seam for an external data layer is `EditorPorts`, unchanged.

## Bundles

A **bundle** is a named choice of the three dimensions, for hosts that want a starting point instead of picking levels. `composeBundle(bundle, options?)` (from `@skaile/forge-editor/vue/advanced` or `/react/advanced`; `composeBundle(ui, bundle, options?)` in the framework-free `@skaile/forge-editor/presets/compose`) expands the bundle from `BUNDLES` and calls `composeEditor`:

<table>
<thead>
  <tr>
    <th>
      Bundle
    </th>
    
    <th>
      <code>
        content
      </code>
    </th>
    
    <th>
      <code>
        interaction
      </code>
    </th>
    
    <th>
      <code>
        ai
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        simple
      </code>
    </td>
    
    <td>
      <code>
        'basic'
      </code>
    </td>
    
    <td>
      <code>
        'minimal'
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        writing
      </code>
    </td>
    
    <td>
      <code>
        media
      </code>
      
      , <code>
        tables
      </code>
      
      , <code>
        mentions
      </code>
    </td>
    
    <td>
      <code>
        block-ui
      </code>
      
      , <code>
        themes
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collaborative
      </code>
    </td>
    
    <td>
      <code>
        media
      </code>
      
      , <code>
        tables
      </code>
      
      , <code>
        mentions
      </code>
      
      , <code>
        authors
      </code>
    </td>
    
    <td>
      <code>
        collab
      </code>
      
      , <code>
        comments
      </code>
      
      , <code>
        block-ui
      </code>
      
      , <code>
        themes
      </code>
    </td>
    
    <td>
      <code>
        false
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        advanced
      </code>
    </td>
    
    <td>
      <code>
        'rich'
      </code>
    </td>
    
    <td>
      <code>
        'full'
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
    </td>
  </tr>
</tbody>
</table>

`BundleOptions` are the options of `composeEditor` without the three dimensions (`backend`, `add`, `remove`, `blockTypes`, `blockUi`, …), plus two adjustments by catalog id: `with` adds features on top of the bundle (each lands in the dimension its catalog row names; an AI feature switches `ai` on) and `without` takes features out, exactly like `remove` (features that `require` them land in `omitted`). A `with` id outside the catalog throws. Any other combination is a `composeEditor` call with explicit id lists.

```ts
// The writing bundle plus the transfer menu, without tables.
const preset = composeBundle('writing', { with: ['transfer'], without: ['tables'], backend })
```

`simpleEditor()` is `composeBundle(…, 'simple')` and `advancedEditor(options)` is `composeBundle('advanced', options)`; the `advancedEditor` options are `BundleOptions`, so the three dimensions are no longer overridable there (use `composeEditor` or a bundle for that).

## Entries

<table>
<thead>
  <tr>
    <th>
      Entry
    </th>
    
    <th>
      Side
    </th>
    
    <th>
      Contents
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @skaile/forge-editor/nuxt
      </code>
    </td>
    
    <td>
      build
    </td>
    
    <td>
      The Nuxt module (<code>
        defineNuxtModule
      </code>
      
      , config key <code>
        tiptapEditor
      </code>
      
      ). Registers the Nitro scan dir, the client context plugin, AI runtime config, <code>
        build.transpile
      </code>
      
      , the <code>
        ui.css
      </code>
      
       Tailwind <code>
        @source
      </code>
      
      , Nitro <code>
        externals.inline
      </code>
      
       and <code>
        experimental.websocket
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/config
      </code>
    </td>
    
    <td>
      anywhere
    </td>
    
    <td>
      Framework-free <code>
        defineEditorConfig
      </code>
      
      , <code>
        serverConfig
      </code>
      
      , <code>
        publicConfig
      </code>
      
       and the types <code>
        EditorConfig
      </code>
      
      , <code>
        EditorConfigInput
      </code>
      
      , <code>
        EditorServerConfig
      </code>
      
      , <code>
        EditorPublicConfig
      </code>
      
      , <code>
        ModelPresetConfig
      </code>
      
      , <code>
        TranscriptionConfig
      </code>
      
      : the module options, the server options and the client options from one definition (see <a href="https://skaile-ai.github.io/forge-editor/guides/ai-configuration">
        AI configuration
      </a>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/server
      </code>
    </td>
    
    <td>
      server
    </td>
    
    <td>
      Framework-free (no Nuxt, h3, Nitro, Vue or React): <code>
        createCollabServer({ ports, schema, hooks })
      </code>
      
       → <code>
        { hocuspocus, handleConnection, forgetDocument, liveContent, contentChanged, stats, close }
      </code>
      
      , <code>
        createAiModels({ presets, apiKey, slots, transcription })
      </code>
      
      , <code>
        createRateLimiter({ max, windowMs })
      </code>
      
      , <code>
        EditorPorts
      </code>
      
       with <code>
        AccessControl
      </code>
      
      , <code>
        DocumentContentStore
      </code>
      
      , <code>
        CollabStateStore
      </code>
      
      , <code>
        Directory
      </code>
      
      , <code>
        AssetStore
      </code>
      
      , <code>
        SettingsStore
      </code>
      
      , <code>
        ThemeStore
      </code>
      
      , <code>
        ModelProvider
      </code>
      
      , <code>
        PORT_CAPABILITY
      </code>
      
      , <code>
        serverCapabilities
      </code>
      
      , <code>
        HttpError
      </code>
      
      . The Nitro installers (<code>
        installEditorServer
      </code>
      
      , <code>
        provideEditorServer
      </code>
      
      , <code>
        useEditorServer
      </code>
      
       of <code>
        @skaile/forge-editor/server/nitro
      </code>
      
      ) return the <code>
        EditorServer
      </code>
      
       handle with <code>
        forgetDocument
      </code>
      
      , <code>
        liveContent
      </code>
      
      , <code>
        enforceRateLimit
      </code>
      
       and <code>
        resolveModel
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/server/handlers
      </code>
    </td>
    
    <td>
      server
    </td>
    
    <td>
      One handler per editor/AI route, <code>
        (ctx, request) => Promise<HandlerResponse>
      </code>
      
       (<code>
        usersGet
      </code>
      
      , <code>
        tagsGet
      </code>
      
      , <code>
        settingsGet/Put
      </code>
      
      , <code>
        assetGet/Post
      </code>
      
      , <code>
        themesGet
      </code>
      
      , <code>
        themeGet/Post/Delete
      </code>
      
      , <code>
        modelsGet
      </code>
      
      , <code>
        chatPost
      </code>
      
      , <code>
        generatePost
      </code>
      
      , <code>
        completePost
      </code>
      
      , <code>
        extractPost
      </code>
      
      , <code>
        transcriptCleanupPost
      </code>
      
      ) and the zod schemas of their bodies (<code>
        chatBodySchema
      </code>
      
      , …). Map any HTTP server's request onto <code>
        HandlerRequest
      </code>
      
       and send the <code>
        HandlerResponse
      </code>
      
      ; <code>
        HttpError
      </code>
      
       carries the status.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/server/node
      </code>
    </td>
    
    <td>
      server (Node)
    </td>
    
    <td>
      <code>
        listenCollab(collab, { port, host })
      </code>
      
      : a Node HTTP server that serves a <code>
        createCollabServer
      </code>
      
       over websockets, for a plain script (needs the <code>
        crossws
      </code>
      
       dependency; Node only).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/collab
      </code>
      
      , <code>
        /collab/vue
      </code>
      
      , <code>
        /collab/react
      </code>
    </td>
    
    <td>
      browser
    </td>
    
    <td>
      framework-free <code>
        collabFeatureCore(ui?)
      </code>
      
      , <code>
        yjsAnchorResolver
      </code>
      
      ; <code>
        collabFeature()
      </code>
      
       per surface
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/block-ui
      </code>
      
      , <code>
        /block-ui/vue
      </code>
      
      , <code>
        /block-ui/react
      </code>
    </td>
    
    <td>
      browser
    </td>
    
    <td>
      framework-free <code>
        blockUiFeatureCore(ui, options?)
      </code>
      
      , <code>
        blockActionsFor
      </code>
      
      , <code>
        selectedBlockOf
      </code>
      
      , <code>
        effectiveTarget
      </code>
      
      , <code>
        BLOCK_CORNER_ATTR
      </code>
      
      , <code>
        blockCornerOf
      </code>
      
      ; <code>
        blockUiFeature(options?)
      </code>
      
      , <code>
        BlockUi
      </code>
      
      , <code>
        BlockActionsOverlay
      </code>
      
       per surface
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/authors
      </code>
      
      , <code>
        /authors/vue
      </code>
      
      , <code>
        /authors/react
      </code>
    </td>
    
    <td>
      browser
    </td>
    
    <td>
      framework-free <code>
        authorsFeatureCore(ui)
      </code>
      
      , <code>
        currentAuthor
      </code>
      
      , <code>
        documentAuthors
      </code>
      
      ; <code>
        authorsFeature()
      </code>
      
       plus <code>
        AuthorColorsButton
      </code>
      
      , <code>
        AuthorColorsPanel
      </code>
      
      , <code>
        SettingsAuthorsTab
      </code>
      
       per surface (see <a href="https://skaile-ai.github.io/forge-editor/guides/authors-and-comments">
        Authors and comments
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/comments
      </code>
      
      , <code>
        /comments/vue
      </code>
      
      , <code>
        /comments/react
      </code>
    </td>
    
    <td>
      browser
    </td>
    
    <td>
      framework-free <code>
        commentsFeatureCore(ui, { model? })
      </code>
      
      , <code>
        createCommentsModel
      </code>
      
      ; <code>
        commentsFeature({ model? })
      </code>
      
       (requires <code>
        collab
      </code>
      
       unless a host <code>
        model
      </code>
      
       backs it), <code>
        useComments
      </code>
      
      , <code>
        CommentsMargin
      </code>
      
      , <code>
        CommentsPopover
      </code>
      
      , <code>
        CommentsListMenu
      </code>
      
      , … per surface
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/themes
      </code>
      
      , <code>
        /themes/vue
      </code>
      
      , <code>
        /themes/react
      </code>
    </td>
    
    <td>
      browser
    </td>
    
    <td>
      framework-free <code>
        themesFeatureCore(ui)
      </code>
      
      , <code>
        startObsidianTheme
      </code>
      
      , <code>
        pinObsidianTheme
      </code>
      
      , <code>
        scopeThemeCss
      </code>
      
      , <code>
        THEME_SCOPE_CLASS
      </code>
      
      ; <code>
        themesFeature()
      </code>
      
       (site-wide Obsidian themes; see <a href="https://skaile-ai.github.io/forge-editor/guides/themes">
        Themes
      </a>
      
      ) and <code>
        SettingsAppearanceTab
      </code>
      
       per surface; Vue-free in <code>
        /themes/schema
      </code>
      
      : <code>
        ThemeRecord
      </code>
      
      , <code>
        THEME_ID
      </code>
      
      , <code>
        MAX_THEME_BYTES
      </code>
      
      , <code>
        themeManifestSchema
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/schema/advanced
      </code>
    </td>
    
    <td>
      anywhere
    </td>
    
    <td>
      Vue-free <code>
        advancedSchemaExtensions()
      </code>
      
      ; imports no Vue, UI or browser code
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/styles/collab.css
      </code>
      
      , <code>
        /block-ui.css
      </code>
      
      , <code>
        /authors.css
      </code>
      
      , <code>
        /comments.css
      </code>
      
      , <code>
        /themes.css
      </code>
    </td>
    
    <td>
      browser
    </td>
    
    <td>
      Remote carets, block-range selection, author colouring, comment highlights and cards, the Obsidian variable bridge. The Nuxt module adds every feature stylesheet to <code>
        css
      </code>
      
       (<code>
        themes.css
      </code>
      
       last).
    </td>
  </tr>
</tbody>
</table>

The server logic (`src/server/`) runs in any Node process: `createCollabServer`, `createAiModels`, `createRateLimiter` and the route handlers take their ports and configuration explicitly. The HTTP routes are one table, `API` (`src/core/api-routes.ts`: method, path, Port and request and response shape of every route), which the HTTP backend reads too; `serverRoutesOf(ports, { ai })` (`src/server/routes.ts`) pairs each row with its handler and serves a route only when its port is present. One installer, `installEditorServer` (`@skaile/forge-editor/server/nitro`), mounts that table and the collab websocket on a Nitro app and returns the `EditorServer` handle (`forgetDocument`, `liveContent`, `enforceRateLimit`, `resolveModel`); the Nuxt module calls it from its server plugin and a plain Nitro app from a plugin of its own. A plain script needs no Nitro at all:

```ts
import { createCollabServer } from '@skaile/forge-editor/server'
import { listenCollab } from '@skaile/forge-editor/server/node'

const collab = createCollabServer({ ports }) // ports.identity.authenticate({ headers, token }) decides who may connect; needs ports.collabState
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:

<table>
<thead>
  <tr>
    <th>
      Entry
    </th>
    
    <th>
      Contents
    </th>
    
    <th>
      May import
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ./<x>
      </code>
    </td>
    
    <td>
      The feature's logic: <code>
        <x>FeatureCore(ui)
      </code>
      
      , the <strong>
        models
      </strong>
      
       (<code>
        create*
      </code>
      
      , <code>
        *Model
      </code>
      
      : framework-free stores such as <code>
        createCommentsModel
      </code>
      
      , <code>
        createCompositeRows
      </code>
      
      , <code>
        createAiAssistant
      </code>
      
      , <code>
        createDocumentChat
      </code>
      
      , <code>
        modelProfiles(app)
      </code>
      
      ), Tiptap extensions and plugins, helpers
    </td>
    
    <td>
      Tiptap/ProseMirror, <code>
        /core
      </code>
      
      , <code>
        /settings
      </code>
      
      ; no <code>
        vue
      </code>
      
      , <code>
        react
      </code>
      
      , <code>
        @nuxt/ui
      </code>
      
       or <code>
        sonner
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ./<x>/vue
      </code>
    </td>
    
    <td>
      <code>
        <x>Feature(): VueFeature
      </code>
      
      , the feature's Vue components and node views, thin Vue <strong>
        hooks
      </strong>
      
       (<code>
        useComments
      </code>
      
      , <code>
        useCompositeRows
      </code>
      
      , <code>
        useAiAssistant
      </code>
      
      , <code>
        useModelProfiles
      </code>
      
      , <code>
        useFileImport
      </code>
      
      , …) over the models
    </td>
    
    <td>
      <code>
        vue
      </code>
      
      , <code>
        @tiptap/vue-3
      </code>
      
      , Nuxt UI; never <code>
        react
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ./<x>/react
      </code>
    </td>
    
    <td>
      <code>
        <x>Feature(): ReactFeature
      </code>
      
      , the React components (shadcn/ui) and node views, the React hooks over the same models
    </td>
    
    <td>
      <code>
        react
      </code>
      
      , <code>
        @tiptap/react
      </code>
      
      , Radix, <code>
        sonner
      </code>
      
      ; never <code>
        vue
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ./<x>/schema
      </code>
    </td>
    
    <td>
      Node/mark specs, protocol schemas and limits for servers and validators
    </td>
    
    <td>
      no UI, no DOM
    </td>
  </tr>
</tbody>
</table>

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 (`coreContentFeature()`, `coreUiFeature()`, `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 `@skaile/forge-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 '@skaile/forge-editor/composites/vue'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { compositeMediaFeature } from '@skaile/forge-editor/integrations/composite-media'
import { mediaFeature } from '@skaile/forge-editor/media/vue'

// Order = order of toolbar groups, menu entries and the schema.
const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), 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 tutorial chapters [Your own block (path A)](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a) and [Your own feature (path B)](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b).
- Prebuilt compositions: `composeEditor(options)` per surface (`@skaile/forge-editor/vue/advanced`, `@skaile/forge-editor/react/advanced`) builds an `EditorPreset` from the three dimensions of the [table at the top](#dimensions-and-integration-depth) plus an optional `backend`: `composeEditor({ content: 'rich', interaction: 'full', ai: true, backend })` returns the preset with `omitted` (`{ id, reason }[]`: a feature dropped because it `requires "<id>"` or because `backend "<name>" lacks "<capability>"`). `advancedEditor({ blockTypes?, …overrides })` (`{ content: 'rich', interaction: 'full', ai: true }`) is a one-line wrapper; the framework-free `simpleEditor()` (`@skaile/forge-editor/presets/compose`: `{ content: 'basic', interaction: 'minimal', ai: false }`, no ⌘K palette) is the component-free simple preset; `SimpleEditor` (`/vue/simple`, `/react/simple`) and `AdvancedEditor` (`/vue/advanced`, `/react/advanced`) are the matching components. `@skaile/forge-editor/presets/compose` is the framework-free assembly (`presets/compose.ts`: `composeEditor(ui, options)`, `CONTENT`, `INTERACTION`, `AI`, `UiBindings<C>`, `ComposeOptions<C>`, `ComposedEditor<C>`, `simpleEditor()`): a UI layer binds only the UI-bound features (core UI, media, transcript, composites, authors, comments, AI and its integrations, collab, block UI, themes), the framework-free ones (core content, mentions, tables, composite-media) are built there; it contains no component and is not a preset to mount. The order is canonical (content, then interaction, then AI, then `add` in the given order), so schema and toolbar order do not depend on how the options were written.
- Both surfaces take the same features: a React preset is `defineEditor({ features: [coreContentFeature(), coreUiFeature(), 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 (`coreContentFeature(), coreUiFeature()`, `mentionsFeature()` and the integrations) fit either ([quick start for React](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-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` ([simple editor tutorial](https://skaile-ai.github.io/forge-editor/tutorial/simple-editor)).
- Components that belong *beside* an editor are separate exports and take the editor as a prop (the toolbar and the settings components find its preset through it). Vue: `EditorToolbar`, `EditorSettingsPanel`, `EditorSettingsModal` (`/vue`), `EditorOutline` (`/outline/vue`), `CompositeTable`, `CompositeInspector` (`/composites/vue`), `AiSidebar` (`/ai/vue/chat`, optional peer `@skaile/forge-chat`), `CommentsMargin` (`/comments/vue`), `DocumentTree` (`/tree/vue`).
- The React equivalents have the same names and props style: `EditorToolbar`, `EditorSettingsPanel`, `EditorSettingsModal` from `@skaile/forge-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.
- `EditorToolbar` (Vue and React) takes `overflow`: `'wrap'` (default) breaks its groups onto further lines; `'collapse'` keeps one line and folds the groups that do not fit, from the end, into one dropdown each (the first command's icon and a chevron; `component` commands, such as the comments and author-colour toggles, stay as buttons). Give the toolbar a bounded width, e.g. `class="w-full"` in a header row.
- 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

<table>
<thead>
  <tr>
    <th>
      Entry group
    </th>
    
    <th>
      Entries
    </th>
    
    <th>
      May import
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Browser, with Vue and Nuxt UI
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
      , <code>
        /vue/simple
      </code>
      
      , <code>
        /vue/advanced
      </code>
      
      , <code>
        /<feature>/vue
      </code>
      
       (<code>
        /media
      </code>
      
      , <code>
        /transcript
      </code>
      
      , <code>
        /authors
      </code>
      
      , <code>
        /comments
      </code>
      
      , <code>
        /composites
      </code>
      
      , <code>
        /ai
      </code>
      
      , <code>
        /collab
      </code>
      
      , <code>
        /block-ui
      </code>
      
      , <code>
        /themes
      </code>
      
      , <code>
        /outline
      </code>
      
      , <code>
        /tree
      </code>
      
      )
    </td>
    
    <td>
      everything above them in the rules of <a href="https://skaile-ai.github.io/forge-editor/reference/dependency-rules">
        Dependency rules
      </a>
      
      ; never React
    </td>
  </tr>
  
  <tr>
    <td>
      Browser, with React and shadcn/ui
    </td>
    
    <td>
      <code>
        /react
      </code>
      
      , <code>
        /react/simple
      </code>
      
      , <code>
        /react/advanced
      </code>
      
      , <code>
        /<feature>/react
      </code>
      
       (the same features)
    </td>
    
    <td>
      the same rules; never Vue, <code>
        @tiptap/vue-3
      </code>
      
       or Nuxt UI
    </td>
  </tr>
  
  <tr>
    <td>
      Browser, framework-free
    </td>
    
    <td>
      <code>
        /core
      </code>
      
       (<code>
        defineEditor
      </code>
      
      , <code>
        createEditorContext
      </code>
      
      , the settings store, <code>
        createStore
      </code>
      
      , the notice seam, the suggestion renderer seam, descriptors such as <code>
        EditorFeature<C>
      </code>
      
       and <code>
        MenuItem
      </code>
      
      ), <code>
        /<feature>
      </code>
      
       (<code>
        <x>FeatureCore(ui)
      </code>
      
      , the models), <code>
        /mentions
      </code>
      
      , <code>
        /integrations/*
      </code>
      
      , <code>
        /presets/*
      </code>
    </td>
    
    <td>
      Tiptap/ProseMirror, <code>
        /core
      </code>
      
       and <code>
        /settings
      </code>
      
       only (plus Yjs/AI SDK where the feature needs them); no <code>
        vue
      </code>
      
      , <code>
        @tiptap/vue-3
      </code>
      
      , <code>
        @nuxt/ui
      </code>
      
      , <code>
        react
      </code>
      
       or <code>
        sonner
      </code>
      
       module
    </td>
  </tr>
  
  <tr>
    <td>
      Server-safe schema and protocol, usable in Node
    </td>
    
    <td>
      <code>
        /core/schema
      </code>
      
      , <code>
        /schema/simple
      </code>
      
      , <code>
        /schema/advanced
      </code>
      
      , <code>
        /media/schema
      </code>
      
      , <code>
        /mentions/schema
      </code>
      
      , <code>
        /transcript/schema
      </code>
      
      , <code>
        /authors/schema
      </code>
      
      , <code>
        /comments/schema
      </code>
      
      , <code>
        /composites/schema
      </code>
      
      , <code>
        /themes/schema
      </code>
      
      , <code>
        /tree/types
      </code>
      
      , <code>
        /settings
      </code>
      
      , <code>
        /ai/protocol
      </code>
      
      , <code>
        /integrations/transcript-ai/protocol
      </code>
    </td>
    
    <td>
      no UI framework, no DOM globals or feature factories
    </td>
  </tr>
  
  <tr>
    <td>
      Server
    </td>
    
    <td>
      <code>
        /server
      </code>
      
      , <code>
        /nuxt
      </code>
    </td>
    
    <td>
      Nitro/Nuxt build code; never imported by browser code
    </td>
  </tr>
</tbody>
</table>

Servers and validators build their ProseMirror schema from the framework-free schema entries (`getSchema(advancedSchemaExtensions())`), never from a browser entry.

## Choosing a preset or features

<table>
<thead>
  <tr>
    <th>
      Goal
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Rich text only, no backend, smallest bundle
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
       (with the ⌘K palette) / <code>
        simpleEditor()
      </code>
      
       from <code>
        /presets/compose
      </code>
      
       (without it); features <code>
        core-content
      </code>
      
      , <code>
        core-ui
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Everything, Nuxt module as the backend
    </td>
    
    <td>
      <code>
        AdvancedEditor
      </code>
      
       / <code>
        advancedEditor({ blockTypes? })
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      A level in between: advanced minus a feature, or a small editor with AI
    </td>
    
    <td>
      <code>
        <AdvancedEditor :remove="['tables']" />
      </code>
      
      , <code>
        <AdvancedEditor content="basic" interaction="minimal" :ai="true" />
      </code>
      
      : <code>
        AdvancedEditor
      </code>
      
       takes <code>
        content
      </code>
      
      , <code>
        interaction
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        add
      </code>
      
      , <code>
        remove
      </code>
      
      , <code>
        backend
      </code>
      
      , <code>
        blockTypes
      </code>
      
      , <code>
        blockUi
      </code>
      
       (which surfaces show block actions: <code>
        'hover'
      </code>
      
      , <code>
        'toolbar'
      </code>
      
      , <code>
        'both'
      </code>
      
      , <code>
        'none'
      </code>
      
      ) and <code>
        coreContent
      </code>
      
       (headings, lists, blockquote, code block or rule left out of the schema), all read once at setup, builds the preset with <code>
        composeEditor
      </code>
      
       and exposes it (<code>
        preset
      </code>
      
      , with <code>
        omitted
      </code>
      
      ). <code>
        SimpleEditor
      </code>
      
       stays lean (core features only; its bundle holds no catalog feature) and takes just <code>
        add
      </code>
      
      : <code>
        <SimpleEditor :add="[aiFeature()]" />
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Something else, or the advanced set plus an own feature
    </td>
    
    <td>
      <code>
        defineEditor({ features: [...] })
      </code>
      
       mounted with <code>
        EditorSurface
      </code>
      
      , or <code>
        advancedEditor({ add: [ownFeature()] })
      </code>
    </td>
  </tr>
</tbody>
</table>

Advanced list in schema order: `core-content`, `core-ui`, `media`, `transcript`, `composites`, `mentions`, `authors`, `comments`, `ai`, `collab`, `block-ui`, `composite-media`, `composite-ai`, `transcript-ai`, `themes`. `transfer` is not part of it; add it through the `interaction` list as above.

<table>
<thead>
  <tr>
    <th>
      Feature (factory, entries)
    </th>
    
    <th>
      Needs (<code>
        requires
      </code>
      
      )
    </th>
    
    <th>
      Backend
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        coreContentFeature()
      </code>
      
       (<code>
        /core
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        coreUiFeature(ui?)
      </code>
      
       (<code>
        /core
      </code>
      
      ; <code>
        ui = { palette }
      </code>
      
       adds the ⌘K palette: the <code>
        SimpleEditor
      </code>
      
       components and the <code>
        composeEditor()
      </code>
      
      /<code>
        advancedEditor()
      </code>
      
       of <code>
        /vue/advanced
      </code>
      
       and <code>
        /react/advanced
      </code>
      
       pass the framework's <code>
        EditorCommandPalette
      </code>
      
      ; the framework-free <code>
        simpleEditor()
      </code>
      
       and a hand-built <code>
        defineEditor
      </code>
      
       list have none unless they pass it themselves)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mediaFeature()
      </code>
      
       (<code>
        /media/vue
      </code>
      
      , <code>
        /media/react
      </code>
      
      ; <code>
        mediaFeatureCore
      </code>
      
       in <code>
        /media
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      uploads (<code>
        backend.assets
      </code>
      
      ; HTTP: <code>
        /api/editor/assets/:id
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mentionsFeature()
      </code>
      
       (<code>
        /mentions
      </code>
      
      , no components: both surfaces)
    </td>
    
    <td>
      none
    </td>
    
    <td>
      <code>
        /api/editor/users
      </code>
      
      , <code>
        /api/editor/tags
      </code>
      
       or host <code>
        metadata
      </code>
      
       lists
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcriptFeature()
      </code>
      
       (<code>
        /transcript/vue
      </code>
      
      , <code>
        /transcript/react
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        authorsFeature()
      </code>
      
       (<code>
        /authors/vue
      </code>
      
      , <code>
        /authors/react
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      none (author comes from the collaboration session <code>
        user
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collabFeature()
      </code>
      
       (<code>
        /collab/vue
      </code>
      
      , <code>
        /collab/react
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      <code>
        /collab/:id
      </code>
      
       websocket; active only when <code>
        collaboration
      </code>
      
       is passed to the surface
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commentsFeature({ model? })
      </code>
      
       (<code>
        /comments/vue
      </code>
      
      , <code>
        /comments/react
      </code>
      
      )
    </td>
    
    <td>
      <code>
        collab
      </code>
      
      , none with <code>
        model
      </code>
    </td>
    
    <td>
      comments live in the Y.Doc, or in the host's <code>
        CommentsModel
      </code>
      
       (<code>
        model: getEditor => CommentsModel
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compositeFeature({ blockTypes? })
      </code>
      
       (<code>
        /composites/vue
      </code>
      
      , <code>
        /composites/react
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      none (also mounts the Typed block overlay: status/tag chips on each title line and, on the Block type icon, a popover with the Block type dropdown (warns before <code>
        changeBlockType
      </code>
      
      , naming the Block property values that would be lost), the Block type's properties and the summary; also read-only: Block type as text, properties disabled; enforces the Block types' Accepted children, <code>
        BlockType.accepts
      </code>
      
      : an edit that nests a Typed block into one that does not accept its Block type is refused with the notice <code>
        composites.nesting.title
      </code>
      
       („Verschachtelung nicht möglich“))
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aiFeature()
      </code>
      
       (<code>
        /ai/vue
      </code>
      
      , <code>
        /ai/react
      </code>
      
      ; framework-free <code>
        aiFeatureCore
      </code>
      
       in <code>
        /ai
      </code>
      
      ; the Vue sidebar is the separate <code>
        /ai/vue/chat
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      <code>
        /api/ai/{models,generate,chat,complete}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockUiFeature()
      </code>
      
       (<code>
        /block-ui/vue
      </code>
      
      , <code>
        /block-ui/react
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      none (drag handle, hover actions)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        themesFeature()
      </code>
      
       (<code>
        /themes/vue
      </code>
      
      , <code>
        /themes/react
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      adapter <code>
        listThemes
      </code>
      
      /<code>
        loadTheme
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transferFeature({ transforms?, defaultTransform? })
      </code>
      
       (<code>
        /transfer/vue
      </code>
      
      , <code>
        /transfer/react
      </code>
      
      ; framework-free <code>
        transferFeatureCore
      </code>
      
       in <code>
        /transfer
      </code>
      
      )
    </td>
    
    <td>
      <code>
        composites
      </code>
      
       (<code>
        requires
      </code>
      
      ); none else (<code>
        summaryTransform
      </code>
      
       and <code>
        bulletsTransform
      </code>
      
       of <code>
        integrations/composite-ai
      </code>
      
       are offered only with an AI backend and the <code>
        typedBlock
      </code>
      
       node in the schema)
    </td>
    
    <td>
      none for <code>
        copy
      </code>
      
      ; <code>
        summary
      </code>
      
       and <code>
        bullets
      </code>
      
       use <code>
        POST /api/ai/generate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compositeMediaFeature()
      </code>
      
       (<code>
        /integrations/composite-media
      </code>
      
      , both surfaces)
    </td>
    
    <td>
      <code>
        composites
      </code>
      
      , <code>
        media
      </code>
    </td>
    
    <td>
      uploads
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compositeAiFeature()
      </code>
      
       (<code>
        /integrations/composite-ai
      </code>
      
      , both surfaces)
    </td>
    
    <td>
      <code>
        composites
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        media
      </code>
    </td>
    
    <td>
      AI plus <code>
        /api/ai/extract
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcriptAiFeature()
      </code>
      
       (<code>
        /integrations/transcript-ai
      </code>
      
      , both surfaces)
    </td>
    
    <td>
      <code>
        transcript
      </code>
      
      , <code>
        ai
      </code>
    </td>
    
    <td>
      AI plus <code>
        /api/ai/transcript-cleanup
      </code>
    </td>
  </tr>
</tbody>
</table>

```ts
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { mediaFeature } from '@skaile/forge-editor/media/vue' // or '/media/react' with a React surface
import { mentionsFeature } from '@skaile/forge-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: [coreContentFeature(), coreUiFeature(), 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`, `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 (`coreContentFeature()`, `coreUiFeature()`, `mentionsFeature()`, the integrations) fit both. A host that brings its own UI kit calls `<x>FeatureCore(ui)` with its own components ([per-feature entries](#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: the other guides of this section; composition and entries: this page.


# Content tree mechanics

> Work on a tree of Typed blocks: colour baskets and hidden titles, splitting by hand, by length or with AI, outline cleanup, focus and basket filter in the tree, and block transfer between two editors.

A document of [Typed blocks](https://skaile-ai.github.io/forge-editor/guides/composites) is a tree. This guide covers the tools for reshaping that tree: sort Typed blocks into **colour baskets**, **hide** their titles, **split** a long Typed block into smaller ones, **repair** the heading outline with AI, **narrow** the tree and the editor to one Typed block, and **move Typed blocks between two editors** with a transform. Everything is client-side editor behaviour on top of the composites feature; the storage of your documents stays yours.

The runnable example is [`examples/vue-two-pane`](https://github.com/skaile-ai/forge-editor/tree/main/examples/vue-two-pane): two panes, each a [`DocumentTree`](https://skaile-ai.github.io/forge-editor/guides/document-tree) over an editor, on the bare Nitro server of the `vue-nitro-json` example. Start it from the repository root:

```sh
AI_KEY=<OpenRouter key> bun run example:two-pane   # http://localhost:3047
```

`AI_KEY` is needed only for the AI parts („Gliederung bereinigen (KI)“, the summary and bullet transforms). Its README lists what to try: import `seed/paper.md`, split a long Typed block, pick baskets, filter and focus in the tree, drag a Typed block from the left pane to the right one.

<table>
<thead>
  <tr>
    <th>
      You want
    </th>
    
    <th>
      Read
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Colour marks and title strips on Typed blocks
    </td>
    
    <td>
      <a href="#baskets-and-hidden-titles">
        Baskets and hidden titles
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Cut one Typed block into several
    </td>
    
    <td>
      <a href="#splitting-a-typed-block">
        Splitting a Typed block
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Join a Typed block with the one after it
    </td>
    
    <td>
      <a href="#merging-with-the-next-typed-block">
        Merging with the next Typed block
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Fix skipped heading levels and numbering
    </td>
    
    <td>
      <a href="#outline-cleanup-with-ai">
        Outline cleanup with AI
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Show only part of the tree or the editor
    </td>
    
    <td>
      <a href="#focus-and-basket-filter">
        Focus and basket filter
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Copy, summarise or list a Typed block into another editor
    </td>
    
    <td>
      <a href="#block-transfer">
        Block transfer
      </a>
    </td>
  </tr>
</tbody>
</table>

## Baskets and hidden titles

A Typed block can sit in one **basket** and its title can be **hidden**. Both live in the Typed block's `meta`, so they are stored with the document, survive Markdown round trips (`::: section {"basket":"red","titleHidden":true}`) and are kept by every Block type: a Block type switch, a conversion or a Markdown import never drops them, and a Block type does not declare Property definitions for them.

<table>
<thead>
  <tr>
    <th>
      <code>
        meta
      </code>
      
       key
    </th>
    
    <th>
      Constant
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        basket
      </code>
    </td>
    
    <td>
      <code>
        BASKET_KEY
      </code>
    </td>
    
    <td>
      the id of one of the editor's baskets; absent = no basket
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        titleHidden
      </code>
    </td>
    
    <td>
      <code>
        TITLE_HIDDEN_KEY
      </code>
    </td>
    
    <td>
      <code>
        true
      </code>
      
       while the title is hidden; absent otherwise
    </td>
  </tr>
</tbody>
</table>

### Baskets

A `Basket` is `{ id, label, color }`; `color` is any CSS colour. The host decides the set:

```ts
import { compositeFeature } from '@skaile/forge-editor/composites/vue'
import type { Basket } from '@skaile/forge-editor/composites'

const BASKETS: readonly Basket[] = [
  { id: 'keep', label: 'Übernehmen', color: '#16a34a' },
  { id: 'check', label: 'Prüfen', color: '#f97316' },
  { id: 'later', label: 'Später', color: 'var(--my-later-colour)' },
]

compositeFeature({ baskets: BASKETS })
// or on the composed editor: composeEditor({ ..., compositeBaskets: BASKETS })
```

Without `baskets` the editor offers `defaultBaskets(t)`: `red`, `orange`, `yellow`, `green`, `blue` (`BASKET_IDS`) with labels in the editor's language (`composites.basket.*`: „Rot“, „Orange“, …). Their colours are CSS variables, which a host overrides:

```css
:root {
  --sk-basket-red: #dc2626;   /* also orange, yellow, green, blue */
}
```

The set is read once, like `blockTypes`. `compositeBasketsOf(editor)` returns the editor's own list (the built-in set for an editor without the composite node). An id on a Typed block that the set does not contain is ignored by the UI (no dot) and kept in the document.

Where baskets show:

- **In the editor.** The chrome row of a Typed block has a basket button (“Basket”): it opens a list of the baskets plus “No basket” (English labels; the German catalog words both differently). A Typed block in a basket gets its colour as a left border stripe (`--sk-basket-color`) and a dot on the button.
- **In the tree.** Every Typed block row shows the dot (the [basket filter](#focus-and-basket-filter) narrows the tree by it).

Commands (`@skaile/forge-editor/composites`, both act on the Typed block at `pos`, default the caret's innermost one):

```ts
editor.commands.setCompositeBasket('check', pos) // false for an id the editor does not offer
editor.commands.setCompositeBasket(null, pos)    // removes the key
```

`basketOf(node)` returns the id of a Typed block's basket (or `null`; it takes a `CompositeRow` as well), `basketById(baskets, id)` the `Basket` of an id among a set (or `undefined`). The defaults come in a light and a dark value (`:where(.dark)`); a host that overrides one sets the dark value too.

### Hidden titles

`setCompositeTitleHidden(hidden, pos?)` hides or shows the title. A hidden title is not rendered; a thin strip keeps the chrome row (basket button and the „Titel einblenden“ eye button). When the caret enters a hidden title (keyboard navigation, click on the strip), the title shows again **for the rest of the editor session** (`CompositeStorage.revealedTitles`, a store of block ids), so nobody types into text they cannot see; the flag in `meta` stays set, and „Titel ausblenden“ hides it again. `titleHiddenOf(node)` reads the flag.

```ts
editor.commands.setCompositeTitleHidden(true, pos)  // also ends a reveal when `hidden` is false
```

Hidden titles are what [splitting](#splitting-a-typed-block) uses for generated parts: the title is only a handle for the tree and for the model, the text carries the content.

## Splitting a Typed block

Three ways cut one Typed block into several. All of them write one transaction (one undo step), give every new part a **title from its first sentence** (`generatedTitle`: up to the first `.`, `!` or `?`, at most 60 characters, `…` appended when cut) and **hide it** (`meta.titleHidden`). New parts get no block id yet; the surface assigns one like for every new block.

Two **modes** decide where the parts go (`SplitMode`):

<table>
<thead>
  <tr>
    <th>
      Mode
    </th>
    
    <th>
      Result
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        'siblings'
      </code>
    </td>
    
    <td>
      the original keeps the first part; each further part is a following sibling of the same Block type
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        'children'
      </code>
    </td>
    
    <td>
      the original keeps its title, description, tags and meta, and its body becomes one nested Typed block per part. The nested Typed blocks are of the default Block type (<code>
        blocks.defaultBlockType
      </code>
      
      ) when the parent accepts it, else of the parent's own Block type when it accepts itself; if neither is accepted (<code>
        BlockType.accepts
      </code>
      
      ) the split is refused
    </td>
  </tr>
</tbody>
</table>

### By hand

`splitCompositeAtCaret({ mode })` splits the caret's innermost Typed block in front of the body block that holds the caret; the part before and the part from the caret on become the two parts. It is refused (`false`) when the caret is not in a body, or at the first body block (nothing before it). The caret moves into the new part.

```ts
editor.commands.splitCompositeAtCaret({ mode: 'siblings' })
editor.can().splitCompositeAtCaret({ mode: 'children' })
```

Block actions: „Block hier teilen“ (siblings) and „In Unterblöcke teilen“ (children), offered on the Typed block around the caret while the caret is past its first body block.

### By length

`splitCompositeByLength({ mode, targetChars?, pos? })` cuts the body of the Typed block at `pos` (default: the caret's) into parts of about `targetChars` characters and never cuts inside a block: a part ends before the block that would push it over the target, and a single block longer than the target forms a part of its own. It is refused with fewer than two parts. `targetChars` defaults to the setting `blocks.splitTargetChars` (default 1500, 200–20000), which has a field „Zielgröße beim Teilen (Zeichen)“ in the settings tab „Bearbeiten“; it is read on every use, so a changed setting applies without recreating the editor.

```ts
editor.commands.splitCompositeByLength({ mode: 'children', targetChars: 1200, pos })
```

Block actions: „Nach Länge in Unterblöcke teilen“ and „Nach Länge in Blöcke teilen“, offered while the body falls into two parts or more. Each of the four manual actions hides itself when its command would refuse, so a Block type that accepts no child Block type never shows the nested variants. They need the ability `composite.meta`.

The pure parts need no editor and are exported from `@skaile/forge-editor/composites`: `splitBodyByLength(blocks, targetChars)`, `generatedTitle(blocks)`, `childKindFor(kinds, parentKind, defaultBlockType)`, `splitComposite(schema, composite, groups, mode, childKind, hideTitles)`; the editor extension is `CompositeSplit` (registered by `compositeFeature`).

### With AI

With `compositeAiFeature()` (see [AI](https://skaile-ai.github.io/forge-editor/guides/ai)) a Typed block with body text gets the block actions „Mit KI in Unterblöcke teilen“ and „Mit KI in Blöcke teilen“ (ability `ai.generate`). The model does not cut text, it only **marks the cuts**: it gets the body as Markdown and the wanted section size (task `split-block`, `generate` Model role, `targetChars` as the prompt) and returns the same text with `##` headings inserted. The Typed block is split at those headings, and each heading becomes the (hidden) title of its part.

The text must not change. `bodyUnchanged(original, result)` compares the answer **without its heading lines** to the original with whitespace collapsed (headings the original already has stay part of the comparison); if the words differ, **nothing is written** and the warning „Die KI hat den Text verändert, nichts wurde geteilt“ appears. Other safeguards: a body longer than `AI_LIMITS.selection` is refused up front, the Typed block is anchored while the model runs, and an edit to its body in the meantime discards the result („Der Block wurde währenddessen geändert …“).

```ts
import { type AiFlowContext, splitCompositeWithAi } from '@skaile/forge-editor/integrations/composite-ai'
import { modelProfiles } from '@skaile/forge-editor/ai'

const flow: AiFlowContext = { ai, modelRef: modelProfiles(app).modelRef, notify, t }
await splitCompositeWithAi(editor, pos, 'children', flow, {
  targetChars: 1500,        // the wanted section size
  defaultBlockType: 'section',   // blocks.defaultBlockType, for the `children` Block type
})
```

`flow` is the `AiFlowContext`: `ai` is `backend.ai` (not undefined), `notify` the surface's notifier and `t` its translator (the example takes them from `useEditorContext()`, `useNotifier(editor)` and `useEditorI18n()`). `splitByInsertedHeadings(schema, composite, blocks, mode, kind)` is the pure part: it groups the result at the lowest heading level present and returns the replacement nodes, or `null` for fewer than two parts.

## Merging with the next Typed block

The counterpart of the split: `mergeCompositeWithNext(pos?)` makes the Typed block at `pos` (default: the caret's innermost one) absorb the Typed block that **directly follows it** in the same parent. The following Typed block's body, its nested Typed blocks included, is appended to the end of the first one's body in document order; the first keeps its title, description, tags, id, Block type and meta, and the following one is gone (its own title, description, tags and meta are dropped; a body that is a single empty paragraph adds nothing). It is one transaction, so one undo restores both Typed blocks, and the caret stays where it was.

```ts
editor.commands.mergeCompositeWithNext(pos)
editor.can().mergeCompositeWithNext()
```

It is refused (`false`, document untouched) when no Typed block directly follows (a paragraph or other block in between counts as "none": nothing is moved across it), when the first Typed block's Block type does not accept the Block type of a Typed block nested in the following one (`BlockType.accepts`), and when the editor is not editable.

Where it is offered: the block action „Mit nächstem zusammenführen“ (icon `i-lucide-merge`, ability `compositeMeta`, hidden when the command would refuse) and a button on every Typed block row of the [`DocumentTree`](https://skaile-ai.github.io/forge-editor/guides/document-tree) (same hover place as „Fokussieren“; only on rows whose Typed block the editor can merge). The row button sends the `TreeCommand` `{ type: 'mergeBlock', id }`, whose executor runs `mergeCompositeWithNext` at the Typed block with that block id. Both are in Vue and React. The extension is `CompositeMerge` (registered by `compositeFeature`), the pure part `mergeBody(kinds, first, next)` (the fragment to append, `null` when refused), both exported from `@skaile/forge-editor/composites`.

## Outline cleanup with AI

„Gliederung bereinigen (KI)“ repairs the **heading outline of the whole document**: no skipped levels, numbering („2. Methodik“) and trailing punctuation gone, double spaces removed, one spelling, and a heading without text under it merged into the next. It is a ⌘K command (`outline-sanitize`, no toolbar button) and a block action on every heading, behind `compositeAiFeature()`.

```ts
import { sanitizeOutline } from '@skaile/forge-editor/integrations/composite-ai'

await sanitizeOutline(editor, flow) // `flow` as above: { ai, modelRef, notify, t }
```

How it stays safe:

1. `collectHeadings(doc)` lists every `heading` node as `OutlineHeading { i, level, text, chars, pos }`; `chars` is the text length of the blocks under it, so the model can tell an empty heading from a long one.
2. The task `outline-sanitize` (`generate` Model role) sends only that list as JSON (`i`, `level`, `text`, `chars`: **no body text**) and expects a JSON list of the same length back. The list is too long for the model (more than `AI_LIMITS.selection` characters) → „Die Gliederung ist zu lang für die KI“.
3. `parseOutlineResponse(text, headings)` accepts exactly one entry per heading (`i` equal to its index, `level` an integer 1–6, `text` a string; a Markdown fence around the JSON is tolerated), else `null`: „Die Antwort der KI war unbrauchbar, nichts wurde geändert“.
4. If the document's headings changed while the model ran, nothing is written („Das Dokument wurde währenddessen geändert …“).
5. `applyOutline(tr, headings, outline)` writes the answer into one transaction, from the last heading to the first: an empty `text` removes the heading, otherwise the level and, when it differs, the text are set. **One undo step** reverses the cleanup.

It works on `heading` nodes, so run it **before** grouping headings into Typed blocks (or on a document that has headings inside Typed blocks). The example does exactly that in its import: it sets the Markdown as plain headings, runs `sanitizeOutline`, then calls `convertHeadingsToComposites({ recursive: true, scope: 'document' })` — see [`import-markdown.ts`](https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-two-pane/src/import-markdown.ts). A host can offer the same as an opt-in checkbox on its import form.

Both AI tasks (`split-block`, `outline-sanitize`) are in `AI_TASK_IDS` and carry `AiTask.programmatic: true`: only a block action or a command sends them, so they never appear in the AI sidebar.

## Focus and basket filter

### Focus in the editor

`focusComposite(id | null)` puts the editor in **focus mode** on the Typed block with block id `id`: every sibling of the Typed block and of each of its ancestors is hidden, so only the Typed block and the titles around it stay. `null` ends it; `false` is returned when `id` is not a Typed block of the document. The decorations carry the classes `sk-focus-hidden`, `sk-focus-target` and `sk-focus-ancestor` (`composites.css` hides the first); a caret outside the focused Typed block moves into its title, and the focus resets by itself when the Typed block is deleted.

```ts
editor.commands.focusComposite(blockId)
compositeFocusOf(editor.state)   // the focused id, or null
editor.commands.focusComposite(null)
```

Every Typed block has the block action „Fokussieren“, and while a focus is active a chip „Fokus: <titel>

· Aufheben“ (`FocusChip`, mounted as an overlay of `compositeFeature`; `CompositesUi.focusChip`) ends it. Also exported from `@skaile/forge-editor/composites`: `CompositeFocus` (the extension), `compositeFocusKey`, `focusDecorations(doc, id)`.

</titel>



### Focus in the tree

Every Typed block row of the [`DocumentTree`](https://skaile-ai.github.io/forge-editor/guides/document-tree) has a focus button („Fokussieren“). Focusing a row lists **only the children of that row** under a breadcrumb: the first crumb is the document and leaves the focus („Fokus aufheben“), the others refocus that level (a Typed block without a title is named by its body there as in the rows, see [Label of an untitled Typed block](https://skaile-ai.github.io/forge-editor/guides/document-tree)). The tree and the editor follow each other: focusing in the tree runs `focusComposite` on the open editor (`TreeCommand` `{ type: 'focusBlock', id }`), and a focus started in the editor (block action, chip, a Typed block that vanished) shows in the tree. A key the tree no longer has, or another open editor, resets it. The Block type filters of the rows on the way down still apply to the children.

### Basket filter

With a live editor that offers baskets, a paint-bucket button (“Filter by basket”) sits next to the title filter. Its menu checks baskets; the tree then shows only the Typed blocks of the checked baskets **plus their ancestors**, which are dimmed (`TreeRowState.dimmed`). None checked means all. Documents, folders and headings are never hidden, and “Reset basket filter” clears the choice.

The choice is part of the shared per-app view state (`TreeViewModel`, see [Document tree](https://skaile-ai.github.io/forge-editor/guides/document-tree#filters-virtual-root-outline)) and persists in `localStorage` under `tip-tree:basket-filter`:

```ts
import { treeView } from '@skaile/forge-editor/tree'

const view = treeView(app)           // or `const { model } = useTreeView()` in a component
view.basketFilter.get()              // string[], [] = all
view.setBasketShown('check', true)
view.clearBasketFilter()
```

An id that the open editor does not offer never filters.

## Block transfer

Block transfer moves a Typed block between **two editor surfaces** or from an editor into **another document tree**, as a copy or as the result of a transform. It has three parts: the drag payload (`core`), the receiving feature (`@skaile/forge-editor/transfer`) and the tree's drop rules.

### The payload

`startBlockDrag` (the drag of a Typed block's Block type icon, or of a permanent drag handle) writes, next to `text/plain`, the block under `application/x-tip-block` (`BLOCK_MIME`). A document tree row of a Typed block writes it too. The payload is a `BlockTransfer`:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        documentId
      </code>
    </td>
    
    <td>
      the document the block lives in (<code>
        null
      </code>
      
       when its editor has none; set it with the surface's <code>
        document-id
      </code>
      
      , which <code>
        coreContentFeature
      </code>
      
       stores as <code>
        editor.storage.blockTransfer.documentId
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockId
      </code>
    </td>
    
    <td>
      the block's id (<code>
        null
      </code>
      
       without)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockType
      </code>
    </td>
    
    <td>
      the Block type id, <code>
        null
      </code>
      
       for other blocks
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        title
      </code>
    </td>
    
    <td>
      the Typed block's title, or the first 80 characters of another block's text
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        json
      </code>
    </td>
    
    <td>
      the block as Tiptap JSON
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        markdown
      </code>
    </td>
    
    <td>
      the block as Markdown (empty in an editor without <code>
        editor.markdown
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

`writeBlockTransfer(dataTransfer, payload)`, `readBlockTransfer(dataTransfer)` (`null` for a missing, unparsable or misshapen payload) and `blockTransferOf(editor, pos)` are exported from `@skaile/forge-editor/core`, so an own drag source or drop target speaks the same format. A drag that starts and ends in the **same** editor stays ProseMirror's native move (`Alt` copies).

### `transferFeature`

```ts
import { transferFeature } from '@skaile/forge-editor/transfer/vue'  // or '/transfer/react'

transferFeature({ transforms?, extraTransforms?, defaultTransform? })
```

It is a regular feature (`id: 'transfer'`, dimension `interaction`), framework-free in `transferFeatureCore(ui, options)` of `@skaile/forge-editor/transfer`. It contributes a drop target and a menu overlay:

- A **plain drop** of a foreign block runs the *default transform* (`defaultTransform`, default `'copy'`) at the drop point.
- **Shift at the drop** opens the transform menu („Einfügen als …“, `TransferMenu`, an overlay) at the pointer, listing the available transforms.
- A drop onto the dragged block's own position in the same document is refused („Ein Block lässt sich nicht auf sich selbst ablegen“, `isSelfDrop`).
- The insert guards and the target's content rules apply: what a transform inserts must be allowed at the drop point, else the warning „Hier lässt sich der Block nicht einfügen“ shows and the document stays unchanged.

`composeEditor` knows it as the catalog id `transfer`. It is **in no level list**: opt in with the interaction list and pass options with `transfer`. With `ai: true` and no own `transfer.transforms`, `composeEditor` offers the copy plus `summaryTransform` and `bulletsTransform` (the layer binds them, so a composition without `ai` holds no AI code); `transferFeature()` on its own offers only the copy. The feature `requires` `composites`.

```ts
import { composeEditor } from '@skaile/forge-editor/vue/advanced'
import { INTERACTION } from '@skaile/forge-editor/presets/compose'

const preset = composeEditor({
  content: 'rich',
  interaction: [...INTERACTION.full, 'transfer'],
  ai: true,
  transfer: { defaultTransform: 'copy' },
})
```

`extraTransforms` adds transforms **after** the default list (or after `transforms`), so an add-on's transforms (`slidesTransforms` of `@skaile/forge-editor-slides`) join the built-in ones without the host listing them again; a transform whose `id` is already in the list is dropped. `AdvancedEditor` (Vue and React) takes the options as the `transfer` prop (and `explore` for the Explore feature), next to `interaction: [...INTERACTION.full, 'transfer']`.

For a hand-built preset, install it after `composites` and list the AI transforms yourself: `transferFeature({ transforms: [copyTransform, summaryTransform, bulletsTransform] })` (the two AI ones from `@skaile/forge-editor/integrations/composite-ai`). The bundle needs `core`, `media` and `composites`, nothing else: no `features/ai`, no integration (`bun run check:editor-entries`, fixtures `transfer`, `transfer-react`, `headless-transfer` fail otherwise).

Commands: `transferBlock({ payload, pos, menu, x?, y? })` puts the block of a payload into the document at `pos` (`menu`: open the transform menu at `x`, `y` instead of running the default transform); the tree's drop executor uses it. `cancelTransfer()` closes the menu. The state of the menu is `editor.storage.blockDropTarget` (`pending`, `available`, `run`; type `BlockDropTargetStorage`).

### The built-in transforms

<table>
<thead>
  <tr>
    <th>
      Id
    </th>
    
    <th>
      Menu text
    </th>
    
    <th>
      What lands in the target
    </th>
    
    <th>
      Needs
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        copy
      </code>
      
       (<code>
        copyTransform
      </code>
      
      )
    </td>
    
    <td>
      „Kopie einfügen“
    </td>
    
    <td>
      the block, with fresh block ids on it and everything in it
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        summary
      </code>
      
       (<code>
        summaryTransform
      </code>
      
      , <code>
        @skaile/forge-editor/integrations/composite-ai
      </code>
      
      )
    </td>
    
    <td>
      „Zusammenfassung einfügen“
    </td>
    
    <td>
      a new Typed block „Zusammenfassung: <titel>
        “ with a model-written summary
      </titel>
    </td>
    
    <td>
      AI backend, Markdown, the <code>
        typedBlock
      </code>
      
       node
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bullets
      </code>
      
       (<code>
        bulletsTransform
      </code>
      
      , same entry)
    </td>
    
    <td>
      „Stichpunkte einfügen“
    </td>
    
    <td>
      a new Typed block „Stichpunkte: <titel>
        “ with the key statements as a list
      </titel>
    </td>
    
    <td>
      same
    </td>
  </tr>
</tbody>
</table>

The AI transforms insert an **empty Typed block first** (Block type `transferKindOf(editor)`: the setting `blocks.defaultBlockType` when the editor offers it, else its first Block type; titled after the source, with `meta.derivation` when the source has a block id, and a running notice while the model streams), stream the model's answer into it with the same write-back as „Ableiten (KI)“ (`writeDerivedBody`) and **remove it again** when the run fails, is aborted or returns nothing. The tasks are `transfer-summary` and `transfer-bullets` (`generate` Model role, `programmatic`, request body from `transferRequest(payload, blocks, model, task)`: the dragged Markdown cut to `AI_LIMITS.selection` as the `selection`).

### Derivation: where a copy comes from

A transferred **Typed block with a block id** records its source in `meta.derivation` ([provenance](https://skaile-ai.github.io/forge-editor/guides/composites#what-the-feature-contributes)), so it is a Derived block:

<table>
<thead>
  <tr>
    <th>
      Transform
    </th>
    
    <th>
      <code>
        from
      </code>
    </th>
    
    <th>
      <code>
        method
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        copy
      </code>
    </td>
    
    <td>
      <code>
        { block, document }
      </code>
    </td>
    
    <td>
      <code>
        'copy'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        summary
      </code>
    </td>
    
    <td>
      <code>
        { block, document }
      </code>
    </td>
    
    <td>
      <code>
        'transform:summary'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bullets
      </code>
    </td>
    
    <td>
      <code>
        { block, document }
      </code>
    </td>
    
    <td>
      <code>
        'transform:bullets'
      </code>
    </td>
  </tr>
</tbody>
</table>

`DerivationSource` `{ block }` may carry `document`, the document the source block lives in. `inputHash` is the hash of the source's body Markdown, `outputHash` of the result's, so the badge shows „bearbeitet“ once the copy is edited. For a source in **another** document the editor cannot look the block up, so it does not compare hashes: `stale` is `null` in the details card (`DerivationDetails.foreign`, `isForeignSource`) and the badge reads „aus anderem Dokument“ (`composites.derivation.foreign`, `derivationIsForeign`) instead of „Quelle geändert“.

### Own transforms

`transforms` replaces the default list (`[copyTransform]`, or with `composeEditor` and `ai` on the copy plus the AI transforms): pass the built-ins you still want next to your own. A `BlockTransform`:

```ts
interface BlockTransform {
  id: string
  label: string                         // menu text, shown as is unless `labelKey` is set
  labelKey?: MessageKey                 // i18n key: the menu renders it in the editor's language
  icon: string                          // Iconify name, e.g. 'i-lucide-quote'
  available?: (ctx: TransformContext) => boolean   // absent = always
  creates?: (ctx: TransformContext) => Creates | null
  run: (ctx: TransformContext) => Promise<void>
}

interface TransformContext {
  editor: Editor
  payload: BlockTransfer
  pos: number                           // a valid drop point of editor.state.doc
  ai: EditorBackend['ai'] | undefined
  app: EditorContext                    // the app context: the AI transforms read the model profiles from it
  notify: Notifier
  t: Translate
}
```

- `available` hides the transform from the menu (and makes a plain drop that names it do nothing).
- `creates` tells what `run` will insert (`{ type, attrs? }`), so the insert guards and the content rules are checked **before** `run`; a refusal shows the warning and runs nothing. Without `creates`, `copy` is checked as inserting the dragged block itself and every other transform has to check for itself.
- `run` inserts at `ctx.pos` with its own transaction and reports its own failures through `ctx.notify`; `runTransform` never throws for a refusal.

```ts
import { copyTransform, type BlockTransform } from '@skaile/forge-editor/transfer'

const asQuote: BlockTransform = {
  id: 'quote',
  label: 'Als Zitat einfügen',
  icon: 'i-lucide-quote',
  available: ({ payload }) => payload.title.length > 0,
  creates: () => ({ type: 'blockquote' }),
  run: async ({ editor, payload, pos }) => {
    editor.view.dispatch(editor.state.tr.insert(pos, editor.schema.nodeFromJSON({
      type: 'blockquote',
      content: [{ type: 'paragraph', content: [{ type: 'text', text: payload.title }] }],
    })))
  },
}

transferFeature({ transforms: [copyTransform, asQuote] })
```

Exports of `@skaile/forge-editor/transfer`: `transferFeatureCore`, `TransferFeatureOptions`, `TransferUi`, `BlockTransform`, `TransformContext`, `TransferEnv`, `copyTransform`, `DEFAULT_TRANSFORMS`, `runTransform`, `availableTransforms`, `transformContextOf`, `transferKindOf`, `transferSourceHash`, `createsOf`, `withFreshBlockIds`, `isSelfDrop`, `BlockDropTargetStorage`, `TransferDrop`, `PendingDrop`. The bindings add `transferFeature` and `TransferMenu` (`/transfer/vue`, `/transfer/react`). `summaryTransform`, `bulletsTransform` and `transferRequest` are exported from `@skaile/forge-editor/integrations/composite-ai`, next to `writeDerivedBody`, which they use.

### Drops on a tree row

A `DocumentTree` takes a foreign Typed block too. In the **virtual root** mode (`blocks.treeRoot = 'file'`, see [Document tree](https://skaile-ai.github.io/forge-editor/guides/document-tree#filters-virtual-root-outline)) the drop is accepted on the document root and on a Typed block row with a block id; every other target shows the refusal „Hier lassen sich keine Blöcke ablegen.“ and the browser's „not allowed“ cursor. An open editor **without the transfer feature** (no `editor.storage.blockDropTarget`, no `transferBlock` command) refuses every foreign drop with „Dieser Editor nimmt keine Blöcke von außen an.“; the executor returns `false` for such a command instead of throwing. The tree emits `TreeCommand` `{ type: 'transferBlock', payload, targetId, menu, x, y }` and its executor runs `editor.commands.transferBlock` at the **end of that Typed block** (`null` = end of the document); Shift opens the transform menu at the pointer. The receiving editor is the tree's `editor` prop. The tree rows themselves write the payload when dragged, so a tree row can be dropped onto the other pane's surface.

## Putting it together

Two panes need nothing beyond what is above: one `composeEditor` preset with `transfer`, one `DocumentTree` per pane over its own editor, and `document-id` on each surface so a transfer names where a block came from. The example does this in [`Pane.vue`](https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-two-pane/src/Pane.vue) and [`PaneEditor.vue`](https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-two-pane/src/PaneEditor.vue). What each part adds to the AI surface (tasks, Model roles, routes) is in [AI](https://skaile-ai.github.io/forge-editor/guides/ai#content-tree-tasks).


# Data views: a query shown as table, list or board

> The dataView Block type: its stored query and layout, the three layouts and what a board needs, how the view asks and refreshes, /ansicht, and the Typed blocks table as the table layout.

A **data view** is a [Typed block](https://skaile-ai.github.io/forge-editor/guides/composites) of the Block type `dataView` that shows the answer to a [query](https://skaile-ai.github.io/forge-editor/guides/query) as a table, a list or a board. It stores the query and the layout and nothing else: the rows are never part of the Document, they are asked for whenever the view is on screen. Copy the Document, export it, or let a collaborator open it: the view shows what the query finds at that moment.

`defaultBlockTypes(t)` lists the type (label „Ansicht“ / "View", icon `i-lucide-table-properties`, capabilities `properties` and the colour basket), so a host that spreads the built-in list has it.

## What a data view stores

Two [Block properties](https://skaile-ai.github.io/forge-editor/guides/block-properties) in the Typed block's `meta`:

<table>
<thead>
  <tr>
    <th>
      Key
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <code>
        text
      </code>
      
      , hidden
    </td>
    
    <td>
      a <code>
        DataQuery
      </code>
      
       as JSON text; the properties form never shows it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        layout
      </code>
    </td>
    
    <td>
      <code>
        select
      </code>
    </td>
    
    <td>
      <code>
        table
      </code>
      
       (the default), <code>
        list
      </code>
      
       or <code>
        board
      </code>
    </td>
  </tr>
</tbody>
</table>

```ts
import { dataViewLayoutOf, dataViewQueryOf, newDataViewMeta } from '@skaile/forge-editor/composites'

newDataViewMeta('task')   // { query: '{"v":1,"source":{"kind":"blocks","blockType":"task"}}' }
dataViewQueryOf(node)     // DataQuery | null; null for no query, bad JSON or a query that names no Block type
dataViewLayoutOf(node)    // 'table' | 'list' | 'board'; an unknown value reads as 'table'
```

`dataViewQueryOf` reads the JSON text like `collectionQueryOf` does and checks only its shape; `validateQuery` names the issues against the Block type's fields, and a view whose query is wrong shows them instead of rows.

## The three layouts

A layout turns the `DataResult` into the model a view draws (`VIEW_LAYOUTS`, `features/composites/views/layouts.ts`). Cell text, sort keys and the right-hand alignment of numbers come from the Property kind registry (`PROPERTY_KINDS`), so a new property type shows in every layout without code here.

<table>
<thead>
  <tr>
    <th>
      Layout
    </th>
    
    <th>
      Shows
    </th>
    
    <th>
      Requires
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        table
      </code>
    </td>
    
    <td>
      one row per Block: title, Block type, then one column per property (long text such as a transcript and hidden properties get none)
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        list
      </code>
    </td>
    
    <td>
      the title first, then the short properties as fields
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        board
      </code>
    </td>
    
    <td>
      one lane per option of the group field, a card per Block
    </td>
    
    <td>
      <code>
        group
      </code>
    </td>
  </tr>
</tbody>
</table>

A board needs a group in the query: its lanes are the options of the grouped property. For a `status` property the lane carries the option's group (`todo`, `doing`, `done`), for a `select` the options in their declared order; a lane of an option nobody uses stays on the board (a board shows where nothing is yet), the lane of Blocks without a value comes last, and `group.hideEmpty` drops it when it holds nothing. `viewModelOf(layout, result, defs, env, input)` refuses a query without a group for the board (`{ ok: false, missing: ['group'] }`), and the view then says so instead of drawing no lanes.

Choosing the board in the view (`chooseDataViewLayout(editor, node, 'board')`) on a query without a group writes the `status` property (else the first `status` or `select` property of the queried Block types) as the group, so the board shows lanes at once. Going back to the table keeps the group.

## How a view asks

The model is `features/composites/views/data-view-model.ts` (`createDataViewModel`), shared by `DataView.vue` and `DataView.tsx`: one model, two thin twins.

- It answers with `backend.index.query` (the Blocks of every Document the user may read). A backend without it answers the same query locally over the Blocks of the open Document, with `evaluateQuery`; the line below the view then says „Nur die Blöcke dieses Dokuments“.
- The state is one of `no-query`, `loading`, `ready`, `needs-group` and `error` (a refused query lists its `QueryIssue`s). The previous rows stay on screen while the next answer is on its way, and an answer that equals the one shown does not redraw the view.
- Only a view on screen asks. The node view reports its visibility (`model.setVisible`); a visible view listens for changes of the Blocks (its own Document and the Blocks of other Documents, as the reference chips do), asks again 200 ms after the last change (`DATA_VIEW_DEBOUNCE_MS`), and every `FOREIGN_CONTENT_REFRESH_MS` (the Blocks of other Documents change without the editor hearing of it). A view scrolled away stops all three and asks again when it comes back.
- A change of the block's `query` or `layout` asks at once.
- Row clicks reveal the Block in the open Document, or open it in its own Document through the host's `openBlock` (`revealCollectionItem`).

## Node view

Both bindings supply the node view (`CompositeNodeViews.dataView`): the usual Typed block view with the answer below its content, and layout buttons while the editor is editable. A binding that renders no live content leaves `dataView` out of `nodeViews`; the block then renders as any Typed block and its query stays in `meta.query`. Both bindings pass `typedBlockViewOptions` to the renderer, like `collection`:

```ts
compositeNodes({
  typedBlock: VueNodeViewRenderer(CompositeView, typedBlockViewOptions),
  dataView: VueNodeViewRenderer(DataView, typedBlockViewOptions),
  reference: VueNodeViewRenderer(ReferenceView),
})
```

## The query builder

In an editable editor the layout bar of a data view has an "Abfrage bearbeiten" button that opens the **query builder** (`QueryBuilder.vue` / `QueryBuilder.tsx`, both over `createQueryBuilderModel` in `views/query-builder-model.ts`; `createEditorQueryBuilder(editor, node)` wires it to a view). The form has:

- the **Block type** the query reads (a stored query that names several types keeps them until another type is chosen);
- a flat **AND list of conditions**, each `field`, `operator`, `value`. The fields are the properties of the type plus the pseudo-fields `$title`, `$tags`, `$type`, `$id`, `$doc` and `$basket` (the baskets are its choices). The operators are the `ops` of the field's kind in `PROPERTY_KINDS`, so a date offers `before`/`after`/`on`, a number `lt`/`gte`, a `status` or `select` its options as choices, a `checkbox` yes/no. Changing the field resets the operator to the first one of its kind;
- one **sort** field with a direction and one **group** field (with "hide the group without a value").

Every change builds the query again and runs `validateQuery`. Only a complete, valid query is written to the block's `meta.query` (through `setDataViewQuery`); a row without a value yet, or a query the validator refuses, writes nothing and the form says how many parts are open. The view then asks again at once because its node changed. What the form has no control for stays as stored: `search`, `aggregates`, `select`, `page`, the `scope`, sorts after the first, and a filter with `or` or nesting (the form shows it as kept and offers to replace it). A change of the stored query from outside (another user, an undo) is followed by the open form.

```ts
import { createEditorQueryBuilder } from '@skaile/forge-editor/composites'

const builder = createEditorQueryBuilder(editor, node)   // null without a block ID or a translator
builder?.setBlockType('task')
const id = builder!.addCondition()
builder!.setConditionField(id, 'status')
builder!.setConditionValue(id, 'done')                   // writes `status eq done`
builder!.setGroup('$basket')
```

## `/ansicht`

The slash command `/ansicht` inserts a data view after the caret's block over the Block type that has the most Typed blocks in the open Document (the first one met wins a tie; a data view never counts). A Document without another Typed block gets a view over the default Block type of the settings. `insertDataView(editor, fallbackType)` does the same from code, and `insertComposite(kind, meta)` takes the `meta` of the block it creates.

The Block type's own slash entry (`/dataView`) is not offered: an empty view says nothing, `/ansicht` always starts with a query.

## The Typed blocks table is the `table` layout

`CompositeTable` (Vue and React) lists the Typed blocks of the open Document. It does not have a table of its own: its columns are those of `VIEW_LAYOUTS.table` (`tableColumnsOf`), its filters are one `DataQuery` that `evaluateQuery` answers over `rowsAsBlockRows(rows)`, and cell text and sort keys come from the kind registry. `tableViewOf` adds what only the panel has (tags, summary, search box, the sort the header sets). A column or kind added to the layout shows in the panel and in every data view.


# Derive methods and the Derivation index

> Register one way to make a block from another block, find the Derived blocks of an original and handle a missing source.

Transcription, text extraction (PDF text, OCR, image description), summary, AI fill, AI derivation into another Block type and bibliography fetch have one thing in common: they make something from a Block. Each is one **derive method**. A Feature contributes its methods as `deriveMethods`, and the preset merges all of them into one registry. The [derive-method contract](https://skaile-ai.github.io/forge-editor/reference/derive-methods) lists the fields.

A Block that was made this way is a **Derived block**. It records in `meta.derivation` what it was made from (its **Derivation**). The original keeps nothing, so the link cannot disagree with the document after a move, a delete or a merge.

## Register a derive method

A derive method declares the capabilities the original must have (`requires`), the ability (`ability`) and, where the capabilities cannot say it, `available(ctx)`: the backend flag `ctx.ctx.backend.ai`, the public AI flags, a readable source. `run` writes the result. A method with sub-choices (derive into one of several Block types) gives `menu` instead of `run`.

The example adds „Kernaussagen ableiten“. It is offered on every Container block with a title when the backend has AI, and it inserts a Typed block of the Block type `note` that records its Derivation:

```ts [docs/snippets/derive-method.ts]
import type { Derivation, EditorFeature } from '@skaile/forge-editor/core'
import { derivationState, derivedOf, newTypedBlockJSON } from '@skaile/forge-editor/core'
import { ABILITY, blockIdOf } from '@skaile/forge-editor/core/schema'
import type { Node as PMNode } from '@tiptap/pm/model'

// One registration: the block action, its gate (`requires`, `ability`, `available`) and the work.
export function keyPointsFeature(): EditorFeature {
  return {
    id: 'key-points',
    dimension: 'ai',
    requires: ['composites'],
    deriveMethods: [{
      id: 'key-points',
      label: () => 'Kernaussagen ableiten',
      icon: 'i-lucide-list-checks',
      ability: ABILITY.compositeDerive,
      requires: ['container', 'title'],
      available: ({ ctx }) => !!ctx.backend.ai,
      run: ({ editor, node, pos }) => {
        const block = blockIdOf(node)
        if (!block) return
        const derivation: Derivation = { from: { block }, method: 'key-points', createdAt: new Date().toISOString(), inputHash: '', outputHash: '' }
        const result = newTypedBlockJSON('note', [{ type: 'paragraph', content: [{ type: 'text', text: 'Kernaussagen ...' }] }])
        // The Derived block records where it came from; the original keeps nothing.
        editor.commands.insertContentAt(pos + node.nodeSize, { ...result, attrs: { ...result.attrs, meta: { derivation } } })
      },
    }],
  }
}

/** The Derived blocks made from the original at `originalPos`, computed from block IDs and asset names. */
export const derivedBlocksOf = (doc: PMNode, originalPos: number, documentId: string) =>
  derivedOf(doc, originalPos, documentId).map(entry => ({ pos: entry.pos, method: entry.derivation.method }))

/** True when the original of the Derived block at `derivedPos` was deleted. */
export const isSourceMissing = (doc: PMNode, derivedPos: number, documentId: string) =>
  derivationState(doc, derivedPos, () => '', documentId)?.source === 'missing'
```

`defineEditor` merges the methods of all Features in feature order into `preset.deriveMethods` and throws for a duplicate id, a method with neither or both of `run` and `menu`, and a `requires` entry that no Feature declares (the built-in capabilities count).

The menu of the user does not change. `blockActionsOf` turns every method into a Block action with the same id (`deriveActionsOf`), so the overlay filter applies `requires`, the ability and `available` like for every other action. `deriveMethodsAt(editor, ctx, pos)` lists the methods that can run on one Block.

The built-in `composite-ai` integration registers its six methods this way:

<table>
<thead>
  <tr>
    <th>
      Method id
    </th>
    
    <th>
      <code>
        requires
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        composite-fill
      </code>
    </td>
    
    <td>
      <code>
        ai-brief
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        composite-summarize
      </code>
      
      , <code>
        composite-derive
      </code>
    </td>
    
    <td>
      <code>
        container
      </code>
      
      , <code>
        title
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bibliography-fetch
      </code>
    </td>
    
    <td>
      <code>
        bibliography
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rendition-create
      </code>
    </td>
    
    <td>
      <code>
        source
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rendition-regenerate
      </code>
    </td>
    
    <td>
      <code>
        derived
      </code>
    </td>
  </tr>
</tbody>
</table>

## The Derivation

`Derivation` is the record in `meta.derivation`: `from` (an asset by asset name, or a Block by block ID, with `document` when the Block lives in another Document), `method` (a `DerivationMethod` such as `'transcription'`, `'ocr'`, `'description'` or any string a host uses), `model`, `createdAt`, `inputHash`, `outputHash` and `output`. The `derived` capability, which the composites feature declares, applies to every Block that has the record (`perNode`), and `derivationOf(node)` reads it.

A Block made from several originals (a mixdown, a summary of several Blocks) names them in `inputs`, a record of `{ from, hash }` by input name. Then `from` is the primary input and `inputHash` holds `derivationFingerprint({ method, inputs })`: the SHA-256 of the method and the hash of every input, by input name, so the order the inputs were written in does not change it. `activity` (`{ id, agent?, at? }`) records the run that produced the Block, for example one AI request and the model that answered; the AI rendition and „Ableiten (KI)“ write it.

## Find the Derived blocks of an original

`derivationIndexOf(doc)` computes the reverse index from block IDs and asset names. It is memoised per `doc` node, so it is recomputed for every new document version, and it cannot disagree with the document after a move or delete (Yjs merges included). The functions on top of it:

- `derivedOf(doc, originalPos, documentId?)` lists the Derived blocks of the original at `originalPos`, in document order. A Derived block that was moved out of its original still counts. Derivations from another Document are not listed.
- `derivationOriginOf(doc, derivedPos, documentId?)` finds the original and answers `found` (with node and position), `missing` or `foreign`.
- `derivationState(doc, derivedPos, bodyHash, documentId?, foreignHash?, inputHashOf?)` adds `stale` (an original changed since) and `edited` (the body changed since). For a Derivation with `inputs`, `inputHashOf(from)` returns the live hash of one input (`null` = unknown): `stale` is `true` when any input differs, `false` when all match and `null` without `inputHashOf` or while an input is unknown.
- `derivedStateOf(state)` folds a `DerivationState` into one `DerivedStateId`: `missing`, `stale`, `edited`, `foreign` or `fresh`, the first that applies.

## State badge

The composites chrome, the Document tree and the row badge use that one state. `derivedChromeOf(editor, row)` returns `{ state }`. The composites feature registers `derivedRowBadge` under `rowBadges`: a Derived block whose original changed shows „veraltet“ (English: "outdated"), one whose original is gone shows „Quelle fehlt“. A tree row of a Derived block that is stale, missing or edited shows a dot with the reason as its label (`OutlineNode.derived`, `TreeItem.derived`). The labels are the keys `composites.derivation.state.<fresh|stale|edited|missing|foreign>`.

## Source missing

When the original is deleted, the Derived block stays. `derivationState(...).source` is `'missing'`, and the composite chrome, the details card, the Block inspector and the outline of the Document tree show „Quelle fehlt“ (English: "Source missing"). A Derivation from another Document is `foreign` and never missing, because listing those needs a query on the documents port. The last two exports of the example read both states:

```ts
derivedBlocksOf(doc, originalPos, documentId)   // [{ pos, method }, ...]
isSourceMissing(doc, derivedPos, documentId)    // true after the original was deleted
```

`derivationIndexOf`, `derivedOf`, `derivationOriginOf`, `derivationState`, `derivedStateOf`, `derivationFingerprint`, `derivationOf`, `derivedChildrenOf` and `DERIVATION_KEY` are exported from `@skaile/forge-editor/core`, and only from there: `/composites` and `/composites/schema` do not re-export them.


# Document tree

> Show folders, documents and the open document's outline in a file drawer over your own DocumentStore, on Vue and React.

`DocumentTree` is the document drawer: folders and documents of *your* storage, with create, rename, move (drag and drop), delete with undo, per-item Block type filters and the Block outline of the open document. It exists for both surfaces: `@skaile/forge-editor/tree/vue` (Nuxt UI) and `@skaile/forge-editor/tree/react` (shadcn/ui; needs `EditorContextProvider` and a mounted `Toaster`). The framework-free `@skaile/forge-editor/tree` holds the `DocumentStore` contract (the tree's own interface, not the server port `DocumentContentStore`) and the view-state model (`createTreeView`, `treeView(context)`, `TreeViewModel`) that both components and their `useTreeView()` hooks sit on. It needs the settings context (`createEditor()` / `createEditorContext()`), the Typed blocks and media features' code (it reads the Block outline of the Typed blocks and imports files) and a `DocumentStore` that you implement over your storage and router; it does no HTTP or routing of its own.

The drawer shows a „Dokumente“ root with folders and documents, create/rename/move/delete, drag and drop, Block type filters per item, a title filter („Titel filtern“), and the Block outline of the open document (its headings and Typed blocks as one tree, in Flat and Structure mode) listed under it. The tree's own messages (delete with undo) are notices: Vue needs `<UApp>`, React needs `EditorContextProvider` and a mounted `Toaster`.

## Mount the tree

```vue
<script setup lang="ts">
import { DocumentTree } from '@skaile/forge-editor/tree/vue'
import type { DocumentStore } from '@skaile/forge-editor/tree'
import type { Editor } from '@tiptap/core'

defineProps<{ store: DocumentStore, editor: Editor | undefined }>()
const selectedFolder = defineModel<string>('selectedFolder', { default: '' })
</script>

<template>
  <DocumentTree v-model:selected-folder="selectedFolder" :store="store" :editor="editor">
    <template #document-actions="{ id }"><!-- optional host buttons per document --></template>
  </DocumentTree>
</template>
```

React, with the same `store` and a controlled folder:

```tsx
import type { DocumentStore } from '@skaile/forge-editor/tree'
import { DocumentTree } from '@skaile/forge-editor/tree/react'
import type { Editor } from '@tiptap/core'
import { useState } from 'react'

export function Drawer({ store, editor }: { store: DocumentStore, editor: Editor | undefined }) {
  const [selectedFolder, setSelectedFolder] = useState('')
  return (
    <DocumentTree
      store={store}
      editor={editor}
      selectedFolder={selectedFolder}
      onSelectedFolderChange={setSelectedFolder}
      documentActions={({ id }) => null /* optional host buttons per document */}
    />
  )
}
```

- `editor` is the open page's editor (`undefined` when no document is open); take it from your page through a shared composable, as `useActiveEditor()` does in the Nuxt app.
- `v-model:selectedFolder` (React: `selectedFolder` / `onSelectedFolderChange`, uncontrolled when omitted) is where new documents, new folders and your own import actions go. Bind the same state in your import button (the Nuxt app binds it in the layout and passes it to `AppDocumentTree`). The Vue `document-actions` slot is `documentActions` on React.
- Place `DocumentTree` anywhere (a sidebar, a drawer); several can coexist, sharing one filter state per app (`useTreeView()` from `/tree/vue` returns the refs `nodeFilters`, `expanded` and `collapsedOutline`, from `/tree/react` the plain values, both with the framework-free `model`).
- **Title filter.** The field „Titel filtern“ above the tree (clear button, `Esc` clears too) filters by title (for a Typed block without a title: by the label derived from its body, see the next but one point), case-insensitive substring, over folders, documents and the outline entries: only matching rows and their parents stay, the matching part is highlighted, and „Keine Treffer“ shows when nothing matches. While the filter is set the parents of matches are shown open without touching the stored open state; clearing the filter restores the rows that were open before (a row opened or closed by hand meanwhile counts only until then). The title filter belongs to one tree; the Block type filters are the shared per-app state.
- **Refused drops.** While a drag hovers a row, the tree asks whether that drop is allowed (`dropVerdict`, with a reason in the editor's language). An allowed target gets a primary outline and takes the drop; a refused one is outlined red, shows the reason under the row („Notiz nimmt keine Aufgabe auf.“, „Ein Ordner lässt sich nicht in sich selbst oder einen seiner Unterordner verschieben.“, …) and the browser shows „not allowed“. Moving a Typed block is judged by the open document's editor (`moveIntoVerdict`, so the Block types' Accepted children apply); documents and folders follow the folder rules of the `DocumentStore` contract. Both components render one framework-free model (`createTreeModel`, internal, not exported from `./tree`); the props of `DocumentTree` are unchanged.
- The outline entries under the open document are its headings and Typed blocks in both modes; in Structure mode with `blocks.treeRoot: 'file'` the open document is the *virtual root*.
- **Label of an untitled Typed block.** A Typed block without a title is labelled by its own body, so a document of many untitled Typed blocks does not read „(ohne Titel)“ in every row: the text of the first heading of its body, else the first non-empty text of its body cut at 60 characters with „…“. Text inside a nested Typed block is not used, and only a Typed block with an empty body keeps „(ohne Titel)“. The row shows such a derived label muted and italic (`TreeItem.labelFromBody`, `data-label-from-body` on the label), so it does not pass for a title; the title filter matches it like a title. A title always wins.
- The tree header has a „Ordner“ / „Datei als Wurzel“ toggle that writes `blocks.treeRoot` (the same value as the radio group in the settings tab „Bearbeiten“). It is disabled, with an explanation, while no Typed block file is open or `blocks.structure` is `'flat'` (Flat mode); the tree then shows the folders.

The host implementation of the store is [`app/composables/useDocumentStore.ts`](https://github.com/skaile-ai/forge-editor/blob/main/app/composables/useDocumentStore.ts); the `DocumentStore` contract it implements is [below](#documentstore).

## Props

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 }`. Further props: `reorder` (a `RowReorder`, see below).

**Host row reorder and Typed block slots (4.3).** The tree moves a Typed block row by the library's own drop rules (into another Typed block, or to the end of the document). A host that orders the rows among each other (e.g. the root blocks of a virtual-root document, where a drop on a row means "take its place") passes `reorder: RowReorder` (exported from `@skaile/forge-editor/tree` with `TreeItem`, `DragPayload` and `DropVerdict`):

- `verdict(source, target): DropVerdict | null` is asked first for every drag of the tree's own rows; `{ ok: true }` or `{ ok: false, reason }` decides (the row shows the reason like any refused drop), `null` leaves it to the library rules.
- `drop(source, target)` runs when the host's verdict was `ok`; the host moves the rows (the tree emits no `moveBlock`).
- `step?(item, direction)` runs on **Ctrl+↑ (-1) / Ctrl+↓ (1)** on a focused row and moves it one place among its siblings; it returns `false` when the row is not the host's (the tree does nothing else with Ctrl+arrow); after a `true` the keyboard focus follows the row to its new place, so the next press moves the same row on. Without `step` the shortcut does nothing.

Two slots decorate Typed block rows only: `block-badges` (`{ item: TreeItem }`; always visible, right after the label, e.g. a warning icon) and `block-actions` (`{ item: TreeItem }`; in the controls that show on hover or focus, after the add menu, e.g. a status menu). The row element carries `data-tree-key` (the item key). In React the props are `reorder`, `blockBadges(item)` and `blockActions(item)`. The runnable adapter is [`app/components/AppDocumentTree.vue`](https://github.com/skaile-ai/forge-editor/blob/main/app/components/AppDocumentTree.vue); the layout holds `selectedFolder` and binds it with `v-model:selected-folder`.

`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/document-store.ts`](https://github.com/skaile-ai/forge-editor/blob/main/examples/react-advanced/src/document-store.ts).

## `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 `@skaile/forge-editor/core`), so the same store drives both components. A Vue host that keeps refs adapts them with `storeFromRef(ref)` and `useStoreRef(storeOrGetter)` from `@skaile/forge-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`. The editor serves them: `GET /api/editor/tree` answers a `TreeFolder` and `GET /api/editor/documents` the `DocumentSummary[]` (from the documents port's `DocumentAdmin.listTree`). A host adapter that builds the tree imports the types from `@skaile/forge-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 Block types 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`, `collapsedOutline`, `expand`, `setKindHidden`, `clearFilter`, `clearAllFilters`, `followFolderMove`), `treeView(context)` returns the one of an `EditorContext`'s app, and `useTreeView()` (`/tree/vue`: `nodeFilters`, `expanded` and `collapsedOutline` as refs; `/tree/react`: as plain values that re-render the component) reads it, so several trees of one app share it (see [§11](https://skaile-ai.github.io/forge-editor/guides/settings)).
- Outline rows are open unless their key (`outline:<block id>`) is in `collapsedOutline`; it lasts for the session, so a tree mounted again shows the rows as they were left. A host sets it to start with rows closed, e.g. `treeView(context).collapsedOutline.set(ids.map(id => `outline:${id}`))` for the top Typed blocks.
- The basket filter belongs to the same view state: `basketFilter` (the basket ids to show, `[]` = all; persists under `tip-tree:basket-filter`), `setBasketShown(id, shown)` and `clearBasketFilter()` on `TreeViewModel` ([below](#baskets-focus-and-foreign-drops)).
- 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 Structure mode (`blocks.structure === 'structured'`) is the *virtual root* of the tree: its Typed blocks are the nested items and dragging one moves the block (`moveBlockInto`) unless the target Typed block's Block type does not accept it (`acceptsChild`, from the Block type's `accepts`): the drop is then refused, outlined red with the reason of `moveIntoVerdict` under the row. With no open document or in Flat mode the tree shows the folders instead. Switching it in the settings panel re-roots the tree immediately.
- The Block outline of the open document is read from `editor` (`documentOutline`, from `/composites`): its headings and Typed blocks as one tree in document order, the same in Flat and Structure mode. A heading nests under the nearest shallower heading before it, a Typed block under the heading it follows, and the headings in a Typed block's body start their own levels below it, so converting headings into Typed blocks („Überschriften in Blöcke“) or back keeps every entry. The Block type filter of the open document and of its rows lists the Block types plus „Überschriften“ (`HEADING_KIND` from `/tree`); hiding the headings lifts the entries below them. The basket filter hides a heading unless a shown Typed block is below it, which then keeps it dimmed. The outline is 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.

## Baskets, focus and foreign drops

Three additions for a tree of Typed blocks; the editor side of each is in [Content tree mechanics](https://skaile-ai.github.io/forge-editor/guides/content-tree). The German labels of the basket controls still use a legacy word, so this section quotes their English catalog labels (English label).

- **Basket dot and filter.** A Typed block row shows the dot of its basket (`meta.basket`; the baskets are the ones the open editor offers, `compositeFeature({ baskets })`). With a live editor that offers baskets, a paint-bucket button (“Filter by basket”) next to the title filter opens a menu of baskets to check; the tree then shows only the Typed blocks of the checked baskets (none checked = all) plus their ancestors, which are dimmed (`TreeRowState.dimmed`). Documents, folders and headings are never hidden; “Reset basket filter” clears it. The choice is `TreeViewModel.basketFilter`, shared by the trees of one app and stored in `localStorage` under `tip-tree:basket-filter`; an id the open editor does not offer never filters.
- **Focus.** Every Typed block row has a focus button („Fokussieren“). A focused row lists only its children, under a breadcrumb whose first crumb is the document („Fokus aufheben“ leaves the focus) and whose other crumbs refocus that level; the Block type filters of the rows on the way down still apply to the children (`TreeState.focusKey`, `focusPath`). The tree and the editor stay in step: focusing a row sends the `TreeCommand` `{ type: 'focusBlock', id }`, whose executor runs `focusComposite(id)` on the `editor` prop (`id: null` leaves it), and a focus started in the editor (block action „Fokussieren“, the focus chip) is mirrored into the tree. A focused Typed block that disappears, or another editor, resets the focus. Only a Typed block with a block id can be focused.
- **Merge.** A Typed block row whose Typed block the open editor can merge with the Typed block after it shows a merge button („Mit nächstem zusammenführen“, next to the focus button). It sends the `TreeCommand` `{ type: 'mergeBlock', id }`, whose executor runs `mergeCompositeWithNext` on the `editor` prop ([Merging with the next Typed block](https://skaile-ai.github.io/forge-editor/guides/content-tree#merging-with-the-next-typed-block)); `TreeModel.canMerge(item)` says whether to show it, `merge(item)` sends it.
- **Foreign drops.** A Typed block dragged in from another editor surface or tree (`BLOCK_MIME`, [payload](https://skaile-ai.github.io/forge-editor/guides/content-tree#the-payload)) is accepted in the *virtual root* mode (`blocks.treeRoot = 'file'`) on the document root and on a Typed block row that has a block id (`DragPayload` `{ type: 'foreign-block' }`); any other row, or the folder mode, refuses it with „Hier lassen sich keine Blöcke ablegen.“. The model emits `TreeCommand` `{ type: 'transferBlock', payload, targetId, menu, x, y }`, and the executor runs `editor.commands.transferBlock` at the **end of the target Typed block** (`targetId: null` = the end of the document); with Shift held at the drop (`menu: true`) the transform menu opens at the pointer first. This needs `transferFeature` in the open editor's preset ([Block transfer](https://skaile-ai.github.io/forge-editor/guides/content-tree#block-transfer)); without it the tree refuses every foreign drop („Dieser Editor nimmt keine Blöcke von außen an.“). The rows write their own payload when dragged, so a tree row can be dropped on another surface or tree.

The `TreeCommand` union gained `transferBlock`, `focusBlock` and `mergeBlock`, and `DragPayload` gained `{ type: 'foreign-block' }`; the components run these commands through the open editor, so a host does not handle them. A host that switches exhaustively over `TreeCommand` or `DragPayload` needs the new cases.

## 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`).


# Edges: backlinks and authored connections

> Which Blocks point at a Block: the Edges the Block index projects from references, Derivations, embeds and tags, the ones a person adds in the inspector, the edges route and the drizzle table.

An **Edge** is a directed, typed connection from one Block to another Block or to a tag name. The [Block index](https://skaile-ai.github.io/forge-editor/guides/workspace) holds the Edges of every Block next to its row, so the question „which Blocks point at this one?“ needs no scan of the Documents.

## Where Edges come from

`projectDocument` (`@skaile/forge-editor/core`) fills `BlockRow.edges` while it projects a Document. One Edge exists per kind and target; a Block never lists the same Edge twice.

<table>
<thead>
  <tr>
    <th>
      <code>
        kind
      </code>
    </th>
    
    <th>
      <code>
        origin
      </code>
    </th>
    
    <th>
      Written by
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        reference
      </code>
    </td>
    
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      a reference chip (<code>
        [@…]
      </code>
      
      ) anywhere in the Block, nested Blocks included
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivation
      </code>
    </td>
    
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      the Block the Block's Derivation was made from (not an uploaded asset)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        embed
      </code>
    </td>
    
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      a <code>
        blockEmbed
      </code>
      
       (<code>
        ![[…]]
      </code>
      
      ) in the Block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tag
      </code>
    </td>
    
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      a tag chip or a tag of a Typed block; the target is <code>
        { tag }
      </code>
      
      , not a Block
    </td>
  </tr>
  
  <tr>
    <td>
      any other string
    </td>
    
    <td>
      <code>
        meta
      </code>
    </td>
    
    <td>
      an Edge a person added by hand: <code>
        meta.edges
      </code>
      
       of the Typed block
    </td>
  </tr>
</tbody>
</table>

A target without a Document resolves to the Document the Block is in. The index never checks that the target exists: an Edge to a deleted Block stays until its source changes.

```ts
import { projectDocument } from '@skaile/forge-editor/core'

const [row] = projectDocument(content, 'doc-1')
row.edges
// [{ to: { documentId: 'doc-2', blockId: 'b' }, kind: 'reference', origin: 'content' },
//  { to: { tag: 'klima' }, kind: 'tag', origin: 'content' },
//  { to: { documentId: 'doc-1', blockId: 'c' }, kind: 'supports', origin: 'meta' }]
```

## Ask for the Edges of a Block

`BlockIndex.edges(address, direction, scope)` answers `BlockEdge[]`: the row's Edge with `from`, the Block it is written in.

- `direction: 'out'` are the Edges written in the Block itself, `tag` Edges included.
- `direction: 'in'` are the Edges of other Blocks that point at it, in Document order of `scope`. A `tag` Edge never points at a Block, so it is never an incoming one.

The **backlinks** of a Block are its incoming Edges. A Block that does not exist has no Edges (`[]`), not an error.

### Route and client

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Route
    </td>
    
    <td>
      <code>
        GET /api/editor/blocks/:documentId/:blockId/edges?direction=in|out
      </code>
      
       (<code>
        API.blockEdges
      </code>
      
      , port <code>
        index
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Default
    </td>
    
    <td>
      <code>
        in
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Client
    </td>
    
    <td>
      <code>
        EditorBackend.index.edges(address, direction?, signal?)
      </code>
      
      , optional: a backend without Edges leaves it out
    </td>
  </tr>
</tbody>
</table>

The route answers only Edges written in Documents the user may read (the same scope as the [Workspace search](https://skaile-ai.github.io/forge-editor/guides/workspace)). It answers `403` when the user may not read the Document of the Block, `400` for a `direction` other than `in` or `out`, `401` without a user and `501` without the `index` port.

## Add Edges by hand

The inspector and the details card of a Typed block show the section **Kanten** (the `edges` slot of `compositeFeature`, `EdgesSection` in both bindings). It lists the Edges of `meta.edges` with the kind and the title of the target, and it has a form to add one: the kind as free text, then the target, searched with the same list as the `[@` popup (the blocks of this Document, and with the `index` capability those of other Documents). A click on an entry adds the Edge; the remove button next to an Edge takes it out again. A read-only editor shows the list without the form.

`meta.edges` is a list of `{ to: { documentId?, blockId }, kind }` (`AuthoredEdge`, `META_EDGES_KEY`). The key is written through `setBlockProperty`, so it follows the same rules as every other Block property: in a collaboration session the server writes it into the open Y.Doc. Entries without a block ID or without a kind are ignored by the projection.

The framework-free model is `features/composites/edges-model.ts` (`edgesSectionOf`, `addAuthoredEdge`, `removeAuthoredEdge`, `edgeTargetChoicesOf`); the Vue and React components only render it.

## The drizzle table

The drizzle adapter writes the Edges to `editor_block_edges` in the same transaction as the rows of `replace`:

<table>
<thead>
  <tr>
    <th>
      Column
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        from_document_id
      </code>
      
      , <code>
        from_block_id
      </code>
    </td>
    
    <td>
      the Block the Edge is written in
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        seq
      </code>
    </td>
    
    <td>
      position in the row's list; with <code>
        from_document_id
      </code>
      
       the primary key
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        to_document_id
      </code>
      
      , <code>
        to_block_id
      </code>
    </td>
    
    <td>
      the target Block; <code>
        NULL
      </code>
      
       for a <code>
        tag
      </code>
      
       Edge
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tag
      </code>
    </td>
    
    <td>
      the tag name of a <code>
        tag
      </code>
      
       Edge, else <code>
        NULL
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        kind
      </code>
      
      , <code>
        origin
      </code>
    </td>
    
    <td>
      as in <code>
        BlockEdgeRow
      </code>
    </td>
  </tr>
</tbody>
</table>

An index on `(to_document_id, to_block_id)` answers the incoming Edges without a scan. `blockIndexTables()` returns `{ blocks, edges }`, so a host that migrates the tables with `drizzle-kit` adds both to its schema; `bootstrapBlockIndexTables(db)` creates both with `IF NOT EXISTS`. The memory adapter answers from its rows; both pass the same contract suite (`test/support/block-index-contract.ts`).


# EditorPorts: auth and storage

> The single seam between the package and the host: ports for identity, documents, Yjs state, assets, settings, themes and AI models.

## 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.

## Registering the ports

The single seam between the package and the host: one object of ports, named by the capabilities the client's `EditorBackend` knows (`documents`, `collaboration`, `assets`, `users`, `tags`, `settings`, `themes`, `ai`, `comments`, `images`). `identity` (type `AccessControl`) and `documents` (type `DocumentContentStore`) are required; every other port is optional, and the route table serves only the routes whose port is present (the client treats a refused settings load as "no account settings" and stays on `localStorage`). `PORT_CAPABILITY` maps port to capability, `serverCapabilities(ports)` lists what a set of ports serves (`tags` follows from `documents`). Register the ports in a Nitro plugin:

```ts [server/plugins/editor-adapter.ts]
import type { User } from '#auth-utils'
import { createJsonAdapter } from '@skaile/forge-editor/adapters/json'
import { provideEditorServer } from '@skaile/forge-editor/server/nitro'
import { createWorkspaceTools } from '@skaile/forge-editor/server'

// Connects the editor package's Nuxt integration to this app's sessions, JSON document store and per-user settings.
// Synchronous on purpose: Nitro does not await a plugin, so registering after an `await` would leave the first requests without an editor server.
export default defineNitroPlugin(() => {
  // The add-ons' ports (render targets, speech, knowledge graph) and Block types; each add-on is on behind its flag, `runtimeConfig.public.addons.<name>` (`server/utils/addons.ts`).
  const addons = createAddonServer({ storeAsset, loadAsset }, addonFlagsOf(useRuntimeConfig().public.addons))
  provideEditorServer({
    ports: {
      identity: {
        // Without a session cookie h3 throws ("Cannot initialize a new session") outside a main handler.
        authenticate: request => getUserSession({ headers: request.headers, context: {} }).then(s => s.user ?? null, () => null),
      },
      documents: {
        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() })
        },
        listContents: async () => (await listAllDocuments()).map(({ id, content }) => ({ id, content })),
        // Document management over the package store: folders, create, move, delete (`/api/editor/{documents,tree}`).
        listDocumentIds: async () => indexedIds(),
        listTree,
        async createDocument(input) {
          const { id, title, updatedAt } = await createDocument(input)
          return { id, title, updatedAt, folder: input.folder ?? '' }
        },
        moveDocument,
        deleteDocument: removeDocument,
      },
      directory: { listUsers: async () => (await listUsers()).map(toSessionUser) },
      collabState: { loadState, storeState, removeState },
      assets: { storeAsset, loadAsset },
      // `user` is what `authenticate` returned: the session user.
      settings: {
        loadSettings: user => getUserSettings((user as User).id),
        storeSettings: (user, settings) => putUserSettings((user as User).id, settings),
      },
      themes: { listThemes, loadTheme, storeTheme, removeTheme },
      // Block index (`index` capability): a projection of the documents above, rebuilt on start and kept current by the editor server; in memory (memory adapter, PGlite with `NUXT_BLOCK_INDEX=pglite`, or PGlite with trigram search and vectors with `NUXT_BLOCK_INDEX=pg-vector`), so nothing to migrate.
      index: createHostBlockIndex(addons.ports.embeddings, addons.embeddingsError),
      // Prüfung records (`pruefung` capability): the editor's JSON store on `<documents dir>/.pruefung.json`, a dot-named file the document store never lists.
      pruefung: createJsonAdapter({ dir: storeRoot() }).pruefung,
      // Change sets of the document chat (`changeSets` capability): what the model proposed for other Documents, decided per Document; `<documents dir>/.change-sets.json`, likewise dot-named.
      changeSets: createJsonAdapter({ dir: storeRoot() }).changeSets,
      // Demo of the model port (`DEMO_STUB_MODEL=1`): the stub answers `{ preset: 'stub' }`; `null` for anything else falls through to the environment presets.
      models: {
        languageModel: async ref => stubModelEnabled() && 'preset' in ref && ref.preset === STUB_MODEL_ID ? stubLanguageModel : null,
        listModels: async () => stubModelEnabled() ? [...publicEnvPresets(), stubModelProfile] : null,
      },
      ...addons.ports,
    },
    ...(addons.blockTypes && { blockTypes: addons.blockTypes }),
    // The document chat's read-only workspace tools (`find_blocks`, `read_block`): the model finds and reads Blocks of the user's other Documents through the block index above.
    tools: createWorkspaceTools(addons.blockTypes && { blockTypes: addons.blockTypes }),
  })
})
```

## Capability probe

By default the HTTP backend assumes every capability and a feature whose route the server does not mount fails on use (404/501). `createHttpBackend({ probe: true })` instead asks `GET /api/editor/capabilities` once, drops the backend fields the server does not list (`comments` without a comments port, `themes` without a themes port, `ai` without configured models, …) and exposes the request as `backend.ready`, which `createEditorContext` awaits before it reports `ready`; so `composeEditor(…, { backend })` prunes exactly what the server lacks, reported in `omitted`. Compose after `await backend.ready` (the Nuxt plugin does: it installs the context with `probe: true` and finishes only then). A failed probe (offline, 401, an answer that is no list) keeps every capability and warns once on the console (`@skaile/forge-editor: the capability probe …`). The Nuxt module passes `probe: true`; a Vite or bare Nitro host opts in.

## Capability locality

Every capability of `EditorBackend` falls in one of three classes, by what a server is needed for. The class is derived from the adapters, not a runtime setting; it tells you which capabilities a client-only host keeps and which it gives up:

<table>
<thead>
  <tr>
    <th>
      Class
    </th>
    
    <th>
      Meaning
    </th>
    
    <th>
      Capabilities
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        local
      </code>
    </td>
    
    <td>
      works in the page; a server only makes it durable or shared
    </td>
    
    <td>
      <code>
        documents
      </code>
      
      , <code>
        assets
      </code>
      
      , <code>
        users
      </code>
      
      , <code>
        tags
      </code>
      
      , <code>
        settings
      </code>
      
       (all served by <a href="https://skaile-ai.github.io/forge-editor/guides/storage-adapters">
        <code>
          createMemoryBackend
        </code>
      </a>
      
      ; documents, uploaded files as <code>
        blob:
      </code>
      
       URLs and settings last as long as the page); <code>
        themes
      </code>
      
       (in the page only through a host-written <code>
        themes
      </code>
      
       member: the memory backend ships none)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        relay
      </code>
    </td>
    
    <td>
      a server only holds a secret and enforces a limit; the work itself can run in the page
    </td>
    
    <td>
      <code>
        ai
      </code>
      
      : the server keeps the model key and applies the per-user rate limit (<code>
        ai.rateLimit
      </code>
      
       of the <a href="https://skaile-ai.github.io/forge-editor/guides/ai-configuration">
        configuration
      </a>
      
      ), then calls the model. <code>
        createDirectAi
      </code>
      
       makes <code>
        generate
      </code>
      
      , <code>
        complete
      </code>
      
      , <code>
        models
      </code>
      
       and <code>
        transcriptCleanup
      </code>
      
       local, at the price of the key in the browser and no rate limit; <code>
        chat
      </code>
      
       and <code>
        extract
      </code>
      
       stay server-only. <code>
        images
      </code>
      
      : the host's provider holds the image-model key, stores the generated and uploaded files and keeps the prompt blocks; there is no browser-direct variant
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        session
      </code>
    </td>
    
    <td>
      a server owns live state that several clients share
    </td>
    
    <td>
      <code>
        collaboration
      </code>
      
       (the Hocuspocus server holds the Yjs document), <code>
        comments
      </code>
      
       (the comments endpoint holds the threads)
    </td>
  </tr>
</tbody>
</table>

A client-only composition is `{ ...createMemoryBackend(), ai: createDirectAi({ presets }) }` (see [Browser-direct AI](https://skaile-ai.github.io/forge-editor/guides/storage-adapters#browser-direct-ai)): the `local` capabilities the memory backend serves plus a locally running `ai`, no `session` capability. `composeEditor(…, { backend })` then prunes `collab`, `comments` and `themes`, reported in `omitted`.

## Port members

<table>
<thead>
  <tr>
    <th>
      Port
    </th>
    
    <th>
      Member
    </th>
    
    <th>
      Signature
    </th>
    
    <th>
      Called
    </th>
    
    <th>
      Must return
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        identity
      </code>
    </td>
    
    <td>
      <code>
        authenticate
      </code>
    </td>
    
    <td>
      <code>
        (request: { headers: Headers, token?: string }) => Promise<object | null>
      </code>
    </td>
    
    <td>
      Collab websocket (Hocuspocus <code>
        onAuthenticate
      </code>
      
      ; <code>
        token
      </code>
      
       is the client's <code>
        collaboration.token
      </code>
      
      , absent for HTTP routes and token-less clients); first in every API route that needs a user
    </td>
    
    <td>
      The user, or <code>
        null
      </code>
      
       (→ 401). The value becomes the Hocuspocus connection context's <code>
        user
      </code>
      
      , the <code>
        user
      </code>
      
       argument of the settings methods and the rate-limit key (<code>
        id
      </code>
      
      , else <code>
        username
      </code>
      
      , else its JSON).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        documents
      </code>
    </td>
    
    <td>
      <code>
        loadContent
      </code>
    </td>
    
    <td>
      <code>
        (id) => Promise<JSONContent | null>
      </code>
    </td>
    
    <td>
      <code>
        onLoadDocument
      </code>
      
      , when no usable Yjs state exists (new, legacy or restored document)
    </td>
    
    <td>
      TipTap JSON to seed the Y.Doc from, as stored (the editor migrates it to the current shape itself, see below); <code>
        null
      </code>
      
       = the document does not exist (connection closed)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        documents
      </code>
    </td>
    
    <td>
      <code>
        storeContent
      </code>
    </td>
    
    <td>
      <code>
        (id, content) => Promise<void>
      </code>
    </td>
    
    <td>
      <code>
        onStoreDocument
      </code>
      
       (debounced after edits, and on shutdown via the Nitro <code>
        close
      </code>
      
       hook)
    </td>
    
    <td>
      Mirrors the JSON; tolerate ids deleted meanwhile
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        documents
      </code>
    </td>
    
    <td>
      <code>
        listContents
      </code>
    </td>
    
    <td>
      <code>
        () => Promise<{ id, content }[]>
      </code>
    </td>
    
    <td>
      <code>
        GET /api/editor/tags
      </code>
    </td>
    
    <td>
      Stored JSON of every document, as stored
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        directory
      </code>
    </td>
    
    <td>
      <code>
        listUsers
      </code>
    </td>
    
    <td>
      <code>
        () => Promise<MentionUser[]>
      </code>
      
       (<code>
        { id, username, color }
      </code>
      
      )
    </td>
    
    <td>
      <code>
        GET /api/editor/users
      </code>
      
      , <code>
        POST /api/ai/generate
      </code>
      
       for tasks that need users
    </td>
    
    <td>
      Every user that can be <code>
        @
      </code>
      
      -mentioned, no credentials
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collabState
      </code>
    </td>
    
    <td>
      <code>
        loadState
      </code>
    </td>
    
    <td>
      <code>
        (id) => Promise<Uint8Array | null>
      </code>
    </td>
    
    <td>
      <code>
        onLoadDocument
      </code>
    </td>
    
    <td>
      The bytes <code>
        storeState
      </code>
      
       received, unchanged (the Yjs update behind a content-version prefix; state from earlier releases is a raw update and loads as version <code>
        null
      </code>
      
      ); <code>
        null
      </code>
      
       = none yet
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collabState
      </code>
    </td>
    
    <td>
      <code>
        storeState
      </code>
    </td>
    
    <td>
      <code>
        (id, state) => Promise<void>
      </code>
    </td>
    
    <td>
      <code>
        onStoreDocument
      </code>
      
      , and right after a Y.Doc was seeded or block IDs were backfilled
    </td>
    
    <td>
      Persist; tolerate deleted ids
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        collabState
      </code>
    </td>
    
    <td>
      <code>
        removeState
      </code>
    </td>
    
    <td>
      <code>
        (id) => Promise<void>
      </code>
    </td>
    
    <td>
      <code>
        EditorServer.forgetDocument
      </code>
      
      , and <code>
        onLoadDocument
      </code>
      
       when the stored state is stale (<code>
        contentVersion
      </code>
      
      )
    </td>
    
    <td>
      Drop the state of a deleted or rewritten document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        identity
      </code>
    </td>
    
    <td>
      <code>
        authorize?
      </code>
    </td>
    
    <td>
      <code>
        (user, id) => Promise<{ readOnly: boolean } | null>
      </code>
    </td>
    
    <td>
      Hocuspocus <code>
        onConnect
      </code>
      
      , with the object <code>
        authenticate
      </code>
      
       returned
    </td>
    
    <td>
      <code>
        null
      </code>
      
       rejects the connection (permission denied); <code>
        { readOnly: true }
      </code>
      
       lets it sync but applies none of its edits. Omit: every authenticated user may edit every document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        documents
      </code>
    </td>
    
    <td>
      <code>
        contentVersion?
      </code>
    </td>
    
    <td>
      <code>
        (id) => Promise<string | null>
      </code>
    </td>
    
    <td>
      <code>
        onLoadDocument
      </code>
      
      ; right after every <code>
        storeContent
      </code>
      
      ; before every store of an open document
    </td>
    
    <td>
      Opaque version of the stored content (mtime, hash, revision; no NUL character), <code>
        null
      </code>
      
       = unknown. A stored state with another version is discarded and the document is re-seeded from <code>
        loadContent
      </code>
      
      ; an open document whose version moved is merged with <code>
        loadContent
      </code>
      
       on its next store instead of being written back. Omit: state is never discarded
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        assets
      </code>
    </td>
    
    <td>
      <code>
        storeAsset
      </code>
    </td>
    
    <td>
      <code>
        (id, asset: AssetRecord & { data: Buffer }) => Promise<void>
      </code>
    </td>
    
    <td>
      <code>
        POST /api/editor/assets/:id
      </code>
    </td>
    
    <td>
      Persist the file under <code>
        asset.name
      </code>
      
       with its record. <code>
        id
      </code>
      
       is a document id or <code>
        scratch
      </code>
      
      ; it need not name an existing document.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        assets
      </code>
    </td>
    
    <td>
      <code>
        loadAsset
      </code>
    </td>
    
    <td>
      <code>
        (id, name) => Promise<{ record, data } | null>
      </code>
    </td>
    
    <td>
      <code>
        GET /api/editor/assets/:id/:name
      </code>
    </td>
    
    <td>
      The stored file; <code>
        null
      </code>
      
       → 404
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        settings
      </code>
    </td>
    
    <td>
      <code>
        loadSettings
      </code>
    </td>
    
    <td>
      <code>
        (user) => Promise<unknown | null>
      </code>
    </td>
    
    <td>
      <code>
        GET /api/editor/settings
      </code>
    </td>
    
    <td>
      Stored settings (normalized by the route), <code>
        null
      </code>
      
       = none yet. Port absent: the settings routes are not mounted, settings stay in <code>
        localStorage
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        settings
      </code>
    </td>
    
    <td>
      <code>
        storeSettings
      </code>
    </td>
    
    <td>
      <code>
        (user, settings) => Promise<void>
      </code>
    </td>
    
    <td>
      <code>
        PUT /api/editor/settings
      </code>
    </td>
    
    <td>
      Persist the validated settings
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        themes
      </code>
    </td>
    
    <td>
      <code>
        listThemes
      </code>
    </td>
    
    <td>
      <code>
        () => Promise<ThemeRecord[]>
      </code>
    </td>
    
    <td>
      <code>
        GET /api/editor/themes
      </code>
    </td>
    
    <td>
      The shared theme library (<code>
        { id, name, version?, author?, authorUrl?, builtin }
      </code>
      
      ), host-seeded themes marked <code>
        builtin: true
      </code>
      
      . Port absent: the themes routes are not mounted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        themes
      </code>
    </td>
    
    <td>
      <code>
        loadTheme
      </code>
    </td>
    
    <td>
      <code>
        (id) => Promise<{ record, css } | null>
      </code>
    </td>
    
    <td>
      <code>
        GET /api/editor/themes/:id
      </code>
    </td>
    
    <td>
      The theme's <code>
        theme.css
      </code>
      
       text with its record; <code>
        null
      </code>
      
       → 404
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        themes
      </code>
    </td>
    
    <td>
      <code>
        storeTheme
      </code>
    </td>
    
    <td>
      <code>
        (record: Omit<ThemeRecord, 'builtin'>, css) => Promise<void>
      </code>
    </td>
    
    <td>
      <code>
        POST /api/editor/themes
      </code>
    </td>
    
    <td>
      Persist an uploaded theme. The route has already validated the content and chosen a unique <code>
        record.id
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        themes
      </code>
    </td>
    
    <td>
      <code>
        removeTheme
      </code>
    </td>
    
    <td>
      <code>
        (id) => Promise<boolean>
      </code>
    </td>
    
    <td>
      <code>
        DELETE /api/editor/themes/:id
      </code>
    </td>
    
    <td>
      Delete an upload; <code>
        false
      </code>
      
       = unknown id or builtin (the route has checked <code>
        listThemes()
      </code>
      
       first and answers 403 / 404 itself)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        models
      </code>
    </td>
    
    <td>
      <code>
        languageModel?
      </code>
    </td>
    
    <td>
      <code>
        (ref: ModelRef, user) => Promise<LanguageModel | null>
      </code>
    </td>
    
    <td>
      Every AI endpoint (<code>
        /api/ai/{generate,chat,complete,transcript-cleanup}
      </code>
      
      ), before the runtime-config Model presets
    </td>
    
    <td>
      The AI SDK language model for <code>
        ref
      </code>
      
       (<code>
        { preset }
      </code>
      
       or a user Model profile's endpoint/model/key), so the host's own providers serve the editor. <code>
        user
      </code>
      
       is what <code>
        authenticate
      </code>
      
       returned. <code>
        null
      </code>
      
       falls through to the Model presets (400 for an unknown preset)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        models
      </code>
    </td>
    
    <td>
      <code>
        listModels?
      </code>
    </td>
    
    <td>
      <code>
        (user) => Promise<ModelProfile[] | null>
      </code>
    </td>
    
    <td>
      <code>
        GET /api/ai/models
      </code>
    </td>
    
    <td>
      The models offered to <code>
        user
      </code>
      
      , replacing the Model preset list (list them with <code>
        source: 'preset'
      </code>
      
       and the <code>
        id
      </code>
      
       that <code>
        languageModel
      </code>
      
       receives as <code>
        { preset: id }
      </code>
      
      ). <code>
        null
      </code>
      
       lists the runtime-config Model presets
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        comments
      </code>
    </td>
    
    <td>
      the <code>
        CommentStore
      </code>
    </td>
    
    <td>
      see <a href="https://skaile-ai.github.io/forge-editor/guides/storage-adapters">
        Storage adapters
      </a>
    </td>
    
    <td>
      the comments routes (Nitro host only)
    </td>
    
    <td>
      The comment store
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        images
      </code>
    </td>
    
    <td>
      <code>
        promptBlocks
      </code>
    </td>
    
    <td>
      <code>
        (user) => Promise<ImageStudioPromptBlock[]>
      </code>
    </td>
    
    <td>
      <code>
        GET /api/editor/images/prompt-blocks
      </code>
    </td>
    
    <td>
      The prompt blocks (<code>
        { id, label, text }
      </code>
      
      : style, brand, …) the host manages, in its order. Port absent: the image routes are not mounted
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        images
      </code>
    </td>
    
    <td>
      <code>
        generate
      </code>
    </td>
    
    <td>
      <code>
        (body: ImageStudioGenerateBody, user) => Promise<ImageStudioImage>
      </code>
    </td>
    
    <td>
      <code>
        POST /api/editor/images/generate
      </code>
    </td>
    
    <td>
      Generates and stores one image from <code>
        { description, instruction, promptBlockIds, referenceUrls }
      </code>
      
      ; the host builds the prompt. Answers <code>
        { id, url, title, active }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        images
      </code>
    </td>
    
    <td>
      <code>
        upload
      </code>
    </td>
    
    <td>
      <code>
        (documentId, file: File, user) => Promise<ImageStudioImage>
      </code>
    </td>
    
    <td>
      <code>
        POST /api/editor/images/upload
      </code>
    </td>
    
    <td>
      Stores an uploaded reference image of document <code>
        documentId
      </code>
      
      . The route has checked the id, that the file is an image and its size (<code>
        413
      </code>
      
       above <code>
        MAX_MEDIA_BYTES.image
      </code>
      
      , <code>
        415
      </code>
      
       for other types)
    </td>
  </tr>
</tbody>
</table>

The collaboration schema is not part of storage: `createCollabServer({ ports, schema })` and `installEditorServer` take `schema?: () => AnyExtension[]` (default `advancedSchemaExtensions()`; host nodes: `() => [...advancedSchemaExtensions(), Callout]`); `provideEditorServer({ ports, schema })` (Nuxt) takes the same option, and `server.collab?.stats()` of the `EditorServer` handle returns `{ connections, documents }` of the running server. The collab server needs the `collabState` port and throws „@skaile/forge-editor: collaboration needs the collabState port“ without it.

The host's Block types are not storage either; `installEditorServer({ blockTypes })` and `provideEditorServer({ ports, blockTypes })` take the list the editors get through `blockTypes` (for instance loaded from a JSON file, see [Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types#the-server)), so the AI chat describes them to the model instead of the `kinds` the client sends.

Omit the `settings` port to keep settings in the browser only (the settings routes are not mounted; the client falls back to `localStorage`).

The theme methods `storeTheme` and `removeTheme` are only needed for uploads; without them the upload and delete routes answer 501 while builtins stay selectable. Without the `themes` port the routes are not mounted and the `themes` feature falls back to the Default appearance (a console warning, the stored setting stays). `ThemeRecord` and the `THEME_ID` pattern come from the Vue-free `@skaile/forge-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

`DELETE /api/editor/documents/:id` does it all: it calls `forgetDocument` of the collaboration server (stateless message `deleted` to connected clients, connections closed, a pending store blocked from writing the state back) and then `DocumentAdmin.deleteDocument`, which also drops the document's Yjs state and its Blocks from the index. A host route that removes a document itself calls `forgetDocument(id)` of the `EditorServer` handle (`installEditorServer` returns it; a Nuxt host's routes get it from `useEditorServer()`) before removing the JSON. `liveContent(id)` of the handle returns the current content of a document that is open in Hocuspocus (unsaved edits included), `null` when nobody has it open.

## Listing, creating and moving documents

A documents port whose documents live in folders implements three optional `DocumentAdmin` members: `listTree(): TreeFolder`, `createDocument({ title?, folder? }): DocumentSummary` and `moveDocument(id, folder)`. They serve `GET /api/editor/documents` (the Documents the user may read, newest first), `GET /api/editor/tree`, `POST /api/editor/documents` and `PUT /api/editor/documents/:id/folder`; without them these routes answer 501. A `DocumentStore` for the file tree (see the document tree guide) is a client of exactly these routes plus `DELETE /api/editor/documents/:id`; the reference app's `server/plugins/editor-adapter.ts` serves them over its package store.

## Changing a document from the server

`POST /api/editor/documents/:id/ops` with `{ ops }` applies block operations (`update`, `add`, `delete`, `convert`: the shape of the document chat's `edit_document` tool, `ModelAgentOp`) to a document nobody has to have open, all or none. The `DocumentMutator` behind it (`createDocumentMutator({ ports, collab, schema, blockTypes, reindex })` of `@skaile/forge-editor/server`; `EditorServer.mutator` of the installed server) checks every operation against the block IDs of the document (`checkAgentOps`), parses the Markdown without an editor (`createMarkdownBlocks`), changes an open document inside its Y.Doc (connected clients see an ordinary edit) and a stored one through `storeContent`, and re-projects the Block index either way. Refusals: `403` for a read-only user, `404` for an unknown document, `409` when a named block no longer exists, `422` for an invalid operation (the error `data` lists the problems). Host code that acts for a user calls `server.mutator.apply(documentId, ops, { user })`.

## Content rewritten behind the editor's back

When something other than the editor writes a document's content (an agent rewrites the file), call `server.collab.contentChanged(id)` (the handle's `collab`, or the one of 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).

## Reading stored content

The ports return content exactly as the host stored it, possibly written by an earlier release. Server code that reads it (a host route, a script) uses the one load operation of `@skaile/forge-editor/server`, which applies the stored-content migration once and completely: `loadCurrentContent(ports.documents, id)` (one document, `null` when missing), `listCurrentContents(ports.documents)` (all documents) and `currentContent(json)` for stored content that did not come from the port (a `.cdoc` package a host imports, a document a host's own route loads next to its metadata). The collaboration load, `GET /api/editor/documents/:id`, the tag index and the reference app's import, `.cdoc` export and `GET`/`PUT /api/documents/:id` all read through them; no caller picks a migration itself.

## What the collab server does on load

1. A stored Yjs state without old persisted node names (`composite*`, `section*`) 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`, read as current content (`loadCurrentContent`: old persisted names, the earliest `section*` family and a flat `meta.transcript` migrated) and given block IDs, then persisted immediately.

## Agent texts for host-driven agent chats

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.


# Explore: backlinks, related Blocks and the trail

> What is connected to a Block: the Blocks that point at it, the Blocks related to it, and the chain of Derivations behind it. The explore Feature, the panel, the related route and derivationTrailOf.

The **Explore** panel answers three questions about one Block, all from the [Block index](https://skaile-ai.github.io/forge-editor/guides/workspace), and a fourth from the host's [knowledge graph](https://skaile-ai.github.io/forge-editor/guides/knowledge-graph) when it has one:

<table>
<thead>
  <tr>
    <th>
      Tab
    </th>
    
    <th>
      Question
    </th>
    
    <th>
      Source
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        backlinks
      </code>
    </td>
    
    <td>
      Which Blocks point at this one?
    </td>
    
    <td>
      <code>
        EditorBackend.index.edges(address, 'in')
      </code>
      
       without the <code>
        tag
      </code>
      
       Edges (see <a href="https://skaile-ai.github.io/forge-editor/guides/edges">
        Edges
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        related
      </code>
    </td>
    
    <td>
      Which Blocks are about the same thing?
    </td>
    
    <td>
      <code>
        EditorBackend.index.related(address)
      </code>
      
      , the related route below
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        trail
      </code>
    </td>
    
    <td>
      How was this Block made?
    </td>
    
    <td>
      <code>
        derivationTrailOf(address, index)
      </code>
      
      , the chain of Derivations, the original first
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        knowledge
      </code>
    </td>
    
    <td>
      What does the knowledge graph know about it?
    </td>
    
    <td>
      <code>
        EditorBackend.knowledge.search(title)
      </code>
      
      , then <code>
        neighbours(id)
      </code>
      
       of the node you choose; see below
    </td>
  </tr>
</tbody>
</table>

A tab shows only when the backend can fill it: `backlinks` needs `index.edges`, `related` needs `index.related`, `trail` needs only `index`, `knowledge` needs the `knowledge` capability. A backend without the `index` capability has no Explore panel.

## Enable it

The `explore` Feature is in no level list of the presets. A host that composes with `composeEditor` opts in by id: `interaction: [...INTERACTION.full, 'explore']`, with `explore: { open, show }` in the options. The Feature `requires` the `composites` Feature and the backend capability `index`; over a backend without it, `composeEditor` reports the Feature in `omitted`.

```ts
import { INTERACTION } from '@skaile/forge-editor/presets/compose'
import { composeEditor } from '@skaile/forge-editor/vue/advanced'

const composed = composeEditor({
  content: 'rich',
  interaction: [...INTERACTION.full, 'explore'],
  ai: false,
  backend,
  explore: {
    // What choosing a Block does: open its Document and reveal the Block.
    open: address => workspace.openBlock(address),
  },
})
```

<table>
<thead>
  <tr>
    <th>
      Entry
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @skaile/forge-editor/explore
      </code>
    </td>
    
    <td>
      framework-free: <code>
        exploreFeature
      </code>
      
      , <code>
        exploreFeatureCore
      </code>
      
      , <code>
        createExploreModel
      </code>
      
      , <code>
        exploreTabsOf
      </code>
      
      , <code>
        exploreCountOf
      </code>
      
      , <code>
        exploreTabLabel
      </code>
      
      , <code>
        exploreKindLabel
      </code>
      
      , <code>
        exploreKnowledgeLinksOf
      </code>
      
       and the types
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/explore/vue
      </code>
      
      , <code>
        @skaile/forge-editor/explore/react
      </code>
    </td>
    
    <td>
      <code>
        exploreFeature
      </code>
      
       with the inspector section, plus <code>
        ExplorePanel
      </code>
      
      , <code>
        ExploreSection
      </code>
      
       and <code>
        useExploreModel
      </code>
    </td>
  </tr>
</tbody>
</table>

The Feature adds the section **Verknüpfungen** to the inspector and the details card of a Typed block: the count of each tab and a button to the panel. `show(address)` in the options is where the host places its panel (a sidebar tab, a drawer); without it, the section shows the panel inline under the counts.

## The panel

`ExplorePanel` takes the Block to show (`address`, `null` for none) and `open`, the host's way to a Block. It renders the `ExploreModel` of `createExploreModel({ backend, address, open })`; the Vue and React components render the same model.

The model keeps one state: the selected `tab` and, per tab, `{ status: 'idle' | 'loading' | 'done' | 'failed', items }`. It loads the three lists when the address changes, cancels what a newer Block replaced, and never loads the same Block twice (`refresh()` loads again). A failing list is `failed` and the others stay usable. `open(address)` calls the host and resolves whether it happened; a throwing host is logged, never rethrown.

## The related route

`GET /api/editor/blocks/:documentId/:blockId/related` answers the Blocks most related to one Block as `BlockSearchHit[]` (`documentId`, `blockId`, `title`, `type`), best first, at most ten, the Block itself never. The score of a candidate Block is:

<table>
<thead>
  <tr>
    <th>
      Evidence
    </th>
    
    <th>
      Points
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      each tag it shares with the Block
    </td>
    
    <td>
      2
    </td>
  </tr>
  
  <tr>
    <td>
      each reference target both point at with a chip
    </td>
    
    <td>
      3
    </td>
  </tr>
  
  <tr>
    <td>
      it holds every word of the Block's title
    </td>
    
    <td>
      1
    </td>
  </tr>
</tbody>
</table>

A candidate with score 0 is left out, and equal scores keep the order of the Documents. `relatedBlocks(row, candidates)` and `relatedScore` in `@skaile/forge-editor/core` are the ranking; the route and the in-memory backend both use them.

The route reads only Documents the user may read (the scope of the [Workspace search](https://skaile-ai.github.io/forge-editor/guides/workspace)). It answers `[]` for an unknown Block, `403` when the user may not read the Document of the Block, `400` without a Document or Block ID, `401` without a user and `501` without the `index` port. An adapter with vectors can rank better behind the same route.

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Route
    </td>
    
    <td>
      <code>
        API.blockRelated
      </code>
      
       (port <code>
        index
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Client
    </td>
    
    <td>
      <code>
        EditorBackend.index.related(address, signal?)
      </code>
      
      , optional: a backend without it leaves the <code>
        related
      </code>
      
       tab out
    </td>
  </tr>
</tbody>
</table>

## The trail

`derivationTrailOf(address, source, signal?)` (`@skaile/forge-editor/core`) follows `derivedFrom` of the [Derivation](https://skaile-ai.github.io/forge-editor/guides/composites) through `source.blockGet` (the Document's current content, so `EditorBackend.index` is a `TrailSource`). It answers `TrailStep[]`, the original first and the Block itself last:

```ts
const trail = await derivationTrailOf({ documentId: 'doc', blockId: 'rendition-of-rendition' }, backend.index!)
// [{ address: …'original', method: null, state: null },
//  { address: …'summary',  method: 'ai:summary', state: 'fresh' },
//  { address: …'short',    method: 'ai:rewrite', state: 'stale' }]
```

- It goes at most `TRAIL_MAX_HOPS` (8) Derivations back and never visits a Block twice.
- A Block without a Derivation is a trail of one step with `method: null` and `state: null`.
- A Block made from an uploaded asset ends the trail there; its `method` says how it was made.
- Each step's `state` is the one the row badge shows (`fresh`, `stale`, `edited`, `missing`, `foreign`). An original that is gone gives `missing`; one the user may not read gives `foreign`.
- It answers `[]` for a Block that does not exist and rejects when the Block itself cannot be read.

## The knowledge tab

The `knowledge` tab („Wissensgraph“) is offered only when the backend has the `knowledge` capability (`EditorBackend.knowledge`, served by the `KnowledgeGraph` port; see [Knowledge graph](https://skaile-ai.github.io/forge-editor/guides/knowledge-graph)). It sits after the trail.

- **List.** Per Block the model reads the title through `index.blockGet` and searches the graph for it. `state.query` is that text (`''` for a Block without a title, which searches nothing), `state.knowledge` the hits (`{ id, label, kind, score }`, best first).
- **Neighbours.** `model.focusNode(hit)` loads `knowledge.neighbours(hit.id)` into `state.focus` (`{ node, status, nodes, edges }`); `exploreKnowledgeLinksOf(state.focus)` lists the nodes joined to it with the edge type and its direction. `focusNode(node)` on one of them moves on, `focusNode(null)` returns to the hits. Another Block resets the focus.
- **No Block.** A knowledge node is no Block, so choosing one never calls the host's `open`.


# AI proposals and the export check

> Show unchecked AI results as „KI-Vorschlag“ in the Freigabestatus, list what to look at before a Typed block is exported, and register your own check source.

An AI result is a Typed block that the model wrote. Two things tell that a block still waits for a person: the block has a Derivation made by the model, and nobody has changed or checked it since. The editor derives both facts on every read. Nothing new is stored: the decision of a person is the [Prüfung](https://skaile-ai.github.io/forge-editor/guides/pruefung) (a record pinned to a content hash), and the status is the derived **Freigabestatus**.

## `vorgeschlagen`

A block is an **AI proposal** when all of these hold (`isAiProposal(editor, node)`, `@skaile/forge-editor/composites`):

- its Derivation names the model as author: `method` starts with `ai:` (as `derive` and `composite-fill` write it), or `activity.agent` is set;
- `outputHash` is not empty and equals the SHA-256 of the block's body Markdown now, so nobody has edited the body since the model wrote it.

The Freigabestatus of a block, per kind, gains one value:

<table>
<thead>
  <tr>
    <th>
      Per kind
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        geprueft
      </code>
    </td>
    
    <td>
      a record of this kind exists at the current hash
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        veraltet
      </code>
    </td>
    
    <td>
      records of this kind exist, none at the current hash
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vorgeschlagen
      </code>
    </td>
    
    <td>
      no record of this kind, and the block is an AI proposal
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        offen
      </code>
    </td>
    
    <td>
      no record of this kind, and the block is not an AI proposal
    </td>
  </tr>
</tbody>
</table>

The order of the cases is fixed: a record decides first. An edit of the body ends the proposal, so the kind reads `offen`, not `vorgeschlagen`: the person who edits has taken the text over, and the Prüfung that follows pins their version. A block that is `vorgeschlagen` counts as open in `freigabeOf`: the document is `freigegeben` only after every such block has a Prüfung.

Where it shows:

<table>
<thead>
  <tr>
    <th>
      Where
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Chip after the title
    </td>
    
    <td>
      „KI-Vorschlag“ (warning) while a kind is <code>
        vorgeschlagen
      </code>
      
       and none is <code>
        veraltet
      </code>
      
      ; „Prüfung veraltet“ and „Geprüft“ keep their rules
    </td>
  </tr>
  
  <tr>
    <td>
      Section „Prüfstand“
    </td>
    
    <td>
      the kind line reads „KI-Vorschlag“
    </td>
  </tr>
</tbody>
</table>

Only blocks whose Block type lists the `pruefung` capability have a Freigabestatus. `PruefungKindStatus` is `'geprueft' | 'veraltet' | 'offen' | 'vorgeschlagen'`; a host that switches over it adds the case.

## The export check

Before a Typed block is exported as Markdown the editor looks for what a reader of the file could trip over. `exportIssuesOf(editor, node)` (`@skaile/forge-editor/composites`) returns one `ExportIssue` per finding, for `node` and every Typed block inside it, in document order:

```ts
interface ExportIssue {
  /** The Typed block the finding concerns (for a reference chip, the block that holds the chip). */
  blockId: string
  code: 'ai-unchecked' | 'stale-derived' | 'source-missing' | 'unresolved-reference'
  /** Title of that block. */
  title: string
}
```

<table>
<thead>
  <tr>
    <th>
      Code
    </th>
    
    <th>
      When
    </th>
    
    <th>
      Label
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ai-unchecked
      </code>
    </td>
    
    <td>
      the block is an AI proposal and still waits for a Prüfung (see the check probe below)
    </td>
    
    <td>
      „KI-Vorschlag ungeprüft“
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stale-derived
      </code>
    </td>
    
    <td>
      the block is Derived and its original changed since it was made
    </td>
    
    <td>
      „Quelle geändert“
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source-missing
      </code>
    </td>
    
    <td>
      the block is Derived and its original is gone
    </td>
    
    <td>
      „Quelle fehlt“
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        unresolved-reference
      </code>
    </td>
    
    <td>
      a reference chip points at a Block that does not exist
    </td>
    
    <td>
      „Verweis ohne Ziel“
    </td>
  </tr>
</tbody>
</table>

The check hashes and serialises bodies. It runs when someone exports or opens the inspector section, not for every row.

### The export never waits

The block action „Als Markdown exportieren“ (`document-export`) runs the check first. With one or more findings it shows a warning notice („1 Hinweis“, „n Hinweise“) that points at the inspector, and it exports anyway. The check informs, it never blocks.

### The inspector section

The composites bindings add the section **„Export-Hinweise“** (id `export-check`) to the Typed block inspector and the details card, for every Block type that lists the `export` capability. It lists the findings with their label and the block title, or „Keine Hinweise“. It follows document changes and Prüfung records. `ExportCheckSection` is exported from `@skaile/forge-editor/composites/vue` and `@skaile/forge-editor/composites/react`. A host that builds `compositeFeatureCore` itself passes the component as `CompositesUi.exportCheck`; without it the Feature adds no section (the notice stays).

## Who tells that a block is checked

`ai-unchecked` needs to know whether a Prüfung exists, and the composites Feature does not know the `pruefung` Feature. A Feature that records checks provides a **check probe** for its editor:

```ts
import { provideCheckProbe } from '@skaile/forge-editor/composites'

const unprovide = provideCheckProbe(editor, {
  // true while the block still waits for a check
  awaitsCheck: (_editor, node) => !myChecks.has(node.attrs.id),
  // optional: the answer changed without a document change (the inspector section draws again)
  subscribe: listener => myChecks.subscribe(listener),
})
```

The `pruefung` Feature does this for its model: a block awaits a check while any configured kind is not `geprueft`. A block whose Block type has no kind awaits nothing, so it is never listed as `ai-unchecked`. Without any probe every AI proposal is `ai-unchecked`. `provideCheckProbe` returns the function that removes the probe; call it when the editor goes away.


# Graph: the Edges around a Block

> The graph route that walks the Edges of the Block index in both directions, the walk's limits, the client call, and the @skaile/forge-editor-graph add-on that draws the answer with sigma in Vue and React.

The [Edges](https://skaile-ai.github.io/forge-editor/guides/edges) of the Block index say which Block points at which. The **graph** is their neighbourhood in one answer: the Blocks within a few hops of a start, and the Edges between them. The library answers it (`GET /api/editor/graph`); the add-on `@skaile/forge-editor-graph` draws it.

## The route

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Route
    </td>
    
    <td>
      <code>
        GET /api/editor/graph?documentId=&blockId=&depth=
      </code>
      
       (<code>
        API.graph
      </code>
      
      , port <code>
        index
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      Start
    </td>
    
    <td>
      <code>
        documentId
      </code>
      
       alone: every Block of the Document that has an Edge. With <code>
        blockId
      </code>
      
      : that one Block (kept even without an Edge).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        depth
      </code>
    </td>
    
    <td>
      Hops from the start Blocks, <code>
        1
      </code>
      
       to <code>
        3
      </code>
      
      , default <code>
        2
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Answer
    </td>
    
    <td>
      <code>
        GraphData
      </code>
      
      : <code>
        { nodes: { address, title, type }[], edges: BlockEdge[], truncated: boolean }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Client
    </td>
    
    <td>
      <code>
        EditorBackend.index.graph({ documentId, blockId?, depth?, signal? })
      </code>
      
      , optional: a backend without it leaves it out
    </td>
  </tr>
</tbody>
</table>

The walk follows Edges in **both** directions (what a Block points at and what points at it). It never follows `tag` Edges (a tag is no Block) or Edges to a Block that does not exist, and it never leaves the Documents the user may read: a Block in another Document is a node only when the user may read that Document. Every Edge in `edges` has both its Blocks in `nodes`.

The answer holds at most 500 Blocks. When the walk meets more, it keeps the first ones in the order it found them (start Blocks first) and sets `truncated`. Edges are answered once each, in the order they were met.

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      When
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      no <code>
        documentId
      </code>
      
      , or a <code>
        depth
      </code>
      
       outside 1 to 3
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        401
      </code>
    </td>
    
    <td>
      no user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        403
      </code>
    </td>
    
    <td>
      the user may not read the Document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      <code>
        blockId
      </code>
      
       names no Block of the Document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        501
      </code>
    </td>
    
    <td>
      the host has no <code>
        index
      </code>
      
       port
    </td>
  </tr>
</tbody>
</table>

The walk itself is `walkGraph(seeds, source, { depth, maxNodes?, keepIsolated? })` in `@skaile/forge-editor/core`, over a `GraphSource` (`edges(address, direction)` and `node(address)`). The route reads a `GraphSource` from the `index` port; the memory backend (`createMemoryBackend`) reads one from its projected rows (`graphSourceOfRows`), so a test or a demo draws the same graph.

## The panel

```ts
import { GraphPanel } from '@skaile/forge-editor-graph/vue' // or '@skaile/forge-editor-graph/react'
```

```vue
<GraphPanel :document-id="documentId" :block-id="blockId" :open="openBlock" />
```

<table>
<thead>
  <tr>
    <th>
      Prop
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        documentId
      </code>
    </td>
    
    <td>
      the Document the graph is about
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockId
      </code>
    </td>
    
    <td>
      optional: the graph around this Block; it is drawn larger and in the middle
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        open(address)
      </code>
    </td>
    
    <td>
      what a click on a node does; resolve <code>
        false
      </code>
      
       when it did not happen
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        depth
      </code>
    </td>
    
    <td>
      hops to start with (1 to 3, default 2); the panel has a select for it
    </td>
  </tr>
</tbody>
</table>

**Opening a Block** is the host's job, as for a search hit: in the open Document `editor.commands.revealBlock(blockId)`, else navigate to the Document with `?block=<id>`. The workspace host of this repository does both in `openHit`; the same function serves the graph (`{ documentId, blockId }` is what a `BlockSearchHit` also carries).

The panel draws:

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Node
    </td>
    
    <td>
      one per Block, labelled with its title (else its type); colour by Block type, the focus Block in rose
    </td>
  </tr>
  
  <tr>
    <td>
      Edge colour
    </td>
    
    <td>
      the kind: <code>
        reference
      </code>
      
      , <code>
        derivation
      </code>
      
      , <code>
        embed
      </code>
      
      , and one colour per authored kind (<code>
        supports
      </code>
      
      , <code>
        contradicts
      </code>
      
      , ...), the same one every time
    </td>
  </tr>
  
  <tr>
    <td>
      Edge dashed
    </td>
    
    <td>
      the Edge was written by hand (<code>
        origin: 'meta'
      </code>
      
      , in the inspector's „Kanten“ section); content Edges are solid
    </td>
  </tr>
  
  <tr>
    <td>
      Arrow
    </td>
    
    <td>
      at the Block the Edge points to
    </td>
  </tr>
  
  <tr>
    <td>
      Legend
    </td>
    
    <td>
      the kinds present, as they are drawn
    </td>
  </tr>
  
  <tr>
    <td>
      List
    </td>
    
    <td>
      every node again as a button, for keyboards and screen readers (the canvas is WebGL and has only a label)
    </td>
  </tr>
  
  <tr>
    <td>
      Notice
    </td>
    
    <td>
      <code>
        truncated
      </code>
      
      : more than 500 Blocks, the rest left out
    </td>
  </tr>
</tbody>
</table>

The panel renders nothing when the backend has no `index.graph`.

## Framework-free parts

`@skaile/forge-editor-graph` (no sigma, no DOM):

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        buildGraph(data, { focus?, iterations? })
      </code>
    </td>
    
    <td>
      the graphology <code>
        MultiDirectedGraph
      </code>
      
      : node attributes <code>
        label x y size color documentId blockId blockType focus
      </code>
      
      , Edge attributes <code>
        color size dash gap kind origin
      </code>
      
      ; positions are deterministic (circle, then ForceAtlas2)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        edgeStyleOf({ kind, origin })
      </code>
    </td>
    
    <td>
      <code>
        { color, dashed }
      </code>
      
      : the style table of the panel
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        legendOf(data)
      </code>
    </td>
    
    <td>
      the legend entries
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createGraphPanelModel({ load, open, depth? })
      </code>
    </td>
    
    <td>
      the model both components render: <code>
        state
      </code>
      
       (target, depth, status, last answer), <code>
        setTarget
      </code>
      
      , <code>
        setDepth
      </code>
      
      , <code>
        reload
      </code>
      
      , <code>
        open
      </code>
      
      , <code>
        dispose
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        graphLoaderOf(backend)
      </code>
    </td>
    
    <td>
      <code>
        load
      </code>
      
       for <code>
        createGraphPanelModel
      </code>
      
      , over <code>
        backend.index.graph
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createGraphTranslator(locale, overrides?)
      </code>
    </td>
    
    <td>
      the add-on's own German and English strings
    </td>
  </tr>
</tbody>
</table>

sigma (WebGL) loads when a panel mounts, so importing the package costs nothing and server-side rendering never meets it. The dashed Edges use sigma's `layerDashed` with the Edge attributes `dash` and `gap`: an authored Edge has 8 px dashes and 5 px gaps, every other Edge one dash longer than the canvas and no gap.

## Wiring a host

The add-on needs no feature and no port of its own. The host only mounts the panel where it wants it (a sidebar tab, the Block's details) and passes `open`:

```vue
<script setup lang="ts">
import { GraphPanel } from '@skaile/forge-editor-graph/vue'
</script>

<template>
  <GraphPanel :document-id="documentId" :block-id="blockId" :open="openHit" />
</template>
```

The repository's document pages (the file-drawer layout, `app/layouts/default.vue`) show it behind `NUXT_PUBLIC_ADDONS_GRAPH=1`; the kitchen sink's standalone pages have no workspace index and show no graph.


# Image studio

> The Bild-Studio block: a picture with its description, prompt blocks, references, previous generations and chat. The node, its Markdown form, the state reducers, the images backend port and the dialog for your own store.

The **Bild-Studio** is a block, not a mode. It holds the text that describes the picture (a placeholder until you write one), opens into a dialog with a chat, and keeps every reference image and every previous generation. One of them is **selected** and is the block's picture.

<table>
<thead>
  <tr>
    <th>
      Part
    </th>
    
    <th>
      What it is
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Description
    </td>
    
    <td>
      The text describing the image. Empty shows „Noch keine Beschreibung“ in the block and „Beschreibe das Bild …“ in the dialog.
    </td>
  </tr>
  
  <tr>
    <td>
      Prompt blocks
    </td>
    
    <td>
      A list of style, brand, … texts that <strong>
        the host manages
      </strong>
      
       (label, text, order). Each can be switched on or off per block.
    </td>
  </tr>
  
  <tr>
    <td>
      References
    </td>
    
    <td>
      Uploaded or picked images. An <em>
        active
      </em>
      
       one goes into the next generation.
    </td>
  </tr>
  
  <tr>
    <td>
      Previous generations
    </td>
    
    <td>
      Every image the chat produced. An <em>
        active
      </em>
      
       one goes into the next generation as a reference.
    </td>
  </tr>
  
  <tr>
    <td>
      Selected image
    </td>
    
    <td>
      The one reference or generation that is the block's picture (<code>
        src
      </code>
      
       of the node).
    </td>
  </tr>
  
  <tr>
    <td>
      Chat
    </td>
    
    <td>
      The log of instructions, each with the image it produced or its problem.
    </td>
  </tr>
</tbody>
</table>

Removing a reference or a generation removes it **from this block only**; the host keeps the file. The package never deletes files.

This guide covers the feature, the node and its Markdown form, the state and its reducers, the backend port, and the dialog for a host that owns the state itself. The framework-free and Vue entries ship since 3.5.0, the React entry (dialog and node view) since 3.5.1.

<table>
<thead>
  <tr>
    <th>
      Entry
    </th>
    
    <th>
      Contents
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @skaile/forge-editor/image-studio/vue
      </code>
    </td>
    
    <td>
      <code>
        imageStudioFeature()
      </code>
      
      , <code>
        ImageStudioDialog
      </code>
      
      , <code>
        createImageStudioNodeStore
      </code>
      
      , the state and reducers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/image-studio/react
      </code>
    </td>
    
    <td>
      <code>
        imageStudioFeature()
      </code>
      
      , <code>
        ImageStudioDialog
      </code>
      
      , <code>
        useImageStudioNodeStore
      </code>
      
      , <code>
        ImageStudioReactStore
      </code>
      
      , the state and reducers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/image-studio
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        imageStudioFeatureCore
      </code>
      
      , the state and reducers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/image-studio/schema
      </code>
    </td>
    
    <td>
      Vue-free <code>
        imageStudioSchemaExtensions()
      </code>
      
       and <code>
        ImageStudioNode
      </code>
      
       for servers
    </td>
  </tr>
</tbody>
</table>

## Enabling it

Add `imageStudioFeature()` to `defineEditor({ features })` next to the core features. The feature has no other dependency and imports no other feature.

```ts
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { imageStudioFeature } from '@skaile/forge-editor/image-studio/vue'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), imageStudioFeature()] })
```

On the React surface (shadcn) import `imageStudioFeature` from `@skaile/forge-editor/image-studio/react` instead; everything else, the block, the Markdown form, the backend port and the behaviour described below, is the same.

The feature adds:

- the `imageStudio` block (an atom, draggable; it revokes the text abilities, so no marks or text commands apply inside it),
- the `/` entry „Bild-Studio“ (command id `imageStudio`, slash id `bild-studio`), offered where the caret has the ability `insert.imageStudio` (`ABILITY.imageStudio`), and the command `insertImageStudio(attrs?)`,
- the block action `image-studio.open` („Im Bild-Studio öffnen“, in the block menu and on the block's chrome), which asks the block's view to open the dialog. The view also opens it on double-click and from its „Bild-Studio öffnen“ button.

A server that validates or stores documents containing the node builds its schema from the schema entry:

```ts
import { getSchema } from '@tiptap/core'
import { coreSchemaExtensions } from '@skaile/forge-editor/core/schema'
import { imageStudioSchemaExtensions } from '@skaile/forge-editor/image-studio/schema'

const schema = getSchema([...coreSchemaExtensions(), ...imageStudioSchemaExtensions()])
```

## The node and its Markdown form

The node `imageStudio` has the attributes `src` (the url of the selected image, `null` without one), `alt` and `studio` (the whole `ImageStudioState`). `setImageStudioState(pos, state)` replaces the state of the block at `pos` in one transaction and sets `src` from the selected image, so undo takes both back together.

<table>
<thead>
  <tr>
    <th>
      Form
    </th>
    
    <th>
      Shape
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      HTML
    </td>
    
    <td>
      <code>
        <img data-image-studio src alt data-studio="{json}">
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Markdown
    </td>
    
    <td>
      <code>
        [Bild-Studio: <alt>](<src>) <!-- {"studio": …} -->
      </code>
      
       on its own line
    </td>
  </tr>
</tbody>
</table>

```md
[Bild-Studio: Segelboot im Abendlicht](/files/a1.png) <!-- {"studio":{"description":"Ein Segelboot im Abendlicht","promptBlockIds":["style"],"references":[],"generations":[{"id":"a1","url":"/files/a1.png","title":"Version 1","active":false}],"selected":"a1","turns":[{"id":"t1","instruction":"","imageId":"a1","createdAt":"2026-10-21T09:00:00.000Z"}]}} -->
```

The label is the literal `Bild-Studio` in every UI language, because parsing looks for it. The comment is left out while the studio is empty (no description, prompt block, image or turn). Reading a document normalises the state: a missing or mistyped field falls back to its empty value, an entry without an `id` is dropped and a `selected` that points at no image becomes `null`. A valid state round-trips unchanged.

## The state and its reducers

The state is plain JSON and knows nothing about the host: image ids are opaque (a host uses its own asset ids).

```ts
interface ImageStudioImage { id: string, url: string, title: string, active: boolean }
interface ImageStudioTurn { id: string, instruction: string, imageId: string | null, createdAt: string, problem?: string }
interface ImageStudioState {
  description: string // '' shows the placeholder
  promptBlockIds: string[] // active prompt blocks, by the host's ids
  references: ImageStudioImage[]
  generations: ImageStudioImage[]
  selected: string | null // id of the generation (or reference) that is the block's image
  turns: ImageStudioTurn[] // the chat log: instruction → generation
}
```

`EMPTY_IMAGE_STUDIO_STATE` is the state of a new block. The reducers are pure: each returns a new state and never touches its argument.

<table>
<thead>
  <tr>
    <th>
      Reducer
    </th>
    
    <th>
      Effect
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        setDescription(state, text)
      </code>
    </td>
    
    <td>
      Replaces the description.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        togglePromptBlock(state, id)
      </code>
    </td>
    
    <td>
      Adds the prompt block to the active ones, or removes it when it is active.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        toggleImage(state, id)
      </code>
    </td>
    
    <td>
      Flips <code>
        active
      </code>
      
       of the reference or generation; an unknown id changes nothing.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        select(state, id | null)
      </code>
    </td>
    
    <td>
      Makes the image the block's picture; <code>
        null
      </code>
      
       clears the choice; an unknown id changes nothing.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        removeImage(state, id)
      </code>
    </td>
    
    <td>
      Drops the image from <code>
        references
      </code>
      
       and <code>
        generations
      </code>
      
      ; clears <code>
        selected
      </code>
      
       when it was selected. The chat log keeps its turns.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        addReference(state, image)
      </code>
    </td>
    
    <td>
      Appends a reference; one with the same id is replaced where it stands.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        adoptImage(state, image)
      </code>
    </td>
    
    <td>
      Makes the image the block's picture: unchanged when it already is; an image the block holds is only selected; any other is added as a reference first.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        addGeneration(state, image, turn)
      </code>
    </td>
    
    <td>
      Appends the generation and its turn (pointing at the image) and <strong>
        selects it
      </strong>
      
      : a chat generate means „this is the picture now“; an earlier one can be selected again.
    </td>
  </tr>
</tbody>
</table>

Helpers: `selectedImage(state)` (the selected image, if the selection still points at one), `isEmptyImageStudioState(state)`, `normalizeImageStudioState(value)` (for stored JSON from outside). All of them, with the types, are exported from `@skaile/forge-editor/image-studio` and `/image-studio/vue`.

## The backend port

Generation, uploads and the list of prompt blocks go through the `images` capability of the [`EditorBackend`](https://skaile-ai.github.io/forge-editor/guides/editor-ports#capability-probe), the last entry of `BACKEND_CAPABILITIES`:

```ts
interface ImagesPort { // EditorBackend['images']
  promptBlocks: () => Promise<ImageStudioPromptBlock[]> // { id, label, text }, in the host's order
  generate: (body: ImageStudioGenerateBody, signal?: AbortSignal) => Promise<ImageStudioImage> // resolves with active: false
  upload: (documentId: string, file: File) => Promise<ImageStudioImage> // resolves with active: true
}

interface ImageStudioGenerateBody {
  description: string
  instruction: string // '' generates from the description alone
  promptBlockIds: string[] // the active prompt blocks
  referenceUrls: string[] // urls of the active references and generations
}
```

The HTTP backend (`createHttpBackend()`) maps the three members to routes. With `probe: true` it drops `images` when the server does not list the capability.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Route
    </th>
    
    <th>
      Body
    </th>
    
    <th>
      Answer
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        promptBlocks()
      </code>
    </td>
    
    <td>
      <code>
        GET /api/editor/images/prompt-blocks
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      <code>
        ImageStudioPromptBlock[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        generate(body, signal)
      </code>
    </td>
    
    <td>
      <code>
        POST /api/editor/images/generate
      </code>
    </td>
    
    <td>
      JSON <code>
        ImageStudioGenerateBody
      </code>
      
       (<code>
        description
      </code>
      
       ≤ 10 000, <code>
        instruction
      </code>
      
       ≤ 4 000 characters, ≤ 50 <code>
        promptBlockIds
      </code>
      
      , ≤ 20 <code>
        referenceUrls
      </code>
      
      )
    </td>
    
    <td>
      <code>
        ImageStudioImage
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        upload(documentId, file)
      </code>
    </td>
    
    <td>
      <code>
        POST /api/editor/images/upload
      </code>
    </td>
    
    <td>
      multipart: <code>
        documentId
      </code>
      
       (a document id or <code>
        scratch
      </code>
      
      ) and <code>
        file
      </code>
    </td>
    
    <td>
      <code>
        ImageStudioImage
      </code>
    </td>
  </tr>
</tbody>
</table>

The routes authenticate like every other editor route. `400` answers a malformed body, a bad `documentId` or a missing file; `413` a file over the image limit (`MAX_MEDIA_BYTES.image`); `415` a file that is no image; `501` any of the three when the server has no `images` port.

The memory backend (`createMemoryBackend()`) has **no** `images` member: image generation needs a server that holds the model key and stores the files. In such a client the block still works as a picture holder, but opening the studio (the block action, double-click or the button) shows the notice „Bildgenerierung ist nicht eingerichtet“ instead of the dialog.

### The server port

On the server the host supplies `EditorPorts.images`, an `ImageProvider`. The package owns authentication, validation and the routes; the provider owns the prompt, the model and the storage. `user` is what `identity.authenticate` returned.

```ts
import { provideEditorServer } from '@skaile/forge-editor/server/nitro'

provideEditorServer({
  ports: {
    identity,
    documents,
    images: {
      // The managed list (label, text, order), e.g. rows of your own table.
      promptBlocks: user => listPromptBlocks(user),
      // Build the prompt from description + instruction + the texts of body.promptBlockIds,
      // pass body.referenceUrls to the model, store the result and return it with active: false.
      generate: async (body, user) => {
        const file = await runImageModel(buildPrompt(body), body.referenceUrls)
        const stored = await storeImage(file, user)
        return { id: stored.id, url: stored.url, title: stored.title, active: false }
      },
      // The route has already checked documentId, size and that the file is an image.
      upload: async (documentId, file, user) => {
        const stored = await storeUpload(documentId, file, user)
        return { id: stored.id, url: stored.url, title: stored.title, active: true }
      },
    },
  },
})
```

`images` maps to the capability `images` (`PORT_CAPABILITY`), so `serverCapabilities(ports)` and `GET /api/editor/capabilities` list it only when the port is given. Without it the three routes answer `501`. The port is described with the others in [EditorPorts](https://skaile-ai.github.io/forge-editor/guides/editor-ports).

## The dialog and your own store

`ImageStudioDialog` is exported for hosts; the block's view uses the same component. The Vue dialog is a modal (`useUiKit().Modal`), the React one a shadcn `Dialog`; both have three columns: description and prompt blocks on the left (a switch per prompt block, its text underneath), references and previous generations in the middle, the selected image and the chat on the right. They use the same texts (`imageStudio.*`).

<table>
<thead>
  <tr>
    <th>
      Prop / event
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        open: boolean
      </code>
      
       (<code>
        v-model:open
      </code>
      
      ; React: <code>
        open
      </code>
      
       and <code>
        onOpenChange(open)
      </code>
      
      )
    </td>
    
    <td>
      Whether the dialog is shown; Vue emits <code>
        update:open
      </code>
      
      , React calls <code>
        onOpenChange
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        store: ImageStudioStore
      </code>
      
       (React: <code>
        ImageStudioReactStore
      </code>
      
      )
    </td>
    
    <td>
      What the dialog drives, see below.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        title?: string
      </code>
    </td>
    
    <td>
      Dialog title; default „Bild-Studio“.
    </td>
  </tr>
</tbody>
</table>

In the middle column a click on a tile toggles `active` (a ring marks it), „Als Bild verwenden“ selects it and „Entfernen“ removes it from the block. A reference is added by the upload button or by dropping files on the zone. In the chat, `Enter` sends the instruction, `Shift+Enter` adds a line, and „Erzeugen“ is disabled while a generation runs. Closing the dialog aborts a running generation; an aborted generation adds nothing, a failed one adds a turn with `problem` set. The description is committed 500 ms after the last keystroke and at once on blur, on „Erzeugen“ and on close, so a prompt is never built from a stale text.

The dialog applies the reducers itself and hands every resulting state to `store.update`. The store only persists, generates and uploads:

```ts
interface ImageStudioStore {
  readonly state: Ref<ImageStudioState>
  readonly promptBlocks: Ref<readonly ImageStudioPromptBlock[]> // the managed list, loaded by the host
  update: (next: ImageStudioState) => void // after a reducer; the host persists it
  generate: (instruction: string, signal: AbortSignal) => Promise<ImageStudioImage> // the host builds the prompt
  upload: (file: File) => Promise<ImageStudioImage> // the dialog then calls addReference
  readonly problem: Ref<string | undefined> // a problem of the store itself, shown as a notice
  readonly library?: ImageStudioLibrary // the host's gallery; a «Galerie» tab appears only when set
  readonly placeholderUrl?: string // shown in the preview while no image is selected
}
```

`generate` reads the description, the active prompt blocks and the active images from `state` and returns **one** image; the dialog calls `addGeneration` with it. Its store methods never write `state` themselves.

For a studio inside the editor, `createImageStudioNodeStore({ editor, getPos, backend, documentId })` builds the store of one `imageStudio` node: `state` follows the node's `studio` attribute (so undo, collaboration and other writers show), `update` writes it back with `setImageStudioState`, and the rest goes to `backend.images`. Call its `dispose()` when the view goes.

A host that keeps the state **outside the document** (a sidecar next to the block, a database row) writes its own store and uses the dialog directly:

```vue
<script setup lang="ts">
import { ImageStudioDialog, type ImageStudioStore, normalizeImageStudioState } from '@skaile/forge-editor/image-studio/vue'
import { ref, shallowRef } from 'vue'

const open = ref(false)

// The block's studio state lives in the host's own record.
const state = shallowRef(normalizeImageStudioState(record.studio))
const promptBlocks = shallowRef(await fetchPromptBlocks())
const problem = shallowRef<string>()

const store: ImageStudioStore = {
  state,
  promptBlocks,
  problem,
  update(next) {
    state.value = next
    void saveStudio(record.id, next) // persist; also mirror the selected image into the block here
  },
  async generate(instruction, signal) {
    const { description, promptBlockIds, references, generations } = state.value
    const referenceIds = [...references, ...generations].filter(image => image.active).map(image => image.id)
    return await requestImage({ description, instruction, promptBlockIds, referenceIds }, signal)
  },
  upload: file => uploadReference(file),
}
</script>

<template>
  <UButton label="Bild-Studio" @click="open = true" />
  <ImageStudioDialog v-model:open="open" :store="store" />
</template>
```

### React

The React dialog takes the same contract with plain values instead of refs, `ImageStudioReactStore`: `state`, `promptBlocks` and `problem` are values, `update`, `generate` and `upload` are the same functions. The host re-renders the dialog with the new `state` after `update`; until `state` changes the dialog keeps building on the state it handed to `update`, so several uploads that finish together all land. The identity of `update` is the identity of the store: keep it stable while the dialog edits one image (`useCallback`), and hand the open dialog another `update` only with another image, so a pending description edit is committed to the image it was typed for. A host that keeps the state in a record writes it with `useState`:

```tsx
import { ImageStudioDialog, type ImageStudioPromptBlock, type ImageStudioReactStore, type ImageStudioState, normalizeImageStudioState } from '@skaile/forge-editor/image-studio/react'
import { useCallback, useMemo, useState } from 'react'

function StudioButton({ record, promptBlocks }: { record: { id: string, studio: unknown }, promptBlocks: ImageStudioPromptBlock[] }) {
  const [open, setOpen] = useState(false)
  const [state, setState] = useState(() => normalizeImageStudioState(record.studio))
  // Stable per record: a new `update` tells the dialog that another image is open.
  const update = useCallback((next: ImageStudioState) => {
    setState(next)
    void saveStudio(record.id, next) // persist; also mirror the selected image into the block here
  }, [record.id])
  const store: ImageStudioReactStore = useMemo(() => ({
    state,
    promptBlocks,
    problem: undefined,
    update,
    async generate(instruction, signal) {
      const { description, promptBlockIds, references, generations } = state
      const referenceIds = [...references, ...generations].filter(image => image.active).map(image => image.id)
      return await requestImage({ description, instruction, promptBlockIds, referenceIds }, signal)
    },
    upload: file => uploadReference(file),
  }), [state, promptBlocks, update])
  return (
    <>
      <button onClick={() => setOpen(true)}>Bild-Studio</button>
      <ImageStudioDialog open={open} onOpenChange={setOpen} store={store} />
    </>
  )
}
```

For the node's own store use `useImageStudioNodeStore({ editor, getPos, backend, documentId })`, which wraps `createImageStudioNodeCore` (the framework-free observable the Vue store wraps as well: `get()`, `subscribe(listener)`, `update`, `generate`, `upload`, `dispose()`). It returns `undefined` on the first render, because the core is built in an effect; render the dialog once there is a store.

Image `id`s can be the host's own ids (an asset id, say) and `url` any url the page can show; the library only compares ids. The host decides what a removed image means for its files, and whether `selected` is also written to wherever the block's picture is read from.

### The gallery tab

With `store.library` the middle column gets two tabs: „Dieser Block“ (references and previous generations, as above) and „Galerie“ (the host's images). The tab re-reads `facets()` each time it opens, lists with the first option of every facet and an empty search, and lists again after a facet change and 300 ms after the last keystroke of the search; a newer read aborts the running one. A tile offers „Als Bild verwenden“ (`adoptImage`), „Als Referenz“ (`addReference`, disabled once the block holds the image), and, when the host gives `rename` / `remove`, a pencil (Enter commits, Escape or blur cancels) and a trash button. A refused `remove` shows the error's message in the tab and keeps the tile; a granted one also drops the image from the block when it holds it.

```ts
interface ImageStudioLibrary {
  facets: () => readonly ImageStudioLibraryFacet[] // { id, label, options: { value, label }[] }; the first option is the default
  list: (query: ImageStudioLibraryQuery, signal: AbortSignal) => Promise<readonly ImageStudioLibraryItem[]> // query: { search, facets: { [facetId]: value } }; item: an ImageStudioImage plus an optional subtitle
  rename?: (id: string, title: string) => Promise<ImageStudioLibraryItem>
  remove?: (id: string) => Promise<void> // reject with an Error whose message the dialog shows
}
```

`placeholderUrl` replaces the text „Noch kein Bild“ in the preview with that picture while no image is selected. The node store sets neither member.

## See also

- [Public exports](https://skaile-ai.github.io/forge-editor/reference/exports) lists the three entries.
- [EditorPorts](https://skaile-ai.github.io/forge-editor/guides/editor-ports) explains the ports, the capability probe and the capability classes.
- [Media, mentions and transcript](https://skaile-ai.github.io/forge-editor/guides/media-mentions-transcript) covers the plain image block and uploads through the `assets` port.


# Importers: what a dropped file becomes

> The importer registry of the feature contract: Importer and ImportPlan, planImport, the Markdown, subtitle and BibTeX importers of the media feature, and how composite-media wraps the plan.

Dropping, pasting or picking a file runs it through the **importer registry**. A feature contributes `importers: Importer[]`; the editor asks them, in feature order, which one takes the file. The result is an `ImportPlan`: the blocks to insert, plus facts about the file as a whole. `fileImport` (`@skaile/forge-editor/media`) inserts the blocks at the drop position and shows the plan's warnings as one notice.

```ts
import type { Importer } from '@skaile/forge-editor/core'

const csvImporter: Importer = {
  id: 'csv',
  accepts: ['.csv', 'text/csv'],
  async plan(editor, file, text) {
    // `text` is the file's text for a text file of at most MAX_TEXT_BYTES, else null
    return { blocks: [{ type: 'paragraph', content: [{ type: 'text', text: text ?? '' }] }] }
  },
}

export const csvFeature = (): EditorFeature<never> => ({ id: 'csv', dimension: 'content', importers: [csvImporter] })
```

## Which importer takes a file

`accepts` lists MIME types (`text/markdown`, `audio/*`), extensions with their dot (`.vtt`, not case-sensitive) or `*`.

- **Specific entries.** The first importer in feature order with a matching MIME type or extension plans the file. A file without a match goes to the **fallback**: text and Markdown files are parsed through the block pipeline (parse, normalize, segment, structure), everything else is uploaded as a media or file block.
- **Wrapping importers (*).** An importer that accepts `*` takes every file but plans last. It receives the plan made so far as `base` and returns the final plan. `composite-media` is one: it puts the blocks of every file into one Typed block.
- **Text.** An importer that matched by extension or a `text/*` type gets the file's text. Files above `MAX_TEXT_BYTES` (2 MB) are not read; such a file goes to the fallback.

Importer ids must be unique: `defineEditor` throws for a second `importers` entry with the same id. Importers are additive, so two features may both contribute some. `planImport(editor, file, fallback)` is the framework-free entry; `importersOf(features)` lists the contributions.

## The importers of the media feature

The `media` feature contributes three importers (`FILE_IMPORTERS`, in this order).

<table>
<thead>
  <tr>
    <th>
      Importer
    </th>
    
    <th>
      Takes
    </th>
    
    <th>
      Plan
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        markdown
      </code>
    </td>
    
    <td>
      <code>
        .md
      </code>
      
      , <code>
        .markdown
      </code>
      
      , <code>
        text/markdown
      </code>
    </td>
    
    <td>
      The body parsed through the block pipeline. The frontmatter keys become <code>
        properties
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        subtitle
      </code>
    </td>
    
    <td>
      <code>
        .vtt
      </code>
      
      , <code>
        .srt
      </code>
      
      , <code>
        text/vtt
      </code>
    </td>
    
    <td>
      One Typed block of Block type <code>
        rendition
      </code>
      
      , titled with the file name, holding one <code>
        transcriptSegment
      </code>
      
       per cue (<code>
        start
      </code>
      
      , <code>
        end
      </code>
      
       in seconds, <code>
        speaker
      </code>
      
       from a WebVTT <code>
        <v Name>
      </code>
      
       tag)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bibtex
      </code>
    </td>
    
    <td>
      <code>
        .bib
      </code>
      
      , <code>
        application/x-bibtex
      </code>
    </td>
    
    <td>
      One Typed block per entry: <code>
        paper
      </code>
      
      , or <code>
        book
      </code>
      
       for CSL <code>
        book
      </code>
      
      . The entry is the CSL record in <code>
        meta.bib
      </code>
      
       (<code>
        doi
      </code>
      
       / <code>
        isbn
      </code>
      
       too)
    </td>
  </tr>
</tbody>
</table>

Without the `composites` feature there are no Typed blocks: the subtitle importer then inserts the segments as they are (paragraphs `Sprecher: Text` without the transcript feature), the BibTeX importer one citation paragraph per entry.

**Frontmatter** is read by `parseFrontmatter` with a small subset: scalars (quoted strings, numbers, `true`, `false`, `null`), flow lists (`tags: [a, "b, c"]`) and block lists (`- item` lines). Nested maps and multi-line scalars are skipped with a warning; the body is never affected. `properties` are not inserted by themselves: a wrapping importer merges them into the `meta` of the Typed block it creates, after which the file's own import facts (`filename`, `mimeType`, `size`, `importedAt`) are set and never replaced.

**Subtitles** (`parseSubtitles`): cue blocks are separated by blank lines; identifier lines (the numbers of SubRip), `NOTE`, `STYLE` and `REGION` blocks and cue settings are ignored, inline tags are dropped, cue lines are joined by a space. Times are `hh:mm:ss.mmm`, `mm:ss.mmm` or `hh:mm:ss,mmm` (`cueTime`). A block without a valid time range is skipped and reported.

**BibTeX** (`parseBibtex`): `@type{key, field = {value} | "value" | number | macro # …}`. `author` and `editor` split on `and` outside braces (`Family, Given`, `Given Family` or a braced institution), `year` and `month` (number or English name) or `date` become `issued`, `@string` macros are resolved, `@comment` and `@preamble` are skipped. LaTeX accent commands are not translated. An entry without key or title is skipped with a warning. The block's title is the entry's title; the CSL record carries no title.

## composite-media

`compositeMediaFeature()` contributes the wrapping importer. For every planned file it creates one Typed block of the Block type whose `import` capability takes the file's media, titled with the file name without its extension. The plan's blocks become its body, the plan's `properties` and the file's facts its `meta`. Without a Block type that takes the file, the plan is inserted as it is. So it is when the plan is already Typed blocks and carries no `properties`: a dropped `.vtt` stays the one transcript block and a `.bib` its paper and book blocks, none of them wrapped in a `document` block. Markdown files (frontmatter `properties`) and plain media or text files keep one wrapper per file.

The wrapper needs a plan to wrap; it never reads files itself. It replaces the earlier `wrapImport` pipeline hook, which allowed one contributor: any number of features can now contribute importers, and `wrapImport` no longer exists.

## Duplicates

Before a dropped file is inserted, the Block index is asked whether the workspace holds it already (`backend.index.importCheck`, route `POST /api/editor/import/check`, body `{ sha256?, doi?, title?, type? }`, at least one of the first three). The answer is a list of `ImportMatch` (`address`, `title`, `reason`), at most ten, over the Documents the user may read:

<table>
<thead>
  <tr>
    <th>
      Reason
    </th>
    
    <th>
      A Block matches when
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        sha256
      </code>
    </td>
    
    <td>
      its file has the same SHA-256 (<code>
        properties.sha256
      </code>
      
      : the <code>
        hash
      </code>
      
       of an uploaded media or file block, or of the first body block of a Typed block that wraps one). An authored <code>
        sha256
      </code>
      
       property wins
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        doi
      </code>
    </td>
    
    <td>
      its bibliographic record (<code>
        properties.bib.DOI
      </code>
      
      , else <code>
        properties.doi
      </code>
      
      ) has the same DOI; case, <code>
        doi:
      </code>
      
       and the <code>
        doi.org
      </code>
      
       URL do not count
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        title
      </code>
    </td>
    
    <td>
      its title has the same words in the same order (<code>
        rankBlockRows
      </code>
      
       ranks, <code>
        titleMatchOf
      </code>
      
       decides); with <code>
        type
      </code>
      
      , the same Block type too
    </td>
  </tr>
</tbody>
</table>

A Block is named once, by the first reason in that order. Of the Blocks of one Document that match for the same reason only the titled ones are kept: a Typed block that wraps an uploaded file and the image inside it carry the same hash, and the Typed block is the one to point at.

The file import (`fileImport`; `useFileImport()`, the `media` feature) asks in two steps. A file that is not text is hashed in the browser first (SHA-256 through WebCrypto), so a file the workspace holds is not uploaded a second time unless the user insists. Otherwise the file is planned and the check asks for every Typed block of the plan (at most 25) with its title, Block type and DOI (`meta.bib.DOI`, else `meta.doi`). A hit is not inserted. A notice offers two answers:

- **Vorhandenen Block referenzieren** inserts a reference chip to the existing Block instead. Of a plan only the duplicate blocks are replaced; a chip into the open Document names no Document.
- **Trotzdem einfügen** inserts the file or the whole plan as it would have been.

The notice stays 30 seconds; closing it skips the file. The drop position is anchored meanwhile, so the answer lands where the file was dropped. A check that fails, a missing `index` port (a backend without Block index) or an editor without reference chips is no duplicate: the file is inserted at once and nothing is asked. The memory backend answers from its own documents, the HTTP backend through the route. `Notice.secondaryAction` is the second button of the notice (Nuxt UI actions, Sonner cancel button).

## Not included

Templates for new Documents are a separate guide (`35.templates`). Frontmatter outside the subset above is not imported.


# Index on Postgres: typos, meaning and SQL pushdown

> The @skaile/forge-editor-index-pg add-on: trigram title search, a vector table kept current on replace, nearest and related Blocks, query pushdown, and the Embedder port with its OpenAI-compatible adapter.

The library's drizzle [Block index](https://skaile-ai.github.io/forge-editor/guides/editor-ports) already runs `search` in Postgres on `tsvector`s. `@skaile/forge-editor-index-pg` wraps it (`createPgBlockIndex`) and adds three things a plain drizzle index lacks. Nothing changes for a host that does not use it.

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Where
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Typo search
    </td>
    
    <td>
      <code>
        search
      </code>
      
       finds a title that holds a word <em>
        similar
      </em>
      
       to each query word (<code>
        pg_trgm
      </code>
      
      ), after the hits for the words as written
    </td>
    
    <td>
      add-on
    </td>
  </tr>
  
  <tr>
    <td>
      Vectors
    </td>
    
    <td>
      <code>
        replace
      </code>
      
       embeds the Blocks whose text changed into <code>
        editor_block_vectors
      </code>
      
       (pgvector); <code>
        nearest
      </code>
      
       and <code>
        related
      </code>
      
       answer by cosine similarity
    </td>
    
    <td>
      add-on + <code>
        Embedder
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      Query pushdown
    </td>
    
    <td>
      <code>
        query
      </code>
      
       filters <code>
        eq
      </code>
      
      , <code>
        ne
      </code>
      
      , <code>
        isEmpty
      </code>
      
      , <code>
        isNotEmpty
      </code>
      
       and <code>
        hasAny
      </code>
      
       on Properties in SQL
    </td>
    
    <td>
      add-on
    </td>
  </tr>
  
  <tr>
    <td>
      Search by meaning
    </td>
    
    <td>
      the search route fuses the keyword hits with <code>
        nearest
      </code>
      
       (reciprocal rank fusion)
    </td>
    
    <td>
      library
    </td>
  </tr>
</tbody>
</table>

## The `Embedder` port

`EditorPorts.embeddings` (`@skaile/forge-editor/server`) turns text into vectors. Capability id `embeddings`; the server lists it in `GET /api/editor/capabilities`, a backend never has it (the client never embeds, the route does).

```ts
interface Embedder {
  /** Names the model; a vector is comparable only with vectors of the same model. */
  model: string
  /** The length of its vectors. */
  dim: number
  embed(texts: string[], user?: object): Promise<number[][]>
}
```

`createOpenAiEmbedder({ endpoint, model, dim, apiKey })` from `@skaile/forge-editor/adapters/embeddings` calls an OpenAI-compatible `POST <endpoint>/embeddings`. The call goes from the server, the key never reaches a page. `OPENAI_EMBEDDING_DIMENSIONS` lists the vector lengths of OpenAI's models; a model it does not list needs its `dim` given.

## Search by meaning

When the host passes `ports.embeddings` and the index has `nearest`, `GET /api/editor/search?q=` runs the keyword search, embeds the query, asks the index for the nearest Blocks and fuses both lists with `fuseRanks` (reciprocal rank fusion: a hit at rank `r` adds `weight / (60 + r)`; keyword 0.7, vector 0.3). A note titled "Hund" then answers the query "Haustier", which shares no word with it. When the embedder fails the route logs it and answers the keyword hits: search never stops working with the endpoint.

`GET /api/editor/blocks/:documentId/:blockId/related` (the [Explore](https://skaile-ai.github.io/forge-editor/guides/explore) tab) prefers `index.related` when the index has it, the Blocks nearest to the Block's own vector, and answers the shared-tags heuristic otherwise, or when the Block has no vector yet.

## Set up

```ts
import { createOpenAiEmbedder } from '@skaile/forge-editor/adapters/embeddings'
import { bootstrapPgBlockIndex, createPgBlockIndex, pgBlockIndexTables } from '@skaile/forge-editor-index-pg'

const embedder = createOpenAiEmbedder({ endpoint: 'https://api.openai.com/v1', model: 'text-embedding-3-small', dim: 1536, apiKey })
await bootstrapPgBlockIndex(db, { dim: embedder.dim })
const index = createPgBlockIndex({ db, tables: pgBlockIndexTables(embedder.dim), embedder })
// installEditorServer({ ports: { index, embeddings: embedder, ... } })
```

- `db` is any drizzle Postgres database whose server has `pg_trgm` and `vector`. On PGlite load them: `new PGlite({ extensions: { pg_trgm, vector } })` with `pg_trgm` from `@electric-sql/pglite/contrib/pg_trgm` and `vector` from `@electric-sql/pglite-pgvector`.
- A host with migrations exports `pgBlockIndexTables(dim)` from its drizzle schema and adds `pgBlockIndexStatements(dim)` (the extensions, the trigram index, the vector table) to a migration. `bootstrapPgBlockIndex` is the same without migrations.
- The vector table has the length `dim` of the embedder. Changing the model to another length needs a new table; changing it to one of the same length makes `replace` embed everything again (the model is stored with each vector).
- Without `embedder`, `createPgBlockIndex` still gives typo search and pushdown, and has no `nearest` or `related`.

## What `replace` does with vectors

Embedding is a network call, so `replace` returns before it is done and `index.settled()` waits for it. Per Document one job runs at a time, always over the latest rows; a second `replace` meanwhile replaces the rows the job is yet to see.

- A Block whose title and text (cut at 6000 characters) hash like its stored vector, with the same model, costs nothing.
- A changed Block is embedded in batches of 64, and each batch is stored when it returns, so a failing endpoint keeps what was made. The failure is logged; the rows stay; the next `replace` of the Document, or the rebuild of the index at server start, makes the vectors that are missing.
- A Block that vanished or has neither title nor text loses its vector; `remove(documentId)` drops the Document's vectors.

## Query pushdown

`query` keeps the contract of the memory adapter: the same rows in the same order. The add-on narrows the candidate rows in SQL, as a pre-filter, and `evaluateQuery` runs over the rows that are left for the final answer (the filter again, sorting, grouping, aggregates, paging, issues), so SQL can only drop rows the filter would drop anyway. A condition is pushed when its SQL is the very test of the Property kind: `eq`, `ne`, `isEmpty`, `isNotEmpty` and `hasAny` on text, textarea, url, select, status and reference Properties, `eq` and `ne` on checkboxes, `hasAny` on multiselects, and the same on the pseudo-fields (`$title`, `$tags`, `$type`, `$id`, `$doc`, `$basket`). An `and` pushes the conditions it can and leaves the others to JS; an `or` is pushed only when every branch is. Dates, numbers, `contains` and the ordering operators, a query without a Block type, and a query that names a key no definition declares go through the drizzle adapter's JS path unchanged. A row whose JSON Postgres cannot read (U+0000) falls back the same way. The contract test runs every case against the memory adapter and the pg adapter on PGlite.

## In the host app

`NUXT_BLOCK_INDEX=pg-vector` starts the index on PGlite with the add-on (`server/utils/block-index.ts`). With `OPENAI_API_KEY` set the host also creates the embedder (`server/utils/addons.ts`: `OPENAI_EMBEDDING_MODEL`, default `text-embedding-3-small`; `OPENAI_EMBEDDING_DIMENSIONS` for a model OpenAI does not list; `OPENAI_BASE_URL` for another OpenAI-compatible endpoint) and passes it to the index and to `ports.embeddings`. Without the key the index has typo search only. PGlite lives in memory: the server rebuilds the index, and with it the vectors, from the Documents on every start, which costs one embedding call per 64 changed Blocks; a host with many Documents uses a Postgres server instead.


# Knowledge graph: sources and concepts beside the Documents

> The read-only KnowledgeGraph port with its search and neighbours routes, the Wissensgraph tab of the Explore panel, the memory adapter for tests and the @skaile/forge-editor-kgs add-on over the KGS SDK.

A **knowledge graph** is a graph the host keeps outside the Documents: ingested sources, concepts and notes with typed edges between them. The editor does not store it and does not write to it. The host passes one `KnowledgeGraph`; the editor adds two read routes, a client call and the **Wissensgraph** tab of the [Explore panel](https://skaile-ai.github.io/forge-editor/guides/explore).

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Port (capability)
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        KnowledgeGraph
      </code>
    </td>
    
    <td>
      <code>
        search(q, user)
      </code>
      
      , <code>
        neighbours(id, user)
      </code>
      
       and optionally <code>
        origin(id, user)
      </code>
    </td>
    
    <td>
      <code>
        knowledge
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /api/editor/knowledge/search?q=
      </code>
    </td>
    
    <td>
      the nodes <code>
        q
      </code>
      
       finds, best first
    </td>
    
    <td>
      <code>
        knowledge
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /api/editor/knowledge/nodes/:id/neighbours
      </code>
    </td>
    
    <td>
      a node, the nodes next to it and the edges between them
    </td>
    
    <td>
      <code>
        knowledge
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EditorBackend['knowledge']
      </code>
    </td>
    
    <td>
      <code>
        search(query, signal?)
      </code>
      
       and <code>
        neighbours(id, signal?)
      </code>
    </td>
    
    <td>
      <code>
        knowledge
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Explore tab <code>
        knowledge
      </code>
    </td>
    
    <td>
      the nodes found for the open Block's title; a click shows the neighbours
    </td>
    
    <td>
      <code>
        index
      </code>
      
       and <code>
        knowledge
      </code>
    </td>
  </tr>
</tbody>
</table>

A node is **not a Block** and an edge is **not an Edge** of the [Block index](https://skaile-ai.github.io/forge-editor/guides/edges): the graph's `kind` (`Source`, `Concept`, …) and its edge types (`References`, `DerivedFrom`, …) are its own words, shown as written.

## The port

`EditorPorts.knowledge` (`@skaile/forge-editor/server`), the shapes in `@skaile/forge-editor/core`:

```ts
interface KnowledgeGraph {
  /** The nodes `q` finds, best first. */
  search(q: string, user: object): Promise<KnowledgeHit[]>
  /** The node `id` (first), the nodes next to it, and the edges that join them. An unknown id: both lists empty. */
  neighbours(id: string, user: object): Promise<KnowledgeNeighbours>
  /** Optional: the nodes `id` was made from (its sources). */
  origin?(id: string, user: object): Promise<KnowledgeNode[]>
}

interface KnowledgeNode { id: string, label: string, kind: string }
interface KnowledgeHit extends KnowledgeNode { score: number }
interface KnowledgeEdge { from: string, to: string, kind: string }
interface KnowledgeNeighbours { nodes: KnowledgeNode[], edges: KnowledgeEdge[] }
```

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        KnowledgeNode
      </code>
    </td>
    
    <td>
      <code>
        id
      </code>
      
       is stable; <code>
        label
      </code>
      
       is what the node is called (its id for a node without a title); <code>
        kind
      </code>
      
       is what it is, in the graph's words
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        KnowledgeHit
      </code>
    </td>
    
    <td>
      a node with the <code>
        score
      </code>
      
       the graph gave it. Higher is better; the scale is the graph's own and only orders the list
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        KnowledgeEdge
      </code>
    </td>
    
    <td>
      a directed edge between two node ids; every edge of a <code>
        KnowledgeNeighbours
      </code>
      
       has both ends in its <code>
        nodes
      </code>
    </td>
  </tr>
</tbody>
</table>

`origin` is not served by a route yet; an add-on or a host reads it from the port.

## Routes

<table>
<thead>
  <tr>
    <th>
      Route (<code>
        API
      </code>
      
       key)
    </th>
    
    <th>
      Request
    </th>
    
    <th>
      Answer
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/editor/knowledge/search
      </code>
      
       (<code>
        knowledgeSearch
      </code>
      
      )
    </td>
    
    <td>
      <code>
        ?q=
      </code>
    </td>
    
    <td>
      <code>
        KnowledgeHit[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /api/editor/knowledge/nodes/:id/neighbours
      </code>
      
       (<code>
        knowledgeNeighbours
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      <code>
        KnowledgeNeighbours
      </code>
    </td>
  </tr>
</tbody>
</table>

Both routes are served only when `ports.knowledge` is present, for every signed-in user: the graph is the host's, and the `user` the port receives is where a host that keeps per-user access applies it.

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      When
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      <code>
        q
      </code>
      
       missing, blank or longer than <code>
        KNOWLEDGE_QUERY_MAX
      </code>
      
       (500) characters; an id blank or longer than <code>
        KNOWLEDGE_ID_MAX
      </code>
      
       (200)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        401
      </code>
    </td>
    
    <td>
      no user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        501
      </code>
    </td>
    
    <td>
      the host has no <code>
        knowledge
      </code>
      
       port
    </td>
  </tr>
</tbody>
</table>

## Provide a port

```ts
import { createMemoryKnowledgeGraph } from '@skaile/forge-editor/adapters/knowledge'
import type { EditorPorts } from '@skaile/forge-editor/server'

// Two nodes and one edge, for a test or a demo.
const knowledge: NonNullable<EditorPorts['knowledge']> = createMemoryKnowledgeGraph(
  [
    { id: 'n1', label: 'Wissensgraph Grundlagen', kind: 'Concept' },
    { id: 'n2', label: 'Wissensgraph Quelle', kind: 'Source' },
  ],
  [{ from: 'n1', to: 'n2', kind: 'DerivedFrom' }],
)
```

`createMemoryKnowledgeGraph(nodes, edges)` searches the words of the labels: a node is a hit when a word of its label starts with a word of the query (case and accents ignored), the `score` is the share of the query's words found (`1` = all), the best first, at most `MEMORY_KNOWLEDGE_LIMIT` (20). `neighbours` answers the node, the nodes joined to it in either direction and every edge among them; an edge to a node that is not listed is left out. `origin(id)` answers the nodes `id` has an outgoing `DerivedFrom` edge to.

A real graph is the host's. The add-on [`@skaile/forge-editor-kgs`](#the-kgs-add-on) wraps the KGS SDK.

## The Wissensgraph tab

With the backend capability `knowledge`, `exploreTabsOf(backend)` lists a fourth tab, `knowledge` („Wissensgraph“ / “Knowledge graph”), after `trail`. A backend without the capability has no such tab.

The `ExploreModel` fills it like the other lists: when the Block changes it reads the Block's title through `index.blockGet` and searches the graph for it (`state.query` is that text; a Block without a title searches nothing and the panel says so). `state.knowledge` is `{ status, items: KnowledgeHit[] }`, and each entry shows its label, its kind and its score.

Choosing a hit calls `model.focusNode(hit)`: `state.focus` is then `{ node, status, nodes, edges }` with the neighbours loading (`neighbours(node.id)`). The panel lists the nodes the graph joins to the focus (`exploreKnowledgeLinksOf(focus)`: node, edge type and `out` or `in`); choosing one of them moves the focus there, and „Zurück zu den Treffern“ calls `focusNode(null)`. A failing search or neighbourhood is `failed` and the other tabs stay usable. Opening a Block stays the host's `open`: knowledge nodes are no Blocks, so choosing one never calls it.

## The KGS add-on

`@skaile/forge-editor-kgs` is the `KnowledgeGraph` over the read side of the KGS SDK (`@kgs/sdk`, a daemon that holds a corpus of sources and concepts). `createKgsKnowledgeGraph(client, options?)` takes a `KgsReadClient`: the three methods of the SDK's `Client` that it calls (`get`, `search`, `neighbors`), typed in the add-on. The add-on does not import `@kgs/sdk` (it is not published on npm); the SDK is an optional peer that the host installs.

<table>
<thead>
  <tr>
    <th>
      <code>
        KnowledgeGraph
      </code>
    </th>
    
    <th>
      KGS call
    </th>
    
    <th>
      Answer
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        search(q)
      </code>
    </td>
    
    <td>
      <code>
        kgs.search
      </code>
    </td>
    
    <td>
      <code>
        { id, label, kind, score }
      </code>
      
      : the node's title, its node type, the daemon's score
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        neighbours(id)
      </code>
    </td>
    
    <td>
      <code>
        kgs.get
      </code>
      
       and <code>
        kgs.neighbors
      </code>
      
       (both directions)
    </td>
    
    <td>
      the node, the nodes next to it and the edges that join them
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        origin(id)
      </code>
    </td>
    
    <td>
      <code>
        kgs.neighbors
      </code>
      
       (<code>
        DerivedFrom
      </code>
      
      , outgoing)
    </td>
    
    <td>
      the nodes <code>
        id
      </code>
      
       was made from
    </td>
  </tr>
</tbody>
</table>

Deleted nodes never appear. Options: `mode` (the daemon's search mode, default `hybrid`), `limit` (hits, default 10), `scope` (a zone to search in).

```ts
import { createKgsKnowledgeGraph } from '@skaile/forge-editor-kgs'
import { Client, TcpTransport } from '@kgs/sdk'

const client = await Client.fromTransport(new TcpTransport('127.0.0.1', 7777))
const knowledge = createKgsKnowledgeGraph(client, { limit: 10 })
// provideEditorServer({ ports: { …, knowledge } })
```

The repository's document pages (the file-drawer layout, `app/layouts/default.vue`, whose Explore panel gets a fourth tab) show it behind `NUXT_PUBLIC_ADDONS_KGS=1` with `KGS_URL` (`tcp://host:port` or `unix:///path/to/.kgs/socket`); the kitchen sink's standalone pages have no workspace index and show no knowledge graph.


# Language

> Choose the editor language once per app, override single messages, and keep user-facing strings in the German and English catalogs.

## Catalogs

Every string the editor shows (toolbar, slash menu, Block 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`.

## Choosing the language

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).

## Messages in features and components

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)`, `defaultBlockTypes(t)`).

## Markdown

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.

## The i18n check

`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.


# Markdown and code

> Edit Markdown files as blocks with frontmatter and unknown fences preserved, edit source files in CodeMirror, and pick a surface per file type.

`@skaile/forge-editor` edits documents that live as plain files in three entry families: Markdown as blocks (`/markdown`, `/markdown/vue`, `/markdown/react`), source files in CodeMirror 6 (`/code`, `/code/vue`, `/code/react`) and one component that picks between them by file type (`/document/vue`, `/document/react`). The Markdown surface keeps the frontmatter and every fence it does not understand byte for byte, so opening and saving a file without edits changes nothing.

<demo-frame name="vue-markdown">

## Markdown (`@skaile/forge-editor/markdown`)

### Framework-free API

- `splitFrontmatter(text)` / `joinFrontmatter(frontmatter, body)`: the YAML block at offset 0 only, kept verbatim.
- `markdownToContent(editor, body, { policy? }): { content, diagnostics }`. The policy `{ allowHtml?, allowDataUrls? }` decides what is dropped: raw HTML, links and media with unsafe URLs are dropped and reported as `MarkdownDiagnostic`s: `raw-html`, `unsafe-url`, `unknown-fence` (info), `unclosed-fence` and `invalid-fence-meta` (errors). `hasFatalDiagnostics` tells whether a result must not be committed.
- `contentToMarkdown(editor)`.
- `MarkdownClipboard.configure({ policy })`: an extension that pastes `text/markdown` and plain text with block syntax as blocks, sanitizes pasted HTML, and copies and cuts as `text/markdown` next to `text/html` and `text/plain`.
- `createSourceMode({ getEditor, toMarkdown?, fromMarkdown?, policy? }): SourceMode`: the `state` store is `{ mode: 'visual' | 'source', source, diagnostics }`; `enter()`, `edit(text)`, `commit(): boolean` (false with the editor untouched on a fatal diagnostic or a document the schema rejects) and `cancel()`.
- Unknown `::: kind` fences are `OpaqueFence` nodes (in `coreSchemaExtensions()`) that are written back byte for byte; Block types the Typed blocks feature registers parse first.

### Vue: `MarkdownSurface`

`MarkdownSurface` from `@skaile/forge-editor/markdown/vue`:

- `v-model` is the Markdown string, frontmatter included. An incoming value equal to the last emitted one is ignored.
- Props, emits and slots of `EditorSurface` are forwarded.
- Prop `policy` also configures the `MarkdownClipboard` it installs.
- Prop `sourceMode` takes a `SourceMode`: while its state is `source` the surface shows the draft in a text area with the diagnostics of a rejected commit and Apply/Cancel; `sourceLabels` supplies their texts.
- Event `diagnostics` reports the load diagnostics.

### React: `MarkdownSurface`

`MarkdownSurface` from `@skaile/forge-editor/markdown/react` takes `value` / `onChange` / `onFrontmatterChange` / `onDiagnostics`, a `policy` prop (it also configures the installed `MarkdownClipboard`) and the `EditorSurface` props forwarded, with the same semantics. It has no source view.

Neither binding imports CodeMirror.

## Code (`@skaile/forge-editor/code`)

CodeMirror 6 on a string, themed by the shared `--sk-*` tokens (`styles/tokens.css`; fallbacks are the token defaults).

### Framework-free API

`createCodeEditor({ parent, doc?, readOnly?, wordWrap?, language?, onSaveShortcut?, onChange? })`, `setReadOnly`, `setWordWrap`, `setLanguage(view, support)`, `loadLanguage(view, id)`, `setDocument(view, text)` (a host text, not an edit), `registerLanguage(id, loader, { core? })` / `resolveLanguage(id)` / `isCoreLang(id)` (language packs are the host's: register the `@codemirror/lang-*` packs you depend on; `jsonl` is built in), `formatJsonInEditor(view)`, `formatJsonText`, `jsonlLanguage`, `kindOf(path, mime?)` (`'markdown' | 'code' | 'binary'`) and `languageOf(path)`.

### Components

- `/code/vue`: `CodeSurface` (`v-model` string, `editable`, `language`, `wordWrap`; emits `update:modelValue`, `save` on Mod-S, `ready(view)`).
- `/code/react`: `CodeSurface` (`value`, `onChange`, `onSave`, `onReady`, same flags).

No ProseMirror or TipTap is reachable from these entries.

## One component for every file: `DocumentSurface`

`DocumentSurface` from `@skaile/forge-editor/document/vue` or `/document/react` renders by file type:

- `MarkdownSurface` for `kindOf(path, mime) === 'markdown'` (prop `markdown`: the Markdown surface's own props, `preset` at least).
- `CodeSurface` for text (language from `languageOf(path)` unless `language` is given).
- A `binary` slot (Vue) or `binary(path)` render prop (React) otherwise.

`ready` carries `{ kind: 'markdown', editor }` or `{ kind: 'code', view }`. These entries reach both editors; use `/markdown/*` or `/code/*` alone to keep one out of a bundle.

## Example: `examples/vue-markdown`

[`examples/vue-markdown`](https://github.com/skaile-ai/forge-editor/tree/main/examples/vue-markdown) is the demo above: a plain Vue app with no data layer that mounts `MarkdownSurface` on a sample document with frontmatter, a table, task items and an `::: note` fence of a Block type no feature knows. Run it with `bun run --cwd examples/vue-markdown dev` (port 3045).

What the example shows:

- **Byte-identical round trip.** The sample is already in the editor's normal form, so a faithful round trip returns it byte for byte. The page prints "Round trip without edits: byte-identical" until you edit; the unknown `::: note` fence stays exactly as written because it is an opaque block.
- **Preset.** `defineEditor` over `coreContentFeature()`, `coreUiFeature({ palette: EditorCommandPalette })` and `tablesFeature()`. The toolbar is a sibling that takes the editor from `@ready`.
- **Source mode.** The „Source" button calls `sourceMode.enter()` on a `createSourceMode` bound to the editor; the surface then shows the Markdown text, and a commit succeeds only when it parses without a fatal diagnostic. `useStoreRef(sourceMode.state)` turns the framework-free store into a ref.
- **Diagnostics.** The `diagnostics` event fills the "Load diagnostics" line; the last pane shows the current Markdown string.

The surface component and its state:

```vue [examples/vue-markdown/src/App.vue]
<script setup lang="ts">
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { createSourceMode, type MarkdownDiagnostic } from '@skaile/forge-editor/markdown'
import { MarkdownSurface } from '@skaile/forge-editor/markdown/vue'
import { tablesFeature } from '@skaile/forge-editor/tables'
import { EditorCommandPalette, EditorToolbar, useStoreRef } from '@skaile/forge-editor/vue'
import type { Editor } from '@tiptap/vue-3'
import { type Component, computed, ref, shallowRef } from 'vue'

// The sample is already in the editor's normal form, so a faithful round trip returns it byte for byte; the `::: note`
// fence is of a kind no feature knows, so it is an opaque block that is written back as it came.
const SAMPLE = `---
title: Sample
tags: [a, b]
---
# Heading

Some text with **bold**.

| Name | Count |
| --- | --- |
| a | 1 |
| b | 2 |

- [ ] open task
- [x] done task

::: note {"tone":"info"}
Unknown kinds   stay
exactly as written.
:::
`

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature<Component>({ palette: EditorCommandPalette }), tablesFeature()] })
const text = ref(SAMPLE)
const editor = shallowRef<Editor>()
const edits = ref(0)
const unchanged = computed(() => edits.value === 0 && text.value === SAMPLE)
const loadDiagnostics = ref<MarkdownDiagnostic[]>([])

// Source mode: the whole document as Markdown text, committed only when it parses without a fatal diagnostic.
const sourceMode = createSourceMode({ getEditor: () => editor.value })
const source = useStoreRef(sourceMode.state)
const inSource = computed(() => source.value.mode === 'source')
</script>
```

The template mounts the surface with `v-model`, the preset, the source mode and the two events:

```vue [examples/vue-markdown/src/App.vue]
<template>
  <UApp>
    <main class="mx-auto flex max-w-4xl flex-col gap-4 p-6">
      <h1 class="text-xl font-semibold">@skaile/forge-editor – MarkdownSurface</h1>
      <p class="text-sm text-muted" data-testid="roundtrip">
        Round trip without edits: {{ unchanged ? 'byte-identical' : 'changed' }}
      </p>
      <div class="flex items-center gap-2">
        <EditorToolbar v-show="!inSource" :editor="editor" />
        <UButton
          v-if="!inSource"
          class="ml-auto"
          label="Source"
          icon="i-lucide-file-code"
          color="neutral"
          variant="outline"
          data-testid="source-enter"
          @click="sourceMode.enter()"
        />
      </div>
      <div class="rounded-lg border border-default p-4" data-testid="surface">
        <MarkdownSurface
          v-model="text"
          :preset="preset"
          :source-mode="sourceMode"
          @ready="editor = $event"
          @update:model-value="edits++"
          @diagnostics="loadDiagnostics = $event"
        />
      </div>
      <p class="text-sm text-muted" data-testid="diagnostics">
        Load diagnostics: {{ loadDiagnostics.length ? loadDiagnostics.map(d => `${d.code}${d.line ? `@${d.line}` : ''}`).join(', ') : 'none' }}
      </p>
      <pre class="max-h-96 overflow-auto rounded-lg bg-elevated p-3 text-xs" data-testid="markdown">{{ text }}</pre>
    </main>
  </UApp>
</template>
```

The app needs the editor context. `main.ts` installs Nuxt UI, then `createEditor` with the Nuxt UI kit and a memory backend (users, tags and uploads live in the page):

```ts [examples/vue-markdown/src/main.ts]
import ui from '@nuxt/ui/vue-plugin'
import { createMemoryBackend } from '@skaile/forge-editor/adapters/memory'
import { createEditor } from '@skaile/forge-editor/vue'
import { nuxtUiKit } from '@skaile/forge-editor/vue/kit/nuxt-ui'
import { createApp } from 'vue'
import App from './App.vue'
import './style.css'

// No data layer: documents, dropped files (as blob: URLs), mention users and tags, and settings live in the page.
const backend = createMemoryBackend({
  users: [
    { id: 'u1', username: 'Ada Lovelace', color: '#7c3aed' },
    { id: 'u2', username: 'Alan Turing', color: '#0ea5e9' },
    { id: 'u3', username: 'Grace Hopper', color: '#16a34a' },
  ],
  tags: ['idee', 'entwurf', 'wichtig'],
})

createApp(App)
  .use(ui)
  .use(createEditor({ kit: nuxtUiKit(), backend }))
  .mount('#app')
```

Import `core.css` and `tables.css` in this order after Tailwind and Nuxt UI ([CSS and UI-provider requirements](https://skaile-ai.github.io/forge-editor/reference/css-and-ui)). In this documentation site the demo is the built example, embedded as an iframe.

</demo-frame>


# Media, mentions and transcript features

> Add image, audio, video and file blocks, @ mentions and # tags, and speaker transcripts as independent features, with uploads, metadata lists and server schemas.

Three independent features extend the core editor. Each is one factory you add to `defineEditor({ features })` next to `coreContentFeature()` and `coreUiFeature()`; none needs Typed blocks, AI or Yjs, and none imports the others (`bun run check:editor-entries` proves it per feature).

```vue
<script setup lang="ts">
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { EditorSurface, EditorToolbar } from '@skaile/forge-editor/vue'
import { mediaFeature } from '@skaile/forge-editor/media/vue'
import { mentionsFeature } from '@skaile/forge-editor/mentions'
import { transcriptFeature } from '@skaile/forge-editor/transcript/vue'
import type { Editor } from '@tiptap/vue-3'
import { shallowRef } from 'vue'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), mediaFeature(), mentionsFeature(), transcriptFeature()] })
const editor = shallowRef<Editor>()
</script>

<template>
  <EditorToolbar :editor="editor" />
  <EditorSurface v-model="content" :preset="preset" @ready="editor = $event" />
</template>
```

Import the feature CSS after `tailwindcss`, `@nuxt/ui` and `core.css`:

```css
@import "@skaile/forge-editor/styles/media.css";
@import "@skaile/forge-editor/styles/mentions.css";
@import "@skaile/forge-editor/styles/transcript.css";
```

## Dependency setup

Installing the package brings the feature dependencies; nothing else is required in the consumer beyond the peers listed in [Installation](https://skaile-ai.github.io/forge-editor/getting-started/installation#prerequisites).

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      Entry
    </th>
    
    <th>
      Vue-free schema entry
    </th>
    
    <th>
      Runtime dependencies it adds
    </th>
    
    <th>
      Needs a backend
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Media
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/media
      </code>
      
       (framework-free), <code>
        /media/vue
      </code>
      
      , <code>
        /media/react
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/media/schema
      </code>
    </td>
    
    <td>
      <code>
        @tiptap/extension-image
      </code>
      
      , <code>
        @tiptap/extension-file-handler
      </code>
    </td>
    
    <td>
      only for uploads (see below); a backend with <code>
        assets
      </code>
      
       stores them
    </td>
  </tr>
  
  <tr>
    <td>
      Mentions
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/mentions
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/mentions/schema
      </code>
    </td>
    
    <td>
      <code>
        @tiptap/extension-mention
      </code>
      
      , <code>
        @tiptap/suggestion
      </code>
    </td>
    
    <td>
      only for the built-in lists (see below); host lists replace them
    </td>
  </tr>
  
  <tr>
    <td>
      Transcript
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/transcript
      </code>
      
       (framework-free), <code>
        /transcript/vue
      </code>
      
      , <code>
        /transcript/react
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/transcript/schema
      </code>
    </td>
    
    <td>
      none beyond core
    </td>
    
    <td>
      no
    </td>
  </tr>
</tbody>
</table>

The `/schema` entries import no Vue, no node view and no feature factory. A server that validates or seeds documents builds the matching schema from them:

```ts
import { getSchema } from '@tiptap/core'
import { coreSchemaExtensions } from '@skaile/forge-editor/core/schema'
import { mediaSchemaExtensions } from '@skaile/forge-editor/media/schema'
import { mentionsSchemaExtensions } from '@skaile/forge-editor/mentions/schema'
import { transcriptSchemaExtensions } from '@skaile/forge-editor/transcript/schema'

const schema = getSchema([...coreSchemaExtensions(), ...mediaSchemaExtensions(), ...mentionsSchemaExtensions(), ...transcriptSchemaExtensions()])
```

The schema entries also export the helpers servers need: `MEDIA_TYPES`, `MAX_MEDIA_BYTES`, `mediaKindOf`, `assetUrl`, `assetRefOf`, `ASSET_NAME`, `ASSET_DOCUMENT_ID`, `SCRATCH_DOCUMENT_ID` (media), `mentionsFromText`, `mentionUsersIn`, `tagsFromText`, `collectTagNames`, `normalizeTagName` (mentions), `speakerParagraphsToSegments`, `lastSpeaker`, `speakersIn` (transcript).

## Upload

`mediaFeature()` adds image, audio, video and file blocks, drop/paste of files, toolbar buttons (Bild, Audio-Datei, Video, Aufnahme), the matching `/` commands and the audio recorder modal. Every path ends in one function, `editor.storage.media.upload(file): Promise<{ url: string, sha256?: string }>`, which calls the backend's `assets` capability: `backend.assets.upload(documentId, file)`; `documentId` is the surface's prop, default `scratch`.

- The HTTP backend (`createHttpBackend()`, the default) sends `POST /api/editor/assets/<documentId>` with a `multipart/form-data` body (field `file`); the response must be `{ url }` and may add `sha256` (hex SHA-256 of the bytes; the bundled server always sends it, and stores it in the asset record). The media blocks keep it as their `hash` attribute; backends that send none (the memory backend) leave `hash` empty.
- To store files elsewhere (S3, a data URL, …), implement `assets.upload` in your own `EditorBackend` (`createEditor({ backend })`); the returned `url` becomes the block's `src`. `createMemoryBackend()` answers with a `blob:` URL.

```ts
const backend: EditorBackend = { name: 'my-store', assets: { upload: async (_documentId, file) => ({ url: await storeSomewhere(file) }) } }
createEditor({ backend })
```

Accepted types and size limits are `MEDIA_TYPES` and `MAX_MEDIA_BYTES` (Vue-free, from `@skaile/forge-editor/media/schema`): images up to 5 MB (png, jpeg, gif, webp), audio 50 MB, video 200 MB, and any other type up to 50 MB as a downloadable file block. A server endpoint should validate against the same constants; the Nuxt module's `/api/editor/assets/*` routes do. A failed upload shows a toast (`Import fehlgeschlagen`) and inserts nothing.

**File import.** Drop, paste, the toolbar and `/` commands all call `editor.storage.media.importFiles(editor, files, pos?)`; `useFileImport()` (from `@skaile/forge-editor/media/vue` or `/media/react`; call it in `setup` / while rendering: it binds the notifier of `editor`'s surface when you pass the editor, else the app's: a Nuxt UI toast on Vue and a sonner toast on React unless the host's `notify` says otherwise) returns the same `importFiles` for your own buttons; the framework-free model is `fileImport(notify, t)` from `@skaile/forge-editor/media` (`t` is the editor context's translator). Every file is planned by the [importer registry](./34.importers): a Markdown, subtitle (`.vtt`, `.srt`) or BibTeX (`.bib`) file by its own importer; any other text file (`.txt`, at most 2 MB) is parsed through the editor's block pipeline (Markdown parse, then `normalize` — mention/tag chips —, `segment` — speaker lines —, `structure`); every other file is uploaded and appears as its media or file block. A wrapping importer (`composite-media`) may then wrap the plan; the resulting blocks are inserted as they are at the drop position (anchored while uploads run, so editing meanwhile does not shift it) or at the selection. Files are imported sequentially; a failed file is reported and skipped.

The recorder (`AudioRecorderModal`) is mounted by `EditorSurface` as a feature overlay. In a custom layout without `EditorSurface`, render `<AudioRecorderModal :editor="editor" />` yourself (exported from `@skaile/forge-editor/media/vue`, or `/media/react`) and open it with `openAudioRecorder(editor)`. It records through `MediaRecorder` (needs HTTPS or localhost and microphone permission) and imports the result like any file. The recording model itself is framework-free: `createAudioRecorder()` from `@skaile/forge-editor/media` (a store with `start`, `stop`, `cancel`, `dispose`).

## Metadata

The mentions feature reads two named lists, the transcript feature one; hosts replace any of them through the `metadata` prop (`EditorMetadata`: a static array or a search function `(q: MetadataQuery) => items | Promise<items>`). Lists the host does not supply fall back to the feature's built-in source; the fallback is only searched when a suggestion popup is actually used.

<table>
<thead>
  <tr>
    <th>
      List
    </th>
    
    <th>
      Used by
    </th>
    
    <th>
      Built-in source when the host supplies none
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mentions
      </code>
    </td>
    
    <td>
      <code>
        @
      </code>
      
       popup, <code>
        normalize
      </code>
      
       stage
    </td>
    
    <td>
      <code>
        GET /api/editor/users?q=<query>
      </code>
      
       → <code>
        { id, username, color }[]
      </code>
      
       (through the context's HTTP client)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hashtags
      </code>
    </td>
    
    <td>
      <code>
        #
      </code>
      
       popup
    </td>
    
    <td>
      <code>
        GET /api/editor/tags?q=<normalized query>
      </code>
      
       → <code>
        string[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        speakers
      </code>
    </td>
    
    <td>
      speaker field of a segment
    </td>
    
    <td>
      speakers already in the document (no backend)
    </td>
  </tr>
</tbody>
</table>

A backend-free app passes its own lists and never calls those endpoints:

```vue
<EditorSurface
  :preset="preset"
  :metadata="{
    mentions: [{ id: 'u1', label: 'anna', color: '#e11d48' }],
    hashtags: q => searchTags(q.query),
  }"
  @metadata-create="(list, item) => persist(list, item)"
/>
```

Mentions are `@username` chips tinted with the item's `color` (a `#rgb`/`#rrggbb` value; anything else is dropped). Tags are `#tag` chips; the typed name is normalized (`normalizeTagName`: lowercase, spaces → `-`, letters/digits/`-`/`_` only plus `/` as the separator of a nested name like `inbox/to-read`, at most 64 characters), and the popup offers „#name erstellen“ when it is not in the list — picking it emits `metadataCreate('hashtags', { id, label })`.

**Pipeline stages.** The mentions feature contributes the `normalize` stage: `@name` / `#tag` in Markdown that is imported from a file or written by AI turns into chips when the name matches a user already in the document or in the `mentions` list, or a tag already in the document. Without the feature installed, those stay plain text. The transcript feature contributes the `segment` stage: a paragraph that starts with a bold `**Name:**` followed by text becomes a speaker segment (a bare `**Aufgaben:**` label stays a paragraph). Both stages run for imported files and for AI results.

## Transcript

`transcriptFeature()` adds the speaker segment block: a „Sprecherblock“ toolbar button (Mod-Shift-S), Enter inside a segment splits it keeping the speaker, a speaker field with suggestions from the `speakers` list, the „Sprecherzeile“ entry in the „Umwandeln in …“ menus (paragraphs, headings, lists, quotes and code blocks become segments carrying the last speaker; segments convert back into any core target), and Markdown `**Name:** text` export. A segment holds only inline text: headings, lists, quotes, code blocks, media and Typed blocks are revoked inside it.


# Migrating from #tiptap-editor

> Move a host from the removed #tiptap-editor Nuxt module to explicit imports from @skaile/forge-editor entries.

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 `'@skaile/forge-editor/nuxt'` (after `'@nuxt/ui'`). The `tiptapEditor` options keep their shape and defaults. Add `"@skaile/forge-editor": "workspace:*"` to the host's dependencies.
2. Replace auto-imported components and composables by explicit imports:

<table>
<thead>
  <tr>
    <th>
      Before (auto-import or <code>
        #tiptap-editor
      </code>
      
      )
    </th>
    
    <th>
      After
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        DocumentEditor
      </code>
    </td>
    
    <td>
      <code>
        AdvancedEditor
      </code>
      
       from <code>
        @skaile/forge-editor/vue/advanced
      </code>
      
       (same props and events; plus <code>
        settings-ui
      </code>
      
      , see <a href="https://skaile-ai.github.io/forge-editor/reference/presets-and-features">
        Presets and features
      </a>
      
      ); on React <code>
        @skaile/forge-editor/react/advanced
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EditorToolbar
      </code>
      
      , <code>
        EditorSettingsModal
      </code>
      
      , <code>
        useEditorSettings
      </code>
      
      , <code>
        useEditorUi
      </code>
      
      , <code>
        useEditorContext
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/vue
      </code>
      
       (the toolbar and the panel take <code>
        :editor
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AiSidebar
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/ai/vue/chat
      </code>
      
       (needs the optional peer <code>
        @skaile/forge-chat
      </code>
      
      ; <code>
        /ai/react
      </code>
      
       on React)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AiReviewBar
      </code>
      
      , <code>
        AiSelectionMenu
      </code>
      
      , <code>
        ModelQuickSwitch
      </code>
      
      , <code>
        useAiAssistant
      </code>
      
      , <code>
        useDocumentChat
      </code>
      
      , <code>
        useModelProfiles
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/ai/vue
      </code>
      
       (<code>
        /ai/react
      </code>
      
       on React; the framework-free models <code>
        modelProfiles
      </code>
      
      , <code>
        createAiAssistant
      </code>
      
      , <code>
        createDocumentChat
      </code>
      
       in <code>
        @skaile/forge-editor/ai
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        useFileImport
      </code>
      
      , <code>
        AudioRecorderModal
      </code>
      
      , <code>
        useAudioRecorder
      </code>
      
      , <code>
        pickFiles
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/media/vue
      </code>
      
       (<code>
        /media/react
      </code>
      
       on React); <code>
        pickFiles
      </code>
      
       and the framework-free models in <code>
        @skaile/forge-editor/media
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createTranscriptCleanup
      </code>
      
      , <code>
        hasTranscriptSegments
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/integrations/transcript-ai
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      The Block type API (the module's former <code>
        Composite*
      </code>
      
       names; today <code>
        defaultBlockTypes(t)
      </code>
      
      , <code>
        BlockType
      </code>
      
      , <code>
        acceptsChild
      </code>
      
      ), <code>
        AcceptedChildren
      </code>
      
      , <code>
        headingsMarkdown
      </code>
      
      , <code>
        compositeOutline
      </code>
      
      , <code>
        moveBlockInto
      </code>
      
      , <code>
        moveIntoVerdict
      </code>
      
      , markdown fence helpers, <code>
        CompositeTable
      </code>
      
      , <code>
        CompositeInspector
      </code>
      
      , <code>
        useCompositeRows
      </code>
      
      , <code>
        setComposite*
      </code>
      
       writers
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/composites
      </code>
      
       (framework-free), <code>
        /composites/vue
      </code>
      
       or <code>
        /composites/react
      </code>
      
       for the components and <code>
        useCompositeRows
      </code>
      
       (schema subset: <code>
        /composites/schema
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        headingOutline
      </code>
      
      , <code>
        revealBlockInEditor
      </code>
      
       (framework-free), <code>
        EditorOutline
      </code>
      
       (<code>
        /outline/vue
      </code>
      
      , <code>
        /outline/react
      </code>
      
      )
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/outline
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EMPTY_EDITOR_CONTENT
      </code>
      
      , <code>
        ABILITY
      </code>
      
      , <code>
        Ability
      </code>
      
      , <code>
        findBlockById
      </code>
      
      , block ID helpers
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core/schema
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        fetchErrorMessage
      </code>
      
      , <code>
        downloadText
      </code>
      
      , abilities helpers (<code>
        abilitiesAtSelection
      </code>
      
      , <code>
        hasAbility
      </code>
      
      )
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DocumentTree
      </code>
      
      , <code>
        useTreeView
      </code>
      
      , <code>
        TreeFolder
      </code>
      
      , <code>
        DocumentSummary
      </code>
      
       (were host files and host shared types)
    </td>
    
    <td>
      <code>
        DocumentTree
      </code>
      
      , <code>
        useTreeView
      </code>
      
       from <code>
        @skaile/forge-editor/tree/vue
      </code>
      
       (or <code>
        /tree/react
      </code>
      
      ); <code>
        DocumentStore
      </code>
      
      , <code>
        TreeFolder
      </code>
      
      , <code>
        DocumentSummary
      </code>
      
       from <code>
        @skaile/forge-editor/tree
      </code>
      
       (the host's <code>
        DocumentStore
      </code>
      
       implementation stays in the app; the host's ref-based store becomes stores with <code>
        storeFromRef
      </code>
      
       from <code>
        @skaile/forge-editor/vue
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setEditorAdapter
      </code>
      
      , <code>
        forgetCollabDocument
      </code>
      
      , <code>
        liveContent
      </code>
      
      , <code>
        EditorAdapter
      </code>
      
       (Nitro, previously auto-imported)
    </td>
    
    <td>
      <code>
        provideEditorServer({ ports })
      </code>
      
      , <code>
        useEditorServer().forgetDocument
      </code>
      
      , <code>
        useEditorServer().liveContent
      </code>
      
       from <code>
        @skaile/forge-editor/server/nitro
      </code>
      
      , <code>
        EditorPorts
      </code>
      
       from <code>
        @skaile/forge-editor/server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Server schema / migration imports of the old shared directory
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/schema/advanced
      </code>
      
      , <code>
        /composites/schema
      </code>
      
      , <code>
        /media/schema
      </code>
      
      , …
    </td>
  </tr>
</tbody>
</table>

1. 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`, [per-feature entries](https://skaile-ai.github.io/forge-editor/guides/composition#per-feature-entries-framework-free-vue-react)), so host code no longer hands toast objects to feature functions.
2. 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.
3. Styles: the Nuxt module adds every feature stylesheet; a plain-Vue app imports `core.css` plus the feature CSS it uses ([README](https://skaile-ai.github.io/forge-editor/reference/css-and-ui)).

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 (`currentContent` on the server, the composites Feature's `migrateContent` hook in the editor).

## Block vocabulary

The library, the reference app and the docs name things in the block vocabulary ([glossary](https://skaile-ai.github.io/forge-editor/getting-started/glossary): Typed block, Block type, Property definition, Model role, …). The former names are removed; no alias remains. Switch a host over like this:

<table>
<thead>
  <tr>
    <th>
      Former name
    </th>
    
    <th>
      New name
    </th>
    
    <th>
      Where
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        CompositeKind
      </code>
      
      , <code>
        CompositeKindAi
      </code>
      
      , <code>
        CompositeMetaField
      </code>
    </td>
    
    <td>
      <code>
        BlockType
      </code>
      
      , <code>
        BlockTypeAi
      </code>
      
      , <code>
        PropertyDefinition
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/composites
      </code>
      
      , <code>
        /composites/schema
      </code>
      
      ; <code>
        PropertyDefinition
      </code>
      
       from <code>
        @skaile/forge-editor/core
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        defaultCompositeKinds
      </code>
      
      , <code>
        fallbackCompositeKinds
      </code>
      
      , <code>
        compositeKind
      </code>
      
      , <code>
        kindAccepts
      </code>
    </td>
    
    <td>
      <code>
        defaultBlockTypes(t)
      </code>
      
      , <code>
        fallbackBlockTypes
      </code>
      
      , <code>
        blockTypeOf
      </code>
      
      , <code>
        acceptsChild
      </code>
    </td>
    
    <td>
      the same entries
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compositeKindsOf(editor)
      </code>
    </td>
    
    <td>
      <code>
        blockTypesOf(editor)
      </code>
    </td>
    
    <td>
      the same entries
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CompositeKindCount
      </code>
      
      , <code>
        CompositeKindOption
      </code>
      
      , <code>
        ChatCompositeKind
      </code>
    </td>
    
    <td>
      <code>
        BlockTypeCount
      </code>
      
      , <code>
        BlockTypeOption
      </code>
      
      , <code>
        ChatBlockType
      </code>
    </td>
    
    <td>
      the same entries; the chat type in <code>
        @skaile/forge-editor/ai
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      command <code>
        setCompositeKind(kind, pos?)
      </code>
    </td>
    
    <td>
      <code>
        changeBlockType(blockTypeId, pos?)
      </code>
    </td>
    
    <td>
      editor commands of the Typed block (not <code>
        setBlockType
      </code>
      
      : ProseMirror uses that name for node-type changes)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compositeMetaWith
      </code>
      
      , <code>
        setCompositeMetaField
      </code>
    </td>
    
    <td>
      <code>
        metaWithProperty
      </code>
      
      , <code>
        setBlockProperty
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/composites
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        renditionsOf
      </code>
    </td>
    
    <td>
      <code>
        derivedChildrenOf
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      option and prop <code>
        kinds
      </code>
      
       or <code>
        compositeKinds
      </code>
    </td>
    
    <td>
      <code>
        blockTypes
      </code>
      
       (<code>
        compositeFeature({ blockTypes })
      </code>
      
      , <code>
        composeEditor({ blockTypes })
      </code>
      
      , <code>
        AdvancedEditor
      </code>
      
      , <code>
        ComposedSurface
      </code>
      
      )
    </td>
    
    <td>
      the same entries
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        skeleton
      </code>
      
       in the <code>
        ai
      </code>
      
       brief of a Block type, and the AI wire field <code>
        block.skeleton
      </code>
    </td>
    
    <td>
      <code>
        contentTemplate
      </code>
    </td>
    
    <td>
      <code>
        BlockTypeAi
      </code>
      
      ; client and server of the AI endpoints ship in the same package
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ModelSlot
      </code>
      
      , <code>
        MODEL_SLOTS
      </code>
      
      , <code>
        MODEL_SLOT_KEYS
      </code>
    </td>
    
    <td>
      <code>
        ModelRole
      </code>
      
      , <code>
        MODEL_ROLES
      </code>
      
      , <code>
        MODEL_ROLE_KEYS
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/settings
      </code>
      
       (the stored key <code>
        ai.slots
      </code>
      
       is now <code>
        ai.roles
      </code>
      
      ; saved settings migrate on load)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PresetConfig
      </code>
    </td>
    
    <td>
      <code>
        ModelPresetConfig
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/config
      </code>
      
      , <code>
        /server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        Identity
      </code>
      
      , <code>
        DocumentStore
      </code>
      
       of the server ports
    </td>
    
    <td>
      <code>
        AccessControl
      </code>
      
      , <code>
        DocumentContentStore
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/server
      </code>
      
       (the <code>
        EditorPorts
      </code>
      
       members <code>
        identity
      </code>
      
       and <code>
        documents
      </code>
      
       keep their names; the Document tree's own <code>
        DocumentStore
      </code>
      
       in <code>
        @skaile/forge-editor/tree
      </code>
      
       keeps its name)
    </td>
  </tr>
  
  <tr>
    <td>
      the tree command string of the folder block
    </td>
    
    <td>
      <code>
        createFolderBlock
      </code>
    </td>
    
    <td>
      <code>
        TreeCommand
      </code>
      
       of <code>
        @skaile/forge-editor/tree
      </code>
      
      ; a host executor that switches on the command type must use the new string
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aiKindsOf
      </code>
      
      , <code>
        derivableKindsOf
      </code>
      
      , <code>
        AiContextKind
      </code>
    </td>
    
    <td>
      <code>
        aiBlockTypesOf
      </code>
      
      , <code>
        derivableBlockTypesOf
      </code>
      
      , <code>
        AiContextBlockType
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/composites
      </code>
      
      , <code>
        /integrations/composite-ai
      </code>
      
      , <code>
        /core
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        AiContext.kinds
      </code>
      
      , <code>
        ChatBlockModel.kinds
      </code>
      
      , the AI chat request field <code>
        kinds
      </code>
    </td>
    
    <td>
      <code>
        blockTypes
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
      
      , <code>
        /ai
      </code>
      
      ; client and server of the AI endpoints ship in the same package
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ConvertTarget
      </code>
      
       <code>
        { type: 'typedBlock', kind }
      </code>
    </td>
    
    <td>
      <code>
        { type: 'typedBlock', blockType }
      </code>
      
       (the target id <code>
        typedBlock:<id>
      </code>
      
       is unchanged)
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BlockProperties.fields
      </code>
    </td>
    
    <td>
      <code>
        BlockProperties.definitions
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/composites
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        listsBlockTypeCapability(type, id)
      </code>
      
      , <code>
        listsCapability(ctx, node, id)
      </code>
    </td>
    
    <td>
      <code>
        listsCapability(type, id)
      </code>
      
       (pass <code>
        ctx.blockTypeOf(node)
      </code>
      
      )
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockTypeConfigOf
      </code>
      
       from <code>
        /composites
      </code>
    </td>
    
    <td>
      <code>
        blockTypeConfigOf(type, id)
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
      
      ; <code>
        configOf
      </code>
      
       and <code>
        capabilityConfigOf
      </code>
      
       now return <code>
        undefined
      </code>
      
       (was <code>
        null
      </code>
      
      ) when absent
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BlockTypeSpec
      </code>
    </td>
    
    <td>
      <code>
        BlockType
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/composites
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivationOf
      </code>
      
      , <code>
        derivationState
      </code>
      
      , <code>
        DERIVATION_KEY
      </code>
      
      , <code>
        Derivation
      </code>
      
      , <code>
        DerivationMethod
      </code>
      
      , <code>
        DerivationSource
      </code>
      
      , <code>
        PropertyDefinition
      </code>
      
       from <code>
        /composites
      </code>
      
       or <code>
        /composites/schema
      </code>
    </td>
    
    <td>
      the same names
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
      
       only
    </td>
  </tr>
  
  <tr>
    <td>
      CSS <code>
        --sk-kind-tone
      </code>
      
      , <code>
        --sk-kind-tone-mix
      </code>
    </td>
    
    <td>
      <code>
        --sk-block-type-tone
      </code>
      
      , <code>
        --sk-block-type-tone-mix
      </code>
    </td>
    
    <td>
      host stylesheets that set or read the tone
    </td>
  </tr>
</tbody>
</table>

Behaviour that changed with the rename:

- **Accepted children.** The built-in Folder and Document Block types declare `accepts: 'all'` themselves; the id-keyed default is gone. A Block type without `accepts`, and a type ID that a list does not define, accepts no nested Typed blocks (`acceptsChild`). A host list that defines its own `folder` or `document` Block type must set `accepts` on it.
- **Block UI.** The hover bar, the toolbar Block actions and the drag handle address the outermost block, so a caret in a list item or a quote paragraph acts on the whole list or quote ([Block UI](https://skaile-ai.github.io/forge-editor/guides/block-ui#where-block-actions-appear)).
- **Labels.** English: Typed block, Block type, Readable rendition, Theme with Default appearance, Document facts, Structure mode and Flat mode. German: Block and Blocktyp; the two German labels that still use the legacy words for basket and readable rendition stay. Message keys keep their IDs, so `messages` overrides still apply, but check the wording of an override against the new labels.

## Block types as data

A `BlockType` (`@skaile/forge-editor/composites`) is now an `id`, its presentation (`label`, `icon`, `titlePlaceholder`, `descriptionPlaceholder`, `chrome`) and a list `capabilities: { id, config? }[]`. The former switches move into it ([Typed blocks](https://skaile-ai.github.io/forge-editor/guides/composites)):

<table>
<thead>
  <tr>
    <th>
      Former field
    </th>
    
    <th>
      Now
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        fields: PropertyDefinition[]
      </code>
    </td>
    
    <td>
      <code>
        { id: 'properties', config: { definitions } }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source: ('image' | 'audio' | 'video' | 'file')[]
      </code>
    </td>
    
    <td>
      <code>
        { id: 'source', config: { media } }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accepts: string[] | 'all'
      </code>
    </td>
    
    <td>
      <code>
        { id: 'container', config: { accepts } }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai: BlockTypeAi
      </code>
    </td>
    
    <td>
      <code>
        { id: 'ai-brief', config: ai }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      (every type had a Basket menu)
    </td>
    
    <td>
      <code>
        { id: 'basket' }
      </code>
      
      ; a type without it has no Basket menu
    </td>
  </tr>
  
  <tr>
    <td>
      a <code>
        bibliography
      </code>
      
       property implied the BibTeX export
    </td>
    
    <td>
      <code>
        { id: 'bibliography' }
      </code>
    </td>
  </tr>
</tbody>
</table>

A host list that spreads `defaultBlockTypes(t)` and adds its own types must give them the capabilities they need. An unknown capability id or an invalid config throws when the editor is created. `meta` keys and the `::: <Block type id>` Markdown fences keep their names; the node and its type attribute are renamed (below).

### Persisted names

Stored documents and settings use the vocabulary of the glossary. Everything saved before loads through a migration that reads the old names and never writes them back; hosts do nothing for stored data.

<table>
<thead>
  <tr>
    <th>
      Old
    </th>
    
    <th>
      New
    </th>
    
    <th>
      Where
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      node <code>
        composite
      </code>
    </td>
    
    <td>
      <code>
        typedBlock
      </code>
    </td>
    
    <td>
      document JSON, Yjs state, <code>
        .cdoc
      </code>
      
       packages, clipboard and drag payloads
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compositeTitle
      </code>
      
      , <code>
        compositeDescription
      </code>
      
      , <code>
        compositeTags
      </code>
    </td>
    
    <td>
      <code>
        typedBlockTitle
      </code>
      
      , <code>
        typedBlockDescription
      </code>
      
      , <code>
        typedBlockTags
      </code>
    </td>
    
    <td>
      same
    </td>
  </tr>
  
  <tr>
    <td>
      attribute <code>
        kind
      </code>
      
       on the Typed block and on <code>
        opaqueFence
      </code>
    </td>
    
    <td>
      <code>
        blockType
      </code>
    </td>
    
    <td>
      same; block IDs (<code>
        attrs.id
      </code>
      
      ) and <code>
        meta
      </code>
      
       are untouched
    </td>
  </tr>
  
  <tr>
    <td>
      HTML <code>
        section[data-type="composite"][data-kind]
      </code>
    </td>
    
    <td>
      <code>
        section[data-type="typedBlock"][data-block-type]
      </code>
    </td>
    
    <td>
      clipboard HTML: both shapes parse, only the new one is written
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BlockTransfer.kind
      </code>
      
       (drag payload on <code>
        application/x-tip-block
      </code>
      
      )
    </td>
    
    <td>
      <code>
        BlockTransfer.blockType
      </code>
    </td>
    
    <td>
      an old payload is read, its <code>
        json
      </code>
      
       migrated
    </td>
  </tr>
</tbody>
</table>

Markdown needs no migration: the fence is `::: <Block type id> #id {meta}` before and after, so old Markdown parses to Typed blocks and the export is byte-identical.

The server migrates Yjs state when a document loads (`onLoadDocument`, before any client syncs): it reads the schema-less JSON of the stored state, applies the same JSON migration and writes the result back with the block IDs and content unchanged, then persists the migrated state. A second load finds nothing to migrate. Client JSON goes through the rename in `defineEditor`, which runs ahead of any contributed `migrateContent` (the Typed blocks feature contributes the legacy-node migration), so a host hook cannot drop it.

Settings version 2 renamed four keys (table below). Saved settings (server store, `localStorage`) migrate on load and are rewritten once. The host config key change needs a code change (no migration).

<table>
<thead>
  <tr>
    <th>
      Old
    </th>
    
    <th>
      New
    </th>
    
    <th>
      Where
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ai.slots
      </code>
    </td>
    
    <td>
      <code>
        ai.roles
      </code>
    </td>
    
    <td>
      settings; host config key (code change, no migration)
    </td>
  </tr>
  
  <tr>
    <td>
      wire key <code>
        slots
      </code>
      
       of <code>
        GET /api/ai/models
      </code>
    </td>
    
    <td>
      <code>
        roles
      </code>
    </td>
    
    <td>
      HTTP response
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blocks.defaultKind
      </code>
    </td>
    
    <td>
      <code>
        blocks.defaultBlockType
      </code>
    </td>
    
    <td>
      settings
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blocks.kindIcon
      </code>
    </td>
    
    <td>
      <code>
        blocks.blockTypeIcon
      </code>
    </td>
    
    <td>
      settings
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blocks.structure
      </code>
      
       value <code>
        'composite'
      </code>
    </td>
    
    <td>
      <code>
        'structured'
      </code>
    </td>
    
    <td>
      settings
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        KIND_ICON_VISIBILITIES
      </code>
      
      , <code>
        KindIconVisibility
      </code>
    </td>
    
    <td>
      <code>
        BLOCK_TYPE_ICON_VISIBILITIES
      </code>
      
      , <code>
        BlockTypeIconVisibility
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/settings
      </code>
      
       (code names, nothing stored)
    </td>
  </tr>
</tbody>
</table>


# Register the Nuxt module

> Register @skaile/forge-editor/nuxt in nuxt.config.ts, what the module wires into build, client and server, and which routes it mounts.

Nuxt apps use the same package entries as every other host; the module only adds the build and server wiring and one client plugin.

## Register the module

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  // @nuxt/ui first: the editor module patches its generated `ui.css` template.
  modules: ['@nuxt/ui', '@skaile/forge-editor/nuxt'],
  tiptapEditor: { ai: { /* see the AI configuration guide */ } },
})
```

Add `"@skaile/forge-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. Because the package is transpiled, Vite does not pre-bundle it; the module therefore adds the TipTap/ProseMirror/Yjs entries the editor imports to `vite.optimizeDeps.include` (merged with the host's list), so they share one ProseMirror with the pre-bundled `@tiptap/*` deps instead of failing with `RangeError: Adding different instances of a keyed plugin`. `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 (`src/nuxt/runtime/plugins/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.

The Nuxt module's server plugin installs the routes at the first request, after every Nitro plugin has run, so the host's `provideEditorServer({ ports })` call (`@skaile/forge-editor/server/nitro`) may sit in any plugin; host routes then reach the installed server with `useEditorServer()` (`forgetDocument`, `liveContent`, `enforceRateLimit`, `resolveModel`). Without provided ports the first request logs “@skaile/forge-editor: provideEditorServer() was not called” and the routes stay unmounted until a request succeeds in installing them. A route whose port the host did not register is not mounted at all (the path answers 404): `documents` routes always exist, `settings` needs the `settings` port, `users` the `directory` port, `assets`, `themes` and `comments` their ports, and `tags` follows from `documents`. The AI routes (`/api/ai/*`) are mounted by the module always, by a plain Nitro app when it passes `ai`. The collaboration websocket is mounted when the `collabState` port is present.

## Without an editor server

A host that serves no editor routes (a client-only editor, or a host with its own `/api/editor/*`) sets `server: false`:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@nuxt/ui', '@skaile/forge-editor/nuxt'],
  tiptapEditor: { server: false },
})
```

The module then adds only the build wiring: the stylesheets, `build.transpile`, the Vite pre-bundling, the Tailwind `@source` and the public AI configuration. It mounts no routes and no websocket, sets no server config and registers no client plugin, because that plugin's HTTP backend talks to the module's routes. The host installs the editor context itself (`createEditor` from `@skaile/forge-editor/vue`) with the backend it has, and calls no `provideEditorServer()`.


# Obsidian: import and export a vault

> The add-on @skaile/forge-editor-obsidian: importVault plans one Document per note with frontmatter as properties, wikilinks as reference chips and ^id block ids kept; exportVault writes them back; a command uploads a vault to an editor server.

The add-on `@skaile/forge-editor-obsidian` moves notes between an [Obsidian](https://obsidian.md) vault and the editor. The database stays canonical ([ADR-0001](https://github.com/skaile-ai/forge-editor/blob/main/docs/adr/0001-database-canonical-markdown-export.md)): a vault is a file format for import and export, the editor does not watch a folder and does not keep a vault in sync.

The add-on has no editor feature and no UI. It is a set of pure functions, a small upload helper and a command. The host needs **no wiring**: install the package where the script runs.

## Import

```ts
import { importVault } from '@skaile/forge-editor-obsidian'

const plan = importVault(files) // files: { path: 'Notes/Note B.md', text: '…' }[]
plan.documents // one PlannedDocument per note
plan.unresolved // links no note answers
plan.warnings // frontmatter or Templater code outside the supported subset, a missing heading or block id
plan.skipped // paths that are no notes (attachments, canvases, folders that start with a dot)
```

`importVault` writes nothing. Each `PlannedDocument` is `{ id, path, title, folder, template, properties, content }`. `content` is the Document's TipTap JSON: one Typed block of the Block type `document` that holds the note's blocks, so `[[Note]]` has a block to point at. Its `meta` is the note's frontmatter, its tags are the note's tags, its title is the file name.

<table>
<thead>
  <tr>
    <th>
      In the note
    </th>
    
    <th>
      In the Document
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Frontmatter keys (the subset <code>
        parseFrontmatter
      </code>
      
       reads: scalars, flow lists, block lists)
    </td>
    
    <td>
      <code>
        properties
      </code>
      
      , the <code>
        meta
      </code>
      
       of the wrapping block. Nested maps are reported in <code>
        warnings
      </code>
      
       and skipped
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tags
      </code>
      
      , <code>
        tag
      </code>
      
       in frontmatter
    </td>
    
    <td>
      The tags of the wrapping block, in the editor's tag name form (<code>
        Ideas/New
      </code>
      
       → <code>
        ideas/new
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aliases
      </code>
      
       in frontmatter
    </td>
    
    <td>
      Kept as a property, and used to resolve links
    </td>
  </tr>
  
  <tr>
    <td>
      Body
    </td>
    
    <td>
      The library's Markdown parser (the same one the server uses for <code>
        documentOps
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        text ^id
      </code>
      
       at the end of a paragraph or heading
    </td>
    
    <td>
      The block's <code>
        id
      </code>
      
       is that id; the marker leaves the text
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ^id
      </code>
      
       on a line of its own after a list, quote, table or code block
    </td>
    
    <td>
      The <code>
        id
      </code>
      
       of the block before it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [[Note]]
      </code>
    </td>
    
    <td>
      A <code>
        reference
      </code>
      
       chip to the note's wrapping block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [[Note#Heading]]
      </code>
      
      , <code>
        [[Note#^id]]
      </code>
    </td>
    
    <td>
      A chip to that heading or block; when the note has none, the chip points at the note and <code>
        warnings
      </code>
      
       says so
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [[Note|alias]]
      </code>
    </td>
    
    <td>
      The chip with the alias as its label
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [[#Heading]]
      </code>
    </td>
    
    <td>
      A chip to a heading of the same note
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ![[Note]]
      </code>
      
      , <code>
        ![[Note#Heading]]
      </code>
      
       alone in a paragraph
    </td>
    
    <td>
      A <code>
        blockEmbed
      </code>
      
       block (the whole note: its children; a heading or block: that block)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        [[Missing]]
      </code>
    </td>
    
    <td>
      Stays text, and is listed in <code>
        unresolved
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.date.now() %>
      </code>
    </td>
    
    <td>
      <code>
        {{date}}
      </code>
      
      , see below
    </td>
  </tr>
</tbody>
</table>

A link names its note by file name, by path (`[[folder/Note]]`) or by an `aliases` entry, without regard to case. Where several notes match, the one in the same folder wins, then the one with the shortest path. Links are resolved in a second pass, after every note has been read, so a link may point at a note that comes later in the vault.

### Block ids

The ids of blocks carry the links: a chip is `{ target: blockId, documentId }`. `importVault` keeps every `^id` as the block's `id` and gives all other blocks a new one. The first of a repeated id wins and the rest are reported in `warnings`. The ids are valid inside one Document only; a link `[[Note#^id]]` is resolved against the ids of that note.

### Templater

Templater is code, and none of it runs. A small subset has a Dokumentvorlage placeholder (see [Templates](https://skaile-ai.github.io/forge-editor/guides/templates)) and is translated:

<table>
<thead>
  <tr>
    <th>
      Templater
    </th>
    
    <th>
      Placeholder
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        <% tp.date.now() %>
      </code>
    </td>
    
    <td>
      <code>
        {{date}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.date.now("YYYY-MM-DD") %>
      </code>
    </td>
    
    <td>
      <code>
        {{date:iso}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.date.now("HH:mm") %>
      </code>
      
       (a clock format)
    </td>
    
    <td>
      <code>
        {{time}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.date.now("DD.MM.YYYY") %>
      </code>
      
      , <code>
        "L"
      </code>
    </td>
    
    <td>
      <code>
        {{date:short}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.date.now("LL") %>
      </code>
      
      , <code>
        "D MMM YYYY"
      </code>
    </td>
    
    <td>
      <code>
        {{date:medium}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.date.now("LLL") %>
      </code>
      
      , a format with <code>
        MMMM
      </code>
    </td>
    
    <td>
      <code>
        {{date:long}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.file.title %>
      </code>
    </td>
    
    <td>
      <code>
        {{title}}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        <% tp.file.cursor() %>
      </code>
    </td>
    
    <td>
      <code>
        {{cursor}}
      </code>
    </td>
  </tr>
</tbody>
</table>

Every other `<% … %>` stays as written and is named in `warnings`. The notes of the vault's templates folder (`templatesFolder`, default `Templates`, `null` for none) are planned into the folder `Dokumentvorlagen` and have `template: true`. A Document made from one of them through `documentCreate` with `templateId` gets the placeholders expanded.

### Options

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        markdown
      </code>
    </td>
    
    <td>
      The Markdown parser, <code>
        createMarkdownBlocks({ blockTypes })
      </code>
      
       of the host, when notes hold <code>
        :::
      </code>
      
       fences of the host's own Block types
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        templatesFolder
      </code>
    </td>
    
    <td>
      The vault's templates folder, default <code>
        Templates
      </code>
      
      , <code>
        null
      </code>
      
       for none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        newId
      </code>
    </td>
    
    <td>
      Where Document ids and missing block ids come from, default <code>
        crypto.randomUUID
      </code>
    </td>
  </tr>
</tbody>
</table>

## Create the Documents

Links between Documents name provisional ids. Create the Documents first, then swap the ids and store the content:

```ts
import { importVault, uploadVault } from '@skaile/forge-editor-obsidian'

const plan = importVault(files)
await uploadVault(plan.documents, { url: 'https://editor.example.com', token })
```

`uploadVault` calls `documentCreate` for every Document, then `documentPut` with the content after `bindDocumentIds` (`API` and `routeUrl` from `@skaile/forge-editor/core` name the routes). `token` goes out as `Authorization: Bearer <token>` and `cookie` as `Cookie: <cookie>`; what the host's `authenticate` makes of them is the host's choice. The Reference app reads its session cookie only, so a bearer token gets `401` there; use `cookie`. A Document goes into its folder when the server has it. The routes cannot create folders, so a note whose folder is missing lands in the root and `warn` says so. The routes do not know a note by its path: a second run creates the Documents again.

## Export

```ts
import { exportVault } from '@skaile/forge-editor-obsidian'

const files = exportVault(documents) // documents: { id, title, folder?, content }[] → { path, text }[]
```

One `.md` per Document, at `<folder>/<title>.md`; two Documents with the same path get ` (2)` added. The Markdown is the library's Markdown export (the same as the source mode), with these changes:

- A Document that is one Typed block of the Block type `document` (what `importVault` plans) is unwrapped: its `meta` and tags are the frontmatter, its body the text. A `derivation` or `edges` entry stays in the database.
- A reference chip or embed to a Document in the export becomes `[[Note]]`, `[[Note#Heading]]`, `[[Note#^id]]` or `![[…]]`, with the chip's label as the alias. Where two Documents share a title, the link names the path. A chip to a Document that is not in the export stays `[@…]`.
- A block that a link names gets its id as `^id`: at the end of a paragraph or heading or list item, else on a line of its own after the block. The ids that came from a vault (`intro`, `key-point`) are written for every block that has one. A block the editor numbered (a UUID) that no link names gets none: the database keeps that id (ADR-0001).
- A link that cannot name its block (the block sits inside a quote, or its id is not a legal Obsidian id) points at the note, and `warn` says so.
- Typed blocks of other types are written as `::: kind` fences. Obsidian shows them as text.

A vault that is exported and imported again keeps its notes' frontmatter, links and `^id` lines.

## Command

```sh
bunx @skaile/forge-editor-obsidian import ./MyVault --url https://editor.example.com --token $TOKEN
```

<table>
<thead>
  <tr>
    <th>
      Option
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --url
      </code>
    </td>
    
    <td>
      The editor server, also <code>
        EDITOR_URL
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --token
      </code>
    </td>
    
    <td>
      Sent as the bearer token (<code>
        Authorization: Bearer
      </code>
      
      ), also <code>
        EDITOR_TOKEN
      </code>
      
      ; for a host whose <code>
        authenticate
      </code>
      
       accepts a bearer token
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --cookie
      </code>
    </td>
    
    <td>
      Sent as the <code>
        Cookie
      </code>
      
       header, also <code>
        EDITOR_COOKIE
      </code>
      
      ; for a host with a session cookie
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --templates
      </code>
    </td>
    
    <td>
      The vault's templates folder (<code>
        ""
      </code>
      
       for none)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dry-run
      </code>
    </td>
    
    <td>
      Plan and print the counts, call nothing; <code>
        --url
      </code>
      
       is then optional
    </td>
  </tr>
</tbody>
</table>

It prints the warnings and unresolved links, and one line per Document with the id the server gave.

### Against the Reference app

The Reference app of this repository has no bearer tokens; it knows a caller by its session cookie. Sign in as one of its users with `POST /api/auth/switch` (`anna`, `ben` or `bernd`) and hand the `set-cookie` pair to `--cookie`:

```sh
COOKIE=$(curl -si -X POST http://localhost:3056/api/auth/switch -H 'content-type: application/json' -d '{"username":"anna"}' | grep -i '^set-cookie:' | sed 's/^[^:]*: *//; s/;.*//')
bunx @skaile/forge-editor-obsidian import ./MyVault --url http://localhost:3056 --cookie "$COOKIE"
```

`$COOKIE` is `nuxt-session=Fe26.2**…`. The Documents belong to that user.

## Not included

- Attachments (images, PDFs) are skipped. Obsidian canvases, Dataview queries, callouts' foldable state and inline `#tags` outside frontmatter stay as the Markdown parser reads them.
- No two-way sync. The `.obsidian` folder and every folder that starts with a dot are never read.


# PDF viewer: passages, anchors and quotes

> The add-on @skaile/forge-editor-pdf-viewer: the source-anchor property, a pdfjs viewer with a text layer, scrolling to a passage on reveal, and „Zitat anlegen“, which creates a quote block derived from the PDF.

The add-on `@skaile/forge-editor-pdf-viewer` shows a PDF next to the text that cites it. A text selection in the PDF becomes an **anchor**: the page, the area on the page and the quoted words. The button „Zitat anlegen“ turns the anchor into a `quote` Typed block that is [derived](https://skaile-ai.github.io/forge-editor/guides/derive-methods) from the PDF. A click on a [reference chip](https://skaile-ai.github.io/forge-editor/guides/citations) with a page locator scrolls the viewer to the passage.

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Where
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        source-anchor
      </code>
    </td>
    
    <td>
      the <a href="https://skaile-ai.github.io/forge-editor/guides/block-properties">
        Block property
      </a>
      
       type of a passage of a PDF
    </td>
    
    <td>
      library (<code>
        @skaile/forge-editor/core
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        page=<n>&anchor=<base64 JSON>
      </code>
    </td>
    
    <td>
      the reference locator that names such a passage
    </td>
    
    <td>
      library
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        quoteBlockTypes(locale)
      </code>
    </td>
    
    <td>
      the Block type <code>
        quote
      </code>
      
       with one <code>
        source-anchor
      </code>
      
       property
    </td>
    
    <td>
      editor and server
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        anchorOfSelection
      </code>
      
      , <code>
        quoteBlockOf
      </code>
    </td>
    
    <td>
      pure: selection to anchor, anchor to <code>
        quote
      </code>
      
       block
    </td>
    
    <td>
      anywhere
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pdfViewerFeature()
      </code>
    </td>
    
    <td>
      the viewer in the inspector of a Typed block that keeps a PDF
    </td>
    
    <td>
      editor
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PdfViewer
      </code>
    </td>
    
    <td>
      the viewer as a component for any page
    </td>
    
    <td>
      editor
    </td>
  </tr>
</tbody>
</table>

## The source-anchor property and the locator

A `source-anchor` value is `{ page, rects, quote: { exact, prefix?, suffix? } }`. `page` counts from 1. `rects` are fractions of the page (`x`, `y`, `w`, `h` from 0 to 1, origin top left), so the passage stays right at any zoom. `quote.exact` is the selected text with white space cut to single blanks; `prefix` and `suffix` are a little text around it.

The property kind orders and compares by page, reads as the quoted text and groups by page (`PROPERTY_KINDS['source-anchor']`), so a [query](https://skaile-ai.github.io/forge-editor/guides/query) can filter quotes by page or by words. The properties form shows page and quote read-only. Only the viewer writes the value.

The same passage as text is the locator of a reference chip: `page=12&anchor=<base64url JSON>`. `anchorLocatorOf(anchor)` writes it and `parseAnchorLocator(text)` reads it back (`null` when the text is not an anchor or its page differs from the locator's). Chips and backlinks show it as `S. 12`; the long base64 stays out of sight. A plain locator (`S. 12`, `12`, `3:07`) works as before.

When the editor reveals a source at an anchor locator, it sends two DOM events to the node view of the PDF's file block: `sk-reveal-page` (`detail` is the page) and `sk-reveal-anchor` (`detail` is the `SourceAnchor`). The viewer listens to both.

## Install and wire

```ts
import { defaultBlockTypes } from '@skaile/forge-editor/composites'
import { quoteBlockTypes } from '@skaile/forge-editor-pdf-viewer'
import { pdfViewerFeature } from '@skaile/forge-editor-pdf-viewer/vue' // or '/react'
import '@skaile/forge-editor-pdf-viewer/styles/pdf-viewer.css'

const editor = composeEditor({
  content: 'rich',
  interaction: 'full',
  // The Block types of the editor: the built-in ones and `quote`.
  blockTypes: [...defaultBlockTypes(t), ...quoteBlockTypes('de')],
  add: [pdfViewerFeature({ workerSrc: '/pdf.worker.min.mjs' })],
})
```

Give the Block type to the server too, so the schema, the AI chat and the query validation know it:

```ts
import { quoteBlockTypes } from '@skaile/forge-editor-pdf-viewer/server'

// installEditorServer({ blockTypes })
export const blockTypes = [...serverBlockTypes, ...quoteBlockTypes('de')]
```

pdfjs needs a worker. By default the viewer loads `pdf.worker.min.mjs` of the installed pdfjs version from jsDelivr. A host that cannot reach the CDN serves the file from `pdfjs-dist/build/` itself and passes its URL as `workerSrc` (feature option, or prop of `PdfViewer`).

## The viewer

`pdfViewerFeature` adds a section „PDF-Ansicht“ to the Typed block inspector. It shows for every block whose source (the `source` capability: `paper`, `book`, `document`) is a PDF file block. The viewer draws only the pages near the visible part, each as a canvas with a transparent text layer on top, so the text can be selected and searched with the browser.

- The toolbar has previous and next page, a page field, zoom out and in (50 % to 300 %).
- A reveal of the PDF's block scrolls to the page, or to the first line of the anchor, and marks the anchor's rects for a few seconds. Reveals of other blocks do not move this viewer.
- `PdfViewer` takes `src` (the URL of the PDF), `editor` (to create quotes and follow reveals) and `blockId` (the Typed block that keeps the PDF). Without `editor` it is a plain viewer.

## Create a quote

Select text in one page and press **Zitat anlegen**. The button works when the editor is editable and the PDF is a stored [asset](https://skaile-ai.github.io/forge-editor/guides/media-mentions-transcript) of a Document. The quote goes right behind the PDF's Typed block and is revealed.

```json
{
  "type": "typedBlock",
  "attrs": {
    "blockType": "quote",
    "meta": {
      "anchor": { "page": 12, "rects": [{ "x": 0.15, "y": 0.1, "w": 0.5, "h": 0.025 }], "quote": { "exact": "Der Hund bellt laut." } },
      "derivation": { "from": { "asset": "<name>.pdf" }, "method": "highlight", "inputHash": "<sha256 of the PDF>", "outputHash": "<sha256 of the body>", "createdAt": "…" }
    }
  }
}
```

The title is the first words of the quote. The body is the quoted text as a block quote and, when the PDF belongs to a Typed block, a reference chip to it whose locator is the anchor: a click on the chip in the quote opens the PDF at the passage. Because the quote has a Derivation, the block shows its origin, the [Explore trail](https://skaile-ai.github.io/forge-editor/guides/explore) lists it, and an edit of the body shows as „bearbeitet“.

`quoteBlockOf(asset, anchor, options)` builds the same JSON without a viewer: use it in an importer or a server tool.

```ts
import { anchorOfSelection, quoteBlockOf } from '@skaile/forge-editor-pdf-viewer/server'

const anchor = anchorOfSelection({ page: 3, box: pageRect, rects: selectionRects, text, pageText })
if (anchor) editor.commands.insertContent(quoteBlockOf({ name, hash }, anchor, { sourceBlockId: paperId }))
```


# Production

> Build and run a Nuxt host with the editor module: runtime secrets, persistent storage and shutdown behaviour.

```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 of [AI configuration and secrets](https://skaile-ai.github.io/forge-editor/guides/ai-configuration)), 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 server plugin's `installEditorServer` registers Nitro's `close` hook, which flushes pending debounced Yjs stores and disconnects the clients.


# Prüfung and Freigabestatus

> Record that a user checked a Typed block at one content state, derive the Freigabestatus, optionally lock checked blocks, and add your own chips and inspector sections.

A **Prüfung** is one immutable record that a user checked one Typed block at one content state, with a **kind** such as `redaktionell` or `fachlich`. The record stores the block ID, the SHA-256 hash of the checked text, the kind, who recorded it (`by`), when (`at`), an optional note and the checked text itself (`snapshot`). A Prüfung stays valid while the hash of its block is unchanged. When the block changes, the hash changes, and the old record no longer matches.

The **Freigabestatus** is derived from the records and the current hashes. It is never stored:

<table>
<thead>
  <tr>
    <th>
      Level
    </th>
    
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Block, per kind
    </td>
    
    <td>
      <code>
        geprueft
      </code>
    </td>
    
    <td>
      a record of this kind exists at the current hash
    </td>
  </tr>
  
  <tr>
    <td>
      
    </td>
    
    <td>
      <code>
        veraltet
      </code>
    </td>
    
    <td>
      records of this kind exist, none at the current hash
    </td>
  </tr>
  
  <tr>
    <td>
      
    </td>
    
    <td>
      <code>
        vorgeschlagen
      </code>
    </td>
    
    <td>
      no record of this kind, and the block is an AI proposal (a Derivation by the model, body not edited since); see <a href="https://skaile-ai.github.io/forge-editor/guides/export-check">
        AI proposals and the export check
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      
    </td>
    
    <td>
      <code>
        offen
      </code>
    </td>
    
    <td>
      no record of this kind
    </td>
  </tr>
  
  <tr>
    <td>
      Document
    </td>
    
    <td>
      <code>
        freigegeben
      </code>
    </td>
    
    <td>
      every Typed block whose Block type lists the <code>
        pruefung
      </code>
      
       capability is <code>
        geprueft
      </code>
      
       for all its kinds
    </td>
  </tr>
  
  <tr>
    <td>
      
    </td>
    
    <td>
      <code>
        offen
      </code>
    </td>
    
    <td>
      at least one such block is not
    </td>
  </tr>
</tbody>
</table>

A Prüfung is not a Block property. A property such as `status` is part of the document and any user who may edit the Block can write it. A Prüfung lives on the server outside the document, is written through its own route after a check of the user's right, and is pinned to the content ([ADR-0002](https://github.com/skaile-ai/forge-editor/blob/main/docs/adr/0002-pruefung-records-outside-the-document.md)). Records key on block IDs, which live in the database; the stored document is canonical and Markdown is an import/export format ([ADR-0001](https://github.com/skaile-ai/forge-editor/blob/main/docs/adr/0001-database-canonical-markdown-export.md)). A block that is copied or imported from Markdown gets a new ID and starts `offen`.

## Enable it

The `pruefung` Feature is in no level list of the presets. A host that composes with `composeEditor` opts in by id, next to the framework binding of the preset: `interaction: [...INTERACTION.full, 'pruefung']`. A host that lists features itself adds `pruefungFeature()`. The Feature `requires` the `composites` Feature and the backend capability `pruefung`; a surface over a backend without that capability throws, and `composeEditor` reports the feature in `omitted`.

<table>
<thead>
  <tr>
    <th>
      Entry
    </th>
    
    <th>
      Content
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @skaile/forge-editor/pruefung
      </code>
    </td>
    
    <td>
      framework-free: <code>
        pruefungFeature
      </code>
      
      , <code>
        pruefungFeatureCore
      </code>
      
      , <code>
        pruefungCapability
      </code>
      
      , <code>
        pruefungHash
      </code>
      
      , <code>
        pruefungMarkdown
      </code>
      
      , <code>
        isBlockLocked
      </code>
      
      , <code>
        UNLOCK_KIND
      </code>
      
      , <code>
        createPruefungModel
      </code>
      
      , <code>
        createRestPruefungModel
      </code>
      
      , <code>
        pruefungModelOf
      </code>
      
       and the types
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/pruefung/schema
      </code>
    </td>
    
    <td>
      Vue-free, server-importable: the record, route and store types and the capability config schema
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/pruefung/vue
      </code>
      
      , <code>
        @skaile/forge-editor/pruefung/react
      </code>
    </td>
    
    <td>
      <code>
        pruefungFeature
      </code>
      
       with the component of the Prüfstand section (<code>
        PruefungBadge
      </code>
      
      )
    </td>
  </tr>
</tbody>
</table>

The chips (Block, document) need no component: they come from the framework-free Feature. Only the inspector section is drawn by the binding, so import `pruefungFeature` from the `/vue` or `/react` entry to get it.

A Block type opts in by listing the `pruefung` capability in `capabilities`. The example gives the Block type `contract` two kinds, and adds the Feature to a preset:

```ts [docs/snippets/pruefung-preset.ts]
import { compositeFeature } from '@skaile/forge-editor/composites/vue'
import { type BlockType, defaultBlockTypes } from '@skaile/forge-editor/composites/schema'
import { coreContentFeature, coreUiFeature, createTranslator, defineEditor } from '@skaile/forge-editor/core'
import { pruefungFeature } from '@skaile/forge-editor/pruefung'

// A Block type opts into the capability and configures it.
const contract: BlockType = {
  id: 'contract',
  label: 'Vertrag',
  icon: 'i-lucide-file-signature',
  capabilities: [
    { id: 'container', config: { accepts: 'all' } },
    { id: 'pruefung', config: { kinds: ['redaktionell', 'fachlich'] } },
  ],
}

const blockTypes = [...defaultBlockTypes(createTranslator('de')), contract]

// A Block type that lists a capability no Feature declares throws when the editor is created; so does a block action that
// `requires` an undeclared id, when the actions are collected.
export const preset = defineEditor({
  features: [
    coreContentFeature(),
    coreUiFeature(),
    compositeFeature({ blockTypes }),
    pruefungFeature(),
  ],
})
```

Block capabilities in general are described in [Block capabilities](https://skaile-ai.github.io/forge-editor/guides/block-capabilities); the shape of `pruefungCapability` is the worked example there. A Block type that does not list `pruefung` has no Prüfung: no action, no chip, no section.

## The capability config

The config is validated when the editor is created (`z.strictObject`: an unknown key throws).

<table>
<thead>
  <tr>
    <th>
      Key
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        kinds
      </code>
    </td>
    
    <td>
      <code>
        string[]
      </code>
      
      , at least one
    </td>
    
    <td>
      the kinds a block of this type takes, in order
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        chain
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
      
      , default <code>
        false
      </code>
    </td>
    
    <td>
      a kind can be recorded only when every kind before it has a record at the block's current hash
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        lock
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
      
      , optional
    </td>
    
    <td>
      the kind whose Prüfung locks the block against edits while it is <code>
        geprueft
      </code>
      
       (<a href="#lock">
        Lock
      </a>
      
      )
    </td>
  </tr>
</tbody>
</table>

## What the hash covers

The hash is the SHA-256 (hex) of the title line, a blank line and the body Markdown of the block (`pruefungMarkdown`, `pruefungHash`). The same text is the `snapshot` of the record. A changed title or body makes the Prüfung `veraltet`. These are not covered, so changing them leaves a Prüfung valid: `meta` (Block properties, Derivation), tags, description, Baskets and the title visibility.

## Who may record

Recording needs two things.

- **The ability pruefung.record** (`ABILITY.pruefungRecord`, from `@skaile/forge-editor/core/schema`). No ability list contains it by default. A host grants it per mount through the `abilities` prop, for example `{ root: [...ROOT_ABILITIES, ABILITY.pruefungRecord] }`. Without it the block actions „Prüfung eintragen“ and „Sperre aufheben“ do not show.
- **The right of the user on the server.** `GET` and `POST /api/editor/pruefung/:id` answer `kinds`, the kinds that the requesting user may record. A read-only user gets `[]`. Otherwise `AccessControl.pruefungKinds(user, id)` decides; when the host does not define it, every user who may edit gets the sentinel `['*']`, which the client reads as every configured kind.

`AccessControl.pruefungKinds` returns the kind names that the user may record in that document:

```ts
const identity: AccessControl = {
  // ...authenticate, authorize
  async pruefungKinds(user, id) {
    return isEditorialStaff(user) ? ['redaktionell'] : ['redaktionell', 'fachlich', 'entsperrt']
  },
}
```

A list that names kinds explicitly applies exactly. A user who may lift a lock needs `entsperrt` (`UNLOCK_KIND`) in it, because „Sperre aufheben“ records that kind. A client shows an action only for a kind in `kinds`; the server enforces it again.

## The server port

The route group needs the port `pruefung` of `EditorPorts`, a `PruefungStore` (`@skaile/forge-editor/pruefung/schema`):

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        list(documentId)
      </code>
    </td>
    
    <td>
      the records of one document, oldest first; empty for an unknown document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        record(entry)
      </code>
    </td>
    
    <td>
      stores <code>
        entry
      </code>
      
       under a new ID and returns the record
    </td>
  </tr>
</tbody>
</table>

Records are never changed or deleted: a later check is a new record. The port provides the backend capability `pruefung`; without it the server mounts no Prüfung route and the Feature is not available. `createJsonAdapter` (`@skaile/forge-editor/adapters/json`) wires a JSON store that keeps the records of all documents in one file, `.pruefung.json`, in the adapter's data directory (a dot-named file, so it is not read as a document). A host with its own database implements `PruefungStore` and passes it as `ports.pruefung`.

The routes:

<table>
<thead>
  <tr>
    <th>
      Route
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/editor/pruefung/:id
      </code>
    </td>
    
    <td>
      answers <code>
        { records, kinds }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/pruefung/:id
      </code>
    </td>
    
    <td>
      body <code>
        { blockId, hash, kind, note?, snapshot, kinds, chain }
      </code>
      
      ; records one Prüfung and answers <code>
        { records, kinds }
      </code>
    </td>
  </tr>
</tbody>
</table>

`kinds` and `chain` in the body echo the capability config. The server uses only their order to apply `chain`; it never takes a right from them. It computes the stored `hash` itself, from `snapshot`.

### Refusals

A refused `POST` answers an error whose data is `{ reason }`. A client switches on `reason`, not on the message. The checks run in this order:

<table>
<thead>
  <tr>
    <th>
      Reason
    </th>
    
    <th>
      HTTP
    </th>
    
    <th>
      Message
    </th>
    
    <th>
      When
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      (none)
    </td>
    
    <td>
      400
    </td>
    
    <td>
      <code>
        Ungültiger JSON-Body
      </code>
    </td>
    
    <td>
      the body is not JSON or a member has the wrong type, or <code>
        blockId
      </code>
      
      , <code>
        hash
      </code>
      
       or <code>
        kind
      </code>
      
       is empty
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        role
      </code>
    </td>
    
    <td>
      403
    </td>
    
    <td>
      <code>
        Keine Berechtigung für diese Prüfung
      </code>
    </td>
    
    <td>
      the user is read-only, or may not record this kind
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        stale
      </code>
    </td>
    
    <td>
      409
    </td>
    
    <td>
      <code>
        Der Block hat sich seit der Prüfung geändert
      </code>
    </td>
    
    <td>
      the SHA-256 of <code>
        snapshot
      </code>
      
       is not <code>
        hash
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        duplicate
      </code>
    </td>
    
    <td>
      409
    </td>
    
    <td>
      <code>
        Diese Prüfung liegt für diesen Stand bereits vor
      </code>
    </td>
    
    <td>
      the block already has a record of this kind at this hash
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        needs-<kind>
      </code>
    </td>
    
    <td>
      409
    </td>
    
    <td>
      <code>
        Zuerst ist die Prüfung „<kind>“ nötig
      </code>
    </td>
    
    <td>
      <code>
        chain
      </code>
      
       is on and <code>
        <kind>
      </code>
      
      , an earlier kind in <code>
        kinds
      </code>
      
      , has no record at this hash
    </td>
  </tr>
</tbody>
</table>

The REST model shows the message of a refused `record` as a warning notice. `stale` is weaker than its name: the server has no Markdown serializer for a block, so it cannot rebuild the current text from the document. It proves only that `snapshot` and `hash` belong together. The client builds both from the live block, so a block that changed between the click and the answer is the client's case ([ADR-0002](https://github.com/skaile-ai/forge-editor/blob/main/docs/adr/0002-pruefung-records-outside-the-document.md), Consequences).

A kind that is not in `kinds` (the unlock record `entsperrt`) is not part of the chain.

## Lock

`lock: '<kind>'` in the capability config locks a block while that kind is `geprueft` at the block's current hash. The lock is a transaction guard, not a stored flag. A local edit inside a locked block is dropped whole and the editor shows the notice „Block ist freigegeben und gesperrt“. The guard hashes only the blocks that a transaction touches and only those whose Block type sets `lock`. Transactions that carry what another user wrote (Yjs sync) pass, because refusing them would make this client differ from the shared document.

The block action „Sperre aufheben“ (ability `pruefung.record`; visible only on a locked block, for a user whose `kinds` include `entsperrt`) records a Prüfung of kind `entsperrt` at the current hash. A block with such a record at its current hash is not locked, and the history of who lifted the lock stays in the records. After the next edit the hash changes, the kind is `veraltet` and the lock is off until someone records the kind again. Any change of the hash lifts the lock, including a collaborator's edit or an import.

## What the user sees

<table>
<thead>
  <tr>
    <th>
      Where
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Block action „Prüfung eintragen“
    </td>
    
    <td>
      with one recordable kind, a click records it; with several, a menu lists the kinds and shows „Für diesen Stand geprüft“ for kinds that are already <code>
        geprueft
      </code>
      
      . Kinds that the user may not record are not listed
    </td>
  </tr>
  
  <tr>
    <td>
      Chip after the title of a block
    </td>
    
    <td>
      „Geprüft“ (success) when every kind is <code>
        geprueft
      </code>
      
      ; „Prüfung veraltet“ (warning) when a kind is <code>
        veraltet
      </code>
      
      ; nothing otherwise
    </td>
  </tr>
  
  <tr>
    <td>
      Inspector and details card, section „Prüfstand“
    </td>
    
    <td>
      the kinds with their status, the records (kind, user, date, note), and „Geprüften Stand anzeigen“, which shows the checked text and the current text in two read-only columns, without a diff
    </td>
  </tr>
  
  <tr>
    <td>
      „Dokument“ header of the inspector, and the open document's row in the Block outline of the Document tree
    </td>
    
    <td>
      the Freigabestatus: „Freigegeben“, or „Offen (n Blöcke)“; nothing while no block opts in
    </td>
  </tr>
</tbody>
</table>

## Add your own chips and sections

The composites Feature draws the chips and sections of other Features and knows nothing about Prüfung. Three optional members of `EditorFeature` (`@skaile/forge-editor/core`) carry them; all three are additive in Feature order and the factory runs once per surface:

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Contribution
    </th>
    
    <th>
      Drawn
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        rowBadges(ctx)
      </code>
    </td>
    
    <td>
      <code>
        RowBadge[]
      </code>
      
      : <code>
        { id, of(editor, row), subscribe? }
      </code>
      
      ; <code>
        of
      </code>
      
       returns a <code>
        BadgeChip
      </code>
      
       (<code>
        { label, tone: 'success' | 'warning' }
      </code>
      
      , label already translated) or <code>
        null
      </code>
    </td>
    
    <td>
      after the title of a Typed block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        documentBadges(ctx)
      </code>
    </td>
    
    <td>
      <code>
        DocumentBadge[]
      </code>
      
      : the same, <code>
        of(editor)
      </code>
      
       without a row
    </td>
    
    <td>
      after the „Dokument“ heading of the inspector and on the open document's row of the Block outline
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inspectorSections(ctx)
      </code>
    </td>
    
    <td>
      <code>
        InspectorSection<C>[]
      </code>
      
      : <code>
        { id, title, component, appliesTo? }
      </code>
      
      ; the component of the framework layer receives <code>
        { editor, node }
      </code>
    </td>
    
    <td>
      below the fields of a Typed block in the inspector and the details card
    </td>
  </tr>
</tbody>
</table>

`of` runs for every row on every redraw, so it must stay cheap: look at `row.capabilities` first. `subscribe(editor, listener)` reports changes of what `of` reads that are not editor transactions (the Prüfung model loads its records later); the chrome calls `of` again after each `listener` call, and `subscribe` returns the unsubscribe function. This Feature puts a chip on every block whose `meta.status` is `entwurf`:

```ts
import type { EditorFeature, RowBadge } from '@skaile/forge-editor/core'

const draftChip: RowBadge = {
  id: 'draft',
  of: (editor, row) =>
    editor.state.doc.nodeAt(row.pos)?.attrs.meta?.status === 'entwurf'
      ? { label: 'Entwurf', tone: 'warning' }
      : null,
}

export const draftFeature: EditorFeature = {
  id: 'draft-chip',
  dimension: 'interaction',
  requires: ['composites'],
  rowBadges: () => [draftChip],
}
```

`pruefungFeatureCore(ui, options)` is the same Feature without a framework: `ui.section` is the component of the Prüfstand, and without `ui` the Feature adds no section. `PruefungFeatureOptions.model` replaces the REST model with a factory for a host's own store; the Feature then needs no `pruefung` backend capability. For the model, `pruefungModelOf(editor)` gives `state`, `refresh`, `record(blockId, kind, note?)`, `mayRecord(kind)`, `statusOf(node)` and `freigabeOf(editor)` (`{ status, open, total }`).


# Query: filter, sort, group and total Blocks

> The DataQuery model, its pseudo-fields and operators per property kind, the evaluator, the BlockIndex.query port method, the route, the client call and the find_blocks tool.

A **query** (`DataQuery`, `@skaile/forge-editor/core`) asks the Block index for the Blocks of one or several Block types: which Documents, which Properties, in which order, grouped how, totalled how. A query is data. It is a JSON object that a view stores in a Typed block's `meta`, that the client sends over HTTP, and that the document chat builds in a tool call. One evaluator, `evaluateQuery`, answers all of them.

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Port (capability)
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        DataQuery
      </code>
      
      , <code>
        DataResult
      </code>
      
      , <code>
        QueryIssue
      </code>
    </td>
    
    <td>
      the query and its answer (<code>
        @skaile/forge-editor/core
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validateQuery(defs, query)
      </code>
    </td>
    
    <td>
      the issues of a query: unknown field, operator the type does not take, wrong value
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        evaluateQuery(rows, defs, query, env)
      </code>
    </td>
    
    <td>
      filters, searches, sorts, groups, totals and pages the rows
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BlockIndex.query(query, scope, env, definitions?)
      </code>
    </td>
    
    <td>
      answers a query over the Documents in <code>
        scope
      </code>
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/query
      </code>
    </td>
    
    <td>
      the same over HTTP
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EditorBackend['index'].query
      </code>
    </td>
    
    <td>
      the client call
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        find_blocks
      </code>
      
       with <code>
        blockType
      </code>
      
       and <code>
        filter
      </code>
    </td>
    
    <td>
      the document chat lists Blocks by their Properties
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
</tbody>
</table>

## The query

```json
{
  "v": 1,
  "source": { "kind": "blocks", "blockType": "task", "scope": { "documentIds": ["plan"] } },
  "filter": { "and": [
    { "field": "status", "op": "eq", "value": "done" },
    { "field": "points", "op": "gte", "value": 3 }
  ] },
  "search": { "q": "angebot" },
  "sorts": [{ "field": "due", "dir": "asc", "nulls": "last" }],
  "group": { "field": "$basket", "hideEmpty": true },
  "aggregates": [{ "fn": "sum", "field": "points", "as": "total" }],
  "select": ["status", "points", "due"],
  "page": { "limit": 50 }
}
```

- `source.blockType` is one Block type id or a list. A Typed block's type is its `blockType`; any other Block has its node type (`paragraph`, `heading`, …). `source.scope` narrows further: `documentIds`, `tags` (a row needs one of them), `basket`. `subtreeOf` is not applied: the index does not know the nesting, and the answer says so with a warning.
- `filter` is a condition `{ field, op, value? }` or `{ and: [...] }` / `{ or: [...] }`, nested as deep as needed. An empty `and` holds, an empty `or` does not.
- `search.q` uses the words rule of the workspace search: every word must match, as a whole word or as the start of one. Without a `sorts` entry that decides, the best match comes first.
- `sorts`: the first entry that tells two rows apart wins. A row without a value sorts last; `nulls: 'first'` turns that around.
- `group` partitions the page into `groups`. The groups follow the order of the property's options (a `status` group `todo`, `doing`, `done` as declared), else the order of first appearance; the group without a value (`key: null`) is last unless `hideEmpty`.
- `aggregates` (`count`, `sum`, `avg`, `min`, `max`) are computed over **all** matching rows, not just the page, and answered under `as`.
- `select` lists the property keys and pseudo-fields to put in `DataRow.values`. Absent: every property of the Block.
- `page.limit` is at most `MAX_QUERY_ROWS` (1000). `nextCursor` of an answer goes into `page.cursor` of the next request. The cursor is the base64 of the row offset, so a page is not stable if Blocks change between two calls.

## Fields

A field is a property key of the Block types in the source, or a pseudo-field:

<table>
<thead>
  <tr>
    <th>
      Pseudo-field
    </th>
    
    <th>
      Value
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        $title
      </code>
    </td>
    
    <td>
      the title of a Typed block, the text of a heading
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $tags
      </code>
    </td>
    
    <td>
      the tag names in the Block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $type
      </code>
    </td>
    
    <td>
      the Block type id or node type
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $id
      </code>
    </td>
    
    <td>
      the block ID
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $doc
      </code>
    </td>
    
    <td>
      the Document ID
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        $basket
      </code>
    </td>
    
    <td>
      the colour basket of a Typed block
    </td>
  </tr>
</tbody>
</table>

Property keys must not start with `$`; `propertyDefinitionSchema` refuses them.

## Operators per property kind

Which operators, sort key, group key and aggregates apply is the property kind's entry in `PROPERTY_KINDS` (`core/property-kinds.ts`); the query does not branch on the type itself.

<table>
<thead>
  <tr>
    <th>
      Kind
    </th>
    
    <th>
      Operators
    </th>
    
    <th>
      Aggregates
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        text
      </code>
      
      , <code>
        textarea
      </code>
      
      , <code>
        url
      </code>
    </td>
    
    <td>
      <code>
        eq
      </code>
      
       <code>
        ne
      </code>
      
       <code>
        contains
      </code>
      
       <code>
        startsWith
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        eq
      </code>
      
       <code>
        ne
      </code>
      
       <code>
        lt
      </code>
      
       <code>
        lte
      </code>
      
       <code>
        gt
      </code>
      
       <code>
        gte
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
      
       <code>
        sum
      </code>
      
       <code>
        avg
      </code>
      
       <code>
        min
      </code>
      
       <code>
        max
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        date
      </code>
    </td>
    
    <td>
      <code>
        eq
      </code>
      
       <code>
        ne
      </code>
      
       <code>
        before
      </code>
      
       <code>
        after
      </code>
      
       <code>
        on
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
      
       <code>
        min
      </code>
      
       <code>
        max
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        select
      </code>
      
      , <code>
        status
      </code>
      
      , <code>
        reference
      </code>
    </td>
    
    <td>
      <code>
        eq
      </code>
      
       <code>
        ne
      </code>
      
       <code>
        hasAny
      </code>
      
       <code>
        hasNone
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        multiselect
      </code>
      
      , <code>
        reference-list
      </code>
    </td>
    
    <td>
      <code>
        hasAny
      </code>
      
       <code>
        hasAll
      </code>
      
       <code>
        hasNone
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checkbox
      </code>
    </td>
    
    <td>
      <code>
        eq
      </code>
      
       <code>
        ne
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bibliography
      </code>
    </td>
    
    <td>
      <code>
        contains
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivation
      </code>
    </td>
    
    <td>
      <code>
        eq
      </code>
      
       <code>
        ne
      </code>
      
       <code>
        contains
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source-anchor
      </code>
    </td>
    
    <td>
      <code>
        eq
      </code>
      
       <code>
        ne
      </code>
      
       <code>
        lt
      </code>
      
       <code>
        lte
      </code>
      
       <code>
        gt
      </code>
      
       <code>
        gte
      </code>
      
       <code>
        contains
      </code>
      
       <code>
        isEmpty
      </code>
      
       <code>
        isNotEmpty
      </code>
    </td>
    
    <td>
      <code>
        count
      </code>
      
       <code>
        min
      </code>
      
       <code>
        max
      </code>
      
       (the page; <code>
        contains
      </code>
      
       reads the quoted text)
    </td>
  </tr>
</tbody>
</table>

Dates: `on` compares the calendar day in `env.timeZone` (a plain `YYYY-MM-DD` is that day whatever the time zone), `before` and `after` compare the instant (a plain day counts as its start in UTC). Text sorts by the collation of `env.locale`, numerically where it holds numbers (`item 2` before `item 10`).

`env` (`QueryEnv`) carries `locale`, `timeZone`, `now` and `me`. The evaluator is pure: the same rows, query and env give the same answer.

## Which Property definitions apply

`evaluateQuery(rows, defs, …)` types a field by `defs`. On the server, `defs` are the `properties` capability of the host's Block types (`EditorServerOptions.blockTypes`) that the query's source names, merged, the first definition of a key winning (`queryDefinitionsOf` in `@skaile/forge-editor/server`). A property that no Block type declares is not an error: the evaluator infers a kind from the values of the rows (a boolean is a `checkbox`, a number a `number`, a date-like text a `date`, other text `text`, a list of addresses a `reference-list`, a list of text a `multiselect`; the first value of a key decides). A key that no row has is an `unknown-field`. So a host with no `blockTypes` configured still answers queries over `task` Blocks, just without option order or status groups.

An error issue means no rows: the answer has `rows: []`, `total: 0` and the issues. A warning (a `select` entry nobody has, `subtreeOf`) is answered along with the rows.

## The port, the route and the client

`BlockIndex.query(query, scope, env, definitions?)` answers a query over the Blocks of the Documents in `scope`. `source.scope.documentIds` narrows the scope and never widens it (`narrowScope`). The memory adapter runs `evaluateQuery` over its rows. The drizzle adapter loads the rows of the source's Block types per Document with one SQL statement and evaluates in JS; a database-specific adapter may push parts of the filter into SQL as long as it gives the answer `evaluateQuery` gives (the `BlockIndex` contract in `test/support/block-index-contract.ts` checks this). A custom `BlockIndex` must implement `query`; the quickest way is `evaluateQuery` over `byDocument`.

`POST /api/editor/query` takes `{ query, env? }` (`QueryRequestBody`; `env` has `locale` and `timeZone`, defaulting to the first `Accept-Language` tag `Intl` knows and `UTC`). It answers a `DataResult` for the Documents the user may read (`readableDocumentsOf`). `401` without a user, `400` for a body that is no query, `422` when the query has an error issue (the error's `data` lists the issues), `501` without the `index` port.

```ts
const result = await backend.index.query({
  v: 1,
  source: { kind: 'blocks', blockType: 'task' },
  filter: { field: 'status', op: 'eq', value: 'done' },
  group: { field: '$basket' },
})
for (const group of result.groups ?? []) console.log(group.key, group.rows.length)
```

`EditorBackend.index.query?(query, { env?, signal? })` is optional: a backend without it leaves data views out. It rejects with `BackendError` (`422`, `data` = the issues) for an invalid query. The HTTP backend sends the browser's time zone unless `env` says otherwise.

## The document chat

`find_blocks` (`createWorkspaceTools()`) gains two inputs:

- `blockType` lists the Blocks of that type (all of them without a `filter`);
- `filter` is a `FilterNode` over their Properties, and needs `blockType`.

With `query` as well, only the hits of the search come back. Each hit then carries its `values`. A filter that does not fit the type comes back to the model as a sentence (`Ungültige Abfrage: …` naming the field and the operators the type takes), so it can correct the call. Without `blockType` the tool works as before: a search by words.


# Render: export a Block or a Document to a file

> The Renderer port with its render targets, the SSE route that streams progress and stores the result as an asset, the client call, and the block action and command that offer it.

A **render target** turns one Typed block, or a whole Document, into a file: Markdown, a PDF, a slide deck, a spoken recording. The editor ships one target, `markdown`. A host or an add-on contributes the others. The `render` capability connects the pieces:

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Port (capability)
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        Renderer
      </code>
    </td>
    
    <td>
      lists the targets a user may use and renders one input to one target
    </td>
    
    <td>
      <code>
        render
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /api/editor/render/targets
      </code>
    </td>
    
    <td>
      the targets with the Block types each accepts and its MIME type
    </td>
    
    <td>
      <code>
        render
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/render
      </code>
    </td>
    
    <td>
      one render, streamed as server-sent events; the result is stored as an asset of the Document
    </td>
    
    <td>
      <code>
        render
      </code>
      
       and <code>
        assets
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EditorBackend['render']
      </code>
    </td>
    
    <td>
      <code>
        targets()
      </code>
      
       and <code>
        render(target, input, { onProgress })
      </code>
    </td>
    
    <td>
      <code>
        render
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Block action <code>
        render
      </code>
      
       and command <code>
        render-document
      </code>
    </td>
    
    <td>
      menus of the targets that take the Block type, or the whole Document
    </td>
    
    <td>
      <code>
        render
      </code>
    </td>
  </tr>
</tbody>
</table>

A render lives as long as its request. There is no job store: the server streams progress while the target runs, stores the file, and ends the stream. A client that disconnects aborts the target through the `AbortSignal` that `Renderer.render` receives.

## Add a target

A target (`RenderTarget`, `@skaile/forge-editor/adapters/render`) is a `RenderTargetInfo` (`id`, `label`, `accepts`, `mime`) plus `run`. `accepts` lists Block type ids, and `'document'` for a whole Document. `run` receives the input (`documentId`, `blockId?`, `content`, `options?`), a `progress` reporter and an `AbortSignal`, and returns `{ data, mime, fileName }`. `createRenderer(targets)` makes the `Renderer` of the host's `ports.render`. A target whose `id` repeats an earlier one is dropped, so a host can list its own before the defaults.

```ts [docs/snippets/render-target.ts]
import { createRenderer, markdownTarget, type RenderTarget } from '@skaile/forge-editor/adapters/render'
import type { EditorPorts } from '@skaile/forge-editor/server'

// A render target names the Block types (or 'document') it accepts and the MIME type it produces. `run` reports its
// steps through `progress` and returns the file; a thrown error reaches the client as the `error` event.
const plainText: RenderTarget = {
  id: 'plain-text',
  label: 'Text (.txt)',
  accepts: ['document'],
  mime: 'text/plain',
  async run({ content }, progress) {
    progress({ phase: 'collect', percent: 50 })
    const text = JSON.stringify(content)
    return { data: new TextEncoder().encode(text), mime: 'text/plain', fileName: 'document.txt' }
  },
}

// The renderer is one port: the host passes its targets, the built-in `markdown` among them.
export const render: NonNullable<EditorPorts['render']> = createRenderer([markdownTarget(), plainText])
```

A host that needs its own target logic, for example a per-user list, implements the `Renderer` interface directly instead of calling `createRenderer`. See the [Renderer port reference](https://skaile-ai.github.io/forge-editor/reference/renderer-port).

## The built-in `markdown` target

`markdownTarget(options?)` renders a Typed block or a whole Document as Markdown, the same text the block action "Als Markdown exportieren" downloads: every Typed block becomes a heading with its description, tags and body beneath it. It accepts `'document'` and every Block type, takes `schema` and `blockTypes` options for a host with its own Block types, and needs no editor, only the schema.

## The route

`POST /api/editor/render` takes `{ target, input }`. The server checks the request before the stream starts:

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Cause
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      malformed body or a Document ID that is not valid
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        401
      </code>
    </td>
    
    <td>
      no user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        403
      </code>
    </td>
    
    <td>
      the user may not read the Document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      unknown target
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        422
      </code>
    </td>
    
    <td>
      the target does not accept this Block type, or a whole Document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        501
      </code>
    </td>
    
    <td>
      the host has no <code>
        render
      </code>
      
       or no <code>
        assets
      </code>
      
       port
    </td>
  </tr>
</tbody>
</table>

After that the answer is a `text/event-stream` with the events `progress` (`{ phase, percent? }`), then `done` (`{ asset, fileName, mime }`) or `error` (`{ message }`). The result is stored through `ports.assets.storeAsset` as an asset of `input.documentId`. `asset` is the asset name: read it with the asset route (`GET /api/editor/assets/:documentId/:asset`), like any upload.

## The client

`backend.render` is present when the server serves the `render` capability. `backend.render.render(target, input, { onProgress, signal })` resolves with `{ asset, fileName, mime, url }` and rejects with the server's message when the render fails. The loop over the stream is `postSse` (`core/sse.ts`), the same helper the AI streams use (`postAiSse` calls it), so there is one parser for server-sent events in the client.

## In the editor

The composites feature adds both entries when the backend serves `render`, and hides them otherwise:

- the block action **„Erzeugen als …“** (`render`) on a Typed block, a menu of the targets whose `accepts` names the Block type;
- the command **„Dokument erzeugen als …“** (`render-document`, ⌘K palette), a menu of the targets that accept `'document'`.

A notice reports the phase and percent of the running render, then the end. The finished file downloads at once.


# Server routes and authentication

> How every editor route authenticates through the identity port, the full route table with status codes, and websocket authentication.

Every route authenticates through `ports.identity.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)).

## Routes

<table>
<thead>
  <tr>
    <th>
      Method
    </th>
    
    <th>
      Path
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      WS
    </td>
    
    <td>
      <code>
        /collab/:id
      </code>
    </td>
    
    <td>
      Hocuspocus sync; the document name comes from the provider's <code>
        name
      </code>
      
      . Yjs state is the source of truth; JSON is mirrored via <code>
        storeContent
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/ai/models
      </code>
    </td>
    
    <td>
      Model presets without keys + default Model roles (not rate limited)
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/ai/complete
      </code>
    </td>
    
    <td>
      Ghost text: <code>
        { before, model }
      </code>
      
       → <code>
        { text }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/ai/generate
      </code>
    </td>
    
    <td>
      Task run → SSE <code>
        delta
      </code>
      
       / <code>
        done
      </code>
      
       / <code>
        error
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/ai/chat
      </code>
    </td>
    
    <td>
      Document chat/agent → SSE <code>
        delta
      </code>
      
      , <code>
        tool
      </code>
      
       (a read-only tool call the server ran), <code>
        ops
      </code>
      
      , <code>
        done
      </code>
      
      , <code>
        error
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/ai/transcript-cleanup
      </code>
    </td>
    
    <td>
      <code>
        { segments, model }
      </code>
      
       → <code>
        { cleaned, failed }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/ai/extract
      </code>
    </td>
    
    <td>
      <code>
        { documentId, name, method, model, bibliography?, doi?, maxPages? }
      </code>
      
       → <code>
        { method, markdown, segments?, bib?, model?, inputHash, outputHash, output, warnings }
      </code>
      
       (<code>
        model
      </code>
      
      : the speech-to-text model of a transcription). Turns a stored asset into readable Markdown: <code>
        method
      </code>
      
       <code>
        auto
      </code>
      
       picks by MIME type (audio/video → <code>
        transcription
      </code>
      
       with segment timestamps, via <code>
        ai.transcription
      </code>
      
      , 501 without it, 413 over 25 MB; image → <code>
        description
      </code>
      
      ; PDF → <code>
        pdf-text
      </code>
      
      , or <code>
        ocr
      </code>
      
       when the text layer averages under 50 characters per page; anything else 415), <code>
        bibliography
      </code>
      
       reads a CSL item from Crossref by DOI (body, or found in the first two pages) and falls back to the model (<code>
        warnings: ['crossref-unavailable']
      </code>
      
      ). <code>
        ocr
      </code>
      
       and <code>
        description
      </code>
      
       use the request's <code>
        model
      </code>
      
       and need a vision-capable one. OCR makes one model call per page, so it reads at most 50 pages (fewer when <code>
        maxPages
      </code>
      
       is lower); skipped pages add <code>
        warnings: ['ocr-truncated']
      </code>
      
      . PDF reading uses <code>
        pdfjs-dist
      </code>
      
      ; page rasterisation for OCR uses the optional dependency <code>
        @napi-rs/canvas
      </code>
      
       (without it a PDF with a text layer answers <code>
        warnings: ['ocr-unavailable']
      </code>
      
      , a scan answers 501). Aborting the request stops the page loops between pages. In <code>
        markdown
      </code>
      
       every PDF page after the first starts with a <code>
        <!-- page N -->
      </code>
      
       line; the client turns it into a page label paragraph and the stored raw output keeps it. The raw Markdown is stored as a <code>
        text/markdown
      </code>
      
       asset (<code>
        output
      </code>
      
       is its name, <code>
        null
      </code>
      
       for <code>
        bibliography
      </code>
      
      ); <code>
        inputHash
      </code>
      
       is the SHA-256 hex of the asset bytes, <code>
        outputHash
      </code>
      
       the SHA-256 hex of that stored raw output (the client hashes its own re-serialised body for edit detection and ignores it).
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/editor/users?q=
      </code>
    </td>
    
    <td>
      <code>
        @
      </code>
      
       popup: up to 20 users
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/editor/capabilities
      </code>
    </td>
    
    <td>
      The capabilities this server serves, as <code>
        BackendCapability[]
      </code>
      
       (<code>
        serverCapabilities(ports)
      </code>
      
      , with <code>
        ai
      </code>
      
       and <code>
        collaboration
      </code>
      
       as really mounted: <code>
        ai
      </code>
      
       iff the AI routes are, <code>
        collaboration
      </code>
      
       iff the websocket is). Always mounted; the client's probe reads it
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/editor/tags?q=
      </code>
    </td>
    
    <td>
      <code>
        #
      </code>
      
       popup: up to 20 tags in use
    </td>
  </tr>
  
  <tr>
    <td>
      GET / PUT
    </td>
    
    <td>
      <code>
        /api/editor/settings
      </code>
    </td>
    
    <td>
      Per-user settings (table below)
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/editor/assets/:id
      </code>
    </td>
    
    <td>
      Multipart <code>
        file
      </code>
      
       → <code>
        { url, name }
      </code>
      
      ; 413 above <code>
        MAX_MEDIA_BYTES
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/editor/assets/:id/:name
      </code>
    </td>
    
    <td>
      Serves an asset with its stored <code>
        Content-Type
      </code>
      
      , single byte-range support; 404 when unknown
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/editor/images/prompt-blocks
      </code>
    </td>
    
    <td>
      The prompt blocks of the host as <code>
        ImageStudioPromptBlock[]
      </code>
      
      ; only mounted with an <code>
        images
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/editor/images/generate
      </code>
    </td>
    
    <td>
      <code>
        { description, instruction, promptBlockIds, referenceUrls }
      </code>
      
       → the generated <code>
        ImageStudioImage
      </code>
      
      ; 400 for a malformed body; only mounted with an <code>
        images
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/editor/images/upload
      </code>
    </td>
    
    <td>
      Multipart <code>
        documentId
      </code>
      
       (string) and <code>
        file
      </code>
      
       (an image) → the stored <code>
        ImageStudioImage
      </code>
      
      ; 400 for a malformed id or a missing file, 413 above <code>
        MAX_MEDIA_BYTES.image
      </code>
      
      , 415 for a file that is no image; only mounted with an <code>
        images
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/editor/themes
      </code>
    </td>
    
    <td>
      The theme library as <code>
        ThemeRecord[]
      </code>
      
      ; only mounted with a <code>
        themes
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      GET
    </td>
    
    <td>
      <code>
        /api/editor/themes/:id
      </code>
    </td>
    
    <td>
      The theme's stylesheet as <code>
        text/css
      </code>
      
      ; 400 for a malformed id, 404 when unknown; only mounted with a <code>
        themes
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      POST
    </td>
    
    <td>
      <code>
        /api/editor/themes
      </code>
    </td>
    
    <td>
      Multipart <code>
        css
      </code>
      
       (file, required), <code>
        manifest
      </code>
      
       (file, optional Obsidian <code>
        manifest.json
      </code>
      
      ), <code>
        name
      </code>
      
       (string, optional) → <code>
        201
      </code>
      
       with the new <code>
        ThemeRecord
      </code>
      
       (<code>
        builtin: false
      </code>
      
      ). The name is <code>
        manifest.name
      </code>
      
      , else <code>
        name
      </code>
      
      , else the CSS file's base name; the id is its slug (<code>
        a-z0-9
      </code>
      
       and <code>
        -
      </code>
      
      , at most 64 characters), made unique with <code>
        -2
      </code>
      
      , <code>
        -3
      </code>
      
       … against the library. Limits: CSS up to <code>
        MAX_THEME_BYTES
      </code>
      
       (2 MB, <code>
        413
      </code>
      
       „Theme ist größer als 2 MB“), manifest up to 64 KB and parseable by <code>
        themeManifestSchema
      </code>
      
       (<code>
        400
      </code>
      
       „Ungültiges manifest.json“); <code>
        400
      </code>
      
       for a missing or empty <code>
        css
      </code>
      
      , for content that is not UTF-8 text (invalid UTF-8, NUL bytes) and for markup (<code>
        <script
      </code>
      
       or <code>
        <?xml
      </code>
      
       in the first 512 bytes); only mounted with a <code>
        themes
      </code>
      
       port
    </td>
  </tr>
  
  <tr>
    <td>
      DELETE
    </td>
    
    <td>
      <code>
        /api/editor/themes/:id
      </code>
    </td>
    
    <td>
      Deletes an uploaded theme (<code>
        204
      </code>
      
      ); <code>
        400
      </code>
      
       for a malformed id, <code>
        404
      </code>
      
       when unknown, <code>
        403
      </code>
      
       „Mitgelieferte Themes können nicht gelöscht werden“ for a builtin; only mounted with a <code>
        themes
      </code>
      
       port
    </td>
  </tr>
</tbody>
</table>

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`.

## Filtering the mounted routes

`installEditorServer` mounts every route of `serverRoutesOf(ports, { ai })` whose port is present. A host that serves some of these paths itself (for example `/api/editor/assets/*` from its own asset studio) passes `routes`, a function from the route table to the routes that are mounted; it can drop or reorder routes. The `RouteDef` type (`method`, `path`, `port`, `handler`) is exported from `@skaile/forge-editor/server/nitro`. The websocket is not part of the table; the default keeps every route.

```ts
installEditorServer(nitroApp, {
  ports,
  collab: false,
  routes: routes => routes.filter(route => !route.path.startsWith('/api/editor/assets')),
})
```

A host that drops the asset routes answers `GET /api/editor/assets/:id/:name` itself (media elements request that URL) and gives the client a backend whose `assets.upload` returns the URL of its own route.

## Settings route status codes

`/api/editor/settings`:

<table>
<thead>
  <tr>
    <th>
      Request
    </th>
    
    <th>
      Status
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET
      </code>
      
      /<code>
        PUT
      </code>
      
       without a user
    </td>
    
    <td>
      401
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
      
      , no <code>
        settings
      </code>
      
       port
    </td>
    
    <td>
      404 (route not mounted; client stays on <code>
        localStorage
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
      
      , nothing stored
    </td>
    
    <td>
      200 with body <code>
        null
      </code>
      
       (client uploads its local settings)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET
      </code>
      
      , stored
    </td>
    
    <td>
      200, <code>
        EditorSettings
      </code>
      
       normalized by <code>
        parseEditorSettings
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
      
      , no <code>
        settings
      </code>
      
       port
    </td>
    
    <td>
      404 (route not mounted)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
      
      , body is no complete valid <code>
        EditorSettings
      </code>
    </td>
    
    <td>
      400
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT
      </code>
      
      , ok
    </td>
    
    <td>
      204
    </td>
  </tr>
</tbody>
</table>

## 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; Nuxt: the module option, installEditorServer: 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.


# Settings and app lifetime

> The versioned EditorSettings object every editor of an app shares: local storage, per-account sync, the settings UI, the settingsUi prop and themes.

## One settings object per app

`app.use(createEditor())` (`createEditor` from `@skaile/forge-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 2) 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. The object has the sections `editing`, `ai`, `blocks` and `appearance`. 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`.

## React

`<EditorContextProvider context={createEditorContext({ notify: reactNotifier })}>` (`EditorContextProvider`, `reactNotifier` and `Toaster` from `@skaile/forge-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`). `settings` is the current `EditorSettings`, `update(draft => { … })` mutates a copy and stores it, and `set(value)` replaces it. `useStore(store)` subscribes a component to any `ReadonlyStore` of the core.

## Local storage and account sync

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. A record saved by an earlier version is migrated when it is read (`migrateEditorSettings`, applied by `parseEditorSettings`) and written back once: version 2 renamed keys (see the [migration guide](https://skaile-ai.github.io/forge-editor/guides/migration#persisted-names)). The server migrates a stored older record on `GET /api/editor/settings` and stores it again, and `PUT` accepts a body of an older version (a tab that was open during the update).

A backend that offers `settings` (the default backend and `createHttpBackend()` do; `createMemoryBackend()` keeps settings in memory only) syncs per account. On the first `useEditorSettings()` the client calls `backend.settings.load()` (the HTTP backend: `GET /api/editor/settings`; only once an editor-side component needs the settings, not at install time): the stored settings replace the local values (`synced`), `null` (`204`: the adapter keeps none), a refusal (`401`, `501`) and network errors keep the local ones; an account without stored settings uploads this browser's. Afterwards every change is sent with `backend.settings.save()` (debounced, 500 ms). The status codes are listed in [Server routes and authentication](https://skaile-ai.github.io/forge-editor/guides/routes-and-auth#settings-route-status-codes). A plain-Vue or React app gets this from the default backend only when its server implements the same two endpoints (`examples/react-advanced` reaches the Nuxt host's through its proxy), otherwise it passes `createMemoryBackend()` and 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.

## Settings UI

Tabs come from the features of a preset (`composites` `editing`, `ai`, `authors`, `comments`, `themes` `appearance`); the simple editor has none. `EditorSettingsPanel` (props `editor`, `contentClass?`, `v-model:tab`) places the tabs anywhere; `EditorSettingsModal` (props `editor`, `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 editor's preset has no tab.

The `settingsUi` prop of `EditorSurface` and `AdvancedEditor` takes two values: `'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 `editor`:

```vue
<script setup lang="ts">
import { EditorSettingsModal } from '@skaile/forge-editor/vue'
import { AdvancedEditor } from '@skaile/forge-editor/vue/advanced'
import type { Editor } from '@tiptap/vue-3'
import { ref, shallowRef } from 'vue'

const editor = shallowRef<Editor>()
const open = ref(false)
const tab = ref<string>()
</script>

<template>
  <AdvancedEditor settings-ui="external" @ready="editor = $event" @settings-open="(t) => { tab = t; open = true }" />
  <EditorSettingsModal v-model:open="open" v-model:tab="tab" :editor="editor" />
</template>
```

## Themes

`themesFeature()` (part of `advancedEditor()` on both surfaces): the setting `appearance.theme` (`null` = Default appearance, which applies no Theme) names an Obsidian theme served by `GET /api/editor/themes/:id`; users pick it in the settings tab „Theme“. 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 and limits: [Themes](https://skaile-ai.github.io/forge-editor/guides/themes).


# Slides: decks, slide layouts and exports

> The add-on @skaile/forge-editor-slides: the Block types deck and slide, the pure HTML render contract, the render targets reveal-html, pptx and marp-md, the transfer transforms that turn blocks into slides, and the slide preview in the inspector.

The add-on `@skaile/forge-editor-slides` adds presentations to the editor. A **deck** is a Typed block of the Block type `deck`. Its body is **slides**, Typed blocks of the Block type `slide`. A slide has a title, a description (the subtitle of a title slide), a body, and three [Block properties](https://skaile-ai.github.io/forge-editor/guides/block-properties): `layout`, `notes` and `status`.

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Where
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        slideBlockTypes(locale)
      </code>
    </td>
    
    <td>
      the Block types <code>
        deck
      </code>
      
       (a container that accepts <code>
        slide
      </code>
      
      ) and <code>
        slide
      </code>
    </td>
    
    <td>
      editor and server
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        renderSlide
      </code>
      
      , <code>
        renderDeck
      </code>
    </td>
    
    <td>
      pure HTML and CSS of a slide or a deck
    </td>
    
    <td>
      anywhere
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        slidesTargets()
      </code>
    </td>
    
    <td>
      the <a href="https://skaile-ai.github.io/forge-editor/guides/render">
        render targets
      </a>
      
       <code>
        reveal-html
      </code>
      
      , <code>
        pptx
      </code>
      
      , <code>
        marp-md
      </code>
    </td>
    
    <td>
      server
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        slidesTransforms()
      </code>
    </td>
    
    <td>
      the transfer transforms <code>
        slides-from-blocks
      </code>
      
       and <code>
        slides-from-blocks-ai
      </code>
    </td>
    
    <td>
      editor
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        slidesFeature()
      </code>
    </td>
    
    <td>
      the block actions „Folien-Layout“ and „Folie anhängen“, the slide preview in the inspector
    </td>
    
    <td>
      editor
    </td>
  </tr>
</tbody>
</table>

The add-on imports the library through its public entries only. The entry `@skaile/forge-editor-slides/server` reaches no editor code: use it in a server program.

## Install and wire

```ts
import { defaultBlockTypes } from '@skaile/forge-editor/composites'
import { copyTransform } from '@skaile/forge-editor/transfer'
import { bulletsTransform, summaryTransform } from '@skaile/forge-editor/integrations/composite-ai'
import { slideBlockTypes, slidesTransforms } from '@skaile/forge-editor-slides'
import { slidesFeature } from '@skaile/forge-editor-slides/vue' // or '/react'

const editor = composeEditor({
  content: 'rich',
  interaction: [...INTERACTION.full, 'transfer'],
  // The Block types of the editor: the built-in ones and the two of this add-on.
  blockTypes: [...defaultBlockTypes(t), ...slideBlockTypes('de')],
  add: [slidesFeature()],
  // A `transfer.transforms` list replaces the default list, so name the built-in transforms too.
  transfer: { transforms: [copyTransform, summaryTransform, bulletsTransform, ...slidesTransforms({ locale: 'de' })] },
})
```

```ts
import { createRenderer, markdownTarget } from '@skaile/forge-editor/adapters/render'
import { slideBlockTypes, slidesTargets } from '@skaile/forge-editor-slides/server'

// installEditorServer({ ports: { render }, blockTypes })
export const render = createRenderer([markdownTarget(), ...slidesTargets()])
export const blockTypes = [...serverBlockTypes, ...slideBlockTypes('de')]
```

The Block types go to the server too: the AI chat then knows what a deck is, and the server builds the schema from the same list ([Block types](https://skaile-ai.github.io/forge-editor/guides/block-types)).

## The slide model

<table>
<thead>
  <tr>
    <th>
      Part of a slide
    </th>
    
    <th>
      Source
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      title
    </td>
    
    <td>
      the title row of the Typed block (hidden on a <code>
        blank
      </code>
      
       slide)
    </td>
  </tr>
  
  <tr>
    <td>
      subtitle
    </td>
    
    <td>
      the description row (shown on a <code>
        title
      </code>
      
       slide)
    </td>
  </tr>
  
  <tr>
    <td>
      body
    </td>
    
    <td>
      the blocks after the chrome rows: paragraphs, headings, lists, quotes, code, images, rules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        layout
      </code>
    </td>
    
    <td>
      Block property, a <code>
        select
      </code>
      
      : <code>
        title
      </code>
      
      , <code>
        bullets
      </code>
      
       (default), <code>
        two-column
      </code>
      
      , <code>
        image
      </code>
      
      , <code>
        blank
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        notes
      </code>
    </td>
    
    <td>
      Block property, a <code>
        textarea
      </code>
      
      : speaker notes
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        status
      </code>
    </td>
    
    <td>
      Block property, a <code>
        status
      </code>
      
      : <code>
        draft
      </code>
      
       (todo), <code>
        ready
      </code>
      
       (doing), <code>
        final
      </code>
      
       (done)
    </td>
  </tr>
</tbody>
</table>

Layouts decide the arrangement only. `two-column` splits the body at the first horizontal rule, or after the first half of its blocks. `image` shows the first image above the other blocks. A deck ignores body blocks that are not slides.

## The render contract

`renderSlide(slide, layout?)` returns one slide in a 16:9 frame. `renderDeck(deck, { css? })` returns all slides, one frame each, in front of a `<style>` element with `SLIDE_CSS`. Both are pure: the same JSON gives the same string, and every text is escaped (links keep only `http`, `https`, `mailto` and relative targets; an image source must be web, relative or a `data:image/` address).

```ts
import { renderDeck } from '@skaile/forge-editor-slides/server'

const html = renderDeck(deckJson, { css: false })
// <div class="sk-deck" data-title="Quartalsbericht">
// <div class="sk-frame"><section class="sk-slide sk-slide--title" data-layout="title"><h1>Willkommen</h1>…
```

Nothing in the contract knows reveal.js, PowerPoint or Marp. Every target reads the same slide blocks (`blocksOf`) and builds its own format.

## Render targets

`slidesTargets(options)` gives three targets for a Block of the type `deck`. A render of any other block fails with a message the client shows.

<table>
<thead>
  <tr>
    <th>
      Target
    </th>
    
    <th>
      File
    </th>
    
    <th>
      What it holds
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        reveal-html
      </code>
    </td>
    
    <td>
      <code>
        .html
      </code>
    </td>
    
    <td>
      a reveal.js 6 page: one <code>
        <section>
      </code>
      
       per slide, the speaker notes as <code>
        <aside class="notes">
      </code>
      
       (speaker view with <code>
        S
      </code>
      
      ). reveal.js loads from <code>
        REVEAL_CDN
      </code>
      
       (jsDelivr); <code>
        options.reveal.cdn
      </code>
      
       points it at your own copy, <code>
        options.reveal.theme
      </code>
      
       picks the theme
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pptx
      </code>
    </td>
    
    <td>
      <code>
        .pptx
      </code>
    </td>
    
    <td>
      PowerPoint through PptxGenJS: the title as one text box, every block of the body as one text box, two stacks for <code>
        two-column
      </code>
      
      , pictures for <code>
        data:
      </code>
      
       images, speaker notes on the notes page
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        marp-md
      </code>
    </td>
    
    <td>
      <code>
        .md
      </code>
    </td>
    
    <td>
      Marp Markdown: front matter, <code>
        ---
      </code>
      
       between slides, the layout as a Marp class, speaker notes as HTML comments
    </td>
  </tr>
</tbody>
</table>

A `pptx` text box has a height from an estimate of the wrapped lines; PowerPoint shrinks text that does not fit when a person edits it. An image with a source other than a `data:` address shows its alt text, because the render cannot fetch it.

## Make slides from blocks

Drag a block into a deck and pick a transform, or drop it in the document and pick **Als Folien einfügen**. Both transforms insert a new `deck` Typed block after the drop position, titled „Folien: <source title="" />

“, with one slide per block of the source:

- A Typed block with nested Typed blocks gives one slide per nested block, depth first. Its own content comes first as a slide titled after it.
- Any other block is split at its headings: a heading starts a slide.
- A block without headings is one slide.

<table>
<thead>
  <tr>
    <th>
      Transform
    </th>
    
    <th>
      Derivation <code>
        method
      </code>
    </th>
    
    <th>
      Needs
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        slides-from-blocks
      </code>
    </td>
    
    <td>
      <code>
        link
      </code>
      
      : the structure is copied
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        slides-from-blocks-ai
      </code>
    </td>
    
    <td>
      <code>
        ai:slides
      </code>
      
      : a model writes the slides from the block's Markdown
    </td>
    
    <td>
      the <code>
        ai
      </code>
      
       capability
    </td>
  </tr>
</tbody>
</table>

The new deck records a [Derivation](https://skaile-ai.github.io/forge-editor/guides/derive-methods) that names the source block. `inputHash` is the hash of the source's body Markdown at that moment (the snapshot) and `outputHash` is the hash of the deck's body, so the Derivation badge shows the deck as stale when the source changes and as edited when the deck body changes. The AI transform also records `activity` (a request id and the model). A drag of a block that has no block id inserts the deck without a Derivation.

The AI transform asks for Markdown: every slide starts with `## Title`, bullets follow, optional lines `Layout: …` and `Notizen: …` set the layout and the speaker notes. The answer is parsed by `slideDraftsFromMarkdown`; an answer without a slide shows a notice and inserts nothing.

## In the editor

`slidesFeature()` of `/vue` or `/react` adds:

- the block action **Folien-Layout** on a slide (a menu of the layouts; `layouts` in the feature options narrows it) and **Folie anhängen** on a deck,
- the section **Folienvorschau** in the Typed block inspector and details card: a slide shows its 16:9 preview, layout buttons and notes; a deck shows all slides. The component is `SlideView`.

The framework-free `slidesFeature()` of the package entry has the block actions without the preview.

## Strings

The add-on keeps its own small catalog in German and English (`SLIDES_MESSAGES`, `createSlidesTranslator(locale, overrides)`), because the library's message keys are closed over the library's own strings. `slideBlockTypes(locale)` and `slidesTransforms({ locale })` take the language; the feature and the preview read it from the editor context.


# Speech: text to audio, and subtitle files

> The SpeechProvider port with its engines and voices, the SSE route that streams progress and stores the audio as an asset, the daily character budget, the client call, and the block action that exports a transcript as WebVTT or SubRip.

The `speech` capability turns text into audio. The host passes one `SpeechProvider`; the editor adds the routes, the daily budget and the client call. The audio is a file like any render result: it is stored as an asset of the Document.

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Port (capability)
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        SpeechProvider
      </code>
    </td>
    
    <td>
      lists engines with their voices, synthesizes text, optionally transcribes audio
    </td>
    
    <td>
      <code>
        speech
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /api/editor/speech/engines
      </code>
    </td>
    
    <td>
      the engines and voices of the user
    </td>
    
    <td>
      <code>
        speech
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/speech
      </code>
    </td>
    
    <td>
      one synthesis, streamed as server-sent events; the audio is stored as an asset of the Document
    </td>
    
    <td>
      <code>
        speech
      </code>
      
       and <code>
        assets
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        EditorBackend['speech']
      </code>
    </td>
    
    <td>
      <code>
        engines()
      </code>
      
       and <code>
        synthesize(request, { onProgress })
      </code>
    </td>
    
    <td>
      <code>
        speech
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Block action <code>
        transcript-export
      </code>
    </td>
    
    <td>
      downloads the timed segments of a transcript as <code>
        .vtt
      </code>
      
       or <code>
        .srt
      </code>
    </td>
    
    <td>
      none
    </td>
  </tr>
</tbody>
</table>

A synthesis lives as long as its request. There is no job store: the server streams progress, stores the file and ends the stream. A client that disconnects aborts the engine through the `AbortSignal` that `SpeechProvider.synthesize` receives.

## Provide a speech port

```ts [docs/snippets/speech-provider.ts]
import { createMemorySpeech, createOpenAiSpeech } from '@skaile/forge-editor/adapters/speech'
import type { EditorPorts } from '@skaile/forge-editor/server'

// The speech port is one provider. `createOpenAiSpeech` calls an OpenAI-compatible `/audio/speech` endpoint from the
// server, so the key never reaches a page; `createMemorySpeech` answers a second of silence, for tests and demos.
export function speechPort(apiKey: string | undefined): NonNullable<EditorPorts['speech']> {
  return apiKey
    ? createOpenAiSpeech({ endpoint: 'https://api.openai.com/v1', model: 'gpt-4o-mini-tts', apiKey })
    : createMemorySpeech()
}
```

`createOpenAiSpeech({ endpoint, model, apiKey?, id?, label?, voices?, fetch? })` offers one engine (id `openai`) and posts `{ model, input, voice, response_format }` to `<endpoint>/audio/speech`. Its voices default to `OPENAI_VOICES`; pass `voices` for a compatible server with other voices. `createMemorySpeech({ engines? })` is one engine `memory` with the voice `silent`: every synthesis answers one second of silence as WAV (`silentWav(seconds?)` builds it), and `mp3` is refused with `422`.

A host with several engines, for example a second vendor, implements `SpeechProvider` itself and lists each engine in `engines`. A provider that can also transcribe adds `transcribe`; the routes do not use it yet.

## The route

`POST /api/editor/speech` takes `{ documentId, engine, voice, text, format }` with `format` `'mp3'` or `'wav'`. The server checks the request before the stream starts:

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Cause
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      malformed body, empty text, text longer than the daily budget, or a Document ID that is not valid
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        401
      </code>
    </td>
    
    <td>
      no user
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        403
      </code>
    </td>
    
    <td>
      the user may not read the Document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      unknown engine, or a voice the engine does not have
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        429
      </code>
    </td>
    
    <td>
      the text does not fit the characters the user has left today; <code>
        Retry-After
      </code>
      
       is the seconds until UTC midnight
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        501
      </code>
    </td>
    
    <td>
      the host has no <code>
        speech
      </code>
      
       or no <code>
        assets
      </code>
      
       port
    </td>
  </tr>
</tbody>
</table>

After that the answer is a `text/event-stream` with the events `progress` (`{ phase, percent? }`), then `done` (`{ asset, fileName, mime }`) or `error` (`{ message }`). The audio is stored through `ports.assets.storeAsset` as an asset of `documentId`; `asset` is its name, read with the asset route like any upload. An engine that fails ends the stream with `error`, stores nothing and gives the characters back.

## Daily budget

Each user may synthesize `SPEECH_CHARS_PER_DAY` (50 000) characters per UTC day. The count is kept in memory per server process and starts over at UTC midnight, so a restart or a second process starts a fresh count. The key is the user's `id` (see `userKey`, the same key the AI rate limit uses). A call that would pass the limit is refused with `429` and counts nothing.

A test or a host with another limit builds its own budget and hands it to the handlers through `HandlerContext.speechBudget`:

```ts
import { createSpeechBudget } from '@skaile/forge-editor/server'

const speechBudget = createSpeechBudget({ limit: 1000, now: () => Date.now() })
```

## The client

`backend.speech` is present when the server serves the `speech` capability. `backend.speech.engines()` lists the engines. `backend.speech.synthesize(request, { onProgress, signal })` resolves with `{ asset, fileName, mime, url }` and rejects with a `BackendError` that carries the server's message and status (`429` over the budget). The loop over the stream is `postSse` (`core/sse.ts`), the same helper `render` uses.

## Subtitle files from a transcript

A transcript is a run of speaker segments with `start` and `end` seconds (see [Media, mentions and transcripts](https://skaile-ai.github.io/forge-editor/guides/media-mentions-transcript)). The transcript feature adds the block action **„Untertitel exportieren“** (`transcript-export`) to a Typed block that holds timed segments. It is also offered in a read-only editor, because it does not change the Document. Its menu downloads the segments as WebVTT (`.vtt`) or SubRip (`.srt`), named after the block's title.

The functions are pure and DOM-free, so a server can write the same files:

<table>
<thead>
  <tr>
    <th>
      Function
    </th>
    
    <th>
      Result
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        vttOf(cues)
      </code>
    </td>
    
    <td>
      <code>
        WEBVTT
      </code>
      
      , then one <code>
        hh:mm:ss.mmm --> hh:mm:ss.mmm
      </code>
      
       block per cue; the speaker is a <code>
        <v Name>
      </code>
      
       voice tag
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        srtOf(cues)
      </code>
    </td>
    
    <td>
      numbered <code>
        hh:mm:ss,mmm --> hh:mm:ss,mmm
      </code>
      
       blocks; the speaker is a <code>
        Name:
      </code>
      
       prefix
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcriptCuesOf(node)
      </code>
    </td>
    
    <td>
      the cues of the timed segments in a node, in order
    </td>
  </tr>
</tbody>
</table>

A cue is `{ start, end, text, speaker? }`. A cue without text is left out, an end before the start is raised to the start, and a segment without a start time has no cue. A segment without an end time ends where the next cue starts, the last one two seconds after its start. The functions come from `@skaile/forge-editor/transcript`. For the port types see the [Speech port reference](https://skaile-ai.github.io/forge-editor/reference/speech-port).


# Storage adapters, comment stores, Nitro host

> Pick where documents live with ready-made EditorPorts adapters, comment stores, a Nuxt-free Nitro host and the useEditorDocument composable.

Ready-made `EditorPorts` bundles ([the ports each storage serves](https://skaile-ai.github.io/forge-editor/guides/editor-ports)), comment stores, a Nuxt-free Nitro host and a Vue composable ship inside this package as subpath entries (formerly the separate package `@skaile/forge-editor-adapters`; from 2.1.0 `@skaile/forge-editor` is the only dependency). A host picks where documents live without touching the editor. All adapters satisfy the same contract test (`test/adapters/adapter-contract.test.ts`).

```sh
bun add @skaile/forge-editor   # plus drizzle-orm only for the three drizzle entries (PGlite or a Postgres driver for the Block index)
```

<table>
<thead>
  <tr>
    <th>
      Entry
    </th>
    
    <th>
      Adapter
    </th>
    
    <th>
      Storage
    </th>
    
    <th>
      Needs
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/json
      </code>
    </td>
    
    <td>
      <code>
        createJsonAdapter({ dir, users? })
      </code>
    </td>
    
    <td>
      files under <code>
        dir
      </code>
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/drizzle
      </code>
    </td>
    
    <td>
      <code>
        createDrizzleAdapter({ db, tables: editorTables() })
      </code>
    </td>
    
    <td>
      SQLite via drizzle (<code>
        bun:sqlite
      </code>
      
      , better-sqlite3, libsql, D1)
    </td>
    
    <td>
      <code>
        drizzle-orm
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/forge
      </code>
    </td>
    
    <td>
      <code>
        createForgeAdapter({ content, state, schema, authenticate, … })
      </code>
    </td>
    
    <td>
      the host's Markdown files; state, assets and settings go to a <code>
        state
      </code>
      
       adapter
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/block-index
      </code>
    </td>
    
    <td>
      <code>
        createMemoryBlockIndex()
      </code>
    </td>
    
    <td>
      the Block index (<code>
        ports.index
      </code>
      
      ) in the process; rebuilt from the documents on start
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/block-index/drizzle
      </code>
    </td>
    
    <td>
      <code>
        createDrizzleBlockIndex({ db, tables: blockIndexTables() })
      </code>
      
      , <code>
        bootstrapBlockIndexTables(db)
      </code>
    </td>
    
    <td>
      the Block index in Postgres or PGlite (<code>
        editor_block_index
      </code>
      
      , one <code>
        tsvector
      </code>
      
       per title and text, and <code>
        editor_block_edges
      </code>
      
      , one row per Edge; search runs in the database, scope as a SQL filter); same answers as the memory adapter (<code>
        test/adapters/block-index-contract.test.ts
      </code>
      
      )
    </td>
    
    <td>
      <code>
        drizzle-orm
      </code>
      
      , a Postgres driver (<code>
        @electric-sql/pglite
      </code>
      
      , <code>
        pg
      </code>
      
      , …)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/anchors
      </code>
    </td>
    
    <td>
      <code>
        captureAnchor
      </code>
      
      , <code>
        capturePoint
      </code>
      
      , <code>
        resolveAnchor
      </code>
      
      , <code>
        mapAnchor
      </code>
    </td>
    
    <td>
      pure functions over ProseMirror documents
    </td>
    
    <td>
      <code>
        @tiptap/pm
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/comments/json
      </code>
    </td>
    
    <td>
      <code>
        createJsonCommentStore({ file })
      </code>
    </td>
    
    <td>
      one JSON file (forge's <code>
        concept-discussions.json
      </code>
      
       layout)
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/comments/drizzle
      </code>
    </td>
    
    <td>
      <code>
        createDrizzleCommentStore({ db, tables: commentTables() })
      </code>
    </td>
    
    <td>
      SQLite via drizzle
    </td>
    
    <td>
      <code>
        drizzle-orm
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/comments/server
      </code>
    </td>
    
    <td>
      <code>
        handleCommentsRequest(store, { method, documentId, body })
      </code>
    </td>
    
    <td>
      the REST handler a host routes its comments endpoint to
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/server/nitro
      </code>
    </td>
    
    <td>
      <code>
        installEditorServer(nitroApp, { ports, collab, ai?, rateLimit?, schema? })
      </code>
    </td>
    
    <td>
      mounts the editor's routes, the collaboration websocket and optional AI and comments routes on a Nitro app (comments: <code>
        ports.comments
      </code>
      
      )
    </td>
    
    <td>
      <code>
        h3
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/vue
      </code>
    </td>
    
    <td>
      <code>
        useEditorDocument(id, { backend?, user?, canComment?, collaboration? })
      </code>
    </td>
    
    <td>
      the document a Vue editor surface binds to, through <code>
        EditorBackend
      </code>
      
       (<code>
        documents
      </code>
      
      , <code>
        collaboration
      </code>
      
      , <code>
        comments
      </code>
      
      ): <code>
        modelValue
      </code>
      
      , <code>
        dirty
      </code>
      
      , <code>
        save()
      </code>
      
      , <code>
        collaboration
      </code>
      
      , <code>
        comments
      </code>
    </td>
    
    <td>
      <code>
        vue
      </code>
      
      , <code>
        yjs
      </code>
      
      , <code>
        @hocuspocus/provider
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/react
      </code>
    </td>
    
    <td>
      <code>
        useEditorDocument(id, { backend?, user?, canComment?, collaboration? })
      </code>
    </td>
    
    <td>
      the same for a React surface: <code>
        modelValue
      </code>
      
      , <code>
        onChange
      </code>
      
      , <code>
        ready
      </code>
      
      , <code>
        dirty
      </code>
      
      , <code>
        save
      </code>
      
      , <code>
        reload
      </code>
      
      , <code>
        error
      </code>
      
      , <code>
        collaboration
      </code>
      
      , <code>
        comments
      </code>
      
      , <code>
        bind
      </code>
    </td>
    
    <td>
      <code>
        react
      </code>
      
      , <code>
        yjs
      </code>
      
      , <code>
        @hocuspocus/provider
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/http
      </code>
    </td>
    
    <td>
      <code>
        createHttpBackend({ fetch?, base?, probe? })
      </code>
    </td>
    
    <td>
      the client port <code>
        EditorBackend
      </code>
      
       (<code>
        createEditorContext({ backend })
      </code>
      
      ) over the editor's <code>
        /api/editor
      </code>
      
       and <code>
        /api/ai
      </code>
      
       routes, the collaboration websocket and the comments endpoint; the default backend of every editor context. <code>
        probe: true
      </code>
      
       asks <code>
        GET /api/editor/capabilities
      </code>
      
       once and drops the capabilities the server does not serve (see below)
    </td>
    
    <td>
      <code>
        @hocuspocus/provider
      </code>
      
      , <code>
        yjs
      </code>
      
      , <code>
        ofetch
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/direct-ai
      </code>
    </td>
    
    <td>
      <code>
        createDirectAi({ presets, roles?, users?, fetch? })
      </code>
    </td>
    
    <td>
      the <code>
        ai
      </code>
      
       capability of <code>
        EditorBackend
      </code>
      
       without a server: <code>
        models
      </code>
      
      , <code>
        complete
      </code>
      
      , <code>
        generate
      </code>
      
       and <code>
        transcriptCleanup
      </code>
      
       call OpenAI-compatible chat-completion endpoints straight from the page (see below); <code>
        chat
      </code>
      
       and <code>
        extract
      </code>
      
       answer 501
    </td>
    
    <td>
      nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters
      </code>
    </td>
    
    <td>
      types only
    </td>
    
    <td>
      
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

Peers: `drizzle-orm` (`^0.45.0`, optional) is needed by `./adapters/drizzle`, `./comments/drizzle` and `./adapters/block-index/drizzle` only; `h3` (optional) by `./server/nitro`; `vue` (optional), `yjs`, `@hocuspocus/provider` by `./adapters/vue`. `bun run check:editor-entries` builds the adapter entries through its fixtures (`adapters-node`: `./adapters`, `./adapters/json`, `./adapters/forge`, `./anchors`, `./comments/server`, `./comments/json`; `adapters-drizzle`: the three drizzle entries; `adapters-nitro`: `./server/nitro`; `adapters-vue`: `./adapters/vue`; `adapters-http`: `./adapters/http`, which holds the REST comments model; `adapters-direct-ai`: `./adapters/direct-ai`, which reaches no AI SDK, server or HTTP client) and proves on the bundles that Vue is only reachable from `./adapters/vue`, Nitro only from `./server/nitro`, drizzle only from the two drizzle entries, and that no adapter entry reaches React (except `./adapters/react`). Entries named `./server/nest` and `./adapters/prisma` are reserved for a later platform adoption and are not exported; the check fails if one of them appears in `exports` before it is designed.

## The tier rule

Three tiers, one direction of dependency:

1. **The editor** (`@skaile/forge-editor`, everything except `adapters/`) and the `EditorPorts` contract (`@skaile/forge-editor/server`). It knows no storage and no host.
2. **Adapters** (`src/adapters/`, the entries above): implementations of that contract and the wiring around it. They depend on the editor; they import no application code, and no entry imports another UI or server framework than the one it is named for.
3. **Hosts**: an app (Nuxt, a bare Nitro server, Vite, a Fastify or tRPC server) that supplies identity (`authenticate`), a store and its own chrome. A host calls these entries; it never reaches into `dist/` internals or table names.

## Adapter matrix

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      <code>
        json
      </code>
    </th>
    
    <th>
      <code>
        drizzle
      </code>
    </th>
    
    <th>
      <code>
        forge
      </code>
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Documents
    </td>
    
    <td>
      <code>
        <id>.json
      </code>
    </td>
    
    <td>
      <code>
        editor_documents
      </code>
    </td>
    
    <td>
      the host's Markdown files
    </td>
  </tr>
  
  <tr>
    <td>
      Collaboration state
    </td>
    
    <td>
      <code>
        <id>.ystate
      </code>
    </td>
    
    <td>
      <code>
        editor_states
      </code>
    </td>
    
    <td>
      the <code>
        state
      </code>
      
       adapter you pass in
    </td>
  </tr>
  
  <tr>
    <td>
      Settings, assets
    </td>
    
    <td>
      files under <code>
        settings/
      </code>
      
      , <code>
        assets/
      </code>
    </td>
    
    <td>
      <code>
        editor_settings
      </code>
      
      , <code>
        editor_assets
      </code>
    </td>
    
    <td>
      the <code>
        state
      </code>
      
       adapter
    </td>
  </tr>
  
  <tr>
    <td>
      Creates documents (<code>
        PUT /api/editor/documents/:id
      </code>
      
      )
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      yes
    </td>
    
    <td>
      no (the host owns its files)
    </td>
  </tr>
  
  <tr>
    <td>
      Default identity
    </td>
    
    <td>
      anonymous dev user outside production
    </td>
    
    <td>
      same
    </td>
    
    <td>
      none: the host supplies <code>
        authenticate
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Comment store
    </td>
    
    <td>
      <code>
        comments/json
      </code>
    </td>
    
    <td>
      <code>
        comments/drizzle
      </code>
    </td>
    
    <td>
      <code>
        comments/json
      </code>
      
       or <code>
        comments/drizzle
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Nodes
    </td>
    
    <td>
      one process
    </td>
    
    <td>
      SQLite writers of the driver
    </td>
    
    <td>
      one process
    </td>
  </tr>
</tbody>
</table>

All three pass the adapter contract test; both comment stores pass `test/adapters/comment-store.test.ts`. The JSON and forge adapters and the JSON comment store are single-node: no cross-process locking.

## Browser-direct AI

By default the `ai` capability is a relay: the browser calls `/api/ai/*`, and the server holds the model key, applies the per-user rate limit (`config.ai.rateLimit`, enforced in the server handlers only) and calls the model. A host without a server, or one that points the editor at a local model, drops the relay: `createDirectAi` is an `EditorBackend['ai']` that runs the same protocol modules as the handlers (`runGenerate`, `runCompletion`, `runTranscriptCleanup`, so prompts, limits and results are identical) and calls `<endpoint>/chat/completions` itself, over a plain `fetch` with a hand-written SSE reader (no AI SDK in the bundle). It goes beside the memory backend:

```ts
import { createDirectAi } from '@skaile/forge-editor/adapters/direct-ai'
import { createMemoryBackend } from '@skaile/forge-editor/adapters/memory'

const backend = {
  ...createMemoryBackend({ users }),
  ai: createDirectAi({
    presets: { local: { label: 'Lokales Modell', endpoint: 'http://localhost:11434/v1', model: 'llama3.1' } },
    roles: { complete: 'local' }, // Model roles without an entry use the first preset
    users: () => ['anna', 'ben'], // offered to tasks that write `@` mentions
  }),
}
app.use(createEditor({ backend }))
```

`endpoint` is the OpenAI-compatible base URL, as for the server's `ModelPresetConfig.endpoint`; `models()` lists the Model presets without their keys, and a request may also carry its own `{ endpoint, model, apiKey }` (the Model profiles users add in the settings). A refused model request (HTTP error, unreachable endpoint) rejects with a `BackendError` carrying the upstream status before anything streams, like the server's non-2xx answers; a failure inside the stream is an `error` event.

Limits to know before choosing it:

- **The key is in the page.** A `presets[].apiKey` is shipped to every visitor and readable in the network panel. Use it for local models, endpoints without a key, or keys the user brings; keep a key that must stay secret behind the server routes.
- **No rate limit.** The per-user limit lives in the server handlers, so nothing throttles direct calls except the model provider itself.
- **chat and extract need a server.** The document chat (tool calls) and `extract` (transcription, OCR, Crossref) answer `BackendError` 501. A host that needs them takes `ai` from the HTTP backend instead (`createHttpBackend` of `@skaile/forge-editor/adapters/http`): `{ ...createMemoryBackend(), ai: createHttpBackend().ai }`, which sends every AI request to `/api/ai`.
- **CORS.** The endpoint must allow the page's origin.

Which capabilities work in the page and which need a server is summarised in [the locality table](https://skaile-ai.github.io/forge-editor/guides/editor-ports#capability-locality).

## Your own store

A host that keeps comments in its own database implements `CommentStore` (`@skaile/forge-editor/comments/server`) and does not have to rewrite the rules. `addComment`, `createThread`, `editComment`, `removeComment`, `setThreadStatus`, `updateAnchor` and `removeThread` are the pure operations the JSON store is built from, and `emptyDiscussion()` is a document without discussion. Each takes the document's `Discussion` (`{ annotations, threads }`), changes it in place and throws a `CommentStoreError` (unknown or duplicate ids, inconsistent input) before it changes anything. A store loads the record, applies the operation and writes the record back:

```ts
import { addComment, createThread, emptyDiscussion, type CommentStore, type Discussion } from '@skaile/forge-editor/comments/server'

// `db`: the host's own storage, one `Discussion` per document id
const load = async (documentId: string): Promise<Discussion> => (await db.get(documentId)) ?? emptyDiscussion()

export const store: Pick<CommentStore, 'getDiscussion' | 'createThread' | 'addComment'> = {
  getDiscussion: load,
  async createThread(documentId, input) {
    const record = await load(documentId)
    const created = createThread(record, input)
    await db.put(documentId, record)
    return created
  },
  async addComment(documentId, threadId, comment) {
    const record = await load(documentId)
    const thread = addComment(record, threadId, comment)
    await db.put(documentId, record)
    return thread
  },
}
```

The other `CommentStore` methods follow the same three steps; `getThread`, `listThreads` and `removeDocuments` need no operation. Serialise the read-modify-write per document (a revision column, a transaction) when several writers share the database.

## Nitro host and composable

```ts
// server/plugins/editor.ts (bare Nitro, no Nuxt)
import { createJsonAdapter } from '@skaile/forge-editor/adapters/json'
import { createJsonCommentStore } from '@skaile/forge-editor/comments/json'
import { installEditorServer } from '@skaile/forge-editor/server/nitro'
import { defineNitroPlugin } from 'nitropack/runtime'

export default defineNitroPlugin((nitroApp) => {
  installEditorServer(nitroApp, {
    ports: {
      ...createJsonAdapter({ dir: '.data/documents' }),
      comments: createJsonCommentStore({ file: '.data/comments.json' }), // optional: mounts /api/editor/comments/:id
    },
    collab: {},                                                   // `false`: no websocket, documents still load and save over HTTP; `{ authenticateUpgrade: true }`: 401 at the upgrade
    // ...serverConfig(defineEditorConfig({ ai: { apiKey: process.env.AI_KEY } })),   // optional: mounts /api/ai/* with the defaults of the AI configuration guide, replaces `collab`/`ai`/`rateLimit`
  })
})
```

`installEditorServer` is the one installer of both hosts: the [Nuxt module](https://skaile-ai.github.io/forge-editor/guides/nuxt-module) calls it from its server plugin, a host without Nuxt calls it from its own; set `experimental: { websocket: true }` in the Nitro config for the collaboration websocket. It mounts `serverRoutesOf(ports, { ai })` (`src/server/routes.ts`), all behind `ports.identity.authenticate`: the editor's client endpoints (`/api/editor/{settings,users,tags,assets/…,themes/…}`, each served only when its port is present), `GET`/`PUT /api/editor/documents/:id` (a document's TipTap JSON; `PUT` needs a `documents` port that also manages documents: `putDocument`), `GET`/`POST /api/editor/comments/:id` (`handleCommentsRequest` over `ports.comments`, mounted only when that port is present), `/api/ai/*` with `ai`, and `/collab/:id` (the Hocuspocus websocket) unless `collab: false`. It returns the `EditorServer` handle: `forgetDocument(id)`, `liveContent(id)`, `enforceRateLimit(request)` and `resolveModel(ref, user)` act on the collaboration server, AI models and rate limiter the routes use (a Nuxt host reaches it with `useEditorServer()`). The returned object (`ports`, `collab`, `models`, `close()`) is for tests and shutdown; Nitro's `close` hook already calls it.

```vue
<script setup lang="ts">
import { useEditorDocument } from '@skaile/forge-editor/adapters/vue'
import { commentsFeature } from '@skaile/forge-editor/comments/vue'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { EditorSurface } from '@skaile/forge-editor/vue'
import { ref } from 'vue'

const id = ref('welcome')
const doc = useEditorDocument(id, { user: { id: 'u1', name: 'Anna', color: '#e11d48' } }) // backend: the one `createEditor({ backend: createHttpBackend() })` installed
const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), commentsFeature({ model: () => doc.comments.value! })] })
</script>

<template>
  <button :disabled="!doc.dirty.value" @click="doc.save()">Save</button>
  <EditorSurface v-if="doc.ready.value" :key="id" :preset="preset" v-bind="doc.bind.value" />
</template>
```

`useEditorDocument(id, options)` loads and saves through `backend.documents` (the HTTP backend: `GET`/`PUT /api/editor/documents/:id`; a missing document, `null`, starts empty and is created by the first `save()`) and returns `modelValue`, `ready`, `dirty`, `save()`, `reload()`, `error`, `collaboration`, `comments` (made by `backend.comments`: the REST comments model of `/api/editor/comments/:id` over HTTP), `editor` and `bind` (the surface's props and events). The backend is `options.backend`, else the one of the editor context (`createEditor({ backend })`, see the `/adapters/http` row above); the default context backend has neither collaboration nor comments, so a host that needs them installs `createHttpBackend()`. `dirty` ignores the block ids the editor assigns when it mounts content; they are saved with the next edit. With `collaboration: true` (or `{ token? }`, the token the collaboration server's `AccessControl.authenticate` receives) the Y.Doc is the document: `backend.collaboration.connect(id, token)` opens it, the server loads and stores the content, nothing is fetched or saved by the composable, and `modelValue` stays `undefined`; a backend without the `collaboration` capability makes the call throw `@skaile/forge-editor: useEditorDocument needs backend capability "collaboration"…`. Mount the surface with `:key="id"` and `v-if="doc.ready.value"`. The React twin, `useEditorDocument(id, options)` from `@skaile/forge-editor/adapters/react`, takes the same options and returns plain values (`modelValue`, `onChange`, `ready`, `dirty`, `save`, `reload`, `error`, `collaboration`, `comments`, `editor`, `bind`) and reads its backend from `EditorContextProvider`; `bind` spreads onto the surface as `value`, `onChange`, `onReady` and `collaboration`, and a `null` or `undefined` id keeps it idle (no document open yet).

Every adapter returns an `EditorPorts` bundle with only the ports it serves (`json` and `drizzle`: identity, documents with `putDocument`/`deleteDocument`/`listDocumentIds`, collabState, directory, assets, settings; `forge`: identity, documents and, when its `state` has them, collabState, assets, settings, themes). All take the same hooks: `authenticate({ headers, token })` (the user behind a request or collaboration socket, `null` refuses; default: an anonymous development user outside `NODE_ENV=production`, nobody in production; the forge adapter has no default), `authorize(user, documentId)` (per-document access for collaboration, `{ readOnly } | null`; omitted = every authenticated user edits every document) and `users()` (who can be `@`-mentioned). Host nodes for the collaboration schema are the server's `schema` option, not an adapter hook. Comment stores are the `comments` port: `{ ...createJsonAdapter({ dir }), comments: createJsonCommentStore({ file }) }`.

The runnable app is [`examples/vue-nitro-json`](https://github.com/skaile-ai/forge-editor/tree/main/examples/vue-nitro-json): `bun run proto:vue-nitro-json` serves it on port 3046, documents land in `examples/vue-nitro-json/.data/documents/<id>.json`, comments in `examples/vue-nitro-json/.data/comments.json`.


# Templates: start a Document from a Dokumentvorlage

> The Dokumentvorlagen folder, the placeholders expandTemplate fills in ({{title}}, {{date}}, {{time}}, {{cursor}}), and the templateId of the Document create route.

A **Dokumentvorlage** is an ordinary Document that sits in a folder named `Dokumentvorlagen` (`TEMPLATES_FOLDER`, `@skaile/forge-editor/core`). A new Document can start as a copy of it: the editor server copies the Dokumentvorlage's content and fills in the placeholders in every text node. The Dokumentvorlage itself is never changed. There is no separate template store, so a Dokumentvorlage has the same access rules, history and editor as any other Document, and a user who may read it may create from it.

## Placeholders

`expandTemplate(text, { title, now, locale })` is pure and framework-free. It returns `{ text, cursor }`.

<table>
<thead>
  <tr>
    <th>
      Placeholder
    </th>
    
    <th>
      Becomes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        {{title}}
      </code>
    </td>
    
    <td>
      the title of the new Document
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {{date}}
      </code>
    </td>
    
    <td>
      the date, <code>
        medium
      </code>
      
       style in <code>
        locale
      </code>
      
       (<code>
        25.10.2026
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {{date:short}}
      </code>
      
      , <code>
        {{date:medium}}
      </code>
      
      , <code>
        {{date:long}}
      </code>
    </td>
    
    <td>
      the date in that <code>
        Intl.DateTimeFormat
      </code>
      
       style
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {{date:iso}}
      </code>
    </td>
    
    <td>
      the date as <code>
        2026-10-25
      </code>
      
       (the local day of <code>
        now
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {{time}}
      </code>
    </td>
    
    <td>
      the time, <code>
        short
      </code>
      
       style in <code>
        locale
      </code>
      
       (<code>
        14:05
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        {{cursor}}
      </code>
    </td>
    
    <td>
      nothing; <code>
        cursor
      </code>
      
       holds its offset in the expanded text. Every further <code>
        {{cursor}}
      </code>
      
       is removed too
    </td>
  </tr>
</tbody>
</table>

Names are not case-sensitive and may have spaces inside the braces (`{{ Title }}`). Anything else in double braces stays exactly as written, an unknown name (`{{author}}`) and an unknown format (`{{date:weird}}`) included, so a Dokumentvorlage can carry text that only looks like a placeholder. Block templates for the AI (`BlockTypeAi.contentTemplate`) keep their own `{key}` syntax; the two are not mixed, and Templater scripts are not translated.

```ts
import { expandTemplate } from '@skaile/forge-editor/core'

const env = { title: 'Sitzung', now: new Date(2026, 9, 25, 14, 5), locale: 'de-DE' }
expandTemplate('# {{title}} ({{date:iso}})\n\n{{cursor}}', env)
// { text: '# Sitzung (2026-10-25)\n\n', cursor: 24 }
```

`expandTemplateContent(content, env)` applies the same expansion to every text node of TipTap JSON. It keeps marks, attributes and block IDs, returns a new tree and drops the cursor, because a new Document has no caret yet.

## Creating from a Dokumentvorlage

`POST /api/editor/documents` takes an optional `templateId` next to `title` and `folder`. In the client it is `backend.documents.create({ title?, folder?, templateId? })`.

```ts
const sitzung = await backend.documents.create({ title: 'Sitzung', folder: 'Projekte', templateId: protokoll.id })
```

The server checks the Dokumentvorlage before it creates anything: the Document must be listed in a folder named `Dokumentvorlagen` (`templatesOf(tree)`, any depth) and the user must be allowed to read it. It then creates the Document through `DocumentAdmin.createDocument` and stores the expanded content with `storeContent`, so the Block index follows as for any write. `{{title}}` is the title the Document got, which is the default title when the request names none. The date and time use the first language tag of the `Accept-Language` header, `de` when there is none.

<table>
<thead>
  <tr>
    <th>
      Answer
    </th>
    
    <th>
      When
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        201
      </code>
      
       with the <code>
        DocumentSummary
      </code>
    </td>
    
    <td>
      created
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        400
      </code>
    </td>
    
    <td>
      <code>
        templateId
      </code>
      
       is an empty string, or the body is otherwise invalid
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        403
      </code>
    </td>
    
    <td>
      the user may not read the Dokumentvorlage
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      <code>
        templateId
      </code>
      
       names no Document inside a <code>
        Dokumentvorlagen
      </code>
      
       folder, or the folder is unknown
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        501
      </code>
    </td>
    
    <td>
      the documents port has no <code>
        createDocument
      </code>
      
       or no <code>
        listTree
      </code>
    </td>
  </tr>
</tbody>
</table>

The content of the Dokumentvorlage is the live one when the collaboration server has it open, so an unsaved edit is part of the copy. Block IDs are copied unchanged: they are unique per Document only, so the copy and the Dokumentvorlage do not clash.

## In the host

The host lists the Dokumentvorlagen from the tree it already has: `templatesOf(tree)` returns the Documents of the first folder named `Dokumentvorlagen`, newest first, as `DocumentSummary`s. The reference app shows them in the menu „Aus Dokumentvorlage“ next to „Neues Dokument“ on `app/pages/documents/index.vue` and passes the choice as `templateId`:

```ts
import { templatesOf } from '@skaile/forge-editor/core'

const templates = templatesOf(tree) // [{ id, title, … }]
await backend.documents.create({ templateId: templates[0]!.id })
```


# Themes (Obsidian)

> Render an Obsidian theme on the whole app, choose, upload and delete themes, and know the limits.

`themesFeature()` (`@skaile/forge-editor/themes/vue` or `/themes/react`, part of `advancedEditor()`; the simple editor stays backend-free) renders an [Obsidian](https://obsidian.md) theme (`theme.css` plus `manifest.json`) on the **whole app**: dashboard, navbars, toolbars, the settings panel, modals and the editor content. `<html>` carries `obsidian-theme theme-dark` or `obsidian-theme theme-light` according to `html.dark` (Nuxt colour mode, or your own `dark` class on React; without a `dark`/`light` class the system preference), observed live, so toggling the mode switches the palette without a reload. Every Nuxt UI `--ui-*` token (on React the shadcn tokens, through `themes-bridge.css` in `advanced.css`) is bridged to the theme's variables, so components follow without per-component CSS; the chrome uses the theme's interface font (the page's root font size stays untouched) and the editor content its text font. The Default appearance („Standard“) applies no Theme: it is the plain Nuxt UI (or shadcn) look. Builtin themes: Nord, Things, Minimal, Catppuccin, Border, Blue Topaz, Tokyo Night, Flexoki, Cupertino, Prism, iA Writer, Shimmering Focus, Gruvbox, Rosé Pine and Solarized. The runtime starts with the first mounted editor surface (the feature's `setup` hook) or the first pin, so a page with neither is not themed.

**Choosing a theme.** `themesFeature()` contributes the settings tab **„Theme“** (English label “Theme”; `SettingsAppearanceTab`, id `appearance`, shown by `EditorSettingsPanel`/`EditorSettingsModal` like any tab; the simple editor has none). Its select lists „Standard“ (English label “Default appearance”) plus every theme of `GET /api/editor/themes`, labelled `name – author`; the choice is `appearance.theme`, applies to the whole app at once and persists with the other settings (per browser, and to the server when remote settings are on). The app's navbars carry a `<UColorModeButton />` that toggles light/dark for the app and the theme together. Programmatically:

```ts
// `PUT /api/editor/settings` with `appearance: { theme: 'nord' }`, or in the browser console (settings are stored per browser until synced):
const key = 'tiptap-editor:settings'
localStorage.setItem(key, JSON.stringify({ ...JSON.parse(localStorage.getItem(key) ?? '{}'), appearance: { theme: 'nord' } }))
// `null` (the default) is the Default appearance.
```

Setup: `@skaile/forge-editor/styles/themes.css` after `core.css` and the feature sheets (the Nuxt module adds it last; React hosts of the advanced editor get it, with the shadcn bridge, from `react/styles/advanced.css`), and an adapter with `listThemes`/`loadTheme` ([EditorPorts](https://skaile-ai.github.io/forge-editor/guides/editor-ports)) serving `GET /api/editor/themes` and `GET /api/editor/themes/:id`. A custom list of features uses `themesFeature()` from `/themes/vue` or `/themes/react` (call the Vue one during component setup); the framework-free `themesFeatureCore(ui)`, `startObsidianTheme(ctx)` (the runtime; returns its release), `scopeThemeCss(css, scope?)` and the Vue-free `ThemeRecord`/`THEME_ID`/`themeManifestSchema` (`/themes/schema`) are exported for hosts.

**A theme per page (pin).** `pinObsidianTheme(ctx, id)` (`@skaile/forge-editor/themes`; `ctx` is the app's `EditorContext` or a `FeatureContext`) shows theme `id` (`null` = Default appearance) instead of `appearance.theme` until its release runs. The setting is not touched: nothing is persisted, and the rest of the app keeps the user's choice. Pins stack per app (the most recent wins, releasing it falls back to the one before, the last release to the setting), and a pin holds the theme runtime, so it applies on a page without an editor surface too. Taking the next page's pin before releasing the previous one in the same task loads only the next theme. The kitchen-sink layout of this repository pins each page's `theme` from its registry entry (`app/editor/kitchen-sink/pages.ts`), on the client only:

```ts
let release: (() => void) | undefined
watch(() => pageOf(route.path.split('/')[2] ?? '')?.theme, (theme) => {
  const previous = release
  release = theme ? pinObsidianTheme(appContext, theme) : undefined
  previous?.()
}, { immediate: true })
onUnmounted(() => release?.())
```

**How it works.** The runtime (one per app, shared by every editor on the page; started by the feature's `setup` hook and reference-counted, so it starts as soon as the first surface mounts; on Vue it then lives until the Vue app unmounts, also on pages without an editor, on React until the last surface that started it unmounts) reads `appearance.theme`, fetches the stylesheet through the app's `fetch` and scopes it with `scopeThemeCss`: `body`, `:root` and `html` rules become the scope element (`body.theme-dark` → `.obsidian-theme.theme-dark`), `.theme-dark`/`.theme-light` rules the scope element with that class, Obsidian's content-root classes (`.markdown-rendered`, `.markdown-preview-view`, `.markdown-source-view`, `.cm-s-obsidian`, …) `.tiptap`, everything else becomes a descendant selector; every emitted selector starts with `.obsidian-theme`. The scope element is `<html>`: the runtime toggles `obsidian-theme` and `theme-dark`/`theme-light` on `document.documentElement` (client side only; the first server-rendered paint shows the Default appearance). The result sits in one `<style data-tiptap-theme>` in `<head>` (removed again for `null`) and is cached per theme for the session. `@font-face`, `@keyframes`, `@media`, `@supports` and `@layer` survive.

**Brand tokens.** One package carries the Skaile brand: `@skaile/brand`. It holds the raw tokens (`@skaile/brand/theme.css`: `--color-success`, `--primary`, …) and the Vue/Nuxt bridge: `@skaile/brand/nuxt-ui.css` maps those tokens onto Nuxt UI's `--ui-*` variables. React hosts import `theme.css` directly. All examples and the app pin `^0.7.0`. When `--color-success` is defined, `--sk-success` follows it in every kit (`nuxt-ui.css`, `react/styles/ui-vars.css`), and the Obsidian bridge maps `--ui-success` to it before falling back to `--color-green`.

**What is mapped.** `styles/themes.css` defines Obsidian's variables with defaults (a theme overrides them) and maps them onto the whole app and the editor content:

<table>
<thead>
  <tr>
    <th>
      Element
    </th>
    
    <th>
      Obsidian variables
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Root <code>
        <html>
      </code>
      
       (background, text colour, interface font; no font size)
    </td>
    
    <td>
      <code>
        --background-primary
      </code>
      
      , <code>
        --text-normal
      </code>
      
      , <code>
        --font-interface
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .tiptap
      </code>
      
       (text font and size, line height, caret) and <code>
        ::selection
      </code>
    </td>
    
    <td>
      <code>
        --font-text
      </code>
      
      , <code>
        --font-text-size
      </code>
      
      , <code>
        --line-height-normal
      </code>
      
      , <code>
        --caret-color
      </code>
      
      , <code>
        --text-selection
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        p
      </code>
      
      , <code>
        h1
      </code>
      
      –<code>
        h6
      </code>
    </td>
    
    <td>
      <code>
        --p-spacing
      </code>
      
      , <code>
        --hN-size
      </code>
      
      /<code>
        -weight
      </code>
      
      /<code>
        -color
      </code>
      
      /<code>
        -line-height
      </code>
      
      /<code>
        -font
      </code>
      
      /<code>
        -variant
      </code>
      
      /<code>
        -style
      </code>
      
      , <code>
        --heading-spacing
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        strong
      </code>
      
      , <code>
        em
      </code>
      
      , <code>
        s
      </code>
      
      , <code>
        u
      </code>
    </td>
    
    <td>
      <code>
        --font-weight
      </code>
      
       + <code>
        --bold-modifier
      </code>
      
      , <code>
        --bold-color
      </code>
      
      , <code>
        --italic-color
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Links
    </td>
    
    <td>
      <code>
        --link-color
      </code>
      
      , <code>
        --link-color-hover
      </code>
      
      , <code>
        --link-external-color
      </code>
      
      , <code>
        --link-decoration
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        code
      </code>
      
      , <code>
        pre
      </code>
    </td>
    
    <td>
      <code>
        --code-background
      </code>
      
      , <code>
        --code-normal
      </code>
      
      , <code>
        --code-size
      </code>
      
      , <code>
        --code-radius
      </code>
      
      , <code>
        --font-monospace
      </code>
      
      , <code>
        --code-white-space
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockquote
      </code>
      
      , <code>
        hr
      </code>
    </td>
    
    <td>
      <code>
        --blockquote-*
      </code>
      
      , <code>
        --hr-color
      </code>
      
      , <code>
        --hr-thickness
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Lists, placeholder
    </td>
    
    <td>
      <code>
        --list-indent
      </code>
      
      , <code>
        --list-marker-color
      </code>
      
      , <code>
        --list-spacing
      </code>
      
      , <code>
        --text-faint
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .tag
      </code>
      
      , <code>
        .mention
      </code>
    </td>
    
    <td>
      <code>
        --tag-*
      </code>
      
      , <code>
        --text-accent
      </code>
      
      , <code>
        --background-modifier-hover
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        .composite
      </code>
      
      , <code>
        .media-block
      </code>
      
      , <code>
        img
      </code>
    </td>
    
    <td>
      <code>
        --embed-border-start
      </code>
      
      , <code>
        --embed-background
      </code>
      
      , <code>
        --radius-s
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Every package feature stylesheet (authors, comments, transcript, composites, media, mentions)
    </td>
    
    <td>
      follows through the Nuxt UI tokens, which the bridge points at Obsidian's: <code>
        --ui-text
      </code>
      
       → <code>
        --text-normal
      </code>
      
      , <code>
        --ui-bg
      </code>
      
       → <code>
        --background-primary
      </code>
      
      , <code>
        --ui-border
      </code>
      
       → <code>
        --background-modifier-border
      </code>
      
      , <code>
        --ui-primary
      </code>
      
       → <code>
        --interactive-accent
      </code>
      
      , <code>
        --ui-warning
      </code>
      
      /<code>
        --ui-error
      </code>
      
      /<code>
        --ui-success
      </code>
      
      /<code>
        --ui-info
      </code>
      
       → <code>
        --color-orange
      </code>
      
      /<code>
        red
      </code>
      
      /<code>
        green
      </code>
      
      /<code>
        blue
      </code>
      
      , <code>
        --font-mono
      </code>
      
       → <code>
        --font-monospace
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Host callout (<code>
        .callout[data-tone]
      </code>
      
      , <a href="https://github.com/skaile-ai/forge-editor/blob/main/app/editor/callout/callout.css" rel="nofollow">
        <code>
          app/editor/callout/callout.css
        </code>
      </a>
      
      )
    </td>
    
    <td>
      <code>
        --callout-info
      </code>
      
      , <code>
        --callout-warning
      </code>
      
      , … as RGB triplets (<code>
        rgba(var(--callout-color), 0.1)
      </code>
      
       background), <code>
        --callout-radius
      </code>
      
      , <code>
        --callout-padding
      </code>
      
      ; the host owns this mapping for its own blocks
    </td>
  </tr>
</tbody>
</table>

Cascade: the bridge is part of `@layer components`; the scoped theme is injected **unlayered**, so its rules beat the bridge and `core.css`. Selecting the Default appearance („Standard“, `null`) removes the style element and the three classes from `<html>`; the app then looks as before.

**Add a builtin theme (host).** In this repository a folder `server/themes/<id>/` with `manifest.json` (`name`, optional `version`, `author`, `authorUrl`; the folder name must match the `THEME_ID` pattern `^[a-z0-9][a-z0-9-]{0,63}$`), `theme.css` and the theme's `LICENSE` is a builtin: `server/utils/themes.ts` reads the folder once per process (restart the server after adding one) and `GET /api/editor/themes` marks it `builtin: true`. Seeded builtins (all MIT): Nord (`nord`), Things (`things`), Minimal (`minimal`), Catppuccin (`catppuccin`), Border (`border`), Blue Topaz (`blue-topaz`), Tokyo Night (`tokyo-night`), Flexoki (`flexoki`), Cupertino (`cupertino`), Prism (`prism`), iA Writer (`ia-writer`), Shimmering Focus (`shimmering-focus`), Gruvbox (`gruvbox`), Rosé Pine (`rose-pine`) and Solarized (`solarized`). Another host implements the adapter methods (`listThemes`/`loadTheme`, plus `storeTheme`/`removeTheme` for uploads) over its own storage.

**Upload and delete.** The „Theme“ tab has a row **„Theme hochladen“** with two file inputs, `theme.css` (required) and `manifest.json` (optional), and an upload button; below it the **Theme-Bibliothek** lists every theme with name, version and author. A successful upload joins the library for every user, is selected for the uploader and shows the toast „Theme „X“ hochgeladen“. Uploads carry a trash button (`DELETE`; deleting the selected theme resets `appearance.theme` to `null`, the Default appearance „Standard“); builtins carry the badge „mitgeliefert“ and no delete button. Failures appear as toasts with the server's German message.

<table>
<thead>
  <tr>
    <th>
      Route
    </th>
    
    <th>
      Request
    </th>
    
    <th>
      Answers
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        POST /api/editor/themes
      </code>
    </td>
    
    <td>
      multipart: <code>
        css
      </code>
      
       (File, required), <code>
        manifest
      </code>
      
       (File, optional), <code>
        name
      </code>
      
       (string, optional)
    </td>
    
    <td>
      <code>
        201
      </code>
      
       + <code>
        ThemeRecord
      </code>
      
       (<code>
        builtin: false
      </code>
      
      ); <code>
        400
      </code>
      
       missing <code>
        css
      </code>
      
      , „Ungültiges manifest.json“, or CSS that is not UTF-8 text or starts with markup (<code>
        <script
      </code>
      
      , <code>
        <?xml
      </code>
      
       within the first 512 bytes); <code>
        413
      </code>
      
       „Theme ist größer als 2 MB“
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE /api/editor/themes/:id
      </code>
    </td>
    
    <td>
      –
    </td>
    
    <td>
      <code>
        204
      </code>
      
      ; <code>
        404
      </code>
      
       unknown id; <code>
        403
      </code>
      
       „Mitgelieferte Themes können nicht gelöscht werden“ for builtins; <code>
        400
      </code>
      
       for an id that does not fit <code>
        THEME_ID
      </code>
    </td>
  </tr>
</tbody>
</table>

Both routes authenticate like the read routes and answer `501` when the host has no `themes` port. **Limits:** `theme.css` up to 2 MB (`MAX_THEME_BYTES`); the manifest is parsed with `themeManifestSchema` (`name` 1–120 characters; `version`, `author`, `authorUrl` optional). The name comes from the manifest, else the `name` field, else the CSS file's base name; the id is its slug (`[^a-z0-9]+` → `-`, at most 64 characters), made unique with `-2`, `-3` … against the library. In this repository uploads persist under `.data/themes/<id>/` (`manifest.json`, `theme.css`; Nitro storage mount `themes`) and survive restarts; the adapter methods `storeTheme(record, css)` and `removeTheme(id)` are the seam for another host's storage ([EditorPorts](https://skaile-ai.github.io/forge-editor/guides/editor-ports)).

**Failures.** A theme that cannot be loaded (deleted, network error, adapter without theme methods) falls back to the Default appearance for the session with a console warning (`tiptap-editor: Theme „<id>“ konnte nicht geladen werden …`); the stored setting is not changed. An id that does not fit `THEME_ID` is rejected by the settings schema.

**Limits.**

- Rules for Obsidian's own chrome (`.workspace*`, `.nav-*`, `.cm-line`, the sidebar, tabs, status bar) are scoped like the rest and match nothing in the app; they do no harm. The app chrome follows the theme through the Nuxt UI tokens only, not through an emulation of Obsidian's DOM.
- Obsidian sets body classes depending on settings and plugins (`is-mobile`, `is-translucent`, …); only `theme-dark`/`theme-light` are set on `<html>`, so rules that need other body classes do not apply (Catppuccin and Minimal fall back to their default palettes).
- `@import` is dropped (a theme never triggers remote requests); fonts must come as `@font-face` in the file, as the builtins do. Imported stylesheets and remote fonts are lost.
- Theme CSS is user-supplied and unlayered: a rule like `.obsidian-theme * { display: none }` breaks the app for whoever selected that theme. Themes are chosen per user.
- A theme's own `body { font-size }` rule lands on `<html>` after scoping and rescales `rem`, as Obsidian applies it to `body`; the bridge itself sets no root font size.
- Scoping needs `CSSStyleSheet.replaceSync` (Chrome 73+, Firefox 101+, Safari 16.4+). Selectors are rewritten from the browser's serialized `selectorText`, so quotes and spacing are normalised; the meaning is unchanged.

`bun run check:editor-entries` proves the isolation with the `themes` fixture.


# Typst: render a Document as a PDF with citations

> The add-on @skaile/forge-editor-typst: the render target typst-pdf that turns a Document or a paper into Typst markup, writes the bibliography as BibTeX, and compiles a PDF in one of four citation styles.

The add-on `@skaile/forge-editor-typst` adds one [render target](https://skaile-ai.github.io/forge-editor/guides/render), `typst-pdf`. It turns a whole Document, or one Typed block of the Block type `paper`, into a PDF made by [Typst](https://typst.app). The [Cite](https://skaile-ai.github.io/forge-editor/guides/citations) nodes of the content become citations, and the Bibliographic records inside the content become the bibliography.

The add-on is server-side only. It needs no editor feature: the block action **„Erzeugen als …“** and the command **„Dokument erzeugen als …“** list every target of the `render` capability, this one among them.

## Install and wire

```ts
import { createRenderer, markdownTarget } from '@skaile/forge-editor/adapters/render'
import { typstTarget } from '@skaile/forge-editor-typst'

// installEditorServer({ ports: { render } })
export const render = createRenderer([markdownTarget(), typstTarget({ style: 'apa', locale: 'de' })])
```

<table>
<thead>
  <tr>
    <th>
      Option of <code>
        typstTarget
      </code>
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        style
      </code>
    </td>
    
    <td>
      citation style when the render names none: one of <code>
        CSL_STYLES
      </code>
      
      , default <code>
        apa
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        locale
      </code>
    </td>
    
    <td>
      language of the PDF (hyphenation, the bibliography title) and of the error messages: <code>
        de
      </code>
      
       (default) or <code>
        en
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      the name in the export menu (default <code>
        PDF (Typst)
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accepts
      </code>
    </td>
    
    <td>
      Block types accepted besides <code>
        'document'
      </code>
      
       (default <code>
        ['paper']
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compile
      </code>
    </td>
    
    <td>
      <code>
        { engine?: 'auto' | 'node' | 'binary', binary?: string }
      </code>
      
      , see below
    </td>
  </tr>
</tbody>
</table>

A render input picks the style per request: `options: { style: 'ieee' }`.

## The compiler

`compileTypst` tries two engines in this order:

1. The native compiler `@myriaddreamin/typst-ts-node-compiler`, an optional dependency of the add-on. It runs inside the server process; no `typst` program is needed. The compile is synchronous and blocks the event loop while it runs.
2. The `typst` program on the `PATH` (or `compile.binary`). The add-on writes `main.typ` and `refs.bib` to a temporary directory, runs `typst compile`, reads the PDF and removes the directory. A client that disconnects aborts the process.

When neither exists the render fails with the error code `typst-missing`. Markup that Typst rejects fails with `typst-failed`; the message holds Typst's own diagnostics. A style outside `CSL_STYLES` fails with `bad-style` before any compile starts. All three are `TypstError` with a stable `code`; the message is in the language of the render and reaches the client as the `error` event.

## What the markup holds

`typstOf(content, bib, style)` is pure. It maps the content like the editor's Markdown export does:

<table>
<thead>
  <tr>
    <th>
      Content
    </th>
    
    <th>
      Typst
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      heading (level <em>
        n
      </em>
      
      )
    </td>
    
    <td>
      <code>
        =
      </code>
      
       repeated <em>
        n
      </em>
      
       times
    </td>
  </tr>
  
  <tr>
    <td>
      Typed block (depth <em>
        d
      </em>
      
      )
    </td>
    
    <td>
      heading of level <em>
        d
      </em>
      
       with its title (not when the title is hidden), the description in <code>
        #emph
      </code>
      
      , the tags in small grey text, then the body
    </td>
  </tr>
  
  <tr>
    <td>
      paragraph, hard break
    </td>
    
    <td>
      text; a break is <code>
        \
      </code>
      
       and a newline
    </td>
  </tr>
  
  <tr>
    <td>
      bold, italic, strike, underline, highlight, sub, super, code, link
    </td>
    
    <td>
      <code>
        #strong
      </code>
      
      , <code>
        #emph
      </code>
      
      , <code>
        #strike
      </code>
      
      , <code>
        #underline
      </code>
      
      , <code>
        #highlight
      </code>
      
      , <code>
        #sub
      </code>
      
      , <code>
        #super
      </code>
      
      , <code>
        #raw
      </code>
      
      , <code>
        #link
      </code>
      
       (the function form works inside a word, which <code>
        *…*
      </code>
      
       does not)
    </td>
  </tr>
  
  <tr>
    <td>
      bullet, ordered and task lists
    </td>
    
    <td>
      <code>
        -
      </code>
      
       and <code>
        1.
      </code>
      
       items, nested by indentation; a task item starts with ☐ or ☑
    </td>
  </tr>
  
  <tr>
    <td>
      table
    </td>
    
    <td>
      <code>
        #table
      </code>
      
       with <code>
        table.header
      </code>
      
       for a header row, <code>
        colspan
      </code>
      
       and <code>
        rowspan
      </code>
      
       kept
    </td>
  </tr>
  
  <tr>
    <td>
      code block, quote, rule
    </td>
    
    <td>
      <code>
        #raw(block: true)
      </code>
      
      , <code>
        #quote(block: true)
      </code>
      
      , <code>
        #line
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      mention, tag, reference chip
    </td>
    
    <td>
      their text
    </td>
  </tr>
  
  <tr>
    <td>
      image, audio, video, file, block embed
    </td>
    
    <td>
      the kind and name in italics: the editor's asset URLs are not files Typst can read
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        cite
      </code>
      
       node
    </td>
    
    <td>
      <code>
        @key
      </code>
      
      , or <code>
        @key[locator]
      </code>
    </td>
  </tr>
</tbody>
</table>

A `cite` whose key names an entry of the bibliography becomes a Typst citation. A `cite` whose key names none reads as the text `(key)`, like the editor's gone chip. When at least one citation resolved, the markup ends with `#bibliography("refs.bib", style: …, title: …)`; Typst prints only the works that are cited. A bare `@key` followed by unmarked text that continues the word gets an empty content block (`@key#[]`), so Typst does not read the text as part of the key.

## The bibliography

`bibEntriesOf(content)` collects the CSL-JSON record of every Typed block with `meta.bib`, in Document order, with the block id and the title. `bibFileOf(entries)` writes one BibTeX entry for each through the library's `bibtexOf`; the citation key is the one the `cite` node holds (`bibtexKey`). Two records that derive one key keep the first. The file is `refs.bib`, next to the main file.

<table>
<thead>
  <tr>
    <th>
      Style
    </th>
    
    <th>
      Typst style
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        apa
      </code>
    </td>
    
    <td>
      APA
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ieee
      </code>
    </td>
    
    <td>
      IEEE
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        chicago-author-date
      </code>
    </td>
    
    <td>
      Chicago author-date
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vancouver
      </code>
    </td>
    
    <td>
      Vancouver
    </td>
  </tr>
</tbody>
</table>

The styles are Typst's built-in CSL styles, so the add-on has no citation processor of its own.

## Pieces for your own pipeline

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        typstTarget(options?)
      </code>
    </td>
    
    <td>
      the <code>
        RenderTarget
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        typstOf
      </code>
      
      , <code>
        typstSourceOf
      </code>
    </td>
    
    <td>
      markup, or markup with its <code>
        .bib
      </code>
      
       text
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bibEntriesOf
      </code>
      
      , <code>
        bibFileOf
      </code>
      
      , <code>
        BIB_FILE
      </code>
    </td>
    
    <td>
      the bibliography of a content tree
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compileTypst
      </code>
      
      , <code>
        typstEngineOf
      </code>
    </td>
    
    <td>
      the PDF; which engine would run, or <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        CSL_STYLES
      </code>
      
      , <code>
        isCslStyle
      </code>
    </td>
    
    <td>
      the citation styles
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TypstError
      </code>
    </td>
    
    <td>
      the error with its <code>
        code
      </code>
    </td>
  </tr>
</tbody>
</table>


# Workspace: find, read, reference and embed Blocks across Documents

> The Block index, Workspace search, Block references and Embeds that name a Block address, Document routes with the DocumentMutator, Tool providers for the document chat, and change sets for edits to other Documents.

A **Block address** is the pair of a Document ID and a block ID. Block IDs are unique per Document only, so the block ID alone names a Block inside its own Document, and the address names it anywhere in the workspace. The workspace layer builds on that pair: a **Block index** holds one row per Block of every Document, and everything that crosses a Document boundary asks the index instead of opening the other Document.

<table>
<thead>
  <tr>
    <th>
      Piece
    </th>
    
    <th>
      What it does
    </th>
    
    <th>
      Port (capability)
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Block index
    </td>
    
    <td>
      one row per Block of every Document; answers <code>
        get
      </code>
      
      , <code>
        byDocument
      </code>
      
      , <code>
        documentIds
      </code>
      
      , <code>
        tags
      </code>
      
      , <code>
        search
      </code>
      
       and <code>
        edges
      </code>
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Block route
    </td>
    
    <td>
      summary or content of one Block by address
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Workspace search
    </td>
    
    <td>
      Blocks of the Documents the user may read whose title or text match
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Foreign references
    </td>
    
    <td>
      <code>
        [@<document>#<block>]
      </code>
      
       chips and Derived blocks whose original is in another Document
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Document routes and <code>
        DocumentMutator
      </code>
    </td>
    
    <td>
      list, create, move, remove and edit Documents from the server
    </td>
    
    <td>
      <code>
        documents
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Tool providers
    </td>
    
    <td>
      read-only tools of the document chat; <code>
        find_blocks
      </code>
      
       and <code>
        read_block
      </code>
    </td>
    
    <td>
      <code>
        index
      </code>
      
       (for the two tools)
    </td>
  </tr>
  
  <tr>
    <td>
      Change set
    </td>
    
    <td>
      edits the chat proposes for other Documents, decided per Document
    </td>
    
    <td>
      <code>
        changeSets
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockEmbed
      </code>
    </td>
    
    <td>
      a Block of any Document shown read-only inside another
    </td>
    
    <td>
      <code>
        index
      </code>
    </td>
  </tr>
</tbody>
</table>

Each piece is offered only when its port is present: a missing port turns its routes into `501`, its panel off and its tool answer into a sentence for the model. The split between what the library owns and what a host chooses is ADR-0003 (`docs/adr/0003-one-host-now-apps-ejectable-later.md`).

## The Block index

`BlockIndex` (`EditorPorts.index`, `@skaile/forge-editor/server`) is a **projection** of the Documents, not a second store. The `documents` port stays the truth, and the index can always be rebuilt from `listContents`. A row (`BlockRow`, `@skaile/forge-editor/core`) holds the Block address, the Block type (`type`; the node type for a Block that is not a Typed block), `title`, `properties`, `tags`, `references`, `derivedFrom`, two content hashes (`hash` and `sourceHash`) and the plain `text`. Every node that carries a block ID has a row; a node without an ID has none.

`projectDocument(content, documentId, options?)` computes the rows of one Document. It is pure and framework-free, so the same content always gives the same rows:

```ts [docs/snippets/workspace-index-rows.ts]
import type { JSONContent } from '@tiptap/core'
import { type BlockRow, projectDocument } from '@skaile/forge-editor/core'

// The Block index is a projection: the rows of a Document's content, one per node that carries a block ID.
// `projectDocument` is pure, so the same content always gives the same rows.
export function referencesOf(content: JSONContent, documentId: string): BlockRow['references'] {
  return projectDocument(content, documentId).flatMap(row => row.references)
}

// Every row holds its address, the Block type, the title, the plain text, the tags and the content hashes.
export function titlesOf(content: JSONContent, documentId: string): string[] {
  return projectDocument(content, documentId)
    .filter(row => row.title !== '')
    .map(({ blockId, type, title }) => `${documentId}#${blockId} (${type}): ${title}`)
}
```

The editor server keeps the index current. `installEditorServer` (and `provideEditorServer` for a Nuxt host) wraps the ports with `withBlockIndex`: the index is built from `listContents` at start, with the live content of an open Document first, and every write through the `documents` port (`storeContent`, `putDocument`, `deleteDocument`) re-projects the Document it touched. A failure of that maintenance is logged and never fails the write: the `documents` port is the truth, and the next write of the Document re-projects it. A host route that stores content itself calls `reindexDocument(id)` of the `EditorServer` handle afterwards. Reads wait for the first build.

The workspace tag list (`GET /api/editor/tags`, the `#` popup) is read from the Block index, so it reads no stored Document, with one exception: a Document that is currently open in the collaboration server is read from its live Y.Doc (`listWorkspaceTags` in `server/handlers/editor.ts`). A tag added in one open Document then shows in another before the debounced store. The index adds to that, so a tag removed in an open Document stays listed until the store re-projects the Document. A host without the `index` port gets the tags from the stored content of `documents` (`listCurrentContents`) instead, again with the live Y.Doc for open Documents.

Add the port next to the ones a host already has. `createWorkspaceTools()` registers the chat's two read-only tools, and `readableDocuments` on `identity` is optional (see Workspace search):

```ts [docs/snippets/workspace-ports.ts]
// server/plugins/editor-adapter.ts
import type { JSONContent } from '@tiptap/core'
import { createMemoryBlockIndex } from '@skaile/forge-editor/adapters/block-index'
import { createWorkspaceTools } from '@skaile/forge-editor/server'
import { provideEditorServer } from '@skaile/forge-editor/server/nitro'

export default defineNitroPlugin(() => {
  const contents = new Map<string, JSONContent>()
  provideEditorServer({
    ports: {
      identity: {
        authenticate: async () => ({ id: 'demo', username: 'demo' }),
        // Optional: the Documents a user may read, so a search never has to ask `authorize` once per Document.
        readableDocuments: async () => 'all',
      },
      documents: {
        loadContent: async id => contents.get(id) ?? null,
        storeContent: async (id, content) => { contents.set(id, content) },
        listContents: async () => [...contents].map(([id, content]) => ({ id, content })),
      },
      // The `index` capability: a projection of `documents`, rebuilt on start and kept current by the editor server.
      index: createMemoryBlockIndex(),
    },
    // The read-only tools of the document chat: `find_blocks` and `read_block`.
    tools: createWorkspaceTools(),
  })
})

// Nuxt auto-imports `defineNitroPlugin` in `server/plugins`; this declaration lets the file typecheck on its own.
declare function defineNitroPlugin(plugin: () => void): unknown
```

### Adapters

<table>
<thead>
  <tr>
    <th>
      Entry
    </th>
    
    <th>
      Factory
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/block-index
      </code>
    </td>
    
    <td>
      <code>
        createMemoryBlockIndex()
      </code>
    </td>
    
    <td>
      rows in memory by Document, then by block ID; gone with the process, so the server rebuilds them on start
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/block-index/drizzle
      </code>
    </td>
    
    <td>
      <code>
        createDrizzleBlockIndex({ db, tables: blockIndexTables() })
      </code>
      
      , <code>
        bootstrapBlockIndexTables(db)
      </code>
    </td>
    
    <td>
      the index in Postgres or PGlite through drizzle (<code>
        drizzle-orm
      </code>
      
      , optional peer)
    </td>
  </tr>
</tbody>
</table>

The drizzle adapter keeps two tables. `editor_block_index` (`document_id`, `block_id`, `seq`, `row`, `tags`, `title_words`, `text_words`, `text_length` and two generated `tsvector` columns with GIN indexes) holds the rows; `editor_block_edges` (`from_document_id`, `from_block_id`, `seq`, `to_document_id`, `to_block_id`, `tag`, `kind`, `origin`, with an index on the target) holds their [Edges](https://skaile-ai.github.io/forge-editor/guides/edges), written in the same transaction as the rows. The whole `BlockRow` sits in the `row` JSON column, so a later release can add row fields without a schema change. `blockIndexTables()` returns both tables (`{ blocks, edges }`) for the host's drizzle schema, so `drizzle-kit` migrates them; `bootstrapBlockIndexTables(db)` creates the tables and their indexes with `CREATE ... IF NOT EXISTS` for a host without migrations. `search` runs in the database and returns the same hits in the same order as the memory adapter: every query word must match the title or the text as a whole word or as the start of one, and a word in the title outranks any match in the text only. The adapters share one test suite (`test/support/block-index-contract.ts`), so a third adapter can be held to the same contract.

The reference app chooses its adapter with `NUXT_BLOCK_INDEX` (`memory`, the default, or `pglite`: Postgres in the process, in memory, rebuilt on every start). This is the PGlite start of `server/utils/block-index.ts`; a host with a Postgres server passes its own drizzle database to `createDrizzleBlockIndex` instead:

```ts [server/utils/block-index.ts]
byDocument: async documentId => (await started()).byDocument(documentId),
    documentIds: async () => (await started()).documentIds(),
    tags: async () => (await started()).tags(),
    search: async (query, scope, options) => (await started()).search(query, scope, options),
    edges: async (address, direction, scope) => (await started()).edges(address, direction, scope),
    query: async (query, scope, env, definitions) => (await started()).query(query, scope, env, definitions),
    ...(withVectors && {
      nearest: async (vector, scope, options) => (await started()).nearest!(vector, scope, options),
      related: async (address, scope, options) => (await started()).related!(address, scope, options),
    }),
  }
```

## The Block route

`GET /api/editor/blocks/:documentId/:blockId` answers the summary of one Block: `title`, `type`, `hash`, `sourceHash` and `gone`. `sourceHash` is what the stale badge of a Derived block with an original in another Document compares against the `inputHash` its Derivation recorded. The server answers `404` for an unknown Block or Document (the HTTP client turns that into `gone: true`) and `403` for a Document the user may not read. `?content=block` adds the Block's own nodes as TipTap JSON (`BlockSummary.content`), `?content=children` the Blocks nested in it; any other value is `400`. The content is read from the Document's current content, unsaved edits of an open Document included. In the client the route is `backend.index.blockGet(address, signal?, content?)`; foreign references and Embeds read through it.

## Workspace search

`GET /api/editor/search?q=` answers `BlockSearchHit[]` (`documentId`, `blockId`, `title`, `type`), best first, 20 at most. A query is words: a Block matches when every word occurs in its title or text, as a whole word or as the start of one, ignoring case and diacritics; a Block with a word in its title ranks above one that has it only in its text. A query without a word answers `[]`.

Search only ever sees Documents the user may read. The route asks `readableDocumentsOf(ports, user)` for the scope (`DocumentScope`: `'all'` or a list of Document IDs) and hands it to `BlockIndex.search`, so a Block of any other Document is never a candidate. There is one read rule for the whole workspace (`server/readable-documents.ts`: `documentAccess`, `mayReadDocument`, `mayEditDocument`, `readableAmong`), and the block route, the document GET, the tree, the ops route, the search and the chat's tools all ask it: `identity.readableDocuments(user)` decides when the host has it, else `authorize(user, id)` does (`null` = not readable), and with neither every authenticated user may read every Document. A Document that `readableDocuments` names but `authorize` refuses is read-only. Without `readableDocuments` the scope is `'all'` when there is no `authorize`, else every Document `authorize` does not refuse; the candidates come from `documents.listDocumentIds`, else `index.documentIds()` (the Documents that have Blocks, the only ones a search could find), else the IDs of `listContents`. A host with many Documents implements `readableDocuments`, because the derived scope costs one `authorize` call per Document and request.

The search panel is a framework-free model (`createSearchModel`, `@skaile/forge-editor/search`) behind a `SearchPanel` in each framework (`@skaile/forge-editor/search/vue`, `@skaile/forge-editor/search/react`). The panel never opens a hit itself: its `open` property is the host's navigation, which opens the Document and reveals the Block. `documentTitle` is optional and turns a Document ID into a label. The panel appears only when the backend has the `index` capability. This is the reference app's layout:

```vue [app/layouts/default.vue]
const selectedFolder = ref('')

// Workspace search: a hit in the open document is revealed in place; any other hit opens its document, whose page reveals
// the block (`?block=`) once the editor has synced.
const route = useRoute()
const activeEditor = useActiveEditor()
const { documents } = useDocuments()
const documentTitle = (id: string) => documents.value.find(document => document.id === id)?.title

// Edits the chat proposed for other documents wait here for the user's decision, per document.
const changeSets = useChangeSets()
const openDocument = (id: string) => navigateTo(`/documents/${id}`)

// The Explore panel (backlinks, related blocks, trail; with a knowledge graph a fourth tab) shows the Block „Verknüpfungen anzeigen“
// in the inspector chose (`useExploreTarget`). The graph panel (`NUXT_PUBLIC_ADDONS_GRAPH=1`) draws the Edges around the open document, or around that Block.
const exploreTarget = useExploreTarget()
const { graph: graphEnabled } = addonFlagsOf(useRuntimeConfig().public.addons)
```

```vue [app/layouts/default.vue]
to="/kitchen-sink"
```

## References to Blocks of other Documents

A reference chip (`ReferenceAttrs`) has an optional `documentId`. Without one it points into its own Document, as before. With one it points at a Block of another Document, and its label is the live title of that Block, read through `backend.index.blockGet` and refreshed in the background; the cached `label` only stands in while the Block cannot be resolved. The Markdown form puts the Document in front of the block ID, percent-encoded:

```md
[@minutes-2026-10#0d7c9a0e-3f1a-4a4e-9c52-1b8a6d3f2e11]
[@minutes-2026-10#0d7c9a0e-3f1a-4a4e-9c52-1b8a6d3f2e11, S. 12]
```

The second line adds a locator. A token without a Document keeps the short form `[@<block>]`. A token with a Document always becomes a chip, because the importing Document cannot tell whether the Block exists; the index resolves it or the chip shows it as gone. Typing `[@` offers Blocks of every Document through the search. The Markdown fence of a Typed block carries its block ID only when a reference chip or a field points at it, so the ID survives the Markdown round trip (ADR-0001).

A Derived block can name an original in another Document (`DerivationSource.document`). Whether it is stale is decided by comparing the `inputHash` its Derivation recorded with the `sourceHash` of the original's row, which the Block route also answers.

## Document routes and the DocumentMutator

A documents port that implements the optional `DocumentAdmin` members (`listTree`, `createDocument`, `moveDocument`, next to `deleteDocument`) serves the Document routes. Without those members they answer `501`. The list and the tree hide the Documents the user may not read.

<table>
<thead>
  <tr>
    <th>
      Route
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/editor/documents
      </code>
    </td>
    
    <td>
      the Documents the user may read, newest first
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        GET /api/editor/tree
      </code>
    </td>
    
    <td>
      the workspace as a folder tree
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/documents
      </code>
    </td>
    
    <td>
      creates a Document (<code>
        { title?, folder?, templateId? }
      </code>
      
      ; a <code>
        templateId
      </code>
      
       copies a Dokumentvorlage, see <a href="https://skaile-ai.github.io/forge-editor/guides/templates">
        Templates
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PUT /api/editor/documents/:id/folder
      </code>
    </td>
    
    <td>
      moves a Document into a folder
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DELETE /api/editor/documents/:id
      </code>
    </td>
    
    <td>
      removes a Document with its Yjs state and its rows in the index
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/documents/:id/ops
      </code>
    </td>
    
    <td>
      applies block operations (<code>
        { ops }
      </code>
      
      ), all or none
    </td>
  </tr>
</tbody>
</table>

The `DocumentMutator` behind the last route (`createDocumentMutator`, `@skaile/forge-editor/server`; `EditorServer.mutator` of the installed server) changes a Document nobody has to have open. The operations are those of the chat's `edit_document` tool (`update`, `add`, `delete`, `convert`). It checks each one against the block IDs of the Document, parses the Markdown without an editor (`createMarkdownBlocks`), writes an open Document inside its Y.Doc, so connected clients see an ordinary edit, and a stored Document through `storeContent`; the index is re-projected either way. Refusals are `HttpError`s: `403` for a user without write access, `404` for an unknown Document, `409` when a block the operations name no longer exists, `422` for an invalid operation. Host code that changes a Document on a user's behalf calls the same method:

```ts [docs/snippets/workspace-mutator.ts]
// server/api/documents/[id]/replace-block.post.ts
import { HttpError } from '@skaile/forge-editor/server'
import { useEditorServer } from '@skaile/forge-editor/server/nitro'

// A host route that changes a Document on a user's behalf. The mutator checks the user's right (`authorize`, 403), the block
// IDs (409 when a block is gone) and the operations (422), applies all or none, and keeps the Block index current.
export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  const user = await currentUser(event)
  if (!id || !user) throw new HttpError(400, 'Document and user needed')
  const { blockId, markdown } = await readBody<{ blockId: string, markdown: string }>(event)
  const { mutator } = useEditorServer()
  return mutator.apply(id, [{ type: 'update', id: blockId, markdown }], { user })
})

// Nuxt auto-imports and the host's session helper, declared so the file typechecks on its own.
declare function defineEventHandler(handler: (event: object) => Promise<unknown>): unknown
declare function getRouterParam(event: object, name: string): string | undefined
declare function readBody<T>(event: object): Promise<T>
declare function currentUser(event: object): Promise<object | null>
```

## Tool providers

The document chat has one tool of its own, `edit_document`. A host can add read-only tools: `tools` of `installEditorServer` or `provideEditorServer` takes a list of `ToolProvider`s (`@skaile/forge-editor/server`). A provider is `{ name, tool, handle(ctx, input) }`: `tool` is the AI SDK definition the model sees (description and input schema, no `execute`), `handle` is what the server runs. The server feeds the returned text back to the model and lets it answer again. `ToolContext` holds the ports, the user behind the request, an abort signal and `liveContent(id)`; every read must stay inside what that user may read. `toolRegistry(providers)` indexes the list and throws for a missing or duplicate name and for `edit_document`; the install calls it, so a bad provider fails at start.

`createWorkspaceTools(options?)` provides two:

<table>
<thead>
  <tr>
    <th>
      Tool
    </th>
    
    <th>
      Input
    </th>
    
    <th>
      Answers
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        find_blocks
      </code>
    </td>
    
    <td>
      <code>
        query
      </code>
      
      , <code>
        limit?
      </code>
      
       (10 by default)
    </td>
    
    <td>
      the best hits over the Documents the user may read: address, Block type, title and the start of the text
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        read_block
      </code>
    </td>
    
    <td>
      <code>
        documentId
      </code>
      
      , <code>
        blockId
      </code>
    </td>
    
    <td>
      the Block as Markdown (6000 characters at most, cut with a note), read from the current content
    </td>
  </tr>
</tbody>
</table>

An unreadable Document and an unknown Block get the same answer from `read_block`, so the tool never confirms that a Block exists where the user may not look. Without the `index` port a call answers that the workspace has no index. A provider can be wrapped to add behaviour; the wrapper keeps the definition:

```ts [docs/snippets/workspace-tool.ts]
import { createWorkspaceTools, type ToolProvider } from '@skaile/forge-editor/server'

// A ToolProvider is a definition for the model (`name`, `tool`: description and input schema, no `execute`) and the handler
// the server runs. `handle` gets the model's raw input and answers the text the model reads. This wrapper keeps the
// definition and adds a log line to every call; the `ToolContext` holds the ports, the user, an abort signal and `liveContent`.
function logged(provider: ToolProvider): ToolProvider {
  return {
    ...provider,
    async handle(ctx, input) {
      const answer = await provider.handle(ctx, input)
      console.info(`[tool ${provider.name}] ${JSON.stringify(input)} -> ${answer.length} characters`)
      return answer
    },
  }
}

// Register the result next to your own providers: `provideEditorServer({ ports, tools })`.
export const tools: ToolProvider[] = createWorkspaceTools().map(logged)
```

The reference app registers the tools in its Nitro plugin:

```ts [server/plugins/editor-adapter.ts]
listModels: async () => stubModelEnabled() ? [...publicEnvPresets(), stubModelProfile] : null,
      },
```

## Change sets

When the server has a `DocumentMutator` and the host provides the `changeSets` port (`EditorPorts.changeSets`, a `ChangeSetStore`; `createJsonAdapter({ dir }).changeSets` keeps them in `.change-sets.json`), `edit_document` accepts an optional `documentId` on an operation. Such an operation aims at another Document, which the user must be able to read and edit. The chat does not apply it. The server stores the operations of one answer as a **change set** for the asking user, and the user decides each **hunk** (one operation on one Block of one Document) on its own.

A hunk is `pending` until it is decided, then `accepted`, `rejected`, `stale` (a block it names is gone or changed underneath, `409`) or `invalid` (refused otherwise: `403`, `404`, `422`, or a failure of the mutator that is no HTTP refusal, so the hunk is never applied blindly again). Accepting a hunk applies it through the `DocumentMutator`, so the checks above decide. Accepting claims the named hunks atomically, so two requests for the same hunk cannot both apply it. A decided hunk never changes again, and the model gets the outcomes as feedback with the next message. A change set belongs to the user whose chat proposed it (`changeSetOwner(user)` is the key: `id`, else `username`, else the serialized user); only that user lists and decides it.

<table>
<thead>
  <tr>
    <th>
      Route
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/editor/change-sets
      </code>
    </td>
    
    <td>
      the user's change sets that still have a pending hunk, oldest first
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/change-sets/:id/accept
      </code>
    </td>
    
    <td>
      accepts the named hunks (<code>
        { hunks: ['op3', ...] }
      </code>
      
      ) and answers the change set
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/change-sets/:id/reject
      </code>
    </td>
    
    <td>
      rejects the named hunks; nothing is applied
    </td>
  </tr>
</tbody>
</table>

In the client, `createChangeSetModel({ backend: backend.changeSets })` (`@skaile/forge-editor/change-sets`) is the model, and `ChangeSetPanel` renders it grouped by Document (`@skaile/forge-editor/change-sets/vue` or `/react`). The same model goes to the chat as the `changeSets` property of `AiSidebar`, so the chat can hand over a new change set and read the decisions. Edits to the open Document stay with the in-document Review. The reference app wires it once, in `app/composables/useChangeSets.ts`, and places the panel next to the search:

```vue [app/layouts/default.vue]
icon="i-lucide-blocks"
```

## Embeds

A `blockEmbed` shows a Block of any Document, read-only, inside another Document. The Block has one **home**, the Document where it is stored and edited, and each embed is one **mount** of it. The embed stores no content: it is an atom node with `documentId`, `blockId`, `mode` (`block` or `children`, the Blocks nested in it) and a `label`, and its view reads the home Block. In the open Document itself the read is live and needs no request. For any other Document it goes through `backend.index.blockGet` with the Block's content, and the client **polls**: the server pushes nothing, so each mounted embed asks again every `FOREIGN_CONTENT_REFRESH_MS` (4 seconds), and an edit of the home Block shows in the other Document after at most about that long. A reference chip to another Document fetches only the summary, again when it is drawn after `FOREIGN_BLOCK_REFRESH_MS` (15 seconds) has passed since the last answer. An embed shows one of five states instead of content: `loading`, `gone` (the Block or its Document does not exist), `unavailable` (no index, a Document the user may not read, a failed read), `cycle` and `limit`.

The cycle guard follows the chain of Blocks an embed is rendered inside, outermost first. An embed whose home Block is already in that chain would render itself again, so it shows `cycle`. Embeds nest, so an embed can show a Block that holds embeds of its own, up to three levels deep and 24 mounted embeds under one outermost embed; past either bound an embed shows `limit` and neither reads nor follows its Block.

The Markdown form is on a line of its own, ids percent-encoded. Typing `![[` opens a popup that inserts one. `blockEmbedMarkdown` and `referenceMarkdown` write the two address forms (`@skaile/forge-editor/composites`):

```ts [docs/snippets/workspace-embed.ts]
import { blockEmbedMarkdown, referenceMarkdown } from '@skaile/forge-editor/composites'
import { compositeFeature } from '@skaile/forge-editor/composites/vue'

const address = { documentId: 'minutes-2026-10', blockId: '0d7c9a0e-3f1a-4a4e-9c52-1b8a6d3f2e11' }

// Both forms name a Block by its address (Document ID and block ID); the Document ID is percent-encoded.
export const embed = blockEmbedMarkdown(address)
// ![[minutes-2026-10#0d7c9a0e-3f1a-4a4e-9c52-1b8a6d3f2e11]]
export const embedChildren = blockEmbedMarkdown({ ...address, mode: 'children' })
// ![[minutes-2026-10#0d7c9a0e-3f1a-4a4e-9c52-1b8a6d3f2e11|children]]
export const chip = referenceMarkdown({ documentId: address.documentId, target: address.blockId, locator: 'S. 12' })
// [@minutes-2026-10#0d7c9a0e-3f1a-4a4e-9c52-1b8a6d3f2e11, S. 12]

// „Am Ursprung bearbeiten“ on an embed: the host opens the home Document with the Block revealed (`revealBlock`).
export const composites = compositeFeature({
  openBlock: ({ documentId, blockId }) => { console.info(`open /documents/${documentId}?block=${blockId}`) },
})
```

To edit an embedded Block, the user edits it at its home. `openBlock` of `compositeFeature` receives the address when the user picks „Am Ursprung bearbeiten“ on an embed; without it the embed has no such action. The host decides what that means. The reference app reveals the Block when its Document is the open one and otherwise opens the Document with `?block=<id>`, whose page reveals the Block (`revealBlock`) once the editor has synced:

```vue [app/pages/documents/[id].vue]
// „Am Ursprung bearbeiten“ on an embedded block: the open document reveals the block in place, any other opens its document with
// `?block=` (the reveal above).
function openEmbedSource({ documentId, blockId }: BlockAddress) {
  const instance = editor.value
```

## What the host supplies

The library owns the ports, the routes, the panels' models, the references, the Embed and the tools. The host chooses the storage behind `documents` and `index` (and `changeSets`), the access rule (`authenticate`, `authorize`, `readableDocuments`), where a hit or an Embed's source opens, and which Block types and tools an editor gets. See also the guides on the [editor ports](https://skaile-ai.github.io/forge-editor/guides/editor-ports), [storage adapters](https://skaile-ai.github.io/forge-editor/guides/storage-adapters) and [AI](https://skaile-ai.github.io/forge-editor/guides/ai).


# Vue-free advanced schema

> Use advancedSchemaExtensions() on a server, validator or migration without Vue, React or browser globals.

```ts
import { getSchema } from '@tiptap/core'
import { advancedSchemaExtensions } from '@skaile/forge-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, Typed block 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 `@skaile/forge-editor/schema/simple` for servers that only handle simple documents.

The package's collab server builds `collabSchema()` from this entry, or from the `schema` option when the host passes one (`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`.


# Block capability contract

> BlockCapability, the capability registry, the built-in capabilities with their config and appliesTo, and the BlockAction.requires gate.

The types below come from `packages/editor/src/core/capabilities.ts` and are exported from `@skaile/forge-editor/core`. For how to declare a capability and use it, see [Block capabilities, abilities and actions](https://skaile-ai.github.io/forge-editor/guides/block-capabilities).

## `BlockCapability`

A Feature declares capabilities in `EditorFeature.blockCapabilities`. `defineEditor` merges them with the built-in ones into `preset.capabilities` and throws for a duplicate id or an id of a built-in capability.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Unique across the preset. A Block type's <code>
        capabilities
      </code>
      
       entry and a <code>
        BlockAction.requires
      </code>
      
       or <code>
        DeriveMethod.requires
      </code>
      
       entry name it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        appliesTo
      </code>
    </td>
    
    <td>
      <code>
        (node, ctx: CapabilityContext) => boolean
      </code>
    </td>
    
    <td>
      Whether <code>
        node
      </code>
      
       has the capability. Memoised per node type and Block type id, so it may read only the node type (spec and flags), <code>
        ctx.blockTypeId
      </code>
      
       and the Block type's config (<code>
        ctx.configOf
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        perNode
      </code>
    </td>
    
    <td>
      <code>
        boolean?
      </code>
    </td>
    
    <td>
      <code>
        appliesTo
      </code>
      
       reads attributes of the node itself. It then runs for every node, so keep it a constant-time attribute check.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        configSchema
      </code>
    </td>
    
    <td>
      <code>
        ZodType?
      </code>
    </td>
    
    <td>
      Validates the config a Block type gives. Absent: the capability takes no config, and a Block type that gives one is refused.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        read
      </code>
    </td>
    
    <td>
      <code>
        (node, ctx) => unknown?
      </code>
    </td>
    
    <td>
      What the Block holds for the capability (Source child, Basket id, Bibliographic record), or <code>
        null
      </code>
      
      . Runs only for Blocks that have the capability; not memoised.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        storage
      </code>
    </td>
    
    <td>
      <code>
        { metaKeys?, childTypes? }?
      </code>
    </td>
    
    <td>
      Where the data lives: keys of the <code>
        meta
      </code>
      
       attribute, node type names of the children. Descriptive only.
    </td>
  </tr>
</tbody>
</table>

A capability never installs schema, extensions, node views or settings.

### `CapabilityContext`

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        blockTypeId
      </code>
    </td>
    
    <td>
      The persisted <code>
        attrs.blockType
      </code>
      
       of the node; <code>
        null
      </code>
      
       for a node without one.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockTypeOf(node)
      </code>
    </td>
    
    <td>
      The Block type of <code>
        node
      </code>
      
       among the editor's Block types; <code>
        null
      </code>
      
       for a node without one, an unknown id, or an editor without Block types.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        configOf(node, capability)
      </code>
    </td>
    
    <td>
      The config the Block type of <code>
        node
      </code>
      
       gives <code>
        capability
      </code>
      
      ; <code>
        undefined
      </code>
      
       when the type does not list it or lists it without config.
    </td>
  </tr>
</tbody>
</table>

`listsCapability(ctx.blockTypeOf(node), id)` is the usual `appliesTo` of a capability a Block type opts into.

## Registry and functions

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        BUILT_IN_BLOCK_CAPABILITIES
      </code>
    </td>
    
    <td>
      the structural capabilities every editor has (<code>
        container
      </code>
      
      , <code>
        title
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createCapabilityRegistry(capabilities)
      </code>
    </td>
    
    <td>
      a <code>
        CapabilityRegistry
      </code>
      
      : <code>
        capabilities
      </code>
      
       (built-in first, then the Features' in feature order), <code>
        has(id)
      </code>
      
      , <code>
        get(id)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createCapabilityIndex(registry, blockTypes)
      </code>
    </td>
    
    <td>
      the per-editor <code>
        CapabilityIndex
      </code>
      
      : <code>
        of(node)
      </code>
      
      , <code>
        read(node, id)
      </code>
      
      , <code>
        configOf(node, id)
      </code>
      
      . It depends on the editor's Block types, so editors do not share it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilitiesOf(editor, node)
      </code>
    </td>
    
    <td>
      ids of the capabilities <code>
        node
      </code>
      
       has
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilitiesAt(editor, pos)
      </code>
    </td>
    
    <td>
      the same for the Block at <code>
        pos
      </code>
      
      ; empty where no node starts
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilityConfigOf(editor, node, id)
      </code>
    </td>
    
    <td>
      the config the Block type gives the capability, or <code>
        undefined
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilityDataOf(editor, node, id)
      </code>
    </td>
    
    <td>
      what <code>
        read
      </code>
      
       returns, or <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        validateBlockTypes(registry, blockTypes)
      </code>
    </td>
    
    <td>
      throws when a Block type id is defined twice, a listed capability is unknown or listed twice, or a config fails its <code>
        configSchema
      </code>
      
      . <code>
        capabilityIssues(registry, type)
      </code>
      
       is the same check for one Block type, and returns the problems instead of throwing. <code>
        defineEditor
      </code>
      
       runs <code>
        validateBlockTypes
      </code>
      
       for the Block types of the Features when an editor is created.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockTypeConfigOf(type, id)
      </code>
    </td>
    
    <td>
      the config <code>
        type
      </code>
      
       gives the capability, or <code>
        undefined
      </code>
      
       (also without a <code>
        type
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        listsCapability(type, id)
      </code>
    </td>
    
    <td>
      whether <code>
        type
      </code>
      
       lists the capability; <code>
        false
      </code>
      
       without a <code>
        type
      </code>
    </td>
  </tr>
</tbody>
</table>

`typeIdOf(node)` (the Typed block module of `@skaile/forge-editor/core`) gives the `attrs.blockType` of a node (`''` for a node without one); `findBlockType(blockTypes, node)` is the Block type lookup. `BlockTypeCapability` (`{ id, config? }`) and `BlockTypeData` (`{ id, capabilities }`) are what the registry knows of a Block type; the public `BlockType` extends `BlockTypeData` ([Block type contract](https://skaile-ai.github.io/forge-editor/reference/block-types)).

## `BlockAction.requires`

`BlockAction.requires?: readonly string[]` lists capability ids. The action is hidden on a Block that lacks one of them. `blockActionsOf(preset, ctx)` throws when an id is declared by no Feature; `defineEditor` throws the same for a derive method. It replaces node-name checks in `isVisible`. `blockTypes?: readonly string[]` limits an action to named Block types and is for actions that are truly specific to a type. `ability` is a separate gate: `requires` is what the Block is, `ability` what its place in the document allows (`abilitiesAt(editor, pos, node)`); it hides the action but refuses no edit ([Abilities](https://skaile-ai.github.io/forge-editor/guides/block-capabilities#abilities)).

## Built-in capabilities

`container` and `title` are built in. The composites feature declares the others (`compositeBlockCapabilities()`), so a Block type file that is parsed with the default registry may name all of them. A Block type that lists a capability its node cannot hold (for example `source` on a type without a container body) has no effect.

<table>
<thead>
  <tr>
    <th>
      Id
    </th>
    
    <th>
      Config (<code>
        configSchema
      </code>
      
      )
    </th>
    
    <th>
      Applies to
    </th>
    
    <th>
      <code>
        read
      </code>
      
       returns
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        container
      </code>
    </td>
    
    <td>
      <code>
        { accepts?: string[] | 'all' }
      </code>
      
      : the Block types accepted as nested Typed blocks
    </td>
    
    <td>
      nodes that hold Blocks of their own (<code>
        doc
      </code>
      
      , a Typed block)
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        title
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      nodes whose content starts with chrome (the title row of a Typed block)
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        properties
      </code>
    </td>
    
    <td>
      <code>
        { definitions: PropertyDefinition[] }
      </code>
    </td>
    
    <td>
      a node with the <code>
        meta
      </code>
      
       attribute, if its Block type lists it
    </td>
    
    <td>
      the <code>
        meta
      </code>
      
       values of the keys the definitions name
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        source
      </code>
    </td>
    
    <td>
      <code>
        { media: ('image' | 'audio' | 'video' | 'file')[] }
      </code>
      
       (at least one)
    </td>
    
    <td>
      a container node, if its Block type lists it
    </td>
    
    <td>
      the Source media block, or <code>
        null
      </code>
      
       while the body holds none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        bibliography
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      a node with <code>
        meta
      </code>
      
      , if its Block type lists it
    </td>
    
    <td>
      the CSL-JSON item (<code>
        meta.bib
      </code>
      
      ), or <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        basket
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      a node with <code>
        meta
      </code>
      
      , if its Block type lists it
    </td>
    
    <td>
      the Basket id (<code>
        meta.basket
      </code>
      
      ), or <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        titleHidden
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      a node with <code>
        meta
      </code>
      
      , if its Block type lists it
    </td>
    
    <td>
      whether the title is hidden (<code>
        meta.titleHidden
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ai-brief
      </code>
    </td>
    
    <td>
      <code>
        { purpose, instructions?, instructionsField?, contentTemplate? }
      </code>
    </td>
    
    <td>
      any node whose Block type lists it
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        references
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      a node with <code>
        meta
      </code>
      
      , if its Block type lists it <strong>
        or
      </strong>
      
       one of its Property definitions has the type <code>
        reference
      </code>
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        import
      </code>
    </td>
    
    <td>
      <code>
        { media?: ('image' | 'audio' | 'video' | 'file')[] }
      </code>
    </td>
    
    <td>
      a container node, if its Block type lists it
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        export
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      a container node, if its Block type lists it
    </td>
    
    <td>
      none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derived
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      a node with <code>
        meta
      </code>
      
       whose <code>
        meta.derivation
      </code>
      
       is a Derivation (<code>
        perNode
      </code>
      
      ; any Typed block can be derived, whatever its Block type lists)
    </td>
    
    <td>
      the <code>
        Derivation
      </code>
    </td>
  </tr>
</tbody>
</table>

Storage of the built-ins that keep data: `properties` and `derived` use `meta` (`derived`: the key `derivation`), `bibliography` uses `meta.bib`, `basket` uses `meta.basket`, `titleHidden` uses `meta.titleHidden`, `source` keeps its media block in the body (`childTypes` `image`, `audio`, `video`, `file`), `references` uses `reference` nodes.

`titleHidden` gates the eye button of the chrome („Titel ausblenden“ / „Titel einblenden“, Vue and React `CompositeChrome`): a Typed block of a Block type that does not list it shows no button, so a host that shows or edits the title elsewhere can leave it out. The flag itself (`meta.titleHidden`) is a reserved key that every Block type keeps, and `setCompositeTitleHidden` works for every type; every built-in Block type lists the capability.

`ai-brief` is what the Block type tells the model: `purpose` goes into every AI request's block model; `instructions`, `instructionsField` and `contentTemplate` are read only by the AI fill ([Block types](https://skaile-ai.github.io/forge-editor/reference/block-types#blocktypeai)).


# Block type contract

> BlockType, the config types of the built-in capabilities, PropertyDefinition and the functions that read and combine Block types.

A Block type is plain data. The types come from `packages/editor/src/features/composites/block-types.ts`, `block-types-json.ts` and `core/properties.ts`; the Block type types are exported from `@skaile/forge-editor/composites` and `@skaile/forge-editor/composites/schema`; `PropertyDefinition` and `PROPERTY_TYPES` only from `@skaile/forge-editor/core`. For how to write and load them, see [Block types in code and JSON](https://skaile-ai.github.io/forge-editor/guides/block-types).

## `BlockType`

`BlockType` extends `BlockTypeData` (`{ id, capabilities }`). A Block type JSON file is one array of `BlockType`.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Stored in the <code>
        blockType
      </code>
      
       attribute of a Typed block, in Markdown fences and in AI requests. 1 to 50 letters, digits, <code>
        _
      </code>
      
       or <code>
        -
      </code>
      
       (checked by <code>
        parseBlockTypes
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Name shown to the user.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        icon
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Iconify name, e.g. <code>
        i-lucide-gavel
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        capabilities
      </code>
    </td>
    
    <td>
      <code>
        { id: string, config?: unknown }[]
      </code>
    </td>
    
    <td>
      The <a href="https://skaile-ai.github.io/forge-editor/reference/block-capabilities">
        capabilities
      </a>
      
       the Typed blocks of this type have, with their config. A capability that is not listed is absent. No other field switches a behaviour.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        titlePlaceholder
      </code>
    </td>
    
    <td>
      <code>
        string?
      </code>
    </td>
    
    <td>
      Placeholder of the empty title row.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        descriptionPlaceholder
      </code>
    </td>
    
    <td>
      <code>
        string?
      </code>
    </td>
    
    <td>
      Placeholder of the empty description row.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        chrome
      </code>
    </td>
    
    <td>
      <code>
        { tags?, tone?, controls? }?
      </code>
    </td>
    
    <td>
      How much chrome the type shows (below). Absent: all of it.
    </td>
  </tr>
</tbody>
</table>

`chrome`:

- `tags: false` hides the tag row of the type.
- `tone` is a CSS colour or `var(...)`. A Typed block of the type gets `data-block-type-tone` and `--sk-block-type-tone` on its wrapper (tinted surface and a left border), and its tree rows tint the type icon.
- `controls: false` makes the chrome of the Typed block read-only although the editor is editable: no basket menu, status menu, title-visibility toggle, tag editing or drag handle on the type icon, and a read-only details popover. An existing basket, status and tags still show as chips. Default `true`.

## Config of the built-in capabilities

<table>
<thead>
  <tr>
    <th>
      Interface
    </th>
    
    <th>
      Capability
    </th>
    
    <th>
      Members
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ContainerConfig
      </code>
    </td>
    
    <td>
      <code>
        container
      </code>
    </td>
    
    <td>
      <code>
        accepts?: readonly string[] | 'all'
      </code>
      
      : the Block types accepted as nested Typed blocks; absent: none. Content that is no Typed block is always allowed. Only new moves are checked.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        PropertiesConfig
      </code>
    </td>
    
    <td>
      <code>
        properties
      </code>
    </td>
    
    <td>
      <code>
        definitions: readonly PropertyDefinition[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SourceConfig
      </code>
    </td>
    
    <td>
      <code>
        source
      </code>
    </td>
    
    <td>
      <code>
        media: readonly SourceMedia[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ImportConfig
      </code>
    </td>
    
    <td>
      <code>
        import
      </code>
    </td>
    
    <td>
      <code>
        media?: readonly SourceMedia[]
      </code>
      
      : the media the type takes. Absent or empty: the type takes every imported file that no other type takes, text and Markdown included.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BlockTypeAi
      </code>
    </td>
    
    <td>
      <code>
        ai-brief
      </code>
    </td>
    
    <td>
      see <a href="#blocktypeai">
        <code>
          BlockTypeAi
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

`SourceMedia` is `'image' | 'audio' | 'video' | 'file'` (`SOURCE_MEDIA_TYPES`).

### `BlockTypeAi`

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        purpose
      </code>
    </td>
    
    <td>
      One or two sentences: what a Typed block of this type is for and what its body holds. Goes into every AI request's block model (chat, generate, tasks).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instructions?
      </code>
    </td>
    
    <td>
      Default instruction for filling the body of a Typed block of this type (what to write, structure, tone).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        instructionsField?
      </code>
    </td>
    
    <td>
      Key of a <code>
        textarea
      </code>
      
       property. A Typed block whose value is non-empty uses it instead of <code>
        instructions
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        contentTemplate?
      </code>
    </td>
    
    <td>
      AI content template: target text as Markdown. <code>
        {key}
      </code>
      
       placeholders are replaced by the Typed block's <code>
        meta[key]
      </code>
      
       before it goes to the model; unknown ones stay.
    </td>
  </tr>
</tbody>
</table>

`instructions`, `instructionsField` and `contentTemplate` are read only by the AI fill (`fillComposite`).

## `PropertyDefinition`

One Block property of a Block type, stored under `key` in the `meta` attribute of the Typed block. Defined in `core/properties.ts`.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        key
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Key under which the value is stored in <code>
        meta
      </code>
      
      . Non-empty; must not start with <code>
        $
      </code>
      
       (reserved for the pseudo-fields of a Block query).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Label in the inspector, the details popover and the table.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        type
      </code>
    </td>
    
    <td>
      <code>
        'text' | 'textarea' | 'date' | 'number' | 'select' | 'multiselect' | 'reference' | 'bibliography' | 'derivation' | 'checkbox' | 'url' | 'status' | 'reference-list' | 'source-anchor'
      </code>
    </td>
    
    <td>
      The entries of <code>
        PROPERTY_TYPES
      </code>
      
      . <code>
        bibliography
      </code>
      
      : CSL-JSON item under <code>
        meta.bib
      </code>
      
      . <code>
        derivation
      </code>
      
      : read-only Derivation of a Derived block. <code>
        reference
      </code>
      
      : block ID of another Typed block. <code>
        multiselect
      </code>
      
      : several of <code>
        options
      </code>
      
      , stored as <code>
        string[]
      </code>
      
      ; the key is removed when none is chosen. <code>
        checkbox
      </code>
      
      : <code>
        true
      </code>
      
      ; unchecked removes the key. <code>
        url
      </code>
      
      : a link as text. <code>
        status
      </code>
      
      : one of <code>
        options
      </code>
      
      , whose options carry a <code>
        group
      </code>
      
      . <code>
        reference-list
      </code>
      
      : <code>
        BlockAddress[]
      </code>
      
       (<code>
        documentId
      </code>
      
       <code>
        ''
      </code>
      
       = this Document). <code>
        source-anchor
      </code>
      
      : <code>
        SourceAnchor
      </code>
      
      , a passage of a PDF (<code>
        page
      </code>
      
      , <code>
        rects
      </code>
      
      , <code>
        quote
      </code>
      
      ); read-only in the form.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code>
        PropertyOption[]?
      </code>
      
       (<code>
        { value: string, label: string, group?: 'todo' | 'doing' | 'done' }
      </code>
      
      )
    </td>
    
    <td>
      Choices of a <code>
        select
      </code>
      
      , <code>
        multiselect
      </code>
      
       or <code>
        status
      </code>
      
       property; required for <code>
        multiselect
      </code>
      
      . <code>
        group
      </code>
      
       belongs to <code>
        status
      </code>
      
       options.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        targets
      </code>
    </td>
    
    <td>
      <code>
        readonly string[]?
      </code>
    </td>
    
    <td>
      <code>
        reference
      </code>
      
       only: the Block type ids the reference may point to. Absent: any Typed block.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        hidden
      </code>
    </td>
    
    <td>
      <code>
        boolean?
      </code>
    </td>
    
    <td>
      Stored and queried like any property, but not shown in the Block inspector, the details popover or the Block table.
    </td>
  </tr>
</tbody>
</table>

For the behaviour of each type, see [Block properties](https://skaile-ai.github.io/forge-editor/guides/block-properties). `PROPERTY_KINDS` (`@skaile/forge-editor/core`) maps every type to a `PropertyKind` (`ops`, `sortKey`, `groupKey`, `aggregates`, `text`, `longText`, `align`); the filter, aggregate and environment types it uses (`FilterOp`, `AggregateFn`, `QueryEnv`) live in `core/query-types.ts`.

## Functions

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Returns
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        defaultBlockTypes(t)
      </code>
    </td>
    
    <td>
      the built-in Block types in the language of translator <code>
        t
      </code>
      
       (<code>
        createTranslator('de')
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockTypeOf(blockTypes, id)
      </code>
    </td>
    
    <td>
      the Block type with that id; an unknown id gets the presentation of the <code>
        section
      </code>
      
       type (else the first type) under its own id and label
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockTypeConfigOf(type, id)
      </code>
      
      , <code>
        listsCapability(type, id)
      </code>
    </td>
    
    <td>
      the config the type gives capability <code>
        id
      </code>
      
       (<code>
        undefined
      </code>
      
       when it gives none) and whether it lists it. Both are in <code>
        @skaile/forge-editor/core
      </code>
      
       (<a href="https://skaile-ai.github.io/forge-editor/reference/block-capabilities">
        Block capabilities
      </a>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        isRootBlockType(type)
      </code>
    </td>
    
    <td>
      whether the <code>
        container
      </code>
      
       config of the type says <code>
        root: true
      </code>
      
      : the type stands for the file of a document tree (the built-in Document type)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        propertiesOf(type)
      </code>
    </td>
    
    <td>
      the Property definitions of the type (none without the <code>
        properties
      </code>
      
       capability)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sourceMediaOf(type)
      </code>
    </td>
    
    <td>
      the media of its <code>
        source
      </code>
      
       capability, or <code>
        undefined
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aiBriefOf(type)
      </code>
    </td>
    
    <td>
      its <code>
        ai-brief
      </code>
      
       config, or <code>
        undefined
      </code>
      
       (the AI fill is not offered then)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        acceptsChild(blockTypes, parentType, childType)
      </code>
    </td>
    
    <td>
      whether <code>
        parentType
      </code>
      
       accepts <code>
        childType
      </code>
      
       as nested Typed block; a parent type the list does not know accepts nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        acceptsImport(blockTypes, parentType)
      </code>
    </td>
    
    <td>
      whether an imported file can go into a Typed block of <code>
        parentType
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        importTypeOf(blockTypes, media)
      </code>
    </td>
    
    <td>
      the id of the Block type that takes an imported file of <code>
        media
      </code>
      
       (<code>
        null
      </code>
      
      : text, Markdown or another file the media pipeline does not know): the first type whose <code>
        import
      </code>
      
       names <code>
        media
      </code>
      
      , else the first that lists <code>
        import
      </code>
      
       without media; <code>
        undefined
      </code>
      
       when none takes it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aiBlockTypesOf(blockTypes)
      </code>
    </td>
    
    <td>
      the Block types as the AI chat model learns them: <code>
        AiContextBlockType[]
      </code>
      
      , <code>
        { id, label, fields, purpose? }
      </code>
      
       (<code>
        fields
      </code>
      
      : the Property definitions)
    </td>
  </tr>
</tbody>
</table>

## JSON files

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        parseBlockTypes(input, { registry? })
      </code>
    </td>
    
    <td>
      reads a JSON array of <code>
        BlockType
      </code>
      
       (text or parsed value) and checks each entry: the fields (strict: unknown members are refused), a unique <code>
        id
      </code>
      
      , every listed capability exists and is listed once, and its <code>
        config
      </code>
      
       passes the <code>
        configSchema
      </code>
      
      . A capability without a <code>
        configSchema
      </code>
      
       takes no config. <code>
        registry
      </code>
      
       defaults to the built-in capabilities and those of the composites feature; pass <code>
        preset.capabilities
      </code>
      
       when a Feature adds more. Throws <code>
        BlockTypeJsonError
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mergeBlockTypes(base, extra)
      </code>
    </td>
    
    <td>
      layers <code>
        extra
      </code>
      
       over <code>
        base
      </code>
      
      : a type with an id that <code>
        base
      </code>
      
       has replaces it in place, the others follow
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BlockTypeJsonError
      </code>
    </td>
    
    <td>
      <code>
        Error
      </code>
      
       with <code>
        issues: BlockTypeJsonIssue[]
      </code>
      
      ; <code>
        message
      </code>
      
       has one line per issue
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        BlockTypeJsonIssue
      </code>
    </td>
    
    <td>
      <code>
        { index, typeId, capability, path, message }
      </code>
      
      : the entry's position (<code>
        -1
      </code>
      
       for the file), its <code>
        id
      </code>
      
       (<code>
        null
      </code>
      
       when it has none), the capability whose config is wrong (<code>
        null
      </code>
      
       for the entry itself) and the path inside the entry or config, e.g. <code>
        definitions[0].type
      </code>
    </td>
  </tr>
</tbody>
</table>

## Where Block types go in

<table>
<thead>
  <tr>
    <th>
      Place
    </th>
    
    <th>
      Option
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        compositeFeature({ blockTypes })
      </code>
      
       (Vue and React), <code>
        compositeFeatureCore(ui, { blockTypes })
      </code>
    </td>
    
    <td>
      the Block types of the editor
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        compositeSchemaExtensions({ blockTypes })
      </code>
    </td>
    
    <td>
      schema only; Block types are storage, not schema
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        composeEditor({ blockTypes })
      </code>
      
      , <code>
        AdvancedEditor
      </code>
      
       and <code>
        ComposedSurface
      </code>
      
       prop <code>
        blockTypes
      </code>
    </td>
    
    <td>
      the same, for the surfaces
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        installEditorServer(nitroApp, { ports, blockTypes })
      </code>
      
      , <code>
        provideEditorServer({ ports, blockTypes })
      </code>
      
      , <code>
        AiHandlerContext.blockTypes
      </code>
    </td>
    
    <td>
      the server side: the AI chat describes these types to the model
    </td>
  </tr>
</tbody>
</table>

Without `blockTypes` the built-in types apply: the editor falls back to `defaultBlockTypes` in the language of its translator.


# Changelog

> Release history of @skaile/forge-editor on GitHub and the current version on npm.

The changelog is kept next to the package: [CHANGELOG.md on GitHub](https://github.com/skaile-ai/forge-editor/blob/main/packages/editor/CHANGELOG.md).

[![npm version](https://img.shields.io/npm/v/@skaile/forge-editor)](https://www.npmjs.com/package/@skaile/forge-editor)


# Commands

> Build, check and dev commands of the repository: what each one proves and when to run it.

## Repository commands

From the repository root, after `bun install`:

```sh
bun run dev                                   # Nuxt demo app, http://localhost:3056
bun run typecheck                             # nuxt typecheck of the demo app
bun run --cwd examples/vue-simple dev        # http://localhost:3040
bun run --cwd examples/vue-simple build      # prepares the Nuxt UI theme aliases the library typecheck needs
bun run --cwd examples/vue-simple typecheck
bun run --cwd examples/react-simple dev     # http://localhost:3041
bun run --cwd examples/react-simple typecheck
bun run --cwd examples/react-advanced dev   # http://localhost:3043, needs `bun run dev` (Nuxt host, port 3056)
bun run --cwd examples/react-advanced typecheck
bun run --cwd examples/vue-markdown dev     # http://localhost:3045, MarkdownSurface with frontmatter, tables and source mode
bun run example:two-pane                      # http://localhost:3047, two panes over a Nitro server: Baskets, Document tree focus and filter, splitting, block transfer (examples/vue-two-pane; AI_KEY for the AI features)
bun run typecheck:editor                      # vue-tsc --noEmit -p packages/editor/tsconfig.json (no Nuxt globals)
bun run check:editor-entries                  # production build per fixture, module-graph isolation rules
bun run check:editor-legacy-names             # no former name of the block vocabulary in sources, app, examples, docs
bun run check:editor-markdown-clipboard       # MarkdownClipboard paste/copy cases (HTML, Markdown, plain text, data-URL opt-in) in happy-dom
bun run check:editor-composition              # defineEditor rejects missing `requires`; accepted compositions; one formatAiResult contributor
bun run test:editor                           # bun test over packages/editor/test: framework-free models on a mounted editor (happy-dom)
```

On a clean checkout run the example build once before `typecheck:editor`.

## Building and developing in this repository

`bun run build:editor` (`tsdown`, config `packages/editor/tsdown.config.ts`) writes `packages/editor/dist`: ESM plus `.d.ts` for every `exports` subpath (the entries are read from the `skaile-source` condition of `package.json#exports`, so a new export is built as soon as it is declared), unbundled one module per source file, source maps with embedded sources, CSS copied, and the Nuxt runtime directory (`dist/nuxt/runtime`: plugin, server routes, utils) as separate files next to the module that Nuxt and Nitro compile in the host. Dependencies and peers are never bundled.

Each `exports` entry carries a custom **skaile-source** condition first (pointing at `src`) followed by `types`/`import` (or `default`) pointing into `dist`. This repository's Nuxt app (`nuxt.config.ts`) and the examples (`examples/*/vite.config.ts`, `tsconfig.json#customConditions`) enable that condition for Vite, Nitro and the type checker, so **editing the library needs no build step in dev**. Consumers outside the repository never set the condition and get `dist`. `bun run check:editor-entries` builds first and judges the **built** output through `exports` (no `skaile-source`), so it proves what is published; `bun run check:editor-composition` builds first and loads the built entries; `bun run typecheck:editor` resolves through `src` (`customConditions: ["skaile-source"]` in `packages/editor/tsconfig.json`).

## 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:3056
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`.


# CSS and UI-provider requirements

> Design tokens, stylesheet order, Tailwind sources and the UI kit each surface needs.

- Design tokens: `@skaile/forge-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`) with light defaults under `:where(:root)` and dark values under `:where(.dark)`. Every feature stylesheet reads them; a UI kit maps them onto its own variables (Nuxt UI: `vue/kit/nuxt-ui.css`, React/shadcn: `react/styles/ui-vars.css`), a host may override them once.
- Basket colours: `@skaile/forge-editor/styles/composites.css` declares the colours of the default colour Baskets (`compositeFeature({ baskets })`) as `--sk-basket-red`, `--sk-basket-orange`, `--sk-basket-yellow`, `--sk-basket-green` and `--sk-basket-blue`, light values under `:where(:root)` and dark values under `:where(.dark)` like the design tokens, so a host overrides them once. A custom Basket brings its own `color`. The Typed block's node view sets `--sk-basket-color` on a Typed block in a Basket; the stripe reads it.
- Block type tone: a Block type with `chrome.tone` (`BlockType`, any CSS colour or `var(...)`) sets its Typed blocks apart. The Typed block's node view sets `data-block-type-tone` and `--sk-block-type-tone` on the wrapper of such a Typed block; `composites.css` tints its surface with the tone and paints the left border in it (a Basket stripe still wins on the border), and the Document tree rows of the Block type tint the Block type icon. How strong the tint is comes from `--sk-block-type-tone-mix` (`8%` under `:where(:root)`, `14%` under `:where(.dark)`, like the Basket colours). A Block type without a tone is untouched.
- Vue UI kit: the Vue binding is built on Nuxt UI. The chrome renders through the kit handed to `createEditor({ kit })`; `kit` is optional and defaults to `nuxtUiKit()` (`@skaile/forge-editor/vue/kit/nuxt-ui`, needs `@nuxt/ui`, stylesheet `@skaile/forge-editor/vue/kit/nuxt-ui.css`). `@skaile/forge-editor/vue/kit` holds the `VueUiKit` contract and `useUiKit()`; pass your own `VueUiKit` only to render the chrome with another library. Only the `nuxt-ui` kit entry imports `@nuxt/ui`. The Nuxt module has no `kit` option: it always adds `vue/kit/nuxt-ui.css`, patches Nuxt UI's `ui.css` so Tailwind scans the package (`@nuxt/ui` must be registered before the module) and installs the Nuxt UI context plugin.
- Import the core CSS **after** Tailwind and Nuxt UI, and let Tailwind see the library's classes. Scan the whole `dist` of the package (Vue files in `dist/vue` and `dist/features/*/components`, React files in `dist/react` and `dist/features/*/react`), never a single subdirectory; in this repository the examples scan `packages/editor/src`:```css
@import "tailwindcss";
@import "@nuxt/ui";
@import "@skaile/forge-editor/styles/core.css";
@source "../node_modules/@skaile/forge-editor/dist"; /* relative path from this CSS file to the installed package's dist */
```

<br />

The Nuxt module needs none of this: it adds `core.css` and every feature sheet to `css` (`themes.css` last) and appends the package to Tailwind's `@source` list. In plain Vue also import the sheet of each feature you use, e.g. `@skaile/forge-editor/styles/media.css`, after `core.css`. The AI sidebar (`@skaile/forge-editor/ai/vue/chat`) renders on the optional peer `@skaile/forge-chat`, whose resources the host owns, in Nuxt as well: import `@skaile/forge-chat/styles/chat.css`, add `@source` for `@skaile/forge-chat/dist` (e.g. `@source "../../../node_modules/@skaile/forge-chat/dist";`) and, in Nuxt, `'@skaile/forge-chat/nuxt'` after `'@nuxt/ui'` in `modules`. `styles/ai.css` no longer imports the chat stylesheet.
- Plain Vue: Vite plugins `vue()` and `ui({ router: false })` from `@nuxt/ui/vite`, `app.use(ui)` with `import ui from '@nuxt/ui/vue-plugin'`, and the editor context `app.use(createEditor())` (`createEditor` from `@skaile/forge-editor/vue`). Wrap the page in `<UApp>` (overlays, toasts, tooltips).
- React: Vite with `@vitejs/plugin-react` and `@tailwindcss/vite`. The CSS needs Tailwind, `tw-animate-css`, `@skaile/forge-editor/react/styles/ui-vars.css`, `core.css` (plus the sheet of each feature you use, e.g. `mentions.css`), the shadcn theme block (`:root`/`.dark` tokens and `@theme inline`; `bunx shadcn@latest init` generates it) and `@source` for the library's whole `dist` (`@source "../node_modules/@skaile/forge-editor/dist";`): the Features' React components live in `dist/features/*/react`, not in `dist/react`. For the advanced editor import `@skaile/forge-editor/react/styles/advanced.css` instead of those three library sheets: it bundles `ui-vars.css`, `core.css`, every feature sheet and `themes.css` (last). Preload the icons with `addCollection(lucide)` from `@iconify/react`, wrap the tree in `<EditorContextProvider context={createEditorContext({ notify: reactNotifier })}>` and mount `<Toaster />` (sonner, from `@skaile/forge-editor/react`) once so notices show up; see the [usage guide](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-react), [Advanced editor in React](https://skaile-ai.github.io/forge-editor/guides/advanced-react), [`examples/react-simple`](https://github.com/skaile-ai/forge-editor/tree/main/examples/react-simple) and [`examples/react-advanced`](https://github.com/skaile-ai/forge-editor/tree/main/examples/react-advanced).
- Icons: Nuxt UI resolves `i-lucide-*` names at build time. A workspace library lies outside the Vite root that Nuxt UI scans, so list its icons for the client bundle (see how `examples/vue-simple/vite.config.ts` collects them) to avoid Iconify API requests at runtime.
- The editor context is mandatory: Vue `EditorSurface`, `SimpleEditor` and `EditorToolbar` throw a descriptive error without `createEditor()`, the React components without `<EditorContextProvider>`. Both wrap the framework-free `createEditorContext()` from `@skaile/forge-editor/core`; the host owns the React context and may call `context.dispose()` itself.


# Dependency rules

> Which layer of @skaile/forge-editor may import which, and how the bundle isolation check enforces it.

Imports inside `packages/editor/src` follow one direction; the entry checks enforce them on the emitted bundles.

<table>
<thead>
  <tr>
    <th>
      Layer
    </th>
    
    <th>
      May import
    </th>
    
    <th>
      Must not import
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        core
      </code>
      
      , <code>
        settings
      </code>
    </td>
    
    <td>
      each other, external packages other than <code>
        vue
      </code>
      
      , <code>
        @tiptap/vue-3
      </code>
      
      , <code>
        @nuxt/ui
      </code>
      
      , <code>
        react
      </code>
      
      , <code>
        sonner
      </code>
    </td>
    
    <td>
      those, <code>
        vue/
      </code>
      
      , <code>
        react/
      </code>
      
      , any feature, integration, <code>
        outline
      </code>
      
      , <code>
        tree
      </code>
      
      , preset, <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        vue
      </code>
      
       (<code>
        src/vue
      </code>
      
      : <code>
        EditorSurface
      </code>
      
      , <code>
        EditorToolbar
      </code>
      
      , settings components, <code>
        createEditor
      </code>
      
      , <code>
        useEditorUi
      </code>
      
      , <code>
        vueSuggestionRenderer
      </code>
      
      , the queued notifier; <code>
        SimpleEditor
      </code>
      
      /<code>
        AdvancedEditor
      </code>
      
       also the preset they mount)
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        settings
      </code>
      
      , Vue, <code>
        @tiptap/vue-3
      </code>
      
      , Nuxt UI
    </td>
    
    <td>
      <code>
        react
      </code>
      
      , <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        react
      </code>
      
       (<code>
        src/react
      </code>
      
      : <code>
        EditorSurface
      </code>
      
      , <code>
        EditorToolbar
      </code>
      
      , settings components, <code>
        EditorContextProvider
      </code>
      
      , <code>
        reactSuggestionRenderer
      </code>
      
      , <code>
        reactNotifier
      </code>
      
      , vendored shadcn primitives in <code>
        ui/
      </code>
      
      ; <code>
        SimpleEditor
      </code>
      
      /<code>
        AdvancedEditor
      </code>
      
       also the preset they mount)
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        settings
      </code>
      
      , React, <code>
        @tiptap/react
      </code>
      
      , Radix, sonner, <code>
        @iconify/react
      </code>
      
      , framework-free features and presets
    </td>
    
    <td>
      <code>
        vue
      </code>
      
      , <code>
        @tiptap/vue-3
      </code>
      
      , Nuxt UI, <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        outline
      </code>
      
      , <code>
        outline/vue
      </code>
      
      , <code>
        outline/react
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
       (and its layer)
    </td>
    
    <td>
      <code>
        tree
      </code>
      
      , composites, any feature
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        search
      </code>
      
      , <code>
        search/vue
      </code>
      
      , <code>
        search/react
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
       (and its layer)
    </td>
    
    <td>
      <code>
        tree
      </code>
      
      , <code>
        outline
      </code>
      
      , composites, any feature
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        change-sets
      </code>
      
      , <code>
        change-sets/vue
      </code>
      
      , <code>
        change-sets/react
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
       (and its layer)
    </td>
    
    <td>
      <code>
        tree
      </code>
      
      , <code>
        outline
      </code>
      
      , <code>
        search
      </code>
      
      , composites, any feature
    </td>
  </tr>
  
  <tr>
    <td>
      features (<code>
        media
      </code>
      
      , <code>
        mentions
      </code>
      
      , <code>
        transcript
      </code>
      
      , <code>
        authors
      </code>
      
      , <code>
        comments
      </code>
      
      , <code>
        composites
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        collab
      </code>
      
      , <code>
        block-ui
      </code>
      
      , <code>
        themes
      </code>
      
      ): <code>
        features/<x>/{index,feature,model…}.ts
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        settings
      </code>
      
      , their own <code>
        schema
      </code>
      
      /<code>
        protocol
      </code>
      
      ; no UI framework
    </td>
    
    <td>
      another feature (by implementation), integrations, <code>
        tree
      </code>
      
      , <code>
        vue
      </code>
      
      , <code>
        react
      </code>
      
      , <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transfer
      </code>
      
       (<code>
        features/transfer
      </code>
      
      : the block drop target, its menu, <code>
        copyTransform
      </code>
      
      , <code>
        BlockTransform
      </code>
      
      /<code>
        TransferEnv
      </code>
      
      , the payload plumbing)
    </td>
    
    <td>
      <code>
        core
      </code>
      
       and the <code>
        composites/schema
      </code>
      
       entry
    </td>
    
    <td>
      any other feature by implementation, integrations, <code>
        tree
      </code>
      
      , a UI framework in its framework-free files. Its AI transforms (<code>
        summaryTransform
      </code>
      
      , <code>
        bulletsTransform
      </code>
      
       and their tasks) live in <code>
        integrations/composite-ai
      </code>
      
      ; <code>
        composeEditor
      </code>
      
       (a preset) adds them to the transfer row when <code>
        ai
      </code>
      
       is on
    </td>
  </tr>
  
  <tr>
    <td>
      feature bindings (<code>
        features/<x>/vue.ts
      </code>
      
       + <code>
        vue/
      </code>
      
       components, <code>
        features/<x>/react.ts
      </code>
      
       + <code>
        react/
      </code>
      
       components)
    </td>
    
    <td>
      the feature's framework-free files, <code>
        core
      </code>
      
      , <code>
        settings
      </code>
      
      , and that framework's layer (<code>
        vue
      </code>
      
       or <code>
        react
      </code>
      
      )
    </td>
    
    <td>
      the other framework, other features' implementations, <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      integrations
    </td>
    
    <td>
      the features they connect (framework-free feature entries, or only their schema)
    </td>
    
    <td>
      other integrations' internals, a UI framework, <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tree
      </code>
      
       (<code>
        index
      </code>
      
      , <code>
        tree-view-model
      </code>
      
      , <code>
        store
      </code>
      
      ; <code>
        vue.ts
      </code>
      
      ; <code>
        react.ts
      </code>
      
      )
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        outline
      </code>
      
      , <code>
        composites
      </code>
      
      , <code>
        media
      </code>
      
       (the bindings also their framework's layer)
    </td>
    
    <td>
      AI, collab, transcript, mentions, block-ui, integrations; the other framework
    </td>
  </tr>
  
  <tr>
    <td>
      presets (<code>
        presets/compose
      </code>
      
       framework-free; <code>
        vue/compose.ts
      </code>
      
      , <code>
        react/compose.ts
      </code>
      
       bind it)
    </td>
    
    <td>
      everything they compose
    </td>
    
    <td>
      <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        adapters/direct-ai
      </code>
      
       (<code>
        ./adapters/direct-ai
      </code>
      
      , the browser-direct <code>
        EditorBackend['ai']
      </code>
      
      )
    </td>
    
    <td>
      <code>
        core
      </code>
      
       (<code>
        BackendError
      </code>
      
      , backend types), <code>
        settings
      </code>
      
       values, the client-safe protocols <code>
        features/ai/protocol
      </code>
      
       and <code>
        integrations/transcript-ai/protocol
      </code>
      
      , the platform <code>
        fetch
      </code>
    </td>
    
    <td>
      <code>
        server
      </code>
      
      , the AI SDK (<code>
        ai
      </code>
      
      , <code>
        @ai-sdk/*
      </code>
      
      ), an HTTP client, <code>
        vue
      </code>
      
      , <code>
        react
      </code>
      
      , <code>
        nuxt
      </code>
      
      , other adapters
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        nuxt
      </code>
      
      , <code>
        server
      </code>
    </td>
    
    <td>
      Nitro/Nuxt, framework-free schema entries, the client-safe <code>
        features/ai/protocol
      </code>
      
      ; the composite modules of the exception below
    </td>
    
    <td>
      browser components, any other feature implementation
    </td>
  </tr>
</tbody>
</table>

**Exception: server imports framework-free composite modules.** The server parses and converts Markdown and projects Blocks without an editor, so it needs more of `features/composites` than its schema entry. `server/document-mutator.ts` imports `block-types` and `convert`, `server/markdown-blocks.ts` imports `block-types`, `fences` and `reference-text`, `server/block-index.ts` imports `block-types` and `fences`, `server/workspace-tools.ts` imports the `block-types` type, and `server/stored-content.ts` imports `legacy` (the older precedent). These modules and the composite modules they pull in (`nodes`, `heading-composites`, `meta-keys`, `reference`) import only `core`, `settings`, `i18n`, TipTap's framework-free packages (`@tiptap/core`, `@tiptap/pm`, `@tiptap/suggestion`) and each other, never Vue, React, the DOM or another feature. The exception covers exactly them; a server module that needs another composite module or another feature implementation extends it only by an edit here. (`server/extract.ts` also takes a type from `features/media/assets`; a type import carries no code into the server bundle.)

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`, `coreContentFeature()`, `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.

Run `typecheck:editor`, `check:editor-entries` and `check:editor-composition` as described in [Commands](https://skaile-ai.github.io/forge-editor/reference/commands).

`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.

## Bundle isolation proof

`bun run check:editor-entries` builds each fixture in `packages/editor/checks/fixtures/<name>/` as its own production Vite app, collects the module IDs of every emitted chunk and fails on forbidden modules (or on a missing required one, so exported factories cannot be tree-shaken away unnoticed). Last result for `simple`: 325 modules, JS 1082.5 kB (gzip 331.1 kB), CSS 194.5 kB (gzip 25.2 kB); for `tree`: 433 modules, JS 1314.5 kB (gzip 389.2 kB), CSS 197.6 kB (gzip 25.7 kB). The `code-only` and `code-only-react` fixtures prove the code surface carries CodeMirror and no ProseMirror or TipTap (and nothing of this package outside `src/code`), and the `markdown-vue` and `tables` fixtures prove the Markdown entries contain no CodeMirror. The check also bundles the advanced schema for Node and compares it with a snapshot (`checks/schema.ts`).


# Derive method contract

> DeriveMethod, DeriveContext, the derive registry, the Derivation record and the derivation index functions.

The types come from `packages/editor/src/core/derive.ts` and `core/derivation.ts` and are exported from `@skaile/forge-editor/core`. For how to write a derive method, see [Derive methods and the Derivation index](https://skaile-ai.github.io/forge-editor/guides/derive-methods).

## `DeriveMethod`

One way to make a new block or text from a block. A Feature contributes methods in `EditorFeature.deriveMethods`; `defineEditor` merges them in feature order into `preset.deriveMethods` (`DeriveRegistry`).

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Unique across the preset. Also the id of the block action generated from the method.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      <code>
        (ctx: FeatureContext) => string
      </code>
    </td>
    
    <td>
      Menu label, in the language of the surface (<code>
        ctx.t
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        icon
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Iconify name.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ability
      </code>
    </td>
    
    <td>
      <code>
        Ability?
      </code>
    </td>
    
    <td>
      Shown only on blocks that have this ability (<code>
        BlockAction.ability
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        order
      </code>
    </td>
    
    <td>
      <code>
        number?
      </code>
    </td>
    
    <td>
      Position among the block actions (<code>
        BlockAction.order
      </code>
      
      ).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        placement
      </code>
    </td>
    
    <td>
      <code>
        BlockAction['placement']?
      </code>
    </td>
    
    <td>
      Where the action shows.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        requires
      </code>
    </td>
    
    <td>
      <code>
        readonly string[]
      </code>
    </td>
    
    <td>
      Capability ids the original must all have. Every id must be declared by a Feature (or built in) when the preset is defined.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        available
      </code>
    </td>
    
    <td>
      <code>
        (ctx: DeriveContext) => boolean?
      </code>
    </td>
    
    <td>
      Backend flags and per-block conditions (<code>
        ctx.ctx.backend.ai
      </code>
      
      , a readable source). Absent: always available where <code>
        requires
      </code>
      
       holds.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        run
      </code>
    </td>
    
    <td>
      <code>
        (ctx: DeriveContext) => void
      </code>
    </td>
    
    <td>
      Does the work and writes the result, and for a Derived block its Derivation.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        menu
      </code>
    </td>
    
    <td>
      <code>
        (ctx: DeriveContext) => MenuItem[]
      </code>
    </td>
    
    <td>
      For a method with sub-choices (derive into one of several Block types).
    </td>
  </tr>
</tbody>
</table>

Exactly one of `run` and `menu` is set; `defineEditor` throws for neither or both, for a duplicate id and for a `requires` entry no Feature declares.

### `DeriveContext`

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        editor
      </code>
    </td>
    
    <td>
      the editor
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        node
      </code>
    </td>
    
    <td>
      the original block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pos
      </code>
    </td>
    
    <td>
      the position right before <code>
        node
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ctx
      </code>
    </td>
    
    <td>
      the <code>
        FeatureContext
      </code>
      
       of the surface (backend, public AI flags, settings, notices, translations)
    </td>
  </tr>
</tbody>
</table>

## Registry and functions

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Does
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        DeriveRegistry
      </code>
    </td>
    
    <td>
      <code>
        methods
      </code>
      
       (feature order) and <code>
        get(id)
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createDeriveRegistry(methods)
      </code>
    </td>
    
    <td>
      builds a registry
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        deriveMethodsAt(editor, ctx, pos)
      </code>
    </td>
    
    <td>
      the methods that can run on the block at <code>
        pos
      </code>
      
      : the block has every capability the method <code>
        requires
      </code>
      
      , and <code>
        available
      </code>
      
       holds. Empty without a block there or without a preset.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        deriveActionsOf(preset, ctx)
      </code>
    </td>
    
    <td>
      one <code>
        BlockAction
      </code>
      
       per method, in the shape the block UI renders; <code>
        requires
      </code>
      
      , <code>
        ability
      </code>
      
       and <code>
        available
      </code>
      
       gate it. <code>
        blockActionsOf
      </code>
      
       includes them.
    </td>
  </tr>
</tbody>
</table>

## `Derivation`

The record in `meta.derivation` of a Derived block. The original keeps nothing.

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        from
      </code>
    </td>
    
    <td>
      <code>
        { asset: string } | { block: string, document?: string }
      </code>
    </td>
    
    <td>
      The original: an uploaded asset by asset name, or a block by block ID. <code>
        document
      </code>
      
       is the Document the block lives in; absent = this Document.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        method
      </code>
    </td>
    
    <td>
      <code>
        DerivationMethod
      </code>
    </td>
    
    <td>
      How it was made: <code>
        'transcription'
      </code>
      
      , <code>
        'pdf-text'
      </code>
      
      , <code>
        'ocr'
      </code>
      
      , <code>
        'description'
      </code>
      
      , <code>
        'bibliography'
      </code>
      
      , <code>
        ai:<typeId>
      </code>
      
       for a block derived by the model, or any string.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        model
      </code>
    </td>
    
    <td>
      <code>
        string?
      </code>
    </td>
    
    <td>
      The model that made it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createdAt
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      ISO timestamp.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inputHash
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      SHA-256 hex of the asset bytes or of the source block's Markdown; <code>
        ''
      </code>
      
       when unknown.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        outputHash
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      SHA-256 hex of the produced body's Markdown; <code>
        ''
      </code>
      
       when unknown.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        output
      </code>
    </td>
    
    <td>
      <code>
        string?
      </code>
    </td>
    
    <td>
      Asset name of the stored raw output (text/markdown).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inputs
      </code>
    </td>
    
    <td>
      <code>
        Record<string, { from: DerivationSource, hash: string }>?
      </code>
    </td>
    
    <td>
      The named inputs of an N-to-1 Derivation (<code>
        mixdown
      </code>
      
      , a summary of several Blocks). <code>
        from
      </code>
      
       and <code>
        inputHash
      </code>
      
       then name the primary input, and <code>
        inputHash
      </code>
      
       is <code>
        derivationFingerprint
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        activity
      </code>
    </td>
    
    <td>
      <code>
        { id: string, agent?: string, at?: string }?
      </code>
    </td>
    
    <td>
      The run that produced the Block (an AI request, a job); <code>
        agent
      </code>
      
       is a model or tool id.
    </td>
  </tr>
</tbody>
</table>

`DERIVATION_KEY` is the `meta` key (`'derivation'`). `derivationOf(node)` reads a Derivation (`null` without one). `derivedChildrenOf(parent)` lists the direct children of `parent` that are Derived blocks, with their child index. `isForeignSource(derivation, documentId)` tells whether it points at a block of another Document.

## Derivation index

`derivationIndexOf(doc)` builds the reverse index once per document version (memoised per `doc` node):

<table>
<thead>
  <tr>
    <th>
      Member of <code>
        DerivationIndex
      </code>
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        derived
      </code>
    </td>
    
    <td>
      every Derived block with its position, in document order
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockById(id)
      </code>
    </td>
    
    <td>
      <code>
        { node, pos }
      </code>
      
       of the block with block ID <code>
        id
      </code>
      
       (any depth), or <code>
        null
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        assetBlocks(name)
      </code>
    </td>
    
    <td>
      the <code>
        AssetBlock[]
      </code>
      
       (<code>
        { node, pos, holder }
      </code>
      
      ) that hold the stored asset <code>
        name
      </code>
      
      , in document order; <code>
        holder
      </code>
      
       is the position and size of the block around the asset block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivedFromBlock(id)
      </code>
    </td>
    
    <td>
      the Derived blocks whose Derivation points at block <code>
        id
      </code>
      
      , in this or any Document (<code>
        isForeignSource
      </code>
      
       tells them apart)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivedFromAsset(name)
      </code>
    </td>
    
    <td>
      the Derived blocks whose Derivation points at the stored asset <code>
        name
      </code>
    </td>
  </tr>
</tbody>
</table>

Functions on top of it:

<table>
<thead>
  <tr>
    <th>
      Function
    </th>
    
    <th>
      Returns
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        derivedOf(doc, originalPos, documentId?)
      </code>
    </td>
    
    <td>
      the <code>
        DerivedEntry[]
      </code>
      
       (<code>
        { node, pos, derivation }
      </code>
      
      ) made from the original at <code>
        originalPos
      </code>
      
      , in document order. They point at its block ID or at an asset the original holds as a direct child (its Source media). A Derived block moved out of the original still counts; Derivations from another Document are not listed.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivationOriginOf(doc, derivedPos, documentId?)
      </code>
    </td>
    
    <td>
      <code>
        DerivationOrigin
      </code>
      
      : <code>
        { status: 'found', node, pos }
      </code>
      
      , <code>
        { status: 'missing' }
      </code>
      
       (the original was deleted) or <code>
        { status: 'foreign' }
      </code>
      
       (another Document, not looked up); <code>
        null
      </code>
      
       when the node is no Derived block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivationState(doc, derivedPos, bodyHash, documentId?, foreignHash?, inputHashOf?)
      </code>
    </td>
    
    <td>
      <code>
        DerivationState
      </code>
      
      : <code>
        source
      </code>
      
       (the origin <code>
        status
      </code>
      
      ), <code>
        stale
      </code>
      
       (an original changed since: an asset's stored <code>
        hash
      </code>
      
       against <code>
        inputHash
      </code>
      
      , a Block of another Document through <code>
        foreignHash
      </code>
      
      , each named input through <code>
        inputHashOf(from)
      </code>
      
      ; <code>
        null
      </code>
      
       for a block original in this Document, when unknown, and for <code>
        inputs
      </code>
      
       without <code>
        inputHashOf
      </code>
      
      ) and <code>
        edited
      </code>
      
       (<code>
        bodyHash()
      </code>
      
       differs from <code>
        outputHash
      </code>
      
      ; <code>
        null
      </code>
      
       when <code>
        outputHash
      </code>
      
       is unknown); <code>
        null
      </code>
      
       when the node is no Derived block
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivedStateOf(state)
      </code>
    </td>
    
    <td>
      <code>
        DerivedStateId
      </code>
      
       (<code>
        'fresh' | 'stale' | 'edited' | 'missing' | 'foreign'
      </code>
      
      ): the first that applies of <code>
        missing
      </code>
      
      , <code>
        stale
      </code>
      
      , <code>
        edited
      </code>
      
      , <code>
        foreign
      </code>
      
       (original in another Document, nothing known of it), else <code>
        fresh
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        derivationFingerprint({ method, inputs })
      </code>
    </td>
    
    <td>
      SHA-256 hex of the method and the hash of every input by input name; independent of the order of the keys in <code>
        inputs
      </code>
    </td>
  </tr>
</tbody>
</table>


# Public exports

> Every explicit subpath of @skaile/forge-editor and the names it exports.

Every entry is an explicit subpath of `package.json#exports`; there is no wildcard into internal folders and no runtime umbrella barrel. Importing an entry registers nothing globally.

<table>
<thead>
  <tr>
    <th>
      Import
    </th>
    
    <th>
      Contents
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        @skaile/forge-editor
      </code>
    </td>
    
    <td>
      Type-only: <code>
        EditorSettings
      </code>
      
      , <code>
        EditorFeature
      </code>
      
      , <code>
        EditorPreset
      </code>
      
      , <code>
        FeatureContext
      </code>
      
      , <code>
        AnchorResolver
      </code>
      
      , <code>
        CommandDef
      </code>
      
      , <code>
        ToolbarGroupDef
      </code>
      
      , <code>
        BlockAction
      </code>
      
      , <code>
        AbilitiesOptions
      </code>
      
      , <code>
        EditorMetadata
      </code>
      
      , <code>
        MetadataItem
      </code>
      
      , <code>
        AuthorIdentity
      </code>
      
      , …
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/vue
      </code>
    </td>
    
    <td>
      The Vue layer (Nuxt UI chrome): <code>
        createEditor
      </code>
      
       (Vue plugin around <code>
        createEditorContext
      </code>
      
      ), <code>
        EDITOR_CONTEXT
      </code>
      
      , <code>
        useEditorContext
      </code>
      
      , <code>
        useEditorSettings
      </code>
      
      , <code>
        useNotifier
      </code>
      
      , <code>
        trackedStore
      </code>
      
      , <code>
        useStoreRef
      </code>
      
      , <code>
        useWritableStoreRef
      </code>
      
      , <code>
        storeFromRef
      </code>
      
      , <code>
        EDITOR_UI
      </code>
      
      , <code>
        useEditorUi
      </code>
      
       (<code>
        openSettings
      </code>
      
      , <code>
        toggleSidebar
      </code>
      
      , <code>
        toggleComments
      </code>
      
      , <code>
        commentsOpen
      </code>
      
      , <code>
        togglePalette
      </code>
      
      , <code>
        paletteOpen
      </code>
      
      ), <code>
        vueSuggestionRenderer
      </code>
      
      , the components <code>
        EditorSurface
      </code>
      
      , <code>
        EditorToolbar
      </code>
      
      , <code>
        EditorSettingsPanel
      </code>
      
      , <code>
        EditorSettingsModal
      </code>
      
      , <code>
        EditorCommandPalette
      </code>
      
       (the ⌘K palette, the <code>
        core-ui
      </code>
      
       overlay: <code>
        coreUiFeature<Component>({ palette: EditorCommandPalette })
      </code>
      
      ), <code>
        SettingsSection
      </code>
      
      , <code>
        SuggestionList
      </code>
      
      , and the types <code>
        VueFeature
      </code>
      
      , <code>
        VuePreset
      </code>
      
       (the preset components are the two entries below)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/vue/simple
      </code>
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
       component (<code>
        core-content
      </code>
      
       + <code>
        core-ui
      </code>
      
       plus the host features in <code>
        add
      </code>
      
      , e.g. <code>
        aiFeature()
      </code>
      
      ; no <code>
        composeEditor
      </code>
      
      , so the bundle holds no catalog feature; exposes <code>
        editor
      </code>
      
       and the <code>
        preset
      </code>
      
       it mounts)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/vue/advanced
      </code>
    </td>
    
    <td>
      <code>
        AdvancedEditor
      </code>
      
       component (same props, defaults <code>
        'rich'
      </code>
      
      , <code>
        'full'
      </code>
      
      , <code>
        true
      </code>
      
      ; optional collaboration session) and <code>
        advancedEditor(options): VuePreset
      </code>
      
       (the preset for an <code>
        EditorSurface
      </code>
      
       you mount yourself, and the base for own feature lists); <code>
        EditorToolbar
      </code>
      
      /<code>
        EditorSettingsPanel
      </code>
      
      /<code>
        EditorSettingsModal
      </code>
      
       beside it take the <code>
        editor
      </code>
      
       and find the preset through it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/react
      </code>
    </td>
    
    <td>
      The React layer (shadcn/ui chrome; Vue-free): <code>
        EditorContextProvider
      </code>
      
      , <code>
        useEditorContext
      </code>
      
      , the components <code>
        EditorSurface
      </code>
      
       (ref handle <code>
        EditorSurfaceHandle
      </code>
      
      : <code>
        editor
      </code>
      
      , <code>
        openSettings
      </code>
      
      ), <code>
        EditorToolbar
      </code>
      
      , <code>
        EditorSettingsPanel
      </code>
      
      , <code>
        EditorSettingsModal
      </code>
      
      , <code>
        EditorCommandPalette
      </code>
      
       (the ⌘K palette, the <code>
        core-ui
      </code>
      
       overlay: <code>
        coreUiFeature({ palette: EditorCommandPalette })
      </code>
      
      ), <code>
        SettingsSection
      </code>
      
      , <code>
        SuggestionList
      </code>
      
      , <code>
        Icon
      </code>
      
      , the hooks <code>
        useEditorSettings
      </code>
      
       (<code>
        settings
      </code>
      
      , <code>
        update
      </code>
      
      , <code>
        set
      </code>
      
      , <code>
        ready
      </code>
      
      , <code>
        synced
      </code>
      
      ), <code>
        useEditorUi
      </code>
      
      , <code>
        useNotifier
      </code>
      
      , <code>
        useStore
      </code>
      
      , <code>
        EditorUiContext
      </code>
      
      , <code>
        reactSuggestionRenderer
      </code>
      
      , the notice seam <code>
        reactNotifier
      </code>
      
       and sonner's <code>
        Toaster
      </code>
      
       (mount it once per page), the <code>
        cn
      </code>
      
       class helper, and the types <code>
        ReactFeature
      </code>
      
      , <code>
        ReactPreset
      </code>
      
      , <code>
        EditorSurfaceProps
      </code>
      
      , <code>
        EditorSurfaceHandle
      </code>
      
      , <code>
        SuggestionListHandle
      </code>
      
      . Presets are <code>
        defineEditor({ features })
      </code>
      
       from <code>
        /core
      </code>
      
       over the <code>
        /<feature>/react
      </code>
      
       bindings and framework-free features, or <code>
        advancedEditor()
      </code>
      
       from <code>
        /react/advanced
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/react/simple
      </code>
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
       component (props: the surface's except <code>
        preset
      </code>
      
      , plus <code>
        add
      </code>
      
      ; ref handle <code>
        SimpleEditorHandle
      </code>
      
      : <code>
        editor
      </code>
      
      , <code>
        openSettings
      </code>
      
      , <code>
        preset
      </code>
      
      ), <code>
        SimpleEditorProps
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/react/advanced
      </code>
    </td>
    
    <td>
      <code>
        AdvancedEditor
      </code>
      
       component (every feature and integration with its React binding, optional collaboration session; props <code>
        AdvancedEditorProps
      </code>
      
       = <code>
        EditorSurface
      </code>
      
      's except <code>
        preset
      </code>
      
      , plus <code>
        content
      </code>
      
      , <code>
        interaction
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        add
      </code>
      
      , <code>
        remove
      </code>
      
      , <code>
        backend
      </code>
      
      , <code>
        blockTypes
      </code>
      
      , <code>
        blockUi
      </code>
      
      , <code>
        coreContent
      </code>
      
      ; ref handle <code>
        AdvancedEditorHandle
      </code>
      
      ) and <code>
        advancedEditor(options): ReactPreset
      </code>
      
      ; mount <code>
        Toaster
      </code>
      
       from <code>
        /react
      </code>
      
       beside it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/react/styles/ui-vars.css
      </code>
    </td>
    
    <td>
      Maps the shadcn tokens (<code>
        --primary
      </code>
      
      , <code>
        --background
      </code>
      
      , …) to the <code>
        --ui-*
      </code>
      
       variables the feature sheets read; import it before <code>
        core.css
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/react/styles/advanced.css
      </code>
    </td>
    
    <td>
      One import for React hosts of the advanced editor: <code>
        ui-vars.css
      </code>
      
      , <code>
        core.css
      </code>
      
      , every feature sheet and <code>
        themes.css
      </code>
      
       (with the shadcn bridge for Obsidian themes), in the order the Nuxt module registers them
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/presets/compose
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        composeEditor(ui, { content, interaction, ai, backend?, add?, remove?, blockTypes?, comments?, blockUi?, coreContent? })
      </code>
      
       builds a preset from three dimensions (<code>
        content
      </code>
      
      : <code>
        'basic'
      </code>
      
      /<code>
        'rich'
      </code>
      
      ; <code>
        interaction
      </code>
      
      : <code>
        'minimal'
      </code>
      
      /<code>
        'full'
      </code>
      
      /<code>
        []
      </code>
      
      ; <code>
        ai
      </code>
      
      : boolean) and prunes by the backend's capabilities (<code>
        omitted
      </code>
      
      ), with <code>
        CONTENT
      </code>
      
      , <code>
        INTERACTION
      </code>
      
      , <code>
        AI
      </code>
      
       (feature ids in canonical order), <code>
        UiBindings<C>
      </code>
      
       (the layer binds only the UI-bound features), <code>
        ComposeOptions<C>
      </code>
      
      , <code>
        ComposedEditor<C>
      </code>
      
      , and <code>
        simpleEditor(): ComposedEditor<never>
      </code>
      
       (<code>
        core-content
      </code>
      
       + <code>
        core-ui
      </code>
      
      , no ⌘K palette). The ready compositions with the palette are <code>
        composeEditor
      </code>
      
       and <code>
        advancedEditor
      </code>
      
       of <code>
        /vue/advanced
      </code>
      
       and <code>
        /react/advanced
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
    </td>
    
    <td>
      Framework-free (Tiptap/ProseMirror only; imports no <code>
        vue
      </code>
      
      , <code>
        @tiptap/vue-3
      </code>
      
      , <code>
        @nuxt/ui
      </code>
      
       or React): <code>
        defineEditor
      </code>
      
      , <code>
        coreContentFeature
      </code>
      
      , <code>
        coreUiFeature
      </code>
      
      , <code>
        createEditorContext
      </code>
      
       (settings context and the translator <code>
        ctx.t
      </code>
      
      , options <code>
        locale: 'de' | 'en'
      </code>
      
       and partial <code>
        messages
      </code>
      
      ; with <code>
        createStore
      </code>
      
       <code>
        createStore
      </code>
      
      , <code>
        derived
      </code>
      
      , <code>
        Store
      </code>
      
      , <code>
        ReadonlyStore
      </code>
      
      ), the notice seam (<code>
        Notice
      </code>
      
      , <code>
        Notifier
      </code>
      
      , <code>
        silentNotifier
      </code>
      
      ), the suggestion renderer seam (<code>
        SuggestionPopup
      </code>
      
      , <code>
        suggestionPopupOf
      </code>
      
      , <code>
        SuggestionListProps
      </code>
      
      , <code>
        SuggestionPopupHandle
      </code>
      
      , <code>
        SuggestionPopupRenderer
      </code>
      
      ), <code>
        registerEditor
      </code>
      
      , <code>
        Abilities
      </code>
      
       and ability helpers, <code>
        BlockFlash
      </code>
      
      , <code>
        SlashCommand
      </code>
      
      , <code>
        Metadata
      </code>
      
      , <code>
        parseBlocks
      </code>
      
       / <code>
        DEFAULT_BLOCK_PIPELINE
      </code>
      
      , generic helpers <code>
        downloadText
      </code>
      
       and <code>
        fetchErrorMessage
      </code>
      
      , the feature/toolbar/extension-point types (<code>
        EditorFeature<C>
      </code>
      
      , <code>
        FeatureContext
      </code>
      
      , <code>
        CommandDef
      </code>
      
      , <code>
        MenuItem
      </code>
      
      , …), <code>
        command
      </code>
      
       / <code>
        commandState
      </code>
      
       / <code>
        toolbarOf
      </code>
      
      , and the block-conversion engine for own features (<code>
        ConversionProvider
      </code>
      
      , <code>
        ConvertTarget
      </code>
      
       with its <code>
        custom
      </code>
      
       member for host blocks, <code>
        createConverter
      </code>
      
      , <code>
        convertCoreBlocks
      </code>
      
      , <code>
        finishConversion
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
      
       (Typed block)
    </td>
    
    <td>
      Framework-free; the one definition of the Typed block (<code>
        core/typed-block.ts
      </code>
      
      ): the persisted names <code>
        TYPED_BLOCK
      </code>
      
      , <code>
        TYPED_BLOCK_TITLE
      </code>
      
      , <code>
        TYPED_BLOCK_DESCRIPTION
      </code>
      
      , <code>
        TYPED_BLOCK_TAGS
      </code>
      
      , <code>
        BLOCK_TYPE_ATTR
      </code>
      
      , <code>
        BIB_KEY
      </code>
      
       (the <code>
        meta
      </code>
      
       key of the bibliographic record); <code>
        newTypedBlockJSON(blockType, body?, meta?, title?)
      </code>
      
       (the JSON of a fresh Typed block); <code>
        isTypedBlock(node | json)
      </code>
      
      , <code>
        typedBlockAt(doc, pos)
      </code>
      
       (<code>
        null
      </code>
      
       for an invalid or non-Typed-block position), <code>
        typeIdOf(block)
      </code>
      
      , <code>
        findBlockType(blockTypes, block)
      </code>
      
      , <code>
        metaOf
      </code>
      
       / <code>
        withMeta
      </code>
      
       / <code>
        withoutMeta
      </code>
      
       (copies, the block is never changed). The Derivation record (<code>
        Derivation
      </code>
      
      , <code>
        DERIVATION_KEY
      </code>
      
      , <code>
        derivationOf
      </code>
      
      ) is part of it. <code>
        /core/schema
      </code>
      
       does not export the names
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/core
      </code>
      
       (derivation and derive methods)
    </td>
    
    <td>
      Framework-free. <code>
        Derivation
      </code>
      
      , <code>
        DerivationSource
      </code>
      
      , <code>
        DerivationMethod
      </code>
      
      , <code>
        DERIVATION_KEY
      </code>
      
      , <code>
        derivationOf
      </code>
      
      , <code>
        derivedChildrenOf
      </code>
      
      , <code>
        derivationIndexOf
      </code>
      
       (original → Derived blocks, computed from block IDs and memoised per document node), <code>
        derivedOf(doc, pos)
      </code>
      
      , <code>
        derivationOriginOf
      </code>
      
      , <code>
        derivedStateLabel(state, t)
      </code>
      
       (the reason label of a Derived block's state), <code>
        derivationState
      </code>
      
       (<code>
        source: 'found' | 'missing' | 'foreign'
      </code>
      
      ); the derive method registry: <code>
        EditorFeature.deriveMethods
      </code>
      
      , <code>
        DeriveMethod
      </code>
      
       (<code>
        id
      </code>
      
      , <code>
        label
      </code>
      
      , <code>
        icon
      </code>
      
      , <code>
        requires
      </code>
      
      , <code>
        available
      </code>
      
      , <code>
        run
      </code>
      
       or <code>
        menu
      </code>
      
      ), <code>
        DeriveContext
      </code>
      
      , <code>
        DeriveRegistry
      </code>
      
      , <code>
        createDeriveRegistry
      </code>
      
      , <code>
        deriveMethodsAt(editor, ctx, pos)
      </code>
      
      , <code>
        deriveActionsOf(preset, ctx)
      </code>
      
      ; <code>
        preset.deriveMethods
      </code>
      
       is the merged registry
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/core/schema
      </code>
    </td>
    
    <td>
      Vue-free base schema: <code>
        coreSchemaExtensions()
      </code>
      
      , <code>
        coreContentSchemaExtensions(options?)
      </code>
      
       with <code>
        CoreContentOptions
      </code>
      
       (drop headings, lists, blockquote, code block, rule) and <code>
        starterKitOf
      </code>
      
      , <code>
        EMPTY_EDITOR_CONTENT
      </code>
      
      , <code>
        StrikeX
      </code>
      
      , <code>
        BlockId
      </code>
      
       helpers (<code>
        BLOCK_ID_TYPES
      </code>
      
      , <code>
        blockIdOf
      </code>
      
      , <code>
        findBlockById
      </code>
      
      , <code>
        assignBlockIds
      </code>
      
      ), <code>
        NodeFlags
      </code>
      
       (copies the node flags <code>
        editorBlockContainer
      </code>
      
      , <code>
        editorChrome
      </code>
      
       and <code>
        editorBlock
      </code>
      
       onto the node spec; <code>
        editorBlock: true
      </code>
      
       gives an own node block IDs), <code>
        isEditorBlock
      </code>
      
      , <code>
        isBlockContainer
      </code>
      
      , <code>
        isChromeNode
      </code>
      
      , the ability vocabulary (<code>
        ABILITY
      </code>
      
      , <code>
        ROOT_ABILITIES
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/schema/simple
      </code>
    </td>
    
    <td>
      Vue-free <code>
        simpleSchemaExtensions()
      </code>
      
       for servers and validators
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/settings
      </code>
    </td>
    
    <td>
      <code>
        EditorSettings
      </code>
      
      , <code>
        EDITOR_SETTINGS_VERSION
      </code>
      
      , <code>
        EDITOR_SETTINGS_DEFAULTS
      </code>
      
      , <code>
        editorSettingsSchema
      </code>
      
      , <code>
        parseEditorSettings
      </code>
      
      , <code>
        ModelRole
      </code>
      
      , inert value constants (<code>
        MODEL_ROLES
      </code>
      
      , the Model roles; <code>
        STRUCTURE_MODES
      </code>
      
      , <code>
        TREE_ROOTS
      </code>
      
      , <code>
        BLOCK_TYPE_ICON_VISIBILITIES
      </code>
      
      , <code>
        DRAG_HANDLE_VISIBILITIES
      </code>
      
      , <code>
        AI_LANGUAGES
      </code>
      
      , <code>
        AUTHOR_COLOR_STYLES
      </code>
      
      , <code>
        COMMENTS_LAYOUTS
      </code>
      
      , …)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/outline
      </code>
      
      , <code>
        /outline/vue
      </code>
      
      , <code>
        /outline/react
      </code>
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        EditorOutline
      </code>
      
       (the Block outline); framework-free: <code>
        headingOutline
      </code>
      
      , <code>
        revealBlockInEditor
      </code>
      
      , <code>
        HeadingOutlineNode
      </code>
      
       (imports no tree and no Typed block code)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/search
      </code>
      
      , <code>
        /search/vue
      </code>
      
      , <code>
        /search/react
      </code>
    </td>
    
    <td>
      Workspace search over the Block index (backend capability <code>
        index
      </code>
      
      ). <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        SearchPanel
      </code>
      
       (props <code>
        open(hit)
      </code>
      
       and optional <code>
        documentTitle(id)
      </code>
      
      ; React also <code>
        className
      </code>
      
      ; renders nothing without the <code>
        index
      </code>
      
       capability), <code>
        useSearchModel
      </code>
      
      ; framework-free: <code>
        createSearchModel
      </code>
      
      , <code>
        hitLabel
      </code>
      
      , <code>
        SearchModel
      </code>
      
      , <code>
        SearchModelOptions
      </code>
      
      , <code>
        SearchState
      </code>
      
      , <code>
        SearchStatus
      </code>
      
       (imports no tree, no feature)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/change-sets
      </code>
      
      , <code>
        /change-sets/vue
      </code>
      
      , <code>
        /change-sets/react
      </code>
    </td>
    
    <td>
      What the document chat proposed for other Documents than the open one, reviewed per Document (backend capability <code>
        changeSets
      </code>
      
      ). <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        ChangeSetPanel
      </code>
      
       (props <code>
        model
      </code>
      
      , optional <code>
        documentTitle(id)
      </code>
      
       and <code>
        open(id)
      </code>
      
      ; React also <code>
        className
      </code>
      
      ; renders nothing while there is nothing to show), <code>
        useChangeSetModel({ backend })
      </code>
      
       (one model per app, shared with the chat through <code>
        AiSidebar
      </code>
      
      's <code>
        changeSets
      </code>
      
      ); framework-free: <code>
        createChangeSetModel
      </code>
      
      , <code>
        groupChangeSets
      </code>
      
      , <code>
        hunkLabel
      </code>
      
      , <code>
        HUNK_STATUS_KEYS
      </code>
      
      , <code>
        ChangeSetModel
      </code>
      
      , <code>
        ChangeSetModelOptions
      </code>
      
      , <code>
        ChangeSetState
      </code>
      
      , <code>
        ChangeSetGroup
      </code>
      
      , <code>
        ChangeSetEntry
      </code>
      
      , <code>
        ChangeSetFailure
      </code>
      
       and the types <code>
        ChangeSet
      </code>
      
      , <code>
        ChangeSetHunk
      </code>
      
      , <code>
        ChangeSetHunkStatus
      </code>
      
      , <code>
        ChangeSetOp
      </code>
      
      , <code>
        ChangeSetFeed
      </code>
      
       (imports no tree, no feature)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/tree
      </code>
      
      , <code>
        /tree/vue
      </code>
      
      , <code>
        /tree/react
      </code>
      
      , <code>
        /tree/types
      </code>
    </td>
    
    <td>
      Document tree. <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        DocumentTree
      </code>
      
       (Vue: props <code>
        store
      </code>
      
      , <code>
        editor
      </code>
      
      , <code>
        v-model:selectedFolder
      </code>
      
      , slot <code>
        document-actions
      </code>
      
      ; React: props <code>
        store
      </code>
      
      , <code>
        editor
      </code>
      
      , <code>
        selectedFolder
      </code>
      
      /<code>
        onSelectedFolderChange
      </code>
      
       (uncontrolled when omitted), <code>
        documentActions
      </code>
      
      , <code>
        className
      </code>
      
      ; needs <code>
        EditorContextProvider
      </code>
      
       and a mounted <code>
        Toaster
      </code>
      
      ), <code>
        useTreeView
      </code>
      
       (Vue: <code>
        nodeFilters
      </code>
      
      /<code>
        expanded
      </code>
      
       as refs; React: as values); framework-free: <code>
        DocumentStore
      </code>
      
       (the tree's store interface; store-based: <code>
        tree
      </code>
      
      , <code>
        documents
      </code>
      
      , <code>
        activeId
      </code>
      
       are <code>
        ReadonlyStore
      </code>
      
      s plus the host's operations), <code>
        createTreeView
      </code>
      
      , <code>
        treeView(context)
      </code>
      
       (the per-app view state: node filters, expanded folders), <code>
        TreeViewModel
      </code>
      
      , <code>
        NodeFilters
      </code>
      
      , <code>
        TreeFolder
      </code>
      
      , <code>
        DocumentSummary
      </code>
      
      ; <code>
        /vue
      </code>
      
       also <code>
        useStoreRef
      </code>
      
       and <code>
        storeFromRef
      </code>
      
       (adapters from Vue refs to the store shape). Depends on core, outline, composites and media; see the <a href="https://skaile-ai.github.io/forge-editor/guides/document-tree">
        integration guide
      </a>
      
      . <code>
        /tree/types
      </code>
      
       has the <code>
        TreeFolder
      </code>
      
      /<code>
        DocumentSummary
      </code>
      
       types alone, for servers whose typecheck has no DOM. Content tree: <code>
        TreeViewModel.basketFilter
      </code>
      
       (<code>
        Store<string[]>
      </code>
      
      , persisted under <code>
        tip-tree:basket-filter
      </code>
      
      ), <code>
        setBasketShown(id, shown)
      </code>
      
      , <code>
        clearBasketFilter()
      </code>
      
      ; <code>
        TreeState.basketFilter
      </code>
      
      , <code>
        focusKey
      </code>
      
      , <code>
        focusPath
      </code>
      
      ; the model's <code>
        focus(key)
      </code>
      
       and <code>
        defocus()
      </code>
      
      ; <code>
        TreeRowState.dimmed
      </code>
      
      ; the <code>
        TreeCommand
      </code>
      
       members <code>
        transferBlock
      </code>
      
       and <code>
        focusBlock
      </code>
      
      ; <code>
        DragPayload
      </code>
      
       <code>
        foreign-block
      </code>
      
       with <code>
        TreeModel.foreignDragOver(item)
      </code>
      
       and <code>
        dropForeign(item, payload, menu, x, y)
      </code>
      
      . See <a href="https://skaile-ai.github.io/forge-editor/guides/document-tree#baskets-focus-and-foreign-drops">
        Document tree
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/media
      </code>
      
      , <code>
        /media/vue
      </code>
      
      , <code>
        /media/react
      </code>
      
      , <code>
        /media/schema
      </code>
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        mediaFeature
      </code>
      
      , <code>
        useFileImport
      </code>
      
      , <code>
        AudioRecorderModal
      </code>
      
      , <code>
        useAudioRecorder
      </code>
      
      ; framework-free: <code>
        mediaFeatureCore
      </code>
      
      , <code>
        fileImport
      </code>
      
      , <code>
        createAudioRecorder
      </code>
      
      , <code>
        pickFiles
      </code>
      
      , <code>
        openAudioRecorder
      </code>
      
      , <code>
        mediaSchemaExtensions()
      </code>
      
      , <code>
        MEDIA_TYPES
      </code>
      
      , <code>
        MAX_MEDIA_BYTES
      </code>
      
      , asset helpers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/image-studio
      </code>
      
      , <code>
        /image-studio/vue
      </code>
      
      , <code>
        /image-studio/react
      </code>
      
      , <code>
        /image-studio/schema
      </code>
    </td>
    
    <td>
      The Bild-Studio block (<a href="https://skaile-ai.github.io/forge-editor/guides/image-studio">
        guide
      </a>
      
      ). <code>
        /vue
      </code>
      
      : <code>
        imageStudioFeature()
      </code>
      
      , <code>
        ImageStudioDialog
      </code>
      
       (props <code>
        open
      </code>
      
       / <code>
        v-model:open
      </code>
      
      , <code>
        store
      </code>
      
      , <code>
        title?
      </code>
      
      ), <code>
        createImageStudioNodeStore({ editor, getPos, backend, documentId })
      </code>
      
       (with <code>
        ImageStudioNodeStore
      </code>
      
      , <code>
        ImageStudioNodeStoreOptions
      </code>
      
      ; <code>
        dispose()
      </code>
      
       detaches it), <code>
        ImageStudioStore
      </code>
      
       (the contract the dialog drives: <code>
        state
      </code>
      
      , <code>
        promptBlocks
      </code>
      
      , <code>
        update
      </code>
      
      , <code>
        generate
      </code>
      
      , <code>
        upload
      </code>
      
      , <code>
        problem
      </code>
      
      , all as refs) and everything from the framework-free entry. <code>
        /react
      </code>
      
      : <code>
        imageStudioFeature()
      </code>
      
      , <code>
        ImageStudioDialog
      </code>
      
       (props <code>
        open
      </code>
      
      , <code>
        onOpenChange
      </code>
      
      , <code>
        store
      </code>
      
      , <code>
        title?
      </code>
      
      ), <code>
        ImageStudioReactStore
      </code>
      
       (the same contract with plain values instead of refs; the host re-renders the dialog with the new <code>
        state
      </code>
      
       after <code>
        update
      </code>
      
      , and keeps <code>
        update
      </code>
      
       stable per image: its identity is the store's), <code>
        useImageStudioNodeStore({ editor, getPos, backend, documentId })
      </code>
      
       (the store of one node, <code>
        undefined
      </code>
      
       on the first render), <code>
        createImageStudioNodeCore
      </code>
      
      , <code>
        ImageStudioNodeCore
      </code>
      
      , <code>
        ImageStudioNodeCoreOptions
      </code>
      
      , <code>
        ImageStudioNodeSnapshot
      </code>
      
       and the state and reducers. Framework-free: <code>
        imageStudioFeatureCore(ui?)
      </code>
      
      , <code>
        ImageStudioUi
      </code>
      
      , <code>
        IMAGE_STUDIO_OPEN
      </code>
      
      , <code>
        ImageStudioNode
      </code>
      
      , <code>
        imageStudioSchemaExtensions()
      </code>
      
       (<code>
        /schema
      </code>
      
       is Vue-free, for servers), <code>
        ImageStudioAttrs
      </code>
      
      , the types <code>
        ImageStudioState
      </code>
      
      , <code>
        ImageStudioImage
      </code>
      
      , <code>
        ImageStudioTurn
      </code>
      
      , <code>
        ImageStudioPromptBlock
      </code>
      
      , the gallery types <code>
        ImageStudioLibrary
      </code>
      
      , <code>
        ImageStudioLibraryFacet
      </code>
      
      , <code>
        ImageStudioLibraryQuery
      </code>
      
      , <code>
        ImageStudioLibraryItem
      </code>
      
      , <code>
        EMPTY_IMAGE_STUDIO_STATE
      </code>
      
      , the pure reducers <code>
        setDescription
      </code>
      
      , <code>
        togglePromptBlock
      </code>
      
      , <code>
        toggleImage
      </code>
      
      , <code>
        select
      </code>
      
      , <code>
        removeImage
      </code>
      
      , <code>
        addReference
      </code>
      
      , <code>
        adoptImage
      </code>
      
      , <code>
        addGeneration
      </code>
      
      , and <code>
        selectedImage
      </code>
      
      , <code>
        isEmptyImageStudioState
      </code>
      
      , <code>
        normalizeImageStudioState
      </code>
      
      . The backend side is <code>
        EditorBackend.images
      </code>
      
       (capability <code>
        images
      </code>
      
      ), <code>
        EditorPorts.images
      </code>
      
       (<code>
        ImageProvider
      </code>
      
      ) and the routes under <code>
        /api/editor/images/
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/mentions
      </code>
      
      , <code>
        /mentions/schema
      </code>
    </td>
    
    <td>
      <code>
        mentionsFeature
      </code>
      
      , <code>
        mentionSuggestion
      </code>
      
      , <code>
        tagSuggestion
      </code>
      
      ; Vue-free: <code>
        mentionsSchemaExtensions()
      </code>
      
      , <code>
        MentionNode
      </code>
      
      , <code>
        TagNode
      </code>
      
      , <code>
        mentionsFromText
      </code>
      
      , <code>
        tagsFromText
      </code>
      
      , <code>
        normalizeTagName
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/tables
      </code>
      
      , <code>
        /tables/schema
      </code>
    </td>
    
    <td>
      <code>
        tablesFeature()
      </code>
      
       (GFM tables and task lists: the nodes, toolbar group <code>
        table
      </code>
      
       with insert 3×3, add/delete row, add/delete column, delete table, slash entries <code>
        table.insert
      </code>
      
       and <code>
        task.insert
      </code>
      
      ; no components, so it fits both framework layers); Vue-free: <code>
        tablesSchemaExtensions()
      </code>
      
       (also part of <code>
        /schema/simple
      </code>
      
       and <code>
        /schema/advanced
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/markdown
      </code>
      
      , <code>
        /markdown/vue
      </code>
      
      , <code>
        /markdown/react
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        splitFrontmatter(text)
      </code>
      
       / <code>
        joinFrontmatter(frontmatter, body)
      </code>
      
       (YAML block at offset 0 only, kept verbatim), <code>
        markdownToContent(editor, body, { policy? }): { content, diagnostics }
      </code>
      
       (policy <code>
        { allowHtml?, allowDataUrls? }
      </code>
      
      : raw HTML, links and media with unsafe URLs are dropped and reported as <code>
        MarkdownDiagnostic
      </code>
      
      s — <code>
        raw-html
      </code>
      
      , <code>
        unsafe-url
      </code>
      
      , <code>
        unknown-fence
      </code>
      
       (info), <code>
        unclosed-fence
      </code>
      
       and <code>
        invalid-fence-meta
      </code>
      
       (errors); <code>
        hasFatalDiagnostics
      </code>
      
      ), <code>
        contentToMarkdown(editor)
      </code>
      
      , <code>
        MarkdownClipboard.configure({ policy })
      </code>
      
       (an extension: pastes <code>
        text/markdown
      </code>
      
       and plain text with block syntax as blocks, sanitizes pasted HTML, copies and cuts as <code>
        text/markdown
      </code>
      
       next to <code>
        text/html
      </code>
      
       and <code>
        text/plain
      </code>
      
      ), <code>
        createSourceMode({ getEditor, toMarkdown?, fromMarkdown?, policy? }): SourceMode
      </code>
      
       (<code>
        state
      </code>
      
       store <code>
        { mode: 'visual' | 'source', source, diagnostics }
      </code>
      
      , <code>
        enter()
      </code>
      
      , <code>
        edit(text)
      </code>
      
      , <code>
        commit(): boolean
      </code>
      
       — false with the editor untouched on a fatal diagnostic or a document the schema rejects —, <code>
        cancel()
      </code>
      
      ). Unknown <code>
        ::: kind
      </code>
      
       fences are <code>
        OpaqueFence
      </code>
      
       nodes (in <code>
        coreSchemaExtensions()
      </code>
      
      ) that are written back byte for byte; the Block types a Typed block feature registers parse first. Vue: <code>
        MarkdownSurface
      </code>
      
       (<code>
        v-model
      </code>
      
       is the Markdown string, frontmatter included; props, emits and slots of <code>
        EditorSurface
      </code>
      
       forwarded; an incoming value equal to the last emitted one is ignored; prop <code>
        policy
      </code>
      
       (also configures the <code>
        MarkdownClipboard
      </code>
      
       it installs), prop <code>
        sourceMode
      </code>
      
       (a <code>
        SourceMode
      </code>
      
      : while its state is <code>
        source
      </code>
      
       the surface shows the draft in a text area with the diagnostics of a rejected commit and Apply/Cancel, <code>
        sourceLabels
      </code>
      
       for their texts), event <code>
        diagnostics
      </code>
      
      ). React: <code>
        MarkdownSurface
      </code>
      
       (<code>
        value
      </code>
      
       / <code>
        onChange
      </code>
      
       / <code>
        onFrontmatterChange
      </code>
      
       / <code>
        onDiagnostics
      </code>
      
      , prop <code>
        policy
      </code>
      
       (also configures the installed <code>
        MarkdownClipboard
      </code>
      
      ), the <code>
        EditorSurface
      </code>
      
       props forwarded, same semantics; no source view). Neither imports CodeMirror
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/code
      </code>
      
      , <code>
        /code/vue
      </code>
      
      , <code>
        /code/react
      </code>
    </td>
    
    <td>
      CodeMirror 6 on a string, themed by the shared <code>
        --sk-*
      </code>
      
       tokens (<code>
        styles/tokens.css
      </code>
      
      ; fallbacks are the token defaults). Framework-free: <code>
        createCodeEditor({ parent, doc?, readOnly?, wordWrap?, language?, onSaveShortcut?, onChange? })
      </code>
      
      , <code>
        setReadOnly
      </code>
      
      , <code>
        setWordWrap
      </code>
      
      , <code>
        setLanguage(view, support)
      </code>
      
      , <code>
        loadLanguage(view, id)
      </code>
      
      , <code>
        setDocument(view, text)
      </code>
      
       (a host text, not an edit), <code>
        registerLanguage(id, loader, { core? })
      </code>
      
       / <code>
        resolveLanguage(id)
      </code>
      
       / <code>
        isCoreLang(id)
      </code>
      
       (language packs are the host's: register the <code>
        @codemirror/lang-*
      </code>
      
       packs you depend on; <code>
        jsonl
      </code>
      
       is built in), <code>
        formatJsonInEditor(view)
      </code>
      
      , <code>
        formatJsonText
      </code>
      
      , <code>
        jsonlLanguage
      </code>
      
      , <code>
        kindOf(path, mime?)
      </code>
      
       (<code>
        'markdown' | 'code' | 'binary'
      </code>
      
      ), <code>
        languageOf(path)
      </code>
      
      . <code>
        /code/vue
      </code>
      
      : <code>
        CodeSurface
      </code>
      
       (<code>
        v-model
      </code>
      
       string, <code>
        editable
      </code>
      
      , <code>
        language
      </code>
      
      , <code>
        wordWrap
      </code>
      
      ; emits <code>
        update:modelValue
      </code>
      
      , <code>
        save
      </code>
      
       on Mod-S, <code>
        ready(view)
      </code>
      
      ). <code>
        /code/react
      </code>
      
      : <code>
        CodeSurface
      </code>
      
       (<code>
        value
      </code>
      
      , <code>
        onChange
      </code>
      
      , <code>
        onSave
      </code>
      
      , <code>
        onReady
      </code>
      
      , same flags). No ProseMirror or TipTap is reachable from these entries
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/document/vue
      </code>
      
      , <code>
        /document/react
      </code>
    </td>
    
    <td>
      <code>
        DocumentSurface
      </code>
      
      : <code>
        MarkdownSurface
      </code>
      
       for <code>
        kindOf(path, mime) === 'markdown'
      </code>
      
       (props <code>
        markdown
      </code>
      
      : the Markdown surface's own props, <code>
        preset
      </code>
      
       at least), <code>
        CodeSurface
      </code>
      
       for text (language from <code>
        languageOf(path)
      </code>
      
       unless <code>
        language
      </code>
      
       is given), a <code>
        binary
      </code>
      
       slot (Vue) / <code>
        binary(path)
      </code>
      
       render prop (React) otherwise. <code>
        ready
      </code>
      
       carries <code>
        { kind: 'markdown', editor }
      </code>
      
       or <code>
        { kind: 'code', view }
      </code>
      
      . These entries reach both editors; use <code>
        /markdown/*
      </code>
      
       or <code>
        /code/*
      </code>
      
       alone to keep one out of a bundle
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/transcript
      </code>
      
      , <code>
        /transcript/vue
      </code>
      
      , <code>
        /transcript/react
      </code>
      
      , <code>
        /transcript/schema
      </code>
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        transcriptFeature
      </code>
      
      , <code>
        TranscriptSegmentView
      </code>
      
      ; framework-free: <code>
        transcriptFeatureCore
      </code>
      
      , <code>
        transcriptSegment
      </code>
      
      , <code>
        speakerConversions
      </code>
      
      , <code>
        segmentSpeakerLines
      </code>
      
      , <code>
        transcriptSchemaExtensions()
      </code>
      
      , <code>
        speakerParagraphsToSegments
      </code>
      
      , <code>
        lastSpeaker
      </code>
      
      , <code>
        speakersIn
      </code>
      
      , and the subtitle export <code>
        vttOf(cues)
      </code>
      
      , <code>
        srtOf(cues)
      </code>
      
      , <code>
        transcriptCuesOf(node)
      </code>
      
      , <code>
        TranscriptCue
      </code>
      
       (block action <code>
        transcript-export
      </code>
      
      ; see <a href="https://skaile-ai.github.io/forge-editor/guides/speech">
        Speech
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/authors
      </code>
      
      , <code>
        /authors/vue
      </code>
      
      , <code>
        /authors/react
      </code>
      
      , <code>
        /authors/schema
      </code>
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        authorsFeature
      </code>
      
      , <code>
        AuthorColorsPanel
      </code>
      
      , <code>
        AuthorColorsButton
      </code>
      
      , <code>
        SettingsAuthorsTab
      </code>
      
      ; framework-free: <code>
        authorsFeatureCore
      </code>
      
      , <code>
        currentAuthor
      </code>
      
      , <code>
        AuthorAttribution
      </code>
      
      , <code>
        authorsSchemaExtensions()
      </code>
      
      , <code>
        AuthorMark
      </code>
      
      , <code>
        documentAuthors
      </code>
      
      , <code>
        AuthorIdentity
      </code>
      
      , <code>
        AUTHOR_COLOR_STYLES
      </code>
      
      , <code>
        AuthorColorStyle
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/themes
      </code>
      
      , <code>
        /themes/vue
      </code>
      
      , <code>
        /themes/react
      </code>
      
      , <code>
        /themes/schema
      </code>
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        themesFeature()
      </code>
      
       (site-wide Obsidian themes: its <code>
        setup
      </code>
      
       hook starts the theme runtime and returns its teardown, its <code>
        appearance
      </code>
      
       settings tab picks the theme), <code>
        SettingsAppearanceTab
      </code>
      
      ; framework-free: <code>
        themesFeatureCore
      </code>
      
      , <code>
        startObsidianTheme(ctx)
      </code>
      
       (reference-counted per app, returns the release), <code>
        pinObsidianTheme(ctx, id)
      </code>
      
       (shows a theme over the setting until released, nothing persisted), <code>
        ThemeHost
      </code>
      
      , <code>
        scopeThemeCss
      </code>
      
      , <code>
        THEME_SCOPE_CLASS
      </code>
      
      ; Vue-free schema: <code>
        ThemeRecord
      </code>
      
      , <code>
        ThemeManifest
      </code>
      
      , <code>
        themeManifestSchema
      </code>
      
      , <code>
        THEME_ID
      </code>
      
      , <code>
        MAX_THEME_BYTES
      </code>
      
      . Needs an adapter with <code>
        listThemes
      </code>
      
      /<code>
        loadTheme
      </code>
      
      ; see the <a href="https://skaile-ai.github.io/forge-editor/guides/themes">
        usage guide
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/comments
      </code>
      
      , <code>
        /comments/vue
      </code>
      
      , <code>
        /comments/react
      </code>
      
      , <code>
        /comments/schema
      </code>
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        commentsFeature
      </code>
      
       (requires <code>
        collab
      </code>
      
      ), <code>
        useComments
      </code>
      
      , <code>
        CommentsMargin
      </code>
      
      , <code>
        CommentsPopover
      </code>
      
      , <code>
        CommentsListMenu
      </code>
      
      , <code>
        CommentThreadView
      </code>
      
      , <code>
        CommentComposer
      </code>
      
      , <code>
        CommentBubble
      </code>
      
      , <code>
        SettingsCommentsTab
      </code>
      
       (<code>
        /vue
      </code>
      
       also the type <code>
        CommentsStore
      </code>
      
      ); framework-free: <code>
        commentsFeatureCore
      </code>
      
      , <code>
        createCommentsModel
      </code>
      
      , <code>
        Comments
      </code>
      
       plugin helpers, <code>
        commentsSchemaExtensions()
      </code>
      
      , <code>
        CommentMark
      </code>
      
      , <code>
        CommentThread
      </code>
      
      , <code>
        CommentReply
      </code>
      
      , <code>
        COMMENT_LIMITS
      </code>
      
      , <code>
        COMMENTS_LAYOUTS
      </code>
      
      , <code>
        CommentsLayout
      </code>
      
      , and the margin's layout (the active thread pinned to its text's line, the others one-line cards out of its way): <code>
        layoutMargin(entries, activeId, { gap, minTop })
      </code>
      
       (with <code>
        MarginEntry
      </code>
      
      , <code>
        MarginLayout
      </code>
      
      , <code>
        MARGIN_GAP
      </code>
      
      ), <code>
        marginCards
      </code>
      
       (with <code>
        MarginCard
      </code>
      
      , <code>
        DRAFT_CARD
      </code>
      
      ; an orphaned thread sits at its deletion point, <code>
        CommentsSnapshot.orphanAt
      </code>
      
      , which host models may omit), <code>
        createMarginController
      </code>
      
       (with <code>
        MarginController
      </code>
      
      , <code>
        MarginSource
      </code>
      
      , <code>
        MarginState
      </code>
      
      : measuring and scheduling for both <code>
        CommentsMargin
      </code>
      
      s)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/composites/vue
      </code>
      
      , <code>
        /composites/react
      </code>
    </td>
    
    <td>
      <code>
        compositeFeature()
      </code>
      
       (Vue: Nuxt UI, React: shadcn), the host-placed <code>
        CompositeTable
      </code>
      
       and <code>
        CompositeInspector
      </code>
      
      , <code>
        SettingsEditingTab
      </code>
      
      , <code>
        CompositeChrome
      </code>
      
      , <code>
        CompositeDetails
      </code>
      
      , <code>
        CompositeView
      </code>
      
       and editors, <code>
        useCompositeRows
      </code>
      
      , <code>
        useCompositeAnchors
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/composites
      </code>
      
      , <code>
        /composites/schema
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        compositeFeatureCore
      </code>
      
      , <code>
        Composite
      </code>
      
      , <code>
        BlockType
      </code>
      
      , <code>
        BlockTypeAi
      </code>
      
      , <code>
        defaultBlockTypes
      </code>
      
      , <code>
        blockTypeOf
      </code>
      
      , <code>
        acceptsChild
      </code>
      
       (the Block types' Accepted children, <code>
        BlockType.accepts
      </code>
      
      ), <code>
        AcceptedChildren
      </code>
      
       (the editor extension that enforces them; registered by <code>
        compositeFeatureCore
      </code>
      
      ). Also <code>
        compositeOutline
      </code>
      
      , <code>
        documentOutline(doc, untitled, capabilitiesOf?, documentId?)
      </code>
      
       (the Block outline: headings and Typed blocks as one tree; <code>
        DocumentOutlineEntry
      </code>
      
      , <code>
        DocumentOutlineBlock
      </code>
      
      , <code>
        DocumentOutlineHeading
      </code>
      
      ), <code>
        moveBlockInto
      </code>
      
       (returns whether the document changed), <code>
        moveIntoVerdict(editor, id, targetId, t)
      </code>
      
       (with <code>
        MoveVerdict
      </code>
      
      : <code>
        { ok: true }
      </code>
      
       or <code>
        { ok: false, reason }
      </code>
      
       in the language of <code>
        t
      </code>
      
      ), <code>
        canMoveBlockInto
      </code>
      
       (<code>
        moveIntoVerdict(...).ok
      </code>
      
      ), <code>
        headingsMarkdown
      </code>
      
      , <code>
        documentCompositeMarkdown
      </code>
      
      , <code>
        Structure
      </code>
      
      , <code>
        createCompositeRows
      </code>
      
      , <code>
        createCompositeInspector
      </code>
      
      , <code>
        compositeFieldText
      </code>
      
      , <code>
        observeCompositeAnchors
      </code>
      
      , <code>
        compositeRows
      </code>
      
      , <code>
        setBlockProperty
      </code>
      
      , <code>
        setCompositeTags
      </code>
      
      , <code>
        setCompositeDescription
      </code>
      
      , <code>
        compositeDescriptionText
      </code>
      
      , <code>
        compositeSchemaExtensions()
      </code>
      
      , <code>
        blocksFromMarkdown
      </code>
      
      , <code>
        compositeFence
      </code>
      
      , conversions and heading↔Typed block transforms. Source-holding Typed blocks: <code>
        SOURCE_MEDIA_TYPES
      </code>
      
      , <code>
        sourceOf
      </code>
      
      , <code>
        derivedChildrenOf
      </code>
      
       (the Derived blocks of a Typed block), <code>
        Derivation
      </code>
      
       with <code>
        DERIVATION_KEY
      </code>
      
      , <code>
        derivationOf
      </code>
      
      , <code>
        derivationState
      </code>
      
      , <code>
        bodyMarkdown
      </code>
      
      ; bibliography: <code>
        CslItem
      </code>
      
      , <code>
        CSL_TYPES
      </code>
      
      , <code>
        bibOf
      </code>
      
      , <code>
        cslOf
      </code>
      
      , <code>
        citeShort
      </code>
      
      , <code>
        citeFull
      </code>
      
      , <code>
        bibtexOf
      </code>
      
      , <code>
        yearOf
      </code>
      
      , <code>
        cslTypeOptions
      </code>
      
      ; references: <code>
        ReferenceNode
      </code>
      
      , <code>
        referencesFromText
      </code>
      
      , <code>
        normalizeReferences
      </code>
      
      , <code>
        referenceMarkdown
      </code>
      
      ; <code>
        /composites
      </code>
      
       also <code>
        referenceSuggestion
      </code>
      
      , <code>
        referenceLabel
      </code>
      
      , <code>
        compositeBacklinks
      </code>
      
       (with <code>
        CompositeBacklink
      </code>
      
      , <code>
        CompositeReference
      </code>
      
      ) and <code>
        revealSource
      </code>
      
      , <code>
        seekSource
      </code>
      
      , <code>
        parseLocator
      </code>
      
      , <code>
        SourceReveal
      </code>
      
       (show a Typed block's source at a time or page); <code>
        /composites/schema
      </code>
      
       also <code>
        compositeIdsOf
      </code>
      
      . Baskets: <code>
        Basket
      </code>
      
       (<code>
        { id, label, color }
      </code>
      
      ), <code>
        BASKET_IDS
      </code>
      
      , <code>
        defaultBaskets(t)
      </code>
      
      , `basketOf(node
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/ai
      </code>
      
      , <code>
        /ai/protocol
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        aiFeatureCore
      </code>
      
      , <code>
        modelProfiles(app)
      </code>
      
      , <code>
        createAiAssistant
      </code>
      
      , <code>
        createDocumentChat
      </code>
      
      , <code>
        createAiSelectionFlow
      </code>
      
       (with <code>
        AI_SELECTION_MENU_KEY
      </code>
      
      ), <code>
        createAiReviewBar({ notify, t, editor })
      </code>
      
       (model of the review bar), <code>
        createAgentOpReview({ notify, t })
      </code>
      
       (host-driven agent edit review), <code>
        notifyAiRateLimited(notify, t)
      </code>
      
      , review/apply helpers (<code>
        startAiReview
      </code>
      
      , <code>
        applyAiResult
      </code>
      
      , …) and the protocol (<code>
        AI_TASKS
      </code>
      
      , <code>
        ModelRef
      </code>
      
      , <code>
        AGENT_OP_TYPES
      </code>
      
      , <code>
        AGENT_OP_OUTCOMES
      </code>
      
      , <code>
        CHAT_LIMITS
      </code>
      
      , …), importable alone from <code>
        /ai/protocol
      </code>
      
      ; the model-facing agent texts (<code>
        checkAgentOps
      </code>
      
      , <code>
        agentShownMessage
      </code>
      
      , <code>
        agentFeedbackText
      </code>
      
      , <code>
        agentRetryMessage
      </code>
      
      ) take a <code>
        locale: 'de' | 'en'
      </code>
      
       option (default <code>
        de
      </code>
      
      ), and <code>
        agentRetryMessage(problems, scoped, { locale, tool })
      </code>
      
       names the <code>
        tool
      </code>
      
       the model must call again (default <code>
        edit_document
      </code>
      
      ). The <code>
        [id]
      </code>
      
       line format of the chat's document text has one owner there, <code>
        block-lines
      </code>
      
      : writer helpers (<code>
        blockLine
      </code>
      
      , <code>
        singleBlockLine
      </code>
      
      , <code>
        nestedLinePrefix
      </code>
      
      , <code>
        quoteLinePrefix
      </code>
      
      , <code>
        listLinePrefix
      </code>
      
      , <code>
        continuedLinePrefix
      </code>
      
      , <code>
        compositeChromePart
      </code>
      
      , <code>
        compositeLineHeader
      </code>
      
      , <code>
        compositeLineClose
      </code>
      
      , <code>
        TRUNCATED_LINE
      </code>
      
      ), the reader <code>
        readBlockLines
      </code>
      
       (the block ids and which blocks lie inside which; lines in fenced code are not block lines; type <code>
        BlockLines
      </code>
      
      ), the echo strippers <code>
        stripBlockLineEcho
      </code>
      
       and <code>
        stripListMarkerEcho
      </code>
      
      , and the (German, model-facing) prompt texts <code>
        BLOCK_LINES_LABEL
      </code>
      
      , <code>
        BLOCK_LINE_INTRO
      </code>
      
      , <code>
        BLOCK_LINE_MARKERS
      </code>
      
      , <code>
        BLOCK_LINE_LIST_TEXT
      </code>
      
      , <code>
        BLOCK_LINE_HOST_TEXT
      </code>
      
      , <code>
        BLOCK_LINE_COMPOSITE_TEXT
      </code>
      
      , <code>
        BLOCK_LINE_ECHO_TEXT
      </code>
      
      , <code>
        BLOCK_LINE_IDS_HINT
      </code>
      
       with the example (<code>
        BLOCK_LINE_EXAMPLE
      </code>
      
      , <code>
        BLOCK_LINE_EXAMPLE_ID
      </code>
      
      , <code>
        BLOCK_LINE_EXAMPLE_TEXT
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/ai/actions
      </code>
    </td>
    
    <td>
      <code>
        documentActions({ editor, review, scope?, targets? })
      </code>
      
       (<code>
        DocumentActionsOptions
      </code>
      
      ): the forge actions <code>
        doc.read
      </code>
      
       and <code>
        doc.propose_ops
      </code>
      
       for a host chat with client tools (optional peer <code>
        @skaile/forge-app-actions
      </code>
      
      ; see <a href="https://skaile-ai.github.io/forge-editor/guides/ai#chat-agent-operations">
        Chat agent operations
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/ai/vue
      </code>
      
      , <code>
        /ai/react
      </code>
    </td>
    
    <td>
      <code>
        aiFeature()
      </code>
      
      , <code>
        AiSidebar
      </code>
      
       (React only; the Vue one is <code>
        /ai/vue/chat
      </code>
      
      ), <code>
        ModelQuickSwitch
      </code>
      
      , <code>
        AiReviewBar
      </code>
      
      , <code>
        AiSelectionMenu
      </code>
      
      , <code>
        SettingsAiTab
      </code>
      
      , <code>
        SettingsModelProfiles
      </code>
      
      ; <code>
        /ai/vue
      </code>
      
       also <code>
        useAiAssistant
      </code>
      
      , <code>
        useDocumentChat
      </code>
      
      , <code>
        useModelProfiles
      </code>
      
       (thin hooks over the models); <code>
        /ai/vue
      </code>
      
       is free of <code>
        @skaile/forge-chat
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/ai/vue/chat
      </code>
    </td>
    
    <td>
      The Vue <code>
        AiSidebar
      </code>
      
      . Renders on the optional peer <code>
        @skaile/forge-chat
      </code>
      
       (<code>
        ChatPanel
      </code>
      
      ): importing the entry without it throws an error naming the peer. The host imports <code>
        @skaile/forge-chat/styles/chat.css
      </code>
      
       and adds Tailwind <code>
        @source
      </code>
      
       for the package
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/direct-ai
      </code>
    </td>
    
    <td>
      <code>
        createDirectAi({ presets, roles?, users?, fetch? })
      </code>
      
       (<code>
        DirectAiOptions
      </code>
      
      , <code>
        DirectAiPreset
      </code>
      
      ): an <code>
        EditorBackend['ai']
      </code>
      
       that calls OpenAI-compatible chat-completion endpoints from the browser (<code>
        models
      </code>
      
      , <code>
        complete
      </code>
      
      , <code>
        generate
      </code>
      
      , <code>
        transcriptCleanup
      </code>
      
      ; <code>
        chat
      </code>
      
       and <code>
        extract
      </code>
      
       answer 501). The preset keys are readable by the page and no server rate limit applies; see <a href="https://skaile-ai.github.io/forge-editor/guides/storage-adapters#browser-direct-ai">
        Browser-direct AI
      </a>
      
       and the <a href="https://skaile-ai.github.io/forge-editor/guides/editor-ports#capability-locality">
        capability locality
      </a>
      
       table
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/render
      </code>
    </td>
    
    <td>
      <code>
        createRenderer(targets)
      </code>
      
       (a <code>
        Renderer
      </code>
      
       over <code>
        RenderTarget
      </code>
      
      s, the port <code>
        EditorPorts.render
      </code>
      
      ), <code>
        markdownTarget(options?)
      </code>
      
       (the built-in <code>
        markdown
      </code>
      
       target), <code>
        RenderTarget
      </code>
      
      , <code>
        RenderOutput
      </code>
      
      , <code>
        MarkdownTargetOptions
      </code>
      
      ; Node program, no Vue, React, Nitro or drizzle. See <a href="https://skaile-ai.github.io/forge-editor/guides/render">
        Render
      </a>
      
       and the <a href="https://skaile-ai.github.io/forge-editor/reference/renderer-port">
        Renderer port
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/speech
      </code>
    </td>
    
    <td>
      <code>
        createOpenAiSpeech(options)
      </code>
      
       (a <code>
        SpeechProvider
      </code>
      
       over an OpenAI-compatible <code>
        /audio/speech
      </code>
      
       endpoint, the port <code>
        EditorPorts.speech
      </code>
      
      ), <code>
        OPENAI_VOICES
      </code>
      
      , <code>
        createMemorySpeech(options?)
      </code>
      
       (one second of silent WAV, for tests and demos), <code>
        silentWav(seconds?)
      </code>
      
      ; Node program, no Vue, React, Nitro or drizzle. The daily budget <code>
        createSpeechBudget
      </code>
      
       and <code>
        SPEECH_CHARS_PER_DAY
      </code>
      
       are in <code>
        @skaile/forge-editor/server
      </code>
      
      . See <a href="https://skaile-ai.github.io/forge-editor/guides/speech">
        Speech
      </a>
      
       and the <a href="https://skaile-ai.github.io/forge-editor/reference/speech-port">
        Speech port
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/embeddings
      </code>
    </td>
    
    <td>
      <code>
        createOpenAiEmbedder(options)
      </code>
      
       (an <code>
        Embedder
      </code>
      
       over an OpenAI-compatible <code>
        /embeddings
      </code>
      
       endpoint, the port <code>
        EditorPorts.embeddings
      </code>
      
      ), <code>
        OPENAI_EMBEDDING_DIMENSIONS
      </code>
      
      ; Node program, no Vue, React, Nitro or drizzle. See <a href="https://skaile-ai.github.io/forge-editor/guides/index-pg">
        Index on Postgres
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/adapters/knowledge
      </code>
    </td>
    
    <td>
      <code>
        createMemoryKnowledgeGraph(nodes, edges)
      </code>
      
       (a <code>
        KnowledgeGraph
      </code>
      
       over fixed nodes and edges, searched by the words of the labels, the port <code>
        EditorPorts.knowledge
      </code>
      
      , for tests and demos), <code>
        MEMORY_KNOWLEDGE_LIMIT
      </code>
      
      ; Node program, no Vue, React, Nitro or drizzle. A real graph is the host's: <code>
        @skaile/forge-editor-kgs
      </code>
      
       wraps the KGS SDK. See <a href="https://skaile-ai.github.io/forge-editor/guides/knowledge-graph">
        Knowledge graph
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/integrations/composite-ai
      </code>
    </td>
    
    <td>
      Framework-free (labels quoted in their English catalog form): <code>
        compositeAiFeature
      </code>
      
       (requires <code>
        composites
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        media
      </code>
      
      ), <code>
        fillComposite
      </code>
      
      , <code>
        generateCompositeBody
      </code>
      
       (with <code>
        CompositeBodyResult
      </code>
      
      ), <code>
        summarizeComposite
      </code>
      
      , <code>
        createRendition
      </code>
      
      , <code>
        regenerateRendition
      </code>
      
      , <code>
        canCreateRendition
      </code>
      
      , <code>
        canRegenerateRendition
      </code>
      
      , <code>
        RenditionOptions
      </code>
      
       (“Create readable rendition”, “Regenerate (replace)”), <code>
        deriveComposite
      </code>
      
      , <code>
        canDeriveAfter
      </code>
      
      , <code>
        derivableBlockTypesOf
      </code>
      
      , <code>
        isDerivableSource
      </code>
      
       (“Derive (AI)”), <code>
        fetchBibliography
      </code>
      
      , <code>
        canFetchBibliography
      </code>
      
      , <code>
        doiOf
      </code>
      
       (“Fetch bibliography”), <code>
        compositeSourceText
      </code>
      
      , <code>
        COMPOSITE_BODY_START
      </code>
      
      . Splitting and outline: <code>
        splitCompositeWithAi
      </code>
      
      , <code>
        bodyUnchanged
      </code>
      
      , <code>
        splitByInsertedHeadings
      </code>
      
       (“Split into sub-blocks with AI” / “Split into blocks with AI”); <code>
        sanitizeOutline
      </code>
      
      , <code>
        collectHeadings
      </code>
      
      , <code>
        parseOutlineResponse
      </code>
      
      , <code>
        applyOutline
      </code>
      
      , <code>
        OutlineHeading
      </code>
      
      , <code>
        OutlineEntry
      </code>
      
       (“Clean up outline (AI)”); <code>
        writeDerivedBody
      </code>
      
      , <code>
        discardDerived
      </code>
      
       (the write-back of “Derive (AI)”). Transfer: <code>
        summaryTransform
      </code>
      
      , <code>
        bulletsTransform
      </code>
      
       (<code>
        BlockTransform
      </code>
      
      s for the transfer menu: “Insert summary”, “Insert bullet points”), <code>
        transferRequest
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/integrations/composite-media
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        compositeMediaFeature
      </code>
      
       (requires <code>
        composites
      </code>
      
      , <code>
        media
      </code>
      
      ): imported files become Typed blocks of the Block type whose <code>
        import
      </code>
      
       capability takes their media (built in: <code>
        recording
      </code>
      
       for audio/video, <code>
        figure
      </code>
      
       for images, <code>
        document
      </code>
      
       otherwise); block action “Replace source” (English label)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/integrations/transcript-ai
      </code>
      
      , <code>
        /transcript-ai/protocol
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        transcriptAiFeature
      </code>
      
       (requires <code>
        transcript
      </code>
      
      , <code>
        ai
      </code>
      
      ), <code>
        createTranscriptCleanup
      </code>
      
      , <code>
        hasTranscriptSegments
      </code>
      
      ; server contract: <code>
        TRANSCRIPT_CLEANUP_LIMITS
      </code>
      
      , <code>
        transcriptCleanupRequestSchema
      </code>
      
      , <code>
        transcriptCleanupMessages
      </code>
      
      , <code>
        transcriptCleanupChunks
      </code>
      
      , <code>
        parseTranscriptCleanup
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/collab
      </code>
      
      , <code>
        /collab/vue
      </code>
      
      , <code>
        /collab/react
      </code>
    </td>
    
    <td>
      Framework-free: <code>
        collabFeatureCore(ui?)
      </code>
      
       (Yjs <code>
        Collaboration
      </code>
      
      /<code>
        CollaborationCaret
      </code>
      
      , active only with a <code>
        collaboration
      </code>
      
       session on the surface), <code>
        yjsAnchorResolver
      </code>
      
      ; <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        collabFeature()
      </code>
      
       (the Vue one adds the <code>
        @tiptap/vue-3
      </code>
      
       state-sync workaround, the React one needs none)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/block-ui
      </code>
      
      , <code>
        /block-ui/vue
      </code>
      
      , <code>
        /block-ui/react
      </code>
    </td>
    
    <td>
      <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        blockUiFeature(options?)
      </code>
      
       (<code>
        BlockUiOptions.actions
      </code>
      
      : <code>
        'hover'
      </code>
      
       default, <code>
        'toolbar'
      </code>
      
      , <code>
        'both'
      </code>
      
      , <code>
        'none'
      </code>
      
      ), <code>
        BlockUi
      </code>
      
      , <code>
        BlockActionsOverlay
      </code>
      
      ; framework-free: <code>
        blockUiFeatureCore(ui, options?)
      </code>
      
      , <code>
        blockActionsFor(editor, target, actions, surface)
      </code>
      
      , <code>
        selectedBlockOf
      </code>
      
      , <code>
        sameBlock
      </code>
      
      , <code>
        actionSurfacesOf
      </code>
      
      , <code>
        effectiveTarget
      </code>
      
      , <code>
        BLOCK_CORNER_ATTR
      </code>
      
       and <code>
        blockCornerOf
      </code>
      
       (a node view marks its own top-right icons with <code>
        data-block-corner
      </code>
      
      ; the bar docks left of them): drag handle, hover targeting and block actions (opt-in; the simple editor never includes it)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/transfer
      </code>
      
      , <code>
        /transfer/vue
      </code>
      
      , <code>
        /transfer/react
      </code>
    </td>
    
    <td>
      Block transfer between editor surfaces and trees. Framework-free: <code>
        transferFeatureCore(ui, options?)
      </code>
      
      , <code>
        TransferFeatureOptions
      </code>
      
       (<code>
        { transforms?, defaultTransform? }
      </code>
      
      ), <code>
        TransferUi
      </code>
      
      , <code>
        BlockTransform
      </code>
      
      , <code>
        TransformContext
      </code>
      
      , <code>
        TransferEnv
      </code>
      
      , <code>
        copyTransform
      </code>
      
      , <code>
        DEFAULT_TRANSFORMS
      </code>
      
       (the copy), <code>
        runTransform
      </code>
      
      , <code>
        availableTransforms
      </code>
      
      , <code>
        transformContextOf
      </code>
      
      , <code>
        transferKindOf
      </code>
      
      , <code>
        transferSourceHash
      </code>
      
      , <code>
        createsOf
      </code>
      
      , <code>
        withFreshBlockIds
      </code>
      
      , <code>
        isSelfDrop
      </code>
      
      , <code>
        BlockDropTargetStorage
      </code>
      
      , <code>
        TransferDrop
      </code>
      
      , <code>
        PendingDrop
      </code>
      
      ; the AI transforms <code>
        summaryTransform
      </code>
      
      , <code>
        bulletsTransform
      </code>
      
       and <code>
        transferRequest
      </code>
      
       are in <code>
        @skaile/forge-editor/integrations/composite-ai
      </code>
      
      ; <code>
        /vue
      </code>
      
       and <code>
        /react
      </code>
      
      : <code>
        transferFeature(options?)
      </code>
      
      , <code>
        TransferMenu
      </code>
      
      . The payload side (<code>
        BLOCK_MIME
      </code>
      
      , <code>
        BlockTransfer
      </code>
      
      , <code>
        readBlockTransfer
      </code>
      
      , <code>
        writeBlockTransfer
      </code>
      
      , <code>
        blockTransferOf
      </code>
      
      , <code>
        BlockTransferStorage
      </code>
      
      ) is in <code>
        @skaile/forge-editor/core
      </code>
      
      . See <a href="https://skaile-ai.github.io/forge-editor/guides/content-tree#block-transfer">
        Content tree mechanics
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/schema/advanced
      </code>
    </td>
    
    <td>
      Vue-free <code>
        advancedSchemaExtensions()
      </code>
      
      : the advanced schema for servers, validators and migrations
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/server
      </code>
      
      , <code>
        /server/handlers
      </code>
      
      , <code>
        /server/node
      </code>
      
      , <code>
        /nuxt
      </code>
    </td>
    
    <td>
      Server side without a web framework: <code>
        createCollabServer
      </code>
      
      , <code>
        createAiModels
      </code>
      
      , <code>
        createRateLimiter
      </code>
      
      , <code>
        loadCurrentContent
      </code>
      
      , <code>
        listCurrentContents
      </code>
      
      , <code>
        currentContent
      </code>
      
       (stored content in the current shape), <code>
        EditorPorts
      </code>
      
       with its port interfaces (<code>
        AccessControl
      </code>
      
      , <code>
        DocumentContentStore
      </code>
      
      , <code>
        CollabStateStore
      </code>
      
      , <code>
        Directory
      </code>
      
      , <code>
        AssetStore
      </code>
      
      , <code>
        SettingsStore
      </code>
      
      , <code>
        ThemeStore
      </code>
      
      , <code>
        ModelProvider
      </code>
      
      ), <code>
        serverCapabilities
      </code>
      
      , one request handler per route (<code>
        /server/handlers
      </code>
      
      ), <code>
        listenCollab
      </code>
      
       for a plain Node script (<code>
        /server/node
      </code>
      
      ); the Nitro installers <code>
        installEditorServer
      </code>
      
      , <code>
        provideEditorServer
      </code>
      
       and <code>
        useEditorServer
      </code>
      
       (<code>
        /server/nitro
      </code>
      
      ), whose <code>
        EditorServer
      </code>
      
       handle offers <code>
        forgetDocument
      </code>
      
      , <code>
        liveContent
      </code>
      
      , <code>
        enforceRateLimit
      </code>
      
      , <code>
        resolveModel
      </code>
      
      ; the Nuxt module (config key <code>
        tiptapEditor
      </code>
      
      ) wraps the same core. See the <a href="https://skaile-ai.github.io/forge-editor/guides/editor-ports">
        integration guide
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        @skaile/forge-editor/styles/core.css
      </code>
      
       (required), <code>
        /composites.css
      </code>
      
      , <code>
        /media.css
      </code>
      
      , <code>
        /mentions.css
      </code>
      
      , <code>
        /tables.css
      </code>
      
      , <code>
        /authors.css
      </code>
      
      , <code>
        /comments.css
      </code>
      
      , <code>
        /transcript.css
      </code>
      
      , <code>
        /ai.css
      </code>
      
      , <code>
        /collab.css
      </code>
      
      , <code>
        /block-ui.css
      </code>
      
      , <code>
        /themes.css
      </code>
    </td>
    
    <td>
      Feature CSS (import after Tailwind, Nuxt UI (Vue) or <code>
        ui-vars.css
      </code>
      
       (React) and <code>
        core.css
      </code>
      
      ; <code>
        themes.css
      </code>
      
       after the feature sheets). The Nuxt module adds all of them itself
    </td>
  </tr>
</tbody>
</table>


# Feature contract

> The EditorFeature, FeatureContext and EditorPreset types, what defineEditor validates and how to contribute a custom feature.

A feature is an object whose optional members are the contribution points. Fill only what you need. The types below come straight from `packages/editor/src/core/feature.ts`.

## `EditorFeature`

```ts [packages/editor/src/core/feature.ts]
*/
export type Dimension = 'content' | 'interaction' | 'ai'

/** One named contribution to an editor (blocks, toolbar entries, menus, settings, AI knowledge). Every member is optional but `dimension`; identity and ordering come from the feature list. */
export interface EditorFeature<C = unknown> {
  id: string
  /** The feature's primary dimension. */
  dimension: Dimension
  /**
   * The Vue-free schema-bearing extensions of this feature (no node views, no UI), collected by `schemaExtensionsOf` for
   * the server schema. Present on every feature whose nodes or marks the stored document can contain.
   */
  schemaExtensions?: () => AnyExtension[]
  /** Ids of features that must also be installed (`defineEditor` does not install them). */
  requires?: readonly string[]
  /** Backend capabilities the feature cannot work without; a surface session over a backend lacking one throws. Optional capabilities (users and tags for mentions) are not listed. */
  backend?: readonly BackendCapability[]
  extensions?: (ctx: FeatureContext) => AnyExtension[]
  blockActions?: (ctx: FeatureContext) => BlockAction[]
  /**
   * Block capabilities the feature declares (`container` and `title` are built in): descriptors of what a block is, which a
   * `BlockAction.requires` names and `capabilitiesAt` answers. Ids are unique across features. A capability installs nothing:
   * schema, extensions and node views stay with the feature that owns the mechanism.
   */
  blockCapabilities?: readonly BlockCapability[]
  /**
   * Ways to make a new block or text from a block (transcription, text extraction, summary, AI fill, AI derivation, bibliography fetch):
   * one registry across all features, each method declaring the capabilities the original must have (`requires`) and its backend
   * flags (`available`). The block actions of the methods are generated from it. Ids are unique across features and every
   * `requires` id must be a declared capability; `defineEditor` throws otherwise.
   */
  deriveMethods?: readonly DeriveMethod[]
  /**
   * The Block types the feature's editor offers: data (an id and the capabilities each type lists with their config) the capability
   * registry answers from. Additive: the contributions of all features concatenate in feature order. An editor created from the preset
   * checks them against the declared capabilities (`validateBlockTypes`): an unknown capability id or an invalid config throws. Block
   * types are per editor (the composites feature builds its defaults in the surface's language).
   */
  blockTypes?: (editor: Editor) => readonly BlockTypeData[]
  /**
   * Options of the block UI (`BlockUiOptions`: which surfaces render block actions). Set by the block-ui feature; the
   * overlay components are mounted by the surface without props, so they read it from the editor entry (`EditorEntry.blockUi`).
   */
  blockUi?: Readonly<BlockUiOptions>
  /** The feature's commands, each declared once with its toolbar and `/` placements (see `CommandDef`). */
  commands?: (ctx: FeatureContext) => CommandDef<C>[]
  /** Toolbar groups the feature declares; every command's `toolbar.group` must be declared by some feature. Ids are unique across features. */
  toolbarGroups?: ToolbarGroupDef[]
  /** Rules a command's `creates` must pass at the caret besides the schema (e.g. a Typed block's accepted children). */
```

The members at a glance:

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Contributes
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        extensions(ctx)
      </code>
    </td>
    
    <td>
      TipTap extensions (nodes, marks, plugins)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        commands(ctx)
      </code>
      
      , <code>
        toolbarGroups
      </code>
      
      , <code>
        insertGuards(ctx)
      </code>
    </td>
    
    <td>
      <code>
        CommandDef[]
      </code>
      
       declared once with <code>
        toolbar
      </code>
      
       and <code>
        slash
      </code>
      
       placements (toolbar, <code>
        /
      </code>
      
       menu, ⌘K palette, enabled/visible state via <code>
        commandState
      </code>
      
      ), the groups they name, and guards a <code>
        creates
      </code>
      
       command must pass (e.g. a Typed block's Accepted children)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transactionGuards(ctx)
      </code>
    </td>
    
    <td>
      <code>
        TransactionGuard[]
      </code>
      
      : <code>
        (tr, state) => true | string
      </code>
      
      , run in feature order for every transaction that changes the document (not for selection-only ones). The first string refuses the whole transaction and is shown as the notice. For rules no schema expresses (a locked paragraph, a required document shape); <code>
        insertGuards
      </code>
      
       only gate commands
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockActions(ctx)
      </code>
    </td>
    
    <td>
      block actions (shown by <code>
        block-ui
      </code>
      
      : hover bar, selected-block toolbar or both, per <code>
        BlockUiOptions.actions
      </code>
      
      ); <code>
        ability
      </code>
      
       unset = every block; <code>
        placement: 'hover' | 'toolbar' | 'both'
      </code>
      
       (default <code>
        'both'
      </code>
      
      ) narrows the surface; <code>
        target: 'block' | 'typedBlock'
      </code>
      
       (default <code>
        'block'
      </code>
      
      ): with <code>
        'typedBlock'
      </code>
      
       the toolbar evaluates the action against the Typed block around the selected block (<code>
        ctx.node
      </code>
      
      , <code>
        ctx.pos
      </code>
      
       are the Typed block's), absent when none encloses it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        overlays
      </code>
    </td>
    
    <td>
      framework components (<code>
        EditorFeature<C>
      </code>
      
      ; Vue: <code>
        VueFeature
      </code>
      
      ) mounted beside the content, receiving <code>
        { editor }
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        rowBadges(ctx)
      </code>
    </td>
    
    <td>
      <code>
        RowBadge[]
      </code>
      
      : chips after the title of a Typed block in the composites chrome, additive in feature order (<code>
        of(editor, row)
      </code>
      
       returns <code>
        { label, tone } | null
      </code>
      
      ; optional <code>
        subscribe
      </code>
      
       for changes outside the editor's transactions). The Prüfung feature draws „Geprüft“ / „Prüfung veraltet“ this way
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        documentBadges(ctx)
      </code>
    </td>
    
    <td>
      <code>
        DocumentBadge[]
      </code>
      
      : chips of the whole document, drawn after the „Dokument“ heading of the inspector and on the open document's row of the Block outline in the Document tree (<code>
        of(editor)
      </code>
      
      , optional <code>
        subscribe
      </code>
      
      ). The Prüfung feature draws the Freigabestatus this way
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inspectorSections(ctx)
      </code>
    </td>
    
    <td>
      <code>
        InspectorSection<C>[]
      </code>
      
      : sections of the Typed block inspector and details card below the block's fields, additive in feature order (<code>
        { id, title, component, appliesTo? }
      </code>
      
      ; ids unique). The Prüfung feature adds „Prüfstand“
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        setup(ctx)
      </code>
    </td>
    
    <td>
      per-surface side effect when the surface mounts (runtime, listener, <code>
        <head>
      </code>
      
       element); returns an optional <strong>
        teardown
      </strong>
      
       the surface runs when it unmounts
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        settingsTabs
      </code>
    </td>
    
    <td>
      factory <code>
        (ctx: EditorContext) => SettingsTab<C>[]
      </code>
      
       for the tabs of <code>
        EditorSettingsPanel
      </code>
      
      /<code>
        EditorSettingsModal
      </code>
      
       (<code>
        SettingsTab<C>
      </code>
      
      : <code>
        label
      </code>
      
       is already translated, the <code>
        component
      </code>
      
       slot is the framework's component type)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadataDefaults(ctx)
      </code>
    </td>
    
    <td>
      built-in <code>
        @
      </code>
      
      /<code>
        #
      </code>
      
      -style lists
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blocks
      </code>
      
      , <code>
        conversions
      </code>
    </td>
    
    <td>
      block pipeline stages, „Umwandeln in …“ providers
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        anchorResolver
      </code>
      
      , <code>
        aiContext
      </code>
      
      , <code>
        formatAiResult
      </code>
    </td>
    
    <td>
      collaboration positions, what AI knows about the document, AI result formatting
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        aiBlockData
      </code>
    </td>
    
    <td>
      material per Typed block for „Block füllen (KI)“ (additive; the host owns the fetch)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        requires
      </code>
    </td>
    
    <td>
      ids of features that must also be listed
    </td>
  </tr>
</tbody>
</table>

## `FeatureContext`

Every factory (`extensions`, `commands`, `blockActions`, …) receives the `FeatureContext` of the surface it runs on. It is created when a surface is set up and never shared between editors.

```ts [packages/editor/src/core/feature.ts]
stopUndoCapture: (state: EditorState) => boolean
}

/** Per-surface dependencies of a feature's factories. Created when a surface is set up; never shared between editors. */
export interface FeatureContext {
  /** The app context the surface belongs to (shared by all editors of the app): app-level models key on it. */
  readonly app: EditorContext
  /** The app's shared settings (see `createEditorContext`): read with `get()`, write with `update()`, observe with `subscribe()`. */
  readonly settings: Store<EditorSettings>
  readonly metadata: MetadataRegistry
  /** Chrome of the editor this context belongs to (settings, sidebar). */
  readonly ui: EditorUi
  /** Shows a notice through the surface's framework (Nuxt UI toast, sonner). */
  readonly notify: Notifier
  /** The app's UI language (`createEditorContext({ locale })`). */
  readonly locale: Locale
  /** Renders a catalog message in the app's language; every label a feature contributes goes through it. */
  readonly t: Translate
  /** The data layer of the app (`createEditorContext({ backend })`): uploads, mention lookups, themes, AI. */
  readonly backend: EditorBackend
  /** Inert public AI configuration of the app context; absent when none was supplied. */
  readonly ai: EditorAiConfig | undefined
  /** Document whose package stores uploads (media feature). */
  readonly documentId: string | undefined
  readonly collaboration: CollaborationSession | undefined
  /** The collaboration-aware position mapping of the preset's `anchorResolver` feature; null means local mapping only. */
  readonly anchorResolver: AnchorResolver | null
  /** Host options for the ability extension (`abilities` prop). */
  readonly abilities: Partial<AbilitiesOptions>
  /** The final command list: the features' commands after the host's `commands` transformer. The `/` menu lists the ones with a `slash` placement. */
  readonly commands: () => CommandDef[]
```

## `EditorPreset`

```ts [packages/editor/src/core/feature.ts]
/**
   * Refusals of whole transactions: every transaction that changes the document runs through the guards of all
   * features, in feature order; the first one answering a string refuses it and shows that string as a notice. For rules
   * about the document as a whole that no schema expresses (a locked paragraph, a required document shape).
   */
  transactionGuards?: (ctx: FeatureContext) => TransactionGuard[]
  /** Components mounted beside the editor content; they receive `{ editor }`. `C` is the component type of the framework layer that renders them. */
  overlays?: readonly C[]
  /**
   * Chips after the title of a Typed block in the composites chrome, additive in feature order (one per `RowBadge`).
   * The factory runs once per surface; the chrome reads the result from the editor entry (`EditorEntry.rowBadges`).
   */
```

## What `defineEditor` validates

`defineEditor({ features })` keeps the given order, neither deduplicates nor installs missing dependencies, and throws for:

- a feature without a `dimension`;
- a duplicate feature `id`;
- a `requires` entry that is not installed;
- a toolbar group declared by two features (`toolbarGroups`);
- a singleton hook contributed twice (`parseMarkdown`, `segment`, `structure`, `migrateContent`, `anchorResolver`, `formatAiResult`);
- an importer id declared twice (`importers`).

A command naming a toolbar group no feature declares needs the feature context to build the commands: `toolbarOf` throws it. `normalize` hooks chain left to right. `aiContext` contributions merge (`blockTypes` and `blocks` concatenated in feature order, `structure` from one feature only); `aiBlockData` contributions are additive too. The doc comment of the function:

```ts [packages/editor/src/core/define-editor.ts]
const fail = (message: string): never => failWith(message, 'defineEditor')

/**
 * Validates `features` and resolves their pipeline and conversion providers. Keeps the given order; neither
 * deduplicates nor installs missing dependencies. Throws on duplicate ids, a `requires` entry that is not installed,
 * a toolbar group declared by two features (`toolbarGroups`), a block capability declared twice or with a built-in id (`blockCapabilities`), a derive method declared twice, with neither `run` nor `menu` or requiring an undeclared capability (`deriveMethods`), an importer id declared twice (`importers`) and a singleton hook (`parseMarkdown`, `segment`, `structure`, `migrateContent`, `anchorResolver`,
 * `formatAiResult`) contributed twice. A command naming a toolbar group no feature declares needs the feature context
 * to build the commands: `toolbarOf` throws it. `normalize` hooks chain left to right. `aiContext` contributions merge (`blockTypes` and `blocks`
 * concatenated in feature order, `structure` from one feature only); their conflicts surface when the merged `aiContext` reads the editor.
```

## Example: a `notes` feature

```ts
// notes/feature.ts
import { command } from '@skaile/forge-editor/core'
import type { VueFeature } from '@skaile/forge-editor/vue'
import SettingsNotesTab from './SettingsNotesTab.vue'

export function notesFeature(): VueFeature {
  return {
    id: 'notes',
    dimension: 'interaction', // 'content' when it adds nodes or marks, 'ai' for AI features
    // requires: ['block-ui'], // fail at composition time when a dependency is missing
    toolbarGroups: [{ id: 'notes', order: 100 }],
    // One declaration per command: the toolbar button and the `/strich` entry share label, icon and gating.
    commands: () => [
      command({
        id: 'dash',
        toolbar: { group: 'notes' },
        slash: { id: 'strich' },
        icon: 'i-lucide-minus',
        label: 'Gedankenstrich',
        command: chain => chain.insertContent('\u2013'),
      }),
    ],
    // 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 '@skaile/forge-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 '@skaile/forge-editor/core'
import { advancedEditor } from '@skaile/forge-editor/vue/advanced'
import { notesFeature } from './notes/feature'

const preset = defineEditor({ features: [...advancedEditor().features, notesFeature()] })
```

## Things that bite

- Items gated by an own `ability` (`CommandDef.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 block that draws its own icons in its top-right corner marks them with `data-block-corner` (`BLOCK_CORNER_ATTR` from `/block-ui`): the bar then docks immediately left of them, centred on their row, instead of covering them.
- 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 `schema` option of `provideEditorServer({ ports, schema })`, so register the Vue-free node file there (`schema: () => [...advancedSchemaExtensions(), YourNode]`, [tutorial chapter, Backend and collaboration](https://skaile-ai.github.io/forge-editor/tutorial/backend-and-collaboration)); 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`, `commands`, `blockActions`, ...) receive the `FeatureContext`: `app`, `settings`, `metadata`, `ui`, `notify`, `backend`, `ai`, `documentId`, `collaboration`, `getEditor()`. `backend` is the `EditorBackend` of the app (uploads, lookups, themes, AI: `ctx.backend.assets?.upload(...)`); features never call `fetch`. `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. Menu commands 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` commands receive `{ editor }` as props.

Complete worked example with node, node view, conversions and AI description: the tutorial chapter [The callout as a feature](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b) and the runnable [`app/editor/callout/`](https://github.com/skaile-ai/forge-editor/tree/main/app/editor/callout). Lighter path without a feature (`extensions` prop and `commands` transformer): [The callout through props](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a).


# Presets and features

> Which features each preset contains, which backend it needs and which modules its bundle must not contain.

<table>
<thead>
  <tr>
    <th>
      Preset
    </th>
    
    <th>
      Features
    </th>
    
    <th>
      Backend / Yjs
    </th>
    
    <th>
      Bundle isolation (<code>
        check:editor-entries
      </code>
      
      )
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        simple
      </code>
      
       (<code>
        SimpleEditor
      </code>
      
      , <code>
        simpleEditor()
      </code>
      
      )
    </td>
    
    <td>
      <code>
        core
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      no feature, integration, AI SDK, Yjs, y-tiptap, Hocuspocus, Nuxt or server modules in the emitted chunks
    </td>
  </tr>
  
  <tr>
    <td>
      React <code>
        SimpleEditor
      </code>
      
       + <code>
        EditorToolbar
      </code>
      
       (<code>
        ./react/simple
      </code>
      
      , <code>
        ./react
      </code>
      
      )
    </td>
    
    <td>
      <code>
        core
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      no <code>
        vue
      </code>
      
      , <code>
        @vue
      </code>
      
      , <code>
        @tiptap/vue-3
      </code>
      
      , Nuxt UI or Vue-layer module in the emitted chunks (<code>
        react-simple
      </code>
      
       fixture); the headless core (<code>
        core-headless
      </code>
      
       fixture) contains no Vue, React or layer module at all
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        mediaFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        media
      </code>
    </td>
    
    <td>
      uploads only (a backend with <code>
        assets
      </code>
      
      )
    </td>
    
    <td>
      no Typed block, AI, Yjs, Nuxt or sibling-feature modules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        mentionsFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        mentions
      </code>
    </td>
    
    <td>
      built-in <code>
        @
      </code>
      
      /<code>
        #
      </code>
      
       lists only (or host lists)
    </td>
    
    <td>
      same
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        transcriptFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        transcript
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      same
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        authorsFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        authors
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      same
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        themesFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        themes
      </code>
    </td>
    
    <td>
      <code>
        /api/editor/themes[/:id]
      </code>
      
       (adapter <code>
        listThemes
      </code>
      
      /<code>
        loadTheme
      </code>
      
      )
    </td>
    
    <td>
      no Typed block, AI, media, mentions, transcript, authors, comments, collaboration, block-UI, integration, Yjs or Nuxt modules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        collabFeature()
      </code>
      
       + <code>
        commentsFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        collab
      </code>
      
      , <code>
        comments
      </code>
    </td>
    
    <td>
      <code>
        /collab/:id
      </code>
      
       websocket (comments live in the Y.Doc)
    </td>
    
    <td>
      no Typed block, AI, media, mentions, transcript, authors, block-UI, integration or Nuxt modules; Yjs is bundled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        aiFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        ai
      </code>
    </td>
    
    <td>
      <code>
        /api/ai/{models,generate,chat,complete}
      </code>
      
       (see <a href="https://skaile-ai.github.io/forge-editor/guides/ai">
        AI
      </a>
      
      )
    </td>
    
    <td>
      no Typed block, transcript, media, mentions, collaboration, integration, Yjs or Nuxt modules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        media
      </code>
      
       + <code>
        composites
      </code>
      
       + <code>
        aiFeature()
      </code>
      
       + <code>
        compositeAiFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        media
      </code>
      
      , <code>
        composites
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        composite-ai
      </code>
    </td>
    
    <td>
      AI endpoints plus <code>
        /api/ai/extract
      </code>
    </td>
    
    <td>
      no transcript, mentions, collaboration, other integration, Yjs or Nuxt modules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        transcriptFeature()
      </code>
      
       + <code>
        aiFeature()
      </code>
      
       + <code>
        transcriptAiFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        transcript
      </code>
      
      , <code>
        ai
      </code>
      
      , <code>
        transcript-ai
      </code>
    </td>
    
    <td>
      AI endpoints plus <code>
        /api/ai/transcript-cleanup
      </code>
    </td>
    
    <td>
      no Typed blocks, media, mentions, collaboration, other integration, Yjs or Nuxt modules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        collabFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        collab
      </code>
    </td>
    
    <td>
      <code>
        /collab/:id
      </code>
      
       websocket (Nuxt module) or any Hocuspocus server on the advanced schema
    </td>
    
    <td>
      no Typed block, AI, media, mentions, block-UI, integration or Nuxt modules; Yjs is bundled
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        blockUiFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        block-ui
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      no Typed block, AI, media, mentions, collab-feature or Nuxt modules (the drag handle's upstream package bundles Yjs support code)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        compositeFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        composites
      </code>
    </td>
    
    <td>
      none
    </td>
    
    <td>
      no AI, media, transcript, mentions, collaboration, block-UI, integration, Yjs or Nuxt modules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        composites
      </code>
      
       + <code>
        transferFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        composites
      </code>
      
      , <code>
        transfer
      </code>
    </td>
    
    <td>
      none (<code>
        copy
      </code>
      
       only; the AI transforms <code>
        summary
      </code>
      
       and <code>
        bullets
      </code>
      
       come from <code>
        integrations/composite-ai
      </code>
      
      , which <code>
        composeEditor
      </code>
      
       adds with <code>
        ai
      </code>
      
       on)
    </td>
    
    <td>
      no AI, media, transcript, mentions, collaboration, integration, Yjs or Nuxt modules in the framework-free <code>
        transfer
      </code>
      
       entry; its bindings add their framework's layer only
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        core
      </code>
      
       + <code>
        media
      </code>
      
       + <code>
        composites
      </code>
      
       + <code>
        compositeMediaFeature()
      </code>
    </td>
    
    <td>
      <code>
        core
      </code>
      
      , <code>
        media
      </code>
      
      , <code>
        composites
      </code>
      
      , <code>
        composite-media
      </code>
    </td>
    
    <td>
      uploads only
    </td>
    
    <td>
      no AI, transcript, mentions, collaboration, other integration, Yjs or Nuxt modules
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        DocumentTree
      </code>
      
       (<code>
        ./tree/vue
      </code>
      
       or <code>
        ./tree/react
      </code>
      
      ) beside <code>
        core
      </code>
      
       + <code>
        media
      </code>
      
       + <code>
        composites
      </code>
    </td>
    
    <td>
      tree, <code>
        core
      </code>
      
      , <code>
        media
      </code>
      
      , <code>
        composites
      </code>
    </td>
    
    <td>
      the host's <code>
        DocumentStore
      </code>
    </td>
    
    <td>
      no AI, transcript, mentions, collaboration, block-UI, integration, Yjs or Nuxt modules; the <code>
        simple
      </code>
      
       bundle never contains the tree; the React tree contains no Vue module (<code>
        tree-react
      </code>
      
       fixture), the framework-free <code>
        ./tree
      </code>
      
       no Vue and no React (<code>
        headless-tree
      </code>
      
       fixture)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        advancedEditor()
      </code>
      
       / <code>
        AdvancedEditor
      </code>
      
       (<code>
        ./vue/advanced
      </code>
      
      )
    </td>
    
    <td>
      every feature (including <code>
        themes
      </code>
      
      ) and integration, Vue bindings
    </td>
    
    <td>
      <code>
        /collab/:id
      </code>
      
      , AI endpoints, assets, users/tags, themes (Nuxt module plus a host adapter, or a host server)
    </td>
    
    <td>
      requires all feature and integration modules; no React, <code>
        sonner
      </code>
      
      , Nuxt, <code>
        nitropack
      </code>
      
      , <code>
        h3
      </code>
      
      , vue-router or server code in the browser bundle (<code>
        advanced
      </code>
      
       fixture)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        advancedEditor()
      </code>
      
       / <code>
        AdvancedEditor
      </code>
      
       (<code>
        ./react/advanced
      </code>
      
      )
    </td>
    
    <td>
      every feature (including <code>
        themes
      </code>
      
      ) and integration, React bindings
    </td>
    
    <td>
      the same endpoints, through the Nuxt host or a host server (<code>
        examples/react-advanced
      </code>
      
       proxies <code>
        /api
      </code>
      
       and <code>
        /collab
      </code>
      
       to the Nuxt app)
    </td>
    
    <td>
      requires all feature and integration modules; no <code>
        vue
      </code>
      
      , <code>
        @vue
      </code>
      
      , <code>
        @tiptap/vue-3
      </code>
      
      , Nuxt UI, Vue-layer or <code>
        .vue
      </code>
      
       module, no Nuxt or server code (<code>
        advanced-react
      </code>
      
       fixture)
    </td>
  </tr>
  
  <tr>
    <td>
      Any feature on one layer (<code>
        <x>/vue
      </code>
      
      , <code>
        <x>/react
      </code>
      
      , <code>
        <x>
      </code>
      
       alone)
    </td>
    
    <td>
      <code>
        core
      </code>
      
       + that feature
    </td>
    
    <td>
      as listed above
    </td>
    
    <td>
      <code>
        <x>-react
      </code>
      
       fixtures contain no Vue or Nuxt UI module; the Vue fixtures no React, <code>
        react-dom
      </code>
      
       or <code>
        sonner
      </code>
      
      ; the framework-free <code>
        headless-<x>
      </code>
      
       fixtures neither framework
    </td>
  </tr>
</tbody>
</table>

Settings are stored as one inert, versioned JSON object shared by all editors of an app (`EditorSettings`); a simple editor installs no feature that reads the non-core parts.

`core` is configurable (`CoreContentOptions`: `headings` or heading `levels`, `lists`, `blockquote`, `codeBlock`, `rule`): `coreContentFeature(options)` and `composeEditor({ coreContent })` take it, and the schema-extension list the server derives from the preset follows, so editor and server schema cannot drift. Bundle isolation is unaffected: the options only change which StarterKit extensions are configured.


# Renderer port

> The Renderer, RenderTargetInfo and RenderInput types, the render routes and events, and the createRenderer and markdownTarget adapter.

The server types come from `packages/editor/src/server/ports.ts` (`@skaile/forge-editor/server`), the wire types from `packages/editor/src/core/backend-types.ts` (`@skaile/forge-editor/core`), the adapter from `@skaile/forge-editor/adapters/render`. For how to add a target and what the editor shows, see [Render](https://skaile-ai.github.io/forge-editor/guides/render).

## `Renderer`

`EditorPorts.render` (capability `render`). The result is stored through `EditorPorts.assets`; without it `POST /api/editor/render` answers `501`.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        targets
      </code>
    </td>
    
    <td>
      <code>
        (user: object) => Promise<RenderTargetInfo[]>
      </code>
    </td>
    
    <td>
      The targets this user may use.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        render
      </code>
    </td>
    
    <td>
      <code>
        (target, input, user, progress, signal) => Promise<{ data: Uint8Array, mime: string, fileName: string }>
      </code>
    </td>
    
    <td>
      Renders <code>
        input
      </code>
      
       to <code>
        target
      </code>
      
      . <code>
        progress
      </code>
      
       is a <code>
        RenderProgressReporter
      </code>
      
       (<code>
        (p: RenderProgress) => void
      </code>
      
      ); <code>
        signal
      </code>
      
       aborts when the client goes away. Throw to fail the render: the message reaches the client.
    </td>
  </tr>
</tbody>
</table>

## `RenderTargetInfo`

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Unique among the targets of one renderer.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Already in the user's language.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        accepts
      </code>
    </td>
    
    <td>
      <code>
        readonly string[]
      </code>
    </td>
    
    <td>
      Block type ids, or <code>
        'document'
      </code>
      
       for a whole Document.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mime
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      MIME type of the result.
    </td>
  </tr>
</tbody>
</table>

## `RenderInput`

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        documentId
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The Document the result is stored under.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockId
      </code>
    </td>
    
    <td>
      <code>
        string?
      </code>
    </td>
    
    <td>
      Set for a Block; absent for the whole Document.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        content
      </code>
    </td>
    
    <td>
      <code>
        JSONContent
      </code>
    </td>
    
    <td>
      The Block's TipTap JSON, or the whole Document without <code>
        blockId
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <code>
        Record<string, unknown>?
      </code>
    </td>
    
    <td>
      Target specific options.
    </td>
  </tr>
</tbody>
</table>

## Routes

<table>
<thead>
  <tr>
    <th>
      Route (<code>
        API
      </code>
      
       key)
    </th>
    
    <th>
      Request
    </th>
    
    <th>
      Answer
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/editor/render/targets
      </code>
      
       (<code>
        renderTargets
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      <code>
        RenderTargetInfo[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/render
      </code>
      
       (<code>
        renderPost
      </code>
      
      )
    </td>
    
    <td>
      <code>
        { target: string, input: RenderInput }
      </code>
    </td>
    
    <td>
      SSE: <code>
        progress
      </code>
      
       <code>
        { phase: string, percent?: number }
      </code>
      
      , then <code>
        done
      </code>
      
       <code>
        { asset: string, fileName: string, mime: string }
      </code>
      
       or <code>
        error
      </code>
      
       <code>
        { message: string }
      </code>
    </td>
  </tr>
</tbody>
</table>

Both routes are served only when `ports.render` is present. Refusals before the stream starts: `400`, `401`, `403`, `404` (unknown target), `422` (the target does not accept the Block type), `501` (no `assets` port).

## `EditorBackend['render']`

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        targets
      </code>
    </td>
    
    <td>
      <code>
        (signal?) => Promise<RenderTargetInfo[]>
      </code>
    </td>
    
    <td>
      The targets of the user.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        render
      </code>
    </td>
    
    <td>
      <code>
        (target, input, { onProgress?, signal? }?) => Promise<RenderResult>
      </code>
    </td>
    
    <td>
      Streams one render. <code>
        RenderResult
      </code>
      
       is <code>
        RenderDone
      </code>
      
       (<code>
        asset
      </code>
      
      , <code>
        fileName
      </code>
      
      , <code>
        mime
      </code>
      
      ) plus <code>
        url
      </code>
      
       of the stored asset. Rejects with the server's message when the render fails.
    </td>
  </tr>
</tbody>
</table>

## `@skaile/forge-editor/adapters/render`

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        createRenderer(targets)
      </code>
    </td>
    
    <td>
      A <code>
        Renderer
      </code>
      
       over a list of <code>
        RenderTarget
      </code>
      
      s. A repeated <code>
        id
      </code>
      
       keeps the first; <code>
        render
      </code>
      
       rejects with <code>
        404
      </code>
      
       for an unknown id.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        RenderTarget
      </code>
    </td>
    
    <td>
      <code>
        RenderTargetInfo
      </code>
      
       plus <code>
        run(input, progress, signal)
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        markdownTarget(options?)
      </code>
    </td>
    
    <td>
      The built-in target <code>
        markdown
      </code>
      
       (<code>
        text/markdown
      </code>
      
      ); options <code>
        schema
      </code>
      
      , <code>
        blockTypes
      </code>
      
      , <code>
        label
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>


# Speech port

> The SpeechProvider, SpeechEngineInfo and SpeechRequest types, the speech routes and events, the daily budget, and the createOpenAiSpeech and createMemorySpeech adapters.

The server types come from `packages/editor/src/server/ports.ts` (`@skaile/forge-editor/server`), the wire types from `packages/editor/src/core/backend-types.ts` (`@skaile/forge-editor/core`), the adapters from `@skaile/forge-editor/adapters/speech`. For how to provide a port and what the editor shows, see [Speech](https://skaile-ai.github.io/forge-editor/guides/speech).

## `SpeechProvider`

`EditorPorts.speech` (capability `speech`). The audio is stored through `EditorPorts.assets`; without it `POST /api/editor/speech` answers `501`.

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        engines
      </code>
    </td>
    
    <td>
      <code>
        (user: object) => Promise<SpeechEngineInfo[]>
      </code>
    </td>
    
    <td>
      The engines this user may use, each with its voices.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        synthesize
      </code>
    </td>
    
    <td>
      <code>
        (request: SpeechRequest, user: object, signal: AbortSignal) => Promise<{ data: Uint8Array, mime: string }>
      </code>
    </td>
    
    <td>
      Reads <code>
        request.text
      </code>
      
       with <code>
        request.voice
      </code>
      
       of <code>
        request.engine
      </code>
      
      . <code>
        signal
      </code>
      
       aborts when the client goes away. Throw to fail the synthesis: the message reaches the client. Throw <code>
        HttpError
      </code>
      
       <code>
        404
      </code>
      
       for an unknown engine or voice.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcribe
      </code>
    </td>
    
    <td>
      <code>
        (audio: Uint8Array, mime: string, user: object) => Promise<{ segments: SpeechSegment[] }>
      </code>
    </td>
    
    <td>
      Optional. The timed text of <code>
        audio
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## Types

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Fields
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        SpeechEngineInfo
      </code>
    </td>
    
    <td>
      <code>
        id
      </code>
      
      , <code>
        label
      </code>
      
       (already in the user's language), <code>
        voices: SpeechVoice[]
      </code>
      
      , optional <code>
        formats
      </code>
      
       (the formats it makes; absent: <code>
        mp3
      </code>
      
       and <code>
        wav
      </code>
      
      ; <code>
        createMemorySpeech
      </code>
      
       lists <code>
        wav
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SpeechVoice
      </code>
    </td>
    
    <td>
      <code>
        id
      </code>
      
      , <code>
        label
      </code>
      
      , <code>
        lang
      </code>
      
       (BCP 47, <code>
        und
      </code>
      
       for any language)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SpeechRequest
      </code>
    </td>
    
    <td>
      <code>
        engine
      </code>
      
      , <code>
        voice
      </code>
      
      , <code>
        text
      </code>
      
      , <code>
        format: SpeechFormat
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SpeechFormat
      </code>
    </td>
    
    <td>
      <code>
        'mp3' | 'wav'
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SpeechBody
      </code>
    </td>
    
    <td>
      <code>
        SpeechRequest
      </code>
      
       plus <code>
        documentId
      </code>
      
      , the Document the audio is stored under
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        SpeechSegment
      </code>
    </td>
    
    <td>
      <code>
        start
      </code>
      
      , <code>
        end
      </code>
      
       (seconds into the audio), <code>
        text
      </code>
    </td>
  </tr>
</tbody>
</table>

## Routes

<table>
<thead>
  <tr>
    <th>
      Route (<code>
        API
      </code>
      
       key)
    </th>
    
    <th>
      Request
    </th>
    
    <th>
      Answer
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/editor/speech/engines
      </code>
      
       (<code>
        speechEngines
      </code>
      
      )
    </td>
    
    <td>
      none
    </td>
    
    <td>
      <code>
        SpeechEngineInfo[]
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/editor/speech
      </code>
      
       (<code>
        speechSynthesize
      </code>
      
      )
    </td>
    
    <td>
      <code>
        SpeechBody
      </code>
    </td>
    
    <td>
      SSE: <code>
        progress
      </code>
      
       <code>
        { phase: string, percent?: number }
      </code>
      
      , then <code>
        done
      </code>
      
       <code>
        { asset: string, fileName: string, mime: string }
      </code>
      
       or <code>
        error
      </code>
      
       <code>
        { message: string }
      </code>
    </td>
  </tr>
</tbody>
</table>

Both routes are served only when `ports.speech` is present. Refusals before the stream starts: `400`, `401`, `403`, `404` (unknown engine or voice), `429` (daily budget, with `Retry-After` in seconds), `501` (no `assets` port).

## Daily budget

<table>
<thead>
  <tr>
    <th>
      Export (<code>
        @skaile/forge-editor/server
      </code>
      
      )
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        SPEECH_CHARS_PER_DAY
      </code>
    </td>
    
    <td>
      <code>
        50_000
      </code>
      
      , the characters one user may synthesize per UTC day.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createSpeechBudget({ limit?, now? })
      </code>
    </td>
    
    <td>
      A <code>
        SpeechBudget
      </code>
      
       held in memory. <code>
        charge(key, chars)
      </code>
      
       returns <code>
        0
      </code>
      
       when the characters fit, else the seconds until UTC midnight (at least 1) and counts nothing. <code>
        refund(key, chars)
      </code>
      
       gives characters back after a failed synthesis.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        HandlerContext.speechBudget
      </code>
    </td>
    
    <td>
      The budget the speech handler uses. Without it one budget per <code>
        ports
      </code>
      
       object applies, with the default limit.
    </td>
  </tr>
</tbody>
</table>

## `EditorBackend['speech']`

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        engines
      </code>
    </td>
    
    <td>
      <code>
        (signal?) => Promise<SpeechEngineInfo[]>
      </code>
    </td>
    
    <td>
      The engines and voices of the user.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        synthesize
      </code>
    </td>
    
    <td>
      <code>
        (request: SpeechBody, { onProgress?, signal? }?) => Promise<RenderResult>
      </code>
    </td>
    
    <td>
      Streams one synthesis; <code>
        RenderResult
      </code>
      
       is <code>
        RenderDone
      </code>
      
       (<code>
        asset
      </code>
      
      , <code>
        fileName
      </code>
      
      , <code>
        mime
      </code>
      
      ) plus the <code>
        url
      </code>
      
       of the stored asset. Rejects with the server's message when it fails.
    </td>
  </tr>
</tbody>
</table>

## `@skaile/forge-editor/adapters/speech`

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        createOpenAiSpeech(options)
      </code>
    </td>
    
    <td>
      A <code>
        SpeechProvider
      </code>
      
       over <code>
        POST <endpoint>/audio/speech
      </code>
      
      . Options <code>
        endpoint
      </code>
      
      , <code>
        model
      </code>
      
      , <code>
        apiKey?
      </code>
      
      , <code>
        id?
      </code>
      
       (default <code>
        openai
      </code>
      
      ), <code>
        label?
      </code>
      
      , <code>
        voices?
      </code>
      
      , <code>
        fetch?
      </code>
      
      . An upstream error rejects with its status and the first 300 characters of its body.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OPENAI_VOICES
      </code>
    </td>
    
    <td>
      The voices of OpenAI's speech models.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        createMemorySpeech(options?)
      </code>
    </td>
    
    <td>
      A <code>
        SpeechProvider
      </code>
      
       that answers one second of silence as WAV; option <code>
        engines
      </code>
      
      . Default engine <code>
        memory
      </code>
      
      , voice <code>
        silent
      </code>
      
      . <code>
        mp3
      </code>
      
       is refused with <code>
        422
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        silentWav(seconds?)
      </code>
    </td>
    
    <td>
      The silent mono 16-bit WAV (8 kHz) as <code>
        Uint8Array
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## Subtitle export (`@skaile/forge-editor/transcript`)

<table>
<thead>
  <tr>
    <th>
      Export
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        vttOf(cues)
      </code>
    </td>
    
    <td>
      WebVTT text of <code>
        TranscriptCue[]
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        srtOf(cues)
      </code>
    </td>
    
    <td>
      SubRip text of <code>
        TranscriptCue[]
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        transcriptCuesOf(node)
      </code>
    </td>
    
    <td>
      The <code>
        TranscriptCue[]
      </code>
      
       of the timed <code>
        transcriptSegment
      </code>
      
      s in a node.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        TranscriptCue
      </code>
    </td>
    
    <td>
      <code>
        { start, end, text, speaker? }
      </code>
      
      , seconds. A <code>
        SpeechSegment
      </code>
      
       fits.
    </td>
  </tr>
</tbody>
</table>


# Chapter 7: AI

> Add aiFeature() to the meeting-notes editor, provide the /api/ai endpoints and keys, and describe the callout to the model with aiContext.

The meeting-notes editor can summarise, rewrite and extend text, and a sidebar can chat with the document and propose edits. All of it is one feature, `aiFeature()`. This chapter adds it, shows what the server side needs, and then does the one thing only you can do: tell the model that a „Callout“ block exists and how to write it.

This chapter has no live demo, because the model calls need a server and a provider key. Run the repository's Nuxt app (`bun run dev`, port 3056) with a key in `.env` and open `/kitchen-sink/surface` (the callout feature with the AI sidebar) or `/kitchen-sink/simple` (`SimpleEditor` with `aiFeature()`) to try it.

## Add the feature

`aiFeature()` adds a selection menu (rewrite tasks such as shorter, formal or translate, plus free prompts), the `/ai` command and a „KI“ toolbar group, in-document review of rewrites (accept or reject per change), ghost autocomplete while typing (Tab accepts, Esc dismisses), model profiles and the `ai` settings tab. The sidebar (document chat and block generation) and the quick model switch are components you place yourself; the sidebar comes from `@skaile/forge-editor/ai/vue/chat` and needs the optional peer `@skaile/forge-chat`. It needs no Typed blocks, transcript, media, mentions or Yjs; `bun run check:editor-entries` proves it with a `core + ai` fixture.

```vue
<script setup lang="ts">
import { aiFeature } from '@skaile/forge-editor/ai/vue'
import { AiSidebar } from '@skaile/forge-editor/ai/vue/chat'
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { EditorSurface, EditorToolbar } from '@skaile/forge-editor/vue'
import type { Editor } from '@tiptap/vue-3'
import { shallowRef } from 'vue'

const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature(), aiFeature()] })
const editor = shallowRef<Editor>()
const sidebarOpen = shallowRef(false)
</script>

<template>
  <EditorToolbar :editor="editor" />
  <div class="flex">
    <EditorSurface v-model="content" v-model:sidebar-open="sidebarOpen" :preset="preset" class="flex-1" @ready="editor = $event" />
    <AiSidebar v-model:open="sidebarOpen" :editor="editor" class="w-[380px]" />
  </div>
</template>
```

`aiFeature()` needs no component setup: the model profiles come from the app's editor context, and its notices (rate limits, import problems) go to the surface's notifier. Import `@skaile/forge-editor/styles/ai.css` after `core.css`. The Vue sidebar renders on `@skaile/forge-chat` (its `ChatPanel`), an optional peer of the editor package: install it, import `@skaile/forge-chat/styles/chat.css` and add `@source "…/node_modules/@skaile/forge-chat/dist";` next to the one for the library; a Nuxt host also lists `'@skaile/forge-chat/nuxt'` after `'@nuxt/ui'` in `modules`. The `AdvancedEditor` of chapter 6 already contains the feature (`ai: true`); `SimpleEditor` takes it through its `add` prop.

## The server side

The feature talks to its endpoints through the backend's `ai` port. The Nuxt module mounts the routes for you; with another transport you provide them yourself. The handlers in [`packages/editor/src/server/handlers/ai.ts`](https://github.com/skaile-ai/forge-editor/blob/main/packages/editor/src/server/handlers/ai.ts) are the reference implementation.

<table>
<thead>
  <tr>
    <th>
      Endpoint
    </th>
    
    <th>
      Purpose
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        GET /api/ai/models
      </code>
    </td>
    
    <td>
      <code>
        { presets: ModelProfile[], roles: Record<ModelRole, string> }
      </code>
      
      : the server Model presets as Model profiles (no keys) and the default Model preset per Model role (<code>
        complete
      </code>
      
      , <code>
        rewrite
      </code>
      
      , <code>
        generate
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/ai/generate
      </code>
    </td>
    
    <td>
      SSE (<code>
        delta
      </code>
      
      , <code>
        done
      </code>
      
      , <code>
        error
      </code>
      
      ) for selection tasks and block generation
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/ai/chat
      </code>
    </td>
    
    <td>
      SSE for the sidebar's document chat with edit operations
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        POST /api/ai/complete
      </code>
    </td>
    
    <td>
      <code>
        { text }
      </code>
      
       continuation for ghost autocomplete
    </td>
  </tr>
</tbody>
</table>

API keys never reach the client. In Nuxt the module's `tiptapEditor.ai` options (Model presets, default Model preset per Model role, rate limit) and these environment variables supply the server side:

- `NUXT_TIPTAP_EDITOR_AI_API_KEY`: the shared fallback key for every preset.
- `NUXT_TIPTAP_EDITOR_AI_PRESETS_<ID>_API_KEY`: the key of one preset (`flashLite` becomes `NUXT_TIPTAP_EDITOR_AI_PRESETS_FLASH_LITE_API_KEY`).
- `NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY`: a Deepgram key; the repository's config enables transcription only when it is set.

Public AI configuration is inert data passed to `createEditor`, for example `createEditor({ ai: { roles: { complete: 'flashLite', rewrite: 'sonnet', generate: 'sonnet' }, transcription: false } })`: the default Model preset per Model role until the user picks one in the `ai` settings tab. The full description is in [AI configuration](https://skaile-ai.github.io/forge-editor/guides/ai-configuration) and [AI](https://skaile-ai.github.io/forge-editor/guides/ai).

## Teach the model about the callout

Without help the model sees a flat document with no custom Block types. Features adjust that through the `aiContext` hook, and a block feature uses its `blocks` list. First what the model **sees** and what it **can write**:

- **What the model sees.** `editor.getMarkdown()` and every `editor.markdown.serialize(…)` (selection text, document context, summaries) use your `renderMarkdown` from chapter 4. The chat's document view lists *text blocks* as `[<block id>] <Markdown>` lines. A wrapper block like the callout appears as a header line with the block's own ID and its Markdown opener, `[<id>] !!! info`; its body blocks follow two spaces further in, each with its own ID. This is why `editorBlock: true` matters: the model can address, update, delete, extend or convert a block by that ID.
- **What the model can write.** AI results are parsed by the block pipeline (`parseBlocks`), so Markdown in your syntax becomes your node. The model knows the syntax only if you describe it in `aiContext.blocks`; the library does not guess it from `renderMarkdown`.

The callout contributes its description like this:

```ts [app/editor/callout/feature.ts]
aiContext: () => ({
      blocks: [{
        id: 'callout',
        label: 'Callout',
        description: 'A colour-highlighted box for a note (info), a warning (warning) or something completed (success). Holds paragraphs, lists or quotes, no headings.',
        syntax: '!!! <info|warning|success>\n<content, blocks separated by a line break; a blank line ends the callout>',
        example: '!!! warning\nPlease check the figures before sending.',
      }],
    }),
```

Each `AiBlock` (a type exported from `@skaile/forge-editor/core`) describes one host block:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        id
      </code>
    </td>
    
    <td>
      The node type name (<code>
        callout
      </code>
      
      ); doubles as the <code>
        convert
      </code>
      
       target id
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      The block's name in the document's language
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        description
      </code>
    </td>
    
    <td>
      One or two sentences on its purpose and allowed content
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        syntax
      </code>
    </td>
    
    <td>
      The Markdown form with placeholders in angle brackets
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        example
      </code>
    </td>
    
    <td>
      One complete Markdown example
    </td>
  </tr>
</tbody>
</table>

What happens with it:

- **aiContext is additive.** Any number of features may contribute. `defineEditor` merges the contributions: `blockTypes` and `blocks` concatenate in feature order, and `structure` (the Structure mode: `'flat'` or `'structured'`) may come from one feature only. A block `id` described twice, or two features that set `structure`, is reported when the merged context is first read (`aiContextOf(editor)`), not when you call `defineEditor`.
- **The prompts.** The chat lists the blocks in its system prompt and sends them with each request; the generate tasks (sidebar and selection menu) list them too. A result may then contain the block in your syntax, and the block pipeline turns it into your node. `syntax` and `example` must match `renderMarkdown` and the tokenizer, or the result will not parse back into the node.
- **convert targets.** The chat sends the model its list of `convert` targets: the core ids, the Block types of `aiContext.blockTypes`, and each `blocks` entry whose id a registered conversion provider parses. The callout's `conversions` from chapter 5 do, so „Umwandeln in Callout“ is also an agent operation. A block without such a provider is not a `convert` target, but the model may still `add` or `update` it through Markdown in its syntax.

### `aiBlockData`

A second hook, `aiBlockData: ({ editor, node, pos, signal }) => AiBlockDatum[] | Promise<AiBlockDatum[]>`, supplies material for one Typed block (examples, a record) before „Block füllen (KI)“ asks the model. All contributions run in parallel and concatenate in feature order. The library only collects and caps the entries; the fetch belongs to your feature, and `signal` aborts it with the editor. The callout does not need it; the repository's Epikrise host feature (`app/editor/epikrise/feature.ts`, on `/kitchen-sink/epikrise`) shows one that does.

## What an agent edit does

The model proposes changes to the document through the `edit_document` tool. The server checks them (`checkAgentOps`, from `@skaile/forge-editor/ai/protocol`) and streams the valid ones; the client shows each as an in-document review change the user accepts or rejects. There are four operation types (`AGENT_OP_TYPES`):

<table>
<thead>
  <tr>
    <th>
      Type
    </th>
    
    <th>
      Effect
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        add
      </code>
    </td>
    
    <td>
      Insert block(s) after a block ID; <code>
        afterId: null
      </code>
      
       is the document start. For the callout, <code>
        add
      </code>
      
       after a body block inserts <em>
        inside
      </em>
      
       the callout.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        update
      </code>
    </td>
    
    <td>
      Replace block <code>
        id
      </code>
      
      ; a single paragraph is diffed within the block.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        delete
      </code>
    </td>
    
    <td>
      Remove the block.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        convert
      </code>
    </td>
    
    <td>
      Change the block type, keeping the content; <code>
        to
      </code>
      
       must be one of the request's targets.
    </td>
  </tr>
</tbody>
</table>

So after this chapter the model can write `!!! warning` blocks into your notes, change an existing hint's text through its ID, or convert a paragraph into a callout. Invalid operations are dropped with a reason (`unknown`, `scope`, `field`, `duplicate`, `limit`, `target`, `inside`) and the outcome of every operation is fed back to the model with the next message. The complete tables, limits and the Typed block Markdown fence format are in [AI](https://skaile-ai.github.io/forge-editor/guides/ai).

## What you have now

An editor with AI on every level: selection rewrites, ghost autocomplete, a chat sidebar with reviewable edit operations, and a model that knows the „Callout“ block exists, how to write it, and that it can convert into it.

## Next

[Chapter 8: The React surface](https://skaile-ai.github.io/forge-editor/tutorial/react-surface) shows the same editor on React.


# Chapter 6: Backend and collaboration

> Register the Nuxt module, hand it EditorPorts for identity and storage, and open one document in two browsers with the collaboration session.

Until now the editor kept its data in the page. Meeting notes belong to a team, so this chapter moves them behind a server and lets several people edit one document. Two pieces cooperate: the **Nuxt module** (routes, Hocuspocus websocket server, rate limiting) and the **EditorPorts** you give it (who the user is, where documents live). On the client, collaboration is a feature, not a mode.

This chapter has no live demo: it needs a server. The repository's Nuxt app is the runnable reference. Start it with `bun run dev` (port 3056); it needs `NUXT_SESSION_PASSWORD` (at least 32 characters, for the session cookie) in `.env`. The app has no login: a visitor acts as one of the demo users `anna`, `ben` and `bernd` and switches in the user menu top right. Open `/kitchen-sink/advanced` for the advanced editor on a sample document:

![The advanced editor of the repository's Nuxt app: toolbar, Block outline groups, Typed blocks and the JSON and Markdown panes](https://skaile-ai.github.io/forge-editor/img/tutorial-advanced.png)

## Register the Nuxt module

The module goes into `nuxt.config.ts` after `@nuxt/ui`, because it patches Nuxt UI's generated stylesheet. The repository's own config registers it by path, so that editing the library needs no build step; in your app the entry is `@skaile/forge-editor/nuxt`:

```ts [nuxt.config.ts]
extends: ['nuxt-layer-annotation-inbox'],
  compatibilityDate: '2026-09-01',
  devtools: { enabled: true },
  devServer: { port: 3056 }, // assigned by dev-server skill (~/.skills/devskill/ports.tsv)
  ssr: false, // TipTap is client-only
  // Nuxt does not honour custom export conditions when it resolves a module name, so the source module is loaded by path.
  modules: ['@nuxt/ui', '@skaile/forge-chat/nuxt', 'nuxt-auth-utils', './packages/editor/src/nuxt/module.ts'],
  ui: { fonts: false },
  // `EDITOR_LOCALE=en` renders the editor chrome in English (default: German). Speech-to-text (“Create readable rendition” on
  // audio/video) runs on Deepgram only when `NUXT_TIPTAP_EDITOR_AI_TRANSCRIPTION_API_KEY` is set (the key itself is read at runtime).
```

The module registers one client plugin, which installs the editor context (`createEditor`) with account-synced settings and the public AI configuration; the context then talks to the module's HTTP routes. It auto-registers no component or composable: import everything from the package entries. [Nuxt module](https://skaile-ai.github.io/forge-editor/guides/nuxt-module) has the details, and [Quick start: Nuxt](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-nuxt) has the full setup including the minimal in-memory ports.

## Give it `EditorPorts`

The package owns the routes, the websocket server, rate limiting and the wire formats. **You own identity** (sessions, sign-in, which user may open which document) **and storage** (where documents, Yjs state, assets, settings and themes live). Both enter through one object, `EditorPorts`, which you provide in a Nitro plugin with `provideEditorServer({ ports })`. The package never reads cookies or touches files itself: `authenticate` returns the user or `null`, and the storage methods persist what they are given. The repository's plugin wires the ports to session cookies and the file system:

```ts [server/plugins/editor-adapter.ts]
import type { User } from '#auth-utils'
import { createJsonAdapter } from '@skaile/forge-editor/adapters/json'
import { provideEditorServer } from '@skaile/forge-editor/server/nitro'
import { createWorkspaceTools } from '@skaile/forge-editor/server'

// Connects the editor package's Nuxt integration to this app's sessions, JSON document store and per-user settings.
// Synchronous on purpose: Nitro does not await a plugin, so registering after an `await` would leave the first requests without an editor server.
export default defineNitroPlugin(() => {
  // The add-ons' ports (render targets, speech, knowledge graph) and Block types; each add-on is on behind its flag, `runtimeConfig.public.addons.<name>` (`server/utils/addons.ts`).
  const addons = createAddonServer({ storeAsset, loadAsset }, addonFlagsOf(useRuntimeConfig().public.addons))
  provideEditorServer({
    ports: {
      identity: {
        // Without a session cookie h3 throws ("Cannot initialize a new session") outside a main handler.
        authenticate: request => getUserSession({ headers: request.headers, context: {} }).then(s => s.user ?? null, () => null),
      },
      documents: {
        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() })
        },
        listContents: async () => (await listAllDocuments()).map(({ id, content }) => ({ id, content })),
        // Document management over the package store: folders, create, move, delete (`/api/editor/{documents,tree}`).
        listDocumentIds: async () => indexedIds(),
        listTree,
        async createDocument(input) {
          const { id, title, updatedAt } = await createDocument(input)
          return { id, title, updatedAt, folder: input.folder ?? '' }
        },
        moveDocument,
        deleteDocument: removeDocument,
      },
      directory: { listUsers: async () => (await listUsers()).map(toSessionUser) },
      collabState: { loadState, storeState, removeState },
      assets: { storeAsset, loadAsset },
      // `user` is what `authenticate` returned: the session user.
      settings: {
        loadSettings: user => getUserSettings((user as User).id),
        storeSettings: (user, settings) => putUserSettings((user as User).id, settings),
      },
      themes: { listThemes, loadTheme, storeTheme, removeTheme },
      // Block index (`index` capability): a projection of the documents above, rebuilt on start and kept current by the editor server; in memory (memory adapter, PGlite with `NUXT_BLOCK_INDEX=pglite`, or PGlite with trigram search and vectors with `NUXT_BLOCK_INDEX=pg-vector`), so nothing to migrate.
      index: createHostBlockIndex(addons.ports.embeddings, addons.embeddingsError),
      // Prüfung records (`pruefung` capability): the editor's JSON store on `<documents dir>/.pruefung.json`, a dot-named file the document store never lists.
      pruefung: createJsonAdapter({ dir: storeRoot() }).pruefung,
      // Change sets of the document chat (`changeSets` capability): what the model proposed for other Documents, decided per Document; `<documents dir>/.change-sets.json`, likewise dot-named.
      changeSets: createJsonAdapter({ dir: storeRoot() }).changeSets,
      // Demo of the model port (`DEMO_STUB_MODEL=1`): the stub answers `{ preset: 'stub' }`; `null` for anything else falls through to the environment presets.
      models: {
        languageModel: async ref => stubModelEnabled() && 'preset' in ref && ref.preset === STUB_MODEL_ID ? stubLanguageModel : null,
        listModels: async () => stubModelEnabled() ? [...publicEnvPresets(), stubModelProfile] : null,
      },
      ...addons.ports,
    },
    ...(addons.blockTypes && { blockTypes: addons.blockTypes }),
    // The document chat's read-only workspace tools (`find_blocks`, `read_block`): the model finds and reads Blocks of the user's other Documents through the block index above.
    tools: createWorkspaceTools(addons.blockTypes && { blockTypes: addons.blockTypes }),
  })
})
```

You implement only the ports your product needs. A route whose port you did not register is not mounted (the path answers 404), and the client's probe omits the features that depend on it. [EditorPorts](https://skaile-ai.github.io/forge-editor/guides/editor-ports) lists every port, [Routes and auth](https://skaile-ai.github.io/forge-editor/guides/routes-and-auth) the routes and how each authenticates, and [Storage adapters](https://skaile-ai.github.io/forge-editor/guides/storage-adapters) the ready-made bundles (`createJsonAdapter`, `createDrizzleAdapter`, `createForgeAdapter`) that save you from writing `documents` yourself.

## Open a collaborative document

The preset contains `collabFeature()`, and the surface gets a session through the `collaboration` prop: a Yjs document, a Hocuspocus provider and the current user. The Yjs document **is** the document, so there is no `v-model`. The repository's document page creates the session once per document:

```vue [app/pages/documents/[id].vue]
const commentsOpen = useState('tiptap-editor-comments', () => false)
// The editor's scroll container: CommentsMargin aligns its cards with the commented text inside it.
const scrollEl = useTemplateRef<HTMLElement>('scrollEl')

// Demo of the opt-in `pruefung` feature: the built-in Block types plus „Prüfabschnitt“ (`shared/utils/host-block-types.ts`); the user
// holds `pruefung.record` (not part of ROOT_ABILITIES).
// The optional add-ons (flags `runtimeConfig.public.addons`, `app/editor/addons.ts`) add their Block types (slides, quotes) and features, loaded here
// before the editor mounts and only for the flags that are on; Explore is always on.
const { t, locale } = useEditorI18n()
const exploreTarget = useExploreTarget()
// Choosing a Block in the Explore panel opens it like an embed's source; „Verknüpfungen anzeigen“ shows the panel in the sidebar.
const addons = await loadAddons({
  addons: addonFlagsOf(useRuntimeConfig().public.addons),
```

and hands it to `AdvancedEditor`, the ready-made composition of every catalog feature (media, transcript, Typed blocks, mentions, authors, comments, collab, block UI, themes and, optionally, AI):

```vue [app/pages/documents/[id].vue]
>
                {{ titleError }}
              </p>
            </div>
            <AdvancedEditor
              v-model:sidebar-open="sidebarOpen"
              v-model:comments-open="commentsOpen"
              :document-id="id"
              :collaboration="{ ydoc, provider, user: { id: user.id, name: user.username, color: user.color } }"
              :block-types="blockTypes"
```

With your own preset the same wiring reads `<EditorSurface :preset="preset" :collaboration="{ ydoc, provider, user }" />` over a `defineEditor` list that contains `collabFeature()` (from `@skaile/forge-editor/collab/vue`). What to know about the session:

- **Undo is per client.** Core turns its own undo history off; the Collaboration extension brings a per-client undo and redo (`Mod-z`, `Mod-y`, `Shift-Mod-z`), so undo never reverts another user's edits.
- **Carets.** `provider` adds remote carets labelled with `user`; without a provider the Yjs document is edited locally only. `user` is an `AuthorIdentity` (`{ id, name, color }`, your stable user id). The optional `authors` and `comments` features attribute text and comments to it.
- **Fixed at mount.** Remount with a new `key` when the document changes, so Yjs document, provider and editor never bleed between documents.
- **Setup errors.** Supplying `collaboration` to a preset without `collabFeature()` throws „`collaboration` needs a preset with the collaboration feature“. Without a `collaboration` prop the feature adds no extension and the editor behaves like a standalone one with a JSON `v-model`.
- **CSS.** Include `@skaile/forge-editor/styles/collab.css` (the Nuxt module adds it) for the caret styles.

To try it: open the same document URL in a second browser tab, or as another user in a private window (switch to `ben` in the user menu). Text and carets appear in both within a moment, and the header badge reads „Synchronisiert“. [Collaboration](https://skaile-ai.github.io/forge-editor/guides/collaboration) covers authors, comments and positions that survive concurrent edits.

## Teach the server your block

A Yjs document is valid only if every participant knows the same schema. The standalone editors of chapters 4 and 5 use a JSON `v-model` and need nothing here. With a collaboration session the **server must know the callout, too**:

- The module's collab route builds its schema from the advanced entry plus the `schema` option you give the server: `provideEditorServer({ ports, schema: () => [...advancedSchemaExtensions(), Callout] })` (the option also exists on `createCollabServer` and `installEditorServer`; the default is `advancedSchemaExtensions()`). Without it, a document that contains a `callout` is outside what that route can load: seeding from JSON and the load-time block-ID backfill both go through a schema without the node.
- Pass the **Vue-free** node file, `Callout` from `callout/node.ts`, never `CalloutBlock`, so no Vue component loads on the server. This is why chapter 4 split the node into two files.
- A plain Vue or React app with **its own Hocuspocus server** builds the schema itself: `getSchema([...advancedSchemaExtensions(), Callout])`, with the same Collaboration `field` as the client (`default`).
- `editorBlock: true` works on the server too: `assignBlockIds` reads the flag from the schema, so the server backfills IDs for callouts exactly like for paragraphs.
- The client mounts a preset that contributes the same node: `advancedEditor().features` plus `calloutFeature()`, together with `collabFeature()`'s session, which `advancedEditor()` already has.

[Advanced schema](https://skaile-ai.github.io/forge-editor/reference/advanced-schema) shows the Vue-free schema entries, and [Production](https://skaile-ai.github.io/forge-editor/guides/production) the build and the process-wide registry.

## What you have now

A server side for the editor: the Nuxt module with ports for identity and storage, a collaboration session that two browsers share, and a callout the server can load. You also know where to look when a route is missing (the port is not registered) or a document will not load (the server schema lacks a node).

## Next

[Chapter 7: AI](https://skaile-ai.github.io/forge-editor/tutorial/ai) teaches the editor, and through `aiContext` the model, about callouts.


# Chapter 3: Compose features

> Replace SimpleEditor with EditorSurface over defineEditor and add mentions, media, tables and block UI as features.

`SimpleEditor` is a fixed composition. An editor is really a list of **features**, and `EditorSurface` mounts any list you build with `defineEditor`. In this chapter the meeting-notes editor gets people and tag mentions, image drop, tables and a drag handle by adding four entries to that list.

Try it. Type `@a` for people, `#i` for tags, `/` for the block menu, drop an image on the page, or insert a table from the toolbar:

<demo-composed-editor>



</demo-composed-editor>

## The preset

Each feature is one factory you import from its own entry, so a feature you do not import is not in your bundle. `defineEditor({ features })` keeps the given order: toolbar groups, menu entries and the schema follow it. The component of the demo above is the whole code:

```vue [docs/app/components/content/DemoComposedEditor.client.vue]
<script setup lang="ts">
import { coreContentFeature, coreUiFeature, defineEditor } from '@skaile/forge-editor/core'
import { blockUiFeature } from '@skaile/forge-editor/block-ui/vue'
import { mediaFeature } from '@skaile/forge-editor/media/vue'
import { mentionsFeature } from '@skaile/forge-editor/mentions'
import { tablesFeature } from '@skaile/forge-editor/tables'
import { EditorSurface, EditorToolbar } from '@skaile/forge-editor/vue'
import type { Editor, JSONContent } from '@tiptap/vue-3'
import { ref, shallowRef } from 'vue'

// An editor is the sum of its features. Mentions and tags come from the `backend` the app context carries.
const preset = defineEditor({
  features: [coreContentFeature(), coreUiFeature(), mentionsFeature(), mediaFeature(), tablesFeature(), blockUiFeature()],
})

const content = ref<JSONContent>({
  type: 'doc',
  content: [
    { type: 'heading', attrs: { level: 1 }, content: [{ type: 'text', text: 'Meeting notes' }] },
    {
      type: 'paragraph',
      content: [{ type: 'text', text: 'Type @ to mention a person, # to add a tag, / for the block menu, or drop an image.' }],
    },
  ],
})
const editor = shallowRef<Editor>()
</script>

<template>
  <!-- Global MDC components skip Nuxt's `.client` handling, so the page's server render would reach the editor: no UI kit there. -->
  <ClientOnly>
    <div class="not-prose my-6 flex flex-col gap-3">
      <EditorToolbar :editor="editor" />
      <div class="min-h-64 rounded-lg border border-default p-4">
        <EditorSurface v-model="content" :preset="preset" @ready="editor = $event" />
      </div>
    </div>
  </ClientOnly>
</template>
```

What each feature adds on top of `coreContentFeature()` (headings, lists, marks and so on) and `coreUiFeature()` (toolbar, `/` menu, command palette):

<table>
<thead>
  <tr>
    <th>
      Feature
    </th>
    
    <th>
      Entry
    </th>
    
    <th>
      What it adds
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        mentionsFeature()
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/mentions
      </code>
    </td>
    
    <td>
      <code>
        @username
      </code>
      
       and <code>
        #tag
      </code>
      
       chips with suggestion popups
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        mediaFeature()
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/media/vue
      </code>
    </td>
    
    <td>
      Image, audio, video and file blocks, drop and paste of files, toolbar buttons, the audio recorder
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tablesFeature()
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/tables
      </code>
    </td>
    
    <td>
      Tables with a toolbar group
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        blockUiFeature()
      </code>
    </td>
    
    <td>
      <code>
        @skaile/forge-editor/block-ui/vue
      </code>
    </td>
    
    <td>
      Drag handle, hover actions per block, block-range selection
    </td>
  </tr>
</tbody>
</table>

None of the four needs Typed blocks, AI or Yjs, and none imports the others: `bun run check:editor-entries` proves that per feature. The framework-free entries (`/mentions`, `/tables`, `/core`) work on both surfaces; the entries with a `/vue` suffix carry Vue components, and their React twins end in `/react` (chapter 8).

Two rules to remember:

- **The preset is read once.** Build it in `<script setup>` or at module level. To change the list, remount `EditorSurface` with a new `key`.
- **EditorSurface takes v-model, :preset, :editable, :metadata, :abilities, :extensions and :commands.** The last three are the props chapter 4 uses; `metadata` supplies the lists behind `@` and `#` when you do not want the context's backend to.

## Where the suggestions come from

The `@` and `#` popups search two named lists, `mentions` and `hashtags`. A list your app does not supply falls back to the feature's built-in source, which asks the context's backend: `users` for mentions, `tags` for hashtags. The memory backend of the example's `main.ts` (chapter 2) answers both from the data you gave it:

```ts [examples/vue-simple/src/main.ts]
// No data layer: documents, dropped files (as blob: URLs), mention users and tags, and settings live in the page.
const backend = createMemoryBackend({
  users: [
    { id: 'u1', username: 'Ada Lovelace', color: '#7c3aed' },
    { id: 'u2', username: 'Alan Turing', color: '#0ea5e9' },
    { id: 'u3', username: 'Grace Hopper', color: '#16a34a' },
  ],
  tags: ['idee', 'entwurf', 'wichtig'],
})

createApp(App)
  .use(ui)
  .use(createEditor({ kit: nuxtUiKit(), backend }))
```

An app without a backend can pass its own lists on the surface instead, and never calls those endpoints:

```vue
<EditorSurface
  :preset="preset"
  :metadata="{
    mentions: [{ id: 'u1', label: 'anna', color: '#e11d48' }],
    hashtags: q => searchTags(q.query),
  }"
  @metadata-create="(list, item) => persist(list, item)"
/>
```

Mentions are `@username` chips tinted with the item's `color` (a `#rgb` or `#rrggbb` value; anything else is dropped). Tags are `#tag` chips; the typed name is normalised (lower case, spaces become `-`, letters, digits, `-` and `_` only, at most 64 characters), and the popup offers „#name erstellen“ when it is not in the list. Picking that entry emits `metadataCreate('hashtags', { id, label })`.

## Images and files

`mediaFeature()` adds image, audio, video and file blocks, drop and paste of files, the toolbar buttons (Bild, Audio-Datei, Video, Aufnahme), the matching `/` commands and the audio recorder. Every path ends in one function, `editor.storage.media.upload(file)`, which calls the backend's `assets` capability. The memory backend answers with a `blob:` URL, so a dropped image shows up at once and disappears when the page reloads. To store files elsewhere, implement `assets.upload` in your own backend; the returned `url` becomes the block's `src`. Accepted types and sizes are in [Media, mentions and transcript](https://skaile-ai.github.io/forge-editor/guides/media-mentions-transcript). The transcript feature (speaker blocks) is described there as well; the meeting notes do not need it.

## The feature stylesheets

Features that draw their own UI ship a stylesheet. Import each one after Tailwind, Nuxt UI and `core.css`:

```css
@import "@skaile/forge-editor/styles/mentions.css";
@import "@skaile/forge-editor/styles/media.css";
@import "@skaile/forge-editor/styles/tables.css";
@import "@skaile/forge-editor/styles/block-ui.css";
```

[CSS and UI-provider requirements](https://skaile-ai.github.io/forge-editor/reference/css-and-ui) has the full list and the reason for the order.

## The shortcut: `composeEditor`

`defineEditor` is the explicit form. `composeEditor` from `@skaile/forge-editor/vue/advanced` builds the same kind of preset from three **dimensions**, the document model (`content`), the editing UX (`interaction`) and `ai`, each a named level or a list of feature ids:

```ts
import { composeEditor } from '@skaile/forge-editor/vue/advanced'

// core-content and core-ui plus mentions, media, tables and block UI, without AI.
const preset = composeEditor({ content: ['mentions', 'media', 'tables'], interaction: ['block-ui'], ai: false })
```

The result is a preset like the one from `defineEditor`, plus `omitted`, the features that were selected but dropped because a feature they `require` is missing or because the `backend` lacks a capability. `advancedEditor()` is the one-line wrapper for the full catalog. Prefer `defineEditor` while you learn what each feature does, and `composeEditor` when you want a level (`'rich'`, `'full'`) instead of a list. See [Feature composition](https://skaile-ai.github.io/forge-editor/guides/composition) for the levels.

## What you have now

An editor assembled from features: mentions and tags backed by a memory backend, image drop with `blob:` URLs, tables and a drag handle, mounted with `EditorSurface`. You also know the rule that makes this safe: a feature that is not in the list contributes nothing, neither code nor schema.

## Next

[Chapter 4: Your own block, path A](https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a) adds a block the library does not have.


# Tutorial: overview

> Build a meeting-notes editor in eight chapters: a simple editor, composed features, an own block, a backend with collaboration, AI, and the same editor on React.

This tutorial builds one editor for meeting notes. You start with the smallest working editor, add features one at a time, write your own block, connect it to a server, teach it to an AI model and finally see the same editor on React. Every chapter ends with a working result and one link to the next chapter.

The finished editor of chapters 1 to 5 runs below. Type `/callout` to add a callout, hover a callout block to change its tone, and open „Umwandeln in …“ on any paragraph.

<demo-callout-path-b>



</demo-callout-path-b>

## What you build

<table>
<thead>
  <tr>
    <th>
      Chapter
    </th>
    
    <th>
      You add
    </th>
    
    <th>
      Result
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/tutorial/simple-editor">
        2. A simple editor
      </a>
    </td>
    
    <td>
      <code>
        SimpleEditor
      </code>
      
      , <code>
        EditorToolbar
      </code>
      
      , <code>
        EditorOutline
      </code>
    </td>
    
    <td>
      Rich text, toolbar, outline, read-only switch
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/tutorial/compose-features">
        3. Compose features
      </a>
    </td>
    
    <td>
      <code>
        EditorSurface
      </code>
      
       over <code>
        defineEditor
      </code>
      
      , mentions, media, tables, block UI
    </td>
    
    <td>
      <code>
        @
      </code>
      
       and <code>
        #
      </code>
      
       suggestions, image drop, tables, drag handle
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/tutorial/own-block-path-a">
        4. Own block, path A
      </a>
    </td>
    
    <td>
      The „Hinweis“ node through the <code>
        extensions
      </code>
      
       and <code>
        commands
      </code>
      
       props
    </td>
    
    <td>
      A callout block with a <code>
        /hinweis
      </code>
      
       entry
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b">
        5. Own feature, path B
      </a>
    </td>
    
    <td>
      The callout as an <code>
        EditorFeature
      </code>
    </td>
    
    <td>
      Toolbar button, hover menu, „Umwandeln in …“
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/tutorial/backend-and-collaboration">
        6. Backend and collaboration
      </a>
    </td>
    
    <td>
      The Nuxt module, <code>
        EditorPorts
      </code>
      
      , a collaboration session
    </td>
    
    <td>
      Two browsers on one document
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/tutorial/ai">
        7. AI
      </a>
    </td>
    
    <td>
      <code>
        aiFeature()
      </code>
      
      , <code>
        aiContext
      </code>
    </td>
    
    <td>
      The model knows about callouts
    </td>
  </tr>
  
  <tr>
    <td>
      <a href="https://skaile-ai.github.io/forge-editor/tutorial/react-surface">
        8. The React surface
      </a>
    </td>
    
    <td>
      <code>
        EditorContextProvider
      </code>
      
      , <code>
        EditorSurface
      </code>
      
      , <code>
        SimpleEditor
      </code>
    </td>
    
    <td>
      The same editor on React
    </td>
  </tr>
</tbody>
</table>

The UI strings of the examples are German („Hinweis“, „Warnung“, „Erledigt“, „Umwandeln in …“), the code and this tutorial are English. Pass `createEditor({ locale: 'en' })` to switch the built-in strings of the library to English; the strings of your own block stay yours.

## Prerequisites

- Node 22 or newer and [Bun](https://bun.sh) (the commands below use `bun`; `npm` works the same).
- A Vite app with Vue 3. Nuxt UI's Vite plugin, `@nuxt/ui/vite`, provides the theme, icons and component imports; the editor's Vue layer uses Nuxt UI components. You do not need Nuxt for chapters 1 to 5.
- `@skaile/forge-editor` and its peers installed as described in [Installation](https://skaile-ai.github.io/forge-editor/getting-started/installation).

If you start from nothing, [Quick start: plain Vue](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-vue) lists the three small files (`package.json`, `index.html`, `tsconfig.json`) a new app needs. The Vite config of the runnable example, `examples/vue-simple`, is the one this tutorial builds on:

```ts [examples/vue-simple/vite.config.ts]
// Plain Vite + Vue (no Nuxt, router or backend). Nuxt UI's Vite plugin brings the theme, icons and component imports.
export default defineConfig({
  server: { port: 3040, strictPort: true },
  resolve: sourceResolve,
  plugins: [
    vue(),
    ui({ router: false, icon: { clientBundle: { scan: true, icons: [...libraryIcons] } } }),
  ],
})
```

Two parts of this file belong to the repository only. `sourceResolve` makes Vite read the library from `packages/editor/src` instead of a built package, and `libraryIcons` bundles the library's icons although the library lies outside the Vite root. In your own app the plugin list `[vue(), ui({ router: false })]` is enough; the icon bundling is optional and only avoids runtime requests to the Iconify API.

## Run the examples

Every chapter shows code from a real file of the repository, so you can run the same code:

```sh
bun install
bun run --cwd examples/vue-simple dev   # chapters 2 and 4, port 3040
bun run dev                             # chapters 5 to 7, port 3056 (the repository's Nuxt app)
```

## What you have now

A plan, and a place to run each step: the simple example app for the first chapters and the repository's Nuxt app for the advanced ones.

## Next

[Chapter 2: A simple editor](https://skaile-ai.github.io/forge-editor/tutorial/simple-editor).


# Chapter 4: Your own block, path A

> Write the „Hinweis“ callout as a TipTap node and plug it into SimpleEditor through the extensions and commands props.

Meeting notes need a block the library does not ship: a coloured box for a hint, a warning or a decision. In this chapter you write it as the **„Hinweis“ block** (`callout`, attribute `tone` = `info` | `warning` | `success`) and add it to the simple editor through two props. The chapter after this one turns the same node into a full feature.

The example exists twice on purpose, so each runnable app is self-contained; both copies are identical:

<table>
<thead>
  <tr>
    <th>
      Copy
    </th>
    
    <th>
      Files
    </th>
    
    <th>
      Used by
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Simple playground
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/tree/main/examples/vue-simple/src/callout" rel="nofollow">
        <code>
          examples/vue-simple/src/callout/
        </code>
      </a>
      
      : <code>
        node.ts
      </code>
      
      , <code>
        CalloutView.vue
      </code>
      
      , <code>
        index.ts
      </code>
      
      , <code>
        callout.css
      </code>
    </td>
    
    <td>
      Path A, wired in <a href="https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-simple/src/App.vue" rel="nofollow">
        <code>
          examples/vue-simple/src/App.vue
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      Advanced kitchen sink
    </td>
    
    <td>
      <a href="https://github.com/skaile-ai/forge-editor/tree/main/app/editor/callout" rel="nofollow">
        <code>
          app/editor/callout/
        </code>
      </a>
      
      : the same four files plus <code>
        feature.ts
      </code>
      
       and <code>
        convert.ts
      </code>
    </td>
    
    <td>
      Path B, chapter 5
    </td>
  </tr>
</tbody>
</table>

Start the simple playground with `bun run --cwd examples/vue-simple dev` (port 3040) and pick the sample „Hinweise“. The UI strings of the examples are German, the code and this guide are English.

## Two ways to add a block

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      Path A: props
    </th>
    
    <th>
      Path B: a feature
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      What you write
    </td>
    
    <td>
      A TipTap node, plus a <code>
        commands
      </code>
      
       transformer
    </td>
    
    <td>
      An <code>
        EditorFeature
      </code>
      
       (<code>
        id
      </code>
      
      , <code>
        extensions
      </code>
      
      , <code>
        commands
      </code>
      
      , <code>
        toolbarGroups
      </code>
      
      , <code>
        blockActions
      </code>
      
      , <code>
        conversions
      </code>
      
      , …)
    </td>
  </tr>
  
  <tr>
    <td>
      Where it plugs in
    </td>
    
    <td>
      The <code>
        extensions
      </code>
      
       and <code>
        commands
      </code>
      
       props of <code>
        SimpleEditor
      </code>
      
      , <code>
        AdvancedEditor
      </code>
      
       or <code>
        EditorSurface
      </code>
    </td>
    
    <td>
      A preset: <code>
        defineEditor({ features: [...] })
      </code>
      
       mounted with <code>
        EditorSurface
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      You get
    </td>
    
    <td>
      The node in the schema, its commands, input rules and shortcuts, its Markdown form, a <code>
        /
      </code>
      
       menu entry, block IDs when the node declares <code>
        editorBlock
      </code>
    </td>
    
    <td>
      Everything of path A, plus a toolbar button, ability-gated <code>
        /
      </code>
      
       entries, hover actions, „Umwandeln in …“ targets and a <code>
        requires
      </code>
      
       check of the features it builds on
    </td>
  </tr>
  
  <tr>
    <td>
      You do not get
    </td>
    
    <td>
      A toolbar button, hover actions, conversion targets: the toolbar renders what features contribute
    </td>
    
    <td>
      —
    </td>
  </tr>
</tbody>
</table>

Both paths share the same node. Start with path A; move to path B when the block needs a toolbar button, hover actions or conversion.

## Anatomy of a block the editor understands

### The node

`node.ts` is the complete, Vue-free definition: schema, commands, shortcut and Markdown form. It imports only `@tiptap/core` and the Vue-free `@skaile/forge-editor/core/schema`, so a server can import it without loading a component. Four things in order: the tones, the typed commands, the schema, the Markdown form.

The tones and their labels are plain data, shared with the node view:

```ts [examples/vue-simple/src/callout/node.ts]
import { mergeAttributes, Node } from '@tiptap/core'
import { ABILITY } from '@skaile/forge-editor/core/schema'

// Vue-free and server-importable: the callout's schema, commands and Markdown form. The Vue node view is attached in
// `index.ts`, so a server (`getSchema([...advancedSchemaExtensions(), Callout])`, or the simple schema) never loads a
// component.

export type Tone = 'info' | 'warning' | 'success'

export const TONES: readonly { value: Tone, label: string, icon: string }[] = [
  { value: 'info', label: 'Hinweis', icon: 'i-lucide-info' },
  { value: 'warning', label: 'Warnung', icon: 'i-lucide-triangle-alert' },
  { value: 'success', label: 'Erledigt', icon: 'i-lucide-circle-check' },
]
```

The commands are declared on TipTap's `Commands` interface so `editor.commands.setCallout()` is typed everywhere:

```ts [examples/vue-simple/src/callout/node.ts]
declare module '@tiptap/core' {
  interface Commands<ReturnType> {
    callout: {
      /** Wrap the selected blocks in a callout of `tone` (default `info`). */
      setCallout: (tone?: Tone) => ReturnType
      /** Wrap the selection in a callout, or lift it out when it already is inside one. */
      toggleCallout: () => ReturnType
      /** Change the tone of the callout around the selection. */
      setCalloutTone: (tone: Tone) => ReturnType
    }
  }
}
```

The schema part of the node. A callout holds one or more blocks (`content: 'block+'`), carries a `tone` attribute, and declares two fields the library reads: `editorBlock` and `abilities`:

```ts [examples/vue-simple/src/callout/node.ts]
export const Callout = Node.create({
  name: 'callout',
  group: 'block',
  content: 'block+',
  defining: true,
  // Carries a block ID like a paragraph: block flash/reveal, paste de-duplication, the server's ID backfill.
  editorBlock: true,
  // A callout holds plain text blocks: no headings, Typed blocks, media, records or speaker lines inside it.
  abilities: {
    revokes: [ABILITY.headings, ABILITY.composite, ABILITY.media, ABILITY.record, ABILITY.transcript],
  },
  addAttributes: () => ({
    tone: {
      default: 'info',
      parseHTML: el => el.getAttribute('data-tone') ?? 'info',
      renderHTML: attrs => ({ 'data-tone': attrs.tone }),
    },
  }),
  parseHTML: () => [{ tag: 'div[data-type="callout"]' }],
  renderHTML: ({ HTMLAttributes }) => ['div', mergeAttributes(HTMLAttributes, { 'data-type': 'callout' }), 0],
```

The Markdown form, in both directions. `@tiptap/markdown` reads these four fields; the AI and the Markdown export both depend on them (chapter 7):

```ts [examples/vue-simple/src/callout/node.ts]
// Markdown: `!!! <tone>` followed by the body up to the next blank line. `:::` belongs to Typed blocks. The body blocks
  // are joined by a single newline (without a separator `renderChildren` would glue them: „text- item“), so a body
  // with several paragraphs reads back as one; a blank line would end the callout for the tokenizer below.
  renderMarkdown: (node, h) => `!!! ${node.attrs?.tone ?? 'info'}\n${h.renderChildren(node.content ?? [], '\n')}`,
  markdownTokenName: 'callout',
  markdownTokenizer: {
    name: 'callout',
    level: 'block',
    start: src => src.indexOf('!!! '),
    tokenize(src, _tokens, lexer) {
      const match = /^!!! (info|warning|success)\n([\s\S]+?)(?:\n{2,}|$)/.exec(src)
      if (!match) return
      return { type: 'callout', raw: match[0], tone: match[1], tokens: lexer.blockTokens(match[2]!) }
    },
  },
  parseMarkdown: (token, h) => h.createNode('callout', { tone: typeof token.tone === 'string' ? token.tone : 'info' }, h.parseChildren(token.tokens ?? [])),
```

The commands and the keyboard shortcut close the node:

```ts [examples/vue-simple/src/callout/node.ts]
addCommands() {
    return {
      setCallout: tone => ({ commands }) => commands.wrapIn(this.name, { tone: tone ?? 'info' }),
      toggleCallout: () => ({ editor, commands }) =>
        editor.isActive(this.name) ? commands.lift(this.name) : commands.wrapIn(this.name, { tone: 'info' }),
      setCalloutTone: tone => ({ commands }) => commands.updateAttributes(this.name, { tone }),
    }
  },
  addKeyboardShortcuts() {
    // Mod-Alt-c is the code block; Mod-Shift-s / -m / -k belong to the transcript, mention and tag features.
    return { 'Mod-Shift-h': () => this.editor.commands.toggleCallout() }
  },
})
```

### Fields the library reads

Besides the plain TipTap fields (`name`, `group`, `content`, `defining`, `addAttributes`, `parseHTML` and `renderHTML`, commands, shortcuts) the package reads these `NodeConfig` fields:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Read by
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        editorBlock
      </code>
    </td>
    
    <td>
      <code>
        NodeFlags
      </code>
      
       (<a href="https://github.com/skaile-ai/forge-editor/blob/main/packages/editor/src/core/schema/node-flags.ts" rel="nofollow">
        <code>
          node-flags.ts
        </code>
      </a>
      
      ) and <code>
        BlockId
      </code>
      
       (<a href="https://github.com/skaile-ai/forge-editor/blob/main/packages/editor/src/core/schema/block-ids.ts" rel="nofollow">
        <code>
          block-ids.ts
        </code>
      </a>
      
      )
    </td>
    
    <td>
      The node is an addressable block: it gets the <code>
        id
      </code>
      
       attribute (rendered <code>
        data-id
      </code>
      
      ) the built-in blocks have. Block IDs are what block flash and reveal look up (<code>
        findBlockById
      </code>
      
      ), what paste de-duplication and the server's ID backfill (<code>
        assignBlockIds
      </code>
      
      ) iterate, and what the AI chat addresses: a text block with an ID is a <code>
        [<id>] …
      </code>
      
       line of the chat's document view and can be updated, deleted, extended or converted by that ID. <strong>
        Built-in block nodes default to <code>
          true
        </code>
      </strong>
      
       (<code>
        BLOCK_ID_TYPES
      </code>
      
      ); every other node defaults to <code>
        false
      </code>
      
       and then has no <code>
        id
      </code>
      
       attribute. <code>
        isEditorBlock(node)
      </code>
      
       (from <code>
        @skaile/forge-editor/core/schema
      </code>
      
      ) reads the flag.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        editorBlockContainer
      </code>
      
      , <code>
        editorChrome
      </code>
    </td>
    
    <td>
      <code>
        NodeFlags
      </code>
      
      , block conversion and drag targeting
    </td>
    
    <td>
      A <em>
        Container block
      </em>
      
       (the document, a Typed block) holds blocks that are individually convertible and draggable; <em>
        chrome
      </em>
      
       is fixed header rows of such a block. The callout declares neither: it is one block, its inner paragraphs are not offered separately.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        abilities
      </code>
    </td>
    
    <td>
      the <code>
        Abilities
      </code>
      
       extension (<code>
        AbilityRule
      </code>
      
      : <code>
        grants
      </code>
      
      , <code>
        revokes
      </code>
      
      , <code>
        own
      </code>
      
      )
    </td>
    
    <td>
      What editing abilities hold inside the node. The callout revokes headings, Typed blocks, media, recording and speaker lines for its content. Ability ids are plain strings; host rules passed through the <code>
        abilities
      </code>
      
       prop replace a node's own rule (chapter 5 grants a custom ability).
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        renderMarkdown
      </code>
      
      , <code>
        markdownTokenName
      </code>
      
      , <code>
        markdownTokenizer
      </code>
      
      , <code>
        parseMarkdown
      </code>
    </td>
    
    <td>
      <code>
        @tiptap/markdown
      </code>
    </td>
    
    <td>
      The Markdown form of the block, in both directions.
    </td>
  </tr>
</tbody>
</table>

**Why !!!.** The Markdown form is the form the model reads and writes, and the one `getMarkdown()` exports. Pick syntax that no other stage claims: `:::` fences belong to Typed blocks, and `**Name:**` lines are turned into speaker segments by the transcript feature's `segment` stage.

<note>

**Limitation of this example.** `renderMarkdown` joins the body blocks with `'\n'` and the tokenizer ends a callout at the first blank line. A callout with several paragraphs therefore exports without blank lines and re-imports as **one** paragraph. Keep callouts to one paragraph when the Markdown round trip matters, or extend the tokenizer.

</note>

### Node view and styles

The node view is attached in a second file, so `node.ts` stays free of Vue:

```ts [examples/vue-simple/src/callout/index.ts]
import type { NodeViewRenderer } from '@tiptap/core'
import { VueNodeViewRenderer } from '@tiptap/vue-3'
import CalloutView from './CalloutView.vue'
import { Callout } from './node'

export { Callout, TONES, type Tone } from './node'

// The schema node plus its Vue node view; node.ts stays Vue-free so a server can import it on its own.
export const CalloutBlock = Callout.extend({
  // Explicit return type: keeps the declaration independent of the Vue view's inferred types.
  addNodeView(): NodeViewRenderer {
    return VueNodeViewRenderer(CalloutView)
  },
})
```

On a React surface the same second file attaches `ReactNodeViewRenderer(CalloutView)` from `@tiptap/react` instead; `node.ts` stays unchanged and framework-free.

The view renders a non-editable header (tone icon and a `USelect`) above the editable body:

```vue [examples/vue-simple/src/callout/CalloutView.vue]
<script setup lang="ts">
import { NodeViewContent, nodeViewProps, NodeViewWrapper } from '@tiptap/vue-3'
import { computed } from 'vue'
import { type Tone, TONES } from './node'

const props = defineProps(nodeViewProps)

const tone = computed(() => TONES.find(t => t.value === props.node.attrs.tone) ?? TONES[0])
</script>

<template>
  <NodeViewWrapper as="div" class="callout" :data-tone="node.attrs.tone">
    <div class="callout-header" contenteditable="false">
      <UIcon :name="tone?.icon ?? 'i-lucide-info'" class="size-4 shrink-0" />
      <USelect
        :items="[...TONES]"
        value-key="value"
        label-key="label"
        :model-value="node.attrs.tone"
        size="xs"
        variant="ghost"
        :disabled="!editor.isEditable"
        @update:model-value="(value: Tone) => updateAttributes({ tone: value })"
      />
    </div>
    <NodeViewContent as="div" class="callout-body" />
  </NodeViewWrapper>
</template>
```

The styles are plain CSS with Nuxt UI's colour variables, one rule set per tone. Import them **after** the core stylesheet (`@import "./callout/callout.css";` right below `core.css`, as in the example's `style.css`):

```css [examples/vue-simple/src/callout/callout.css]
/* The „Hinweis“ block: a tinted box per tone; the tone colours come from Nuxt UI's colour variables. */
.callout {
  --callout-color: var(--ui-info);
  border-left: 3px solid var(--callout-color);
  border-radius: 0.375rem;
  padding: 0.5rem 0.75rem;
  margin: 0.5rem 0;
  background: color-mix(in oklab, var(--callout-color) 8%, transparent);
}

.callout[data-tone='info'] {
  --callout-color: var(--ui-info);
}

.callout[data-tone='warning'] {
  --callout-color: var(--ui-warning);
}

.callout[data-tone='success'] {
  --callout-color: var(--ui-success);
}

.callout-header {
  display: flex;
  align-items: center;
  gap: 0.25rem;
  color: var(--callout-color);
}

.callout-body > :first-child {
  margin-top: 0;
}

.callout-body > :last-child {
  margin-bottom: 0;
}
```

## Path A: `extensions` and `commands`

The simple playground adds the node to a `SimpleEditor` with two props. The same props exist on `AdvancedEditor` and `EditorSurface`. `extensions` adds TipTap extensions after the built-in ones; `commands` transforms the whole command list, and a command with a `slash` placement joins the `/` menu. Both are read once at setup, so pass a constant and a module-level function:

```vue [examples/vue-simple/src/App.vue]
// Added to the simple schema through the `extensions` prop (constant: read once at setup).
const extensions = [CalloutBlock]

// Host commands next to the simple editor's own (the `/h1` … `/rule` block entries and the toolbar): `/datum`, `/hinweis`.
function hostCommands(defaults: CommandDef[]): CommandDef[] {
  return [
    ...defaults,
    {
      id: 'datum',
      label: 'Datum',
      icon: 'i-lucide-calendar',
      slash: {},
      run: editor => editor.chain().focus().insertContent(new Date().toLocaleDateString('de-DE')).run(),
    },
    {
      id: 'hinweis',
      label: 'Hinweis',
      icon: 'i-lucide-info',
      slash: {},
      run: editor => editor.chain().focus().setCallout('info').run(),
    },
  ]
}
```

`slash.id` (default: the command `id`) is what the user types after `/`; the query matches it or the label as a prefix, case-insensitively. `run` is called after the `/query` text is deleted. The two props reach the editor in the template:

```vue [examples/vue-simple/src/App.vue]
<SimpleEditor
              :model-value="content"
              :editable="editable"
              :extensions="extensions"
              :commands="hostCommands"
              @ready="onReady"
              @update:model-value="onUpdate"
              @content-error="onContentError"
            />
```

Try it. The demo loads the „Hinweise“ sample; type `/hinweis` and press Enter, or press `Mod-Shift-h`, and change the tone with the select in the callout's header:

<demo-callout-path-a>



</demo-callout-path-a>

What the user gets:

- Typing `/hinweis` Enter wraps the paragraph at the caret in an `info` callout; `Mod-Shift-h` toggles it (wrap, or lift out of the callout).
- The tone `USelect` in the callout's header changes `attrs.tone`; the Markdown form then reads `!!! success` for that block.
- Nodes with `editorBlock: true` get an `id`. The JSON pane of the example shows `editor.getJSON()` (not the `v-model` value) so you can see the IDs the editor adds.
- The `/` entry has no `ability`, so it is listed wherever the `/` menu opens. A toolbar button needs path B: the toolbar renders what features contribute, and a prop cannot add to it.

The simple editor rejects documents with unknown nodes, so the „Hinweise“ sample (`callouts` in [`samples.ts`](https://github.com/skaile-ai/forge-editor/blob/main/examples/vue-simple/src/samples.ts)) loads only because `CalloutBlock` is in the schema. Content with a `typedBlock` still ends up in `contentError` (chapter 2).

## What you have now

A `callout` node with schema, commands, a shortcut, a Markdown form and a Vue node view, plugged into `SimpleEditor` through the `extensions` and `commands` props. The block shows up in `/` and the Markdown export, but not in the toolbar, in hover actions or in the conversion menu.

## Next

[Chapter 5: Your own feature, path B](https://skaile-ai.github.io/forge-editor/tutorial/own-feature-path-b) gives the block a toolbar button, a hover menu and „Umwandeln in …“.


# Chapter 5: Your own feature, path B

> Turn the callout into an EditorFeature with a toolbar button, a hover menu for the tone, „Umwandeln in …“ and its own ability.

Path A gave the callout a slash entry. Path B makes it a feature like the built-in ones: a toolbar button next to the media buttons, a hover menu on the block that switches the tone, „Umwandeln in Callout“ for paragraphs and „Umwandeln in …“ out of a callout. It reuses the node of chapter 4 unchanged.

A feature is a bundle of contributions behind one `id`. Features differ only by which contribution slots they fill; nothing is registered globally. The callout feature fills six slots, shown piece by piece below. Try the result first: the toolbar has a „Callout“ button in the `inserts` group, hovering a callout shows a bar with the tone menu, and the block's „Umwandeln in …“ menu lists the conversions:

<demo-callout-path-b>



</demo-callout-path-b>

## The feature

`feature.ts` in the kitchen sink (`app/editor/callout/`) starts with the ability that gates the callout and the factory that returns the feature. Three fields identify it: `id`, the `dimension` (`'content'`, because it adds a node to the document) and the node it contributes.

```ts [app/editor/callout/feature.ts]
import { command, type EditorFeature } from '@skaile/forge-editor/core'
import { calloutConversions } from './convert'
import { CalloutBlock } from './index'
import { Callout, TONES } from './node'

/** The ability that gates the callout's toolbar button, `/` command and hover menu; grant it at root through the `abilities` prop. */
export const CALLOUT_ABILITY = 'insert.callout'

/**
 * The callout as a full editor feature: node, one command (toolbar button merged into the `inserts` group beside
 * "Speaker block", and `/callout`), a hover menu for the tone, the two-way "Convert to …" conversion and its description for the AI
 * (`aiContext.blocks`), so chat and generate tasks can create, convert to and edit callouts.
 */
export function calloutFeature(): EditorFeature<never> {
  return {
    id: 'callout',
    dimension: 'content',
    schemaExtensions: () => [Callout],
    extensions: () => [CalloutBlock],
```

- **extensions** adds the node with its view to the editor's schema. Feature extensions are added in feature order, before the `extensions` prop.
- **schemaExtensions** names the Vue-free node file. A server that validates or seeds documents collects these with `schemaExtensionsOf(features)` from `@skaile/forge-editor/core/schema` (chapter 6).
- **EditorFeature<never>** says the feature holds no framework components. It fits a Vue and a React list alike; the callout node view stays in `index.ts`.

### `commands`: toolbar, `/` menu and palette from one definition

A command is declared once, with the placements that show it. `toolbar: { group, order }` puts it on the toolbar, `slash: { id? }` in the `/` menu, and the ⌘K palette lists every command that runs or opens a menu. The toolbar, the `/` menu and the palette all derive their entries and their enabled and visible state from the same definition, so a command cannot be gated differently in two places.

```ts [app/editor/callout/feature.ts]
commands: () => [
      command({
        id: 'callout',
        toolbar: { group: 'inserts', order: 15 },
        slash: { id: 'callout' },
        creates: { type: 'callout' },
        icon: 'i-lucide-info',
        label: 'Callout',
        kbds: ['meta', 'shift', 'h'],
        ability: CALLOUT_ABILITY,
        command: c => c.toggleCallout(),
        active: e => e.isActive('callout'),
      }),
    ],
```

- **Groups.** `toolbar.group` must name a group some feature declares in `toolbarGroups`. The callout needs none of its own: it puts its button into the `inserts` group that the transcript feature (speaker button, `order: 10`) and the media feature (pickers, `order` 20 to 50) fill, so `order: 15` places „Callout“ between „Sprecherblock“ and the media buttons. A command `id` is unique per editor.
- **Bodies.** `command: chain => chain.toggleX()` builds a `run` command from a command chain: it focuses the editor, runs the chain and is disabled while `editor.can().chain()` says it is impossible. `active` makes it a toggle. Write `run: editor => …` yourself for anything else, or `menu` for a dropdown. `kbds` only labels the tooltip; the shortcut itself is the node's `addKeyboardShortcuts`.
- **Gating.** `ability` disables the command where the caret does not hold that ability. `creates: { type }` names the node the command inserts: it is disabled where the schema does not allow that node at the caret. `can(editor)` adds a structural check of your own, `visible(editor)` hides the command. The `/` menu lists enabled commands only; the toolbar and the palette grey them.
- **Abilities at root.** A command whose `ability` is neither in `ROOT_ABILITIES` nor granted by the `abilities` prop never becomes enabled at document root. The surface logs a warning once per command when it mounts. The mount below grants it.

### `blockActions`: the hover menu

Hover actions sit on a block's top line at the editor's right edge, shown by an installed `block-ui` feature. `ability` is checked on the block itself, `isVisible` narrows it further, and `order` sorts feature actions; actions with a larger `order`, like the callout's 500, follow the built-in ones. With `menu` instead of `run` the action opens a dropdown. The callout's lists the tones and applies one with `setCalloutTone` after selecting the block.

```ts [app/editor/callout/feature.ts]
blockActions: () => [{
      id: 'callout-tone',
      label: 'Callout tone',
      icon: 'i-lucide-palette',
      ability: CALLOUT_ABILITY,
      order: 500,
      isVisible: ({ node }) => node.type.name === 'callout',
      menu: ({ editor, pos }) => TONES.map(tone => ({
        label: tone.label,
        icon: tone.icon,
        onSelect: () => editor.chain().focus().setNodeSelection(pos).setCalloutTone(tone.value).run(),
      })),
    }],
    conversions: [calloutConversions],
```

The bar is hidden while the editor is read-only.

Where the bar appears is the host's choice: `blockUiFeature({ actions })` (or `composeEditor({ blockUi: { actions } })`) selects the hover bar (default), a toolbar on the block holding the selection, both, or none. An action can restrict itself with `placement: 'hover' | 'toolbar' | 'both'` (default `'both'`), e.g. a rarely needed action on the toolbar only. `ability` stays a gate on the block's place in the document, not a presentation switch: removing an ability hides the action everywhere, `placement` and `actions` only decide on which surface it is offered.

### `conversions`: „Umwandeln in …“

„Umwandeln in …“ (hover menu, toolbar groups, the AI `convert` operation) runs through `ConversionProvider`s. The callout contributes one, in `convert.ts`:

```ts [app/editor/callout/convert.ts]
import type { Node as PMNode } from '@tiptap/pm/model'
import {
  childrenOf,
  type ConversionProvider,
  CORE_TARGET_IDS,
  convertCoreBlocks,
  type ConvertTarget,
  createConverter,
  finishConversion,
  isCoreSource,
  parseCoreTarget,
} from '@skaile/forge-editor/core'

const CALLOUT = 'callout'
// A host block names itself with the inert `custom` target: `id` is the target id and the node type name.
const TARGET: ConvertTarget = { type: 'custom', id: CALLOUT }
/** The core targets a callout unwraps into. */
const UNWRAP_TARGETS: readonly ConvertTarget[] = CORE_TARGET_IDS.flatMap(id => parseCoreTarget(id) ?? [])

const isCallout = (node: PMNode) => node.type.name === CALLOUT

/**
 * Paragraphs, headings, code blocks, lists and quotes become a callout (the quote rule: textblocks turn into
 * paragraphs, lists and quotes keep their blocks); a callout unwraps into every core target through the core engine.
 * `handlesSource` makes this provider execute every conversion of a callout, the core provider has none for it.
 */
export const calloutConversions: ConversionProvider = {
  handlesSource: isCallout,
  targets: (_editor, node) => {
    const { nodes } = node.type.schema
    if (isCallout(node)) return UNWRAP_TARGETS.filter(target => nodes[target.type])
    return isCoreSource(node) && nodes[CALLOUT] ? [TARGET] : []
  },
  parseTarget: id => id === CALLOUT ? TARGET : null,
  label: target => target.type === 'custom' && target.id === CALLOUT ? { label: 'Callout', icon: 'i-lucide-info' } : null,
  convert: (state, $start, target) => {
    const node = $start.nodeAfter
    const { schema } = state
    if (!node) return null
    let output: PMNode[] | null
    if (isCallout(node)) {
      const children = childrenOf(node)
      output = convertCoreBlocks(schema, children, target) ?? children
    }
    else if (target.type === 'custom' && target.id === CALLOUT && schema.nodes[CALLOUT] && isCoreSource(node)) {
      const quote = createConverter(schema).toQuote([node])[0]
      output = quote ? [schema.nodes[CALLOUT].create({ tone: 'info' }, quote.content)] : null
    }
    else return null
    const blocks = output && finishConversion([node], output)
    return blocks ? { from: $start.pos, to: $start.pos + node.nodeSize, blocks } : null
  },
}
```

The rules a provider follows:

- **The custom target.** `ConvertTarget` is a closed union of inert descriptors; `{ type: 'custom', id, attrs? }` is the member for host blocks. `id` is both the target id and the node type name. The core engine never executes a `custom` target.
- **Ownership.** The provider whose `parseTarget(id)` returns the target owns it (labels through `label`, execution through `convert`). A target id offered by two providers throws.
- **handlesSource.** The first provider that claims a source block executes *every* conversion of it. The callout claims callouts, so unwrapping into a paragraph or a list runs here and reuses the core engine (`convertCoreBlocks`). Without a claim, the target's owner executes.
- **Helpers.** `createConverter`, `convertCoreBlocks`, `childrenOf`, `isCoreSource`, `CORE_TARGET_IDS`, `parseCoreTarget` and `finishConversion` (carries block IDs and checks the result) come from `@skaile/forge-editor/core`. Return `null` for "not possible"; the result must fit its parent, so a callout is only offered where one may stand.
- **One transaction.** A conversion is one undo step.

### `aiContext`

The last slot, `aiContext`, tells the model that the block exists and how to write it. It is chapter 7's topic.

## Composing and mounting

The chapter-3 pattern again: a preset from `defineEditor`, mounted with `EditorSurface`. The preset lists the callout feature next to the core features and `blockUiFeature()`, which draws the hover bar. The `abilities` prop grants the custom ability at document root:

```vue [docs/app/components/content/DemoCalloutPathB.client.vue]
const preset = defineEditor({
  features: [coreContentFeature(), coreUiFeature(), blockUiFeature(), calloutFeature()],
})
```

The custom ability is not part of `ROOT_ABILITIES`, so the host grants it at document root, or the toolbar button, `/callout` and the hover menu stay hidden:

```vue [docs/app/components/content/DemoCalloutPathB.client.vue]
const abilities: Partial<AbilitiesOptions> = { root: [...ROOT_ABILITIES, CALLOUT_ABILITY] }
```

`ROOT_ABILITIES` is the built-in set from `@skaile/forge-editor/core/schema`; spreading it keeps every standard ability and adds yours. The surface then takes both:

```vue
<EditorSurface v-model="content" :preset="preset" :abilities="abilities" @ready="editor = $event" />
```

In the repository's kitchen sink (`app/pages/kitchen-sink/surface.vue`, route `/kitchen-sink/surface`) the callout joins the full advanced composition instead of a short list; `add` appends host features after the catalog. Another host feature, `epikriseFeature()`, has its own page, `/kitchen-sink/epikrise`:

```vue [app/pages/kitchen-sink/surface.vue]
// The advanced composition plus the host's own feature, handed to the surface as one preset.
const preset = advancedEditor({ blockTypes: defaultBlockTypes(useEditorI18n().t), add: [calloutFeature()] })
```

Rules for the composition:

- **Declare the dimension.** Every feature names the axis it belongs to in `dimension`: `'content'` (nodes, marks or structure; the callout), `'interaction'` (editing UX, no schema) or `'ai'`. `defineEditor` fails with `feature "<id>" declares no dimension` otherwise.
- **Order is order.** `defineEditor` keeps the given order: toolbar groups, menu entries and the schema follow it. A feature that is not in the list contributes nothing, and a smaller list works too: `core + ui + callout` needs `blockUiFeature()` only for the hover actions.
- **Grant a custom ability.** Items gated by your own ability id are inert until the ability exists at the caret. Without the grant the toolbar button is disabled, and `/callout` and the hover menu are missing. Root abilities come from the `abilities` prop; per-node rules go in `rules`, or in the node's own `abilities`.
- **Build the preset once.** Build it in `<script setup>` (or a React `useState`/`useMemo`): the preset is read once at mount, like every prop of the surface. Call `advancedEditor()` during component setup: some of its features hook the Vue app's lifetime.
- **requires.** Name features your feature builds on with `requires: ['block-ui']`: `defineEditor` throws at composition time when one is missing, instead of a button silently not appearing. The callout does not declare it because it works without hover actions.

The full contract of `EditorFeature`, including the slots this chapter did not use, is on [Feature contract](https://skaile-ai.github.io/forge-editor/reference/feature-contract).

### Markdown import

The kitchen sink's Surface page has an „Insert Markdown“ button that shows the tokenizer of chapter 4 working through the block pipeline: `parseBlocks(editor, markdown).blocks` returns TipTap JSON blocks, here with a `callout`.

```vue [app/pages/kitchen-sink/surface.vue]
/** Imports Markdown with the callout syntax through the editor's block pipeline (the tokenizer of `callout/node.ts`). */
function insertCalloutMarkdown() {
  const editor = pane.editor
  if (!editor) return
  editor.chain().focus().insertContent(parseBlocks(editor, CALLOUT_MARKDOWN).blocks).run()
}
```

## What you have now

The callout is a feature: a toolbar button in the `inserts` group, a `/callout` entry and a shortcut from one command definition, a hover menu that switches the tone, „Umwandeln in …“ in both directions, all gated by `CALLOUT_ABILITY`, which the host grants at the document root.

## Next

[Chapter 6: Backend and collaboration](https://skaile-ai.github.io/forge-editor/tutorial/backend-and-collaboration) puts the editor behind a server and lets two browsers edit one document.


# Chapter 8: The React surface

> Run the meeting-notes editor on React: EditorContextProvider, EditorSurface, EditorToolbar, SimpleEditor and the Toaster, and where the callout would go.

Everything in chapters 2 to 7 has a React twin. The React layer (`@skaile/forge-editor/react`, shadcn/ui on Radix and Tailwind 4) renders the same framework-free core as the Vue layer: the simple editor, `EditorToolbar`, the settings panel and modal, and the `@`, `#` and `/` suggestion popups. It uses no Vue, Nuxt UI or Nuxt module.

The runnable reference is `examples/react-simple` (port 3041); it is built into this page. It has the same sample picker, read-only switch, host `/datum` command and JSON and Markdown panes as the Vue example from chapter 2, plus `@` mentions:

<demo-frame name="react-simple">



</demo-frame>

Start it yourself with `bun run --cwd examples/react-simple dev`. [Quick start: React](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-react) lists the dependencies, `vite.config.ts` and `index.css` an app needs; this chapter shows how the pieces map to what you already know.

## The context: `EditorContextProvider`

Vue has `app.use(createEditor())`. React has a context object that **you own**: `createEditorContext()` from the framework-free `@skaile/forge-editor/core` takes the same options as the Vue plugin (`backend`, `locale`, `ai`, …), and `EditorContextProvider` hands it to the tree. The provider never disposes the context; call `context.dispose()` yourself when the context outlives your app. The toolbar and menus render `i-lucide-*` names through `@iconify/react`, so the example preloads the icon collection and the page makes no request to the Iconify API:

```tsx [examples/react-simple/src/main.tsx]
import lucide from '@iconify-json/lucide/icons.json'
import { addCollection } from '@iconify/react'
import { createMemoryBackend } from '@skaile/forge-editor/adapters/memory'
import { createEditorContext } from '@skaile/forge-editor/core'
import { EditorContextProvider } from '@skaile/forge-editor/react'
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { App } from './App'
import './index.css'

// Preload the icon set: the page makes no request to the Iconify API.
addCollection(lucide)

// The host owns the context; the provider never disposes it. No data layer: documents, dropped files (as blob: URLs),
// mention users and tags, and settings live in the page.
const context = createEditorContext({
  backend: createMemoryBackend({
    users: [
      { id: 'u1', username: 'Ada Lovelace', color: '#7c3aed' },
      { id: 'u2', username: 'Alan Turing', color: '#0ea5e9' },
    ],
    tags: ['idee', 'entwurf', 'wichtig'],
  }),
})

createRoot(document.getElementById('app')!).render(
  <StrictMode>
    <EditorContextProvider context={context}>
      <App />
    </EditorContextProvider>
  </StrictMode>,
)
```

Notices of app-level models, such as the AI model profiles, go through the context's notifier. The simple editor raises none, so `createEditorContext()` is enough here. A host of features passes `createEditorContext({ notify: reactNotifier })` and mounts sonner's `Toaster` once (both from `@skaile/forge-editor/react`); components such as `DocumentTree` need the `Toaster` to be mounted.

## `EditorSurface` and `EditorToolbar`

The React `EditorSurface` takes the same kind of preset as the Vue one. `EditorToolbar` is again a sibling that works on the editor you pass it (from `onReady`), never on a global active editor, and it renders no groups without an editor. The preset follows chapter 3, with the same feature factories:

```tsx [examples/react-simple/src/App.tsx]
// Preset and metadata are read once at mount: module constants.
const preset = defineEditor({ features: [coreContentFeature(), coreUiFeature<ComponentType<{ editor: Editor }>>({ palette: EditorCommandPalette }), mentionsFeature()] })
const metadata: EditorMetadata = {
  mentions: [
    { id: 'u1', label: 'Ada Lovelace', color: '#7c3aed' },
    { id: 'u2', label: 'Alan Turing' },
  ],
}
```

`coreContentFeature()`, `coreUiFeature()`, `mentionsFeature()` and the three integrations have no components and work in both layers. A feature with components has a React entry: `mediaFeature` from `@skaile/forge-editor/media/react`, `blockUiFeature` from `@skaile/forge-editor/block-ui/react`, and so on. Mixing a Vue feature into a React preset is a type error. Module constants matter more than in Vue: the preset, `metadata`, `abilities`, `extensions` and `commands` are read once at mount.

The surface itself differs from Vue in the prop names: `value` and `onChange` instead of `v-model`, `onReady` instead of `@ready`, and so on:

```tsx [examples/react-simple/src/App.tsx]
<EditorSurface
              preset={preset}
              metadata={metadata}
              commands={hostCommands}
              value={content}
              editable={editable}
              onReady={setEditor}
              onChange={onChange}
              onContentError={onContentError}
            />
```

<table>
<thead>
  <tr>
    <th>
      Name
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        preset
      </code>
    </td>
    
    <td>
      <code>
        EditorSurface
      </code>
      
       only: <code>
        defineEditor({ features })
      </code>
      
       (a <code>
        ReactPreset
      </code>
      
      ); fixed at mount, remount with <code>
        key
      </code>
      
       to change it.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        value
      </code>
      
       / <code>
        onChange
      </code>
    </td>
    
    <td>
      TipTap JSON document and its edits. A new object replaces the document without an <code>
        onChange
      </code>
      
      ; JSON the editor emitted itself and the host hands back unchanged is ignored, so the round trip keeps caret and undo history.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        editable
      </code>
    </td>
    
    <td>
      Read-only when <code>
        false
      </code>
      
       (default <code>
        true
      </code>
      
      ); reactive.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        metadata
      </code>
    </td>
    
    <td>
      Host lists (<code>
        EditorMetadata
      </code>
      
      ); reactive, pass a constant.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        abilities
      </code>
      
      , <code>
        extensions
      </code>
      
      , <code>
        commands
      </code>
    </td>
    
    <td>
      As in Vue; read once at mount.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        onReady
      </code>
      
      , <code>
        onMetadataCreate
      </code>
      
      , <code>
        onContentError
      </code>
    </td>
    
    <td>
      The Vue events <code>
        ready
      </code>
      
      , <code>
        metadataCreate
      </code>
      
       and <code>
        contentError
      </code>
      
       as callbacks.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        settingsUi
      </code>
    </td>
    
    <td>
      <code>
        'internal'
      </code>
      
       (default) mounts the settings modal inside the surface; <code>
        'external'
      </code>
      
       calls <code>
        onSettingsOpen(tab?)
      </code>
      
       and the host renders <code>
        EditorSettingsPanel
      </code>
      
       or <code>
        EditorSettingsModal
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## The one-liner: `SimpleEditor`

Without own features, `SimpleEditor` from `@skaile/forge-editor/react/simple` builds the preset itself (`core-content` and `core-ui`, plus the features in its `add` prop) on an `EditorSurface`. The ref exposes `{ editor, openSettings, preset }`:

```tsx
import { EditorToolbar } from '@skaile/forge-editor/react'
import { SimpleEditor } from '@skaile/forge-editor/react/simple'
import type { Editor } from '@tiptap/core'
import { useState } from 'react'

export function App() {
  const [editor, setEditor] = useState<Editor | null>(null)
  return (
    <>
      <EditorToolbar editor={editor ?? undefined} />
      <SimpleEditor onReady={setEditor} />
    </>
  )
}
```

## Settings in React

`useEditorSettings()` from `@skaile/forge-editor/react` reads the app's settings from the context: `{ settings, update, set, ready, synced }`, where `update(draft => { … })` mutates a copy and stores it and `set(value)` replaces it. Persistence is the same as in Vue: the `localStorage` key `tiptap-editor:settings`, optionally synced per account.

## Where the callout would go

There is no React callout in the repository: the Hinweis block of the examples is a Vue example, and the React sample says so („Hinweis-Blöcke gehören nicht zur Bibliothek; das Vue-Beispiel bringt einen eigenen mit.“). Porting it is small, because the node is already framework-free:

- `node.ts` from chapter 4 stays unchanged. It imports only `@tiptap/core` and `@skaile/forge-editor/core/schema`.
- The second file attaches the view: `Callout.extend({ addNodeView: () => ReactNodeViewRenderer(CalloutView) })` with `ReactNodeViewRenderer` from `@tiptap/react` and a React `CalloutView` built from `NodeViewWrapper` and `NodeViewContent`.
- Path A is the same: pass `extensions` (a module constant) and `commands` (a module function) to `EditorSurface` or `SimpleEditor`.
- Path B is the same: `calloutFeature()` fills no component slot, so it is an `EditorFeature<never>` and fits a React list as it is. Add `blockUiFeature()` from `@skaile/forge-editor/block-ui/react` for the hover actions.

## What you have now

The same editor on React: a context you own, an `EditorSurface` over a preset of the features from chapter 3, a toolbar, the `SimpleEditor` shortcut and the settings hook. You have finished the tutorial: from a simple editor to composed features, an own block, a server with collaboration and AI, on both surfaces.

## Next

- [Advanced editor in React](https://skaile-ai.github.io/forge-editor/guides/advanced-react) for the full catalog on React (`AdvancedEditor`, `composeEditor`, collaboration).
- [Exports](https://skaile-ai.github.io/forge-editor/reference/exports) for the inventory of every entry of the package.


# Chapter 2: A simple editor

> Mount SimpleEditor with a JSON v-model, add the toolbar and the outline beside it, switch it read-only and handle rejected content.

`SimpleEditor` is the two core features alone (`core-content` and `core-ui`): bold, italic, underline, strike, code and link, headings, lists, quotes, code blocks, a horizontal rule, undo and redo. It makes no backend request, has no Yjs and no feature code. This is the right start for meeting notes.

Try it first. The toolbar and the outline sit beside the editor, the JSON pane shows the document the editor holds, and the switch makes it read-only:

<demo-simple-editor>



</demo-simple-editor>

## The editor context

Every editor component reads shared state (settings, language, backend) from an editor context that the app installs once. `createEditor()` from `@skaile/forge-editor/vue` is that context as a Vue plugin; Nuxt UI's `ui` plugin provides the components. The example's `main.ts` in full:

```ts [examples/vue-simple/src/main.ts]
import ui from '@nuxt/ui/vue-plugin'
import { createMemoryBackend } from '@skaile/forge-editor/adapters/memory'
import { createEditor } from '@skaile/forge-editor/vue'
import { nuxtUiKit } from '@skaile/forge-editor/vue/kit/nuxt-ui'
import { createApp } from 'vue'
import App from './App.vue'
import './style.css'

// No data layer: documents, dropped files (as blob: URLs), mention users and tags, and settings live in the page.
const backend = createMemoryBackend({
  users: [
    { id: 'u1', username: 'Ada Lovelace', color: '#7c3aed' },
    { id: 'u2', username: 'Alan Turing', color: '#0ea5e9' },
    { id: 'u3', username: 'Grace Hopper', color: '#16a34a' },
  ],
  tags: ['idee', 'entwurf', 'wichtig'],
})

createApp(App)
  .use(ui)
  .use(createEditor({ kit: nuxtUiKit(), backend }))
  .mount('#app')
```

- `nuxtUiKit()` tells the library's Vue layer to render its toolbar, menus and dialogs with Nuxt UI components.
- `createMemoryBackend()` (`@skaile/forge-editor/adapters/memory`) keeps everything in the page: settings in `localStorage`, dropped files as `blob:` URLs, and the lists behind `@` and `#`. The simple editor does not use the lists; chapter 3 does. Without a `backend` option the context talks to the HTTP routes of the Nuxt module instead ([Nuxt module](https://skaile-ai.github.io/forge-editor/guides/nuxt-module)).
- `createEditor({ locale: 'en' })` switches the library's own strings to English.

Then the stylesheet. Tailwind, Nuxt UI, then the core CSS, and a `@source` line so Tailwind generates the utility classes the library's Vue files use:

```css
@import "tailwindcss";
@import "@nuxt/ui";
@import "@skaile/forge-editor/vue/kit/nuxt-ui.css";
@import "@skaile/forge-editor/styles/core.css";
@source "../node_modules/@skaile/forge-editor/dist";
```

The `@source` path is relative to the CSS file and points to the installed library's `dist` directory: the whole of it, because the Features' components (`features/*/components`) sit beside `vue`. In this repository the examples point at the sibling's `src` (`../../../packages/editor/src`) instead. The order matters: [CSS and UI-provider requirements](https://skaile-ai.github.io/forge-editor/reference/css-and-ui) lists every sheet and why it comes where it does.

## Mount the editor

`v-model` carries the document as TipTap JSON. `EditorToolbar` and `EditorOutline` are siblings of the editor, not children: they work on exactly the editor you hand them, taken from the `ready` event. Keep that instance in a `shallowRef`; a deep `ref` would wrap the TipTap instance in a Vue proxy.

```vue
<script setup lang="ts">
import { ref, shallowRef } from 'vue'
import type { Editor, JSONContent } from '@tiptap/core'
import { SimpleEditor } from '@skaile/forge-editor/vue/simple'
import { EditorToolbar } from '@skaile/forge-editor/vue'
import { EditorOutline } from '@skaile/forge-editor/outline/vue'

const editor = shallowRef<Editor>()
const content = ref<JSONContent>({ type: 'doc', content: [{ type: 'paragraph' }] })
</script>

<template>
  <UApp>
    <EditorToolbar :editor="editor" />
    <SimpleEditor v-model="content" @ready="editor = $event" />
    <EditorOutline :editor="editor" />
  </UApp>
</template>
```

`<UApp>` provides the overlays, tooltips and toasts the toolbar uses. The example's own template adds a sample picker, the read-only switch and two output panes. The part that matters here is how the editor, its toolbar and its outline are wired:

```vue [examples/vue-simple/src/App.vue]
<template>
  <UApp>
    <main class="mx-auto flex max-w-7xl flex-col gap-4 p-6">
      <h1 class="text-xl font-semibold">@skaile/forge-editor – SimpleEditor</h1>

      <div class="flex flex-wrap items-center gap-3">
        <USelect
          v-model="sample"
          :items="SAMPLES"
          value-key="id"
          label-key="label"
          class="w-64"
          aria-label="Beispiel"
          data-testid="sample"
        />
        <USwitch v-model="editable" label="Bearbeitbar" data-testid="editable" />
        <span class="text-sm text-muted" data-testid="edits">Änderungen: {{ edits }}</span>
      </div>

      <UAlert v-if="contentError" color="error" variant="subtle" title="Inhalt abgelehnt" :description="contentError" data-testid="content-error" />

      <div class="grid grid-cols-[14rem_minmax(0,1fr)_20rem] gap-6">
        <aside aria-label="Gliederung">
          <EditorOutline :editor="editor" />
        </aside>
        <div class="flex min-w-0 flex-col gap-3">
          <EditorToolbar :editor="editable ? editor : undefined" />
          <div class="rounded-lg border border-default p-4" data-testid="surface">
            <SimpleEditor
              :model-value="content"
              :editable="editable"
              :extensions="extensions"
              :commands="hostCommands"
              @ready="onReady"
              @update:model-value="onUpdate"
              @content-error="onContentError"
            />
          </div>
        </div>
        <div class="flex min-w-0 flex-col gap-3">
          <section>
            <h3 class="mb-1 text-sm font-semibold">JSON</h3>
            <pre class="max-h-72 overflow-auto rounded-lg bg-elevated p-3 text-xs" data-testid="json">{{ json }}</pre>
          </section>
          <section>
            <h3 class="mb-1 text-sm font-semibold">Markdown</h3>
            <pre class="max-h-72 overflow-auto rounded-lg bg-elevated p-3 text-xs" data-testid="markdown">{{ markdown }}</pre>
          </section>
        </div>
      </div>
```

Three details:

- **Read-only.** `editable` is reactive. The example hands the toolbar `undefined` while the editor is read-only; without an editor the toolbar renders no groups.
- **The editor owns the document.** `v-model` mirrors it as JSON. Assigning a new object to the model replaces the document without an update event (the editor calls `setContent(json, { emitUpdate: false })`), so loading a sample does not count as an edit. JSON the editor emitted itself and you hand back unchanged is recognised and ignored, so the usual `v-model` round trip keeps the caret and the undo history.
- **Props that are read once.** `extensions`, `commands` and `abilities` are read when the component is set up. Pass constants, or remount with a new `key`.

## Rejected content: `contentError`

The simple schema is not a lossy view of richer documents. Initial and external JSON is checked against the installed schema. A document with unknown node or mark types, for example `{ type: 'doc', content: [{ type: 'typedBlock' }] }` (the node of a Typed block), is rejected: `contentError` fires with the reason and the **last valid document stays** in the editor. Nothing is flattened or silently dropped. The `v-model` value is your own state, so move it back when you want it to follow the editor. This is how the example handles its „Ungültig (Block-JSON)“ sample: the alert shows the reason, and the model and the picker return to the previous sample.

```vue [examples/vue-simple/src/App.vue]
// `shown` is the sample the editor currently shows. The editor keeps its last valid document when it rejects a
// load; the model and the picker follow it back.
let shown = firstSample.id
let rejectedLoad: { id: string, content: JSONContent } | undefined
watch(sample, (id) => {
  const next = SAMPLES.find(s => s.id === id)
  if (!next || id === shown) return
  rejectedLoad = { id: shown, content: content.value }
  shown = id
  contentError.value = ''
  content.value = next.content
})
function onContentError(error: Error) {
  contentError.value = error.message
  if (!rejectedLoad) return
  content.value = rejectedLoad.content
  shown = rejectedLoad.id
  sample.value = rejectedLoad.id
  rejectedLoad = undefined
}
```

The full list of props and events of `SimpleEditor` is in [Quick start: plain Vue](https://skaile-ai.github.io/forge-editor/getting-started/quick-start-vue). The editor is isolated on purpose: `bun run check:editor-entries` proves that the simple bundle contains no feature, AI SDK, Yjs, Hocuspocus or server module.

## What you have now

A Vue app with a working rich-text editor: JSON `v-model`, a toolbar and an outline that follow the editor you give them, a read-only mode, and a defined behaviour for documents the schema rejects. The editor has no features beyond the core ones yet.

## Next

[Chapter 3: Compose features](https://skaile-ai.github.io/forge-editor/tutorial/compose-features) replaces `SimpleEditor` with an editor you assemble from features.


<u-page-hero>
<template v-slot:title="">

A block editor for Vue and React

</template>

<template v-slot:description="">

`@skaile/forge-editor` is built on TipTap v3 and assembled from features: a simple editor without a backend, an advanced editor with media, mentions, Typed blocks, AI, collaboration and comments, and a Nuxt module with server ports.

</template>

<template v-slot:links="">
<u-button color="neutral" size="xl" to="https://skaile-ai.github.io/forge-editor/getting-started/introduction" trailing-icon="i-lucide-arrow-right">

Get started

</u-button>

<u-button color="neutral" size="xl" to="https://skaile-ai.github.io/forge-editor/tutorial/overview" variant="outline">

Tutorial

</u-button>
</template>
</u-page-hero>

<u-page-section>
<template v-slot:title="">

What you get

</template>

<template v-slot:features="">
<u-page-feature icon="i-lucide-blocks" to="https://skaile-ai.github.io/forge-editor/reference/presets-and-features">
<template v-slot:title="">

Features and <span className="text-primary">

presets

</span>
</template>

<template v-slot:description="">

An editor is a list of features: formatting, media, mentions, tables, Typed blocks, themes and block UI. Compose your own or take the simple or advanced preset.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-layout-panel-left" to="https://skaile-ai.github.io/forge-editor/getting-started/quick-start-vue">
<template v-slot:title="">
<span className="text-primary">

Vue and React

</span>

 surfaces

</template>

<template v-slot:description="">

The same framework-free core renders through Nuxt UI on Vue and through shadcn/ui on React, with toolbar, outline, settings and the file browser as components you place yourself.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-server" to="https://skaile-ai.github.io/forge-editor/guides/editor-ports">
<template v-slot:title="">

Nuxt module and <span className="text-primary">

server ports

</span>
</template>

<template v-slot:description="">

Register one `EditorPorts` object for identity and storage; the package owns the routes, the collaboration server, rate limiting and the wire formats.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-sparkles" to="https://skaile-ai.github.io/forge-editor/guides/ai">
<template v-slot:title="">
<span className="text-primary">

AI

</span>

 assistance

</template>

<template v-slot:description="">

A sidebar chat, an AI selection menu with review, agent edit operations and optional integrations for Typed blocks and transcripts.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-users" to="https://skaile-ai.github.io/forge-editor/guides/collaboration">
<template v-slot:title="">

Collaboration and <span className="text-primary">

comments

</span>
</template>

<template v-slot:description="">

Yjs and Hocuspocus for live editing, author colors and comment threads that survive concurrent edits.

</template>
</u-page-feature>

<u-page-feature icon="i-lucide-bot" to="https://skaile-ai.github.io/forge-editor/ai-agents">
<template v-slot:title="">
<span className="text-primary">

Agent-ready

</span>

 docs

</template>

<template v-slot:description="">

`llms.txt`, `llms-full.txt`, a Markdown twin of every page and an installable agent skill for coding agents.

</template>
</u-page-feature>
</template>
</u-page-section>

## Resources for Agents

- [API catalog: every service document this site publishes](https://skaile-ai.github.io/forge-editor/.well-known/api-catalog)
- [Sitemap (XML)](https://skaile-ai.github.io/forge-editor/sitemap.xml)
- [Sitemap (Markdown): every page on the site](https://skaile-ai.github.io/forge-editor/sitemap.md)
- [llms.txt: index of the documentation for LLMs](https://skaile-ai.github.io/forge-editor/llms.txt)
- [llms-full.txt: the full documentation as a single file](https://skaile-ai.github.io/forge-editor/llms-full.txt)
- [Agent skills index: every skill published by this site](https://skaile-ai.github.io/forge-editor/.well-known/skills/index.json)
- [Agent skill: ecsplico-editor](https://skaile-ai.github.io/forge-editor/.well-known/skills/ecsplico-editor/SKILL.md)
- [OpenAPI document: every route this site serves to agents](https://skaile-ai.github.io/forge-editor/openapi.json)