@vived/app 5.3.0 → 6.1.0

package/src/Dispatcher/README.md

@@ -0,0 +1,652 @@
+# Dispatcher Feature
+
+The Dispatcher feature provides a communication bridge between VIVED applications and their host environments. It follows Clean Architecture principles with Domain-Driven Design, allowing applications to dispatch requests to the host for handling external operations like UI dialogs, asset management, state navigation, and result submission.
+
+## Overview
+
+The Dispatcher acts as the primary communication mechanism between a VIVED app and its hosting environment. It encapsulates request/response patterns into type-safe Use Cases, enabling the app to request host services without direct coupling to host implementation details.
+
+**Key Responsibilities:**
+- Dispatch requests from app to host environment
+- Manage app lifecycle events (ready state, state changes)
+- Handle asset operations (fetch, metadata, URLs)
+- Control state navigation (previous, next, completion)
+- Trigger UI interactions (alerts, confirmations, editors)
+- Submit activity results and logs
+- Manage ZSpace integration
+- Register external resources (stylesheets)
+
+## Architecture
+
+### Entities
+
+#### AppDispatcher
+Core entity that manages communication with the host environment.
+
+```typescript
+abstract class AppDispatcher extends AppObjectEntity {
+  static readonly type = "APP_DISPATCHER";
+  verbose: boolean; // Enable logging of dispatched requests
+  
+  abstract dispatch: (request: Request) => void;
+  abstract formRequestAndDispatch: (
+    type: string,
+    version: number,
+    payload?: object
+  ) => void;
+}
+```
+
+**Creation:**
+```typescript
+import { makeAppDispatcher } from "@vived/app";
+
+const dispatcher = makeAppDispatcher(appObject, hostHandler);
+dispatcher.verbose = true; // Optional: enable request logging
+```
+
+### Use Cases
+
+All Use Cases follow a consistent pattern and require an AppDispatcher to function. Each UC encapsulates a specific host interaction with:
+- A unique `requestType` string
+- A `requestVersion` number for API versioning
+- Type-safe methods for dispatching requests
+- Automatic validation that AppDispatcher exists
+
+#### App Lifecycle Use Cases
+
+**AppIsReadyUC** - Notify host that app has initialized
+```typescript
+import { appIsReady } from "@vived/app";
+
+appIsReady(appObjects);
+```
+
+**DispatchStateChangeUC** - Notify host of state changes (authoring mode)
+```typescript
+import { dispatchStateChange } from "@vived/app";
+
+// Requires StateMachineEntity and BaseAppState
+dispatchStateChange(appObjects);
+```
+
+**RestoreCurrentStateUC** - Request host to restore current state
+```typescript
+const uc = RestoreCurrentStateUC.get(appObjects);
+uc?.doDispatch();
+```
+
+#### State Navigation Use Cases
+
+**GoToNextStateUC** - Navigate to next state
+```typescript
+const uc = GoToNextStateUC.get(appObjects);
+uc?.doDispatch();
+```
+
+**GoToPreviousStateUC** - Navigate to previous state
+```typescript
+const uc = GoToPreviousStateUC.get(appObjects);
+uc?.doDispatch();
+```
+
+**HasNextStateUC** - Check if next state exists
+```typescript
+const uc = HasNextStateUC.get(appObjects);
+const hasNext = await uc?.doDispatch();
+```
+
+**HasPreviousStateUC** - Check if previous state exists
+```typescript
+const uc = HasPreviousStateUC.get(appObjects);
+const hasPrevious = await uc?.doDispatch();
+```
+
+**StateHasChangedUC** - Check if state has changed
+```typescript
+const uc = StateHasChangedUC.get(appObjects);
+const hasChanged = await uc?.doDispatch();
+```
+
+**StateIsCompleteUC** - Check if current state is complete
+```typescript
+const uc = StateIsCompleteUC.get(appObjects);
+const isComplete = await uc?.doDispatch();
+```
+
+#### Asset Management Use Cases
+
+**GetAssetBlobURLUC** - Fetch blob URL for an asset
+```typescript
+import { getAssetBlobURL } from "@vived/app";
+
+const blobURL = await getAssetBlobURL("asset-id", appObjects);
+```
+
+**GetAssetFolderURLUC** - Get URL for asset folder
+```typescript
+const uc = GetAssetFolderURLUC.get(appObjects);
+const folderURL = await uc?.doDispatch();
+```
+
+**GetAssetMetaUC** - Retrieve asset metadata
+```typescript
+const uc = GetAssetMetaUC.get(appObjects);
+const meta = await uc?.doDispatch("asset-id");
+// Returns: AssetMetaDTO { id, name, description }
+```
+
+**GetAssetsForOwnerUC** - Get all assets for an owner
+```typescript
+const uc = GetAssetsForOwnerUC.get(appObjects);
+const assets = await uc?.doDispatch("owner-id");
+```
+
+**GetLinkedAssetsUC** - Get assets linked to current activity
+```typescript
+const uc = GetLinkedAssetsUC.get(appObjects);
+const assets = await uc?.doDispatch();
+```
+
+**IsAssetFetchedUC** - Check if asset has been fetched
+```typescript
+const uc = IsAssetFetchedUC.get(appObjects);
+const isFetched = await uc?.doDispatch("asset-id");
+```
+
+**SubmitActivityAssetUC** - Submit an asset for the activity
+```typescript
+const uc = SubmitActivityAssetUC.get(appObjects);
+await uc?.submitAsset(assetID, file);
+```
+
+#### UI Interaction Use Cases
+
+**ShowAlertUC** - Display alert dialog
+```typescript
+const uc = ShowAlertUC.get(appObjects);
+uc?.showAlert({
+  title: "Alert Title",
+  message: "Alert message",
+  closeButtonLabel: "OK",
+  closeCallback: () => console.log("Alert closed")
+});
+```
+
+**ShowConfirmUC** - Display confirmation dialog
+```typescript
+const uc = ShowConfirmUC.get(appObjects);
+uc?.showConfirm({
+  title: "Confirm Action",
+  message: "Are you sure?",
+  confirmButtonLabel: "Yes",
+  cancelButtonLabel: "No",
+  confirmCallback: () => console.log("Confirmed"),
+  cancelCallback: () => console.log("Cancelled")
+});
+```
+
+**ShowMarkdownEditorUC** - Display markdown editor
+```typescript
+const uc = ShowMarkdownEditorUC.get(appObjects);
+uc?.showMarkdownEditor({
+  markdown: "# Initial Content",
+  saveCallback: (updatedMarkdown) => console.log(updatedMarkdown),
+  closeCallback: () => console.log("Editor closed")
+});
+```
+
+**ShowSelectModelUC** - Show model selection dialog
+```typescript
+const uc = ShowSelectModelUC.get(appObjects);
+const selectedModel = await uc?.doDispatch();
+```
+
+**ShowSpinnerUC** - Show/hide loading spinner
+```typescript
+const uc = ShowSpinnerUC.get(appObjects);
+uc?.showSpinner(true); // Show spinner
+uc?.showSpinner(false); // Hide spinner
+```
+
+#### Result Submission Use Cases
+
+**SubmitResultResultUC** - Submit activity results
+```typescript
+import { 
+  submitHitResult, 
+  submitProgressResult,
+  submitQualityResult 
+} from "@vived/app";
+
+// Hit/Miss result
+submitHitResult({ 
+  success: true, 
+  description: "Correct answer" 
+}, appObjects);
+
+// Progress result
+submitProgressResult({ 
+  progress: 0.75, 
+  description: "75% complete" 
+}, appObjects);
+
+// Multi-hit result
+const uc = SubmitResultResultUC.get(appObjects);
+uc?.submitMultiHitResult({
+  hits: 8,
+  misses: 2,
+  unanswered: 0,
+  description: "Quiz results"
+});
+
+// Quality result (star rating)
+submitQualityResult({
+  stars: 4,
+  maxStars: 5,
+  description: "Good performance"
+}, appObjects);
+
+// Score result
+uc?.submitScoreResult({
+  score: 85,
+  maxScore: 100,
+  description: "Test score"
+});
+```
+
+#### ZSpace Integration Use Cases
+
+**IsZSpaceAvailableUC** - Check if ZSpace is available
+```typescript
+const uc = IsZSpaceAvailableUC.get(appObjects);
+const isAvailable = await uc?.doDispatch();
+```
+
+**DispatchStartZSpaceUC** - Start ZSpace mode
+```typescript
+const uc = DispatchStartZSpaceUC.get(appObjects);
+uc?.doDispatch();
+```
+
+**DispatchStopZSpaceUC** - Stop ZSpace mode
+```typescript
+import { dispatchStopZSpace } from "@vived/app";
+
+dispatchStopZSpace(appObjects);
+```
+
+#### Utility Use Cases
+
+**LogUC** - Send log messages to host
+```typescript
+const uc = LogUC.get(appObjects);
+uc?.dispatchLog("ComponentName", "Info message");
+uc?.dispatchWarn("ComponentName", "Warning message");
+uc?.dispatchError("ComponentName", "Error message");
+uc?.dispatchFatal("ComponentName", "Fatal error");
+```
+
+**RegisterExternalStylesheetsUC** - Register external CSS files
+```typescript
+const uc = RegisterExternalStylesheetsUC.get(appObjects);
+uc?.doDispatch(["https://example.com/style1.css", "https://example.com/style2.css"]);
+```
+
+### Controllers
+
+Controllers provide convenient wrapper functions for common operations:
+
+**dispatchStopZSpace** - Stop ZSpace mode
+```typescript
+import { dispatchStopZSpace } from "@vived/app";
+
+dispatchStopZSpace(appObjects);
+```
+
+### Types
+
+**AssetMetaDTO** - Asset metadata structure
+```typescript
+interface AssetMetaDTO {
+  id: string;
+  name: string;
+  description: string;
+}
+```
+
+### Factories
+
+#### DispatcherFeatureFactory
+Domain factory for setting up the complete Dispatcher feature.
+
+```typescript
+import { DispatcherFeatureFactory } from "@vived/app";
+
+const factory = new DispatcherFeatureFactory(appObject, hostHandler);
+factory.verbose = true; // Optional: enable dispatcher logging
+factory.setup(); // Sets up entity and all 24 use cases
+```
+
+**Legacy Setup Function:**
+```typescript
+import { setupDispatchers } from "@vived/app";
+
+// Older approach, prefer DispatcherFeatureFactory for new code
+setupDispatchers(appObjects, hostHandler);
+```
+
+## Usage Patterns
+
+### Basic Setup
+
+```typescript
+import { 
+  AppObjectRepo, 
+  makeAppObjectRepo,
+  Handler 
+} from "@vived/core";
+import { DispatcherFeatureFactory } from "@vived/app";
+
+// Create app objects repository
+const appObjects = makeAppObjectRepo();
+const dispatcherAO = appObjects.getOrCreate("App Dispatcher");
+
+// Define host handler
+const hostHandler: Handler = (request) => {
+  console.log("Host received:", request);
+  // Forward to host environment
+};
+
+// Setup dispatcher feature
+const factory = new DispatcherFeatureFactory(dispatcherAO, hostHandler);
+factory.setup();
+```
+
+### Using Dispatcher in Features
+
+```typescript
+import { appIsReady, getAssetBlobURL, submitHitResult } from "@vived/app";
+
+// Notify host app is ready
+appIsReady(appObjects);
+
+// Fetch an asset
+try {
+  const blobURL = await getAssetBlobURL("asset-123", appObjects);
+  console.log("Asset URL:", blobURL);
+} catch (error) {
+  console.error("Failed to fetch asset:", error);
+}
+
+// Submit activity result
+submitHitResult(
+  { success: true, description: "User completed task" },
+  appObjects
+);
+```
+
+### Request/Response Pattern
+
+The dispatcher uses a Request object format:
+
+```typescript
+interface Request {
+  type: string;      // e.g., "SHOW_ALERT"
+  version: number;   // API version (1, 2, 3...)
+  payload?: object;  // Optional data
+}
+```
+
+Example of what gets dispatched:
+```typescript
+// When calling showAlert
+{
+  type: "SHOW_ALERT",
+  version: 1,
+  payload: {
+    title: "Title",
+    message: "Message",
+    closeButtonLabel: "OK",
+    closeCallback: Function
+  }
+}
+```
+
+## Testing
+
+### Testing with Mocks
+
+The Dispatcher feature provides mock implementations for testing:
+
+**MockDispatcher** - Mock the AppDispatcher entity
+```typescript
+import { makeMockDispatcher } from "@vived/app";
+
+const mockDispatcher = makeMockDispatcher(appObjects);
+// Use in tests without actual host communication
+```
+
+**Mock Use Cases** - Available mocks:
+- `MockShowAlert` - Mock alert dialogs
+- `MockShowConfirm` - Mock confirmation dialogs
+- `MockShowMarkdown` - Mock markdown editor
+- `MockShowSpinner` - Mock spinner control
+- `MockSubmitResult` - Mock result submission
+- `MockDispatchStateChange` - Mock state change dispatching
+- `MockGetAssetFolderURL` - Mock asset folder URL retrieval
+- `GetAssetBlobURLUCMock` - Mock asset blob URL retrieval
+- `GetLinkedAssetsUCMock` - Mock linked assets retrieval
+- `ShowSelectModelUCMock` - Mock model selection
+
+Example test:
+```typescript
+import { makeAppObjectRepo } from "@vived/core";
+import { makeMockDispatcher, makeShowAlertUC } from "@vived/app";
+
+describe("Feature using alerts", () => {
+  it("Shows an alert", () => {
+    const appObjects = makeAppObjectRepo();
+    const dispatcherAO = appObjects.getOrCreate("Dispatcher");
+    
+    const mockDispatcher = makeMockDispatcher(appObjects);
+    const spy = jest.spyOn(mockDispatcher, "formRequestAndDispatch");
+    
+    const uc = makeShowAlertUC(dispatcherAO);
+    uc.showAlert({
+      title: "Test",
+      message: "Test message",
+      closeButtonLabel: "OK",
+      closeCallback: jest.fn()
+    });
+    
+    expect(spy).toHaveBeenCalledWith("SHOW_ALERT", 1, expect.any(Object));
+  });
+});
+```
+
+### Testing Use Cases
+
+Use Cases follow a standard test pattern:
+1. Create test rig with MockDispatcher
+2. Create the Use Case
+3. Spy on `formRequestAndDispatch`
+4. Verify request type, version, and payload
+
+Example:
+```typescript
+import { makeAppObjectRepo } from "@vived/core";
+import { AppDispatcher } from "@vived/app";
+import { ShowAlertUC, makeShowAlertUC } from "@vived/app";
+
+class MockDispatcher extends AppDispatcher {
+  dispatch = jest.fn();
+  formRequestAndDispatch = jest.fn();
+}
+
+function makeTestRig() {
+  const appObjects = makeAppObjectRepo();
+  const dispatcher = appObjects.getOrCreate("Dispatcher");
+  const mockDispatcher = new MockDispatcher(dispatcher, AppDispatcher.type);
+  const uc = makeShowAlertUC(dispatcher);
+  
+  return { uc, mockDispatcher, appObjects };
+}
+
+describe("ShowAlertUC", () => {
+  it("Dispatches correct request type", () => {
+    const { uc, mockDispatcher } = makeTestRig();
+    const spy = jest.spyOn(mockDispatcher, "formRequestAndDispatch");
+    
+    uc.showAlert({
+      title: "Test",
+      message: "Message",
+      closeButtonLabel: "OK",
+      closeCallback: jest.fn()
+    });
+    
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy.mock.calls[0][0]).toEqual("SHOW_ALERT");
+    expect(spy.mock.calls[0][1]).toEqual(1); // version
+  });
+});
+```
+
+## Component Summary
+
+### Entities (1)
+- `AppDispatcher` - Core dispatcher entity
+
+### Use Cases (27)
+**Lifecycle:** AppIsReadyUC, DispatchStateChangeUC, RestoreCurrentStateUC
+
+**State Navigation:** GoToNextStateUC, GoToPreviousStateUC, HasNextStateUC, HasPreviousStateUC, StateHasChangedUC, StateIsCompleteUC
+
+**Assets:** GetAssetBlobURLUC, GetAssetFolderURLUC, GetAssetMetaUC, GetAssetsForOwnerUC, GetLinkedAssetsUC, IsAssetFetchedUC, SubmitActivityAssetUC
+
+**UI:** ShowAlertUC, ShowConfirmUC, ShowMarkdownEditorUC, ShowSelectModelUC, ShowSpinnerUC
+
+**Results:** SubmitResultResultUC
+
+**ZSpace:** DispatchStartZSpaceUC, DispatchStopZSpaceUC, IsZSpaceAvailableUC
+
+**Utilities:** LogUC, RegisterExternalStylesheetsUC
+
+### Controllers (1)
+- `dispatchStopZSpace` - Controller for stopping ZSpace
+
+### Factories (2)
+- `DispatcherFeatureFactory` - Modern factory for complete setup
+- `setupDispatchers` - Legacy setup function
+
+### Mocks (12)
+- `MockDispatcher` - Mock dispatcher entity
+- `MockShowAlert`, `MockShowConfirm`, `MockShowMarkdown` - UI mocks
+- `MockShowSpinner`, `MockSubmitResult` - Action mocks
+- `MockDispatchStateChange`, `MockGetAssetFolderURL` - State/Asset mocks
+- `GetAssetBlobURLUCMock`, `GetLinkedAssetsUCMock`, `ShowSelectModelUCMock` - UC mocks
+
+### Types (1)
+- `AssetMetaDTO` - Asset metadata structure
+
+## Dependencies
+
+**Required:**
+- `@vived/core` - Core VIVED framework types and utilities
+
+**Optional (for specific features):**
+- `StateMachineEntity` - Required for DispatchStateChangeUC
+- `BaseAppState` - Required for DispatchStateChangeUC
+
+## Best Practices
+
+1. **Always check UC availability** - Use optional chaining when getting UCs
+   ```typescript
+   const uc = ShowAlertUC.get(appObjects);
+   uc?.showAlert(data); // Safe call
+   ```
+
+2. **Handle async operations** - Many UCs return Promises
+   ```typescript
+   try {
+     const url = await getAssetBlobURL("id", appObjects);
+   } catch (error) {
+     console.error("Failed:", error);
+   }
+   ```
+
+3. **Use factory for setup** - Prefer DispatcherFeatureFactory over manual setup
+   ```typescript
+   const factory = new DispatcherFeatureFactory(appObject, hostHandler);
+   factory.setup();
+   ```
+
+4. **Enable verbose logging during development**
+   ```typescript
+   const dispatcher = AppDispatcher.get(appObjects);
+   if (dispatcher) dispatcher.verbose = true;
+   ```
+
+5. **Mock in tests** - Always use mock implementations for unit testing
+   ```typescript
+   const mockDispatcher = makeMockDispatcher(appObjects);
+   ```
+
+6. **Version your requests** - When host API changes, increment requestVersion
+   ```typescript
+   // In UC implementation
+   readonly requestVersion = 2; // Incremented from 1
+   ```
+
+## Request Type Reference
+
+| Request Type | Version | Use Case | Description |
+|--------------|---------|----------|-------------|
+| APP_IS_READY | 1 | AppIsReadyUC | App initialization complete |
+| ON_STATE_CHANGE | 3 | DispatchStateChangeUC | State has changed (authoring) |
+| RESTORE_CURRENT_STATE | 1 | RestoreCurrentStateUC | Restore current state |
+| GO_TO_NEXT_STATE | 1 | GoToNextStateUC | Navigate to next state |
+| GO_TO_PREVIOUS_STATE | 1 | GoToPreviousStateUC | Navigate to previous state |
+| HAS_NEXT_STATE | 1 | HasNextStateUC | Check next state exists |
+| HAS_PREVIOUS_STATE | 1 | HasPreviousStateUC | Check previous state exists |
+| STATE_HAS_CHANGED | 1 | StateHasChangedUC | Check if state changed |
+| STATE_IS_COMPLETE | 1 | StateIsCompleteUC | Check if state complete |
+| GET_ASSET_BLOB | 1 | GetAssetBlobURLUC | Fetch asset blob URL |
+| GET_ASSET_FOLDER | 1 | GetAssetFolderURLUC | Get asset folder URL |
+| GET_ASSET_META | 1 | GetAssetMetaUC | Get asset metadata |
+| GET_ASSETS_FOR_OWNER | 1 | GetAssetsForOwnerUC | Get owner's assets |
+| GET_LINKED_ASSETS | 1 | GetLinkedAssetsUC | Get linked assets |
+| IS_ASSET_FETCHED | 1 | IsAssetFetchedUC | Check asset fetched |
+| SUBMIT_ACTIVITY_ASSET | 1 | SubmitActivityAssetUC | Submit activity asset |
+| SHOW_ALERT | 1 | ShowAlertUC | Display alert dialog |
+| SHOW_CONFIRM | 1 | ShowConfirmUC | Display confirm dialog |
+| SHOW_MARKDOWN_EDITOR | 1 | ShowMarkdownEditorUC | Show markdown editor |
+| SHOW_SELECT_MODEL | 1 | ShowSelectModelUC | Show model selection |
+| SHOW_SPINNER | 1 | ShowSpinnerUC | Toggle loading spinner |
+| SUBMIT_RESULTS | 1 | SubmitResultResultUC | Submit activity results |
+| START_ZSPACE | 1 | DispatchStartZSpaceUC | Start ZSpace mode |
+| STOP_ZSPACE | 1 | DispatchStopZSpaceUC | Stop ZSpace mode |
+| IS_ZSPACE_AVAILABLE | 1 | IsZSpaceAvailableUC | Check ZSpace available |
+| SUBMIT_LOG | 1 | LogUC | Send log message |
+| REGISTER_EXTERNAL_STYLESHEETS | 1 | RegisterExternalStylesheetsUC | Register CSS files |
+
+## AI Agent Guidelines
+
+When working with the Dispatcher feature:
+
+1. **Identify the operation** - Determine what host interaction is needed
+2. **Find the appropriate UC** - Reference the component summary or request type table
+3. **Check dependencies** - Ensure AppDispatcher is set up in the AppObjectRepo
+4. **Use type-safe APIs** - Follow the UC interfaces and DTOs
+5. **Handle errors gracefully** - Many UCs return Promises that can reject
+6. **Test with mocks** - Use provided mock implementations for isolated testing
+7. **Follow naming conventions** - UCs are PascalCase, factories/functions are camelCase
+8. **Document request versions** - Note which API version each request uses
+
+For new functionality, extend by:
+1. Creating a new UC extending `AppObjectUC`
+2. Defining `requestType` and `requestVersion`
+3. Implementing dispatch logic using AppDispatcher
+4. Adding to DispatcherFeatureFactory's `setupUCs()`
+5. Creating corresponding mock for testing
+6. Writing comprehensive tests following AAA pattern