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

package/src/hooks/usePackage.ts

@@ -1,128 +0,0 @@
-/**
- * usePackage — Load a package manifest and resolve its dependencies
- *
- * Reads a blueprint definition (category='blueprint') from the runtime context,
- * extracts its PackageManifest from metadata, and resolves child definitions
- * and dependency packages.
- *
- * Usage in .workflow.tsx:
- *   const { manifest, children, isResolved } = usePackage('my-package');
- *   // Access child definitions via scoped slugs
- *   const mainWorkflow = children.find(c => c.slug === manifest.entrypoint);
- */
-
-import { useMemo } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-export interface PackageManifest {
-  slug: string;
-  name: string;
-  version: string;
-  description?: string;
-  dependencies: Record<string, string>;
-  exports: string[];
-  private: string[];
-  entrypoint?: string;
-}
-
-export interface PackageChild {
-  id: string;
-  slug: string;
-  name: string;
-  category: string;
-  version?: string;
-}
-
-export interface PackageResult {
-  /** The package manifest (null if not found or not a package) */
-  manifest: PackageManifest | null;
-  /** Child definitions within this package */
-  children: PackageChild[];
-  /** Whether all dependencies are resolved */
-  isResolved: boolean;
-  /** Dependency package slugs */
-  dependencySlugs: string[];
-}
-
-export function usePackage(packageSlug: string): PackageResult {
-  const runtime = useRuntimeContext();
-
-  return useMemo((): PackageResult => {
-    const snapshot = runtime.getSnapshot();
-    const definition = (runtime as any).config?.definition;
-
-    // Look for a blueprint definition matching the slug
-    const childDefs: any[] = definition?.child_definitions ?? [];
-    const metadata: Record<string, any> = definition?.metadata ?? {};
-
-    // If this definition IS the package
-    if (definition?.slug === packageSlug && definition?.category === 'blueprint') {
-      const manifest: PackageManifest = {
-        slug: definition.slug,
-        name: definition.name ?? packageSlug,
-        version: definition.version ?? '0.0.1',
-        description: metadata.description ?? '',
-        dependencies: metadata.dependencies ?? {},
-        exports: metadata.exports ?? [],
-        private: metadata.private ?? [],
-        entrypoint: metadata.entrypoint,
-      };
-
-      const children: PackageChild[] = childDefs.map((child: any) => ({
-        id: String(child.id ?? ''),
-        slug: String(child.slug ?? ''),
-        name: String(child.name ?? child.slug ?? ''),
-        category: String(child.category ?? 'workflow'),
-        version: child.version ? String(child.version) : undefined,
-      }));
-
-      const dependencySlugs = Object.keys(manifest.dependencies);
-
-      return {
-        manifest,
-        children,
-        isResolved: dependencySlugs.length === 0, // Simple: resolved if no deps
-        dependencySlugs,
-      };
-    }
-
-    // Search child_definitions for a nested package reference
-    const stateData = snapshot.stateData as Record<string, any> | undefined;
-    const packages: any[] = stateData?.packages ?? [];
-    const found = packages.find((p: any) => p.slug === packageSlug);
-
-    if (found) {
-      const manifest: PackageManifest = {
-        slug: found.slug,
-        name: found.name ?? packageSlug,
-        version: found.version ?? '0.0.1',
-        description: found.description ?? '',
-        dependencies: found.dependencies ?? {},
-        exports: found.exports ?? [],
-        private: found.private ?? [],
-        entrypoint: found.entrypoint,
-      };
-
-      return {
-        manifest,
-        children: (found.children ?? []).map((c: any) => ({
-          id: String(c.id ?? ''),
-          slug: String(c.slug ?? ''),
-          name: String(c.name ?? c.slug ?? ''),
-          category: String(c.category ?? 'workflow'),
-          version: c.version ? String(c.version) : undefined,
-        })),
-        isResolved: Object.keys(manifest.dependencies).length === 0,
-        dependencySlugs: Object.keys(manifest.dependencies),
-      };
-    }
-
-    // Not found
-    return {
-      manifest: null,
-      children: [],
-      isResolved: false,
-      dependencySlugs: [],
-    };
-  }, [runtime, packageSlug]);
-}

