# Editor V2 Tiptap Plan

## Purpose

This document is a single execution plan for replacing the current BlockNote-based editor in `bland` with Tiptap.

This merged plan assumes:

- License pressure is the primary reason for the replacement.
- Data migration is out of scope.
- D1 `doc_snapshots` data and local IndexedDB editor state can be wiped.
- Churn is acceptable for this work.
- The migration should preserve the live product contract, not just the current visual style.

## Decision Summary

- Keep the public `EditorPane` API stable so `page-view.tsx` and `shared-page-view.tsx` do not need broad changes.
- Keep the current collaborative split:
  - body content in `YJS_DOCUMENT_STORE` as `Y.XmlFragment`
  - title in `YJS_PAGE_TITLE` as `Y.Text`
- Keep `Y.Doc`, `IndexeddbPersistence`, `y-partyserver/provider`, and the `onProvider` callback contract.
- Make a Phase 0 compatibility spike mandatory before the broader rewrite.
- Treat slash menu, formatting toolbar, link toolbar, upload wiring, and shared-media resolution as cutover-scope parity, not optional polish.
- Keep code blocks in cutover scope, including the existing allowed language set and syntax highlighting. Prefer a Shiki-backed implementation, but allow a fallback if the preferred package proves unstable.
- Treat drag handle behavior as confirm-first and non-blocking. It can land after cutover if needed.
- Treat `tiptap-ui-components` as a fallback accelerator, not the default path.
- Remove BlockNote-specific dependencies, overrides, and CSS once the Tiptap implementation passes parity checks.

## Current Editor Surface To Preserve

The replacement must preserve the behaviors already wired into the live tree:

- collaborative body content stored in `YJS_DOCUMENT_STORE`
- collaborative title stored separately in `YJS_PAGE_TITLE`
- IndexedDB persistence keyed by page id
- `y-partyserver/provider` auth and share-token connection params
- provider awareness for presence and sync UI outside the editor
- read-only shared-page mode
- upload flow through `src/client/lib/uploads.ts`
- share-token-aware media rendering for shared pages
- provider custom messages used for page metadata refresh
- code blocks with the current allowed language list

Primary live integration points:

- `src/client/components/editor/editor-pane.tsx`
- `src/client/components/editor/controllers/formatting-toolbar.tsx`
- `src/client/components/editor/controllers/link-toolbar.tsx`
- `src/client/components/editor/controllers/suggestion-menu.tsx`
- `src/client/components/editor/controllers/placement.ts`
- `src/client/components/page-view.tsx`
- `src/client/components/shared-page-view.tsx`
- `src/client/lib/uploads.ts`
- `src/client/hooks/use-sync.ts`
- `src/shared/constants.ts`
- `src/shared/doc-messages.ts`
- `src/client/styles/app.css`
- `src/client/styles/custom.css`

## Explicit Non-Goals

- preserving BlockNote document compatibility
- preserving BlockNote-specific schema or JSON output
- matching BlockNote DOM structure or CSS class names
- reworking the worker-side DocSync model
- changing upload routes, auth flow, or shared types unless the migration requires it

## Phase Plan

## Phase 0: Compatibility Spike

Goal: verify the collaboration stack and provider contract before broader UI work.

Tasks:

- install the minimum Tiptap packages needed for a spike
- mount a temporary Tiptap editor body in place of BlockNote on one page
- bind Tiptap collaboration to the existing `Y.Doc` and `YJS_DOCUMENT_STORE` fragment
- verify `@tiptap/extension-collaboration-caret` works with `y-partyserver/provider` awareness
- verify the same provider awareness still drives the existing avatar stack
- verify remote cursor rendering and awareness updates use a compatible user shape
- verify page switch teardown does not leak providers or awareness state
- verify read-only shared-page rendering still works with the same `shareToken` flow

Exit criteria:

- multi-tab editing syncs through the existing provider
- remote cursors render correctly
- existing presence UI still works from the same `provider.awareness`
- no duplicate awareness clients appear after page switches
- shared-page read-only render works without BlockNote

If Phase 0 fails, stop and resolve the provider or extension mismatch before proceeding.

## Phase 1: Core Swap

Goal: replace the editor body while preserving the collaboration, title, and provider lifecycle contracts.

Tasks:

