@mmapp/player-core 0.1.0-alpha.1

package/src/expression/functions.ts

@@ -0,0 +1,214 @@
+/**
+ * Core Expression Functions — 31 functions across 6 categories.
+ *
+ * These are the standard functions available in every player context.
+ * Platform-specific functions ($domain, $fe_ref, etc.) are registered
+ * separately by the host environment.
+ */
+
+import type { ExpressionFunction } from './types';
+
+// =============================================================================
+// Math (8 functions)
+// =============================================================================
+
+const add: ExpressionFunction = {
+  name: 'add', fn: (a: unknown, b: unknown) => Number(a) + Number(b), arity: 2,
+};
+const subtract: ExpressionFunction = {
+  name: 'subtract', fn: (a: unknown, b: unknown) => Number(a) - Number(b), arity: 2,
+};
+const multiply: ExpressionFunction = {
+  name: 'multiply', fn: (a: unknown, b: unknown) => Number(a) * Number(b), arity: 2,
+};
+const divide: ExpressionFunction = {
+  name: 'divide', fn: (a: unknown, b: unknown) => {
+    const d = Number(b);
+    return d === 0 ? 0 : Number(a) / d;
+  }, arity: 2,
+};
+const abs: ExpressionFunction = {
+  name: 'abs', fn: (a: unknown) => Math.abs(Number(a)), arity: 1,
+};
+const round: ExpressionFunction = {
+  name: 'round', fn: (a: unknown, decimals?: unknown) => {
+    const d = decimals != null ? Number(decimals) : 0;
+    const factor = Math.pow(10, d);
+    return Math.round(Number(a) * factor) / factor;
+  }, arity: -1,
+};
+const min: ExpressionFunction = {
+  name: 'min', fn: (...args: unknown[]) => {
+    const nums = args.flat().map(Number).filter(n => !isNaN(n));
+    return nums.length === 0 ? 0 : Math.min(...nums);
+  }, arity: -1,
+};
+const max: ExpressionFunction = {
+  name: 'max', fn: (...args: unknown[]) => {
+    const nums = args.flat().map(Number).filter(n => !isNaN(n));
+    return nums.length === 0 ? 0 : Math.max(...nums);
+  }, arity: -1,
+};
+
+// =============================================================================
+// Comparison (6 functions)
+// =============================================================================
+
+const eq: ExpressionFunction = {
+  name: 'eq', fn: (a: unknown, b: unknown) => a === b || String(a) === String(b), arity: 2,
+};
+const neq: ExpressionFunction = {
+  name: 'neq', fn: (a: unknown, b: unknown) => a !== b && String(a) !== String(b), arity: 2,
+};
+const gt: ExpressionFunction = {
+  name: 'gt', fn: (a: unknown, b: unknown) => Number(a) > Number(b), arity: 2,
+};
+const gte: ExpressionFunction = {
+  name: 'gte', fn: (a: unknown, b: unknown) => Number(a) >= Number(b), arity: 2,
+};
+const lt: ExpressionFunction = {
+  name: 'lt', fn: (a: unknown, b: unknown) => Number(a) < Number(b), arity: 2,
+};
+const lte: ExpressionFunction = {
+  name: 'lte', fn: (a: unknown, b: unknown) => Number(a) <= Number(b), arity: 2,
+};
+
+// =============================================================================
+// Logic (5 functions)
+// =============================================================================
+
+const if_fn: ExpressionFunction = {
+  name: 'if', fn: (cond: unknown, then: unknown, else_: unknown) => cond ? then : else_, arity: 3,
+};
+const and: ExpressionFunction = {
+  name: 'and', fn: (...args: unknown[]) => args.every(Boolean), arity: -1,
+};
+const or: ExpressionFunction = {
+  name: 'or', fn: (...args: unknown[]) => args.some(Boolean), arity: -1,
+};
+const not: ExpressionFunction = {
+  name: 'not', fn: (a: unknown) => !a, arity: 1,
+};
+const coalesce: ExpressionFunction = {
+  name: 'coalesce', fn: (...args: unknown[]) => {
+    for (const arg of args) {
+      if (arg != null) return arg;
+    }
+    return null;
+  }, arity: -1,
+};
+
+// =============================================================================
+// String (6 functions)
+// =============================================================================
+
+const concat: ExpressionFunction = {
+  name: 'concat', fn: (...args: unknown[]) => args.map(String).join(''), arity: -1,
+};
+const upper: ExpressionFunction = {
+  name: 'upper', fn: (s: unknown) => String(s ?? '').toUpperCase(), arity: 1,
+};
+const lower: ExpressionFunction = {
+  name: 'lower', fn: (s: unknown) => String(s ?? '').toLowerCase(), arity: 1,
+};
+const trim: ExpressionFunction = {
+  name: 'trim', fn: (s: unknown) => String(s ?? '').trim(), arity: 1,
+};
+const format: ExpressionFunction = {
+  name: 'format', fn: (template: unknown, ...args: unknown[]) => {
+    let result = String(template ?? '');
+    args.forEach((arg, i) => {
+      result = result.replace(`{${i}}`, String(arg ?? ''));
+    });
+    return result;
+  }, arity: -1,
+};
+const length: ExpressionFunction = {
+  name: 'length', fn: (v: unknown) => {
+    if (Array.isArray(v)) return v.length;
+    if (typeof v === 'string') return v.length;
+    if (v && typeof v === 'object') return Object.keys(v).length;
+    return 0;
+  }, arity: 1,
+};
+
+// =============================================================================
+// Path (3 functions)
+// =============================================================================
+
+const get: ExpressionFunction = {
+  name: 'get', fn: (obj: unknown, path: unknown) => {
+    if (obj == null || typeof path !== 'string') return undefined;
+    const parts = path.split('.');
+    let current: unknown = obj;
+    for (const part of parts) {
+      if (current == null || typeof current !== 'object') return undefined;
+      current = (current as Record<string, unknown>)[part];
+    }
+    return current;
+  }, arity: 2,
+};
+const includes: ExpressionFunction = {
+  name: 'includes', fn: (collection: unknown, value: unknown) => {
+    if (Array.isArray(collection)) return collection.includes(value);
+    if (typeof collection === 'string') return collection.includes(String(value));
+    return false;
+  }, arity: 2,
+};
+const is_defined: ExpressionFunction = {
+  name: 'is_defined', fn: (v: unknown) => v !== undefined && v !== null, arity: 1,
+};
+
+// =============================================================================
+// Type (3 functions)
+// =============================================================================
+
+const is_empty: ExpressionFunction = {
+  name: 'is_empty', fn: (v: unknown) => {
+    if (v == null) return true;
+    if (typeof v === 'string') return v.length === 0;
+    if (Array.isArray(v)) return v.length === 0;
+    if (typeof v === 'object') return Object.keys(v).length === 0;
+    return false;
+  }, arity: 1,
+};
+const is_null: ExpressionFunction = {
+  name: 'is_null', fn: (v: unknown) => v === null || v === undefined, arity: 1,
+};
+const to_string: ExpressionFunction = {
+  name: 'to_string', fn: (v: unknown) => {
+    if (v == null) return '';
+    if (typeof v === 'object') return JSON.stringify(v);
+    return String(v);
+  }, arity: 1,
+};
+
+// =============================================================================
+// Export all 31 core functions
+// =============================================================================
+
+export const CORE_FUNCTIONS: ExpressionFunction[] = [
+  // Math (8)
+  add, subtract, multiply, divide, abs, round, min, max,
+  // Comparison (6)
+  eq, neq, gt, gte, lt, lte,
+  // Logic (5)
+  if_fn, and, or, not, coalesce,
+  // String (6)
+  concat, upper, lower, trim, format, length,
+  // Path (3)
+  get, includes, is_defined,
+  // Type (3)
+  is_empty, is_null, to_string,
+];
+
+/** Lookup map for O(1) function resolution */
+export function buildFunctionMap(
+  functions: ExpressionFunction[],
+): Map<string, ExpressionFunction['fn']> {
+  const map = new Map<string, ExpressionFunction['fn']>();
+  for (const fn of functions) {
+    map.set(fn.name, fn.fn);
+  }
+  return map;
+}

