Evaluate lifecycle-sensitive Observable stdlib helpers for notebooks #132

New issue

Closed

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

steve commented

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

Owner

Problem

The current notebook runtime already exposes the low-risk helper subset used by the System Guide, including display, Inputs, html, svg, md, tex, d3, Plot, DOM, Generators, and Promises. The remaining helper gaps are harder: now, width, visibility, and invalidation depend on lifecycle, visibility, rerun, teardown, and resource ownership semantics that Observable normally derives from its observer runtime.

Goal

Define which lifecycle-sensitive helpers Lapis notebooks can support under explicit notebook execution ownership, implement only the compatible subset, and document any helpers that stay unsupported by design.

Scope

Evaluate now, width, visibility, and invalidation against the existing notebook session model, worker/in-process split, DOM output registry, rerun commands, and teardown/cancellation behavior.
Define lifecycle and cleanup rules for every helper selected for implementation, including how it behaves on explicit rerun, input-triggered dependent rerun, notebook stop/cancel, output clearing, view teardown, and persisted-output restore.
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 only when a helper materially changes user-visible rendering or reactive behavior.
Record unsupported-by-design decisions in the parity audit instead of leaving candidates ambiguous.

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.
Do not revisit already-supported md and tex helper behavior in this issue unless a lifecycle helper requires shared infrastructure.
Do not add sample dataset globals or notebook-local module imports here; those are separate parity slices.

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.
Helpers that remain unsupported are listed with a short reason tied to Lapis execution ownership or lifecycle constraints.

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.
Treat invalidation as the highest-risk candidate because it implies a per-cell resource lifecycle contract that must compose with worker termination and in-process DOM outputs.

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

Evaluate sample datasets such as penguins separately from runtime helper semantics.
Consider local module imports separately because they are an authoring/module-resolution concern, not a stdlib lifecycle concern.

Implementation Summary

Added now and rerun-scoped invalidation helpers, documented unsupported width/visibility, and updated language-service globals.

Evaluate the remaining lifecycle-sensitive System Guide helpers that could fit the existing Lapis notebook runtime without reopening the broader decision against full Observable runtime compatibility. ## Problem The current notebook runtime already exposes the low-risk helper subset used by the System Guide, including `display`, `Inputs`, `html`, `svg`, `md`, `tex`, `d3`, `Plot`, `DOM`, `Generators`, and `Promises`. The remaining helper gaps are harder: `now`, `width`, `visibility`, and `invalidation` depend on lifecycle, visibility, rerun, teardown, and resource ownership semantics that Observable normally derives from its observer runtime. ## Goal Define which lifecycle-sensitive helpers Lapis notebooks can support under explicit notebook execution ownership, implement only the compatible subset, and document any helpers that stay unsupported by design. ## Scope - Evaluate `now`, `width`, `visibility`, and `invalidation` against the existing notebook session model, worker/in-process split, DOM output registry, rerun commands, and teardown/cancellation behavior. - Define lifecycle and cleanup rules for every helper selected for implementation, including how it behaves on explicit rerun, input-triggered dependent rerun, notebook stop/cancel, output clearing, view teardown, and persisted-output restore. - 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 only when a helper materially changes user-visible rendering or reactive behavior. - Record unsupported-by-design decisions in the parity audit instead of leaving candidates ambiguous. ## 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. - Do not revisit already-supported `md` and `tex` helper behavior in this issue unless a lifecycle helper requires shared infrastructure. - Do not add sample dataset globals or notebook-local module imports here; those are separate parity slices. ## 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. - Helpers that remain unsupported are listed with a short reason tied to Lapis execution ownership or lifecycle constraints. ## 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. - Treat `invalidation` as the highest-risk candidate because it implies a per-cell resource lifecycle contract that must compose with worker termination and in-process DOM outputs. ## 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 - Evaluate sample datasets such as `penguins` separately from runtime helper semantics. - Consider local module imports separately because they are an authoring/module-resolution concern, not a stdlib lifecycle concern. ## Implementation Summary Added now and rerun-scoped invalidation helpers, documented unsupported width/visibility, and updated language-service globals.

steve added this to the Complete Daily-Use App milestone

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

steve added the

labels

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

steve referenced this issue

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

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

steve changed title from ~~Add selected Observable System Guide stdlib helpers that fit the Lapis notebook runtime~~ to Evaluate lifecycle-sensitive Observable stdlib helpers for notebooks

2026-05-29 11:20:48 +00:00

steve

2026-05-29 12:13:11 +00:00