Polish Notebook v0 into a reliable, understandable feature #79

New issue

Closed

opened 2026-05-22 11:30:31 +00:00 by steve · 0 comments

steve commented

2026-05-22 11:30:31 +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.

Sequencing

This is step 5 of the recommended six-issue sequence.
Start this issue after 78 and 80 so notebook execution states, fallback modes, and output persistence line up with the app-wide recovery and generated-state model.
Complete this issue before 81.
Treat the notebook polish work as a stabilization pass, not a reason to reorder earlier recovery or data-safety work.

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.
After this lands, move directly to 81.

Implementation Summary

Added notebook-owned runtime and output status visibility, stable run/stale/clear actions, focused runtime tests, and notebook Playwright coverage for worker/fallback and restored output messaging.

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. ## Sequencing - This is step 5 of the recommended six-issue sequence. - Start this issue after [78](78-add-safe-mode-and-recovery-flows-for-startup-plugin-layout-metadata-and-search-failures.md) and [80](80-harden-data-export-import-backup-and-generated-state-rebuild-flows.md) so notebook execution states, fallback modes, and output persistence line up with the app-wide recovery and generated-state model. - Complete this issue before [81](81-add-journey-based-e2e-and-smoke-tests-for-the-complete-daily-use-path.md). - Treat the notebook polish work as a stabilization pass, not a reason to reorder earlier recovery or data-safety work. ## 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. - After this lands, move directly to [81](81-add-journey-based-e2e-and-smoke-tests-for-the-complete-daily-use-path.md). ## Implementation Summary Added notebook-owned runtime and output status visibility, stable run/stale/clear actions, focused runtime tests, and notebook Playwright coverage for worker/fallback and restored output messaging.

steve added the

labels

2026-05-22 11:30:31 +00:00

steve added this to the Complete Daily-Use App milestone

2026-05-22 11:38:50 +00:00