@lapis-notes/lapis-plugin-notebook

v0.1.0

Published

18 hours ago

Executable .notebook.md notebooks with reactive cells and rich outputs for Lapis Notes

0High
0Medium
0Low

`@lapis-notes/lapis-plugin-notebook`

First-party external Notebook plugin for Lapis. It ports the legacy @lapis-notes/notebook plugin: executable .notebook.md Markdown documents with reactive cells, rich outputs, interactive inputs, and DuckDB queries, presented through public @lapismd/design-core surfaces inside the host workspace.

The plugin owns notebook documents, execution, panels, and settings. Hosts own routing, vault state, persistence, and application policy.

Current package status

Public package: @lapis-notes/[email protected]. The repository validates against published registry dependencies.
Runtime plugin id: lapis-notebook (preserved from the legacy plugin so persisted plugin-data keys stay compatible).
Runtime peers: @lapis-notes/api@^0.2.2, @lapis-notes/markdown@^0.2.0, @lapismd/design-core@^0.7.2, @lapis-notes/ui@^0.1.5, svelte@^5.
Canonical repository: lapismd/lapis-plugin-notebook.
Live catalog: https://lapismd.github.io/lapis-plugin-notebook/.
The port is staged per spec/src/plugins/notebook/; verification statuses in spec/src/verification.md track exactly which stage has landed.

Install

Hosts load the plugin class through the Lapis plugin lifecycle; onload registers the notebook editor view, commands, settings tab, and panels.

pnpm add @lapis-notes/lapis-plugin-notebook

Import the plugin stylesheet once at the application boundary:

import "@lapis-notes/lapis-plugin-notebook/styles.css";

Runtime surfaces

| Surface | Entry | Use for | | ---------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | Notebook view | *.notebook.md exclusive editor-view contribution | Cell rendering, source/preview modes, run-all header action, inline editors | | Execution | Shared engine with Web Worker transport and in-process fallback | TypeScript/JavaScript, SQL, and Markdown/HTML cells with dependency-graph ordering | | Inputs | packages/input DOM runtime on Design Core primitives | viewof text/table/range and every UI-backed input factory with targeted reruns | | DuckDB | packages/duckdb on pinned DuckDB-WASM | SQL cells over app snapshot tables (lapis.notes, lapis.links, lapis.search_documents) | | Panels | Variables, Dependencies, and Packages right-sidebar views | Data-source inspection, dependency graphs, and npm package management | | Default grouping | Notebook sidebar group seeded from layout state | One right-sidebar group presenting Variables, Dependencies, and Packages together | | Settings | Versioned plugin data plus settings tab | Execution, autorun, and panel auto-open policy |

Cell and output coverage

Embed a rendered notebook in another note with ![[Analysis.notebook.md]]. The embed shows notebook prose and available cell outputs, with an action to open the source notebook. Saved results restore without running cells; first execution remains manual. Repeated embeds share input values while keeping separate controls.

Cells execute through one shared engine reachable over two transports: a dedicated module Web Worker for eligible notebooks and an in-process fallback for notebooks that need DuckDB, live DOM outputs, or host-only providers. Reactivity is Lapis-owned and explicit — a marimo/Pluto-style dependency graph reruns or marks stale descendants; there is no implicit observer runtime. Generated outputs persist as typed generated state through the host appDatabase notebook-state contract, shared by web, desktop, and hosted Rust back ends.

Styling contract

The plugin uses native CSS, Design Core semantic tokens, and notebook-owned notebook- prefixed classes. Production sources stay free of Tailwind utility strings (pnpm check:no-tailwind).

Import @lapis-notes/lapis-plugin-notebook/styles.css once.
Theme through Design Core tokens; the notebook layer rebinds public custom properties (editor surfaces, table previews, status palette) at its own boundaries.
Do not style private production selectors to make a story or host look correct.

Status tones use a static AA-contrast palette with .dark overrides; section anatomy paints grey full-bleed headers over white bodies.

Layout conventions

src/
  lib/            plugin class, settings, views, render layer, panels, styles
  stories/        App-backed shell stories, panel placement stories, demos
packages/
  notebook-core/  host-neutral document model, graph, and stdlib
  notebook-stdlib/
  notebook-input/ lazy DOM input runtime
  notebook-duckdb/
  notebook-duckdb-assets/
  notebook-worker/ transport-only worker entry
spec/
  src/            canonical specification (mdBook)
  records/        slice and acceptance records
stories/
  catalog/        story parity and taxonomy declarations

Private support packages keep host-neutrality boundaries (LN-NB-027) and resolve from TypeScript source through shared Vite/tsconfig plumbing, so the published root manifest stays free of workspace: dependencies.

Usage example

A notebook document is ordinary Markdown with :::cell directives:

---
notebook:
  autorun: true
---

:::cell{#calc lang="ts"}

```ts
const answer = 6 * 7;
display(`The answer is ${answer}.`);
```

:::

:::cell{#query lang="sql"}

```sql
SELECT count(*) AS note_count FROM lapis.notes;
```

:::

Interactive inputs use viewof cells; dependencies rerun targeted downstream cells on change.

Storybook and local documentation

Run the local catalog (defaults to port 7040):

pnpm storybook
pnpm storybook:stop
pnpm storybook:restart

Build the static catalog:

pnpm build-storybook

The canonical specification lives in spec/src. Prefer QMD-backed search for locating requirements and guidance, and keep the wiring healthy after tooling updates:

pnpm spec:search -- "panel group"
pnpm spec:search -- "worker transport" --semantic
pnpm spec:index
pnpm exec spec-validator doctor
pnpm spec:check

CI and local parity

Portable validation defaults to the fail-closed Docker runner (scripts/validation.mjs); Docker failure never falls back to the host. See docs/validation.md for contexts, reports, and owned cleanup. Native diagnosis requires the explicit LAPIS_NOTEBOOK_VALIDATION_RUNTIME=native override.

pnpm test:storybook runs the Storybook Vitest project in sequential shards, each with a fresh browser process and one worker, mirroring the Tasks mitigation for intermittent orchestrator transport drops. Keep the unbatched command available for diagnosis.

CI runs the validation, specification, quality, unit, build, publint, and Storybook interaction and static-build lanes on every pull request and push to main, and publishes the static catalog to GitHub Pages from main.

Refreshing local development dependencies

When the sibling repositories are present, .pnpmfile.cjs installs local package snapshots for development acceptance. These snapshots need refreshing after sibling source or public exports change. If Storybook reports missing files that exist in the owning repository, stop it and refresh the snapshots:

pnpm storybook:stop
pnpm install --lockfile=false --force
pnpm test
pnpm test:storybook
pnpm storybook

This temporary local validation setup leaves the registry lockfile unchanged. Validate releases and CI against the published registry dependencies.

The preview inherits DM Sans Variable and Source Code Pro Variable from Design Core, matching the Lapis hosts.

Release and validation

Common validation commands:

pnpm spec:first
pnpm spec:check
pnpm check
pnpm test
pnpm build
pnpm publint
pnpm test:storybook
pnpm build-storybook
pnpm validation:all