API reference

@aionbuilders/nabu

Create an editor, mount it, pick the built-in extensions and reach its subsystems.

Functions 15

• createDialogueExtension Dialogue extension factory.
• createDocumentEditor Paragraph + headings + rich text. Good for articles, notes.
• createEditor Create a Nabu editor instance from a preset and optional extra extensions.
• createFullEditor All built-in blocks + rich text. The full Nabu experience.
• createMinimalEditor Paragraph-only editor. Ideal as a simple textarea replacement.
• createPersistedEditor Create a Nabu editor instance with automatic IndexedDB persistence.
• createTextEditor Paragraph + rich text marks. Good for comment boxes, descriptions.
• deltaToHtml Converts a Loro text delta to inline HTML. Marks are rendered as semantic HTML tags.
• deltaToMarkdown Converts a Loro text delta to inline Markdown. A line break (\n in the text) is exported as a markdown hard break (backslash + newline), unless rawBreaks (a block that re-reads its own lines, like a callout body, keeps the plain newline).
• formatChord Format a chord for display, per platform. macOS: ⌃⌥⇧⌘ + key, no separator (⌘⇧Z, ⌘↩). Elsewhere: Ctrl+Alt+Shift+Meta+Key (Ctrl+Shift+Z, Ctrl+Enter).
• insertImageFromFile Insert an image block from a local File: optimistic preview → persist → ref. Re-exported for back-compat.
• insertMediaFromFile Insert a media block of type from a local File. The block appears at once (pending, with a local preview), the bytes are hashed and written to the local store (ADR 014), then the block gets its nabu-asset:sha256-… ref: ready, or — with a host (files.onBeforePersist) — still pending while the background upload runs (block.progress, block.retry(), block.cancel()); the ref never changes afterwards. A file over files.maxFileSize is refused: the block is created rejected, with no ref and a readable reason.
• isSupportedJsonVersion Whether importJSON can read a document export of this version (see JSON_FORMAT_VERSION). A missing version is read as the current one; the number 1 and the string '1' are the same version.
• RegionsExtension Regions extension factory (ADR 016, data model of ADR 018): structure a text in divisions. Installs the region container block (its header is its title, its body is its children), the placement / nesting normalizer, and the reactive registry (nabu.regions, also Regions.get(nabu)).
• sanitizeUrl Return url when it is safe to put in an href / src, otherwise null.

Classes 7

• FileRejectedError Thrown by Files#ingest / Files#persist for a file the options refuse (maxFileSize).
• Files Document-level file/asset manager (ADR 014). The bytes of a file live in an AssetStore, the document only holds nabu-asset:sha256-<hex> references and a small assetIndex Loro map (hash → { mime, name, size, url? }). Lazy: Files.get(nabu).
• MemoryOutbox In-memory Outbox (lost with the page, like a non-persisted document).
• Nabu The editor engine. It owns the document (a Loro CRDT), the block tree and its registry, the selection, the commands and the extensions, and runs the event, clipboard and drag and drop pipelines; NabuEditor renders it. Create one with createEditor (or a preset factory such as createDocumentEditor) rather than new Nabu(...), then read and write the content through serialize, importMarkdown, importJSON, exec and transact. The members documented as public are the stable contract of @aionbuilders/nabu/extend; internals is the unstable door to the rest.
• Region One division of the document, as computed by the registry (ADR 018 §3.4). A read-only VIEW over a region BLOCK, a container of the tree: the structure (level, parent, children, index, path) is derived from the tree; title / fields / label / blocks / wordCount read reactive state when you read them.
• Regions Document-level reactive registry of the regions (ADR 018 §3.4): a pure, derived view over the TREE (stores nothing in Loro). Lazy and cheap: ONE pass over the root blocks and the bodies of the regions builds everything, and it only re-runs when the STRUCTURE changes (a region inserted / moved / deleted / retyped, a child added to a region body), not when text is typed. Obtain it with Regions.get(nabu); RegionsExtension also installs it as nabu.regions.
• Todos Document-level reactive registry of all to-do items (checklist list-items). Pure derived view over the block tree — stores nothing in Loro. Lazy: obtain via Todos.get(nabu).

Components 1

• NabuEditor The contenteditable root: renders the document of an editor and wires every event to the engine.

Constants 31

