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

package/src/local/LocalEngine.ts

@@ -1,388 +0,0 @@
-/**
- * LocalWorkflowEngine — Browser-side workflow state machine
- *
- * Lightweight, pure-function engine that runs workflow definitions locally.
- * Used by blueprint-specific bridges to drive state via workflow transitions
- * instead of React dispatch actions.
- *
- * - Immutable: applyTransition returns a new WorkflowInstance
- * - Lamport versioning: monotonic counter for ordering transitions across peers
- * - No side effects: safe to call in React render path
- */
-
-// ============================================================================
-// TYPES — Subset of mm-engine WorkflowDefinition relevant to frontend
-// ============================================================================
-
-export interface WorkflowState {
-  name: string;
-  state_type: 'START' | 'REGULAR' | 'END';
-  description?: string;
-}
-
-export interface WorkflowTransition {
-  name: string;
-  /** States this transition can fire from. */
-  from: string[];
-  /** Target state, or null for self-loop (stays in current state). */
-  to: string | null;
-  description?: string;
-  required_fields?: string[];
-}
-
-export interface WorkflowFieldDef {
-  name: string;
-  field_type: string;
-  default_value?: unknown;
-  [key: string]: unknown;
-}
-
-export interface WorkflowDefinition {
-  id: string;
-  slug: string;
-  name: string;
-  version: string;
-  description?: string;
-  states: WorkflowState[];
-  transitions: WorkflowTransition[];
-  fields: WorkflowFieldDef[];
-  state_data?: Record<string, unknown>;
-  [key: string]: unknown;
-}
-
-// ============================================================================
-// WORKFLOW INSTANCE — Runtime state of a single workflow
-// ============================================================================
-
-export interface WorkflowInstance {
-  /** Unique instance ID */
-  id: string;
-  /** Slug of the definition this instance was created from */
-  definitionSlug: string;
-  /** Current state name */
-  currentState: string;
-  /** Field values (mutable data carried by this instance) */
-  fields: Record<string, unknown>;
-  /** Lamport version counter — incremented on every transition */
-  version: number;
-  /** Timestamp of last transition (ms since epoch) */
-  updatedAt: number;
-}
-
-// ============================================================================
-// WORKFLOW EVENT — emitted by on_enter / transition actions
-// ============================================================================
-
-export interface WorkflowEvent {
-  event: string;
-  instanceId: string;
-  definitionSlug: string;
-}
-
-/** Extended instance type carrying pending events from on_enter actions */
-export interface WorkflowInstanceWithEvents extends WorkflowInstance {
-  _pendingEvents?: WorkflowEvent[];
-}
-
-// ============================================================================
-// ENGINE
-// ============================================================================
-
-/** Callback type for event subscriptions */
-export type WorkflowEventHandler = (event: WorkflowEvent) => void;
-
-export class LocalWorkflowEngine {
-  private definitions = new Map<string, WorkflowDefinition>();
-  private eventSubscriptions = new Map<string, Set<WorkflowEventHandler>>();
-
-  /** Register a workflow definition by slug */
-  registerDefinition(def: WorkflowDefinition): void {
-    this.definitions.set(def.slug, def);
-  }
-
-  /** Get a registered definition */
-  getDefinition(slug: string): WorkflowDefinition | undefined {
-    return this.definitions.get(slug);
-  }
-
-  /** Get all registered definitions */
-  getAllDefinitions(): WorkflowDefinition[] {
-    return Array.from(this.definitions.values());
-  }
-
-  /** Check if a definition is registered */
-  hasDefinition(slug: string): boolean {
-    return this.definitions.has(slug);
-  }
-
-  /**
-   * Subscribe to a workflow event by name.
-   * Returns an unsubscribe function.
-   */
-  onEvent(eventName: string, handler: WorkflowEventHandler): () => void {
-    let handlers = this.eventSubscriptions.get(eventName);
-    if (!handlers) {
-      handlers = new Set();
-      this.eventSubscriptions.set(eventName, handlers);
-    }
-    handlers.add(handler);
-    return () => {
-      handlers!.delete(handler);
-      if (handlers!.size === 0) {
-        this.eventSubscriptions.delete(eventName);
-      }
-    };
-  }
-
-  /**
-   * Emit a workflow event to all local subscribers.
-   * Called after applyTransition when _pendingEvents are present.
-   */
-  emitEvent(event: WorkflowEvent): void {
-    const handlers = this.eventSubscriptions.get(event.event);
-    if (handlers) {
-      for (const handler of handlers) {
-        try {
-          handler(event);
-        } catch (err) {
-          console.error(`[WorkflowEngine] Event handler error for "${event.event}":`, err);
-        }
-      }
-    }
-  }
-
-  /**
-   * Process all pending events from a transition result.
-   * Emits locally and returns the events for P2P broadcast.
-   */
-  processPendingEvents(instance: WorkflowInstance): WorkflowEvent[] {
-    const events = (instance as WorkflowInstanceWithEvents)._pendingEvents;
-    if (!events?.length) return [];
-    for (const evt of events) {
-      this.emitEvent(evt);
-    }
-    return events;
-  }
-
-  /** Create a new workflow instance from a definition */
-  createInstance(
-    slug: string,
-    id: string,
-    initialFields?: Record<string, unknown>
-  ): WorkflowInstance {
-    const def = this.definitions.get(slug);
-    if (!def) {
-      throw new Error(`WorkflowDefinition not found: ${slug}`);
-    }
-
-    // Find the START state (support both state_type and type field naming)
-    const startState = def.states.find(
-      (s) => s.state_type === 'START' || (s as unknown as Record<string, unknown>).type === 'START',
-    );
-    if (!startState) {
-      throw new Error(`No START state in definition: ${slug}`);
-    }
-
-    // Build default field values from definition
-    const fields: Record<string, unknown> = {};
-    for (const fieldDef of def.fields) {
-      fields[fieldDef.name] = fieldDef.default_value ?? null;
-    }
-
-    // Merge state_data defaults
-    if (def.state_data) {
-      for (const [key, value] of Object.entries(def.state_data)) {
-        if (!(key in fields)) {
-          fields[key] = value;
-        }
-      }
-    }
-
-    // Override with caller-provided initial values
-    if (initialFields) {
-      Object.assign(fields, initialFields);
-    }
-
-    return {
-      id,
-      definitionSlug: slug,
-      currentState: startState.name,
-      fields,
-      version: 0,
-      updatedAt: Date.now(),
-    };
-  }
-
-  /** Check if a transition can fire from the instance's current state */
-  canTransition(instance: WorkflowInstance, transitionName: string): boolean {
-    const def = this.definitions.get(instance.definitionSlug);
-    if (!def) return false;
-
-    const transition = def.transitions.find((t) => t.name === transitionName);
-    if (!transition) return false;
-
-    return transition.from.includes(instance.currentState);
-  }
-
-  /** Get all transitions available from the instance's current state */
-  getAvailableTransitions(instance: WorkflowInstance): string[] {
-    const def = this.definitions.get(instance.definitionSlug);
-    if (!def) return [];
-
-    return def.transitions
-      .filter((t) => t.from.includes(instance.currentState))
-      .map((t) => t.name);
-  }
-
-  /**
-   * Apply a transition, returning a new WorkflowInstance (immutable).
-   *
-   * @param instance - Current instance state
-   * @param transitionName - Name of the transition to apply
-   * @param data - Optional field updates to merge into instance fields
-   * @returns New WorkflowInstance with updated state and version
-   * @throws If transition is not valid from current state
-   */
-  applyTransition(
-    instance: WorkflowInstance,
-    transitionName: string,
-    data?: Record<string, unknown>
-  ): WorkflowInstance {
-    const def = this.definitions.get(instance.definitionSlug);
-    if (!def) {
-      throw new Error(`Definition not found: ${instance.definitionSlug}`);
-    }
-
-    const transition = def.transitions.find((t) => t.name === transitionName);
-    if (!transition) {
-      throw new Error(
-        `Transition "${transitionName}" not found in ${instance.definitionSlug}`
-      );
-    }
-
-    if (!transition.from.includes(instance.currentState)) {
-      throw new Error(
-        `Transition "${transitionName}" cannot fire from state "${instance.currentState}" ` +
-        `(allowed from: ${transition.from.join(', ')})`
-      );
-    }
-
-    // Determine target state: null means self-loop (stay in current state)
-    const nextState = transition.to ?? instance.currentState;
-
-    // Merge field updates
-    const fields = data
-      ? { ...instance.fields, ...data }
-      : { ...instance.fields };
-
-    let result: WorkflowInstance = {
-      ...instance,
-      currentState: nextState,
-      fields,
-      version: instance.version + 1,
-      updatedAt: Date.now(),
-    };
-
-    // Execute on_enter actions for the target state
-    const targetStateDef = def.states.find((s) => s.name === nextState);
-    if (targetStateDef) {
-      const onEnter = (targetStateDef as unknown as Record<string, unknown>).on_enter as
-        | Array<{ action_type: string; config?: Record<string, unknown> }>
-        | undefined;
-
-      if (onEnter) {
-        const pendingEvents: WorkflowEvent[] = [];
-
-        for (const action of onEnter) {
-          if (action.action_type === 'emit_event' && action.config) {
-            pendingEvents.push({
-              event: action.config.event as string,
-              instanceId: result.id,
-              definitionSlug: result.definitionSlug,
-            });
-          }
-          if (action.action_type === 'set_field' && action.config) {
-            const field = action.config.field as string;
-            const expression = action.config.expression as string;
-            if (field && expression) {
-              if (expression.startsWith('$.transition_data.') && data) {
-                const key = expression.replace('$.transition_data.', '');
-                result = {
-                  ...result,
-                  fields: { ...result.fields, [field]: data[key] },
-                };
-              }
-            }
-          }
-        }
-
-        if (pendingEvents.length > 0) {
-          (result as WorkflowInstanceWithEvents)._pendingEvents = pendingEvents;
-        }
-      }
-    }
-
-    // Execute transition-level actions (e.g., set_field, emit_event)
-    const transitionActions = (transition as unknown as Record<string, unknown>).actions as
-      | Array<{ action_type: string; config?: Record<string, unknown> }>
-      | undefined;
-
-    if (transitionActions) {
-      for (const action of transitionActions) {
-        if (action.action_type === 'set_field' && action.config) {
-          const field = action.config.field as string;
-          const expression = action.config.expression as string;
-          if (field && expression) {
-            if (expression.startsWith('$.transition_data.') && data) {
-              const key = expression.replace('$.transition_data.', '');
-              result = {
-                ...result,
-                fields: { ...result.fields, [field]: data[key] },
-              };
-            } else if (expression === 'now()') {
-              result = {
-                ...result,
-                fields: { ...result.fields, [field]: new Date().toISOString() },
-              };
-            }
-          }
-        }
-        if (action.action_type === 'emit_event' && action.config) {
-          const events = (result as WorkflowInstanceWithEvents)._pendingEvents || [];
-          events.push({
-            event: action.config.event as string,
-            instanceId: result.id,
-            definitionSlug: result.definitionSlug,
-          });
-          (result as WorkflowInstanceWithEvents)._pendingEvents = events;
-        }
-      }
-    }
-
-    return result;
-  }
-
-  /**
-   * Apply a transition only if the incoming version is newer.
-   * Used for P2P sync — skips stale transitions.
-   */
-  applyRemoteTransition(
-    instance: WorkflowInstance,
-    transitionName: string,
-    data: Record<string, unknown> | undefined,
-    remoteVersion: number
-  ): WorkflowInstance | null {
-    // Skip stale transitions
-    if (remoteVersion <= instance.version) {
-      return null;
-    }
-
-    if (!this.canTransition(instance, transitionName)) {
-      return null;
-    }
-
-    const updated = this.applyTransition(instance, transitionName, data);
-    // Use the remote version to stay in sync
-    return { ...updated, version: remoteVersion };
-  }
-}

