@pilotiq/pilotiq 0.6.1 → 0.7.0

package/src/pageData.ts

@@ -244,6 +244,12 @@ export async function panelInfo(
     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,
@@ -254,6 +260,7 @@ export async function panelInfo(
     ...(databaseNotifications ? { databaseNotifications } : {}),
     ...(rightSidebar ? { rightSidebar } : {}),
     ...(Object.keys(renderHooks).length > 0 ? { renderHooks } : {}),
+    ...(aiSuggestionsMode !== 'auto' ? { aiSuggestionsMode } : {}),
   }
 }
 
@@ -1872,7 +1879,7 @@ export async function resourceEditData(
   // 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 = buildRelationTabs(R, recordId, cfg.path, '__edit')
+  const relationTabsEl = await buildRelationTabs(R, recordId, cfg.path, '__edit', user, record)
   if (relationTabsEl) elements.unshift(relationTabsEl)
 
   const recordTitle = record !== undefined && record !== null
@@ -2237,7 +2244,7 @@ async function buildRelationListData(
   tagActionDispatch(elements, listUrl)
   await loadTableRecords(elements, scope.query ?? {}, listUrl, user)
 
-  const tabs = buildRelationTabs(R, scope.recordId, base, scope.relationship)
+  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
   if (tabs) elements.unshift(tabs)
 
   const breadcrumbs = relationListBreadcrumbs(
@@ -2313,7 +2320,7 @@ async function buildRelationCreateData(
     if (scope.prefill.errors) form.withErrors(scope.prefill.errors)
   }
 
-  const tabs = buildRelationTabs(R, scope.recordId, base, scope.relationship)
+  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
   if (tabs) elements.unshift(tabs)
 
   const breadcrumbs = relationCreateBreadcrumbs(
@@ -2406,15 +2413,16 @@ async function buildRelationViewData(
   // 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 = buildNestedRelationTabs(
+  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 = buildRelationTabs(R, scope.recordId, base, scope.relationship)
+  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
   if (tabs) elements.unshift(tabs)
 
   const breadcrumbs = relationViewBreadcrumbs(
@@ -2524,7 +2532,7 @@ async function buildRelationEditData(
     form.withValues(values)
   }
 
-  const tabs = buildRelationTabs(R, scope.recordId, base, scope.relationship)
+  const tabs = await buildRelationTabs(R, scope.recordId, base, scope.relationship, user, parentRecord)
   if (tabs) elements.unshift(tabs)
 
   const breadcrumbs = relationEditBreadcrumbs(
@@ -2844,7 +2852,7 @@ async function buildNestedRelationListData(
   tagActionDispatch(elements, listUrl)
   await loadTableRecords(elements, scope.query ?? {}, listUrl, user)
 
-  const tabs = buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship)
+  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(
@@ -2898,7 +2906,7 @@ async function buildNestedRelationCreateData(
     if (scope.prefill.errors) form.withErrors(scope.prefill.errors)
   }
 
-  const tabs = buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship)
+  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(
@@ -2963,7 +2971,7 @@ async function buildNestedRelationViewData(
 
   const elements: Element[] = M2.detail(child2, child1)
 
-  const tabs = buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship)
+  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(
@@ -3045,7 +3053,7 @@ async function buildNestedRelationEditData(
     form.withValues(values)
   }
 
-  const tabs = buildNestedRelationTabs(resolved.R, resolved.M1, base, scope.chain[0], scope.chain[1].recordId, scope.chain[1].relationship)
+  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(
@@ -3092,21 +3100,38 @@ async function buildNestedRelationEditData(
  * 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.
  */
-function buildNestedRelationTabs(
-  R:           ResourceClass,
-  M:           typeof RelationManager,
-  basePath:    string,
-  step0:       RelationChainStep,
-  child1Id:    string,
-  activeKey:   string,
-): RelationTabs | undefined {
+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
@@ -3120,9 +3145,10 @@ function buildNestedRelationTabs(
     iconOwner: M.name,
   }))
 
-  for (const N of siblings) {
+  siblings.forEach((N, i) => {
+    if (!siblingVisible[i]) return
     let nestedRel = ''
-    try { nestedRel = N.getRelationship() } catch { continue }
+    try { nestedRel = N.getRelationship() } catch { return }
     const icon = N.getIcon()
     tabs.push(relationTab({
       key:    nestedRel,
@@ -3131,7 +3157,12 @@ function buildNestedRelationTabs(
       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)
 }
@@ -3144,11 +3175,25 @@ function buildNestedRelationTabs(
  * 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 (Filament-style 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).
+ * `__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
@@ -3156,23 +3201,65 @@ function buildNestedRelationTabs(
  * (View+Edit sub-nav alone isn't worth a tab strip; users navigate
  * those via headerActions or the back link.)
  */
-function buildRelationTabs(
-  R:         ResourceClass,
-  recordId:  string,
-  basePath:  string,
-  activeKey: string,
-): RelationTabs | undefined {
-  const managers = R.relations()
-  if (managers.length === 0) return undefined
+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[] = []
 
-  // View tab — only when the resource has a ViewPage registered.
-  // Defaults always include one; users who pruned ViewPage in their
-  // `static pages()` override get no broken link.
-  if (pages.view) {
+  if (pages.view && canView) {
     tabs.push(relationTab({
       key:       '__view',
       label:     'View',
@@ -3183,8 +3270,7 @@ function buildRelationTabs(
     }))
   }
 
-  // Edit tab — same defensive check.
-  if (pages.edit) {
+  if (pages.edit && canEdit) {
     tabs.push(relationTab({
       key:       '__edit',
       label:     'Edit',
@@ -3198,9 +3284,29 @@ function buildRelationTabs(
     }))
   }
 
-  for (const M of managers) {
+  // 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 { continue }
+    try { rel = M.getRelationship() } catch { return }
     const icon = M.getIcon()
     tabs.push(relationTab({
       key:    rel,
@@ -3209,11 +3315,25 @@ function buildRelationTabs(
       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'. */
@@ -4178,7 +4298,7 @@ export async function resourceViewData(
 
   // Plan #11 — prepend the relation tabs strip with the "Details" tab
   // active when the resource has relation managers configured.
-  const relationTabsEl = buildRelationTabs(R, recordId, cfg.path, '__view')
+  const relationTabsEl = await buildRelationTabs(R, recordId, cfg.path, '__view', user, record)
   if (relationTabsEl) elements.unshift(relationTabsEl)
 
   const recordTitle = record !== undefined && record !== null
@@ -4210,6 +4330,102 @@ export async function resourceViewData(
   }
 }
 
+/**
+ * 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,
@@ -4606,9 +4822,13 @@ export async function dispatchPageData(pageContext: PageContextLike): Promise<un
       })
       // Tagged failure shapes (`{ ok: false, status: 403 }`) leak straight
       // through to the +Page renderer, which can branch on the shape.
-      // For Plan #11 we let null short-circuit the SPA render the same
-      // way the resource builders do.
-      return out === null ? null : (out as Record<string, unknown>)
+      // null = no manager named `relationship` on R; fall through to the
+      // record sub-page lookup so URLs like `/admin/users/u1/activity`
+      // (where `activity` is registered under `pages().record`) route
+      // through `resourceRecordPageData` rather than 404ing.
+      if (out !== null) return out as Record<string, unknown>
+      const recordOut = await resourceRecordPageData(panel, slug, id, relationship)
+      return recordOut === null ? null : (recordOut as Record<string, unknown>)
     }
 
     case '/pages/(pilotiq)/relation-create': {

package/src/react/AppShell.tsx

@@ -1,4 +1,4 @@
-import React, { useState } from 'react'
+import React, { useEffect, useState } from 'react'
 import { SidebarLayout } from './layouts/SidebarLayout.js'
 import { TopbarLayout } from './layouts/TopbarLayout.js'
 import { ToasterProvider } from './Toaster.js'
@@ -38,6 +38,11 @@ export interface AppShellProps {
      *  `panelInfo()` server-side. */
     renderHooks?: RenderHookMap
     themeEditor?: boolean
+    /** AI suggestion mode — absent means `'auto'` (the default). When
+     *  set to `'review'`, AI plugins read this and stage writes as
+     *  `PendingSuggestion`s for user approval instead of applying
+     *  immediately. Plan: `docs/plans/ai-review-mode.md`. */
+    aiSuggestionsMode?: 'auto' | 'review'
   }
   basePath: string
   /** Pathname used to compute active-link state in the sidebar/topbar. */
@@ -60,14 +65,32 @@ export interface AppShellProps {
    * chrome simply doesn't mount.
    */
   rightPanelRegistry?: RightPanelRegistry
+  /**
+   * Build-time layout-provider registry from the Vite plugin. Each entry
+   * is a React component that wraps the panel's layout tree at the
+   * root. Plugins register via `Pilotiq.layoutProvider(C)`; the Vite
+   * plugin harvests refs into this array. Empty `[]` is the no-op
+   * default — chrome renders without any extra wrapping.
+   */
+  layoutProviderRegistry?: ReadonlyArray<React.ComponentType<{ children: React.ReactNode; basePath?: string }>>
   children: React.ReactNode
 }
 
-export function AppShell({ layout = 'sidebar', notifications, componentRegistry, rightPanelRegistry, ...props }: AppShellProps) {
+export function AppShell({ layout = 'sidebar', notifications, componentRegistry, rightPanelRegistry, layoutProviderRegistry, ...props }: AppShellProps) {
   const Layout = layout === 'topbar' ? TopbarLayout : SidebarLayout
   // exactOptionalPropertyTypes: only spread `initialNotifications` when set.
   const toasterProps = notifications ? { initialNotifications: notifications } : {}
 
+  // Stamp the panel-wide AI suggestion mode on a window global so the
+  // AI plugin's `update_form_state` client-tool handler can read it
+  // without context plumbing. Singleton flag — doesn't change between
+  // pages within the same panel. Plan: `docs/plans/ai-review-mode.md`.
+  const aiSuggestionsMode = props.panel.aiSuggestionsMode ?? 'auto'
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    ;(window as unknown as { __pilotiqAiSuggestionsMode?: 'auto' | 'review' }).__pilotiqAiSuggestionsMode = aiSuggestionsMode
+  }, [aiSuggestionsMode])
+
   // Plan #12 — palette open state lives at AppShell so the trigger pill
   // (rendered inside the layout's header) and the palette dialog both
   // observe the same flag via context.
@@ -106,7 +129,11 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
     </ToasterProvider>
   )
 
-  return (
+  // Plugin-registered layout providers (e.g. AI chat queue, tenant
+  // theme switcher). Wraps in registration order: the FIRST registered
+  // provider sits OUTERMOST (closest to the layout root); LAST sits
+  // INNERMOST (closest to the page tree). Empty / unset → no wrap.
+  const wrapped = wrapInLayoutProviders(
     <ComponentRegistryProvider value={componentRegistry}>
       <RightPanelRegistryProvider value={rightPanelRegistry}>
         {rightSidebarMeta ? (
@@ -117,8 +144,32 @@ export function AppShell({ layout = 'sidebar', notifications, componentRegistry,
           inner
         )}
       </RightPanelRegistryProvider>
-    </ComponentRegistryProvider>
+    </ComponentRegistryProvider>,
+    layoutProviderRegistry,
+    props.basePath,
   )
+
+  return wrapped
+}
+
+/**
+ * Fold registered layout providers around `tree` from last to first so
+ * the first-registered provider ends up outermost in the React tree
+ * (closest to the layout root) — matches the registration-order
+ * intuition documented on `Pilotiq.layoutProvider`.
+ */
+function wrapInLayoutProviders(
+  tree:     React.ReactElement,
+  registry: ReadonlyArray<React.ComponentType<{ children: React.ReactNode; basePath?: string }>> | undefined,
+  basePath: string,
+): React.ReactElement {
+  if (!registry || registry.length === 0) return tree
+  let acc: React.ReactElement = tree
+  for (let i = registry.length - 1; i >= 0; i--) {
+    const Provider = registry[i]!
+    acc = <Provider basePath={basePath}>{acc}</Provider>
+  }
+  return acc
 }
 
 /**

package/src/react/PendingSuggestionApplierRegistry.ts

@@ -0,0 +1,80 @@
+import type { PendingSuggestion } from './PendingSuggestionsContext.js'
+
+/**
+ * A function that applies a `PendingSuggestion` to its target field —
+ * registered by the field renderer (or editor adapter) on mount, looked
+ * up by aggregate consumers (e.g. a chat-sidebar pending-pill's
+ * "Approve all" button) that live outside the form's React tree.
+ *
+ * The applier is responsible for the apply *only*. Dismissing the
+ * suggestion from the queue is the caller's job — the apply path is
+ * decoupled from the queue-side bookkeeping so a future Phase that
+ * mirrors approvals to a server can do both via different code paths.
+ */
+export type PendingSuggestionApplier = (suggestion: PendingSuggestion) => void
+
+interface RegistryEntry {
+  formId:    string | undefined
+  fieldName: string
+  apply:     PendingSuggestionApplier
+}
+
+const _entries = new Map<string, RegistryEntry>()
+
+/**
+ * Compose the registry key. `formId` defaults to `'*'` (global form
+ * scope) so renderers in non-multi-form pages don't have to thread an
+ * id. Form-scoped registrations always win over the wildcard when both
+ * exist for the same field name.
+ */
+function keyFor(formId: string | undefined, fieldName: string): string {
+  return `${formId ?? '*'}::${fieldName}`
+}
+
+/**
+ * Register an applier for `(formId, fieldName)`. Returns an unregister
+ * function for `useEffect` cleanup. Re-registering with the same key
+ * replaces the previous entry — the most recently mounted renderer
+ * wins (typical in multi-instance form scenarios where an old form
+ * unmounts after a new one mounts during navigation).
+ */
+export function registerPendingSuggestionApplier(
+  formId:    string | undefined,
+  fieldName: string,
+  apply:     PendingSuggestionApplier,
+): () => void {
+  const key = keyFor(formId, fieldName)
+  const entry: RegistryEntry = { formId, fieldName, apply }
+  _entries.set(key, entry)
+  return () => {
+    // Only delete if this entry is still the one we registered — a
+    // re-register from another instance may have replaced us.
+    if (_entries.get(key) === entry) _entries.delete(key)
+  }
+}
+
+/**
+ * Look up an applier for `(formId, fieldName)`. Tries the form-scoped
+ * key first; falls back to the wildcard form ('*') so a producer that
+ * pushed a suggestion without `formId` still resolves an applier from
+ * a single-form page.
+ */
+export function getPendingSuggestionApplier(
+  formId:    string | undefined,
+  fieldName: string,
+): PendingSuggestionApplier | undefined {
+  if (formId !== undefined) {
+    const scoped = _entries.get(keyFor(formId, fieldName))
+    if (scoped) return scoped.apply
+  }
+  const wild = _entries.get(keyFor(undefined, fieldName))
+  return wild?.apply
+}
+
+/**
+ * Test seam — clear the registry between tests. Not part of the public
+ * API.
+ */
+export function _clearAppliersForTests(): void {
+  _entries.clear()
+}