@vived/core 2.0.0 → 2.0.2

package/dist/esm/ExampleFeature/Entities/ExampleRepo.js

@@ -72,12 +72,11 @@ export function makeExampleRepo(appObject) {
 class ExampleRepoImp extends ExampleRepo {
     /**
      * Factory implementation for creating ExampleEntity instances
-     * @param id The ID for the entity's AppObject
+     * @param appObject The AppObject for the entity
      * @returns A newly created ExampleEntity
      */
-    entityFactory(id) {
-        const ao = this.appObjects.getOrCreate(id);
-        return makeExampleEntity(ao);
+    entityFactory(appObject) {
+        return makeExampleEntity(appObject);
     }
     /**
      * Deletes an ExampleEntity from the repository by its AppObject ID

package/dist/esm/ExampleFeature/Entities/ExampleRepo.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExampleRepo.js","sourceRoot":"","sources":["../../../../src/ExampleFeature/Entities/ExampleRepo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAa,mBAAmB,EAAiB,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAiB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAKnE;;;GAGG;AACH,MAAM,OAAgB,WAAY,SAAQ,mBAAkC;IAO1E;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,MAAiB;QAC1B,OAAO,MAAM,CAAC,YAAY,CAAc,IAAI,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CACZ,EAAU,EACV,UAAyB;QAEzB,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,YAAY,CAAc,IAAI,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,SAAoB;QACtC,MAAM,QAAQ,GAAG,SAAS,CAAC,YAAY,CAAc,WAAW,CAAC,IAAI,CAAC,CAAC;QACvE,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;;AAxCD,gDAAgD;AAChC,gBAAI,GAAG,iBAAiB,CAAC;AA0C3C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,SAAoB;IAClD,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,cAAe,SAAQ,WAAW;IACtC;;;;OAIG;IACH,aAAa,CAAC,EAAU;QACtB,MAAM,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3C,OAAO,iBAAiB,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACH,mBAAmB,CAAC,EAAU;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM;YAAE,OAAO;QAEpB,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IAED,YAAY,SAAoB;QAC9B,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;CACF","sourcesContent":["/**\r\n * ExampleRepo.ts\r\n *\r\n * This file demonstrates how to implement a repository to manage collections of entities.\r\n * Repositories are responsible for creating, retrieving, and deleting entities.\r\n *\r\n * Key concepts:\r\n * - Repositories extend AppObjectEntityRepo<T> where T is the entity type\r\n * - They provide methods to create and delete entities\r\n * - They manage collections of entities and provide access to them\r\n * - They can use custom entity factories to create specialized entities\r\n *\r\n * Usage pattern:\r\n * 1. Get or create a repository using getById, get, or addIfMissing\r\n * 2. Use the repository to create new entities\r\n * 3. Access entities through the repository's getters\r\n * 4. Delete entities through the repository when they're no longer needed\r\n */\r\n\r\nimport { AppObject, AppObjectEntityRepo, AppObjectRepo } from \"../../AppObject\";\r\nimport { ExampleEntity, makeExampleEntity } from \"./ExampleEntity\";\r\n\r\n/** Type definition for a factory function that creates ExampleEntity instances */\r\nexport type ExampleEntityFactory = (id: string) => ExampleEntity;\r\n\r\n/**\r\n * ExampleRepo manages a collection of ExampleEntity instances.\r\n * Abstract class provides the interface and static helper methods.\r\n */\r\nexport abstract class ExampleRepo extends AppObjectEntityRepo<ExampleEntity> {\r\n  /** Unique type identifier for this component */\r\n  static readonly type = \"ExampleRepoType\";\r\n\r\n  /** Deletes an entity by its AppObject ID */\r\n  abstract deleteExampleEntity(id: string): void;\r\n\r\n  /**\r\n   * Retrieves an ExampleRepo component from an AppObject\r\n   * @param appObj The AppObject to get the component from\r\n   * @returns The ExampleRepo component or undefined if not found\r\n   */\r\n  static get(appObj: AppObject): ExampleRepo | undefined {\r\n    return appObj.getComponent<ExampleRepo>(this.type);\r\n  }\r\n\r\n  /**\r\n   * Retrieves an ExampleRepo by its parent AppObject's ID\r\n   * @param id The ID of the parent AppObject\r\n   * @param appObjects The AppObjectRepo to search in\r\n   * @returns The ExampleRepo component or undefined if not found\r\n   */\r\n  static getById(\r\n    id: string,\r\n    appObjects: AppObjectRepo\r\n  ): ExampleRepo | undefined {\r\n    return appObjects.get(id)?.getComponent<ExampleRepo>(this.type);\r\n  }\r\n\r\n  /**\r\n   * Ensures an ExampleRepo exists on the AppObject, creating one if needed\r\n   * @param appObject The AppObject to check/add the component to\r\n   * @returns The existing or newly created ExampleRepo\r\n   */\r\n  static addIfMissing(appObject: AppObject): ExampleRepo {\r\n    const existing = appObject.getComponent<ExampleRepo>(ExampleRepo.type);\r\n    if (existing) {\r\n      return existing;\r\n    } else {\r\n      return makeExampleRepo(appObject);\r\n    }\r\n  }\r\n}\r\n\r\n/**\r\n * Factory function to create a new ExampleRepo\r\n * @param appObject The AppObject to attach the repo to\r\n * @returns A new ExampleRepo instance\r\n */\r\nexport function makeExampleRepo(appObject: AppObject): ExampleRepo {\r\n  return new ExampleRepoImp(appObject);\r\n}\r\n\r\n/**\r\n * Concrete implementation of ExampleRepo\r\n * This private class handles the actual implementation details\r\n */\r\nclass ExampleRepoImp extends ExampleRepo {\r\n  /**\r\n   * Factory implementation for creating ExampleEntity instances\r\n   * @param id The ID for the entity's AppObject\r\n   * @returns A newly created ExampleEntity\r\n   */\r\n  entityFactory(id: string): ExampleEntity {\r\n    const ao = this.appObjects.getOrCreate(id);\r\n    return makeExampleEntity(ao);\r\n  }\r\n\r\n  /**\r\n   * Deletes an ExampleEntity from the repository by its AppObject ID\r\n   * @param id The ID of the entity's AppObject\r\n   */\r\n  deleteExampleEntity(id: string): void {\r\n    const entity = this.getById(id);\r\n    if (!entity) return;\r\n\r\n    entity.appObject.dispose();\r\n    this.removeById(id);\r\n  }\r\n\r\n  constructor(appObject: AppObject) {\r\n    super(appObject, ExampleRepo.type);\r\n  }\r\n}\r\n"]}
+{"version":3,"file":"ExampleRepo.js","sourceRoot":"","sources":["../../../../src/ExampleFeature/Entities/ExampleRepo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAa,mBAAmB,EAAiB,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAiB,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAKnE;;;GAGG;AACH,MAAM,OAAgB,WAAY,SAAQ,mBAAkC;IAO1E;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,MAAiB;QAC1B,OAAO,MAAM,CAAC,YAAY,CAAc,IAAI,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CACZ,EAAU,EACV,UAAyB;QAEzB,OAAO,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,YAAY,CAAc,IAAI,CAAC,IAAI,CAAC,CAAC;IAClE,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,SAAoB;QACtC,MAAM,QAAQ,GAAG,SAAS,CAAC,YAAY,CAAc,WAAW,CAAC,IAAI,CAAC,CAAC;QACvE,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,QAAQ,CAAC;QAClB,CAAC;aAAM,CAAC;YACN,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;;AAxCD,gDAAgD;AAChC,gBAAI,GAAG,iBAAiB,CAAC;AA0C3C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,SAAoB;IAClD,OAAO,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,MAAM,cAAe,SAAQ,WAAW;IACtC;;;;OAIG;IACH,aAAa,CAAC,SAAoB;QAChC,OAAO,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,mBAAmB,CAAC,EAAU;QAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,MAAM;YAAE,OAAO;QAEpB,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IAED,YAAY,SAAoB;QAC9B,KAAK,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;CACF","sourcesContent":["/**\r\n * ExampleRepo.ts\r\n *\r\n * This file demonstrates how to implement a repository to manage collections of entities.\r\n * Repositories are responsible for creating, retrieving, and deleting entities.\r\n *\r\n * Key concepts:\r\n * - Repositories extend AppObjectEntityRepo<T> where T is the entity type\r\n * - They provide methods to create and delete entities\r\n * - They manage collections of entities and provide access to them\r\n * - They can use custom entity factories to create specialized entities\r\n *\r\n * Usage pattern:\r\n * 1. Get or create a repository using getById, get, or addIfMissing\r\n * 2. Use the repository to create new entities\r\n * 3. Access entities through the repository's getters\r\n * 4. Delete entities through the repository when they're no longer needed\r\n */\r\n\r\nimport { AppObject, AppObjectEntityRepo, AppObjectRepo } from \"../../AppObject\";\r\nimport { ExampleEntity, makeExampleEntity } from \"./ExampleEntity\";\r\n\r\n/** Type definition for a factory function that creates ExampleEntity instances */\r\nexport type ExampleEntityFactory = (appObject: AppObject) => ExampleEntity;\r\n\r\n/**\r\n * ExampleRepo manages a collection of ExampleEntity instances.\r\n * Abstract class provides the interface and static helper methods.\r\n */\r\nexport abstract class ExampleRepo extends AppObjectEntityRepo<ExampleEntity> {\r\n  /** Unique type identifier for this component */\r\n  static readonly type = \"ExampleRepoType\";\r\n\r\n  /** Deletes an entity by its AppObject ID */\r\n  abstract deleteExampleEntity(id: string): void;\r\n\r\n  /**\r\n   * Retrieves an ExampleRepo component from an AppObject\r\n   * @param appObj The AppObject to get the component from\r\n   * @returns The ExampleRepo component or undefined if not found\r\n   */\r\n  static get(appObj: AppObject): ExampleRepo | undefined {\r\n    return appObj.getComponent<ExampleRepo>(this.type);\r\n  }\r\n\r\n  /**\r\n   * Retrieves an ExampleRepo by its parent AppObject's ID\r\n   * @param id The ID of the parent AppObject\r\n   * @param appObjects The AppObjectRepo to search in\r\n   * @returns The ExampleRepo component or undefined if not found\r\n   */\r\n  static getById(\r\n    id: string,\r\n    appObjects: AppObjectRepo\r\n  ): ExampleRepo | undefined {\r\n    return appObjects.get(id)?.getComponent<ExampleRepo>(this.type);\r\n  }\r\n\r\n  /**\r\n   * Ensures an ExampleRepo exists on the AppObject, creating one if needed\r\n   * @param appObject The AppObject to check/add the component to\r\n   * @returns The existing or newly created ExampleRepo\r\n   */\r\n  static addIfMissing(appObject: AppObject): ExampleRepo {\r\n    const existing = appObject.getComponent<ExampleRepo>(ExampleRepo.type);\r\n    if (existing) {\r\n      return existing;\r\n    } else {\r\n      return makeExampleRepo(appObject);\r\n    }\r\n  }\r\n}\r\n\r\n/**\r\n * Factory function to create a new ExampleRepo\r\n * @param appObject The AppObject to attach the repo to\r\n * @returns A new ExampleRepo instance\r\n */\r\nexport function makeExampleRepo(appObject: AppObject): ExampleRepo {\r\n  return new ExampleRepoImp(appObject);\r\n}\r\n\r\n/**\r\n * Concrete implementation of ExampleRepo\r\n * This private class handles the actual implementation details\r\n */\r\nclass ExampleRepoImp extends ExampleRepo {\r\n  /**\r\n   * Factory implementation for creating ExampleEntity instances\r\n   * @param appObject The AppObject for the entity\r\n   * @returns A newly created ExampleEntity\r\n   */\r\n  entityFactory(appObject: AppObject): ExampleEntity {\r\n    return makeExampleEntity(appObject);\r\n  }\r\n\r\n  /**\r\n   * Deletes an ExampleEntity from the repository by its AppObject ID\r\n   * @param id The ID of the entity's AppObject\r\n   */\r\n  deleteExampleEntity(id: string): void {\r\n    const entity = this.getById(id);\r\n    if (!entity) return;\r\n\r\n    entity.appObject.dispose();\r\n    this.removeById(id);\r\n  }\r\n\r\n  constructor(appObject: AppObject) {\r\n    super(appObject, ExampleRepo.type);\r\n  }\r\n}\r\n"]}

package/dist/esm/ExampleFeature/index.js

@@ -0,0 +1,7 @@
+// Controllers
+export * from "./Controllers/setExampleText";
+export * from "./Controllers/toggleExampleBoolean";
+// Adapters
+export * from "./Adapters/examplePmAdapter";
+export * from "./Adapters/exampleSingletonPmAdapter";
+//# sourceMappingURL=index.js.map

package/dist/esm/ExampleFeature/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/ExampleFeature/index.ts"],"names":[],"mappings":"AAAA,cAAc;AACd,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AAEnD,WAAW;AACX,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sCAAsC,CAAC","sourcesContent":["// Controllers\r\nexport * from \"./Controllers/setExampleText\";\r\nexport * from \"./Controllers/toggleExampleBoolean\";\r\n\r\n// Adapters\r\nexport * from \"./Adapters/examplePmAdapter\";\r\nexport * from \"./Adapters/exampleSingletonPmAdapter\";\r\n"]}

package/dist/types/AppObject/AppObjectEntityRepo.d.ts

@@ -1,3 +1,4 @@
+import { AppObject } from "./AppObject";
 import { AppObjectEntity } from "./AppObjectEntity";
 /**
  * A repository for managing collections of AppObjectEntity instances.
@@ -106,7 +107,7 @@ export declare class AppObjectEntityRepo<T extends AppObjectEntity> extends AppO
      * @returns {T} A new entity instance
      * @throws {Error} If not overridden in derived class
      */
-    entityFactory(id: string): T;
+    entityFactory(appObject: AppObject): T;
     /**
      * Removes the entity associated with the specified ID.
      *
@@ -152,5 +153,12 @@ export declare class AppObjectEntityRepo<T extends AppObjectEntity> extends AppO
      * @returns {T[]} An array of all entities
      */
     getAll: () => T[];
+    /**
+     * Gets an entity by ID, or creates it if it doesn't exist.
+     *
+     * @param {string} id - The ID of the entity to get or create
+     * @returns {T} The existing or newly created entity
+     */
+    getOrCreate: (id: string) => T;
 }
 //# sourceMappingURL=AppObjectEntityRepo.d.ts.map

package/dist/types/AppObject/AppObjectEntityRepo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppObjectEntityRepo.d.ts","sourceRoot":"","sources":["../../../src/AppObject/AppObjectEntityRepo.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,mBAAmB,CAC9B,CAAC,SAAS,eAAe,CACzB,SAAQ,eAAe;IACvB,OAAO,CAAC,YAAY,CAAwB;IAE5C,OAAO,CAAC,sBAAsB,CAAyB;IACvD;;;;OAIG;IACH,sBAAsB,GAAI,UAAU,CAAC,WAAW,EAAE,CAAC,KAAK,IAAI,UAE1D;IAEF;;;;OAIG;IACH,yBAAyB,GAAI,UAAU,CAAC,WAAW,EAAE,CAAC,KAAK,IAAI,KAAG,IAAI,CAEpE;IAEF,OAAO,CAAC,wBAAwB,CAAyB;IACzD;;;;OAIG;IACH,wBAAwB,GAAI,UAAU,CAAC,aAAa,EAAE,CAAC,KAAK,IAAI,UAE9D;IAEF;;;;OAIG;IACH,2BAA2B,GACzB,UAAU,CAAC,aAAa,EAAE,CAAC,KAAK,IAAI,KACnC,IAAI,CAEL;IAEF;;;;;OAKG;IACH,GAAG,GAAI,IAAI,MAAM,KAAG,OAAO,CAEzB;IAEF;;;;;;OAMG;IACH,eAAe,GAAI,aAAa,MAAM,KAAG,OAAO,CAE9C;IAEF;;;;;;;OAOG;IACH,GAAG,CAAC,MAAM,EAAE,CAAC;IAYb;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC;IAOtB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,CAAC;IAK5B;;;;;;OAMG;IACH,UAAU,GAAI,IAAI,MAAM,UAQtB;IAEF;;;;;;;OAOG;IACH,kBAAkB,GAAI,IAAI,MAAM,UAE9B;IAEF;;;;;OAKG;IACH,SAAS,aAUP;IAEF;;;;;OAKG;IACH,OAAO,GAAI,IAAI,MAAM,KAAG,CAAC,GAAG,SAAS,CAEnC;IAEF;;;;;;OAMG;IACH,eAAe,GAAI,aAAa,MAAM,KAAG,CAAC,GAAG,SAAS,CAEpD;IAEF;;;;OAIG;IACH,MAAM,QAAO,CAAC,EAAE,CAEd;CACH"}
+{"version":3,"file":"AppObjectEntityRepo.d.ts","sourceRoot":"","sources":["../../../src/AppObject/AppObjectEntityRepo.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,mBAAmB,CAC9B,CAAC,SAAS,eAAe,CACzB,SAAQ,eAAe;IACvB,OAAO,CAAC,YAAY,CAAwB;IAE5C,OAAO,CAAC,sBAAsB,CAAyB;IACvD;;;;OAIG;IACH,sBAAsB,GAAI,UAAU,CAAC,WAAW,EAAE,CAAC,KAAK,IAAI,UAE1D;IAEF;;;;OAIG;IACH,yBAAyB,GAAI,UAAU,CAAC,WAAW,EAAE,CAAC,KAAK,IAAI,KAAG,IAAI,CAEpE;IAEF,OAAO,CAAC,wBAAwB,CAAyB;IACzD;;;;OAIG;IACH,wBAAwB,GAAI,UAAU,CAAC,aAAa,EAAE,CAAC,KAAK,IAAI,UAE9D;IAEF;;;;OAIG;IACH,2BAA2B,GACzB,UAAU,CAAC,aAAa,EAAE,CAAC,KAAK,IAAI,KACnC,IAAI,CAEL;IAEF;;;;;OAKG;IACH,GAAG,GAAI,IAAI,MAAM,KAAG,OAAO,CAEzB;IAEF;;;;;;OAMG;IACH,eAAe,GAAI,aAAa,MAAM,KAAG,OAAO,CAE9C;IAEF;;;;;;;OAOG;IACH,GAAG,CAAC,MAAM,EAAE,CAAC;IAYb;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC;IAQtB;;;;;;;;;OASG;IACH,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,CAAC;IAKtC;;;;;;OAMG;IACH,UAAU,GAAI,IAAI,MAAM,UAQtB;IAEF;;;;;;;OAOG;IACH,kBAAkB,GAAI,IAAI,MAAM,UAE9B;IAEF;;;;;OAKG;IACH,SAAS,aAUP;IAEF;;;;;OAKG;IACH,OAAO,GAAI,IAAI,MAAM,KAAG,CAAC,GAAG,SAAS,CAEnC;IAEF;;;;;;OAMG;IACH,eAAe,GAAI,aAAa,MAAM,KAAG,CAAC,GAAG,SAAS,CAEpD;IAEF;;;;OAIG;IACH,MAAM,QAAO,CAAC,EAAE,CAEd;IAEF;;;;;OAKG;IACH,WAAW,GAAI,IAAI,MAAM,KAAG,CAAC,CAM3B;CACH"}

package/dist/types/ExampleFeature/Entities/ExampleRepo.d.ts

@@ -19,7 +19,7 @@
 import { AppObject, AppObjectEntityRepo, AppObjectRepo } from "../../AppObject";
 import { ExampleEntity } from "./ExampleEntity";
 /** Type definition for a factory function that creates ExampleEntity instances */
-export type ExampleEntityFactory = (id: string) => ExampleEntity;
+export type ExampleEntityFactory = (appObject: AppObject) => ExampleEntity;
 /**
  * ExampleRepo manages a collection of ExampleEntity instances.
  * Abstract class provides the interface and static helper methods.

package/dist/types/ExampleFeature/Entities/ExampleRepo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExampleRepo.d.ts","sourceRoot":"","sources":["../../../../src/ExampleFeature/Entities/ExampleRepo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAqB,MAAM,iBAAiB,CAAC;AAEnE,kFAAkF;AAClF,MAAM,MAAM,oBAAoB,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,aAAa,CAAC;AAEjE;;;GAGG;AACH,8BAAsB,WAAY,SAAQ,mBAAmB,CAAC,aAAa,CAAC;IAC1E,gDAAgD;IAChD,MAAM,CAAC,QAAQ,CAAC,IAAI,qBAAqB;IAEzC,4CAA4C;IAC5C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAE9C;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS;IAItD;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CACZ,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,GACxB,WAAW,GAAG,SAAS;IAI1B;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW;CAQvD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW,CAEjE"}
+{"version":3,"file":"ExampleRepo.d.ts","sourceRoot":"","sources":["../../../../src/ExampleFeature/Entities/ExampleRepo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,aAAa,EAAqB,MAAM,iBAAiB,CAAC;AAEnE,kFAAkF;AAClF,MAAM,MAAM,oBAAoB,GAAG,CAAC,SAAS,EAAE,SAAS,KAAK,aAAa,CAAC;AAE3E;;;GAGG;AACH,8BAAsB,WAAY,SAAQ,mBAAmB,CAAC,aAAa,CAAC;IAC1E,gDAAgD;IAChD,MAAM,CAAC,QAAQ,CAAC,IAAI,qBAAqB;IAEzC,4CAA4C;IAC5C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAE9C;;;;OAIG;IACH,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS;IAItD;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CACZ,EAAE,EAAE,MAAM,EACV,UAAU,EAAE,aAAa,GACxB,WAAW,GAAG,SAAS;IAI1B;;;;OAIG;IACH,MAAM,CAAC,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW;CAQvD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW,CAEjE"}

package/dist/types/ExampleFeature/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./Controllers/setExampleText";
+export * from "./Controllers/toggleExampleBoolean";
+export * from "./Adapters/examplePmAdapter";
+export * from "./Adapters/exampleSingletonPmAdapter";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/ExampleFeature/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ExampleFeature/index.ts"],"names":[],"mappings":"AACA,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AAGnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,sCAAsC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vived/core",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Core Components for VIVED Apps and Hosts",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
@@ -55,6 +55,7 @@
     "uuid": "^11.1.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/**/README.md"
   ]
 }

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
+