@caperjs/core 0.1.0

package/src/plugins/KeyboardPlugin.ts

@@ -0,0 +1,160 @@
+import { IApplication } from '../core';
+import { Signal } from '../signals';
+import { isDev, KeyboardKey, Logger } from '../utils';
+import type { IPlugin } from './Plugin';
+import { Plugin } from './Plugin';
+
+export type KeyboardEventType = 'keydown' | 'keyup';
+export type KeyboardEventDetail = { event: KeyboardEvent; key: string };
+export type KeySignal = Signal<(detail: KeyboardEventDetail) => void>;
+
+export interface IKeyboardPlugin extends IPlugin {
+  enabled: boolean;
+  readonly keysDown: Set<string>;
+
+  onKeyDown(key?: KeyboardKey): KeySignal;
+
+  onKeyUp(key?: KeyboardKey): KeySignal;
+
+  isKeyDown(key: string): boolean;
+}
+
+export function normalizeKey(key: string | undefined): string {
+  if (key === undefined) {
+    key = '*undefined*';
+  } else if (key === ' ') {
+    key = 'Space';
+  } else if (key.length === 1) {
+    key = key.toUpperCase();
+  }
+  return key;
+}
+
+export class KeyboardPlugin extends Plugin implements IKeyboardPlugin {
+  public readonly id: string = 'keyboard';
+  // global signals
+  public onGlobalKeyDown: Signal<(detail: KeyboardEventDetail) => void> = new Signal();
+  public onGlobalKeyUp: Signal<(detail: KeyboardEventDetail) => void> = new Signal();
+
+  private _keyDownSignals: Map<string | undefined, KeySignal> = new Map();
+  private _keyUpSignals: Map<string | undefined, KeySignal> = new Map();
+
+  private _keysDown: Set<string> = new Set();
+
+  // Dev-only guard: warn once if key events arrive with no consumers connected.
+  private _warnedNoConsumers = false;
+
+  get keysDown() {
+    return this._keysDown;
+  }
+
+  private _enabled: boolean = true;
+
+  public get enabled(): boolean {
+    return this._enabled;
+  }
+
+  public set enabled(value: boolean) {
+    this._enabled = value;
+  }
+
+  // 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);
+  }
+
+  public onKeyDown(key?: KeyboardKey): KeySignal {
+    return this._checkAndAddSignal(key || undefined, 'keydown');
+  }
+
+  public onKeyUp(key?: KeyboardKey): KeySignal {
+    return this._checkAndAddSignal(key || undefined, 'keyup');
+  }
+
+  public isKeyDown(key: KeyboardKey): boolean {
+    return this._keysDown.has(key);
+  }
+
+  _update() {
+    //
+  }
+
+  protected getCoreSignals(): string[] {
+    return ['onGlobalKeyDown', 'onGlobalKeyUp'];
+  }
+
+  protected getCoreFunctions(): string[] {
+    return ['onKeyDown', 'onKeyUp', 'isKeyDown'];
+  }
+
+  private _handleKeyDown(e: KeyboardEvent): void {
+    const key = normalizeKey(e.key);
+    this._keysDown.add(key);
+    this.onGlobalKeyDown.emit({ event: e, key: e.key });
+  }
+
+  private _handleKeyUp(e: KeyboardEvent): void {
+    const key = normalizeKey(e.key);
+    this._keysDown.delete(key);
+    // DX guard: a key arrived but nothing consumes it (no KeyboardControls / no
+    // onKeyDown|onKeyUp subscribers). Almost always an Application subclass whose
+    // postInitialize() skipped framework wiring, or controls never connected.
+    if (isDev && !this._warnedNoConsumers && this._keyUpSignals.size === 0 && this._keyDownSignals.size === 0) {
+      this._warnedNoConsumers = true;
+      Logger.warn(
+        'KeyboardPlugin received a key event but no consumers are connected, so keyboard ' +
+          'actions will not fire. Ensure the InputPlugin controls are connected — e.g. an ' +
+          'Application subclass overriding postInitialize() must not skip framework wiring, ' +
+          'or call app.controls.connect().',
+      );
+    }
+    this.onGlobalKeyUp.emit({ event: e, key: e.key });
+  }
+
+  /**
+   * Check if the signal exists and add it if it doesn't
+   * Also, if this is the first signal, start listening for the event
+   * @param {string} key
+   * @param {KeyboardEventType} eventType
+   * @returns {KeySignal}
+   * @private
+   */
+  private _checkAndAddSignal(key: string | undefined, eventType: KeyboardEventType): KeySignal {
+    const signalMap = eventType === 'keydown' ? this._keyDownSignals : this._keyUpSignals;
+
+    if (!signalMap.size) {
+      this._listen(eventType);
+    }
+
+    key = normalizeKey(key);
+
+    if (!signalMap.has(key)) {
+      signalMap.set(key, new Signal<(detail: KeyboardEventDetail) => void>());
+    }
+
+    return signalMap.get(key) as KeySignal;
+  }
+
+  private _listen(eventType: KeyboardEventType): void {
+    document.addEventListener(eventType, this._handleEvent);
+  }
+
+  private _handleEvent(event: KeyboardEvent): void {
+    if (!this._enabled) {
+      return;
+    }
+    const signalMap = event.type === 'keydown' ? this._keyDownSignals : this._keyUpSignals;
+    const key = normalizeKey(event.key);
+    signalMap.get('*undefined*')?.emit({ event, key });
+    signalMap.get(key)?.emit({ event, key });
+  }
+}

