@pilotiq/pilotiq 0.13.1 → 0.15.0

package/src/Page.ts

@@ -4,6 +4,34 @@ import type { ResourceClass, NavigationBadgeColor, NavigationBadgeHandler } from
 import type { ClusterClass } from './Cluster.js'
 import { type IconValue, serializeIcon } from './icons/types.js'
 
+/**
+ * Per-custom-page collab configuration. Custom pages have no record id
+ * to derive a room from, so `room` is required and must be supplied as
+ * a literal string (e.g. `'team-settings'`). The plugin reads this off
+ * the panel-level `pageCollab` map and uses it to seed the page's
+ * Y.Doc.
+ *
+ *   room     — literal room identifier; namespaced internally so two
+ *              pages with the same `room` literal collide deliberately.
+ *   presence — when false, suppress the awareness layer (focus chips,
+ *              cursor positions) while keeping value-sync. Defaults to true.
+ *
+ * Field-level `.collab(false)` always wins per field. Resource-bound
+ * default pages (List/Create/Edit/View) ignore this — record-scoped
+ * collab is governed by `Resource.collab`.
+ */
+export interface PageCollabConfig {
+  room:     string
+  presence: boolean
+}
+
+/** Raw shape accepted by `static collab` before normalization. Unlike
+ * `Resource.collab` there is no `true` shorthand — `room` is required. */
+export type PageCollabInput = {
+  room:      string
+  presence?: boolean
+}
+
 /**
  * Discriminator the framework uses for default rendering, route generation,
  * and breadcrumbs. `'custom'` is for standalone Pages that don't belong to
@@ -107,6 +135,38 @@ export class Page {
     return this._schemaDef !== undefined || this.schema !== Page.schema
   }
 
+  // ─── Realtime collab opt-in ────────────────────────────────
+  // Per-page opt-in for custom Pages. Resource-bound default pages
+  // (List/Create/Edit/View) ignore this — record-scoped collab is
+  // governed by `Resource.collab`. Set on a custom Page subclass to
+  // mount the plugin-registered custom-page wrapper around its content
+  // area at runtime.
+
+  /** Enable collab on this custom page. `room` is required (no recordId
+   * to derive one from). Omitting `static collab` keeps the page
+   * collab-free even when the `@pilotiq-pro/collab` plugin is installed. */
+  static collab: PageCollabInput | null = null
+
+  /**
+   * Normalize `static collab` into the canonical wire shape, or return
+   * `null` when the page has not opted in. Centralizes the `presence`
+   * default. Resource-bound default pages always return `null` here —
+   * use `Resource.collab` for those.
+   *
+   * Result lands on `panelInfo().pageCollab[slug]`; the gate reads it to
+   * decide whether to mount the custom-page wrapper.
+   */
+  static getResolvedCollabConfig(): PageCollabConfig | null {
+    if (this.getMode() !== 'custom') return null
+    const raw = this.collab
+    if (raw === null || raw === undefined) return null
+    if (typeof raw.room !== 'string' || raw.room.length === 0) return null
+    return {
+      room:     raw.room,
+      presence: raw.presence ?? true,
+    }
+  }
+
   /** Plan #10: authorization. Custom pages get a single `canAccess` gate
    * (no per-record predicates — pages are too freeform to assume a
    * record concept). Resource-bound default page subclasses can still

package/src/fields/MarkdownField.ts

@@ -36,20 +36,31 @@ export const DEFAULT_MARKDOWN_TOOLBAR: readonly MarkdownToolbarButton[] = [
 ] as const
 
 /**
- * Plain-markdown editor. The wire format is identical to `TextareaField` —
- * a single string under the field name — so no new coerce branch is
- * needed. The client mounts a `<textarea>` plus a formatting toolbar and
- * a live HTML preview pane (rendered via `marked`).
+ * Markdown editor. The wire format is a plain markdown string under the
+ * field name — same shape as `TextareaField`, so no new coerce branch
+ * is needed.
+ *
+ * **Renderer is pluggable.** When `@pilotiq/tiptap` is installed, its
+ * `registerTiptap()` hook wires a WYSIWYG editor that parses the
+ * markdown into a Tiptap document, exposes a rich-text toolbar, and
+ * serializes back to markdown on every change via `tiptap-markdown`.
+ * Editor / Source / Preview tabs let users switch between the WYSIWYG
+ * view, raw markdown, and a rendered preview without leaving the form.
+ * Collab is automatic — when a `<RecordCollabRoom>` is mounted up-tree
+ * the editor binds to the shared `Y.XmlFragment` and all peers see live
+ * edits, the same way `RichTextField` does. Without `@pilotiq/tiptap`,
+ * `MarkdownInput` falls back to a textarea with a formatting toolbar +
+ * a preview tab — works fine for panels that don't install the adapter.
  *
  * The toolbar is configurable via `toolbarButtons([…])` /
- * `disableToolbarButtons([…])`; pass `[]` to ship a chrome-less textarea
- * with just a preview tab.
+ * `disableToolbarButtons([…])`; pass `[]` to hide the toolbar entirely.
  *
- * `attachFiles` integrates with the panel's `UploadAdapter` (the same one
- * `FileUpload` uses) — the toolbar button + paste-image handler upload
- * the file via `POST {base}/_uploads` and splice an `![alt](url)` reference
- * at the cursor. When no adapter is registered, the button is stripped
- * server-side so apps without uploads never see a broken affordance.
+ * `attachFiles` integrates with the panel's `UploadAdapter` (the same
+ * one `FileUpload` uses) — the toolbar button uploads the file via
+ * `POST {base}/_uploads` and inserts an `![alt](url)` image (or a
+ * `[name](url)` link for non-images). When no adapter is registered,
+ * the button is stripped server-side so apps without uploads never see
+ * a broken affordance.
  *
  * @example
  * ```ts

package/src/index.ts

@@ -83,7 +83,7 @@ export {
 } from './RelationManager.js'
 export { Global, type GlobalPages, type GlobalClass } from './Global.js'
 export { Cluster, type ClusterClass } from './Cluster.js'
-export { Page, type PageMeta, type PageMode } from './Page.js'
+export { Page, type PageMeta, type PageMode, type PageCollabConfig, type PageCollabInput } from './Page.js'
 export {
   // Page base classes — extend these to bind a Page to a Resource.
   ListPage, CreatePage, EditPage, ViewPage,

package/src/pageData/navigation.ts

@@ -1,5 +1,5 @@
 import type { Pilotiq, PilotiqConfig } from '../Pilotiq.js'
-import type { Page } from '../Page.js'
+import type { Page, PageCollabConfig } from '../Page.js'
 import type { ResourceClass, NavigationBadgeColor, ResourceCollabConfig } from '../Resource.js'
 import type { GlobalClass } from '../Global.js'
 import type { ClusterClass } from '../Cluster.js'
@@ -223,6 +223,34 @@ function buildRecordCollabMap(cfg: Readonly<PilotiqConfig>): RecordCollabMap | u
   return Object.keys(map).length > 0 ? map : undefined
 }
 
+/**
+ * Per-custom-page collab opt-in map, keyed by the page's URL slug
+ * (cluster-prefixed for clustered pages). `CustomPageWrapperGate`
+ * reads this to decide whether to mount the plugin-registered
+ * custom-page wrapper (collab room, audit trail, …) around the page
+ * content area.
+ *
+ * Resource-bound default pages (List/Create/Edit/View) never appear
+ * here — `Page.getResolvedCollabConfig()` returns `null` for them.
+ * Record-scoped collab is governed by `Resource.collab` and lands on
+ * `recordCollab`.
+ */
+export type PageCollabMap = Record<string, PageCollabConfig>
+
+function pageSlugForGate(P: typeof Page): string {
+  const slug = P.getSlug()
+  return P.cluster ? `${P.cluster.getSlug()}/${slug}` : slug
+}
+
+function buildPageCollabMap(cfg: Readonly<PilotiqConfig>): PageCollabMap | undefined {
+  const map: PageCollabMap = {}
+  for (const P of cfg.pages) {
+    const collab = P.getResolvedCollabConfig()
+    if (collab) map[pageSlugForGate(P)] = collab
+  }
+  return Object.keys(map).length > 0 ? map : undefined
+}
+
 export async function panelInfo(
   pilotiq: Pilotiq,
   req?:    unknown,
@@ -240,6 +268,7 @@ export async function panelInfo(
   ])
   const databaseNotifications = buildDatabaseNotificationsMeta(cfg, user)
   const recordCollab = buildRecordCollabMap(cfg)
