Skip to content

Open cached notebooks offline without waiting for Drive - #392

Merged
jlewi merged 2 commits into
mainfrom
jlewi/local-first-notebook-open
Sep 24, 2026
Merged

jlewi merged 2 commits into
mainfrom
jlewi/local-first-notebook-open

Conversation

@jlewi

@jlewi jlewi commented Sep 23, 2026

Copy link
Copy Markdown
Collaborator

Cached notebooks could remain on the loading screen until a Drive sync completed or the storage worker's five-minute RPC timeout expired. Newly created files in mounted Drive folders were already persisted locally with asynchronous upstream creation, but load() immediately awaited that sync because lastSynced was empty.

Open cached .runme OPFS logs, cached JSON/IPYNB models, and newly created empty notebooks immediately; queue due reconciliation in the background. Pending Drive creation no longer blocks opening or editing. Only uncached notebooks await a download, and first-download errors propagate instead of appearing as successful empty notebooks.

Open and local refresh render the snapshot captured by their operation-log save adapter. This prevents an upstream or other-tab append between two reads from becoming unseen content that the next save accidentally deletes. The returned snapshot is detached from the adapter's baseline. The worker createView response includes that snapshot, and its protocol version is bumped to 2. Mixed-version clients receive the existing reload error; close/reopen all tabs on the origin after deployment if an old worker remains alive. Browser storage need not be cleared.

Fixes #250. Local content is immediately editable, including offline use.

Validation on jlewi-runme-dev:

  • runme run build test passed.
  • Full app suite: 1,757 tests passed (vitest run --testTimeout=15000).
  • Focused storage, worker, and controller suites: 214 tests passed.
  • Original blocked-queue regression fails on unmodified main and passes with the fix.
  • Regression coverage for snapshot interleaving, detached save baseline, unseen-cell preservation, and empty JSON/IPYNB creation offline.
  • Real Chromium SharedWorker test passed: captured views cross MessagePorts, concurrent edits converge, cached open succeeds during stalled reconciliation, offline folder creation/edit/save/reopen succeeds, and exact OPFS bytes survive browser restart. Isolated profile and stalled test credentials; no production Drive requests.
  • Updated recovery CUJ with the local-first and causal snapshot contracts and acceptance steps.

This removes upstream progress from local opening. Direct Drive-creation/Save As completion semantics, network deadlines, and diagnosis of the particular stalled production queue item are outside this change.

@jlewi jlewi left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed loading, asynchronous creation, worker RPC/version compatibility, journal lock boundaries, causal save adapters, first-download failures, and regression coverage.

Two findings were resolved in b72b076:

  • P1 — mismatched editor/save snapshots: .runme open and local refresh separately read the displayed snapshot and save baseline. Sync or another tab could append between those reads, causing a subsequent save to delete unseen content. Both now display the adapter's detached initialNotebook, returned with its captured history through the worker. The wire contract is versioned accordingly.
  • P2 — empty JSON creation still waited for Drive: the initial empty doc was treated as a cache miss while upstream creation was pending. A locally created record with a pending parent identity now opens immediately, with JSON/IPYNB regressions.

Validation: required build/tests passed; all 1,757 app tests passed; 214 focused tests passed; real Chromium SharedWorker/OPFS concurrent-edit, blocked-sync, offline creation, and browser-restart checks passed. No unresolved review findings. Merge remains gated on CI for b72b076.

@jlewi
jlewi merged commit a996b06 into main Sep 24, 2026
3 checks passed
@jlewi
jlewi deleted the jlewi/local-first-notebook-open branch September 24, 2026 00:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Rethink open behavior

1 participant