@caperjs/core 0.1.0

package/src/plugins/Plugin.ts

@@ -0,0 +1,200 @@
+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';
+
+/**
+ * Public contract for a Caper plugin. A plugin is a long-lived object
+ * with `initialize` / `postInitialize` / `destroy` lifecycle hooks,
+ * registered at app bootstrap and accessed via `app.getPlugin(id)`.
+ *
+ * **Lifecycle order** (per plugin):
+ *
+ *   1. `constructor` — instantiated by the framework. Don't reference
+ *      the app yet; it isn't attached.
+ *   2. `initialize(options, app)` — set up internal state, parse options,
+ *      open connections, register signals. Awaited by the framework
+ *      before any other plugin's `initialize` runs (when ordered by
+ *      `requires`). Don't call out to other plugins here unless they
+ *      are listed in your `requires` — order isn't guaranteed otherwise.
+ *   3. `postInitialize(app)` — runs after every plugin has finished
+ *      `initialize`. Safe to look up sibling plugins via `app.getPlugin`
+ *      regardless of `requires`. Use for cross-plugin wiring.
+ *   4. (use phase) — the plugin is live; signal handlers fire, exposed
+ *      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`.
+ *
+ * Discovery: plugin classes under `src/plugins/` are auto-discovered
+ * by the Vite plugin if they default-export a class. Annotate with
+ * `definePlugin({ id, requires })` for the canonical id and any
+ * dependency declarations:
+ *
+ * @example
+ * ```ts
+ * import { definePlugin, IApplication, Plugin } from '@caperjs/core';
+ *
+ * export const plugin = definePlugin({
+ *   id: 'leaderboard',
+ *   requires: ['firebase'],   // firebase initializes first
+ * });
+ *
+ * export default class LeaderboardPlugin extends Plugin {
+ *   public readonly id = 'leaderboard';
+ *
+ *   async initialize(_options, app) {
+ *     this.firebase = app.getPlugin('firebase'); // guaranteed to exist
+ *   }
+ * }
+ * ```
+ */
+export interface IPlugin<O = any> {
+  /** Unique plugin id. Must match the `definePlugin({ id })` value. */
+  id: string;
+
+  /** The owning application instance. Available after registration. */
+  app: IApplication;
+
+  /** Resolved options after `initialize` merges defaults with the user's. */
+  readonly options: O;
+
+  /**
+   * Set up the plugin. Called once at bootstrap, awaited before any
+   * dependent plugin's `initialize` runs. Use this to parse options,
+   * open connections, and register signals.
+   *
+   * @param options Partial options from `caper.config.ts plugins[]`.
+   * @param app The application instance, fully constructed but possibly
+   *   mid-bootstrap (other plugins may not yet be initialized — see
+   *   `requires` and `postInitialize`).
+   */
+  initialize(options: Partial<O>, app: IApplication): Promise<void> | void;
+
+  /**
+   * Cross-plugin wiring hook. Called after every plugin has finished
+   * `initialize`. Safe to look up siblings via `app.getPlugin(id)` here
+   * regardless of `requires` — they're all live.
+   */
+  postInitialize(_app: IApplication): Promise<void> | void;
+
+  /** Tear down. Called on app shutdown. */
+  destroy(): void;
+
+  /**
+   * Track a signal connection so it gets auto-disconnected on `destroy`.
+   * Prefer this over storing connections manually.
+   */
+  addSignalConnection(...args: SignalConnection[]): void;
+
+  /** Disconnect every connection added via `addSignalConnection`. */
+  clearSignalConnections(): void;
+
+  /** Register methods this plugin exposes via the core function registry. */
+  registerCoreFunctions(): void;
+
+  /** Register signals this plugin exposes via the core signal registry. */
+  registerCoreSignals(): void;
+}
+
+export interface PluginListItem {
+  id: string;
+  path: string;
+  module?: ImportListItemModule<IPlugin>;
+  assets?: string[];
+  plugins?: string[];
+  /**
+   * IDs of other plugins that must initialize before this one. Populated
+   * from `definePlugin({ requires: [...] })` for local plugins; carried
+   * through discovery to bootstrap so the framework can topologically
+   * sort the active plugin set.
+   */
+  requires?: string[];
+}
+
+export class Plugin<O = any> implements IPlugin<O> {
+  private readonly __caper_method_binding_root = true;
+  // A collection of signal connections.
+  protected _signalConnections: SignalConnections = new SignalConnections();
+
+  protected _options: O;
+
+  get options(): O {
+    return this._options;
+  }
+
+  constructor(public id: string = 'Plugin') {
+    bindAllMethods(this);
+  }
+
+  public get app(): AppTypeOverrides['App'] {
+    return Application.getInstance();
+  }
+
+  public destroy(): void {
+    this._signalConnections.disconnectAll();
+  }
+
+  public initialize(options?: Partial<O>, _app?: IApplication): Promise<void> | void;
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public async initialize(_options: Partial<O>, _app?: IApplication): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  public postInitialize(_app: IApplication): Promise<void> | void;
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  public async postInitialize(_app: IApplication): Promise<void> {
+    return Promise.resolve(undefined);
+  }
+
+  /**
+   * Add signal connections to the container.
+   * @param args - The signal connections to add.
+   */
+  public addSignalConnection(...args: SignalConnection[]) {
+    for (const connection of args) {
+      this._signalConnections.add(connection);
+    }
+  }
+
+  public clearSignalConnections() {
+    this._signalConnections.disconnectAll();
+  }
+
+  /**
+   * @override
+   * @protected
+   */
+  public registerCoreFunctions(): void {
+    const functions = this.getCoreFunctions();
+    functions.forEach((f) => {
+      const fName = f as keyof ICoreFunctions;
+      // @ts-expect-error implicit any
+      coreFunctionRegistry[fName] = this[f];
+    });
+  }
+
+  /**
+   * @override
+   * @protected
+   */
+  public registerCoreSignals(): void {
+    const signals = this.getCoreSignals();
+    signals.forEach((s) => {
+      const sName = s as keyof ICoreSignals;
+      // @ts-expect-error implicit any
+      coreSignalRegistry[sName] = this[s];
+    });
+  }
+
+  protected getCoreFunctions(): string[] {
+    return [];
+  }
+
+  protected getCoreSignals(): string[] {
+    return [];
+  }
+}