+  const pageCollab = buildPageCollabMap(cfg)
   // AI suggestion mode — sparse: omit when 'auto' (the default) so the
   // wire shape stays minimal for panels that don't opt into review mode.
   // Plugin clients (e.g. @pilotiq-pro/ai's `AiClientToolBindings`) read
@@ -256,6 +285,7 @@ export async function panelInfo(
     ...(databaseNotifications ? { databaseNotifications } : {}),
     ...(rightSidebar ? { rightSidebar } : {}),
     ...(recordCollab ? { recordCollab } : {}),
+    ...(pageCollab ? { pageCollab } : {}),
     ...(Object.keys(renderHooks).length > 0 ? { renderHooks } : {}),
     ...(aiSuggestionsMode !== 'auto' ? { aiSuggestionsMode } : {}),
   }

package/src/pageData.test.ts

@@ -1406,3 +1406,45 @@ describe('panelInfo — recordCollab map (resource collab opt-in)', () => {
     })
   })
 })
+
+describe('panelInfo — pageCollab map (custom-page collab opt-in)', () => {
+  it('absent when no page opts in', async () => {
+    class Analytics extends Page {
+      static override slug  = 'analytics'
+      static override label = 'Analytics'
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').pages([Analytics]))
+    assert.equal((info as { pageCollab?: unknown }).pageCollab, undefined)
+  })
+
+  it('emits an entry per opted-in custom page keyed by URL slug', async () => {
+    class Settings extends Page {
+      static override slug   = 'settings'
+      static override label  = 'Settings'
+      static override collab = { room: 'settings-general' }
+    }
+    class Analytics extends Page {
+      static override slug  = 'analytics'
+      static override label = 'Analytics'
+      // No collab — should NOT appear in the map.
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').pages([Settings, Analytics]))
+    const map = (info as { pageCollab?: Record<string, unknown> }).pageCollab
+    assert.deepEqual(map, {
+      settings: { room: 'settings-general', presence: true },
+    })
+  })
+
+  it('object form can suppress presence', async () => {
+    class Settings extends Page {
+      static override slug   = 'settings'
+      static override label  = 'Settings'
+      static override collab = { room: 'settings', presence: false }
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').pages([Settings]))
+    const map = (info as { pageCollab?: Record<string, unknown> }).pageCollab
+    assert.deepEqual(map, {
+      settings: { room: 'settings', presence: false },
+    })
+  })
+})

package/src/react/AppShell.tsx

@@ -11,6 +11,7 @@ import { RightPanelRegistryProvider } from './right-panel-registry.js'
 import { RightSidebarProvider, useRightSidebarOptional } from './RightSidebarContext.js'
 import { RightSidebar } from './RightSidebar.js'
 import { RecordWrapperGate, type RecordCollabMap } from './RecordWrapperGate.js'
+import { CustomPageWrapperGate, type PageCollabMap } from './CustomPageWrapperGate.js'
 import { useIsMobile } from './hooks/use-mobile.js'
 import type { NavItem, UserMenuMeta, DatabaseNotificationsMeta, RightSidebarMeta } from '../pageData.js'
 import type { RenderHookMap } from '../RenderHook.js'
@@ -39,6 +40,10 @@ export interface AppShellProps {
      *  decide whether to mount the plugin-registered RecordWrapper on
      *  a record edit/view URL. Absent when no resource opted in. */
     recordCollab?: RecordCollabMap
+    /** Per-custom-page collab opt-in map — read by `CustomPageWrapperGate`
+     *  to decide whether to mount the plugin-registered CustomPageWrapper
+     *  on a custom-page URL. Absent when no page opted in. */
+    pageCollab?: PageCollabMap
     /** Pre-resolved render-hook slots for the panel chrome (body /
      *  topbar / sidebar / user-menu / footer / head). Sparse map —
      *  slots with no registered entries are absent. Built by
@@ -137,7 +142,13 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
         {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
         {...(props.panel.recordCollab !== undefined ? { recordCollab: props.panel.recordCollab } : {})}
       >
-        {props.children}
+        <CustomPageWrapperGate
+          basePath={props.basePath}
+          {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
+          {...(props.panel.pageCollab !== undefined ? { pageCollab: props.panel.pageCollab } : {})}
+        >
+          {props.children}
+        </CustomPageWrapperGate>
       </RecordWrapperGate>
     ),
   }

package/src/react/CustomPageWrapperGate.tsx

@@ -0,0 +1,69 @@
+import { type ReactNode } from 'react'
+import { getCustomPageWrapper } from './CustomPageWrapperRegistry.js'
+import type { PageCollabConfig } from '../Page.js'
+
+/** Per-custom-page collab opt-in keyed by URL slug (`P.getSlug()` for
+ * non-clustered, `${cluster.slug}/${P.getSlug()}` for clustered). Built
+ * server-side by `panelInfo()` as `pageCollab`. */
+export type PageCollabMap = Record<string, PageCollabConfig>
+
+export interface CustomPageWrapperGateProps {
+  currentPath?: string
+  basePath:     string
+  /** Per-page opt-in map. Absent means no custom page opted in — gate
+   *  always passes through. */
+  pageCollab?: PageCollabMap
+  children:    ReactNode
+}
+
+/**
+ * Strip `basePath` from `currentPath` and return the remaining slash-
+ * joined tail. Returns `null` when the path is empty / doesn't start
+ * with `basePath` / has no tail. Mirrors `parseRecordPageUrl`'s
+ * normalization (trailing slash on either side is tolerated).
+ */
+function pageSlugFromUrl(currentPath: string, basePath: string): string | null {
+  if (!currentPath) return null
+  const trimmedPath = currentPath.replace(/\/+$/, '')
+  const trimmedBase = basePath.replace(/\/+$/, '')
+
+  if (trimmedBase !== '' && !trimmedPath.startsWith(trimmedBase)) return null
+
+  const tail = trimmedPath.slice(trimmedBase.length).replace(/^\/+/, '')
+  if (tail.length === 0) return null
+  return tail
+}
+
+/**
+ * Conditionally wraps the page tree with the plugin-registered
+ * `CustomPageWrapper` when the current URL resolves to a custom page
+ * (a `Page` subclass with `static collab = { room: '…' }`).
+ * Pass-through in every other case:
+ *
+ *   - no plugin registered a wrapper (`getCustomPageWrapper() === null`)
+ *   - `currentPath` not yet known on the very first SSR render
+ *   - `pageCollab` map absent (no page opted in)
+ *   - the URL tail doesn't match any registered page slug (resource
+ *     list/edit/view pages, dashboard, theme editor, etc.)
+ *
+ * Mounted inside `AppShell` around the page content area, beside
+ * `RecordWrapperGate`. The two gates are mutually exclusive in
+ * practice — record routes have 3+ segments ending in /edit or /view,
+ * custom-page routes are 1-2 segments matching a registered page slug.
+ */
+export function CustomPageWrapperGate({ currentPath, basePath, pageCollab, children }: CustomPageWrapperGateProps) {
+  const Wrapper = getCustomPageWrapper()
+  if (!Wrapper || !currentPath || !pageCollab) return <>{children}</>
+
+  const slug = pageSlugFromUrl(currentPath, basePath)
+  if (!slug) return <>{children}</>
+
+  const cfg = pageCollab[slug]
+  if (!cfg) return <>{children}</>
+
+  return (
+    <Wrapper pageSlug={slug} room={cfg.room} presence={cfg.presence}>
+      {children}
+    </Wrapper>
+  )
+}

package/src/react/CustomPageWrapperRegistry.ts

@@ -0,0 +1,45 @@
+import type { ComponentType, ReactNode } from 'react'
+
+/**
+ * Props the custom-page wrapper receives from `CustomPageWrapperGate`
+ * when the current URL resolves to an opted-in custom page (a `Page`
+ * subclass with `static collab = { room: '…' }`).
+ *
+ * The wrapper owns whatever page-scoped context the plugin provides —
+ * `@pilotiq-pro/collab` mounts a collab room here so every collab
+ * field inside the page tree shares one Y.Doc + WS connection. Other
+ * plugins could mount per-page presence, audit logging, etc.
+ *
+ * `pageSlug` is the gate's URL slug (cluster-prefixed for clustered
+ * pages). `room` is the literal `room` value the page declared on
+ * `static collab` — opaque to pilotiq; the plugin is free to namespace
+ * it internally before opening the WS.
+ */
+export interface CustomPageWrapperProps {
+  pageSlug: string
+  room:     string
+  presence: boolean
+  children: ReactNode
+}
+
+let _component: ComponentType<CustomPageWrapperProps> | null = null
+
+/**
+ * Register a component that wraps the page tree on every opted-in
+ * custom-page route. Called once at boot by a plugin (e.g.
+ * `@pilotiq-pro/collab`). No-op when no plugin registers —
+ * `CustomPageWrapperGate` passes through unchanged.
+ */
+export function registerCustomPageWrapper(C: ComponentType<CustomPageWrapperProps>): void {
+  _component = C
+}
+
+/** Returns the registered wrapper component, or `null`. */
+export function getCustomPageWrapper(): ComponentType<CustomPageWrapperProps> | null {
+  return _component
+}
+
+/** Test-only — drops any registered wrapper so tests stay isolated. */
+export function _resetCustomPageWrapper(): void {
+  _component = null
+}

package/src/react/MarkdownEditorRegistry.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  registerMarkdownEditor,
+  getMarkdownEditor,
+} from './MarkdownEditorRegistry.js'
+
+describe('MarkdownEditorRegistry', () => {
+  beforeEach(() => {
+    registerMarkdownEditor(null)
+  })
+
+  it('returns null when no editor is registered', () => {
+    assert.equal(getMarkdownEditor(), null)
+  })
+
+  it('stores the registered editor component', () => {
+    const Component = () => null
+    registerMarkdownEditor(Component)
+    assert.equal(getMarkdownEditor(), Component)
+  })
+
+  it('clears when called with null', () => {
+    const Component = () => null
+    registerMarkdownEditor(Component)
+    registerMarkdownEditor(null)
+    assert.equal(getMarkdownEditor(), null)
+  })
+
+  it('last registration wins', () => {
+    const A = () => null
+    const B = () => null
+    registerMarkdownEditor(A)
+    registerMarkdownEditor(B)
+    assert.equal(getMarkdownEditor(), B)
+  })
+})

package/src/react/MarkdownEditorRegistry.ts

@@ -0,0 +1,87 @@
+import type { ComponentType } from 'react'
+
+/**
+ * Module-level registry slot for the WYSIWYG markdown editor renderer.
+ *
+ * Wiring posture (mirrors `CollabTextRendererRegistry` /
+ * `FormCollabBindingRegistry`):
+ *   - `@pilotiq/tiptap`'s `registerTiptap(...)` calls `registerMarkdownEditor(...)`
+ *     once at boot. The registered component closes over `@tiptap/*` +
+ *     `tiptap-markdown` imports so pilotiq core stays free of any tiptap peer
+ *     dep — same posture as `CollabTextRendererRegistry`.
+ *   - `MarkdownInput` checks for the registered component on every mount. When
+ *     present, it replaces the legacy textarea + manual-toolbar path with a
+ *     real WYSIWYG editor that serializes to / parses from markdown on the
+ *     wire. When absent, `MarkdownInput` falls back to today's textarea path so
+ *     panels that don't install `@pilotiq/tiptap` still get a working editor.
+ *   - The adapter handles collab itself via the existing `useCollabRoom()` +
+ *     `getCollabExtensions()` plumbing — when a `<RecordCollabRoom>` is mounted
+ *     up-tree it binds the editor to the shared `Y.XmlFragment`. Markdown
+ *     serialization runs locally on every change; only the ProseMirror tree
+ *     ships over the wire.
+ *
+ * Wire format on the form remains a plain markdown string under the field
+ * `name` — `MarkdownField` doesn't add a new coerce branch. The editor is
+ * expected to write the current markdown to a hidden input (or call
+ * `onChange` and let the host stamp it) so the form submission round-trip
+ * stays identical to the textarea path.
+ */
+export interface MarkdownEditorProps {
+  /** Field name — drives the hidden form-input name AND the
+   * `Y.XmlFragment` selector when collab is active. */
+  name: string
+  /**
+   * Server-rendered default value (raw markdown string). The renderer parses
+   * this into the editor's initial document. When collab is active and the
+   * room has no persisted state for this field, the renderer also seeds the
+   * `Y.XmlFragment` from this value.
+   */
+  defaultValue: string
+  /** Optional placeholder hint shown in the editor when empty. */
+  placeholder?: string
+  /** Disabled / read-only state. */
+  disabled?: boolean
+  /** Fired on every editor change with the current serialized markdown. */
+  onChange: (markdown: string) => void
+  /** Fired on editor blur — host wires this to live-onBlur trigger semantics. */
+  onBlur?: () => void
+
+  /**
+   * Configured toolbar buttons. The adapter is free to map these onto its own
+   * command set; unknown / unsupported ids are skipped. Empty array hides
+   * the toolbar entirely. See `MarkdownField.toolbarButtons()`.
+   */
+  toolbarButtons: ReadonlyArray<string>
+  /** CSS height for the editor's collapsed state. */
+  minHeight?: string
+  /** CSS cap on grown height. */
+  maxHeight?: string
+  /** Sub-directory hint forwarded to the upload adapter on paste-image. */
+  fileAttachmentsDirectory?: string
+  /** Adapter-defined visibility hint (`'public'` or `'private'`). */
+  fileAttachmentsVisibility?: string
+  /** Panel upload route — stamped by `pageData.uploadCtx` only when an
+   *  `UploadAdapter` is registered. Absent → adapter hides upload affordances. */
+  uploadUrl?: string
+}
+
+export type MarkdownEditor = ComponentType<MarkdownEditorProps>
+
+let _editor: MarkdownEditor | null = null
+
+/**
+ * Register the WYSIWYG markdown editor component. Called once at boot by
+ * `@pilotiq/tiptap`'s `registerTiptap()` (or directly by an app that imports
+ * the renderer). Calling with `null` clears the registry — useful for tests.
+ *
+ * When no editor is registered, `MarkdownInput` falls back to the textarea +
+ * manual-toolbar path that's worked since `MarkdownField` shipped.
+ */
+export function registerMarkdownEditor(component: MarkdownEditor | null): void {
+  _editor = component
+}
+
+/** Returns the registered editor component, or `null` when no adapter is installed. */
+export function getMarkdownEditor(): MarkdownEditor | null {
+  return _editor
+}

package/src/react/fields/MarkdownInput.tsx

@@ -1,5 +1,6 @@
 import React, { useEffect, useMemo, useRef, useState } from 'react'
 import { marked } from 'marked'
+import type { MarkdownEditor as MarkdownEditorComponent } from '../MarkdownEditorRegistry.js'
 import {
   BoldIcon, ItalicIcon, StrikethroughIcon, LinkIcon,
   HeadingIcon, ListIcon, ListOrderedIcon, QuoteIcon,
@@ -8,6 +9,7 @@ import {
 import { useFieldState } from '../FormStateContext.js'
 import { useCollabRoom } from '../CollabRoomContext.js'
 import { getCollabTextRenderer, type CollabTextRenderer } from '../CollabTextRendererRegistry.js'
+import { getMarkdownEditor } from '../MarkdownEditorRegistry.js'
 import { useRowCoords } from '../RowCoordsContext.js'
 import { parseRowFieldPath } from '../formStateHelpers.js'
 import { useToast } from '../Toaster.js'
@@ -51,8 +53,37 @@ export function MarkdownInput({
   const fs = useFieldState(name)
   const room = useCollabRoom()
   const collabRenderer = getCollabTextRenderer()
+  const markdownEditor = getMarkdownEditor()
   const rowCoords = useRowCoords()
 
+  // Plug-supplied WYSIWYG markdown editor (typically `@pilotiq/tiptap`'s
+  // Tiptap + tiptap-markdown integration). When registered, it replaces
+  // BOTH the legacy non-collab textarea path AND the prior collab plain-text
+  // path with a single rich editor that handles WYSIWYG editing, markdown
+  // serialization, and collab binding (via its own `useCollabRoom()` read)
+  // internally. Repeater/Builder row leaves still bypass it — dotted-path
+  // field names don't have a stable Y.XmlFragment key today; see
+  // `MarkdownCollabInput` below for the prior row-aware path that stays as
+  // the fallback inside Repeater/Builder rows.
+  const isRowLeaf = name.includes('.')
+  if (markdownEditor && !isRowLeaf) {
+    return (
+      <MarkdownEditorHost
+        Editor={markdownEditor}
+        name={name}
+        defaultValue={defaultValue}
+        disabled={disabled}
+        {...(placeholder !== undefined ? { placeholder } : {})}
+        toolbarButtons={toolbarButtons}
+        {...(minHeight !== undefined ? { minHeight } : {})}
+        {...(maxHeight !== undefined ? { maxHeight } : {})}
+        {...(fileAttachmentsDirectory !== undefined ? { fileAttachmentsDirectory } : {})}
+        {...(fileAttachmentsVisibility !== undefined ? { fileAttachmentsVisibility } : {})}
+        {...(uploadUrl !== undefined ? { uploadUrl } : {})}
+      />
+    )
+  }
+
   // Tiptap-backed plain-text editor for markdown source when collab is on.
   // Same architectural fix as `TextLikeInput`'s `CollabTextField`:
   // y-prosemirror's `RelativePosition` cursor anchoring against a
@@ -457,3 +488,60 @@ function stringValue(v: unknown): string {
   if (typeof v === 'string') return v
   return String(v)
 }
+
+/**
+ * Bridges the registered adapter editor (`@pilotiq/tiptap`'s `MarkdownEditor`)
+ * to pilotiq's form-state + form-submit wire shape. The adapter owns the
+ * editor surface (WYSIWYG, toolbar, paste-image, optional source / preview
+ * tabs) and its own collab binding via `useCollabRoom()`; this host just
+ * threads form-state updates and writes the current markdown to a hidden
+ * input so submit picks it up unchanged.
+ */
+function MarkdownEditorHost({
+  Editor, name, defaultValue, disabled, placeholder,
+  toolbarButtons, minHeight, maxHeight,
+  fileAttachmentsDirectory, fileAttachmentsVisibility, uploadUrl,
+}: {
+  Editor:                     MarkdownEditorComponent
+  name:                       string
+  defaultValue:               unknown
+  disabled:                   boolean
+  placeholder?:               string
+  toolbarButtons:             ReadonlyArray<string>
+  minHeight?:                 string
+  maxHeight?:                 string
+  fileAttachmentsDirectory?:  string
+  fileAttachmentsVisibility?: string
+  uploadUrl?:                 string
+}): React.ReactElement {
+  const fs = useFieldState(name)
+  const initial = useMemo(() => stringValue(defaultValue), [])
+  const [text, setText] = useState<string>(initial)
+
+  const handleChange = (next: string): void => {
+    setText(next)
+    if (fs.controlled) fs.setValue(next)
+    fs.triggerLive(next)
+  }
+  const handleBlur = (): void => { /* live trigger already ran on change */ }
+
+  return (
+    <>
+      <input type="hidden" name={name} value={text} readOnly />
+      <Editor
+        name={name}
+        defaultValue={initial}
+        disabled={disabled}
+        {...(placeholder !== undefined ? { placeholder } : {})}
+        toolbarButtons={toolbarButtons}
+        {...(minHeight !== undefined ? { minHeight } : {})}
+        {...(maxHeight !== undefined ? { maxHeight } : {})}
+        {...(fileAttachmentsDirectory !== undefined ? { fileAttachmentsDirectory } : {})}
+        {...(fileAttachmentsVisibility !== undefined ? { fileAttachmentsVisibility } : {})}
+        {...(uploadUrl !== undefined ? { uploadUrl } : {})}
+        onChange={handleChange}
+        onBlur={handleBlur}
+      />
+    </>
+  )
+}

package/src/react/index.ts

@@ -49,6 +49,12 @@ export {
   type CollabTextRenderer,
   type CollabTextRendererProps,
 } from './CollabTextRendererRegistry.js'
+export {
+  registerMarkdownEditor,
+  getMarkdownEditor,
+  type MarkdownEditor,
+  type MarkdownEditorProps,
+} from './MarkdownEditorRegistry.js'
 export {
   registerFormCollabBinding,
   getFormCollabBinding,
@@ -78,6 +84,16 @@ export {
   RecordWrapperGate,
   type RecordWrapperGateProps,
 } from './RecordWrapperGate.js'
+export {
+  registerCustomPageWrapper,
+  getCustomPageWrapper,
+  type CustomPageWrapperProps,
+} from './CustomPageWrapperRegistry.js'
+export {
+  CustomPageWrapperGate,
+  type CustomPageWrapperGateProps,
+  type PageCollabMap,
+} from './CustomPageWrapperGate.js'
 export {
   parseRecordPageUrl,
   parseRecordEditUrl,