- rewrite the BlockNote-backed body editor as a Tiptap-backed body editor
- keep the exported `EditorPane` component name and prop contract unchanged
- keep title management in the existing textarea flow
- keep `Y.Doc` bootstrap, title observer, title seeding, provider setup, and teardown logic
- keep `IndexeddbPersistence` with `bland:doc:${pageId}`
- keep `onProvider` behavior unchanged so sync status and presence UI continue to work
- configure Tiptap collaboration against the existing `YJS_DOCUMENT_STORE` fragment
- support `readOnly` with `editable: false`
- add basic content styling so the editor is readable before parity UI lands

Exit criteria:

- authenticated page editing works with Tiptap
- title sync still works through `YJS_PAGE_TITLE`
- `onProvider` still drives existing sync and presence UI
- shared read-only pages still render correctly
- page remount and teardown behavior remains correct

This phase is not the cutover gate by itself. Do not remove BlockNote yet.

## Phase 2: Controller Parity

Goal: restore the editor controls that are part of the current live editor surface.

Tasks:

- rebuild the slash menu against Tiptap APIs
- gate slash-menu visibility with `shouldShow` and `isChangeOrigin(transaction)` so it only opens for the local editor change in collaborative sessions
- rebuild the floating formatting toolbar against Tiptap APIs
- rebuild the link toolbar against Tiptap APIs
- wire image upload through the existing `uploadFile(workspaceId, file, pageId, shareToken)` flow
- support paste and drag/drop image upload
- preserve share-token-aware media rendering for shared pages
- keep read-only mode from exposing editing or upload actions
- preserve the current floating placement behavior by reusing `placement.ts`

Exit criteria:

- slash menu works with keyboard and mouse
- formatting toolbar appears on selection and applies marks correctly
- link toolbar supports edit, remove, and open behavior
- image upload works in authenticated pages
- uploaded media render correctly in shared pages
- no auth-only media URLs leak into shared-page rendering

Phase 2 restores controller parity, but cutover is not complete until Phase 3 code block parity and cleanup also pass validation.

## Phase 3: Extensions And Polish

Goal: finish the remaining editor-specific parity work, remove BlockNote, and clean up the tree.

Tasks:

- implement code blocks with the current language parity
- prefer a Shiki-backed path for highlighting
- allow a maintained fallback if the preferred Shiki package proves incompatible
- keep the current allowed language list centralized and explicit
- remove BlockNote dependencies from `package.json`
- delete `bn-components.tsx`
- remove BlockNote-only controllers, imports, and CSS
- remove `@source "../../../node_modules/@blocknote/shadcn";` from `src/client/styles/app.css`
- replace `.bn-*` styling with `.tiptap` and related editor styles
- wipe D1 `doc_snapshots` and validate fresh-document behavior

Exit criteria:

- BlockNote packages and imports are gone
- the editor still passes collaboration, upload, and shared-page checks
- code blocks remain editable and render with acceptable highlighting
- typecheck and build pass

## Drag Handle Policy

Drag handle behavior is not a cutover gate.

- If `@tiptap/extension-drag-handle-react` fits cleanly, it can land during or after Phase 3.
- If it introduces instability or extra churn, defer it to a follow-up.
- Shipping without it is acceptable as long as the rest of editor parity is in place.

## File Strategy

Prefer the smallest file churn that keeps ownership clear.

Recommended approach:

- keep `src/client/components/editor/editor-pane.tsx` as the public entry point
- rewrite `editor-pane.tsx` in place unless a thin wrapper around a new Tiptap implementation is clearly cleaner
- keep `controllers/placement.ts` unchanged
- rewrite the current controller files in place unless splitting a helper out materially improves clarity
- add new files only when they clearly earn their keep

Likely file outcomes:

- rewrite `src/client/components/editor/editor-pane.tsx`
- rewrite `src/client/components/editor/controllers/formatting-toolbar.tsx`
- rewrite `src/client/components/editor/controllers/link-toolbar.tsx`
- rewrite `src/client/components/editor/controllers/suggestion-menu.tsx`
- delete `src/client/components/editor/bn-components.tsx`
- update `src/client/styles/app.css`
- update `src/client/styles/custom.css`

Possible new files if needed:

- `src/client/components/editor/extensions/slash-menu.ts`
- `src/client/components/editor/controllers/slash-items.ts`
- `src/client/components/editor/views/code-block-view.tsx`
- `src/client/components/editor/views/image-view.tsx`

