Add selected Observable System Guide stdlib helpers that fit the Lapis notebook runtime #135

New issue

Closed

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

steve commented

2026-05-27 16:06:00 +00:00

Owner

Add the next System Guide-style stdlib helpers that can live cleanly inside the existing Lapis notebook runtime without reopening the broader decision against full Observable runtime compatibility.

Problem

The current notebook runtime already exposes display, Inputs, html, svg, d3, Plot, DOM, Generators, and Promises, but it still lacks several System Guide helpers and tagged templates that users expect when reading Observable examples. The clearest remaining gaps are now, width, visibility, invalidation, md, and tex.

Goal

Add a selected subset of Observable System Guide stdlib helpers where the behavior can be defined in terms of explicit Lapis runtime ownership, notebook-local rendering, and predictable cleanup.

Scope

Evaluate and implement the compatible helper subset from now, width, visibility, invalidation, md, and tex.
Define lifecycle and cleanup rules for helpers that depend on notebook reruns, visibility, or cell disposal.
Expose the supported helpers through the documented notebook runtime surface and language-service globals.
Add focused tests for helper evaluation, cleanup, and rerun behavior.
Update the markdown-native parity fixture or add a sibling fixture when a helper materially changes the user-facing parity story.

Non-goals

Do not adopt Observable's observer lifecycle wholesale.
Do not add mutable variables or generator cells as ambient notebook syntax.
Do not add helpers whose semantics depend on replacing explicit notebook execution ownership with implicit runtime observers.

Acceptance Criteria

The chosen supported helper subset is explicitly documented in the notebook parity audit and runtime docs.
Each newly supported helper has focused tests that cover its notebook-specific behavior.
Helpers with cleanup or visibility semantics document how they interact with explicit reruns and notebook teardown.
The notebook language-service globals include the newly supported helpers so editor diagnostics and completions match runtime behavior.
Workspace acceptance covers at least one newly added helper when it affects user-visible rendering or rerun behavior.

Implementation Notes

Prefer helper semantics that can be hosted inside notebook-owned runtime contracts rather than emulating Observable internals.
If a candidate helper conflicts with explicit Lapis execution ownership, narrow the supported subset and record that decision in spec instead of adding a leaky compatibility shim.
Keep startup-thin behavior intact by loading helper dependencies lazily when practical.

Suggested Files or Specs To Inspect

packages/notebook/stdlib/src/**
packages/notebook/src/lib/runtime/**
packages/notebook/src/notebook-plugin.ts
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

Revisit whether any remaining System Guide helper should stay explicitly unsupported by design after the selected subset lands.
Evaluate sample datasets such as penguins separately from runtime helper semantics.

Implementation Summary

Duplicate of #132.

Add the next System Guide-style stdlib helpers that can live cleanly inside the existing Lapis notebook runtime without reopening the broader decision against full Observable runtime compatibility. ## Problem The current notebook runtime already exposes `display`, `Inputs`, `html`, `svg`, `d3`, `Plot`, `DOM`, `Generators`, and `Promises`, but it still lacks several System Guide helpers and tagged templates that users expect when reading Observable examples. The clearest remaining gaps are `now`, `width`, `visibility`, `invalidation`, `md`, and `tex`. ## Goal Add a selected subset of Observable System Guide stdlib helpers where the behavior can be defined in terms of explicit Lapis runtime ownership, notebook-local rendering, and predictable cleanup. ## Scope - Evaluate and implement the compatible helper subset from `now`, `width`, `visibility`, `invalidation`, `md`, and `tex`. - Define lifecycle and cleanup rules for helpers that depend on notebook reruns, visibility, or cell disposal. - Expose the supported helpers through the documented notebook runtime surface and language-service globals. - Add focused tests for helper evaluation, cleanup, and rerun behavior. - Update the markdown-native parity fixture or add a sibling fixture when a helper materially changes the user-facing parity story. ## Non-goals - Do not adopt Observable's observer lifecycle wholesale. - Do not add mutable variables or generator cells as ambient notebook syntax. - Do not add helpers whose semantics depend on replacing explicit notebook execution ownership with implicit runtime observers. ## Acceptance Criteria - The chosen supported helper subset is explicitly documented in the notebook parity audit and runtime docs. - Each newly supported helper has focused tests that cover its notebook-specific behavior. - Helpers with cleanup or visibility semantics document how they interact with explicit reruns and notebook teardown. - The notebook language-service globals include the newly supported helpers so editor diagnostics and completions match runtime behavior. - Workspace acceptance covers at least one newly added helper when it affects user-visible rendering or rerun behavior. ## Implementation Notes - Prefer helper semantics that can be hosted inside notebook-owned runtime contracts rather than emulating Observable internals. - If a candidate helper conflicts with explicit Lapis execution ownership, narrow the supported subset and record that decision in spec instead of adding a leaky compatibility shim. - Keep startup-thin behavior intact by loading helper dependencies lazily when practical. ## Suggested Files or Specs To Inspect - `packages/notebook/stdlib/src/**` - `packages/notebook/src/lib/runtime/**` - `packages/notebook/src/notebook-plugin.ts` - `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 - Revisit whether any remaining System Guide helper should stay explicitly unsupported by design after the selected subset lands. - Evaluate sample datasets such as `penguins` separately from runtime helper semantics. ## Implementation Summary Duplicate of #132.

steve added this to the Complete Daily-Use App milestone

2026-05-27 16:06:00 +00:00

steve added the

labels

2026-05-27 16:06:00 +00:00

steve

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