bard-legends-framework 1.11.3 → 1.11.4

package/AGENTS.md

@@ -324,10 +324,67 @@ Resolve via constructor injection or `Service.get(X)`:
 
 ## Testing
 
-- Call `BardLegendsHardReset.hardReset()` in `beforeEach` (alongside `actions-lib`'s
-  `ActionLib.hardReset()`) to clear entity/singleton/DI registries between tests.
-- Drive frames with `UpdateCycle.triggerUpdateTick(delta)`; use fake timers for `wait`/animations.
-- Because delivery is synchronous (`actions-lib`), most assertions need no awaiting.
+All testing utilities live on `BardLegendsTestingHelper`.
+
+### Concepts
+
+- **`BardLegendsTestingHelper.hardReset()`** — call it first thing in `beforeEach`. It calls
+  `ActionLib.hardReset()` itself (no separate call needed) and resets all per-test state: DI
+  service instances, entity instances, singleton creation latches, and mock gateway bindings.
+  **Import-time registrations survive the reset** — `@ServiceDecorator`/`@EntityDecorator`
+  metadata and real controller→gateway bindings stay valid, so modules imported once at the top
+  of a test file keep working across tests.
+- **Module-level (gateway) tests** — a module's public surface is its gateway. Test through
+  `Service.get(TheGateway)`: side-effect-import the module's own `*.controller.ts` (this registers
+  the real controller and pulls in its services/entities), and do **not** import any `*.view.ts`
+  (unimported views never activate, so entities render nothing).
+- **`BardLegendsTestingHelper.bindMockControllerToGateway(Gateway, mock)`** — fills a foreign
+  module's gateway with a mock controller, exactly like `@ControllerDecorator` does for a real
+  one. Since the foreign module's controller file is never imported in the test, its gateway
+  prototype is empty; the mock's prototype methods fill it. Colliding with an already registered
+  method throws. All mock bindings are removed on the next `hardReset()`, so bind them in every
+  test's setup, after the reset.
+- Mocks are plain classes matching the foreign controller's shape (`implements
+  Partial<TheController>`): mutable public fields for state, regular class methods reading them.
+  Methods must live on the prototype — arrow-function fields are not bound.
+
+### Sample (module test with a mocked neighbor)
+
+```ts
+import './sample.controller';                       // registers the module under test
+
+describe('SampleController', () => {
+  let otherGatewayMock: OtherGatewayMock;
+  let sampleGateway: InstanceType<typeof SampleGateway>;
+
+  beforeEach(() => {
+    BardLegendsTestingHelper.hardReset();           // always first
+    otherGatewayMock = new OtherGatewayMock();
+    BardLegendsTestingHelper.bindMockControllerToGateway(OtherGateway, otherGatewayMock);
+    sampleGateway = Service.get(SampleGateway);
+  });
+
+  test('does the thing', () => {
+    otherGatewayMock.value = 42;                    // steer the mock through its state fields
+    expect(sampleGateway.doTheThing()).toEqual(42);
+  });
+});
+```
+
+### Do / Don't
+
+```ts
+// DO: hardReset() first in beforeEach, then bind mocks, then Service.get(...) fresh handles.
+// DO: test a module only through its gateway; mock every foreign gateway it reaches.
+// DO: drive frames with UpdateCycle.triggerUpdateTick(delta); use fake timers for wait/animations.
+// DO: assert synchronously — actions-lib delivery is synchronous, most flows need no awaiting.
+
+// DON'T: import another module's *.controller.ts or any *.view.ts in a module test.
+// DON'T: use arrow-function fields as mock methods — only prototype methods are bound.
+// DON'T: hold gateway/service references across tests — re-fetch after each hardReset().
+// DON'T: put state in services — controllers/services persist across hardReset by design;
+//        per-test state belongs in entities, which do reset.
+```
 
 ---
 

package/dist/index.d.mts

@@ -79,11 +79,6 @@ declare abstract class SingletonEntity extends Entity {
  */
 declare function Gateway<TController>(): new () => TController;
 
-declare class BardLegendsHardReset {
-    static readonly onHardReset: actions_lib.Notifier<void>;
-    static hardReset(): void;
-}
-
 type SceneClassType = new (...services: any[]) => Scene<any, any>;
 type SceneInput<T> = T extends Scene<infer I, any> ? I : never;
 declare function SceneDecorator(): (SceneClass: SceneClassType) => any;
@@ -113,6 +108,23 @@ declare class Service {
     static get<T extends Service>(ServiceClass: new (...args: any[]) => T): T;
 }
 
+declare class BardLegendsTestingHelper {
+    static readonly onHardReset: actions_lib.Notifier<void>;
+    static hardReset(): void;
+    /**
+     * Binds a partial mock controller to a gateway, exactly like `@ControllerDecorator` does for a
+     * real controller — its prototype methods are installed onto the gateway prototype. Intended for
+     * tests where the module behind a gateway is not loaded: the real controller never registers
+     * (controllers load via the eager `*.controller.ts` glob, which tests skip), so the mock's
+     * methods fill the gateway.
+     *
+     * The mock's methods must be prototype methods (regular class methods, not arrow-function
+     * fields). Colliding with an already registered method throws. All mock bindings are removed on
+     * `hardReset()`, so bind mocks in each test's setup after the reset.
+     */
+    static bindMockControllerToGateway<TController>(GatewayClass: new () => TController, mock: Partial<TController>): void;
+}
+
 declare class UpdateCycle {
     static readonly beforeSceneUpdateAction: actions_lib.Notifier<{
         time: number;
@@ -1330,4 +1342,4 @@ declare abstract class MovablePhysicsEntity extends PhysicsEntity {
     convertToDTO(): PhysicsBodyDTO;
 }
 
-export { AdvancedSound, type AdvancedSoundOptions, AnimationFlicker, AnimationInterpolationFunctions, type AnimationOptions, Animations, AnimationsCompletionHandlingType, Animator, type AnimatorAnimation, type AssetDefinition, type AudioAppearTransitionType, BORDER_MATERIAL_NAME, BardLegendsHardReset, type BlendMode, type BorderProperties, Camera, CameraGateway, type CircleShapeData, ClosestAvailableSpaceHelper, type CollisionDetails, type CollisionReport, Container, ContainerEventType, ControllerDecorator, type CreateDashedLineOptions, type CreatePhysicsWorldRequestDTO, Cursor, DEFAULT_SHADER_RESOLUTION, DeltaTime, DisplayObjectArray, type DisplayObjectArrayOptions, type DropShadowOptions, Entity, EntityDecorator, type EntityID, type ExplosionHit, FadeInContent, type FadeInContentOptions, FocusingAnimation, Game, Gateway, type GlowEffectOptions, type GlowOptions, type GlowingShapeDefinition, Graphics, type HitTestOptions, ImmovablePhysicsEntity, type InteractingBodyGroups, type KeyboardKeyInfo, KeyboardService, type MapSizeDTO, type MaterialContactDefinition, type MaterialDefinition, MenuEntity, type MenuOptions, MenuUI, MenuView, MouseService, MouseTargetFocusService, MovableEntity, MovablePhysicsEntity, Music, MusicPlayer, type MusicPlayerOptions, type PartialTextOptions, PathFinder, type PathFinderResult, type PhysicsBodyDTO, PhysicsEntity, type PhysicsEntityDefinition, type PhysicsExplosionOptions, PhysicsGateway, PhysicsShapeType, type PhysicsWorldID, Placeholder, type PolygonDefinition, type PolygonShapeData, ROTATIONAL_SPEED_LIMIT, type RayCast, type RayCastHit, ReAnimateHandlingType, type RectangleShapeData, RichText, type RichTextOptions, type RichTextRectangleCut, type RichTextStyles, SOUND_TRANSITION_DURATION, SPEED_LIMIT, Scene, SceneDecorator, ScrollAreaUI, ScrollDirection, type ScrollInContentOptions, ScrollMaskUI, Service, ServiceDecorator, type SetParentOptions, type ShapeDefinition, SingletonEntity, SlideInContent, SlideInContentByIndex, SlideStateAnimation, SlideStateAnimationState, Sound, type SoundDefinition, type SoundID, type SoundIDRegistry, type SoundOptions, Sprite, type SpriteDefinition, type SpriteID, type SpriteIDRegistry, StateAnimation, type StateAnimationOptions, type StateAnimationState, Text, type TextAlignment, type TextOptions, ThroughEmptyStateAnimation, UpdatableContainer, UpdateCycle, VectorFieldPathFinder, VectorSet, View, ViewDecorator, type ViewDecoratorMeta };
+export { AdvancedSound, type AdvancedSoundOptions, AnimationFlicker, AnimationInterpolationFunctions, type AnimationOptions, Animations, AnimationsCompletionHandlingType, Animator, type AnimatorAnimation, type AssetDefinition, type AudioAppearTransitionType, BORDER_MATERIAL_NAME, BardLegendsTestingHelper, type BlendMode, type BorderProperties, Camera, CameraGateway, type CircleShapeData, ClosestAvailableSpaceHelper, type CollisionDetails, type CollisionReport, Container, ContainerEventType, ControllerDecorator, type CreateDashedLineOptions, type CreatePhysicsWorldRequestDTO, Cursor, DEFAULT_SHADER_RESOLUTION, DeltaTime, DisplayObjectArray, type DisplayObjectArrayOptions, type DropShadowOptions, Entity, EntityDecorator, type EntityID, type ExplosionHit, FadeInContent, type FadeInContentOptions, FocusingAnimation, Game, Gateway, type GlowEffectOptions, type GlowOptions, type GlowingShapeDefinition, Graphics, type HitTestOptions, ImmovablePhysicsEntity, type InteractingBodyGroups, type KeyboardKeyInfo, KeyboardService, type MapSizeDTO, type MaterialContactDefinition, type MaterialDefinition, MenuEntity, type MenuOptions, MenuUI, MenuView, MouseService, MouseTargetFocusService, MovableEntity, MovablePhysicsEntity, Music, MusicPlayer, type MusicPlayerOptions, type PartialTextOptions, PathFinder, type PathFinderResult, type PhysicsBodyDTO, PhysicsEntity, type PhysicsEntityDefinition, type PhysicsExplosionOptions, PhysicsGateway, PhysicsShapeType, type PhysicsWorldID, Placeholder, type PolygonDefinition, type PolygonShapeData, ROTATIONAL_SPEED_LIMIT, type RayCast, type RayCastHit, ReAnimateHandlingType, type RectangleShapeData, RichText, type RichTextOptions, type RichTextRectangleCut, type RichTextStyles, SOUND_TRANSITION_DURATION, SPEED_LIMIT, Scene, SceneDecorator, ScrollAreaUI, ScrollDirection, type ScrollInContentOptions, ScrollMaskUI, Service, ServiceDecorator, type SetParentOptions, type ShapeDefinition, SingletonEntity, SlideInContent, SlideInContentByIndex, SlideStateAnimation, SlideStateAnimationState, Sound, type SoundDefinition, type SoundID, type SoundIDRegistry, type SoundOptions, Sprite, type SpriteDefinition, type SpriteID, type SpriteIDRegistry, StateAnimation, type StateAnimationOptions, type StateAnimationState, Text, type TextAlignment, type TextOptions, ThroughEmptyStateAnimation, UpdatableContainer, UpdateCycle, VectorFieldPathFinder, VectorSet, View, ViewDecorator, type ViewDecoratorMeta };

package/dist/index.d.ts

@@ -79,11 +79,6 @@ declare abstract class SingletonEntity extends Entity {
  */
 declare function Gateway<TController>(): new () => TController;
 
-declare class BardLegendsHardReset {
-    static readonly onHardReset: actions_lib.Notifier<void>;
-    static hardReset(): void;
-}
-
 type SceneClassType = new (...services: any[]) => Scene<any, any>;
 type SceneInput<T> = T extends Scene<infer I, any> ? I : never;
 declare function SceneDecorator(): (SceneClass: SceneClassType) => any;
@@ -113,6 +108,23 @@ declare class Service {
     static get<T extends Service>(ServiceClass: new (...args: any[]) => T): T;
 }
 
+declare class BardLegendsTestingHelper {
+    static readonly onHardReset: actions_lib.Notifier<void>;
+    static hardReset(): void;
+    /**
+     * Binds a partial mock controller to a gateway, exactly like `@ControllerDecorator` does for a
+     * real controller — its prototype methods are installed onto the gateway prototype. Intended for
+     * tests where the module behind a gateway is not loaded: the real controller never registers
+     * (controllers load via the eager `*.controller.ts` glob, which tests skip), so the mock's
+     * methods fill the gateway.
+     *
+     * The mock's methods must be prototype methods (regular class methods, not arrow-function
+     * fields). Colliding with an already registered method throws. All mock bindings are removed on
+     * `hardReset()`, so bind mocks in each test's setup after the reset.
+     */
+    static bindMockControllerToGateway<TController>(GatewayClass: new () => TController, mock: Partial<TController>): void;
+}
+
 declare class UpdateCycle {
     static readonly beforeSceneUpdateAction: actions_lib.Notifier<{
         time: number;
@@ -1330,4 +1342,4 @@ declare abstract class MovablePhysicsEntity extends PhysicsEntity {
     convertToDTO(): PhysicsBodyDTO;
 }
 
-export { AdvancedSound, type AdvancedSoundOptions, AnimationFlicker, AnimationInterpolationFunctions, type AnimationOptions, Animations, AnimationsCompletionHandlingType, Animator, type AnimatorAnimation, type AssetDefinition, type AudioAppearTransitionType, BORDER_MATERIAL_NAME, BardLegendsHardReset, type BlendMode, type BorderProperties, Camera, CameraGateway, type CircleShapeData, ClosestAvailableSpaceHelper, type CollisionDetails, type CollisionReport, Container, ContainerEventType, ControllerDecorator, type CreateDashedLineOptions, type CreatePhysicsWorldRequestDTO, Cursor, DEFAULT_SHADER_RESOLUTION, DeltaTime, DisplayObjectArray, type DisplayObjectArrayOptions, type DropShadowOptions, Entity, EntityDecorator, type EntityID, type ExplosionHit, FadeInContent, type FadeInContentOptions, FocusingAnimation, Game, Gateway, type GlowEffectOptions, type GlowOptions, type GlowingShapeDefinition, Graphics, type HitTestOptions, ImmovablePhysicsEntity, type InteractingBodyGroups, type KeyboardKeyInfo, KeyboardService, type MapSizeDTO, type MaterialContactDefinition, type MaterialDefinition, MenuEntity, type MenuOptions, MenuUI, MenuView, MouseService, MouseTargetFocusService, MovableEntity, MovablePhysicsEntity, Music, MusicPlayer, type MusicPlayerOptions, type PartialTextOptions, PathFinder, type PathFinderResult, type PhysicsBodyDTO, PhysicsEntity, type PhysicsEntityDefinition, type PhysicsExplosionOptions, PhysicsGateway, PhysicsShapeType, type PhysicsWorldID, Placeholder, type PolygonDefinition, type PolygonShapeData, ROTATIONAL_SPEED_LIMIT, type RayCast, type RayCastHit, ReAnimateHandlingType, type RectangleShapeData, RichText, type RichTextOptions, type RichTextRectangleCut, type RichTextStyles, SOUND_TRANSITION_DURATION, SPEED_LIMIT, Scene, SceneDecorator, ScrollAreaUI, ScrollDirection, type ScrollInContentOptions, ScrollMaskUI, Service, ServiceDecorator, type SetParentOptions, type ShapeDefinition, SingletonEntity, SlideInContent, SlideInContentByIndex, SlideStateAnimation, SlideStateAnimationState, Sound, type SoundDefinition, type SoundID, type SoundIDRegistry, type SoundOptions, Sprite, type SpriteDefinition, type SpriteID, type SpriteIDRegistry, StateAnimation, type StateAnimationOptions, type StateAnimationState, Text, type TextAlignment, type TextOptions, ThroughEmptyStateAnimation, UpdatableContainer, UpdateCycle, VectorFieldPathFinder, VectorSet, View, ViewDecorator, type ViewDecoratorMeta };
+export { AdvancedSound, type AdvancedSoundOptions, AnimationFlicker, AnimationInterpolationFunctions, type AnimationOptions, Animations, AnimationsCompletionHandlingType, Animator, type AnimatorAnimation, type AssetDefinition, type AudioAppearTransitionType, BORDER_MATERIAL_NAME, BardLegendsTestingHelper, type BlendMode, type BorderProperties, Camera, CameraGateway, type CircleShapeData, ClosestAvailableSpaceHelper, type CollisionDetails, type CollisionReport, Container, ContainerEventType, ControllerDecorator, type CreateDashedLineOptions, type CreatePhysicsWorldRequestDTO, Cursor, DEFAULT_SHADER_RESOLUTION, DeltaTime, DisplayObjectArray, type DisplayObjectArrayOptions, type DropShadowOptions, Entity, EntityDecorator, type EntityID, type ExplosionHit, FadeInContent, type FadeInContentOptions, FocusingAnimation, Game, Gateway, type GlowEffectOptions, type GlowOptions, type GlowingShapeDefinition, Graphics, type HitTestOptions, ImmovablePhysicsEntity, type InteractingBodyGroups, type KeyboardKeyInfo, KeyboardService, type MapSizeDTO, type MaterialContactDefinition, type MaterialDefinition, MenuEntity, type MenuOptions, MenuUI, MenuView, MouseService, MouseTargetFocusService, MovableEntity, MovablePhysicsEntity, Music, MusicPlayer, type MusicPlayerOptions, type PartialTextOptions, PathFinder, type PathFinderResult, type PhysicsBodyDTO, PhysicsEntity, type PhysicsEntityDefinition, type PhysicsExplosionOptions, PhysicsGateway, PhysicsShapeType, type PhysicsWorldID, Placeholder, type PolygonDefinition, type PolygonShapeData, ROTATIONAL_SPEED_LIMIT, type RayCast, type RayCastHit, ReAnimateHandlingType, type RectangleShapeData, RichText, type RichTextOptions, type RichTextRectangleCut, type RichTextStyles, SOUND_TRANSITION_DURATION, SPEED_LIMIT, Scene, SceneDecorator, ScrollAreaUI, ScrollDirection, type ScrollInContentOptions, ScrollMaskUI, Service, ServiceDecorator, type SetParentOptions, type ShapeDefinition, SingletonEntity, SlideInContent, SlideInContentByIndex, SlideStateAnimation, SlideStateAnimationState, Sound, type SoundDefinition, type SoundID, type SoundIDRegistry, type SoundOptions, Sprite, type SpriteDefinition, type SpriteID, type SpriteIDRegistry, StateAnimation, type StateAnimationOptions, type StateAnimationState, Text, type TextAlignment, type TextOptions, ThroughEmptyStateAnimation, UpdatableContainer, UpdateCycle, VectorFieldPathFinder, VectorSet, View, ViewDecorator, type ViewDecoratorMeta };