@caperjs/core 0.2.4 → 0.4.0

package/src/plugins/WebEventsPlugin.ts

@@ -44,24 +44,17 @@ export class WebEventsPlugin extends Plugin implements IWebEventsPlugin {
   }
 
   public initialize(): void {
-    document.addEventListener('visibilitychange', this._onVisibilityChanged, false);
-    window.addEventListener('pagehide', this._onPageHide, false);
-    window.addEventListener('pageshow', this._onPageShow, false);
-    window.addEventListener('resize', this._onResize);
-    document.addEventListener('fullscreenchange', this._onResize);
-    window.addEventListener('orientationchange', this._onOrientationChanged);
+    this.listen(document, 'visibilitychange', this._onVisibilityChanged, false);
+    this.listen(window, 'pagehide', this._onPageHide, false);
+    this.listen(window, 'pageshow', this._onPageShow, false);
+    this.listen(window, 'resize', this._onResize);
+    this.listen(document, 'fullscreenchange', this._onResize);
+    this.listen(window, 'orientationchange', this._onOrientationChanged);
     // installed PWAs (standalone/fullscreen display modes) can miss or mistime window.resize
     // during launch transitions; visualViewport reports the settled size
-    window.visualViewport?.addEventListener('resize', this._onVisualViewportResize);
-  }
-
-  public destroy() {
-    document.removeEventListener('visibilitychange', this._onVisibilityChanged, false);
-    window.removeEventListener('resize', this._onResize);
-    document.removeEventListener('fullscreenchange', this._onResize);
-    window.removeEventListener('pagehide', this._onPageHide, false);
-    window.removeEventListener('pageshow', this._onPageShow, false);
-    window.visualViewport?.removeEventListener('resize', this._onVisualViewportResize);
+    if (window.visualViewport) {
+      this.listen(window.visualViewport, 'resize', this._onVisualViewportResize);
+    }
   }
 
   protected getCoreSignals(): string[] {

package/src/plugins/actions/ActionsPlugin.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// ActionsPlugin -> Plugin.ts transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import type { IApplication } from '../../core';
+import { ActionsPlugin } from './ActionsPlugin';
+
+function makePlugin(actions: Record<string, { context: string | string[] }>) {
+  const plugin = new ActionsPlugin();
+  plugin.initialize({}, { config: { actions } } as unknown as IApplication);
+  return plugin;
+}
+
+describe('ActionsPlugin', () => {
+  it('does not dispatch an action whose context merely contains the current context', () => {
+    const plugin = makePlugin({ foo: { context: 'popup' } });
+    const handler = vi.fn();
+    plugin.getAction('foo').connect(handler);
+
+    plugin.setActionContext('pop');
+    plugin.sendAction('foo');
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('dispatches an action when the string context matches exactly', () => {
+    const plugin = makePlugin({ foo: { context: 'popup' } });
+    const handler = vi.fn();
+    plugin.getAction('foo').connect(handler);
+
+    plugin.setActionContext('popup');
+    plugin.sendAction('foo');
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('dispatches an action with a wildcard context in any context', () => {
+    const plugin = makePlugin({ foo: { context: '*' } });
+    const handler = vi.fn();
+    plugin.getAction('foo').connect(handler);
+
+    plugin.setActionContext('anything');
+    plugin.sendAction('foo');
+
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('dispatches an action when an array context includes the current context', () => {
+    const plugin = makePlugin({ foo: { context: ['menu', 'popup'] } });
+    const handler = vi.fn();
+    plugin.getAction('foo').connect(handler);
+
+    plugin.setActionContext('menu');
+    plugin.sendAction('foo');
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    plugin.setActionContext('men');
+    plugin.sendAction('foo');
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+});

package/src/plugins/actions/ActionsPlugin.ts

@@ -80,11 +80,11 @@ export class ActionsPlugin extends Plugin<IActionsPluginOptions> implements IAct
 
     // check if action is allowed for current context
     // send action if allowed
-    if (
-      this._actions[actionId]?.context === '*' ||
-      this._actions[actionId]?.context === this.context ||
-      this._actions[actionId]?.context?.includes(this.context)
-    ) {
+    const actionContext = this._actions[actionId]!.context;
+    const allowed = Array.isArray(actionContext)
+      ? actionContext.includes(this.context)
+      : actionContext === this.context || actionContext === '*';
+    if (allowed) {
       const detail: ActionDetail<TActionData> = { id: actionId, context: this.context, data };
       this.getAction<TActionData>(actionId).emit(detail);
       // notify automation / observers of the dispatched (allowed) action

package/src/plugins/audio/AudioChannel.test.ts

@@ -80,6 +80,25 @@ describe('AudioChannel', () => {
     expect(media.volume).toBeCloseTo(0.8 * 0.5 * 1);
   });
 
+  it('destroy() stops/destroys every tracked instance and clears them', () => {
+    const manager = createManager();
+    const channel = new AudioChannel('sfx', manager);
+
+    const instance1 = channel.add('boom', new AudioInstance('boom', channel, manager));
+    const media1 = createMedia();
+    instance1.media = media1 as never;
+
+    const instance2 = channel.add('splat', new AudioInstance('splat', channel, manager));
+    const media2 = createMedia();
+    instance2.media = media2 as never;
+
+    channel.destroy();
+
+    expect(media1.stop).toHaveBeenCalled();
+    expect(media2.stop).toHaveBeenCalled();
+    expect(channel.instances).toEqual([]);
+  });
+
   it('remove(id) stops all instances tracked under that alias', () => {
     const manager = createManager();
     const channel = new AudioChannel('sfx', manager);

package/src/plugins/audio/AudioChannel.ts

@@ -160,5 +160,12 @@ export class AudioChannel<C extends ChannelName = ChannelName> {
     this.volume = this._volume;
   }
 
-  destroy() {}
+  destroy() {
+    this._sounds.forEach((bucket) => {
+      // destroy() -> stop() -> emits onEnd, whose handler may call
+      // removeInstance() and mutate `bucket` mid-iteration. Iterate a copy.
+      [...bucket].forEach((instance) => instance.destroy());
+    });
+    this._sounds.clear();
+  }
 }

package/src/plugins/audio/AudioManagerPlugin.test.ts

@@ -0,0 +1,41 @@
+import { sound } from '@pixi/sound';
+import { describe, expect, it, vi } from 'vitest';
+
+// AudioManagerPlugin -> Plugin.ts transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { AudioManagerPlugin } from './AudioManagerPlugin';
+
+describe('AudioManagerPlugin', () => {
+  it('destroy() disconnects onChannelMuted along with the other signals', () => {
+    const manager = new AudioManagerPlugin();
+    const handler = vi.fn();
+    manager.onChannelMuted.connect(handler);
+
+    manager.destroy();
+
+    manager.onChannelMuted.emit({ channel: {} as never, muted: true });
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('caches a resolved sound id under the original id so probing is not repeated', () => {
+    const exists = vi.spyOn(sound, 'exists').mockImplementation((id: string) => id === 'foo.mp3');
+    const manager = new AudioManagerPlugin();
+
+    const resolved = (manager as any)._verifySoundId('foo');
+    expect(resolved).toBe('foo.mp3');
+    expect(((manager as any)._idMap as Map<string, string>).get('foo')).toBe('foo.mp3');
+
+    exists.mockClear();
+    expect((manager as any)._verifySoundId('foo')).toBe('foo.mp3');
+    expect(exists).not.toHaveBeenCalled();
+
+    exists.mockRestore();
+  });
+});

package/src/plugins/audio/AudioManagerPlugin.ts

@@ -272,6 +272,7 @@ export class AudioManagerPlugin<C extends ChannelName = ChannelName> extends Plu
     this.onMuted.disconnectAll();
     this.onMasterVolumeChanged.disconnectAll();
     this.onChannelVolumeChanged.disconnectAll();
+    this.onChannelMuted.disconnectAll();
 
     super.destroy();
   }
@@ -701,7 +702,7 @@ export class AudioManagerPlugin<C extends ChannelName = ChannelName> extends Plu
     }
     for (let id of soundId) {
       if (this._idMap.has(id)) {
-        soundId = this._idMap.get(id) as string;
+        id = this._idMap.get(id) as string;
       }
       const channel = this._channels.get(channelName);
       if (channel) {
@@ -795,7 +796,7 @@ export class AudioManagerPlugin<C extends ChannelName = ChannelName> extends Plu
         }
       }
     }
-    this._idMap.set(soundId, soundId);
+    this._idMap.set(originalSoundId, soundId);
     return soundId;
   }
 

package/src/plugins/audio/VoiceOverPlugin.ts

@@ -1,3 +1,4 @@
+import { gsap } from 'gsap';
 import { Signal } from '../../signals';
 import { Logger } from '../../utils';
 import type { IPlugin } from '../Plugin';

package/src/plugins/breakpoints/BreakpointPlugin.ts

@@ -150,7 +150,6 @@ export class BreakpointPlugin extends Plugin<BreakpointPluginOptions> implements
   }
 
   public destroy(): void {
-    this._pointerQuery?.removeEventListener('change', this._onPointerChange);
     this._pointerQuery = null;
     for (const signal of this._enter.values()) signal.disconnectAll();
     for (const signal of this._leave.values()) signal.disconnectAll();
@@ -259,7 +258,7 @@ export class BreakpointPlugin extends Plugin<BreakpointPluginOptions> implements
     }
     this._pointerQuery = window.matchMedia('(pointer: coarse)');
     this._pointer = this._pointerQuery.matches ? 'coarse' : 'fine';
-    this._pointerQuery.addEventListener('change', this._onPointerChange);
+    this.listen(this._pointerQuery, 'change', this._onPointerChange as EventListener);
   }
 
   private _signal(store: Map<string, Signal<() => void>>, name: string): Signal<() => void> {

package/src/plugins/captions/CaptionsPlugin.test.ts

@@ -0,0 +1,40 @@
+import { Assets } from 'pixi.js';
+import { describe, expect, it, vi } from 'vitest';
+
+// CaptionsPlugin -> Plugin.ts transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { CaptionsPlugin } from './CaptionsPlugin';
+
+describe('CaptionsPlugin', () => {
+  it('loadLocale returns early when the locale is already loaded', async () => {
+    const load = vi.spyOn(Assets, 'load').mockResolvedValue({});
+    const plugin = new CaptionsPlugin();
+    (plugin as any)._locale = 'en';
+    (plugin as any)._dicts = { en: { hello: 'hello' } };
+    (plugin as any)._options = { files: [{ id: 'en', json: 'en.json' }] };
+
+    await plugin.loadLocale('en');
+
+    expect(load).not.toHaveBeenCalled();
+    load.mockRestore();
+  });
+
+  it('loadLocale still loads the current locale when its dictionary is missing', async () => {
+    const load = vi.spyOn(Assets, 'load').mockResolvedValue({ a: 1 });
+    const plugin = new CaptionsPlugin();
+    (plugin as any)._locale = 'en';
+    (plugin as any)._options = { files: [{ id: 'en', json: 'en.json' }] };
+
+    await plugin.loadLocale('en');
+
+    expect(load).toHaveBeenCalledWith('en.json');
+    load.mockRestore();
+  });
+});

package/src/plugins/captions/CaptionsPlugin.ts

@@ -298,7 +298,7 @@ export class CaptionsPlugin extends Plugin<CaptionsOptions> implements ICaptions
     const RendererClass: CaptionRendererConstructor = this.options.renderer;
     this.renderer = this.view.addChild(new RendererClass(this)) as CaptionsRenderer;
 
-    this.app.ticker.add(this.update);
+    this.addTickerCallback(this.update);
     this.app.scenes.onSceneChangeStart.connect(this.stopAllCaptions);
   }
 
@@ -327,7 +327,7 @@ export class CaptionsPlugin extends Plugin<CaptionsOptions> implements ICaptions
    * @returns Promise<void>
    */
   async loadLocale(localeId: string) {
-    if (this._locale === 'localeId') {
+    if (this._dicts[localeId]) {
       return;
     }
     const file = this._options.files.find((file) => localeId === file.id);

package/src/plugins/focus/FocusManagerPlugin.test.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockApp = vi.hoisted(() => ({
+  config: { focus: {} },
+  renderer: {
+    accessibility: {
+      isActive: false,
+      destroy: vi.fn(),
+      postrender: vi.fn(),
+      _deactivate: vi.fn(),
+    },
+  },
+  scenes: { onSceneChangeStart: { connect: vi.fn() } },
+  ticker: { addOnce: vi.fn(), add: vi.fn(), remove: vi.fn() },
+}));
+
+// FocusManagerPlugin transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../../core/Application', () => ({
+  Application: { getInstance: () => mockApp },
+}));
+
+import { FocusManagerPlugin } from './FocusManagerPlugin';
+
+describe('FocusManagerPlugin destroy', () => {
+  let plugin: FocusManagerPlugin;
+
+  beforeEach(() => {
+    plugin = new FocusManagerPlugin();
+  });
+
+  it('stops handling window keydown after destroy', () => {
+    const spy = vi.spyOn(plugin as any, '_onKeyDown');
+    plugin.initialize({}, mockApp as never);
+
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab' }));
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    plugin.destroy();
+    window.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab' }));
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops handling window keyup after destroy', () => {
+    const spy = vi.spyOn(plugin as any, '_onKeyUp');
+    plugin.initialize({}, mockApp as never);
+
+    window.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter' }));
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    plugin.destroy();
+    window.dispatchEvent(new KeyboardEvent('keyup', { key: 'Enter' }));
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops handling the capture-phase document mousemove after destroy', () => {
+    const spy = vi.spyOn(plugin as any, '_onMouseMove');
+    plugin.initialize({}, mockApp as never);
+    (plugin as any)._activate();
+
+    document.dispatchEvent(new MouseEvent('mousemove'));
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    plugin.destroy();
+    document.dispatchEvent(new MouseEvent('mousemove'));
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+});

package/src/plugins/focus/FocusManagerPlugin.ts

@@ -734,6 +734,13 @@ export class FocusManagerPlugin extends Plugin<FocusManagerPluginOptions> implem
   private _removeGlobalListeners() {
     globalThis.document.removeEventListener('mousemove', this._handleGlobalMouseMove);
     globalThis.document.removeEventListener('pointerdown', this._handleGlobalPointerDown);
+    // keydown is added by _setupKeyboardListeners (window) and again, when pixi
+    // accessibility is off, by _updatePixiAccessibility (globalThis)
+    window.removeEventListener('keydown', this._onKeyDown, false);
+    globalThis.removeEventListener('keydown', this._onKeyDown, false);
+    globalThis.removeEventListener('keyup', this._onKeyUp, false);
+    // capture-phase listener added by _activate()
+    globalThis.document.removeEventListener('mousemove', this._onMouseMove, true);
   }
 
   private _handleGlobalMouseMove() {

package/src/plugins/gesture/GesturePlugin.ts

@@ -74,23 +74,19 @@ export class GesturePlugin extends Plugin<GesturePluginOptions> implements IGest
       canvas.style.touchAction = 'none';
     }
 
-    canvas.addEventListener('pointerdown', this._onPointerDown);
-    window.addEventListener('pointermove', this._onPointerMove);
-    window.addEventListener('pointerup', this._onPointerUp);
-    window.addEventListener('pointercancel', this._onPointerCancel);
+    this.listen(canvas, 'pointerdown', this._onPointerDown as EventListener);
+    this.listen(window, 'pointermove', this._onPointerMove as EventListener);
+    this.listen(window, 'pointerup', this._onPointerUp as EventListener);
+    this.listen(window, 'pointercancel', this._onPointerCancel as EventListener);
   }
 
   public destroy(): void {
     if (this._canvas) {
-      this._canvas.removeEventListener('pointerdown', this._onPointerDown);
       if (this._options.preventDefault) {
         this._canvas.style.touchAction = this._previousTouchAction;
       }
       this._canvas = null;
     }
-    window.removeEventListener('pointermove', this._onPointerMove);
-    window.removeEventListener('pointerup', this._onPointerUp);
-    window.removeEventListener('pointercancel', this._onPointerCancel);
 
     this._pointers.clear();
     this._state = 'idle';

package/src/plugins/input/AbstractControls.ts

@@ -1,15 +1,116 @@
 import type { ControlsActionMap } from '../..';
-import { IApplication } from '../../core';
 import { Application } from '../../core/Application';
+import { WithSignals } from '../../mixins/signals';
+import { Logger } from '../../utils';
+import type { Action } from '../actions';
+import { buildDownMaps, buildUpMap, isInputActive, type SchemeSection } from './controlsCore';
 
-export class AbstractControls {
+/**
+ * Terminates the destroy chain — WithSignals' destroy() calls super.destroy().
+ * Also the binding root: `bindAllMethods` in an adapter binds everything down
+ * to here and stops, exactly like `Application` / `Plugin` / `Container`.
+ */
+class ControlsRoot {
+  private static readonly __caper_method_binding_root = true;
+
+  destroy(): void {}
+}
+
+/**
+ * Shared machinery for every controls adapter: scheme storage, context-gated
+ * down/up map building (rebuilt whenever the action context changes), the
+ * `isActionActive` query and the ticker hookup. Adapters supply the scheme
+ * sections, the "is this input down" predicates and the dispatch loop.
+ */
+export abstract class AbstractControls extends WithSignals(ControlsRoot) {
   protected scheme: any;
+  /** `+` combinations, longest first — the update loop relies on that order. */
+  protected combinations: string[][] = [];
+  protected combinationsMap: Map<string[], Action> = new Map();
+  protected activeDownInputs: Map<string, Action> = new Map();
+  protected activeUpInputs: Map<string, Action> = new Map();
+  private _warnedMissingActions: Set<string> = new Set();
 
-  get app(): IApplication {
+  get app() {
     return Application.getInstance();
   }
 
   initialize(scheme: Partial<ControlsActionMap>) {
     this.scheme = scheme;
+    this.addSignalConnection(this.app.signal.onActionContextChanged.connect(this._sortActions));
+    this._sortActions();
+  }
+
+  public connect(): void {
+    this.app.ticker.add(this._update);
+  }
+
+  public destroy(): void {
+    this.app.ticker.remove(this._update);
+    super.destroy();
+  }
+
+  isActionActive(action: Action): boolean {
+    const input = this.scheme?.down?.[action] ?? null;
+    if (!input) {
+      return false;
+    }
+    if (Array.isArray(input)) {
+      return input.some((item: string) => this._isInputActive(item));
+    }
+    return this._isInputActive(input);
+  }
+
+  /** The `down` section of the adapter's scheme. */
+  protected get downSection(): SchemeSection | undefined {
+    return this.scheme?.down;
+  }
+
+  /** The `up` section of the adapter's scheme. */
+  protected get upSection(): SchemeSection | undefined {
+    return this.scheme?.up;
+  }
+
+  /** Prefix for scheme warnings — a field, so minification cannot rename it away. */
+  protected abstract readonly logLabel: string;
+
+  /** Whether a single input is currently down. */
+  protected abstract isInputDown(id: string): boolean;
+
+  /** Whether an input counts as down *as part of a combination*. */
+  protected isComboPartDown(id: string): boolean {
+    return this.isInputDown(id);
+  }
+
+  /** Dispatch actions for the current input state — added to the ticker by {@link connect}. */
+  protected abstract _update(): void;
+
+  protected _isInputActive(input: string): boolean {
+    return isInputActive(input, this.isInputDown, this.isComboPartDown);
+  }
+
+  /** Rebuild the down/up maps for the current action context. */
+  protected _sortActions(): void {
+    const actions = this.app.actionsPlugin.getActions();
+    const context = this.app.actionContext as string;
+
+    const { combinations, combinationsMap, singles } = buildDownMaps<Action>(
+      this.downSection,
+      actions,
+      context,
+      this._warnMissingAction,
+    );
+    this.combinations = combinations;
+    this.combinationsMap = combinationsMap;
+    this.activeDownInputs = singles;
+    this.activeUpInputs = buildUpMap<Action>(this.upSection, actions, context, this._warnMissingAction);
+  }
+
+  protected _warnMissingAction(key: string): void {
+    if (this._warnedMissingActions.has(key)) {
+      return;
+    }
+    this._warnedMissingActions.add(key);
+    Logger.warn(`${this.logLabel}: scheme references unknown action "${key}"`);
   }
 }