@pilotiq/pilotiq 0.7.1 → 0.8.0

package/src/pageData.ts

@@ -9,4742 +9,133 @@
  * data needs to come from the same builder. Routing both paths through a
  * single builder keeps them in sync.
  */
-import type { Pilotiq, PilotiqConfig } from './Pilotiq.js'
 import { PilotiqRegistry } from './PilotiqRegistry.js'
-import type { Page } from './Page.js'
-import type { ResourceClass, NavigationBadgeColor } from './Resource.js'
-import type { GlobalClass } from './Global.js'
-import { resourceBasePath, globalBasePath, pageBasePath, clusterBasePath } from './clusterPaths.js'
-import type { ClusterClass } from './Cluster.js'
-import { Element, type ElementMeta } from './schema/Element.js'
-import { Field } from './fields/Field.js'
-import { resolveSchema, type RenderContext, type SchemaContext } from './schema/resolveSchema.js'
-import { isServerDataElement, type ServerDataElement } from './schema/ServerDataElement.js'
-import { Form } from './elements/Form.js'
-import { Table } from './elements/Table.js'
-import { Column } from './Column.js'
-import { applyStateUpdate, coerceFormValues, findForms, findWizardStep, loadRelationRows, selectFormById } from './elements/dispatchForm.js'
-import { isRepeaterField, RepeaterField } from './fields/RepeaterField.js'
-import { isBuilderField, BuilderField } from './fields/BuilderField.js'
-import { SelectField } from './fields/SelectField.js'
-import { validateSchema } from './validation/index.js'
-import { searchAllResources, type GlobalSearchResult } from './search.js'
-import { loadTableRecords, findTables, type QueryParams } from './elements/dispatchTable.js'
-import { findActions, findRowExtraActions } from './elements/dispatchAction.js'
-import { Filter } from './filters/Filter.js'
-import { TrashedFilter } from './filters/TrashedFilter.js'
-import { ListTabs } from './elements/ListTabs.js'
-import { ListTab } from './Tab.js'
-import { resolveTheme } from './theme/resolve.js'
-import type { ThemeMeta } from './theme/types.js'
-import { consumeFlashedNotifications } from './notifications/flash.js'
-import {
-  notificationChannel,
-  NOTIFICATION_CREATED_EVENT,
-} from './notifications/broadcast.js'
-import { serializeIcon, type SerializedIcon, type IconValue } from './icons/types.js'
-import {
-  RIGHT_PANEL_DEFAULT_WIDTH,
-  RIGHT_PANEL_MIN_WIDTH,
-  RIGHT_PANEL_MAX_WIDTH,
-} from './RightPanel.js'
-import type { UserMenuItemMeta } from './UserMenuItem.js'
-import {
-  RelationManager,
-  safeManagerPolicy as safeManagerPolicyImpl,
-  type ManagerCanMethod as ManagerCanMethodType,
-  type RelationManagerContext,
-} from './RelationManager.js'
-import { RelationTabs, relationTab, type RelationTabMeta } from './schema/RelationTabs.js'
-import { Breadcrumbs, type BreadcrumbItem } from './schema/Breadcrumbs.js'
-import {
-  resolveRenderHooks,
-  CHROME_HOOK_NAMES,
-  type RenderHookContext,
-  type RenderHookMap,
-  type RenderHookName,
-} from './RenderHook.js'
-import { applyPageHooks, pageHooksFor, type PageRole } from './applyPageHooks.js'
-import {
-  modelSave, modelLoadRecord, modelRelationTableRecords, findRecord, getPrimaryKey,
-  getRelationType,
-  getMorphRelationDescriptor,
-  type ModelLike, type ModelQuery,
-} from './orm/modelDefaults.js'
-import { normalizeRelationMode, type RelationMode } from './RelationManager.js'
-
-// ─── Shared helpers ──────────────────────────────────────────
-
-/**
- * Top-right user dropdown shipped to the renderer in `viewProps.panel`.
- * `null` when no `Pilotiq.user(req => …)` resolver is configured or the
- * resolver returns `null` (no logged-in user) — the renderer suppresses
- * the dropdown entirely in that case.
- *
- * `user.name / user.email / user.avatar` are duck-typed off the
- * resolver's return value; whichever fields are present round-trip into
- * the dropdown trigger (initials fall back to the first two letters of
- * `name` when no avatar URL is set).
- */
-export interface UserMenuMeta {
-  user:     { name?: string; email?: string; avatar?: string }
-  items:    UserMenuItemMeta[]
-  signOut?: { url: string; label: string; method: 'POST' | 'GET' }
-}
-
-/**
- * Bell-icon dropdown configuration shipped under `viewProps.panel`. Sparse —
- * absent when `Pilotiq.databaseNotifications()` wasn't called OR when no
- * user resolves (anonymous request → no inbox to surface). Renderer mounts
- * the bell only when this is set.
- *
- * Routes are absolute URLs (panel `basePath` already applied). Client
- * substitutes `:id` per row when calling read / unread; `_widget`-style
- * params aren't used here because the bell only ever issues these four
- * fetch shapes.
- *
- * `polling` mirrors `DatabaseNotificationsConfig.polling` — `null` ships
- * over the wire to disable client-side polling. The bell still fetches on
- * mount + after every mark-read mutation.
- */
-export interface DatabaseNotificationsMeta {
-  position:    'topbar' | 'sidebar'
-  polling:     number | null
-  pageSize:    number
-  badgeColor:  NavigationBadgeColor
-  trigger?:    { icon?: string; label?: string }
-  listUrl:     string
-  readAllUrl:  string
-  /** Template URL with literal `:id` placeholder. Client replaces. */
-  readUrl:     string
-  /** Template URL with literal `:id` placeholder. Client replaces. */
-  unreadUrl:   string
-  /**
-   * Template URL for the notification-action dispatch endpoint with
-   * literal `:id` and `:actionName` placeholders. Bell client builds
-   * per-action URLs by substituting both at render time. Used only by
-   * `handler`-mode actions; `url` / `post` actions ride their own URL
-   * verbatim.
-   */
-  actionUrl:   string
-  /**
-   * Phase 2 — broadcast hint. Sparse — absent when
-   * `databaseNotifications({ broadcast: true })` wasn't set OR when no
-   * resolved user has an `id` to scope the channel to.
-   *
-   * Client connects to `wsUrl` via `@rudderjs/broadcast`'s
-   * `RudderSocket`, subscribes to the `channel` (already includes the
-   * `private-` prefix), and listens for `event` to trigger refetches.
-   */
-  broadcast?: {
-    wsUrl:   string
-    channel: string
-    event:   string
-  }
-}
-
-/**
- * Right-sidebar shipped under `viewProps.panel.rightSidebar`. Sparse —
- * absent from `panelInfo()` when no contributions are registered, every
- * registered contribution failed `canAccess(user)`, or every visible
- * contribution is `hidden: true`. Renderer mounts the chrome only when
- * this is set.
- *
- * The React component reference for each contribution does NOT travel
- * here — only its tab-strip metadata. The actual body component is
- * resolved client-side from the Vite plugin's `_components.ts` manifest
- * keyed by contribution `id`, mirroring the icon-class round-trip.
- *
- * `defaultWidth` rolls up: contribution-level value when one
- * contribution was registered with one, otherwise the panel-level
- * baseline (`RIGHT_PANEL_DEFAULT_WIDTH`). Client also clamps
- * localStorage values to `[minWidth, maxWidth]`.
- */
-export interface RightPanelMeta {
-  id:           string
-  label:        string
-  icon?:        SerializedIcon
-  defaultWidth: number
-}
-
-export interface RightSidebarMeta {
-  panels:       RightPanelMeta[]
-  defaultWidth: number
-  minWidth:     number
-  maxWidth:     number
-}
-
-/**
- * Single nav-tree entry. `name` is the JS class name (`R.name` /
- * `G.name` / `P.name`) — also the lookup key into the build-time
- * `_components.ts` manifest the Vite plugin emits, so component-typed
- * icons resolve from the same identifier.
- */
-export interface NavItem {
-  name:        string
-  label:       string
-  url:         string
-  icon?:       SerializedIcon
-  group?:      string
-  sort?:       number
-  badge?:      string
-  badgeColor?: NavigationBadgeColor
-  children?:   NavItem[]
-}
-
-/**
- * Build the panel header summary + the unified navigation tree.
- *
- * Pipeline:
- *   1. flatten resources + globals + pages into raw NavItem records
- *   2. drop items whose `canAccess(user)` (Plan #10) returns false
- *   3. resolve `navigationParentItem` references → nest under parents
- *      (cycles broken with a console warn; dangling parents render at top level)
- *   4. sort within each grouping (top-level *and* every parent's children)
- *      by `navigationSort` ascending → registration order
- *   5. resolve every `navigationBadge()` in parallel via `Promise.all`;
- *      handler errors are swallowed (badge omitted) so a flaky count
- *      never blanks the page
- *
- * `req` is the active request; pilotiq calls `pilotiq.resolveUser(req)`
- * once and threads the user into every Resource/Global/Page `canAccess`
- * check. When `Pilotiq.user(fn)` isn't configured, user is `null` and the
- * default `canAccess` returns true → no items dropped.
- */
-/**
- * Optional route-context for `panelInfo()`. When set, render-hook
- * `scope: { resource | page | global }` filters fire correctly for the
- * active route. Missing keys mean the slot has no scope-able identifier
- * (chrome-only routes); scope-less hooks still fire either way.
- *
- * `url` defaults to `cfg.path` when unset. `recordId` rides through to
- * `RenderHookContext.recordId` for hooks that need it.
- */
-export interface PanelInfoRoute {
-  resource?: ResourceClass
-  page?:     typeof Page
-  global?:   GlobalClass
-  recordId?: string
-  url?:      string
-}
-
-export async function panelInfo(
-  pilotiq: Pilotiq,
-  req?:    unknown,
-  route:   PanelInfoRoute = {},
-) {
-  const cfg = pilotiq.getConfig()
-  const merged = pilotiq.getMergedTheme()
-  const theme: ThemeMeta | undefined = merged ? resolveTheme(merged) : undefined
-  const user = await pilotiq.resolveUser(req)
-  const [navigation, userMenu, renderHooks, rightSidebar] = await Promise.all([
-    buildNavigation(pilotiq, user),
-    buildUserMenu(pilotiq, user),
-    resolveChromeHooks(pilotiq, user, route),
-    buildRightSidebarMeta(cfg, user),
-  ])
-  const databaseNotifications = buildDatabaseNotificationsMeta(cfg, user)
-  // 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
-  // this to decide whether to apply writes immediately or stage them as
-  // PendingSuggestions for user approval.
-  const aiSuggestionsMode = pilotiq.getAiSuggestionsMode()
-  return {
-    name: cfg.name,
-    branding: cfg.branding,
-    navigation,
-    theme,
-    themeEditor: cfg.themeEditor ?? false,
-    ...(userMenu ? { userMenu } : {}),
-    ...(databaseNotifications ? { databaseNotifications } : {}),
-    ...(rightSidebar ? { rightSidebar } : {}),
-    ...(Object.keys(renderHooks).length > 0 ? { renderHooks } : {}),
-    ...(aiSuggestionsMode !== 'auto' ? { aiSuggestionsMode } : {}),
-  }
-}
-
-/**
- * Build the bell-icon meta. Returns `null` when:
- *   - `Pilotiq.databaseNotifications()` was never called, OR
- *   - no user resolves (no inbox to surface).
- *
- * Defaults follow Filament: 30s polling, 25 rows per page, primary
- * badge color, topbar position.
- */
-function buildDatabaseNotificationsMeta(
-  cfg:  Readonly<PilotiqConfig>,
-  user: unknown,
-): DatabaseNotificationsMeta | null {
-  if (!cfg.databaseNotifications?.enabled) return null
-  if (user === null || user === undefined) return null
-
-  const dn   = cfg.databaseNotifications
-  const base = cfg.path
-  const meta: DatabaseNotificationsMeta = {
-    position:   dn.position   ?? 'topbar',
-    polling:    dn.polling    === null ? null : (dn.polling ?? 30),
-    pageSize:   dn.pageSize   ?? 25,
-    badgeColor: dn.badgeColor ?? 'primary',
-    listUrl:    `${base}/_notifications`,
-    readAllUrl: `${base}/_notifications/read-all`,
-    readUrl:    `${base}/_notifications/:id/read`,
-    unreadUrl:  `${base}/_notifications/:id/unread`,
-    actionUrl:  `${base}/_notifications/:id/_action/:actionName`,
-  }
-  if (dn.trigger) meta.trigger = { ...dn.trigger }
-  // Phase 2 broadcast hint — only ship when broadcast is enabled AND the
-  // resolved user has an `id` to scope the channel to. The client uses
-  // `wsUrl` for the WebSocket connection and `channel` for the subscribe
-  // call (the private- prefix is already baked in).
-  if (dn.broadcast) {
-    const userId = (user as { id?: unknown } | null | undefined)?.id
-    if (userId !== undefined && userId !== null) {
-      const wsUrl = typeof dn.broadcast === 'object' && dn.broadcast.wsUrl
-        ? dn.broadcast.wsUrl
-        : ''  // empty = client falls back to same-origin /ws
-      meta.broadcast = {
-        wsUrl,
-        channel: notificationChannel(String(userId)),
-        event:   NOTIFICATION_CREATED_EVENT,
-      }
-    }
-  }
-  return meta
-}
-
-/**
- * Build the right-sidebar meta from registered contributions. Returns
- * `null` when:
- *
- *   - no contributions were registered, OR
- *   - every contribution failed `canAccess(user)` (or its predicate
- *     threw — fail-closed), OR
- *   - every passing contribution is `hidden: true` (no tab-strip
- *     surface to mount; programmatic-open consumers should ship at
- *     least one visible tab).
- *
- * Visible contributions are sorted by `sort` ascending (default 100),
- * with registration order as a stable tiebreaker. Each entry's icon is
- * serialized through `serializeIcon` keyed on the contribution `id`
- * (Phase B's Vite plugin extends `_components.ts` to round-trip
- * component-typed icons under that key). `defaultWidth` rolls up:
- * panel-level baseline is `RIGHT_PANEL_DEFAULT_WIDTH`; per-contribution
- * overrides ride on `RightPanelMeta.defaultWidth`.
- *
- * Errors thrown by `canAccess` are swallowed (the contribution is
- * dropped + a single console warn is emitted) so a flaky predicate on
- * one pane never blanks the whole sidebar.
- */
-async function buildRightSidebarMeta(
-  cfg:  Readonly<PilotiqConfig>,
-  user: unknown,
-): Promise<RightSidebarMeta | null> {
-  const list = cfg.rightPanels ?? []
-  if (list.length === 0) return null
-
-  const indexed = list.map((c, idx) => ({ c, idx }))
-  const gated = await Promise.all(
-    indexed.map(async ({ c, idx }) => {
-      if (c.canAccess) {
-        try {
-          const ok = await c.canAccess(user)
-          if (!ok) return null
-        } catch (err) {
-          // eslint-disable-next-line no-console
-          console.warn(`[Pilotiq] rightPanel "${c.id}" canAccess threw — dropping`, err)
-          return null
-        }
-      }
-      return { c, idx }
-    }),
-  )
-
-  const visible = gated
-    .filter((x): x is { c: typeof list[number]; idx: number } => x !== null)
-    .filter((x) => !x.c.hidden)
-    .sort((a, b) => {
-      const sa = a.c.sort ?? 100
-      const sb = b.c.sort ?? 100
-      if (sa !== sb) return sa - sb
-      return a.idx - b.idx
-    })
-
-  if (visible.length === 0) return null
-
-  const panels: RightPanelMeta[] = visible.map(({ c }) => {
-    const meta: RightPanelMeta = {
-      id:           c.id,
-      label:        c.label ?? c.id,
-      defaultWidth: c.defaultWidth ?? RIGHT_PANEL_DEFAULT_WIDTH,
-    }
-    if (c.icon !== undefined) {
-      meta.icon = serializeIcon(c.icon, c.id)
-    }
-    return meta
-  })
-
-  return {
-    panels,
-    defaultWidth: panels[0]?.defaultWidth ?? RIGHT_PANEL_DEFAULT_WIDTH,
-    minWidth:     RIGHT_PANEL_MIN_WIDTH,
-    maxWidth:     RIGHT_PANEL_MAX_WIDTH,
-  }
-}
-
-/**
- * Resolve every chrome render hook (body / topbar / sidebar / user-menu
- * / footer / head). Returns a sparse map — slots with no matching
- * registered entries are omitted so the wire payload stays minimal on
- * panels that don't use render hooks at all.
- */
-async function resolveChromeHooks(
-  pilotiq: Pilotiq,
-  user:    unknown,
-  route:   PanelInfoRoute,
-): Promise<RenderHookMap> {
-  const cfg = pilotiq.getConfig()
-  const entries = cfg.renderHooks ?? []
-  if (entries.length === 0) return {}
-  const ctx: RenderHookContext = {
-    user,
-    basePath: cfg.path,
-    url:      route.url ?? cfg.path,
-  }
-  if (route.resource !== undefined) ctx.resource = route.resource
-  if (route.page     !== undefined) ctx.page     = route.page
-  if (route.global   !== undefined) ctx.global   = route.global
-  if (route.recordId !== undefined) ctx.recordId = route.recordId
-  return resolveRenderHooks(entries, CHROME_HOOK_NAMES, ctx)
-}
-
-/**
- * Resolve a subset of page-role render hooks (e.g. `panels::page.start`
- * + the list-records / create-record / view-record / edit-record /
- * global-search slot families). Per-page-role data builders call this
- * after schema resolution and stamp the result on `viewProps.renderHooks`.
- *
- * `names` lets each builder declare exactly which slots it serves so a
- * list-page builder doesn't ship slots that only fire on the edit page.
- */
-/**
- * Per-builder one-shot — resolve the role's slot set + splice the
- * results into the resolved schema. Wraps the two steps a per-builder
- * data fn always does in lockstep:
- *
- *   1. `resolvePageHooks(pilotiq, user, pageHooksFor(role), route)`
- *   2. `applyPageHooks(schemaData, hooks, role)`
- *
- * Returns the wrapped `ElementMeta[]`. No-op when the panel has no
- * registered hooks. Pass through what you'd pass to `panelInfo()`'s
- * route arg — same shape.
- */
-export async function applyRoleHooks(
-  pilotiq:    Pilotiq,
-  user:       unknown,
-  role:       PageRole,
-  schemaData: ElementMeta[],
-  route:      PanelInfoRoute = {},
-): Promise<ElementMeta[]> {
-  const cfg = pilotiq.getConfig()
-  if (!cfg.renderHooks || cfg.renderHooks.length === 0) return schemaData
-  const hooks = await resolvePageHooks(pilotiq, user, pageHooksFor(role), route)
-  return applyPageHooks(schemaData, hooks, role)
-}
-
-export async function resolvePageHooks(
-  pilotiq: Pilotiq,
-  user:    unknown,
-  names:   readonly RenderHookName[],
-  route:   PanelInfoRoute,
-): Promise<RenderHookMap> {
-  const cfg = pilotiq.getConfig()
-  const entries = cfg.renderHooks ?? []
-  if (entries.length === 0 || names.length === 0) return {}
-  const ctx: RenderHookContext = {
-    user,
-    basePath: cfg.path,
-    url:      route.url ?? cfg.path,
-  }
-  if (route.resource !== undefined) ctx.resource = route.resource
-  if (route.page     !== undefined) ctx.page     = route.page
-  if (route.global   !== undefined) ctx.global   = route.global
-  if (route.recordId !== undefined) ctx.recordId = route.recordId
-  return resolveRenderHooks(entries, names, ctx)
-}
-
-
-/**
- * Build the top-right user-menu meta. Returns `null` when:
- *   - `Pilotiq.user()` isn't configured, or
- *   - the resolver returned `null` (anonymous request), or
- *   - the user object has no extractable identity AND the panel
- *     configured no items / no sign-out (nothing to render).
- *
- * Items resolve in parallel with their visibility predicates
- * (`UserMenuItem.visible`). Throwing predicates fail closed (item
- * dropped). Sort by `.sort(n)` ascending → registration order.
- */
-async function buildUserMenu(pilotiq: Pilotiq, user: unknown): Promise<UserMenuMeta | null> {
-  if (user === null || user === undefined) return null
-
-  const cfg = pilotiq.getConfig()
-  const items = cfg.userMenuItems ?? []
-  const ctx = { user }
-
-  // Resolve every item in parallel. `null` returns mean "filtered by
-  // visibility predicate" — drop them. Indexed pre-sort so stable ties
-  // resolve to registration order.
-  const resolved = await Promise.all(
-    items.map(async (item, idx) => {
-      try {
-        const meta = await item.resolve(ctx)
-        return meta ? { meta, idx, sort: item.getSort() } : null
-      } catch {
-        return null
-      }
-    }),
-  )
-  const visibleItems = resolved
-    .filter((x): x is { meta: UserMenuItemMeta; idx: number; sort: number | undefined } => x !== null)
-    .sort((a, b) => {
-      const aHas = a.sort !== undefined, bHas = b.sort !== undefined
-      if (aHas && bHas) return a.sort! - b.sort! || a.idx - b.idx
-      if (aHas)         return -1
-      if (bHas)         return  1
-      return a.idx - b.idx
-    })
-    .map(x => x.meta)
-
-  // Auto-inject the profile entry from `cfg.profilePage` when set.
-  // Prepended (Filament-style) so it always sits at the top of the
-  // dropdown regardless of user-authored item ordering. Falls through
-  // its own `canAccess(user)` so per-user gating works without the
-  // user repeating the predicate at the menu level.
-  const profileItem = await buildProfileMenuItem(cfg, user)
-  const finalItems  = profileItem ? [profileItem, ...visibleItems] : visibleItems
-
-  const meta: UserMenuMeta = {
-    user:  extractUserIdentity(user),
-    items: finalItems,
-  }
-  if (cfg.signOut) {
-    meta.signOut = {
-      url:    cfg.signOut.url,
-      label:  cfg.signOut.label  ?? 'Sign out',
-      method: cfg.signOut.method ?? 'POST',
-    }
-  }
-  return meta
-}
-
-/** Build the auto-injected profile entry from `cfg.profilePage`. The
- *  Page's `static label` / `static icon` win; defaults `'Edit profile'`
- *  + `'user-circle'` (registry-resolved). Returns `null` when no
- *  profile page is configured or `Page.canAccess(user)` denies. */
-async function buildProfileMenuItem(
-  cfg: Readonly<PilotiqConfig>,
-  user: unknown,
-): Promise<UserMenuItemMeta | null> {
-  const P = cfg.profilePage
-  if (!P) return null
-  if (!(await safeAccess(() => P.canAccess(user)))) return null
-  const url  = pageBasePath(cfg.path, P)
-  const icon = serializeIcon(P.icon ?? 'user-circle', P.name)
-  const meta: UserMenuItemMeta = {
-    name:  '__profile',
-    label: P.label ?? 'Edit profile',
-    url,
-  }
-  if (icon !== undefined) meta.icon = icon
-  return meta
-}
-
-/** Duck-type the user object for display fields. We never throw — a
- *  user resolver might return literally anything (a primitive, a class
- *  instance with getters, a plain object) and the dropdown should
- *  degrade gracefully (initials fallback to '?' when no name found). */
-function extractUserIdentity(user: unknown): { name?: string; email?: string; avatar?: string } {
-  if (user === null || user === undefined) return {}
-  if (typeof user !== 'object') return { name: String(user) }
-  const obj = user as Record<string, unknown>
-  const out: { name?: string; email?: string; avatar?: string } = {}
-  const name = obj.name ?? obj.fullName ?? obj.displayName ?? obj.username
-  if (typeof name   === 'string' && name)   out.name   = name
-  if (typeof obj.email === 'string' && obj.email) out.email = obj.email
-  const avatar = obj.avatar ?? obj.avatarUrl ?? obj.image
-  if (typeof avatar === 'string' && avatar) out.avatar = avatar
-  return out
-}
-
-/** @internal Internal node before nesting; carries the registration index
- *  so we can stable-sort by it as the tie-breaker. */
-interface RawNavItem extends NavItem {
-  parent?: string
-  /** Registration index across resources → globals → pages (in that order),
-   *  so resources beat globals on a sort tie within the same group. */
-  _idx: number
-}
-
-/** Run a `canAccess` check, swallowing throws as `false`. Used by
- *  `buildNavigation` to fail-closed on flaky auth predicates without
- *  blanking the page. */
-async function safeAccess(fn: () => boolean | Promise<boolean>): Promise<boolean> {
-  try {
-    return Boolean(await fn())
-  } catch {
-    return false
-  }
-}
-
-/** Plan #10 — stamp the resolved user onto a SchemaContext so action
- *  visibility predicates can see it during `resolveSchema`. The `user`
- *  field is opaque (whatever `Pilotiq.user(req => …)` returns); skipped
- *  when null/undefined to keep ctx tidy. */
-function userCtx<C extends SchemaContext>(ctx: C, user: unknown): C {
-  if (user === null || user === undefined) return ctx
-  return { ...ctx, user: user as NonNullable<SchemaContext['user']> }
-}
-
-/** Plan #6 — stamp the panel-wide upload URL so `FileUpload` fields
- *  emit it on their meta. Single URL for the whole panel; no per-field
- *  variation. The route is always registered (see `_uploads` in
- *  `routes.ts`) — meta is stamped regardless of whether an adapter is
- *  configured so the renderer can show a clear error rather than
- *  silently breaking. The companion `hasUploadAdapter` flag distinguishes
- *  "URL exists but adapter missing" so fields with optional upload
- *  affordances (e.g. `MarkdownField`'s `attachFiles` button) can hide
- *  themselves rather than render a broken control. */
-function uploadCtx<C extends SchemaContext>(ctx: C, cfg: PilotiqConfig): C {
-  return {
-    ...ctx,
-    uploadUrl: `${cfg.path}/_uploads`,
-    ...(cfg.uploads ? { hasUploadAdapter: true } : {}),
-  }
-}
-
-async function buildNavigation(pilotiq: Pilotiq, user: unknown): Promise<NavItem[]> {
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-
-  // Flatten + resolve badges in parallel. We build the raw list first so
-  // every entry has its identity (`name`) and parent set; badges resolve
-  // alongside.
-  const raw: RawNavItem[] = []
-  let idx = 0
-
-  const pushBadge: Array<{ item: RawNavItem; handler: () => unknown }> = []
-
-  // Plan #10 — pre-evaluate canAccess for every owner in parallel so we
-  // can drop forbidden items before flattening. Failed predicates fail
-  // closed (treated as `false`) so a thrown auth check doesn't accidentally
-  // expose nav items. Clusters compose: a child gated through its
-  // cluster's `canAccess` returning false drops the child even when the
-  // child's own predicate would have passed.
-  const [resourceAccess, globalAccess, pageAccess, clusterAccess] = await Promise.all([
-    Promise.all(cfg.resources.map(R => safeAccess(() => R.canAccess(user)))),
-    Promise.all(cfg.globals.map(G => safeAccess(() => G.canAccess(user)))),
-    Promise.all(cfg.pages.map(P => safeAccess(() => P.canAccess(user)))),
-    Promise.all(cfg.clusters.map(C => safeAccess(() => C.canAccess(user)))),
-  ])
-
-  // Identity-keyed so two clusters that happen to share a `.name`
-  // (minifier collisions, hot-reload duplicate imports) don't clobber.
-  const clusterAccessByClass = new Map<ClusterClass, boolean>()
-  cfg.clusters.forEach((C, i) => clusterAccessByClass.set(C, !!clusterAccess[i]))
-
-  const firstChildUrlByCluster = new Map<ClusterClass, string>()
-  const recordChildUrl = (cluster: ClusterClass, url: string) => {
-    if (!firstChildUrlByCluster.has(cluster)) firstChildUrlByCluster.set(cluster, url)
-  }
-
-  for (let i = 0; i < cfg.resources.length; i++) {
-    const R = cfg.resources[i]!
-    if (!resourceAccess[i]) continue
-    if (R.cluster && !clusterAccessByClass.get(R.cluster)) continue
-    const url = resourceBasePath(base, R)
-    if (R.cluster) recordChildUrl(R.cluster, url)
-    const item: RawNavItem = {
-      name:  R.name,
-      label: R.getNavigationLabel(),
-      url,
-      icon:  serializeIcon(R.getNavigationIcon(), R.name),
-      _idx:  idx++,
-    }
-    if (R.navigationGroup        !== undefined) item.group        = R.navigationGroup
-    if (R.navigationSort         !== undefined) item.sort         = R.navigationSort
-    // Cluster nesting wins over `navigationParentItem`. Both being set
-    // is a misconfiguration; cluster placement is the structural one.
-    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 })
-    raw.push(item)
-  }
-
-  for (let i = 0; i < cfg.globals.length; i++) {
-    if (!globalAccess[i]) continue
-    const G = cfg.globals[i]!
-    if (G.cluster && !clusterAccessByClass.get(G.cluster)) continue
-    // Globals default `navigationGroup` to `'Settings'`. Allow `null` as
-    // an explicit opt-out → render at top level.
-    const group = G.navigationGroup === null ? undefined : G.navigationGroup
-    const url = globalBasePath(base, G)
-    if (G.cluster) recordChildUrl(G.cluster, url)
-    const item: RawNavItem = {
-      name:  G.name,
-      label: G.getNavigationLabel(),
-      url,
-      icon:  serializeIcon(G.getNavigationIcon(), G.name),
-      _idx:  idx++,
-    }
-    if (group                    !== undefined) item.group        = group
-    if (G.navigationSort         !== undefined) item.sort         = G.navigationSort
-    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 })
-    raw.push(item)
-  }
-
-  for (let i = 0; i < cfg.pages.length; i++) {
-    if (!pageAccess[i]) continue
-    const P = cfg.pages[i]!
-    if (P.cluster && !clusterAccessByClass.get(P.cluster)) continue
-    // The dashboard page collapses its nav URL to `${base}` so the
-    // sidebar entry deep-links to the panel root rather than
-    // `${base}/${P.getSlug()}` (which would 404 — the slug route skips
-    // the dashboard page at boot).
-    const isDashboard = cfg.dashboardPage === P
-    const url = isDashboard ? base : pageBasePath(base, P)
-    if (P.cluster && !isDashboard) recordChildUrl(P.cluster, url)
-    const item: RawNavItem = {
-      name:  P.name,
-      label: P.getNavigationLabel(),
-      url,
-      icon:  serializeIcon(P.getNavigationIcon(), P.name),
-      _idx:  idx++,
-    }
-    if (P.navigationGroup        !== undefined) item.group        = P.navigationGroup
-    if (P.navigationSort         !== undefined) item.sort         = P.navigationSort
-    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 })
-    raw.push(item)
-  }
-
-  // Clusters render as first-class nav items. Each gets a URL pointing
-  // at its `landingPage` (when set + accessible) or its first accessible
-  // child. Clusters whose every child was gated out are dropped silently
-  // — same posture as `navigationParentItem` with no resolvable parent.
-  for (let i = 0; i < cfg.clusters.length; i++) {
-    if (!clusterAccess[i]) continue
-    const C = cfg.clusters[i]!
-    let url: string | undefined
-    if (C.landingPage) {
-      const lpIdx = cfg.pages.indexOf(C.landingPage)
-      if (lpIdx !== -1 && pageAccess[lpIdx]) {
-        url = cfg.dashboardPage === C.landingPage ? base : pageBasePath(base, C.landingPage)
-      }
-    }
-    if (url === undefined) url = firstChildUrlByCluster.get(C)
-    if (url === undefined) continue   // empty cluster — drop entirely
-    const item: RawNavItem = {
-      name:  C.name,
-      label: C.getNavigationLabel(),
-      url,
-      icon:  serializeIcon(C.getNavigationIcon(), C.name),
-      _idx:  idx++,
-    }
-    if (C.navigationGroup        !== undefined) item.group        = C.navigationGroup
-    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 })
-    raw.push(item)
-  }
-
-  await Promise.all(pushBadge.map(async ({ item, handler }) => {
-    try {
-      const v = await handler()
-      if (v === undefined || v === null) return
-      item.badge = String(v)
-    } catch {
-      // Per-badge errors stay silent.
-    }
-  }))
-
-  return nestAndSort(raw)
-}
-
-/**
- * Resolve `parent` references → nest, drop cycles, sort within each
- * grouping, then strip internal scaffolding (`parent`, `_idx`).
- */
-function nestAndSort(raw: RawNavItem[]): NavItem[] {
-  const byName = new Map<string, RawNavItem>()
-  for (const it of raw) byName.set(it.name, it)
-
-  // Detect parent cycles: walk upwards from each item; any name seen
-  // twice → cycle. Items in a cycle get treated as top-level.
-  const inCycle = new Set<string>()
-  for (const it of raw) {
-    if (it.parent === undefined) continue
-    const seen = new Set<string>([it.name])
-    let cur: string | undefined = it.parent
-    while (cur !== undefined) {
-      if (seen.has(cur)) {
-        if (typeof console !== 'undefined' && typeof console.warn === 'function') {
-          console.warn(`[Pilotiq] navigationParentItem cycle detected at "${it.name}" — rendering at top level.`)
-        }
-        inCycle.add(it.name)
-        break
-      }
-      seen.add(cur)
-      const parent = byName.get(cur)
-      if (!parent) break
-      cur = parent.parent
-    }
-  }
-
-  const childrenOf = new Map<string, RawNavItem[]>()
-  const top: RawNavItem[] = []
-  for (const it of raw) {
-    const parent = it.parent
-    if (parent && byName.has(parent) && !inCycle.has(it.name)) {
-      const list = childrenOf.get(parent) ?? []
-      list.push(it)
-      childrenOf.set(parent, list)
-    } else {
-      top.push(it)
-    }
-  }
-
-  // Sort items in a sibling group by sort (asc), ties → registration order.
-  const sortItems = (items: RawNavItem[]): RawNavItem[] => {
-    return [...items].sort((a, b) => {
-      const aHas = a.sort !== undefined, bHas = b.sort !== undefined
-      if (aHas && bHas)  return a.sort! - b.sort! || a._idx - b._idx
-      if (aHas)          return -1   // sorted items come before unsorted
-      if (bHas)          return  1
-      return a._idx - b._idx
-    })
-  }
-
-  // Strip internals + recurse into children.
-  const finalize = (items: RawNavItem[]): NavItem[] =>
-    sortItems(items).map(it => {
-      const kids = childrenOf.get(it.name)
-      const { parent, _idx, ...rest } = it
-      const out: NavItem = { ...rest }
-      if (kids && kids.length > 0) out.children = finalize(kids)
-      return out
-    })
-
-  return finalize(top)
-}
-
-export async function callPageSchema(PageClass: typeof Page, ctx: SchemaContext): Promise<Element[]> {
-  return Promise.resolve(PageClass.schema(ctx))
-}
-
-/** Mark every Form on the page with its action URL so the rendered <form> posts to itself. */
-export function tagFormActions(elements: ReadonlyArray<Element>, action: string): void {
-  for (const form of findForms(elements)) {
-    if (!form.getAction()) form.action(action)
-  }
-}
-
-/**
- * Plan #5 — stamp the partial-resolve endpoint URL on every form whose
- * descendants include at least one `live()` field. The client uses
- * `FormMeta.stateUrl` to flip into controlled-state mode; forms without
- * any live fields stay uncontrolled (zero-cost legacy path).
- *
- * `urlBuilder(formId)` lets the caller compose a per-form URL — the
- * endpoint shape is `${base}/${slug}/_form/${formId}/state` so each
- * form on a multi-form page gets its own route segment.
- */
-export function tagFormStateUrls(
-  elements:   ReadonlyArray<Element>,
-  urlBuilder: (formId: string) => string,
-): void {
-  for (const form of findForms(elements)) {
-    if (formHasLiveField(form)) {
-      form.withStateUrl(urlBuilder(form.getFormId()))
-    }
-  }
-}
-
-/**
- * Reorderable rows — stamp the POST-reorder URL on every `Table` that
- * has `Table.reorderable()` set. The renderer reads `TableMeta.reorderUrl`
- * to wire the drop handler; tables that aren't reorderable skip wiring
- * entirely. Same shape as `tagFormStateUrls` so the call site stays
- * consistent.
- */
-export function tagTableReorderUrls(
-  elements: ReadonlyArray<Element>,
-  url:      string,
-): void {
-  for (const table of findTables(elements)) {
-    if (table.isReorderable() && !table.getReorderUrl()) {
-      table.withReorderUrl(url)
-    }
-  }
-}
-
-// Marks every Table on the page deferred and stamps the URL the
-// renderer will fetch from after mount. Must run BEFORE `loadTableRecords`
-// so the records handler short-circuits.
-export function tagTableDeferred(
-  elements: ReadonlyArray<Element>,
-  url:      string,
-): void {
-  for (const table of findTables(elements)) {
-    table.withDeferred(true)
-    table.withTableUrl(url)
-  }
-}
-
-/**
- * Editable cell columns — walk every table on the page and stamp
- * `_cellEditUrls[colName]` per row, but only on rows that already
- * carry a `_cellEditable[colName]` marker (set by `loadTableRecords`
- * after `R.canEdit(user, row)` passed). The dispatcher stays
- * URL-shape-agnostic; URL building lives here parallel to
- * `tagFormStateUrls / tagTableReorderUrls`.
- *
- * `idOf` extracts the per-row primary key. Defaults to reading `id` —
- * works for the rudder ORM convention. Resources with a different
- * primary-key column should pass an override (none in v1).
- */
-export function tagCellEditUrls(
-  elements:  ReadonlyArray<Element>,
-  resourceUrl: string,
-  idOf:      (row: Record<string, unknown>) => unknown = row => row['id'],
-): void {
-  for (const table of findTables(elements)) {
-    const rows = table.getRows() as ReadonlyArray<Record<string, unknown>> | undefined
-    if (!rows || rows.length === 0) continue
-    // Optimisation: skip the table when none of its columns are editable.
-    const editable = (table.getChildren() ?? []).some(c => c instanceof Column && c.isEditable())
-    if (!editable) continue
-    for (const row of rows) {
-      const editableMap = row['_cellEditable'] as Record<string, true> | undefined
-      if (!editableMap) continue
-      const id = idOf(row)
-      if (id === undefined || id === null || id === '') continue
-      const urls: Record<string, string> = {}
-      for (const colName of Object.keys(editableMap)) {
-        urls[colName] = `${resourceUrl}/${encodeURIComponent(String(id))}/_cell/${encodeURIComponent(colName)}`
-      }
-      ;(row as Record<string, unknown>)['_cellEditUrls'] = urls
-    }
-  }
-}
-
-/**
- * Plan #8 — stamp the wizard step-validate endpoint URL on every form
- * whose descendants include a `Wizard` element. `FormMeta.wizardUrl` is
- * what the client posts to on Next-button clicks; forms without a wizard
- * descendant skip wiring.
- */
-export function tagFormWizardUrls(
-  elements:   ReadonlyArray<Element>,
-  urlBuilder: (formId: string) => string,
-): void {
-  for (const form of findForms(elements)) {
-    if (formHasWizard(form)) {
-      form.withWizardUrl(urlBuilder(form.getFormId()))
-    }
-  }
-}
-
-/**
- * Stamp `_agentRunBase` on every field element in the resolved
- * `ElementMeta[]` tree that carries `aiActions`. Operates on the
- * post-`resolveSchema` wire shape (plain objects) rather than on
- * `Element` instances — `aiActions` is added by the `field-ai.ts`
- * wrapper during `toMeta()`, so it isn't visible to pre-resolve walkers.
- *
- * Only called on edit pages where a `recordId` is known. Create pages
- * deliberately skip it — field AI actions target existing content.
- */
-export function tagFieldAiUrls(
-  elements: ReadonlyArray<Record<string, unknown>>,
-  agentBase: string,
-): void {
-  for (const el of elements) {
-    if (Array.isArray(el['aiActions']) && (el['aiActions'] as unknown[]).length > 0) {
-      ;(el as Record<string, unknown>)['_agentRunBase'] = agentBase
-    }
-    const children = el['children']
-    if (Array.isArray(children)) tagFieldAiUrls(children as Record<string, unknown>[], agentBase)
-    // Repeater rows
-    const rows = el['rows']
-    if (Array.isArray(rows)) {
-      for (const row of rows as Record<string, unknown>[]) {
-        const rowChildren = row['children']
-        if (Array.isArray(rowChildren)) tagFieldAiUrls(rowChildren as Record<string, unknown>[], agentBase)
-      }
-    }
-  }
-}
-
-/**
- * Audit row 2026-05-07 cont'd⁸ — stamp the inline-create-option endpoint
- * URL on every `SelectField` that has called `createOptionForm()`. Walks
- * every form on the page so the URL carries the parent form's id; URL
- * shape `${formScopeUrl}/_form/${formId}/create-option/${fieldName}` so
- * the route handler can pick the form by id and the field by name.
- *
- * Mirrors `tagFormStateUrls / tagFormWizardUrls` — operates on the
- * un-resolved Element tree, mutates field-instance state via
- * `field.withCreateOptionUrl(url)`, and the field's `toMeta()` reads it
- * back to emit `createOption.url`.
- *
- * Stops at Repeater / Builder boundaries (parallel to the form-state /
- * wizard walkers): inside-row schemas are dispatched per-row and the
- * createOption shape doesn't compose with row body coercion in v1.
- */
-export function tagSelectCreateOptionUrls(
-  elements:   ReadonlyArray<Element>,
-  urlBuilder: (formId: string, fieldName: string) => string,
-): void {
-  for (const form of findForms(elements)) {
-    const formId = form.getFormId()
-    walkSelectFields(form.getChildren() as Element[] ?? [], (field) => {
-      if (field.hasCreateOption() && !field.getCreateOptionUrl()) {
-        field.withCreateOptionUrl(urlBuilder(formId, field.name))
-      }
-    })
-  }
-}
-
-function walkSelectFields(elements: Element[], visit: (f: SelectField) => void): void {
-  for (const el of elements) {
-    if (el instanceof SelectField) {
-      visit(el)
-      // SelectField has no children of its own — no recursion needed.
-      continue
-    }
-    // Stop at row-array boundaries — see comment on `tagSelectCreateOptionUrls`.
-    if (el instanceof RepeaterField) continue
-    if (el instanceof BuilderField)  continue
-    const children = el.getChildren()
-    if (children && children.length > 0) walkSelectFields(children as Element[], visit)
-  }
-}
-
-/**
- * Adapter-package async-resolve walker. Stamps the per-form mentions URL
- * on every field that ducks like a "rich text with at least one async
- * mention provider". The duck-typed contract lives here (as opposed to
- * importing from `@pilotiq/tiptap`) so pilotiq core stays adapter-free —
- * any future field type with an async-resolve trigger can satisfy the
- * same shape and pick up URL stamping for free.
- *
- * Contract:
- *   - `getType() === 'richtext'`  (fast filter)
- *   - `hasAsyncMentions(): boolean`
- *   - `withMentionsUrl(url: string): unknown`
- *
- * Walks every form on the page so the URL builder can mint a per-form
- * URL (mirrors `tagFormStateUrls / tagFormWizardUrls`). The route handler
- * uses formId in the URL to select the form; the body carries `field`
- * + `trigger` + `query`. One URL per (form, scope), reused across every
- * async-mention field on that form.
- */
-interface AsyncMentionFieldLike {
-  hasAsyncMentions(): boolean
-  withMentionsUrl(url: string): unknown
-}
-
-function isAsyncMentionField(el: Element): el is Element & AsyncMentionFieldLike {
-  if (el.getType() !== 'richtext') return false
-  const candidate = el as unknown as Partial<AsyncMentionFieldLike>
-  return typeof candidate.hasAsyncMentions === 'function'
-      && typeof candidate.withMentionsUrl  === 'function'
-}
-
-export function tagRichTextMentionUrls(
-  elements:   ReadonlyArray<Element>,
-  urlBuilder: (formId: string) => string,
-): void {
-  for (const form of findForms(elements)) {
-    const url = urlBuilder(form.getFormId())
-    let stampedAny = false
-    const visit = (els: ReadonlyArray<Element>): void => {
-      for (const el of els) {
-        // Don't cross into nested forms — each form gets its own URL.
-        if (el !== form && el.getType() === 'form') continue
-        if (isAsyncMentionField(el) && el.hasAsyncMentions()) {
-          el.withMentionsUrl(url)
-          stampedAny = true
-        }
-        // Builder.getChildren() returns undefined to keep the field-level
-        // walkers from treating heterogeneous rows as flat children. Manual
-        // descent into each block's schema covers the URL-stamping path
-        // without changing the no-cross posture for save/coerce.
-        if (isBuilderField(el)) {
-          for (const block of (el as BuilderField).getBlocks()) visit(block.getSchema())
-          continue
-        }
-        const children = el.getChildren()
-        if (children) visit(children)
-      }
-    }
-    const children = form.getChildren()
-    if (children) visit(children)
-    void stampedAny // silence unused — kept locally for readability
-  }
-}
-
-function formHasLiveField(form: Form): boolean {
-  let found = false
-  const visit = (els: ReadonlyArray<Element>): void => {
-    for (const el of els) {
-      if (found) return
-      // Either a server-side `live()` (drives a roundtrip) OR a
-      // client-side `afterStateUpdatedJs(body)` (JS-only) is enough to
-      // mount the controlled-form path: the FormStateProvider holds the
-      // values map either path needs, and the client gates the actual
-      // network POST on `live` separately. Cost of the over-stamp for
-      // JS-only forms is one unused endpoint URL per form — endpoint
-      // never gets hit because the client only POSTs on `live`.
-      if (el instanceof Field && (el.isLive() || el.getAfterStateUpdatedJs() !== undefined)) {
-        found = true
-        return
-      }
-      const children = el.getChildren()
-      if (children) visit(children)
-    }
-  }
-  const children = form.getChildren()
-  if (children) visit(children)
-  return found
-}
-
-function formHasWizard(form: Form): boolean {
-  let found = false
-  const visit = (els: ReadonlyArray<Element>): void => {
-    for (const el of els) {
-      if (found) return
-      if (el.getType() === 'wizard') { found = true; return }
-      const children = el.getChildren()
-      if (children) visit(children)
-    }
-  }
-  const children = form.getChildren()
-  if (children) visit(children)
-  return found
-}
-
-/**
- * Run the edit-mode fill pipeline on a loaded record:
- *   mutateFormDataBeforeFill  →  fillFromRecord  →  mutateFormDataAfterFill
- *
- * `fillFromRecord` defaults to `{ ...record }` when not configured. Both
- * mutators are optional and may be async. `ctx.record` is the loaded
- * record so mutators can read from fields the form doesn't surface.
- */
-export async function applyFillPipeline<R>(
-  form:   Form<R>,
-  record: R,
-): Promise<Record<string, unknown>> {
-  const recordObj = record as unknown as Record<string, unknown>
-  let values: Record<string, unknown> = { ...recordObj }
-
-  const before = form.getMutateFormDataBeforeFill()
-  if (before) values = await before(values, { values, record })
-
-  const fill = form.getFillFromRecord()
-  if (fill) values = fill(record)
-
-  const after = form.getMutateFormDataAfterFill()
-  if (after) values = await after(values, { values, record })
-
-  return values
-}
-
-/**
- * Walk the form's top-level Repeaters and replace `values[fieldName]`
- * with rows fetched from `parent.related(name)` for any
- * relationship-backed Repeater. Each loaded row stamps `__id` to the
- * child's primary key so the renderer can round-trip identity through
- * a hidden input and the save-side diff can match submitted rows back
- * to existing records.
- *
- * No-op when the parent record is null (create mode), when no
- * relationship-backed Repeaters exist on the form, or when the
- * resource has no `R.model` (relation queries need it).
- *
- * Mutates and returns a fresh values object — never the input.
- */
-export async function applyRelationshipRepeaterFill(
-  form:        Form,
-  values:      Record<string, unknown>,
-  record:      unknown,
-  parentModel: ModelLike | undefined,
-): Promise<Record<string, unknown>> {
-  if (record == null) return values
-  if (!parentModel)  return values
-  const repeaters = findRelationshipRepeaters(form.getChildren() ?? [])
-  if (repeaters.length === 0) return values
-
-  const out: Record<string, unknown> = { ...values }
-  for (const repeater of repeaters) {
-    const cfg = repeater.getRelationship()!
-    const pivotColumns = cfg.pivotColumns
-    let rows: unknown[]
-    try {
-      rows = await loadRelationRows(parentModel, record, cfg.name, pivotColumns)
-    } catch {
-      // Failed lookup (e.g. missing `relations` map on a test stub)
-      // — fall back to whatever value applyFillPipeline produced
-      // rather than wiping the field. Better to render stale data
-      // than to silently empty the row list.
-      continue
-    }
-
-    // The child model is opaque here — we don't have the full
-    // descriptor at this seam, so use the configured override or
-    // peek the parent's relations map for the FK column. Strip it
-    // (and the PK) from each row's payload so the inner schema
-    // doesn't surface them as form values. For morphMany the
-    // attachment is two columns instead of one — strip both.
-    const pkColumn   = pickChildPrimaryKey(parentModel, cfg.name) ?? 'id'
-    const fkColumn   = cfg.foreignKey ?? pickChildForeignKey(parentModel, cfg.name)
-    const morph      = getMorphRelationDescriptor(parentModel, cfg.name)
-    const morphIdCol = morph ? `${morph.morphName}Id`   : undefined
-    const morphTyCol = morph ? `${morph.morphName}Type` : undefined
-
-    out[repeater.name] = rows.map(row => {
-      const r = (row && typeof row === 'object') ? { ...(row as Record<string, unknown>) } : {}
-      const pkValue = r[pkColumn]
-      delete r[pkColumn]
-      if (fkColumn)   delete r[fkColumn]
-      if (morphIdCol) delete r[morphIdCol]
-      if (morphTyCol) delete r[morphTyCol]
-      // M2M pivot extras — flatten `row.pivot[col]` onto the row's data
-      // so each pivot column round-trips through the inner schema as a
-      // regular form field. The pivot envelope itself is dropped from
-      // the values shape — the persist side splits pivot vs child
-      // columns by name lookup against `cfg.pivotColumns`.
-      const pivotEnvelope = r['pivot']
-      delete r['pivot']
-      const stamped: Record<string, unknown> = { ...r }
-      if (pivotColumns && pivotColumns.length > 0
-        && pivotEnvelope && typeof pivotEnvelope === 'object'
-      ) {
-        const pe = pivotEnvelope as Record<string, unknown>
-        for (const col of pivotColumns) {
-          if (col in pe) stamped[col] = pe[col]
-        }
-      }
-      if (pkValue !== undefined && pkValue !== null) {
-        stamped['__id'] = String(pkValue)
-      }
-      return stamped
-    })
-  }
-  return out
-}
-
-/** Walk the form's children for top-level relationship-backed Repeaters. */
-function findRelationshipRepeaters(elements: ReadonlyArray<Element>): RepeaterField[] {
-  const out: RepeaterField[] = []
-  const walk = (els: ReadonlyArray<Element>): void => {
-    for (const el of els) {
-      if (isRepeaterField(el)) {
-        const r = el as RepeaterField
-        if (r.getRelationship()) out.push(r)
-        // Don't dive into Repeater children — relationship-on-relationship
-        // isn't supported in v1.
-        continue
-      }
-      // Don't dive into Builder children either — relationship-backed
-      // Builders are resolved separately by `findRelationshipBuilders`.
-      if (isBuilderField(el)) continue
-      const children = el.getChildren()
-      if (children && children.length > 0) walk(children)
-    }
-  }
-  walk(elements)
-  return out
-}
-
-/**
- * Walk the form's top-level Builders and replace `values[fieldName]` with
- * rows fetched from `parent.related(name)` for any relationship-backed
- * Builder. Each loaded row stamps `__id` (child PK) + `type` (block
- * discriminator) + `data` (per-block JSON payload) so the renderer can
- * round-trip the heterogeneous envelope.
- *
- * Mirrors `applyRelationshipRepeaterFill`. No-op when the parent record
- * is null (create mode), the resource has no `R.model`, or no
- * relationship-backed Builders exist on the form.
- */
-export async function applyRelationshipBuilderFill(
-  form:        Form,
-  values:      Record<string, unknown>,
-  record:      unknown,
-  parentModel: ModelLike | undefined,
-): Promise<Record<string, unknown>> {
-  if (record == null) return values
-  if (!parentModel)  return values
-  const builders = findRelationshipBuilders(form.getChildren() ?? [])
-  if (builders.length === 0) return values
-
-  const out: Record<string, unknown> = { ...values }
-  for (const builder of builders) {
-    const cfg = builder.getRelationship()!
-    let rows: unknown[]
-    try {
-      rows = await loadRelationRows(parentModel, record, cfg.name)
-    } catch {
-      // Failed lookup (e.g. missing `relations` map on a test stub) —
-      // fall back to whatever value applyFillPipeline produced rather
-      // than wiping the field. Better stale than silently empty.
-      continue
-    }
-
-    const pkColumn   = pickChildPrimaryKey(parentModel, cfg.name) ?? 'id'
-    const fkColumn   = cfg.foreignKey ?? pickChildForeignKey(parentModel, cfg.name)
-    const typeColumn = cfg.typeColumn ?? 'type'
-    const dataColumn = cfg.dataColumn ?? 'data'
-
-    out[builder.name] = rows.map(row => {
-      const r = (row && typeof row === 'object') ? { ...(row as Record<string, unknown>) } : {}
-      const pkValue   = r[pkColumn]
-      const blockType = typeof r[typeColumn] === 'string' ? (r[typeColumn] as string) : ''
-      const dataRaw   = r[dataColumn]
-      const blockData = parseBuilderDataPayload(dataRaw)
-
-      const stamped: Record<string, unknown> = {
-        type: blockType,
-        data: blockData,
-      }
-      if (pkValue !== undefined && pkValue !== null) {
-        stamped['__id'] = String(pkValue)
-      }
-      // Non-`type` / `data` / FK / PK columns aren't surfaced — the
-      // JSON envelope is the source of truth for per-block fields. If
-      // a user denormalizes a column, they handle it via per-block
-      // mutate hooks, not by leaking the column into row values.
-      void fkColumn
-      return stamped
-    })
-  }
-  return out
-}
-
-/**
- * Normalize the JSON payload column into a plain object. Prisma
- * hydrates `Json` columns to objects; some adapters return strings.
- * Anything that isn't a parseable object falls back to `{}` so the
- * inner schema renders fresh defaults.
- */
-function parseBuilderDataPayload(raw: unknown): Record<string, unknown> {
-  if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
-    return raw as Record<string, unknown>
-  }
-  if (typeof raw === 'string') {
-    try {
-      const parsed: unknown = JSON.parse(raw)
-      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-        return parsed as Record<string, unknown>
-      }
-    } catch {
-      // fall through to {}
-    }
-  }
-  return {}
-}
-
-/** Walk the form's children for top-level relationship-backed Builders. */
-function findRelationshipBuilders(elements: ReadonlyArray<Element>): BuilderField[] {
-  const out: BuilderField[] = []
-  const walk = (els: ReadonlyArray<Element>): void => {
-    for (const el of els) {
-      if (isBuilderField(el)) {
-        const b = el as BuilderField
-        if (b.getRelationship()) out.push(b)
-        continue
-      }
-      // Don't dive into Repeater children either — both array-row
-      // boundaries are walker stops here.
-      if (isRepeaterField(el)) continue
-      const children = el.getChildren()
-      if (children && children.length > 0) walk(children)
-    }
-  }
-  walk(elements)
-  return out
-}
-
-/** Read the child model's PK column from the parent's relations map, when present. */
-function pickChildPrimaryKey(parentModel: ModelLike, name: string): string | undefined {
-  const relations = (parentModel as unknown as Record<string, unknown>)['relations']
-  if (!relations || typeof relations !== 'object') return undefined
-  const entry = (relations as Record<string, unknown>)[name]
-  if (!entry || typeof entry !== 'object') return undefined
-  const e = entry as Record<string, unknown>
-  if (typeof e['model'] !== 'function') return undefined
-  try {
-    const child = (e['model'] as () => ModelLike)()
-    return getPrimaryKey(child)
-  } catch {
-    return undefined
-  }
-}
-
-/** Read the FK column from the parent's relations map, when present. */
-function pickChildForeignKey(parentModel: ModelLike, name: string): string | undefined {
-  const relations = (parentModel as unknown as Record<string, unknown>)['relations']
-  if (!relations || typeof relations !== 'object') return undefined
-  const entry = (relations as Record<string, unknown>)[name]
-  if (!entry || typeof entry !== 'object') return undefined
-  const e = entry as Record<string, unknown>
-  return typeof e['foreignKey'] === 'string' ? (e['foreignKey'] as string) : undefined
-}
-
-// ─── Plan #15 server-data widgets ─────────────────────────────
-
-/** Wire-shape of the per-widget data map shipped to the client.
- *  Lazy elements stamp `null` (renderer paints skeleton + fetches);
- *  eager elements stamp their resolved payload. Errors stamp
- *  `{ error: '<message>' }` so the renderer can surface a per-widget
- *  failure without blanking the page. */
-export type ServerDataMap = Record<string, unknown>
-
-/**
- * Plan #15 — collect every `ServerDataElement` in the schema tree and
- * resolve their `getServerData(ctx)` payloads in parallel. Returns a
- * map keyed by element id, ready to ship as `viewProps._widgetData`.
- *
- * Lazy elements (default — `lazy(false)` opts out) skip the hook and
- * stamp `null` so the renderer paints a skeleton and fetches the
- * payload via `POST {base}/_widget/:id` on mount. Eager elements
- * resolve synchronously and ship the data with the page.
- *
- * Per-widget errors are caught and surfaced as `{ error: '...' }` —
- * one flaky `getStats()` shouldn't 500 the entire dashboard.
- *
- * Visibility is **not** re-evaluated here. The schema resolver
- * (`resolveSchema → evaluateVisibility`) drops hidden layout elements
- * before any widget code runs. Widgets inside still-rendered branches
- * always resolve (or stamp lazy null).
- */
-export async function resolveServerDataElements(
-  elements: ReadonlyArray<Element>,
-  ctx:      RenderContext,
-): Promise<ServerDataMap> {
-  const widgets = collectServerDataElements(elements)
-  if (widgets.length === 0) return {}
-  const out: ServerDataMap = {}
-  await Promise.all(widgets.map(async (el) => {
-    const id = el.getId()
-    if (el.isLazy()) {
-      out[id] = null  // sentinel — renderer paints skeleton, fetches on mount
-      return
-    }
-    try {
-      out[id] = await el.resolveServerData(ctx)
-    } catch (err) {
-      out[id] = { error: err instanceof Error ? err.message : 'Widget failed to load' }
-    }
-  }))
-  return out
-}
-
-/** Walk the tree collecting every `ServerDataElement`. Walks into
- *  containers but stops at Form/Repeater/Builder boundaries — widgets
- *  inside an editable form don't make sense in v1. */
-function collectServerDataElements(elements: ReadonlyArray<Element>): ServerDataElement[] {
-  const out: ServerDataElement[] = []
-  const walk = (els: ReadonlyArray<Element>): void => {
-    for (const el of els) {
-      if (isServerDataElement(el)) {
-        out.push(el)
-        // Don't recurse into a widget's children — `View` etc. are leaves
-        // for v1 (no nested widgets inside widgets).
-        continue
-      }
-      // Skip walkers that imply per-row resolution — widgets inside
-      // Repeater/Builder rows don't have a stable id space.
-      const type = el.getType()
-      if (type === 'form' || type === 'repeater' || type === 'builder' || type === 'table' || type === 'tableWidget') continue
-      const children = el.getChildren()
-      if (children) walk(children)
-    }
-  }
-  walk(elements)
-  return out
-}
-
-/**
- * Plan #15 — stamp the polling-endpoint URL on every `ServerDataElement`
- * in the tree. Mirrors `tagFormStateUrls / tagTableReorderUrls`. Walks
- * with the same boundaries as `collectServerDataElements` so the wire
- * stays in sync (no orphan widgets without URLs and vice versa).
- *
- * `urlBuilder(id)` typically produces `${base}/_widget/${id}` for
- * dashboard widgets and `${base}/${pageSlug}/_widget/${id}` for
- * custom-page widgets — the route handlers for both shapes are wired up
- * in `routes.ts` (see Phase A.4).
- */
-export function tagWidgetUrls(
-  elements:   ReadonlyArray<Element>,
-  urlBuilder: (id: string) => string,
-): void {
-  for (const widget of collectServerDataElements(elements)) {
-    if (widget.getWidgetUrl()) continue // user-set wins
-    widget.withWidgetUrl(urlBuilder(widget.getId()))
-  }
-}
-
-/** Stamp dispatchUrl on every handler-style Action so the client knows where to POST. */
-export function tagActionDispatch(elements: ReadonlyArray<Element>, baseUrl: string): void {
-  for (const action of findActions(elements)) {
-    if (!action.getHandler()) continue
-    if (action.getHref() || action.getMethod()) continue
-    if (action.getDispatchUrl()) continue
-    action.dispatchUrl(`${baseUrl}/_action/${action.name}`)
-  }
-  // Row-scoped extraItemActions (Repeater/Builder). Stamped here too so
-  // the client can POST to the same `_action/:name` route — the renderer
-  // attaches `_rowPath=<fieldName>.<index>` per click; the server's
-  // dispatcher uses that to walk into the right row when building
-  // `ctx.row`. See `findRowExtraActions` in `dispatchAction.ts`.
-  for (const { action } of findRowExtraActions(elements)) {
-    if (!action.getHandler()) continue
-    if (action.getDispatchUrl()) continue
-    action.dispatchUrl(`${baseUrl}/_action/${action.name}`)
-  }
-}
-
-// ─── Per-role data builders ──────────────────────────────────
-
-export async function dashboardData(pilotiq: Pilotiq, req?: unknown): Promise<Record<string, unknown>> {
-  const cfg = pilotiq.getConfig()
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ basePath: cfg.path }, user), cfg)
-
-  // Plan #15 — when `panel.dashboard(P)` was called, resolve P's
-  // schema instead of the builder-level `cfg.schema`. Page-scoped
-  // schema means widget elements read like a regular custom page —
-  // including action dispatch, form-state, and `_widget/:id` polling.
-  let elements: Element[]
-  if (cfg.dashboardPage) {
-    elements = await callPageSchema(cfg.dashboardPage, ctx)
-    tagFormActions(elements, cfg.path)
-    tagFormStateUrls(elements, formId => `${cfg.path}/_form/${formId}/state`)
-    tagFormWizardUrls(elements, formId => `${cfg.path}/_form/${formId}/wizard`)
-    tagRichTextMentionUrls(elements, formId => `${cfg.path}/_form/${formId}/mentions`)
-    tagSelectCreateOptionUrls(elements, (formId, fieldName) => `${cfg.path}/_form/${formId}/create-option/${fieldName}`)
-    tagActionDispatch(elements, cfg.path)
-  } else {
-    elements = []
-    if (cfg.schema) {
-      const def = cfg.schema
-      elements = typeof def === 'function' ? await def(ctx) : def
-    }
-  }
-
-  // Stamp polling URLs on every widget — panel-scope (no pageSlug
-  // segment) for the dashboard. Done before schema resolve so the URL
-  // rides on each widget's stamped meta.
-  tagWidgetUrls(elements, id => `${cfg.path}/_widget/${id}`)
-
-  const widgetData = await resolveServerDataElements(elements, ctx)
-  const dashRoute: PanelInfoRoute = cfg.dashboardPage ? { page: cfg.dashboardPage } : {}
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'dashboard',
-    await resolveSchema(elements, ctx),
-    dashRoute,
-  )
-
-  return {
-    panel:    await panelInfo(pilotiq, req, dashRoute),
-    page:     cfg.dashboardPage ? cfg.dashboardPage.toMeta() : undefined,
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    _widgetData: widgetData,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-export async function resourceIndexData(
-  pilotiq: Pilotiq,
-  slug:    string,
-  query:   Record<string, string> = {},
-  req?:    unknown,
-): Promise<Record<string, unknown> | null> {
-  const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
-  if (!R) return null
-
-  const pages = R.resolvePages()
-  if (!pages.index) return null
-  const PageClass = pages.index
-
-  const indexUrl = resourceBasePath(cfg.path, R)
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'table', basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-  tagActionDispatch(elements, indexUrl)
-  // Plan #15 — resource-scope widget polling URL. Stamped before the
-  // schema resolves so each widget's meta carries its endpoint.
-  tagWidgetUrls(elements, id => `${indexUrl}/_widget/${id}`)
-  // Mark the active tab + parallel-eval badges + stamp per-tab URLs
-  // before the table records run — `loadTableRecords` walks the schema
-  // for the active tab and splices its `modifyQuery` predicate into the
-  // ORM chain alongside filters.
-  await resolveActiveTab(elements, query, indexUrl)
-  if (R.deferLoading) tagTableDeferred(elements, `${indexUrl}/_table`)
-  await loadTableRecords(elements, query, indexUrl, user, {
-    canEdit: (u, record) => R.canEdit(u, record),
-  })
-  tagTableReorderUrls(elements, `${indexUrl}/_reorder`)
-  tagCellEditUrls(elements, indexUrl)
-  const widgetData = await resolveServerDataElements(elements, ctx)
-
-  const breadcrumbs = resourceListBreadcrumbs(cfg, R)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const listRoute: PanelInfoRoute = { resource: R, page: PageClass }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'list',
-    await resolveSchema(elements, ctx),
-    listRoute,
-  )
-
-  return {
-    pageType: 'resource',
-    panel:    await panelInfo(pilotiq, req, listRoute),
-    page:     PageClass.toMeta(),
-    resource: { name: R.name, label: R.label, labelSingular: R.labelSingular, slug, icon: serializeIcon(R.icon, R.name) },
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    _widgetData: widgetData,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-// Deferred-load JSON endpoint payload — `GET {base}/{slug}/_table`
-// re-runs the list-page builder without the deferred flag, then returns
-// every resolved `TableMeta` as a flat array. Returns null on missing
-// resource / index page (route 404s).
-export async function resourceTableData(
-  pilotiq: Pilotiq,
-  slug:    string,
-  query:   Record<string, string> = {},
-  req?:    unknown,
-): Promise<{ tables: Record<string, unknown>[] } | null> {
-  const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
-  if (!R) return null
-
-  const pages = R.resolvePages()
-  if (!pages.index) return null
-  const PageClass = pages.index
-
-  const indexUrl = resourceBasePath(cfg.path, R)
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'table', basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-  tagActionDispatch(elements, indexUrl)
-  await resolveActiveTab(elements, query, indexUrl)
-  await loadTableRecords(elements, query, indexUrl, user, {
-    canEdit: (u, record) => R.canEdit(u, record),
-  })
-  tagTableReorderUrls(elements, `${indexUrl}/_reorder`)
-  tagCellEditUrls(elements, indexUrl)
-  const schemaData = await resolveSchema(elements, ctx)
-
-  const tables = collectTableMetas(schemaData)
-  return { tables }
-}
-
-function collectTableMetas(
-  metas: ReadonlyArray<Record<string, unknown>>,
-): Record<string, unknown>[] {
-  const out: Record<string, unknown>[] = []
-  const walk = (nodes: ReadonlyArray<Record<string, unknown>>): void => {
-    for (const node of nodes) {
-      if (node['type'] === 'table') out.push(node)
-      const children = node['children']
-      if (Array.isArray(children)) walk(children as Record<string, unknown>[])
-    }
-  }
-  walk(metas)
-  return out
-}
-
-/**
- * Walk the schema for `ListTabs` containers, pick the active tab from
- * `?tab=…` (defaulting to the tab marked `.default()` or the first one),
- * stamp render-time state (`active` flag, per-tab `?tab=` URL, and
- * resolved badge counts) onto each tab. The active tab's query/context
- * modifier is NOT applied here — `loadTableRecords` walks for the active
- * tab and splices in its modifier when it builds the records-handler
- * `TableContext`.
- *
- * No-op when the page has no `ListTabs`.
- */
-export async function resolveActiveTab(
-  elements:    ReadonlyArray<Element>,
-  query:       Record<string, string>,
-  currentPath: string,
-): Promise<void> {
-  const listTabs = findListTabs(elements)
-  if (listTabs.length === 0) return
-
-  for (const container of listTabs) {
-    const children = (container.getChildren() ?? []).filter((c): c is ListTab => c.getType() === 'listTab')
-    if (children.length === 0) continue
-
-    // Default tab (used both for `?tab=` fallback and to omit the param
-    // from the canonical URL of that tab — see `buildTabUrl`).
-    const defaultTab = children.find(t => t.isDefault()) ?? children[0]!
-
-    // Active tab: explicit `?tab=name` → default tab.
-    const wanted = typeof query['tab'] === 'string' ? query['tab'] : undefined
-    const active = (wanted && children.find(t => t.name === wanted)) || defaultTab
-
-    // Stamp render-time state on each tab.
-    children.forEach(t => {
-      t.withActive(t === active)
-      t.withUrl(buildTabUrl(currentPath, query, t.name, defaultTab.name))
-    })
-
-    // Resolve every tab's badge in parallel — failed handlers swallow
-    // silently (badge omitted) so a flaky count never blanks the page.
-    await Promise.all(children.map(async (tab) => {
-      const handler = tab.getBadgeHandler()
-      if (!handler) return
-      try {
-        const v = await handler()
-        if (v === undefined || v === null) return
-        tab.withResolvedBadge(String(v))
-      } catch {
-        // Per-tab badge errors stay silent.
-      }
-    }))
-  }
-}
-
-function findListTabs(elements: ReadonlyArray<Element>): ListTabs[] {
-  const out: ListTabs[] = []
-  const walk = (els: ReadonlyArray<Element>): void => {
-    for (const el of els) {
-      if (el.getType() === 'listTabs') out.push(el as ListTabs)
-      const children = el.getChildren()
-      if (children) walk(children)
-    }
-  }
-  walk(elements)
-  return out
-}
-
-function buildTabUrl(
-  pathname:       string,
-  query:          Record<string, string>,
-  tabName:        string,
-  defaultTabName: string,
-): string {
-  // Carry forward search/sort/perPage + any filter values; reset page to 1
-  // (tab change reshapes the result set, page numbers don't translate).
-  // The default tab gets the canonical, paramless URL — visiting that URL
-  // already lands on the default, so emitting `?tab=default` would just be
-  // noise that bookmarks/share-links pick up.
-  const params = new URLSearchParams()
-  for (const [k, v] of Object.entries(query)) {
-    if (v === undefined || v === '' || v === null) continue
-    if (k === 'tab' || k === 'page') continue
-    params.set(k, String(v))
-  }
-  if (tabName !== defaultTabName) params.set('tab', tabName)
-  const qs = params.toString()
-  return qs ? `${pathname}?${qs}` : pathname
-}
-
-export async function resourceCreateData(
-  pilotiq: Pilotiq,
-  slug:    string,
-  prefill?: { values?: Record<string, unknown>; errors?: Record<string, string[]> },
-  req?:    unknown,
-): Promise<Record<string, unknown> | null> {
-  const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
-  if (!R) return null
-  const pages = R.resolvePages()
-  if (!pages.create) return null
-  const PageClass = pages.create
-
-  const resourceBase = resourceBasePath(cfg.path, R)
-  const createUrl = `${resourceBase}/create`
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'create', basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-  tagFormActions(elements, createUrl)
-  tagActionDispatch(elements, createUrl)
-  tagFormStateUrls(elements, formId => `${resourceBase}/_form/${formId}/state`)
-  tagFormWizardUrls(elements, formId => `${resourceBase}/_form/${formId}/wizard`)
-  tagRichTextMentionUrls(elements, formId => `${resourceBase}/_form/${formId}/mentions`)
-  tagSelectCreateOptionUrls(elements, (formId, fieldName) => `${resourceBase}/_form/${formId}/create-option/${fieldName}`)
-  if (prefill) {
-    const form = findForms(elements)[0]
-    if (form) {
-      if (prefill.values) form.withValues(prefill.values)
-      if (prefill.errors) form.withErrors(prefill.errors)
-    }
-  }
-
-  const breadcrumbs = resourceCreateBreadcrumbs(cfg, R)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const createRoute: PanelInfoRoute = { resource: R, page: PageClass }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'create',
-    await resolveSchema(elements, ctx),
-    createRoute,
-  )
-
-  return {
-    panel:    await panelInfo(pilotiq, req, createRoute),
-    page:     PageClass.toMeta(),
-    resource: { name: R.name, label: R.labelSingular, slug, icon: serializeIcon(R.icon, R.name) },
-    mode:     'create' as const,
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-    ...(prefill?.errors ? { hasErrors: true } : {}),
-  }
-}
-
-export async function resourceEditData(
-  pilotiq:  Pilotiq,
-  slug:     string,
-  recordId: string,
-  prefill?: { values?: Record<string, unknown>; errors?: Record<string, string[]> },
-  req?:     unknown,
-): Promise<Record<string, unknown> | null> {
-  const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
-  if (!R) return null
-  const pages = R.resolvePages()
-  if (!pages.edit) return null
-  const PageClass = pages.edit
-
-  const resourceBase = resourceBasePath(cfg.path, R)
-  const editUrl = `${resourceBase}/${recordId}/edit`
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'edit', recordId, basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-  tagFormActions(elements, editUrl)
-  tagActionDispatch(elements, editUrl)
-  tagFormStateUrls(elements, formId => `${resourceBase}/${recordId}/_form/${formId}/state`)
-  tagFormWizardUrls(elements, formId => `${resourceBase}/${recordId}/_form/${formId}/wizard`)
-  tagRichTextMentionUrls(elements, formId => `${resourceBase}/${recordId}/_form/${formId}/mentions`)
-  tagSelectCreateOptionUrls(elements, (formId, fieldName) => `${resourceBase}/${recordId}/_form/${formId}/create-option/${fieldName}`)
-
-  // Locate the primary form, load the record, fill values.
-  const form = findForms(elements)[0]
-  let record: unknown = undefined
-  if (form?.getLoadRecord()) {
-    try {
-      record = await form.getLoadRecord()!(recordId, { values: prefill?.values ?? {} })
-    } catch {
-      // sentinel/missing record — fall through
-    }
-    if (!prefill?.values && record != null) {
-      const values = await applyFillPipeline(form, record)
-      const withRelations  = await applyRelationshipRepeaterFill(form, values, record, R.model)
-      const withBuilders   = await applyRelationshipBuilderFill(form, withRelations, record, R.model)
-      form.withValues(withBuilders)
-    } else if (prefill?.values) {
-      form.withValues(prefill.values)
-    }
-    if (prefill?.errors) form.withErrors(prefill.errors)
-  }
-
-  // Plan #11 — when the resource has relation managers, prepend a
-  // navigation strip so users can drill into each manager's table
-  // without leaving the parent record context. The "Edit" tab is
-  // active here.
-  const relationTabsEl = await buildRelationTabs(R, recordId, cfg.path, '__edit', user, record)
-  if (relationTabsEl) elements.unshift(relationTabsEl)
-
-  const recordTitle = record !== undefined && record !== null
-    ? deriveParentTitle(R, record)
-    : recordId
-  const breadcrumbs = resourceEditBreadcrumbs(cfg, R, recordId, recordTitle)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const editRoute: PanelInfoRoute = { resource: R, page: PageClass, recordId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'edit',
-    await resolveSchema(
-      elements,
-      record !== undefined ? { ...ctx, record } : ctx,
-    ),
-    editRoute,
-  )
-
-  tagFieldAiUrls(schemaData as Record<string, unknown>[], `${resourceBase}/${recordId}/_agents`)
-
-  return {
-    panel:    await panelInfo(pilotiq, req, editRoute),
-    page:     PageClass.toMeta(),
-    resource: { name: R.name, label: R.labelSingular, slug, icon: serializeIcon(R.icon, R.name) },
-    mode:     'edit' as const,
-    recordId,
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-    ...(prefill?.errors ? { hasErrors: true } : {}),
-  }
-}
-
-// ─── Plan #11 relation-manager data builder ─────────────────
-
-/**
- * Plan #11 — three scopes a single relation-manager URL space resolves to:
- *
- *   list:    GET    {base}/{slug}/:id/{rel}
- *   create:  GET    {base}/{slug}/:id/{rel}/create
- *   edit:    GET    {base}/{slug}/:id/{rel}/{childId}/edit
- *
- * Each carries enough state for `relationManagerData` to load the right
- * parent + (for edit) child + form/table context. Submit-side handlers
- * live in `routes.ts` and reuse `dispatchFormSubmit`.
- */
-export type RelationManagerScope =
-  | { kind: 'relation-list';   slug: string; recordId: string; relationship: string; query?: Record<string, string> }
-  | { kind: 'relation-create'; slug: string; recordId: string; relationship: string; prefill?: { values?: Record<string, unknown>; errors?: Record<string, string[]> } }
-  | { kind: 'relation-view';   slug: string; recordId: string; relationship: string; childId: string }
-  | { kind: 'relation-edit';   slug: string; recordId: string; relationship: string; childId: string; prefill?: { values?: Record<string, unknown>; errors?: Record<string, string[]> } }
-  // Phase B nested resources — the leaf is one manager deeper than the
-  // depth-1 variants. The two-step `chain` carries the (recordId,
-  // relationship) for each layer; the trailing `childId` (when present)
-  // is the leaf record's id under chain[1].
-  | { kind: 'nested-relation-list';   slug: string; chain: [RelationChainStep, RelationChainStep]; query?: Record<string, string> }
-  | { kind: 'nested-relation-create'; slug: string; chain: [RelationChainStep, RelationChainStep]; prefill?: { values?: Record<string, unknown>; errors?: Record<string, string[]> } }
-  | { kind: 'nested-relation-view';   slug: string; chain: [RelationChainStep, RelationChainStep]; childId: string }
-  | { kind: 'nested-relation-edit';   slug: string; chain: [RelationChainStep, RelationChainStep]; childId: string; prefill?: { values?: Record<string, unknown>; errors?: Record<string, string[]> } }
-
-/** Phase B — one parent layer in a nested-resources URL chain. The list
- *  of these identifies a path through the manager tree:
- *    `[ { recordId: '123', relationship: 'comments' } ]` picks comment
- *    "456 under post 123" when paired with `childId: '456'`. */
-export interface RelationChainStep {
-  recordId:     string
-  relationship: string
-}
-
-/**
- * Failure outcomes the data builder discriminates back to the route
- * handler, which decides between 403 / 404 / HTML / JSON shapes.
- *
- *   `null`            — unknown panel / parent / manager / child;
- *                        route returns 404
- *   `{ ok: false, status: 403 }` — policy denied; route returns 403
- *
- * Success returns the schemaData payload directly (a record, not
- * tagged) for parity with `resourceIndexData / resourceCreateData`.
- */
-export type RelationManagerResult =
-  | Record<string, unknown>
-  | { ok: false; status: 403 }
-  | null
-
-/**
- * Discover the related Resource for a manager. Order:
- *   1. `M.relatedResource` explicit override (skip discovery).
- *   2. Rudder ORM convention: walk
- *      `R.model.relations[manager.relationship].model()` and find
- *      `cfg.resources[i].model === relatedModel`.
- *   3. Otherwise undefined — caller must error or fall back.
- *
- * A returned Resource is the one whose `model` backs the related
- * table. Callers use it for `Related.model.find(childId)`,
- * `Related.canEdit(user, child)`, and the auto-wired form save handler.
- */
-export function findRelatedResource(
-  M:   typeof RelationManager,
-  R:   ResourceClass,
-  cfg: ReturnType<Pilotiq['getConfig']>,
-): ResourceClass | undefined {
-  if (M.relatedResource) return M.relatedResource
-  const ParentModel = R.model as unknown as { relations?: Record<string, { model?: () => unknown }> } | undefined
-  if (!ParentModel) return undefined
-  const def = ParentModel.relations?.[M.getRelationship()]
-  const RelatedModel = typeof def?.model === 'function' ? def.model() : undefined
-  if (!RelatedModel) return undefined
-  return cfg.resources.find(r => (r.model as unknown) === RelatedModel)
-}
-
-/** Find a registered manager on a Resource by its relationship key.
- *  Throws on unknown manager — so the route can 404 cleanly. */
-function findManager(
-  R:            ResourceClass,
-  relationship: string,
-): typeof RelationManager | undefined {
-  return R.relations().find(M => {
-    try { return M.getRelationship() === relationship } catch { return false }
-  })
-}
-
-/**
- * Verify a child record actually belongs to the given parent under the
- * declared relationship. Anti-IDOR — without this an attacker can swap
- * the `:childId` segment to load any related-model row regardless of
- * whether it's actually owned by the parent.
- *
- * Strategy: re-resolve the parent's relation query and check whether
- * the child's primary key shows up in `where(pk, '=', childId).paginate(1, 1)`.
- * Yes, it's a second round-trip — but it's the single point of trust
- * for IDOR safety, and it fits naturally into the same query path
- * `modelRelationTableRecords` uses.
- */
-async function childBelongsToParent(
-  parentModel:  ModelLike,
-  parent:       unknown,
-  relationship: string,
-  childPk:      string,
-  childId:      string,
-): Promise<boolean> {
-  try {
-    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)
-    return result.total > 0
-  } catch {
-    return false
-  }
-}
-
-/**
- * Auto-wire the manager's table records loader against the parent's
- * relation query when the user didn't set `Table.records()` themselves.
- * Mirrors `defaultPages`'s wiring of `Table.records()` from `R.model`
- * for the resource list page.
- */
-function autoWireManagerTable(
-  table:        Table,
-  parentModel:  ModelLike,
-  parent:       unknown,
-  relationship: string,
-): void {
-  if (table.getRecords()) return  // user wired it explicitly
-  table.records(modelRelationTableRecords(parentModel, parent, relationship, table))
-}
-
-/**
- * Plan #13 polish — auto-inject `TrashedFilter` on a relation manager's
- * table when the **related** Resource opts into soft deletes. Mirrors the
- * resource-list pattern in `defaultPages.applyTableDefaults`. The check
- * is on the related Resource (not the manager), because soft-delete is a
- * model-level capability — if the child model supports trashing, the
- * manager's table should expose the toggle.
- *
- * No-op when:
- *   - the related Resource hasn't set `softDeletes = true`
- *   - the user already attached a `TrashedFilter` in `M.table()`
- */
-function injectManagerTrashedFilter(
-  table:   Table,
-  Related: ResourceClass | undefined,
-): void {
-  if (!Related?.softDeletes) return
-  const children = table.getChildren() ?? []
-  const hasTrashed = children.some(c => c instanceof TrashedFilter)
-  if (hasTrashed) return
-  const existing = children.filter(c => c instanceof Filter) as Filter[]
-  table.filters([...existing, TrashedFilter.make()])
-}
-
-/**
- * Auto-wire the manager's form save + loadRecord handlers against the
- * **related** Resource's `model` when the user didn't set them. The
- * route handler is responsible for stamping the parent context
- * (parent, parentRecord, parentId, relationship) onto the
- * `FormContext` so user-supplied `mutateDataBeforeCreate` etc. can
- * read them.
- */
-function autoWireManagerForm(form: Form, Related: ResourceClass): void {
-  const RelatedModel = Related.model
-  if (!RelatedModel) return
-  if (!form.getSave())       form.save(modelSave(RelatedModel))
-  if (!form.getLoadRecord()) form.loadRecord(modelLoadRecord(Related))
-}
-
-async function safePolicy(fn: () => Promise<boolean> | boolean): Promise<boolean> {
-  try { return Boolean(await fn()) } catch { return false }
-}
-
-/** Plan #11 — authorization predicate names a `RelationManager` carries.
- *  Re-exported from `RelationManager.ts`. */
-export type ManagerCanMethod = ManagerCanMethodType
-
-/** Plan #11 — authorize a relation-manager action with sensible defaults.
- *  Re-exported from `RelationManager.ts` so external callers (route
- *  handlers, third-party plugins) keep their existing import path. */
-export const safeManagerPolicy = safeManagerPolicyImpl
-
-/**
- * Plan #11 — render data for the three relation-manager URL scopes.
- * Mirrors the resource* builders' shape so routes and Vike +data hooks
- * consume identical props. Authorization runs inline (parent
- * `canAccess + canEdit(parent)` then manager-scoped predicate); IDOR
- * check on `relation-edit` runs against the parent's relation query.
- *
- * Returns:
- *   - `null` when panel / parent / manager / child don't exist.
- *   - `{ ok: false, status: 403 }` when authorization denies.
- *   - the props record on success (route picks SSR view / SPA prop
- *     downstream).
- */
-export async function relationManagerData(
-  pilotiq: Pilotiq,
-  scope:   RelationManagerScope,
-  req?:    unknown,
-): Promise<RelationManagerResult> {
-  // Phase B nested-relation-* scopes split out into their own pipeline
-  // — the chain walking + per-layer auth differs enough from the
-  // depth-1 path that interleaving them would mostly hurt readability.
-  if (scope.kind === 'nested-relation-list'
-   || scope.kind === 'nested-relation-create'
-   || scope.kind === 'nested-relation-view'
-   || scope.kind === 'nested-relation-edit') {
-    return nestedRelationManagerData(pilotiq, scope, req)
-  }
-
-  const cfg = pilotiq.getConfig()
-
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
-  if (!R) return null
-
-  const M = findManager(R, scope.relationship)
-  if (!M) return null
-
-  const user = await pilotiq.resolveUser(req)
-
-  // Layer 1: parent access. canAccess gates the resource entirely;
-  // canEdit gates managing its relations (managers are read-write
-  // surfaces — read-only inline views opt in by overriding the
-  // manager's can*). Cluster gate composes with R.canAccess — both
-  // must pass when the parent resource is inside a cluster.
-  if (R.cluster && !await safePolicy(() => R.cluster!.canAccess(user))) return { ok: false, status: 403 }
-  if (!await safePolicy(() => R.canAccess(user))) return { ok: false, status: 403 }
-
-  if (!R.model) {
-    // Without a model on the parent we can't load the parent record,
-    // and without that we can't IDOR-check children. Point users at
-    // the missing wiring rather than silent 500s.
-    throw new Error(
-      `[Pilotiq] Resource "${R.name}" has relations(${M.name}) but no static model. ` +
-      `Set Resource.model = … to enable relation managers, or remove the manager.`,
-    )
-  }
-
-  const parentRecord = await findRecord(R, scope.recordId, { user }).catch(() => undefined)
-  if (!parentRecord) return null
-
-  if (!await safePolicy(() => R.canEdit(user, parentRecord))) return { ok: false, status: 403 }
-
-  // Read the relation type off the parent's relations map once,
-  // normalize to the six-way `RelationMode` the manager-side logic
-  // uses. `belongsToMany` / `morphToMany` (owning polymorphic) /
-  // `morphedByMany` (inverse polymorphic) all flip into pivot-mutation
-  // mode (attach / detach / sync — same accessor surface), `morphMany|
-  // morphOne` collapses to `'morphMany'` (parent-side polymorphic —
-  // auto-fills morph columns on create), `morphTo` is the child-side
-  // polymorphic (no auto-actions; requires explicit `M.relatedResource`).
-  // Everything else collapses to `'hasMany'`.
-  const relationType = getRelationType(R.model, scope.relationship)
-  const mode: RelationMode = normalizeRelationMode(relationType)
-
-  const Related = findRelatedResource(M, R, cfg)
-  // Related Resource is required for: edit/create form auto-wire,
-  // child loading on edit, related URL generation. Throw when missing
-  // *only* if we'd otherwise need it — for `relation-list` it's
-  // optional (the table can be hand-wired by the user).
-  const needRelated = scope.kind !== 'relation-list'
-  if (needRelated && !Related) {
-    throw new Error(
-      `[Pilotiq] RelationManager ${M.name} on ${R.name} could not resolve its related Resource. ` +
-      `Set static relatedResource on the manager, or ensure the parent's model declares relations[${JSON.stringify(M.getRelationship())}].`,
-    )
-  }
-
-  switch (scope.kind) {
-    case 'relation-list':
-      return buildRelationListData(pilotiq, R, M, Related, parentRecord, scope, req, user, mode)
-    case 'relation-create':
-      return buildRelationCreateData(pilotiq, R, M, Related!, parentRecord, scope, req, user, mode)
-    case 'relation-view':
-      return buildRelationViewData(pilotiq, R, M, Related!, parentRecord, scope, req, user, mode)
-    case 'relation-edit':
-      return buildRelationEditData(pilotiq, R, M, Related!, parentRecord, scope, req, user, mode)
-  }
-}
-
-async function buildRelationListData(
-  pilotiq: Pilotiq,
-  R: ResourceClass,
-  M: typeof RelationManager,
-  Related: ResourceClass | undefined,
-  parentRecord: unknown,
-  scope: Extract<RelationManagerScope, { kind: 'relation-list' }>,
-  req: unknown,
-  user: unknown,
-  mode: RelationMode,
-): Promise<RelationManagerResult> {
-  if (!await safeManagerPolicy(M, 'canViewAny', Related, user, parentRecord)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-  const resourceBase = resourceBasePath(base, R)
-  const listUrl = `${resourceBase}/${scope.recordId}/${scope.relationship}`
-
-  // Build a single Table by piping a fresh Table through M.table(table, ctx).
-  // Context lets the user wire `Action.relationCreate / relationEdit /
-  // relationDelete(M, ctx)` factories inside `static table()` to template
-  // URLs without threading basePath / parentId by hand.
-  const managerCtx: RelationManagerContext = {
-    basePath:     base,
-    parentSlug:   scope.slug,
-    parentId:     scope.recordId,
-    relationship: scope.relationship,
-    parentRecord,
-    related:      Related,
-    mode,
-  }
-  const table = M.table(Table.make(), managerCtx)
-  autoWireManagerTable(table, R.model as ModelLike, parentRecord, scope.relationship)
-  injectManagerTrashedFilter(table, Related)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'table',
-    basePath: base,
-    record:   parentRecord,
-  }, user), cfg)
-
-  const elements: Element[] = [table]
-  tagActionDispatch(elements, listUrl)
-  await loadTableRecords(elements, scope.query ?? {}, listUrl, user)
-
-  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = relationListBreadcrumbs(
-    cfg, R, M, scope.recordId, deriveParentTitle(R, parentRecord),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const relationListRoute: PanelInfoRoute = { resource: R, recordId: scope.recordId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-list',
-    await resolveSchema(elements, ctx),
-    relationListRoute,
-  )
-
-  return {
-    pageType: 'relation-list',
-    panel:    await panelInfo(pilotiq, req, relationListRoute),
-    resource: { name: R.name, label: R.label, labelSingular: R.labelSingular, slug: scope.slug, icon: serializeIcon(R.icon, R.name) },
-    relation: {
-      name:          M.name,
-      label:         M.getLabel(),
-      labelSingular: M.getLabelSingular(),
-      relationship:  scope.relationship,
-      icon:          M.getIcon() ? serializeIcon(M.getIcon()!, M.name) : undefined,
-      relatedSlug:   Related?.getSlug(),
-    },
-    parent: {
-      id:    scope.recordId,
-      title: deriveParentTitle(R, parentRecord),
-    },
-    basePath: base,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-async function buildRelationCreateData(
-  pilotiq: Pilotiq,
-  R: ResourceClass,
-  M: typeof RelationManager,
-  Related: ResourceClass,
-  parentRecord: unknown,
-  scope: Extract<RelationManagerScope, { kind: 'relation-create' }>,
-  req: unknown,
-  user: unknown,
-  mode: RelationMode,
-): Promise<RelationManagerResult> {
-  if (!await safeManagerPolicy(M, 'canCreate', Related, user, parentRecord)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-  const resourceBase = resourceBasePath(base, R)
-  const createUrl = `${resourceBase}/${scope.recordId}/${scope.relationship}/create`
-
-  const managerCtx: RelationManagerContext = {
-    basePath:     base,
-    parentSlug:   scope.slug,
-    parentId:     scope.recordId,
-    relationship: scope.relationship,
-    parentRecord,
-    related:      Related,
-    mode,
-  }
-  const form = M.form(Form.make(), managerCtx)
-  if (Related.model) autoWireManagerForm(form, Related)
-
-  const elements: Element[] = [form]
-  tagFormActions(elements, createUrl)
-
-  if (scope.prefill) {
-    if (scope.prefill.values) form.withValues(scope.prefill.values)
-    if (scope.prefill.errors) form.withErrors(scope.prefill.errors)
-  }
-
-  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = relationCreateBreadcrumbs(
-    cfg, R, M, scope.recordId, deriveParentTitle(R, parentRecord),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'create',
-    basePath: base,
-    record:   parentRecord,
-  }, user), cfg)
-
-  const relationCreateRoute: PanelInfoRoute = { resource: R, recordId: scope.recordId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-create',
-    await resolveSchema(elements, ctx),
-    relationCreateRoute,
-  )
-
-  return {
-    pageType: 'relation-create',
-    panel:    await panelInfo(pilotiq, req, relationCreateRoute),
-    resource: { name: R.name, label: R.labelSingular, slug: scope.slug, icon: serializeIcon(R.icon, R.name) },
-    relation: {
-      name:          M.name,
-      label:         M.getLabel(),
-      labelSingular: M.getLabelSingular(),
-      relationship:  scope.relationship,
-      icon:          M.getIcon() ? serializeIcon(M.getIcon()!, M.name) : undefined,
-      relatedSlug:   Related.getSlug(),
-    },
-    parent: {
-      id:    scope.recordId,
-      title: deriveParentTitle(R, parentRecord),
-    },
-    mode:     'create' as const,
-    basePath: base,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-    ...(scope.prefill?.errors ? { hasErrors: true } : {}),
-  }
-}
-
-/**
- * Phase A — read-only view page for a related record at depth-2:
- * `${base}/${slug}/:id/${rel}/:childId`. Mirrors `buildRelationEditData`'s
- * IDOR + auth posture but resolves the manager's `static detail(child,
- * parent)` instead of its form. The default `detail()` returns `[]` —
- * managers opt in by overriding it; the chrome (RelationTabs strip)
- * still renders so users can sideways-nav between sibling managers.
- */
-async function buildRelationViewData(
-  pilotiq: Pilotiq,
-  R: ResourceClass,
-  M: typeof RelationManager,
-  Related: ResourceClass,
-  parentRecord: unknown,
-  scope: Extract<RelationManagerScope, { kind: 'relation-view' }>,
-  req: unknown,
-  user: unknown,
-  _mode: RelationMode,
-): Promise<RelationManagerResult> {
-  if (!Related.model) {
-    throw new Error(
-      `[Pilotiq] Cannot load child record for ${M.name}: Related Resource ${Related.name} has no static model.`,
-    )
-  }
-  const childPk = getPrimaryKey(Related.model)
-
-  const belongs = await childBelongsToParent(
-    R.model as ModelLike, parentRecord, scope.relationship, childPk, scope.childId,
-  )
-  if (!belongs) return null
-
-  const child = await findRecord(Related, scope.childId, { user }).catch(() => undefined)
-  if (!child) return null
-
-  if (!await safeManagerPolicy(M, 'canView', Related, user, parentRecord, child)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-
-  const elements: Element[] = M.detail(child, parentRecord)
-
-  // Phase B polish — when M declares nested managers, surface them on
-  // this page too. The strip lists the leaf parent's view tab plus one
-  // tab per sibling nested manager so users can jump from the Phase A
-  // view straight into a grandchild list / create / view / edit page.
-  // Active key `'__view'` because the user is currently viewing the
-  // leaf parent record itself, not any nested manager.
-  const nestedTabs = await buildNestedRelationTabs(
-    R, M, base,
-    { recordId: scope.recordId, relationship: scope.relationship },
-    scope.childId,
-    '__view',
-    user, child,
-  )
-  if (nestedTabs) elements.unshift(nestedTabs)
-
-  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = relationViewBreadcrumbs(
-    cfg, R, M, scope.recordId,
-    deriveParentTitle(R, parentRecord),
-    deriveParentTitle(Related, child, M),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'view',
-    basePath: base,
-    record:   child,
-    recordId: scope.childId,
-  }, user), cfg)
-
-  const relationViewRoute: PanelInfoRoute = { resource: R, recordId: scope.childId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-view',
-    await resolveSchema(elements, ctx),
-    relationViewRoute,
-  )
-
-  return {
-    pageType: 'relation-view',
-    panel:    await panelInfo(pilotiq, req, relationViewRoute),
-    resource: { name: R.name, label: R.labelSingular, slug: scope.slug, icon: serializeIcon(R.icon, R.name) },
-    relation: {
-      name:          M.name,
-      label:         M.getLabel(),
-      labelSingular: M.getLabelSingular(),
-      relationship:  scope.relationship,
-      icon:          M.getIcon() ? serializeIcon(M.getIcon()!, M.name) : undefined,
-      relatedSlug:   Related.getSlug(),
-    },
-    parent: {
-      id:    scope.recordId,
-      title: deriveParentTitle(R, parentRecord),
-    },
-    mode:     'view' as const,
-    childId:  scope.childId,
-    basePath: base,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-async function buildRelationEditData(
-  pilotiq: Pilotiq,
-  R: ResourceClass,
-  M: typeof RelationManager,
-  Related: ResourceClass,
-  parentRecord: unknown,
-  scope: Extract<RelationManagerScope, { kind: 'relation-edit' }>,
-  req: unknown,
-  user: unknown,
-  mode: RelationMode,
-): Promise<RelationManagerResult> {
-  if (!Related.model) {
-    throw new Error(
-      `[Pilotiq] Cannot load child record for ${M.name}: Related Resource ${Related.name} has no static model.`,
-    )
-  }
-  const childPk = getPrimaryKey(Related.model)
-
-  // IDOR check first — confirm the child actually belongs to the
-  // parent under this relationship before doing anything else. Guards
-  // against URL tampering swapping `:childId`.
-  const belongs = await childBelongsToParent(
-    R.model as ModelLike, parentRecord, scope.relationship, childPk, scope.childId,
-  )
-  if (!belongs) return null
-
-  const child = await findRecord(Related, scope.childId, { user }).catch(() => undefined)
-  if (!child) return null
-
-  if (!await safeManagerPolicy(M, 'canEdit', Related, user, parentRecord, child)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-  const resourceBase = resourceBasePath(base, R)
-  const editUrl = `${resourceBase}/${scope.recordId}/${scope.relationship}/${scope.childId}/edit`
-
-  const managerCtx: RelationManagerContext = {
-    basePath:     base,
-    parentSlug:   scope.slug,
-    parentId:     scope.recordId,
-    relationship: scope.relationship,
-    parentRecord,
-    related:      Related,
-    mode,
-  }
-  const form = M.form(Form.make(), managerCtx)
-  autoWireManagerForm(form, Related)
-
-  const elements: Element[] = [form]
-  tagFormActions(elements, editUrl)
-
-  // Prefill values: explicit prefill (re-render after 422) wins,
-  // otherwise pipe the loaded child through Form's fill pipeline.
-  if (scope.prefill?.values) {
-    form.withValues(scope.prefill.values)
-    if (scope.prefill.errors) form.withErrors(scope.prefill.errors)
-  } else if (child != null) {
-    const values = await applyFillPipeline(form, child)
-    form.withValues(values)
-  }
-
-  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = relationEditBreadcrumbs(
-    cfg, R, M, scope.recordId,
-    deriveParentTitle(R, parentRecord),
-    scope.childId,
-    deriveParentTitle(Related, child, M),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'edit',
-    basePath: base,
-    record:   child,
-    recordId: scope.childId,
-  }, user), cfg)
-
-  const relationEditRoute: PanelInfoRoute = { resource: R, recordId: scope.childId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-edit',
-    await resolveSchema(elements, ctx),
-    relationEditRoute,
-  )
-
-  return {
-    pageType: 'relation-edit',
-    panel:    await panelInfo(pilotiq, req, relationEditRoute),
-    resource: { name: R.name, label: R.labelSingular, slug: scope.slug, icon: serializeIcon(R.icon, R.name) },
-    relation: {
-      name:          M.name,
-      label:         M.getLabel(),
-      labelSingular: M.getLabelSingular(),
-      relationship:  scope.relationship,
-      icon:          M.getIcon() ? serializeIcon(M.getIcon()!, M.name) : undefined,
-      relatedSlug:   Related.getSlug(),
-    },
-    parent: {
-      id:    scope.recordId,
-      title: deriveParentTitle(R, parentRecord),
-    },
-    mode:     'edit' as const,
-    childId:  scope.childId,
-    basePath: base,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-    ...(scope.prefill?.errors ? { hasErrors: true } : {}),
-  }
-}
-
-// ─── Phase B nested-relation pipeline ────────────────────────
-
-/**
- * Phase B — narrow `scope` discriminator for nested-relation-*. Lets
- * the helpers below avoid restating the union for every parameter.
- */
-type NestedRelationScope = Extract<RelationManagerScope, { kind: `nested-relation-${string}` }>
-
-/**
- * Phase B — chain walk result. Resolved layer-by-layer in
- * `resolveRelationChain`; nested builders consume it. Failures bubble
- * up as the same `{ ok: false, status: 403 }` / `null` shape the
- * depth-1 path uses.
- */
-export interface ResolvedChain {
-  R:                ResourceClass
-  parentRecord:     unknown
-  M1:               typeof RelationManager
-  Related1:         ResourceClass
-  child1:           unknown
-  child1Mode:       RelationMode
-  M2:               typeof RelationManager
-  Related2:         ResourceClass | undefined
-  child2Mode:       RelationMode
-}
-
-/**
- * Phase B — resolve a depth-2 chain, running every auth + IDOR layer:
- *   Layer 0 — top-level Resource: cluster gate, R.canAccess.
- *   Layer 1 — parent record: R.canEdit(parent) (Phase A gate to manage relations).
- *   Layer 2 — first manager M1: relationship discovered, related resource discovered.
- *   IDOR #1 — child1 (the leaf parent) must belong to parentRecord under chain[0].relationship.
- *   Layer 3 — M1.canView(child1, parent) (Filament-style: must be allowed
- *             to view the child to drill into its sub-relations).
- *   Layer 4 — second manager M2 lookup; relation type read off Related1.model.
- *
- * The leaf manager's per-scope predicate (canViewAny / canCreate /
- * canView / canEdit) runs inside the per-scope builders below, since
- * each predicate has different arguments.
- */
-export async function resolveRelationChain(
-  pilotiq: Pilotiq,
-  scope:   NestedRelationScope,
-  user:    unknown,
-): Promise<ResolvedChain | { ok: false; status: 403 } | null> {
-  const cfg = pilotiq.getConfig()
-
-  const R = cfg.resources.find(r => r.getSlug() === scope.slug)
-  if (!R) return null
-
-  // Layer 0 — same gates as the depth-1 pipeline.
-  if (R.cluster && !await safePolicy(() => R.cluster!.canAccess(user))) return { ok: false, status: 403 }
-  if (!await safePolicy(() => R.canAccess(user))) return { ok: false, status: 403 }
-
-  if (!R.model) {
-    throw new Error(
-      `[Pilotiq] Resource "${R.name}" has nested relations but no static model. ` +
-      `Set Resource.model = … or remove the manager.`,
-    )
-  }
-
-  const [step0, step1] = scope.chain
-  const parentRecord = await findRecord(R, step0.recordId, { user }).catch(() => undefined)
-  if (!parentRecord) return null
-
-  // Layer 1 — parent record gate.
-  if (!await safePolicy(() => R.canEdit(user, parentRecord))) return { ok: false, status: 403 }
-
-  // Layer 2 — first manager M1.
-  const M1 = findManager(R, step0.relationship)
-  if (!M1) return null
-  const Related1 = findRelatedResource(M1, R, cfg)
-  if (!Related1) {
-    throw new Error(
-      `[Pilotiq] RelationManager ${M1.name} on ${R.name} could not resolve its related Resource. ` +
-      `Set static relatedResource on the manager, or ensure the parent's model declares relations[${JSON.stringify(M1.getRelationship())}].`,
-    )
-  }
-  if (!Related1.model) {
-    throw new Error(
-      `[Pilotiq] Related Resource ${Related1.name} has no static model — ` +
-      `cannot resolve nested manager chain through it.`,
-    )
-  }
-  const child1Mode: RelationMode = normalizeRelationMode(getRelationType(R.model, step0.relationship))
-
-  // IDOR #1 — confirm the leaf parent (`step1.recordId`) actually
-  // belongs to the top parent under the first relationship key.
-  const child1Pk = getPrimaryKey(Related1.model)
-  const belongs1 = await childBelongsToParent(
-    R.model as ModelLike, parentRecord, step0.relationship, child1Pk, step1.recordId,
-  )
-  if (!belongs1) return null
-
-  const child1 = await findRecord(Related1, step1.recordId, { user }).catch(() => undefined)
-  if (!child1) return null
-
-  // Layer 3 — M1.canView(child1, parent) gate. Filament-style: viewing
-  // the child is the prerequisite for entering its nested manager strip.
-  if (!await safeManagerPolicy(M1, 'canView', Related1, user, parentRecord, child1)) return { ok: false, status: 403 }
-
-  // Layer 4 — second manager M2 declared under M1.relations().
-  const M2 = M1.relations().find(N => {
-    try { return N.getRelationship() === step1.relationship } catch { return false }
-  })
-  if (!M2) return null
-  const Related2 = findRelatedResource(M2, Related1, cfg)
-  const child2Mode: RelationMode = normalizeRelationMode(getRelationType(Related1.model, step1.relationship))
-
-  return { R, parentRecord, M1, Related1, child1, child1Mode, M2, Related2, child2Mode }
-}
-
-/**
- * Phase B dispatcher — splits the four nested scopes onto their builders
- * after the shared chain walk. Mirrors the depth-1 `relationManagerData`
- * function shape.
- */
-async function nestedRelationManagerData(
-  pilotiq: Pilotiq,
-  scope:   NestedRelationScope,
-  req?:    unknown,
-): Promise<RelationManagerResult> {
-  const user = await pilotiq.resolveUser(req)
-  const resolved = await resolveRelationChain(pilotiq, scope, user)
-  if (resolved === null) return null
-  if ('ok' in resolved) return resolved
-
-  // For create / view / edit we strictly need a registered Related2 so
-  // we can load the leaf record + auto-wire the form save.
-  const needRelated2 = scope.kind !== 'nested-relation-list'
-  if (needRelated2 && !resolved.Related2) {
-    throw new Error(
-      `[Pilotiq] Nested RelationManager ${resolved.M2.name} under ${resolved.M1.name} ` +
-      `on ${resolved.R.name} could not resolve its related Resource. ` +
-      `Set static relatedResource on the manager, or ensure the parent's model declares ` +
-      `relations[${JSON.stringify(resolved.M2.getRelationship())}].`,
-    )
-  }
-
-  switch (scope.kind) {
-    case 'nested-relation-list':
-      return buildNestedRelationListData(pilotiq, scope, resolved, req, user)
-    case 'nested-relation-create':
-      return buildNestedRelationCreateData(pilotiq, scope, resolved, req, user)
-    case 'nested-relation-view':
-      return buildNestedRelationViewData(pilotiq, scope, resolved, req, user)
-    case 'nested-relation-edit':
-      return buildNestedRelationEditData(pilotiq, scope, resolved, req, user)
-  }
-}
-
-/** Phase B — build the manager context for a nested leaf manager. The
- *  parent here is `child1` (the chain's leaf parent record); the URL
- *  prefix comes from `scope.chain[0]` via `Action.relation*` factories
- *  reading `ctx.chain`. */
-function nestedManagerCtx(
-  base:     string,
-  scope:    NestedRelationScope,
-  resolved: ResolvedChain,
-): RelationManagerContext {
-  const [step0, step1] = scope.chain
-  return {
-    basePath:     base,
-    parentSlug:   resolved.R.getSlug(),
-    parentId:     step1.recordId,           // immediate parent = child1's id
-    relationship: step1.relationship,       // leaf manager's relationship
-    parentRecord: resolved.child1,          // immediate parent record = child1
-    related:      resolved.Related2,
-    mode:         resolved.child2Mode,
-    chain:        [{
-      slug:         resolved.R.getSlug(),
-      recordId:     step0.recordId,
-      relationship: step0.relationship,
-    }],
-  }
-}
-
-/** Phase B — assemble the response shape that mirrors the depth-1
- *  builders but adds a `chain` array so renderers can build breadcrumbs
- *  and back-links without re-deriving them. */
-function nestedResponseEnvelope(
-  pageType: 'nested-relation-list' | 'nested-relation-create' | 'nested-relation-view' | 'nested-relation-edit',
-  pilotiq:  Pilotiq,
-  base:     string,
-  scope:    NestedRelationScope,
-  resolved: ResolvedChain,
-  req:      unknown,
-): {
-  pageType: typeof pageType
-  resource: { name: string; label?: string | undefined; slug: string; icon?: SerializedIcon | undefined }
-  parentRelation: { name: string; relationship: string; label: string; relatedSlug?: string | undefined }
-  parentChild:    { id: string; title: string }
-  relation:       { name: string; relationship: string; label: string; labelSingular: string; icon?: SerializedIcon | undefined; relatedSlug?: string | undefined }
-  parent:         { id: string; title: string }
-  basePath: string
-  layout:   PilotiqConfig['layout']
-  notifications: ReturnType<typeof consumeFlashedNotifications>
-} {
-  const { R, M1, Related1, child1, M2, Related2 } = resolved
-  const [step0, step1] = scope.chain
-  const parentChildTitle = deriveParentTitle(Related1, child1, M1)
-
-  return {
-    pageType,
-    resource: { name: R.name, label: R.labelSingular, slug: R.getSlug(), icon: serializeIcon(R.icon, R.name) },
-    parentRelation: {
-      name:         M1.name,
-      relationship: step0.relationship,
-      label:        M1.getLabel(),
-      relatedSlug:  Related1.getSlug(),
-    },
-    parentChild: {
-      id:    step1.recordId,
-      title: parentChildTitle,
-    },
-    relation: {
-      name:          M2.name,
-      relationship:  step1.relationship,
-      label:         M2.getLabel(),
-      labelSingular: M2.getLabelSingular(),
-      icon:          M2.getIcon() ? serializeIcon(M2.getIcon()!, M2.name) : undefined,
-      relatedSlug:   Related2?.getSlug(),
-    },
-    parent: {
-      // Top-of-chain record — same shape the depth-1 builders ship as
-      // `parent` so renderers can reuse the back-to-resource link.
-      id:    step0.recordId,
-      title: deriveParentTitle(R, resolved.parentRecord),
-    },
-    basePath: base,
-    layout:   pilotiq.getConfig().layout,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-async function buildNestedRelationListData(
-  pilotiq:  Pilotiq,
-  scope:    Extract<NestedRelationScope, { kind: 'nested-relation-list' }>,
-  resolved: ResolvedChain,
-  req:      unknown,
-  user:     unknown,
-): Promise<RelationManagerResult> {
-  const { Related1, child1, M2, Related2 } = resolved
-
-  if (!await safeManagerPolicy(M2, 'canViewAny', Related2, user, child1)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-  const [step0, step1] = scope.chain
-  const resourceBase = resourceBasePath(base, resolved.R)
-  const listUrl = `${resourceBase}/${step0.recordId}/${step0.relationship}/${step1.recordId}/${step1.relationship}`
-
-  const managerCtx = nestedManagerCtx(base, scope, resolved)
-  const table = M2.table(Table.make(), managerCtx)
-  if (Related1.model) {
-    autoWireManagerTable(table, Related1.model as ModelLike, child1, step1.relationship)
-  }
-  injectManagerTrashedFilter(table, Related2)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'table',
-    basePath: base,
-    record:   child1,
-  }, user), cfg)
-
-  const elements: Element[] = [table]
-  tagActionDispatch(elements, listUrl)
-  await loadTableRecords(elements, scope.query ?? {}, listUrl, user)
-
-  const tabs = await buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship, user, resolved.child1)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = nestedRelationListBreadcrumbs(
-    cfg, resolved.R, resolved.M1, M2, scope.chain[0],
-    deriveParentTitle(resolved.R, resolved.parentRecord),
-    scope.chain[1].recordId,
-    deriveParentTitle(Related1, child1, resolved.M1),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const nestedListRoute: PanelInfoRoute = { resource: resolved.R, recordId: scope.chain[1].recordId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-list',
-    await resolveSchema(elements, ctx),
-    nestedListRoute,
-  )
-
-  return {
-    ...nestedResponseEnvelope('nested-relation-list', pilotiq, base, scope, resolved, req),
-    panel:    await panelInfo(pilotiq, req, nestedListRoute),
-    schemaData,
-  }
-}
-
-async function buildNestedRelationCreateData(
-  pilotiq:  Pilotiq,
-  scope:    Extract<NestedRelationScope, { kind: 'nested-relation-create' }>,
-  resolved: ResolvedChain,
-  req:      unknown,
-  user:     unknown,
-): Promise<RelationManagerResult> {
-  const { child1, M2, Related2 } = resolved
-
-  if (!await safeManagerPolicy(M2, 'canCreate', Related2, user, child1)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-  const [step0, step1] = scope.chain
-  const resourceBase = resourceBasePath(base, resolved.R)
-  const createUrl = `${resourceBase}/${step0.recordId}/${step0.relationship}/${step1.recordId}/${step1.relationship}/create`
-
-  const managerCtx = nestedManagerCtx(base, scope, resolved)
-  const form = M2.form(Form.make(), managerCtx)
-  if (Related2?.model) autoWireManagerForm(form, Related2)
-
-  const elements: Element[] = [form]
-  tagFormActions(elements, createUrl)
-
-  if (scope.prefill) {
-    if (scope.prefill.values) form.withValues(scope.prefill.values)
-    if (scope.prefill.errors) form.withErrors(scope.prefill.errors)
-  }
-
-  const tabs = await buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship, user, resolved.child1)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = nestedRelationCreateBreadcrumbs(
-    cfg, resolved.R, resolved.M1, M2, scope.chain[0],
-    deriveParentTitle(resolved.R, resolved.parentRecord),
-    scope.chain[1].recordId,
-    deriveParentTitle(resolved.Related1, child1, resolved.M1),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'create',
-    basePath: base,
-    record:   child1,
-  }, user), cfg)
-
-  const nestedCreateRoute: PanelInfoRoute = { resource: resolved.R, recordId: scope.chain[1].recordId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-create',
-    await resolveSchema(elements, ctx),
-    nestedCreateRoute,
-  )
-
-  return {
-    ...nestedResponseEnvelope('nested-relation-create', pilotiq, base, scope, resolved, req),
-    panel:    await panelInfo(pilotiq, req, nestedCreateRoute),
-    mode:     'create' as const,
-    schemaData,
-    ...(scope.prefill?.errors ? { hasErrors: true } : {}),
-  }
-}
-
-async function buildNestedRelationViewData(
-  pilotiq:  Pilotiq,
-  scope:    Extract<NestedRelationScope, { kind: 'nested-relation-view' }>,
-  resolved: ResolvedChain,
-  req:      unknown,
-  user:     unknown,
-): Promise<RelationManagerResult> {
-  const { Related1, child1, M2, Related2 } = resolved
-  if (!Related2?.model) {
-    throw new Error(
-      `[Pilotiq] Cannot load child record for nested manager ${M2.name}: ` +
-      `Related Resource ${Related2?.name ?? '(none)'} has no static model.`,
-    )
-  }
-  const [, step1] = scope.chain
-  const child2Pk = getPrimaryKey(Related2.model)
-
-  const belongs2 = await childBelongsToParent(
-    Related1.model as ModelLike, child1, step1.relationship, child2Pk, scope.childId,
-  )
-  if (!belongs2) return null
-
-  const child2 = await findRecord(Related2, scope.childId, { user }).catch(() => undefined)
-  if (!child2) return null
-
-  if (!await safeManagerPolicy(M2, 'canView', Related2, user, child1, child2)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-
-  const elements: Element[] = M2.detail(child2, child1)
-
-  const tabs = await buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship, user, resolved.child1)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = nestedRelationViewBreadcrumbs(
-    cfg, resolved.R, resolved.M1, M2, scope.chain[0],
-    deriveParentTitle(resolved.R, resolved.parentRecord),
-    scope.chain[1].recordId,
-    deriveParentTitle(Related1, child1, resolved.M1),
-    deriveParentTitle(Related2, child2, M2),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'view',
-    basePath: base,
-    record:   child2,
-    recordId: scope.childId,
-  }, user), cfg)
-
-  const nestedViewRoute: PanelInfoRoute = { resource: resolved.R, recordId: scope.childId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-view',
-    await resolveSchema(elements, ctx),
-    nestedViewRoute,
-  )
-
-  return {
-    ...nestedResponseEnvelope('nested-relation-view', pilotiq, base, scope, resolved, req),
-    panel:    await panelInfo(pilotiq, req, nestedViewRoute),
-    mode:     'view' as const,
-    childId:  scope.childId,
-    schemaData,
-  }
-}
-
-async function buildNestedRelationEditData(
-  pilotiq:  Pilotiq,
-  scope:    Extract<NestedRelationScope, { kind: 'nested-relation-edit' }>,
-  resolved: ResolvedChain,
-  req:      unknown,
-  user:     unknown,
-): Promise<RelationManagerResult> {
-  const { Related1, child1, M2, Related2 } = resolved
-  if (!Related2?.model) {
-    throw new Error(
-      `[Pilotiq] Cannot load child record for nested manager ${M2.name}: ` +
-      `Related Resource ${Related2?.name ?? '(none)'} has no static model.`,
-    )
-  }
-  const [step0, step1] = scope.chain
-  const child2Pk = getPrimaryKey(Related2.model)
-
-  const belongs2 = await childBelongsToParent(
-    Related1.model as ModelLike, child1, step1.relationship, child2Pk, scope.childId,
-  )
-  if (!belongs2) return null
-
-  const child2 = await findRecord(Related2, scope.childId, { user }).catch(() => undefined)
-  if (!child2) return null
-
-  if (!await safeManagerPolicy(M2, 'canEdit', Related2, user, child1, child2)) return { ok: false, status: 403 }
-
-  const cfg = pilotiq.getConfig()
-  const base = cfg.path
-  const resourceBase = resourceBasePath(base, resolved.R)
-  const editUrl = `${resourceBase}/${step0.recordId}/${step0.relationship}/${step1.recordId}/${step1.relationship}/${scope.childId}/edit`
-
-  const managerCtx = nestedManagerCtx(base, scope, resolved)
-  const form = M2.form(Form.make(), managerCtx)
-  autoWireManagerForm(form, Related2)
-
-  const elements: Element[] = [form]
-  tagFormActions(elements, editUrl)
-
-  if (scope.prefill?.values) {
-    form.withValues(scope.prefill.values)
-    if (scope.prefill.errors) form.withErrors(scope.prefill.errors)
-  } else if (child2 != null) {
-    const values = await applyFillPipeline(form, child2)
-    form.withValues(values)
-  }
-
-  const tabs = await buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship, user, resolved.child1)
-  if (tabs) elements.unshift(tabs)
-
-  const breadcrumbs = nestedRelationEditBreadcrumbs(
-    cfg, resolved.R, resolved.M1, M2, scope.chain[0],
-    deriveParentTitle(resolved.R, resolved.parentRecord),
-    scope.chain[1].recordId,
-    deriveParentTitle(Related1, child1, resolved.M1),
-    scope.childId,
-    deriveParentTitle(Related2, child2, M2),
-  )
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const ctx: SchemaContext = uploadCtx(userCtx({
-    mode:     'edit',
-    basePath: base,
-    record:   child2,
-    recordId: scope.childId,
-  }, user), cfg)
-
-  const nestedEditRoute: PanelInfoRoute = { resource: resolved.R, recordId: scope.childId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'relation-edit',
-    await resolveSchema(elements, ctx),
-    nestedEditRoute,
-  )
-
-  return {
-    ...nestedResponseEnvelope('nested-relation-edit', pilotiq, base, scope, resolved, req),
-    panel:    await panelInfo(pilotiq, req, nestedEditRoute),
-    mode:     'edit' as const,
-    childId:  scope.childId,
-    schemaData,
-    ...(scope.prefill?.errors ? { hasErrors: true } : {}),
-  }
-}
-
-/**
- * Phase B — build a `RelationTabs` strip scoped to a parent's nested
- * children (e.g. tabs for `replies / reactions` listed under a single
- * comment). The strip's "back" tab points to the depth-2 view page for
- * the leaf parent itself, then one tab per sibling nested manager.
- *
- * Only emitted when the depth-1 manager declares `M.relations()` —
- * absent that, callers skip the prepend so single-manager surfaces stay
- * clean. `activeKey` accepts the literal `'__view'` for the leaf
- * parent's view tab, or any sibling manager's relationship key.
- *
- * Per-tab `canX` gating (2026-05-11) — sibling nested-manager tabs run
- * `N.canViewAny(user, child1Record)` (with fall-through to the related
- * Resource via `safeManagerPolicy`) so the strip hides tabs the user
- * couldn't reach anyway. The back-link `__view` stays unconditional
- * since the user is already on a page scoped under `M.canViewAny` —
- * they reached this strip, they can navigate back to it.
- */
-async function buildNestedRelationTabs(
-  R:             ResourceClass,
-  M:             typeof RelationManager,
-  basePath:      string,
-  step0:         RelationChainStep,
-  child1Id:      string,
-  activeKey:     string,
-  user:          unknown,
-  child1Record:  unknown,
-): Promise<RelationTabs | undefined> {
-  const siblings = M.relations()
-  if (siblings.length === 0) return undefined
-
-  const resourceBase = resourceBasePath(basePath, R)
-  const parentBase   = `${resourceBase}/${step0.recordId}/${step0.relationship}`
-
-  // Sibling gating runs in parallel — each predicate may hit auth /
-  // db, so don't serialize them.
-  const siblingGates = siblings.map(N => {
-    const Related = (N as unknown as { relatedResource?: ResourceClass }).relatedResource
-    return safeManagerPolicyImpl(N, 'canViewAny', Related, user, child1Record)
-  })
-  const siblingVisible = await Promise.all(siblingGates)
-
-  const tabs: RelationTabMeta[] = []
-
-  // Back-link: depth-2 view page for the leaf parent record. Acts as
-  // the "View" tab in the same way `__view` does on depth-1 strips.
-  tabs.push(relationTab({
-    key:       '__view',
-    label:     M.getLabelSingular(),
-    url:       `${parentBase}/${child1Id}`,
-    active:    activeKey === '__view',
-    icon:      M.getIcon(),
-    iconOwner: M.name,
-  }))
-
-  siblings.forEach((N, i) => {
-    if (!siblingVisible[i]) return
-    let nestedRel = ''
-    try { nestedRel = N.getRelationship() } catch { return }
-    const icon = N.getIcon()
-    tabs.push(relationTab({
-      key:    nestedRel,
-      label:  N.getLabel(),
-      url:    `${parentBase}/${child1Id}/${nestedRel}`,
-      active: activeKey === nestedRel,
-      ...(icon !== undefined ? { icon, iconOwner: N.name } : {}),
-    }))
-  })
-
-  // After gating, only the back-link may remain — one tab isn't a
-  // useful sub-nav. Drop the strip in that case (consistent with
-  // depth-1's empty-tabs branch).
-  if (tabs.length <= 1) return undefined
-
-  return RelationTabs.make(tabs)
-}
-
-/**
- * Plan #11 — build the `RelationTabs` strip for a parent record. The
- * strip surfaces the per-record sub-navigation: View, Edit, plus one
- * tab per `R.relations()` manager. `activeKey` selects which tab the
- * renderer highlights — `'__view'` / `'__edit'` for the parent tabs,
- * the manager's relationship key for a manager tab.
- *
- * Sub-nav follow-up (2026-05-03 cont'd) — emit BOTH `__view` and
- * `__edit` as sibling tabs (record sub-navigation) instead of one
- * parent tab whose label depends on mode. Tabs are dropped when the
- * corresponding page role isn't registered (a Resource overriding
- * `pages()` to omit `view` or `edit` shouldn't surface a tab that
- * 404s).
- *
- * Per-tab `canX` gating (2026-05-11) — the strip now also evaluates
- * the matching predicate for each tab and drops the entry when the
- * user can't reach it. Routes still enforce; this is presentation
- * polish so the chrome doesn't promise a link that 403s on click.
- *
- *   - `__view`  → `R.canView(user, parentRecord)` (skip gating when
- *                 `parentRecord` is undefined — record load failed,
- *                 so the route's own load+gate will surface a 404/403
- *                 rather than the strip hiding silently).
- *   - `__edit`  → `R.canEdit(user, parentRecord)` (same posture).
- *   - manager  → `safeManagerPolicy(M, 'canViewAny', Related, user,
- *                 parentRecord)` (falls through to Related's
- *                 `canViewAny` when the manager hasn't overridden).
- *
- * Returns `undefined` when the resource has no relation managers — the
- * caller can then skip the prepend entirely so resources without
- * relations stay shape-compatible with their existing schemaData.
- * (View+Edit sub-nav alone isn't worth a tab strip; users navigate
- * those via headerActions or the back link.)
- */
-async function buildRelationTabs(
-  R:            ResourceClass,
-  recordId:     string,
-  basePath:     string,
-  activeKey:    string,
-  user:         unknown,
-  parentRecord: unknown,
-): Promise<RelationTabs | undefined> {
-  const managers       = R.relations()
-  const recordPageMap  = R.getRecordPages()
-  const recordPageSlugs = Object.keys(recordPageMap)
-  // No managers AND no record sub-pages → no strip. View+Edit alone
-  // isn't worth a tab strip; users navigate those via headerActions or
-  // the back link. (When either is non-empty, the strip is worth
-  // mounting even if all the dynamic tabs end up gated away — the
-  // post-gate emptiness check below catches that.)
-  if (managers.length === 0 && recordPageSlugs.length === 0) return undefined
-
-  const resourceBase = resourceBasePath(basePath, R)
-  const pages = R.resolvePages()
-
-  // Evaluate every per-tab predicate in parallel. The arrays line up
-  // 1:1 with `pages.view` / `pages.edit` / `recordPageSlugs` /
-  // `managers` below — we resolve all gates first so the tab-build
-  // loop stays straight-line.
-  // Record-aware predicates short-circuit to `true` when no parent
-  // record was loaded (presentation should never hide more aggressively
-  // than the route can enforce; a missing record means the route will
-  // 404/403 on click and the strip stays consistent with that).
-  const canViewPromise = pages.view && parentRecord !== undefined && parentRecord !== null
-    ? safeBool(() => R.canView(user, parentRecord))
-    : Promise.resolve(true)
-  const canEditPromise = pages.edit && parentRecord !== undefined && parentRecord !== null
-    ? safeBool(() => R.canEdit(user, parentRecord))
-    : Promise.resolve(true)
-  const recordPageGates = recordPageSlugs.map(subSlug => {
-    // Record sub-page gates run against the parent record verbatim —
-    // missing record still calls the predicate so a sub-page that
-    // gates on global user state (no record needed) still evaluates.
-    // safeBool fails closed for throwing predicates.
-    return safeBool(() => recordPageMap[subSlug]!.canAccess(user, parentRecord))
-  })
-  const managerGates    = managers.map(M => {
-    const Related = (M as unknown as { relatedResource?: ResourceClass }).relatedResource
-    return safeManagerPolicyImpl(M, 'canViewAny', Related, user, parentRecord)
-  })
-  const gateResults = await Promise.all([
-    canViewPromise, canEditPromise,
-    ...recordPageGates,
-    ...managerGates,
-  ])
-  const canView         = gateResults[0] as boolean
-  const canEdit         = gateResults[1] as boolean
-  const recordPageVisible = gateResults.slice(2, 2 + recordPageSlugs.length) as boolean[]
-  const managerVisible    = gateResults.slice(2 + recordPageSlugs.length)    as boolean[]
-
-  const tabs: RelationTabMeta[] = []
-
-  if (pages.view && canView) {
-    tabs.push(relationTab({
-      key:       '__view',
-      label:     'View',
-      url:       `${resourceBase}/${recordId}`,
-      active:    activeKey === '__view',
-      icon:      R.icon as IconValue | undefined,
-      iconOwner: R.name,
-    }))
-  }
-
-  if (pages.edit && canEdit) {
-    tabs.push(relationTab({
-      key:       '__edit',
-      label:     'Edit',
-      url:       `${resourceBase}/${recordId}/edit`,
-      active:    activeKey === '__edit',
-      // Re-use the resource icon so when ViewPage is pruned, Edit
-      // still carries the visual identity. When both are present, the
-      // icon repeats — acceptable; the labels disambiguate.
-      icon:      R.icon as IconValue | undefined,
-      iconOwner: R.name,
-    }))
-  }
-
-  // Record sub-page tabs — between Edit and the managers, in declaration
-  // order. Tab label inherits from the sub-page's class (`getLabel()`);
-  // icon picks up the sub-page's static `icon` when set. Slug doubles as
-  // the URL segment AND the `activeKey` discriminator the data builder
-  // passes when rendering the sub-page.
-  recordPageSlugs.forEach((subSlug, i) => {
-    if (!recordPageVisible[i]) return
-    const SubPage = recordPageMap[subSlug]!
-    tabs.push(relationTab({
-      key:       subSlug,
-      label:     SubPage.getLabel(),
-      url:       `${resourceBase}/${recordId}/${subSlug}`,
-      active:    activeKey === subSlug,
-      ...(SubPage.icon !== undefined
-        ? { icon: SubPage.icon, iconOwner: SubPage.name }
-        : {}),
-    }))
-  })
-
-  managers.forEach((M, i) => {
-    if (!managerVisible[i]) return
-    let rel = ''
-    try { rel = M.getRelationship() } catch { return }
-    const icon = M.getIcon()
-    tabs.push(relationTab({
-      key:    rel,
-      label:  M.getLabel(),
-      url:    `${resourceBase}/${recordId}/${rel}`,
-      active: activeKey === rel,
-      ...(icon !== undefined ? { icon, iconOwner: M.name } : {}),
-    }))
-  })
-
-  // After gating, the strip may collapse to zero entries. Mirror the
-  // "no managers + no sub-pages" branch above — no strip is friendlier
-  // than a one-tab strip with just the active page.
-  if (tabs.length === 0) return undefined
-
-  return RelationTabs.make(tabs)
-}
-
-/**
- * Tiny shim over `try { Boolean(await fn()) } catch { false }` so the
- * relation-tabs builder stays straight-line — mirrors `checkPolicy`
- * in `routes.ts` but kept local to avoid cross-module imports.
- */
-async function safeBool(fn: () => boolean | Promise<boolean>): Promise<boolean> {
-  try { return Boolean(await fn()) } catch { return false }
-}
-
-/** Pull a human-readable title off a parent record for breadcrumb /
- *  page-title use. Falls back through `recordTitleAttribute` →
- *  `name` → `title` → primary key value → 'Record'. */
-function deriveParentTitle(
-  R:       ResourceClass,
-  record:  unknown,
-  manager?: typeof RelationManager,
-): string {
-  const r = record as Record<string, unknown>
-  // Manager-scoped child rows prefer the manager's `recordTitleAttribute`
-  // when set — the manager owns its presentation surface, and the related
-  // Resource may not opt into the same column (e.g. nested-only Resources
-  // that exist purely to back a manager).
-  const managerAttr = manager?.recordTitleAttribute
-  if (managerAttr && r[managerAttr] != null) return String(r[managerAttr])
-  const attr = R.recordTitleAttribute
-  if (attr && r[attr] != null) return String(r[attr])
-  if (r['name']  != null) return String(r['name'])
-  if (r['title'] != null) return String(r['title'])
-  if (R.model) {
-    const pk = getPrimaryKey(R.model)
-    if (r[pk] != null) return String(r[pk])
-  }
-  return 'Record'
-}
-
-// ─── Phase C breadcrumb builders ─────────────────────────────
-//
-// Server-resolved chain rendered above any other top-of-page chrome
-// (e.g. RelationTabs). The trailing item is always the current page,
-// emitted without a `url` so the renderer can paint it as plain text
-// + `aria-current="page"`. All earlier items link to their canonical
-// URL — clusters route through `clusterBasePath`, resources through
-// `resourceBasePath`, etc., so a clustered resource resolves to
-// `Home / Cluster / Resource / …` instead of skipping the cluster
-// rung.
-
-function homeBreadcrumb(cfg: PilotiqConfig): BreadcrumbItem {
-  return {
-    label: cfg.branding?.title ?? cfg.name ?? 'Home',
-    url:   cfg.path,
-  }
-}
-
-function clusterBreadcrumb(cfg: PilotiqConfig, child: { cluster?: ClusterClass }): BreadcrumbItem | undefined {
-  if (!child.cluster) return undefined
-  return {
-    label: child.cluster.label,
-    url:   clusterBasePath(cfg.path, child.cluster),
-  }
-}
-
-function buildBreadcrumbs(items: BreadcrumbItem[]): Breadcrumbs | undefined {
-  // A single "Home" rung carries no information beyond the dashboard
-  // link the layout already exposes — drop it. Every other length is
-  // worth rendering.
-  if (items.length < 2) return undefined
-  return Breadcrumbs.make(items)
-}
-
-function resourceListBreadcrumbs(cfg: PilotiqConfig, R: ResourceClass): Breadcrumbs | undefined {
-  const items: BreadcrumbItem[] = [homeBreadcrumb(cfg)]
-  const cluster = clusterBreadcrumb(cfg, R)
-  if (cluster) items.push(cluster)
-  items.push({ label: R.getBreadcrumb() })
-  return buildBreadcrumbs(items)
-}
-
-function resourceCreateBreadcrumbs(cfg: PilotiqConfig, R: ResourceClass): Breadcrumbs | undefined {
-  const items: BreadcrumbItem[] = [homeBreadcrumb(cfg)]
-  const cluster = clusterBreadcrumb(cfg, R)
-  if (cluster) items.push(cluster)
-  items.push({ label: R.getBreadcrumb(), url: resourceBasePath(cfg.path, R) })
-  items.push({ label: 'Create' })
-  return buildBreadcrumbs(items)
-}
-
-function resourceViewBreadcrumbs(cfg: PilotiqConfig, R: ResourceClass, recordTitle: string): Breadcrumbs | undefined {
-  const items: BreadcrumbItem[] = [homeBreadcrumb(cfg)]
-  const cluster = clusterBreadcrumb(cfg, R)
-  if (cluster) items.push(cluster)
-  items.push({ label: R.getBreadcrumb(), url: resourceBasePath(cfg.path, R) })
-  items.push({ label: recordTitle })
-  return buildBreadcrumbs(items)
-}
-
-function resourceEditBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  recordId:    string,
-  recordTitle: string,
-): Breadcrumbs | undefined {
-  const items: BreadcrumbItem[] = [homeBreadcrumb(cfg)]
-  const cluster = clusterBreadcrumb(cfg, R)
-  if (cluster) items.push(cluster)
-  const resourceBase = resourceBasePath(cfg.path, R)
-  items.push({ label: R.getBreadcrumb(), url: resourceBase })
-  // Link the record title to the View page when registered — falls
-  // back to plain text so users who pruned ViewPage don't hit a 404.
-  const hasView = R.resolvePages().view !== undefined
-  items.push(hasView
-    ? { label: recordTitle, url: `${resourceBase}/${recordId}` }
-    : { label: recordTitle })
-  items.push({ label: 'Edit' })
-  return buildBreadcrumbs(items)
-}
-
-function globalBreadcrumbs(cfg: PilotiqConfig, G: GlobalClass): Breadcrumbs | undefined {
-  // Globals don't have a list page — `Home > <Global Label>` is the
-  // shortest meaningful chain. Edit and View collapse to the same
-  // breadcrumb (both render the singleton).
-  const items: BreadcrumbItem[] = [homeBreadcrumb(cfg)]
-  const cluster = clusterBreadcrumb(cfg, G)
-  if (cluster) items.push(cluster)
-  items.push({ label: G.label })
-  return buildBreadcrumbs(items)
-}
-
-function customPageBreadcrumbs(cfg: PilotiqConfig, P: typeof Page): Breadcrumbs | undefined {
-  const items: BreadcrumbItem[] = [homeBreadcrumb(cfg)]
-  const cluster = clusterBreadcrumb(cfg, P)
-  if (cluster) items.push(cluster)
-  items.push({ label: P.getLabel() })
-  return buildBreadcrumbs(items)
-}
-
-/** Common "Home / cluster? / Resource / parent record" prefix used by
- *  every relation-* / nested-relation-* breadcrumb. The parent record
- *  links to its View page when registered; the resource list is the
- *  fallback so users still have a back-link out of the relation chain. */
-function relationBreadcrumbPrefix(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  parentId:    string,
-  parentTitle: string,
-): BreadcrumbItem[] {
-  const items: BreadcrumbItem[] = [homeBreadcrumb(cfg)]
-  const cluster = clusterBreadcrumb(cfg, R)
-  if (cluster) items.push(cluster)
-  const resourceBase = resourceBasePath(cfg.path, R)
-  items.push({ label: R.getBreadcrumb(), url: resourceBase })
-  const hasView = R.resolvePages().view !== undefined
-  items.push(hasView
-    ? { label: parentTitle, url: `${resourceBase}/${parentId}` }
-    : { label: parentTitle })
-  return items
-}
 
