Add Observable-style ${...} interpolation and HTML source cells to markdown-native notebooks #130

New issue

Closed

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

steve commented

2026-05-27 16:01:33 +00:00

Owner

Problem

The current notebook runtime supports dynamic markdown cells only through {{name}} placeholders and does not support first-class html source cells. Observable's System Guide relies on ${...} source interpolation in Markdown and HTML cells, and that remains one of the clearest parity gaps still visible to users comparing the two systems.

Goal

Add notebook-owned support for ${...} interpolation in markdown-native source cells and introduce first-class HTML notebook cells, while preserving .notebook.md files, explicit notebook execution ownership, and notebook-owned renderers.

Scope

Add html as a recognized notebook cell language.
Define the evaluation rules for ${...} expressions in notebook markdown cells.
Define the evaluation and escaping rules for ${...} expressions in notebook HTML cells.
Extend notebook parsing, dependency analysis, and rendering so interpolated markdown and HTML cells participate in the notebook graph.
Add focused runtime and workspace acceptance coverage for interpolated markdown and HTML notebook cells.
Update the notebook spec pages that describe current parity and runtime behavior.

Non-goals

Do not adopt Observable's HTML notebook file format.
Do not add full Observable ambient JavaScript syntax.
Do not replace notebook-owned output rendering with Observable inspectors.

Acceptance Criteria

Notebook parsing recognizes lang="html" cells as first-class notebook cells.
Markdown notebook cells can interpolate ${...} expressions from notebook state while preserving markdown-native file authoring.
HTML notebook cells can interpolate ${...} expressions and treat interpolated values as escaped text by default.
Notebook dependency analysis tracks values referenced from interpolated markdown and HTML cells.
Focused runtime or renderer tests cover both markdown and HTML source interpolation behavior.
Workspace acceptance extends the System Guide parity coverage or adds a sibling fixture that exercises interpolated markdown and HTML cells end to end.
The notebook parity audit and runtime spec pages describe the new support boundary.

Implementation Notes

Keep existing {{name}} placeholder support working unless there is an explicit migration plan.
Prefer notebook-owned parsing and rendering over source-to-source emulation of the Observable HTML notebook format.
Treat escaping rules for HTML source as a contract that must be documented and tested explicitly.

Suggested Files or Specs To Inspect

packages/notebook/src/lib/parse/**
packages/notebook/src/lib/runtime/**
packages/notebook/src/lib/render/**
spec/src/20-packages/plugins/notebook/documents-and-runtime.md
spec/src/20-packages/plugins/notebook/observable-system-guide-parity.md

Validation Commands

pnpm --filter @lapis-notes/notebook exec vitest run
pnpm --filter @lapis-notes/workspace exec playwright test e2e/notebook-system-guide.spec.ts
make spec-lint
pnpm test:smoke

Follow-up Tasks

Evaluate whether ${...} support makes md tagged-template parity substantially less important for the next slice.
Decide whether {{name}} placeholders remain a permanent markdown-native convenience or become a compatibility alias.

Implementation Summary

Implemented first-class HTML notebook cells, Observable-style markdown and HTML source interpolation, dependency analysis, runtime coverage, System Guide acceptance coverage, and parity/runtime spec updates.

Close the biggest remaining source-authoring gap between the current markdown-native notebook runtime and Observable's System Guide by adding first-class HTML notebook cells plus `${...}` expression interpolation for markdown-native notebook source. ## Problem The current notebook runtime supports dynamic markdown cells only through `{{name}}` placeholders and does not support first-class `html` source cells. Observable's System Guide relies on `${...}` source interpolation in Markdown and HTML cells, and that remains one of the clearest parity gaps still visible to users comparing the two systems. ## Goal Add notebook-owned support for `${...}` interpolation in markdown-native source cells and introduce first-class HTML notebook cells, while preserving `.notebook.md` files, explicit notebook execution ownership, and notebook-owned renderers. ## Scope - Add `html` as a recognized notebook cell language. - Define the evaluation rules for `${...}` expressions in notebook markdown cells. - Define the evaluation and escaping rules for `${...}` expressions in notebook HTML cells. - Extend notebook parsing, dependency analysis, and rendering so interpolated markdown and HTML cells participate in the notebook graph. - Add focused runtime and workspace acceptance coverage for interpolated markdown and HTML notebook cells. - Update the notebook spec pages that describe current parity and runtime behavior. ## Non-goals - Do not adopt Observable's HTML notebook file format. - Do not add full Observable ambient JavaScript syntax. - Do not replace notebook-owned output rendering with Observable inspectors. ## Acceptance Criteria - Notebook parsing recognizes `lang="html"` cells as first-class notebook cells. - Markdown notebook cells can interpolate `${...}` expressions from notebook state while preserving markdown-native file authoring. - HTML notebook cells can interpolate `${...}` expressions and treat interpolated values as escaped text by default. - Notebook dependency analysis tracks values referenced from interpolated markdown and HTML cells. - Focused runtime or renderer tests cover both markdown and HTML source interpolation behavior. - Workspace acceptance extends the System Guide parity coverage or adds a sibling fixture that exercises interpolated markdown and HTML cells end to end. - The notebook parity audit and runtime spec pages describe the new support boundary. ## Implementation Notes - Keep existing `{{name}}` placeholder support working unless there is an explicit migration plan. - Prefer notebook-owned parsing and rendering over source-to-source emulation of the Observable HTML notebook format. - Treat escaping rules for HTML source as a contract that must be documented and tested explicitly. ## Suggested Files or Specs To Inspect - `packages/notebook/src/lib/parse/**` - `packages/notebook/src/lib/runtime/**` - `packages/notebook/src/lib/render/**` - `spec/src/20-packages/plugins/notebook/documents-and-runtime.md` - `spec/src/20-packages/plugins/notebook/observable-system-guide-parity.md` ## Validation Commands ```bash pnpm --filter @lapis-notes/notebook exec vitest run pnpm --filter @lapis-notes/workspace exec playwright test e2e/notebook-system-guide.spec.ts make spec-lint pnpm test:smoke ``` ## Follow-up Tasks - Evaluate whether `${...}` support makes `md` tagged-template parity substantially less important for the next slice. - Decide whether `{{name}}` placeholders remain a permanent markdown-native convenience or become a compatibility alias. ## Implementation Summary Implemented first-class HTML notebook cells, Observable-style markdown and HTML source interpolation, dependency analysis, runtime coverage, System Guide acceptance coverage, and parity/runtime spec updates.

steve added this to the Complete Daily-Use App milestone

2026-05-27 16:01:33 +00:00

steve added the

labels

2026-05-27 16:01:33 +00:00

steve referenced this issue

2026-05-29 11:16:01 +00:00