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

package/src/hooks/useChannel.ts

@@ -1,304 +0,0 @@
-/**
- * useChannel — Pub/sub messaging channel between workflow instances.
- *
- * Provides real-time communication between participants (e.g., rider ↔ driver)
- * using WebSocket-backed channels. Messages are published to named channels
- * and delivered to all subscribers.
- *
- * Usage in .workflow.tsx:
- *   const { publish, messages, subscribe } = useChannel('ride:abc123');
- *
- *   // Publish driver location
- *   publish('location', { lat: 40.7128, lng: -74.0060 });
- *
- *   // Subscribe to messages
- *   useEffect(() => {
- *     return subscribe('location', (data) => {
- *       updateDriverMarker(data.lat, data.lng);
- *     });
- *   }, [subscribe]);
- */
-
-import { useState, useEffect, useCallback, useRef, useMemo } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** A message received on a channel. */
-export interface ChannelMessage {
-  /** The event type within the channel. */
-  event: string;
-  /** The message payload. */
-  data: unknown;
-  /** When the message was received. */
-  timestamp: number;
-  /** Sender identifier (if available). */
-  sender?: string;
-}
-
-/** Options for configuring a channel. */
-export interface ChannelOptions {
-  /** WebSocket URL (defaults to /ws/workflow). */
-  wsUrl?: string;
-  /** Enable/disable the channel (default: true). */
-  enabled?: boolean;
-  /** Maximum messages to keep in buffer (default: 100). */
-  bufferSize?: number;
-  /** Auto-reconnect on disconnect. */
-  reconnect?: boolean;
-  /** Reconnect delay in ms (default: 3000). */
-  reconnectDelay?: number;
-}
-
-/** Channel handle returned by useChannel. */
-export interface ChannelHandle {
-  /** Publish a message to the channel. */
-  publish: (event: string, data: unknown) => void;
-  /** Subscribe to a specific event type. Returns unsubscribe function. */
-  subscribe: (event: string, handler: (data: unknown, message: ChannelMessage) => void) => () => void;
-  /** All messages received (capped by bufferSize). */
-  messages: ChannelMessage[];
-  /** Whether the WebSocket is connected. */
-  connected: boolean;
-  /** Disconnect and reconnect. */
-  reconnect: () => void;
-}
-
-/** Channel transport — pluggable WebSocket implementation. */
-export interface ChannelTransport {
-  send: (channel: string, event: string, data: unknown) => void;
-  subscribe: (channel: string, handler: (message: ChannelMessage) => void) => () => void;
-  connect: () => void;
-  disconnect: () => void;
-  readonly connected: boolean;
-}
-
-// Global transport (set by provider)
-let _globalTransport: ChannelTransport | null = null;
-
-export function setChannelTransport(transport: ChannelTransport | null): void {
-  _globalTransport = transport;
-}
-
-// =============================================================================
-// Internal — default WebSocket transport
-// =============================================================================
-
-function getToken(): string | null {
-  return typeof localStorage !== 'undefined' ? localStorage.getItem('auth_token') : null;
-}
-
-function createDefaultTransport(wsUrl: string, reconnectOpts: { enabled: boolean; delay: number }): ChannelTransport {
-  let ws: WebSocket | null = null;
-  let isConnected = false;
-  const listeners = new Map<string, Set<(message: ChannelMessage) => void>>();
-  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-
-  const doConnect = () => {
-    const token = getToken();
-    const url = token ? `${wsUrl}?token=${encodeURIComponent(token)}` : wsUrl;
-    ws = new WebSocket(url);
-
-    ws.onopen = () => {
-      isConnected = true;
-      // Re-subscribe to channels
-      for (const channel of listeners.keys()) {
-        ws?.send(JSON.stringify({ type: 'subscribe', channel }));
-      }
-    };
-
-    ws.onmessage = (e) => {
-      try {
-        const msg = JSON.parse(e.data);
-        const channel = msg.channel as string;
-        const handlers = listeners.get(channel);
-        if (handlers) {
-          const channelMsg: ChannelMessage = {
-            event: msg.event,
-            data: msg.data,
-            timestamp: msg.timestamp ?? Date.now(),
-            sender: msg.sender,
-          };
-          for (const handler of handlers) {
-            handler(channelMsg);
-          }
-        }
-      } catch {
-        // Ignore parse errors
-      }
-    };
-
-    ws.onclose = () => {
-      isConnected = false;
-      if (reconnectOpts.enabled) {
-        reconnectTimer = setTimeout(doConnect, reconnectOpts.delay);
-      }
-    };
-
-    ws.onerror = () => {
-      ws?.close();
-    };
-  };
-
-  return {
-    get connected() {
-      return isConnected;
-    },
-    connect: doConnect,
-    disconnect: () => {
-      if (reconnectTimer) clearTimeout(reconnectTimer);
-      ws?.close();
-      ws = null;
-      isConnected = false;
-    },
-    send: (channel, event, data) => {
-      if (ws?.readyState === WebSocket.OPEN) {
-        ws.send(JSON.stringify({ type: 'publish', channel, event, data }));
-      }
-    },
-    subscribe: (channel, handler) => {
-      if (!listeners.has(channel)) {
-        listeners.set(channel, new Set());
-        // Subscribe on the WebSocket
-        if (ws?.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ type: 'subscribe', channel }));
-        }
-      }
-      listeners.get(channel)!.add(handler);
-
-      return () => {
-        const handlers = listeners.get(channel);
-        if (handlers) {
-          handlers.delete(handler);
-          if (handlers.size === 0) {
-            listeners.delete(channel);
-            if (ws?.readyState === WebSocket.OPEN) {
-              ws.send(JSON.stringify({ type: 'unsubscribe', channel }));
-            }
-          }
-        }
-      };
-    },
-  };
-}
-
-// =============================================================================
-// Hook
-// =============================================================================
-
-/**
- * Pub/sub messaging channel for real-time communication.
- *
- * @param channelName - Channel identifier (e.g., 'ride:abc123').
- * @param options - Channel configuration.
- * @returns Channel handle with publish/subscribe/messages.
- */
-export function useChannel(
-  channelName: string,
-  options: ChannelOptions = {},
-): ChannelHandle {
-  const {
-    wsUrl = '/ws/workflow',
-    enabled = true,
-    bufferSize = 100,
-    reconnect: autoReconnect = true,
-    reconnectDelay = 3000,
-  } = options;
-
-  const [messages, setMessages] = useState<ChannelMessage[]>([]);
-  const [connected, setConnected] = useState(false);
-  const [reconnectKey, setReconnectKey] = useState(0);
-  const handlersRef = useRef(new Map<string, Set<(data: unknown, msg: ChannelMessage) => void>>());
-  const transportRef = useRef<ChannelTransport | null>(null);
-  const bufferSizeRef = useRef(bufferSize);
-  bufferSizeRef.current = bufferSize;
-
-  // Connect transport
-  useEffect(() => {
-    if (!enabled) return;
-
-    const transport = _globalTransport ?? createDefaultTransport(wsUrl, {
-      enabled: autoReconnect,
-      delay: reconnectDelay,
-    });
-    transportRef.current = transport;
-
-    if (!_globalTransport) {
-      transport.connect();
-    }
-
-    // Subscribe to the channel
-    const unsub = transport.subscribe(channelName, (msg) => {
-      setMessages((prev) => {
-        const next = [...prev, msg];
-        return next.length > bufferSizeRef.current ? next.slice(-bufferSizeRef.current) : next;
-      });
-
-      // Dispatch to event-specific handlers
-      const eventHandlers = handlersRef.current.get(msg.event);
-      if (eventHandlers) {
-        for (const handler of eventHandlers) {
-          handler(msg.data, msg);
-        }
-      }
-    });
-
-    // Poll connected status
-    const interval = setInterval(() => {
-      setConnected(transport.connected);
-    }, 1000);
-    setConnected(transport.connected);
-
-    return () => {
-      unsub();
-      clearInterval(interval);
-      if (!_globalTransport) {
-        transport.disconnect();
-      }
-    };
-  }, [channelName, wsUrl, enabled, autoReconnect, reconnectDelay, reconnectKey]);
-
-  const publish = useCallback(
-    (event: string, data: unknown) => {
-      transportRef.current?.send(channelName, event, data);
-    },
-    [channelName],
-  );
-
-  const subscribe = useCallback(
-    (event: string, handler: (data: unknown, msg: ChannelMessage) => void): (() => void) => {
-      if (!handlersRef.current.has(event)) {
-        handlersRef.current.set(event, new Set());
-      }
-      handlersRef.current.get(event)!.add(handler);
-
-      return () => {
-        const handlers = handlersRef.current.get(event);
-        if (handlers) {
-          handlers.delete(handler);
-          if (handlers.size === 0) {
-            handlersRef.current.delete(event);
-          }
-        }
-      };
-    },
-    [],
-  );
-
-  const forceReconnect = useCallback(() => {
-    setReconnectKey((k) => k + 1);
-    setMessages([]);
-  }, []);
-
-  return useMemo(
-    (): ChannelHandle => ({
-      publish,
-      subscribe,
-      messages,
-      connected,
-      reconnect: forceReconnect,
-    }),
-    [publish, subscribe, messages, connected, forceReconnect],
-  );
-}

