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.

Context

Key Decisions

Already Done (this branch)

Dependency Graph

Phase 1: renderType + editable + ReadOnly Fixes

1a. Editor constructor changes

1b. ReadOnly block fixes

1c. Markdown shortcut guards

1d. Toolbar suppression when not editable

Phase 2: Editor Extensions (parallel, separate PRs)

2a. Block Highlighting

2b. Image Gallery

2c. Block Hover Actions

2d. Range Selection / Citation Bubble

2e. Supernumbers

Phase 3: Renderer Swap

What to do

Phase 4: In-Place Editing

4a. Click-to-edit behavior

4b. Draft auto-load

4c. Machine wiring

4d. Account switching

Phase 5: Publishing via Machine

What to do

Phase 6: Cleanup

Phase 7 (Later): Collapsed Blocks Extension

PR Strategy

Supersedes

Key Reference Files