@vived/core 2.0.1 → 2.0.2

package/src/AppObject/README.md

@@ -0,0 +1,476 @@
+# App Object Architecture
+
+> This document describes the `AppObject` architecture and its component ecosystem. The low-level `AppObjectController` base class file itself is not detailed here, but controller *behavior* and flow are now documented for completeness.
+
+## Overview
+The architecture centers around the concept of an **App Object** – a composable, observable container of domain-specific components. Each `AppObject` aggregates behavior and state through **components** that follow clear separation-of-responsibility categories:
+
+- Entity: stateful, observable model logic
+- Presentation Manager (PM): derives and emits immutable view models
+- Use Case (UC): encapsulates application operations / workflows
+- View: renders or binds presentation output to a UI or rendering substrate
+- (Other) Arbitrary/custom components categorized as `UNKNOWN`
+
+The system encourages:
+- Decoupling via **component lookup** and **repository-level singleton resolution**
+- Reactive propagation via observer lists on entities, PMs, and AppObjects
+- Composability: AppObjects can be extended at runtime by adding/replacing components
+- Testability: Small, focused classes with explicit contracts
+
+## Core Building Blocks
+
+### AppObject (`AppObject.ts`)
+An abstract observable node that:
+- Owns a unique `id`
+- Registers itself in an `AppObjectRepo`
+- Manages a map of `type -> AppObjectComponent`
+- Notifies observers when its component set changes (e.g., add/remove/replace)
+- Handles lifecycle: `dispose()` removes itself from the repo and disposes all components
+
+Creation is performed via `makeAppObject(id, repo)` which returns a concrete internal implementation.
+
+### AppObjectComponent (`AppObjectComponent.ts`)
+The base class for all components. Responsibilities:
+- Auto–attaches to its parent `AppObject` on construction
+- Exposes `componentType` (categorical enum) and `type` (unique string identifier)
+- Provides cached retrieval helpers:
+  - `getCachedLocalComponent(type)` – same AppObject
+  - `getCachedSingleton(type)` – repo-level singleton component
+  - `getSingleton(type, logLevel)` – non‑cached lookup with log control
+- Supports disposal: removing itself if still attached
+- Provides uniform logging APIs proxied to the repository
+
+Design Notes:
+- Caching avoids repeated map traversal and singleton scans
+- Logging includes composite key `AppObjectID/ComponentTypeString`
+
+### AppObjectEntity (`AppObjectEntity.ts`)
+Specialized component for **domain/application state**. Provides:
+- Change observers via `addChangeObserver` / `notifyOnChange`
+- Disposal observers via `addOnDisposeObserver`
+- Automatic registration of the parent `AppObject`'s `notify` method as a change observer so AppObject-level observers react to entity changes
+
+Patterns enabled:
+- PM subscribes to one or more Entities to derive view state
+- Repository-level aggregation via `AppObjectEntityRepo`
+
+### AppObjectSingletonEntity (`AppObjectSingletonEntity.ts`)
+A specialized entity that automatically registers itself as a singleton. Extends `AppObjectEntity` with:
+- Automatic singleton registration via `appObjects.registerSingleton(this)` in constructor
+- Automatic singleton unregistration via `appObjects.unregisterSingleton(this.type)` on disposal
+- Ensures only one instance of this entity type exists across the entire application
+
+Use this when you need globally unique entities (e.g., application-wide configuration, user session state).
+
+### AppObjectEntityRepo (`AppObjectEntityRepo.ts`)
+A stateful collection component (itself an `AppObjectEntity`) that manages many entity instances keyed by `AppObject.id`:
+- Add/remove operations attach/detach change observers on each entity to bubble aggregate change notifications
+- Emits addition/removal notifications through dedicated observer lists
+- Factory pattern support:
+  - `create(id?: string)` – creates a new entity via `entityFactory` and adds it to the repository (auto-generates ID if not provided)
+  - `entityFactory(appObject: AppObject)` – abstract method that derived classes override to provide custom entity creation logic
+- Query surface:
+  - `has(id)` – checks if an entity exists for the given ID
+  - `getById(id)` – retrieves an entity by its ID
+  - `getOrCreate(id)` – gets an existing entity by ID, or creates it if it doesn't exist
+  - `getAll()` – returns all entities in the repository
+- Mutation operations:
+  - `add(entity)` – adds an entity to the repository
+  - `removeById(id)` – removes a single entity by its ID
+  - `deleteAll()` – removes all entities from the repository
+- Legacy methods (deprecated):
+  - `hasForAppObject(id)` – use `has(id)` instead
+  - `getForAppObject(id)` – use `getById(id)` instead
+  - `removeForAppObject(id)` – use `removeById(id)` instead
+
+**Factory Pattern Usage:**
+Derived repositories should override `entityFactory` to provide entity creation logic:
+```ts
+class PlayerRepo extends AppObjectEntityRepo<PlayerEntity> {
+  static type = "playerRepo";
+  
+  constructor(appObject: AppObject) {
+    super(appObject, PlayerRepo.type);
+  }
+  
+  entityFactory(appObject: AppObject): PlayerEntity {
+    return new PlayerEntity(appObject);
+  }
+}
+
+// Usage
+const repo = new PlayerRepo(repoAppObject);
+const player1 = repo.create("player-1"); // Create with specific ID
+const player2 = repo.create(); // Create with auto-generated ID
+const player3 = repo.getOrCreate("player-1"); // Get existing player1 or create if missing
+```
+
+This enables higher-level coordination (e.g., multi-selection, batch processing, dashboards) with cohesive reactivity.
+
+### AppObjectSingletonEntityRepo (`AppObjectSingletonEntityRepo.ts`)
+Generic singleton repository for managing entity collections. Extends `AppObjectEntityRepo<T>` with:
+- Automatic singleton registration and unregistration (same pattern as `AppObjectSingletonEntity`)
+- Type-safe entity collection management across the entire application
+- Use when you need a single, centralized collection (e.g., all players, all items, all tasks)
+
+Example:
+```ts
+class PlayerRepo extends AppObjectSingletonEntityRepo<PlayerEntity> {
+  static type = "playerRepo";
+  constructor(appObject: AppObject) {
+    super(appObject, PlayerRepo.type);
+  }
+}
+```
+
+### AppObjectPM (`AppObjectPM.ts`)
+The Presentation Manager (Presentation Model / MVVM mediator). Responsibilities:
+- Maintains last emitted view model (`lastVM`)
+- Optionally provides a `defaultVM` for initial state before any view model is generated
+- Compares new vs prior view model via abstract `vmsAreEqual(a,b)` to suppress redundant updates
+- Manages a list of view observers (`addView` / `removeView`)
+- Provides `doUpdateView(vm)` to push updates only when meaningfully changed
+- Supports automatic entity observation via `observeEntity(entity)` for reactive view model updates
+- Implements lazy evaluation: `formVM()` is only called when views are registered
+- Provides `onViewAdded()` lifecycle hook that is called whenever a view is added
+- Automatically cleans up entity observers on disposal
+
+**New Reactive Pattern (Preferred):**
+Derived PMs can now use automatic entity observation:
+1. Call `observeEntity(entity)` in the constructor to register entities
+2. Override `formVM()` to generate view models from entity state
+3. When observed entities change, `formVM()` is automatically called (only if views are registered)
+4. Optionally override `onViewAdded()` to react when views are added (e.g., start animations, log analytics)
+5. Entity observers are automatically cleaned up on disposal
+
+**Backward Compatibility:**
+All existing PM implementations continue to work without modification. The new features are optional enhancements that provide:
+- Automatic view model regeneration on entity changes
+- Default view model support for initial state
+- Simplified entity observation with automatic cleanup
+- Lifecycle hooks for reacting to view additions
+
+This isolates transformation logic and prevents UI churn.
+
+### AppObjectSingletonPM (`AppObjectSingletonPM.ts`)
+Abstract singleton presentation manager that extends `AppObjectPM<T>` with:
+- Automatic singleton registration and unregistration
+- Ensures only one PM instance of this type exists across the application
+- Inherits all automatic entity observation and view model caching features
+- Use for global UI state (e.g., application theme, notification center, global progress indicator)
+
+Example:
+```ts
+class GlobalThemePM extends AppObjectSingletonPM<ThemeVM> {
+  static type = "globalThemePM";
+  
+  constructor(appObject: AppObject) {
+    super(appObject, GlobalThemePM.type);
+    const settings = this.getCachedSingleton<SettingsEntity>(SettingsEntity.type);
+    if (settings) this.observeEntity(settings);
+  }
+  
+  vmsAreEqual(a: ThemeVM, b: ThemeVM): boolean {
+    return a.mode === b.mode && a.primaryColor === b.primaryColor;
+  }
+  
+  formVM(): void {
+    // Transform settings into theme view model
+  }
+}
+```
+
+### AppObjectUC (`AppObjectUC.ts`)
+A semantic base for **application operations** (e.g., workflows, transactional steps). It adds categorical identity (`componentType = UC`) but intentionally stays minimal so concrete subclasses can:
+- Orchestrate entities, PMs, and repositories
+- Enforce validation and domain rules
+- Trigger PM updates or entity mutations
+
+### AppObjectSingletonUC (`AppObjectSingletonUC.ts`)
+Singleton use case component that extends `AppObjectUC` with:
+- Automatic singleton registration and unregistration
+- Ensures only one UC instance of this type exists across the application
+- Use for application-wide orchestration logic (e.g., global purchase manager, authentication coordinator)
+
+Example:
+```ts
+class AuthenticationUC extends AppObjectSingletonUC {
+  static type = "authenticationUC";
+  
+  constructor(appObject: AppObject) {
+    super(appObject, AuthenticationUC.type);
+  }
+  
+  login(username: string, password: string): Promise<boolean> {
+    // Application-wide authentication logic
+  }
+  
+  logout(): void {
+    // Clean up session, notify entities, etc.
+  }
+}
+```
+
+### AppObjectView (`AppObjectView.ts`)
+A rendering/binding endpoint:
+- Categorized as `VIEW`
+- Typically subscribes to one or more PMs (manually, via the PM's `addView` API)
+- Focused purely on projecting view models to a target (DOM, WebGL scene graph, canvas, etc.)
+
+### getSingletonComponent (`getSingletonComponent.ts`)
+A convenience helper:
+```ts
+const camera = getSingletonComponent<CameraPM>(CameraPM.type, repo);
+```
+- Wraps `repo.getSingleton(type)` to simplify imports and generics at call sites
+
+### printAppObjectDetails (`printAppObjectDetails.ts`)
+Debugging utility that enumerates components attached to a given AppObject ID.
+
+## Repository Layer
+`AppObjectRepo`:
+- Tracks all AppObjects (`id -> AppObject`)
+- Aggregates reactivity: registers itself as observer of each AppObject; its own observers can react to structural changes
+- Maintains explicit singleton registry (Map of `type -> component`)
+  - `registerSingleton(component)` – explicitly register a component as singleton
+  - `unregisterSingleton(type)` – remove a singleton registration (called automatically by singleton components on disposal)
+  - `hasSingleton(type)` – check if a singleton exists (checks registry first, then falls back to scanning for single instance)
+  - `getSingleton(type)` – retrieve a singleton component
+  - Fallback heuristic: if not explicitly registered, scan all components of that type
+  - Warns on zero or multiple matches; caches first valid resolution
+- Query Helpers:
+  - `getAllAppObjectsWithComponent(type)`
+  - `getAllComponents(type)`
+  - `getAppObjectComponent(appObjectID, type)`
+- Logging hub consumed by components
+
+### Singleton Component Pattern
+The framework provides four singleton base classes that automatically handle registration/unregistration:
+- `AppObjectSingletonEntity` – singleton entities
+- `AppObjectSingletonEntityRepo<T>` – singleton entity repositories
+- `AppObjectSingletonPM<T>` – singleton presentation managers
+- `AppObjectSingletonUC` – singleton use cases
+
+All singleton components:
+1. Call `this.appObjects.registerSingleton(this)` in their constructor
+2. Call `this.appObjects.unregisterSingleton(this.type)` in their `dispose()` method
+3. Can be retrieved via `repo.getSingleton(type)` or `component.getCachedSingleton(type)`
+
+This pattern ensures singleton lifecycle management is handled consistently across all component types.
+
+## Typical User → UI → Domain Flow
+
+1. **Controller Trigger**  
+  A user action (click, input, gesture, hotkey, network event) calls a small *controller function*. Controllers are intentionally plain functions (see `ExampleFeature/Controllers/*.ts`). They:
+  - Accept raw UI parameters (strings, numbers, ids)
+  - Locate the appropriate Use Case (by `id` for per-object UCs or via static singleton accessors for global UCs)
+  - Guard against missing UCs and submit warnings through the repo
+  - Invoke a single semantic method on the UC
+
+2. **Use Case Mutation**  
+  The Use Case applies business rules and mutates one or more **Entities** (and occasionally invokes other UCs). Entities are considered part of the inner domain and remain decoupled from presentation concerns.
+
+3. **Entity Notification**  
+  Entities call `notifyOnChange()` after state mutation. Their change observers (PMs, the parent `AppObject`, repositories, etc.) are invoked.
+
+4. **Presentation Derivation**  
+  PMs receiving the change recompute an immutable **View Model**. If `vmsAreEqual(last, next)` is false, `doUpdateView(nextVM)` broadcasts the new model.
+
+5. **View Update**  
+  Views (or framework-side adapters) receive the new View Model and update rendering / UI bindings. React hooks, canvas redraws, WebGL scene updates, etc., occur here.
+
+Controller Functions remain deliberately slim: *resolve UC → call UC → handle missing cases*. This keeps UI code declarative and reduces duplication of lookup logic.
+
+### Adapters (Domain Boundary Helpers)
+Adapters (see `ExampleFeature/Adapters/*.ts`) standardize subscription mechanics between UI frameworks (React hooks, etc.) and PMs:
+- Provide a `defaultVM` for initial render
+- Encapsulate `subscribe` / `unsubscribe` logic
+- Support both per-object (`PmAdapter`) and singleton (`SingletonPmAdapter`) patterns
+
+## Dependency Direction (Clean Architecture Constraints)
+
+Strict layering reduces coupling and prevents presentation concerns from leaking inward:
+
+| Layer | May Depend On | Must NOT Depend On | Notes |
+|-------|----------------|--------------------|-------|
+| Entities (incl. Repos & Value Objects) | Other Entities, Value Objects | UCs, PMs, Controllers, Adapters | Repositories are treated as Entities (state holders) |
+| Use Cases (UCs) | Entities, other UCs | PMs | They orchestrate but never shape view models directly |
+| PMs | Entities, UCs | Other PMs (allowed but avoided), Controllers | No current need for PM→PM dependency encountered |
+| Controllers | UCs, (optionally) Repos for lookup | Entities, PM internals | Pure boundary functions; translate UI intent to UC invocation |
+| Adapters | PMs (subscription), Repos (to resolve PM) | UCs, Entities (direct mutation) | Provide view-model streaming into UI layer |
+| Views | PMs (via adapters or direct subscription) | UCs, Entities | Rendering only |
+
+Additional Rules:
+- Repos are considered data/state layer; treat them like Entities for dependency purposes.
+- Singletons do not relax dependency direction—acquire them only where the layer already allows the dependency.
+- Logging via repo methods is allowed anywhere because it does not introduce upward coupling.
+
+Violation Signals:
+- An Entity importing a UC or PM
+- A UC importing a PM
+- A PM invoking controller logic
+- Adapters mutating Entity state directly
+
+Refactor Strategy on Violation:
+1. Push mutation inward (Controller → UC → Entity)
+2. Introduce a new UC if orchestration spans multiple existing UCs
+3. Decompose a PM if it begins coordinating workflow rather than projecting state
+
+## Data & Reactive Flow
+1. Entity mutation occurs (e.g., property set in a subclass) → calls `notifyOnChange()`
+2. Entity notifies its observers (including its parent AppObject and any PMs)
+3. AppObject notifies its observers (repository + any external listeners)
+4. PM recalculates view model; if changed (`vmsAreEqual` is false), it calls `doUpdateView(vm)`
+5. Views previously registered with the PM receive the new view model and re-render
+
+```
+Entity --(notifyOnChange)--> PM --(doUpdateView)--> View
+   |                              ^                 |
+   +----> AppObject --(notify)----+                 |
+                 |                                   |
+                 v                                   |
+            AppObjectRepo (optional higher-level observers)
+```
+
+## Lifecycle Summary
+- Construct `AppObject` via `makeAppObject(id, repo)` → auto-added to repo
+- Construct components with `(appObject, type)` → auto-attached
+- Replace component: adding another of same `type` disposes previous instance
+- Dispose entity / component: removes self from AppObject, clears observers
+- Dispose AppObject: disposes all components, removes itself from repo
+
+## Extension Guidelines
+When adding a new component type:
+1. Define a static string identifier (e.g., `export const MyFeatureEntityType = "MyFeatureEntity";`)
+2. Choose the appropriate base class:
+   - For **regular components**: `AppObjectEntity`, `AppObjectPM`, `AppObjectUC`, or `AppObjectView`
+   - For **singleton components**: `AppObjectSingletonEntity`, `AppObjectSingletonEntityRepo<T>`, `AppObjectSingletonPM<T>`, or `AppObjectSingletonUC`
+3. Invoke `super(appObject, MyFeatureEntityType);` in constructor
+4. For PMs: implement `vmsAreEqual` (and optionally `formVM()` with `observeEntity()` for automatic updates)
+5. For singleton components: No additional registration needed—handled automatically by the base class
+6. Use cached getters for performance when repeatedly accessing collaborating components
+
+### Choosing Between Regular and Singleton Components
+Use **singleton components** when:
+- Only one instance should exist across the entire application
+- The component represents global application state or behavior
+- Examples: user session, app configuration, global theme, authentication manager
+
+Use **regular components** when:
+- Multiple instances may exist (one per AppObject)
+- The component represents per-object state or behavior
+- Examples: player state, item properties, entity-specific UI
+
+### Choosing Component Categories
+- Put durable, observable state in an Entity
+- Put pure transformation / derivation logic in a PM
+- Put orchestration / cross-entity logic in a UC
+- Put rendering / binding logic in a View
+- Avoid mixing responsibilities—compose instead
+
+## Example Composition (Pseudo-Code)
+```ts
+// Create repo & object
+const repo = makeAppObjectRepo();
+const playerAO = makeAppObject("player-1", repo);
+
+// Entity
+class PlayerState extends AppObjectEntity {
+  static type = "PlayerState";
+  health = 100;
+  constructor(ao: AppObject) { super(ao, PlayerState.type); }
+  damage(amount: number) { this.health = Math.max(0, this.health - amount); this.notifyOnChange(); }
+}
+
+// PM using new automatic entity observation (v1.7+)
+class PlayerHUDPM extends AppObjectPM<{ healthPercent: number }> {
+  static type = "PlayerHUDPM";
+  readonly defaultVM = { healthPercent: 1.0 }; // Initial full health
+  
+  constructor(ao: AppObject) {
+    super(ao, PlayerHUDPM.type);
+    const state = ao.getComponent<PlayerState>(PlayerState.type);
+    if (state) {
+      this.observeEntity(state); // Automatic observation
+    }
+  }
+  
+  vmsAreEqual(a, b) { return a.healthPercent === b.healthPercent; }
+  
+  // Automatically called when observed entities change (if views are registered)
+  formVM(): void {
+    const state = this.getCachedLocalComponent<PlayerState>(PlayerState.type);
+    if (state) {
+      this.doUpdateView({ healthPercent: state.health / 100 });
+    }
+  }
+}
+
+// View (simplified)
+class ConsoleHUDView extends AppObjectView {
+  static type = "ConsoleHUDView";
+  constructor(ao: AppObject, hudPM: PlayerHUDPM) { 
+    super(ao, ConsoleHUDView.type); 
+    hudPM.addView(vm => console.log("HP:", vm.healthPercent)); 
+  }
+}
+
+new PlayerState(playerAO);
+const hudPM = new PlayerHUDPM(playerAO);
+new ConsoleHUDView(playerAO, hudPM);
+
+// Trigger - PM automatically updates views when entity changes
+const ps = playerAO.getComponent<PlayerState>(PlayerState.type);
+ps?.damage(10); // PM automatically calls formVM() and updates views
+```
+
+**Legacy Pattern (Pre-v1.7, still supported):**
+```ts
+class PlayerHUDPM extends AppObjectPM<{ healthPercent: number }> {
+  static type = "PlayerHUDPM";
+  constructor(ao: AppObject) { super(ao, PlayerHUDPM.type); }
+  vmsAreEqual(a, b) { return a.healthPercent === b.healthPercent; }
+  
+  // Manual update method
+  update() {
+    const state = this.getCachedLocalComponent<PlayerState>(PlayerState.type);
+    if (!state) return;
+    this.doUpdateView({ healthPercent: state.health / 100 });
+  }
+}
+
+// Manual trigger required
+ps?.damage(10);
+hudPM.update(); // Must manually call update
+```
+
+## Logging & Diagnostics
+- Components call `log|warn|error` → forwarded via repo (current implementation prints to console)
+- `printAppObjectDetails(id, repo)` lists attached component types
+- Replacing a component logs a warning
+
+## Performance Considerations
+- Component caches avoid redundant map lookups and singleton scans
+- PM equality check prevents spurious view updates
+- Repository singleton cache resolves dynamic discovery only once per type
+
+## Error Handling & Warnings
+- Missing singleton lookup emits a warning (not fatal)
+- Multiple candidates for a supposed singleton: first is used + warning
+- Replacing a component of same type logs a warning and disposes old instance
+
+## Glossary
+- AppObject: A composable, observable unit of application composition
+- Component: A behavior/state module attached to an AppObject
+- Entity: Stateful, observable component storing domain data
+- PM (Presentation Manager): Transforms Entities into view models for Views
+- UC (Use Case): Encapsulates business workflow logic
+- View: Renders or binds presentation logic to UI / output medium
+- Singleton Component: A component intended to exist once across the repo, retrievable via `getSingleton`
+
+## Future Enhancements (Ideas)
+- Stronger typing for component `type` identifiers (string literal unions)
+- Async disposal hooks for resources (e.g., WebGL buffers)
+- Built-in metrics / instrumentation hooks
+- Dev tooling: Graph generation of AppObjects and dependencies
+

package/src/DomainFactories/README.md

@@ -0,0 +1,154 @@
+# DomainFactories
+
+The DomainFactories feature provides a structured approach for organizing and initializing application domains. It enforces a multi-phase setup sequence that ensures dependencies are properly resolved across different architectural layers.
+
+## Overview
+
+A domain factory is responsible for setting up all components within a specific domain or feature of your application. The setup is orchestrated through a four-phase process:
+
+1. **Entities** - Data models and repositories
+2. **Use Cases (UCs)** - Business logic that operates on entities
+3. **Presentation Managers (PMs)** - View models that transform entity data
+4. **Final Setup** - Any remaining initialization after all components are ready
+
+This phased approach ensures that components can depend on earlier phases being complete, both within a domain and across different domains.
+
+## Core Components
+
+### DomainFactory
+
+Abstract base class that all domain factories must extend. Each concrete factory must implement four setup methods:
+
+- `setupEntities()` - Initialize data models and repositories
+- `setupUCs()` - Initialize business logic components
+- `setupPMs()` - Initialize presentation layer components
+- `finalSetup()` - Perform final initialization
+
+Domain factories automatically register themselves with the `DomainFactoryRepo` upon construction.
+
+### DomainFactoryRepo
+
+Singleton repository that manages all domain factories and orchestrates their initialization. It provides:
+
+- **Phase coordination** - Executes setup phases across all factories in the correct order
+- **Factory lookup** - Retrieve factories by name using `getByName()`
+- **Global access** - Singleton accessible via `DomainFactoryRepo.get(appObjects)`
+
+## Usage
+
+### Creating a Domain Factory
+
+```typescript
+import { DomainFactory } from "@vived/core";
+import { AppObject } from "@vived/core";
+
+export class MyFeatureDomainFactory extends DomainFactory
+{
+	readonly factoryName = "MyFeatureDomainFactory";
+
+	setupEntities(): void
+	{
+		// Create and configure entities and repositories
+		// Example: new MyEntityRepo(this.appObjects.getOrCreate("MyEntityRepo"));
+	}
+
+	setupUCs(): void
+	{
+		// Create and configure use cases
+		// Example: new MyUseCase(this.appObjects.getOrCreate("MyUseCase"));
+	}
+
+	setupPMs(): void
+	{
+		// Create and configure presentation managers
+		// Example: new MyPM(this.appObjects.getOrCreate("MyPM"));
+	}
+
+	finalSetup(): void
+	{
+		// Perform any final initialization
+		// Example: Subscribe to events, configure cross-domain dependencies
+	}
+
+	constructor(appObject: AppObject)
+	{
+		super(appObject);
+	}
+}
+```
+
+### Initializing the Domain Layer
+
+```typescript
+import { makeAppObjectRepo, makeDomainFactoryRepo } from "@vived/core";
+import { MyFeatureDomainFactory } from "./MyFeatureDomainFactory";
+import { AnotherFeatureDomainFactory } from "./AnotherFeatureDomainFactory";
+
+// Create the application object repository
+const appObjects = makeAppObjectRepo();
+
+// Create the domain factory repository
+const domainFactoryRepo = makeDomainFactoryRepo(appObjects);
+
+// Instantiate your domain factories (they auto-register)
+new MyFeatureDomainFactory(appObjects.getOrCreate("MyFeatureDomainFactory"));
+new AnotherFeatureDomainFactory(appObjects.getOrCreate("AnotherFeatureDomainFactory"));
+
+// Execute the complete domain setup in proper sequence
+domainFactoryRepo.setupDomain();
+```
+
+### Accessing a Domain Factory
+
+```typescript
+// Retrieve a specific domain factory by name
+const myFactory = domainFactoryRepo.getByName("MyFeatureDomainFactory");
+
+// Access the singleton repo from anywhere
+const repo = DomainFactoryRepo.get(appObjects);
+```
+
+## Setup Sequence
+
+When `setupDomain()` is called, the repository executes phases in this order:
+
+1. All factories execute `setupEntities()`
+2. All factories execute `setupUCs()`
+3. All factories execute `setupPMs()`
+4. All factories execute `finalSetup()`
+
+This ensures that if Factory B's use cases depend on Factory A's entities, those entities will already be initialized.
+
+## Testing
+
+The `MockDomainFactory` class provides a test double with Jest mock functions for all setup methods:
+
+```typescript
+import { MockDomainFactory } from "@vived/core";
+import { makeAppObjectRepo } from "@vived/core";
+
+const appObjects = makeAppObjectRepo();
+const mockFactory = new MockDomainFactory(appObjects.getOrCreate("test"));
+
+// Verify setup methods are called
+expect(mockFactory.setupEntities).toHaveBeenCalled();
+
+// Check call order
+expect(mockFactory.setupEntities).toHaveBeenCalledBefore(mockFactory.setupUCs);
+```
+
+## Best Practices
+
+- **Keep factories focused** - Each factory should manage a single domain or feature
+- **Use meaningful names** - Set `factoryName` to something descriptive for easy retrieval
+- **Respect phase boundaries** - Don't access components from later phases during earlier phases
+- **Avoid cross-phase dependencies** - Entities shouldn't depend on UCs, UCs shouldn't depend on PMs
+- **Use finalSetup sparingly** - Most initialization should happen in the appropriate phase
+
+## Architecture Benefits
+
+- **Dependency management** - Clear initialization order prevents "component not found" errors
+- **Modularity** - Each domain is self-contained in its own factory
+- **Testability** - Mock factories enable isolated testing of the orchestration logic
+- **Scalability** - Easy to add new domains without modifying existing code
+- **Maintainability** - Clear structure makes it obvious where components should be initialized