One document, one window
Make desktop navigation predictable with explicit document ownership, a navigation state machine, and safe cleanup of duplicate windows after an update.

Problem

Users can accidentally open the same document in several desktop windows. When they edit one instance and see different content in another, it becomes unclear which draft is current and whether their work was saved. The original issue captures this confusion and the open questions around versions, drafts, comments, and navigation.

PR #1366 — Prevent duplicate desktop windows for the same document established the initial duplicate-window prevention and has merged. The follow-up makes the policy explicit across every navigation path, including Back/Forward, concurrent requests, and renderer failures. It also handles users whose saved sessions already contain duplicates when they update.

Solution

One document has at most one owning desktop window. Versions, selected blocks, document tabs, and an edit draft of that document share ownership. A new unpublished draft has its own identity. This settles the original version question: requesting a different version changes the view in the owning window.

What users experience

    Open a document: use its existing window if one exists. Restore it if minimized, show it, and focus it. An explicit request for a new window creates one only when the document is unclaimed; normal navigation can reuse the current window.

    Open another version, block, or document tab: apply the requested view in the same owning window. Metadata, Comments, Activity, Directory, Collaborators, site profile, and all-documents views share the document's ownership.

    Follow a link from another window: navigate the destination's existing owner and focus it. Keep the source window's page and history position unchanged.

    Use Back or Forward: apply the same ownership rules. If the destination is open elsewhere, focus that window and leave the source history cursor where it was. Reopening the exact same route only focuses; moving through identical entries within one window still moves its history cursor.

    Open or edit a draft: reuse the window claiming that draft, including its published-document or new-draft placeholder aliases. Settings, Contacts, and API Inspector also remain singletons; unrelated pages can appear in multiple windows.

Navigation state machine

One coordinator in Electron's main process owns the window registry and serializes navigation requests. The renderer receives an authorized history snapshot and acknowledges it after the outgoing document has unmounted. Until then, the window reserves both its old and new documents, preventing another request from claiming either midway through the transition.

The diagram uses the implemented state names. New requests queue while a transition is in progress.

stateDiagram-v2 direction TB [*] --> idle idle --> resolving: queued request resolving --> idle: nothing to apply resolving --> awaitingReady: select owner and reserve target awaitingReady --> dispatching: target renderer ready dispatching --> idle: exact reopen / focus owner dispatching --> awaitingCommit: send authorized history awaitingCommit --> committing: matching acknowledgement committing --> idle: persist state, release old claim, focus awaitingCommit --> reconciling: delivery failure or disconnect reconciling --> awaitingReady: renderer reconnects / replay reconciling --> committing: matching acknowledgement arrives note right of awaitingCommit Keep old and new claims until outgoing document cleanup and a matching acknowledgement. end note note right of reconciling Keep reservations while the outcome is unknown. end note

Window creation checks existing and pending claims synchronously before creating a new window, then registers its initial route. A loading owner is reused once ready. Blurring or minimizing never releases ownership. A confirmed window closure releases its claims and retries affected requests from surviving source windows; a cancelled close does not. Target disconnection can enter recovery from any active transition, and stale acknowledgements are ignored.

History entries that are not currently displayed do not own documents. On reconnect, the coordinator resends the same authorized snapshot, so a retry cannot append duplicate history entries. There is no unrestricted local-navigation fallback when the outcome is uncertain.

Cleanup when users update

Reconcile the saved session before restoring document editors, on every startup. This covers existing duplicates from older versions and keeps the operation safe to repeat. It is a startup workflow alongside the navigation state machine.

flowchart TD A["Start app and load saved session"] --> B["Validate routes and resolve document/draft identities"] B --> C["Group windows with overlapping ownership"] C --> D["Keep the most recently focused window per group"] D --> E["Checkpoint the original session"] E --> F["Restore surviving windows"] F --> G{"All remaining windows have navigation and UI ready?"} G -->|Yes| H["Persist clean session and remove checkpoint"] G -->|Still loading| I["Keep original session and wait for readiness events"] I --> G F -->|Restore fails| J["Preserve original session and report failure"]

Use a stable window-ID ordering when focus timestamps are missing or tied. Preserve the survivor's route, version, history, account, layout, and assistant state. Duplicate windows are omitted from restoration; their histories are not merged. Draft content is neither deleted nor rewritten. The original session stays recoverable until the remaining restored windows are ready; windows explicitly closed during restoration leave that waiting set.

For example, an older session with three windows on different versions or tabs of the same document restores one window at the most recently focused view. The other documents in the session restore normally.

Scope

Status as of November 17, 2026: PR #1366 is the merged baseline. The explicit state machine, renderer acknowledgement protocol, and startup reconciliation are implemented locally as a follow-up; that follow-up has not yet been committed or opened as a PR. The PR link above does not represent the complete follow-up or establish that it has shipped.

Local verification recorded during implementation:

    direnv exec . pnpm --filter @shm/desktop test:unit src: 1,502 passed, 1 skipped.

    direnv exec . pnpm typecheck: passed. Formatting checks on the implementation files passed.

    An isolated Electron smoke test covered cross-window focus, duplicate creation, Metadata aliases, ownership transfer, and Back navigation.

    Agent CI could not run because Docker was unavailable. Full CI verification remains incomplete.

Remaining work is review, CI, and upgrade testing before release. Planning estimate: 1–2 engineering days, subject to review findings and CI availability; release scheduling is not committed.

Acceptance checks for review:

    Simultaneous requests, loading or minimized owners, versions, draft aliases, and document tabs cannot create a second owner.

    Back/Forward, replace, deep links, and embedded-browser URL resolution all use the same coordinator.

    Renderer disconnect/reconnect, stale acknowledgements, and cancelled closes retain ownership correctly.

    An older duplicate session restores one survivor per resource; interrupted restoration preserves the original session, and cleanup is safe to repeat.

The follow-up's main implementation is frontend/apps/desktop/src/window-navigation-machine.ts; startup reconciliation is in utils/window-session.ts under the same directory. The durable architecture description is hypermedia/build/desktop-navigation.md in the local follow-up.

Rabbit Holes

    Synchronizing multiple live editors for the same document or bringing back the earlier backend reactive-event experiment.

    Merging duplicate windows' histories or designing a general tab/workspace manager.

    Parallelizing navigation across windows before the ownership protocol is proven. The current global queue can wait behind an unresponsive renderer until it reconnects or its window closes; this is a known availability tradeoff for the team to review.

    Expanding this policy to embedded-document editing or changing the embedded browser's own history model.

No Gos

    No second document window created by switching version, block selection, draft alias, or document tab.

    No draft-content deletion or merging as part of session cleanup.

    No migration that forcibly closes already-running editors; deduplication happens before editors mount at startup.

    No ownership release on a close request, blur, minimization, or uncertain IPC outcome.

    No promise of cross-device or cross-process exclusivity: ownership is scoped to one running desktop application instance.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime