Context

Three planning docs (editor-big-plan.md, plan-editor-document-features.md, plan-editor-migration-steps.md) describe the same vision: use the editor to render all document content (read-only and editable), replacing BlocksContent entirely.

The document lifecycle machine (XState v5) is already built and wired into resource pages on branch unified-document-lifecycle-machine. This plan merges all three docs into one.

Key Decisions

Extensions before swap: Core extensions must reach feature parity before replacing BlocksContent
Single editor instance: Toggle isEditable rather than swapping components
renderType + editable: Constructor takes { renderType: 'document' | 'embed' | 'comment', editable: boolean }. renderType is context metadata; plugin loading controlled by editable only (for now)
Core 4 extensions + Supernumbers: Block Highlighting, Image Gallery, Hover Actions, Range Selection, Supernumbers — Collapsed Blocks deferred
Editing blocked on renderer swap: In-place editing only after editor is the renderer
Click-to-edit: Single click on text block or bottom empty area enters edit mode (not a button). Click-drag = text selection (shows range selection bubble), NOT edit trigger
Draft auto-load: If user has edit access and a draft exists, show draft in edit mode automatically
Account switching: Save draft + exit edit mode when switching to non-editor account; enter edit mode (or allow it) when switching to editor account
Supernumbers: Top-right of block, shown in all modes when count > 0. Click emits event from editor, app decides behavior (desktop: open right panel focused on block)

Already Done (this branch)

✅ Document machine (document-machine.ts, 465 lines)
✅ React hooks/provider (use-document-machine.ts)
✅ Debug drawer + inspect tools
✅ Wired into resource-page-common.tsx with DocumentMachineProvider
✅ Desktop/web pages pass canEdit, existingDraftId
✅ Old draft page + draftMachine untouched and functional

Dependency Graph

Phase 1: renderType + editable + readOnly fixes
    │
    ├──→ Phase 2a: Block Highlighting ext    ──┐
    ├──→ Phase 2b: Image Gallery ext         ──┤
    ├──→ Phase 2c: Block Hover Actions ext   ──┤  (parallel, separate PRs)
    ├──→ Phase 2d: Range Selection ext       ──┤
    └──→ Phase 2e: Supernumbers ext          ──┘
                                                │
                                                ▼
                                     Phase 3: Renderer Swap
                                     (BlocksContent → editor readOnly)
                                                │
                                                ▼
                                     Phase 4: In-place Editing
                                     (click-to-edit + machine wiring + account switching)
                                                │
                                                ▼
                                     Phase 5: Publishing via Machine
                                                │
                                                ▼
                                     Phase 6: Cleanup
                                                │
                                                ▼
                                     Phase 7 (later): Collapsed Blocks ext

Phase 1: renderType + editable + ReadOnly Fixes

Goal: Introduce renderType + editable to editor constructor, fix blocks that misbehave in readOnly, guard markdown shortcuts.

1a. Editor constructor changes

Add to BlockNoteEditor.ts options: renderType: 'document' | 'embed' | 'comment' and keep existing editable: boolean
renderType stored on editor instance for extensions to read (context only, does not affect plugin loading yet)
editable controls plugin loading as before
Default: renderType: 'document', editable: true

1b. ReadOnly block fixes

1c. Markdown shortcut guards

Guard # → heading, - → bullet list, 1. → numbered list triggers behind editor.isEditable
These are likely TipTap/ProseMirror input rules — find and guard them
Location: BlockNode.ts handleTextInput (lines 444-460) and/or TipTap extension input rules
Also check MarkdownExtension.ts (lines 160-217) paste handler

1d. Toolbar suppression when not editable

editor-view.tsx: conditionally render FormattingToolbarPositioner, SlashMenuPositioner, LinkMenuPositioner, HyperlinkToolbarPositioner only when editable
SideMenu: only when editable
Key files:
- frontend/packages/editor/src/blocknote/core/BlockNoteEditor.ts
- frontend/packages/editor/src/blocknote/core/extensions/Blocks/nodes/BlockNode.ts
- frontend/packages/editor/src/blocknote/core/extensions/Markdown/MarkdownExtension.ts
- frontend/packages/editor/src/editor-view.tsx
- frontend/packages/editor/src/math.tsx
- frontend/packages/editor/src/mentions-plugin.tsx
- frontend/packages/editor/src/media-container.tsx
Verify: Render editor with editable: false containing math, images, mentions. No interactive controls, no markdown shortcuts fire, no toolbars. pnpm -C frontend typecheck.

Phase 2: Editor Extensions (parallel, separate PRs)

All follow the pattern: *Plugin.ts (ProseMirror plugin) + *Positioner.tsx (React UI). Registered in BlockNoteEditor.ts. Reference patterns: SideMenuPlugin.ts, FormattingToolbarPlugin.ts.

2a. Block Highlighting

Highlight block from URL #blockId, yellow highlights for citation ranges
ProseMirror decoration plugin adding CSS classes
Source: blocks-content.tsx focusBlockId + highlight logic
New: editor/src/extensions/BlockHighlight/BlockHighlightPlugin.ts

2b. Image Gallery

Double-click image when !editable → full-screen overlay with keyboard/swipe nav
Source: blocks-content.tsx ImageGalleryProvider (lines 163-320)
Reuse: collectImageBlocks, resolveGalleryNavigation, resolveSwipeDirection (already exported)
New: editor/src/extensions/ImageGallery/ImageGalleryPlugin.ts, react/ImageGallery/ImageGalleryOverlay.tsx
Modify: image.tsx (double-click handler when !isEditable)

2c. Block Hover Actions

Hover block → floating card positioned top-right of block: copy block link, start comment
Mouse tracking + editor.view.posAtCoords() → emit to React positioner
Source: blocks-content.tsx BlockNodeContent hover card (lines 550-700)
Version-aware links: In edit mode, block hover uses publishedVersion for existing blocks (blocks that existed before editing started). For new blocks (added during current edit session), copy link/reference uses path + blockRef without version. Editor emits a generic onBlockAction event; the app resolves the correct version.
New: editor/src/extensions/BlockHoverActions/BlockHoverActionsPlugin.ts, react/BlockHoverActions/BlockHoverActionsPositioner.tsx
Context needed: resourceId, publishedVersion, onBlockAction callback

2d. Range Selection / Citation Bubble

Select text (click-drag) when !editable → bubble with "cite" and "comment" actions
Active only when !isEditable
In edit mode: click-drag selects text normally (formatting toolbar), does NOT trigger citation bubble
Source: blocks-content.tsx range selection, useRangeSelection from @shm/shared
New: editor/src/extensions/RangeSelection/RangeSelectionPlugin.ts, react/RangeSelection/RangeSelectionPositioner.tsx

2e. Supernumbers

Positioned top-right of block (near/combined with hover actions area)
Shows citations + comments count as a small badge/number
Visible in ALL renderTypes and ALL editable states when count > 0, hidden when 0
Click emits onSupernumberClick({ blockId }) event — editor does NOT decide what happens, the consuming app does (desktop: opens right panel focused on block)
Data source: blockCitations record passed via editor options/context (same as current blocks-content.tsx line 133)
New: editor/src/extensions/Supernumbers/SupernumbersPlugin.ts, react/Supernumbers/SupernumbersPositioner.tsx
Verify each: Render published document with editor editable: false. Feature works. pnpm -C frontend typecheck. Visual comparison with current BlocksContent.

Phase 3: Renderer Swap

Goal: Replace <BlocksContent> with editor (editable: false, renderType: 'document') in resource-page-common.tsx.

What to do

Add @shm/editor as dependency of @shm/ui (frontend/packages/ui/package.json)
Create ReadOnlyEditor component in @shm/ui:
- useBlockNote({ editable: false, renderType: 'document', blockSchema: hmBlockSchema })
- Convert blocks via hmBlocksToEditorContent()
- Populate via editor.replaceBlocks() on mount / when blocks change
- Render <BlockNoteView> — no toolbars (suppressed by editable: false)
In resource-page-common.tsx → ContentViewWithOutline: swap <BlocksContentProvider><BlocksContent> → <ReadOnlyEditor>
Keep BlocksContent for other consumers (comments, previews) — remove only from document view
Move setGroupTypes() from desktop/src/models/editor-utils.ts to shared location
Key files:
- frontend/packages/ui/package.json
- frontend/packages/ui/src/read-only-editor.tsx (NEW)
- frontend/packages/ui/src/resource-page-common.tsx
- @seed-hypermedia/client/hmblock-to-editorblock
Verify: Open any published document → renders via editor. All block types correct. All 5 extensions work. SSR works on web. pnpm -C frontend typecheck.

Phase 4: In-Place Editing

Goal: Click on text block → editor becomes editable. Wire machine editing states. Handle account switching.

4a. Click-to-edit behavior

