Observable System Guide Parity

Status: Snapshot of the current markdown-native notebook compatibility boundary against Observable Notebook Kit’s System Guide. This page records what the shipped Lapis notebook runtime supports today, what is a reasonable future parity target, and what remains intentionally out of scope.

This audit complements Notebook Documents and Runtime by comparing the current .notebook.md runtime to the user-facing concepts in Observable’s System Guide rather than restating the full notebook implementation surface.

Purpose

Lapis notebooks intentionally borrow selected Observable-style runtime concepts while preserving a markdown-native file format, explicit notebook execution commands, notebook-owned typed renderers, and generated-state persistence keyed by notebook cell ids.

The parity question for the System Guide is therefore not whether Lapis accepts Observable source unchanged. The practical question is which System Guide behaviors are already covered by the current markdown-native notebook runtime, which additional behaviors are reasonable next targets, and which Observable semantics currently conflict with the Lapis notebook architecture.

Supported Today

The current notebook runtime supports the following System Guide-aligned behaviors today:

• async JavaScript and TypeScript cells that resolve state before downstream cells render
• JavaScript program cells that can explicitly render one or more values through display(...)
• trusted live DOM output from htl-backed html and svg tagged templates in JavaScript-like cells
• first-class html source cells with ${...} interpolation and escaped interpolated values
• plain top-level const|let|var name = view(expression) input declarations, with downstream reruns when the input value changes
• direct Inputs.table(...) support for serializable row selection over attachment-backed tabular data, including sortable column headers
• vault-backed lapis.FileAttachment(path) reads for arrayBuffer, text, json, blob, csv, and tsv
• bundled notebook globals that overlap Observable concepts where Lapis already has a stable ownership story, including display, Inputs, html, svg, md, tex, d3, Plot, DOM, Generators, Promises, now, invalidation, and the upstream Observable sample dataset bundle (aapl, alphabet, cars, citywages, diamonds, flare, industries, miserables, olympians, penguins, pizza, and weather)
• JavaScript and TypeScript cells that can use top-level static ESM imports for configured runtime packages and host-installed bare packages
• JavaScript and TypeScript cells that can use vault-scoped relative JavaScript imports for notebook-local helper modules
• notebook-aware markdown outputs and dynamic markdown cells that can reference values from other cells through ${...} expressions or legacy {{name}} placeholders

The checked-in acceptance anchor for this boundary is the markdown-native System Guide fixture at e2e-vault/plugin-notebook/System Guide.notebook.md, which currently covers async setup, display(...), view(...), sortable Inputs.table(...), markdown and HTML source interpolation, escaped HTML interpolation, trusted DOM output, md/tex, now, bundled sample dataset access, and JSON/CSV FileAttachment-backed data loading.

Supported Differently

Some System Guide concepts exist in Lapis today, but with intentionally different authoring or execution rules:

• Lapis notebooks use .notebook.md files with :::cell{...} directives instead of Observable’s HTML notebook source format
• notebook execution is explicit-first: notebooks do not auto-run on load, though stale cells can rerun automatically after edits when notebook settings allow it
• markdown reactivity keeps {{name}} placeholders as a Lapis convenience while also supporting Observable-style ${...} expressions inside Markdown source
• notebook inputs use the constrained top-level view(...) declaration form rather than arbitrary Observable source transformations
• notebook outputs render through notebook-owned typed renderers and DOM mount points rather than the Observable inspector as the primary presentation surface

These differences are part of the current product design, not accidental gaps.

Not Supported Today

The following Observable System Guide behaviors are not currently supported by the shipped Lapis notebook runtime:

• the layout-sensitive System Guide built-ins visibility and width

These are the clearest remaining gaps between the current System Guide examples and the shipped markdown-native notebook runtime.

Out Of Scope By Design

Some Observable semantics remain intentionally outside the current Lapis notebook architecture:

• adopting @observablehq/runtime as the core notebook engine
• accepting Observable’s ambient source model wholesale inside .notebook.md cells
• Observable mutable variables
• generator cells as ambient notebook syntax
• observer-driven output lifecycle semantics tied directly to Observable runtime observers
• implicit invalidation or resource lifecycle behavior that bypasses explicit Lapis notebook execution ownership

These items currently conflict with explicit notebook execution commands, typed output rendering, generated-state persistence keyed by notebook cell ids and source fingerprints, and the worker versus in-process execution split used by the Lapis runtime.

Next Parity Targets

The next reasonable parity targets are the remaining System Guide behaviors that improve user-facing compatibility without requiring a wholesale Observable runtime model:

1. Layout-sensitive helper parity. Evaluate visibility and width only if the notebook runtime gains a stable per-cell DOM lifecycle contract that works across worker fallback, restored outputs, and explicit reruns.
2. Broader table interactions. Revisit optional filtering or larger-data presentation improvements for Inputs.table(...) now that the first serializable selection and sortable-header contracts have proven stable.

These targets are suitable for separate follow-up tasks because each can be evaluated against the existing notebook execution model, worker/in-process split, and typed output protocol without reopening the broader decision against full Observable source compatibility.

Validation Anchor

When parity changes land, they should extend both the markdown-native System Guide fixture and the focused workspace acceptance coverage so this page remains a current description of shipped behavior rather than a speculative wishlist.