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

package/src/providers/RuntimeContext.ts

@@ -1,20 +0,0 @@
-/**
- * RuntimeContext — React Context for WorkflowRuntime
- *
- * Provides the runtime instance to all effect hooks via useRuntimeContext.
- */
-
-import { createContext, useContext } from 'react';
-import type { WorkflowRuntime } from '../core/WorkflowRuntime';
-
-export const RuntimeContext = createContext<WorkflowRuntime | null>(null);
-
-export function useRuntimeContext(): WorkflowRuntime {
-  const runtime = useContext(RuntimeContext);
-  if (!runtime) {
-    throw new Error(
-      'useRuntimeContext must be used within a WorkflowProvider or RuntimeContext.Provider'
-    );
-  }
-  return runtime;
-}

package/src/providers/WorkflowProvider.tsx

@@ -1,28 +0,0 @@
-/**
- * WorkflowProvider — Provider for WorkflowRuntime with QueryClient
- *
- * Wraps children with RuntimeContext and QueryClientProvider.
- * Provides the runtime instance to all effect hooks and useRuntimeContext.
- */
-
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { RuntimeContext } from './RuntimeContext';
-import type { WorkflowRuntime } from '../core/WorkflowRuntime';
-
-const defaultQueryClient = new QueryClient();
-
-export interface WorkflowProviderProps {
-  runtime: WorkflowRuntime;
-  queryClient?: QueryClient;
-  children: React.ReactNode;
-}
-
-export function WorkflowProvider({ runtime, queryClient, children }: WorkflowProviderProps) {
-  return (
-    <QueryClientProvider client={queryClient ?? defaultQueryClient}>
-      <RuntimeContext.Provider value={runtime}>
-        {children}
-      </RuntimeContext.Provider>
-    </QueryClientProvider>
-  );
-}

package/src/routing/instance-key.ts

@@ -1,107 +0,0 @@
-/**
- * Instance Key Derivation — deterministic key generation for workflow instances.
- *
- * When a blueprint mounts at a route, it needs a stable instance key that
- * uniquely identifies the workflow instance for that route + parameters.
- *
- * The key is derived from:
- *   sha256(blueprintSlug + ":" + layoutPath + ":" + sortedParams)
- *
- * This ensures:
- * - Same route + same params → same instance (idempotent)
- * - Different params → different instances (e.g., /chat/123 vs /chat/456)
- * - Deterministic across page refreshes
- * - No collision between blueprints
- *
- * Usage:
- *   import { deriveInstanceKey, deriveInstanceKeySync } from '@mindmatrix/react';
- *
- *   const key = deriveInstanceKeySync('mm-chat', '/chat/[channelId]', { channelId: '123' });
- *   // → 'mm-chat:a1b2c3d4'
- */
-
-// =============================================================================
-// Types
-// =============================================================================
-
-export interface InstanceKeyParams {
-  [key: string]: string;
-}
-
-// =============================================================================
-// Key derivation
-// =============================================================================
-
-/**
- * Derives a deterministic instance key from blueprint slug, layout path, and route params.
- * Uses Web Crypto API (async).
- */
-export async function deriveInstanceKey(
-  blueprintSlug: string,
-  layoutPath: string,
-  params: InstanceKeyParams = {}
-): Promise<string> {
-  const input = buildKeyInput(blueprintSlug, layoutPath, params);
-
-  // Use Web Crypto API for SHA-256
-  const encoder = new TextEncoder();
-  const data = encoder.encode(input);
-  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-  const hashArray = Array.from(new Uint8Array(hashBuffer));
-  const hashHex = hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
-
-  // Return slug prefix + first 16 hex chars (64-bit uniqueness)
-  return `${blueprintSlug}:${hashHex.substring(0, 16)}`;
-}
-
-/**
- * Derives a deterministic instance key synchronously.
- * Uses a simple hash function (djb2) instead of SHA-256.
- * Suitable for non-cryptographic contexts where async is inconvenient.
- */
-export function deriveInstanceKeySync(
-  blueprintSlug: string,
-  layoutPath: string,
-  params: InstanceKeyParams = {}
-): string {
-  const input = buildKeyInput(blueprintSlug, layoutPath, params);
-  const hash = djb2Hash(input);
-  return `${blueprintSlug}:${hash}`;
-}
-
-/**
- * Builds the canonical key input string.
- * Params are sorted alphabetically for determinism.
- */
-function buildKeyInput(
-  blueprintSlug: string,
-  layoutPath: string,
-  params: InstanceKeyParams
-): string {
-  const sortedParams = Object.keys(params)
-    .sort()
-    .map((k) => `${k}=${params[k]}`)
-    .join('&');
-
-  return `${blueprintSlug}:${layoutPath}:${sortedParams}`;
-}
-
-/**
- * DJB2 hash function — fast, deterministic, non-cryptographic.
- * Returns a 16-character hex string.
- */
-function djb2Hash(str: string): string {
-  let hash1 = 5381;
-  let hash2 = 52711;
-
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash1 = ((hash1 << 5) + hash1 + char) | 0; // hash * 33 + char
-    hash2 = ((hash2 << 5) + hash2 + char) | 0;
-  }
-
-  // Combine both hashes for 64 bits of entropy
-  const h1 = (hash1 >>> 0).toString(16).padStart(8, '0');
-  const h2 = (hash2 >>> 0).toString(16).padStart(8, '0');
-  return h1 + h2;
-}