package/src/expression/index.ts

@@ -0,0 +1,13 @@
+export type {
+  ExpressionResult,
+  ExpressionDiagnostics,
+  FailurePolicy,
+  ExpressionContext,
+  ExpressionFunction,
+  EvaluatorConfig,
+  Evaluator,
+  FailurePolicyContext,
+} from './types';
+
+export { CORE_FUNCTIONS, buildFunctionMap } from './functions';
+export { createEvaluator, WEB_FAILURE_POLICIES, clearExpressionCache } from './evaluator';

package/src/expression/types.ts

@@ -0,0 +1,64 @@
+/**
+ * Expression Engine Types
+ *
+ * Defines the contract for expression evaluation across all player contexts.
+ * See player-specification.md §2.3 for full specification.
+ */
+
+/** Result of evaluating an expression */
+export interface ExpressionResult<T = unknown> {
+  value: T;
+  status: 'ok' | 'error' | 'fallback';
+  error?: string;
+  diagnostics?: ExpressionDiagnostics;
+}
+
+/** Diagnostic information for debugging expressions */
+export interface ExpressionDiagnostics {
+  expression: string;
+  duration_ms: number;
+  resolved_paths: string[];
+  unresolved_paths: string[];
+}
+
+/** Failure policy determines behavior when an expression fails */
+export interface FailurePolicy {
+  on_error: 'return_fallback' | 'throw' | 'log_and_skip';
+  fallback_value: unknown;
+  log_level: 'silent' | 'warn' | 'error';
+}
+
+/** Expression context for evaluation */
+export interface ExpressionContext {
+  [key: string]: unknown;
+}
+
+/** A registered function available in expressions */
+export interface ExpressionFunction {
+  name: string;
+  fn: (...args: unknown[]) => unknown;
+  arity?: number; // -1 means variadic
+  description?: string;
+}
+
+/** Configuration for createEvaluator factory */
+export interface EvaluatorConfig {
+  functions: ExpressionFunction[];
+  failurePolicy: FailurePolicy;
+  maxDepth?: number;
+  maxOperations?: number;
+}
+
+/** The evaluator interface returned by createEvaluator */
+export interface Evaluator {
+  evaluate<T = unknown>(expression: string, context: ExpressionContext): ExpressionResult<T>;
+  evaluateTemplate(template: string, context: ExpressionContext): ExpressionResult<string>;
+  validate(expression: string): { valid: boolean; errors: string[] };
+}
+
+/** Pre-defined failure policy contexts for the Web Player */
+export type FailurePolicyContext =
+  | 'VIEW_BINDING'
+  | 'EVENT_REACTION'
+  | 'DURING_ACTION'
+  | 'CONDITIONAL_VISIBILITY';

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @mindmatrix/player-core — Framework-agnostic browser-side workflow engine.
+ *
+ * Modules:
+ * - expression: Expression evaluation with 31 core functions
+ * - state-machine: Workflow state machine interpreter
+ * - events: Pub/sub event bus with glob pattern matching
+ * - actions: Action dispatcher with handler registry
+ * - dsl: DSL compiler pipeline
+ */
+
+export * from './expression';
+export * from './state-machine';
+export * from './events';
+export * from './actions';
+export * from './testing';
+export * from './validation';
+
+export { compile } from './dsl/compiler';
+export type {
+  CompilationResult,
+  IRWorkflowDefinition,
+  CompilerError,
+  CompilerErrorCode,
+  IRStateDefinition,
+  IRTransitionDefinition,
+  IRFieldDefinition,
+  IRFieldValidation,
+  IRActionDefinition,
+  IRDuringAction,
+  IROnEventSubscription,
+  IROnEventAction,
+  IRConditionDefinition,
+  IRRoleDefinition,
+  IRExperienceNode,
+  IRExperienceDefinition,
+  IRBlueprintManifest,
+  IRDataSource,
+  IRWorkflowDataSource,
+  IRApiDataSource,
+  IRRefDataSource,
+  IRStaticDataSource,
+  IRGrammarIsland,
+  IRWorkflowFieldType,
+  IRStateType,
+  IRActionMode,
+  IRStateHome,
+  RuntimeProfile,
+  PureFormWorkflow,
+  CompiledOutput,
+} from './dsl/ir-types';
+export { normalizeCategory } from './dsl/ir-types';
+
+// IR Migration
+export {
+  normalizeDefinition,
+  detectIRVersion,
+  needsMigration,
+  CURRENT_IR_VERSION,
+} from './dsl/ir-migration';
+export type { MigrationResult } from './dsl/ir-migration';

