@pilotiq/pilotiq 0.8.2 → 0.9.0

package/dist/react/parseRecordEditUrl.js

@@ -1,4 +1,34 @@
-export function parseRecordEditUrl(currentPath, basePath) {
+/**
+ * URL → record-page identity parser. Used by `RecordWrapperGate` (and any
+ * plugin that wants to reason about record-bound URLs) to decide whether
+ * the current page is a record-edit or record-view route.
+ *
+ * A URL matches when:
+ *   1. it starts with the panel's `basePath`
+ *   2. after stripping the prefix it ends with `/edit` or `/view`
+ *   3. there are at least three remaining segments (resource slug,
+ *      record id, terminal token)
+ *
+ * The `resourceSlug` is the slash-joined chain of every segment up to
+ * the record id — this gives clustered resources (`${base}/blog/articles/123/edit`)
+ * and nested-relation edits (`${base}/articles/123/comments/456/edit`)
+ * distinct slugs so two URLs that target different records always
+ * produce different room names downstream.
+ *
+ *   `/admin/articles/123/edit`                      → { slug: 'articles',              id: '123', role: 'edit' }
+ *   `/admin/articles/123/view`                      → { slug: 'articles',              id: '123', role: 'view' }
+ *   `/admin/blog/articles/123/edit`                 → { slug: 'blog/articles',         id: '123', role: 'edit' }
+ *   `/admin/articles/123/comments/456/edit`         → { slug: 'articles/123/comments', id: '456', role: 'edit' }
+ *   `/admin/articles/123/comments`                  → null  (no trailing /edit or /view)
+ *   `/admin/articles/123/comments/create`           → null  (terminal token isn't edit|view)
+ *   `/site/articles/123/edit`                       → null  (basePath mismatch when basePath='/admin')
+ */
+const RECOGNIZED_ROLES = ['edit', 'view'];
+/**
+ * Parse a pilotiq URL into a `{ slug, id, role }` identity. Returns
+ * `null` for any URL that isn't a record-edit or record-view page.
+ */
+export function parseRecordPageUrl(currentPath, basePath) {
     if (!currentPath)
         return null;
     // Normalise — trailing slashes on the URL or trailing slashes on
@@ -11,7 +41,8 @@ export function parseRecordEditUrl(currentPath, basePath) {
     const parts = tail.split('/').filter(Boolean);
     if (parts.length < 3)
         return null;
-    if (parts[parts.length - 1] !== 'edit')
+    const terminal = parts[parts.length - 1];
+    if (!RECOGNIZED_ROLES.includes(terminal))
         return null;
     const recordId = parts[parts.length - 2];
     const slugParts = parts.slice(0, parts.length - 2);
@@ -20,6 +51,13 @@ export function parseRecordEditUrl(currentPath, basePath) {
     return {
         resourceSlug: slugParts.join('/'),
         recordId,
+        role: terminal,
     };
 }
+export function parseRecordEditUrl(currentPath, basePath) {
+    const identity = parseRecordPageUrl(currentPath, basePath);
+    if (!identity || identity.role !== 'edit')
+        return null;
+    return { resourceSlug: identity.resourceSlug, recordId: identity.recordId };
+}
 //# sourceMappingURL=parseRecordEditUrl.js.map

package/dist/react/parseRecordEditUrl.js.map

@@ -1 +1 @@
-{"version":3,"file":"parseRecordEditUrl.js","sourceRoot":"","sources":["../../src/react/parseRecordEditUrl.ts"],"names":[],"mappings":"AA4BA,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,QAAmB;IAEnB,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAA;IAC7B,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACnD,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAEhD,IAAI,WAAW,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAA;IAE3E,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACtE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAE7C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IAEnD,MAAM,QAAQ,GAAM,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAA;IAC5C,MAAM,SAAS,GAAK,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACpD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEvC,OAAO;QACL,YAAY,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;QACjC,QAAQ;KACT,CAAA;AACH,CAAC"}
+{"version":3,"file":"parseRecordEditUrl.js","sourceRoot":"","sources":["../../src/react/parseRecordEditUrl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAiBH,MAAM,gBAAgB,GAAkC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAExE;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,QAAmB;IAEnB,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAA;IAC7B,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,WAAW,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACnD,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAEhD,IAAI,WAAW,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC;QAAE,OAAO,IAAI,CAAA;IAE3E,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IACtE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAE7C,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACjC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAA;IACzC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,QAA0B,CAAC;QAAE,OAAO,IAAI,CAAA;IAEvE,MAAM,QAAQ,GAAM,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAA;IAC5C,MAAM,SAAS,GAAK,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IACpD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAEvC,OAAO;QACL,YAAY,EAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC;QACjC,QAAQ;QACR,IAAI,EAAU,QAA0B;KACzC,CAAA;AACH,CAAC;AAWD,MAAM,UAAU,kBAAkB,CAChC,WAAmB,EACnB,QAAmB;IAEnB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAA;IAC1D,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM;QAAE,OAAO,IAAI,CAAA;IACtD,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAA;AAC7E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotiq/pilotiq",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "View-based admin panel for RudderJS",
   "license": "MIT",
   "repository": {

package/src/Resource.test.ts

@@ -237,4 +237,48 @@ describe('Resource (static API)', () => {
       assert.equal(await R.canRestore(null, { ownedBy: 'other' }), false)
     })
   })
+
+  describe('collab opt-in', () => {
+    it('omitted static collab → getResolvedCollabConfig returns null', () => {
+      class R extends Resource {}
+      assert.equal(R.getResolvedCollabConfig(), null)
+    })
+
+    it('static collab = false → null (explicit opt-out)', () => {
+      class R extends Resource {
+        static override collab = false as const
+      }
+      assert.equal(R.getResolvedCollabConfig(), null)
+    })
+
+    it('static collab = true → defaults to { pages: [edit], presence: true }', () => {
+      class R extends Resource {
+        static override collab = true as const
+      }
+      assert.deepEqual(R.getResolvedCollabConfig(), {
+        pages:    ['edit'],
+        presence: true,
+      })
+    })
+
+    it('object form merges with defaults', () => {
+      class R extends Resource {
+        static override collab = { pages: ['edit', 'view'] as const }
+      }
+      assert.deepEqual(R.getResolvedCollabConfig(), {
+        pages:    ['edit', 'view'],
+        presence: true,   // default preserved
+      })
+    })
+
+    it('object form can suppress presence', () => {
+      class R extends Resource {
+        static override collab = { presence: false }
+      }
+      assert.deepEqual(R.getResolvedCollabConfig(), {
+        pages:    ['edit'],   // default preserved
+        presence: false,
+      })
+    })
+  })
 })

package/src/Resource.ts

@@ -50,6 +50,33 @@ export type NavigationBadgeColor =
 export type NavigationBadgeHandler =
   () => string | number | undefined | Promise<string | number | undefined>
 
+/**
+ * Per-resource collab configuration. Set via `static collab = true` (the
+ * 90% case — opts the edit page in with presence) or via the object form
+ * for finer control. Omitting `static collab` entirely keeps the resource
+ * collab-free even when the `@pilotiq-pro/collab` plugin is registered.
+ *
+ *   pages    — page roles where collab activates. `'edit'` syncs values +
+ *              presence; `'view'` is presence-only (the page is read-only,
+ *              value-sync would be moot). Defaults to `['edit']`.
+ *   presence — when false, suppress the awareness layer (focus chips,
+ *              cursor positions) while keeping value-sync. Defaults to true.
+ *
+ * Field-level `.collab(false)` always wins over this setting — opting the
+ * resource in then opting individual fields out is the supported shape.
+ */
+export interface ResourceCollabConfig {
+  pages:    ReadonlyArray<'edit' | 'view'>
+  presence: boolean
+}
+
+/** Raw shape accepted by `static collab` before normalization. `true` is a
+ * shorthand for `{ pages: ['edit'], presence: true }`. */
+export type ResourceCollabInput = boolean | {
+  pages?:    ReadonlyArray<'edit' | 'view'>
+  presence?: boolean
+}
+
 /**
  * Abstract Resource base class. **All methods are static** — resources are
  * registered by class, not by instance. Routes look up the class and call
@@ -297,6 +324,37 @@ export abstract class Resource {
     return undefined
   }
 
+  // ─── Realtime collab opt-in ────────────────────────────────
+  // Opt-in per resource. The `@pilotiq-pro/collab` plugin registers the
+  // global singletons (transport, Tiptap extension factory, RecordWrapper
+  // factory); resources with `static collab` unset stay collab-free even
+  // when the plugin is installed. Field-level `.collab(false)` overrides
+  // this setting per field.
+
+  /** Enable collab on this resource. `true` is the 90% case — shorthand
+   * for `{ pages: ['edit'], presence: true }`. Use the object form to
+   * narrow which page roles activate or to suppress presence. Default
+   * `false` (collab off — the WS room is never opened for this resource). */
+  static collab: ResourceCollabInput = false
+
+  /**
+   * Normalize `static collab` into the canonical wire shape, or return
+   * `null` when the resource has opted out. Centralizes the `true` →
+   * defaults expansion and the `{ pages?: … }` merge.
+   *
+   * Result lands on `panelInfo().recordCollab[slug]`; the gate reads it
+   * to decide whether to mount the record wrapper.
+   */
+  static getResolvedCollabConfig(): ResourceCollabConfig | null {
+    const raw = this.collab
+    if (raw === false || raw == null) return null
+    if (raw === true) return { pages: ['edit'], presence: true }
+    return {
+      pages:    raw.pages    ?? ['edit'],
+      presence: raw.presence ?? true,
+    }
+  }
+
   // ─── Plan #10: authorization predicates ────────────────────
   // All async, all default `true`. Routes call them with the resolved
   // user (from `Pilotiq.user(fn)`); the renderer threads the same user

package/src/pageData/navigation.ts

@@ -1,6 +1,6 @@
 import type { Pilotiq, PilotiqConfig } from '../Pilotiq.js'
 import type { Page } from '../Page.js'
-import type { ResourceClass, NavigationBadgeColor } from '../Resource.js'
+import type { ResourceClass, NavigationBadgeColor, ResourceCollabConfig } from '../Resource.js'
 import type { GlobalClass } from '../Global.js'
 import type { ClusterClass } from '../Cluster.js'
 import { resourceBasePath, globalBasePath, pageBasePath } from '../clusterPaths.js'
@@ -194,6 +194,35 @@ export interface PanelInfoRoute {
   url?:      string
 }
 
+/**
+ * Per-resource collab opt-in map, keyed by the URL slug
+ * `parseRecordPageUrl` produces. Non-clustered resource → `getSlug()`;
+ * clustered resource → `${cluster.getSlug()}/${R.getSlug()}`.
+ *
+ * `RecordWrapperGate` reads this map to decide whether the page tree
+ * needs the plugin-registered RecordWrapper (collab room, audit, …)
+ * mounted around the record view/edit content area.
+ *
+ * Nested-relation edit URLs (`/articles/123/comments/456/edit`) have a
+ * dynamic-id segment in the gate's URL slug and don't match here in v1.
+ * Collab on nested-relation edits is a follow-up — top-level resource
+ * edits are the common case and ship now.
+ */
+export type RecordCollabMap = Record<string, ResourceCollabConfig>
+
+function resourceSlugForGate(R: ResourceClass): string {
+  return R.cluster ? `${R.cluster.getSlug()}/${R.getSlug()}` : R.getSlug()
+}
+
+function buildRecordCollabMap(cfg: Readonly<PilotiqConfig>): RecordCollabMap | undefined {
+  const map: RecordCollabMap = {}
+  for (const R of cfg.resources) {
+    const collab = R.getResolvedCollabConfig()
+    if (collab) map[resourceSlugForGate(R)] = collab
+  }
+  return Object.keys(map).length > 0 ? map : undefined
+}
+
 export async function panelInfo(
   pilotiq: Pilotiq,
   req?:    unknown,
@@ -210,6 +239,7 @@ export async function panelInfo(
     buildRightSidebarMeta(cfg, user),
   ])
   const databaseNotifications = buildDatabaseNotificationsMeta(cfg, user)
+  const recordCollab = buildRecordCollabMap(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
@@ -225,6 +255,7 @@ export async function panelInfo(
     ...(userMenu ? { userMenu } : {}),
     ...(databaseNotifications ? { databaseNotifications } : {}),
     ...(rightSidebar ? { rightSidebar } : {}),
+    ...(recordCollab ? { recordCollab } : {}),
     ...(Object.keys(renderHooks).length > 0 ? { renderHooks } : {}),
     ...(aiSuggestionsMode !== 'auto' ? { aiSuggestionsMode } : {}),
   }

package/src/pageData.test.ts

@@ -1202,3 +1202,39 @@ describe('tagRichTextMentionUrls — nested Repeater + Builder rows', () => {
     assert.equal(inner.stamped, '/admin/_form/art/mentions')
   })
 })
+
+describe('panelInfo — recordCollab map (resource collab opt-in)', () => {
+  it('absent when no resource opts in', async () => {
+    class Posts extends Resource { static override label = 'Posts' }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').resources([Posts]))
+    assert.equal((info as { recordCollab?: unknown }).recordCollab, undefined)
+  })
+
+  it('emits an entry for each opted-in resource keyed by URL slug', async () => {
+    class Posts extends Resource {
+      static override label  = 'Posts'
+      static override collab = true as const
+    }
+    class Users extends Resource {
+      static override label  = 'Users'
+      // No collab — should NOT appear in the map.
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').resources([Posts, Users]))
+    const map = (info as { recordCollab?: Record<string, unknown> }).recordCollab
+    assert.deepEqual(map, {
+      posts: { pages: ['edit'], presence: true },
+    })
+  })
+
+  it('honors object form of static collab (pages + presence override defaults)', async () => {
+    class Posts extends Resource {
+      static override label  = 'Posts'
+      static override collab = { pages: ['edit', 'view'] as const, presence: false }
+    }
+    const info = await panelInfo(Pilotiq.make('T').path('/admin').resources([Posts]))
+    const map = (info as { recordCollab?: Record<string, unknown> }).recordCollab
+    assert.deepEqual(map, {
+      posts: { pages: ['edit', 'view'], presence: false },
+    })
+  })
+})

package/src/react/AppShell.tsx

@@ -10,7 +10,7 @@ import type { RightPanelRegistry } from './right-panel-registry.js'
 import { RightPanelRegistryProvider } from './right-panel-registry.js'
 import { RightSidebarProvider, useRightSidebarOptional } from './RightSidebarContext.js'
 import { RightSidebar } from './RightSidebar.js'
-import { RecordWrapperGate } from './RecordWrapperGate.js'
+import { RecordWrapperGate, type RecordCollabMap } from './RecordWrapperGate.js'
 import { useIsMobile } from './hooks/use-mobile.js'
 import type { NavItem, UserMenuMeta, DatabaseNotificationsMeta, RightSidebarMeta } from '../pageData.js'
 import type { RenderHookMap } from '../RenderHook.js'
@@ -34,6 +34,10 @@ export interface AppShellProps {
      *  `panelInfo()` only ships this when at least one contribution
      *  was registered AND passed the auth gate AND is non-hidden. */
     rightSidebar?: RightSidebarMeta
+    /** Per-resource collab opt-in map — read by `RecordWrapperGate` to
+     *  decide whether to mount the plugin-registered RecordWrapper on
+     *  a record edit/view URL. Absent when no resource opted in. */
+    recordCollab?: RecordCollabMap
     /** 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
@@ -130,6 +134,7 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
       <RecordWrapperGate
         basePath={props.basePath}
         {...(props.currentPath !== undefined ? { currentPath: props.currentPath } : {})}
+        {...(props.panel.recordCollab !== undefined ? { recordCollab: props.panel.recordCollab } : {})}
       >
         {props.children}
       </RecordWrapperGate>

package/src/react/FormCollabBindingRegistry.ts

@@ -1,5 +1,44 @@
+import type { ElementMeta } from '../schema/Element.js'
 import type { CollabRoom } from './CollabRoomContext.js'
 
+/**
+ * Phase F.6 — character-level edit op emitted by `TextLikeInput` and
+ * applied through `TextBinding.applyDelta`. `replace` covers IME / paste
+ * / multi-char selections; `insert` and `delete` cover the single-key
+ * common path. Pilotiq core stays Yjs-free — the binding impl in
+ * `@pilotiq-pro/collab` translates these into `Y.Text.insert / delete`
+ * inside a transaction.
+ */
+export type TextDelta =
+  | { kind: 'insert',  index: number,  text: string }
+  | { kind: 'delete',  index: number,  length: number }
+  | { kind: 'replace', from:  number,  to: number, text: string }
+
+/**
+ * Phase F.6 — per-field character-level CRDT handle. Issued by
+ * `FormCollabBinding.getTextBinding(name)` for text-shaped fields
+ * (`TextField / TextareaField / EmailField / SlugField / MarkdownField`);
+ * returns `null` for non-text fields or text fields opted out via
+ * `.collab(false)`. The surface stays intentionally narrow so pilotiq
+ * core never touches Yjs directly — same posture as `FormCollabBinding`.
+ *
+ *   - `read()` returns the current full string. `TextLikeInput` calls
+ *     this once on mount to seed its controlled value.
+ *   - `applyDelta(delta)` is called from `onInput` events with a single
+ *     `insert / delete / replace` op derived from the input's selection.
+ *   - `observe(fn)` registers a remote-change listener; `fn(next)`
+ *     receives the post-change string. Returns an unsubscribe function.
+ *   - `destroy()` cleans up everything the handle holds. The owning
+ *     `FormCollabBinding.destroy()` is expected to cascade — consumers
+ *     don't need to call this directly.
+ */
+export interface TextBinding {
+  read():     string
+  applyDelta(delta: TextDelta): void
+  observe(fn: (next: string) => void): () => void
+  destroy():  void
+}
+
 /**
  * Binding contract that a collab plugin returns from
  * `registerFormCollabBinding` — wraps a single form's value map in a
@@ -16,8 +55,14 @@ import type { CollabRoom } from './CollabRoomContext.js'
  *   - `subscribe(fn)` registers a listener that fires when REMOTE
  *     changes land; `fn(snapshot)` receives the full updated map.
  *     The provider re-applies this snapshot onto its React state.
+ *   - `getTextBinding(name)` (Phase F.6) returns a `Y.Text`-backed
+ *     handle for text-shaped fields, or `null` for non-text fields and
+ *     text fields opted out via `.collab(false)`. The text/non-text
+ *     allowlist lives in the binding impl — `FormStateProvider` asks
+ *     for every field and routes per-field on the answer.
  *   - `destroy()` is called on unmount — gives the plugin a chance to
- *     remove its CRDT observer.
+ *     remove its CRDT observer. Implementations are expected to cascade
+ *     into every `TextBinding` they issued.
  *
  * `unknown` payloads keep pilotiq core Yjs-free; the binding owns its
  * own type knowledge. Same posture as `CollabExtensionFactory`.
@@ -29,6 +74,12 @@ export interface FormCollabBinding {
   set(name: string, value: unknown): void
   /** Subscribe to remote changes. Returns an unsubscribe function. */
   subscribe(fn: (snapshot: Record<string, unknown>) => void): () => void
+  /** Phase F.6 — per-field text-CRDT handle. Returns `null` for non-text
+   *  fields or text fields opted out via `.collab(false)`. Optional so
+   *  existing F1-era plugins keep type-checking without a no-op stub;
+   *  when absent, every text field stays on today's whole-string LWW
+   *  path (i.e. F.6 character-level CRDT is opt-in by impl). */
+  getTextBinding?(name: string): TextBinding | null
   /** Cleanup hook called when the form unmounts. */
   destroy():    void
 }
@@ -51,6 +102,17 @@ export interface FormCollabBindingFactoryArgs {
    * map already populated and skip.
    */
   initial: Record<string, unknown>
+  /**
+   * Phase F.6 — initial form meta from the server. The binding walks
+   * this once at construction to decide which fields are text-shaped
+   * (`fieldType ∈ { text, textarea, email, slug, markdown }`) and
+   * which have opted out via `.collab(false)`. Text fields get a
+   * dedicated `Y.Text` and route through `getTextBinding`; non-text
+   * fields stay on the `Y.Map`. The meta is captured at mount; later
+   * structural changes from `live()` re-resolves aren't re-walked
+   * (rare in practice — dynamic field add/remove is an F-followup).
+   */
+  formMeta: ElementMeta
 }
 
 export type FormCollabBindingFactory = (args: FormCollabBindingFactoryArgs) => FormCollabBinding

package/src/react/FormStateContext.tsx

@@ -18,7 +18,11 @@ import {
 import { runJsHandler } from './fieldJsHandler.js'
 import { useToast } from './Toaster.js'
 import { useCollabRoom } from './CollabRoomContext.js'
-import { getFormCollabBinding, type FormCollabBinding } from './FormCollabBindingRegistry.js'
+import {
+  getFormCollabBinding,
+  type FormCollabBinding,
+  type TextBinding,
+} from './FormCollabBindingRegistry.js'
 
 export type FieldStatus = 'idle' | 'pending'
 
@@ -40,6 +44,13 @@ export interface FormStateApi {
   formMeta:      ElementMeta
   inFlight:      boolean
   fieldStatus:   (name: string) => FieldStatus
+  /** Phase F.6 — per-field text-CRDT handles stashed at collab-room mount.
+   *  `null` outside a room or before the binding effect has populated the
+   *  map. The text/non-text allowlist lives in the binding impl —
+   *  `FormStateProvider` asks for every top-level field and only stashes
+   *  non-null answers, so a `Map.get()` hit means the binding has opted
+   *  this field into the character-level path. */
+  textBindings:  ReadonlyMap<string, TextBinding> | null
 }
 
 const FormStateContext = createContext<FormStateApi | null>(null)
@@ -93,6 +104,15 @@ export interface UseFieldStateResult {
   /** True while a live re-resolve POST is in flight for this field. */
   pending:     boolean
   errors:      string[]
+  /** Phase F.6 — character-level CRDT handle for text-shaped fields when
+   *  a collab room is mounted up-tree AND the binding strategy applies
+   *  (allowlist + `.collab() !== false`). Null in every other case —
+   *  outside a `FormStateProvider`, outside a `<RecordCollabRoom>`, on
+   *  non-text fields, on dotted-path inner-Repeater rows (deferred to
+   *  F.5), and on text fields opted out via `.collab(false)`. Text input
+   *  renderers branch on this: non-null → character-level path with
+   *  `applyDelta + observe`; null → today's whole-string LWW path. */
+  textBinding: TextBinding | null
 }
 
 /** Per-field accessor. Inside a `FormStateProvider` it returns the controlled
@@ -108,6 +128,7 @@ export function useFieldState(name: string): UseFieldStateResult {
       triggerLive: () => {},
       pending:     false,
       errors:      [],
+      textBinding: null,
     }
   }
   // Dotted-path fields (inner Repeater rows) always render uncontrolled
@@ -120,6 +141,11 @@ export function useFieldState(name: string): UseFieldStateResult {
     triggerLive: (valueOverride?: unknown) => ctx.triggerLive(name, valueOverride),
     pending:     ctx.fieldStatus(name) === 'pending',
     errors:      ctx.errors[name] ?? [],
+    // Phase F.6 — dotted-path inner-Repeater rows skipped in v1 (deferred
+    // to F.5 alongside Y.Array row identity). Outside a collab room or
+    // for non-text fields, the stash returns null and the renderer falls
+    // back to today's whole-string LWW path.
+    textBinding: dotted ? null : (ctx.textBindings?.get(name) ?? null),
   }
 }
 
@@ -170,6 +196,13 @@ export function FormStateProvider({
   const [errors,   setErrors] = useState<Record<string, string[]>>(initialErrors)
   const [pendingNames, setPendingNames] = useState<Set<string>>(() => new Set())
   const [inFlight, setInFlight] = useState(false)
+  // Phase F.6 — per-field text-CRDT stash. `null` until the collab effect
+  // populates it; stays `null` outside a collab room. Stored in state (not
+  // a ref) so consumers of `useFieldState` re-render once the bindings
+  // land. One extra render after collab-mount; acceptable since the
+  // existing `setValuesState` overlay below already triggers one when the
+  // room has pre-existing state.
+  const [textBindings, setTextBindings] = useState<ReadonlyMap<string, TextBinding> | null>(null)
 
   const { notify } = useToast()
 
@@ -215,7 +248,12 @@ export function FormStateProvider({
   useEffect(() => {
     if (!collabRoom || !bindingFactory || !formId) return
 
-    const binding = bindingFactory({ room: collabRoom, formId, initial: valuesRef.current })
+    const binding = bindingFactory({
+      room:     collabRoom,
+      formId,
+      initial:  valuesRef.current,
+      formMeta: formMetaRef.current,
+    })
     bindingRef.current = binding
 
     // Lift any state already in the room (subsequent joiners — first
@@ -228,6 +266,25 @@ export function FormStateProvider({
       setValuesState((prev) => ({ ...prev, ...synced }))
     }
 
+    // Phase F.6 — ask the binding for a `TextBinding` on every top-level
+    // field name. The text/non-text allowlist lives in the binding impl,
+    // not in core: the binding returns `null` for non-text fields and
+    // text fields opted out via `.collab(false)`. `getTextBinding` is
+    // optional on the contract — F1-era plugins that haven't implemented
+    // it short-circuit the whole stash and every text field stays on the
+    // LWW path. We stash only the non-null answers. Cleanup is owned by
+    // `binding.destroy()` (expected to cascade into every issued
+    // `TextBinding`).
+    if (binding.getTextBinding) {
+      const textStash = new Map<string, TextBinding>()
+      for (const fieldName of Object.keys(valuesRef.current)) {
+        if (fieldName.includes('.')) continue
+        const tb = binding.getTextBinding(fieldName)
+        if (tb) textStash.set(fieldName, tb)
+      }
+      if (textStash.size > 0) setTextBindings(textStash)
+    }
+
     // Subscribe to remote changes. Local writes ALSO trigger this
     // (Yjs observers fire on local transactions too) — the per-key
     // Object.is short-circuit below collapses them into no-op renders.
@@ -249,6 +306,7 @@ export function FormStateProvider({
       unsubscribe()
       binding.destroy()
       bindingRef.current = null
+      setTextBindings(null)
     }
     // `valuesRef.current` is intentionally read once at mount — initial
     // values seed the binding; subsequent edits flow through `setValue`
@@ -479,7 +537,8 @@ export function FormStateProvider({
     formMeta,
     inFlight,
     fieldStatus,
-  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus])
+    textBindings,
+  }), [values, setValue, triggerLive, errors, applyErrors, formMeta, inFlight, fieldStatus, textBindings])
 
   return (
     <FormStateContext.Provider value={api}>

package/src/react/RecordWrapperGate.tsx

@@ -1,37 +1,55 @@
 import { type ReactNode } from 'react'
 import { getRecordWrapper } from './RecordWrapperRegistry.js'
-import { parseRecordEditUrl } from './parseRecordEditUrl.js'
+import { parseRecordPageUrl } from './parseRecordEditUrl.js'
+import type { ResourceCollabConfig } from '../Resource.js'
+
+/** Per-resource collab opt-in keyed by URL slug (`R.getSlug()` for
+ * non-clustered, `${cluster.slug}/${R.getSlug()}` for clustered). Built
+ * server-side by `panelInfo()` as `recordCollab`. */
+export type RecordCollabMap = Record<string, ResourceCollabConfig>
 
 export interface RecordWrapperGateProps {
   currentPath?: string
   basePath:     string
+  /** Resource opt-in map. Absent means no resource opted in (or the
+   *  panel has no resources) — gate always passes through. */
+  recordCollab?: RecordCollabMap
   children:     ReactNode
 }
 
 /**
  * Conditionally wraps the page tree with the plugin-registered
- * `RecordWrapper` when the current URL resolves to a record-bound edit
- * page. Pass-through in every other case:
+ * `RecordWrapper` when the current URL resolves to a record-bound page
+ * AND the underlying resource has opted into collab on that page role.
+ * Pass-through in every other case:
  *
  *   - no plugin registered a wrapper (`getRecordWrapper() === null`)
- *   - the URL isn't a record-edit URL (list / create / view / dashboard / …)
+ *   - the URL isn't a record edit/view page
  *   - `currentPath` not yet known on the very first SSR render
+ *   - the resource has not opted in via `static collab` (or has opted in
+ *     but excluded the current page role)
  *
  * Mounted once inside `AppShell` around the page content area so
  * record-scoped plugins (collab room, audit trail, …) get one
  * lifetimed mount per record-view-or-edit without each plugin having
  * to thread URL parsing into its own provider.
  *
- * Scope limited to `/edit` URLs in v1; view-page support (read-only
- * collab cursors on `ViewPage`) is a follow-up.
+ * v1 caveat: nested-relation edit URLs (`/articles/:parentId/comments/:childId/edit`)
+ * have a dynamic-id segment baked into the URL slug, so they don't match
+ * the resource-keyed `recordCollab` map and fall through to no-collab.
+ * Collab on nested-relation edits is a follow-up.
  */
-export function RecordWrapperGate({ currentPath, basePath, children }: RecordWrapperGateProps) {
+export function RecordWrapperGate({ currentPath, basePath, recordCollab, children }: RecordWrapperGateProps) {
   const Wrapper = getRecordWrapper()
   if (!Wrapper || !currentPath) return <>{children}</>
 
-  const identity = parseRecordEditUrl(currentPath, basePath)
+  const identity = parseRecordPageUrl(currentPath, basePath)
   if (!identity) return <>{children}</>
 
+  const cfg = recordCollab?.[identity.resourceSlug]
+  if (!cfg) return <>{children}</>
+  if (!cfg.pages.includes(identity.role)) return <>{children}</>
+
   return (
     <Wrapper resourceSlug={identity.resourceSlug} recordId={identity.recordId}>
       {children}