package/src/server/transition-context.ts

@@ -1,172 +0,0 @@
-/**
- * TransitionContext — server-side API contract for workflow actions.
- *
- * This is the full server-side API available to action handlers running
- * on the backend. The React compiler generates references to these actions,
- * and the backend runtime provides the concrete implementation.
- *
- * Usage in action files (actions.server.ts):
- *   import type { TransitionContext } from '@mindmatrix/react/server';
- *
- *   export async function notifyMembers(ctx: TransitionContext) {
- *     const channel = ctx.stateData;
- *     const members = await ctx.refs('member', { channel_id: ctx.env.instance_id });
- *     for (const member of members) {
- *       await ctx.emit('notification:send', { user_id: member.stateData.user_id });
- *     }
- *   }
- *
- * Data Model (4 layers — matching backend):
- *   1. stateData: user-facing form data (fields)
- *   2. memory: internal persistent state (not visible to user)
- *   3. actionResults: results from previous actions in this transition
- *   4. context: read-only external context injected by runtime
- */
-
-// =============================================================================
-// Types
-// =============================================================================
-
-/**
- * Result from a previous action execution within the same transition.
- */
-export interface ActionResult {
-  actionId: string;
-  success: boolean;
-  data?: unknown;
-  error?: string;
-}
-
-/**
- * Reference to another workflow instance.
- */
-export interface InstanceRef {
-  id: string;
-  slug: string;
-  currentState: string;
-  stateData: Record<string, unknown>;
-  memory: Record<string, unknown>;
-  createdAt: string;
-  updatedAt: string;
-}
-
-/**
- * Query parameters for cross-instance queries.
- */
-export interface RefQuery {
-  [field: string]: unknown;
-  limit?: number;
-  offset?: number;
-  orderBy?: string;
-  order?: 'asc' | 'desc';
-}
-
-/**
- * Query parameters for the query() function.
- */
-export interface QueryParams {
-  slug?: string;
-  state?: string | string[];
-  filter?: Record<string, unknown>;
-  limit?: number;
-  offset?: number;
-  orderBy?: string;
-  order?: 'asc' | 'desc';
-}
-
-/**
- * Options for spawning a sub-workflow instance.
- */
-export interface SpawnOptions {
-  /** Whether to wait for the spawned workflow to reach an end state. */
-  blocking?: boolean;
-  /** Map parent fields to child input fields. */
-  input_mapping?: Record<string, string>;
-  /** Map child output fields back to parent fields. */
-  output_mapping?: Record<string, string>;
-  /** What to do if the spawned workflow fails. */
-  on_failure?: 'fail' | 'retry' | 'transition' | 'manual';
-  /** For retry: max number of retries. */
-  max_retries?: number;
-  /** For transition: which transition to fire on failure. */
-  failure_transition?: string;
-}
-
-/**
- * Runtime environment information available during action execution.
- */
-export interface ActionEnvironment {
-  tenant_id: string;
-  user_id: string;
-  instance_id: string;
-  definition_slug: string;
-  definition_version: string;
-  current_state: string;
-  transition_name: string;
-}
-
-/**
- * The full server-side API available to workflow action handlers.
- *
- * This interface matches the backend's ActionExecutionContext.
- */
-export interface TransitionContext {
-  // =========================================================================
-  // Data Layers (read)
-  // =========================================================================
-
-  /** User-facing form data (workflow fields). */
-  readonly stateData: Record<string, unknown>;
-  /** Internal persistent state (not visible to users). */
-  readonly memory: Record<string, unknown>;
-  /** Results from previous actions in this transition. */
-  readonly actionResults: Record<string, ActionResult>;
-  /** Read-only external context injected by the runtime. */
-  readonly context: Record<string, unknown>;
-
-  // =========================================================================
-  // Environment
-  // =========================================================================
-
-  /** Runtime environment information. */
-  readonly env: ActionEnvironment;
-
-  // =========================================================================
-  // Cross-Instance References
-  // =========================================================================
-
-  /** Get a single instance by slug and id. */
-  ref: (slug: string, id: string) => Promise<InstanceRef>;
-  /** Query instances by slug and filter. */
-  refs: (slug: string, query: RefQuery) => Promise<InstanceRef[]>;
-
-  // =========================================================================
-  // Mutations
-  // =========================================================================
-
-  /** Set a workflow field value. */
-  setField: (field: string, value: unknown) => void;
-  /** Set an internal memory value. */
-  setMemory: (key: string, value: unknown) => void;
-  /** Emit a domain event. */
-  emit: (event: string, payload?: Record<string, unknown>) => void;
-  /** Log a message with optional structured data. */
-  log: (message: string, data?: Record<string, unknown>) => void;
-  /** Fire a transition on the current instance. */
-  transition: (name: string) => void;
-
-  // =========================================================================
-  // Cross-Instance Operations
-  // =========================================================================
-
-  /** Query workflow instances. */
-  query: <T = Record<string, unknown>>(slug: string, params: QueryParams) => Promise<T[]>;
-  /** Spawn a sub-workflow instance. */
-  spawn: (slug: string, input?: Record<string, unknown>, options?: SpawnOptions) => Promise<string>;
-}
-
-/**
- * Server action function signature.
- * Exported functions in *.server.ts files must match this shape.
- */
-export type ServerActionFn = (ctx: TransitionContext) => void | Promise<void>;

