@mmapp/player-core 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -0,0 +1,66 @@
+# @mmapp/player-core
+
+Framework-agnostic workflow engine for browser-side state machines, expression evaluation, and event-driven reactions.
+
+Published on npm as `@mmapp/player-core` (internal workspace name: `@mindmatrix/player-core`).
+
+## Installation
+
+```bash
+npm install @mmapp/player-core
+```
+
+## What's Inside
+
+- **StateMachine** — state machine interpreter with transition guards, actions, and event subscriptions
+- **ActionDispatcher** — action execution pipeline with failure policies
+- **EventBus** — pub/sub event system with pattern matching
+- **Evaluator** — expression evaluation engine (Pratt parser + tree-walk)
+- **DSL Compiler** — compiles workflow DSL to IR (Intermediate Representation)
+- **Validator** — validates workflow definitions against the IR schema
+- **Testing** — test runner, blueprint test runner, graph analysis, NRT tracing
+
+## Usage
+
+```typescript
+import { StateMachine, createEvaluator, validateDefinition } from '@mmapp/player-core';
+
+// Validate a workflow definition
+const errors = validateDefinition(myDefinition);
+
+// Create and run a state machine
+const machine = new StateMachine(myDefinition);
+machine.transition('submit');
+```
+
+## npm Publishing
+
+This package is published to npm under the `@mmapp` scope.
+
+| npm name | workspace name | current version |
+|----------|---------------|-----------------|
+| `@mmapp/player-core` | `@mindmatrix/player-core` | 0.1.0-alpha.1 |
+
+### Publishing a new version
+
+Use the publish script from the monorepo root:
+
+```bash
+# Publish all 3 packages (player-core, react, react-compiler)
+./scripts/publish-npm.sh patch   # 0.1.0-alpha.1 → 0.1.0-alpha.2
+./scripts/publish-npm.sh minor   # 0.1.0-alpha.1 → 0.2.0-alpha.1
+./scripts/publish-npm.sh 0.2.0-beta.1  # explicit version
+```
+
+Or publish just this package:
+
+```bash
+cd packages/player-core
+pnpm run publish:alpha          # auto-increments alpha version
+```
+
+### Version strategy
+
+- `0.1.0-alpha.X` — internal development (current)
+- `0.1.0-beta.X` — user testing
+- `1.0.0` — production launch

package/dist/index.d.mts

@@ -360,6 +360,8 @@ declare class ActionDispatcher {
     execute(actions: ActionDefinition[], context: ExpressionContext, evaluator?: Evaluator): Promise<ActionResult[]>;
     /** Get count of registered handlers */
     get size(): number;
+    /** Get all registered action type names */
+    getRegisteredTypes(): string[];
     /** Remove all handlers */
     clear(): void;
 }
