[shovon]

Found while verifying #114. The same behaviour showed up on main from before it.

What was wrong

PagesApi promises that a write or a trail step resolves only after onChanged has heard the state it led to. Main sent the state before replying, but on the first pages.show() in a window the reply still arrived first. The state followed a fraction of a millisecond later, so ProjectView showed "Loading…" a moment longer.

The cause is in Electron (44.1.1), not pbnotes:

• An invoke reply goes over the frame's shared IPC channel (AssociatedRemote<ElectronApiIPC>).
• webContents.send is mainFrame.send. It goes through WebFrameMain on a separate mojo::Remote<ElectronRenderer> pipe, which is created the first time main sends to that frame (MaybeSetupMojoConnection in electron_api_web_frame_main.cc).
• Mojo keeps messages in order within one pipe, never across two. The first send to a window lost the race every time. Later sends arrived in order, but nothing guarantees that.

"Fresh ledger" turned out to be a red herring: what matters is the first send to a window since it loaded. A 30-line Electron app with no pbnotes code reproduces it (first call [0,1,1,…]). Touching webContents.mainFrame early hides it, and that is also why adding debug logs made the bug disappear.

The fix

• publish (pages-session.ts) numbers each state it sends (send(changed, state, n)) and resolves to that number. show, go/back/rezoom and the writes reply with it.
• A new src/preload/heard/heard.ts keeps one pages:changed listener for the life of the page. It hands each state to the onChanged listeners, then lets through any call waiting on that number or an earlier one. A call that sent nothing (ledger unreadable) waits on nothing.
• PagesApi keeps the same types and the same promise. Its docs, app/CLAUDE.md and three comments now say how the promise is kept.

The renderer relies on this order in two places:

• PageView drops a write's prediction when the write settles. A reply that arrived first would make the block jump back.
• ProjectView.goToBlock sets its scroll target right after go() resolves.

ProjectView's own show() only shows "Loading…" until the first state arrives, so it was never wrong, just slow.

Testing

• npm test: 91 pass, including 7 new tests in heard.test.ts and 2 in pages-session.test.ts.
• tsc --noEmit and eslint are clean.
• End to end, on scratch instances over CDP (fresh user-data dir and an empty folder each time; add, open, subscribe, await show()):
  • before the fix, 0 states had arrived when the first show() resolved, in 3 of 3 launches
  • after the fix, 1 state in 3 of 3 launches, plus 90 later fresh and warm show() calls all with 1
• addBlock, go, editBlock and back each resolve with their state already heard.

Merged with main after #114 landed. The numbering now lives in publish in pages-session.ts, and broadcastPages passes the number on. Two new pages-session.test.ts tests check that show, writes and trail steps resolve to the number of the state they sent, and to none when nothing was sent. Tests: 91 pass. The end-to-end check was re-run on the merged code.

🤖 Generated with Claude Code