@pilotiq/tiptap 3.1.1 → 3.2.1

package/src/PlainTextEditor.ts

@@ -0,0 +1,229 @@
+/**
+ * Plain-text editor factory — Tiptap editor config tuned to behave like a
+ * native `<input>` (single-line) or `<textarea>` (multi-line), with no marks
+ * and a Document schema restricted to paragraph(s) of inline text.
+ *
+ * Built for `@pilotiq/pilotiq`'s collab-text-field path: when collab is on,
+ * the renderer mounts a Tiptap editor instead of a native input so y-prosemirror
+ * can anchor selections to Yjs `RelativePosition` items (positional identity).
+ * This avoids the cursor-jump + concurrent-insert races inherent to the
+ * `Y.Text` + manual `computeDelta` + heuristic `preserveCursor` path.
+ *
+ * Pure config — no React. Caller passes the returned object to `useEditor` or
+ * `new Editor(...)`. Caller is also responsible for passing in the collab
+ * extension list (typically `Collaboration` + `CollaborationCursor` from the
+ * pilotiq collab adapter); we never import `@tiptap/extension-collaboration`
+ * directly so the open-core package stays free of collab peer deps.
+ */
+import {
+  Node,
+  Extension,
+  mergeAttributes,
+  type AnyExtension,
+  type EditorOptions,
+  type Editor,
+} from '@tiptap/core'
+import Placeholder from '@tiptap/extension-placeholder'
+
+/** Block separator used by `getText` — newline matches `<textarea>.value`. */
+const BLOCK_SEPARATOR = '\n'
+
+/**
+ * Bare paragraph block — the only block the plain-text schema permits.
+ * No options, no input rules, no toggles. `inline*` content lets any inline
+ * node (today just `text`) appear inside.
+ */
+const PlainTextParagraph = Node.create({
+  name: 'paragraph',
+  group: 'block',
+  content: 'inline*',
+  priority: 1000,
+  parseHTML() {
+    return [{ tag: 'p' }]
+  },
+  renderHTML({ HTMLAttributes }) {
+    return ['p', mergeAttributes(HTMLAttributes), 0]
+  },
+})
+
+/** The text node — Tiptap requires this to be defined explicitly. */
+const PlainTextText = Node.create({
+  name: 'text',
+  group: 'inline',
+})
+
+/**
+ * Build a Document node with content restricted to either a single paragraph
+ * (single-line mode) or one-or-more paragraphs (multi-line mode). The schema
+ * itself blocks paste of incompatible content — ProseMirror will coerce or
+ * reject non-matching nodes at parse time.
+ */
+function makePlainTextDocument(multiline: boolean) {
+  return Node.create({
+    name: 'doc',
+    topNode: true,
+    content: multiline ? 'paragraph+' : 'paragraph',
+  })
+}
+
+/**
+ * Single-line Enter handler. Tiptap's default `Enter` keymap splits the
+ * paragraph — meaningless when the schema only allows exactly one — so we
+ * intercept and either delegate to `onSubmit` (caller-supplied) or blur.
+ *
+ * Filament's plain-text fields blur on Enter; matching that default.
+ */
+function makeSingleLineKeymap(onSubmit: ((editor: Editor) => boolean | void) | undefined) {
+  return Extension.create({
+    name: 'plainTextSingleLineKeymap',
+    addKeyboardShortcuts() {
+      const handleEnter = (): boolean => {
+        const handled = onSubmit?.(this.editor)
+        if (handled === true) return true
+        this.editor.commands.blur()
+        return true
+      }
+      return {
+        Enter:         handleEnter,
+        'Mod-Enter':   () => true,
+        'Shift-Enter': () => true,
+      }
+    },
+  })
+}
+
+export interface PlainTextEditorOptions {
+  /** If true, allow multiple paragraphs (textarea-like). Default `false` (input-like). */
+  multiline?: boolean
+  /** Placeholder text shown while the editor is empty. */
+  placeholder?: string
+  /** Editable / disabled state. Default `true`. */
+  editable?: boolean
+  /**
+   * Initial textual content. Ignored when a Collaboration extension is passed
+   * via `extensions` — Collaboration takes ownership of the document and seeds
+   * from the Yjs fragment instead. Use the caller's own first-load seed (see
+   * `@pilotiq/tiptap` README) when collab is on.
+   */
+  content?: string
+  /**
+   * Extra extensions to merge into the editor — typically the Collaboration +
+   * CollaborationCursor pair from the pilotiq collab adapter. Pass `[]` (or
+   * omit) for the non-collab path.
+   */
+  extensions?: AnyExtension[]
+  /**
+   * Called on every editor update with the editor's plain-text value (blocks
+   * joined by `'\n'`). Use this to mirror the value into form-state for
+   * submission via a hidden `<input>`.
+   */
+  onUpdate?: (text: string, editor: Editor) => void
+  /**
+   * Single-line Enter handler. Return `true` to suppress the default blur
+   * behavior. When omitted, Enter simply blurs the editor.
+   */
+  onSubmit?: (editor: Editor) => boolean | void
+  /**
+   * DOM attributes for the editor's contenteditable wrapper — typically
+   * `{ class: '…tailwind classes…' }` to style the editor like the native
+   * `<input>` / `<textarea>` it replaces.
+   */
+  editorAttributes?: Record<string, string>
+}
+
+/**
+ * Read the editor's current value as plain text, with paragraphs joined by
+ * `'\n'`. Mirrors the behavior of `<textarea>.value`.
+ */
+export function plainTextOf(editor: Editor): string {
+  return editor.getText({ blockSeparator: BLOCK_SEPARATOR })
+}
+
+/**
+ * Convert a plain-text string into a Tiptap JSON doc that satisfies the
+ * plain-text schema. Multi-line input splits on `'\n'` into separate
+ * paragraphs; single-line strips any embedded newlines into a single run.
+ * Exported for tests — pure, no editor instance required.
+ */
+export function plainTextToDoc(text: string, multiline: boolean): {
+  type: 'doc'
+  content: Array<{ type: 'paragraph'; content?: Array<{ type: 'text'; text: string }> }>
+} {
+  if (!multiline) {
+    const flat = text.replace(/\r?\n/g, '')
+    return {
+      type: 'doc',
+      content: [
+        flat ? { type: 'paragraph', content: [{ type: 'text', text: flat }] }
+             : { type: 'paragraph' },
+      ],
+    }
+  }
+  const lines = text.split(/\r?\n/)
+  return {
+    type: 'doc',
+    content: lines.map((line) =>
+      line ? { type: 'paragraph', content: [{ type: 'text', text: line }] }
+           : { type: 'paragraph' },
+    ),
+  }
+}
+
+/**
+ * Build the Tiptap editor config for a plain-text field. Pass the returned
+ * object to `useEditor` (React) or `new Editor(...)` (vanilla).
+ *
+ * The editor schema is deliberately minimal:
+ *   - `doc` → `paragraph` (single-line) or `paragraph+` (multi-line)
+ *   - `paragraph` → `inline*`
+ *   - `text` (inline)
+ *
+ * No marks, no input rules, no list items, no code blocks — just text. Pasted
+ * rich content is stripped to plain text by ProseMirror's schema enforcement.
+ */
+export function createPlainTextEditor(
+  options: PlainTextEditorOptions = {},
+): Partial<EditorOptions> {
+  const {
+    multiline = false,
+    placeholder,
+    editable = true,
+    content = '',
+    extensions = [],
+    onUpdate,
+    onSubmit,
+    editorAttributes,
+  } = options
+
+  const schema: AnyExtension[] = [
+    makePlainTextDocument(multiline),
+    PlainTextParagraph,
+    PlainTextText,
+  ]
+
+  const behavior: AnyExtension[] = []
+  if (!multiline) behavior.push(makeSingleLineKeymap(onSubmit))
+  if (placeholder !== undefined) {
+    behavior.push(Placeholder.configure({ placeholder }))
+  }
+
+  const allExtensions: AnyExtension[] = [...schema, ...behavior, ...extensions]
+
+  // When Collaboration owns the doc, an explicit `content` would race the
+  // Yjs sync. Caller is responsible for omitting `content` in that case; we
+  // pass it through verbatim either way.
+  const initialContent = content ? plainTextToDoc(content, multiline) : ''
+
+  const config: Partial<EditorOptions> = {
+    editable,
+    extensions: allExtensions,
+    content: initialContent,
+  }
+  if (onUpdate) {
+    config.onUpdate = ({ editor }) => onUpdate(plainTextOf(editor), editor)
+  }
+  if (editorAttributes) {
+    config.editorProps = { attributes: editorAttributes }
+  }
+  return config
+}