Do not create a larger `tiptap/` subtree by default. Add structure only if the implementation actually needs it.

## Dependency Strategy

Use the latest stable Tiptap 3 release and keep every `@tiptap/*` package on the same version.

### Required Core

- `@tiptap/react`
- `@tiptap/pm`
- `@tiptap/y-tiptap`
- `@tiptap/starter-kit`
- `@tiptap/extension-collaboration`
- `@tiptap/extension-collaboration-caret`
- `@tiptap/extension-image`
- `@tiptap/extension-placeholder`

### Required For Parity

- `@tiptap/extension-file-handler`
- `@tiptap/suggestion`
- a code block extension path with acceptable highlighting

### Likely Needed

- `@tiptap/extension-task-list`
- `@tiptap/extension-task-item`

### Confirm-First

- table support
- drag handle support
- `tiptap-ui-components`

### Remove

- `@blocknote/core`
- `@blocknote/react`
- `@blocknote/shadcn`
- BlockNote-only transitive UI dependencies that are no longer referenced

Dependency note:

`@radix-ui/react-popover` is currently only referenced by the BlockNote override file. It is not a required keeper for the Tiptap migration. If the new editor UI does not use it directly, it should leave with BlockNote.

## Implementation Notes

### Tiptap Configuration Direction

Use a Tiptap configuration that mirrors the existing collaboration contract:

- `StarterKit.configure({ undoRedo: false, link: { openOnClick: false, autolink: true } })`
- `Collaboration.configure({ fragment: ydoc.getXmlFragment(YJS_DOCUMENT_STORE) })`
- `CollaborationCaret.configure({ provider, user })`
- `Image.configure({ inline: false, allowBase64: false })`
- `Placeholder.configure(...)`

History must stay disabled when Yjs collaboration is enabled.

`Link` and `Underline` already come from `StarterKit` in Tiptap 3. Configure them through `StarterKit.configure(...)` instead of adding standalone extensions unless the implementation has a specific reason to split them out.

### React Integration Direction

Preferred default:

- use Tiptap's React Composable API for the new editor shell
- create the editor instance with `useEditor`
- render through `<Tiptap instance={editor}>`
- let child UI read the editor through `useTiptap()` or `useTiptapState()` instead of prop drilling where that improves clarity

Fallback:

- use `useEditor` with direct `EditorContent` wiring if that keeps `EditorPane` materially simpler in this codebase

The composable API is the preferred React pattern for this migration, but it is not a hard requirement.

### Controller Strategy

Default path:

- rebuild the current controllers against Tiptap APIs
- keep using `@floating-ui/react` and the existing placement helpers

Fallback:

- if rebuilding a controller turns out to be materially more complex than expected, vendor only the minimum `tiptap-ui-components` pieces needed to finish the migration

Do not default to vendoring a large Tiptap UI template.

### Upload And Shared-Media Strategy

Keep the backend flow unchanged.

Client requirements:

- call the existing `uploadFile()` helper
- insert uploaded images into the Tiptap document
- disable upload entry points in read-only mode
- preserve share-token-aware media rendering

Preferred rendering strategy:

- use a small custom Image NodeView if runtime share-token resolution is needed

Alternative:

- normalize URLs at insertion time only if it proves clearly simpler and token behavior remains acceptable

### Code Block Strategy

Code blocks stay in cutover scope.

Requirements:

- keep the current allowed language list
- preserve insertion and editing
- provide acceptable syntax highlighting
- keep the language selector behavior or an equivalent explicit language choice

Preferred path:

- Shiki-backed highlighting

Acceptable fallback:

- a maintained non-Shiki code block extension if it keeps language parity and avoids blocking the migration

Package choice is an implementation detail. Language parity is the actual requirement.

## Document Schema Direction

The Tiptap extension set is the effective schema for the editor. For this migration, keep that schema narrow and semantic.

Storage model:

- keep title in `YJS_PAGE_TITLE` as `Y.Text`
- keep body in `YJS_DOCUMENT_STORE` as `Y.XmlFragment`
- keep Yjs as the only collaborative source of truth for live document state
- treat JSON and HTML as import/export formats, not the mergeable canonical store

Schema rules:

- use a small set of typed nodes and marks
- do not add a generic `block` node with `kind: string`
- do not use `data: Record<string, unknown>` attr bags
- do not persist runtime or UI state in the document
- add new semantics as new nodes or marks, not opaque attrs on unrelated nodes

