@vived/app 5.3.0 → 6.1.0

package/src/RequestHandler/README.md

@@ -0,0 +1,790 @@
+# RequestHandler Feature
+
+The RequestHandler feature provides a centralized request-response mechanism for handling app-level operations in VIVED applications. It implements a versioned request protocol that allows external systems to interact with the application through well-defined request types and payloads.
+
+## Overview
+
+This feature acts as a command dispatcher that routes incoming requests to appropriate handlers (Use Cases) based on the request type. It supports payload versioning to maintain backward compatibility as the API evolves, and provides introspection capabilities to query supported request types and their versions.
+
+## Architecture
+
+The RequestHandler feature follows Clean Architecture and Domain-Driven Design principles:
+
+- **Entity**: `AppHandlerEntity` - Manages request handler registration and routing
+- **Use Cases**: 10 specialized use cases handle different app-level operations
+- **Factory**: `RequestHandlerFeatureFactory` - Sets up all feature components
+- **Legacy Setup**: `setupAppHandlers()` - Function-based setup for backward compatibility
+
+## Configuration
+
+The `RequestHandlerFeatureFactory` accepts an optional configuration object to control feature support and logging behavior. This allows you to disable features that your application doesn't need, reducing memory overhead and initialization time.
+
+### Configuration Options
+
+Pass a configuration object when creating the factory:
+
+```typescript
+import {
+  makeRequestHandlerFeatureFactory,
+  IRequestHandlerConfig,
+} from "@vived/app";
+
+const config: IRequestHandlerConfig = {
+  verbose: true, // Enable verbose logging
+  zSpaceSupported: false, // Disable zSpace-related handlers
+  themeSupported: true, // Enable theme color handlers (default)
+  babylonSupported: false, // Disable Babylon inspector handler
+};
+
+const factory = makeRequestHandlerFeatureFactory(appObjects, config);
+```
+
+### Available Configuration Options
+
+| Property           | Type      | Default | Controls                   | Related Use Cases         |
+| ------------------ | --------- | ------- | -------------------------- | ------------------------- |
+| `verbose`          | `boolean` | `false` | Request logging to console | All requests              |
+| `zSpaceSupported`  | `boolean` | `true`  | zSpace XR functionality    | START_ZSPACE, STOP_ZSPACE |
+| `themeSupported`   | `boolean` | `true`  | Theme color management     | SET_THEME_COLORS          |
+| `babylonSupported` | `boolean` | `true`  | Babylon.js inspector       | SHOW_BABYLON_INSPECTOR    |
+
+### Verbose Logging
+
+When `verbose` is enabled, all incoming requests are logged to the console:
+
+```typescript
+const factory = makeRequestHandlerFeatureFactory(appObjects, { verbose: true });
+
+// Now all requests will be logged
+const request: Request = {
+  type: "START_APP",
+  version: 2,
+  payload: { container: document.getElementById("app") },
+};
+appHandler.handler(request);
+// Console output: [AppHandler] Request received: { type: "START_APP", version: 2, payload: {...} }
+```
+
+**When to Enable**:
+
+- Debugging request flow issues
+- Monitoring which requests are being sent
+- Troubleshooting version mismatches
+- Development and testing environments
+
+**Note**: Disable verbose logging in production to avoid console clutter.
+
+### Feature Support Flags
+
+Use configuration flags to disable optional features:
+
+```typescript
+// Minimal configuration - only required features
+const minimalConfig = {
+  zSpaceSupported: false,
+  themeSupported: false,
+  babylonSupported: false,
+};
+
+// Development configuration - all features with logging
+const devConfig = {
+  verbose: true,
+  zSpaceSupported: true,
+  themeSupported: true,
+  babylonSupported: true,
+};
+
+// Production configuration - no debugging features
+const prodConfig = {
+  verbose: false,
+  zSpaceSupported: true,
+  themeSupported: true,
+  babylonSupported: false,
+};
+```
+
+**When to Disable Features**:
+
+- Your application doesn't use zSpace devices → set `zSpaceSupported: false`
+- Your application has fixed styling → set `themeSupported: false`
+- You're not using Babylon.js or don't need debugging tools → set `babylonSupported: false`
+
+## Sending Requests
+
+Requests are sent using the standard VIVED core `Request` interface:
+
+```typescript
+import { Request } from "@vived/core";
+
+const request: Request = {
+  type: "REQUEST_TYPE",
+  version: 1,
+  payload: {
+    // Request-specific data
+  },
+};
+
+appHandler.handler(request);
+```
+
+## Supported Request Types
+
+### 1. START_APP
+
+Starts the application rendering in a specified HTML container.
+
+- **Request Type**: `START_APP`
+- **Current Version**: 2
+- **Payload**:
+  ```typescript
+  {
+    container: HTMLElement;
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "START_APP",
+    version: 2,
+    payload: {
+      container: document.getElementById("app-container"),
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### 2. STOP_APP
+
+Stops the application rendering.
+
+- **Request Type**: `STOP_APP`
+- **Current Version**: 1
+- **Payload**: None
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "STOP_APP",
+    version: 1,
+  };
+  appHandler.handler(request);
+  ```
+
+### 3. DISPOSE_APP
+
+Disposes of the application and cleans up resources.
+
+- **Request Type**: `DISPOSE_APP`
+- **Current Version**: 1
+- **Payload**: None
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "DISPOSE_APP",
+    version: 1,
+  };
+  appHandler.handler(request);
+  ```
+
+### 4. SET_APP_STATE
+
+Sets the application state, including slide navigation and state machine configuration.
+
+- **Request Type**: `SET_APP_STATE`
+- **Current Version**: 3
+- **Payload**:
+  ```typescript
+  {
+    finalState?: SerializedStates;  // State machine configuration
+    hasNextSlide: boolean;           // Whether there's a next slide
+    hasPreviousSlide: boolean;       // Whether there's a previous slide
+    hideNavigation: boolean;         // Whether to hide slide navigation
+    duration?: number;               // Transition duration in ms
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "SET_APP_STATE",
+    version: 3,
+    payload: {
+      hasNextSlide: true,
+      hasPreviousSlide: false,
+      hideNavigation: false,
+      duration: 500,
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### 5. SET_IS_AUTHORING
+
+Sets whether the application is in authoring mode.
+
+- **Request Type**: `SET_IS_AUTHORING`
+- **Current Version**: 1
+- **Payload**:
+  ```typescript
+  {
+    isAuthoring: boolean;
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "SET_IS_AUTHORING",
+    version: 1,
+    payload: {
+      isAuthoring: true,
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### 6. ENABLE_FEATURE
+
+Enables a feature flag in the application.
+
+- **Request Type**: `ENABLE_FEATURE`
+- **Current Version**: 1
+- **Payload**:
+  ```typescript
+  {
+    featureFlag: string;
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "ENABLE_FEATURE",
+    version: 1,
+    payload: {
+      featureFlag: "NEW_FEATURE_NAME",
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### 7. SET_THEME_COLORS
+
+Sets the theme colors for the application.
+
+- **Request Type**: `SET_THEME_COLORS`
+- **Current Version**: 1
+- **Payload**:
+  ```typescript
+  {
+    colors: {
+      [colorType: string]: string;  // Hex color values
+    }
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "SET_THEME_COLORS",
+    version: 1,
+    payload: {
+      colors: {
+        primary: "#FF5733",
+        secondary: "#33C3FF",
+      },
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### 8. SHOW_BABYLON_INSPECTOR
+
+Shows or hides the Babylon.js scene inspector for debugging.
+
+- **Request Type**: `SHOW_BABYLON_INSPECTOR`
+- **Current Version**: 1
+- **Payload**:
+  ```typescript
+  {
+    showBabylonInspector: boolean;
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "SHOW_BABYLON_INSPECTOR",
+    version: 1,
+    payload: {
+      showBabylonInspector: true,
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### 9. START_ZSPACE
+
+Starts zSpace XR functionality.
+
+- **Request Type**: `START_ZSPACE`
+- **Current Version**: 3
+- **Payload**:
+  ```typescript
+  {
+    session: XRSession | null;
+    emulate: boolean;
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "START_ZSPACE",
+    version: 3,
+    payload: {
+      session: xrSession,
+      emulate: false,
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### 10. STOP_ZSPACE
+
+Stops zSpace XR functionality.
+
+- **Request Type**: `STOP_ZSPACE`
+- **Current Version**: 1
+- **Payload**: None
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "STOP_ZSPACE",
+    version: 1,
+  };
+  appHandler.handler(request);
+  ```
+
+## Introspection Requests
+
+The RequestHandler provides two special introspection requests that allow external systems to discover supported request types and versions.
+
+### GET_APP_PAYLOAD_VERSION
+
+Retrieves the current payload version for all registered request handlers.
+
+- **Request Type**: `GET_APP_PAYLOAD_VERSION`
+- **Version**: 2
+- **Payload**:
+  ```typescript
+  {
+    callback: (versionMap: Map<string, number>) => void;
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "GET_APP_PAYLOAD_VERSION",
+    version: 2,
+    payload: {
+      callback: (versionMap: Map<string, number>) => {
+        console.log("Supported request types:", versionMap);
+        // Map will contain entries like:
+        // "START_APP" => 2
+        // "STOP_APP" => 1
+        // etc.
+      },
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+### GET_APP_HANDLER_VERSION
+
+Retrieves the current version of the AppHandler system itself.
+
+- **Request Type**: `GET_APP_HANDLER_VERSION`
+- **Version**: 1
+- **Payload**:
+  ```typescript
+  {
+    callback: (version: number) => void;
+  }
+  ```
+- **Example**:
+  ```typescript
+  const request: Request = {
+    type: "GET_APP_HANDLER_VERSION",
+    version: 1,
+    payload: {
+      callback: (version: number) => {
+        console.log("AppHandler version:", version);
+      },
+    },
+  };
+  appHandler.handler(request);
+  ```
+
+## Creating Custom Request Handlers
+
+You can extend the RequestHandler feature with custom request handlers by implementing the `RequestHandler` interface and registering it with the `AppHandlerEntity`.
+
+### Step 1: Implement RequestHandler Interface
+
+```typescript
+import { AppObject, AppObjectUC } from "@vived/core";
+import {
+  AppHandlerEntity,
+  RequestHandler,
+  UnsupportedRequestVersion,
+  UnableToParsePayload,
+} from "@vived/app";
+
+export abstract class MyCustomUC extends AppObjectUC implements RequestHandler {
+  static readonly type = "MyCustomUC";
+  readonly requestType = "MY_CUSTOM_REQUEST";
+  readonly payloadVersion = 1;
+
+  abstract action: (data: MyPayload) => void;
+  abstract handleRequest: (version: number, payload?: unknown) => void;
+}
+
+export function makeMyCustomUC(appObject: AppObject): MyCustomUC {
+  return new MyCustomUCImp(appObject);
+}
+
+class MyCustomUCImp extends MyCustomUC {
+  action = (data: MyPayload) => {
+    // Implement your custom logic here
+    console.log("Custom action executed:", data);
+  };
+
+  handleRequest = (version: number, payload: unknown) => {
+    if (version === this.payloadVersion) {
+      const data = this.castPayload(payload);
+      this.action(data);
+    } else {
+      throw new UnsupportedRequestVersion(this.requestType, version);
+    }
+  };
+
+  private castPayload(payload: unknown): MyPayload {
+    const castPayload = payload as MyPayload;
+    if (castPayload.myField === undefined) {
+      throw new UnableToParsePayload(
+        this.requestType,
+        this.payloadVersion,
+        JSON.stringify(payload),
+      );
+    }
+    return castPayload;
+  }
+
+  constructor(appObject: AppObject) {
+    super(appObject, MyCustomUC.type);
+
+    // Register this handler with AppHandlerEntity
+    const handler = appObject.getComponent<AppHandlerEntity>(
+      AppHandlerEntity.type,
+    );
+    if (!handler) {
+      this.warn(
+        "MyCustomUC requires AppHandlerEntity to be added to the app object first",
+      );
+      return;
+    }
+
+    handler.registerRequestHandler(this);
+  }
+}
+
+type MyPayload = {
+  myField: string;
+};
+```
+
+### Step 2: Register Your Custom Handler
+
+```typescript
+import { makeMyCustomUC } from "./MyCustomUC";
+
+// After setting up RequestHandler feature
+const handlerAO = appObjectRepo.getOrCreate("AppHandlers");
+makeMyCustomUC(handlerAO);
+```
+
+### Step 3: Use Your Custom Handler
+
+```typescript
+const request: Request = {
+  type: "MY_CUSTOM_REQUEST",
+  version: 1,
+  payload: {
+    myField: "custom data",
+  },
+};
+appHandler.handler(request);
+```
+
+## Overriding Default Use Case Behavior
+
+If you need to customize the behavior of an existing request handler without creating a completely new one, you can inject a custom `action` function. All Use Cases expose their `action` property, which can be overridden after instantiation.
+
+### Example: Customizing START_APP Behavior
+
+```typescript
+import { setupAppHandlers, StartAppBaseUC } from "@vived/app";
+import { makeAppObjectRepo } from "@vived/core";
+
+const appObjectRepo = makeAppObjectRepo();
+const appHandler = setupAppHandlers(appObjectRepo);
+
+// Get the existing StartAppUC
+const handlerAO = appObjectRepo.get("AppHandlers");
+const startAppUC = handlerAO?.getComponent<StartAppBaseUC>(StartAppBaseUC.type);
+
+if (startAppUC) {
+  // Override the default action with custom behavior
+  startAppUC.action = (container: HTMLElement) => {
+    console.log("Custom start logic before rendering");
+
+    // Add your custom initialization here
+    myCustomSetup();
+
+    // Call the original behavior if needed, or replace entirely
+    const appRenderingUC = AppRenderingUC.get(appObjectRepo);
+    appRenderingUC?.startRendering(container);
+
+    console.log("Custom start logic after rendering");
+  };
+}
+```
+
+### Example: Customizing DISPOSE_APP Behavior
+
+```typescript
+import { DisposeAppBaseUC } from "@vived/app";
+
+// Get the existing DisposeAppUC
+const disposeAppUC = handlerAO?.getComponent<DisposeAppBaseUC>(
+  DisposeAppBaseUC.type,
+);
+
+if (disposeAppUC) {
+  // Inject custom disposal logic
+  disposeAppUC.action = () => {
+    console.log("Performing custom cleanup");
+
+    // Your custom cleanup logic
+    cleanupCustomResources();
+    removeEventListeners();
+
+    console.log("Cleanup complete");
+  };
+}
+```
+
+### Example: Augmenting SET_APP_STATE Behavior
+
+```typescript
+import { SetAppStateBaseUC, SetAppStateAction } from "@vived/app";
+
+// Get the existing SetAppStateUC
+const setAppStateUC = handlerAO?.getComponent<SetAppStateBaseUC>(
+  SetAppStateBaseUC.type,
+);
+
+if (setAppStateUC) {
+  // Store the original action
+  const originalAction = setAppStateUC.action;
+
+  // Create augmented action that calls original and adds custom logic
+  setAppStateUC.action = (data) => {
+    console.log("Before state change:", data);
+
+    // Call original behavior
+    originalAction(data);
+
+    // Add custom logic after
+    notifyStateChangeListeners(data);
+    console.log("After state change complete");
+  };
+}
+```
+
+### When to Override vs Create New Handler
+
+**Override the action function when:**
+
+- You want to modify or extend existing request handler behavior
+- You need to add logging, metrics, or side effects
+- You want to wrap the default behavior with pre/post processing
+- You're working within the same application context
+
+**Create a new request handler when:**
+
+- You need a completely different request type
+- You require different payload structure or versioning
+- You're adding new functionality rather than modifying existing
+
+### Important Notes
+
+1. **Override After Setup**: Always override the action after the RequestHandler feature has been fully initialized
+2. **Type Safety**: Use the proper types (e.g., `SetAppStateAction`) when defining your custom action
+3. **Original Behavior**: Store a reference to the original action if you want to call it as part of your custom logic
+4. **Validation**: The `handleRequest` method still performs version checking and payload validation before calling your custom action
+
+## Error Handling
+
+The RequestHandler provides two main error types:
+
+### UnsupportedRequestVersion
+
+Thrown when a request is sent with an unsupported version number.
+
+```typescript
+try {
+  appHandler.handler(request);
+} catch (error) {
+  if (error instanceof UnsupportedRequestVersion) {
+    console.error("Version not supported:", error.message);
+  }
+}
+```
+
+### UnableToParsePayload
+
+Thrown when the payload cannot be parsed or is missing required fields.
+
+```typescript
+try {
+  appHandler.handler(request);
+} catch (error) {
+  if (error instanceof UnableToParsePayload) {
+    console.error("Invalid payload:", error.message);
+  }
+}
+```
+
+## Best Practices
+
+1. **Version Compatibility**: Always check supported versions using `GET_APP_PAYLOAD_VERSION` before sending requests to ensure compatibility.
+
+2. **Error Handling**: Wrap request handler calls in try-catch blocks to gracefully handle unsupported versions or invalid payloads.
+
+3. **Registration Order**: Ensure the `AppHandlerEntity` is created before registering any request handlers.
+
+4. **Single Responsibility**: Each request handler should handle one specific operation. Create separate handlers for different operations.
+
+5. **Payload Validation**: Always validate payloads thoroughly in the `castPayload` method to ensure type safety.
+
+6. **Versioning**: When updating request payloads, increment the version number and maintain backward compatibility where possible.
+
+7. **Action Injection**: To customize default behavior, inject a custom `action` function rather than creating an entirely new request handler. This maintains the existing request routing and validation logic.
+
+8. **Logging**: The system automatically logs warnings for:
+   - Unregistered request types
+   - Multiple handlers registered for the same type
+   - Handler execution errors
+
+## Dependencies
+
+The RequestHandler feature depends on:
+
+- `@vived/core`: Core application framework
+- `BaseApp`: For app state and rendering control
+- `StateMachine`: For state management (SET_APP_STATE)
+- `UndoRedo`: For undo/redo stack management (SET_APP_STATE)
+- `FeatureFlags`: For feature flag management (ENABLE_FEATURE)
+- `ThemeColors`: For theme color management (SET_THEME_COLORS)
+- `Babylon`: For scene inspector (SHOW_BABYLON_INSPECTOR)
+- `XR`: For XR rendering (START_ZSPACE)
+- `zSpace`: For zSpace device support (START_ZSPACE, STOP_ZSPACE)
+- `Stylus`: For stylus emulation (START_ZSPACE)
+
+## Testing
+
+The feature includes comprehensive unit tests. To run tests:
+
+```bash
+npm run test:once RequestHandler
+```
+
+Test coverage includes:
+
+- Request routing and handler execution
+- Version validation
+- Payload parsing and validation
+- Error handling
+- Multiple handler registration warnings
+- Introspection request handling
+
+## Example: Complete Usage
+
+```typescript
+import { makeAppObjectRepo } from "@vived/core";
+import { setupAppHandlers } from "@vived/app";
+
+// Setup
+const appObjectRepo = makeAppObjectRepo();
+const appHandler = setupAppHandlers(appObjectRepo);
+
+// Query supported versions
+const versionRequest = {
+  type: "GET_APP_PAYLOAD_VERSION",
+  version: 2,
+  payload: {
+    callback: (versionMap: Map<string, number>) => {
+      console.log("Supported requests:", versionMap);
+    },
+  },
+};
+appHandler.handler(versionRequest);
+
+// Start the app
+const startRequest = {
+  type: "START_APP",
+  version: 2,
+  payload: {
+    container: document.getElementById("app-container"),
+  },
+};
+appHandler.handler(startRequest);
+
+// Enable a feature
+const featureRequest = {
+  type: "ENABLE_FEATURE",
+  version: 1,
+  payload: {
+    featureFlag: "ADVANCED_MODE",
+  },
+};
+appHandler.handler(featureRequest);
+
+// Set app state
+const stateRequest = {
+  type: "SET_APP_STATE",
+  version: 3,
+  payload: {
+    hasNextSlide: true,
+    hasPreviousSlide: false,
+    hideNavigation: false,
+    duration: 300,
+  },
+};
+appHandler.handler(stateRequest);
+
+// Stop the app
+const stopRequest = {
+  type: "STOP_APP",
+  version: 1,
+};
+appHandler.handler(stopRequest);
+```
+
+## Migration Notes
+
+When upgrading to newer versions of the RequestHandler feature:
+
+1. Use the introspection requests to check supported versions
+2. Update your request payloads to match the latest version
+3. Test thoroughly with the new version before deploying
+4. Maintain fallback logic for older versions if needed
+
+## Support
+
+For questions or issues with the RequestHandler feature, please refer to the VIVED documentation or contact the development team.