Text blocks only: Single click on paragraph/heading/code-block places cursor → sends edit.start to machine → editable toggles to true, toolbars appear
Bottom of editor: Click on empty area below last block → same behavior (creates empty paragraph, enters edit mode)
Non-text blocks (image, video, embed): single click does NOT trigger edit mode
Click-drag (text selection): does NOT trigger edit mode — shows range selection/citation bubble instead
Implementation: ProseMirror plugin that intercepts click events on text nodes, checks if !editable && canEdit, then sends edit.start

4b. Draft auto-load

When navigating to a document where user has edit access:
- Query findByEdit for existing draft
- If draft exists → pass existingDraftId → machine auto-transitions loaded → editing → show draft content in edit mode
- If no draft → show published content in read-only (user clicks to edit)

4c. Machine wiring

useDocumentEditor hook in desktop app:
- Wraps useBlockNote with machine event wiring
- onEditorContentChange → actorRef.send({type: 'change'})
- Toggle editor.isEditable based on selectIsEditing
- Show/hide toolbars based on editing state
Create writeDraft actor factory (extract from documents.ts:611-652)
Provide machine via documentMachine.provide({actors: {writeDraft}}) in desktop-resource.tsx
Wire navigation guard for unsaved changes

4d. Account switching

Add capability.changed event to document machine
useSelectedAccountCapability() already reacts to account changes
When capability changes:
- Editor → non-editor: Machine receives capability.changed { canEdit: false } → if in editing state: auto-save draft, transition to loaded, set editable: false
- Non-editor → editor: Machine receives capability.changed { canEdit: true } → update canEdit in context, user can now click-to-edit (or auto-enter editing if draft exists)
Key files:
- frontend/apps/desktop/src/pages/desktop-resource.tsx
- frontend/apps/desktop/src/models/documents.ts (lines 479, 611-652)
- frontend/packages/shared/src/models/document-machine.ts
- frontend/packages/shared/src/models/capabilities.ts
Verify:
- Click text block → editor becomes editable, toolbars appear, cursor placed
- Click image → nothing (stays read-only)
- Click-drag to select → range selection bubble, NOT edit mode
- Click bottom empty area → enters edit mode
- Type → autosave creates draft
- Navigate to doc with existing draft + edit access → auto-editing with draft content
- Switch account to non-editor while editing → draft saved, exits edit mode
- Switch account to editor → can click-to-edit again
- Old /draft page still works as fallback

Phase 5: Publishing via Machine

Goal: publish.start → publishing.inProgress → cleaningUp → loaded.

What to do

Extract publish pipeline from publish-draft-button.tsx into publishDocument actor
Provide via .provide() in desktop-resource.tsx
Update publish button to read machine state + send publish.start
context.deps used as baseVersion
Key files:
- frontend/apps/desktop/src/publish-draft-button.tsx
- frontend/apps/desktop/src/pages/desktop-resource.tsx
Verify: Full flow: view → click to edit → change → save → publish → back to loaded. Publish error → editing, draft intact. Parent auto-link + push to peers work.

Phase 6: Cleanup

Goal: Remove old code paths.

Redirect /draft/:id routes to document routes with editing state
Remove draft-machine.ts, draft.tsx, useDraftEditor
Remove BlocksContent from document view (keep for comments/previews if still needed)
Remove the three planning docs, replace with this single macro plan

Verify: No references to old draft machine. All existing tests pass. pnpm -C frontend typecheck.

Phase 7 (Later): Collapsed Blocks Extension

Collapse/expand block children (headings, nested content)
Source: blocks-content.tsx collapsedBlocks state (lines 344-355, 967-978)
ProseMirror plugin managing collapsed state set + decorations
Not blocking any other phase

PR Strategy

Phase 1: 1 PR (renderType + editable + readOnly fixes + markdown guards)
Phase 2: 5 separate PRs/commits (one per extension, independent)
Phase 3: 1 PR (renderer swap)
Phase 4: 1 PR (click-to-edit + machine wiring + account switching)
Phase 5: 1 PR (publishing)
Phase 6: 1 PR (cleanup)

Supersedes

This plan merges and replaces:

docs/plans/editor-big-plan.md (Phases 1-4 done, 5-8 absorbed here)
docs/plans/plan-editor-document-features.md (extensions + EditorMode absorbed here)
docs/plans/plan-editor-migration-steps.md (steps 1-10 absorbed here)

Those docs can be removed in Phase 6 cleanup.

Key Reference Files