package/src/plugins/LayoutPlugin.ts

@@ -0,0 +1,127 @@
+import '@pixi/layout';
+import { Layout } from '@pixi/layout';
+import '@pixi/layout/devtools';
+
+import { Plugin, type IPlugin } from './Plugin';
+
+/**
+ * Interface for the Layout plugin providing PIXI.js layout management.
+ * Enables advanced CSS-like layout capabilities for PIXI display objects.
+ */
+export interface ILayoutPlugin extends IPlugin {}
+
+/**
+ * Layout management plugin for PIXI.js applications using @pixi/layout.
+ *
+ * Integrates the @pixi/layout library to provide CSS-like layout capabilities
+ * for PIXI display objects, including flexbox, positioning, and responsive design.
+ * Automatically configures sensible default styles for consistent layout behavior.
+ *
+ * Key Features:
+ * - CSS Flexbox-like layout system for PIXI containers
+ * - Responsive design capabilities with intrinsic sizing
+ * - Automatic layout calculation and positioning
+ * - Gap, padding, and margin support
+ * - Transform origin and object positioning controls
+ * - Development tools integration for layout debugging
+ *
+ * Default Style Configuration:
+ * - Container: Auto width/height with no gap
+ * - Leaf: Intrinsic sizing with flex shrink enabled
+ * - Shared: Center transform origin, row direction, stretch alignment
+ *
+ * @example
+ * ```typescript
+ * // Plugin is automatically initialized with the application
+ * // Layout capabilities are immediately available on all containers
+ *
+ * // Create a flexbox-style layout
+ * const container = new PIXI.Container();
+ * container.layout = {
+ *   display: 'flex',
+ *   flexDirection: 'row',
+ *   justifyContent: 'space-between',
+ *   alignItems: 'center',
+ *   gap: 10,
+ *   padding: 20
+ * };
+ *
+ * // Add children that will be automatically laid out
+ * const button1 = new PIXI.Sprite(buttonTexture);
+ * const button2 = new PIXI.Sprite(buttonTexture);
+ * const button3 = new PIXI.Sprite(buttonTexture);
+ *
+ * container.addChild(button1, button2, button3);
+ * // Children are automatically positioned using flexbox rules
+ *
+ * // Responsive design with intrinsic sizing
+ * const responsiveContainer = new PIXI.Container();
+ * responsiveContainer.layout = {
+ *   width: '100%',
+ *   maxWidth: 800,
+ *   flexDirection: 'column',
+ *   alignItems: 'center'
+ * };
+ * ```
+ *
+ * @remarks
+ * - Requires @pixi/layout package to be installed
+ * - Provides devtools integration for layout debugging in development
+ * - Default styles are optimized for common game UI patterns
+ * - Layout calculations happen automatically when display objects are added/modified
+ * - Supports both absolute and relative positioning
+ */
+export class LayoutPlugin extends Plugin implements ILayoutPlugin {
+  /** Plugin identifier for framework registration */
+  public readonly id = 'LayoutPlugin';
+
+  /**
+   * Initializes the Layout plugin with optimized default styles.
+   * Configures the @pixi/layout system with sensible defaults for game development,
+   * including flexbox behavior, sizing, and alignment settings.
+   *
+   * Default Configuration Details:
+   * - **Container styles**: Auto-sizing with no gaps for efficient nesting
+   * - **Leaf styles**: Intrinsic sizing with flex shrink for responsive behavior
+   * - **Shared styles**: Center origins, row direction, and stretch alignment
+   * - **Transform origin**: Set to 50% for predictable scaling and rotation
+   * - **Object position**: Centered for consistent alignment behavior
+   *
+   * @example
+   * ```typescript
+   * // Called automatically by the plugin system
+   * // After initialization, all PIXI containers support layout properties
+   *
+   * const container = new PIXI.Container();
+   * container.layout = {
+   *   display: 'flex',        // Use flexbox layout
+   *   flexDirection: 'column', // Stack children vertically
+   *   gap: 10,                // 10px gap between children
+   *   padding: 15             // 15px padding around content
+   * };
+   * ```
+   */
+  async initialize() {
+    Layout.defaultStyle = {
+      container: {
+        width: 'auto',
+        height: 'auto',
+        gap: 0,
+      },
+      leaf: {
+        width: 'intrinsic',
+        height: 'intrinsic',
+        flexShrink: 1,
+      },
+      shared: {
+        transformOrigin: '50%',
+        objectPosition: 'center',
+        flexShrink: 1,
+        flexDirection: 'row',
+        alignContent: 'stretch',
+        flexWrap: 'nowrap',
+        overflow: 'visible',
+      },
+    };
+  }
+}