package/src/hooks/useComputed.ts

@@ -1,154 +0,0 @@
-/**
- * useComputed — declares a computed field with one of three execution modes.
- *
- * Computed fields derive their value from other fields via expressions.
- * The execution mode determines WHEN the computation runs:
- *
- *   - 'read-time' (RT): Computed on every read. No storage overhead.
- *     Best for lightweight derivations (string concat, arithmetic).
- *     Cannot be filtered/sorted at the database level.
- *
- *   - 'transaction-maintained' (TM): Recomputed synchronously whenever
- *     a dependency changes within the same transaction. Stored in the
- *     database alongside regular fields. Can be indexed and queried.
- *     Default for RLS-critical fields.
- *
- *   - 'async-materialized' (AM): Recomputed asynchronously via a
- *     background job after dependencies change. Stored in the database.
- *     Best for expensive computations (aggregations, external API calls).
- *     May be stale between updates.
- *
- * At compile time, the react-compiler extracts useComputed() calls into
- * IRFieldDefinition entries with `computed` expression and `computed_mode`.
- *
- * At runtime, this hook reads the materialized value from instance state
- * (for TM/AM) or evaluates the expression on the fly (for RT).
- *
- * @example
- *   // Read-time: evaluated on every render
- *   const fullName = useComputed('full_name', () => `${firstName} ${lastName}`, {
- *     mode: 'read-time',
- *     deps: ['first_name', 'last_name'],
- *   });
- *
- *   // Transaction-maintained: stored, updated on dependency change
- *   const total = useComputed('line_total', () => quantity * unitPrice, {
- *     mode: 'transaction-maintained',
- *     deps: ['quantity', 'unit_price'],
- *   });
- *
- *   // Async-materialized: stored, updated via background job
- *   const score = useComputed('credit_score', () => calculateScore(income, debt), {
- *     mode: 'async-materialized',
- *     deps: ['income', 'debt'],
- *     staleness: '5m', // acceptable staleness window
- *   });
- */
-
-import { useMemo, useRef } from 'react';
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/** The three execution modes for computed fields. */
-export type ComputedFieldMode =
-  | 'read-time'
-  | 'transaction-maintained'
-  | 'async-materialized';
-
-/** Options for useComputed. */
-export interface UseComputedOptions {
-  /** Execution mode. Default: 'read-time'. */
-  mode?: ComputedFieldMode;
-  /** Field names this computation depends on. Used by the compiler for dependency tracking. */
-  deps?: string[];
-  /** For async-materialized: acceptable staleness duration (e.g., '5m', '1h'). */
-  staleness?: string;
-  /** For async-materialized: whether this field is used in RLS policies. */
-  rlsStalenessOk?: boolean;
-  /** Output field type hint. Default: inferred from expression return type. */
-  type?: string;
-}
-
-/** The result of a computed field — the value plus metadata. */
-export interface ComputedFieldResult<T> {
-  /** The current computed value. */
-  value: T;
-  /** Whether the value is potentially stale (only for async-materialized). */
-  stale: boolean;
-  /** When the value was last computed (ISO timestamp). */
-  computedAt: string | null;
-  /** The execution mode. */
-  mode: ComputedFieldMode;
-}
-
-// =============================================================================
-// Hook Implementation
-// =============================================================================
-
-/**
- * Declares a computed field.
- *
- * @param name - The canonical field name (snake_case).
- * @param compute - The computation function. References to other fields
- *   should use the variables declared by useState() in the same component.
- * @param options - Configuration including execution mode and dependencies.
- * @returns The computed value (for read-time) or a ComputedFieldResult.
- */
-export function useComputed<T = unknown>(
-  _name: string,
-  compute: () => T,
-  options?: UseComputedOptions,
-): T {
-  const mode = options?.mode ?? 'read-time';
-  const deps = options?.deps ?? [];
-
-  // For read-time: just compute on every call (let React.useMemo optimize)
-  // The deps array is for compiler metadata, not React deps — we always recompute
-  // since the compiler handles dependency extraction at build time.
-  const computeRef = useRef(compute);
-  computeRef.current = compute;
-
-  if (mode === 'read-time') {
-    // Read-time: evaluate on every render cycle
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    return useMemo(() => computeRef.current(), [
-      // We intentionally depend on deps.join to recompute when tracked fields change
-      // The actual dependency tracking happens at the compiler level
-      deps.join(','),
-    ]);
-  }
-
-  // For transaction-maintained and async-materialized modes:
-  // At runtime, the value comes from the instance's state_data (already computed
-  // server-side or by the engine). The compute function serves as:
-  //   1. Documentation of the formula
-  //   2. Fallback for local/offline execution
-  //   3. Compile-time extraction target
-  //
-  // In a full runtime environment, this would read from WorkflowRuntime context.
-  // For now, we evaluate locally as a fallback.
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  return useMemo(() => computeRef.current(), [deps.join(',')]);
-}
-
-/**
- * Overload that returns full metadata including staleness info.
- * Useful for async-materialized fields where you need to show staleness indicators.
- */
-export function useComputedWithMeta<T = unknown>(
-  name: string,
-  compute: () => T,
-  options?: UseComputedOptions,
-): ComputedFieldResult<T> {
-  const value = useComputed(name, compute, options);
-  const mode = options?.mode ?? 'read-time';
-
-  return {
-    value,
-    stale: false, // In full runtime, this would check engine staleness tracking
-    computedAt: new Date().toISOString(),
-    mode,
-  };
-}

