@pilotiq/pilotiq 0.20.0 → 0.22.0

package/src/PilotiqServiceProvider.ts

@@ -3,9 +3,14 @@ import type { Application } from '@rudderjs/core'
 import type { Pilotiq } from './Pilotiq.js'
 import { PilotiqRegistry } from './PilotiqRegistry.js'
 import { registerPilotiqRoutes } from './routes.js'
+import { migrateThemeOverrides } from './theme/migrate.js'
+import { prismaThemeStorage } from './theme/storage.js'
+import type { PanelGlobalDelegate, ThemeStorageAdapter } from './theme/storage.js'
 
 // ─── Service Provider ─────────────────────────────────────
 
+const autoFallbackWarned = new Set<string>()
+
 class PilotiqServiceProvider extends ServiceProvider {
   private panels: Pilotiq[]
 
@@ -26,25 +31,72 @@ class PilotiqServiceProvider extends ServiceProvider {
       router: Parameters<typeof registerPilotiqRoutes>[0]
     }
 
-    // Load saved theme overrides from DB for panels with themeEditor enabled
     for (const panel of PilotiqRegistry.all()) {
       if (panel.getConfig().themeEditor) {
-        try {
-          const prisma = this.app.make('prisma') as any
-          const slug = `${panel.getConfig().name}__theme`
-          const row = await prisma.panelGlobal.findUnique({ where: { slug } })
-          if (row?.data) {
-            const raw = typeof row.data === 'string' ? JSON.parse(row.data as string) : row.data
-            const { migrateThemeOverrides } = await import('./theme/migrate.js')
-            panel.setThemeOverrides(migrateThemeOverrides(raw))
-          }
-        } catch { /* no DB or no table — use code defaults */ }
+        await loadThemeOverrides(this.app, panel)
       }
       registerPilotiqRoutes(router, panel)
     }
   }
 }
 
+/**
+ * Resolve the panel's theme storage adapter and hydrate any persisted
+ * overrides onto the panel.
+ *
+ * - Explicit `themeEditor({ storage })`: errors bubble (the user opted
+ *   in, misconfiguration should surface loudly).
+ * - Implicit Prisma fallback: errors swallowed for back-compat with a
+ *   one-time deprecation warning. Removing this branch is the breaking
+ *   change scheduled for the next minor.
+ */
+async function loadThemeOverrides(app: Application, panel: Pilotiq): Promise<void> {
+  const adapter = resolveThemeStorage(app, panel)
+  if (!adapter) return
+
+  const isExplicit = panel.getConfig().themeStorage === adapter
+  if (!isExplicit) panel._setThemeStorage(adapter)
+
+  try {
+    const overrides = await adapter.load()
+    if (overrides) panel.setThemeOverrides(migrateThemeOverrides(overrides))
+  } catch (e) {
+    if (isExplicit) throw e
+    // Implicit fallback: swallow connection / schema errors. Removed
+    // alongside the auto-fallback branch in a future minor.
+  }
+}
+
+function resolveThemeStorage(app: Application, panel: Pilotiq): ThemeStorageAdapter | null {
+  const explicit = panel.getConfig().themeStorage
+  if (explicit) return explicit
+
+  let prisma: PanelGlobalDelegate | null
+  try {
+    prisma = app.make('prisma') as PanelGlobalDelegate
+  } catch {
+    return null
+  }
+  if (!prisma || typeof prisma.panelGlobal?.findUnique !== 'function') return null
+
+  const panelName = panel.getConfig().name
+  if (!autoFallbackWarned.has(panelName)) {
+    autoFallbackWarned.add(panelName)
+    console.warn(
+      `[pilotiq] themeEditor() on panel "${panelName}" is using the implicit ` +
+      `Prisma fallback for theme persistence. Pass storage explicitly — ` +
+      `themeEditor({ storage: prismaThemeStorage(prisma, { slug: '${panelName}__theme' }) }) — ` +
+      `the implicit fallback is deprecated and will be removed in a future minor.`,
+    )
+  }
+  return prismaThemeStorage(prisma, { slug: `${panelName}__theme` })
+}
+
+/** @internal — test seam; resets the "deprecation already warned" memo. */
+export function _resetThemeFallbackWarned(): void {
+  autoFallbackWarned.clear()
+}
+
 // ─── Factory ──────────────────────────────────────────────
 
 /**

package/src/actions/importFactory.ts

@@ -65,6 +65,11 @@ export interface ImportOptions {
    *  exceeded — protects against accidental million-row uploads. Default
    *  `10_000`. */
   maxRows?: number
