@caperjs/core 0.2.4 → 0.4.0

package/src/display/Camera.test.ts

@@ -0,0 +1,40 @@
+import { Container as PixiContainer } from 'pixi.js';
+import { describe, expect, it, vi } from 'vitest';
+
+// Camera transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+
+const mocks = vi.hoisted(() => ({
+  app: {
+    size: { width: 800, height: 400 },
+  },
+}));
+
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => mocks.app },
+}));
+
+import { Camera } from './Camera';
+
+describe('Camera targetScale', () => {
+  it('reflects the target scale, not the target pivot', () => {
+    const camera = new Camera({ container: new PixiContainer(), viewportWidth: 200, viewportHeight: 100 });
+
+    camera.zoom(3);
+
+    expect(camera.targetScale.x).toBe(3);
+    expect(camera.targetScale.y).toBe(3);
+    expect(camera.targetScale).not.toBe(camera.targetPivot);
+  });
+});
+
+describe('Camera viewportHeight default', () => {
+  it('falls back to app.size.height, not app.size.width', () => {
+    const camera = new Camera({ container: new PixiContainer() });
+
+    expect(camera.viewportHeight).toBe(mocks.app.size.height);
+  });
+});

package/src/display/Camera.ts

@@ -85,7 +85,7 @@ export class Camera extends Container implements ICamera {
         this.minY = config.minY;
       }
       this.viewportWidth = config.viewportWidth ?? this.app.size.width;
-      this.viewportHeight = config.viewportHeight ?? this.app.size.width;
+      this.viewportHeight = config.viewportHeight ?? this.app.size.height;
       this.worldWidth = config.worldWidth ?? this.viewportWidth;
       this.worldHeight = config.worldHeight ?? this.viewportHeight;
       this.maxX = config.maxX ?? this.worldWidth - this.viewportWidth;
