Core API Reference

Editor Engine & Core Reference

Reference

[1]

Core Engine API

The @velo-sci/notebook-core package contains the fundamental data models and the state engine for managing scientific notebooks.

[2]

Dual-Mode System

Each cell independently tracks its mode (editing field on the Cell model).

Edit mode:

• The cell renders a text editor (textarea, CodeMirror, Monaco, or adapter-provided input)
• Raw Markdown/LaTeX/Mermaid source is visible
• Syntax highlighting is active (via adapter or plugin)

View mode:

• The cell’s source is passed through the rendering pipeline
• The rendered output (HTML) replaces the editor
• Clicking the rendered cell switches it back to edit mode

Mode Transitions

┌──────────┐  click / Enter / dblclick  ┌──────────┐
│   VIEW   │ ─────────────────────────► │   EDIT   │
│   mode   │                            │   mode   │
│          │ ◄───────────────────────── │          │
└──────────┘  Escape / blur / Cmd+Enter └──────────┘

Notebook-Level Mode

• setAllEditMode() — every cell enters edit mode (raw MD view)
• setAllViewMode() — every cell enters view mode (rendered)

[3]

// Selection Model
interface SelectionState {
  focusedCellId: string | null;
  selectedCellIds: Set<string>;
  cursorOffset: number | null;
  textSelection: { start: number; end: number } | null;
}

// Navigation rules:
// ArrowUp at top of cell → focus previous cell (cursor at end)
// ArrowDown at bottom → focus next cell (cursor at start)
// Shift+ArrowUp/Down → extend cell selection
// Cmd/Ctrl+A → select all cells
// Tab → indent (edit mode) or focus next cell (view mode)

[4]

// Undo/Redo — Command Pattern
interface Command {
  label: string;
  execute(): void;
  undo(): void;
}

// Rapid keystrokes batched into one undo entry (debounce 300ms)
// checkpoint() forces a new undo boundary

// HistoryManager maintains a stack of Command objects
// maxHistory limits the stack depth (default: 100)

[5]

Default Keybindings

Key	Action	Context
Enter	Enter edit mode on focused cell	view mode
Escape	Exit edit mode	edit mode
Cmd+Enter	Run cell & advance (if plugin)	edit mode
Shift+Enter	Exit edit mode & focus next	edit mode
ArrowUp/Down	Navigate cells	view mode
Cmd+Shift+D	Delete focused cell	any
Cmd+Shift+ArrowUp	Move cell up	any
Cmd+Shift+ArrowDown	Move cell down	any
Cmd+Z	Undo	any
Cmd+Shift+Z	Redo	any
Cmd+B	Toggle bold (insert **)	edit mode
Cmd+I	Toggle italic (insert *)	edit mode
Cmd+K	Insert link	edit mode
Cmd+/	Toggle cell type (md / code)	any

Plugins can register additional keybindings via plugin.keybindings.

[6]

Cell Split & Merge

Split (Cmd+Shift+Enter): source is split at cursorOffset, original keeps text before cursor, new cell gets text after. Both inherit the same type.

Merge Up (Backspace at cell start): current cell’s source appended to previous, current deleted.

Merge Down (Delete at cell end): symmetric to merge up.

[7]

// Event Bus — all events
type EventType =
  | "cell:created" | "cell:deleted" | "cell:updated"
  | "cell:moved" | "cell:mode-changed" | "cell:focused"
  | "selection:changed"
  | "history:undo" | "history:redo" | "history:checkpoint"
  | "notebook:updated"
  | "plugin:registered" | "plugin:unregistered"
  | string; // plugins can emit custom events

// Bus is synchronous by default.
// Async listeners can wrap in queueMicrotask.

// Drag & Drop: actual DOM drag handling is implemented by
// each framework adapter. The engine only tracks state
// and emits "cell:moved" events.