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

package/src/index.ts

@@ -1,465 +0,0 @@
-/**
- * @mindmatrix/react — React integration for the MindMatrix Player.
- *
- * Modules:
- * - core: WorkflowRuntime class
- * - hooks: Effect hooks (useOnEnter, useOnExit, etc.), instance hooks (useWorkflow, useTransition)
- * - providers: RuntimeContext, WorkflowProvider
- * - local: LocalWorkflowEngine for P2P chat
- * - legacy: usePlayer, PlayerProvider (backward compatibility)
- */
-
-// ============================================================================
-// CORE RUNTIME
-// ============================================================================
-export { WorkflowRuntime } from './core/WorkflowRuntime';
-export type { RuntimeConfig, RuntimeSnapshot } from './core/WorkflowRuntime';
-
-// ============================================================================
-// EFFECT HOOKS
-// ============================================================================
-export { useOnEnter } from './hooks/useOnEnter';
-export { useOnExit } from './hooks/useOnExit';
-export { useOnTransition } from './hooks/useOnTransition';
-export { useOnEvent } from './hooks/useOnEvent';
-export type { EventPayload, UseOnEventOptions } from './hooks/useOnEvent';
-export { useOnChange } from './hooks/useOnChange';
-export { useWhileIn } from './hooks/useWhileIn';
-export { useDuringAction } from './hooks/useDuringAction';
-export type { DuringActionConfig } from './hooks/useDuringAction';
-
-// ============================================================================
-// DATA HOOKS
-// ============================================================================
-export { useQuery, setQueryResolver } from './hooks/useQuery';
-export type { QueryParams, QueryResult, QueryResolver } from './hooks/useQuery';
-export { useMutation, setMutationResolver } from './hooks/useMutation';
-export type { MutationHandle, TypedMutationHandle, MutationResolver } from './hooks/useMutation';
-export { useView, setViewResolver } from './hooks/useView';
-export type { ViewDefinitionResult, ViewRecord, ViewResolver } from './hooks/useView';
-export { useExpressionLibrary, setExpressionLibraryResolver } from './hooks/useExpressionLibrary';
-export type { ExpressionLibraryResult, LibraryParam, ExpressionLibraryRecord, ExpressionLibraryResolver } from './hooks/useExpressionLibrary';
-
-// ============================================================================
-// SERVER HOOKS
-// ============================================================================
-export { useServerAction, setServerActionResolver } from './hooks/useServerAction';
-export type { ServerActionOptions, ServerActionResult, ServerActionHandle, ServerActionResolver } from './hooks/useServerAction';
-export { useServerState, setServerStateResolver } from './hooks/useServerState';
-export type { ServerStateOptions, ServerStateSnapshot, ServerStateResult, ServerStateResolver } from './hooks/useServerState';
-
-// ============================================================================
-// INSTANCE HOOKS
-// ============================================================================
-export { useWorkflow } from './hooks/useWorkflow';
-export type { WorkflowHandle, UseWorkflowOptions } from './hooks/useWorkflow';
-export { useTransition } from './hooks/useTransition';
-export type { TransitionHandle } from './hooks/useTransition';
-export { useRole, setRoleHierarchy } from './hooks/useRole';
-export type { RoleResult, RoleOptions } from './hooks/useRole';
-export { useParams } from './hooks/useParams';
-export { usePackage } from './hooks/usePackage';
-export type { PackageManifest, PackageChild, PackageResult } from './hooks/usePackage';
-
-// ============================================================================
-// ROUTING HOOKS
-// ============================================================================
-export { useRouter } from './hooks/useRouter';
-export type {
-  RouterHandle,
-  RouterOptions,
-  RouteDefinition,
-  RouteGuard,
-  RouteLocation,
-} from './hooks/useRouter';
-export { useRouteParams } from './hooks/useRouteParams';
-export type { RouteParamsOptions } from './hooks/useRouteParams';
-
-// ============================================================================
-// REAL-TIME HOOKS
-// ============================================================================
-export { useRealtimeQuery, setRealtimeQueryResolver } from './hooks/useRealtimeQuery';
-export type { RealtimeQueryParams, RealtimeQueryResult } from './hooks/useRealtimeQuery';
-export { useChannel, setChannelTransport } from './hooks/useChannel';
-export type {
-  ChannelMessage,
-  ChannelOptions,
-  ChannelHandle,
-  ChannelTransport,
-} from './hooks/useChannel';
-
-// ============================================================================
-// GEOLOCATION HOOKS
-// ============================================================================
-export { useGeolocation } from './hooks/useGeolocation';
-export type {
-  GeoPosition,
-  GeolocationOptions,
-  GeolocationResult,
-  GeolocationError,
-} from './hooks/useGeolocation';
-export { useMapView } from './hooks/useMapView';
-export type {
-  LatLng,
-  LatLngBounds,
-  MapMarker,
-  MapViewOptions,
-  MapViewHandle,
-} from './hooks/useMapView';
-
-// ============================================================================
-// AUTH HOOKS
-// ============================================================================
-export { useAuth, setAuthResolver } from './hooks/useAuth';
-export type {
-  AuthUser,
-  LoginCredentials,
-  AuthOptions,
-  AuthResult,
-  AuthResolver,
-} from './hooks/useAuth';
-
-// ============================================================================
-// FORM HOOKS
-// ============================================================================
-export { useForm } from './hooks/useForm';
-export type {
-  FormValidator,
-  FieldValidator,
-  FormConfig,
-  FieldRegistration,
-  FormHandle,
-} from './hooks/useForm';
-
-// ============================================================================
-// NOTIFICATION HOOKS
-// ============================================================================
-export { useNotification } from './hooks/useNotification';
-export type { NotifyOptions, NotificationResult } from './hooks/useNotification';
-export { useToast } from './hooks/useToast';
-export type {
-  ToastVariant,
-  ToastConfig,
-  ToastInstance,
-  ToastHandle,
-} from './hooks/useToast';
-
-// ============================================================================
-// MIDDLEWARE
-// ============================================================================
-export { useMiddleware, requireAuth, requireRole, prefetchData } from './hooks/useMiddleware';
-export type {
-  MiddlewareResult,
-  MiddlewareContext,
-  MiddlewareFn,
-  MiddlewareOptions,
-  MiddlewareHandle,
-} from './hooks/useMiddleware';
-
-// ============================================================================
-// PROVIDERS
-// ============================================================================
-export { WorkflowProvider } from './providers/WorkflowProvider';
-export type { WorkflowProviderProps } from './providers/WorkflowProvider';
-export { RuntimeContext, useRuntimeContext } from './providers/RuntimeContext';
-
-// ============================================================================
-// LOCAL ENGINE (P2P)
-// ============================================================================
-export { LocalWorkflowEngine } from './local/LocalEngine';
-export type {
-  WorkflowState,
-  WorkflowTransition,
-  WorkflowFieldDef,
-  WorkflowDefinition,
-  WorkflowInstance,
-  WorkflowEvent,
-  WorkflowInstanceWithEvents,
-  WorkflowEventHandler,
-} from './local/LocalEngine';
-export { LocalEngineProvider, useLocalEngine } from './local/LocalEngineContext';
-export type { LocalEngineStore, LocalEngineContextValue } from './local/LocalEngineContext';
-export { createLocalEngineAdapter, createLocalDataResolver } from './local/LocalEngineAdapter';
-export type {
-  LocalEngineAdapter,
-  LocalDataResolver,
-  WorkflowDataSource,
-  DataSource,
-  DataSourceResult,
-  InstanceData,
-} from './local/LocalEngineAdapter';
-
-// ============================================================================
-// ACTION HELPERS
-// ============================================================================
-export {
-  setField, setFields,
-  logEvent,
-  notify,
-  spawn,
-  serverAction, deviceAction,
-  connector,
-  llm,
-  action,
-} from './actions';
-export type { ActionNotifyOptions, SpawnActionOptions, ActionOptions } from './actions';
-
-// ============================================================================
-// TYPE-SAFE ACTION & EVENT CREATORS
-// ============================================================================
-export { createActions } from './actionCreators';
-export type {
-  ActionManifestEntry,
-  ActionManifest,
-  ActionCreator,
-  ActionCreators,
-} from './actionCreators';
-
-// ============================================================================
-// MODEL & BLUEPRINT CONFIGURATION
-// ============================================================================
-export { defineModel } from './config/defineModel';
-export type {
-  ModelDefinition,
-  WorkflowFieldDescriptor,
-  FieldValidation,
-  ValidationRule,
-  StateHome,
-  ActionDefinition,
-  EventSubscription,
-  DuringAction,
-  StateDescriptor,
-  TransitionCondition,
-  TransitionDescriptor,
-  RoleDefinition,
-} from './config/defineModel';
-export { defineBlueprint } from './config/defineBlueprint';
-export type {
-  BlueprintConfig,
-  BlueprintManifest,
-  SlotContributions,
-  BlueprintRoute,
-  BlueprintSlotContribution,
-  BlueprintAction,
-  BlueprintConfigSchema,
-  BlueprintDependency,
-  ModuleRouteConfig,
-  SetupWizard,
-  SetupWizardStep,
-} from './config/defineBlueprint';
-
-// ============================================================================
-// CONDITION HELPERS
-// ============================================================================
-export {
-  expr, when,
-  hasRole, hasAnyRole,
-  isOwner, isActor, isSender, isCreator,
-  fieldEquals, fieldNotEquals, fieldGreaterThan, fieldLessThan,
-  fieldIn, fieldNotIn, fieldContains, fieldIsSet, fieldIsEmpty, fieldMatches,
-  inputRequired, inputEquals,
-  inState, notInState,
-  and, or, not,
-  refHasRole, refHasAnyRole,
-} from './conditions';
-
-// ============================================================================
-// TYPE INFERENCE UTILITIES
-// ============================================================================
-export type {
-  InferFields,
-  InferTransitions,
-  InferStates,
-  InferSlug,
-  InferFieldNames,
-  FieldTypeMap,
-} from './types/workflow-inference';
-
-// ============================================================================
-// MODEL HOOKS (recommended API for views)
-// ============================================================================
-export { useModel, useCollection } from './hooks/useModel';
-export type {
-  ModelHandle,
-  UseModelOptions,
-  CollectionHandle,
-  UseCollectionOptions,
-} from './hooks/useModel';
-
-// ============================================================================
-// COMPILE-TIME ATOM STUBS
-// ============================================================================
-export {
-  Stack, Row, Column, Grid, Divider, Spacer,
-  Text, Heading, Field, Image, Badge, Icon,
-  Button, Link,
-  Show, Each,
-  Card, Tabs, Accordion, Section, Modal,
-  TextInput, Select, Markdown, ScrollArea,
-  Canvas3D, DataGrid, AnimatedBox, ServerGrid, Chart, MetricCard,
-  Slot,
-  Router, Route, NavLink, RoleGuard,
-} from './atoms';
-
-// ============================================================================
-// GRAMMAR ISLANDS (Tagged Templates)
-// ============================================================================
-export { cedar, sql, cron, dmn, graphql, jsonpath } from './grammar';
-export type { GrammarIsland, CedarPolicy, CronFields, DmnRule } from './grammar';
-
-// ============================================================================
-// SERVER-SIDE TYPES
-// ============================================================================
-export type {
-  TransitionContext,
-  ActionResult,
-  InstanceRef,
-  ActionEnvironment,
-  SpawnOptions,
-  ServerActionFn,
-} from './server/transition-context';
-
-// ============================================================================
-// ROUTING
-// ============================================================================
-export { deriveInstanceKey, deriveInstanceKeySync } from './routing/instance-key';
-export type { InstanceKeyParams } from './routing/instance-key';
-
-// ============================================================================
-// RE-EXPORT PLAYER-CORE ESSENTIALS
-// ============================================================================
-export type {
-  PlayerWorkflowDefinition,
-  TransitionResult,
-  StateMachineEvent,
-  ExpressionContext,
-  RuntimeProfile,
-  IRStateHome,
-} from '@mindmatrix/player-core';
-
-// ============================================================================
-// AUTHORING API — compile-time declarations for .workflow.tsx files
-// The Babel plugin transforms these at compile time; they are not called
-// at runtime. Exported so TypeScript can type-check authored workflow files.
-// ============================================================================
-export { useState as useWorkflowState } from './authoring';
-export type { TransitionConfig } from './authoring';
-
-// ============================================================================
-// WORKSPACE / BLUEPRINT CONFIG
-// ============================================================================
-export { defineWorkspace } from './config/defineWorkspace';
-
-// ============================================================================
-// MODULE HOOKS
-// ============================================================================
-export { useModule } from './hooks/useModule';
-export type { ModuleHandle, UseModuleOptions } from './hooks/useModule';
-export { useModuleConfig, setInstalledModules, setModuleConfigDefaults, getInstalledModule, getInstalledModules } from './hooks/useModuleConfig';
-export type { InstalledModuleRef } from './hooks/useModuleConfig';
-
-// ============================================================================
-// MODULE SYSTEM (legacy aliases — modules and blueprints are the same thing)
-// ============================================================================
-export { defineModule } from './config/defineBlueprint';
-export type {
-  ModuleManifest,
-  ModuleRoute,
-  SlotContribution,
-  ModuleAction,
-  ModuleConfigSchema,
-  ModuleDependency,
-} from './config/defineBlueprint';
-
-// ============================================================================
-// BUILDER API — fluent chainable API for constructing ModelDefinitions
-// ============================================================================
-export {
-  model,
-  ModelBuilder,
-  field,
-  FieldBuilder,
-  state,
-  StateBuilder,
-  transition,
-  TransitionBuilder,
-  TypedTransitionBuilder,
-  createPipeline,
-  createCRUD,
-} from './builders';
-export type { ActionContext, ActionHandler, PipelineConfig, PipelineStage, CRUDConfig } from './builders';
-
-// ============================================================================
-// MODEL MIXINS
-// ============================================================================
-export {
-  applyMixins,
-  pipe,
-  withAuditTrail,
-  withSoftDelete,
-  withVersioning,
-  withRBAC,
-  withTimestamps,
-  withSlug,
-  withOwnership,
-  withTags,
-  withSearch,
-  withPagination,
-} from './mixins';
-export type {
-  ModelMixin,
-  WithAuditTrailOptions,
-  WithSoftDeleteOptions,
-  WithVersioningOptions,
-  WithRBACOptions,
-  WithSlugOptions,
-  WithOwnershipOptions,
-  WithSearchOptions,
-} from './mixins';
-
-// ============================================================================
-// BLUEPRINT BASE CLASS
-// ============================================================================
-export { Blueprint } from './Blueprint';
-export type { BlueprintViewDeclaration, BlueprintServerActionDeclaration } from './Blueprint';
-
-// ============================================================================
-// TRANSITION FACTORIES (reusable workflow patterns)
-// ============================================================================
-export { approval, escalation, review, crud } from './factories';
-export type { ApprovalConfig, EscalationConfig, ReviewConfig, CrudConfig } from './factories';
-
-// ============================================================================
-// TESTING UTILITIES
-// ============================================================================
-export { validateModel, assertModelValid, testModel, describeModel } from './testing';
-export type { ValidationIssue, ModelTestContext, TestStep, TestChain } from './testing';
-
-// ============================================================================
-// LEGACY EXPORTS (Backward Compatibility)
-// ============================================================================
-export * from './hooks';
-export * from './components';
-export * from './loader';
-export { setPlayerDebug, isPlayerDebug, playerLog } from './logger';
-export { BrowserPlayer } from './browser-player';
-export type {
-  BrowserPlayerConfig,
-  MmWasmModule,
-  PlayerInstance,
-  TransitionResult as BrowserTransitionResult,
-  PlayerEvent,
-  PlayerEventCallback,
-  Subscription,
-} from './browser-player';
-
-export type {
-  PlayerConfig,
-  PlayerHandle,
-  DomainEvent,
-  DomainSubscriptionConfig,
-  ExperienceWorkflowDefinition,
-  ExperienceViewConfig,
-  PlayerLogEntry,
-  PlayerEventListener,
-} from './types';