• BlockExtension The block:transform action: turn a block into another type (exec('block:transform', { type, props })). The block extensions' own actions (heading:1, callout...) and the slash menu go through it.
• BlockquoteExtension The quote block: the > shortcut, Backspace and Enter de-transformations, markdown and HTML paste rules, and the "Quote" slash entry.
• CalloutExtension The callout block (note, tip, important, warning, caution variants): the ! shortcut, the callout action and the "Callout" slash entry.
• CLIPBOARD_FORMAT_VERSION Current version of the application/x-nabu+json clipboard format (see docs/design/clipboard-format.md). Written on copy as version; the Nabu paste interpreter accepts it (and fragments without a version).
• CodeExtension The code block: plain monospace text with a language, the ``` shortcut, the code:block action and the "Code" slash entry.
• createRegionsExtension Alias following the createXxxExtension naming of the other factories.
• DEFAULT_REGION_MESSAGES The default texts of the regions: command labels, the seam and end marker wording, the chooser and the hold prompt (English). Override any key with RegionsExtension({ messages }).
• DEFAULT_REGION_TYPES Default types: ONE generic section division over three levels, as three types (the level IS the type: changing the level of a region = changing its type, ADR 016 §3.4). Labels "1.", "1.1", "1.1.1".
• DialogueExtension Default instance (dash –).
• DividerExtension The divider block (a horizontal rule): the --- shortcut, markdown and HTML paste rules, and the "Divider" slash entry.
• DocumentPreset Paragraph + headings + rich text. Document-like, no lists.
• FileExtension The file block: an attachment (name, size, download link) stored through the files option; the file:* actions, file paste for any file type and the "File" slash entry.
• FullPreset All built-in block types + rich text.
• HeadingExtension The heading block (levels 1 to 6): the # shortcuts, the heading:1 to heading:6 actions and the "Heading" slash entries.
• HtmlPasteExtension Paste of text/html (web pages, Google Docs, Word, spreadsheets): turns the markup into blocks through the rules the registered block classes declare (htmlRules).
• ImageExtension The image block: stored through the files option, with the image:insert and image:pick actions, image file paste and the "Image" slash entry.
• JSON_FORMAT_VERSION Version written by serialize('json') (document export). importJSON reads this one (a missing version is read as it).
• ListExtension The list container (bulleted, numbered or to-do): the list:* actions, Tab and Shift+Tab indentation over a selection, and the list slash entries. Always loaded together with ListItemExtension.
• ListItemExtension The list item block: Enter, Backspace and Tab behaviour inside lists, the to-do checkbox and todo:toggle (Mod-Enter). Always loaded together with ListExtension.
• MarkdownPasteExtension Paste of markdown typed as text/plain: parses it into blocks and inline marks through the rules the registered block classes declare (markdownRules). It also powers importMarkdown().
• MarkdownShortcutsExtension Inline markdown shortcuts while typing: **bold**, _italic_, `code`, ~~strike~~ turn into marks as the closing delimiter is typed.
• MinimalPreset Paragraph only. The simplest possible editor.
• NabuPasteExtension Paste of application/x-nabu+json, the format Nabu writes on copy and cut: copying between Nabu editors keeps the block structure, marks and files.
• ParagraphExtension The paragraph block, the default text block: the paragraph action (turn a block back into text) and the "Text" slash entry.
• PlainTextPasteExtension Interprète text/plain comme du texte pur. - Chaque ligne non vide → un bloc (une ligne = un bloc) - Les lignes vides ne sont que des séparateurs (aucun paragraphe vide) Priorité 0 (fallback de dernier recours).
• REASON_CODES The stable codes of FileReason.
• RichTextExtension The inline marks (bold, italic, underline, code, strikethrough) and links: the mark:* and link:* actions and their keyboard shortcuts.
• TextPreset Paragraph + rich text marks (bold, italic, underline, code, strikethrough).
• ToggleExtension The toggle block: a collapsible container with its own header text and a body of child blocks; the toggle action and the "Toggle" slash entry.
• TypographyExtension Smart typography input rules. Currently: -- → — (em-dash substitution while typing). A longer run of dashes (--- , a divider-like -----) is left alone: the -- must not be preceded by another -.
• VideoExtension The video block: stored through the files option, with the video:insert and video:pick actions, video file paste and the "Video" slash entry.

Types 29

• Chord A parsed key chord: a key and its four modifiers (Mod is resolved to ctrl or meta for the platform).
• CommandConfirm
• CommandConfirmOptions
• CommandContext What the engine builds at each key press (and for nabu.exec of a command, with event: null). Extensions add FACTS (any other property) through Extension#commandContext; facts never replace the fields below.
• CommandDef A command: a label, optional default keys, a when condition, a scope and a run function. Declared by extensions (ExtensionInit.commands); every command is also an action of the bus (nabu.exec(id, data)).
• CommandInfo What nabu.commands.list() / get() return: a plain snapshot (the registry is fixed once the editor is built, so it needs no reactivity; read it again after a keymap change, i.e. a new editor).
• CompactOptions
• CompactResult
• ConfirmMessages
• EditorOptions Options of the editor factories: every NabuInit option (files, placeholders, snapshot, keymap, tab, lang…, forwarded to Nabu) plus the preset the factory starts from. extensions are appended to the preset's. - preset: base extensions (default: FullPreset, or the preset of the named factory). - tab: default by preset: Minimal / Text 'focus', Document / Full 'stay', a custom preset array 'focus'.
• EmbeddedAsset
• FieldKind
• FieldSpec
• FilesConfig
• HistoryConfig
• NabuInit The options of an editor: the extensions to load, an initial snapshot, files, placeholders, readonly, language, Tab behaviour, keymap and command confirmation. Accepted by new Nabu(init), by createEditor and the preset factories, and by createPersistedEditor.
• Numbering
• PlaceholdersConfig
• PlaceholdersOption
• PlaceholderText A string, false (no placeholder) or a function of the block returning one of those.
• Platform The platform whose conventions Mod and the displayed shortcuts follow: 'mac' (Cmd) or 'other' (Ctrl).
• Recovery What happened when a stored document could not be read (ADR 010, theme 8). Exposed as nabu.persistence.recovery and given to the onRecover option, so the host can tell the user.
• RegionMessageParams
• RegionMessages
• RegionNameParams
• RegionsConfig
• RegionTypeDef
• RegionTypeInit
• RegionTypeParams

@aionbuilders/nabu/ui

The optional UI: formatting toolbar, slash menu, drag handle and command-confirmation surfaces.

Classes 1

• SlashMenuController The state of the "/" menu for one editor: whether it is open, the query typed after the slash, the filtered and sorted entries and the selected one. SlashMenu is its default rendering; use it directly to build your own menu.

Components 5

• CommandChooser Default NEUTRAL rendering of the choose strategy (ADR 017 §3.4c): a list at the caret. The keyboard (arrows, Enter, digits 1-9, Escape) is handled by the engine while the chooser is pending; this component renders the state and takes the mouse. The editor keeps the focus, so options are not tabbable: the highlighted one is announced by the live region.
• CommandInvite true always shows it; false never (the target draws everything).
• DragHandle The handle shown next to a block to drag it elsewhere in the document.
• FloatingToolbar Floating mark toolbar. Appears above the current (non-collapsed) selection. Positioned with position: fixed in viewport coordinates, so it works inside any layout (scrollable containers, overflow: hidden ancestors…) without a positioning wrapper.
• SlashMenu The "/" menu: a filterable list of blocks to insert, anchored at the caret.

Types 1

• SlashCommand An entry of the slash menu: a title, optional subtitle, icon and aliases to filter on, a group and order for sorting, an optional when to limit where it is offered, and the action to run. Extensions contribute theirs with slashCommands.

@aionbuilders/nabu/extend

The extension() factory, the block base classes, the text behavior and the stable contract of a third-party block.

Functions 11

• canonicalChord Parse then canonicalize a chord string.
• chordId The canonical string of a chord: Ctrl-Alt-Shift-Meta-<key>.
• detectPlatform Detect the platform whose conventions Mod and the displayed shortcuts follow: Cmd on macOS and iOS, Ctrl everywhere else.
• escapeAttr Escape a value for a quoted HTML attribute. Same table as escapeHtml; kept as a distinct name so the call sites say what they mean.
• escapeHtml Escape text for use as HTML text content OR inside a quoted attribute value (& < > " ').
• eventChord Normalize a keyboard event to a chord, with the rules of the module doc.
• eventChordId The canonical string of a keyboard event (see eventChord), or null.
• extension Create an extension: the unit that bundles a block type, its component, hooks, commands, actions, paste handlers and slash entries. Shorthand for new Extension(name, init).
• hasCommandModifier Whether the chord carries a modifier that makes it a shortcut rather than typing: Ctrl, Alt or Meta. Shift alone does not (Shift+letter is a capital letter).
• isReservedChord Whether a chord is reserved by the browser or the OS (close tab, reload, quit...) and so refused when a command declares it.
• parseChord Parse a chord string. Returns null for anything invalid: empty, unknown key name, unknown/duplicated modifier, or Shift on a digit/symbol (see the module doc).

Classes 8

• Block The base class of every block. A block wraps a node of the document tree (Loro) and holds the behaviour of one block type: the capability flags, the tree accessors, and the handlers for typing, keys, splitting, merging, pasting and serialization that a subclass overrides.
• CommandRegistry Holds the commands of an editor (nabu.commands is its public face): registers them from the extensions, resolves the keymap and the key chords at keydown, and answers list, get, has and run.
• Extension A named bundle of editor behaviour (see ExtensionInit); the built-in blocks and behaviours are extensions. Build one with extension(name, init) and pass it to createEditor({ extensions }).
• MegaBlock A block that holds child blocks (a container): list, list item, toggle, region. It keeps its children in sync with the tree and delegates positions, word count and event handling to them.
• NabuSelection Utilitaire réactif pour gérer la sélection de texte avec Svelte 5 runes
• SvelteSelection Utilitaire réactif pour gérer la sélection de texte avec Svelte 5 runes
• TextBehavior The editing of a block's rich text: wraps a Loro text and offers the reactive text and delta, the selection in that text, and insertion, deletion, splitting, marks and links. Text blocks use it through TextBlock; a container with a header (list item, toggle) owns one.
• TextBlock Base class for purely textual blocks (paragraph, heading, dialogue…). Owns a single TextBehavior and proxies the standard Block text API to it, removing the proxy boilerplate previously duplicated in every text block.

Components 2

• BlockComponent Renders one block with the component its extension registered. Used by container blocks to render their children.
• RichText Renders the delta of a text block: marks, links and the trailing-line filler.

Constants 1

• RESERVED_CHORDS Chords the browser or the OS keeps for itself (tabs, windows, quit, reload, address bar, devtools, zoom, tab switching): a page often cannot intercept them, and stealing them would be hostile anyway. Commands cannot bind them (refused at registration with a warning). Written with Mod, resolved per platform by reservedChords.

Types 20

• Chord A parsed key chord: a key and its four modifiers (Mod is resolved to ctrl or meta for the platform).
• CommandContext What the engine builds at each key press (and for nabu.exec of a command, with event: null). Extensions add FACTS (any other property) through Extension#commandContext; facts never replace the fields below.
• CommandDef A command: a label, optional default keys, a when condition, a scope and a run function. Declared by extensions (ExtensionInit.commands); every command is also an action of the bus (nabu.exec(id, data)).
• ExtensionHooks The hooks an extension can register (ExtensionInit.hooks). A hook returns nabu.BREAK (or, for onSplit, an object) to stop the engine from going on; the others return nothing. Any other name is a custom hook, run with nabu.trigger(name, ...args). Declared as methods, so a handler may narrow the block parameter ((nabu, block: Paragraph) => ...).
• ExtensionInit What an extension is made of: a block class and its component, hooks, serializers, actions, commands, paste interpreters and file handlers, input rules, slash menu entries and Loro text styles. Every field is optional; pass it to extension(name, init).
• HtmlHelpers
• HtmlRule selector is a CSS selector tested with el.matches(). priority: higher is tried first (a specific block beats a generic fallback). filter: an extra test once the selector matches. embed: the element may sit inside the inline content of another block and is then lifted out as a block of its own. props: props the rule asks fromHTML to set.
• InputRule A declarative text-replacement rule applied while typing: when the text before the caret matches pattern, handler runs (the markdown shortcuts and the typography substitutions are input rules).
• MarkdownHelpers
• MarkdownRule detect: does the block start at this line. consume: how many lines it takes from index (at least 1). priority: higher is tried first. interruptsParagraph: the block may start in the middle of a paragraph (a fence, a heading, a quote...); true means "whenever detect matches".
• NabuInternals The engine machinery behind Nabu#internals. Unstable: may change in any version (see docs/guides/extensions.md, "Stability"). Methods are bound to the editor; their signatures are those of the Nabu methods of the same name.
• NabuNode
• PasteBlock
• PasteFileHandler What an extension does with a FILE pasted from the clipboard (a screenshot, a file copied from the OS): it makes a block of it. The engine reads the bytes, stores them through Files (in the document, or sent to files.onBeforePersist with the optimistic pending block) and inserts the blocks at the caret, in the order of the files, as ONE undo step. The engine names no block type: whatever an extension accepts is its own business.
• PasteFragment
• PasteInterpreter
• PasteInterpretOptions
• Platform The platform whose conventions Mod and the displayed shortcuts follow: 'mac' (Cmd) or 'other' (Ctrl).
• SerializeContext recurse: serialize one child block. recurseAll (markdown only): serialize siblings in order, telling each its neighbours. before / after (markdown only): the siblings around this block.
• SplitData What onSplit receives besides the block: where the text is cut, and the tail that moves to the new block.