@@ -125,7 +125,7 @@ export class Camera extends Container implements ICamera {
   protected _targetScale: Point = new Point(1, 1);
 
   get targetScale(): Point {
-    return this._targetPivot;
+    return this._targetScale;
   }
 
   private _lerp: number = 0;
@@ -135,7 +135,7 @@ export class Camera extends Container implements ICamera {
   }
 
   set lerp(value: number) {
-    // if the value is less than 0 or greater than 1, clamp it to the range [0, 1], and log an error
+    // if the value is less than 0 or greater than 1, throw an error
     if (value < 0 || value > 1) {
       throw new Error('Camera lerp value must be in the range [0, 1]');
     }

package/src/display/Entity.ts

@@ -9,8 +9,8 @@ import { Container } from './Container';
  *
  * **Lifecycle** (inherited from Container):
  *
- *   1. `constructor(props)` — props are stashed on `this.props` before
- *      Container's constructor runs. Don't reference `this.app` yet.
+ *   1. `constructor(props)` — Container's constructor runs first, then props
+ *      are stashed on `this.props`. Don't reference `this.app` yet.
  *   2. **addChild** — the factory auto-adds the instance to the calling
  *      Container; Pixi emits an `added` event.
  *   3. `added()` — override this to build the display tree using

package/src/display/SceneTransition.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+// Registers the factory method table `Factory()` (part of Container's mixin
+// chain) reads from — must be imported before any display/ui class is
+// constructed. See importOrder.containerFirst.test.ts.
+import '../mixins/factory/const';
+import { Signal } from '../signals';
+import { SceneTransition } from './SceneTransition';
+
+describe('SceneTransition asset signal wiring', () => {
+  let app: {
+    assets: {
+      onLoadStart: Signal<() => void>;
+      onLoadProgress: Signal<(progress: number) => void>;
+      onLoadComplete: Signal<() => void>;
+    };
+  };
+  let originalAppDescriptor: PropertyDescriptor | undefined;
+
+  beforeEach(() => {
+    app = {
+      assets: {
+        onLoadStart: new Signal<() => void>(),
+        onLoadProgress: new Signal<(progress: number) => void>(),
+        onLoadComplete: new Signal<() => void>(),
+      },
+    };
+    // Container.app is a getter; override it on the prototype so the
+    // constructor picks up the fake app before the instance even exists.
+    originalAppDescriptor = Object.getOwnPropertyDescriptor(SceneTransition.prototype, 'app');
+    Object.defineProperty(SceneTransition.prototype, 'app', { get: () => app, configurable: true });
+  });
+
+  afterEach(() => {
+    if (originalAppDescriptor) {
+      Object.defineProperty(SceneTransition.prototype, 'app', originalAppDescriptor);
+    } else {
+      delete (SceneTransition.prototype as any).app;
+    }
+  });
+
+  it('routes progress ticks to handleLoadProgress and completion to handleLoadComplete', () => {
+    const progressSpy = vi.spyOn(SceneTransition.prototype as any, 'handleLoadProgress');
+    const completeSpy = vi.spyOn(SceneTransition.prototype as any, 'handleLoadComplete');
+
+    const transition = new SceneTransition();
+    void transition;
+
+    app.assets.onLoadProgress.emit(0.5);
+
+    expect(progressSpy).toHaveBeenCalledTimes(1);
+    expect(completeSpy).not.toHaveBeenCalled();
+
+    app.assets.onLoadComplete.emit();
+
+    expect(completeSpy).toHaveBeenCalledTimes(1);
+    expect(progressSpy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/display/SceneTransition.ts

@@ -46,7 +46,7 @@ export class SceneTransition extends Container {
     this.addSignalConnection(
       this.app.assets.onLoadStart.connect(this.handleLoadStart),
       this.app.assets.onLoadProgress.connect(this.handleLoadProgress),
-      this.app.assets.onLoadProgress.connect(this.handleLoadComplete),
+      this.app.assets.onLoadComplete.connect(this.handleLoadComplete),
     );
   }
 

package/src/display/SpineAnimation.ts

@@ -20,8 +20,8 @@ export interface ISpineAnimation<ANames extends string = string> extends Instanc
   readonly onAnimationEvent: Signal<(entry: TrackEntry, event: Event) => void>;
   readonly onPaused: Signal<(entry: TrackEntry | null) => void>;
   readonly onResumed: Signal<(entry: TrackEntry | null) => void>;
-  setAnimation(name: ANames, loop?: boolean, tracklndex?: number): void;
-  getCurrentAnimation(tracklndex?: number): ANames;
+  setAnimation(name: ANames, loop?: boolean, trackIndex?: number): void;
+  getCurrentAnimation(trackIndex?: number): ANames;
   pause(): void;
   resume(): void;
   togglePause(): void;
@@ -113,8 +113,8 @@ export class SpineAnimation<ANames extends string = string> extends _SpineAnimat
     return (this.spine.state.getCurrent(trackIndex)?.animation?.name as ANames) || ('' as ANames);
   }
 
-  setAnimation(name: ANames, loop = false, tracklndex: number = 0) {
-    this.spine.state.setAnimation(tracklndex, name, loop);
+  setAnimation(name: ANames, loop = false, trackIndex: number = 0) {
+    this.spine.state.setAnimation(trackIndex, name, loop);
   }
 
   pause() {

package/src/mixins/factory/methods.ts

@@ -12,7 +12,6 @@ export function createFactoryMethods<T extends typeof defaultFactoryMethods = ty
       const obj = methods[key](...args);
       if (addToStage) {
         instance.addChild(obj);
-        // instance.addChild(obj);
       }
       return obj;
     };

package/src/plugins/AssetsPlugin.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// AssetsPlugin extends Plugin, which transitively imports Application → Pixi
+// display graph. Stub it the same way Plugin.test.ts does.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({ canvas: { dispatchEvent: vi.fn() } }) },
+}));
+
+vi.mock('pixi.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('pixi.js')>();
+  return {
+    ...actual,
+    Assets: {
+      load: vi.fn(async () => undefined),
+      loadBundle: vi.fn(async () => undefined),
+      setPreferences: vi.fn(),
+      backgroundLoad: vi.fn(async () => undefined),
+      backgroundLoadBundle: vi.fn(async () => undefined),
+      unload: vi.fn(async () => undefined),
+      unloadBundle: vi.fn(async () => undefined),
+    },
+  };
+});
+
+import { Assets } from 'pixi.js';
+import { AssetsPlugin } from './AssetsPlugin';
+
+const loadBundle = vi.mocked(Assets.loadBundle);
+
+describe('AssetsPlugin', () => {
+  it('loadRequired only requests bundles that are not already loaded', async () => {
+    const plugin = new AssetsPlugin();
+
+    // Mark bundle 'a' as already loaded.
+    await plugin.loadBundles('a');
+    loadBundle.mockClear();
+
+    plugin.initialize({ preload: { bundles: ['a', 'b'] } });
+    await plugin.loadRequired();
+
+    expect(loadBundle).toHaveBeenCalledTimes(1);
+    expect(loadBundle).toHaveBeenCalledWith(['b'], expect.anything());
+  });
+});

package/src/plugins/AssetsPlugin.ts

@@ -187,7 +187,9 @@ export class AssetsPlugin extends Plugin<AssetLoadingOptions> implements IAssets
           bundles = [bundles];
         }
         bundles = bundles.filter((bundle) => !this._isBundleLoaded(bundle));
-        await Assets.loadBundle(this._required.bundles, this._handleLoadProgress);
+        if (bundles.length) {
+          await Assets.loadBundle(bundles, this._handleLoadProgress);
+        }
       }
     }
     this._handleLoadComplete();