package/src/local/LocalEngineAdapter.ts

@@ -1,175 +0,0 @@
-/**
- * LocalEngineDataSourceAdapter — Adapter for querying LocalWorkflowEngine
- * from within ComponentTreeRenderer context.
- *
- * Provides the same interface as backend API queries but reads from the
- * local workflow engine instead. Fully generic — no workflow-specific concepts.
- */
-
-import type { LocalWorkflowEngine, WorkflowInstance } from './LocalEngine';
-import type { LocalEngineStore } from './LocalEngineContext';
-
-export interface WorkflowDataSource {
-  type: 'workflow';
-  slug?: string;
-  query?: 'latest' | 'list';
-  filters?: Record<string, unknown>;
-  filter?: Record<string, unknown>;
-}
-
-export interface DataSource {
-  type: string;
-}
-
-export interface DataSourceResult {
-  instance?: unknown;
-  instances?: unknown[];
-  loading: boolean;
-  error: Error | null;
-}
-
-export interface InstanceData {
-  id: string;
-  current_state: string;
-  state_data?: Record<string, unknown>;
-  /** Alias for state_data — compiled views reference $item.fields.x */
-  fields?: Record<string, unknown>;
-  created_at?: string;
-  updated_at?: string;
-}
-
-export type LocalDataResolver = (source: DataSource, localState: Record<string, unknown>) => DataSourceResult | null;
-
-export interface LocalEngineAdapter {
-  query(dataSource: WorkflowDataSource, localState: Record<string, unknown>): DataSourceResult;
-}
-
-/**
- * Convert a WorkflowInstance to InstanceData for CTR consumption.
- */
-function instanceToData(inst: WorkflowInstance): InstanceData {
-  const fieldsCopy = { ...inst.fields };
-  return {
-    id: inst.id,
-    current_state: inst.currentState,
-    state_data: fieldsCopy,
-    // Alias: compiled views reference $item.fields.x instead of $item.state_data.x
-    fields: fieldsCopy,
-    created_at: inst.fields.created_at as string | undefined,
-    updated_at: inst.fields.updated_at as string | undefined,
-  };
-}
-
-/**
- * Create an adapter that queries a LocalWorkflowEngine.
- * Supports list queries with filter expressions.
- */
-export function createLocalEngineAdapter(
-  _engine: LocalWorkflowEngine,
-  store: LocalEngineStore,
-): LocalEngineAdapter {
-  return {
-    query(dataSource: WorkflowDataSource, localState: Record<string, unknown>): DataSourceResult {
-      const { slug, query, filters, filter: staticFilter } = dataSource;
-
-      if (!slug) {
-        return { loading: false, error: new Error('LocalEngineAdapter: slug is required') };
-      }
-
-      // Handle app instance
-      if (store.app && store.app.definitionSlug === slug) {
-        return {
-          instance: instanceToData(store.app),
-          loading: false,
-          error: null,
-        };
-      }
-
-      // Look up the instance map for this slug
-      const instanceMap = store.instances?.get(slug);
-      if (!instanceMap || typeof instanceMap.values !== 'function') {
-        return { instances: [], loading: false, error: null };
-      }
-
-      // Convert map values to InstanceData array
-      let instances = Array.from(instanceMap.values()).map(instanceToData);
-
-      // Apply filters (merge static + dynamic)
-      const allFilters = { ...staticFilter, ...filters };
-      if (allFilters && Object.keys(allFilters).length > 0) {
-        instances = instances.filter((inst) => {
-          for (const [key, valueExpr] of Object.entries(allFilters)) {
-            let expectedValue: unknown;
-
-            // Resolve bind expressions like { bind: '$local.some_field_id' }
-            if (typeof valueExpr === 'object' && valueExpr !== null && 'bind' in valueExpr) {
-              const bindExpr = (valueExpr as { bind: string }).bind;
-              if (bindExpr.startsWith('$local.')) {
-                const localKey = bindExpr.slice(7);
-                expectedValue = localState[localKey];
-              } else if (bindExpr.startsWith('$item.')) {
-                // For slot contributions, $item is the parent instance
-                // This is handled by the slot resolver, not here
-                continue;
-              } else {
-                expectedValue = bindExpr;
-              }
-            } else {
-              expectedValue = valueExpr;
-            }
-
-            // Compare field value (look in state_data)
-            const actualValue = inst.state_data?.[key];
-            if (actualValue !== expectedValue) {
-              return false;
-            }
-          }
-          return true;
-        });
-      }
-
-      // For 'latest', return single instance
-      if (query === 'latest') {
-        return {
-          instance: instances[0],
-          instances: undefined,
-          loading: false,
-          error: null,
-        };
-      }
-
-      // For 'list', return array
-      return {
-        instances,
-        loading: false,
-        error: null,
-      };
-    },
-  };
-}
-
-/**
- * Create a LocalDataResolver function compatible with useExperienceData.
- * Returns non-null DataSourceResult for slugs handled by the local engine,
- * null for everything else (falls through to server API).
- */
-export function createLocalDataResolver(
-  engine: LocalWorkflowEngine,
-  store: LocalEngineStore,
-): LocalDataResolver {
-  const adapter = createLocalEngineAdapter(engine, store);
-
-  return (source: DataSource, localState: Record<string, unknown>): DataSourceResult | null => {
-    // Only handle workflow dataSources
-    if (source.type !== 'workflow') return null;
-    const wfSource = source as WorkflowDataSource;
-    if (!wfSource.slug) return null;
-
-    // Check if this slug is served by the local engine
-    if (store.app?.definitionSlug === wfSource.slug || store.instances?.has(wfSource.slug)) {
-      return adapter.query(wfSource, localState);
-    }
-
-    return null;
-  };
-}