package/src/testing/index.ts

@@ -1,9 +0,0 @@
-/**
- * Testing hooks — React integration for the Testing OS.
- */
-
-export { useGraphAnalysis } from './useGraphAnalysis';
-export { useTestRunner } from './useTestRunner';
-export type { TestRunnerHandle } from './useTestRunner';
-export { useBlueprintTestRunner } from './useBlueprintTestRunner';
-export type { BlueprintTestRunnerHandle } from './useBlueprintTestRunner';

package/src/testing/useBlueprintTestRunner.ts

@@ -1,91 +0,0 @@
-/**
- * useBlueprintTestRunner — React hook for executing test Blueprints.
- *
- * The test IS a Blueprint running on a Player. This hook wraps the
- * Blueprint test runner with React state management.
- *
- * Supports two execution modes:
- * - in-process: StateMachines in memory (sub-millisecond)
- * - api: HTTP calls to running NestJS backend (MM Server Player)
- *
- * For API mode, provide an ApiTestAdapter via the config.
- */
-
-import { useCallback, useRef, useState } from 'react';
-import { runBlueprintTestProgram } from '@mindmatrix/player-core';
-import type {
-  TestProgram,
-  TestProgramResult,
-  StepResult,
-  BlueprintRunnerConfig,
-} from '@mindmatrix/player-core';
-
-export interface BlueprintTestRunnerHandle {
-  run: (program: TestProgram) => Promise<TestProgramResult>;
-  cancel: () => void;
-  result: TestProgramResult | null;
-  running: boolean;
-  liveSteps: StepResult[];
-  mode: 'in-process' | 'api';
-  reset: () => void;
-}
-
-export function useBlueprintTestRunner(
-  config: Omit<BlueprintRunnerConfig, 'onStepComplete' | 'onScenarioComplete' | 'abortSignal'>,
-): BlueprintTestRunnerHandle {
-  const [result, setResult] = useState<TestProgramResult | null>(null);
-  const [running, setRunning] = useState(false);
-  const [liveSteps, setLiveSteps] = useState<StepResult[]>([]);
-  const abortControllerRef = useRef<AbortController | null>(null);
-
-  const run = useCallback(
-    async (program: TestProgram): Promise<TestProgramResult> => {
-      abortControllerRef.current?.abort();
-      const controller = new AbortController();
-      abortControllerRef.current = controller;
-
-      setRunning(true);
-      setResult(null);
-      setLiveSteps([]);
-
-      const runnerConfig: BlueprintRunnerConfig = {
-        ...config,
-        abortSignal: controller.signal,
-        onStepComplete: (_scenarioIdx, step) => {
-          setLiveSteps(prev => [...prev, step]);
-        },
-      } as BlueprintRunnerConfig;
-
-      const programResult = await runBlueprintTestProgram(program, runnerConfig);
-      setResult(programResult);
-      setRunning(false);
-      abortControllerRef.current = null;
-      return programResult;
-    },
-    [config],
-  );
-
-  const cancel = useCallback(() => {
-    abortControllerRef.current?.abort();
-    abortControllerRef.current = null;
-    setRunning(false);
-  }, []);
-
-  const reset = useCallback(() => {
-    abortControllerRef.current?.abort();
-    abortControllerRef.current = null;
-    setResult(null);
-    setRunning(false);
-    setLiveSteps([]);
-  }, []);
-
-  return {
-    run,
-    cancel,
-    result,
-    running,
-    liveSteps,
-    mode: config.mode,
-    reset,
-  };
-}