package/src/plugins/LookupPlugin.ts

@@ -0,0 +1,308 @@
+import { Container as PIXIContainer } from 'pixi.js';
+import { IPlugin, Plugin } from '.';
+import { Container } from '../display';
+
+/**
+ * Interface for the LookupPlugin providing fast container lookup functionality.
+ * Enables O(1) lookups of PIXI containers using hierarchical path strings.
+ */
+export interface ILookupPlugin extends IPlugin {
+  /**
+   * Retrieves a container at the specified hierarchical path.
+   * @param path - Slash-separated path like 'Parent/Child/GrandChild'
+   * @returns The container at the path, or undefined if not found
+   * @example
+   * ```typescript
+   * const button = lookupPlugin.getChildAtPath('UI/Menu/StartButton');
+   * ```
+   */
+  getChildAtPath(path: string): PIXIContainer | undefined;
+
+  /**
+   * Gets the hierarchical path for a given container.
+   * @param container - The PIXI container to get the path for
+   * @returns The hierarchical path string, or empty string if not tracked
+   * @example
+   * ```typescript
+   * const path = lookupPlugin.getPathForChild(myContainer); // 'Parent/Child'
+   * ```
+   */
+  getPathForChild(container: PIXIContainer): string;
+
+  /**
+   * Batch retrieval of containers at multiple paths.
+   * @param paths - Array of hierarchical paths to look up
+   * @returns Array of containers found at the specified paths (undefined entries filtered out)
+   * @example
+   * ```typescript
+   * const [ui, player] = lookupPlugin.getChildrenAtPaths('UI/HUD', 'Game/Player');
+   * ```
+   */
+  getChildrenAtPaths(...paths: string[]): PIXIContainer[];
+
+  /**
+   * Batch retrieval of paths for multiple containers.
+   * @param containers - Array of PIXI containers to get paths for
+   * @returns Array of hierarchical paths for the containers
+   * @example
+   * ```typescript
+   * const paths = lookupPlugin.getPathsForChildren(container1, container2);
+   * ```
+   */
+  getPathsForChildren(...containers: PIXIContainer[]): string[];
+
+  /**
+   * Gets all currently tracked hierarchical paths.
+   * @returns Array of all path strings in the lookup system
+   * @example
+   * ```typescript
+   * const allPaths = lookupPlugin.getAllPaths(); // ['UI/Menu', 'Game/Player', ...]
+   * ```
+   */
+  getAllPaths(): string[];
+}
+
+/**
+ * High-performance container lookup plugin for PIXI.js applications.
+ *
+ * Provides O(1) lookup of containers using hierarchical path strings by maintaining
+ * bidirectional maps between paths and containers. Automatically tracks container
+ * hierarchy changes through global Container events.
+ *
+ * @example
+ * ```typescript
+ * // Access containers by path
+ * const player = app.lookup.getChildAtPath('Game/Entities/Player');
+ * const menuButton = app.lookup.getChildAtPath('UI/MainMenu/StartButton');
+ *
+ * // Get paths for containers
+ * const playerPath = app.lookup.getPathForChild(playerSprite); // 'Game/Entities/Player'
+ * ```
+ *
+ * @remarks
+ * - Paths are built using container labels in hierarchical order
+ * - Only containers with labels are included in paths
+ * - Automatically handles container addition/removal through event listeners
+ * - Uses Map data structures for optimal performance
+ */
+export class LookupPlugin extends Plugin implements ILookupPlugin {
+  public name = 'lookup';
+
+  /** Fast O(1) lookup map: hierarchical path -> container reference */
+  private pathToContainer = new Map<string, PIXIContainer>();
+
+  /** Reverse lookup for efficient path updates: container reference -> hierarchical path */
+  private containerToPath = new Map<PIXIContainer, string>();
+
+  /**
+   * Core function names exposed by this plugin for framework integration.
+   */
+  get coreFunctions(): string[] {
+    return ['getChildAtPath', 'getPathForChild', 'getChildrenAtPaths', 'getPathsForChildren', 'getAllPaths'];
+  }
+
+  /**
+   * Initializes the lookup plugin by connecting to global container events.
+   * Sets up automatic tracking of container hierarchy changes.
+   */
+  public async initialize() {
+    Container.onGlobalChildAdded.connect(this.onChildAdded);
+    Container.onGlobalChildRemoved.connect(this.onChildRemoved);
+  }
+
+  /**
+   * Fast O(1) lookup of container by hierarchical path.
+   *
+   * @param path - Slash-separated path like 'Parent/Child/GrandChild'
+   * @returns The container at the specified path, or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * // Get a specific UI element
+   * const healthBar = lookup.getChildAtPath('UI/HUD/HealthBar');
+   * if (healthBar) {
+   *   // Update health display
+   *   healthBar.visible = true;
+   * }
+   * ```
+   */
+  public getChildAtPath(path: string): PIXIContainer | undefined {
+    return this.pathToContainer.get(path);
+  }
+
+  /**
+   * Batch retrieval of containers at multiple paths.
+   * Filters out undefined results for convenience.
+   *
+   * @param paths - Variable number of hierarchical paths to look up
+   * @returns Array of found containers (undefined entries filtered out)
+   *
+   * @example
+   * ```typescript
+   * // Get multiple UI elements at once
+   * const [menu, hud, inventory] = lookup.getChildrenAtPaths(
+   *   'UI/MainMenu',
+   *   'UI/HUD',
+   *   'UI/Inventory'
+   * );
+   * ```
+   */
+  public getChildrenAtPaths(...paths: string[]): PIXIContainer[] {
+    return paths.map((path) => this.getChildAtPath(path)).filter((container) => container !== undefined);
+  }
+
+  /**
+   * Get the hierarchical path for a given container.
+   *
+   * @param container - The container to get the path for
+   * @returns The hierarchical path or empty string if not tracked
+   *
+   * @example
+   * ```typescript
+   * // Get path for debugging or logging
+   * const containerPath = lookup.getPathForChild(someSprite);
+   * console.log(`Container is at: ${containerPath}`);
+   * ```
+   */
+  public getPathForChild(container: PIXIContainer): string {
+    return this.containerToPath.get(container) || '';
+  }
+
+  /**
+   * Batch retrieval of paths for multiple containers.
+   *
+   * @param containers - Variable number of PIXI containers to get paths for
+   * @returns Array of hierarchical paths for the containers
+   *
+   * @example
+   * ```typescript
+   * // Get paths for multiple containers for debugging
+   * const paths = lookup.getPathsForChildren(sprite1, sprite2, sprite3);
+   * console.log('Container paths:', paths);
+   * ```
+   */
+  public getPathsForChildren(...containers: PIXIContainer[]): string[] {
+    return containers.map((container) => this.getPathForChild(container));
+  }
+
+  /**
+   * Gets all currently tracked hierarchical paths.
+   * Useful for debugging, serialization, or introspection.
+   *
+   * @returns Array of all path strings in the lookup system
+   *
+   * @example
+   * ```typescript
+   * // Debug all tracked containers
+   * const allPaths = lookup.getAllPaths();
+   * console.log('All tracked containers:', allPaths);
+   * ```
+   */
+  public getAllPaths(): string[] {
+    return Array.from(this.pathToContainer.keys());
+  }
+
+  /**
+   * Gets all currently tracked containers.
+   * Useful for bulk operations or debugging.
+   *
+   * @returns Array of all container references in the lookup system
+   */
+  public getAllChildren(): PIXIContainer[] {
+    return Array.from(this.pathToContainer.values());
+  }
+
+  /**
+   * Event handler for when a child is added to any container.
+   * Automatically adds the new container to the lookup system.
+   *
+   * @param child - The newly added container
+   */
+  private onChildAdded(child: PIXIContainer) {
+    this.addToLookup(child);
+  }
+
+  /**
+   * Event handler for when a child is removed from any container.
+   * Automatically removes the container from the lookup system.
+   *
+   * @param child - The removed container
+   */
+  private onChildRemoved(child: PIXIContainer) {
+    this.removeFromLookup(child);
+  }
+
+  /**
+   * Add a container and all its descendants to the lookup system.
+   * Recursively processes the entire subtree to maintain lookup integrity.
+   *
+   * @param container - The container to add (along with all its children)
+   */
+  private addToLookup(container: PIXIContainer): void {
+    const path = this.buildPath(container);
+
+    if (path) {
+      this.pathToContainer.set(path, container);
+      this.containerToPath.set(container, path);
+    }
+
+    // Recursively add all children to maintain lookup integrity
+    if (container.children) {
+      for (const child of container.children) {
+        this.addToLookup(child as PIXIContainer);
+      }
+    }
+  }
+
+  /**
+   * Remove a container and all its descendants from the lookup system.
+   * Recursively processes the entire subtree to prevent memory leaks.
+   *
+   * @param container - The container to remove (along with all its children)
+   */
+  private removeFromLookup(container: PIXIContainer): void {
+    // Remove all descendants first
+    if (container.children) {
+      for (const child of container.children) {
+        this.removeFromLookup(child as PIXIContainer);
+      }
+    }
+
+    // Remove this container from lookup
+    const path = this.containerToPath.get(container);
+    if (path) {
+      this.pathToContainer.delete(path);
+      this.containerToPath.delete(container);
+    }
+  }
+
+  /**
+   * Build the hierarchical path for a container by traversing up the parent chain.
+   * Only includes containers with labels in the path, stopping at 'Stage'.
+   *
+   * @param container - The container to build a path for
+   * @returns The hierarchical path string, or empty string if no labeled ancestors
+   *
+   * @example
+   * ```typescript
+   * // For a container structure: Stage -> Game -> Player -> HealthBar
+   * // Where each has a label, this would return: 'Game/Player/HealthBar'
+   * ```
+   */
+  private buildPath(container: PIXIContainer): string {
+    const pathSegments: string[] = [];
+    let current: PIXIContainer | null = container;
+
+    // Traverse up the parent chain to build path segments
+    while (current && current.label) {
+      pathSegments.unshift(current.label);
+      current = current.parent as PIXIContainer;
+      if (current?.label === 'Stage') {
+        break;
+      }
+    }
+
+    // Only return a path if we have at least one labeled segment
+    return pathSegments.length > 0 ? pathSegments.join('/') : '';
+  }
+}