package/src/hooks/useParams.ts

@@ -1,33 +0,0 @@
-/**
- * useParams — Access workflow params passed via call invocation
- *
- * When a workflow is invoked via `call "slug"(params)`, the params
- * are stored in the instance's context. This hook reads them.
- * Supports D1 workflows-as-functions.
- *
- * Usage in .workflow.tsx:
- *   const { orderId, quantity } = useParams<{ orderId: string; quantity: number }>();
- */
-
-import { useMemo } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-/**
- * Read the invocation parameters for the current workflow instance.
- *
- * @returns The params object passed when this workflow was called, or an empty object.
- */
-export function useParams<T extends Record<string, unknown> = Record<string, unknown>>(): T {
-  const runtime = useRuntimeContext();
-
-  return useMemo(() => {
-    const snapshot = runtime.getSnapshot();
-    // Params are passed via call invocation and stored in state_data._params
-    // or directly spread into state_data as the initial data
-    const params =
-      (snapshot.stateData as any)?._params ??
-      (snapshot.memory as any)?._callParams ??
-      {};
-    return params as T;
-  }, [runtime]);
-}

package/src/hooks/usePlayer.ts

@@ -1,308 +0,0 @@
-/**
- * usePlayer — Main hook for browser-side workflow engine.
- *
- * Creates and manages a StateMachine + EventBus + ActionDispatcher
- * from a PlayerWorkflowDefinition. Returns a PlayerHandle for
- * React components to interact with the engine.
- *
- * The hook:
- * - Initializes the state machine from the definition's START state
- * - Wires on_event subscriptions from state definitions to the event bus
- * - Registers action handlers (built-in + custom)
- * - Triggers React re-renders on state transitions
- * - Provides structured logging at event match and action dispatch points
- */
-
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import {
-  StateMachine,
-  EventBus,
-  ActionDispatcher,
-  createEvaluator,
-  WEB_FAILURE_POLICIES,
-} from '@mindmatrix/player-core';
-import type {
-  TransitionResult,
-  Evaluator,
-  ExpressionContext,
-  StateMachineEvent,
-  ActionHandler,
-  PlayerAction,
-} from '@mindmatrix/player-core';
-import type { PlayerConfig, PlayerHandle } from '../types';
-import { playerLog, setPlayerDebug } from '../logger';
-
-interface PlayerState {
-  currentState: string;
-  stateData: Record<string, unknown>;
-  status: 'ACTIVE' | 'COMPLETED' | 'CANCELLED';
-  availableTransitions: string[];
-}
-
-function computePlayerState(sm: StateMachine): PlayerState {
-  return {
-    currentState: sm.currentState,
-    stateData: sm.stateData,
-    status: sm.status as PlayerState['status'],
-    availableTransitions: sm.getAvailableTransitions().map(t => t.name),
-  };
-}
-
-export function usePlayer(config: PlayerConfig): PlayerHandle {
-  const configRef = useRef(config);
-  configRef.current = config;
-
-  // Enable debug logging
-  useEffect(() => {
-    if (config.debug) setPlayerDebug(true);
-  }, [config.debug]);
-
-  // Create evaluator (stable — only changes if functions change)
-  const evaluator = useMemo<Evaluator>(() => {
-    return createEvaluator({
-      functions: config.functions ?? [],
-      failurePolicy: WEB_FAILURE_POLICIES.EVENT_REACTION,
-    });
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config.definition.id]);
-
-  // Create engine components (stable per definition)
-  const engine = useMemo(() => {
-    const actionHandlers = new Map<string, ActionHandler>();
-
-    // Wrap custom ActionHandlerFn (config, ctx) into ActionHandler (action, ctx)
-    if (config.actionHandlers) {
-      for (const [type, handler] of Object.entries(config.actionHandlers)) {
-        actionHandlers.set(type, (action: PlayerAction, ctx: ExpressionContext) => handler(action.config, ctx));
-      }
-    }
-
-    // Built-in set_field handler
-    let smRef: StateMachine | null = null;
-    actionHandlers.set('set_field', (action: PlayerAction) => {
-      if (smRef && typeof action.config.field === 'string') {
-        smRef.setField(action.config.field, action.config.value);
-        playerLog({
-          level: 'debug',
-          category: 'action_dispatch',
-          message: `set_field: ${action.config.field} = ${JSON.stringify(action.config.value)}`,
-        });
-      }
-    });
-
-    // Built-in set_memory handler
-    actionHandlers.set('set_memory', (action: PlayerAction) => {
-      if (smRef && typeof action.config.key === 'string') {
-        smRef.setMemory(action.config.key, action.config.value);
-        playerLog({
-          level: 'debug',
-          category: 'action_dispatch',
-          message: `set_memory: ${action.config.key} = ${JSON.stringify(action.config.value)}`,
-        });
-      }
-    });
-
-    const sm = new StateMachine(
-      config.definition,
-      config.initialData ?? {},
-      { evaluator, actionHandlers },
-    );
-    smRef = sm;
-
-    const eventBus = new EventBus();
-    const dispatcher = new ActionDispatcher();
-
-    // Register built-in handlers on dispatcher (for on_event action dispatch)
-    dispatcher.register('set_field', (cfg: Record<string, unknown>) => {
-      if (smRef && typeof cfg.field === 'string') {
-        smRef.setField(cfg.field, cfg.value);
-      }
-    });
-    dispatcher.register('set_memory', (cfg: Record<string, unknown>) => {
-      if (smRef && typeof cfg.key === 'string') {
-        smRef.setMemory(cfg.key, cfg.value);
-      }
-    });
-
-    // Mirror custom action handlers to dispatcher (dispatcher uses ActionHandlerFn signature)
-    if (config.actionHandlers) {
-      for (const [type, handler] of Object.entries(config.actionHandlers)) {
-        dispatcher.register(type, handler);
-      }
-    }
-
-    return { sm, eventBus, dispatcher };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config.definition.id, evaluator]);
-
-  const { sm, eventBus } = engine;
-
-  // React state derived from state machine
-  const [playerState, setPlayerState] = useState<PlayerState>(() => computePlayerState(sm));
-
-  // Wire on_event subscriptions from current state definition
-  useEffect(() => {
-    const stateDef = sm.getCurrentStateDefinition();
-    if (!stateDef?.on_event?.length) return;
-
-    const unsubs: Array<() => void> = [];
-
-    for (const sub of stateDef.on_event) {
-      playerLog({
-        level: 'debug',
-        category: 'event_match',
-        message: `Subscribing to pattern: "${sub.match}"`,
-        data: { state: sm.currentState, conditions: sub.conditions, actionCount: sub.actions.length },
-      });
-
-      const unsub = eventBus.subscribe(sub.match, async (event) => {
-        playerLog({
-          level: 'info',
-          category: 'event_match',
-          message: `Event matched: "${event.topic}" → pattern "${sub.match}"`,
-          data: { state: sm.currentState, payload: event.payload },
-        });
-
-        // Evaluate conditions
-        if (sub.conditions?.length) {
-          const ctx: ExpressionContext = {
-            ...sm.stateData,
-            state_data: sm.stateData,
-            memory: sm.getSnapshot().memory,
-            current_state: sm.currentState,
-            status: sm.status,
-            event: event.payload,
-          };
-
-          for (const condition of sub.conditions) {
-            const result = evaluator.evaluate<boolean>(condition, ctx);
-            if (!result.value) {
-              playerLog({
-                level: 'debug',
-                category: 'event_match',
-                message: `Condition not met: "${condition}" — skipping actions`,
-              });
-              return;
-            }
-          }
-        }
-
-        // Execute actions
-        for (const action of sub.actions) {
-          playerLog({
-            level: 'info',
-            category: 'action_dispatch',
-            message: `Dispatching action: "${action.type}"`,
-            data: { config: action.config, trigger: 'on_event', pattern: sub.match },
-          });
-
-          const ctx: ExpressionContext = {
-            ...sm.stateData,
-            state_data: sm.stateData,
-            memory: sm.getSnapshot().memory,
-            current_state: sm.currentState,
-            status: sm.status,
-            event: event.payload,
-          };
-          await engine.dispatcher.execute([action], ctx, evaluator);
-        }
-
-        // Update React state after actions
-        setPlayerState(computePlayerState(sm));
-      });
-
-      unsubs.push(unsub);
-    }
-
-    return () => {
-      for (const unsub of unsubs) unsub();
-    };
-  }, [sm, eventBus, evaluator, engine.dispatcher, playerState.currentState]);
-
-  // Listen to state machine events for React state sync
-  useEffect(() => {
-    const unsub = sm.on((event: StateMachineEvent) => {
-      if (event.type === 'transition' || event.type === 'state_enter') {
-        setPlayerState(computePlayerState(sm));
-      }
-      if (event.type === 'error') {
-        playerLog({
-          level: 'error',
-          category: 'transition',
-          message: `State machine error: ${event.error}`,
-          data: { action: event.action },
-        });
-      }
-    });
-    return unsub;
-  }, [sm]);
-
-  // Stable callbacks
-  const transition = useCallback(
-    async (name: string, data?: Record<string, unknown>): Promise<TransitionResult> => {
-      playerLog({
-        level: 'info',
-        category: 'transition',
-        message: `Transition requested: "${name}"`,
-        data: { from: sm.currentState, data },
-      });
-      const result = await sm.transition(name, data);
-      if (result.success) {
-        playerLog({
-          level: 'info',
-          category: 'transition',
-          message: `Transition complete: ${result.from_state} → ${result.to_state}`,
-          data: { actions: result.actions_executed.length },
-        });
-      } else {
-        playerLog({
-          level: 'warn',
-          category: 'transition',
-          message: `Transition failed: "${name}" — ${result.error}`,
-        });
-      }
-      return result;
-    },
-    [sm],
-  );
-
-  const setField = useCallback(
-    (field: string, value: unknown) => {
-      sm.setField(field, value);
-      setPlayerState(computePlayerState(sm));
-    },
-    [sm],
-  );
-
-  const setMemory = useCallback(
-    (key: string, value: unknown) => {
-      sm.setMemory(key, value);
-    },
-    [sm],
-  );
-
-  const publishEvent = useCallback(
-    (topic: string, payload?: Record<string, unknown>) => {
-      playerLog({
-        level: 'debug',
-        category: 'event_match',
-        message: `Publishing local event: "${topic}"`,
-        data: payload,
-      });
-      eventBus.emit(topic, payload);
-    },
-    [eventBus],
-  );
-
-  return {
-    currentState: playerState.currentState,
-    stateData: playerState.stateData,
-    status: playerState.status,
-    availableTransitions: playerState.availableTransitions,
-    transition,
-    setField,
-    setMemory,
-    publishEvent,
-    eventBus,
-  };
-}

