@caperjs/core 0.2.2 → 0.2.4

package/src/mixins/factory/const.ts

@@ -1,20 +1,23 @@
 import { BitmapText, Graphics, HTMLText, Sprite, Text, TilingSprite } from 'pixi.js';
 
-import { AnimatedSprite, Container, ContainerConfigKeys, SpineAnimation, Svg } from '../../display';
+import { AnimatedSprite } from '../../display/AnimatedSprite';
+import { Container, ContainerConfigKeys } from '../../display/Container';
 import { ParticleContainer, ParticleContainerConfigKeys } from '../../display/ParticleContainer';
-import {
-  Button,
-  ButtonConfigKeys,
-  FlexContainer,
-  FlexContainerConfigKeys,
-  Toaster,
-  UICanvas,
-  UICanvasConfigKeys,
-} from '../../ui';
-import type { ButtonConfig, FlexContainerConfig, ToastConfig, ToasterConfig, UICanvasProps } from '../../ui';
+import { SpineAnimation } from '../../display/SpineAnimation';
+import { Svg } from '../../display/Svg';
+import type { ButtonConfig } from '../../ui/Button';
+import { Button, ButtonConfigKeys } from '../../ui/Button';
+import type { FlexContainerConfig } from '../../ui/FlexContainer';
+import { FlexContainer, FlexContainerConfigKeys } from '../../ui/FlexContainer';
+import type { ToastConfig } from '../../ui/Toast';
+import type { ToasterConfig } from '../../ui/Toaster';
+import { Toaster } from '../../ui/Toaster';
+import type { UICanvasProps } from '../../ui/UICanvas';
+import { UICanvas, UICanvasConfigKeys } from '../../ui/UICanvas';
 import type { EntityId, EntityInstance, EntityProps, UIId, UIInstance, UIProps } from '../../utils';
 import { pluck, resolvePointLike, Spine, WithRequiredProps } from '../../utils';
 
+import { setDefaultFactoryMethods } from './defaults';
 import type { EntityFactoryProps } from './props';
 import {
   AnimatedSpriteProps,
@@ -361,3 +364,7 @@ export const defaultFactoryMethods = {
     return instance;
   },
 };
+
+// Hand the table to the import-free registration slot the moment it exists, so
+// `Factory()` can read it without importing this module. See ./defaults.ts.
+setDefaultFactoryMethods(defaultFactoryMethods);

package/src/mixins/factory/defaults.ts

@@ -0,0 +1,28 @@
+/**
+ * Registration slot for the factory method table.
+ *
+ * This module deliberately has ZERO imports. `mixins/factory/const` builds the
+ * table (and to do so imports every ui/display class), while `Factory()` — which
+ * every one of those classes extends — needs the table at construct time. A
+ * direct import either way closes the cycle and hands out an undefined binding
+ * to whichever module is mid-evaluation. Routing through this import-free slot
+ * breaks the edge: `const.ts` pushes the table in when it evaluates, `Factory`
+ * pulls it out lazily, inside the constructor.
+ */
+let defaults: Record<string, any> | null = null;
+
+/** Called by `mixins/factory/const` as soon as the table is defined. */
+export function setDefaultFactoryMethods(methods: Record<string, any>): void {
+  defaults = methods;
+}
+
+/** Read the registered table. Throws if `const.ts` has not evaluated yet. */
+export function getDefaultFactoryMethods(): Record<string, any> {
+  if (!defaults) {
+    throw new Error(
+      "[caper] The factory method table hasn't been initialized. Import '@caperjs/core' (or its factory module) " +
+        'before deep-importing display/ui classes so the table is registered first.',
+    );
+  }
+  return defaults;
+}

package/src/mixins/factory/methods.ts