package/src/state-machine/index.ts

@@ -0,0 +1,16 @@
+export type {
+  StateType,
+  PlayerAction,
+  PlayerOnEventSubscription,
+  PlayerStateDefinition,
+  PlayerTransitionDefinition,
+  PlayerWorkflowDefinition,
+  PlayerInstance,
+  TransitionResult,
+  StateMachineListener,
+  StateMachineEvent,
+  ActionHandler,
+} from './types';
+
+export { StateMachine } from './interpreter';
+export type { StateMachineConfig } from './interpreter';

package/src/state-machine/interpreter.ts

@@ -0,0 +1,319 @@
+/**
+ * State Machine Interpreter — browser-side workflow engine.
+ *
+ * Interprets PlayerWorkflowDefinition instances with:
+ * - State transitions (manual + auto)
+ * - on_enter / on_exit action execution
+ * - Condition evaluation via expression engine
+ * - Listener-based event emission
+ * - Auto-transition drain loop with depth limit
+ */
+
+import type { Evaluator, ExpressionContext } from '../expression/types';
+import type {
+  PlayerWorkflowDefinition,
+  PlayerInstance,
+  PlayerStateDefinition,
+  PlayerTransitionDefinition,
+  TransitionResult,
+  StateMachineListener,
+  StateMachineEvent,
+  ActionHandler,
+  PlayerAction,
+} from './types';
+
+const MAX_AUTO_CHAIN = 10;
+
+export interface StateMachineConfig {
+  evaluator: Evaluator;
+  actionHandlers?: Map<string, ActionHandler>;
+}
+
+export class StateMachine {
+  private readonly evaluator: Evaluator;
+  private readonly actionHandlers: Map<string, ActionHandler>;
+  private readonly listeners: Set<StateMachineListener> = new Set();
+  private instance: PlayerInstance;
+
+  constructor(
+    definition: PlayerWorkflowDefinition,
+    initialData: Record<string, unknown> = {},
+    config: StateMachineConfig,
+  ) {
+    this.evaluator = config.evaluator;
+    this.actionHandlers = config.actionHandlers ?? new Map();
+
+    const startState = definition.states.find(s => s.type === 'START');
+    if (!startState) {
+      throw new Error(`No START state found in definition ${definition.slug}`);
+    }
+
+    this.instance = {
+      definition,
+      current_state: startState.name,
+      state_data: { ...initialData },
+      memory: {},
+      status: 'ACTIVE',
+    };
+  }
+
+  /** Get the current instance snapshot (immutable copy) */
+  getSnapshot(): Readonly<PlayerInstance> {
+    return { ...this.instance, state_data: { ...this.instance.state_data }, memory: { ...this.instance.memory } };
+  }
+
+  /** Get current state name */
+  get currentState(): string {
+    return this.instance.current_state;
+  }
+
+  /** Get current state_data */
+  get stateData(): Record<string, unknown> {
+    return this.instance.state_data;
+  }
+
+  /** Get current status */
+  get status(): string {
+    return this.instance.status;
+  }
+
+  /** Subscribe to state machine events */
+  on(listener: StateMachineListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Register an action handler */
+  registerAction(type: string, handler: ActionHandler): void {
+    this.actionHandlers.set(type, handler);
+  }
+
+  /** Execute a named transition */
+  async transition(transitionName: string, data?: Record<string, unknown>): Promise<TransitionResult> {
+    if (this.instance.status !== 'ACTIVE') {
+      return {
+        success: false,
+        from_state: this.instance.current_state,
+        to_state: this.instance.current_state,
+        actions_executed: [],
+        error: `Cannot transition: instance status is ${this.instance.status}`,
+      };
+    }
+
+    const transition = this.instance.definition.transitions.find(
+      t => t.name === transitionName && t.from.includes(this.instance.current_state),
+    );
+
+    if (!transition) {
+      return {
+        success: false,
+        from_state: this.instance.current_state,
+        to_state: this.instance.current_state,
+        actions_executed: [],
+        error: `Transition "${transitionName}" not valid from state "${this.instance.current_state}"`,
+      };
+    }
+
+    // Merge transition data
+    if (data) {
+      this.instance.state_data = { ...this.instance.state_data, ...data };
+    }
+
+    // Check conditions
+    if (transition.conditions && transition.conditions.length > 0) {
+      const ctx = this.buildContext();
+      for (const condition of transition.conditions) {
+        const result = this.evaluator.evaluate<boolean>(condition, ctx);
+        if (!result.value) {
+          return {
+            success: false,
+            from_state: this.instance.current_state,
+            to_state: this.instance.current_state,
+            actions_executed: [],
+            error: `Transition condition not met: ${condition}`,
+          };
+        }
+      }
+    }
+
+    const result = await this.executeTransition(transition);
+
+    // Drain auto-transitions
+    if (result.success) {
+      await this.drainAutoTransitions();
+    }
+
+    return result;
+  }
+
+  /** Update state_data directly (for on_event set_field actions) */
+  setField(field: string, value: unknown): void {
+    this.instance.state_data = { ...this.instance.state_data, [field]: value };
+  }
+
+  /** Update memory */
+  setMemory(key: string, value: unknown): void {
+    this.instance.memory = { ...this.instance.memory, [key]: value };
+  }
+
+  /** Get available transitions from the current state */
+  getAvailableTransitions(): PlayerTransitionDefinition[] {
+    return this.instance.definition.transitions.filter(
+      t => t.from.includes(this.instance.current_state) && !t.auto,
+    );
+  }
+
+  /** Get the current state definition */
+  getCurrentStateDefinition(): PlayerStateDefinition | undefined {
+    return this.instance.definition.states.find(s => s.name === this.instance.current_state);
+  }
+
+  // ===========================================================================
+  // Private implementation
+  // ===========================================================================
+
+  private async executeTransition(transition: PlayerTransitionDefinition): Promise<TransitionResult> {
+    const fromState = this.instance.current_state;
+    const allActionsExecuted: PlayerAction[] = [];
+
+    // Phase 1: on_exit actions
+    const fromStateDef = this.getCurrentStateDefinition();
+    if (fromStateDef?.on_exit) {
+      await this.executeActions(fromStateDef.on_exit, allActionsExecuted);
+    }
+
+    this.emit({
+      type: 'state_exit',
+      instance_id: this.instance.definition.id,
+      from_state: fromState,
+    });
+
+    // Phase 2: transition actions
+    if (transition.actions) {
+      await this.executeActions(transition.actions, allActionsExecuted);
+    }
+
+    // Phase 3: update state
+    this.instance.current_state = transition.to;
+
+    // Phase 4: check terminal state
+    const toStateDef = this.instance.definition.states.find(s => s.name === transition.to);
+    if (toStateDef?.type === 'END') {
+      this.instance.status = 'COMPLETED';
+    } else if (toStateDef?.type === 'CANCELLED') {
+      this.instance.status = 'CANCELLED';
+    }
+
+    this.emit({
+      type: 'state_enter',
+      instance_id: this.instance.definition.id,
+      to_state: transition.to,
+    });
+
+    // Phase 5: on_enter actions
+    if (toStateDef?.on_enter) {
+      await this.executeActions(toStateDef.on_enter, allActionsExecuted);
+    }
+
+    this.emit({
+      type: 'transition',
+      instance_id: this.instance.definition.id,
+      from_state: fromState,
+      to_state: transition.to,
+    });
+
+    return {
+      success: true,
+      from_state: fromState,
+      to_state: transition.to,
+      actions_executed: allActionsExecuted,
+    };
+  }
+
+  private async drainAutoTransitions(): Promise<void> {
+    for (let depth = 0; depth < MAX_AUTO_CHAIN; depth++) {
+      if (this.instance.status !== 'ACTIVE') break;
+
+      const autoTransition = this.findMatchingAutoTransition();
+      if (!autoTransition) break;
+
+      const result = await this.executeTransition(autoTransition);
+      if (!result.success) break;
+    }
+  }
+
+  private findMatchingAutoTransition(): PlayerTransitionDefinition | null {
+    const candidates = this.instance.definition.transitions.filter(
+      t => t.auto && t.from.includes(this.instance.current_state),
+    );
+
+    const ctx = this.buildContext();
+    for (const candidate of candidates) {
+      if (!candidate.conditions || candidate.conditions.length === 0) {
+        return candidate;
+      }
+
+      const allMet = candidate.conditions.every(condition => {
+        const result = this.evaluator.evaluate<boolean>(condition, ctx);
+        return result.value === true;
+      });
+
+      if (allMet) return candidate;
+    }
+
+    return null;
+  }
+
+  private async executeActions(actions: PlayerAction[], collector: PlayerAction[]): Promise<void> {
+    const ctx = this.buildContext();
+
+    for (const action of actions) {
+      // Check per-action condition
+      if (action.condition) {
+        const condResult = this.evaluator.evaluate<boolean>(action.condition, ctx);
+        if (!condResult.value) continue;
+      }
+
+      const handler = this.actionHandlers.get(action.type);
+      if (handler) {
+        try {
+          await handler(action, ctx);
+          collector.push(action);
+          this.emit({
+            type: 'action_executed',
+            instance_id: this.instance.definition.id,
+            action,
+          });
+        } catch (error) {
+          this.emit({
+            type: 'error',
+            instance_id: this.instance.definition.id,
+            action,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    }
+  }
+
+  private buildContext(): ExpressionContext {
+    return {
+      state_data: this.instance.state_data,
+      memory: this.instance.memory,
+      current_state: this.instance.current_state,
+      status: this.instance.status,
+      // Spread state_data for direct field access (e.g., "title" instead of "state_data.title")
+      ...this.instance.state_data,
+    };
+  }
+
+  private emit(event: StateMachineEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch {
+        // Listener errors don't break the state machine
+      }
+    }
+  }
+}