package/src/hooks/useDomainSubscription.ts

@@ -1,110 +0,0 @@
-/**
- * useDomainSubscription — Bridges WebSocket domain events to the player-core EventBus.
- *
- * This hook receives domain events from the WebSocket transport (or any
- * event source) and publishes them to a player-core EventBus. This enables
- * on_event subscriptions in experience workflows to react to backend state changes.
- *
- * The hook does NOT manage the WebSocket connection itself — that remains
- * with the existing WorkflowSocketContext. Instead, this hook accepts a
- * generic `subscribe` function, making it testable and transport-agnostic.
- */
-
-import { useEffect, useRef } from 'react';
-import type { EventBus } from '@mindmatrix/player-core';
-import type { DomainEvent, DomainSubscriptionConfig } from '../types';
-import { playerLog } from '../logger';
-
-export interface DomainSubscriptionTransport {
-  /** Subscribe to domain events. Returns unsubscribe function. */
-  subscribe: (
-    config: {
-      instanceIds?: string[];
-      entity?: { type: string; id: string };
-    },
-    onEvent: (eventType: string, data: DomainEvent) => void,
-  ) => () => void;
-}
-
-/**
- * Bridge domain events from a transport into a player-core EventBus.
- *
- * Converts domain events into topic strings matching the on_event pattern format:
- * `{definition_slug}:{entity_type}:{entity_id}:{transition_name}.{event_type}`
- *
- * This allows on_event patterns like:
- * - `project:*:*:complete_task.transitioned` — any project completes a task
- * - `**:transitioned` — any transition anywhere
- */
-export function useDomainSubscription(
-  eventBus: EventBus,
-  transport: DomainSubscriptionTransport | null,
-  config: DomainSubscriptionConfig,
-): void {
-  const configRef = useRef(config);
-  configRef.current = config;
-
-  useEffect(() => {
-    if (!transport || config.enabled === false) return;
-
-    const unsub = transport.subscribe(
-      {
-        instanceIds: config.instanceIds,
-        entity: config.entity,
-      },
-      (eventType: string, data: DomainEvent) => {
-        // Build structured topic from domain event
-        const slug = data.definition_slug ?? 'unknown';
-        const entityType = data.entity_type ?? '*';
-        const entityId = data.entity_id ?? '*';
-        const transition = data.transition_name ?? 'unknown';
-
-        // Primary topic: slug:entityType:entityId:transition.eventType
-        const topic = `${slug}:${entityType}:${entityId}:${transition}.${eventType}`;
-
-        playerLog({
-          level: 'info',
-          category: 'event_match',
-          message: `Domain event → topic: "${topic}"`,
-          data: {
-            eventType,
-            from: data.from_state,
-            to: data.to_state,
-            trigger: data.trigger,
-            changed: data.changed_fields,
-          },
-        });
-
-        // Publish to event bus with full payload
-        eventBus.emit(topic, {
-          ...data,
-          _event_type: eventType,
-          _topic: topic,
-        });
-
-        // Also publish a simpler event for broad patterns
-        eventBus.emit(`${eventType}:${slug}`, {
-          ...data,
-          _event_type: eventType,
-        });
-
-        // Call user's onEvent callback if provided
-        configRef.current.onEvent?.({
-          topic,
-          payload: data as unknown as Record<string, unknown>,
-        });
-      },
-    );
-
-    return unsub;
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [
-    eventBus,
-    transport,
-    config.enabled,
-    // Stable serialization of subscription params
-    config.instanceIds?.join(','),
-    config.entity?.type,
-    config.entity?.id,
-  ]);
-}

package/src/hooks/useDuringAction.ts

@@ -1,99 +0,0 @@
-/**
- * useDuringAction — Register a during/while-in-state action
- *
- * Runs a recurring action while the workflow is in a specific state.
- * Similar to useWhileIn but designed for action-based patterns:
- * polling, timers, heartbeats, etc.
- * Supports E1 during actions.
- *
- * Usage in .workflow.tsx:
- *   useDuringAction({
- *     state: 'processing',
- *     action: async () => {
- *       const status = await checkExternalService();
- *       if (status === 'done') transition('complete');
- *     },
- *     intervalMs: 5000,
- *   });
- */
-
-import { useEffect, useRef } from 'react';
-import { useRuntimeContext } from '../providers/RuntimeContext';
-
-export interface DuringActionConfig {
-  /** State name(s) in which the action runs. */
-  state: string | string[];
-  /** The action to execute on each interval tick. */
-  action: () => void | Promise<void>;
-  /** Interval in milliseconds between action executions. Default: 1000. */
-  intervalMs?: number;
-  /** Whether to execute immediately on state entry. Default: true. */
-  immediate?: boolean;
-  /** Whether the action is enabled. Default: true. */
-  enabled?: boolean;
-}
-
-export function useDuringAction(config: DuringActionConfig): void {
-  const runtime = useRuntimeContext();
-  const actionRef = useRef(config.action);
-  actionRef.current = config.action;
-
-  const states = Array.isArray(config.state) ? config.state : [config.state];
-  const intervalMs = config.intervalMs ?? 1000;
-  const immediate = config.immediate ?? true;
-  const enabled = config.enabled ?? true;
-
-  useEffect(() => {
-    if (!enabled) return;
-
-    let timer: ReturnType<typeof setInterval> | null = null;
-    let running = false;
-
-    function executeAction() {
-      if (running) return; // Prevent overlapping executions
-      running = true;
-      try {
-        const result = actionRef.current();
-        if (result instanceof Promise) {
-          result.finally(() => { running = false; });
-        } else {
-          running = false;
-        }
-      } catch {
-        running = false;
-      }
-    }
-
-    function startAction() {
-      if (timer) clearInterval(timer);
-      if (immediate) executeAction();
-      timer = setInterval(executeAction, intervalMs);
-    }
-
-    function stopAction() {
-      if (timer) {
-        clearInterval(timer);
-        timer = null;
-      }
-    }
-
-    // If already in target state, start immediately
-    if (states.includes(runtime.sm.currentState)) {
-      startAction();
-    }
-
-    const unsub = runtime.sm.on((event) => {
-      if (event.type === 'state_enter' && event.to_state && states.includes(event.to_state)) {
-        startAction();
-      }
-      if (event.type === 'state_exit' && event.from_state && states.includes(event.from_state)) {
-        stopAction();
-      }
-    });
-
-    return () => {
-      unsub();
-      stopAction();
-    };
-  }, [runtime, intervalMs, immediate, enabled, ...states]);
-}