@@ -1,4 +1,4 @@
-import { defaultFactoryMethods } from './index';
+import type { defaultFactoryMethods } from './const';
 
 export function createFactoryMethods<T extends typeof defaultFactoryMethods = typeof defaultFactoryMethods>(
   methods: Partial<T>,

package/src/mixins/factory/props.ts

@@ -1,8 +1,10 @@
 import type { LayoutOptions } from '@pixi/layout';
 import { GraphicsContext, HTMLTextStyleOptions, TextStyleOptions } from 'pixi.js';
-import { ContainerConfig } from '../../display';
-import { ParticleContainerConfig } from '../../display/ParticleContainer';
-import { ButtonConfig, FlexContainerConfig, UICanvasProps } from '../../ui';
+import type { ContainerConfig } from '../../display/Container';
+import type { ParticleContainerConfig } from '../../display/ParticleContainer';
+import type { ButtonConfig } from '../../ui/Button';
+import type { FlexContainerConfig } from '../../ui/FlexContainer';
+import type { UICanvasProps } from '../../ui/UICanvas';
 import type {
   BitmapFontFamilyAsset,
   FontFamilyAsset,

package/src/plugins/LookupPlugin.ts

@@ -1,6 +1,6 @@
 import { Container as PIXIContainer } from 'pixi.js';
 import { IPlugin, Plugin } from '.';
-import { Container } from '../display';
+import { Container } from '../display/Container';
 
 /**
  * Interface for the LookupPlugin providing fast container lookup functionality.

package/src/plugins/PopupManagerPlugin.ts

@@ -1,4 +1,4 @@
-import { Container } from '../display';
+import { Container } from '../display/Container';
 import { Signal } from '../signals';
 import type { IPopup, PopupConfig, PopupConstructor } from '../ui';
 import { bindAllMethods, getLastMapEntry } from '../utils';

package/src/plugins/ResizerPlugin.test.ts

@@ -0,0 +1,84 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// ResizerPlugin transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+
+const mocks = vi.hoisted(() => ({
+  app: {
+    config: { resizeToContainer: false } as { resizeToContainer: boolean },
+    renderer: {
+      canvas: { style: {} as Record<string, string>, parentElement: null as unknown },
+      resize: (_w: number, _h: number) => {},
+    },
+  },
+}));
+
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => mocks.app },
+}));
+
+import { ResizerPlugin } from './ResizerPlugin';
+
+/** Shrinks the container below minWidth/minHeight so `_resize()` computes scale > 1. */
+function useContainer(width: number, height: number) {
+  mocks.app.config.resizeToContainer = true;
+  mocks.app.renderer.canvas.parentElement = {
+    getBoundingClientRect: () => ({ width, height }),
+  };
+}
+
+describe('ResizerPlugin safe area', () => {
+  let plugin: ResizerPlugin;
+
+  beforeEach(async () => {
+    mocks.app.config.resizeToContainer = false;
+    mocks.app.renderer.canvas = { style: {}, parentElement: null };
+    plugin = new ResizerPlugin();
+  });
+
+  it('reports zero insets before the first resize', () => {
+    expect(plugin.safeArea).toEqual({ top: 0, right: 0, bottom: 0, left: 0 });
+  });
+
+  it('scales measured insets into logical render units', async () => {
+    await plugin.initialize({ minWidth: 1000, minHeight: 1000 });
+    useContainer(500, 500);
+    plugin._measureSafeAreaCssPx = () => ({ top: 44, right: 0, bottom: 34, left: 12 });
+
+    plugin._resize();
+
+    expect(plugin.scale).toBe(2);
+    expect(plugin.safeArea).toEqual({ top: 88, right: 0, bottom: 68, left: 24 });
+  });
+
+  it('passes measured insets through unscaled at scale 1', async () => {
+    await plugin.initialize({ minWidth: 500, minHeight: 500 });
+    plugin._measureSafeAreaCssPx = () => ({ top: 44, right: 0, bottom: 34, left: 12 });
+
+    plugin._resize();
+
+    expect(plugin.scale).toBe(1);
+    expect(plugin.safeArea).toEqual({ top: 44, right: 0, bottom: 34, left: 12 });
+  });
+
+  it('reports zero insets when useSafeArea is off', async () => {
+    await plugin.initialize({ minWidth: 500, minHeight: 500, useSafeArea: false });
+    plugin._measureSafeAreaCssPx = () => ({ top: 44, right: 0, bottom: 34, left: 12 });
+
+    plugin._resize();
+
+    expect(plugin.safeArea).toEqual({ top: 0, right: 0, bottom: 0, left: 0 });
+  });
+
+  it('measures 0 when the browser does not support env()', async () => {
+    await plugin.initialize({ minWidth: 500, minHeight: 500 });
+
+    plugin._resize();
+
+    expect(plugin.safeArea).toEqual({ top: 0, right: 0, bottom: 0, left: 0 });
+    plugin.destroy();
+  });
+});

package/src/plugins/ResizerPlugin.ts

@@ -1,6 +1,6 @@
 import { Graphics } from 'pixi.js';
 
-import { Container } from '../display';
+import { Container } from '../display/Container';
 import type { Size } from '../utils';
 import type { IPlugin } from './Plugin';
 import { Plugin } from './Plugin';
@@ -11,6 +11,8 @@ import { Plugin } from './Plugin';
 export interface IResizerPlugin extends IPlugin {
   readonly size: Size;
   readonly scale: number;
+  /** Device safe-area insets, in logical render units (already scaled like `size`). */
+  readonly safeArea: { top: number; right: number; bottom: number; left: number };
   resize(): Promise<Size>;
 }
 
@@ -30,6 +32,8 @@ export type ResizerPluginOptions = {
   center: boolean;
   /** Whether to draw debug information for visualizing canvas bounds */
   debug: boolean;
+  /** Whether to measure the device safe-area insets (notch / status bar / gesture bar) */
+  useSafeArea: boolean;
 };
 
 /**
@@ -42,6 +46,7 @@ const defaultOptions: ResizerPluginOptions = {
   letterbox: false,
   center: false,
   debug: false,
+  useSafeArea: true,
 };
 
 export class ResizerPlugin extends Plugin<ResizerPluginOptions> implements IResizerPlugin {
@@ -51,6 +56,8 @@ export class ResizerPlugin extends Plugin<ResizerPluginOptions> implements IResi
   private _size: Size;
   private _scale: number;
   private _resizeId: number | null;
+  private _safeArea = { top: 0, right: 0, bottom: 0, left: 0 };
+  private _safeAreaProbe: HTMLDivElement | null = null;
 
   get size(): Size {
     return this._size;
@@ -60,6 +67,10 @@ export class ResizerPlugin extends Plugin<ResizerPluginOptions> implements IResi
     return this._scale;
   }
 
+  get safeArea(): { top: number; right: number; bottom: number; left: number } {
+    return this._safeArea;
+  }
+
   /**
    * Initializes the Resizer module.
    */
@@ -75,6 +86,39 @@ export class ResizerPlugin extends Plugin<ResizerPluginOptions> implements IResi
     this.resize();
   }
 
+  public destroy(): void {
+    if (this._safeAreaProbe) {
+      this._safeAreaProbe.remove();
+      this._safeAreaProbe = null;
+    }
+    super.destroy();
+  }
+
+  /**
+   * Measures the device safe-area insets in CSS pixels, via a hidden probe element
+   * padded with `env(safe-area-inset-*)`. The probe is created once and reused.
+   * Browsers without env() support (and happy-dom) report empty strings, which fall back to 0.
+   */
+  _measureSafeAreaCssPx(): { top: number; right: number; bottom: number; left: number } {
+    if (!this._safeAreaProbe) {
+      const probe = document.createElement('div');
+      probe.style.cssText =
+        'position:fixed; top:0; left:0; width:0; height:0; visibility:hidden; pointer-events:none;' +
+        'padding-top:env(safe-area-inset-top, 0px); padding-right:env(safe-area-inset-right, 0px);' +
+        'padding-bottom:env(safe-area-inset-bottom, 0px); padding-left:env(safe-area-inset-left, 0px);';
+      document.body.appendChild(probe);
+      this._safeAreaProbe = probe;
+    }
+
+    const style = getComputedStyle(this._safeAreaProbe);
+    return {
+      top: parseFloat(style.paddingTop) || 0,
+      right: parseFloat(style.paddingRight) || 0,
+      bottom: parseFloat(style.paddingBottom) || 0,
+      left: parseFloat(style.paddingLeft) || 0,
+    };
+  }
+
   async resize(): Promise<Size> {
     this._cancelResize!();
     return new Promise((resolve) => {
@@ -151,6 +195,20 @@ export class ResizerPlugin extends Plugin<ResizerPluginOptions> implements IResi
 
     this._scale = scale;
 
+    // Safe-area insets are measured in CSS pixels; the renderer's logical size is
+    // CSS pixels * scale, so the insets have to be scaled the same way.
+    if (this._options.useSafeArea) {
+      const insets = this._measureSafeAreaCssPx();
+      this._safeArea = {
+        top: insets.top * scale,
+        right: insets.right * scale,
+        bottom: insets.bottom * scale,
+        left: insets.left * scale,
+      };
+    } else {
+      this._safeArea = { top: 0, right: 0, bottom: 0, left: 0 };
+    }
+
     // Update canvas style dimensions and scroll window up to avoid issues on mobile resize
     if (letterbox) {
       if (canvasWidth > canvasHeight) {

package/src/plugins/WebEventsPlugin.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// WebEventsPlugin transitively imports Application → Pixi display graph. Stub it.
+vi.mock('../core', () => ({
+  coreFunctionRegistry: {},
+  coreSignalRegistry: {},
+}));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => ({ renderer: { canvas: null } }) },
+}));
+
+import { WebEventsPlugin } from './WebEventsPlugin';
+
+type FakeVisualViewport = EventTarget & { scale: number };
+
+function installFakeVisualViewport(): FakeVisualViewport {
+  const vv = new EventTarget() as FakeVisualViewport;
+  vv.scale = 1;
+  (window as any).visualViewport = vv;
+  return vv;
+}
+
+describe('WebEventsPlugin visualViewport resize', () => {
+  let plugin: WebEventsPlugin;
+
+  beforeEach(() => {
+    delete (window as any).visualViewport;
+    plugin = new WebEventsPlugin();
+  });
+
+  afterEach(() => {
+    plugin.destroy();
+    delete (window as any).visualViewport;
+  });
+
+  it('emits onResize when the visual viewport resizes at scale 1', () => {
+    const vv = installFakeVisualViewport();
+    plugin.initialize();
+    const spy = vi.fn();
+    plugin.onResize.connect(spy);
+
+    vv.dispatchEvent(new Event('resize'));
+
+    expect(spy).toHaveBeenCalledTimes(1);
+    expect(spy).toHaveBeenCalledWith({ width: window.innerWidth, height: window.innerHeight });
+  });
+
+  it('ignores visual viewport resizes during pinch-zoom (scale !== 1)', () => {
+    const vv = installFakeVisualViewport();
+    plugin.initialize();
+    const spy = vi.fn();
+    plugin.onResize.connect(spy);
+
+    vv.scale = 2;
+    vv.dispatchEvent(new Event('resize'));
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('stops listening after destroy', () => {
+    const vv = installFakeVisualViewport();
+    plugin.initialize();
+    const spy = vi.fn();
+    plugin.onResize.connect(spy);
+
+    plugin.destroy();
+    vv.dispatchEvent(new Event('resize'));
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('initializes without error when visualViewport is unavailable', () => {
+    expect(() => plugin.initialize()).not.toThrow();
+  });
+});

package/src/plugins/WebEventsPlugin.ts

@@ -50,6 +50,9 @@ export class WebEventsPlugin extends Plugin implements IWebEventsPlugin {
     window.addEventListener('resize', this._onResize);
     document.addEventListener('fullscreenchange', this._onResize);
     window.addEventListener('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() {
@@ -58,6 +61,7 @@ export class WebEventsPlugin extends Plugin implements IWebEventsPlugin {
     document.removeEventListener('fullscreenchange', this._onResize);
     window.removeEventListener('pagehide', this._onPageHide, false);
     window.removeEventListener('pageshow', this._onPageShow, false);
+    window.visualViewport?.removeEventListener('resize', this._onVisualViewportResize);
   }
 
   protected getCoreSignals(): string[] {
@@ -85,6 +89,17 @@ export class WebEventsPlugin extends Plugin implements IWebEventsPlugin {
     this.onResize.emit({ width: screenWidth, height: screenHeight });
   }
 
+  /**
+   * Called when the visual viewport resizes. Ignores pinch-zoom (scale !== 1),
+   * where the layout size hasn't actually changed.
+   */
+  private _onVisualViewportResize(): void {
+    if ((window.visualViewport?.scale ?? 1) !== 1) {
+      return;
+    }
+    this._onResize();
+  }
+
   /**
    * Called when the page is hidden.
    * Some browsers (like Safari) don't support the `visibilitychange` event, so we also listen for `pagehide`.

package/src/plugins/captions/CaptionsRenderer.ts

@@ -1,6 +1,6 @@
 import { gsap } from 'gsap';
 import { BitmapText, Container as PIXIContainer, Sprite, Texture } from 'pixi.js';
-import { Container } from '../../display';
+import { Container } from '../../display/Container';
 import { type Size } from '../../utils';
 import { CaptionsPlugin } from './CaptionsPlugin';
 

package/src/plugins/i18nPlugin.test.ts

@@ -0,0 +1,124 @@
+import { afterEach, 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 { Logger } from '../utils';
+import type { i18nDict } from './i18nPlugin';
+import { i18nPlugin } from './i18nPlugin';
+
+/** Build an initialized plugin holding `dict` for the `en` locale. */
+async function setup(dict: i18nDict) {
+  const plugin = new i18nPlugin();
+  await plugin.initialize({ defaultLocale: 'en', locales: ['en'] });
+  // `_dicts` is private and normally filled by loadLocale(); inject directly.
+  (plugin as unknown as { _dicts: Record<string, i18nDict> })._dicts = { en: dict };
+  return plugin;
+}
+
+/** Silence the expected Logger.error calls for missing keys. */
+function muteErrors() {
+  return vi.spyOn(Logger, 'error').mockImplementation(() => undefined);
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('i18nPlugin.t', () => {
+  it('returns the key itself when the key is missing', async () => {
+    const error = muteErrors();
+    const plugin = await setup({ hello: 'Hello' });
+    expect(plugin.t('nope.missing')).toBe('nope.missing');
+    expect(error).toHaveBeenCalled();
+  });
+
+  it('returns the key itself when no dictionary is loaded', async () => {
+    const error = muteErrors();
+    const plugin = await setup({ hello: 'Hello' });
+    expect(plugin.t('hello', undefined, 'fr')).toBe('hello');
+    expect(error).toHaveBeenCalled();
+  });
+
+  it('resolves variants to index 0 with no params', async () => {
+    const plugin = await setup({ greet: '[Hi|Hello|Yo] there' });
+    expect(plugin.t('greet')).toBe('Hi there');
+  });
+
+  it('never leaves brackets in the output', async () => {
+    const plugin = await setup({ greet: '[Hi|Hello] [friend|pal]' });
+    expect(plugin.t('greet')).not.toMatch(/[[\]]/);
+    expect(plugin.t('greet', { variant: 'random' })).not.toMatch(/[[\]]/);
+  });
+
+  it('applies a numeric variant to every group', async () => {
+    const plugin = await setup({ greet: '[Hi|Hello] [friend|pal]' });
+    expect(plugin.t('greet', { variant: 1 })).toBe('Hello pal');
+  });
+
+  it('clamps a numeric variant to each group last item', async () => {
+    const plugin = await setup({ greet: '[Hi|Hello|Yo] [friend|pal]' });
+    expect(plugin.t('greet', { variant: 5 })).toBe('Yo pal');
+  });
+
+  it('picks each random variant independently', async () => {
+    const plugin = await setup({ greet: '[a|b] [a|b]' });
+    const random = vi.spyOn(Math, 'random').mockReturnValueOnce(0).mockReturnValueOnce(0.9);
+    expect(plugin.t('greet', { variant: 'random' })).toBe('a b');
+    expect(random).toHaveBeenCalledTimes(2);
+  });
+
+  it('interpolates placeholders after variant resolution', async () => {
+    const plugin = await setup({ greet: '[Hi|Hello] {name}' });
+    expect(plugin.t('greet', { variant: 1, name: 'Ada' })).toBe('Hello Ada');
+  });
+});
+
+describe('i18nPlugin.tCount', () => {
+  const dict: i18nDict = {
+    apples: {
+      one: '{count} apple',
+      other: '{count} apples',
+    },
+    fish: {
+      other: '{count} fish',
+    },
+    guests: {
+      one: '[Just one|One] guest, {host}',
+      other: '{count} guests, {host}',
+    },
+  };
+
+  it('resolves the one category for en', async () => {
+    const plugin = await setup(dict);
+    expect(plugin.tCount('apples', 1)).toBe('1 apple');
+  });
+
+  it('resolves the other category for en', async () => {
+    const plugin = await setup(dict);
+    expect(plugin.tCount('apples', 2)).toBe('2 apples');
+  });
+
+  it('falls back to .other when the category leaf is missing', async () => {
+    const plugin = await setup(dict);
+    expect(plugin.tCount('fish', 1)).toBe('1 fish');
+  });
+
+  it('passes extra params through and still resolves variants', async () => {
+    const plugin = await setup(dict);
+    expect(plugin.tCount('guests', 1, { host: 'Ada' })).toBe('Just one guest, Ada');
+    expect(plugin.tCount('guests', 3, { host: 'Ada' })).toBe('3 guests, Ada');
+  });
+
+  it('returns the .other key when nothing resolves', async () => {
+    muteErrors();
+    const plugin = await setup(dict);
+    expect(plugin.tCount('pears', 2)).toBe('pears.other');
+  });
+});