@pilotiq/pilotiq 0.1.0

package/src/fields/BuilderField.ts

@@ -0,0 +1,568 @@
+import { type ElementMeta } from '../schema/Element.js'
+import { Block, type BlockMeta } from '../schema/Block.js'
+import { Field, type FieldMeta } from './Field.js'
+import type { RenderContext } from '../schema/resolveSchema.js'
+import type { Action, ActionMeta } from '../actions/Action.js'
+import type { ModelLike } from '../orm/modelDefaults.js'
+import {
+  RowButton,
+  type RowButtonKind,
+  type RowButtonsMeta,
+} from './RowButton.js'
+import {
+  serializeRowButtons,
+  normalizeGridConfig,
+  type RepeaterGridConfig,
+  type RepeaterItemCanRule,
+  type RepeaterItemHiddenRule,
+} from './RepeaterField.js'
+
+/**
+ * Configuration for `Builder.relationship(...)`. Heterogeneous-row sibling
+ * of `RepeaterRelationshipConfig`.
+ *
+ * `name` matches a key on the parent model's `static relations` map. The
+ * child model carries a discriminator column (default `type`, holds the
+ * block name) and a JSON payload column (default `data`, holds the
+ * per-block inner-schema values verbatim) — plus the standard FK + PK,
+ * and an optional `sort` column when `orderColumn` is set.
+ *
+ * Two relation modes are supported:
+ *
+ *   - `hasMany`   — single foreign key on the child. `model` + `foreignKey`
+ *                   overrides exist for ORMs that don't follow the
+ *                   convention; both default to discovery via
+ *                   `parent.relations[name]` at submit time.
+ *   - `morphMany` — polymorphic owner side. The child carries
+ *                   `<morphName>Id` + `<morphName>Type` columns (the
+ *                   morph stamp). Resolved entirely off the parent's
+ *                   `relations[name]` morph descriptor — no `foreignKey`
+ *                   override; the column names are driven by `morphName`.
+ *                   `morphOne` collapses into the same branch.
+ *
+ * `typeColumn` + `dataColumn` default to `'type'` and `'data'` — same as
+ * Filament.
+ */
+export interface BuilderRelationshipConfig {
+  /** Relationship key on the parent (e.g. `'blocks'`). */
+  name:         string
+  /** Override the child model. Defaults to `parent.relations[name].model()`. */
+  model?:       ModelLike
+  /** Override the FK column on the child. Defaults to `parent.relations[name].foreignKey`. */
+  foreignKey?:  string
+  /** Discriminator column on the child holding the block name. Default `'type'`. */
+  typeColumn?:  string
+  /** JSON payload column on the child holding the per-block fields. Default `'data'`. */
+  dataColumn?:  string
+  /** Optional integer column on the child to receive the row index. */
+  orderColumn?: string
+}
+
+/** Public meta — `model` + `foreignKey` are server-only and stay private. */
+export interface BuilderRelationshipMeta {
+  name:         string
+  typeColumn?:  string
+  dataColumn?:  string
+  orderColumn?: string
+}
+
+/**
+ * Function evaluated once per row at meta-build to derive a human-readable
+ * label for the collapsed-row header. Receives the row's raw `data` body
+ * and the row's resolved `type`. Errors are swallowed and the renderer
+ * falls back to the block's label + row index.
+ */
+export type BuilderItemLabel = (
+  data: Record<string, unknown>,
+  blockName: string,
+) => string
+
+/**
+ * Per-row visibility rule. Same shape as `Repeater.itemHidden(rule)`:
+ * either a literal `boolean` or a callback receiving a row-scoped
+ * `LayoutContext` (`row.blockType` exposes the block name). Truthy
+ * hides the row; the renderer keeps inputs mounted via `display: none`
+ * so values + `__id` round-trip on submit.
+ *
+ * Throwing → row stays visible (fail-closed-as-visible — same posture as
+ * Repeater).
+ */
+export type BuilderItemHiddenRule = RepeaterItemHiddenRule
+
+export type BuilderItemCanRule = RepeaterItemCanRule
+
+/** Position of the `Add block` button under the field's row stack. */
+export type BuilderAddActionAlignment = 'start' | 'center' | 'end'
+
+/**
+ * Resolved per-row metadata. `id` mirrors Repeater's stable id round-trip;
+ * `type` carries the block discriminator so the renderer knows which
+ * picker option produced this row. `children` is the row's resolved
+ * inner schema (the matching block's `schema()` resolved against
+ * row-scoped values). `unknownType` is set when the row's submitted
+ * `type` doesn't match any registered block — the renderer falls back
+ * to a "missing block" placeholder; values still round-trip.
+ */
+export interface BuilderRowMeta {
+  id:           string
+  type:         string
+  children:     ElementMeta[]
+  itemLabel?:   string
+  hidden?:      boolean
+  unknownType?: boolean
+  /**
+   * Resolved per-row action metas for `extraItemActions(...)`. Same shape
+   * as `RepeaterRowMeta.extraActions` — see RepeaterField for the row
+   * dispatch contract. Field-level only in v1; per-block actions stay
+   * deferred to a future polish (`Block.extraItemActions(...)`).
+   */
+  extraActions?: ActionMeta[]
+  /**
+   * Per-row capability flags. Stamped only when the corresponding
+   * `itemCan*(rule)` resolved falsy for this row. The renderer reads
+   * these and skips the matching button. See `RepeaterRowMeta.canDelete`
+   * for the full contract — semantics are identical (`row.blockType` is
+   * available to the predicate as `ctx.row.blockType`).
+   */
+  canDelete?:   false
+  canClone?:    false
+  canReorder?:  false
+}
+
+export interface BuilderFieldMeta extends FieldMeta {
+  fieldType:           'builder'
+  rows:                BuilderRowMeta[]
+  /** Picker entries — every block registered via `.blocks([…])`. */
+  blocks:              BlockMeta[]
+  /**
+   * Set when `Builder.relationship(...)` is configured. Tells diagnostics
+   * + future UI hooks that submitted rows persist as child records on a
+   * `HasMany` relation; behavior is otherwise server-side. The serialized
+   * shape carries only `{ name, typeColumn?, dataColumn?, orderColumn? }`
+   * — `model` and `foreignKey` are server-only.
+   */
+  relationship?:       BuilderRelationshipMeta
+  minItems?:           number
+  maxItems?:           number
+  defaultBlock?:       string
+  reorderable?:        boolean
+  reorderableWithButtons?: boolean
+  collapsible?:        boolean
+  defaultCollapsed?:   boolean
+  /**
+   * Set when `Builder.accordion()` is configured. The renderer replaces
+   * the per-row collapsed map with a single "open row id" slot — picking
+   * row N collapses every other row. Implies `collapsible: true`. See
+   * `RepeaterFieldMeta.accordion` for the shared semantics.
+   */
+  accordion?:          boolean
+  cloneable?:          boolean
+  addable?:            boolean
+  deletable?:          boolean
+  /**
+   * Set when `Builder.addBetween()` is configured. The renderer mounts a
+   * thin "+" insertion zone above each row (and at the very top) — clicking
+   * it opens a compact picker that inserts the picked block at that
+   * index. The bottom `Add block` button stays — `addBetween` is additive,
+   * not a replacement. Respects `addable === false` and the field-level
+   * `maxItems` cap; per-block `Block.maxItems` already filters the picker.
+   */
+  addBetween?:         boolean
+  addActionLabel?:     string
+  addActionAlignment?: BuilderAddActionAlignment
+  blockPickerColumns?: number
+  blockNumbers?:       boolean
+  blockIcons?:         boolean
+  itemNumbers?:        boolean
+  /**
+   * Set when `Builder.grid(...)` is configured. Lays the ROWS themselves
+   * in an n-column grid — distinct from a Block's inner `Block.columns(n)`,
+   * which grids fields *inside* a single row. Accepts the scalar form
+   * (`grid(2)`) or a responsive object (`grid({ default: 1, md: 2 })`) —
+   * see `RepeaterFieldMeta.grid` for the shared semantics.
+   */
+  grid?:               RepeaterGridConfig
+  /**
+   * Per-slot chrome overrides for the seven built-in row buttons. Same
+   * shape as `RepeaterFieldMeta.buttons`; see `RowButton` for the
+   * customizer. Authors set these via `.addAction(RowButton.make()…)` etc.
+   */
+  buttons?:            RowButtonsMeta
+}
+
+/**
+ * Heterogeneous-row Repeater. The author registers N block-types via
+ * `.blocks([Block.make('heading').schema([…]), …])`; the rendered form
+ * lets the end user pick from those types when adding rows.
+ *
+ * Storage on the parent record is `[{ __id, type, data: {…} }, …]` — a
+ * `{ type, data }` envelope per row. JSON-friendly, collision-free with
+ * any inner field name, mirrors Filament. See `docs/plans/builder-field.md`
+ * for the wire-format details.
+ */
+export class BuilderField extends Field {
+  private _blocks:                Block[] = []
+  private _blocksByName:          Map<string, Block> = new Map()
+  private _minItems?:             number
+  private _maxItems?:             number
+  private _defaultBlock?:         string
+  private _reorderable            = false
+  private _reorderableWithButtons = false
+  private _collapsible            = false
+  private _defaultCollapsed       = false
+  private _accordion              = false
+  private _cloneable              = false
+  private _addable                = true
+  private _deletable              = true
+  private _addBetween             = false
+  private _itemNumbers            = false
+  private _blockNumbers           = false
+  private _blockIcons             = true
+  private _blockPickerColumns?:   number
+  private _addActionLabel?:       string
+  private _addActionAlignment:    BuilderAddActionAlignment = 'start'
+  private _itemLabel?:            BuilderItemLabel
+  private _itemHidden?:           BuilderItemHiddenRule
+  private _itemCanDelete?:        BuilderItemCanRule
+  private _itemCanClone?:         BuilderItemCanRule
+  private _itemCanReorder?:       BuilderItemCanRule
+  private _extraItemActions:      Action[] = []
+  private _grid?:                 RepeaterGridConfig
+  private _buttons:               { [K in RowButtonKind]?: RowButton } = {}
+  private _relationship?:         BuilderRelationshipConfig
+
+  private constructor(name: string) {
+    super(name, 'builder')
+  }
+
+  static make(name: string): BuilderField {
+    return new BuilderField(name)
+  }
+
+  /** Register the block types the user can pick from. Order = picker order. */
+  blocks(blocks: Block[]): this {
+    this._blocks       = blocks
+    this._blocksByName = new Map(blocks.map(b => [b.name, b]))
+    return this
+  }
+
+  /** Validator + client gate. */
+  minItems(n: number): this { this._minItems = n; return this }
+  maxItems(n: number): this { this._maxItems = n; return this }
+
+  /**
+   * Block name auto-selected when adding a row without explicitly opening
+   * the picker (e.g. when there's only one block type, or for "quick add"
+   * UX). Defaults to undefined → picker always opens.
+   */
+  defaultBlock(name: string): this { this._defaultBlock = name; return this }
+
+  reorderable(value: boolean = true): this { this._reorderable = value; return this }
+
+  /**
+   * Force button-only reorder (Up / Down arrows on each row). When `false`
+   * (default), reorderable rows use HTML5 drag-and-drop with the buttons
+   * as a keyboard fallback. Mirrors Filament's
+   * `reorderableWithButtons(bool)`.
+   */
+  reorderableWithButtons(value: boolean = true): this {
+    this._reorderableWithButtons = value
+    return this
+  }
+
+  collapsible(value: boolean = true): this { this._collapsible = value; return this }
+  collapsed(value: boolean = true):   this { this._defaultCollapsed = value; return this }
+
+  /**
+   * Accordion mode: only one row open at a time. Picking a different row
+   * collapses the currently-open one. Pair with `collapsed()` to start
+   * with every row collapsed (default is "first row open"). Auto-arms
+   * `collapsible()` since the accordion ergonomic is meaningless on a
+   * non-collapsible builder. Mirrors `RepeaterField.accordion()`.
+   */
+  accordion(value: boolean = true): this {
+    this._accordion = value
+    if (value) this._collapsible = true
+    return this
+  }
+
+  cloneable(value: boolean = true):   this { this._cloneable = value; return this }
+
+  /**
+   * Hide the `Add block` button. `maxItems` is the validator gate; this is
+   * the separate UX gate (e.g. read-only on a published record). Default `true`.
+   */
+  addable(value: boolean = true): this { this._addable = value; return this }
+
+  /**
+   * Hide the per-row delete button. `minItems` is the validator gate; this
+   * is the UX gate. Default `true`.
+   */
+  deletable(value: boolean = true): this { this._deletable = value; return this }
+
+  /**
+   * Mount inline `+ Insert` zones above each row (and at the very top)
+   * so the user can insert a new block between existing rows without
+   * scrolling to the field's bottom `Add block` button. Mirrors
+   * Filament's `addBetweenAction()` affordance. Additive — the bottom
+   * `Add block` button stays. Respects `addable === false` and
+   * `maxItems`; per-block `Block.maxItems` already filters the picker.
+   */
+  addBetween(value: boolean = true): this { this._addBetween = value; return this }
+
+  /** Position of the `Add block` button. */
+  addActionAlignment(a: BuilderAddActionAlignment): this {
+    this._addActionAlignment = a
+    return this
+  }
+
+  addActionLabel(label: string): this { this._addActionLabel = label; return this }
+
+  /** Grid column count for the picker dropdown. Default 1. */
+  blockPickerColumns(n: number): this { this._blockPickerColumns = n; return this }
+
+  /** Show 1-based numbering on each row's header. */
+  blockNumbers(value: boolean = true): this { this._blockNumbers = value; return this }
+
+  /** Show the block's icon in each row's header. Default `true`. */
+  blockIcons(value: boolean = true): this { this._blockIcons = value; return this }
+
+  /** Alias of `blockNumbers` for users coming from Repeater (parity flag). */
+  itemNumbers(value: boolean = true): this { this._itemNumbers = value; return this }
+
+  itemLabel(fn: BuilderItemLabel): this { this._itemLabel = fn; return this }
+
+  itemHidden(rule: BuilderItemHiddenRule): this { this._itemHidden = rule; return this }
+
+  /**
+   * Per-row gate for the trash button. Mirrors `Repeater.itemCanDelete`.
+   * Predicate sees a row-scoped `LayoutContext` with `ctx.row.blockType`
+   * exposing the row's block name so a single rule can branch by block.
+   * Throwing → button stays visible + warn (fail-open, same posture as
+   * `itemHidden`). Presentation only — gate the parent form's lifecycle
+   * hooks for real authorization.
+   */
+  itemCanDelete(rule: BuilderItemCanRule): this { this._itemCanDelete = rule; return this }
+
+  /**
+   * Per-row gate for the clone (`Duplicate row`) button. Mirrors
+   * `Repeater.itemCanClone`. No-op when `cloneable()` is off field-wide.
+   */
+  itemCanClone(rule: BuilderItemCanRule): this { this._itemCanClone = rule; return this }
+
+  /**
+   * Per-row gate for the reorder controls (drag grip + Up / Down arrows).
+   * Mirrors `Repeater.itemCanReorder`. No-op when `reorderable()` is off
+   * field-wide. Drag targeting is unaffected — non-pinned rows can still
+   * drop at the pinned row's slot; pin both sides to keep a pair adjacent.
+   */
+  itemCanReorder(rule: BuilderItemCanRule): this { this._itemCanReorder = rule; return this }
+
+  /**
+   * Per-row action buttons rendered alongside clone/delete in each row's
+   * header. Field-level only in v1 — applies to every block. Per-block
+   * variants (`Block.extraItemActions(...)`) deferred. See
+   * `RepeaterField.extraItemActions` for the dispatch contract; the only
+   * Builder-specific note is that `ctx.row` exposes `blockType` so a
+   * single handler can branch by block.
+   */
+  extraItemActions(actions: Action[]): this {
+    this._extraItemActions = actions
+    return this
+  }
+
+  /**
+   * Lay the ROWS themselves in an n-column grid. Distinct from
+   * `Block.columns(n)`, which grids fields *inside* a single block's
+   * body. Accepts the scalar form (`grid(2)`) or a responsive object
+   * (`grid({ default: 1, md: 2 })`). See `RepeaterField.grid()` for
+   * the shared semantics — same renderer behavior, same drag-indicator
+   * caveat.
+   */
+  grid(config: RepeaterGridConfig): this {
+    const normalized = normalizeGridConfig(config)
+    if (normalized === undefined) delete this._grid
+    else this._grid = normalized
+    return this
+  }
+
+  /**
+   * Persist rows to a `HasMany` (or `MorphMany` / `MorphOne`) relation on
+   * the parent record instead of serializing them to a JSON column. Each
+   * row maps to a real child record carrying a `type` discriminator + a
+   * JSON `data` payload (column names configurable). Submit creates /
+   * updates / deletes children against the relation transparently.
+   *
+   * For `morphMany`, the child also carries `<morphName>Id` +
+   * `<morphName>Type` columns; the framework stamps both on every create
+   * (and refuses to overwrite them on update) so a tampered POST body
+   * can't reassign a row to a different polymorphic parent. The morph
+   * shape is read off the parent's `static relations[name]` descriptor —
+   * no `foreignKey` override applies.
+   *
+   * Pass either the relationship name as a string (the common case —
+   * `model` + `foreignKey` are auto-discovered from the parent's
+   * `static relations` map; `typeColumn` / `dataColumn` default to
+   * `'type'` / `'data'`) or an object form for explicit overrides.
+   *
+   * Mutually exclusive with `dehydrated(false)` — the field's whole purpose
+   * is to write data, so silently dropping it would be confusing.
+   * Validators run unchanged.
+   */
+  relationship(arg: string | BuilderRelationshipConfig): this {
+    if (this.isDehydrated() === false) {
+      throw new Error(
+        `[Pilotiq] Builder "${this.name}": relationship() is incompatible with dehydrated(false) — the field's purpose is to persist data.`,
+      )
+    }
+    this._relationship = typeof arg === 'string' ? { name: arg } : { ...arg }
+    return this
+  }
+
+  /**
+   * Sugar over `.relationship({ ..., orderColumn: col })`. Sets the order
+   * column on an already-configured relationship; throws when
+   * `relationship()` hasn't been called first so misconfiguration surfaces
+   * eagerly.
+   */
+  orderColumn(col: string): this {
+    if (!this._relationship) {
+      throw new Error(
+        `[Pilotiq] Builder "${this.name}": orderColumn() requires relationship() to be configured first.`,
+      )
+    }
+    this._relationship.orderColumn = col
+    return this
+  }
+
+  /**
+   * Customize the bottom Add button's chrome. Equivalent to
+   * `addActionLabel()` plus icon / color / tooltip overrides; the
+   * customizer wins when both are set (it ships under `meta.buttons.add`
+   * which the renderer reads after `addActionLabel`).
+   */
+  addAction(b: RowButton): this { this._buttons.add = b; return this }
+
+  /** Customize the per-row clone button. */
+  cloneAction(b: RowButton): this { this._buttons.clone = b; return this }
+
+  /** Customize the per-row trash button. */
+  deleteAction(b: RowButton): this { this._buttons.delete = b; return this }
+
+  /** Customize the per-row Up arrow. */
+  moveUpAction(b: RowButton): this { this._buttons.moveUp = b; return this }
+
+  /** Customize the per-row Down arrow. */
+  moveDownAction(b: RowButton): this { this._buttons.moveDown = b; return this }
+
+  /**
+   * Customize the drag-grip handle (label → aria-label, tooltip → title,
+   * icon swaps the glyph, color re-tones the handle). The grip isn't a
+   * real `<button>` so click semantics don't apply.
+   */
+  reorderAction(b: RowButton): this { this._buttons.reorder = b; return this }
+
+  /** Customize the per-row collapse chevron. */
+  collapseAction(b: RowButton): this { this._buttons.collapse = b; return this }
+
+  // ─── Read-only access ────────────────────────────────
+
+  override getChildren(): undefined {
+    // Builder rows are addressed per-row via `getBlocks()` + dotted paths.
+    // Never return them as flat children — the parent walkers must stop
+    // at the Builder boundary, just like RepeaterField.
+    return undefined
+  }
+
+  getBlocks(): Block[]                          { return this._blocks }
+  getBlock(name: string): Block | undefined     { return this._blocksByName.get(name) }
+  getMinItems():                  number | undefined { return this._minItems       }
+  getMaxItems():                  number | undefined { return this._maxItems       }
+  getDefaultBlock():              string | undefined { return this._defaultBlock   }
+  isReorderable():                boolean            { return this._reorderable    }
+  isReorderableWithButtons():     boolean            { return this._reorderableWithButtons }
+  isCollapsible():                boolean            { return this._collapsible    }
+  isDefaultCollapsed():           boolean            { return this._defaultCollapsed }
+  isAccordion():                  boolean            { return this._accordion      }
+  isCloneable():                  boolean            { return this._cloneable      }
+  isAddable():                    boolean            { return this._addable        }
+  isDeletable():                  boolean            { return this._deletable      }
+  isAddBetween():                 boolean            { return this._addBetween     }
+  showsBlockNumbers():            boolean            { return this._blockNumbers || this._itemNumbers }
+  showsBlockIcons():              boolean            { return this._blockIcons     }
+  getBlockPickerColumns():        number | undefined { return this._blockPickerColumns }
+  getAddActionLabel():            string | undefined { return this._addActionLabel }
+  getAddActionAlignment():        BuilderAddActionAlignment { return this._addActionAlignment }
+  getItemLabel():                 BuilderItemLabel | undefined      { return this._itemLabel  }
+  getItemHidden():                BuilderItemHiddenRule | undefined { return this._itemHidden }
+  getItemCanDelete():             BuilderItemCanRule    | undefined { return this._itemCanDelete  }
+  getItemCanClone():              BuilderItemCanRule    | undefined { return this._itemCanClone   }
+  getItemCanReorder():            BuilderItemCanRule    | undefined { return this._itemCanReorder }
+  getExtraItemActions():          Action[]                          { return this._extraItemActions }
+  getGrid():                      RepeaterGridConfig | undefined    { return this._grid }
+  /** Resolved relationship config (`undefined` when not configured). */
+  getRelationship():              BuilderRelationshipConfig | undefined { return this._relationship }
+  isRelationship():               boolean                           { return this._relationship !== undefined }
+  /** The configured customizer for a given slot, or `undefined`. */
+  getButton(kind: RowButtonKind): RowButton | undefined             { return this._buttons[kind] }
+
+  // ─── Meta ────────────────────────────────────────────
+
+  /**
+   * Bare meta — `rows` and per-row resolved children are populated by
+   * `resolveBuilderRows` in `schema/resolveSchema.ts`. The `blocks` array
+   * (picker entries) ships unconditionally; the picker UI needs it before
+   * the user has added any rows.
+   */
+  override toMeta(ctx?: RenderContext): BuilderFieldMeta {
+    const base = this.buildMeta(ctx)
+    const meta: BuilderFieldMeta = {
+      ...base,
+      fieldType: 'builder',
+      rows:      [],
+      blocks:    this._blocks.map(b => b.toMeta()),
+    }
+    if (this._minItems          !== undefined) meta.minItems          = this._minItems
+    if (this._maxItems          !== undefined) meta.maxItems          = this._maxItems
+    if (this._defaultBlock      !== undefined) meta.defaultBlock      = this._defaultBlock
+    if (this._reorderable)                     meta.reorderable       = true
+    if (this._reorderableWithButtons)          meta.reorderableWithButtons = true
+    if (this._collapsible)                     meta.collapsible       = true
+    if (this._defaultCollapsed)                meta.defaultCollapsed  = true
+    if (this._accordion)                       meta.accordion         = true
+    if (this._cloneable)                       meta.cloneable         = true
+    if (this._addable === false)               meta.addable           = false
+    if (this._deletable === false)             meta.deletable         = false
+    if (this._addBetween)                      meta.addBetween        = true
+    if (this._blockNumbers)                    meta.blockNumbers      = true
+    if (this._blockIcons === false)            meta.blockIcons        = false
+    if (this._itemNumbers)                     meta.itemNumbers       = true
+    if (this._blockPickerColumns !== undefined) meta.blockPickerColumns = this._blockPickerColumns
+    if (this._addActionLabel    !== undefined) meta.addActionLabel    = this._addActionLabel
+    if (this._addActionAlignment !== 'start')  meta.addActionAlignment = this._addActionAlignment
+    if (this._grid              !== undefined) meta.grid              = this._grid
+    if (this._relationship      !== undefined) {
+      const r: BuilderRelationshipMeta = { name: this._relationship.name }
+      if (this._relationship.typeColumn  !== undefined) r.typeColumn  = this._relationship.typeColumn
+      if (this._relationship.dataColumn  !== undefined) r.dataColumn  = this._relationship.dataColumn
+      if (this._relationship.orderColumn !== undefined) r.orderColumn = this._relationship.orderColumn
+      meta.relationship = r
+    }
+    const buttons = serializeRowButtons(this._buttons)
+    if (buttons !== undefined)                 meta.buttons           = buttons
+    return meta
+  }
+}
+
+export const Builder = BuilderField
+
+/**
+ * Structural Builder check — Vite's SSR module cache can load this
+ * package via two paths during a single dev session, so `instanceof
+ * BuilderField` can silently return false across module copies. The
+ * structural check matches `getType() === 'field'` (Field's discriminator)
+ * + `fieldType === 'builder'`. Same posture as `isRepeaterField`.
+ */
+export function isBuilderField(el: { getType(): string; fieldType?: string }): boolean {
+  return el.getType() === 'field' && el['fieldType'] === 'builder'
+}