package/src/hooks/useQuery.ts

@@ -1,184 +0,0 @@
-/**
- * useQuery — reactive data fetching hook for workflow instances.
- *
- * Bridges the compiler (which extracts data source declarations) with
- * the runtime (which resolves queries against the backend or local engine).
- *
- * Usage in .workflow.tsx:
- *   const { data: channels, loading, error, refetch } = useQuery('channel', {
- *     state: 'active',
- *     filter: { isPublic: true },
- *     limit: 20,
- *   });
- *
- * The compiler extracts this as an IRDataSource with type 'workflow'.
- * The runtime resolves it via the configured data adapter.
- */
-
-import { useState, useEffect, useCallback, useRef } from 'react';
-import type { ModelDefinition } from '../config/defineModel';
-import type { InferFields } from '../types/workflow-inference';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface QueryParams {
-  /** Filter by workflow state. */
-  state?: string | string[];
-  /** Field-level filters. */
-  filter?: Record<string, unknown>;
-  /** Maximum number of results. */
-  limit?: number;
-  /** Offset for pagination. */
-  offset?: number;
-  /** Sort field. */
-  orderBy?: string;
-  /** Sort direction. */
-  order?: 'asc' | 'desc';
-  /** Sort field (prefix with - for descending, e.g. '-created_at'). */
-  sort?: string;
-  /** Search across text fields. */
-  search?: string;
-  /** Specific fields to search. */
-  searchFields?: string[];
-  /** Disable auto-fetching (manual mode). */
-  enabled?: boolean;
-  /** Refetch interval in milliseconds. */
-  refetchInterval?: number;
-}
-
-/**
- * Represents a workflow instance as returned by the query API.
- * All query results are instances with id, state, and fields.
- */
-export interface WorkflowInstance<F = Record<string, unknown>> {
-  id: string;
-  state: string;
-  fields: F;
-  slug?: string;
-  created_at?: string;
-  updated_at?: string;
-  [key: string]: unknown;
-}
-
-export interface QueryResult<T> {
-  /** The query results — workflow instances. */
-  data: WorkflowInstance<T>[];
-  /** Whether the query is currently loading. */
-  loading: boolean;
-  /** Error from the last query attempt. */
-  error: Error | null;
-  /** Manually trigger a refetch. */
-  refetch: () => Promise<void>;
-  /** Total count (if available from backend). */
-  total?: number;
-  /** Whether there are more results. */
-  hasMore?: boolean;
-}
-
-/**
- * Data resolver interface — the runtime must provide an implementation.
- * This is typically provided by WorkflowProvider or LocalEngineProvider.
- */
-export interface QueryResolver {
-  query: <T>(slug: string, params: QueryParams) => Promise<{ data: T[]; total?: number }>;
-}
-
-// Global resolver (set by provider)
-let _globalResolver: QueryResolver | null = null;
-
-export function setQueryResolver(resolver: QueryResolver | null): void {
-  _globalResolver = resolver;
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Fetches workflow instances by slug with optional filtering.
- *
- * Overload 1: Type-safe — pass a model definition for typed results.
- * Overload 2: String slug — backward-compatible, untyped.
- *
- * @example
- * ```tsx
- * // Typed (recommended)
- * import channelModel from '../models/channel';
- * const { data } = useQuery(channelModel, { state: 'active' });
- * data[0].fields.name; // string — autocomplete works
- *
- * // Untyped (backward compatible)
- * const { data } = useQuery('chat-channel');
- * ```
- */
-export function useQuery<D extends ModelDefinition>(
-  definition: D,
-  params?: QueryParams,
-): QueryResult<InferFields<D>>;
-export function useQuery<T = Record<string, unknown>>(
-  slug: string,
-  params?: QueryParams,
-): QueryResult<T>;
-export function useQuery(
-  slugOrDef: string | ModelDefinition,
-  params: QueryParams = {}
-): QueryResult<any> {
-  const slug = typeof slugOrDef === 'string' ? slugOrDef : slugOrDef.slug;
-  const [data, setData] = useState<any[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [total, setTotal] = useState<number | undefined>(undefined);
-  const paramsRef = useRef(params);
-  paramsRef.current = params;
-
-  const fetchData = useCallback(async () => {
-    if (paramsRef.current.enabled === false) {
-      setLoading(false);
-      return;
-    }
-
-    const resolver = _globalResolver;
-    if (!resolver) {
-      setError(new Error(`useQuery: No query resolver configured. Wrap your app in a WorkflowProvider.`));
-      setLoading(false);
-      return;
-    }
-
-    try {
-      setLoading(true);
-      setError(null);
-      const result = await resolver.query<any>(slug, paramsRef.current);
-      setData(result.data);
-      setTotal(result.total);
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)));
-    } finally {
-      setLoading(false);
-    }
-  }, [slug]);
-
-  useEffect(() => {
-    fetchData();
-  }, [fetchData]);
-
-  // Refetch interval
-  useEffect(() => {
-    if (!params.refetchInterval || params.refetchInterval <= 0) return;
-    const interval = setInterval(fetchData, params.refetchInterval);
-    return () => clearInterval(interval);
-  }, [fetchData, params.refetchInterval]);
-
-  const hasMore = total !== undefined && data.length < total;
-
-  const result: QueryResult<any> = {
-    data,
-    loading,
-    error,
-    refetch: fetchData,
-    total,
-    hasMore,
-  };
-  return result;
-}