@pilotiq/pilotiq 0.15.0 → 0.16.0

package/src/react/fields/MarkdownInput.tsx

@@ -56,21 +56,35 @@ export function MarkdownInput({
   const markdownEditor = getMarkdownEditor()
   const rowCoords = useRowCoords()
 
+  // Row-leaf fields ride a composite `arrayName.rowId.fieldName` key for
+  // collab anchoring so the Y.XmlFragment survives row reorders (the raw
+  // dotted `items.<index>.body` would follow the wrong row after a swap).
+  // Top-level fields pass through unchanged.
+  const fragmentKey: string | null = (() => {
+    if (!name.includes('.')) return name
+    if (!rowCoords) return null
+    const parsed = parseRowFieldPath(name)
+    if (!parsed) return null
+    if (parsed.arrayName !== rowCoords.arrayName) return null
+    if (parsed.index     !== rowCoords.rowIndex)  return null
+    return `${rowCoords.arrayName}.${rowCoords.rowId}.${parsed.fieldName}`
+  })()
+
   // 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) {
+  // internally. Row leaves pass the composite key as `collabKey` so the
+  // editor's collab factory anchors against the stable name while the
+  // hidden input + form-state keep using the original dotted path for
+  // submit routing.
+  if (markdownEditor && fragmentKey !== null) {
     return (
       <MarkdownEditorHost
         Editor={markdownEditor}
         name={name}
+        {...(fragmentKey !== name ? { collabKey: fragmentKey } : {})}
         defaultValue={defaultValue}
         disabled={disabled}
         {...(placeholder !== undefined ? { placeholder } : {})}
@@ -84,12 +98,10 @@ export function MarkdownInput({
     )
   }
 
-  // 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
-  // `Y.XmlFragment` replaces whole-string LWW. Row leaves get the
-  // composite-key transform via `useRowCoords()` + `parseRowFieldPath`
-  // (same shape as TextLikeInput) so the fragment survives row reorders.
+  // Tiptap-backed plain-text editor for markdown source when collab is on
+  // but no WYSIWYG adapter is registered. Same architectural fix as
+  // `TextLikeInput`'s `CollabTextField`: y-prosemirror's `RelativePosition`
+  // cursor anchoring against a `Y.XmlFragment` replaces whole-string LWW.
   //
   // Tradeoff: the markdown toolbar + Cmd-shortcuts + paste-image upload
   // all operate on a `<textarea>`'s DOM selection — they don't have a
@@ -98,15 +110,6 @@ export function MarkdownInput({
   // are write-mode-only on the native path; collab users type markdown
   // syntax directly (`**bold**`, `## heading`). The preview tab keeps
   // working since `MarkdownCollabInput` maintains a local mirror.
-  const fragmentKey: string | null = (() => {
-    if (!name.includes('.')) return name
-    if (!rowCoords) return null
-    const parsed = parseRowFieldPath(name)
-    if (!parsed) return null
-    if (parsed.arrayName !== rowCoords.arrayName) return null
-    if (parsed.index     !== rowCoords.rowIndex)  return null
-    return `${rowCoords.arrayName}.${rowCoords.rowId}.${parsed.fieldName}`
-  })()
   if (room && collabRenderer && fragmentKey !== null) {
     return (
       <MarkdownCollabInput
@@ -498,12 +501,17 @@ function stringValue(v: unknown): string {
  * input so submit picks it up unchanged.
  */
 function MarkdownEditorHost({
-  Editor, name, defaultValue, disabled, placeholder,
+  Editor, name, collabKey, defaultValue, disabled, placeholder,
   toolbarButtons, minHeight, maxHeight,
   fileAttachmentsDirectory, fileAttachmentsVisibility, uploadUrl,
 }: {
   Editor:                     MarkdownEditorComponent
   name:                       string
+  // Distinct from `name` only inside Repeater/Builder rows: the dotted
+  // form-input name (`items.0.body`) is unstable across reorders, so the
+  // editor's collab factory needs a row-id-anchored key. Defaults to
+  // `name` when unset (top-level fields).
+  collabKey?:                 string
   defaultValue:               unknown
   disabled:                   boolean
   placeholder?:               string
@@ -529,7 +537,7 @@ function MarkdownEditorHost({
     <>
       <input type="hidden" name={name} value={text} readOnly />
       <Editor
-        name={name}
+        name={collabKey ?? name}
         defaultValue={initial}
         disabled={disabled}
         {...(placeholder !== undefined ? { placeholder } : {})}

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/,
+    )
+  })
+})

package/src/react/fields/relationshipRenameDispatch.ts

@@ -0,0 +1,97 @@
+/**
+ * PK-switch Phase B — client-side dispatcher.
+ *
+ * The pilotiq server returns `relationshipRenames: { field, old, new }[]`
+ * in the JSON form-submit response whenever a `Repeater.relationship` /
+ * `Builder.relationship` create persisted under a DB-assigned PK that
+ * differs from the submitter's pre-assigned `__id` (see
+ * `pilotiq-pro/docs/plans/repeater-relationship-pk-switch.md`,
+ * `pilotiq/src/elements/dispatchForm.ts` for the wire shape).
+ *
+ * The renames need to land on the form's collab binding so other peers
+ * see the CRDT row re-keyed from UUID → PK without reloading. But the
+ * binding lives inside `FormStateProvider` (it owns `bindingRef`), while
+ * the JSON success path lives in `FormRenderer`'s `onSubmit` — a sibling
+ * component, not a context consumer. We bridge them with a per-`formId`
+ * module-level registry: `FormStateProvider` registers a handler when
+ * its binding mounts; `FormRenderer` dispatches against it after a
+ * successful submit.
+ *
+ * Pattern parallels `repeaterReconcile.ts`'s sessionStorage flag — same
+ * formId-keyed seam, different storage. SessionStorage was right for
+ * Phase A (the flag has to survive a navigation between submit and
+ * next mount); Phase B has to fire BEFORE the navigation, so a plain
+ * in-memory Map is the right shape (no SSR / cross-tab concerns).
+ *
+ * No-op when no handler is registered (consumer has no collab plugin,
+ * or the active binding doesn't implement `renameRow`).
+ */
+
+/**
+ * One UUID → PK rename emitted by the server. Shape mirrors
+ * `pilotiq/src/elements/dispatchForm.ts` `RelationshipRename`; we
+ * duplicate the shape here so this module stays free of server-only
+ * imports (would otherwise pull the form-submit pipeline into the
+ * client bundle).
+ */
+export interface RelationshipRenameEntry {
+  field: string
+  old:   string
+  new:   string
+}
+
+export type RelationshipRenameHandler = (
+  renames: ReadonlyArray<RelationshipRenameEntry>,
+) => void
+
+const handlers = new Map<string, RelationshipRenameHandler>()
+
+/**
+ * Called by `FormStateProvider` when its `FormCollabBinding` mounts AND
+ * implements `renameRow`. Returns the unsubscribe fn to call on
+ * unmount. Idempotent under re-registration on the same `formId` —
+ * later writers replace earlier handlers (Forms only mount one
+ * provider per id; a second mount means the first unmounted without
+ * firing its cleanup, which is acceptable to overwrite).
+ */
+export function registerRelationshipRenameHandler(
+  formId: string,
+  fn:     RelationshipRenameHandler,
+): () => void {
+  if (!formId) return () => {}
+  handlers.set(formId, fn)
+  return () => {
+    // Only clear when the current handler is still ours — protects
+    // against StrictMode dev double-mount where the cleanup of the
+    // first mount fires AFTER the second mount has installed its
+    // handler. Without this guard, the second mount's handler would
+    // be wiped before any submit completes.
+    if (handlers.get(formId) === fn) handlers.delete(formId)
+  }
+}
+
+/**
+ * Called by `FormRenderer`'s `onSubmit` success path. Invokes the
+ * formId's registered handler with the rename list, or no-ops when
+ * either side is empty.
+ *
+ * Errors thrown by the handler propagate — pilotiq's submit path
+ * already catches in a `try`, so a misbehaving binding fails the
+ * navigate cleanly with a toast rather than wedging the form.
+ */
+export function applyRelationshipRenames(
+  formId:  string,
+  renames: ReadonlyArray<RelationshipRenameEntry> | undefined,
+): void {
+  if (!formId) return
+  if (!renames || renames.length === 0) return
+  const fn = handlers.get(formId)
+  if (!fn) return
+  fn(renames)
+}
+
+/** Test seam — drop every registered handler. Not exported from the
+ *  react barrel. */
+export function _resetRelationshipRenameRegistryForTests(): void {
+  handlers.clear()
+}

package/src/react/fields/rowChromeButton.tsx

@@ -131,17 +131,31 @@ export function RowChromeIconButton({
 }
 
 /**
- * Drag grip — a `<span>` not a `<button>`, since native HTML5 DnD only
- * fires `dragstart` on parents with `draggable=true`. Honors the
- * `reorderAction` customizer for icon / label / tooltip / color so users
- * can swap the glyph or copy without owning the drag wiring.
+ * Drag grip — a `<span>` not a `<button>`. Honors the `reorderAction`
+ * customizer for icon / label / tooltip / color so users can swap the
+ * glyph or copy without owning the drag wiring.
+ *
+ * When `dragHandleProps` is passed, the grip carries `draggable=true` +
+ * `onDragStart` and becomes the HTML5 drag source — required for row
+ * layouts whose body hosts a contenteditable (Tiptap-backed fields).
+ * If `draggable=true` lives on the row container instead, a dragstart
+ * that initiates over the contenteditable is absorbed by the text-
+ * selection handler and the row drag never fires. Moving the source to
+ * the grip sidesteps that. Drop-target handlers (`onDragOver/onDrop/
+ * onDragEnd`) stay on the row container — `dragend` bubbles so source-
+ * side cleanup still reaches it.
  */
 export function ReorderGrip({
   disabled,
   buttons,
+  dragHandleProps,
 }: {
   disabled: boolean
   buttons:  RowButtonsMeta | undefined
+  dragHandleProps?: {
+    draggable:   true
+    onDragStart: (e: React.DragEvent<HTMLElement>) => void
+  } | undefined
 }): React.ReactElement {
   const { Icon, label, tooltip, colorClass } = resolveRowChromeFor('reorder', DEFAULT_REORDER, buttons)
   return (
@@ -149,6 +163,7 @@ export function ReorderGrip({
       aria-label={label}
       title={tooltip}
       className={`${colorClass} ${disabled ? 'opacity-30' : 'cursor-grab active:cursor-grabbing'}`}
+      {...dragHandleProps}
     >
       <Icon className="size-4" />
     </span>

package/src/react/schemaRenderer/form/FormRenderer.tsx

@@ -7,6 +7,10 @@ import { getFormCollabBinding } from '../../FormCollabBindingRegistry.js'
 import { useNavigate } from '../../navigate.js'
 import { useToast } from '../../Toaster.js'
 import { markSubmitForReconcile } from '../../fields/repeaterReconcile.js'
+import {
+  applyRelationshipRenames,
+  type RelationshipRenameEntry,
+} from '../../fields/relationshipRenameDispatch.js'
 import { renderField } from './renderField.js'
 
 // ─── Form ───────────────────────────────────────────────────
@@ -113,6 +117,21 @@ export function FormRenderer({
 
       // Success — drain notifications and SPA-navigate to the redirect.
       //
+      // Apply PK-switch Phase B renames against the active form's collab
+      // binding FIRST (synchronous Yjs transact under the hood). The
+      // server emits `relationshipRenames: { field, old, new }[]` for
+      // every relationship-backed row that persisted under a new PK; we
+      // forward each through the formId-keyed dispatch so the binding's
+      // `renameRow` runs before the navigate destroys the provider that
+      // owns it. No-op when no binding is registered (no collab plugin)
+      // OR when the array is empty (no relationship-backed creates this
+      // submit). The submitter-only Phase A reconciler still fires below
+      // — Phase B closes the multi-peer gap WITHOUT obviating the
+      // single-peer cleanup path.
+      const renames = (data as { relationshipRenames?: RelationshipRenameEntry[] })
+        .relationshipRenames
+      applyRelationshipRenames(formId, renames)
+
       // Before navigating, mark this tab for the relationship-backed
       // Repeater/Builder PK-switch reconciler. The next mount of any
       // child Repeater/Builder under this formId will run a one-shot

package/src/routes/globals.ts

@@ -137,7 +137,9 @@ export function registerGlobalRoutes(
       }
 
       const redirect = normalizeRedirect(result.redirect, base) ?? editUrl
-      return sendRedirectResponse(req, res, json, redirect, result.notifications)
+      return sendRedirectResponse(req, res, json, redirect, result.notifications,
+        result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : undefined,
+      )
     })
   }
 

package/src/routes/helpers.ts

@@ -1,6 +1,7 @@
 import type { AppRequest, AppResponse } from '@rudderjs/contracts'
 import type { Pilotiq } from '../Pilotiq.js'
 import { findActions, findRowExtraActions, type DispatchActionResult } from '../elements/dispatchAction.js'
+import type { RelationshipRename } from '../elements/dispatchForm.js'
 import { flashNotifications } from '../notifications/flash.js'
 import type { NotificationMeta } from '../notifications/Notification.js'
 import { findRecord, type ModelQuery } from '../orm/modelDefaults.js'
@@ -105,18 +106,24 @@ export function sendDownload(
 }
 
 /** Low-level success-or-redirect responder. Either emits a JSON envelope
- *  (`{ ok: true, redirect, notifications?, force? }`) when the client
- *  asked for JSON, or flashes notifications to the next request and
- *  issues a 303 redirect. Shared by `sendActionResult`,
+ *  (`{ ok: true, redirect, notifications?, force?, relationshipRenames? }`)
+ *  when the client asked for JSON, or flashes notifications to the next
+ *  request and issues a 303 redirect. Shared by `sendActionResult`,
  *  `sendMutationSuccess`, and the form-submit success branches in
- *  resources / globals / pages / relations. */
+ *  resources / globals / pages / relations.
+ *
+ *  `relationshipRenames` are emitted only on the JSON path — they're a
+ *  collab-side concern (per-row UUID → PK renames from
+ *  `Repeater.relationship` / `Builder.relationship` creates) consumed
+ *  by client-side adapters that own a CRDT binding. The 303 path drops
+ *  them silently; non-collab flows are unaffected. */
 export function sendRedirectResponse(
   req:           AppRequest,
   res:           AppResponse,
   json:          boolean,
   redirect:      string,
   notifications: ReadonlyArray<NotificationMeta> | undefined,
-  extras?:       { force?: boolean },
+  extras?:       { force?: boolean; relationshipRenames?: ReadonlyArray<RelationshipRename> },
 ): unknown {
   if (json) {
     return res.json({
@@ -124,6 +131,9 @@ export function sendRedirectResponse(
       redirect,
       ...(extras?.force ? { force: true } : {}),
       ...(notifications && notifications.length > 0 ? { notifications } : {}),
+      ...(extras?.relationshipRenames && extras.relationshipRenames.length > 0
+        ? { relationshipRenames: extras.relationshipRenames }
+        : {}),
     })
   }
   flashNotifications(req, notifications)

package/src/routes/pages.ts

@@ -168,6 +168,8 @@ export function registerCustomPageRoutes(
     }
 
     const redirect = normalizeRedirect(result.redirect, base) ?? pageUrl
-    return sendRedirectResponse(req, res, json, redirect, result.notifications)
+    return sendRedirectResponse(req, res, json, redirect, result.notifications,
+      result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : undefined,
+    )
   })
 }

package/src/routes/relations.ts

@@ -215,7 +215,9 @@ export function registerRelationRoutes(
         }
 
         const redirect = normalizeRedirect(result.redirect, base) ?? listUrl
-        return sendRedirectResponse(req, res, json, redirect, result.notifications)
+        return sendRedirectResponse(req, res, json, redirect, result.notifications,
+          result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : undefined,
+        )
       })
 
       // View — GET ${resourceBase}/:id/${rel}/:childId  (Phase A nested
@@ -332,7 +334,9 @@ export function registerRelationRoutes(
         }
 
         const redirect = normalizeRedirect(result.redirect, base) ?? editUrl
-        return sendRedirectResponse(req, res, json, redirect, result.notifications)
+        return sendRedirectResponse(req, res, json, redirect, result.notifications,
+          result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : undefined,
+        )
       })
 
       // Delete — POST ${resourceBase}/:id/${rel}/:childId/delete
@@ -773,7 +777,9 @@ export function registerRelationRoutes(
           }
 
           const redirect = normalizeRedirect(result.redirect, base) ?? listUrl
-          return sendRedirectResponse(req, res, json, redirect, result.notifications)
+          return sendRedirectResponse(req, res, json, redirect, result.notifications,
+            result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : undefined,
+          )
         })
 
         // ── View ──
@@ -902,7 +908,9 @@ export function registerRelationRoutes(
           }
 
           const redirect = normalizeRedirect(result.redirect, base) ?? editUrl
-          return sendRedirectResponse(req, res, json, redirect, result.notifications)
+          return sendRedirectResponse(req, res, json, redirect, result.notifications,
+            result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : undefined,
+          )
         })
 
         // ── Delete ──

package/src/routes/resources.ts

@@ -451,7 +451,10 @@ export function registerResourceRoutes(
         const redirect = continueCreate
           ? createUrl
           : normalizeRedirect(result.redirect, base) ?? fallback
-        return sendRedirectResponse(req, res, json, redirect, result.notifications, continueCreate ? { force: true } : undefined)
+        return sendRedirectResponse(req, res, json, redirect, result.notifications, {
+          ...(continueCreate ? { force: true as const } : {}),
+          ...(result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : {}),
+        })
       })
 
       // Action dispatch — POST ${createUrl}/_action/:actionName
@@ -702,7 +705,9 @@ export function registerResourceRoutes(
         }
 
         const redirect = normalizeRedirect(result.redirect, base) ?? editUrl
-        return sendRedirectResponse(req, res, json, redirect, result.notifications)
+        return sendRedirectResponse(req, res, json, redirect, result.notifications,
+          result.relationshipRenames.length > 0 ? { relationshipRenames: result.relationshipRenames } : undefined,
+        )
       })
 
       // Action dispatch — POST ${editUrl}/_action/:actionName