package/src/plugins/DataAdapter.test.ts

@@ -0,0 +1,32 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+// DataAdapter extends Plugin, which transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { vi } from 'vitest';
+import { DataAdapter } from './DataAdapter';
+
+describe('DataAdapter', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  it('clear() with no key removes only this namespace\'s keys, leaving unrelated keys intact', () => {
+    localStorage.setItem('myns-foo', '"bar"');
+    localStorage.setItem('other-bar', '"baz"');
+
+    const adapter = new DataAdapter();
+    adapter.initialize({ namespace: 'myns', initial: { foo: 'bar' } });
+
+    adapter.clear();
+
+    expect(localStorage.getItem('myns-foo')).toBeNull();
+    expect(localStorage.getItem('other-bar')).toBe('"baz"');
+  });
+});

package/src/plugins/DataAdapter.ts

@@ -103,6 +103,7 @@ export class DataAdapter extends Plugin<Partial<IDataAdapterOptions>> implements
 
   destroy() {
     this.data = {} as DataAdapterType;
+    super.destroy();
   }
 
   public initialize(options?: Partial<IDataAdapterOptions>): void {
@@ -205,7 +206,10 @@ export class DataAdapter extends Plugin<Partial<IDataAdapterOptions>> implements
   clear<K extends keyof DataAdapterType>(key?: K): void {
     if (key === undefined) {
       this.data = {} as DataAdapterType;
-      localStorage.clear();
+      const prefix = `${this.namespace}-`;
+      for (const storageKey of Object.keys(localStorage).filter((k) => k.startsWith(prefix))) {
+        localStorage.removeItem(storageKey);
+      }
       this.onDataChange.emit({ key, clear: true });
     } else {
       delete this.data[key];

package/src/plugins/FullScreenPlugin.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// FullScreenPlugin transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({}), containerElement: null },
+}));
+
+import { FullScreenPlugin } from './FullScreenPlugin';
+
+describe('FullScreenPlugin fullscreenchange handling', () => {
+  let plugin: FullScreenPlugin;
+
+  beforeEach(() => {
+    plugin = new FullScreenPlugin();
+    plugin.initialize();
+  });
+
+  afterEach(() => {
+    plugin.destroy();
+    delete (document as any).webkitFullscreenElement;
+  });
+
+  it('clears the cached state when the browser leaves fullscreen', () => {
+    (plugin as any)._isFullScreen = true;
+    const spy = vi.fn();
+    plugin.onFullScreenChange.connect(spy);
+
+    document.dispatchEvent(new Event('fullscreenchange'));
+
+    expect(plugin.isFullScreen).toBe(false);
+    expect(spy).toHaveBeenCalledWith(false);
+  });
+
+  it('sets the cached state from vendor-prefixed fullscreen elements', () => {
+    (document as any).webkitFullscreenElement = document.body;
+    const spy = vi.fn();
+    plugin.onFullScreenChange.connect(spy);
+
+    document.dispatchEvent(new Event('webkitfullscreenchange'));
+
+    expect(plugin.isFullScreen).toBe(true);
+    expect(spy).toHaveBeenCalledWith(true);
+  });
+});