Body document shape:

```ts
doc: block+

paragraph
  attrs: { id?: string }
  content: inline*

heading
  attrs: { id?: string; level: 1 | 2 | 3 }
  content: inline*

blockquote
  attrs: { id?: string }
  content: block+

bulletList
  attrs: { id?: string }
  content: listItem+

orderedList
  attrs: { id?: string; start?: number }
  content: listItem+

listItem
  content: paragraph block*

taskList
  attrs: { id?: string }
  content: taskItem+

taskItem
  attrs: { checked: boolean }
  content: paragraph block*

horizontalRule
  attrs: { id?: string }
  atom: true
  group: block

codeBlock
  attrs: { id?: string; language: AllowedCodeLanguage | null }
  content: text*

image
  attrs: { id?: string; src: string; alt?: string | null; title?: string | null }
  atom: true
  group: block

text

hardBreak
  inline: true
  atom: true

marks:
  bold
  italic
  underline
  strike
  code
  link { href: string }
```

Schema decisions for this migration:

- task lists are in cutover scope
- code blocks persist only raw text plus `language`
- links persist only `href`
- uploaded images persist a stable `/uploads/:id` style path in `src`
- share-token-aware image resolution remains a render concern, not stored content
- `intrinsicWidth` and `intrinsicHeight` are deferred until the upload flow actually captures them

Image node decision:

- use the standard Tiptap image node shape for the migration
- do not introduce a custom `assetImage` node in the initial cutover
- revisit a custom asset node only if we need additional asset semantics such as captions, richer metadata, reuse tracking, or server-driven node targeting

Code block rules:

- keep the language allowlist centralized and explicit
- enforce the allowlist in editor commands, picker UI, import/paste handling, and tests
- do not persist highlighted token output, spans, or other derived render state

Stable block IDs:

- IDs are useful for anchors, comments, analytics, and drag/drop references
- do not make `UniqueID` a hard migration requirement
- add it only when there is a concrete consumer for those IDs
- if added, scope it to real block nodes and configure it for collaboration-safe transaction filtering

## CSS Migration Notes

Remove:

- BlockNote CSS import from the editor
- BlockNote `@source` wiring from `src/client/styles/app.css`
- `.bn-*` selectors and BlockNote-specific theme variables from `src/client/styles/custom.css`

Add:

- `.tiptap` content styling
- placeholder styling
- toolbar and menu styling
- collaboration cursor styling
- code block styling
- image and link styling

Keep:

- existing typography, spacing, and dark theme conventions where they still fit the rest of `bland`

## Validation Plan

### Automated

- `npm run typecheck`
- `npm run build`

### Manual

- edit a page in authenticated mode
- open the same page in a second tab and confirm collaboration
- confirm remote cursors render
- confirm remote presence avatars still show
- confirm sync status still works
- confirm title changes still sync
- reload and confirm IndexedDB restoration works
- switch between pages and confirm old providers are torn down
- open a shared page and confirm read-only render
- upload an image in authenticated mode
- render that image in shared mode
- verify slash menu, formatting toolbar, and link toolbar behavior
- verify code blocks render, remain editable, and preserve language choice

## Acceptance Checklist

- `EditorPane` prop contract remains unchanged
- title remains collaborative through `YJS_PAGE_TITLE`
- body collaboration works through the existing DocSync transport
- provider awareness still drives avatar and cursor presence
- uploads still use existing worker endpoints
- shared uploaded media still render
- read-only shared pages still behave correctly
- code blocks preserve acceptable language and highlighting parity
- BlockNote packages and imports are removed
- typecheck passes
- build passes

## Open Decisions

Decide early, but do not let these block Phase 0:

- whether task lists are required for cutover
- whether table support is required for cutover
- which code block package is the preferred implementation
- whether a custom Image NodeView is needed or simple URL normalization is sufficient
- whether any controller should use vendored `tiptap-ui-components` instead of custom implementation

## Recommended Execution Order

1. Complete Phase 0 and resolve any provider or awareness mismatch.
2. Land the Phase 1 core swap without deleting BlockNote yet.
3. Restore Phase 2 controller parity and shared-media behavior.
4. Finish Phase 3 code block parity and cleanup.
5. Remove BlockNote only after the Tiptap implementation passes validation.

This keeps the migration risk-ordered without redefining the live editor surface as optional.