@mmapp/react 0.1.0-alpha.1 → 0.1.0-alpha.3

package/src/builders.ts

@@ -1,1342 +0,0 @@
-/**
- * @mindmatrix/react/builders — Fluent builder API for ModelDefinition objects.
- *
- * Provides a chainable API for constructing workflow models, fields, states,
- * and transitions without deeply nested object literals.
- *
- * @example
- * ```typescript
- * import { model, field, state, transition } from '@mindmatrix/react/builders';
- *
- * export default model('invoice')
- *   .version('1.0.0')
- *   .category('data')
- *   .field('amount', field.currency().required().min(0))
- *   .field('status', field.enum('draft', 'sent', 'paid').default('draft'))
- *   .state('draft', state.initial())
- *   .state('sent')
- *   .state('paid', state.end())
- *   .transition('send', transition.from('draft').to('sent').require('amount'))
- *   .transition('pay', transition.from('sent').to('paid').auto().when('state_data.paymentReceived == true'))
- *   .build();
- * ```
- */
-
-import {
-  defineModel,
-  type ModelDefinition,
-  type WorkflowFieldDescriptor,
-  type FieldValidation,
-  type ValidationRule,
-  type StateHome,
-  type ActionDefinition,
-  type EventSubscription,
-  type DuringAction,
-  type StateDescriptor,
-  type TransitionCondition,
-  type TransitionDescriptor,
-  type RoleDefinition,
-} from './config/defineModel';
-
-// =============================================================================
-// ActionContext — typed context for inline action bodies
-// =============================================================================
-
-/**
- * Context object passed to inline action handler functions.
- *
- * Methods map to action compositions in the IR — the compiler translates
- * the function body into an action pipeline. At SDK level, the function
- * reference is stored as an `inline_handler` action definition.
- *
- * @example
- * ```typescript
- * .onEnter(async (ctx) => {
- *   ctx.setField("activatedAt", new Date().toISOString());
- *   ctx.log("User activated");
- *   await ctx.notify("admin", "New user activated");
- * })
- * ```
- */
-export interface ActionContext {
-  /** Set a single field value. */
-  setField(field: string, value: unknown): void;
-  /** Set multiple field values at once. */
-  setFields(fields: Record<string, unknown>): void;
-  /** Emit a log entry to the workflow audit trail. */
-  log(message: string, data?: Record<string, unknown>): void;
-  /** Send a notification to a recipient. */
-  notify(recipient: string, message: string, data?: Record<string, unknown>): Promise<void>;
-  /** Spawn a child workflow instance. */
-  spawn(slug: string, input?: Record<string, unknown>): Promise<void>;
-  /** Execute a named server-side action. */
-  serverAction(name: string, config?: Record<string, unknown>): Promise<unknown>;
-}
-
-/** Handler function type for inline action bodies. */
-export type ActionHandler = (ctx: ActionContext) => void | Promise<void>;
-
-/**
- * Convert an ActionHandler to an ActionDefinition for IR storage.
- * The function body is stored as a string; the compiler handles actual compilation.
- * @internal
- */
-function handlerToAction(handler: ActionHandler, qualifier: string): ActionDefinition {
-  return {
-    id: `inline-${qualifier}-${Math.random().toString(36).slice(2, 8)}`,
-    type: 'inline_handler',
-    mode: 'auto',
-    config: {
-      handler: handler.toString(),
-    },
-  };
-}
-
-// =============================================================================
-// FieldBuilder
-// =============================================================================
-
-/**
- * Fluent builder for WorkflowFieldDescriptor objects.
- *
- * Use the `field.*` factory functions to create instances:
- * ```typescript
- * field.string('hello')       // string field with default
- * field.number()              // number field
- * field.enum('a', 'b', 'c')  // enum field
- * field.email().required()    // email field, required
- * ```
- */
-export class FieldBuilder<FT extends string = string> {
-  private _descriptor: WorkflowFieldDescriptor;
-  private _validation: FieldValidation = {};
-  private _rules: ValidationRule[] = [];
-
-  constructor(type: FT, defaultValue?: unknown) {
-    this._descriptor = { type };
-    if (defaultValue !== undefined) {
-      this._descriptor.default = defaultValue;
-    }
-  }
-
-  /** Mark the field as required. */
-  required(): this {
-    this._descriptor.required = true;
-    return this;
-  }
-
-  /** Set the default value. */
-  default(value: unknown): this {
-    this._descriptor.default = value;
-    return this;
-  }
-
-  /** Set the human-readable label. */
-  label(text: string): this {
-    this._descriptor.label = text;
-    return this;
-  }
-
-  /** Set the description / help text. */
-  description(text: string): this {
-    this._descriptor.description = text;
-    return this;
-  }
-
-  // --- Validation ---
-
-  /** Set the minimum numeric value. */
-  min(n: number): this {
-    this._validation.min = n;
-    return this;
-  }
-
-  /** Set the maximum numeric value. */
-  max(n: number): this {
-    this._validation.max = n;
-    return this;
-  }
-
-  /** Set the minimum string length. */
-  minLength(n: number): this {
-    this._validation.minLength = n;
-    return this;
-  }
-
-  /** Set the maximum string length. */
-  maxLength(n: number): this {
-    this._validation.maxLength = n;
-    return this;
-  }
-
-  /** Set a regex pattern the value must match. */
-  pattern(regex: string): this {
-    this._validation.pattern = regex;
-    return this;
-  }
-
-  /** Add a custom expression-based validation rule. */
-  validate(expression: string, message: string, severity?: 'error' | 'warning'): this {
-    this._rules.push({ expression, message, severity });
-    return this;
-  }
-
-  // --- ACL ---
-
-  /** Restrict field visibility to specific states. */
-  visibleIn(...states: string[]): this {
-    this._descriptor.visibleInStates = states;
-    return this;
-  }
-
-  /** Restrict field editability to specific states. */
-  editableIn(...states: string[]): this {
-    this._descriptor.editableInStates = states;
-    return this;
-  }
-
-  /** Restrict field visibility to specific roles. */
-  visibleTo(...roles: string[]): this {
-    this._descriptor.visibleToRoles = roles;
-    return this;
-  }
-
-  /** Restrict field editability to specific roles. */
-  editableBy(...roles: string[]): this {
-    this._descriptor.editableByRoles = roles;
-    return this;
-  }
-
-  /** Set an expression that controls visibility at runtime. */
-  visibleWhen(expression: string): this {
-    this._descriptor.visibleWhen = expression;
-    return this;
-  }
-
-  /** Set an expression that controls editability at runtime. */
-  editableWhen(expression: string): this {
-    this._descriptor.editableWhen = expression;
-    return this;
-  }
-
-  // --- Computed ---
-
-  /** Make this a computed field with the given expression and optional deps. */
-  computed(expression: string, deps?: string[]): this {
-    this._descriptor.computed = expression;
-    if (deps) {
-      this._descriptor.computedDeps = deps;
-    }
-    return this;
-  }
-
-  // --- State Home ---
-
-  /** Set the state home configuration (scope, persistence, sync). */
-  stateHome(config: StateHome): this {
-    this._descriptor.stateHome = config;
-    return this;
-  }
-
-  /** Mark the field as ephemeral (UI-only, not persisted). */
-  ephemeral(): this {
-    this._descriptor.stateHome = { scope: 'ephemeral', persistence: 'none' };
-    return this;
-  }
-
-  /** Build the WorkflowFieldDescriptor with its literal type preserved. */
-  build(): WorkflowFieldDescriptor & { type: FT } {
-    const desc = { ...this._descriptor };
-    // Merge validation if any was set
-    const hasValidation =
-      this._validation.min !== undefined ||
-      this._validation.max !== undefined ||
-      this._validation.minLength !== undefined ||
-      this._validation.maxLength !== undefined ||
-      this._validation.pattern !== undefined ||
-      this._rules.length > 0;
-
-    if (hasValidation) {
-      const validation: FieldValidation = { ...this._validation };
-      if (this._rules.length > 0) {
-        validation.rules = this._rules;
-      }
-      desc.validation = validation;
-    }
-    return desc as WorkflowFieldDescriptor & { type: FT };
-  }
-}
-
-// --- FieldBuilder factory functions ---
-
-/**
- * Field builder namespace with factory functions for common field types.
- *
- * @example
- * ```typescript
- * field.string('hello')       // { type: 'string', default: 'hello' }
- * field.number()              // { type: 'number' }
- * field.email().required()    // { type: 'email', required: true }
- * field.enum('a', 'b', 'c')  // { type: 'string', enum: ['a', 'b', 'c'] }
- * ```
- */
-export const field = {
-  /** Create a string field. */
-  string(defaultValue?: string): FieldBuilder<'string'> {
-    return new FieldBuilder('string', defaultValue);
-  },
-
-  /** Create a number field. */
-  number(defaultValue?: number): FieldBuilder<'number'> {
-    return new FieldBuilder('number', defaultValue);
-  },
-
-  /** Create a boolean field. */
-  boolean(defaultValue?: boolean): FieldBuilder<'boolean'> {
-    return new FieldBuilder('boolean', defaultValue);
-  },
-
-  /** Create a currency field. */
-  currency(defaultValue?: number): FieldBuilder<'currency'> {
-    return new FieldBuilder('currency', defaultValue);
-  },
-
-  /** Create an email field. */
-  email(): FieldBuilder<'email'> {
-    return new FieldBuilder('email');
-  },
-
-  /** Create a URL field. */
-  url(): FieldBuilder<'url'> {
-    return new FieldBuilder('url');
-  },
-
-  /** Create a date field. */
-  date(): FieldBuilder<'date'> {
-    return new FieldBuilder('date');
-  },
-
-  /** Create a datetime field. */
-  datetime(): FieldBuilder<'datetime'> {
-    return new FieldBuilder('datetime');
-  },
-
-  /** Create an array field. */
-  array(): FieldBuilder<'array'> {
-    return new FieldBuilder('array');
-  },
-
-  /** Create an object field. */
-  object(defaultValue?: Record<string, unknown>): FieldBuilder<'object'> {
-    return new FieldBuilder('object', defaultValue);
-  },
-
-  /** Create an enum field with allowed values. */
-  enum(...values: string[]): FieldBuilder<'string'> {
-    const builder = new FieldBuilder('string');
-    (builder as unknown as { _descriptor: WorkflowFieldDescriptor })._descriptor.enum = values;
-    return builder;
-  },
-
-  /** Create a select field (alias for enum). */
-  select(...values: string[]): FieldBuilder<'string'> {
-    return field.enum(...values);
-  },
-};
-
-// =============================================================================
-// StateBuilder
-// =============================================================================
-
-/**
- * Fluent builder for StateDescriptor objects.
- *
- * Use the `state.*` factory functions for typed states:
- * ```typescript
- * state.initial()                           // { type: 'initial' }
- * state.end().onEnter([...actions])         // { type: 'end', onEnter: [...] }
- * new StateBuilder().description('...')     // regular state
- * ```
- */
-export class StateBuilder {
-  private _descriptor: StateDescriptor = {};
-  /** @internal Inline transitions declared via .to() */
-  private _inlineTransitions: Array<{
-    target: string;
-    name: string;
-    configure?: (t: TransitionBuilder) => TransitionBuilder;
-  }> = [];
-
-  constructor(type?: 'initial' | 'end' | 'cancelled') {
-    if (type) {
-      this._descriptor.type = type;
-    }
-  }
-
-  /**
-   * Declare an outgoing transition inline with the state.
-   * This is syntactic sugar — the transition is registered on the model when `.build()` is called.
-   *
-   * @param targetState - The state to transition to
-   * @param transitionName - The name of the transition
-   * @param configure - Optional configuration callback for conditions, actions, roles, etc.
-   *
-   * @example
-   * ```typescript
-   * .state('draft', state.initial()
-   *   .to('review', 'submit', t => t.require('amount'))
-   *   .to('cancelled', 'cancel')
-   * )
-   * ```
-   */
-  to(
-    targetState: string,
-    transitionName: string,
-    configure?: (t: TransitionBuilder) => TransitionBuilder,
-  ): this {
-    this._inlineTransitions.push({
-      target: targetState,
-      name: transitionName,
-      configure,
-    });
-    return this;
-  }
-
-  /**
-   * @internal Get inline transitions declared via .to(), resolved with the owning state name.
-   */
-  getInlineTransitions(fromState: string): Record<string, TransitionDescriptor> {
-    const result: Record<string, TransitionDescriptor> = {};
-    for (const t of this._inlineTransitions) {
-      const builder = new TransitionBuilder().from(fromState).to(t.target);
-      if (t.configure) t.configure(builder);
-      result[t.name] = builder.build();
-    }
-    return result;
-  }
-
-  /** Set the description. */
-  description(text: string): this {
-    this._descriptor.description = text;
-    return this;
-  }
-
-  /**
-   * Set onEnter actions or an inline handler function.
-   *
-   * @example
-   * ```typescript
-   * // Action definitions
-   * state.initial().onEnter(setField('status', '"active"'), logEvent('activated'))
-   *
-   * // Inline handler
-   * state.initial().onEnter(async (ctx) => {
-   *   ctx.setField('activatedAt', new Date().toISOString());
-   *   ctx.log('User activated');
-   * })
-   * ```
-   */
-  onEnter(handler: ActionHandler): this;
-  onEnter(...actions: ActionDefinition[]): this;
-  onEnter(...args: [ActionHandler] | ActionDefinition[]): this {
-    if (args.length === 1 && typeof args[0] === 'function') {
-      this._descriptor.onEnter = [handlerToAction(args[0] as ActionHandler, 'on-enter')];
-    } else {
-      this._descriptor.onEnter = args as ActionDefinition[];
-    }
-    return this;
-  }
-
-  /**
-   * Set onExit actions or an inline handler function.
-   *
-   * @example
-   * ```typescript
-   * .onExit(async (ctx) => {
-   *   ctx.log('Leaving state');
-   * })
-   * ```
-   */
-  onExit(handler: ActionHandler): this;
-  onExit(...actions: ActionDefinition[]): this;
-  onExit(...args: [ActionHandler] | ActionDefinition[]): this {
-    if (args.length === 1 && typeof args[0] === 'function') {
-      this._descriptor.onExit = [handlerToAction(args[0] as ActionHandler, 'on-exit')];
-    } else {
-      this._descriptor.onExit = args as ActionDefinition[];
-    }
-    return this;
-  }
-
-  /** Add an event subscription. */
-  onEvent(subscription: EventSubscription): this {
-    const existing = this._descriptor.onEvent
-      ? [...this._descriptor.onEvent]
-      : [];
-    existing.push(subscription);
-    this._descriptor.onEvent = existing;
-    return this;
-  }
-
-  /** Add a during (scheduled) action. */
-  during(action: DuringAction): this {
-    const existing = this._descriptor.during
-      ? [...this._descriptor.during]
-      : [];
-    existing.push(action);
-    this._descriptor.during = existing;
-    return this;
-  }
-
-  /** Set a timeout with fallback action or transition. */
-  timeout(duration: string, fallback: { action?: string; transition?: string }): this {
-    this._descriptor.timeout = { duration, fallback };
-    return this;
-  }
-
-  /** Build the StateDescriptor. */
-  build(): StateDescriptor {
-    return { ...this._descriptor };
-  }
-}
-
-// --- StateBuilder factory functions ---
-
-/**
- * State builder namespace with factory functions for typed states.
- */
-export const state = {
-  /** Create an initial state. */
-  initial(): StateBuilder {
-    return new StateBuilder('initial');
-  },
-
-  /** Create an end (terminal) state. */
-  end(): StateBuilder {
-    return new StateBuilder('end');
-  },
-
-  /** Create a cancelled (terminal) state. */
-  cancelled(): StateBuilder {
-    return new StateBuilder('cancelled');
-  },
-};
-
-// =============================================================================
-// TransitionBuilder
-// =============================================================================
-
-/**
- * Fluent builder for TransitionDescriptor objects.
- *
- * @example
- * ```typescript
- * transition.from('draft').to('sent').require('amount', 'recipient')
- * transition.from('sent', 'delivered').to('edited').when('context.actor_id == state_data.senderId')
- * ```
- */
-export class TransitionBuilder {
-  private _descriptor: Partial<TransitionDescriptor> = {};
-
-  /** Set source state(s). */
-  from(...states: string[]): this {
-    this._descriptor.from = states.length === 1 ? states[0] : states;
-    return this;
-  }
-
-  /** Set the target state. */
-  to(targetState: string): this {
-    this._descriptor.to = targetState;
-    return this;
-  }
-
-  /** Set the description. */
-  description(text: string): this {
-    this._descriptor.description = text;
-    return this;
-  }
-
-  /**
-   * Add guard conditions. Strings are treated as expression conditions.
-   *
-   * @example
-   * ```typescript
-   * .when('state_data.amount > 0')
-   * .when({ type: 'role', role: 'admin' })
-   * .when('input.email != null', { type: 'field', field: 'status', operator: 'eq', value: 'draft' })
-   * ```
-   */
-  when(...conditions: (TransitionCondition | string)[]): this {
-    const existing = this._descriptor.conditions
-      ? [...this._descriptor.conditions]
-      : [];
-    existing.push(...conditions);
-    this._descriptor.conditions = existing;
-    return this;
-  }
-
-  /**
-   * Add actions or an inline handler to execute on this transition.
-   *
-   * @example
-   * ```typescript
-   * // Action definitions
-   * .do(setField('status', '"approved"'), logEvent('approved'))
-   *
-   * // Inline handler
-   * .do(async (ctx) => {
-   *   ctx.setField('approvedAt', new Date().toISOString());
-   *   await ctx.notify('requester', 'Your request was approved');
-   * })
-   * ```
-   */
-  do(handler: ActionHandler): this;
-  do(...actions: ActionDefinition[]): this;
-  do(...args: [ActionHandler] | ActionDefinition[]): this {
-    const existing = this._descriptor.actions
-      ? [...this._descriptor.actions]
-      : [];
-    if (args.length === 1 && typeof args[0] === 'function') {
-      existing.push(handlerToAction(args[0] as ActionHandler, 'transition'));
-    } else {
-      existing.push(...(args as ActionDefinition[]));
-    }
-    this._descriptor.actions = existing;
-    return this;
-  }
-
-  /** Set the allowed roles. */
-  roles(...roles: string[]): this {
-    this._descriptor.roles = roles;
-    return this;
-  }
-
-  /** Set required fields that must have values before this transition fires. */
-  require(...fields: string[]): this {
-    this._descriptor.requiredFields = fields;
-    return this;
-  }
-
-  /** Mark this as an auto-transition (fires when conditions are met). */
-  auto(): this {
-    this._descriptor.auto = true;
-    return this;
-  }
-
-  /** Build the TransitionDescriptor. */
-  build(): TransitionDescriptor {
-    if (!this._descriptor.from) {
-      throw new Error('TransitionBuilder: from() is required');
-    }
-    if (!this._descriptor.to) {
-      throw new Error('TransitionBuilder: to() is required');
-    }
-    return this._descriptor as TransitionDescriptor;
-  }
-}
-
-// =============================================================================
-// TypedTransitionBuilder — constrains from/to to known state names
-// =============================================================================
-
-/**
- * A transition builder whose `.from()` and `.to()` methods only accept
- * state names that have been declared on the model.
- *
- * Obtained via the callback overload of `ModelBuilder.transition()`:
- * ```typescript
- * model('invoice')
- *   .state('draft', state.initial())
- *   .state('sent')
- *   .state('paid', state.end())
- *   .transition('send', t => t.from('draft').to('sent').require('amount'))
- *   //                   ^ t is TypedTransitionBuilder<'draft' | 'sent' | 'paid'>
- *   .build();
- * ```
- */
-export class TypedTransitionBuilder<S extends string> {
-  /** @internal Delegate to an untyped builder for the actual work. */
-  private _inner = new TransitionBuilder();
-
-  /** Set source state(s) — constrained to declared state names. */
-  from(...states: S[]): this {
-    this._inner.from(...states);
-    return this;
-  }
-
-  /** Set the target state — constrained to declared state names. */
-  to(targetState: S): this {
-    this._inner.to(targetState);
-    return this;
-  }
-
-  /** Set the description. */
-  description(text: string): this {
-    this._inner.description(text);
-    return this;
-  }
-
-  /** Add guard conditions. */
-  when(...conditions: (TransitionCondition | string)[]): this {
-    this._inner.when(...conditions);
-    return this;
-  }
-
-  /** Add actions or an inline handler. */
-  do(handler: ActionHandler): this;
-  do(...actions: ActionDefinition[]): this;
-  do(...args: [ActionHandler] | ActionDefinition[]): this {
-    (this._inner.do as (...a: unknown[]) => TransitionBuilder)(...args);
-    return this;
-  }
-
-  /** Set allowed roles. */
-  roles(...roles: string[]): this {
-    this._inner.roles(...roles);
-    return this;
-  }
-
-  /** Set required fields. */
-  require(...fields: string[]): this {
-    this._inner.require(...fields);
-    return this;
-  }
-
-  /** Mark as auto-transition. */
-  auto(): this {
-    this._inner.auto();
-    return this;
-  }
-
-  /** Build the TransitionDescriptor. */
-  build(): TransitionDescriptor {
-    return this._inner.build();
-  }
-}
-
-// --- TransitionBuilder factory function ---
-
-/**
- * Transition builder namespace with the `from()` entry point.
- */
-export const transition = {
-  /** Start building a transition from the given source state(s). */
-  from(...states: string[]): TransitionBuilder {
-    return new TransitionBuilder().from(...states);
-  },
-};
-
-// =============================================================================
-// ModelBuilder
-// =============================================================================
-
-/**
- * Fluent builder for ModelDefinition objects.
- *
- * @example
- * ```typescript
- * const authModel = model('mod-authentication')
- *   .version('2.0.0')
- *   .category('module')
- *   .field('appName', field.string(''))
- *   .field('layout', field.enum('card', 'split', 'minimal').default('card'))
- *   .state('unauthenticated', state.initial().onEnter(clearError))
- *   .state('authenticated')
- *   .transition('login', transition.from('unauthenticated').to('authenticating'))
- *   .build();
- * ```
- */
-export class ModelBuilder<
-  F extends Record<string, { type: string }> = {},
-  S extends string = never,
-  T extends string = never,
-> {
-  private _slug: string;
-  private _version?: string;
-  private _name?: string;
-  private _description?: string;
-  private _category?: string | readonly string[];
-  private _tags?: string[];
-  private _fields: Record<string, WorkflowFieldDescriptor> = {};
-  private _states: Record<string, StateDescriptor> = {};
-  private _transitions: Record<string, TransitionDescriptor> = {};
-  private _roles?: Record<string, RoleDefinition>;
-  private _metadata?: Record<string, unknown>;
-  private _onEvent?: EventSubscription[];
-  private _mixins: Array<(def: ModelDefinition) => ModelDefinition> = [];
-
-  constructor(slug: string) {
-    this._slug = slug;
-  }
-
-  /** Set the semantic version. */
-  version(v: string): ModelBuilder<F, S, T> {
-    this._version = v;
-    return this;
-  }
-
-  /** Set the display name. */
-  name(n: string): ModelBuilder<F, S, T> {
-    this._name = n;
-    return this;
-  }
-
-  /** Set the description. */
-  description(d: string): ModelBuilder<F, S, T> {
-    this._description = d;
-    return this;
-  }
-
-  /** Set the category (string or array of strings). */
-  category(c: string | string[]): ModelBuilder<F, S, T> {
-    this._category = c;
-    return this;
-  }
-
-  /** Add tags. */
-  tags(...tagList: string[]): ModelBuilder<F, S, T> {
-    if (!this._tags) {
-      this._tags = [];
-    }
-    this._tags.push(...tagList);
-    return this;
-  }
-
-  /**
-   * Add a field. Accepts a WorkflowFieldDescriptor object or a FieldBuilder.
-   * The field type is tracked for type inference with `useModel()`.
-   *
-   * @example
-   * ```typescript
-   * .field('email', { type: 'email', required: true })
-   * .field('name', field.string().required().maxLength(100))
-   * ```
-   */
-  field<N extends string, FT extends string>(
-    name: N,
-    descriptor: (WorkflowFieldDescriptor & { type: FT }) | FieldBuilder<FT>,
-  ): ModelBuilder<F & Record<N, { type: FT }>, S, T> {
-    this._fields[name] = descriptor instanceof FieldBuilder
-      ? descriptor.build()
-      : descriptor;
-    return this as unknown as ModelBuilder<F & Record<N, { type: FT }>, S, T>;
-  }
-
-  /**
-   * Add a state. Accepts an optional StateDescriptor or StateBuilder.
-   * If no descriptor is provided, creates an empty state.
-   *
-   * @example
-   * ```typescript
-   * .state('draft', state.initial())
-   * .state('active')
-   * .state('done', state.end())
-   * .state('error', { timeout: { duration: '5m', fallback: { transition: 'retry' } } })
-   * ```
-   */
-  state<N extends string>(
-    name: N,
-    descriptor?: StateDescriptor | StateBuilder,
-  ): ModelBuilder<F, S | N, T> {
-    if (descriptor === undefined) {
-      this._states[name] = {};
-    } else if (descriptor instanceof StateBuilder) {
-      this._states[name] = descriptor.build();
-      // Extract inline transitions declared via .to()
-      const inlineTransitions = descriptor.getInlineTransitions(name);
-      for (const [tName, tDesc] of Object.entries(inlineTransitions)) {
-        // Standalone transitions win over inline (more explicit)
-        if (!this._transitions[tName]) {
-          this._transitions[tName] = tDesc;
-        }
-      }
-    } else {
-      this._states[name] = descriptor;
-    }
-    return this as unknown as ModelBuilder<F, S | N, T>;
-  }
-
-  /**
-   * Add a transition. Accepts a TransitionDescriptor, TransitionBuilder, or
-   * a callback that receives a `TypedTransitionBuilder` constrained to known state names.
-   *
-   * The callback form provides type-safe `.from()` and `.to()` — only state names
-   * already declared via `.state()` are accepted.
-   *
-   * @example
-   * ```typescript
-   * // Untyped (existing API — any string accepted)
-   * .transition('send', transition.from('draft').to('sent').require('amount'))
-   * .transition('approve', { from: 'review', to: 'approved', roles: ['admin'] })
-   *
-   * // Type-safe callback (only declared states accepted)
-   * .state('draft', state.initial())
-   * .state('sent')
-   * .transition('send', t => t.from('draft').to('sent').require('amount'))
-   * //                   ^ autocomplete shows 'draft' | 'sent'
-   * ```
-   */
-  transition<N extends string>(
-    name: N,
-    descriptor: TransitionDescriptor | TransitionBuilder | ((t: TypedTransitionBuilder<S>) => TypedTransitionBuilder<S>),
-  ): ModelBuilder<F, S, T | N> {
-    if (typeof descriptor === 'function') {
-      const typed = new TypedTransitionBuilder<S>();
-      descriptor(typed);
-      this._transitions[name] = typed.build();
-    } else if (descriptor instanceof TransitionBuilder) {
-      this._transitions[name] = descriptor.build();
-    } else {
-      this._transitions[name] = descriptor;
-    }
-    return this as unknown as ModelBuilder<F, S, T | N>;
-  }
-
-  /** Add a role definition. */
-  role(name: string, def: RoleDefinition): ModelBuilder<F, S, T> {
-    if (!this._roles) {
-      this._roles = {};
-    }
-    this._roles[name] = def;
-    return this;
-  }
-
-  /** Add a model-level event subscription. */
-  onEvent(subscription: EventSubscription): ModelBuilder<F, S, T> {
-    if (!this._onEvent) {
-      this._onEvent = [];
-    }
-    this._onEvent.push(subscription);
-    return this;
-  }
-
-  /** Set arbitrary metadata. */
-  meta(key: string, value: unknown): ModelBuilder<F, S, T> {
-    if (!this._metadata) {
-      this._metadata = {};
-    }
-    this._metadata[key] = value;
-    return this;
-  }
-
-  /**
-   * Apply a mixin function that transforms the built ModelDefinition.
-   * Mixins are applied in order after all other properties are set.
-   */
-  mixin(fn: (def: ModelDefinition) => ModelDefinition): ModelBuilder<F, S, T> {
-    this._mixins.push(fn);
-    return this;
-  }
-
-  /**
-   * Declare a linear sequence of states (an "execution line").
-   *
-   * Every element is a state. Transitions between consecutive states are auto-generated
-   * with names like `draft_to_review`. Use tuples to configure states or the edge
-   * leading INTO that state.
-   *
-   * Multiple `.line()` calls combine to form the full state machine graph.
-   * States appearing in multiple lines are the same state.
-   *
-   * @example Simple linear flow:
-   * ```typescript
-   * model('order')
-   *   .line('placed', 'confirmed', 'shipped', 'delivered')
-   *   .line('placed', 'cancelled')  // branch
-   *   .build()
-   * // Transitions: placed_to_confirmed, confirmed_to_shipped, shipped_to_delivered, placed_to_cancelled
-   * ```
-   *
-   * @example With state and edge configuration:
-   * ```typescript
-   * .line(
-   *   ['draft', state.initial()],                    // state with descriptor
-   *   ['review', t => t.require('title')],           // edge draft→review requires 'title'
-   *   ['published', t => t.roles('editor')],         // edge review→published requires 'editor' role
-   * )
-   * ```
-   *
-   * @example Named transitions (use tuple with string to override auto-name):
-   * ```typescript
-   * .line(
-   *   'draft',
-   *   ['review', 'submit'],                          // name this edge 'submit' instead of 'draft_to_review'
-   *   ['published', 'approve', t => t.roles('mgr')], // named + configured
-   * )
-   * ```
-   */
-  line(
-    ...elements: Array<
-      | string
-      | [string, StateBuilder]
-      | [string, StateDescriptor]
-      | [string, (t: TransitionBuilder) => TransitionBuilder]
-      | [string, string]
-      | [string, string, (t: TransitionBuilder) => TransitionBuilder]
-    >
-  ): ModelBuilder<F, S, T> {
-    // Every element is a state (possibly with config).
-    // Tuples:
-    //   [name, StateBuilder]       → state with descriptor
-    //   [name, fn]                 → state + configure INCOMING edge
-    //   [name, string]             → state + name for INCOMING edge
-    //   [name, string, fn]         → state + named + configured INCOMING edge
-    const nodes: Array<{
-      name: string;
-      stateConfig?: StateBuilder | StateDescriptor;
-      edgeConfig?: (t: TransitionBuilder) => TransitionBuilder;
-      edgeName?: string;
-    }> = [];
-
-    for (const el of elements) {
-      if (Array.isArray(el)) {
-        const [name, second, third] = el as [string, unknown, unknown];
-        if (second instanceof StateBuilder) {
-          nodes.push({ name, stateConfig: second });
-        } else if (typeof second === 'function') {
-          nodes.push({ name, edgeConfig: second as (t: TransitionBuilder) => TransitionBuilder });
-        } else if (typeof second === 'string') {
-          // [name, edgeName] or [name, edgeName, configFn]
-          const configFn = typeof third === 'function'
-            ? third as (t: TransitionBuilder) => TransitionBuilder
-            : undefined;
-          nodes.push({ name, edgeName: second, edgeConfig: configFn });
-        } else if (typeof second === 'object' && second !== null) {
-          nodes.push({ name, stateConfig: second as StateDescriptor });
-        } else {
-          nodes.push({ name });
-        }
-      } else {
-        nodes.push({ name: el });
-      }
-    }
-
-    // Register states
-    for (const node of nodes) {
-      if (!this._states[node.name]) {
-        if (node.stateConfig instanceof StateBuilder) {
-          this._states[node.name] = node.stateConfig.build();
-        } else if (node.stateConfig) {
-          this._states[node.name] = node.stateConfig;
-        } else {
-          this._states[node.name] = {};
-        }
-      } else if (node.stateConfig instanceof StateBuilder) {
-        Object.assign(this._states[node.name], node.stateConfig.build());
-      } else if (node.stateConfig) {
-        Object.assign(this._states[node.name], node.stateConfig);
-      }
-    }
-
-    // Register transitions (edges between consecutive states)
-    for (let i = 0; i < nodes.length - 1; i++) {
-      const from = nodes[i];
-      const to = nodes[i + 1];
-      const transitionName = to.edgeName || `${from.name}_to_${to.name}`;
-
-      const existing = this._transitions[transitionName];
-      if (existing) {
-        // Merge from states
-        const existingFrom = Array.isArray(existing.from) ? [...existing.from] : [existing.from];
-        if (!existingFrom.includes(from.name)) {
-          existingFrom.push(from.name);
-          existing.from = existingFrom.length === 1 ? existingFrom[0] : existingFrom;
-        }
-      } else {
-        const builder = new TransitionBuilder().from(from.name).to(to.name);
-        if (to.edgeConfig) {
-          to.edgeConfig(builder);
-        }
-        this._transitions[transitionName] = builder.build();
-      }
-    }
-
-    return this;
-  }
-
-  /**
-   * Build the final ModelDefinition with full type information preserved.
-   * The returned type carries field types, state names, and transition names
-   * so that `useModel()` and `useCollection()` can provide full IntelliSense.
-   */
-  build(): ModelDefinition & {
-    fields: F;
-    states: Record<S, StateDescriptor>;
-    transitions: Record<T, TransitionDescriptor>;
-  } {
-    let def: ModelDefinition = {
-      slug: this._slug,
-      fields: this._fields,
-      states: this._states,
-      transitions: this._transitions,
-    };
-
-    if (this._version !== undefined) def.version = this._version;
-    if (this._name !== undefined) def.name = this._name;
-    if (this._description !== undefined) def.description = this._description;
-    if (this._category !== undefined) def.category = this._category;
-    if (this._tags !== undefined) def.tags = this._tags;
-    if (this._roles !== undefined) def.roles = this._roles;
-    if (this._metadata !== undefined) def.metadata = this._metadata;
-    if (this._onEvent !== undefined) def.onEvent = this._onEvent;
-
-    // Apply mixins
-    for (const mixin of this._mixins) {
-      def = mixin(def);
-    }
-
-    return defineModel(def) as ModelDefinition & {
-      fields: F;
-      states: Record<S, StateDescriptor>;
-      transitions: Record<T, TransitionDescriptor>;
-    };
-  }
-}
-
-// --- ModelBuilder entry function ---
-
-/**
- * Create a new ModelBuilder for the given slug.
- *
- * @example
- * ```typescript
- * import { model, field, state, transition } from '@mindmatrix/react/builders';
- *
- * export default model('my-model')
- *   .version('1.0.0')
- *   .field('name', field.string().required())
- *   .state('active', state.initial())
- *   .state('done', state.end())
- *   .transition('finish', transition.from('active').to('done'))
- *   .build();
- * ```
- */
-export function model(slug: string): ModelBuilder<{}, never, never> {
-  return new ModelBuilder(slug);
-}
-
-// =============================================================================
-// Factory Functions (Patterns)
-// =============================================================================
-
-/**
- * Pipeline stage configuration for `createPipeline`.
- */
-export interface PipelineStage {
-  /** Stage name (becomes a state). */
-  name: string;
-  /** Actions to run when entering this stage. */
-  onEnter?: ActionDefinition[];
-  /** Actions to run when exiting this stage. */
-  onExit?: ActionDefinition[];
-  /** Auto-transition condition expression (advances to next stage when truthy). */
-  advanceWhen?: string;
-}
-
-/**
- * Configuration for the `createPipeline` factory.
- */
-export interface PipelineConfig {
-  /** Workflow slug. */
-  slug: string;
-  /** Semantic version. */
-  version?: string;
-  /** Field definitions. */
-  fields: Record<string, WorkflowFieldDescriptor>;
-  /** Ordered list of pipeline stages. */
-  stages: PipelineStage[];
-  /** Failure handling configuration. */
-  onFailure?: {
-    /** Actions to run on failure. */
-    actions?: ActionDefinition[];
-    /** Whether to allow retrying from the failed state. */
-    allowRetry?: boolean;
-  };
-}
-
-/**
- * Create a linear pipeline model — a chain of auto-transitioning states.
- *
- * Each stage becomes a state, with auto-transitions between consecutive stages.
- * An optional `failed` state is added if `onFailure` is configured.
- *
- * @example
- * ```typescript
- * const pipeline = createPipeline({
- *   slug: 'data-import',
- *   fields: {
- *     source: { type: 'string', required: true },
- *     result: { type: 'object', default: null },
- *     error: { type: 'string', default: '' },
- *   },
- *   stages: [
- *     { name: 'validating', onEnter: [validateAction] },
- *     { name: 'transforming', advanceWhen: 'state_data.validated == true' },
- *     { name: 'loading', advanceWhen: 'state_data.loaded == true' },
- *     { name: 'complete' },
- *   ],
- *   onFailure: { allowRetry: true },
- * });
- * ```
- */
-export function createPipeline(config: PipelineConfig): ModelDefinition {
-  const { slug, version, fields, stages, onFailure } = config;
-
-  if (stages.length < 2) {
-    throw new Error(`createPipeline(${slug}): requires at least 2 stages`);
-  }
-
-  const states: Record<string, StateDescriptor> = {};
-  const transitions: Record<string, TransitionDescriptor> = {};
-
-  // Build states
-  for (let i = 0; i < stages.length; i++) {
-    const stg = stages[i];
-    const desc: StateDescriptor = {};
-
-    if (i === 0) desc.type = 'initial';
-    if (i === stages.length - 1) desc.type = 'end';
-    if (stg.onEnter) desc.onEnter = stg.onEnter;
-    if (stg.onExit) desc.onExit = stg.onExit;
-
-    states[stg.name] = desc;
-  }
-
-  // Build auto-transitions between consecutive stages
-  for (let i = 0; i < stages.length - 1; i++) {
-    const from = stages[i];
-    const to = stages[i + 1];
-    const transName = `advance_${from.name}_to_${to.name}`;
-    const trans: TransitionDescriptor = {
-      from: from.name,
-      to: to.name,
-      auto: true,
-    };
-    if (from.advanceWhen) {
-      trans.conditions = [{ type: 'expression', expression: from.advanceWhen }];
-    }
-    transitions[transName] = trans;
-  }
-
-  // Add failed state + transitions if configured
-  if (onFailure) {
-    const failedDesc: StateDescriptor = { type: 'end' };
-    if (onFailure.actions) {
-      failedDesc.onEnter = onFailure.actions;
-    }
-    states['failed'] = failedDesc;
-
-    // Every non-terminal stage can fail
-    const failSources = stages
-      .filter((_, i) => i < stages.length - 1)
-      .map((s) => s.name);
-
-    transitions['fail'] = {
-      from: failSources,
-      to: 'failed',
-    };
-
-    if (onFailure.allowRetry) {
-      // Override failed to not be terminal so retry works
-      states['failed'] = { ...failedDesc, type: undefined };
-      transitions['retry'] = {
-        from: 'failed',
-        to: stages[0].name,
-      };
-    }
-  }
-
-  return defineModel({
-    slug,
-    version,
-    fields,
-    states,
-    transitions,
-  });
-}
-
-/**
- * Configuration for the `createCRUD` factory.
- */
-export interface CRUDConfig {
-  /** Workflow slug. */
-  slug: string;
-  /** Semantic version. */
-  version?: string;
-  /** Field definitions. */
-  fields: Record<string, WorkflowFieldDescriptor>;
-  /** Use soft delete (archived state) instead of hard delete. Default: true. */
-  softDelete?: boolean;
-  /** Role definitions. */
-  roles?: Record<string, RoleDefinition>;
-}
-
-/**
- * Create a standard CRUD model with draft/active/archived lifecycle.
- *
- * States: `draft` (initial) -> `active` -> `archived` (if softDelete) or `deleted` (end).
- * Transitions: `publish`, `update` (self-loop), `archive`/`delete`, `restore` (from archived).
- *
- * @example
- * ```typescript
- * const product = createCRUD({
- *   slug: 'product',
- *   fields: {
- *     name: { type: 'string', required: true },
- *     price: { type: 'currency', required: true, validation: { min: 0 } },
- *     sku: { type: 'string', required: true },
- *   },
- *   softDelete: true,
- *   roles: {
- *     admin: { permissions: ['manage'] },
- *     editor: { permissions: ['read', 'write'] },
- *   },
- * });
- * ```
- */
-export function createCRUD(config: CRUDConfig): ModelDefinition {
-  const { slug, version, fields, softDelete = true, roles } = config;
-
-  const states: Record<string, StateDescriptor> = {
-    draft: { type: 'initial' },
-    active: {},
-  };
-
-  const transitions: Record<string, TransitionDescriptor> = {
-    publish: {
-      from: 'draft',
-      to: 'active',
-    },
-    update: {
-      from: 'active',
-      to: 'active',
-    },
-  };
-
-  if (softDelete) {
-    states['archived'] = {};
-    transitions['archive'] = {
-      from: 'active',
-      to: 'archived',
-    };
-    transitions['restore'] = {
-      from: 'archived',
-      to: 'active',
-    };
-  } else {
-    states['deleted'] = { type: 'end' };
-    transitions['delete'] = {
-      from: ['draft', 'active'],
-      to: 'deleted',
-    };
-  }
-
-  return defineModel({
-    slug,
-    version,
-    fields,
-    states,
-    transitions,
-    roles,
-  });
-}