Notes about how the document machine should work

here are the events and lifecycles that can update the document content, because the main issue is the main document content:

user enters docA
we fetch the resource
when resolved we load the document in the editor in reading mode (loaded state)
when the user that can edit clicks on any element in the content, we transition to edit mode (editing state).
from editing the user can enter into publishing state
in any state, the user can open the versions history panel and change to view an older version of the document. in this case we need to re-render the document content (document header and document editor content) and render the selected version WITHOUT APPLYING ANY DATA FROM THE CURRENT DOCUMENT DRAFT IF ANY.
when viewing an old version of a document, we should PREVENT editing the document by clicking any block inside the content (we should not transition to editing from loaded when rendering an older version).
when we press "discard draft" and confirm the action, we should: render the latest document version, delete the current draft for the document, show a toast that the changes where removed.
it should not be possible to discard changs if there's no draft available for the current document.
let's remove the option to start editing the document from an old version of the document.
the rebase flow: we should enter rebase ONLY when the current base version gets outdated. this can happen when a new version gets synced to the daemon and the external polling invalidates the useResource result. WE SHOULD NOT REBASE WHILE WE ARE EITHER SABING OR IN ANOTHER REBASE FLOW
the rebase check for conflicts should not affect the editing experience.
when there's a rebase conflict, for now we should just ignore it, so we can transition to the rebase idle state.

---

See also:

State machines to visualize the work of agents — using state machines to make LLM agent behavior more deterministic, extending the state machine pattern beyond UI to agent orchestration
State machines are great, but hard to establish — discussion on state machine adoption challenges and mixed logic patterns
Modeling resizable panels using State Machines — another practical UI state machine example
Product Backlog — State Machine Inspector — Opportunity #2 proposes a visual inspector/debugger for the document machine's 10+ states, addressing the "hard to establish" pain point
What I want for the commenting experience to be — commenting UX pain points that the document machine's editing states must support (inline comments, discussions panel)
Project Plan — No more Edit mode: New Publish mental model Pt.1 — implements the document machine (XState v5, 465 lines) with loaded/editing/publishing states
Publish Guard: block publishing when document content references local drafts — implements publish.start → publishing.inProgress guard transition in the document machine
Root Level Grouping Research — blank/fragment node proposal; the Tech Sync adopted this as the implementation path for the document machine
2026-07-09: Tech Sync — consensus to keep HMBlockNode + introduce blank/fragment nodes, confirming the actionable implementation path
Document Web Editing — web-side implementation of the same document-machine, with web-flavored actors (IndexedDB drafts, WebCrypto signer, capability gate) for vault-delegated editing
Draft Publishing Chain solution proposal — the publish/rebase lifecycle challenge: resolving draft-link chains when publishing, directly extending the document machine's publishing state
Enhancing document machine to update multiple drafts at the same time — extends the document machine beyond single-draft editing: spawning actors for each draft card, handling concurrent draft metadata updates within the same editor
Product Backlog — Opportunity 14: Document Machine OSS Package — proposes extracting the document machine as an open-source @shm/document-machine XState v5 package for the broader ecosystem
Case Study: Document Editor — external educational case study on the same document machine: version history, branching, and preventing edits on old versions, from the UI with State Machines hub