API Architecture Reference

Reference

[1]

Sci-Notebook Architecture

Sci-Notebook is a framework-agnostic scientific notebook engine built entirely in TypeScript. It runs 100% in the browser with zero server dependencies.

[2]

graph TD
    subgraph UI[UI Adapters]
        React[React 18+] --- Vue[Vue 3+] --- Svelte[Svelte 5+] --- Vanilla[Vanilla JS]
    end

    subgraph Pipeline[Rendering Pipeline]
        MD[Markdown-it] --> AST[AST] --> Trans[Transformers] --> HTML[HTML + Shiki]
    end

    subgraph Core[Core Engine]
        Engine[EditorEngine] --- EventBus[EventBus]
        History[History] --- Keybindings[Keybindings]
        Version[VersionHistory] --- Mobile[MobileAdapter]
    end

    subgraph Plugins[Plugin System]
        LaTeX[LaTeX] --- Export[Export]
    end

    UI --> Pipeline
    Pipeline --> Core
    Core --> Plugins

    style UI fill:transparent,stroke-dasharray: 5 5
    style Pipeline fill:transparent,stroke-dasharray: 5 5
    style Core fill:transparent,stroke-dasharray: 5 5
    style Plugins fill:transparent,stroke-dasharray: 5 5

Mermaid not available. Import mermaid and expose it as globalThis.mermaid.

[3]

Package Structure

Package	Description	Size
@velo-sci/notebook-core	Document model, engine, events, presentation, mobile	~45KB
@velo-sci/notebook-renderer	Markdown→HTML pipeline, Shiki highlighting	~30KB
@velo-sci/notebook-react	React 18+ adapter, hooks, components	~80KB
@velo-sci/notebook-vue	Vue 3+ adapter, composables	~15KB
@velo-sci/notebook-svelte	Svelte 5+ adapter, stores	~10KB
@velo-sci/notebook-vanilla	Vanilla JS adapter, DOM renderer	~20KB
@velo-sci/notebook-plugin-export	PDF/DOCX export	~12KB

[4]

Unidirectional Data Flow

[5]

graph LR
  A[User Action] --> B[EditorEngine]
  B --> C[State Mutation]
  C --> D[EventBus]
  D --> E[Framework Adapter]
  E --> F[RenderPipeline]
  F --> G[HTML Output]
  G --> H[DOM Update]

Mermaid not available. Import mermaid and expose it as globalThis.mermaid.

[6]

1. User Interaction → triggers a command in EditorEngine
2. State Mutation → engine updates the immutable Notebook state
3. Event Emission → engine emits notebook:updated via EventBus
4. Reactive Update → framework adapter catches event, triggers re-render
5. Rendering Pipeline → RenderPipeline processes cells (with LRU cache) → HTML

[7]

import { createNotebook, EditorEngine } from '@velo-sci/notebook-core';

// Create an engine from a notebook
const engine: EditorEngine = createNotebook({
  notebook: myNotebook,
  config: { plugins: [latexPlugin, exportPlugin] }
});

// Cell operations
engine.insertCell(0, 'markdown', '# New Section');
engine.updateCellSource('cell-id', 'Updated content');
engine.deleteCell('cell-id');
engine.moveCell('cell-id', 3);

// History
engine.undo();
engine.redo();

// Events
engine.on('notebook:updated', (payload) => {
  console.log('Notebook changed:', payload.data.notebook);
});

[8]

Design Principles

Principle	Description
Instant feedback	Every action produces visual result in <16ms
Zero friction	Never more than 2 clicks for common operations
Keyboard-first	Everything accessible by keyboard
Offline-first	Works without connection, syncs when online
Composable	Every feature is an opt-in plugin, tree-shakeable
Framework agnostic	Core has zero framework dependencies
Open	Standard JSON format, MIT license, no vendor lock-in