@pilotiq/pilotiq 0.5.0 → 0.6.0

package/src/applyPageHooks.test.ts

@@ -9,13 +9,16 @@ import { Form } from './elements/Form.js'
 import { TextField } from './fields/TextField.js'
 import { Heading } from './schema/Heading.js'
 import { Alert } from './schema/Alert.js'
-import { resourceIndexData, resourceCreateData, resourceViewData, customPageData } from './pageData.js'
+import { Action } from './actions/Action.js'
+import { resourceIndexData, resourceCreateData, resourceViewData, resourceEditData, customPageData } from './pageData.js'
 import { Page } from './Page.js'
 
-const heading = (content: string): ElementMeta => ({ type: 'heading', content })
+const heading = (content: string, children?: ElementMeta[]): ElementMeta =>
+  children ? { type: 'heading', content, children } : { type: 'heading', content }
 const table   = (rows = 0): ElementMeta => ({ type: 'table', rows })
 const form    = (id = 'f'): ElementMeta => ({ type: 'form', formId: id })
 const tabs    = (children: ElementMeta[] = []): ElementMeta => ({ type: 'listTabs', children })
+const action  = (label: string): ElementMeta => ({ type: 'action', label })
 
 describe('pageHooksFor()', () => {
   it('returns universal page bounds for non-resource roles', () => {
@@ -36,6 +39,24 @@ describe('pageHooksFor()', () => {
     assert.ok(names.includes('panels::resource.pages.create-record.form.before'))
     assert.ok(names.includes('panels::resource.pages.create-record.form.after'))
   })
+
+  it('extends with header.actions.before/.after for the four resource roles', () => {
+    assert.ok(pageHooksFor('list').includes('panels::resource.pages.list-records.header.actions.before'))
+    assert.ok(pageHooksFor('list').includes('panels::resource.pages.list-records.header.actions.after'))
+    assert.ok(pageHooksFor('create').includes('panels::resource.pages.create-record.header.actions.before'))
+    assert.ok(pageHooksFor('create').includes('panels::resource.pages.create-record.header.actions.after'))
+    assert.ok(pageHooksFor('edit').includes('panels::resource.pages.edit-record.header.actions.before'))
+    assert.ok(pageHooksFor('edit').includes('panels::resource.pages.edit-record.header.actions.after'))
+    assert.ok(pageHooksFor('view').includes('panels::resource.pages.view-record.header.actions.before'))
+    assert.ok(pageHooksFor('view').includes('panels::resource.pages.view-record.header.actions.after'))
+  })
+
+  it('does not include header.actions slots on non-resource roles', () => {
+    const names = pageHooksFor('dashboard')
+    assert.ok(!names.some(n => n.includes('header.actions')))
+    const search = pageHooksFor('search')
+    assert.ok(!search.some(n => n.includes('header.actions')))
+  })
 })
 
 describe('applyPageHooks()', () => {
@@ -172,6 +193,107 @@ describe('applyPageHooks()', () => {
     assert.deepEqual(contents, ['outer-top', 'inner-top', 'detail', 'inner-bottom', 'outer-bottom'])
   })
 
+  it('appends list-records.header.actions.before/.after into the first heading children', () => {
+    const out = applyPageHooks(
+      [heading('Posts', [action('Create')]), table()],
+      {
+        'panels::resource.pages.list-records.header.actions.before': [action('Plugin Pre')],
+        'panels::resource.pages.list-records.header.actions.after':  [action('Plugin Post')],
+      },
+      'list',
+    )
+    const updated = out[0] as ElementMeta
+    assert.equal(updated.type, 'heading')
+    assert.equal(updated.children?.length, 3)
+    assert.equal(updated.children?.[0]?.['label'], 'Plugin Pre')
+    assert.equal(updated.children?.[1]?.['label'], 'Create')
+    assert.equal(updated.children?.[2]?.['label'], 'Plugin Post')
+  })
+
+  it('header.actions.before fires on create-record role around the heading children', () => {
+    const out = applyPageHooks(
+      [heading('Create Post', [action('Save')]), form()],
+      {
+        'panels::resource.pages.create-record.header.actions.before': [action('Agents')],
+      },
+      'create',
+    )
+    const updated = out[0] as ElementMeta
+    assert.equal(updated.children?.length, 2)
+    assert.equal(updated.children?.[0]?.['label'], 'Agents')
+    assert.equal(updated.children?.[1]?.['label'], 'Save')
+  })
+
+  it('header.actions.after fires on edit-record role appended after existing children', () => {
+    const out = applyPageHooks(
+      [heading('Edit Post', [action('Save'), action('Delete')]), form()],
+      {
+        'panels::resource.pages.edit-record.header.actions.after': [action('Agents')],
+      },
+      'edit',
+    )
+    const updated = out[0] as ElementMeta
+    assert.equal(updated.children?.length, 3)
+    assert.equal(updated.children?.[2]?.['label'], 'Agents')
+  })
+
+  it('header.actions.before/.after fires on view-record role', () => {
+    const out = applyPageHooks(
+      [heading('View Post', [action('Edit')])],
+      {
+        'panels::resource.pages.view-record.header.actions.before': [action('Pre')],
+        'panels::resource.pages.view-record.header.actions.after':  [action('Post')],
+      },
+      'view',
+    )
+    const updated = out[0] as ElementMeta
+    assert.deepEqual(updated.children?.map(c => c['label']), ['Pre', 'Edit', 'Post'])
+  })
+
+  it('drops header.actions hooks silently when no heading anchor exists', () => {
+    const out = applyPageHooks(
+      [table()],
+      { 'panels::resource.pages.list-records.header.actions.before': [action('lost')] },
+      'list',
+    )
+    assert.equal(out.length, 1)
+    assert.equal(out[0]?.type, 'table')
+  })
+
+  it('only the first top-level heading receives header.actions splice', () => {
+    const out = applyPageHooks(
+      [heading('First'), heading('Second')],
+      { 'panels::resource.pages.list-records.header.actions.before': [action('Once')] },
+      'list',
+    )
+    assert.equal((out[0] as ElementMeta).children?.length, 1)
+    assert.equal((out[1] as ElementMeta).children, undefined)
+  })
+
+  it('non-action contributions land in heading.children at meta level (renderer filters at paint)', () => {
+    const out = applyPageHooks(
+      [heading('Posts', [action('Create')])],
+      {
+        'panels::resource.pages.list-records.header.actions.before': [heading('non-action')],
+      },
+      'list',
+    )
+    const updated = out[0] as ElementMeta
+    assert.equal(updated.children?.length, 2)
+    assert.equal(updated.children?.[0]?.type, 'heading')
+    assert.equal(updated.children?.[1]?.['label'], 'Create')
+  })
+
+  it('does not splice header.actions on non-resource roles', () => {
+    const out = applyPageHooks(
+      [heading('Hello', [action('Built-in')])],
+      { 'panels::resource.pages.list-records.header.actions.before': [action('Lost')] },
+      'dashboard',
+    )
+    assert.equal((out[0] as ElementMeta).children?.length, 1)
+    assert.equal((out[0] as ElementMeta).children?.[0]?.['label'], 'Built-in')
+  })
+
   it('does not splice list-records.* on a non-list role', () => {
     const out = applyPageHooks(
       [table()],
@@ -274,6 +396,49 @@ describe('Per-builder render-hook integration', () => {
     assert.equal(schema[0]?.['content'], 'Page banner')
   })
 
+  it('resourceIndexData splices header.actions.before into the page heading children', async () => {
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .resources([Articles])
+      .renderHook(
+        'panels::resource.pages.list-records.header.actions.before',
+        () => [Action.make('agents').label('Agents')],
+      )
+    const data = await resourceIndexData(panel, 'articles')
+    const schema = data?.['schemaData'] as ElementMeta[]
+    const headingMeta = schema.find(m => m.type === 'heading')
+    assert.ok(headingMeta, 'expected page heading')
+    const labels = (headingMeta.children ?? []).map(c => c['label'])
+    assert.ok(labels.includes('Agents'))
+    // Plugin chip appears at the start (before the resource's built-in
+    // "New Article" / equivalents).
+    assert.equal(labels[0], 'Agents')
+  })
+
+  it('resourceEditData scoped header.actions hook only fires for matching Resource', async () => {
+    class OtherResource extends Resource {
+      static override label = 'Other'
+      static override slug  = 'other'
+      static override form(form: Form): Form { return form.schema([TextField.make('name')]) }
+    }
+    const panel = Pilotiq.make('admin')
+      .path('/admin')
+      .resources([Articles, OtherResource])
+      .renderHook(
+        'panels::resource.pages.edit-record.header.actions.after',
+        () => [Action.make('agents').label('Agents')],
+        { resource: Articles },
+      )
+    const onArticles = await resourceEditData(panel, 'articles', 'rec-1')
+    const onOther    = await resourceEditData(panel, 'other',    'rec-2')
+    const findAgents = (sd: ElementMeta[] | undefined): boolean => {
+      const h = (sd ?? []).find(m => m.type === 'heading')
+      return Boolean((h?.children ?? []).some(c => c['label'] === 'Agents'))
+    }
+    assert.ok(findAgents(onArticles?.['schemaData'] as ElementMeta[]))
+    assert.equal(findAgents(onOther?.['schemaData'] as ElementMeta[]), false)
+  })
+
   it('scoped hook only fires when the matching resource is active', async () => {
     class OtherResource extends Resource {
       static override label = 'Other'

package/src/applyPageHooks.ts

@@ -55,24 +55,32 @@ export function pageHooksFor(role: PageRole): readonly RenderHookName[] {
         'panels::resource.pages.list-records.table.before',
         'panels::resource.pages.list-records.table.after',
         'panels::resource.pages.list-records.tabs.end',
+        'panels::resource.pages.list-records.header.actions.before',
+        'panels::resource.pages.list-records.header.actions.after',
       ]
     case 'create':
       return [
         ...PAGE_BOUNDS,
         'panels::resource.pages.create-record.form.before',
         'panels::resource.pages.create-record.form.after',
+        'panels::resource.pages.create-record.header.actions.before',
+        'panels::resource.pages.create-record.header.actions.after',
       ]
     case 'edit':
       return [
         ...PAGE_BOUNDS,
         'panels::resource.pages.edit-record.form.before',
         'panels::resource.pages.edit-record.form.after',
+        'panels::resource.pages.edit-record.header.actions.before',
+        'panels::resource.pages.edit-record.header.actions.after',
       ]
     case 'view':
       return [
         ...PAGE_BOUNDS,
         'panels::resource.pages.view-record.start',
         'panels::resource.pages.view-record.end',
+        'panels::resource.pages.view-record.header.actions.before',
+        'panels::resource.pages.view-record.header.actions.after',
       ]
     case 'search':
       return [
@@ -85,6 +93,40 @@ export function pageHooksFor(role: PageRole): readonly RenderHookName[] {
   }
 }
 
+/**
+ * Map a resource page role to its `header.actions.before / .after`
+ * slot pair. Returns `undefined` for non-resource roles where the
+ * concept doesn't apply.
+ */
+function headerActionSlotsFor(
+  role: PageRole,
+): readonly [RenderHookName, RenderHookName] | undefined {
+  switch (role) {
+    case 'list':
+      return [
+        'panels::resource.pages.list-records.header.actions.before',
+        'panels::resource.pages.list-records.header.actions.after',
+      ]
+    case 'create':
+      return [
+        'panels::resource.pages.create-record.header.actions.before',
+        'panels::resource.pages.create-record.header.actions.after',
+      ]
+    case 'edit':
+      return [
+        'panels::resource.pages.edit-record.header.actions.before',
+        'panels::resource.pages.edit-record.header.actions.after',
+      ]
+    case 'view':
+      return [
+        'panels::resource.pages.view-record.header.actions.before',
+        'panels::resource.pages.view-record.header.actions.after',
+      ]
+    default:
+      return undefined
+  }
+}
+
 /**
  * Splice a `RenderHookMap` into a resolved page schema at the
  * role-specific positions. Returns a new `ElementMeta[]`; the input
@@ -167,6 +209,20 @@ export function applyPageHooks(
     )
   }
 
+  // Resource-page header actions — splice into the first top-level
+  // Heading's children alongside built-in actions. Slot is action-only
+  // by convention (the heading renderer filters children to action /
+  // actionGroup); non-action contributions are silently skipped at
+  // render time.
+  const headerSlots = headerActionSlotsFor(role)
+  if (headerSlots) {
+    result = spliceHeadingActions(
+      result,
+      hooks[headerSlots[0]],
+      hooks[headerSlots[1]],
+    )
+  }
+
   // Universal page.start / page.end wrap everything else.
   result = wrap(
     result,
@@ -205,6 +261,38 @@ function spliceAroundType(
   return result
 }
 
+/**
+ * Splice `before` / `after` into the first top-level `'heading'` meta's
+ * `children` array — the slot the heading renderer uses to mount the
+ * page-title's right-aligned action chips. No-op when neither slot has
+ * content; drops silently when no heading anchor exists (custom
+ * headers carry their own action layout).
+ */
+function spliceHeadingActions(
+  metas:  ElementMeta[],
+  before: ElementMeta[] | undefined,
+  after:  ElementMeta[] | undefined,
+): ElementMeta[] {
+  const hasBefore = before && before.length > 0
+  const hasAfter  = after  && after.length  > 0
+  if (!hasBefore && !hasAfter) return metas
+  let mutated = false
+  return metas.map(m => {
+    if (!mutated && m.type === 'heading') {
+      mutated = true
+      return {
+        ...m,
+        children: [
+          ...(hasBefore ? before : []),
+          ...(m.children ?? []),
+          ...(hasAfter  ? after  : []),
+        ],
+      }
+    }
+    return m
+  })
+}
+
 /** Append `toAppend` into the first top-level meta whose `type`
  *  matches, on its `children` array. No-op when the type isn't found. */
 function appendIntoChildrenOfType(

package/src/elements/dispatchForm.test.ts

@@ -2,7 +2,7 @@ import { describe, it } from 'node:test'
 import assert from 'node:assert/strict'
 
 import { Form } from './Form.js'
-import { applyStateUpdate, coerceFormValues, dispatchFormSubmit, findForms, findWizardStepFields, selectForm, selectFormById } from './dispatchForm.js'
+import { applyStateUpdate, coerceFormValues, dispatchFormSubmit, findForms, findWizardStep, findWizardStepFields, selectForm, selectFormById } from './dispatchForm.js'
 import { Wizard, Step } from '../schema/Wizard.js'
 import { TextField } from '../fields/TextField.js'
 import { NumberField } from '../fields/NumberField.js'
@@ -453,3 +453,25 @@ describe('findWizardStepFields (Plan #8)', () => {
     assert.equal((fields![0] as TextField).name, 'nested')
   })
 })
+
+describe('findWizardStep (Plan #8)', () => {
+  it('returns the live Step instance for the requested index', () => {
+    const stepA = Step.make('a').schema([TextField.make('email')])
+    const stepB = Step.make('b').schema([TextField.make('name')])
+    const form = Form.make().schema([Wizard.make().steps([stepA, stepB])])
+    const found = findWizardStep(form.getChildren()!, 1)
+    assert.equal(found, stepB)
+  })
+
+  it('returns undefined when no Wizard descendant exists', () => {
+    const form = Form.make().schema([TextField.make('plain')])
+    assert.equal(findWizardStep(form.getChildren()!, 0), undefined)
+  })
+
+  it('returns undefined when the step index is out of range', () => {
+    const form = Form.make().schema([
+      Wizard.make().steps([Step.make('only').schema([])]),
+    ])
+    assert.equal(findWizardStep(form.getChildren()!, 5), undefined)
+  })
+})

package/src/elements/dispatchForm.ts

@@ -397,6 +397,16 @@ export function coerceFormValues(
         break
     }
 
+    // `TextField.trim()` — strips leading/trailing whitespace from the
+    // submitted value. Runs BEFORE stripCharacters so a value like
+    // `'  (415) 555-1212  '` first trims, then has the listed mask
+    // characters removed. Skipped for non-strings.
+    const trimmer = (field as { getTrim?: () => boolean }).getTrim
+    if (typeof trimmer === 'function' && trimmer.call(field)) {
+      const cur = out[name]
+      if (typeof cur === 'string') out[name] = cur.trim()
+    }
+
     // `TextField.stripCharacters([…])` — applies after type-specific
     // coercion so the persisted value never carries the listed
     // characters. Duck-typed: any Field whose `getStripCharacters?`
@@ -767,17 +777,18 @@ export function findForms(elements: ReadonlyArray<Element>): Form[] {
 }
 
 /**
- * Plan #8 — locate the children of a Wizard step at the given index inside
- * the form's tree. Returns `undefined` when the form has no Wizard
- * descendant or the step index is out of range. Step children are returned
- * as a fresh Element[] so callers can pass them straight to
- * `validateSchema`. Walks structurally (`getType() === 'wizard'/'step'`)
- * to stay robust to Vite SSR module-cache duplication.
+ * Plan #8 — locate the Wizard step Element at the given index inside the
+ * form's tree. Returns the live Step instance so callers can read both
+ * its children (`step.getChildren()`) and any hooks attached to it
+ * (`getBeforeValidation / getAfterValidation`). Walks structurally
+ * (`getType() === 'wizard'/'step'`) to stay robust to Vite SSR
+ * module-cache duplication. `undefined` when the form has no Wizard
+ * descendant or the step index is out of range.
  */
-export function findWizardStepFields(
+export function findWizardStep(
   formChildren: ReadonlyArray<Element>,
   stepIndex:    number,
-): Element[] | undefined {
+): Element | undefined {
   let wizard: Element | undefined
   const walk = (els: ReadonlyArray<Element>): void => {
     for (const el of els) {
@@ -790,7 +801,20 @@ export function findWizardStepFields(
   walk(formChildren)
   if (!wizard) return undefined
   const steps = (wizard.getChildren() ?? []).filter(c => c.getType() === 'step')
-  const step = steps[stepIndex]
+  return steps[stepIndex]
+}
+
+/**
+ * Sibling helper: returns just the children of the Wizard step at the
+ * given index. Thin wrapper over `findWizardStep` for callers that only
+ * need to validate the step's fields without touching the Step instance
+ * itself. `undefined` when the step is missing.
+ */
+export function findWizardStepFields(
+  formChildren: ReadonlyArray<Element>,
+  stepIndex:    number,
+): Element[] | undefined {
+  const step = findWizardStep(formChildren, stepIndex)
   if (!step) return undefined
   return step.getChildren() ?? []
 }

package/src/fields/TextField.test.ts

@@ -91,6 +91,51 @@ describe('TextField rich affordances (audit gap #3)', () => {
     })
   })
 
+  describe('trim', () => {
+    it('emits the flag only when set', () => {
+      const a = TextField.make('x').trim().toMeta()
+      assert.equal(a['trim'], true)
+
+      const b = TextField.make('x').toMeta()
+      assert.equal(b['trim'], undefined)
+    })
+
+    it('disarms with explicit false', () => {
+      const a = TextField.make('x').trim(false).toMeta()
+      assert.equal(a['trim'], undefined)
+    })
+
+    it('strips leading and trailing whitespace during coerce', () => {
+      const f = TextField.make('email').trim()
+      const out = coerceFormValues([f], { email: '   user@example.com\n' })
+      assert.equal(out['email'], 'user@example.com')
+    })
+
+    it('coerce no-ops when not configured', () => {
+      const f = TextField.make('plain')
+      const out = coerceFormValues([f], { plain: '  spaced  ' })
+      assert.equal(out['plain'], '  spaced  ')
+    })
+
+    it('coerce skips non-string values', () => {
+      const f = TextField.make('x').trim()
+      const out = coerceFormValues([f], { x: 42 as unknown as string })
+      assert.equal(out['x'], 42)
+    })
+
+    it('runs before stripCharacters when both are set', () => {
+      const f = TextField.make('phone').trim().stripCharacters('()- ')
+      const out = coerceFormValues([f], { phone: '  (415) 555-1212  ' })
+      assert.equal(out['phone'], '4155551212')
+    })
+
+    it('preserves empty strings', () => {
+      const f = TextField.make('x').trim()
+      const out = coerceFormValues([f], { x: '   ' })
+      assert.equal(out['x'], '')
+    })
+  })
+
   describe('inputMode + autocapitalize', () => {
     it('emits each attribute when set', () => {
       const a = TextField.make('q').inputMode('search').autocapitalize('off').toMeta()

package/src/fields/TextField.ts

@@ -38,6 +38,7 @@ export class TextField extends Field {
   private _mask?:        string
   private _datalist?:    string[]
   private _stripCharacters?: string[]
+  private _trim              = false
   private _inputMode?:        TextInputMode
   private _autocapitalize?:   TextAutocapitalize
   private _prefixAction?: Action
@@ -117,6 +118,17 @@ export class TextField extends Field {
 
   getStripCharacters(): string[] | undefined { return this._stripCharacters }
 
+  /**
+   * Strip leading and trailing whitespace from the submitted value
+   * before validation runs. Mirrors Laravel's `TrimStrings` middleware
+   * — server-side authority, so a tampered client still gets trimmed
+   * values. Composes with `stripCharacters()` (trim runs first). Empty
+   * strings remain empty; non-string values pass through.
+   */
+  trim(v: boolean = true): this { this._trim = v; return this }
+
+  getTrim(): boolean { return this._trim }
+
   /**
    * Set the HTML `inputmode` attribute — drives the virtual-keyboard
    * layout on mobile. Distinct from `type=` (a `text` field with
@@ -157,6 +169,7 @@ export class TextField extends Field {
       ...(this._mask           !== undefined ? { mask:           this._mask           } : {}),
       ...(this._datalist       !== undefined ? { datalist:       this._datalist       } : {}),
       ...(this._stripCharacters!== undefined ? { stripCharacters:this._stripCharacters} : {}),
+      ...(this._trim                           ? { trim:            true                  } : {}),
       ...(this._inputMode      !== undefined ? { inputMode:      this._inputMode      } : {}),
       ...(this._autocapitalize !== undefined ? { autocapitalize: this._autocapitalize } : {}),
     }

package/src/index.ts

@@ -172,6 +172,7 @@ export { MetaTag,   type MetaTagAttrs }   from './schema/MetaTag.js'
 export { LinkTag,   type LinkTagAttrs }   from './schema/LinkTag.js'
 export { ScriptTag, type ScriptTagAttrs } from './schema/ScriptTag.js'
 export { StyleTag } from './schema/StyleTag.js'
+export { SlotComponent } from './schema/SlotComponent.js'
 
 // Plan #16 — read-only entry primitives for `Resource.detail()`.
 export {

package/src/pageData.test.ts

@@ -8,6 +8,7 @@ import {
   applyFillPipeline,
   formCreateOptionData,
   formStateData,
+  formWizardData,
   mentionResolveData,
   panelInfo,
   resolveActiveTab,
@@ -29,6 +30,7 @@ import { TextField } from './fields/TextField.js'
 import { SelectField } from './fields/SelectField.js'
 import { ToggleField } from './fields/ToggleField.js'
 import { Section } from './schema/Section.js'
+import { Wizard, Step } from './schema/Wizard.js'
 import { Repeater } from './fields/RepeaterField.js'
 import { Builder } from './fields/BuilderField.js'
 import { Block } from './schema/Block.js'
@@ -1098,6 +1100,87 @@ describe('mentionResolveData (async mention items)', () => {
   })
 })
 
+describe('formWizardData — Step.beforeValidation / afterValidation hooks', () => {
+  function panelWithWizard(steps: Step[]) {
+    class TestPage extends Page {
+      static override slug = 'demo'
+      static override schema() {
+        return [Form.make().formId('the-form').schema([Wizard.make().steps(steps)])]
+      }
+    }
+    return Pilotiq.make('T').path('/admin').pages([TestPage])
+  }
+
+  const dispatch = (panel: ReturnType<typeof Pilotiq.make>, body: { formId: string; step: number; values: Record<string, unknown> }) =>
+    formWizardData(panel, { kind: 'page', pageSlug: 'demo' }, body)
+
+  it('returns ok:true when no hooks are set and validation passes', async () => {
+    const panel = panelWithWizard([Step.make('a').schema([TextField.make('x')])])
+    const result = await dispatch(panel, { formId: 'the-form', step: 0, values: { x: 'v' } })
+    assert.deepEqual(result, { ok: true })
+  })
+
+  it('runs beforeValidation before validators and lets it mutate values in place', async () => {
+    const seen: string[] = []
+    const panel = panelWithWizard([
+      Step.make('a').schema([TextField.make('email').required()])
+        .beforeValidation((values) => {
+          seen.push('before')
+          values['email'] = 'auto@example.com'
+        }),
+    ])
+    const result = await dispatch(panel, { formId: 'the-form', step: 0, values: {} })
+    assert.deepEqual(result, { ok: true })
+    assert.deepEqual(seen, ['before'])
+  })
+
+  it('throwing from beforeValidation halts with 422 under the _step key', async () => {
+    const panel = panelWithWizard([
+      Step.make('a').schema([TextField.make('x')])
+        .beforeValidation(async () => { throw new Error('email already in use') }),
+    ])
+    const result = await dispatch(panel, { formId: 'the-form', step: 0, values: { x: 'v' } })
+    assert.equal((result as { ok: false; status: number }).ok, false)
+    assert.equal((result as { ok: false; status: number }).status, 422)
+    assert.deepEqual((result as { errors: Record<string, string[]> }).errors, { _step: ['email already in use'] })
+  })
+
+  it('runs afterValidation only when validators pass', async () => {
+    let afterRan = false
+    const panel = panelWithWizard([
+      Step.make('a').schema([TextField.make('x').required()])
+        .afterValidation(() => { afterRan = true }),
+    ])
+    // Failing field validators short-circuit before afterValidation fires.
+    const failed = await dispatch(panel, { formId: 'the-form', step: 0, values: { x: '' } })
+    assert.equal((failed as { ok: false }).ok, false)
+    assert.equal(afterRan, false)
+    // Passing values let afterValidation run.
+    const passed = await dispatch(panel, { formId: 'the-form', step: 0, values: { x: 'v' } })
+    assert.deepEqual(passed, { ok: true })
+    assert.equal(afterRan, true)
+  })
+
+  it('throwing from afterValidation halts with 422 under the _step key', async () => {
+    const panel = panelWithWizard([
+      Step.make('a').schema([TextField.make('x')])
+        .afterValidation(() => { throw new Error('cross-field invariant failed') }),
+    ])
+    const result = await dispatch(panel, { formId: 'the-form', step: 0, values: { x: 'v' } })
+    assert.equal((result as { ok: false; status: number }).status, 422)
+    assert.deepEqual((result as { errors: Record<string, string[]> }).errors, { _step: ['cross-field invariant failed'] })
+  })
+
+  it('non-Error throws still produce a usable message', async () => {
+    const panel = panelWithWizard([
+      Step.make('a').schema([TextField.make('x')])
+        .beforeValidation(() => { throw 'plain string failure' as unknown as Error }),
+    ])
+    const result = await dispatch(panel, { formId: 'the-form', step: 0, values: { x: 'v' } })
+    assert.deepEqual((result as { errors: Record<string, string[]> }).errors, { _step: ['plain string failure'] })
+  })
+})
+
 describe('tagRichTextMentionUrls — nested Repeater + Builder rows', () => {
   it('stamps a Repeater template field via the form-level URL', () => {
     const inner = new FakeRichTextField('body', true)