@pilotiq/pilotiq 0.15.1 → 0.16.0

package/src/elements/dispatchForm.ts

@@ -19,6 +19,32 @@ import {
 } from '../orm/modelDefaults.js'
 import { resolveM2MAccessor } from '../orm/m2mAccessor.js'
 
+/**
+ * Server-emitted rename of a `Repeater.relationship` / `Builder.relationship`
+ * row's stable id. When a brand-new row is submitted with a renderer-minted
+ * UUID `__id`, `persistRelationshipRows` calls `model.create(...)` and the
+ * DB assigns a real primary key — the row's identity then switches from
+ * the UUID to `String(pk)`. The submitter learns the new id from the
+ * reloaded form's `initialRows`; other collab peers don't, leaving their
+ * Y.Doc row state keyed by the orphan UUID. Phase B (see
+ * `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`) lets a
+ * collab adapter subscribe to these renames from the form-submit JSON
+ * response and rename the row in the shared CRDT so other peers converge
+ * without reloading. Carries no opinion about transport — emitted unconditionally
+ * on every relationship-backed row create; consumers without a collab
+ * binding ignore the field.
+ */
+export interface RelationshipRename {
+  /** Field name on the form (the `Repeater.make(...)` / `Builder.make(...)` name). */
+  field: string
+  /** The id the renderer submitted — usually a UUID, occasionally a numeric string
+   *  when the consumer pre-assigned an id. May equal `new` when the consumer's
+   *  pre-assigned id matched the DB-assigned PK; consumers can no-op in that case. */
+  old:   string
+  /** The DB-assigned primary key, stringified. */
+  new:   string
+}
+
 export interface DispatchSuccess<R> {
   ok:            true
   record:        R
@@ -30,6 +56,12 @@ export interface DispatchSuccess<R> {
    * path drops them until a flash mechanism lands.
    */
   notifications: NotificationMeta[]
+  /**
+   * Per-row UUID → PK renames emitted by `Repeater.relationship` /
+   * `Builder.relationship` creates. Empty when the submitted form had
+   * no relationship-backed fields or no new rows. See {@link RelationshipRename}.
+   */
+  relationshipRenames: RelationshipRename[]
 }
 
 export interface DispatchFailure {
@@ -130,6 +162,7 @@ export async function dispatchFormSubmit<R = unknown>(
   // Persist the relationship-backed Repeater diffs against the saved
   // parent. Runs BEFORE `afterCreate / afterUpdate` so user hooks can
   // observe the fully-saved tree (parent + children).
+  const relationshipRenames: RelationshipRename[] = []
   if (relationshipDeferrals.length > 0 || builderRelationshipDeferrals.length > 0) {
     const parentModel = (ctx as { parentModel?: ModelLike }).parentModel
     if (!parentModel) {
@@ -139,10 +172,12 @@ export async function dispatchFormSubmit<R = unknown>(
       )
     }
     for (const deferral of relationshipDeferrals) {
-      await persistRelationshipRows(record, deferral, parentModel)
+      const renames = await persistRelationshipRows(record, deferral, parentModel)
+      relationshipRenames.push(...renames)
     }
     for (const deferral of builderRelationshipDeferrals) {
-      await persistRelationshipBuilderRows(record, deferral, parentModel)
+      const renames = await persistRelationshipBuilderRows(record, deferral, parentModel)
+      relationshipRenames.push(...renames)
     }
   }
 
@@ -163,7 +198,7 @@ export async function dispatchFormSubmit<R = unknown>(
   )
   const notifications = notification ? [notification] : []
 
-  return { ok: true, record, redirect, notifications }
+  return { ok: true, record, redirect, notifications, relationshipRenames }
 }
 
 /**
@@ -1513,7 +1548,8 @@ async function persistRelationshipRows(
   parent:      unknown,
   deferral:    RelationshipDeferral,
   parentModel: ModelLike,
-): Promise<void> {
+): Promise<RelationshipRename[]> {
+  const renames: RelationshipRename[] = []
   const { rows, cfg, field } = deferral
   const attachment  = resolveChildAndAttachment(parentModel, cfg)
   const { model }   = attachment
@@ -1675,6 +1711,18 @@ async function persistRelationshipRows(
         }
         createdRecord = created
       }
+      // Phase B PK-switch — emit the rename so a collab adapter can swap
+      // the row's id in the shared CRDT. Skipped when the submitter didn't
+      // pass an `__id` (rare: only happens when consumer code constructs
+      // a row server-side); skipped when old === new (consumer pre-assigned
+      // the DB PK on the row).
+      const createdPk = (createdRecord as Record<string, unknown> | null | undefined)?.[pk]
+      if (submittedId !== undefined && createdPk !== undefined && createdPk !== null) {
+        const newId = String(createdPk)
+        if (submittedId !== newId) {
+          renames.push({ field: cfg.name, old: submittedId, new: newId })
+        }
+      }
       if (afterCreate) await afterCreate(createdRecord, buildRowCtx(idx))
     }
   }
@@ -1691,6 +1739,7 @@ async function persistRelationshipRows(
     }
     if (afterDelete) await afterDelete(removedRow, buildRowCtx(-1))
   }
+  return renames
 }
 
 /**
@@ -1863,7 +1912,8 @@ async function persistRelationshipBuilderRows(
   parent:      unknown,
   deferral:    BuilderRelationshipDeferral,
   parentModel: ModelLike,
-): Promise<void> {
+): Promise<RelationshipRename[]> {
+  const renames: RelationshipRename[] = []
   const { rows, cfg } = deferral
   const attachment  = resolveBuilderChildAndAttachment(parentModel, cfg)
   const { model }   = attachment
@@ -1923,7 +1973,15 @@ async function persistRelationshipBuilderRows(
       } else {
         Object.assign(payload, morphStamp)
       }
-      await model.create(payload)
+      const createdRecord = await model.create(payload)
+      // Phase B PK-switch — see persistRelationshipRows for the contract.
+      const createdPk = (createdRecord as Record<string, unknown> | null | undefined)?.[pk]
+      if (submittedId !== undefined && createdPk !== undefined && createdPk !== null) {
+        const newId = String(createdPk)
+        if (submittedId !== newId) {
+          renames.push({ field: cfg.name, old: submittedId, new: newId })
+        }
+      }
     }
   }
 
@@ -1931,4 +1989,5 @@ async function persistRelationshipBuilderRows(
     if (keptPks.has(pkVal)) continue
     await model.delete(pkVal)
   }
+  return renames
 }

package/src/fields/RepeaterRelationship.test.ts

@@ -413,6 +413,126 @@ describe('Repeater.relationship — full pipeline', () => {
   })
 })
 
+describe('Repeater.relationship — PK-switch renames (Phase B)', () => {
+  it('emits a rename for each create when submitted __id differs from new PK', async () => {
+    const child = makeFakeChildModel([])
+    const parent = makeFakeParentModel({
+      childModel:   child.model,
+      childRows:    child.rows,
+      relationName: 'items',
+      foreignKey:   'orderId',
+    })
+
+    const form = Form.make()
+      .schema([
+        RepeaterField.make('items').relationship('items').schema([
+          TextField.make('label').required(),
+        ]),
+      ])
+      .save(async () => ({ id: 'p1' }))
+
+    const result = await dispatchFormSubmit(
+      form,
+      // Renderer-minted UUIDs on the two new rows — Fake model assigns
+      // `c1` / `c2` so the post-save renames swap the UUIDs to those.
+      { items: [{ __id: 'uuid-A', label: 'A' }, { __id: 'uuid-B', label: 'B' }] },
+      {
+        values:      { items: [{ __id: 'uuid-A', label: 'A' }, { __id: 'uuid-B', label: 'B' }] },
+        parentModel: parent,
+      },
+    )
+    assert.equal(result.ok, true)
+    if (!result.ok) return
+    assert.deepEqual(result.relationshipRenames, [
+      { field: 'items', old: 'uuid-A', new: 'c1' },
+      { field: 'items', old: 'uuid-B', new: 'c2' },
+    ])
+  })
+
+  it('skips renames for rows that resolve as updates (submitted __id matches existing PK)', async () => {
+    const child = makeFakeChildModel([
+      { id: 'c1', orderId: 'p1', label: 'old' },
+    ])
+    const parent = makeFakeParentModel({
+      childModel:   child.model,
+      childRows:    child.rows,
+      relationName: 'items',
+      foreignKey:   'orderId',
+    })
+
+    const form = Form.make()
+      .schema([
+        RepeaterField.make('items').relationship('items').schema([
+          TextField.make('label').required(),
+        ]),
+      ])
+      .save(async () => ({ id: 'p1' }))
+
+    const result = await dispatchFormSubmit(
+      form,
+      { items: [{ __id: 'c1', label: 'new' }, { __id: 'uuid-X', label: 'fresh' }] },
+      {
+        values:      { items: [{ __id: 'c1', label: 'new' }, { __id: 'uuid-X', label: 'fresh' }] },
+        record:      { id: 'p1' },
+        parentModel: parent,
+      },
+    )
+    assert.equal(result.ok, true)
+    if (!result.ok) return
+    // Update of c1 emits no rename; create from uuid-X resolves to a new id.
+    assert.equal(result.relationshipRenames.length, 1)
+    assert.equal(result.relationshipRenames[0]?.field, 'items')
+    assert.equal(result.relationshipRenames[0]?.old, 'uuid-X')
+  })
+
+  it('skips the rename when the consumer pre-assigned the DB PK', async () => {
+    const child = makeFakeChildModel([])
+    // Pre-assign id `c1` on the submitted row — the fake model honors data.id.
+    const parent = makeFakeParentModel({
+      childModel:   child.model,
+      childRows:    child.rows,
+      relationName: 'items',
+      foreignKey:   'orderId',
+    })
+
+    const form = Form.make()
+      .schema([
+        RepeaterField.make('items').relationship('items').schema([
+          TextField.make('label').required(),
+        ]),
+      ])
+      .save(async () => ({ id: 'p1' }))
+
+    const result = await dispatchFormSubmit(
+      form,
+      { items: [{ __id: 'c1', label: 'A', id: 'c1' }] },
+      {
+        values:      { items: [{ __id: 'c1', label: 'A', id: 'c1' }] },
+        parentModel: parent,
+      },
+    )
+    assert.equal(result.ok, true)
+    if (!result.ok) return
+    // Submitted __id already matches the PK — no rename to emit.
+    assert.equal(result.relationshipRenames.length, 0)
+  })
+
+  it('returns an empty array on a parent save with no relationship fields', async () => {
+    const form = Form.make()
+      .schema([TextField.make('title')])
+      .save(async () => ({ id: 'p1' }))
+
+    const result = await dispatchFormSubmit(
+      form,
+      { title: 'Hello' },
+      { values: { title: 'Hello' } },
+    )
+    assert.equal(result.ok, true)
+    if (!result.ok) return
+    assert.deepEqual(result.relationshipRenames, [])
+  })
+})
+
 describe('Repeater.relationship — load (applyRelationshipRepeaterFill)', () => {
   it('stamps __id from PK and strips PK + FK from each row', async () => {
     const child = makeFakeChildModel([

package/src/index.ts

@@ -359,6 +359,7 @@ export {
   type DispatchResult,
   type DispatchSuccess,
   type DispatchFailure,
+  type RelationshipRename,
 } from './elements/dispatchForm.js'
 export {
   dispatchAction,

package/src/react/FormCollabBindingRegistry.ts

@@ -113,6 +113,28 @@ export interface FormCollabBinding {
    * Empty array when the binding has no state for `arrayName` yet.
    */
   getRowOrder?(arrayName: string): string[]
+
+  /**
+   * PK-switch Phase B — re-key a row from `oldId` to `newId` across the
+   * binding's row CRDT surface. Called by `FormRenderer` after a successful
+   * form submit that emitted `relationshipRenames` in the JSON response;
+   * the relevant `Repeater.relationship` / `Builder.relationship` field
+   * pre-assigned the submitter's UUID and the server returned the DB PK
+   * each row was actually persisted under. Renaming inside CRDT means
+   * other peers converge on the DB PK without reloading.
+   *
+   * Idempotent: bindings should no-op on `oldId === newId`, on unknown
+   * `oldId`, on unknown `arrayName`, AND on collisions where `newId`
+   * already exists (clobbering an unrelated row's content is worse than
+   * leaving the orphan UUID for the mount-time reconciler to drop).
+   *
+   * When absent, the dispatch step silently skips — the submitting
+   * peer's Phase A reconciler still drops orphans on next mount, but
+   * other peers stay on the UUID until they reload (the documented
+   * pre-Phase-B posture). See
+   * `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`.
+   */
+  renameRow?(arrayName: string, oldId: string, newId: string): void
 }
 
 /**

package/src/react/FormStateContext.tsx

@@ -25,6 +25,7 @@ import {
   type FormCollabBinding,
   type RowBindingApi,
 } from './FormCollabBindingRegistry.js'
+import { registerRelationshipRenameHandler } from './fields/relationshipRenameDispatch.js'
 
 export type FieldStatus = 'idle' | 'pending'
 
@@ -311,8 +312,26 @@ export function FormStateProvider({
       })
     })
 
+    // PK-switch Phase B — register a per-formId rename handler so
+    // `FormRenderer`'s submit-success path can re-key newly persisted
+    // relationship rows on the CRDT without us having to expose the
+    // binding through React context (FormRenderer lives outside this
+    // provider). No-op when the active binding skipped the optional
+    // `renameRow` method; the documented fallback is the submitter-only
+    // Phase A reconciler (other peers reload to converge). See
+    // `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`.
+    const renameRow = binding.renameRow
+    const unregisterRename = renameRow
+      ? registerRelationshipRenameHandler(formId, (renames) => {
+          for (const r of renames) {
+            renameRow.call(binding, r.field, r.old, r.new)
+          }
+        })
+      : () => {}
+
     return () => {
       unsubscribe()
+      unregisterRename()
       binding.destroy()
       bindingRef.current = null
       setRowBindings(null)

package/src/react/fields/BuilderInput.tsx

@@ -879,10 +879,10 @@ function BuilderRow({
   onClone:           () => void
   onRemove:          () => void
   onToggleCollapse:  () => void
-  onDragStart:       (e: React.DragEvent<HTMLDivElement>) => void
-  onDragOver:        (e: React.DragEvent<HTMLDivElement>) => void
-  onDrop:            (e: React.DragEvent<HTMLDivElement>) => void
-  onDragEnd:         (e: React.DragEvent<HTMLDivElement>) => void
+  onDragStart:       (e: React.DragEvent<HTMLElement>) => void
+  onDragOver:        (e: React.DragEvent<HTMLElement>) => void
+  onDrop:            (e: React.DragEvent<HTMLElement>) => void
+  onDragEnd:         (e: React.DragEvent<HTMLElement>) => void
 }): React.ReactElement {
   // Inner inputs sit under `name.<i>.data.*` so the {type, data}
   // envelope round-trips through FormData. Hidden envelope inputs
@@ -942,28 +942,37 @@ function BuilderRow({
   const canClone   = row.canClone   !== false
   const canReorder = row.canReorder !== false
 
-  const dragProps = reorderable && !buttonsOnly && !disabled && canReorder
+  // Drag source on the grip `<span>`, drop target on the row container.
+  // See RepeaterInput's RepeaterRow for the rationale (lets the row body
+  // host a Tiptap contenteditable without losing reorder).
+  const rowRef = useRef<HTMLDivElement>(null)
+  const dragEnabled = reorderable && !buttonsOnly && !disabled && canReorder
+  const containerDropTargetProps = dragEnabled
+    ? { onDragOver, onDrop, onDragEnd }
+    : {}
+  const gripDragHandleProps = dragEnabled
     ? {
-        draggable:     true as const,
-        onDragStart,
-        onDragOver,
-        onDrop,
-        onDragEnd,
+        draggable: true as const,
+        onDragStart: (e: React.DragEvent<HTMLElement>): void => {
+          if (rowRef.current) e.dataTransfer.setDragImage(rowRef.current, 0, 0)
+          onDragStart(e)
+        },
       }
-    : {}
+    : undefined
 
   const innerColumns = block.columns && block.columns > 1 ? block.columns : 1
 
   return (
     <RowCoordsContext.Provider value={rowCoords}>
     <div
+      ref={rowRef}
       className={`rounded-md border bg-card transition-opacity ${isDragging ? 'opacity-50' : ''}`}
       data-pilotiq-builder-row=""
-      {...dragProps}
+      {...containerDropTargetProps}
     >
       <div className="flex items-center gap-2 border-b px-3 py-2">
         {reorderable && !buttonsOnly && canReorder && (
-          <ReorderGrip disabled={disabled} buttons={buttons} />
+          <ReorderGrip disabled={disabled} buttons={buttons} dragHandleProps={gripDragHandleProps} />
         )}
         {collapsible && (
           <CollapseChevron

package/src/react/fields/RepeaterInput.tsx

@@ -1,4 +1,4 @@
-import React, { useContext, useEffect, useId, useMemo, useState } from 'react'
+import React, { useContext, useEffect, useId, useMemo, useRef, useState } from 'react'
 import { PlusIcon } from 'lucide-react'
 import type { ElementMeta } from '../../schema/Element.js'
 import { Button } from '../ui/button.js'
@@ -811,21 +811,29 @@ function RepeaterRow({
   const canClone   = row.canClone   !== false
   const canReorder = row.canReorder !== false
 
-  // Native HTML5 DnD only fires `dragstart` from elements with `draggable=true`.
-  // We attach it at the row container so the grip handle (and the empty
-  // header gutter, for forgiving aim) both initiate a drag. The handle's
-  // visual cursor + aria-label tell users where the affordance lives.
-  // Pinned rows (`canReorder === false`) lose drag-start; other rows can
-  // still drop next to them — see itemCanReorder docstring.
-  const dragProps = reorderable && !disabled && canReorder
+  // Drag source lives on the grip `<span>` (see `ReorderGrip`). The
+  // row container is only the drop target — `dragend` bubbles, so source
+  // cleanup still reaches it. Splitting source from target this way lets
+  // row contents host a Tiptap contenteditable without the editor's
+  // text-selection handler swallowing the row's dragstart.
+  // Pinned rows (`canReorder === false`) lose the grip; others can still
+  // accept drops — see itemCanReorder docstring.
+  const rowRef = useRef<HTMLDivElement>(null)
+  const dragEnabled = reorderable && !disabled && canReorder
+  const containerDropTargetProps = dragEnabled
+    ? { onDragOver, onDrop, onDragEnd }
+    : {}
+  const gripDragHandleProps = dragEnabled
     ? {
-        draggable:     true as const,
-        onDragStart,
-        onDragOver,
-        onDrop,
-        onDragEnd,
+        draggable: true as const,
+        onDragStart: (e: React.DragEvent<HTMLElement>): void => {
+          // Use the row element as the drag preview so the user still
+          // sees the whole row floating, not just the grip icon.
+          if (rowRef.current) e.dataTransfer.setDragImage(rowRef.current, 0, 0)
+          onDragStart(e)
+        },
       }
-    : {}
+    : undefined
 
   // Simple-mode: flatten the row to one input + inline action strip — no
   // header, no border, no collapse (a single field has nothing to collapse).
@@ -839,12 +847,15 @@ function RepeaterRow({
     return (
       <RowCoordsContext.Provider value={rowCoords}>
       <div
+        ref={rowRef}
         className={`flex items-center gap-2 transition-opacity ${isDragging ? 'opacity-50' : ''}`}
         data-pilotiq-repeater-row="simple"
-        {...dragProps}
+        {...containerDropTargetProps}
       >
         <input type="hidden" name={`${prefix}.__id`} value={row.id} readOnly />
-        {reorderable && canReorder && <ReorderGrip disabled={disabled} buttons={buttons} />}
+        {reorderable && canReorder && (
+          <ReorderGrip disabled={disabled} buttons={buttons} dragHandleProps={gripDragHandleProps} />
+        )}
         <div className="flex-1 [&_label]:sr-only">
           <SchemaRenderer elements={namespaced} />
         </div>
@@ -880,12 +891,15 @@ function RepeaterRow({
   return (
     <RowCoordsContext.Provider value={rowCoords}>
     <div
+      ref={rowRef}
       className={`rounded-md border bg-card transition-opacity ${isDragging ? 'opacity-50' : ''}`}
       data-pilotiq-repeater-row=""
-      {...dragProps}
+      {...containerDropTargetProps}
     >
       <div className="flex items-center gap-2 border-b px-3 py-2">
-        {reorderable && canReorder && <ReorderGrip disabled={disabled} buttons={buttons} />}
+        {reorderable && canReorder && (
+          <ReorderGrip disabled={disabled} buttons={buttons} dragHandleProps={gripDragHandleProps} />
+        )}
         {collapsible && (
           <CollapseChevron
             isCollapsed={isCollapsed}
@@ -1255,22 +1269,29 @@ function RepeaterTableRow({
   const canClone   = row.canClone   !== false
   const canReorder = row.canReorder !== false
 
-  const dragProps = reorderable && !disabled && canReorder
+  // Drag source on the grip, drop target on the `<tr>` — see RepeaterRow.
+  const rowRef = useRef<HTMLTableRowElement>(null)
+  const dragEnabled = reorderable && !disabled && canReorder
+  const containerDropTargetProps = dragEnabled
+    ? { onDragOver, onDrop, onDragEnd }
+    : {}
+  const gripDragHandleProps = dragEnabled
     ? {
         draggable: true as const,
-        onDragStart,
-        onDragOver,
-        onDrop,
-        onDragEnd,
+        onDragStart: (e: React.DragEvent<HTMLElement>): void => {
+          if (rowRef.current) e.dataTransfer.setDragImage(rowRef.current, 0, 0)
+          onDragStart(e)
+        },
       }
-    : {}
+    : undefined
 
   return (
     <RowCoordsContext.Provider value={rowCoords}>
     <tr
+      ref={rowRef}
       className={`border-t align-top ${isDragging ? 'opacity-50' : ''}`}
       data-pilotiq-repeater-row=""
-      {...dragProps}
+      {...containerDropTargetProps}
     >
       <input type="hidden" name={`${prefix}.__id`} value={row.id} readOnly />
       {columns.map((c, i) => (
@@ -1282,7 +1303,7 @@ function RepeaterTableRow({
         <div className="inline-flex items-center gap-1">
           {reorderable && canReorder && (
             <>
-              <ReorderGrip disabled={disabled} buttons={buttons} />
+              <ReorderGrip disabled={disabled} buttons={buttons} dragHandleProps={gripDragHandleProps} />
               <RowChromeIconButton
                 defaults={DEFAULT_MOVE_UP}
                 override={buttons?.moveUp}

package/src/react/fields/relationshipRenameDispatch.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import {
+  applyRelationshipRenames,
+  registerRelationshipRenameHandler,
+  _resetRelationshipRenameRegistryForTests,
+  type RelationshipRenameEntry,
+  type RelationshipRenameHandler,
+} from './relationshipRenameDispatch.js'
+
+describe('relationshipRenameDispatch', () => {
+  beforeEach(() => {
+    _resetRelationshipRenameRegistryForTests()
+  })
+
+  it('routes a rename through the registered handler for its formId', () => {
+    const seen: ReadonlyArray<RelationshipRenameEntry>[] = []
+    registerRelationshipRenameHandler('form-1', (renames) => { seen.push(renames) })
+
+    applyRelationshipRenames('form-1', [
+      { field: 'comments', old: 'uuid-foo', new: '42' },
+    ])
+
+    assert.equal(seen.length, 1)
+    assert.deepEqual(seen[0], [{ field: 'comments', old: 'uuid-foo', new: '42' }])
+  })
+
+  it('isolates handlers across formIds — multi-form pages do not cross-fire', () => {
+    const a: RelationshipRenameEntry[][] = []
+    const b: RelationshipRenameEntry[][] = []
+    registerRelationshipRenameHandler('form-a', (r) => { a.push([...r]) })
+    registerRelationshipRenameHandler('form-b', (r) => { b.push([...r]) })
+
+    applyRelationshipRenames('form-a', [{ field: 'x', old: 'u', new: '1' }])
+
+    assert.equal(a.length, 1)
+    assert.equal(b.length, 0)
+  })
+
+  it('cleanup unregisters the handler', () => {
+    let calls = 0
+    const off = registerRelationshipRenameHandler('form-1', () => { calls += 1 })
+    off()
+    applyRelationshipRenames('form-1', [{ field: 'x', old: 'u', new: '1' }])
+    assert.equal(calls, 0)
+  })
+
+  it("cleanup does NOT wipe a handler that another caller replaced (StrictMode-safe)", () => {
+    // StrictMode dev double-mount: provider A mounts, registers fn1; React
+    // schedules cleanup; provider A's effect re-runs and registers fn2; THEN
+    // the cleanup of the first effect fires. fn2 must survive.
+    let calls1 = 0
+    let calls2 = 0
+    const fn1: RelationshipRenameHandler = () => { calls1 += 1 }
+    const fn2: RelationshipRenameHandler = () => { calls2 += 1 }
+
+    const off1 = registerRelationshipRenameHandler('form-1', fn1)
+    registerRelationshipRenameHandler('form-1', fn2)
+    off1()
+
+    applyRelationshipRenames('form-1', [{ field: 'x', old: 'u', new: '1' }])
+    assert.equal(calls1, 0)
+    assert.equal(calls2, 1, 'second registration survived the first cleanup')
+  })
+
+  it('apply with no handler registered is a silent no-op', () => {
+    // The success path always fires apply; consumers without a collab
+    // plugin shouldn't see any error.
+    assert.doesNotThrow(() => {
+      applyRelationshipRenames('form-unknown', [{ field: 'x', old: 'u', new: '1' }])
+    })
+  })
+
+  it('apply with empty or undefined rename list short-circuits', () => {
+    let calls = 0
+    registerRelationshipRenameHandler('form-1', () => { calls += 1 })
+
+    applyRelationshipRenames('form-1', [])
+    applyRelationshipRenames('form-1', undefined)
+
+    assert.equal(calls, 0)
+  })
+
+  it('apply with empty formId is a no-op', () => {
+    let calls = 0
+    registerRelationshipRenameHandler('', () => { calls += 1 })
+    applyRelationshipRenames('', [{ field: 'x', old: 'u', new: '1' }])
+    assert.equal(calls, 0)
+  })
+
+  it('register returns a stub cleanup when formId is empty (no crash)', () => {
+    const off = registerRelationshipRenameHandler('', () => {})
+    assert.doesNotThrow(off)
+  })
+
+  it('handler errors propagate so FormRenderer can surface a save-failed toast', () => {
+    registerRelationshipRenameHandler('form-1', () => {
+      throw new Error('binding wedged')
+    })
+    assert.throws(
+      () => applyRelationshipRenames('form-1', [{ field: 'x', old: 'u', new: '1' }]),
+      /binding wedged/,
+    )
+  })
+})