Evaluate layout-sensitive Observable width and visibility helpers for notebooks #139

New issue

Open

opened 2026-05-29 13:07:41 +00:00 by steve · 0 comments

steve commented

2026-05-29 13:07:41 +00:00

Owner

Close the remaining Observable System Guide layout-helper gap now that notebook parity covers now, invalidation, the bundled sample datasets, notebook-local imports, and sortable Inputs.table(...) headers.

Problem

The notebook runtime still documents width and visibility as unsupported because both helpers depend on layout, viewport, resize, and visibility semantics that Observable derives from its cell observer runtime. The current markdown-native notebook execution model has worker and in-process paths, DOM-backed outputs, rerun commands, restored output state, and notebook teardown, but it does not yet define how layout-sensitive helper values should be computed, refreshed, or cleaned up.

Goal

Decide and implement the smallest notebook-owned contract for width and visibility that fits the current runtime architecture, keeps markdown-native notebooks stable across reruns and reloads, and makes the remaining System Guide examples understandable in Lapis.

Scope

Audit the Observable System Guide uses of width and visibility against the current notebook session model, output host registry, rerun flow, and worker/in-process split.
Decide whether each helper should be implemented directly, exposed only on the in-process DOM-backed path, or remain intentionally unsupported with stronger documentation.
If implementation is chosen, define value ownership, update timing, teardown behavior, and fallback semantics for restored outputs, hidden leaves, and notebook reruns.
Extend runtime or workspace acceptance coverage with at least one markdown-native fixture example that exercises the chosen contract.
Update parity/runtime docs and notebook language-service globals to match the shipped behavior.

Non-goals

Do not broaden this issue into full Observable observer/runtime parity.
Do not require cross-window synchronized layout state beyond what the current notebook host already tracks.
Do not bundle unrelated table, dataset, or FileAttachment follow-up work into this slice.
Do not implement speculative responsive chart helpers beyond width and visibility.

Acceptance Criteria

The parity audit clearly states the supported contract for width and visibility, including any intentional limitations.
If either helper is implemented, value updates are consistent across reruns and notebook teardown without leaking listeners or stale promises.
Focused tests cover the chosen helper semantics on the controlling runtime path.
Workspace acceptance or smoke coverage exercises at least one layout-sensitive notebook example.
Runtime docs explain author guidance for layout-sensitive notebook cells.

Implementation Notes

Prefer a notebook-owned helper contract over pulling in Observable's full observer lifecycle.
Be explicit about whether worker-backed notebooks proxy layout state from the host or fall back to an unsupported contract.
Preserve deterministic behavior for restored notebook outputs and hidden panes.

Suggested Files or Specs To Inspect

packages/notebook/src/lib/runtime/**
packages/notebook/src/lib/session/**
packages/notebook/src/notebook-plugin.ts
packages/workspace/e2e/notebook-system-guide.spec.ts
e2e-vault/plugin-notebook/System Guide.notebook.md
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 test:e2e -- e2e/notebook-system-guide.spec.ts --project chromium
pnpm test:smoke
make spec-lint && mdbook build spec

Follow-up Tasks

Revisit broader responsive helper parity only after the width / visibility contract is stable.
If visibility remains intentionally unsupported, consider author-facing guidance or diagnostics that explain the limitation inline.

Implementation Summary

Populate when closing the issue.

Close the remaining Observable System Guide layout-helper gap now that notebook parity covers `now`, `invalidation`, the bundled sample datasets, notebook-local imports, and sortable `Inputs.table(...)` headers. ## Problem The notebook runtime still documents `width` and `visibility` as unsupported because both helpers depend on layout, viewport, resize, and visibility semantics that Observable derives from its cell observer runtime. The current markdown-native notebook execution model has worker and in-process paths, DOM-backed outputs, rerun commands, restored output state, and notebook teardown, but it does not yet define how layout-sensitive helper values should be computed, refreshed, or cleaned up. ## Goal Decide and implement the smallest notebook-owned contract for `width` and `visibility` that fits the current runtime architecture, keeps markdown-native notebooks stable across reruns and reloads, and makes the remaining System Guide examples understandable in Lapis. ## Scope - Audit the Observable System Guide uses of `width` and `visibility` against the current notebook session model, output host registry, rerun flow, and worker/in-process split. - Decide whether each helper should be implemented directly, exposed only on the in-process DOM-backed path, or remain intentionally unsupported with stronger documentation. - If implementation is chosen, define value ownership, update timing, teardown behavior, and fallback semantics for restored outputs, hidden leaves, and notebook reruns. - Extend runtime or workspace acceptance coverage with at least one markdown-native fixture example that exercises the chosen contract. - Update parity/runtime docs and notebook language-service globals to match the shipped behavior. ## Non-goals - Do not broaden this issue into full Observable observer/runtime parity. - Do not require cross-window synchronized layout state beyond what the current notebook host already tracks. - Do not bundle unrelated table, dataset, or FileAttachment follow-up work into this slice. - Do not implement speculative responsive chart helpers beyond `width` and `visibility`. ## Acceptance Criteria - The parity audit clearly states the supported contract for `width` and `visibility`, including any intentional limitations. - If either helper is implemented, value updates are consistent across reruns and notebook teardown without leaking listeners or stale promises. - Focused tests cover the chosen helper semantics on the controlling runtime path. - Workspace acceptance or smoke coverage exercises at least one layout-sensitive notebook example. - Runtime docs explain author guidance for layout-sensitive notebook cells. ## Implementation Notes - Prefer a notebook-owned helper contract over pulling in Observable's full observer lifecycle. - Be explicit about whether worker-backed notebooks proxy layout state from the host or fall back to an unsupported contract. - Preserve deterministic behavior for restored notebook outputs and hidden panes. ## Suggested Files or Specs To Inspect - `packages/notebook/src/lib/runtime/**` - `packages/notebook/src/lib/session/**` - `packages/notebook/src/notebook-plugin.ts` - `packages/workspace/e2e/notebook-system-guide.spec.ts` - `e2e-vault/plugin-notebook/System Guide.notebook.md` - `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 test:e2e -- e2e/notebook-system-guide.spec.ts --project chromium pnpm test:smoke make spec-lint && mdbook build spec ``` ## Follow-up Tasks - Revisit broader responsive helper parity only after the `width` / `visibility` contract is stable. - If `visibility` remains intentionally unsupported, consider author-facing guidance or diagnostics that explain the limitation inline. ## Implementation Summary Populate when closing the issue.

steve added the

labels

2026-05-29 13:07:41 +00:00