@pilotiq/pilotiq 0.5.0 → 0.6.1

package/src/pageData.ts

@@ -23,7 +23,7 @@ import { isServerDataElement, type ServerDataElement } from './schema/ServerData
 import { Form } from './elements/Form.js'
 import { Table } from './elements/Table.js'
 import { Column } from './Column.js'
-import { applyStateUpdate, coerceFormValues, findForms, findWizardStepFields, loadRelationRows, selectFormById } from './elements/dispatchForm.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'
@@ -3732,16 +3732,49 @@ export async function formWizardData(
   if (!form) return { ok: false, status: 404, error: `Form "${body.formId}" not found on page` }
 
   const formChildren = form.getChildren() ?? []
-  const stepFields = findWizardStepFields(formChildren, body.step)
-  if (!stepFields) return { ok: false, status: 404, error: `Step ${body.step} not found on form "${body.formId}"` }
+  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(stepFields, body.values, record)
+  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 {

package/src/react/RightSidebarContext.tsx

@@ -93,20 +93,43 @@ export function RightSidebarProvider({ meta, basePath, children }: RightSidebarP
 
   const fallbackId = meta.panels[0]?.id ?? null
 
-  const [open,     setOpenState]     = useState<boolean>(() => readBool(openKey, false))
-  const [activeId, setActiveIdState] = useState<string | null>(() => {
-    const stored = readString(activeKey)
-    if (stored && meta.panels.some(p => p.id === stored)) return stored
-    return fallbackId
-  })
-  const [width,    setWidthState]    = useState<number>(() => {
-    const stored = readString(widthKey)
-    return clampPanelWidth(stored ?? meta.defaultWidth, {
+  // SSR-safety: initialise to closed / fallback / default-width so the
+  // server-rendered tree matches a fresh client (no localStorage). The
+  // useEffect below rehydrates from localStorage AFTER mount, avoiding a
+  // hydration mismatch warning every time a returning user reloads with
+  // the panel previously open. Brief closed→open flash is acceptable and
+  // identical to first-visit behaviour.
+  const [open,     setOpenState]     = useState<boolean>(false)
+  const [activeId, setActiveIdState] = useState<string | null>(fallbackId)
+  const [width,    setWidthState]    = useState<number>(() =>
+    clampPanelWidth(meta.defaultWidth, {
       min: meta.minWidth,
       max: meta.maxWidth,
       defaultWidth: meta.defaultWidth,
-    })
-  })
+    }),
+  )
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return
+    const storedOpen = readBool(openKey, false)
+    setOpenState(storedOpen)
+    const storedActive = readString(activeKey)
+    if (storedActive && meta.panels.some(p => p.id === storedActive)) {
+      setActiveIdState(storedActive)
+    }
+    const storedWidth = readString(widthKey)
+    if (storedWidth !== null) {
+      setWidthState(clampPanelWidth(storedWidth, {
+        min: meta.minWidth,
+        max: meta.maxWidth,
+        defaultWidth: meta.defaultWidth,
+      }))
+    }
+    // Run once on mount per basePath. Width / activeId / open keys are
+    // basePath-derived, so the dependency list is effectively static for
+    // a given panel — no stale-closure risk on subsequent renders.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [basePath])
 
   // Re-validate `activeId` when the contribution set changes (e.g.,
   // canAccess gating flipped after a route nav). If the stored id has

package/src/react/SchemaRenderer.tsx

@@ -104,6 +104,7 @@ import { StatsOverviewRenderer } from './widgets/StatsOverviewRenderer.js'
 import { TableWidgetRenderer } from './widgets/TableWidgetRenderer.js'
 import { ViewRenderer } from './widgets/ViewRenderer.js'
 import { getEntryComponent } from '../entries/registry.js'
+import { getSlotComponent } from '../slot-components/registry.js'
 import { getWidgetRenderer } from './widgetRegistry.js'
 
 /** Resolve an icon name through the user-extensible registry. Returns
@@ -1205,6 +1206,14 @@ function renderActionLike(
   index: number,
   opts:  RenderActionOptions = {},
 ): React.ReactNode {
+  if (el.type === 'slotComponent') {
+    // Plugin-contributed React mount — render through the main element
+    // dispatcher, which looks up the registered component and forwards
+    // its serialised props bag. Keeps every action-row slot (heading
+    // children, alert footer, empty-state footer, table-toolbar bulk
+    // strip) usable as a plugin extension point.
+    return renderElement(el, index)
+  }
   if (el.type === 'actionGroup') {
     return <ActionGroupTrigger key={index} el={el} ids={opts.ids ?? []} />
   }
@@ -2949,7 +2958,7 @@ function renderElement(el: ElementMeta, index: number): React.ReactNode {
       const level = (el['level'] as number) ?? 1
       const content = String(el['content'] ?? '')
       const description = el['description'] ? String(el['description']) : undefined
-      const headerActions = (el.children ?? []).filter(c => c.type === 'action' || c.type === 'actionGroup')
+      const headerActions = (el.children ?? []).filter(c => c.type === 'action' || c.type === 'actionGroup' || c.type === 'slotComponent')
       const Tag = level === 1 ? 'h1' : level === 2 ? 'h2' : 'h3'
       const sizes = { 1: 'text-2xl', 2: 'text-xl', 3: 'text-lg' } as const
       const titleBlock = (
@@ -2976,7 +2985,7 @@ function renderElement(el: ElementMeta, index: number): React.ReactNode {
     }
 
     case 'alert': {
-      const footer = (el.children ?? []).filter(c => c.type === 'action' || c.type === 'actionGroup')
+      const footer = (el.children ?? []).filter(c => c.type === 'action' || c.type === 'actionGroup' || c.type === 'slotComponent')
       return (
         <AlertRenderer
           key={index}
@@ -2998,7 +3007,7 @@ function renderElement(el: ElementMeta, index: number): React.ReactNode {
       const iconName    = el['icon']        ? String(el['icon'])        : undefined
       const contained   = el['contained'] !== false
       const Icon        = iconName ? resolveIcon(iconName) : undefined
-      const footer      = (el.children ?? []).filter(c => c.type === 'action' || c.type === 'actionGroup')
+      const footer      = (el.children ?? []).filter(c => c.type === 'action' || c.type === 'actionGroup' || c.type === 'slotComponent')
       const wrapper = contained
         ? 'rounded-lg border border-border bg-card text-card-foreground py-12 px-6'
         : 'py-8'
@@ -3201,6 +3210,36 @@ function renderElement(el: ElementMeta, index: number): React.ReactNode {
     case 'view':
       return <ViewRenderer key={index} meta={el} />
 
+    case 'slotComponent': {
+      const componentName = String(el['component'] ?? '')
+      if (!componentName) {
+        return (
+          <div
+            key={index}
+            className="rounded-md border border-amber-500/40 bg-amber-50 p-3 text-sm text-amber-800 dark:bg-amber-950/30 dark:text-amber-200"
+            role="alert"
+          >
+            SlotComponent without a registered <code className="font-mono">component</code> name.
+          </div>
+        )
+      }
+      const Component = getSlotComponent(componentName)
+      if (!Component) {
+        return (
+          <div
+            key={index}
+            className="rounded-md border border-amber-500/40 bg-amber-50 p-3 text-sm text-amber-800 dark:bg-amber-950/30 dark:text-amber-200"
+            role="alert"
+          >
+            No slot component registered for <code className="font-mono">{componentName}</code>.
+            Call <code className="font-mono">registerSlotComponents({'{ '}{componentName}{' }'})</code> at app boot.
+          </div>
+        )
+      }
+      const props = (el['props'] ?? {}) as Record<string, unknown>
+      return <Component key={index} {...props} />
+    }
+
     default: {
       // Plan #15 Phase C — server-data widget elements registered by
       // adapter packages (`@pilotiq/recharts` for `'chart'`, future
@@ -5281,7 +5320,7 @@ function TableRendererBody({ el }: { el: ElementMeta }) {
   const columns  = children.filter(c => c.type === 'column')
   // Actions and ActionGroups share placement — both show up in the
   // header/bulk/row toolbars depending on their `placement` field.
-  const actionLike = children.filter(c => c.type === 'action' || c.type === 'actionGroup')
+  const actionLike = children.filter(c => c.type === 'action' || c.type === 'actionGroup' || c.type === 'slotComponent')
   const filters    = children.filter(c => c.type === 'filter')
   const hasRecordUrl     = Boolean(el['recordUrl'])
   const hasRecordClasses = Boolean(el['recordClasses'])

package/src/react/cells/EditableCell.tsx

@@ -81,11 +81,15 @@ async function patchCell(url: string, value: unknown): Promise<PatchResult> {
 }
 
 /** Pull the first error message out of a `{ errors: { value: [...] } }`
- * response. Falls back to a generic "Couldn't save" string. */
+ * response. Also reads the reserved `_cell` key surfaced by
+ * `Column.beforeStateUpdated / afterStateUpdated` halts. Falls back to
+ * a generic "Couldn't save" string. */
 function firstErrorMessage(result: PatchResultErrors | PatchResultError): string {
   if ('errors' in result) {
     const fieldErrs = result.errors['value']
     if (fieldErrs && fieldErrs.length > 0) return fieldErrs[0]!
+    const cellErrs = result.errors['_cell']
+    if (cellErrs && cellErrs.length > 0) return cellErrs[0]!
   }
   if ('error' in result) return result.error
   return "Couldn't save"

package/src/routes.test.ts

@@ -1608,6 +1608,147 @@ describe('Editable cell columns — _cell route', () => {
     assert.equal(body.ok, false)
     assert.match(body.error, /database is on fire/)
   })
+
+  describe('beforeStateUpdated / afterStateUpdated hooks', () => {
+    it('runs beforeStateUpdated before the DB update and afterStateUpdated after', async () => {
+      const order: string[] = []
+      const { M, calls } = makeUpdatableModel([{ id: '1', title: 'old' }])
+      class Posts extends Resource {
+        static override label = 'Posts'
+        static override slug  = 'posts'
+        static override model = M as any
+        static override table(t: Table): Table {
+          return t.columns([
+            Column.make('id'),
+            TextInputColumn.make('title')
+              .beforeStateUpdated((value, { record }) => {
+                order.push(`before:${value}:${(record as { title: string }).title}`)
+              })
+              .afterStateUpdated((value) => {
+                order.push(`after:${value}`)
+              }),
+          ])
+        }
+      }
+      registerPilotiqRoutes(router, panelWith(Posts))
+      const route = router.list().find(r => r.path === '/admin/posts/:id/_cell/:column' && r.method === 'POST')!
+      const { res } = await callHandlerCapturing(route.handler, fakeReq({
+        params: { id: '1', column: 'title' },
+        body:   { value: 'new' },
+      }))
+      assert.equal(res.statusCode, 200)
+      assert.deepEqual(calls.update, [{ id: '1', data: { title: 'new' } }])
+      assert.deepEqual(order, ['before:new:old', 'after:new'])
+    })
+
+    it('throwing from beforeStateUpdated halts before the DB update with 422 _cell', async () => {
+      const { M, calls } = makeUpdatableModel([{ id: '1', title: 'a' }])
+      class Posts extends Resource {
+        static override label = 'Posts'
+        static override slug  = 'posts'
+        static override model = M as any
+        static override table(t: Table): Table {
+          return t.columns([
+            Column.make('id'),
+            TextInputColumn.make('title').beforeStateUpdated(() => {
+              throw new Error('locked while review is pending')
+            }),
+          ])
+        }
+      }
+      registerPilotiqRoutes(router, panelWith(Posts))
+      const route = router.list().find(r => r.path === '/admin/posts/:id/_cell/:column' && r.method === 'POST')!
+      const { res } = await callHandlerCapturing(route.handler, fakeReq({
+        params: { id: '1', column: 'title' },
+        body:   { value: 'new' },
+      }))
+      assert.equal(res.statusCode, 422)
+      const body = res.sentBody as { ok: boolean; errors: { _cell: string[] } }
+      assert.equal(body.ok, false)
+      assert.deepEqual(body.errors, { _cell: ['locked while review is pending'] })
+      assert.equal(calls.update.length, 0)
+    })
+
+    it('throwing from afterStateUpdated returns 422 _cell but the row is already updated', async () => {
+      const { M, calls } = makeUpdatableModel([{ id: '1', title: 'a' }])
+      class Posts extends Resource {
+        static override label = 'Posts'
+        static override slug  = 'posts'
+        static override model = M as any
+        static override table(t: Table): Table {
+          return t.columns([
+            Column.make('id'),
+            TextInputColumn.make('title').afterStateUpdated(async () => {
+              throw new Error('broadcast queue down')
+            }),
+          ])
+        }
+      }
+      registerPilotiqRoutes(router, panelWith(Posts))
+      const route = router.list().find(r => r.path === '/admin/posts/:id/_cell/:column' && r.method === 'POST')!
+      const { res } = await callHandlerCapturing(route.handler, fakeReq({
+        params: { id: '1', column: 'title' },
+        body:   { value: 'new' },
+      }))
+      assert.equal(res.statusCode, 422)
+      const body = res.sentBody as { ok: boolean; errors: { _cell: string[] } }
+      assert.deepEqual(body.errors, { _cell: ['broadcast queue down'] })
+      assert.deepEqual(calls.update, [{ id: '1', data: { title: 'new' } }])
+    })
+
+    it('hooks do not run when validators fail', async () => {
+      let beforeRan = false
+      const { M, calls } = makeUpdatableModel([{ id: '1', title: 'a' }])
+      class Posts extends Resource {
+        static override label = 'Posts'
+        static override slug  = 'posts'
+        static override model = M as any
+        static override table(t: Table): Table {
+          return t.columns([
+            Column.make('id'),
+            TextInputColumn.make('title')
+              .validate(minLength(3))
+              .beforeStateUpdated(() => { beforeRan = true }),
+          ])
+        }
+      }
+      registerPilotiqRoutes(router, panelWith(Posts))
+      const route = router.list().find(r => r.path === '/admin/posts/:id/_cell/:column' && r.method === 'POST')!
+      const { res } = await callHandlerCapturing(route.handler, fakeReq({
+        params: { id: '1', column: 'title' },
+        body:   { value: 'ab' },
+      }))
+      assert.equal(res.statusCode, 422)
+      assert.equal(beforeRan, false)
+      assert.equal(calls.update.length, 0)
+    })
+
+    it('non-Error throws still produce a usable _cell message', async () => {
+      const { M } = makeUpdatableModel([{ id: '1', title: 'a' }])
+      class Posts extends Resource {
+        static override label = 'Posts'
+        static override slug  = 'posts'
+        static override model = M as any
+        static override table(t: Table): Table {
+          return t.columns([
+            Column.make('id'),
+            TextInputColumn.make('title').beforeStateUpdated(() => {
+              throw 'plain string failure' as unknown as Error
+            }),
+          ])
+        }
+      }
+      registerPilotiqRoutes(router, panelWith(Posts))
+      const route = router.list().find(r => r.path === '/admin/posts/:id/_cell/:column' && r.method === 'POST')!
+      const { res } = await callHandlerCapturing(route.handler, fakeReq({
+        params: { id: '1', column: 'title' },
+        body:   { value: 'new' },
+      }))
+      assert.equal(res.statusCode, 422)
+      const body = res.sentBody as { ok: boolean; errors: { _cell: string[] } }
+      assert.deepEqual(body.errors, { _cell: ['plain string failure'] })
+    })
+  })
 })
 
 describe('persistFiltersInSession — list-page filter restore', () => {

package/src/routes.ts

@@ -161,6 +161,15 @@ function forbidden(res: AppResponse, json: boolean): unknown {
   return res.send('Forbidden')
 }
 
+/** Extract a user-facing message from a thrown value inside an editable
+ *  column's beforeStateUpdated / afterStateUpdated hook. Stamped under
+ *  the reserved `_cell` key in the 422 response. */
+function cellHookErrorMessage(err: unknown): string {
+  if (err instanceof Error && err.message) return err.message
+  if (typeof err === 'string' && err.length > 0) return err
+  return 'Update halted'
+}
+
 /** Run a `canX(...)` predicate, treating throws as `false`. The predicate
  * is user-authored and we want a flaky check to fail closed (deny) rather
  * than 500 the page. */
@@ -547,7 +556,10 @@ async function handleUploadRequest(
     }
   }
 
-  // Server-side resize via @rudderjs/image (optional peer dep)
+  // Server-side resize via @rudderjs/image (optional peer dep). Variable-
+  // string `import(name)` keeps Vite's static import-analysis from trying
+  // to pre-resolve the module on host apps that don't have @rudderjs/image
+  // installed — same pattern as `notifications/database.ts` for `@rudderjs/orm`.
   const resizeWidthStr  = typeof body['resize_width']  === 'string' ? body['resize_width']  : ''
   const resizeHeightStr = typeof body['resize_height'] === 'string' ? body['resize_height'] : ''
   let uploadFile: File = file
@@ -556,8 +568,9 @@ async function handleUploadRequest(
     const h = Number(resizeHeightStr)
     if (Number.isFinite(w) && w > 0 && Number.isFinite(h) && h > 0) {
       try {
+        const imageModuleName = '@rudderjs/image'
         // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-        const pkg = await import('@rudderjs/image' as string) as { image: (input: unknown) => { resize(w: number, h: number): { format(f: string): { toBuffer(): Promise<Buffer> } } } }
+        const pkg = await import(/* @vite-ignore */ imageModuleName) as { image: (input: unknown) => { resize(w: number, h: number): { format(f: string): { toBuffer(): Promise<Buffer> } } } }
         const buf = await pkg.image(file).resize(w, h).format('webp').toBuffer()
         const baseName = file.name.replace(/\.[^.]+$/, '')
         uploadFile = new File([buf.buffer as ArrayBuffer], `${baseName}.webp`, { type: 'image/webp' })
@@ -1114,6 +1127,17 @@ export function registerPilotiqRoutes(
             return res.json({ ok: false, errors: { value: errors } })
           }
 
+          // beforeStateUpdated — runs after validators pass, before the
+          // DB write. Throwing halts with 422 under `_cell`.
+          const beforeHook = col.getBeforeStateUpdated()
+          if (beforeHook) {
+            try { await beforeHook(value, { record: record as Record<string, unknown>, user }) }
+            catch (err) {
+              res.status(422)
+              return res.json({ ok: false, errors: { _cell: [cellHookErrorMessage(err)] } })
+            }
+          }
+
           try {
             await R.model!.update(id, { [col.name]: value })
           } catch (err) {
@@ -1124,6 +1148,18 @@ export function registerPilotiqRoutes(
             })
           }
 
+          // afterStateUpdated — runs only on a confirmed write. Throwing
+          // surfaces the error to the user; the DB row is already
+          // updated (the hook is for follow-up effects, not rollback).
+          const afterHook = col.getAfterStateUpdated()
+          if (afterHook) {
+            try { await afterHook(value, { record: record as Record<string, unknown>, user }) }
+            catch (err) {
+              res.status(422)
+              return res.json({ ok: false, errors: { _cell: [cellHookErrorMessage(err)] } })
+            }
+          }
+
           return res.json({ ok: true, value, notifications: [] })
         })
       }

package/src/schema/SlotComponent.test.ts

@@ -0,0 +1,77 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { SlotComponent } from './SlotComponent.js'
+
+describe('SlotComponent schema primitive', () => {
+  it('emits component name and no props by default', () => {
+    const meta = SlotComponent.make('BookmarkButton').toMeta()
+    assert.equal(meta['type'],      'slotComponent')
+    assert.equal(meta['component'], 'BookmarkButton')
+    assert.equal('props' in meta,   false)
+  })
+
+  it('ships .props({...}) verbatim under meta.props', () => {
+    const meta = SlotComponent.make('BookmarkButton')
+      .props({ basePath: '/admin', recordId: '42' })
+      .toMeta()
+    assert.deepEqual(meta['props'], { basePath: '/admin', recordId: '42' })
+  })
+
+  it('successive .props() calls merge shallowly', () => {
+    const meta = SlotComponent.make('X')
+      .props({ a: 1, b: 2 })
+      .props({ b: 3, c: 4 })
+      .toMeta()
+    assert.deepEqual(meta['props'], { a: 1, b: 3, c: 4 })
+  })
+
+  it('exposes the component name via getComponentName()', () => {
+    const el = SlotComponent.make('BookmarkButton')
+    assert.equal(el.getComponentName(), 'BookmarkButton')
+  })
+
+  it('inherits Element.visible() / hidden() / columnSpan', () => {
+    const el = SlotComponent.make('X').visible(false).columnSpan(2)
+    assert.equal(el.hasVisibilityRule(), true)
+    assert.deepEqual(el.getLayoutPositioning(), { columnSpan: 2 })
+  })
+
+  it('getType returns slotComponent (matches wire shape discriminator)', () => {
+    assert.equal(SlotComponent.make('X').getType(), 'slotComponent')
+  })
+})
+
+describe('Slot component runtime registry', () => {
+  it('registers, retrieves, and resets', async () => {
+    const { registerSlotComponents, getSlotComponent, _resetSlotComponentRegistryForTests } =
+      await import('../slot-components/registry.js')
+    _resetSlotComponentRegistryForTests()
+    const Stub = (() => null) as unknown as Parameters<typeof registerSlotComponents>[0][string]
+    registerSlotComponents({ Stub })
+    assert.equal(getSlotComponent('Stub'), Stub)
+    assert.equal(getSlotComponent('Missing'), undefined)
+    _resetSlotComponentRegistryForTests()
+    assert.equal(getSlotComponent('Stub'), undefined)
+  })
+
+  it('skips falsy values during register', async () => {
+    const { registerSlotComponents, getSlotComponent, _resetSlotComponentRegistryForTests } =
+      await import('../slot-components/registry.js')
+    _resetSlotComponentRegistryForTests()
+    registerSlotComponents({ Bad: undefined as never })
+    assert.equal(getSlotComponent('Bad'), undefined)
+  })
+
+  it('multiple registrations merge into the same registry', async () => {
+    const { registerSlotComponents, getSlotComponent, _resetSlotComponentRegistryForTests } =
+      await import('../slot-components/registry.js')
+    _resetSlotComponentRegistryForTests()
+    const A = (() => null) as never
+    const B = (() => null) as never
+    registerSlotComponents({ A })
+    registerSlotComponents({ B })
+    assert.equal(getSlotComponent('A'), A)
+    assert.equal(getSlotComponent('B'), B)
+  })
+})

package/src/schema/SlotComponent.ts

@@ -0,0 +1,71 @@
+import { Element } from './Element.js'
+
+/**
+ * Escape-hatch schema element that hands rendering off to a user-supplied
+ * React component registered via `registerSlotComponents()`. Distinct from
+ * `ComponentEntry` (which is record-bound and label-shelled for infolists)
+ * and from `View` (which is widget-shaped with `getData`/polling). Use for
+ * plugin-contributed UI that needs to mount inline at any schema position
+ * — toolbars, header chips, sidebar contributions, anywhere `Action` /
+ * `ActionGroup` would otherwise live.
+ *
+ * Wire shape ships only the registered name + a serialisable `props` bag.
+ * The `_components.ts` build-time manifest doesn't see runtime-registered
+ * components (they live in plugin packages, not `cfg.resources / globals
+ * / pages` statics), so the lookup happens at render via the runtime
+ * registry — same model as `registerEntryComponents` and
+ * `registerWidgetComponents`.
+ *
+ * @example
+ *   // bootstrap/providers.ts
+ *   registerSlotComponents({ BookmarkButton })
+ *
+ *   // A plugin / app contributes the chip into the resource-edit header:
+ *   panel.renderHook(
+ *     'panels::resource.pages.edit-record.header.actions.before',
+ *     (ctx) => [
+ *       SlotComponent.make('BookmarkButton').props({
+ *         basePath: ctx.basePath,
+ *         resourceSlug: ctx.resource?.getSlug(),
+ *         recordId: ctx.recordId,
+ *       }),
+ *     ],
+ *   )
+ */
+export class SlotComponent extends Element {
+  protected _componentName: string
+  protected _props?: Record<string, unknown>
+
+  protected constructor(componentName: string) {
+    super()
+    this._componentName = componentName
+  }
+
+  static make(componentName: string): SlotComponent {
+    return new SlotComponent(componentName)
+  }
+
+  /**
+   * Static props passed verbatim to the registered component. Must be
+   * JSON-serialisable — they ride through `viewProps` to the client.
+   * Successive calls merge shallowly with the previous bag.
+   */
+  props(props: Record<string, unknown>): this {
+    this._props = { ...(this._props ?? {}), ...props }
+    return this
+  }
+
+  getComponentName(): string {
+    return this._componentName
+  }
+
+  override getType(): string { return 'slotComponent' }
+
+  override toMeta(): Record<string, unknown> {
+    return {
+      type: 'slotComponent' as const,
+      component: this._componentName,
+      ...(this._props ? { props: this._props } : {}),
+    }
+  }
+}

package/src/schema/Wizard.ts

@@ -1,5 +1,26 @@
 import { Element } from './Element.js'
 
+/**
+ * Context handed to `Step.beforeValidation` / `afterValidation` hooks.
+ * Mirrors the shape used by Form lifecycle hooks (record + user; values
+ * are passed positionally so handlers can mutate them in place).
+ */
+export interface StepValidationContext {
+  record?: unknown
+  user?:   unknown
+}
+
+/**
+ * Hook signature for `Step.beforeValidation` / `afterValidation`.
+ * Throwing aborts the wizard advance with a 422 stamped under the
+ * reserved `_step` error key — surface a user-facing message via the
+ * thrown Error's `.message`.
+ */
+export type StepValidationHook = (
+  values: Record<string, unknown>,
+  ctx:    StepValidationContext,
+) => void | Promise<void>
+
 /**
  * Single step inside a `Wizard`. Holds a label, optional icon/description,
  * and a list of child Elements. Children resolve unconditionally on every
@@ -9,6 +30,8 @@ import { Element } from './Element.js'
 export class Step extends Element {
   private _icon?: string
   private _description?: string
+  private _beforeValidation?: StepValidationHook
+  private _afterValidation?:  StepValidationHook
 
   private constructor(private _label: string) {
     super()
@@ -30,6 +53,28 @@ export class Step extends Element {
     return this
   }
 
+  /**
+   * Runs on the server BEFORE the step's fields are validated when the
+   * user clicks Next. Use to mutate `values` in place (e.g. stamp a
+   * computed field needed by validators) or run an async availability
+   * check that should block advance. Throw an Error to halt — the
+   * thrown message lands under the reserved `_step` key in the 422
+   * response so the renderer can show it next to the Next button.
+   */
+  beforeValidation(fn: StepValidationHook): this { this._beforeValidation = fn; return this }
+
+  /**
+   * Runs on the server AFTER the step's validators pass and before the
+   * 200 advance response. Use for cross-field invariants, side-effects
+   * that should fire only on confirmed advance, or computed-field stamps
+   * that downstream steps will read. Throw to halt — same `_step` key
+   * convention as `beforeValidation`.
+   */
+  afterValidation(fn: StepValidationHook): this { this._afterValidation = fn; return this }
+
+  getBeforeValidation(): StepValidationHook | undefined { return this._beforeValidation }
+  getAfterValidation():  StepValidationHook | undefined { return this._afterValidation }
+
   getType(): string { return 'step' }
 
   toMeta(): Record<string, unknown> {