package/src/plugins/PopupManagerPlugin.ts

@@ -0,0 +1,263 @@
+import { Container } from '../display';
+import { Signal } from '../signals';
+import type { IPopup, PopupConfig, PopupConstructor } from '../ui';
+import { bindAllMethods, getLastMapEntry } from '../utils';
+import type { PopupId, PopupInstance, PopupProps } from '../utils';
+import type { IPlugin } from './Plugin';
+import { Plugin } from './Plugin';
+
+type PopupListItem = {
+  id: string | number;
+  active?: boolean;
+  module?: PopupConstructor | (() => Promise<unknown>);
+};
+
+/**`
+ * Interface for PopupManager
+ */
+export interface IPopupManagerPlugin extends IPlugin {
+  readonly view: Container; // The view of the PopupManager
+  readonly current: IPopup | undefined; // The current active popup
+  readonly hasActivePopups: boolean; // Whether there are any active popups
+  readonly popupCount: number; // The count of popups
+  readonly currentPopupId: string | number | undefined; // The id of the current popup
+  // signals
+  onShowPopup: Signal<(detail: PopupSignalDetail) => void>; // Signal for when a popup is shown
+  onHidePopup: Signal<(detail: PopupSignalDetail) => void>; // Signal for when a popup is hidden
+  onPopupChanged: Signal<(detail: PopupSignalDetail) => void>; // Signal for when a popup is changed
+
+  /**
+   * Show a discovered popup by id. The `config.data` field is narrowed to
+   * the popup's declared data type (if it extends `Popup<MyData>`). Awaits
+   * the full show lifecycle (initialize → beforeShow → show animation).
+   */
+  showPopup<K extends PopupId>(id: K, config?: PopupProps<K>): Promise<PopupInstance<K> | undefined>;
+
+  /** Alias for `showPopup` — shorter when called as `this.popups.show(...)`. */
+  show<K extends PopupId>(id: K, config?: PopupProps<K>): Promise<PopupInstance<K> | undefined>;
+
+  hidePopup<T = any>(id: string | number, data?: any): Promise<IPopup<T> | undefined>; // Hide a popup
+
+  removeAllPopups(animate?: boolean): void; // Remove all popups
+}
+
+export type PopupSignalDetail<T = any> = { id: string | number; data?: T };
+
+/**
+ * PopupManager
+ */
+
+export class PopupManagerPlugin extends Plugin implements IPopupManagerPlugin {
+  public readonly id: string = 'popups'; // The id of the PopupManager
+  public readonly view = new Container(); // The view of the PopupManager
+
+  // signals
+  public onShowPopup: Signal<(detail: PopupSignalDetail) => void> = new Signal<(detail: PopupSignalDetail) => void>(); // Signal for when a popup is shown
+  public onHidePopup: Signal<(detail: PopupSignalDetail) => void> = new Signal<(detail: PopupSignalDetail) => void>(); // Signal for when a popup is hidden
+  public onPopupChanged: Signal<(detail: PopupSignalDetail) => void> = new Signal<
+    (detail: PopupSignalDetail) => void
+  >(); // Signal for when a popup is changed
+  // Map entries may start out as a dynamic-import function (from discovery)
+  // and get replaced with the resolved constructor on first `show()` call.
+  private _popups: Map<string | number, PopupConstructor | (() => Promise<unknown>)> = new Map();
+  private _activePopups: Map<string | number, IPopup> = new Map(); // Map of active popups
+
+  private _currentPopupId: string | number | undefined = undefined; // The id of the current popup
+
+  get currentPopupId(): string | number | undefined {
+    return this._currentPopupId;
+  }
+
+  get popupCount(): number {
+    return this._popups.size;
+  }
+
+  get current(): IPopup | undefined {
+    if (this._currentPopupId === undefined) {
+      return undefined;
+    }
+    return this._activePopups.get(this._currentPopupId);
+  }
+
+  get hasActivePopups(): boolean {
+    return this._activePopups.size > 0;
+  }
+
+  /**
+   * Initialize the PopupManager. Reads the discovered `popupList` from the
+   * `caper-runtime` global and pre-registers every active popup. Dynamic
+   * imports are stored as-is and resolved on first `show()` call.
+   */
+  initialize(): void {
+    bindAllMethods(this);
+    this.view.label = 'PopupManager';
+    this._setupAppListeners();
+    this._registerDiscoveredPopups();
+  }
+
+  /**
+   * Destroy the PopupManager
+   */
+  destroy(): void {
+    this._activePopups.clear();
+    super.destroy();
+  }
+
+  /**
+   * Show a discovered popup by id.
+   * @param id - The id of the popup (typed against `AppPopups`).
+   * @param config - The configuration for the popup. `config.data` is
+   *   narrowed via the popup class's `Popup<T>` generic.
+   * @returns a promise resolving to the popup instance.
+   */
+  async showPopup<K extends PopupId>(
+    id: K,
+    config: PopupProps<K> = {} as PopupProps<K>,
+  ): Promise<PopupInstance<K> | undefined> {
+    const resolved = await this._resolvePopupCtor(id);
+    if (!resolved) return;
+
+    const typedConfig = config as Partial<PopupConfig<any>> & { id?: string | number };
+    typedConfig.id = id;
+    const instance = this.view.add.existing(new resolved(id, typedConfig as Partial<PopupConfig>));
+    instance.initialize();
+    this.app.focus.clearFocus();
+    instance.beforeShow();
+    await instance.show();
+
+    this.app.focus.setFocusLayer(id);
+    instance.afterShow();
+
+    this._activePopups.set(id, instance);
+    this._currentPopupId = id;
+
+    return new Promise((resolve) => {
+      this.app.ticker.addOnce(() => {
+        this.onShowPopup.emit({ id, data: typedConfig?.data });
+        instance.start();
+        this.onPopupChanged.emit({ id, data: typedConfig?.data });
+        resolve(instance as PopupInstance<K>);
+      });
+    });
+  }
+
+  /** Alias for `showPopup`. */
+  show<K extends PopupId>(id: K, config?: PopupProps<K>): Promise<PopupInstance<K> | undefined> {
+    return this.showPopup(id, config);
+  }
+
+  /**
+   * Hide a popup
+   * @param id - The id of the popup
+   * @param data
+   * @returns a promise resolving to the popup, if it exists
+   */
+  async hidePopup<T = any>(id: string | number, data?: T): Promise<IPopup<T> | undefined> {
+    const popup = this._activePopups.get(id);
+    if (popup) {
+      popup.beforeHide();
+      await popup.hide();
+      this.view.removeChild(popup as any);
+      this._activePopups.delete(id);
+      this._currentPopupId = getLastMapEntry(this._activePopups)?.[0] || undefined;
+      return new Promise((resolve) => {
+        this.app.ticker.addOnce(() => {
+          this.onHidePopup.emit({ id, data });
+          popup.end();
+          this.onPopupChanged.emit({ id, data });
+          resolve(popup);
+          popup.restoreActionContext();
+        });
+      });
+    }
+    return;
+  }
+
+  /**
+   * Remove all popups
+   * @param animate - Whether to animate the removal
+   */
+  removeAllPopups(animate: boolean = false): void {
+    if (animate) {
+      this._activePopups.forEach((popup) => {
+        popup.hide();
+      });
+    } else {
+      this._activePopups.clear();
+      this.view.removeChildren();
+    }
+  }
+
+  protected getCoreFunctions() {
+    return ['hidePopup', 'showPopup', 'removeAllPopups'];
+  }
+
+  protected getCoreSignals() {
+    return ['onShowPopup', 'onHidePopup', 'onPopupChanged'];
+  }
+
+  /**
+   * Setup application listeners
+   * @private
+   */
+  private _setupAppListeners(): void {
+    this.addSignalConnection(this.app.scenes.onSceneChangeStart.connect(() => this.removeAllPopups()));
+    this.app.keyboard.onKeyUp('Escape').connect(this._handleEscape);
+  }
+
+  /**
+   * Pull every active popup off `globalThis.Caper.popupList` (populated by
+   * the `caper-runtime` virtual module before the Application starts) and
+   * seed the registry. Entries stay as dynamic-import functions until the
+   * first `show()` call resolves them.
+   */
+  private _registerDiscoveredPopups(): void {
+    const list: PopupListItem[] =
+      ((globalThis as unknown as { Caper?: { get?: (key: string) => unknown } }).Caper?.get?.(
+        'popupList',
+      ) as PopupListItem[] | undefined) ?? [];
+    for (const item of list) {
+      if (item.active === false || !item.module) continue;
+      this._popups.set(item.id, item.module);
+    }
+  }
+
+  /**
+   * Ensure the popup constructor for `id` is loaded and return it. Resolves
+   * dynamic-import functions on first access, caches the result back onto
+   * the registry so subsequent shows are synchronous.
+   */
+  private async _resolvePopupCtor(id: string | number): Promise<PopupConstructor | undefined> {
+    const entry = this._popups.get(id);
+    if (!entry) {
+      const known = [...this._popups.keys()].map((k) => `'${String(k)}'`).join(', ');
+      throw new Error(
+        `[caper] Unknown popup id '${String(id)}'. ` +
+          `Known: ${known.length > 0 ? known : '(none — discovery may have failed)'}`,
+      );
+    }
+    // Already a constructor (has prototype)
+    if (typeof entry === 'function' && (entry as PopupConstructor).prototype) {
+      return entry as PopupConstructor;
+    }
+    // Dynamic import function — resolve and cache
+    const mod = (await (entry as () => Promise<unknown>)()) as { default?: PopupConstructor };
+    const ctor = mod?.default;
+    if (!ctor) {
+      throw new Error(`[caper] Popup '${String(id)}' module did not export a default class.`);
+    }
+    this._popups.set(id, ctor);
+    return ctor;
+  }
+
+  /**
+   * Handle escape key press
+   * if the current popup should close when escape is pressed (true by default), closes it
+   * @private
+   */
+  private _handleEscape() {
+    if (this.current && this.current.config.closeOnEscape) {
+      void this.hidePopup(this.current.id);
+    }
+  }
+}