+  /** Number of rows to process in parallel. The importer chunks the row
+   *  list into batches of this size and runs each chunk via `Promise.all`.
+   *  Order within a chunk is non-deterministic; row indices in error
+   *  messages still match the original CSV/JSON position. Default `10`. */
+  concurrency?: number
   /** Final hook after the import loop. Useful for audit-log writes,
    *  cache invalidation, etc. Async-aware. */
   onComplete?: (summary: ImportSummary, ctx: ImportContext) => void | Promise<void>
@@ -123,16 +128,21 @@ export async function runImport(
 ): Promise<ImportSummary> {
   const summary: ImportSummary = { created: 0, updated: 0, skipped: 0, errors: [] }
   const upsertBy = opts.upsertBy
+  const concurrency = Math.max(1, opts.concurrency ?? 10)
 
-  for (let i = 0; i < rows.length; i++) {
-    const row = rows[i]!
+  // Per-row outcome — a small value type so chunks can resolve in any
+  // order and we still accumulate `summary` in original-row order.
+  type RowOutcome =
+    | { kind: 'created' }
+    | { kind: 'updated' }
+    | { kind: 'skipped'; row: number; message: string }
+
+  async function processRow(row: Record<string, unknown>, i: number): Promise<RowOutcome> {
     const rowCtx: ImportContext = { ...ctx, rowIndex: i }
     try {
       const guard = await opts.validate?.(row, rowCtx)
       if (typeof guard === 'string' && guard.length > 0) {
-        summary.skipped++
-        summary.errors.push({ row: i + 1, message: guard })
-        continue
+        return { kind: 'skipped', row: i + 1, message: guard }
       }
 
       if (mode === 'upsert' && upsertBy) {
@@ -144,8 +154,7 @@ export async function runImport(
             ? await opts.beforeUpdate(row, existing, rowCtx)
             : row
           await M.update(id, payload)
-          summary.updated++
-          continue
+          return { kind: 'updated' }
         }
       }
 
@@ -153,10 +162,22 @@ export async function runImport(
         ? await opts.beforeCreate(row, rowCtx)
         : row
       await M.create(payload)
-      summary.created++
+      return { kind: 'created' }
     } catch (err) {
-      summary.skipped++
-      summary.errors.push({ row: i + 1, message: err instanceof Error ? err.message : 'unknown' })
+      return { kind: 'skipped', row: i + 1, message: err instanceof Error ? err.message : 'unknown' }
+    }
+  }
+
+  for (let start = 0; start < rows.length; start += concurrency) {
+    const slice = rows.slice(start, start + concurrency)
+    const outcomes = await Promise.all(slice.map((row, idx) => processRow(row, start + idx)))
+    for (const outcome of outcomes) {
+      if (outcome.kind === 'created')      summary.created++
+      else if (outcome.kind === 'updated') summary.updated++
+      else {
+        summary.skipped++
+        summary.errors.push({ row: outcome.row, message: outcome.message })
+      }
     }
   }
 

package/src/orm/modelDefaults.ts

@@ -50,6 +50,16 @@ export interface ModelQuery {
   orderBy(column: string, direction?: 'ASC' | 'DESC'): ModelQuery
   paginate(page: number, perPage?: number): Promise<{ data: unknown[]; total: number }>
 
+  /**
+   * Single-row `LIMIT 1` SELECT — Laravel-parity sibling of `paginate`
+   * for the "first matching row" case. Optional on the structural shape;
+   * the `@rudderjs/orm` `QueryBuilder` ships it, test stubs typically
+   * don't. Callers that need it should fall back to
+   * `(await q.paginate(1, 1)).data[0]` when absent — see `findRecord` /
+   * `loadSingularRecord` / `childBelongsToParent` for the pattern.
+   */
+  first?(): Promise<unknown | null>
+
   /**
    * Plan #13 — soft-delete query scopes. Optional on the structural
    * shape; the `@rudderjs/orm-prisma` QueryBuilder ships them when
@@ -192,7 +202,7 @@ export function modelLoadRecord(R: ResourceLike): LoadRecordHandler {
  * `Global` subclasses with `static model = M` set get this wired
  * automatically by `defaultGlobalEditPage`.
  *
- * Default strategy: paginate(1, 1) — i.e. "the first row". Pass
+ * Default strategy: `.first()` — i.e. the first matching row. Pass
  * `findSingular` to switch to a fixed-id lookup
  * (`(q) => q.where('id', '=', 1)`) or a slug-style lookup
  * (`(q) => q.where('key', '=', 'site')`).
@@ -208,6 +218,7 @@ export function loadSingularRecord(
   return async (): Promise<unknown> => {
     let q = M.query()
     if (opts?.findSingular) q = opts.findSingular(q)
+    if (q.first) return (await q.first()) ?? null
     const result = await q.paginate(1, 1)
     const data = (result?.data ?? []) as unknown[]
     return data[0] ?? null
@@ -234,7 +245,9 @@ export async function findRecord<T = unknown>(
   const M = R.model
   if (!M) return undefined
   const pk = getPrimaryKey(M)
-  const result = await R.query(ctx).where(pk, '=', id).paginate(1, 1)
+  const q = R.query(ctx).where(pk, '=', id)
+  if (q.first) return ((await q.first()) ?? undefined) as T | undefined
+  const result = await q.paginate(1, 1)
   const data = (result?.data ?? []) as unknown[]
   return data[0] as T | undefined
 }

package/src/pageData/forms.ts

@@ -58,7 +58,7 @@ async function resolveScopeForm(
   let baseCtxExtras: Record<string, unknown> = {}
 
   if (scope.kind === 'resource-create' || scope.kind === 'resource-edit') {
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+    const R = pilotiq.findResource(scope.slug)
     if (!R) return null
     const pages = R.resolvePages()
     if (scope.kind === 'resource-create') {
@@ -77,14 +77,14 @@ async function resolveScopeForm(
       }
     }
   } else if (scope.kind === 'global-edit') {
-    const G = cfg.globals.find(g => g.getSlug() === scope.slug)
+    const G = pilotiq.findGlobal(scope.slug)
     if (!G) return null
     const pages = G.resolvePages()
     if (!pages.edit) return null
     PageClass = pages.edit
     mode = 'edit'
   } else {
-    const P = cfg.pages.find(p => p.getSlug() === scope.pageSlug)
+    const P = pilotiq.findPage(scope.pageSlug)
     if (!P) return null
     PageClass = P
     // Custom pages don't have a record/edit-mode concept — pass mode

package/src/pageData/misc.ts

@@ -43,7 +43,7 @@ export async function globalEditData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
+  const G = pilotiq.findGlobal(slug)
   if (!G) return null
   const pages = G.resolvePages()
   if (!pages.edit) return null
@@ -98,7 +98,7 @@ export async function globalViewData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
+  const G = pilotiq.findGlobal(slug)
   if (!G) return null
   const pages = G.resolvePages()
   if (!pages.view) return null
@@ -134,7 +134,7 @@ export async function customPageData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const PageClass = cfg.pages.find(P => P.getSlug() === pageSlug)
+  const PageClass = pilotiq.findPage(pageSlug)
   if (!PageClass) return null
 
   const pageUrl = pageBasePath(cfg.path, PageClass)
@@ -237,14 +237,14 @@ export async function widgetData(
     ctx = uploadCtx(userCtx({ basePath: cfg.path }, user), cfg)
     elements = await callPageSchema(cfg.dashboardPage, ctx)
   } else if (scope.kind === 'page') {
-    const P = cfg.pages.find(p => p.getSlug() === scope.pageSlug)
+    const P = pilotiq.findPage(scope.pageSlug)
     if (!P) return { ok: false, status: 404, error: 'Page not found' }
     ctx = uploadCtx(userCtx({ basePath: cfg.path }, user), cfg)
     elements = await callPageSchema(P, ctx)
   } else {
     // Resource-scope: re-resolve the list page's schema so widgets from
     // `Resource.headerSchema()` / `footerSchema()` are reachable.
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+    const R = pilotiq.findResource(scope.slug)
     if (!R) return { ok: false, status: 404, error: 'Resource not found' }
     const pages = R.resolvePages()
     if (!pages.index) return { ok: false, status: 404, error: 'Resource has no list page' }

package/src/pageData/navigation.ts

@@ -627,7 +627,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
   const raw: RawNavItem[] = []
   let idx = 0
 
-  const pushBadge: Array<{ item: RawNavItem; handler: () => unknown }> = []
+  const pushBadge: Array<{ item: RawNavItem; handler: () => unknown; owner: string }> = []
 
   // Plan #10 — pre-evaluate canAccess for every owner in parallel so we
   // can drop forbidden items before flattening. Failed predicates fail
@@ -672,7 +672,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (R.cluster)                              item.parent       = R.cluster.name
     else if (R.navigationParentItem !== undefined) item.parent    = R.navigationParentItem
     if (R.navigationBadgeColor   !== 'default') item.badgeColor   = R.navigationBadgeColor
-    if (R.navigationBadge)                       pushBadge.push({ item, handler: R.navigationBadge })
+    if (R.navigationBadge)                       pushBadge.push({ item, handler: R.navigationBadge, owner: R.name })
     raw.push(item)
   }
 
@@ -697,7 +697,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (G.cluster)                              item.parent       = G.cluster.name
     else if (G.navigationParentItem !== undefined) item.parent    = G.navigationParentItem
     if (G.navigationBadgeColor   !== 'default') item.badgeColor   = G.navigationBadgeColor
-    if (G.navigationBadge)                       pushBadge.push({ item, handler: G.navigationBadge })
+    if (G.navigationBadge)                       pushBadge.push({ item, handler: G.navigationBadge, owner: G.name })
     raw.push(item)
   }
 
@@ -724,7 +724,7 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (P.cluster && !isDashboard)              item.parent       = P.cluster.name
     else if (P.navigationParentItem !== undefined) item.parent    = P.navigationParentItem
     if (P.navigationBadgeColor   !== 'default') item.badgeColor   = P.navigationBadgeColor
-    if (P.navigationBadge)                       pushBadge.push({ item, handler: P.navigationBadge })
+    if (P.navigationBadge)                       pushBadge.push({ item, handler: P.navigationBadge, owner: P.name })
     raw.push(item)
   }
 
@@ -755,15 +755,17 @@ export async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<
     if (C.navigationSort         !== undefined) item.sort         = C.navigationSort
     if (C.navigationParentItem   !== undefined) item.parent       = C.navigationParentItem
     if (C.navigationBadgeColor   !== 'default') item.badgeColor   = C.navigationBadgeColor
-    if (C.navigationBadge)                       pushBadge.push({ item, handler: C.navigationBadge })
+    if (C.navigationBadge)                       pushBadge.push({ item, handler: C.navigationBadge, owner: C.name })
     raw.push(item)
   }
 
-  await Promise.all(pushBadge.map(async ({ item, handler }) => {
+  await Promise.all(pushBadge.map(async ({ item, handler, owner }) => {
     try {
-      const v = await handler()
-      if (v === undefined || v === null) return
-      item.badge = String(v)
+      const v = await pilotiq.resolveNavigationBadge(owner, user, async () => {
+        const raw = await handler()
+        return raw === undefined || raw === null ? undefined : String(raw)
+      })
+      if (v !== undefined) item.badge = v
     } catch {
       // Per-badge errors stay silent.
     }

package/src/pageData/relationPages.ts

@@ -193,7 +193,9 @@ async function childBelongsToParent(
     const q: ModelQuery = (parentModel.relatedQuery
       ? parentModel.relatedQuery(parent, relationship)
       : (parent as { related: (n: string) => ModelQuery }).related(relationship))
-    const result = await q.where(childPk, '=', childId).paginate(1, 1)
+      .where(childPk, '=', childId)
+    if (q.first) return (await q.first()) !== null
+    const result = await q.paginate(1, 1)
     return result.total > 0
   } catch {
     return false
@@ -294,7 +296,7 @@ export async function relationManagerData(
 
   const cfg = pilotiq.getConfig()
 
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+  const R = pilotiq.findResource(scope.slug)
   if (!R) return null
 
   const M = findManager(R, scope.relationship)
@@ -769,7 +771,7 @@ export async function resolveRelationChain(
 ): Promise<ResolvedChain | { ok: false; status: 403 } | null> {
   const cfg = pilotiq.getConfig()
 
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
+  const R = pilotiq.findResource(scope.slug)
   if (!R) return null
 
   // Layer 0 — same gates as the depth-1 pipeline.

package/src/pageData/resourcePages.ts

@@ -142,7 +142,7 @@ export async function resourceIndexData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
 
   const pages = R.resolvePages()
@@ -193,7 +193,7 @@ export async function resourceTableData(
   req?:    unknown,
 ): Promise<{ tables: Record<string, unknown>[] } | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
 
   const pages = R.resolvePages()
@@ -321,7 +321,7 @@ export async function resourceCreateData(
   req?:    unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.create) return null
@@ -373,7 +373,7 @@ export async function resourceEditData(
   req?:     unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.edit) return null
@@ -466,7 +466,7 @@ export async function resourceViewData(
   req?:     unknown,
 ): Promise<Record<string, unknown> | null> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const pages = R.resolvePages()
   if (!pages.view) return null
@@ -538,7 +538,7 @@ export async function resourceRecordPageData(
   req?:          unknown,
 ): Promise<Record<string, unknown> | null | { ok: false; status: 403 }> {
   const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
+  const R = pilotiq.findResource(slug)
   if (!R) return null
   const recordPages = R.getRecordPages()
   const PageClass = recordPages[subPageSlug]

package/src/plugins/index.ts

@@ -1 +1,8 @@
 export { themeEditor } from './themeEditor.js'
+export type { ThemeEditorOptions } from './themeEditor.js'
+export { prismaThemeStorage } from '../theme/storage.js'
+export type {
+  ThemeStorageAdapter,
+  PanelGlobalDelegate,
+  PrismaThemeStorageOptions,
+} from '../theme/storage.js'

package/src/plugins/themeEditor.test.ts

@@ -0,0 +1,36 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { Pilotiq } from '../Pilotiq.js'
+import { themeEditor } from './themeEditor.js'
+import type { ThemeStorageAdapter } from '../theme/storage.js'
+
+function makeStubAdapter(): ThemeStorageAdapter {
+  return {
+    async load() { return null },
+    async save() { /* noop */ },
+    async clear() { /* noop */ },
+  }
+}
+
+describe('themeEditor() plugin', () => {
+  it('bare themeEditor() leaves the storage slot undefined (boot resolves it)', () => {
+    const panel = Pilotiq.make('admin').use(themeEditor())
+    assert.equal(panel.getConfig().themeEditor, true)
+    assert.equal(panel.getThemeStorage(), undefined)
+  })
+
+  it('themeEditor({ storage }) stamps the adapter onto the panel', () => {
+    const adapter = makeStubAdapter()
+    const panel = Pilotiq.make('admin').use(themeEditor({ storage: adapter }))
+    assert.equal(panel.getThemeStorage(), adapter)
+  })
+
+  it('themeEditor() can be called on multiple panels without leaking adapters', () => {
+    const a = makeStubAdapter()
+    const b = makeStubAdapter()
+    const panelA = Pilotiq.make('admin').use(themeEditor({ storage: a }))
+    const panelB = Pilotiq.make('billing').use(themeEditor({ storage: b }))
+    assert.equal(panelA.getThemeStorage(), a)
+    assert.equal(panelB.getThemeStorage(), b)
+  })
+})

package/src/plugins/themeEditor.ts

@@ -1,4 +1,24 @@
 import type { PilotiqPlugin } from '../Pilotiq.js'
+import type { ThemeStorageAdapter } from '../theme/storage.js'
+
+export interface ThemeEditorOptions {
+  /**
+   * Override persistence adapter. Defaults to the implicit Prisma
+   * fallback (auto-resolved from `app.make('prisma')` against the
+   * `panelGlobal` row) — that fallback is deprecated; pass an explicit
+   * adapter to opt out and silence the deprecation warning.
+   *
+   * @example
+   * ```ts
+   * import { prismaThemeStorage, themeEditor } from '@pilotiq/pilotiq/plugins'
+   *
+   * .use(themeEditor({
+   *   storage: prismaThemeStorage(prisma, { slug: 'admin__theme' }),
+   * }))
+   * ```
+   */
+  storage?: ThemeStorageAdapter
+}
 
 /**
  * Theme editor plugin — adds an interactive theme customization page
@@ -14,11 +34,12 @@ import type { PilotiqPlugin } from '../Pilotiq.js'
  *   .use(themeEditor())
  * ```
  */
-export function themeEditor(): PilotiqPlugin {
+export function themeEditor(opts: ThemeEditorOptions = {}): PilotiqPlugin {
   return {
     name: 'theme-editor',
     register(panel) {
       panel.enableThemeEditor()
+      if (opts.storage) panel._setThemeStorage(opts.storage)
     },
   }
 }

package/src/react/CollabRoomContext.ts

@@ -22,6 +22,18 @@ export interface CollabRoom {
   ydoc:      unknown
   /** `WebsocketProvider` instance. Opaque to pilotiq core. */
   provider:  unknown
+  /**
+   * Resolves on the provider's first sync. Present when the room is
+   * wired through `@rudderjs/sync/react`'s `CollabRoomManager` (which is
+   * what `@pilotiq-pro/collab@>=0.2`'s `<RecordCollabRoom>` does);
+   * absent for legacy / hand-rolled providers. `useCollabSeed` gates
+   * its seed callback on this Promise — adapters that need a
+   * "fragment-empty?" check after first sync should consume the hook
+   * rather than calling `onProviderSynced` themselves.
+   */
+  synced?:   Promise<void>
+  /** IndexedDB persistence handle, when the room wraps `y-indexeddb`. Opaque. */
+  persistence?: unknown
   /** Presence info for cursors / avatars. Forwarded to the extension factory. */
   user?: {
     name?:  string

package/src/react/CollabTextRendererRegistry.ts

@@ -24,8 +24,26 @@ import type { ComponentType } from 'react'
  * keeps the seam narrow: handler callbacks + DOM chrome only.
  */
 export interface CollabTextRendererProps {
-  /** Field name — drives the `Y.XmlFragment` selector inside the collab adapter. */
+  /**
+   * Field name — drives the FormData hidden input AND the routing key
+   * for AI suggestion delivery (chip widget, applier registry). For
+   * Repeater / Builder row leaves this is the dotted positional path
+   * (`items.0.title`).
+   */
   name: string
+  /**
+   * Collab-stable identifier for the `Y.XmlFragment` selector. When
+   * present, the renderer binds its collab fragment under this key
+   * instead of `name`. Row leaves pass a row-id-anchored composite
+   * (`items.<rowId>.title`) so the fragment survives reorders even
+   * as the dotted positional `name` shifts. Top-level fields omit
+   * it — `name` is stable on its own.
+   *
+   * AI suggestion routing continues to use `name` regardless. Tool
+   * calls reference fields by their positional FormData name, not
+   * the collab-stable composite.
+   */
+  fragmentKey?: string
   /** `true` for textarea-like (multiple paragraphs); `false` for input-like. */
   multiline: boolean
   /**

package/src/react/fields/MarkdownInput.tsx

@@ -463,7 +463,8 @@ function MarkdownCollabInput({
         <div style={wrapperStyle} className="overflow-auto">
           <input type="hidden" name={hiddenInputName} value={text} />
           <Renderer
-            name={fragmentKey}
+            name={hiddenInputName}
+            {...(fragmentKey !== hiddenInputName ? { fragmentKey } : {})}
             multiline={true}
             defaultValue={initial}
             {...(placeholder !== undefined ? { placeholder } : {})}

package/src/react/fields/TextLikeInput.tsx

@@ -233,7 +233,8 @@ function CollabTextField({
     <>
       <input type="hidden" name={hiddenInputName} value={text} />
       <Renderer
-        name={fragmentKey}
+        name={hiddenInputName}
+        {...(fragmentKey !== hiddenInputName ? { fragmentKey } : {})}
         multiline={multiline}
         defaultValue={defaultValue}
         {...(placeholder !== undefined ? { placeholder } : {})}

package/src/react/index.ts

@@ -39,6 +39,7 @@ export {
   type CollabRoom,
   type SyncedProviderLike,
 } from './CollabRoomContext.js'
+export { useCollabSeed } from './useCollabSeed.js'
 export {
   registerCollabExtensions,
   getCollabExtensions,