Polish Notebook v0 into a reliable, understandable feature #85

New issue

Closed

opened 2026-05-22 11:34:52 +00:00 by steve · 0 comments

steve commented

2026-05-22 11:34:52 +00:00

Owner

Stabilize notebook v0 around a small, predictable set of execution and output
behaviors before adding more notebook surface area.

Problem

Notebooks are one of the strongest differentiators in Lapis Notes, but they
currently span markdown storage, cells, execution ordering, generated state,
DuckDB, worker and in-process execution, DOM-dependent fallbacks, and rich
output restoration. The v0 user experience needs to be understandable before it
expands further.

Goal

Make notebook behavior reliable and visible for a user who creates a notebook,
edits cells, runs cells explicitly, inspects runtime mode, sees stale outputs,
and restarts the app.

Scope

Improve notebook UI and runtime status so users can see runtime mode and why a
fallback was selected.
Show notebook and cell-level execution state clearly.
Make stale outputs, restored generated state, and rebuilt state visible.
Surface dependency failures, DuckDB failures, and DOM-required execution
fallbacks as notebook-visible errors.
Support notebook execution being disabled under Safe Mode.
Add sample notebook coverage in the demo vault plus smoke or e2e coverage for
create, run, restart, and reopen flows.

Non-goals

Python kernels.
Remote execution.
Collaborative notebooks.
Full Observable or Marimo compatibility.
New major notebook languages or runtime models.

Acceptance Criteria

A user can create a simple .notebook.md file from the UI.
A user can run a simple JavaScript cell.
A user can see whether the notebook is using worker or in-process execution.
A user can see why a fallback runtime was selected.
A user can see stale outputs after editing an upstream cell.
A user can clear outputs.
After restart, a user can understand whether outputs were restored or
recomputed.
Dependency and load failures appear as notebook-visible errors.
DuckDB unavailable or failure paths show useful errors.
Notebook execution can be disabled by Safe Mode.
The sample or demo vault includes at least one notebook fixture.
Smoke or e2e coverage exercises create, run, restart, and reopen.

Implementation Notes

Prefer making existing behavior visible and reliable over adding new features.
Keep generated notebook state clearly separate from canonical markdown.
Avoid hidden automatic execution unless the spec already requires it.
Ensure failure messages are understandable to non-authors.

Suggested Files or Specs To Inspect

spec/src/20-packages/notebook/
spec/src/20-packages/plugins/
spec/src/40-testing/current-state.md
e2e-vault/plugin-notebook/

Validation Commands

pnpm --filter @lapis-notes/notebook check
pnpm test:smoke

Follow-up Tasks

Link runtime-specific follow-ups separately if worker and in-process recovery
need to be split.

Implementation Summary

Duplicate of active issue #79; keeping #79 as the canonical notebook polish issue.

Stabilize notebook v0 around a small, predictable set of execution and output behaviors before adding more notebook surface area. ## Problem Notebooks are one of the strongest differentiators in Lapis Notes, but they currently span markdown storage, cells, execution ordering, generated state, DuckDB, worker and in-process execution, DOM-dependent fallbacks, and rich output restoration. The v0 user experience needs to be understandable before it expands further. ## Goal Make notebook behavior reliable and visible for a user who creates a notebook, edits cells, runs cells explicitly, inspects runtime mode, sees stale outputs, and restarts the app. ## Scope - Improve notebook UI and runtime status so users can see runtime mode and why a fallback was selected. - Show notebook and cell-level execution state clearly. - Make stale outputs, restored generated state, and rebuilt state visible. - Surface dependency failures, DuckDB failures, and DOM-required execution fallbacks as notebook-visible errors. - Support notebook execution being disabled under Safe Mode. - Add sample notebook coverage in the demo vault plus smoke or e2e coverage for create, run, restart, and reopen flows. ## Non-goals - Python kernels. - Remote execution. - Collaborative notebooks. - Full Observable or Marimo compatibility. - New major notebook languages or runtime models. ## Acceptance Criteria - A user can create a simple `.notebook.md` file from the UI. - A user can run a simple JavaScript cell. - A user can see whether the notebook is using worker or in-process execution. - A user can see why a fallback runtime was selected. - A user can see stale outputs after editing an upstream cell. - A user can clear outputs. - After restart, a user can understand whether outputs were restored or recomputed. - Dependency and load failures appear as notebook-visible errors. - DuckDB unavailable or failure paths show useful errors. - Notebook execution can be disabled by Safe Mode. - The sample or demo vault includes at least one notebook fixture. - Smoke or e2e coverage exercises create, run, restart, and reopen. ## Implementation Notes - Prefer making existing behavior visible and reliable over adding new features. - Keep generated notebook state clearly separate from canonical markdown. - Avoid hidden automatic execution unless the spec already requires it. - Ensure failure messages are understandable to non-authors. ## Suggested Files or Specs To Inspect - `spec/src/20-packages/notebook/` - `spec/src/20-packages/plugins/` - `spec/src/40-testing/current-state.md` - `e2e-vault/plugin-notebook/` ## Validation Commands - `pnpm --filter @lapis-notes/notebook check` - `pnpm test:smoke` ## Follow-up Tasks - Link runtime-specific follow-ups separately if worker and in-process recovery need to be split. ## Implementation Summary Duplicate of active issue #79; keeping #79 as the canonical notebook polish issue.

steve

2026-05-22 11:34:52 +00:00