package/src/index.ts

@@ -17,6 +17,12 @@ export {
   type MentionProviderMeta,
 } from './MentionProvider.js'
 export { registerTiptap } from './register.js'
+export {
+  createPlainTextEditor,
+  plainTextOf,
+  plainTextToDoc,
+  type PlainTextEditorOptions,
+} from './PlainTextEditor.js'
 export { tiptap } from './plugin.js'
 export { TiptapEditor } from './react/TiptapEditor.js'
 export {

package/src/react/CollabTextRenderer.tsx

@@ -0,0 +1,165 @@
+import { useEffect, useMemo, useState } from 'react'
+import { useEditor, EditorContent, type Extension } from '@tiptap/react'
+import type { AnyExtension } from '@tiptap/core'
+import {
+  useCollabRoom,
+  getCollabExtensions,
+  type CollabTextRendererProps,
+} from '@pilotiq/pilotiq/react'
+import { createPlainTextEditor, plainTextOf, plainTextToDoc } from '../PlainTextEditor.js'
+
+/**
+ * Tiptap-backed plain-text editor for pilotiq's `TextField` / `TextareaField`
+ * / similar single-line / multi-line text fields when collab is on.
+ *
+ * Lifts the cursor-bookkeeping burden off the field renderer: y-prosemirror
+ * anchors selections to `Yjs.RelativePosition` items, so concurrent and
+ * mid-word remote edits translate the local cursor correctly without any
+ * heuristic. Replaces the legacy `Y.Text` + `computeDelta` + `preserveCursor`
+ * path documented in `docs/plans/text-fields-tiptap-backed-collab.md`.
+ *
+ * Mount conditions (enforced upstream by `TextLikeInput`):
+ *   - A `<RecordCollabRoom>` is mounted up-tree (`useCollabRoom() !== null`).
+ *   - A collab extension factory was registered (`getCollabExtensions() !== null`).
+ *   - The field hasn't opted out via `.collab(false)`.
+ *   - The field is not masked (`.mask(pattern)`).
+ *   - The field is top-level (not a Repeater / Builder row leaf).
+ *
+ * If either the room or the factory disappears at runtime (e.g. the plugin
+ * was never installed), we still render an editor — it's just a non-collab
+ * plain Tiptap. That's a regression vs `<input>` ergonomically but never
+ * crashes; in practice the upstream gate prevents this branch from mounting
+ * when collab isn't wired.
+ */
+export function CollabTextRenderer({
+  name,
+  multiline,
+  defaultValue,
+  placeholder,
+  disabled,
+  onChange,
+  onBlur,
+  onSubmit,
+  className,
+  editorAttributes,
+}: CollabTextRendererProps): React.ReactElement {
+  const room    = useCollabRoom()
+  const factory = getCollabExtensions()
+  const collabActive = !!(room && factory)
+
+  // Built once per editor mount. The factory closes over the room's `ydoc`
+  // + `provider` and the field name to produce a `Collaboration` (and
+  // optional `CollaborationCursor`) extension targeting the field's
+  // `Y.XmlFragment`. Re-running on every render would tear down the editor.
+  const collabExtensions = useMemo<AnyExtension[]>(() => {
+    if (!collabActive || !room || !factory) return []
+    return factory({
+      ydoc:      room.ydoc,
+      provider:  room.provider,
+      fieldName: name,
+      ...(room.user ? { user: room.user } : {}),
+    }) as Extension[]
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collabActive])
+
+  const editor = useEditor(
+    createPlainTextEditor({
+      multiline,
+      ...(placeholder !== undefined ? { placeholder } : {}),
+      editable: !disabled,
+      // When Collaboration owns the doc, omit `content` so the editor
+      // doesn't race the y-prosemirror sync. The post-`synced` effect below
+      // seeds the fragment on first connect when it's still empty. When
+      // collab is off, seed from defaultValue directly.
+      content: collabActive ? '' : defaultValue,
+      extensions: collabExtensions,
+      onUpdate: (text) => onChange(text),
+      ...(onSubmit ? { onSubmit: () => { onSubmit(); return false } } : {}),
+      ...(className || editorAttributes
+        ? {
+            editorAttributes: {
+              ...(editorAttributes ?? {}),
+              ...(className ? { class: className } : {}),
+            },
+          }
+        : {}),
+    }),
+    // Re-mount when collab toggles. Other props (multiline, name, etc) are
+    // stable per mount under the upstream gate.
+    [collabActive],
+  )
+
+  // Mirror the editor's editable state with the prop. `useEditor` snapshots
+  // `editable` at first call, so we update it imperatively on changes.
+  useEffect(() => {
+    if (!editor) return
+    editor.setEditable(!disabled)
+  }, [editor, disabled])
+
+  // First-load seed when collab is active. Collaboration starts the editor
+  // empty regardless of `defaultValue`; once the provider syncs the room
+  // state from the server we check whether the field's `Y.XmlFragment`
+  // was ever written. Empty + we have an initial value = first session for
+  // this record — push the SSR-rendered default into the editor once.
+  //
+  // Race caveat: two peers simultaneously mounting against a brand-new
+  // record (both seeing `fragment.length === 0`) can both seed and produce
+  // duplicated text. Same window as `TiptapEditor`'s rich-text seed path.
+  // Acceptable for now; can be tightened later via a deterministic
+  // first-writer election or a server-side seed handoff.
+  const [hasSeeded, setHasSeeded] = useState(false)
+  useEffect(() => {
+    if (!editor || !collabActive || !room || hasSeeded) return
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ydoc     = room.ydoc as any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const provider = room.provider as any
+    if (!ydoc || !provider) return
+
+    const trySeed = (): void => {
+      try {
+        const fragment = ydoc.getXmlFragment(name)
+        if (fragment && fragment.length === 0 && defaultValue) {
+          editor.commands.setContent(plainTextToDoc(defaultValue, multiline))
+        }
+        setHasSeeded(true)
+      } catch {
+        setHasSeeded(true)
+      }
+    }
+
+    if (provider.synced) {
+      trySeed()
+      return
+    }
+    provider.once('synced', trySeed)
+    return () => {
+      try { provider.off?.('synced', trySeed) } catch { /* ignore */ }
+    }
+    // Seed once per editor instance — keyed remount above resets `hasSeeded`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor, collabActive, room])
+
+  // Bubble the editor's blur event up to the host. Tiptap exposes this via
+  // `editor.on('blur', ...)`. The simpler `onBlur` prop on `EditorContent`
+  // fires on the DOM node, but selection inside contenteditable can land on
+  // child nodes; the Tiptap event is the canonical "editor lost focus".
+  useEffect(() => {
+    if (!editor) return
+    const handler = (): void => onBlur()
+    editor.on('blur', handler)
+    return () => { editor.off('blur', handler) }
+  }, [editor, onBlur])
+
+  // Best-effort getText safety net — onUpdate should fire on every
+  // y-prosemirror sync, but if a remote update somehow doesn't trigger
+  // `onUpdate`, the wrapper's hidden input goes stale. Re-emit on every
+  // editor render tick. No-op when text matches the last emit.
+  useEffect(() => {
+    if (!editor) return
+    onChange(plainTextOf(editor))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor])
+
+  return <EditorContent editor={editor} />
+}

package/src/react/TiptapEditor.tsx

@@ -13,7 +13,12 @@ import { Table, TableRow, TableCell, TableHeader } from '@tiptap/extension-table
 import { Details, DetailsSummary, DetailsContent } from '@tiptap/extension-details'
 import { Grid, GridColumn } from '../extensions/GridExtension.js'
 import { Popover } from '@base-ui/react/popover'
-import type { FieldRendererProps } from '@pilotiq/pilotiq/react'
+import type {
+  FieldRendererProps,
+  CollabRoom,
+  CollabExtensionFactory,
+} from '@pilotiq/pilotiq/react'
+import { useCollabRoom, getCollabExtensions } from '@pilotiq/pilotiq/react'
 import { useAiSuggestionBridge } from './useAiSuggestionBridge.js'
 import type { BlockMeta } from '../Block.js'
 import type { ToolbarGroups, RichTextStorage, ColorSwatch } from '../RichTextField.js'
@@ -66,7 +71,7 @@ export function TiptapEditor(props: FieldRendererProps) {
     const storage = (props.el['storage'] as RichTextStorage | undefined) ?? 'json'
     const initialValue = serializeForHidden(props.defaultValue, storage)
     return (
-      <div className="flex flex-col gap-1">
+      <div className="flex flex-col">
         <input type="hidden" name={props.name} value={initialValue} />
         <div className="prose prose-sm max-w-none min-h-[180px] rounded-md border border-input bg-transparent px-10 py-3 text-sm text-muted-foreground">
           {props.placeholder ?? 'Start writing…'}
@@ -75,11 +80,51 @@ export function TiptapEditor(props: FieldRendererProps) {
     )
   }
 
-  return <ClientEditor {...props} />
+  return <CollabAwareTiptap {...props} />
 }
 
-function ClientEditor(props: FieldRendererProps) {
-  const { el, name, defaultValue, placeholder, disabled } = props
+/**
+ * Bridges pilotiq's open-core `CollabRoomContext` + `CollabExtensionFactory`
+ * registry into the Tiptap renderer. When `@pilotiq-pro/collab` is wired
+ * AND a `<RecordCollabRoom>` is mounted up-tree, the room flips non-null;
+ * keying `ClientEditor` on that toggle remounts the editor cleanly so the
+ * `Collaboration` extension can install (Tiptap can't swap it at runtime).
+ *
+ * No-op shell when collab isn't installed — `room` stays `null`,
+ * `getCollabExtensions()` returns `null`, and `ClientEditor` runs its
+ * plain Tiptap path with the same shape as before.
+ */
+function CollabAwareTiptap(props: FieldRendererProps) {
+  const room    = useCollabRoom()
+  const factory = getCollabExtensions()
+  // Per-field opt-out — `RichTextField.collab(false)` stamps `meta.collab`
+  // explicitly false, overriding the panel-wide auto-on default. Useful for
+  // fields that should stay device-local (private notes, draft scratch
+  // space, etc.) inside an otherwise collab-on form.
+  const fieldCollab  = props.el['collab'] as boolean | undefined
+  const collabActive = !!(room && factory) && fieldCollab !== false
+  return (
+    <ClientEditor
+      key={collabActive ? 'collab' : 'local'}
+      {...props}
+      room={collabActive ? room : null}
+      factory={collabActive ? factory : null}
+      collabActive={collabActive}
+    />
+  )
+}
+
+interface ClientEditorProps extends FieldRendererProps {
+  /** Active record room, or `null` when no `<RecordCollabRoom>` is mounted. */
+  room:         CollabRoom | null
+  /** Registered collab extension factory, or `null` when no plugin registered. */
+  factory:      CollabExtensionFactory | null
+  /** Convenience flag — `true` iff both `room` AND `factory` are non-null. */
+  collabActive: boolean
+}
+
+function ClientEditor(props: ClientEditorProps) {
+  const { el, name, defaultValue, placeholder, disabled, room, factory, collabActive } = props
 
   const blocks            = (el['blocks']           as BlockMeta[]     | undefined) ?? []
   const slashEnabled      = (el['slashCommand']     as boolean         | undefined) ?? true
@@ -165,13 +210,35 @@ function ClientEditor(props: FieldRendererProps) {
   // the extension config to re-evaluate, triggering a full editor reset).
   const editorRef = useRef<Editor | null>(null)
 
+  // Resolve the collab-attached extensions once per editor build.
+  // `Collaboration` is constructed eagerly here (during `useEditor`'s
+  // first call); the keyed remount above guarantees we never swap it.
+  const collabExtensions = useMemo(() => {
+    if (!collabActive || !room || !factory) return [] as unknown[]
+    return factory({
+      ydoc:      room.ydoc,
+      provider:  room.provider,
+      fieldName: name,
+      ...(room.user ? { user: room.user } : {}),
+    })
+    // Intentionally deps-stable across renders within the same collab
+    // mount — the keyed wrapper above remounts us when collab toggles.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collabActive])
+
   const editor = useEditor({
     editable: !disabled,
     extensions: [
       // StarterKit 3.22+ ships Link AND Underline; configure through the
       // kit rather than re-adding (else "Duplicate extension names" warns).
+      // `Collaboration` brings its own Yjs-backed history — disable
+      // StarterKit's local `undoRedo` extension when collab is active
+      // (renamed from `history` in Tiptap v3.x; passing `history: false`
+      // silently no-ops and produces a runtime "not compatible with
+      // @tiptap/extension-undo-redo" warning).
       StarterKit.configure({
         link: { openOnClick: false, autolink: true },
+        ...(collabActive ? { undoRedo: false } : {}),
       }),
       Subscript,
       Superscript,
@@ -252,8 +319,21 @@ function ClientEditor(props: FieldRendererProps) {
       // inline strikethrough + Approve/Reject chip widgets. Idle until the
       // host calls `editor.commands.addAiSuggestion(...)`.
       AiSuggestionExtension,
+      // Realtime-collab extensions (Yjs `Collaboration` + cursor) — empty
+      // when no `<RecordCollabRoom>` is mounted up-tree, or when no plugin
+      // registered a factory via `registerCollabExtensions`.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      ...(collabExtensions as any[]),
     ],
-    content: initialContent ?? '',
+    // Collaboration takes ownership of the document — `content` would race
+    // the Y.XmlFragment sync. Seed instead via the post-`synced` effect
+    // below so existing DB content lands once and only once. The non-collab
+    // branch also gates on `isTiptapShapedContent` so leftover content from
+    // a previous editor (e.g. Lexical's `{ root: {...} }`) doesn't crash
+    // the schema-strict node parser on first paint.
+    content: collabActive
+      ? ''
+      : (initialContent !== undefined && isTiptapShapedContent(initialContent) ? initialContent : ''),
     onUpdate: ({ editor: ed }) => {
       // Debounce serialization — every keystroke fires onUpdate.
       if (debounceRef.current) clearTimeout(debounceRef.current)
@@ -338,6 +418,55 @@ function ClientEditor(props: FieldRendererProps) {
   // scratch on every keystroke.
   useEffect(() => { editorRef.current = editor ?? null }, [editor])
 
+  // First-load seed when collab is active. Collaboration starts the
+  // editor empty regardless of `defaultValue`; once the WebsocketProvider
+  // syncs the room state from the server we check whether the field's
+  // Y.XmlFragment was ever written. Empty + we have an initial value =
+  // first session for this record — push the DB content into the ydoc
+  // exactly once. Non-empty = the room already has authoritative state;
+  // don't overwrite.
+  useEffect(() => {
+    if (!editor || !collabActive || !room) return
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const provider = room.provider as any
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ydoc     = room.ydoc as any
+    if (!provider || !ydoc) return
+
+    const trySeed = () => {
+      try {
+        const fragment = ydoc.getXmlFragment(name)
+        if (
+          fragment &&
+          fragment.length === 0 &&
+          initialContent !== undefined &&
+          initialContent !== null &&
+          initialContent !== '' &&
+          isTiptapShapedContent(initialContent)
+        ) {
+          // setContent dispatches a Tiptap transaction; the bound
+          // y-prosemirror binding (inside Collaboration) mirrors it
+          // into the fragment so every peer sees the seeded state.
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          editor.commands.setContent(initialContent as any)
+        }
+      } catch { /* ignore — seed is best-effort */ }
+    }
+
+    if (provider.synced) {
+      trySeed()
+      return
+    }
+    provider.once('synced', trySeed)
+    return () => {
+      try { provider.off?.('synced', trySeed) } catch { /* ignore */ }
+    }
+    // `initialContent` resolves once per mount (parsed from defaultValue
+    // at the top of this body). The keyed remount above guarantees we
+    // get a fresh closure per collab session.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [editor, collabActive, room, name])
+
   // Cross-package suggestion bridge — sync the host's
   // `<PendingSuggestionsContext>` queue with the editor's `AiSuggestion`
   // extension. No-op when no provider is mounted (default no-op context).
@@ -348,7 +477,7 @@ function ClientEditor(props: FieldRendererProps) {
   const tick = useEditorTick(editor)
 
   return (
-    <div className="relative flex flex-col gap-1">
+    <div className="relative flex flex-col">
       <input type="hidden" name={name} value={serialized} />
       {editor && toolbarGroups && toolbarGroups.length > 0 && (
         <Toolbar
@@ -513,6 +642,25 @@ function SlashPopover({
   )
 }
 
+/**
+ * Loose shape check — returns `true` only when the value looks like a Tiptap
+ * (ProseMirror JSON) document: either an HTML string or an object that opens
+ * with `{ type: 'doc' }` at the top level. Used by the collab seed effect to
+ * skip leftover content from previous editors (notably Lexical's
+ * `{ root: {...} }` envelope) without crashing Tiptap's strict node parser.
+ *
+ * The conservative posture: if we can't recognise the shape we don't seed.
+ * Worst case the user sees an empty editor on the first collab session and
+ * types fresh — better than the editor showing nothing because a parse threw.
+ */
+function isTiptapShapedContent(raw: unknown): boolean {
+  if (typeof raw === 'string') return true            // HTML or raw text — Tiptap parses both.
+  if (raw === null || typeof raw !== 'object') return false
+  const obj = raw as { type?: unknown; content?: unknown; root?: unknown }
+  if (obj.root !== undefined) return false            // Lexical state envelope — never Tiptap.
+  return obj.type === 'doc'                           // ProseMirror JSON always opens with `type:'doc'`.
+}
+
 function parseInitialContent(raw: unknown): object | string | undefined {
   if (raw === undefined || raw === null || raw === '') return undefined
   if (typeof raw === 'object') return raw as object

package/src/register.ts

@@ -1,6 +1,7 @@
-import { registerFieldRenderer } from '@pilotiq/pilotiq/react'
+import { registerFieldRenderer, registerCollabTextRenderer } from '@pilotiq/pilotiq/react'
 import { registerRichTextRenderer } from '@pilotiq/pilotiq/richtext'
 import { TiptapEditor } from './react/TiptapEditor.js'
+import { CollabTextRenderer } from './react/CollabTextRenderer.js'
 import { renderRichTextToHtml, isRichTextValue } from './render.js'
 
 /**
@@ -24,4 +25,10 @@ import { renderRichTextToHtml, isRichTextValue } from './render.js'
 export function registerTiptap(): void {
   registerFieldRenderer('richtext', TiptapEditor)
   registerRichTextRenderer(renderRichTextToHtml, isRichTextValue)
+  // Phase B — opt every plain-text field in the panel into y-prosemirror
+  // backing when collab is on. `TextLikeInput` checks this registry; if it's
+  // populated AND a `<RecordCollabRoom>` is up-tree AND the field hasn't opted
+  // out via `.collab(false)`, the renderer mounts `CollabTextRenderer`
+  // instead of the legacy `Y.Text` + `computeDelta` + `preserveCursor` path.
+  registerCollabTextRenderer(CollabTextRenderer)
 }