Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Notebook Core Package (@lapis-notes/notebook-core)

@lapis-notes/notebook-core is the first extracted package from the notebook runtime refactor. It owns reusable notebook contracts that do not depend on the bundled product plugin, Svelte views, DuckDB-Wasm, workers, or @lapis-notes/api.

Source: packages/notebook/core/src/

Current Scope

The package currently exports:

  • the notebook output protocol for text, markdown, HTML, structured input outputs, trusted live DOM, table, chart, image, and error outputs
  • notebook cell, document, block, and frontmatter model contracts
  • notebook session state, run-state, checkpoint, setup-phase, and progress-event contracts
  • table metadata types used by DuckDB-backed query output normalization and dataframe rendering
  • runtime feature flags used by worker policy and runtime routing code, including the distinction between broad DOM-related helper usage and live browser DOM requirements
  • generic notebook execution result/options contracts, including a typed runtime dependency loader hook, a host-neutral notebook file reader provider contract, and a JavaScript-like compile provider contract for TypeScript/ESM rewriting hosts
  • generic notebook graph types and pure graph helpers for graph construction from analyzed cells, dependency closure, stale descendant collection, duplicate-definition detection, topological order, and cycle detection
  • pure language-service projection helpers that concatenate TypeScript cells into a virtual TypeScript document and map provider positions/ranges back to cell-local coordinates
  • subpath exports for @lapis-notes/notebook-core/execution, @lapis-notes/notebook-core/graph, @lapis-notes/notebook-core/language-service, @lapis-notes/notebook-core/model, @lapis-notes/notebook-core/outputs, @lapis-notes/notebook-core/runtime-features, and @lapis-notes/notebook-core/session

The bundled notebook product plugin still owns notebook parsing, frontmatter normalization, analyzer selection, UI, the concrete NotebookSession runtime, persistence, worker selection, DuckDB runtime setup, and command wiring. It consumes and re-exports the core model/output/session protocol through compatibility shims and binds core graph construction to the current TypeScript, SQL, and markdown analyzers through a product-plugin wrapper.

Notebook execution provider contracts live here when they are host-neutral. The file reader provider receives notebook paths plus the source note path so browser, worker, and future desktop hosts can preserve notebook-relative syntax while swapping the underlying file-read implementation. The JavaScript-like compile provider receives the original JavaScript or TypeScript cell source plus source/cell metadata and returns executable source with any static notebook import rewrites already applied. Browser execution continues to use the product plugin’s default vault reader and lazy TypeScript compiler when no providers are injected.

Boundary Rules

Notebook core must stay host-neutral and startup-cheap.

  • Do not import Svelte, @lapis-notes/api, DuckDB-Wasm, htl, Observable inputs, d3, Plot, or worker entry points from this package.
  • Keep exports focused on stable contracts and pure helper functions that are not notebook-authored builtin implementations.
  • Move additional runtime contracts here only when they can be extracted without carrying product-plugin lifecycle or host dependencies with them.

Follow-Up Direction

Additional host-neutral contracts can move here later if they emerge from the notebook product runtime, but the current package-split plan does not require another core extraction before the product plugin can continue owning concrete runtime behavior.

The current output protocol now reserves a first-class input output kind for reconstructable notebook controls. That contract is host-neutral: it describes the persisted control artifact, including the owning cell id, exported variable name, input type, current scalar value, optional serializable config, reconstructable flag, and optional source metadata. Live DOM nodes remain out of scope for notebook core and continue to be represented separately as ephemeral dom outputs.