@caperjs/core 0.2.4 → 0.4.0

package/src/plugins/Plugin.test.ts

@@ -1,15 +1,21 @@
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 // Plugin.ts transitively imports Application → Pixi display graph. Stub it.
 vi.mock('../core', () => ({
   coreFunctionRegistry: {},
   coreSignalRegistry: {},
 }));
+
+const { mockTicker } = vi.hoisted(() => ({
+  mockTicker: { add: vi.fn(), remove: vi.fn() },
+}));
+
 vi.mock('../core/Application', () => ({
-  Application: { getInstance: () => ({}) },
+  Application: { getInstance: () => ({ ticker: mockTicker }) },
 }));
 
 import { Signal } from '../signals';
+import { Logger } from '../utils';
 import { Plugin } from './Plugin';
 
 class TestPlugin extends Plugin<{ foo: string }> {
@@ -71,3 +77,125 @@ describe('Plugin', () => {
     await expect(p.postInitialize({} as never)).resolves.toBeUndefined();
   });
 });
+
+describe('Plugin lifecycle cleanup', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    mockTicker.add.mockClear();
+    mockTicker.remove.mockClear();
+  });
+
+  it('runs disposers LIFO, and only once', () => {
+    const p = new TestPlugin();
+    const order: string[] = [];
+    p.addDisposer(
+      () => order.push('a'),
+      () => order.push('b'),
+    );
+    p.addDisposer(() => order.push('c'));
+
+    p.destroy();
+    expect(order).toEqual(['c', 'b', 'a']);
+
+    p.destroy();
+    expect(order).toEqual(['c', 'b', 'a']);
+  });
+
+  it('destroy is idempotent for signal connections too', () => {
+    const p = new TestPlugin();
+    const s = new Signal<() => void>();
+    const handler = vi.fn();
+    p.addSignalConnection(s.connect(handler));
+
+    p.destroy();
+    expect(() => p.destroy()).not.toThrow();
+    s.emit();
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('a throwing disposer does not stop the rest, and is reported', () => {
+    const errorSpy = vi.spyOn(Logger, 'error').mockImplementation(() => undefined);
+    const p = new TestPlugin();
+    const first = vi.fn();
+    const last = vi.fn();
+
+    p.addDisposer(first);
+    p.addDisposer(() => {
+      throw new Error('boom');
+    });
+    p.addDisposer(last);
+
+    expect(() => p.destroy()).not.toThrow();
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(last).toHaveBeenCalledTimes(1);
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('listen() attaches now and detaches on destroy', () => {
+    const p = new TestPlugin();
+    const target = document.createElement('div');
+    const handler = vi.fn();
+
+    p.listen(target, 'click', handler);
+    target.dispatchEvent(new Event('click'));
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    p.destroy();
+    target.dispatchEvent(new Event('click'));
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('listen() detaches capture-phase listeners with matching options', () => {
+    const p = new TestPlugin();
+    const parent = document.createElement('div');
+    const child = document.createElement('div');
+    parent.appendChild(child);
+    document.body.appendChild(parent);
+    const handler = vi.fn();
+
+    p.listen(parent, 'click', handler, true);
+    child.dispatchEvent(new Event('click', { bubbles: true }));
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    p.destroy();
+    child.dispatchEvent(new Event('click', { bubbles: true }));
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    parent.remove();
+  });
+
+  it('listen() returns an early-removal fn that is safe to call twice', () => {
+    const p = new TestPlugin();
+    const target = document.createElement('div');
+    const handler = vi.fn();
+
+    const remove = p.listen(target, 'click', handler);
+    remove();
+    remove();
+    target.dispatchEvent(new Event('click'));
+    expect(handler).not.toHaveBeenCalled();
+    expect(() => p.destroy()).not.toThrow();
+  });
+
+  it('addTickerCallback() adds to the app ticker and removes on destroy', () => {
+    const p = new TestPlugin();
+    const fn = vi.fn();
+
+    p.addTickerCallback(fn, p, 5);
+    expect(mockTicker.add).toHaveBeenCalledWith(fn, p, 5);
+
+    p.destroy();
+    expect(mockTicker.remove).toHaveBeenCalledWith(fn, p);
+  });
+
+  it('addTickerCallback() returns an early-removal fn that only removes once', () => {
+    const p = new TestPlugin();
+    const fn = vi.fn();
+
+    const remove = p.addTickerCallback(fn);
+    remove();
+    remove();
+    p.destroy();
+    expect(mockTicker.remove).toHaveBeenCalledTimes(1);
+  });
+});

package/src/plugins/Plugin.ts

@@ -1,8 +1,9 @@
+import type { Ticker } from 'pixi.js';
 import type { IApplication, ICoreFunctions, ICoreSignals } from '../core';
 import { coreFunctionRegistry, coreSignalRegistry } from '../core';
 import { Application } from '../core/Application';
 import { SignalConnection, SignalConnections } from '../signals';
-import { type AppTypeOverrides, bindAllMethods, ImportListItemModule } from '../utils';
+import { type AppTypeOverrides, bindAllMethods, ImportListItemModule, Logger } from '../utils';
 
 /**
  * Public contract for a Caper plugin. A plugin is a long-lived object
@@ -25,7 +26,40 @@ import { type AppTypeOverrides, bindAllMethods, ImportListItemModule } from '../
  *      methods are called from scenes / other plugins / the app.
  *   5. `destroy()` — called when the app shuts down. Tear down
  *      connections, disconnect signals, free resources. The base class
- *      already disconnects everything added via `addSignalConnection`.
+ *      already disconnects everything added via `addSignalConnection`
+ *      and runs everything registered via the cleanup primitives below.
+ *
+ * **Cleanup primitives.** Don't hand-roll matching add/remove pairs —
+ * register the resource through the base class and `destroy()` releases
+ * it for you. Overriding `destroy()` is still fine; just call
+ * `super.destroy()`.
+ *
+ *   - `addSignalConnection(...)` — signal connections.
+ *   - `listen(target, type, handler, options?)` — DOM listeners. Adds
+ *     now, removes on destroy with the same capture/options semantics.
+ *   - `addTickerCallback(fn, context?, priority?)` — ticker callbacks on
+ *     `app.ticker`. Added now, removed on destroy.
+ *   - `addDisposer(...fns)` — anything else (DOM nodes, timers, third
+ *     party handles). Disposers run last-in-first-out on destroy, each
+ *     isolated so one failure can't skip the others.
+ *
+ * `listen` and `addTickerCallback` also return a removal function, for
+ * the rarer case where you need to detach before the plugin dies. It's
+ * safe to call more than once.
+ *
+ * @example
+ * ```ts
+ * public initialize(): void {
+ *   this.listen(window, 'resize', this._onResize);
+ *   this.addTickerCallback(this._update);
+ *   this.addDisposer(() => this._el.remove());
+ * }
+ * // no destroy() override needed — the base class cleans all three up
+ * ```
+ *
+ * Listeners that get attached and detached repeatedly at runtime (an
+ * activate/deactivate cycle, say) should stay manual — the primitives
+ * are for resources whose lifetime matches the plugin's.
  *
  * Discovery: plugin classes under `src/plugins/` are auto-discovered
  * by the Vite plugin if they default-export a class. Annotate with
@@ -79,7 +113,11 @@ export interface IPlugin<O = any> {
    */
   postInitialize(_app: IApplication): Promise<void> | void;
 
-  /** Tear down. Called on app shutdown. */
+  /**
+   * Tear down. Called on app shutdown. Runs every registered disposer
+   * (last-in-first-out) and disconnects every tracked signal connection.
+   * Safe to call more than once — the second call is a no-op.
+   */
   destroy(): void;
 
   /**
@@ -91,6 +129,40 @@ export interface IPlugin<O = any> {
   /** Disconnect every connection added via `addSignalConnection`. */
   clearSignalConnections(): void;
 
+  /**
+   * Register cleanup callbacks to run on `destroy`. Use for resources
+   * the other primitives don't cover — DOM nodes, timers, third-party
+   * handles.
+   *
+   * Disposers run last-in-first-out (so teardown mirrors setup), and each
+   * one is isolated: a throwing disposer is reported and the rest still
+   * run.
+   */
+  addDisposer(...fns: Array<() => void>): void;
+
+  /**
+   * Add a DOM event listener now and remove it on `destroy`, with the
+   * same capture/options semantics it was added with.
+   *
+   * @returns A removal function, for the rarer case where the listener
+   *   must come off before the plugin dies. Safe to call more than once.
+   */
+  listen(
+    target: EventTarget,
+    type: string,
+    handler: EventListenerOrEventListenerObject,
+    options?: AddEventListenerOptions | boolean,
+  ): () => void;
+
+  /**
+   * Add a callback to `app.ticker` now and remove it on `destroy`. The
+   * ticker is resolved when this is called, not at construction.
+   *
+   * @returns A removal function, for the rarer case where the callback
+   *   must come off before the plugin dies. Safe to call more than once.
+   */
+  addTickerCallback(fn: (ticker: Ticker) => void, context?: unknown, priority?: number): () => void;
+
   /** Register methods this plugin exposes via the core function registry. */
   registerCoreFunctions(): void;
 
@@ -117,6 +189,8 @@ export class Plugin<O = any> implements IPlugin<O> {
   private static readonly __caper_method_binding_root = true;
   // A collection of signal connections.
   protected _signalConnections: SignalConnections = new SignalConnections();
+  // Cleanup callbacks registered via addDisposer / listen / addTickerCallback.
+  protected _disposers: Array<() => void> = [];
 
   protected _options: O;
 
@@ -132,7 +206,25 @@ export class Plugin<O = any> implements IPlugin<O> {
     return Application.getInstance();
   }
 
+  /**
+   * Tear down the plugin. Runs every registered disposer (last-in-first-out,
+   * each isolated so one failure can't skip the others), then disconnects
+   * every tracked signal connection. Idempotent.
+   *
+   * Subclasses may override this, but must call `super.destroy()`.
+   */
   public destroy(): void {
+    // swap the list out first, so a disposer that (indirectly) re-enters
+    // destroy can't run anything twice
+    const disposers = this._disposers;
+    this._disposers = [];
+    for (let i = disposers.length - 1; i >= 0; i--) {
+      try {
+        disposers[i]();
+      } catch (e) {
+        Logger.error(`Plugin "${this.id}" threw while running a disposer:`, e);
+      }
+    }
     this._signalConnections.disconnectAll();
   }
 
@@ -164,6 +256,70 @@ export class Plugin<O = any> implements IPlugin<O> {
     this._signalConnections.disconnectAll();
   }
 
+  /**
+   * Register cleanup callbacks to run on `destroy`, last-in-first-out.
+   * Use for resources the other primitives don't cover — DOM nodes,
+   * timers, third-party handles.
+   * @param fns - The cleanup callbacks to register.
+   */
+  public addDisposer(...fns: Array<() => void>): void {
+    for (const fn of fns) {
+      this._disposers.push(fn);
+    }
+  }
+
+  /**
+   * Add a DOM event listener now and remove it on `destroy`, with the same
+   * capture/options semantics it was added with.
+   * @param target - The event target to listen on.
+   * @param type - The event type.
+   * @param handler - The listener.
+   * @param options - Passed through to both add and remove, so capture-phase
+   *   listeners detach correctly.
+   * @returns A removal function for early detachment. Safe to call more than once.
+   */
+  public listen(
+    target: EventTarget,
+    type: string,
+    handler: EventListenerOrEventListenerObject,
+    options?: AddEventListenerOptions | boolean,
+  ): () => void {
+    target.addEventListener(type, handler, options);
+    let removed = false;
+    const remove = () => {
+      if (removed) {
+        return;
+      }
+      removed = true;
+      target.removeEventListener(type, handler, options);
+    };
+    this.addDisposer(remove);
+    return remove;
+  }
+
+  /**
+   * Add a callback to `app.ticker` now and remove it on `destroy`. The ticker
+   * is resolved when this is called, not at construction.
+   * @param fn - The ticker callback.
+   * @param context - The context to invoke the callback with.
+   * @param priority - Pixi `UPDATE_PRIORITY` for the callback.
+   * @returns A removal function for early detachment. Safe to call more than once.
+   */
+  public addTickerCallback(fn: (ticker: Ticker) => void, context?: unknown, priority?: number): () => void {
+    const ticker = this.app.ticker;
+    ticker.add(fn, context, priority);
+    let removed = false;
+    const remove = () => {
+      if (removed) {
+        return;
+      }
+      removed = true;
+      ticker.remove(fn, context);
+    };
+    this.addDisposer(remove);
+    return remove;
+  }
+
   /**
    * @override
    * @protected

package/src/plugins/PopupManagerPlugin.test.ts

@@ -0,0 +1,53 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockApp = vi.hoisted(() => ({
+  ticker: { addOnce: (cb: () => void) => cb() },
+}));
+
+// PopupManagerPlugin transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => mockApp },
+}));
+
+// Evaluating the table registers it into mixins/factory/defaults, which the
+// plugin's `view` Container reads lazily on construction.
+import '../mixins/factory/const';
+import { PopupManagerPlugin } from './PopupManagerPlugin';
+
+function makeFakePopup() {
+  return {
+    beforeHide: vi.fn(),
+    hide: vi.fn().mockResolvedValue(undefined),
+    end: vi.fn(),
+    restoreActionContext: vi.fn(),
+  };
+}
+
+describe('PopupManagerPlugin removeAllPopups', () => {
+  let plugin: PopupManagerPlugin;
+
+  beforeEach(() => {
+    plugin = new PopupManagerPlugin();
+    vi.spyOn(plugin.view, 'removeChild').mockReturnValue(undefined as never);
+  });
+
+  it('clears active popups and the current id when animating', async () => {
+    const first = makeFakePopup();
+    const second = makeFakePopup();
+    (plugin as any)._activePopups.set('first', first);
+    (plugin as any)._activePopups.set('second', second);
+    (plugin as any)._currentPopupId = 'second';
+
+    plugin.removeAllPopups(true);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(first.hide).toHaveBeenCalledTimes(1);
+    expect(second.hide).toHaveBeenCalledTimes(1);
+    expect(plugin.hasActivePopups).toBe(false);
+    expect(plugin.currentPopupId).toBeUndefined();
+  });
+});

package/src/plugins/PopupManagerPlugin.ts

@@ -179,9 +179,11 @@ export class PopupManagerPlugin extends Plugin implements IPopupManagerPlugin {
    */
   removeAllPopups(animate: boolean = false): void {
     if (animate) {
-      this._activePopups.forEach((popup) => {
-        popup.hide();
-      });
+      // reuse the single-popup hide path so the view, the active map and the
+      // current id get cleaned up once each hide animation resolves
+      for (const id of [...this._activePopups.keys()]) {
+        void this.hidePopup(id);
+      }
     } else {
       this._activePopups.clear();
       this.view.removeChildren();

package/src/plugins/SceneManagerPlugin.test.ts

@@ -0,0 +1,76 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Signal } from '../signals';
+
+const mockApp = vi.hoisted(() => ({
+  config: {} as Record<string, unknown>,
+  onPause: null as any,
+  onResume: null as any,
+}));
+
+// SceneManagerPlugin transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => mockApp, containerElement: null },
+}));
+
+import { SceneManagerPlugin } from './SceneManagerPlugin';
+
+describe('SceneManagerPlugin destroy', () => {
+  let plugin: SceneManagerPlugin;
+
+  beforeEach(() => {
+    mockApp.config = { showSceneDebugMenu: false, useHash: true };
+    mockApp.onPause = new Signal<(config: any) => void>();
+    mockApp.onResume = new Signal<(config: any) => void>();
+    (globalThis as any).Caper = { get: () => [] };
+    plugin = new SceneManagerPlugin();
+  });
+
+  afterEach(() => {
+    delete (globalThis as any).Caper;
+    window.location.hash = '';
+  });
+
+  it('stops responding to hashchange after destroy', async () => {
+    await plugin.initialize({}, mockApp as never);
+    const spy = vi.spyOn(plugin, 'getSceneFromHash').mockReturnValue(null);
+
+    window.dispatchEvent(new Event('hashchange'));
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    plugin.destroy();
+    window.dispatchEvent(new Event('hashchange'));
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops forwarding pause/resume to the current scene after destroy', async () => {
+    await plugin.initialize({}, mockApp as never);
+    const onPause = vi.fn();
+    const onResume = vi.fn();
+    plugin.currentScene = { onPause, onResume } as never;
+
+    mockApp.onPause.emit({});
+    mockApp.onResume.emit({});
+    expect(onPause).toHaveBeenCalledTimes(1);
+    expect(onResume).toHaveBeenCalledTimes(1);
+
+    plugin.destroy();
+    mockApp.onPause.emit({});
+    mockApp.onResume.emit({});
+    expect(onPause).toHaveBeenCalledTimes(1);
+    expect(onResume).toHaveBeenCalledTimes(1);
+  });
+
+  it('removes the debug menu from the DOM after destroy', async () => {
+    mockApp.config = { showSceneDebugMenu: true };
+    await plugin.initialize({}, mockApp as never);
+    expect(document.getElementById('scene-debug')).not.toBeNull();
+
+    plugin.destroy();
+    expect(document.getElementById('scene-debug')).toBeNull();
+  });
+});

package/src/plugins/SceneManagerPlugin.ts

@@ -139,8 +139,6 @@ export class SceneManagerPlugin extends Plugin implements ISceneManagerPlugin {
     this._defaultLoadMethod = method;
   }
 
-  public destroy(): void {}
-
   public async initialize(_options: any, app: IApplication): Promise<void> {
     this._debugVisible =
       this.app.config?.showSceneDebugMenu === true || (isDev && this.app.config?.showSceneDebugMenu !== false);
@@ -179,8 +177,10 @@ export class SceneManagerPlugin extends Plugin implements ISceneManagerPlugin {
       this._listenForHashChange();
     }
 
-    this.app.onPause.connect(this._onPause, 'highest');
-    this.app.onResume.connect(this._onResume, 'highest');
+    this.addSignalConnection(
+      this.app.onPause.connect(this._onPause, 'highest'),
+      this.app.onResume.connect(this._onResume, 'highest'),
+    );
 
     return Promise.resolve(undefined);
   }
@@ -368,12 +368,14 @@ export class SceneManagerPlugin extends Plugin implements ISceneManagerPlugin {
   }
 
   private _listenForHashChange() {
-    window.addEventListener('hashchange', () => {
-      const sceneId = this.getSceneFromHash();
-      if (sceneId) {
-        void this.loadScene(sceneId);
-      }
-    });
+    this.listen(window, 'hashchange', this._onHashChange);
+  }
+
+  private _onHashChange() {
+    const sceneId = this.getSceneFromHash();
+    if (sceneId) {
+      void this.loadScene(sceneId);
+    }
   }
 
   private async _createCurrentScene() {
@@ -569,6 +571,7 @@ export class SceneManagerPlugin extends Plugin implements ISceneManagerPlugin {
     this._debugMenu.appendChild(icon);
 
     (Application.containerElement || document.body).appendChild(this._debugMenu);
+    this.addDisposer(() => this._debugMenu?.parentElement?.removeChild(this._debugMenu));
 
     this._sceneSelect = document.createElement('select');
     this._sceneSelect.style.cssText =
@@ -643,7 +646,7 @@ export class SceneManagerPlugin extends Plugin implements ISceneManagerPlugin {
 
     this._debugMenu.appendChild(this._sceneSelect);
 
-    this._debugMenu.addEventListener('change', (e: Event) => {
+    this.listen(this._debugMenu, 'change', (e: Event) => {
       if (this._queue) {
         e.preventDefault();
         return;
@@ -655,8 +658,10 @@ export class SceneManagerPlugin extends Plugin implements ISceneManagerPlugin {
       }
     });
 
-    this.onSceneChangeStart.connect(this._disableDebugMenu);
-    this.onSceneChangeComplete.connect(this._enableDebugMenu);
+    this.addSignalConnection(
+      this.onSceneChangeStart.connect(this._disableDebugMenu),
+      this.onSceneChangeComplete.connect(this._enableDebugMenu),
+    );
   }
 
   private _enableDebugMenu() {

package/src/plugins/StatsPlugin.ts

@@ -1,4 +1,4 @@
-import { Ticker, UPDATE_PRIORITY } from 'pixi.js';
+import { UPDATE_PRIORITY } from 'pixi.js';
 import Stats from 'stats.js';
 import { Application } from '../core/Application';
 import { Plugin } from './Plugin';
@@ -12,6 +12,7 @@ export class StatsPlugin extends Plugin {
     this.stats.dom.id = 'stats';
 
     Application.containerElement?.appendChild(this.stats.dom);
+    this.addDisposer(() => this.stats.dom.remove());
 
     this.stats.dom.style.position = 'absolute';
     this.stats.dom.style.top = 'auto';
@@ -19,6 +20,6 @@ export class StatsPlugin extends Plugin {
     this.stats.dom.style.right = '0';
     this.stats.dom.style.left = 'auto';
 
-    Ticker.shared.add(this.stats.update, this.stats, UPDATE_PRIORITY.UTILITY);
+    this.addTickerCallback(this.stats.update, this.stats, UPDATE_PRIORITY.UTILITY);
   }
 }

package/src/plugins/TimerPlugin.ts

@@ -676,7 +676,7 @@ export class TimerPlugin extends Plugin implements ITimerPlugin {
 
   public postInitialize() {
     // Set up update loop for main thread timers only
-    this.app.ticker.add(this.update);
+    this.addTickerCallback(this.update);
 
     // Initialize worker if needed
     this.initWorker();
@@ -763,7 +763,6 @@ export class TimerPlugin extends Plugin implements ITimerPlugin {
   }
 
   public destroy(): void {
-    this.app.ticker.remove(this.update);
     this.worker?.terminate();
     this.worker = null;
     this.timerCallbacks.clear();

package/src/plugins/WebEventsPlugin.test.ts

@@ -9,6 +9,7 @@ vi.mock('../core/Application', () => ({
   Application: { getInstance: () => ({ renderer: { canvas: null } }) },
 }));
 
+import { Signal } from '../signals';
 import { WebEventsPlugin } from './WebEventsPlugin';
 
 type FakeVisualViewport = EventTarget & { scale: number };
@@ -73,3 +74,34 @@ describe('WebEventsPlugin visualViewport resize', () => {
     expect(() => plugin.initialize()).not.toThrow();
   });
 });
+
+describe('WebEventsPlugin destroy', () => {
+  let plugin: WebEventsPlugin;
+
+  beforeEach(() => {
+    plugin = new WebEventsPlugin();
+  });
+
+  it('stops handling orientationchange after destroy', () => {
+    const spy = vi.spyOn(plugin as any, '_onOrientationChanged');
+    plugin.initialize();
+
+    window.dispatchEvent(new Event('orientationchange'));
+    expect(spy).toHaveBeenCalledTimes(1);
+
+    plugin.destroy();
+    window.dispatchEvent(new Event('orientationchange'));
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('disconnects tracked signal connections on destroy', () => {
+    const signal = new Signal<() => void>();
+    const handler = vi.fn();
+    plugin.addSignalConnection(signal.connect(handler));
+
+    plugin.destroy();
+    signal.emit();
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+});