package/src/plugins/Plugin.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// Plugin.ts transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({}) },
+}));
+
+import { Signal } from '../signals';
+import { Plugin } from './Plugin';
+
+class TestPlugin extends Plugin<{ foo: string }> {
+  public initCalls = 0;
+  public postCalls = 0;
+  public readonly id = 'test';
+  protected _options = { foo: 'default' };
+
+  async initialize(options: Partial<{ foo: string }> = {}) {
+    this._options = { ...this._options, ...options };
+    this.initCalls++;
+  }
+
+  async postInitialize() {
+    this.postCalls++;
+  }
+}
+
+describe('Plugin', () => {
+  it('runs initialize and merges options', async () => {
+    const p = new TestPlugin();
+    await p.initialize({ foo: 'bar' });
+    expect(p.initCalls).toBe(1);
+    expect(p.options.foo).toBe('bar');
+  });
+
+  it('runs postInitialize independently', async () => {
+    const p = new TestPlugin();
+    await p.postInitialize();
+    expect(p.postCalls).toBe(1);
+  });
+
+  it('destroy disconnects tracked signal connections', () => {
+    const p = new TestPlugin();
+    const s = new Signal<() => void>();
+    const handler = vi.fn();
+    p.addSignalConnection(s.connect(handler));
+    s.emit();
+    expect(handler).toHaveBeenCalledTimes(1);
+
+    p.destroy();
+    s.emit();
+    expect(handler).toHaveBeenCalledTimes(1);
+  });
+
+  it('clearSignalConnections disconnects without destroying', () => {
+    const p = new TestPlugin();
+    const s = new Signal<() => void>();
+    const handler = vi.fn();
+    p.addSignalConnection(s.connect(handler));
+    p.clearSignalConnections();
+    s.emit();
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it('base Plugin.initialize/postInitialize resolve without error', async () => {
+    const p = new Plugin('base');
+    await expect(p.initialize({})).resolves.toBeUndefined();
+    await expect(p.postInitialize({} as never)).resolves.toBeUndefined();
+  });
+});