package/src/local/LocalEngineContext.ts

@@ -1,30 +0,0 @@
-/**
- * LocalEngineContext — Provides local workflow engine to ComponentTreeRenderer
- *
- * Used for P2P features where workflow instances are stored
- * locally instead of on the server. Fully generic — no workflow-specific concepts.
- */
-
-import { createContext, useContext } from 'react';
-import type { LocalWorkflowEngine, WorkflowInstance } from './LocalEngine';
-
-export interface LocalEngineStore {
-  app?: WorkflowInstance;
-  /** Generic slug-keyed instance maps: slug → (id → instance) */
-  instances: Map<string, Map<string, WorkflowInstance>>;
-}
-
-export interface LocalEngineContextValue {
-  engine: LocalWorkflowEngine;
-  store: LocalEngineStore;
-  /** Generic action dispatch — blueprint-specific actions keyed by name */
-  actions?: Record<string, (data?: unknown) => void>;
-}
-
-const LocalEngineContext = createContext<LocalEngineContextValue | null>(null);
-
-export function useLocalEngine(): LocalEngineContextValue | null {
-  return useContext(LocalEngineContext);
-}
-
-export const LocalEngineProvider = LocalEngineContext.Provider;

package/src/logger.ts

@@ -1,37 +0,0 @@
-/**
- * Player Logger — structured console.warn logging for event matching and action dispatch.
- */
-
-import type { PlayerLogEntry } from './types';
-
-let debugEnabled = false;
-
-export function setPlayerDebug(enabled: boolean): void {
-  debugEnabled = enabled;
-}
-
-export function isPlayerDebug(): boolean {
-  return debugEnabled;
-}
-
-export function playerLog(entry: Omit<PlayerLogEntry, 'timestamp'>): void {
-  if (!debugEnabled && entry.level === 'debug') return;
-
-  const prefix = `[player-web:${entry.category}]`;
-  const msg = `${prefix} ${entry.message}`;
-
-  switch (entry.level) {
-    case 'error':
-      console.error(msg, entry.data ?? '');
-      break;
-    case 'warn':
-      console.warn(msg, entry.data ?? '');
-      break;
-    case 'info':
-      console.info(msg, entry.data ?? '');
-      break;
-    case 'debug':
-      console.debug(msg, entry.data ?? '');
-      break;
-  }
-}