package/src/plugins/ResizerPlugin.ts

@@ -0,0 +1,220 @@
+import { Graphics } from 'pixi.js';
+
+import { Container } from '../display';
+import type { Size } from '../utils';
+import type { IPlugin } from './Plugin';
+import { Plugin } from './Plugin';
+
+/**
+ * Interface for Resizer module.
+ */
+export interface IResizerPlugin extends IPlugin {
+  readonly size: Size;
+  readonly scale: number;
+  resize(): Promise<Size>;
+}
+
+/**
+ * Configuration options for the Resizer plugin
+ */
+export type ResizerPluginOptions = {
+  /** Whether to scroll the window to the top when resizing */
+  autoScroll: boolean;
+  /** The minimum width at which the renderer will resize. Also controls aspect ratio in letterbox mode */
+  minWidth: number;
+  /** The minimum height of the canvas. Also controls aspect ratio in letterbox mode */
+  minHeight: number;
+  /** Whether to letterbox the canvas to maintain aspect ratio */
+  letterbox: boolean;
+  /** Whether to center the canvas (particularly useful in letterbox mode) */
+  center: boolean;
+  /** Whether to draw debug information for visualizing canvas bounds */
+  debug: boolean;
+};
+
+/**
+ * Default options for Resizer module.
+ */
+const defaultOptions: ResizerPluginOptions = {
+  autoScroll: false,
+  minWidth: 0,
+  minHeight: 0,
+  letterbox: false,
+  center: false,
+  debug: false,
+};
+
+export class ResizerPlugin extends Plugin<ResizerPluginOptions> implements IResizerPlugin {
+  public readonly id = 'resizer';
+  private _debugContainer: Container;
+  private _gfx: Graphics;
+  private _size: Size;
+  private _scale: number;
+  private _resizeId: number | null;
+
+  get size(): Size {
+    return this._size;
+  }
+
+  get scale(): number {
+    return this._scale;
+  }
+
+  /**
+   * Initializes the Resizer module.
+   */
+  async initialize(options: Partial<ResizerPluginOptions>) {
+    this._options = { ...defaultOptions, ...options };
+  }
+
+  /**
+   * Post-initialization of the Resizer module.
+   * when this is called, the renderer is already created, and the dom element has been appended
+   */
+  async postInitialize() {
+    this.resize();
+  }
+
+  async resize(): Promise<Size> {
+    this._cancelResize!();
+    return new Promise((resolve) => {
+      this._resizeId = requestAnimationFrame(() => {
+        this._resize();
+        resolve(this._size);
+      });
+    });
+  }
+
+  _cancelResize = (): void => {
+    if (this._resizeId) {
+      cancelAnimationFrame(this._resizeId);
+      this._resizeId = null;
+    }
+  };
+
+  _resizeInternal(w: number, h: number, minWidth: number, minHeight: number, letterbox: boolean) {
+    const aspectRatio = minWidth / minHeight;
+    let canvasWidth = w;
+    let canvasHeight = h;
+
+    if (letterbox) {
+      if (minWidth < minHeight) {
+        canvasWidth = canvasHeight * aspectRatio;
+      } else {
+        canvasHeight = canvasWidth / aspectRatio;
+      }
+    }
+
+    const scaleX = canvasWidth < minWidth ? minWidth / canvasWidth : 1;
+    const scaleY = canvasHeight < minHeight ? minHeight / canvasHeight : 1;
+    const scale = scaleX > scaleY ? scaleX : scaleY;
+    const width = Math.floor(canvasWidth * scale);
+    const height = Math.floor(canvasHeight * scale);
+
+    return { width, height, aspectRatio };
+  }
+  /**
+   * Resizes the application based on window size and module options.
+   */
+
+  _resize() {
+    const minWidth = this._options.minWidth;
+    const minHeight = this._options.minHeight;
+    const letterbox = this._options.letterbox;
+    const center = this._options.center;
+
+    let canvasWidth = minWidth;
+    let canvasHeight = minHeight;
+
+    if (this.app.config.resizeToContainer) {
+      const canvas = this.app.renderer.canvas;
+      const el = canvas?.parentElement;
+      const bounds = el?.getBoundingClientRect();
+      if (bounds) {
+        canvasWidth = bounds.width;
+        canvasHeight = bounds.height;
+      }
+    }
+
+    const { width, height, aspectRatio } = this._resizeInternal(
+      canvasWidth,
+      canvasHeight,
+      minWidth,
+      minHeight,
+      letterbox,
+    );
+
+    // Calculate renderer and canvas sizes based on current dimensions
+    const scaleX = canvasWidth < minWidth ? minWidth / canvasWidth : 1;
+    const scaleY = canvasHeight < minHeight ? minHeight / canvasHeight : 1;
+    const scale = scaleX > scaleY ? scaleX : scaleY;
+
+    this._scale = scale;
+
+    // Update canvas style dimensions and scroll window up to avoid issues on mobile resize
+    if (letterbox) {
+      if (canvasWidth > canvasHeight) {
+        // Calculate dimensions based on width
+        let styleWidth = canvasWidth;
+        let styleHeight = canvasWidth / aspectRatio;
+
+        // Constrain height if it exceeds container
+        if (styleHeight > canvasHeight) {
+          styleHeight = canvasHeight;
+          styleWidth = styleHeight * aspectRatio;
+        }
+
+        this.app.renderer.canvas.style.width = `${styleWidth}px`;
+        this.app.renderer.canvas.style.height = `${styleHeight}px`;
+      } else {
+        // Calculate dimensions based on height
+        let styleHeight = canvasHeight;
+        let styleWidth = canvasHeight * aspectRatio;
+
+        // Constrain width if it exceeds container
+        if (styleWidth > canvasWidth) {
+          styleWidth = canvasWidth;
+          styleHeight = styleWidth / aspectRatio;
+        }
+
+        this.app.renderer.canvas.style.height = `${styleHeight}px`;
+        this.app.renderer.canvas.style.width = `${styleWidth}px`;
+      }
+      if (center) {
+        this.app.renderer.canvas.style.position = 'absolute';
+        this.app.renderer.canvas.style.left = '50%';
+        this.app.renderer.canvas.style.top = '50%';
+        this.app.renderer.canvas.style.transform = `translate3d(-50%, -50%, 0)`;
+      }
+    } else {
+      this.app.renderer.canvas.style.width = `${canvasWidth}px`;
+      this.app.renderer.canvas.style.height = `${canvasHeight}px`;
+    }
+
+    if (this._options.autoScroll) {
+      window?.scrollTo(0, 0);
+    }
+
+    // Update renderer and navigation screens dimensions
+    this.app.renderer.resize(width, height);
+    this._size = { width, height };
+
+    if (this._options.debug) {
+      this._drawDebug();
+    }
+  }
+
+  /**
+   * Draws debug information if debug option is enabled.
+   */
+  private _drawDebug() {
+    if (!this._debugContainer) {
+      this._debugContainer = this.app.stage.addChild(new Container());
+      this._gfx = this._debugContainer.add.graphics();
+    }
+
+    this._gfx.clear();
+    this._gfx.rect(0, 0, this._size.width, this._size.height);
+    this._gfx.stroke({ width: 4, color: 0x000fff });
+  }
+}