Nabu

What a hook or an onBeforeInput handler returns to stop the engine (and the hooks after it).

What a hook returns to let the engine go on (same as returning nothing).

Every live block of the document, by tree id.

The live blocks of each type (reactive sets, by block type).

Nabu.BREAK, reachable from the instance a hook receives.

The root blocks of the document, in order (reactive).

Commands and keyboard shortcuts (ADR 017): list(), get(id), has(id), run(id, data), offer(id). A plain snapshot API; the set of commands is fixed once the editor is built.

The Svelte components registered by the loaded extensions, by block type.

Nabu.CONTINUE, reachable from the instance a hook receives.

When true, nabu.warn() logs to the console ([Nabu]).

Type of the default text block (declared by an extension with defaultBlock: true): created by the engine when it needs an empty text block of its own, e.g. a caret after a trailing void block.

The Loro document behind the editor (public: connect it to a server with doc.subscribeLocalUpdates and importRemote).

The extensions the editor was built with, in order.

Resolved placeholders option (see NabuInit). Reassign to change it at runtime.

Number of caret positions in the document (the sum of the root blocks').

The block classes registered by the loaded extensions, by block type.

The text selection of the editor (a reactive wrapper of the DOM selection, in terms of blocks).

Root-level serializers. Each function receives the Nabu instance and returns the serialized document.

Slash-menu entries contributed by extensions (Extension#slashCommands); the slash menu lists ONLY these (plus the integrator's extras), sorted by group / order, keeping those whose when(engine, block) holds at the caret.

Resolved spellcheck option (see NabuInit). Reactive: assign to change it at runtime.

Registered subsystems. Each system should implement:

• start(): void — called when the editor mounts
• stop(): void — called when the editor unmounts

Announcement of the Escape-then-Tab way out (option tabHint), false for none. Reactive.

The document tree (Loro): one node per block, node.data holds the block's type and props.

Text of the polite live region of the editor (prompts and outcomes of confirmations). Reactive.

True during an IME composition: the browser owns the DOM, the caret must not be touched.

The block holding the running composition, or null. Reactive.

The door to everything the engine uses internally that the stable contract (the members tagged public in their JSDoc) does not cover: the command-confirm controller, the action bus, the hook and rule registries, the clipboard / drop / event pipelines, undo capture, stored marks, the selection's repair machinery. They are the same references the engine runs on, not copies.

The door itself is part of the stable contract; @unstable is everything behind it: nothing reached through internals is a promise, it may change, move or disappear in ANY minor version. Prefer the stable members; use this when you must, and pin the version of the package. The set of keys is frozen by a test, so a change shows up in the changelog.

True when the document has no block.

Resolved lang option (see NabuInit): a valid BCP 47 tag, or undefined (inherit the page language). Reactive: assign to change it at runtime; an invalid value is ignored (warning) and leaves it unchanged.

The deepest last block of the document that can hold a caret in the rendered document: follows the last child at each level, but never enters a block that hides its children.

The command waiting for the user's confirmation (ADR 017 §3.4), reactive; null when none: { id, strategy: 'hold' | 'invite' | 'choose', label, display, message, target?, progress, options?, selectedIndex }. progress (hold, 0 → 1) and selectedIndex (choose) are reactive fields of that object.

Read-only mode (see the readonly option of NabuInit). Reactive: assign to switch it on or off at runtime. While true the user cannot change the document: input, paste, cut, drop, drag moves and commands (shortcuts, commands.run, exec of a command, undo / redo) are ignored by the engine, and the UI components hide themselves. Programmatic edits by the host (insert, importJSON...) are not blocked. View state that is not part of the document (a toggle opened to read it) stays possible and is never written to the document.

Resolved tab option (see NabuInit): what Tab / Shift+Tab do in a plain text block. Reactive: assign to change it at runtime; an unknown value warns and gives the default of the editor (its preset).

Cancel the pending confirmation, if any: nothing runs.

Commit the pending changes as one Loro transaction.

Creates a block inside a container, recursively handling nested children. Public: part of the paste toolbox a block's acceptPaste hook builds on. No commit.

the created block

Delete a block (and its children) from the tree. No commit: call commit() afterwards.

Dispatch an action to all registered handlers for the given topic. Re-syncs the model selection from the DOM first: selectionchange is async, so right after a keyboard-only selection change (Shift+Arrow, Home/End, Ctrl+A) the model would be stale.

Place the DOM + model selection. Asynchronous by nature: it waits for Svelte to flush pending state (tick()), because the target blocks' DOM may not be rendered yet (e.g. right after a commit/insert). The returned promise resolves once the selection has been set, i.e. once nabu.selection reflects it: await nabu.focus(...) before exec(...) / typing. Fire-and-forget callers are unaffected.

Replace the entire document with the given PasteFragment. Unlike insertFragment(), this does not depend on a live DOM selection: blocks are created at the root through the same registry pipeline as paste.

Replace the entire document with a serialize('json') export. An export of a version this editor does not know is refused with a warning (the document is left untouched), like the clipboard does; a block type that is not registered is degraded to the default text block (degradeUnknownBlocks), nothing is dropped.

Replace the entire document with content parsed from a Markdown string. Requires MarkdownPasteExtension (or any text/plain interpreter) to be loaded.

Import changes made ELSEWHERE (another tab, a peer, a stored copy of the document: ADR 010 multi-tab sync). They are the document's own history, not the user's actions: Loro's UndoManager records local commits only, so an import is never an undo step (undoing the user's own edits afterwards still works, Loro transforms them). The DOM follows through the normal Loro events. The caret of the local user stays on the same CHARACTER: it is captured as Loro cursors before the import and put back after the render (a text node rewritten by Svelte would otherwise send it to the start of the block); the page is never scrolled for it. Idempotent (importing what the document already has changes nothing). Called DURING an IME composition it is applied at once (not held): the model is safe, because the composition anchor is a Loro cursor that follows the edit, and the caret restore is skipped meanwhile (the browser owns it). (persistence/sync.js still holds the updates it receives while composing, which keeps the composing text node untouched by the render.)

Insert a new block of a registered type and commit (throws when the type is not registered).

The created block

Inserts a PasteBlock after afterNode. Handles both leaf blocks (wrapOrphan) and container blocks (creates container, recurses into children). Returns the outer node to use as the next prevNode. Public: part of the paste toolbox a block's acceptPaste hook builds on. No commit.

True when every selected text run carries the given mark. Reactive: reads block.selected and the behaviors' selections/deltas, so it can be used directly in component templates (e.g. FloatingToolbar).

Make the NEXT commit its own undo step (and the typing right after it another one), even though it holds no structural op: for a non-structural change that must undo on its own, e.g. a flag toggled from the keyboard, which would otherwise merge with the typing around it. Call it just before commit().

The document must always offer a caret after its last block. Call it on user intent (ArrowDown / ArrowRight leaving the document, a click below the last block): when the last block holds text, the caret goes to its end; when it does not (a void block such as a divider / image, or a container whose end is not a text position), an empty default text block is appended at the root, in one undo step, and takes the caret. Never called eagerly on load.

The block now holding the caret

The pending confirmation when it is ABOUT target (what confirm.target(ctx) returned: usually a block), else null. Reactive: a block that draws its own hold progress reads nabu.pendingCommandOn(block)?.progress.

Redo the last undone operation. The selection comes back where that operation ended.

The block and local offset that hold a document-wide caret offset (positions counted from the start of the document).

Serialize the document with the root serializer registered for format ('markdown', 'json', or one an extension adds with serializers); null (and a warning) for an unknown format.

Apply a markdown BLOCK shortcut (# , - , > , --- …) so that undo gives back exactly what the user typed, trigger included: one Ctrl+Z after # leaves a paragraph "# " with the caret after the space; a second one removes the typing as usual.

1. trigger (the swallowed space) is inserted at the caret and committed like normal typing;
2. transform runs (delete the prefix incl. the trigger, change/replace the block…) and is committed as its own structural undo step (see commit()), whose stored caret is right after the trigger. Both commits run in the same synchronous turn, so the intermediate "# " is never painted.

For a trigger that is not text (``` + Enter), pass trigger = '': nothing is inserted and undo restores the text typed before the key (the fence line, without the Enter).

resolves immediately, doing nothing, when block.transformsEnabled === false

Run Loro mutations as a single transaction, then optionally restore the cursor. Centralizes the "mutate → commit → setCursor" dance used by most actions.

Run the hookName hooks of every extension, in order, until one returns BREAK. Each is called as hook(nabu, ...args).

Undo the last operation. The selection as it was before that operation comes back (see ADR 015).

Log a diagnostic to the console when debugging is on. Silent otherwise.