@@ -1039,6 +1041,8 @@ interface IRActionDefinition {
     mode: IRActionMode;
     config: Record<string, unknown>;
     condition?: string;
+    /** Saga compensation: action to run if a subsequent action fails (Design 28). */
+    compensate?: IRActionDefinition;
 }
 interface IRDuringAction {
     id: string;
@@ -1072,6 +1076,8 @@ interface IRStateDefinition {
     during: IRDuringAction[];
     on_exit: IRActionDefinition[];
     on_event?: IROnEventSubscription[];
+    /** Where this state executes at runtime (server, client, worker, edge, any). */
+    runtime?: string;
 }
 interface IRConditionDefinition {
     type?: string;
@@ -1092,6 +1098,8 @@ interface IRTransitionDefinition {
     roles?: string[];
     auto?: boolean;
     required_fields?: string[];
+    /** Where this transition executes at runtime (server, client, worker, edge, any). */
+    runtime?: string;
 }
 interface IRFieldValidation {
     min?: number;
@@ -1378,6 +1386,84 @@ declare function validateDefinition(def: IRWorkflowDefinition, options?: Validat
  */
 declare function isViableDefinition(def: unknown): def is IRWorkflowDefinition;
 
+/**
+ * Player Capability Declaration & Compatibility Check (ISS-059)
+ *
+ * Each player runtime (web, iOS, console, TUI) declares its capabilities
+ * via a PlayerManifest. When loading a blueprint, the compatibility checker
+ * compares manifest against requirements to produce warnings/errors.
+ *
+ * This is informational, not blocking — players should still attempt to render.
+ */
+/** Declares what a player runtime can render and execute. */
+interface PlayerManifest {
+    /** Player identifier (e.g., "web", "ios", "console", "tui") */
+    player: string;
+    /** Player version */
+    version: string;
+    /** Supported atom component IDs */
+    atoms: string[];
+    /** Supported action types */
+    actions: string[];
+    /** Whether the player can evaluate expressions natively */
+    expressions: boolean;
+    /** Whether the player works offline */
+    offline: boolean;
+}
+/** What a blueprint requires from a player to render correctly. */
+interface BlueprintRequirements {
+    /** Atom component IDs used in the experience tree */
+    atoms: string[];
+    /** Action types referenced in transitions/states */
+    actions: string[];
+    /** Whether the blueprint uses expressions */
+    expressions: boolean;
+}
+/** Result of comparing a PlayerManifest against BlueprintRequirements. */
+interface CompatibilityResult {
+    /** Whether the player can render the blueprint without missing critical features */
+    compatible: boolean;
+    /** Atom component IDs the blueprint uses but the player doesn't support */
+    missingAtoms: string[];
+    /** Action types the blueprint references but the player can't handle */
+    missingActions: string[];
+    /** Human-readable warnings (non-blocking issues) */
+    warnings: string[];
+}
+/**
+ * Compare a player's capabilities against a blueprint's requirements.
+ *
+ * Missing atoms produce warnings (graceful degradation — render fallback).
+ * Missing actions produce errors (may cause runtime failures).
+ * The check is informational — players should still attempt to load.
+ */
+declare function checkCompatibility(manifest: PlayerManifest, requirements: BlueprintRequirements): CompatibilityResult;
+/**
+ * Walk a JSON experience tree and transition/state actions to extract
+ * all atom component IDs and action types referenced.
+ *
+ * This mirrors the Rust `WorkflowDefinition::extract_requirements()`.
+ */
+declare function extractRequirements(definition: {
+    experience?: unknown;
+    states?: Array<{
+        on_enter?: Array<{
+            action_type?: string;
+            type?: string;
+        }>;
+        on_exit?: Array<{
+            action_type?: string;
+            type?: string;
+        }>;
+    }>;
+    transitions?: Array<{
+        actions?: Array<{
+            action_type?: string;
+            type?: string;
+        }>;
+    }>;
+}): BlueprintRequirements;
+
 /**
  * DSL Compiler — entry point.
  *
@@ -1433,4 +1519,4 @@ declare function normalizeDefinition(def: Record<string, unknown>): MigrationRes
  */
 declare function needsMigration(def: Record<string, unknown>): boolean;
 
-export { type ActionDefinition, ActionDispatcher, type ActionHandler, type ActionHandlerFn, type ActionRecorder, type ActionResult, type ActionTick, type ActionTrace, type AnalysisResult, type AnalysisSummary, type ApiInstanceSnapshot, type ApiTestAdapter, type ApiTestRunnerConfig, type ApiTransitionResult, type AssertionResult, type BlueprintRunnerConfig, type BusEvent, CORE_FUNCTIONS, CURRENT_IR_VERSION, type CompilationResult, type CompiledOutput, type CompilerError, type CompilerErrorCode, type Evaluator, type EvaluatorConfig, EventBus, type EventHandler, type EventSubscription, type ExpressionContext, type ExpressionDiagnostics, type ExpressionFunction, type ExpressionResult, type FailurePolicy, type FailurePolicyContext, type GraphPath, type IRActionDefinition, type IRActionMode, type IRApiDataSource, type IRBlueprintManifest, type IRConditionDefinition, type IRDataSource, type IRDuringAction, type IRExperienceDefinition, type IRExperienceNode, type IRFieldDefinition, type IRFieldValidation, type IRGrammarIsland, type IROnEventAction, type IROnEventSubscription, type IRRefDataSource, type IRRoleDefinition, type IRStateDefinition, type IRStateHome, type IRStateType, type IRStaticDataSource, type IRTransitionDefinition, type IRWorkflowDataSource, type IRWorkflowDefinition, type IRWorkflowFieldType, type MigrationResult, type NRT, type NRTChange, type NRTDiff, type NRTEvent, type NRTEventTarget, type NRTNavState, type NRTNode, type PlayerAction, type PlayerInstance, type PlayerOnEventSubscription, type PlayerStateDefinition, type PlayerTransitionDefinition, type PlayerWorkflowDefinition, type PureFormWorkflow, type RuntimeProfile, type ScenarioResult, StateMachine, type StateMachineConfig, type StateMachineEvent, type StateMachineListener, type StateNode, type StateType, type StepResult, type TestActionState, type TestAssertion, type TestInstance, type TestProgram, type TestProgramResult, type TestRunnerConfig, type TestScenario, type TestStep, type TransitionEdge, type TransitionResult, type Unsubscribe, type ValidationCategory, type ValidationIssue, type ValidationResult, type ValidationSeverity, type ValidatorOptions, WEB_FAILURE_POLICIES, analyzeDefinition, buildFunctionMap, clearExpressionCache, clearPatternCache, compareNRT, compile, compilePattern, compileTestProgram, compileTestScenario, countByKind, countNodes, createActionRecorder, createApiTestActions, createEmptyNRT, createEvaluator, createInProcessTestActions, detectIRVersion, findInteractiveNodes, findNode, findVisibleNodes, generateCoverageScenarios, getFinalState, getTransitionPath, hasTransition, isViableDefinition, matchTopic, needsMigration, normalizeCategory, normalizeDefinition, runBlueprintScenario, runBlueprintTestProgram, runScenario, runTestProgram, validateDefinition };
+export { type ActionDefinition, ActionDispatcher, type ActionHandler, type ActionHandlerFn, type ActionRecorder, type ActionResult, type ActionTick, type ActionTrace, type AnalysisResult, type AnalysisSummary, type ApiInstanceSnapshot, type ApiTestAdapter, type ApiTestRunnerConfig, type ApiTransitionResult, type AssertionResult, type BlueprintRequirements, type BlueprintRunnerConfig, type BusEvent, CORE_FUNCTIONS, CURRENT_IR_VERSION, type CompatibilityResult, type CompilationResult, type CompiledOutput, type CompilerError, type CompilerErrorCode, type Evaluator, type EvaluatorConfig, EventBus, type EventHandler, type EventSubscription, type ExpressionContext, type ExpressionDiagnostics, type ExpressionFunction, type ExpressionResult, type FailurePolicy, type FailurePolicyContext, type GraphPath, type IRActionDefinition, type IRActionMode, type IRApiDataSource, type IRBlueprintManifest, type IRConditionDefinition, type IRDataSource, type IRDuringAction, type IRExperienceDefinition, type IRExperienceNode, type IRFieldDefinition, type IRFieldValidation, type IRGrammarIsland, type IROnEventAction, type IROnEventSubscription, type IRRefDataSource, type IRRoleDefinition, type IRStateDefinition, type IRStateHome, type IRStateType, type IRStaticDataSource, type IRTransitionDefinition, type IRWorkflowDataSource, type IRWorkflowDefinition, type IRWorkflowFieldType, type MigrationResult, type NRT, type NRTChange, type NRTDiff, type NRTEvent, type NRTEventTarget, type NRTNavState, type NRTNode, type PlayerAction, type PlayerInstance, type PlayerManifest, type PlayerOnEventSubscription, type PlayerStateDefinition, type PlayerTransitionDefinition, type PlayerWorkflowDefinition, type PureFormWorkflow, type RuntimeProfile, type ScenarioResult, StateMachine, type StateMachineConfig, type StateMachineEvent, type StateMachineListener, type StateNode, type StateType, type StepResult, type TestActionState, type TestAssertion, type TestInstance, type TestProgram, type TestProgramResult, type TestRunnerConfig, type TestScenario, type TestStep, type TransitionEdge, type TransitionResult, type Unsubscribe, type ValidationCategory, type ValidationIssue, type ValidationResult, type ValidationSeverity, type ValidatorOptions, WEB_FAILURE_POLICIES, analyzeDefinition, buildFunctionMap, checkCompatibility, clearExpressionCache, clearPatternCache, compareNRT, compile, compilePattern, compileTestProgram, compileTestScenario, countByKind, countNodes, createActionRecorder, createApiTestActions, createEmptyNRT, createEvaluator, createInProcessTestActions, detectIRVersion, extractRequirements, findInteractiveNodes, findNode, findVisibleNodes, generateCoverageScenarios, getFinalState, getTransitionPath, hasTransition, isViableDefinition, matchTopic, needsMigration, normalizeCategory, normalizeDefinition, runBlueprintScenario, runBlueprintTestProgram, runScenario, runTestProgram, validateDefinition };

package/dist/index.d.ts

@@ -360,6 +360,8 @@ declare class ActionDispatcher {
     execute(actions: ActionDefinition[], context: ExpressionContext, evaluator?: Evaluator): Promise<ActionResult[]>;
     /** Get count of registered handlers */
     get size(): number;
+    /** Get all registered action type names */
+    getRegisteredTypes(): string[];
     /** Remove all handlers */
     clear(): void;
 }
@@ -1039,6 +1041,8 @@ interface IRActionDefinition {
     mode: IRActionMode;
     config: Record<string, unknown>;
     condition?: string;
+    /** Saga compensation: action to run if a subsequent action fails (Design 28). */
+    compensate?: IRActionDefinition;
 }
 interface IRDuringAction {
     id: string;
@@ -1072,6 +1076,8 @@ interface IRStateDefinition {
     during: IRDuringAction[];
     on_exit: IRActionDefinition[];
     on_event?: IROnEventSubscription[];
+    /** Where this state executes at runtime (server, client, worker, edge, any). */
+    runtime?: string;
 }
 interface IRConditionDefinition {
     type?: string;
@@ -1092,6 +1098,8 @@ interface IRTransitionDefinition {
     roles?: string[];
     auto?: boolean;
     required_fields?: string[];
+    /** Where this transition executes at runtime (server, client, worker, edge, any). */
+    runtime?: string;
 }
 interface IRFieldValidation {
     min?: number;
@@ -1378,6 +1386,84 @@ declare function validateDefinition(def: IRWorkflowDefinition, options?: Validat
  */
 declare function isViableDefinition(def: unknown): def is IRWorkflowDefinition;
 
+/**
+ * Player Capability Declaration & Compatibility Check (ISS-059)
+ *
+ * Each player runtime (web, iOS, console, TUI) declares its capabilities
+ * via a PlayerManifest. When loading a blueprint, the compatibility checker
+ * compares manifest against requirements to produce warnings/errors.
+ *
+ * This is informational, not blocking — players should still attempt to render.
+ */
+/** Declares what a player runtime can render and execute. */
+interface PlayerManifest {
+    /** Player identifier (e.g., "web", "ios", "console", "tui") */
+    player: string;
+    /** Player version */
+    version: string;
+    /** Supported atom component IDs */
+    atoms: string[];
+    /** Supported action types */
+    actions: string[];
+    /** Whether the player can evaluate expressions natively */
+    expressions: boolean;
+    /** Whether the player works offline */
+    offline: boolean;
+}
+/** What a blueprint requires from a player to render correctly. */
+interface BlueprintRequirements {
+    /** Atom component IDs used in the experience tree */
+    atoms: string[];
+    /** Action types referenced in transitions/states */
+    actions: string[];
+    /** Whether the blueprint uses expressions */
+    expressions: boolean;
+}
+/** Result of comparing a PlayerManifest against BlueprintRequirements. */
+interface CompatibilityResult {
+    /** Whether the player can render the blueprint without missing critical features */
+    compatible: boolean;
+    /** Atom component IDs the blueprint uses but the player doesn't support */
+    missingAtoms: string[];
+    /** Action types the blueprint references but the player can't handle */
+    missingActions: string[];
+    /** Human-readable warnings (non-blocking issues) */
+    warnings: string[];
+}
+/**
+ * Compare a player's capabilities against a blueprint's requirements.
+ *
+ * Missing atoms produce warnings (graceful degradation — render fallback).
+ * Missing actions produce errors (may cause runtime failures).
+ * The check is informational — players should still attempt to load.
+ */
+declare function checkCompatibility(manifest: PlayerManifest, requirements: BlueprintRequirements): CompatibilityResult;
+/**
+ * Walk a JSON experience tree and transition/state actions to extract
+ * all atom component IDs and action types referenced.
+ *
+ * This mirrors the Rust `WorkflowDefinition::extract_requirements()`.
+ */
+declare function extractRequirements(definition: {
+    experience?: unknown;
+    states?: Array<{
+        on_enter?: Array<{
+            action_type?: string;
+            type?: string;
+        }>;
+        on_exit?: Array<{
+            action_type?: string;
+            type?: string;
+        }>;
+    }>;
+    transitions?: Array<{
+        actions?: Array<{
+            action_type?: string;
+            type?: string;
+        }>;
+    }>;
+}): BlueprintRequirements;
+
 /**
  * DSL Compiler — entry point.
  *
@@ -1433,4 +1519,4 @@ declare function normalizeDefinition(def: Record<string, unknown>): MigrationRes
  */
 declare function needsMigration(def: Record<string, unknown>): boolean;
 
-export { type ActionDefinition, ActionDispatcher, type ActionHandler, type ActionHandlerFn, type ActionRecorder, type ActionResult, type ActionTick, type ActionTrace, type AnalysisResult, type AnalysisSummary, type ApiInstanceSnapshot, type ApiTestAdapter, type ApiTestRunnerConfig, type ApiTransitionResult, type AssertionResult, type BlueprintRunnerConfig, type BusEvent, CORE_FUNCTIONS, CURRENT_IR_VERSION, type CompilationResult, type CompiledOutput, type CompilerError, type CompilerErrorCode, type Evaluator, type EvaluatorConfig, EventBus, type EventHandler, type EventSubscription, type ExpressionContext, type ExpressionDiagnostics, type ExpressionFunction, type ExpressionResult, type FailurePolicy, type FailurePolicyContext, type GraphPath, type IRActionDefinition, type IRActionMode, type IRApiDataSource, type IRBlueprintManifest, type IRConditionDefinition, type IRDataSource, type IRDuringAction, type IRExperienceDefinition, type IRExperienceNode, type IRFieldDefinition, type IRFieldValidation, type IRGrammarIsland, type IROnEventAction, type IROnEventSubscription, type IRRefDataSource, type IRRoleDefinition, type IRStateDefinition, type IRStateHome, type IRStateType, type IRStaticDataSource, type IRTransitionDefinition, type IRWorkflowDataSource, type IRWorkflowDefinition, type IRWorkflowFieldType, type MigrationResult, type NRT, type NRTChange, type NRTDiff, type NRTEvent, type NRTEventTarget, type NRTNavState, type NRTNode, type PlayerAction, type PlayerInstance, type PlayerOnEventSubscription, type PlayerStateDefinition, type PlayerTransitionDefinition, type PlayerWorkflowDefinition, type PureFormWorkflow, type RuntimeProfile, type ScenarioResult, StateMachine, type StateMachineConfig, type StateMachineEvent, type StateMachineListener, type StateNode, type StateType, type StepResult, type TestActionState, type TestAssertion, type TestInstance, type TestProgram, type TestProgramResult, type TestRunnerConfig, type TestScenario, type TestStep, type TransitionEdge, type TransitionResult, type Unsubscribe, type ValidationCategory, type ValidationIssue, type ValidationResult, type ValidationSeverity, type ValidatorOptions, WEB_FAILURE_POLICIES, analyzeDefinition, buildFunctionMap, clearExpressionCache, clearPatternCache, compareNRT, compile, compilePattern, compileTestProgram, compileTestScenario, countByKind, countNodes, createActionRecorder, createApiTestActions, createEmptyNRT, createEvaluator, createInProcessTestActions, detectIRVersion, findInteractiveNodes, findNode, findVisibleNodes, generateCoverageScenarios, getFinalState, getTransitionPath, hasTransition, isViableDefinition, matchTopic, needsMigration, normalizeCategory, normalizeDefinition, runBlueprintScenario, runBlueprintTestProgram, runScenario, runTestProgram, validateDefinition };
+export { type ActionDefinition, ActionDispatcher, type ActionHandler, type ActionHandlerFn, type ActionRecorder, type ActionResult, type ActionTick, type ActionTrace, type AnalysisResult, type AnalysisSummary, type ApiInstanceSnapshot, type ApiTestAdapter, type ApiTestRunnerConfig, type ApiTransitionResult, type AssertionResult, type BlueprintRequirements, type BlueprintRunnerConfig, type BusEvent, CORE_FUNCTIONS, CURRENT_IR_VERSION, type CompatibilityResult, type CompilationResult, type CompiledOutput, type CompilerError, type CompilerErrorCode, type Evaluator, type EvaluatorConfig, EventBus, type EventHandler, type EventSubscription, type ExpressionContext, type ExpressionDiagnostics, type ExpressionFunction, type ExpressionResult, type FailurePolicy, type FailurePolicyContext, type GraphPath, type IRActionDefinition, type IRActionMode, type IRApiDataSource, type IRBlueprintManifest, type IRConditionDefinition, type IRDataSource, type IRDuringAction, type IRExperienceDefinition, type IRExperienceNode, type IRFieldDefinition, type IRFieldValidation, type IRGrammarIsland, type IROnEventAction, type IROnEventSubscription, type IRRefDataSource, type IRRoleDefinition, type IRStateDefinition, type IRStateHome, type IRStateType, type IRStaticDataSource, type IRTransitionDefinition, type IRWorkflowDataSource, type IRWorkflowDefinition, type IRWorkflowFieldType, type MigrationResult, type NRT, type NRTChange, type NRTDiff, type NRTEvent, type NRTEventTarget, type NRTNavState, type NRTNode, type PlayerAction, type PlayerInstance, type PlayerManifest, type PlayerOnEventSubscription, type PlayerStateDefinition, type PlayerTransitionDefinition, type PlayerWorkflowDefinition, type PureFormWorkflow, type RuntimeProfile, type ScenarioResult, StateMachine, type StateMachineConfig, type StateMachineEvent, type StateMachineListener, type StateNode, type StateType, type StepResult, type TestActionState, type TestAssertion, type TestInstance, type TestProgram, type TestProgramResult, type TestRunnerConfig, type TestScenario, type TestStep, type TransitionEdge, type TransitionResult, type Unsubscribe, type ValidationCategory, type ValidationIssue, type ValidationResult, type ValidationSeverity, type ValidatorOptions, WEB_FAILURE_POLICIES, analyzeDefinition, buildFunctionMap, checkCompatibility, clearExpressionCache, clearPatternCache, compareNRT, compile, compilePattern, compileTestProgram, compileTestScenario, countByKind, countNodes, createActionRecorder, createApiTestActions, createEmptyNRT, createEvaluator, createInProcessTestActions, detectIRVersion, extractRequirements, findInteractiveNodes, findNode, findVisibleNodes, generateCoverageScenarios, getFinalState, getTransitionPath, hasTransition, isViableDefinition, matchTopic, needsMigration, normalizeCategory, normalizeDefinition, runBlueprintScenario, runBlueprintTestProgram, runScenario, runTestProgram, validateDefinition };

package/dist/index.js

@@ -28,6 +28,7 @@ __export(index_exports, {
   WEB_FAILURE_POLICIES: () => WEB_FAILURE_POLICIES,
   analyzeDefinition: () => analyzeDefinition,
   buildFunctionMap: () => buildFunctionMap,
+  checkCompatibility: () => checkCompatibility,
   clearExpressionCache: () => clearExpressionCache,
   clearPatternCache: () => clearPatternCache,
   compareNRT: () => compareNRT,
@@ -43,6 +44,7 @@ __export(index_exports, {
   createEvaluator: () => createEvaluator,
   createInProcessTestActions: () => createInProcessTestActions,
   detectIRVersion: () => detectIRVersion,
+  extractRequirements: () => extractRequirements,
   findInteractiveNodes: () => findInteractiveNodes,
   findNode: () => findNode,
   findVisibleNodes: () => findVisibleNodes,
@@ -1137,8 +1139,8 @@ var ActionDispatcher = class {
       }
       const handler = this.handlers.get(action.type);
       if (!handler) {
-        console.warn(`[player-core] No handler registered for action type "${action.type}"`);
-        results.push({ type: action.type, success: false, error: `No handler for "${action.type}"` });
+        console.warn(`[player-core] No handler registered for action type "${action.type}" \u2014 unsupported action`);
+        results.push({ type: action.type, success: false, error: `unsupported action: "${action.type}"` });
         continue;
       }
       try {
@@ -1156,6 +1158,10 @@ var ActionDispatcher = class {
   get size() {
     return this.handlers.size;
   }
+  /** Get all registered action type names */
+  getRegisteredTypes() {
+    return Array.from(this.handlers.keys());
+  }
   /** Remove all handlers */
   clear() {
     this.handlers.clear();
@@ -3155,6 +3161,77 @@ function isViableDefinition(def) {
   return typeof d.slug === "string" && Array.isArray(d.states) && d.states.length > 0 && Array.isArray(d.transitions) && Array.isArray(d.fields);
 }
 
+// src/capabilities.ts
+function checkCompatibility(manifest, requirements) {
+  const manifestAtomSet = new Set(manifest.atoms);
+  const manifestActionSet = new Set(manifest.actions);
+  const missingAtoms = requirements.atoms.filter((a) => !manifestAtomSet.has(a));
+  const missingActions = requirements.actions.filter((a) => !manifestActionSet.has(a));
+  const warnings = [];
+  if (missingAtoms.length > 0) {
+    warnings.push(
+      `Player "${manifest.player}" is missing ${missingAtoms.length} atom(s): ${missingAtoms.join(", ")}. These components will render as fallbacks.`
+    );
+  }
+  if (missingActions.length > 0) {
+    warnings.push(
+      `Player "${manifest.player}" is missing ${missingActions.length} action type(s): ${missingActions.join(", ")}. These actions will fail at runtime.`
+    );
+  }
+  if (requirements.expressions && !manifest.expressions) {
+    warnings.push(
+      `Blueprint uses expressions but player "${manifest.player}" has no expression engine. Bindings and conditions will not evaluate.`
+    );
+  }
+  const compatible = missingActions.length === 0 && !(requirements.expressions && !manifest.expressions);
+  return { compatible, missingAtoms, missingActions, warnings };
+}
+function extractRequirements(definition) {
+  const atoms = /* @__PURE__ */ new Set();
+  const actions = /* @__PURE__ */ new Set();
+  let expressions = false;
+  if (definition.experience) {
+    walkTree(definition.experience, atoms, (v) => {
+      expressions = expressions || v;
+    });
+  }
+  for (const t of definition.transitions ?? []) {
+    for (const a of t.actions ?? []) {
+      const type = a.action_type ?? a.type;
+      if (type) actions.add(type);
+    }
+  }
+  for (const s of definition.states ?? []) {
+    for (const a of s.on_enter ?? []) {
+      const type = a.action_type ?? a.type;
+      if (type) actions.add(type);
+    }
+    for (const a of s.on_exit ?? []) {
+      const type = a.action_type ?? a.type;
+      if (type) actions.add(type);
+    }
+  }
+  return {
+    atoms: Array.from(atoms).sort(),
+    actions: Array.from(actions).sort(),
+    expressions
+  };
+}
+function walkTree(node, atoms, setExpressions) {
+  if (Array.isArray(node)) {
+    for (const item of node) walkTree(item, atoms, setExpressions);
+    return;
+  }
+  if (node && typeof node === "object") {
+    const obj = node;
+    if (typeof obj.component === "string") atoms.add(obj.component);
+    if (obj.bindings || obj.condition || obj.when) setExpressions(true);
+    if (obj.children) walkTree(obj.children, atoms, setExpressions);
+    if (obj.routes) walkTree(obj.routes, atoms, setExpressions);
+    if (obj.view) walkTree(obj.view, atoms, setExpressions);
+  }
+}
+
 // src/dsl/lexer.ts
 var SECTION_KEYWORDS = /* @__PURE__ */ new Set([
   "things",
@@ -4793,6 +4870,7 @@ function needsMigration(def) {
   WEB_FAILURE_POLICIES,
   analyzeDefinition,
   buildFunctionMap,
+  checkCompatibility,
   clearExpressionCache,
   clearPatternCache,
   compareNRT,
@@ -4808,6 +4886,7 @@ function needsMigration(def) {
   createEvaluator,
   createInProcessTestActions,
   detectIRVersion,
+  extractRequirements,
   findInteractiveNodes,
   findNode,
   findVisibleNodes,

package/dist/index.mjs

@@ -1072,8 +1072,8 @@ var ActionDispatcher = class {
       }
       const handler = this.handlers.get(action.type);
       if (!handler) {
-        console.warn(`[player-core] No handler registered for action type "${action.type}"`);
-        results.push({ type: action.type, success: false, error: `No handler for "${action.type}"` });
+        console.warn(`[player-core] No handler registered for action type "${action.type}" \u2014 unsupported action`);
+        results.push({ type: action.type, success: false, error: `unsupported action: "${action.type}"` });
         continue;
       }
       try {
@@ -1091,6 +1091,10 @@ var ActionDispatcher = class {
   get size() {
     return this.handlers.size;
   }
+  /** Get all registered action type names */
+  getRegisteredTypes() {
+    return Array.from(this.handlers.keys());
+  }
   /** Remove all handlers */
   clear() {
     this.handlers.clear();
@@ -3090,6 +3094,77 @@ function isViableDefinition(def) {
   return typeof d.slug === "string" && Array.isArray(d.states) && d.states.length > 0 && Array.isArray(d.transitions) && Array.isArray(d.fields);
 }
 
+// src/capabilities.ts
+function checkCompatibility(manifest, requirements) {
+  const manifestAtomSet = new Set(manifest.atoms);
+  const manifestActionSet = new Set(manifest.actions);
+  const missingAtoms = requirements.atoms.filter((a) => !manifestAtomSet.has(a));
+  const missingActions = requirements.actions.filter((a) => !manifestActionSet.has(a));
+  const warnings = [];
+  if (missingAtoms.length > 0) {
+    warnings.push(
+      `Player "${manifest.player}" is missing ${missingAtoms.length} atom(s): ${missingAtoms.join(", ")}. These components will render as fallbacks.`
+    );
+  }
+  if (missingActions.length > 0) {
+    warnings.push(
+      `Player "${manifest.player}" is missing ${missingActions.length} action type(s): ${missingActions.join(", ")}. These actions will fail at runtime.`
+    );
+  }
+  if (requirements.expressions && !manifest.expressions) {
+    warnings.push(
+      `Blueprint uses expressions but player "${manifest.player}" has no expression engine. Bindings and conditions will not evaluate.`
+    );
+  }
+  const compatible = missingActions.length === 0 && !(requirements.expressions && !manifest.expressions);
+  return { compatible, missingAtoms, missingActions, warnings };
+}
+function extractRequirements(definition) {
+  const atoms = /* @__PURE__ */ new Set();
+  const actions = /* @__PURE__ */ new Set();
+  let expressions = false;
+  if (definition.experience) {
+    walkTree(definition.experience, atoms, (v) => {
+      expressions = expressions || v;
+    });
+  }
+  for (const t of definition.transitions ?? []) {
+    for (const a of t.actions ?? []) {
+      const type = a.action_type ?? a.type;
+      if (type) actions.add(type);
+    }
+  }
+  for (const s of definition.states ?? []) {
+    for (const a of s.on_enter ?? []) {
+      const type = a.action_type ?? a.type;
+      if (type) actions.add(type);
+    }
+    for (const a of s.on_exit ?? []) {
+      const type = a.action_type ?? a.type;
+      if (type) actions.add(type);
+    }
+  }
+  return {
+    atoms: Array.from(atoms).sort(),
+    actions: Array.from(actions).sort(),
+    expressions
+  };
+}
+function walkTree(node, atoms, setExpressions) {
+  if (Array.isArray(node)) {
+    for (const item of node) walkTree(item, atoms, setExpressions);
+    return;
+  }
+  if (node && typeof node === "object") {
+    const obj = node;
+    if (typeof obj.component === "string") atoms.add(obj.component);
+    if (obj.bindings || obj.condition || obj.when) setExpressions(true);
+    if (obj.children) walkTree(obj.children, atoms, setExpressions);
+    if (obj.routes) walkTree(obj.routes, atoms, setExpressions);
+    if (obj.view) walkTree(obj.view, atoms, setExpressions);
+  }
+}
+
 // src/dsl/lexer.ts
 var SECTION_KEYWORDS = /* @__PURE__ */ new Set([
   "things",
@@ -4727,6 +4802,7 @@ export {
   WEB_FAILURE_POLICIES,
   analyzeDefinition,
   buildFunctionMap,
+  checkCompatibility,
   clearExpressionCache,
   clearPatternCache,
   compareNRT,
@@ -4742,6 +4818,7 @@ export {
   createEvaluator,
   createInProcessTestActions,
   detectIRVersion,
+  extractRequirements,
   findInteractiveNodes,
   findNode,
   findVisibleNodes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmapp/player-core",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.10",
   "description": "Framework-agnostic workflow engine for browser-side state machines, expression evaluation, and event-driven reactions",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -18,7 +18,8 @@
     "test": "vitest run",
     "test:watch": "vitest --watch",
     "test:coverage": "vitest --coverage",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "publish:alpha": "cd ../.. && ./scripts/publish-npm.sh"
   },
   "keywords": [
     "workflow",

package/package.json.backup

@@ -1,35 +0,0 @@
-{
-  "name": "@mmapp/player-core",
-  "version": "0.1.0-alpha.1",
-  "description": "Framework-agnostic workflow engine for browser-side state machines, expression evaluation, and event-driven reactions",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "test": "vitest run",
-    "test:watch": "vitest --watch",
-    "test:coverage": "vitest --coverage",
-    "type-check": "tsc --noEmit"
-  },
-  "keywords": [
-    "workflow",
-    "state-machine",
-    "expression-engine",
-    "player",
-    "reactive"
-  ],
-  "author": "MindMatrix Team",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  }
-}