@vived/app 6.0.0 → 6.2.0

package/src/StateMachine/README.md

@@ -0,0 +1,430 @@
+# StateMachine Feature
+
+The StateMachine feature provides centralized state management for VIVED applications, enabling systems to save, restore, and transition between different application states with versioned serialization support.
+
+## Purpose
+
+This feature coordinates state management across multiple independent systems within a VIVED application. It allows:
+
+- Capturing snapshots of application state
+- Restoring previously saved states
+- Smooth transitions between states with configurable easing
+- Versioned serialization for backwards compatibility
+- Default state management for missing or corrupted states
+
+## Architecture
+
+The StateMachine feature follows Clean Architecture with these components:
+
+### Entities
+
+- **StateMachineEntity**: Core entity managing state coordination across all registered systems
+- **SerializedSystem**: Interface that systems must implement to participate in state management
+- **SerializedStates**: Data structure representing versioned collection of system states
+- **SystemState**: Individual system's serialized state with version information
+
+### Controllers
+
+- **clickRestorePreviousState**: Restores the most recently saved state (replaces deprecated `clickRestoreScene`)
+
+### Factories
+
+- **StateMachineFeatureFactory**: Domain factory for initializing the StateMachine feature with proper DDD pattern
+- **setupStateMachine**: Legacy setup function (maintained for backwards compatibility)
+
+### Mocks
+
+- **MockStateMachine**: Mock implementation for testing components that depend on StateMachine
+
+## Getting Started
+
+### Basic Setup
+
+Use the factory to initialize the StateMachine feature:
+
+```typescript
+import { makeStateMachineFeatureFactory } from "@vived/app";
+import { AppObjectRepo } from "@vived/core";
+
+function setupApp(appObjects: AppObjectRepo) {
+  const stateMachineFactory = makeStateMachineFeatureFactory(appObjects);
+  stateMachineFactory.runSetup();
+}
+```
+
+### Implementing a Serialized System
+
+Any system that needs to participate in state management must implement the `SerializedSystem` interface:
+
+```typescript
+import { SerializedSystem } from "@vived/app";
+
+class MyCustomSystem implements SerializedSystem {
+  name = "MyCustomSystem";
+  serializationVersion = 1;
+
+  getSystemState(): object | undefined {
+    // Return the current state as a serializable object
+    return {
+      position: this.currentPosition,
+      scale: this.currentScale,
+      isVisible: this.isVisible,
+    };
+  }
+
+  applySystemState(
+    state: object,
+    version: number,
+    transitionDuration: number,
+  ): void {
+    // Apply the provided state to your system
+    const myState = state as MySystemState;
+    this.animateToPosition(myState.position, transitionDuration);
+    this.animateToScale(myState.scale, transitionDuration);
+    this.setVisibility(myState.isVisible);
+  }
+
+  applyDefaultState(transitionDuration: number): void {
+    // Reset to default state
+    this.animateToPosition({ x: 0, y: 0, z: 0 }, transitionDuration);
+    this.animateToScale(1, transitionDuration);
+    this.setVisibility(true);
+  }
+
+  constructor() {
+    // Register this system with the StateMachine
+    const stateMachine = StateMachineEntity.get(appObjects);
+    if (stateMachine) {
+      stateMachine.registerSerializedSystem(mySystem);
+    }
+  }
+}
+```
+
+## Usage Patterns
+
+### Capturing Current State
+
+```typescript
+import { StateMachineEntity } from "@vived/app";
+
+const stateMachine = StateMachineEntity.get(appObjects);
+if (stateMachine) {
+  const currentState = stateMachine.getSerializedStates();
+  // Store this state for later use
+  localStorage.setItem("savedState", JSON.stringify(currentState));
+}
+```
+
+### Restoring a Saved State
+
+```typescript
+import { StateMachineEntity } from "@vived/app";
+
+const stateMachine = StateMachineEntity.get(appObjects);
+if (stateMachine) {
+  const savedStateJson = localStorage.getItem("savedState");
+  const transitionDuration = 1.5; // seconds
+
+  if (savedStateJson) {
+    const savedState = JSON.parse(savedStateJson);
+    stateMachine.setSerializedStates(savedState, transitionDuration);
+  }
+}
+```
+
+### Restoring Previous State (User Action)
+
+Use the controller to restore the most recently applied state:
+
+```typescript
+import { clickRestorePreviousState } from "@vived/app";
+
+// In response to a button click or other user action
+function onRestoreButtonClick() {
+  clickRestorePreviousState(appObjects);
+}
+```
+
+### Applying State from String
+
+For loading states from external sources:
+
+```typescript
+const stateMachine = StateMachineEntity.get(appObjects);
+if (stateMachine) {
+  // Safe parsing with fallback to default state
+  stateMachine.applySerializedStatesString(stateJsonString, 1.0);
+}
+```
+
+### Resetting to Default State
+
+```typescript
+const stateMachine = StateMachineEntity.get(appObjects);
+if (stateMachine) {
+  const transitionDuration = 1.0; // seconds
+  stateMachine.setDefaultState(transitionDuration);
+}
+```
+
+## State Serialization Format
+
+### Version 2 Format (Current)
+
+```typescript
+{
+	version: 2,
+	systems: [
+		{
+			name: "SystemName",
+			serializationVersion: 1,
+			state: {
+				// System-specific state data
+			}
+		}
+	]
+}
+```
+
+**Important Notes:**
+
+- Each system manages its own `state` object format
+- The `serializationVersion` at the system level allows individual systems to evolve independently
+- The top-level `version` indicates the overall StateMachine serialization format
+- Empty string or invalid JSON automatically falls back to default state
+
+## Configuration
+
+### Transition Easing
+
+The StateMachine uses a cubic in-out easing function by default. You can customize this:
+
+```typescript
+import { StateMachineEntity } from "@vived/app";
+
+const stateMachine = StateMachineEntity.get(appObjects);
+if (stateMachine) {
+  // Custom easing function (0-1 normalized input/output)
+  stateMachine.transitionEaseFunction = (t: number) => {
+    // Example: Quadratic ease-in-out
+    return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+  };
+}
+```
+
+### Restore Duration
+
+Configure how long the restore transition takes:
+
+```typescript
+const stateMachine = StateMachineEntity.get(appObjects);
+if (stateMachine) {
+  stateMachine.restoreDurationS = 2.0; // 2 second transition
+}
+```
+
+## State Lifecycle
+
+1. **Registration**: Systems register with StateMachine during initialization
+2. **State Capture**: `getSerializedStates()` queries all registered systems for current state
+3. **State Application**: When applying a state:
+   - Systems not in the saved state receive `applyDefaultState()`
+   - Systems in the saved state receive `applySystemState()` in registration order
+   - The StateMachine notifies observers after all states are applied
+4. **Last State Tracking**: StateMachine automatically tracks the most recently applied state for quick restore
+
+## Observing State Changes
+
+The StateMachine entity extends `AppObjectEntity` and supports change observers:
+
+```typescript
+const stateMachine = StateMachineEntity.get(appObjects);
+if (stateMachine) {
+  stateMachine.addChangeObserver(() => {
+    console.log("State has been applied");
+    // Update UI or trigger other side effects
+  });
+}
+```
+
+## Error Handling
+
+The StateMachine handles errors gracefully:
+
+- **Invalid JSON**: Falls back to default state and logs warning
+- **Unknown system in saved state**: Logs warning, continues with other systems
+- **Unsupported version**: Logs warning, does not apply state
+- **Duplicate system registration**: Logs warning, ignores duplicate
+- **Missing StateMachine entity**: Controllers log error to AppObjectRepo
+
+## Best Practices
+
+### System Implementation
+
+1. **Keep state serializable**: Use plain objects, avoid circular references
+2. **Handle missing properties**: Provide sensible defaults for new properties added in later versions
+3. **Smooth transitions**: Respect the `transitionDuration` parameter in `applySystemState` and `applyDefaultState`
+4. **Version bumps**: Increment `serializationVersion` when making breaking changes to state format
+5. **Backwards compatibility**: Handle old state versions in `applySystemState` when possible
+
+### State Management
+
+1. **Meaningful names**: Use descriptive, unique system names
+2. **Minimal state**: Only serialize what's necessary to restore the system
+3. **Default states**: Ensure `applyDefaultState()` provides a good initial experience
+4. **State validation**: Validate state objects before applying to avoid runtime errors
+
+### Integration
+
+1. **Early registration**: Register systems during feature initialization
+2. **Single StateMachine**: Use the singleton pattern (one StateMachine per app)
+3. **Avoid circular dependencies**: Don't have systems depend on each other's state
+4. **Test thoroughly**: Use MockStateMachine for unit testing dependent components
+
+## Testing
+
+### Using MockStateMachine
+
+```typescript
+import { makeMockStateMachine } from "@vived/app";
+import { makeAppObjectRepo } from "@vived/core";
+
+describe("My Feature", () => {
+  it("Restores state when button clicked", () => {
+    const appObjects = makeAppObjectRepo();
+    const mockStateMachine = makeMockStateMachine(appObjects);
+
+    mockStateMachine.restoreLastState = jest.fn();
+
+    // Test your code that interacts with StateMachine
+    myFeature.onRestoreClick(appObjects);
+
+    expect(mockStateMachine.restoreLastState).toHaveBeenCalled();
+  });
+});
+```
+
+### Testing SerializedSystem Implementation
+
+```typescript
+describe("MySystem Serialization", () => {
+  it("Serializes current state", () => {
+    const system = new MyCustomSystem();
+    system.setValue(42);
+
+    const state = system.getSystemState();
+
+    expect(state).toEqual({ value: 42 });
+  });
+
+  it("Applies serialized state", () => {
+    const system = new MyCustomSystem();
+    const state = { value: 100 };
+
+    system.applySystemState(state, 1, 0);
+
+    expect(system.getValue()).toBe(100);
+  });
+
+  it("Applies default state", () => {
+    const system = new MyCustomSystem();
+    system.setValue(42);
+
+    system.applyDefaultState(0);
+
+    expect(system.getValue()).toBe(0); // assuming 0 is default
+  });
+});
+```
+
+## Migration Guide
+
+### From Legacy Setup
+
+If using the old `setupStateMachine` function, migrate to the factory pattern:
+
+**Before:**
+
+```typescript
+import { setupStateMachine } from "@vived/app";
+
+setupStateMachine(appObjects);
+```
+
+**After:**
+
+```typescript
+import { makeStateMachineFeatureFactory } from "@vived/app";
+
+const factory = makeStateMachineFeatureFactory(appObjects);
+factory.runSetup();
+```
+
+### From clickRestoreScene
+
+The `clickRestoreScene` function is deprecated:
+
+**Before:**
+
+```typescript
+import { clickRestoreScene } from "@vived/app";
+clickRestoreScene(appObjects);
+```
+
+**After:**
+
+```typescript
+import { clickRestorePreviousState } from "@vived/app";
+clickRestorePreviousState(appObjects);
+```
+
+## Common Pitfalls
+
+1. **Forgetting to register**: Systems must be registered before state operations work
+2. **Mutating state objects**: Return new objects from `getSystemState()`, don't expose internal state
+3. **Not handling undefined**: `getSystemState()` can return undefined to skip serialization
+4. **Circular references**: Ensure state objects are JSON-serializable
+
+## API Reference
+
+### StateMachineEntity
+
+#### Properties
+
+- `restoreDurationS: number` - Duration for restoring last state (default: 1)
+- `transitionEaseFunction: (t: number) => number` - Easing function for transitions (default: cubicInOut)
+
+#### Methods
+
+- `getSerializedStates(): SerializedStates` - Capture current state of all systems
+- `setSerializedStates(state: SerializedStates, transitionTime: number): void` - Apply saved state
+- `applySerializedStatesString(state: string, duration?: number): void` - Apply state from JSON string
+- `restoreLastState(): void` - Restore most recently applied state
+- `setDefaultState(transitionTime: number): void` - Reset all systems to default
+- `registerSerializedSystem(system: SerializedSystem): void` - Register a system for state management
+- `static get(appObjects: AppObjectRepo): StateMachineEntity | undefined` - Get singleton instance
+
+### SerializedSystem Interface
+
+#### Properties
+
+- `name: string` - Unique identifier for this system
+- `serializationVersion: number` - Version of this system's state format
+
+#### Methods
+
+- `getSystemState(): object | undefined` - Returns current state or undefined to skip
+- `applySystemState(state: object, version: number, transitionDuration: number): void` - Apply saved state
+- `applyDefaultState(transitionDuration: number): void` - Reset to default state
+
+### Controllers
+
+- `clickRestorePreviousState(appObjects: AppObjectRepo): void` - Restore last applied state
+
+## Examples
+
+See the test files for comprehensive examples:
+
+- [StateMachineEntity.test.ts](Entities/StateMachineEntity.test.ts) - Entity behavior and state management
+- [clickRestorePreviousState.test.ts](Controller/clickRestorePreviousState.test.ts) - Controller usage patterns