-function relationListBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M:   typeof RelationManager,
-  parentId:    string,
-  parentTitle: string,
-): Breadcrumbs | undefined {
-  const items = relationBreadcrumbPrefix(cfg, R, parentId, parentTitle)
-  items.push({ label: M.getLabel() })
-  return buildBreadcrumbs(items)
-}
-
-function relationCreateBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M:   typeof RelationManager,
-  parentId:    string,
-  parentTitle: string,
-): Breadcrumbs | undefined {
-  const items = relationBreadcrumbPrefix(cfg, R, parentId, parentTitle)
-  const relList = `${resourceBasePath(cfg.path, R)}/${parentId}/${M.getRelationship()}`
-  items.push({ label: M.getLabel(), url: relList })
-  items.push({ label: 'Create' })
-  return buildBreadcrumbs(items)
-}
-
-function relationViewBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M:   typeof RelationManager,
-  parentId:    string,
-  parentTitle: string,
-  childTitle:  string,
-): Breadcrumbs | undefined {
-  const items = relationBreadcrumbPrefix(cfg, R, parentId, parentTitle)
-  const relList = `${resourceBasePath(cfg.path, R)}/${parentId}/${M.getRelationship()}`
-  items.push({ label: M.getLabel(), url: relList })
-  items.push({ label: childTitle })
-  return buildBreadcrumbs(items)
-}
-
-function relationEditBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M:   typeof RelationManager,
-  parentId:    string,
-  parentTitle: string,
-  childId:     string,
-  childTitle:  string,
-): Breadcrumbs | undefined {
-  const items = relationBreadcrumbPrefix(cfg, R, parentId, parentTitle)
-  const relBase = `${resourceBasePath(cfg.path, R)}/${parentId}/${M.getRelationship()}`
-  items.push({ label: M.getLabel(), url: relBase })
-  // Phase A always mounts the relation-view page per (R, M), so the
-  // child title can always link back to it.
-  items.push({ label: childTitle, url: `${relBase}/${childId}` })
-  items.push({ label: 'Edit' })
-  return buildBreadcrumbs(items)
-}
-
-/** Phase B — depth-2 prefix shared by every nested-relation-* role.
- *  Returns "Home / cluster? / Resource / parent / M1 / child1". */
-function nestedRelationBreadcrumbPrefix(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M1:  typeof RelationManager,
-  step0:       RelationChainStep,
-  parentTitle: string,
-  child1Id:    string,
-  child1Title: string,
-): BreadcrumbItem[] {
-  const items = relationBreadcrumbPrefix(cfg, R, step0.recordId, parentTitle)
-  const rel1Base = `${resourceBasePath(cfg.path, R)}/${step0.recordId}/${step0.relationship}`
-  items.push({ label: M1.getLabel(), url: rel1Base })
-  // Phase A relation-view always mounted, so child1 always links.
-  items.push({ label: child1Title, url: `${rel1Base}/${child1Id}` })
-  return items
-}
-
-function nestedRelationListBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M1:  typeof RelationManager,
-  M2:  typeof RelationManager,
-  step0:       RelationChainStep,
-  parentTitle: string,
-  child1Id:    string,
-  child1Title: string,
-): Breadcrumbs | undefined {
-  const items = nestedRelationBreadcrumbPrefix(cfg, R, M1, step0, parentTitle, child1Id, child1Title)
-  items.push({ label: M2.getLabel() })
-  return buildBreadcrumbs(items)
-}
-
-function nestedRelationCreateBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M1:  typeof RelationManager,
-  M2:  typeof RelationManager,
-  step0:       RelationChainStep,
-  parentTitle: string,
-  child1Id:    string,
-  child1Title: string,
-): Breadcrumbs | undefined {
-  const items = nestedRelationBreadcrumbPrefix(cfg, R, M1, step0, parentTitle, child1Id, child1Title)
-  const rel2Base = `${resourceBasePath(cfg.path, R)}/${step0.recordId}/${step0.relationship}/${child1Id}/${M2.getRelationship()}`
-  items.push({ label: M2.getLabel(), url: rel2Base })
-  items.push({ label: 'Create' })
-  return buildBreadcrumbs(items)
-}
-
-function nestedRelationViewBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M1:  typeof RelationManager,
-  M2:  typeof RelationManager,
-  step0:       RelationChainStep,
-  parentTitle: string,
-  child1Id:    string,
-  child1Title: string,
-  child2Title: string,
-): Breadcrumbs | undefined {
-  const items = nestedRelationBreadcrumbPrefix(cfg, R, M1, step0, parentTitle, child1Id, child1Title)
-  const rel2Base = `${resourceBasePath(cfg.path, R)}/${step0.recordId}/${step0.relationship}/${child1Id}/${M2.getRelationship()}`
-  items.push({ label: M2.getLabel(), url: rel2Base })
-  items.push({ label: child2Title })
-  return buildBreadcrumbs(items)
-}
-
-function nestedRelationEditBreadcrumbs(
-  cfg: PilotiqConfig,
-  R:   ResourceClass,
-  M1:  typeof RelationManager,
-  M2:  typeof RelationManager,
-  step0:       RelationChainStep,
-  parentTitle: string,
-  child1Id:    string,
-  child1Title: string,
-  child2Id:    string,
-  child2Title: string,
-): Breadcrumbs | undefined {
-  const items = nestedRelationBreadcrumbPrefix(cfg, R, M1, step0, parentTitle, child1Id, child1Title)
-  const rel2Base = `${resourceBasePath(cfg.path, R)}/${step0.recordId}/${step0.relationship}/${child1Id}/${M2.getRelationship()}`
-  items.push({ label: M2.getLabel(), url: rel2Base })
-  items.push({ label: child2Title, url: `${rel2Base}/${child2Id}` })
-  items.push({ label: 'Edit' })
-  return buildBreadcrumbs(items)
-}
-
-// ─── Plan #5 partial-resolve data builder ────────────────────
-
-export type FormStateScope =
-  | { kind: 'resource-create'; slug: string }
-  | { kind: 'resource-edit';   slug: string; recordId: string }
-  | { kind: 'global-edit';     slug: string }
-  | { kind: 'page';            pageSlug: string }
-
-export interface FormStateRequest {
-  formId:  string
-  changed: string
-  values:  Record<string, unknown>
-}
-
-export interface FormStateResult {
-  ok:    true
-  form:  Record<string, unknown>      // resolved FormMeta
-  dirty: string[]
-}
-
-export interface FormStateError {
-  ok:     false
-  status: 404 | 422
-  error:  string
-}
-
-/**
- * Plan #5 — handle a partial-resolve roundtrip from a `live()` field.
- *
- * Locates the page's schema, finds the targeted form by `formId`, runs
- * `applyStateUpdate` to apply the changed value + run
- * `afterStateUpdated`, then re-resolves the form's children with the
- * mutated values + bound `$get / $set` so dependent options /
- * conditional visibility re-evaluate. Returns the resolved FormMeta the
- * client uses to replace its rendered form.
- *
- * Returns `null` when the route prefix doesn't resolve to a real
- * resource/global/page — the route handler turns this into a 404. The
- * inner `{ status: 422 }` failure is for "form found but `changed`
- * field doesn't exist on it" — also a client-side bug.
- */
-export async function formStateData(
-  pilotiq: Pilotiq,
-  scope:   FormStateScope,
-  body:    FormStateRequest,
-  req?:    unknown,
-): Promise<FormStateResult | FormStateError | null> {
-  const cfg = pilotiq.getConfig()
-  const user = await pilotiq.resolveUser(req)
-
-  let PageClass: typeof Page | undefined
-  let mode: 'create' | 'edit'
-  let record: unknown = undefined
-  let recordId: string | undefined
-  let baseCtxExtras: Record<string, unknown> = {}
-
-  if (scope.kind === 'resource-create' || scope.kind === 'resource-edit') {
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
-    if (!R) return null
-    const pages = R.resolvePages()
-    if (scope.kind === 'resource-create') {
-      if (!pages.create) return null
-      PageClass = pages.create
-      mode = 'create'
-    } else {
-      if (!pages.edit) return null
-      PageClass = pages.edit
-      mode = 'edit'
-      recordId = scope.recordId
-      baseCtxExtras = { recordId }
-      if (R.model) {
-        try { record = await findRecord(R, scope.recordId, { user }) } catch { /* ignore */ }
-      } else if (recordId) {
-        record = { id: recordId }
-      }
-    }
-  } else if (scope.kind === 'global-edit') {
-    const G = cfg.globals.find(g => g.getSlug() === 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)
-    if (!P) return null
-    PageClass = P
-    // Custom pages don't have a record/edit-mode concept — pass mode
-    // 'edit' so resolveSchema treats fields as form inputs (not table
-    // cells / view-mode read-only).
-    mode = 'edit'
-  }
-
-  if (!PageClass) return null
-
-  const baseCtx: SchemaContext = uploadCtx(userCtx({ mode, basePath: cfg.path, ...baseCtxExtras }, user), cfg)
-  const elements = await callPageSchema(PageClass, baseCtx)
-  const form = selectFormById(findForms(elements), body.formId)
-  if (!form) return { ok: false, status: 404, error: `Form "${body.formId}" not found on page` }
-
-  const update = await applyStateUpdate(form, body.values, body.changed, {
-    ...(record  !== undefined ? { record } : {}),
-    ...(user    !== null      ? { user   } : {}),
-    request: req,
-  })
-  if (!update) {
-    return { ok: false, status: 422, error: `Field "${body.changed}" not found on form "${body.formId}"` }
-  }
-
-  // Re-resolve the form with the mutated values bound. We bind
-  // `$get / $set` against the post-update values map so further
-  // resolve-time logic (SelectField.options(fn), reactive
-  // visibility) reads current state.
-  const $get = (name: string): unknown => update.values[name]
-  // $set on the resolve pass is a no-op — only afterStateUpdated
-  // mutations survive into the response. Resolve-time `$set` would
-  // race against the client's view of the world.
-  const $set = (_name: string, _v: unknown): void => { /* intentional no-op */ }
-
-  const resolveCtx = {
-    ...baseCtx,
-    values: update.values,
-    $get,
-    $set,
-    changed: body.changed,
-    ...(record !== undefined ? { record } : {}),
-  }
-  // Snapshot values onto the form so its FormMeta carries them.
-  form.withValues(update.values)
-  const resolved = await resolveSchema([form], resolveCtx)
-  const formMeta = resolved[0]
-  if (!formMeta || formMeta.type !== 'form') {
-    return { ok: false, status: 422, error: 'Form re-resolved to non-form meta' }
-  }
-
-  return { ok: true, form: formMeta, dirty: update.dirty }
-}
-
-// ─── Plan #8 wizard step-validate data builder ────────────────
-
-export interface FormWizardRequest {
-  formId: string
-  step:   number
-  values: Record<string, unknown>
-}
-
-export interface FormWizardSuccess {
-  ok: true
-}
-
-export interface FormWizardFailure {
-  ok:     false
-  status: 404 | 422
-  error?: string
-  errors?: Record<string, string[]>
-}
-
-/**
- * Plan #8 — handle a Wizard step-validate POST. Locates the form by id,
- * walks to the Wizard descendant, validates only the fields inside step
- * `step` against `values`. Returns `{ ok: true }` on success or
- * `{ ok: false, status: 422, errors }` when fields fail validation.
- *
- * Errors are keyed by field name, same shape as the form-submit 422 path,
- * so the client (`FormStateApi.applyErrors`) can surface them in-place.
- */
-export async function formWizardData(
-  pilotiq: Pilotiq,
-  scope:   FormStateScope,
-  body:    FormWizardRequest,
-  req?:    unknown,
-): Promise<FormWizardSuccess | FormWizardFailure | null> {
-  const cfg = pilotiq.getConfig()
-  const user = await pilotiq.resolveUser(req)
-
-  let PageClass: typeof Page | undefined
-  let mode: 'create' | 'edit'
-  let record: unknown = undefined
-  let baseCtxExtras: Record<string, unknown> = {}
-
-  if (scope.kind === 'resource-create' || scope.kind === 'resource-edit') {
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
-    if (!R) return null
-    const pages = R.resolvePages()
-    if (scope.kind === 'resource-create') {
-      if (!pages.create) return null
-      PageClass = pages.create
-      mode = 'create'
-    } else {
-      if (!pages.edit) return null
-      PageClass = pages.edit
-      mode = 'edit'
-      baseCtxExtras = { recordId: scope.recordId }
-      if (R.model) {
-        try { record = await findRecord(R, scope.recordId, { user }) } catch { /* ignore */ }
-      } else {
-        record = { id: scope.recordId }
-      }
-    }
-  } else if (scope.kind === 'global-edit') {
-    const G = cfg.globals.find(g => g.getSlug() === 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)
-    if (!P) return null
-    PageClass = P
-    mode = 'edit'
-  }
-
-  if (!PageClass) return null
-
-  const baseCtx: SchemaContext = uploadCtx(userCtx({ mode, basePath: cfg.path, ...baseCtxExtras }, user), cfg)
-  const elements = await callPageSchema(PageClass, baseCtx)
-  const form = selectFormById(findForms(elements), body.formId)
-  if (!form) return { ok: false, status: 404, error: `Form "${body.formId}" not found on page` }
-
-  const formChildren = form.getChildren() ?? []
-  const step = findWizardStep(formChildren, body.step)
-  if (!step) return { ok: false, status: 404, error: `Step ${body.step} not found on form "${body.formId}"` }
-
-  // Step.beforeValidation — runs before validators. May mutate `body.values`
-  // in place (the validator reads from the same object), or throw to halt
-  // with a 422 stamped under the reserved `_step` key.
-  type StepHook = (values: Record<string, unknown>, ctx: { record?: unknown; user?: unknown }) => void | Promise<void>
-  const stepHooks = step as {
-    getBeforeValidation?: () => StepHook | undefined
-    getAfterValidation?:  () => StepHook | undefined
-  }
-  const beforeHook = stepHooks.getBeforeValidation?.call(step)
-  if (beforeHook) {
-    try { await beforeHook(body.values, { record, user }) }
-    catch (err) {
-      return { ok: false, status: 422, errors: { _step: [stepHookErrorMessage(err)] } }
-    }
-  }
-
-  const errors = await validateSchema(step.getChildren() ?? [], body.values, record)
-  if (Object.keys(errors).length > 0) {
-    return { ok: false, status: 422, errors }
-  }
-
-  // Step.afterValidation — fires only when validators pass. Same throw →
-  // 422 contract as beforeValidation.
-  const afterHook = stepHooks.getAfterValidation?.call(step)
-  if (afterHook) {
-    try { await afterHook(body.values, { record, user }) }
-    catch (err) {
-      return { ok: false, status: 422, errors: { _step: [stepHookErrorMessage(err)] } }
-    }
-  }
-
-  return { ok: true }
-}
-
-function stepHookErrorMessage(err: unknown): string {
-  if (err instanceof Error && err.message) return err.message
-  if (typeof err === 'string' && err.length > 0) return err
-  return 'Step validation failed'
-}
-
-// ─── SelectField inline-create-option data builder ───────────
-
-export interface FormCreateOptionRequest {
-  formId:    string
-  fieldName: string
-  values:    Record<string, unknown>
-}
-
-export interface FormCreateOptionSuccess {
-  ok:     true
-  option: { value: string; label: string }
-}
-
-export interface FormCreateOptionFailure {
-  ok:     false
-  status: 403 | 404 | 422 | 500
-  error?:  string
-  errors?: Record<string, string[]>
-}
-
-/** Find a `SelectField` by name inside a form's children, walking through
- *  layout containers but stopping at Repeater / Builder boundaries
- *  (parallel to `tagSelectCreateOptionUrls`'s walker). Returns the first
- *  match or `undefined`. */
-function findSelectFieldByName(elements: Element[], name: string): SelectField | undefined {
-  for (const el of elements) {
-    if (el instanceof SelectField) {
-      if (el.name === name) return el
-      continue
-    }
-    if (el instanceof RepeaterField) continue
-    if (el instanceof BuilderField)  continue
-    const children = el.getChildren()
-    if (children && children.length > 0) {
-      const found = findSelectFieldByName(children as Element[], name)
-      if (found) return found
-    }
-  }
-  return undefined
-}
-
-/**
- * Audit row 2026-05-07 cont'd⁸ — handle a `SelectField.createOptionForm()`
- * modal submit. Locates the parent form by `formId`, finds the SelectField
- * by `fieldName`, re-evaluates the `createOptionAuthorize` rule (so a
- * tampered URL can't bypass), coerces + validates the body against the
- * sub-form's fields, then calls `createOptionUsing(handler)` and returns
- * `{ option }` for the client to append + select.
- *
- * Returns `null` when the route prefix doesn't resolve to a real
- * resource/global/page (route handler turns into 404).
- */
-export async function formCreateOptionData(
-  pilotiq: Pilotiq,
-  scope:   FormStateScope,
-  body:    FormCreateOptionRequest,
-  req?:    unknown,
-): Promise<FormCreateOptionSuccess | FormCreateOptionFailure | null> {
-  const cfg = pilotiq.getConfig()
-  const user = await pilotiq.resolveUser(req)
-
-  let PageClass: typeof Page | undefined
-  let mode: 'create' | 'edit'
-  let record: unknown = undefined
-  let baseCtxExtras: Record<string, unknown> = {}
-
-  if (scope.kind === 'resource-create' || scope.kind === 'resource-edit') {
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
-    if (!R) return null
-    const pages = R.resolvePages()
-    if (scope.kind === 'resource-create') {
-      if (!pages.create) return null
-      PageClass = pages.create
-      mode = 'create'
-    } else {
-      if (!pages.edit) return null
-      PageClass = pages.edit
-      mode = 'edit'
-      baseCtxExtras = { recordId: scope.recordId }
-      if (R.model) {
-        try { record = await findRecord(R, scope.recordId, { user }) } catch { /* ignore */ }
-      } else {
-        record = { id: scope.recordId }
-      }
-    }
-  } else if (scope.kind === 'global-edit') {
-    const G = cfg.globals.find(g => g.getSlug() === 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)
-    if (!P) return null
-    PageClass = P
-    mode = 'edit'
-  }
-
-  if (!PageClass) return null
-
-  const baseCtx: SchemaContext = uploadCtx(userCtx({ mode, basePath: cfg.path, ...baseCtxExtras }, user), cfg)
-  const elements = await callPageSchema(PageClass, baseCtx)
-  const form = selectFormById(findForms(elements), body.formId)
-  if (!form) return { ok: false, status: 404, error: `Form "${body.formId}" not found on page` }
-
-  const field = findSelectFieldByName(form.getChildren() as Element[] ?? [], body.fieldName)
-  if (!field) return { ok: false, status: 404, error: `SelectField "${body.fieldName}" not found on form "${body.formId}"` }
-  if (!field.hasCreateOption()) return { ok: false, status: 404, error: `SelectField "${body.fieldName}" does not configure createOptionForm()` }
-
-  const createForm = field.getCreateOptionForm()!
-  const handler    = field.getCreateOptionHandler()
-  if (!handler) {
-    return { ok: false, status: 500, error: `SelectField "${body.fieldName}" has createOptionForm() but no createOptionUsing() handler` }
-  }
-
-  // Re-evaluate authorize. Build the same ActionVisibilityContext shape
-  // the field's `toMeta` did — keeps server / meta-build paths consistent.
-  const authorize = field.getCreateOptionAuthorize()
-  if (authorize !== undefined) {
-    const authVisible = await (async () => {
-      if (typeof authorize !== 'function') return authorize
-      const visCtx: import('./actions/Action.js').ActionVisibilityContext = {}
-      if (record !== undefined) visCtx.record = record
-      if (user   !== null     ) visCtx.user   = user
-      try { return await authorize(visCtx) } catch { return false }
-    })()
-    if (!authVisible) return { ok: false, status: 403, error: 'createOptionAuthorize denied' }
-  }
-
-  // Coerce + validate body against the sub-form's fields. The createOption
-  // sub-schema is detached from the parent form so we run it against its
-  // own children only — coerceFormValues mutates `out` to normalize toggle
-  // / number / date / etc. shapes (same shape parent forms use).
-  const coerced = coerceFormValues(createForm, { ...body.values })
-  const errors  = await validateSchema(createForm, coerced, undefined)
-  if (Object.keys(errors).length > 0) {
-    return { ok: false, status: 422, errors }
-  }
-
-  const ctx: RenderContext = {
-    ...baseCtx,
-    values: coerced,
-    ...(record !== undefined ? { record } : {}),
-  }
-  let option: { value: string; label: string }
-  try {
-    option = await handler(coerced, ctx)
-  } catch (e) {
-    return { ok: false, status: 500, error: e instanceof Error ? e.message : String(e) }
-  }
-
-  if (!option || typeof option.value !== 'string' || typeof option.label !== 'string') {
-    return { ok: false, status: 500, error: `createOptionUsing must return { value: string, label: string }` }
-  }
-
-  return { ok: true, option }
-}
-
-// ─── Async-mention resolve data builder ──────────────────────
-
-export interface MentionResolveRequest {
-  formId:  string
-  field:   string
-  trigger: string
-  query:   string
-}
-
-/** Wire-side shape for a single resolved item — mirrors `MentionItem` from
- *  `@pilotiq/tiptap`. Pilotiq core doesn't import that package, so the
- *  duck-typed shape lives here. */
-export interface MentionResolveItem {
-  id:     string
-  label:  string
-  group?: string
-}
-
-export interface MentionResolveSuccess {
-  ok:    true
-  items: MentionResolveItem[]
-}
-
-export interface MentionResolveError {
-  ok:     false
-  status: 404 | 422
-  error:  string
-}
-
-interface AsyncMentionResolverField {
-  resolveMention(
-    trigger: string,
-    query:   string,
-    ctx:     { user?: unknown; record?: unknown; request?: unknown },
-  ): Promise<MentionResolveItem[] | null>
-}
-
-function isMentionResolverField(el: Element): el is Element & AsyncMentionResolverField {
-  if (el.getType() !== 'richtext') return false
-  const candidate = el as unknown as Partial<AsyncMentionResolverField>
-  return typeof candidate.resolveMention === 'function'
-}
-
-/**
- * Walk a form's tree looking for the named field. Descends into Repeater /
- * Builder rows when the requested name carries the row-prefix shape:
- *
- *   - Repeater rows: `<repeaterName>.<index>.<innerPath>` — looks up
- *     `<innerPath>` against the Repeater's template schema. Field config
- *     (providers, async resolver) is shared across rows, so any row index
- *     resolves to the same template field.
- *   - Builder rows: `<builderName>.<index>.data.<innerPath>` — looks up
- *     `<innerPath>` against every block's schema; first match wins. Block
- *     schemas often share leaf names — if two blocks define a RichTextField
- *     with the same name and different async-mention providers, only the
- *     first block in declaration order is reachable here. Authors needing
- *     per-block resolution should give the leaves distinct names.
- *
- * Mirrors the boundary-stopping posture of `findFieldByName` inside
- * `dispatchForm.ts` for top-level matches — only the dotted-prefix branch
- * crosses into row schemas.
- */
-function findRichTextFieldByName(
-  elements: ReadonlyArray<Element>,
-  name:     string,
-): (Element & AsyncMentionResolverField) | undefined {
-  for (const el of elements) {
-    if (isMentionResolverField(el) && (el as unknown as { name: string }).name === name) {
-      return el
-    }
-    if (isRepeaterField(el)) {
-      const inner = stripRepeaterRowPrefix(name, (el as RepeaterField).name)
-      if (inner !== undefined) {
-        const hit = findRichTextFieldByName((el as RepeaterField).getInnerSchema(), inner)
-        if (hit) return hit
-      }
-      continue
-    }
-    if (isBuilderField(el)) {
-      const inner = stripBuilderRowPrefix(name, (el as BuilderField).name)
-      if (inner !== undefined) {
-        for (const block of (el as BuilderField).getBlocks()) {
-          const hit = findRichTextFieldByName(block.getSchema(), inner)
-          if (hit) return hit
-        }
-      }
-      continue
-    }
-    const children = el.getChildren()
-    if (children && children.length > 0) {
-      const hit = findRichTextFieldByName(children, name)
-      if (hit) return hit
-    }
-  }
-  return undefined
-}
-
-/**
- * `items.0.body` → `body`. Returns `undefined` when the path doesn't match
- * the `<repeaterName>.<digits>.<rest>` shape so the walker keeps searching
- * other branches instead of misinterpreting an unrelated dotted name.
- */
-function stripRepeaterRowPrefix(path: string, repeaterName: string): string | undefined {
-  const parts = path.split('.')
-  if (parts.length < 3) return undefined
-  if (parts[0] !== repeaterName) return undefined
-  if (!/^\d+$/.test(parts[1] ?? '')) return undefined
-  return parts.slice(2).join('.')
-}
-
-/**
- * `blocks.0.data.heading` → `heading`. The literal `data` segment matches
- * Builder's wire shape (`{ __id, type, data: {…} }`) and distinguishes a
- * Builder leaf from a Repeater leaf at the same depth.
- */
-function stripBuilderRowPrefix(path: string, builderName: string): string | undefined {
-  const parts = path.split('.')
-  if (parts.length < 4) return undefined
-  if (parts[0] !== builderName) return undefined
-  if (!/^\d+$/.test(parts[1] ?? '')) return undefined
-  if (parts[2] !== 'data') return undefined
-  return parts.slice(3).join('.')
-}
-
-/**
- * Resolve one async-mention round-trip. Locates the page's schema, finds
- * the form by `formId` and the RichTextField by `field`, calls its
- * `resolveMention(trigger, query, ctx)`. Returns `{ ok, items }`, a 404
- * when the form / field / trigger isn't present, or `null` for a missing
- * page (the route handler turns `null` into a 404 too).
- *
- * The dispatcher is duck-typed against the contract in `@pilotiq/tiptap`'s
- * `RichTextField` — pilotiq core never imports the adapter. Any future
- * field-type that ships an async-resolve trigger can implement the same
- * shape and pick up routing for free.
- */
-export async function mentionResolveData(
-  pilotiq: Pilotiq,
-  scope:   FormStateScope,
-  body:    MentionResolveRequest,
-  req?:    unknown,
-): Promise<MentionResolveSuccess | MentionResolveError | null> {
-  const cfg = pilotiq.getConfig()
-  const user = await pilotiq.resolveUser(req)
-
-  let PageClass: typeof Page | undefined
-  let mode: 'create' | 'edit'
-  let record: unknown = undefined
-  let baseCtxExtras: Record<string, unknown> = {}
-
-  if (scope.kind === 'resource-create' || scope.kind === 'resource-edit') {
-    const R = cfg.resources.find(r => r.getSlug() === scope.slug)
-    if (!R) return null
-    const pages = R.resolvePages()
-    if (scope.kind === 'resource-create') {
-      if (!pages.create) return null
-      PageClass = pages.create
-      mode = 'create'
-    } else {
-      if (!pages.edit) return null
-      PageClass = pages.edit
-      mode = 'edit'
-      baseCtxExtras = { recordId: scope.recordId }
-      if (R.model) {
-        try { record = await findRecord(R, scope.recordId, { user }) } catch { /* ignore */ }
-      } else {
-        record = { id: scope.recordId }
-      }
-    }
-  } else if (scope.kind === 'global-edit') {
-    const G = cfg.globals.find(g => g.getSlug() === 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)
-    if (!P) return null
-    PageClass = P
-    mode = 'edit'
-  }
-
-  if (!PageClass) return null
-
-  const baseCtx: SchemaContext = uploadCtx(userCtx({ mode, basePath: cfg.path, ...baseCtxExtras }, user), cfg)
-  const elements = await callPageSchema(PageClass, baseCtx)
-  const form = selectFormById(findForms(elements), body.formId)
-  if (!form) return { ok: false, status: 404, error: `Form "${body.formId}" not found on page` }
-
-  const field = findRichTextFieldByName(form.getChildren() ?? [], body.field)
-  if (!field) {
-    return { ok: false, status: 404, error: `Rich-text field "${body.field}" not found on form "${body.formId}"` }
-  }
-
-  let items: MentionResolveItem[] | null
-  try {
-    items = await field.resolveMention(body.trigger, body.query, {
-      ...(record !== undefined ? { record } : {}),
-      ...(user   !== null      ? { user   } : {}),
-      request: req,
-    })
-  } catch (err) {
-    return {
-      ok:     false,
-      status: 422,
-      error:  err instanceof Error ? err.message : 'Mention resolver threw',
-    }
-  }
-
-  if (items === null) {
-    return { ok: false, status: 404, error: `No mention provider for trigger "${body.trigger}" on field "${body.field}"` }
-  }
-
-  return { ok: true, items }
-}
-
-export async function resourceViewData(
-  pilotiq:  Pilotiq,
-  slug:     string,
-  recordId: string,
-  req?:     unknown,
-): Promise<Record<string, unknown> | null> {
-  const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
-  if (!R) return null
-  const pages = R.resolvePages()
-  if (!pages.view) return null
-  const PageClass = pages.view
-
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'view', recordId, basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-  // For the view page we want the record threaded into resolveSchema so
-  // factory-attached visibility predicates see it. Resource.detail()
-  // already runs against the loaded record in user code; here we mirror
-  // that into ctx.record for the action eval pass.
-  let record: unknown = undefined
-  if (R.model) {
-    try { record = await findRecord(R, recordId, { user }) } catch { /* ignore */ }
-  }
-
-  // Plan #11 — prepend the relation tabs strip with the "Details" tab
-  // active when the resource has relation managers configured.
-  const relationTabsEl = await buildRelationTabs(R, recordId, cfg.path, '__view', user, record)
-  if (relationTabsEl) elements.unshift(relationTabsEl)
-
-  const recordTitle = record !== undefined && record !== null
-    ? deriveParentTitle(R, record)
-    : recordId
-  const breadcrumbs = resourceViewBreadcrumbs(cfg, R, recordTitle)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const viewRoute: PanelInfoRoute = { resource: R, page: PageClass, recordId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'view',
-    await resolveSchema(
-      elements,
-      record !== undefined ? { ...ctx, record } : ctx,
-    ),
-    viewRoute,
-  )
-
-  return {
-    panel:    await panelInfo(pilotiq, req, viewRoute),
-    page:     PageClass.toMeta(),
-    resource: { name: R.name, label: R.labelSingular, slug, icon: serializeIcon(R.icon, R.name) },
-    mode:     'view' as const,
-    recordId,
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-/**
- * Custom record sub-page data builder. Mounted at
- * `${resourceBase}/${slug}/:id/${subPageSlug}` for each entry in
- * `Resource.pages().record`. Mirrors `resourceViewData`'s shape: load
- * the record, run R.canAccess + R.canView (parent-resource gates),
- * then SubPage.canAccess(user, record) (sub-page-specific gate),
- * then render the sub-page's schema with `ctx.record` set. Tab strip
- * carries the sub-page slug as the active key so the matching record
- * sub-page tab highlights.
- *
- * Returns:
- *   - `null` — resource / sub-page slug not found (404 upstream).
- *   - `{ ok: false, status: 403 }` — any gate fails or throws.
- *   - resolved page data — on success.
- */
-export async function resourceRecordPageData(
-  pilotiq:       Pilotiq,
-  slug:          string,
-  recordId:      string,
-  subPageSlug:   string,
-  req?:          unknown,
-): Promise<Record<string, unknown> | null | { ok: false; status: 403 }> {
-  const cfg = pilotiq.getConfig()
-  const R = cfg.resources.find(r => r.getSlug() === slug)
-  if (!R) return null
-  const recordPages = R.getRecordPages()
-  const PageClass = recordPages[subPageSlug]
-  if (!PageClass) return null
-
-  const user = await pilotiq.resolveUser(req)
-
-  // Load the parent record before gating so canView / SubPage.canAccess
-  // can branch on record state. Sub-pages without a Resource.model
-  // still get gated against an `undefined` record — the same posture as
-  // resourceViewData when no model is bound.
-  let record: unknown = undefined
-  if (R.model) {
-    try { record = await findRecord(R, recordId, { user }) } catch { /* ignore */ }
-  }
-  if (record === undefined || record === null) {
-    // Distinguish "model bound but record missing" (route should 404)
-    // from "no model bound" (treat record as `{ id: recordId }` so the
-    // page can still render — same convention as the edit page).
-    if (R.model) return null
-    record = { id: recordId }
-  }
-
-  // Three gates: parent resource access + view, then the sub-page's own
-  // canAccess. The route would have run R.canAccess upstream, but
-  // re-running here makes resourceRecordPageData safe to call from
-  // dispatchPageData (where the SPA path skips the route prelude).
-  if (!await safeBool(() => R.canAccess(user))) return { ok: false, status: 403 }
-  if (!await safeBool(() => R.canView(user, record))) return { ok: false, status: 403 }
-  if (!await safeBool(() => PageClass.canAccess(user, record))) return { ok: false, status: 403 }
-
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'view', recordId, basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-
-  // Insert the relation-tabs strip with the sub-page slug active so the
-  // matching tab highlights. `buildRelationTabs` evaluates per-tab
-  // gating against `user + record` — record sub-page tabs are gated
-  // alongside __view/__edit/managers.
-  const relationTabsEl = await buildRelationTabs(R, recordId, cfg.path, subPageSlug, user, record)
-  if (relationTabsEl) elements.unshift(relationTabsEl)
-
-  const recordTitle = record !== undefined && record !== null
-    ? deriveParentTitle(R, record)
-    : recordId
-  const breadcrumbs = resourceViewBreadcrumbs(cfg, R, recordTitle)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const recordPageRoute: PanelInfoRoute = { resource: R, page: PageClass, recordId }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'view',
-    await resolveSchema(
-      elements,
-      record !== undefined ? { ...ctx, record } : ctx,
-    ),
-    recordPageRoute,
-  )
-
-  return {
-    pageType: 'record-page' as const,
-    panel:    await panelInfo(pilotiq, req, recordPageRoute),
-    page:     PageClass.toMeta(),
-    resource: { name: R.name, label: R.labelSingular, slug, icon: serializeIcon(R.icon, R.name) },
-    mode:     'record' as const,
-    recordId,
-    subPage:  { slug: subPageSlug, label: PageClass.getLabel() },
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-export async function globalEditData(
-  pilotiq: Pilotiq,
-  slug:    string,
-  prefill?: { values?: Record<string, unknown>; errors?: Record<string, string[]> },
-  req?:    unknown,
-): Promise<Record<string, unknown> | null> {
-  const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
-  if (!G) return null
-  const pages = G.resolvePages()
-  if (!pages.edit) return null
-  const PageClass = pages.edit
-
-  const editUrl = globalBasePath(cfg.path, G)
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'edit', basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-  tagFormActions(elements, editUrl)
-  tagFormStateUrls(elements, formId => `${editUrl}/_form/${formId}/state`)
-  tagFormWizardUrls(elements, formId => `${editUrl}/_form/${formId}/wizard`)
-  tagRichTextMentionUrls(elements, formId => `${editUrl}/_form/${formId}/mentions`)
-  tagSelectCreateOptionUrls(elements, (formId, fieldName) => `${editUrl}/_form/${formId}/create-option/${fieldName}`)
-
-  const form = findForms(elements)[0]
-  let record: unknown = undefined
-  if (form?.getLoadRecord()) {
-    try { record = await form.getLoadRecord()!('', { values: prefill?.values ?? {} }) } catch { /* ignore */ }
-    if (!prefill?.values && record != null) {
-      const values = await applyFillPipeline(form, record)
-      form.withValues(values)
-    } else if (prefill?.values) {
-      form.withValues(prefill.values)
-    }
-    if (prefill?.errors) form.withErrors(prefill.errors)
-  }
-
-  const breadcrumbs = globalBreadcrumbs(cfg, G)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const globalEditRoute: PanelInfoRoute = { global: G, page: PageClass }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'global-edit',
-    await resolveSchema(
-      elements,
-      record !== undefined ? { ...ctx, record } : ctx,
-    ),
-    globalEditRoute,
-  )
-
-  return {
-    pageType: 'global',
-    panel:    await panelInfo(pilotiq, req, globalEditRoute),
-    page:     PageClass.toMeta(),
-    global:   { name: G.name, label: G.label, labelSingular: G.labelSingular, slug, icon: serializeIcon(G.icon, G.name) },
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-    ...(prefill?.errors ? { hasErrors: true } : {}),
-  }
-}
-
-export async function globalViewData(
-  pilotiq: Pilotiq,
-  slug:    string,
-  req?:    unknown,
-): Promise<Record<string, unknown> | null> {
-  const cfg = pilotiq.getConfig()
-  const G = cfg.globals.find(g => g.getSlug() === slug)
-  if (!G) return null
-  const pages = G.resolvePages()
-  if (!pages.view) return null
-  const PageClass = pages.view
-
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({ mode: 'view', basePath: cfg.path }, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-
-  const breadcrumbs = globalBreadcrumbs(cfg, G)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const globalViewRoute: PanelInfoRoute = { global: G, page: PageClass }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'global-view',
-    await resolveSchema(elements, ctx),
-    globalViewRoute,
-  )
-
-  return {
-    panel:    await panelInfo(pilotiq, req, globalViewRoute),
-    page:     PageClass.toMeta(),
-    global:   { name: G.name, label: G.label, labelSingular: G.labelSingular, slug, icon: serializeIcon(G.icon, G.name) },
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    schemaData,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-export async function customPageData(
-  pilotiq: Pilotiq,
-  pageSlug: string,
-  req?:    unknown,
-): Promise<Record<string, unknown> | null> {
-  const cfg = pilotiq.getConfig()
-  const PageClass = cfg.pages.find(P => P.getSlug() === pageSlug)
-  if (!PageClass) return null
-
-  const pageUrl = pageBasePath(cfg.path, PageClass)
-  const user = await pilotiq.resolveUser(req)
-  const ctx: SchemaContext = uploadCtx(userCtx({}, user), cfg)
-  const elements = await callPageSchema(PageClass, ctx)
-  tagFormActions(elements, pageUrl)
-  tagFormStateUrls(elements, formId => `${pageUrl}/_form/${formId}/state`)
-  tagFormWizardUrls(elements, formId => `${pageUrl}/_form/${formId}/wizard`)
-  tagRichTextMentionUrls(elements, formId => `${pageUrl}/_form/${formId}/mentions`)
-  tagSelectCreateOptionUrls(elements, (formId, fieldName) => `${pageUrl}/_form/${formId}/create-option/${fieldName}`)
-  tagActionDispatch(elements, pageUrl)
-  // Page-scope polling URL (mirrors `${base}/${pageSlug}/_widget/:id`
-  // route registered in routes.ts).
-  tagWidgetUrls(elements, id => `${pageUrl}/_widget/${id}`)
-  const widgetData = await resolveServerDataElements(elements, ctx)
-
-  const breadcrumbs = customPageBreadcrumbs(cfg, PageClass)
-  if (breadcrumbs) elements.unshift(breadcrumbs)
-
-  const customRoute: PanelInfoRoute = { page: PageClass }
-  const schemaData = await applyRoleHooks(
-    pilotiq, user, 'page',
-    await resolveSchema(elements, ctx),
-    customRoute,
-  )
-
-  return {
-    pageType: 'page',
-    panel:    await panelInfo(pilotiq, req, customRoute),
-    page:     PageClass.toMeta(),
-    schemaData,
-    _widgetData: widgetData,
-    basePath: cfg.path,
-    layout:   cfg.layout,
-    notifications: consumeFlashedNotifications(req),
-  }
-}
-
-// ─── Plan #15 widget polling data builder ────────────────────
-
-/**
- * Scopes the polling endpoint resolves against. Mirrors the
- * form-state / wizard scope discriminator.
- *
- *   panel:    dashboard page (`POST {base}/_widget/:id`)
- *   page:     custom page    (`POST {base}/{pageSlug}/_widget/:id`)
- *   resource: list page      (`POST {base}/{slug}/_widget/:id`) —
- *             resolves the resource's index `Page.schema()` so widgets
- *             from `Resource.headerSchema()` / `footerSchema()` are
- *             reachable. Auth runs `R.canAccess + R.canViewAny` in
- *             front of the per-widget visibility check.
- */
-export type WidgetScope =
-  | { kind: 'panel' }
-  | { kind: 'page';     pageSlug: string }
-  | { kind: 'resource'; slug:     string }
-
-export interface WidgetRequest {
-  id:      string
-  filter?: string
-}
+// Re-export `RelationChainStep` so external callsites importing it via
+// `./pageData.js` keep working.
+export type { RelationChainStep } from './pageData/breadcrumbs.js'
+
+// Re-export `ServerDataMap` so external imports via `./pageData.js` keep
+// working — the type is also surfaced from `packages/pilotiq/src/index.ts`.
+export type { ServerDataMap } from './pageData/helpers.js'
+
+// Re-export the URL-tag helpers + fill pipeline + server-data resolver
+// for consumers that import them through `./pageData.js`.
+export {
+  applyFillPipeline,
+  applyRelationshipBuilderFill,
+  applyRelationshipRepeaterFill,
+  callPageSchema,
+  resolveServerDataElements,
+  tagActionDispatch,
+  tagCellEditUrls,
+  tagFieldAiUrls,
+  tagFormActions,
+  tagFormStateUrls,
+  tagFormWizardUrls,
+  tagRichTextMentionUrls,
+  tagSelectCreateOptionUrls,
+  tagTableDeferred,
+  tagTableReorderUrls,
+  tagWidgetUrls,
+} from './pageData/helpers.js'
+
+// Re-export navigation chrome surface so external callsites importing
+// it via `./pageData.js` keep working (e.g. routes/test harnesses).
+export type {
+  DatabaseNotificationsMeta,
+  NavItem,
+  PanelInfoRoute,
+  RightPanelMeta,
+  RightSidebarMeta,
+  UserMenuMeta,
+} from './pageData/navigation.js'
+export {
+  applyRoleHooks,
+  panelInfo,
+  resolvePageHooks,
+} from './pageData/navigation.js'
 
-export interface WidgetSuccess {
-  ok:        true
-  data:      unknown
-  timestamp: number
-}
-
-export interface WidgetFailure {
-  ok:     false
-  status: 403 | 404 | 500
-  error:  string
-}
-
-/**
- * Plan #15 — re-resolve the active page's schema, find the widget by
- * id, fail-closed via `evaluateVisibility`, then run
- * `resolveServerData(ctx)` and return the payload.
- *
- *   - 404 when the page or widget id doesn't exist.
- *   - 403 when the layout-level `visible(rule)` says the widget is
- *     hidden (server doesn't show data for hidden surfaces).
- *   - 500 when the hook itself throws.
- *
- * `body.filter` rides along on `RenderContext.filter` so per-chart
- * filter dropdowns can re-fetch with the new filter value. Treated as
- * an opaque string — widget hooks decode it however they want.
- */
-export async function widgetData(
-  pilotiq: Pilotiq,
-  scope:   WidgetScope,
-  body:    WidgetRequest,
-  req?:    unknown,
-): Promise<WidgetSuccess | WidgetFailure> {
-  const cfg = pilotiq.getConfig()
-  const user = await pilotiq.resolveUser(req)
-
-  let elements: Element[]
-  let ctx: RenderContext
-
-  if (scope.kind === 'panel') {
-    if (!cfg.dashboardPage) return { ok: false, status: 404, error: 'No dashboard page registered' }
-    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)
-    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)
-    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' }
-    ctx = uploadCtx(userCtx({ mode: 'table', basePath: cfg.path }, user), cfg)
-    elements = await callPageSchema(pages.index, ctx)
-  }
-
-  // Stamp the request's filter onto the render context so widget hooks
-  // can branch on it. Opaque string — widgets decode their own format.
-  if (body.filter !== undefined) ctx = { ...ctx, filter: body.filter } as RenderContext
-
-  const widget = findWidgetById(elements, body.id)
-  if (!widget) return { ok: false, status: 404, error: `Widget "${body.id}" not found` }
-
-  // Layout-level visibility re-check — if the widget is hidden by a
-  // visible(rule), refuse to ship data. Same fail-closed posture as
-  // the schema resolver. (Parent-container `visible(false)` would
-  // already drop the widget from the schema tree at SSR time, so a
-  // direct hidden-widget probe here covers the visible-rule-only case.)
-  const layoutCtx: import('./schema/Element.js').LayoutContext = {}
-  if (user !== null && user !== undefined) layoutCtx.user = user
-  if (!await widget.evaluateVisibility(layoutCtx)) {
-    return { ok: false, status: 403, error: 'Widget hidden' }
-  }
-
-  try {
-    const data = await widget.resolveServerData(ctx)
-    return { ok: true, data, timestamp: Date.now() }
-  } catch (err) {
-    return {
-      ok:     false,
-      status: 500,
-      error:  err instanceof Error ? err.message : 'Widget failed',
-    }
-  }
-}
-
-/** Walk the element tree looking for a server-data element with the
- *  given id. Same walker as `collectServerDataElements` but stops on
- *  first match. */
-function findWidgetById(elements: ReadonlyArray<Element>, id: string): ServerDataElement | undefined {
-  let found: ServerDataElement | undefined
-  const walk = (els: ReadonlyArray<Element>): void => {
-    for (const el of els) {
-      if (found) return
-      if (isServerDataElement(el)) {
-        if (el.getId() === id) { found = el; return }
-        continue
-      }
-      const type = el.getType()
-      if (type === 'form' || type === 'repeater' || type === 'builder' || type === 'table' || type === 'tableWidget') continue
-      const children = el.getChildren()
-      if (children) walk(children)
-    }
-  }
-  walk(elements)
-  return found
-}
+import {
+  dashboardData,
+  resourceCreateData,
+  resourceEditData,
+  resourceIndexData,
+  resourceRecordPageData,
+  resourceViewData,
+} from './pageData/resourcePages.js'
+
+// Re-export resource page builders so external callsites importing
+// through `./pageData.js` keep working (e.g. routes.ts handlers, tests).
+export {
+  dashboardData,
+  resolveActiveTab,
+  resourceCreateData,
+  resourceEditData,
+  resourceIndexData,
+  resourceRecordPageData,
+  resourceTableData,
+  resourceViewData,
+} from './pageData/resourcePages.js'
+
+import { relationManagerData } from './pageData/relationPages.js'
+
+// Re-export relation manager builder surface for external consumers
+// (routes.ts dispatches every relation-* role through these).
+export type {
+  RelationManagerResult,
+  RelationManagerScope,
+  ResolvedChain,
+} from './pageData/relationPages.js'
+export {
+  findRelatedResource,
+  relationManagerData,
+  resolveRelationChain,
+  safeManagerPolicy,
+} from './pageData/relationPages.js'
+
+// Re-export form-related builders + types for external callsites.
+export type {
+  FormCreateOptionFailure,
+  FormCreateOptionRequest,
+  FormCreateOptionSuccess,
+  FormStateError,
+  FormStateRequest,
+  FormStateResult,
+  FormStateScope,
+  FormWizardFailure,
+  FormWizardRequest,
+  FormWizardSuccess,
+} from './pageData/forms.js'
+export {
+  formCreateOptionData,
+  formStateData,
+  formWizardData,
+  mentionResolveData,
+} from './pageData/forms.js'
 
-// ─── Plan #12 global search data builder ─────────────────────
+import {
+  customPageData,
+  globalEditData,
+  globalViewData,
+} from './pageData/misc.js'
+
+// Re-export the misc page builders for external callsites (routes.ts
+// dispatches into globals / custom-page / widget / search routes).
+export {
+  customPageData,
+  globalEditData,
+  globalViewData,
+  searchData,
+  widgetData,
+} from './pageData/misc.js'
+export type {
+  WidgetFailure,
+  WidgetRequest,
+  WidgetScope,
+  WidgetSuccess,
+} from './pageData/misc.js'
 
-/**
- * Resolve the user via `pilotiq.resolveUser(req)` and run the
- * panel-wide search. Mirrors the formStateData/formWizardData
- * shape so the `/_search` route handler stays a thin wrapper.
- *
- * Also resolves the `panels::global-search.results.before/.after`
- * render hooks when the panel registered any — sparse, absent when
- * neither slot has registered fns. Sent as a `RenderHookMap` so the
- * client `<CommandPalette>` can mount `<RenderHookSlot>` above and
- * below the result list (same pattern chrome slots use).
- */
-export async function searchData(
-  pilotiq: Pilotiq,
-  query:   string,
-  req?:    unknown,
-): Promise<{
-  ok: true
-  results: GlobalSearchResult[]
-  renderHooks?: RenderHookMap
-}> {
-  const user = await pilotiq.resolveUser(req)
-  const results = await searchAllResources(pilotiq, query, user)
-  const cfg = pilotiq.getConfig()
-  const out: { ok: true; results: GlobalSearchResult[]; renderHooks?: RenderHookMap } = {
-    ok: true,
-    results,
-  }
-  if (cfg.renderHooks && cfg.renderHooks.length > 0) {
-    const hooks = await resolvePageHooks(
-      pilotiq,
-      user,
-      pageHooksFor('search'),
-      { url: `${cfg.path}/_search` },
-    )
-    if (Object.keys(hooks).length > 0) out.renderHooks = hooks
-  }
-  return out
-}
 
 // ─── Vike +data dispatcher ───────────────────────────────────