Glossary

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:
A named contribution to an editor (blocks, toolbar entries, menus, settings, AI knowledge) that a Preset lists.
Avoid: plugin, extension (an extension is a TipTap building block a Feature may contribute)

Integration:
A Feature that exists only to connect two or more other Features (e.g. Typed blocks with AI, transcripts with AI).
Avoid: bridge, glue feature

Preset:
A validated, ordered list of Features that defines one kind of editor. Say Editor preset where a Model preset could be meant.
Avoid: config, editor definition

Surface:
The framework-specific place (Vue or React) where a Preset is mounted and edited.
Avoid: editor component, view

Surface session:
One mount of a Preset on a Surface, from mount to unmount; Feature setups are active exactly while it lives.
Avoid: editor instance, mount

UI binding:
The set of framework components a Feature needs on one Surface (overlays, settings tabs, node views).
Avoid: adapter layer, renderer set

Editor library:
The @skaile/forge-editor package: Features, Presets, Surfaces and the server ports, usable by any host.
Avoid: the editor (ambiguous with a Surface), core

Reference app:
The Nuxt app in this repo that hosts the Editor library and shows one complete setup.
Avoid: the app, demo

Host:
The application that mounts a Preset and supplies backend, UI kit, Block types and Host blocks.
Avoid: client, consumer

Document

Document:
The stored, editable unit a user opens, names and moves; it holds Blocks but is not itself a Block.
Avoid: page, file

Block:
An independently addressable unit of a Document's content. A Block is either a Simple block or a Container block.
Avoid: node (code name only), Baustein (legacy UI label for Typed block)

Simple block:
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.
Avoid: leaf, text block, hierarchical block (retired)

Container block:
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).
Avoid: group, wrapper, hierarchical block (retired)

Typed block:
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.
Avoid: composite block (code name composite), Baustein (legacy UI label), section, card

Host block:
A Block contributed by the Host rather than by the Editor library.
Avoid: custom node

Block type:
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.
Avoid: Baustein kind (legacy UI label), composite kind, node type, block feature (Feature is a composition term)

Block capabilities:
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.
Avoid: block features, abilities

Block actions:
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.
Avoid: commands (code name for the keyboard-level API), block menu (the rendering)

Ability:
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.
Avoid: permission, right, role, capability

Block properties:
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.
Avoid: attributes, metadata, fields

Property definition:
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.
Avoid: meta field, schema field

Block contents:
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.
Avoid: children (alone), payload

Accepted children:
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.
Avoid: allowed content, drop targets

Document block type:
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.
Avoid: document (alone, for the type)

Structure mode:
The user's choice of how Documents are structured: Structure mode nests Typed blocks, Flat mode uses Markdown headings.
Avoid: composite mode, heading mode

Sources, derivation and references

Source media:
The original image, audio, video or file kept as a media Block inside the Block that holds it.
Avoid: attachment, asset, source (alone, when the holding block is meant)

Source:
The capability of holding Source media. A Block type declares which media types its Source may be.
Avoid: source block, source-bearing block, recording block (that is one Block type with the Source capability)

Derivation:
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.
Avoid: provenance (the UI label), lineage, history

Derived block:
A Block that carries a Derivation, whatever its Block type.
Avoid: rendition (that is one Block type), child, copy

Rendition:
The Block type for a readable version of a Source: transcript, full text or description. Shown as Readable rendition in the UI.
Avoid: Lesefassung (legacy UI label), transcript (that is one method)

Block reference:
A property value that points to another Block by its block ID; a Property definition may limit the target Block types.
Avoid: link, pointer, relation

Bibliographic record:
A CSL-JSON description of a publication that a Block carries; the Block's ID and title are not part of it.
Avoid: citation, bib, metadata

Basket:
One named colour group, defined by the Host, that a Typed block can be put into; not a saved filter.
Avoid: Korb (legacy UI label), colour label, tag

AI

Model preset:
A server-defined endpoint and model configuration, identified by preset ID; its key stays on the server.
Avoid: preset (alone, that is an Editor preset), server preset

Model profile:
The client-visible model record (ID, label, endpoint, model) that comes from a Model preset or from the user; it never carries a key.
Avoid: model config, connection

Model reference:
The selector sent with an AI request: a Model preset ID, or an endpoint with model and its own key.
Avoid: ref, model id

Model role:
The category of AI work (complete, rewrite, generate) that settings assign a Model profile to.
Avoid: slot (code name), task type

AI brief:
What a Block type tells the model: its purpose, instructions and the AI content template.
Avoid: prompt, kind ai

AI content template:
The Markdown target text with placeholders that a Block type supplies when AI fills a Typed block of that type.
Avoid: skeleton (code name), Vorlage (legacy UI label)

Proposed change:
One change the model proposes to a Document (replace, blocks, insert or delete); it can contain several Review hunks.
Avoid: edit, operation, diff

Review hunk:
One reviewable difference of a Proposed change that the user accepts or rejects.
Avoid: chunk, suggestion

Review:
One round of deciding the Review hunks of a set of Proposed changes; it ends once every hunk is decided.
Avoid: AI review (unless contrasted with a human review), approval

Panels and menus

Block inspector:
The panel that shows either the Document facts or the Typed block under the caret, and edits its summary, properties and tags.
Avoid: details panel, settings panel

Document facts:
The Document section of the Block inspector: the Document's own title, properties and tags.
Avoid: document settings, document meta

Selection menu:
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.
Avoid: bubble menu (the rendering), AI popup

Document tree:
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.
Avoid: sidebar, file browser, outline (the Block outline is the part for one Document)

Block outline:
The per-Document part of the Document tree: the hierarchy of a Document's Typed blocks, not every paragraph.
Avoid: outline (alone), table of contents

Comments margin:
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.
Avoid: comment sidebar, gutter

Orphaned thread:
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.
Avoid: dangling comment, lost comment

Collaboration and appearance

Author identity:
The writing user's ID, name and colour, used for remote carets, author marks and comments.
Avoid: user, account

Collaboration session:
The live connection of one Surface session to a Document's shared state.
Avoid: room, socket

Theme:
The appearance a user picks for the editor; Default appearance is the choice that applies no Theme.
Avoid: Darstellung (legacy UI label), skin, style

Design tokens:
The named CSS variables (--sk-*) the Editor library styles with; the Theme bridge maps them to the Host's UI variables.
Avoid: CSS vars, palette

UI kit:
The set of widgets (buttons, inputs, overlays) a Host supplies to the Editor library's chrome.
Avoid: component library, design system