package/src/loader/experience-workflow-loader.ts

@@ -1,192 +0,0 @@
-/**
- * Experience Workflow Loader — loads and validates experience workflow definitions.
- *
- * Extends the player-core PlayerWorkflowDefinition concept for browser use:
- * - Validates definition structure (states, transitions, on_event patterns)
- * - Normalizes state types and transition arrays
- * - Extracts on_event subscriptions for the event bus
- * - Provides a loading function compatible with both JSON imports and HTTP fetch
- */
-
-import type { PlayerStateDefinition, PlayerTransitionDefinition } from '@mindmatrix/player-core';
-import type { ExperienceWorkflowDefinition } from '../types';
-import { playerLog } from '../logger';
-
-export interface ValidationResult {
-  valid: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
-/**
- * Validate an experience workflow definition.
- * Returns errors for structural issues, warnings for best-practice violations.
- */
-export function validateExperienceWorkflow(def: unknown): ValidationResult {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  if (!def || typeof def !== 'object') {
-    return { valid: false, errors: ['Definition must be an object'], warnings };
-  }
-
-  const d = def as Record<string, unknown>;
-
-  // Required fields
-  if (!d.id || typeof d.id !== 'string') errors.push('Missing or invalid "id" field');
-  if (!d.slug || typeof d.slug !== 'string') errors.push('Missing or invalid "slug" field');
-
-  // States validation
-  if (!Array.isArray(d.states) || d.states.length === 0) {
-    errors.push('Definition must have at least one state');
-  } else {
-    const stateNames = new Set<string>();
-    let hasStart = false;
-
-    for (const state of d.states as Record<string, unknown>[]) {
-      if (!state.name || typeof state.name !== 'string') {
-        errors.push('Each state must have a "name" string');
-        continue;
-      }
-
-      if (stateNames.has(state.name)) {
-        errors.push(`Duplicate state name: "${state.name}"`);
-      }
-      stateNames.add(state.name);
-
-      if (state.type === 'START') hasStart = true;
-
-      // Validate on_event subscriptions
-      if (Array.isArray(state.on_event)) {
-        for (const sub of state.on_event as Record<string, unknown>[]) {
-          if (!sub.match && !sub.pattern) {
-            errors.push(`on_event in state "${state.name}" missing "match" or "pattern" field`);
-          }
-          if (!Array.isArray(sub.actions) || sub.actions.length === 0) {
-            warnings.push(`on_event in state "${state.name}" has no actions`);
-          }
-        }
-      }
-    }
-
-    if (!hasStart) errors.push('Definition must have a START state');
-  }
-
-  // Transitions validation
-  if (!Array.isArray(d.transitions)) {
-    errors.push('Definition must have a "transitions" array');
-  } else {
-    const stateNames = new Set((d.states as { name: string }[]).map(s => s.name));
-
-    for (const t of d.transitions as Record<string, unknown>[]) {
-      if (!t.name || typeof t.name !== 'string') {
-        errors.push('Each transition must have a "name" string');
-      }
-      if (!t.to || typeof t.to !== 'string') {
-        errors.push(`Transition "${t.name}" missing "to" state`);
-      } else if (!stateNames.has(t.to as string)) {
-        errors.push(`Transition "${t.name}" targets unknown state "${t.to}"`);
-      }
-      if (!Array.isArray(t.from) || t.from.length === 0) {
-        errors.push(`Transition "${t.name}" must have non-empty "from" array`);
-      } else {
-        for (const f of t.from as string[]) {
-          if (!stateNames.has(f)) {
-            errors.push(`Transition "${t.name}" references unknown "from" state "${f}"`);
-          }
-        }
-      }
-    }
-  }
-
-  return { valid: errors.length === 0, errors, warnings };
-}
-
-/**
- * Normalize a raw JSON object into an ExperienceWorkflowDefinition.
- * Applies defaults and coerces common variations.
- */
-export function normalizeDefinition(raw: Record<string, unknown>): ExperienceWorkflowDefinition {
-  const states = (raw.states as Record<string, unknown>[]).map((s): PlayerStateDefinition => ({
-    name: s.name as string,
-    type: (s.type as PlayerStateDefinition['type']) ?? 'REGULAR',
-    on_enter: s.on_enter as PlayerStateDefinition['on_enter'],
-    on_exit: s.on_exit as PlayerStateDefinition['on_exit'],
-    on_event: ((s.on_event as Record<string, unknown>[]) ?? []).map(sub => ({
-      // Support both "match" and "pattern" field names
-      match: (sub.match ?? sub.pattern) as string,
-      conditions: sub.conditions as string[] | undefined,
-      actions: (sub.actions as PlayerStateDefinition['on_enter']) ?? [],
-    })),
-  }));
-
-  const transitions = (raw.transitions as Record<string, unknown>[]).map((t): PlayerTransitionDefinition => ({
-    name: t.name as string,
-    from: Array.isArray(t.from) ? t.from as string[] : [t.from as string],
-    to: t.to as string,
-    conditions: t.conditions as string[] | undefined,
-    auto: t.auto as boolean | undefined,
-    actions: t.actions as PlayerTransitionDefinition['actions'],
-  }));
-
-  return {
-    id: raw.id as string,
-    slug: raw.slug as string,
-    states,
-    transitions,
-    state_views: raw.state_views as ExperienceWorkflowDefinition['state_views'],
-    experience: raw.experience as ExperienceWorkflowDefinition['experience'],
-  };
-}
-
-/**
- * Load and validate an experience workflow definition from a URL or JSON object.
- */
-export async function loadExperienceWorkflow(
-  source: string | Record<string, unknown>,
-): Promise<{ definition: ExperienceWorkflowDefinition; validation: ValidationResult }> {
-  let raw: Record<string, unknown>;
-
-  if (typeof source === 'string') {
-    playerLog({
-      level: 'debug',
-      category: 'lifecycle',
-      message: `Loading experience workflow from URL: ${source}`,
-    });
-    const response = await fetch(source);
-    if (!response.ok) {
-      throw new Error(`Failed to load experience workflow: ${response.status} ${response.statusText}`);
-    }
-    raw = await response.json();
-  } else {
-    raw = source;
-  }
-
-  const validation = validateExperienceWorkflow(raw);
-
-  if (!validation.valid) {
-    playerLog({
-      level: 'error',
-      category: 'lifecycle',
-      message: `Experience workflow validation failed: ${validation.errors.join('; ')}`,
-    });
-  }
-
-  if (validation.warnings.length > 0) {
-    playerLog({
-      level: 'warn',
-      category: 'lifecycle',
-      message: `Experience workflow warnings: ${validation.warnings.join('; ')}`,
-    });
-  }
-
-  const definition = validation.valid ? normalizeDefinition(raw) : normalizeDefinition({
-    id: 'invalid',
-    slug: 'invalid',
-    states: [{ name: 'error', type: 'START' }],
-    transitions: [],
-    ...raw,
-  });
-
-  return { definition, validation };
-}

package/src/loader/index.ts

@@ -1,6 +0,0 @@
-export {
-  validateExperienceWorkflow,
-  normalizeDefinition,
-  loadExperienceWorkflow,
-} from './experience-workflow-loader';
-export type { ValidationResult } from './experience-workflow-loader';