package/src/plugins/FullScreenPlugin.ts

@@ -143,23 +143,11 @@ export class FullScreenPlugin extends Plugin implements IFullScreenPlugin {
    * ```
    */
   public initialize(): void {
-    document.addEventListener('fullscreenchange', this._onFullScreenChange);
-    document.addEventListener('webkitfullscreenchange', this._onFullScreenChange);
-    document.addEventListener('mozfullscreenchange', this._onFullScreenChange);
-    document.addEventListener('msfullscreenchange', this._onFullScreenChange);
-    document.addEventListener('fullscreenchange', this._onFullScreenChange);
-  }
-
-  /**
-   * Cleans up the plugin by removing all event listeners.
-   * Called automatically when the plugin is destroyed.
-   */
-  public destroy() {
-    document.removeEventListener('fullscreenchange', this._onFullScreenChange);
-    document.removeEventListener('webkitfullscreenchange', this._onFullScreenChange);
-    document.removeEventListener('mozfullscreenchange', this._onFullScreenChange);
-    document.removeEventListener('msfullscreenchange', this._onFullScreenChange);
-    document.removeEventListener('fullscreenchange', this._onFullScreenChange);
+    this.listen(document, 'fullscreenchange', this._onFullScreenChange);
+    this.listen(document, 'webkitfullscreenchange', this._onFullScreenChange);
+    this.listen(document, 'mozfullscreenchange', this._onFullScreenChange);
+    this.listen(document, 'msfullscreenchange', this._onFullScreenChange);
+    this.listen(document, 'fullscreenchange', this._onFullScreenChange);
   }
 
   /**
@@ -354,6 +342,9 @@ export class FullScreenPlugin extends Plugin implements IFullScreenPlugin {
    * @private
    */
   private _onFullScreenChange(): void {
-    this.onFullScreenChange.emit(document.fullscreenElement !== null);
+    // the user can leave fullscreen without us (Esc / browser chrome), so re-read
+    // the real state instead of trusting the cached flag
+    this._isFullScreen = this.isFullscreen;
+    this.onFullScreenChange.emit(this._isFullScreen);
   }
 }

package/src/plugins/GSAPPlugin.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// GSAPPlugin.ts extends Plugin.ts, which transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { GSAPPlugin } from './GSAPPlugin';
+
+class TestGSAPPlugin extends GSAPPlugin {
+  public createGlobalContextPublic(): void {
+    this.createGlobalContext();
+  }
+}
+
+describe('GSAPPlugin', () => {
+  it('clearGlobal() does not throw and empties the global context', () => {
+    const plugin = new TestGSAPPlugin();
+    plugin.createGlobalContextPublic();
+
+    plugin.addAnimation({} as never);
+    expect(plugin.getContext('__caper_global')?.size).toBe(1);
+
+    expect(() => plugin.clearGlobal()).not.toThrow();
+    expect(plugin.getContext('__caper_global')?.size).toBe(0);
+  });
+});

package/src/plugins/GSAPPlugin.ts

@@ -348,9 +348,6 @@ export class GSAPPlugin extends Plugin implements IGSAPPlugin {
     (detail: { animation: gsap.core.Tween | gsap.core.Timeline; contextId: string }) => void
   >();
 
-  /** Global animation context reference for quick access */
-  private _globalContext: AnimationContext;
-
   /** Map of all custom animation contexts by their string identifiers */
   private _animationContexts: Map<string, AnimationContext> = new Map();
 
@@ -804,7 +801,7 @@ export class GSAPPlugin extends Plugin implements IGSAPPlugin {
     if (kill) {
       this.killGlobal();
     }
-    this._globalContext.clear();
+    this._animationContexts.get(GSAPPlugin.GLOBAL_CONTEXT_ID)?.clear();
 
     this.onClearGlobal.emit(kill);
   }

package/src/plugins/KeyboardPlugin.ts

@@ -61,15 +61,8 @@ export class KeyboardPlugin extends Plugin implements IKeyboardPlugin {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   public initialize(_options: any, _app: IApplication): void {
     // track which keys are down
-    document.addEventListener('keydown', this._handleKeyDown);
-    document.addEventListener('keyup', this._handleKeyUp);
-  }
-
-  public destroy() {
-    document.removeEventListener('keydown', this._handleKeyDown);
-    document.removeEventListener('keyup', this._handleKeyUp);
-    document.removeEventListener('keydown', this._handleEvent);
-    document.removeEventListener('keyup', this._handleEvent);
+    this.listen(document, 'keydown', this._handleKeyDown as EventListener);
+    this.listen(document, 'keyup', this._handleKeyUp as EventListener);
   }
 
   public onKeyDown(key?: KeyboardKey): KeySignal {
@@ -145,7 +138,7 @@ export class KeyboardPlugin extends Plugin implements IKeyboardPlugin {
   }
 
   private _listen(eventType: KeyboardEventType): void {
-    document.addEventListener(eventType, this._handleEvent);
+    this.listen(document, eventType, this._handleEvent as EventListener);
   }
 
   private _handleEvent(event: KeyboardEvent): void {

package/src/plugins/LookupPlugin.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// LookupPlugin -> Plugin.ts transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {} as Record<string, unknown>,
+  coreSignalRegistry: {} as Record<string, unknown>,
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { coreFunctionRegistry } from '../core';
+import { Container } from '../display/Container';
+import { LookupPlugin } from './LookupPlugin';
+
+describe('LookupPlugin', () => {
+  it('registers getChildAtPath (and its siblings) in the core function registry', () => {
+    const plugin = new LookupPlugin();
+    plugin.registerCoreFunctions();
+
+    expect((coreFunctionRegistry as Record<string, unknown>).getChildAtPath).toBe(plugin.getChildAtPath);
+  });
+
+  it('disconnects its global container subscriptions on destroy', async () => {
+    const plugin = new LookupPlugin();
+    const added = vi.spyOn(plugin as any, 'onChildAdded');
+    const removed = vi.spyOn(plugin as any, 'onChildRemoved');
+    await plugin.initialize();
+
+    const child = { label: 'Thing', children: [] } as any;
+    Container.onGlobalChildAdded.emit(child);
+    Container.onGlobalChildRemoved.emit(child);
+    expect(added).toHaveBeenCalledTimes(1);
+    expect(removed).toHaveBeenCalledTimes(1);
+
+    plugin.destroy();
+    Container.onGlobalChildAdded.emit(child);
+    Container.onGlobalChildRemoved.emit(child);
+    expect(added).toHaveBeenCalledTimes(1);
+    expect(removed).toHaveBeenCalledTimes(1);
+  });
+});

package/src/plugins/LookupPlugin.ts

@@ -97,7 +97,7 @@ export class LookupPlugin extends Plugin implements ILookupPlugin {
   /**
    * Core function names exposed by this plugin for framework integration.
    */
-  get coreFunctions(): string[] {
+  protected getCoreFunctions(): string[] {
     return ['getChildAtPath', 'getPathForChild', 'getChildrenAtPaths', 'getPathsForChildren', 'getAllPaths'];
   }
 
@@ -106,8 +106,20 @@ export class LookupPlugin extends Plugin implements ILookupPlugin {
    * Sets up automatic tracking of container hierarchy changes.
    */
   public async initialize() {
-    Container.onGlobalChildAdded.connect(this.onChildAdded);
-    Container.onGlobalChildRemoved.connect(this.onChildRemoved);
+    this.addSignalConnection(
+      Container.onGlobalChildAdded.connect(this.onChildAdded),
+      Container.onGlobalChildRemoved.connect(this.onChildRemoved),
+    );
+  }
+
+  /**
+   * Disconnects the global container subscriptions and drops the lookup maps,
+   * so a destroyed plugin stops tracking (and holding on to) containers.
+   */
+  public destroy(): void {
+    this.pathToContainer.clear();
+    this.containerToPath.clear();
+    super.destroy();
   }
 
   /**