package/src/testing/useGraphAnalysis.ts

@@ -1,18 +0,0 @@
-/**
- * useGraphAnalysis — React hook for static analysis of workflow definitions.
- *
- * Wraps analyzeDefinition in useMemo for synchronous, sub-ms analysis.
- */
-
-import { useMemo } from 'react';
-import { analyzeDefinition } from '@mindmatrix/player-core';
-import type { PlayerWorkflowDefinition, AnalysisResult } from '@mindmatrix/player-core';
-
-export function useGraphAnalysis(
-  definition: PlayerWorkflowDefinition | null,
-): AnalysisResult | null {
-  return useMemo(() => {
-    if (!definition) return null;
-    return analyzeDefinition(definition);
-  }, [definition]);
-}

package/src/testing/useTestRunner.ts

@@ -1,77 +0,0 @@
-/**
- * useTestRunner — React hook for executing test programs.
- *
- * Returns a handle to run test programs, cancel execution,
- * and observe live step-by-step results.
- */
-
-import { useCallback, useRef, useState } from 'react';
-import { runTestProgram } from '@mindmatrix/player-core';
-import type {
-  TestProgram,
-  TestProgramResult,
-  StepResult,
-  TestRunnerConfig,
-} from '@mindmatrix/player-core';
-
-export interface TestRunnerHandle {
-  run: (program: TestProgram) => Promise<TestProgramResult>;
-  cancel: () => void;
-  result: TestProgramResult | null;
-  running: boolean;
-  liveSteps: StepResult[];
-  reset: () => void;
-}
-
-export function useTestRunner(config?: Partial<TestRunnerConfig>): TestRunnerHandle {
-  const [result, setResult] = useState<TestProgramResult | null>(null);
-  const [running, setRunning] = useState(false);
-  const [liveSteps, setLiveSteps] = useState<StepResult[]>([]);
-  const abortControllerRef = useRef<AbortController | null>(null);
-
-  const run = useCallback(
-    async (program: TestProgram): Promise<TestProgramResult> => {
-      // Cancel any in-flight run
-      abortControllerRef.current?.abort();
-      const controller = new AbortController();
-      abortControllerRef.current = controller;
-
-      setRunning(true);
-      setResult(null);
-      setLiveSteps([]);
-
-      const runnerConfig: TestRunnerConfig = {
-        ...config,
-        abortSignal: controller.signal,
-        onStepComplete: (_scenarioIdx, step) => {
-          setLiveSteps(prev => [...prev, step]);
-          config?.onStepComplete?.(_scenarioIdx, step);
-        },
-        onScenarioComplete: config?.onScenarioComplete,
-      };
-
-      const programResult = await runTestProgram(program, runnerConfig);
-      setResult(programResult);
-      setRunning(false);
-      abortControllerRef.current = null;
-      return programResult;
-    },
-    [config],
-  );
-
-  const cancel = useCallback(() => {
-    abortControllerRef.current?.abort();
-    abortControllerRef.current = null;
-    setRunning(false);
-  }, []);
-
-  const reset = useCallback(() => {
-    abortControllerRef.current?.abort();
-    abortControllerRef.current = null;
-    setResult(null);
-    setRunning(false);
-    setLiveSteps([]);
-  }, []);
-
-  return { run, cancel, result, running, liveSteps, reset };
-}