Align notebook runtime and rendering with Observable Notebooks 2.0 while keeping the markdown-native file format #127

New issue

Closed

opened 2026-05-27 13:33:27 +00:00 by steve · 0 comments

steve commented

2026-05-27 13:33:27 +00:00

Owner

Align the notebook runtime toward Observable Notebook Kit v2 execution and rendering semantics without adopting Observable's HTML notebook file format.

Problem

Lapis notebooks already exceed Observable in app integration, DuckDB access, generated-state persistence, and notebook-specific UI, but the runtime still diverges from the newer Observable direction in several user-visible ways. Input cells still depend on legacy viewof syntax, runtime helpers such as display(...) and additional stdlib behaviors are incomplete, and the acceptance surface is not yet anchored by a markdown-native version of the System Guide.

Goal

Make .notebook.md files behave closer to Observable Notebook Kit v2 for execution and rendering while preserving the existing markdown-native document format and Lapis-owned runtime contracts.

Scope

Replace legacy viewof-first authoring with plain JavaScript view(...) declarations.
Add or align execution semantics needed for the Observable System Guide acceptance path.
Expand notebook stdlib behavior only where it is required for runtime parity.
Update notebook fixtures, tests, and demos that still model legacy viewof usage.

Non-goals

Do not adopt Observable's <notebook> HTML source format as the canonical Lapis format.
Do not replace the Lapis runtime with @observablehq/runtime.
Do not fold notebook-level chrome relocation into this issue; that belongs to a separate notebook status-bar issue.

Acceptance Criteria

Notebook JS/TS input cells support plain top-level const|let|var name = view(expression) declarations.
Legacy viewof authoring is removed or isolated behind explicit migration cleanup rather than remaining the primary documented syntax.
Notebook runtime helpers and rendering semantics required by the System Guide fixture execute correctly in .notebook.md notes.
Focused Vitest coverage exercises the input transform and notebook analysis behavior for plain view(...) declarations.
Workspace acceptance coverage includes a markdown-native System Guide parity fixture or equivalent targeted coverage.

Implementation Notes

Start from the current transformObservableViewof() path and evolve it toward plain declaration transforms before widening into broader stdlib changes.
Keep changes compatible with the existing host-owned lapis.view(name, input) runtime so the initial slice stays small.
Update the notebook and notebook-input specs in the same changes that alter runtime behavior.

Suggested Files or Specs To Inspect

packages/notebook/input/src/observable-viewof.ts
packages/notebook/src/lib/runtime/notebook-worker.ts
packages/notebook/src/lib/runtime/analysis/analyze-ts-cell.ts
spec/src/20-packages/plugins/notebook/documents-and-runtime.md
spec/src/20-packages/notebook-inputs/index.md

Validation Commands

pnpm --filter @lapis-notes/notebook-input exec vitest run src/__tests__/observable-viewof.test.ts
pnpm --filter @lapis-notes/notebook exec vitest run src/lib/runtime/__tests__/observable-viewof-transform.test.ts
pnpm --filter @lapis-notes/notebook check
make spec-lint
pnpm test:smoke

Follow-up Tasks

Add display(...), richer stdlib helpers, and markdown/html interpolation support needed for broader Observable parity.
Convert demo notebooks and workspace fixtures fully away from legacy viewof after the transform/runtime path is stable.

Implementation Summary

Completed the markdown-native Observable parity slice by making plain view(...) the canonical input syntax, adding explicit display(...) support to notebook JS/TS cells through the runtime output coercion path, updating the checked-in System Guide fixture and focused Playwright acceptance to exercise display(...), and keeping the notebook runtime specs in sync.

Align the notebook runtime toward Observable Notebook Kit v2 execution and rendering semantics without adopting Observable's HTML notebook file format. ## Problem Lapis notebooks already exceed Observable in app integration, DuckDB access, generated-state persistence, and notebook-specific UI, but the runtime still diverges from the newer Observable direction in several user-visible ways. Input cells still depend on legacy `viewof` syntax, runtime helpers such as `display(...)` and additional stdlib behaviors are incomplete, and the acceptance surface is not yet anchored by a markdown-native version of the System Guide. ## Goal Make `.notebook.md` files behave closer to Observable Notebook Kit v2 for execution and rendering while preserving the existing markdown-native document format and Lapis-owned runtime contracts. ## Scope - Replace legacy `viewof`-first authoring with plain JavaScript `view(...)` declarations. - Add or align execution semantics needed for the Observable System Guide acceptance path. - Expand notebook stdlib behavior only where it is required for runtime parity. - Update notebook fixtures, tests, and demos that still model legacy `viewof` usage. ## Non-goals - Do not adopt Observable's `<notebook>` HTML source format as the canonical Lapis format. - Do not replace the Lapis runtime with `@observablehq/runtime`. - Do not fold notebook-level chrome relocation into this issue; that belongs to a separate notebook status-bar issue. ## Acceptance Criteria - Notebook JS/TS input cells support plain top-level `const|let|var name = view(expression)` declarations. - Legacy `viewof` authoring is removed or isolated behind explicit migration cleanup rather than remaining the primary documented syntax. - Notebook runtime helpers and rendering semantics required by the System Guide fixture execute correctly in `.notebook.md` notes. - Focused Vitest coverage exercises the input transform and notebook analysis behavior for plain `view(...)` declarations. - Workspace acceptance coverage includes a markdown-native System Guide parity fixture or equivalent targeted coverage. ## Implementation Notes - Start from the current `transformObservableViewof()` path and evolve it toward plain declaration transforms before widening into broader stdlib changes. - Keep changes compatible with the existing host-owned `lapis.view(name, input)` runtime so the initial slice stays small. - Update the notebook and notebook-input specs in the same changes that alter runtime behavior. ## Suggested Files or Specs To Inspect - `packages/notebook/input/src/observable-viewof.ts` - `packages/notebook/src/lib/runtime/notebook-worker.ts` - `packages/notebook/src/lib/runtime/analysis/analyze-ts-cell.ts` - `spec/src/20-packages/plugins/notebook/documents-and-runtime.md` - `spec/src/20-packages/notebook-inputs/index.md` ## Validation Commands ```bash pnpm --filter @lapis-notes/notebook-input exec vitest run src/__tests__/observable-viewof.test.ts pnpm --filter @lapis-notes/notebook exec vitest run src/lib/runtime/__tests__/observable-viewof-transform.test.ts pnpm --filter @lapis-notes/notebook check make spec-lint pnpm test:smoke ``` ## Follow-up Tasks - Add `display(...)`, richer stdlib helpers, and markdown/html interpolation support needed for broader Observable parity. - Convert demo notebooks and workspace fixtures fully away from legacy `viewof` after the transform/runtime path is stable. ## Implementation Summary Completed the markdown-native Observable parity slice by making plain view(...) the canonical input syntax, adding explicit display(...) support to notebook JS/TS cells through the runtime output coercion path, updating the checked-in System Guide fixture and focused Playwright acceptance to exercise display(...), and keeping the notebook runtime specs in sync.

steve added this to the Complete Daily-Use App milestone

2026-05-27 13:33:27 +00:00

steve added the

labels

2026-05-27 13:33:27 +00:00

steve changed title from ~~New issue~~ to Align notebook runtime and rendering with Observable Notebooks 2.0 while keeping the markdown-native file format

2026-05-27 13:45:49 +00:00

steve

2026-05-27 15:28:03 +00:00