@caperjs/core 0.2.2 → 0.2.3

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');
+  });
+});

package/src/plugins/i18nPlugin.ts

@@ -17,6 +17,17 @@ export type LocaleKey = AppTypeOverrides extends { LocaleKeys: infer K extends s
   ? K | (string & {})
   : string;
 
+/**
+ * Base keys that have plural leaves (i.e. a `<base>.other` entry exists in the
+ * reference locale). These are the keys `tCount()` accepts.
+ *
+ * `(string & {})` preserves autocomplete for known keys while still
+ * accepting dynamic strings.
+ */
+export type PluralLocaleKey = AppTypeOverrides extends { LocaleKeys: infer K extends string }
+  ? (K extends `${infer B}.other` ? B : never) | (string & {})
+  : string;
+
 /**
  * Type definition for i18n dictionary.
  */
@@ -73,6 +84,8 @@ export interface Ii18nPlugin extends IPlugin {
 
   t(key: LocaleKey, params?: i18nTParams, locale?: string): string;
 
+  tCount(key: PluralLocaleKey, count: number, params?: i18nTParams, locale?: string): string;
+
   parse(input: string, locale?: string): string;
 }
 
@@ -152,10 +165,13 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
 
   /**
    * Translates a key into a string.
-   * If the key is not found, it will return an empty string.
+   * If the key is not found (or no dictionary is loaded), it returns the key itself, so a typo
+   * renders visibly on screen instead of blanking the UI.
    * If the key is found, it will replace any placeholders in the string with the values from the params object.
-   * If the key contains a variant, it will select a random variant if the variant param is set to 'random'.
-   * If the key contains a number variant, it will select the variant based on the variant param.
+   * Every `[a|b|c]` group in the string is resolved, whether or not params were passed:
+   * `variant: 'random'` picks a random item per group, `variant: <number>` picks that index for every
+   * group (clamped to the group's last item), and with no variant param index 0 is used. Brackets never
+   * survive into the output.
    * @param key The key to translate.
    * @param params The parameters to replace in the string.
    * @param locale The locale to use for translation.
@@ -166,7 +182,7 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
     const dict = this._dicts[locale];
     if (!dict) {
       Logger.error(`i18n:: No dictionary loaded for current locale: ${locale}`);
-      return '';
+      return key as string;
     }
     // Dot-path resolution: `t('obj.nested')` walks the dict tree. Flat keys
     // still work (including keys that literally contain dots, via the
@@ -176,24 +192,26 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
 
     if (!str) {
       Logger.error(`i18n:: No result found for the key ${key} in the locale: ${this._locale}`);
-      return '';
+      return key as string;
     }
 
-    if (params) {
-      if (typeof params.variant === 'number' || params.variant === 'random') {
-        const match = /\[(.*?)\]/.exec(str);
-        if (match) {
-          // Split the string by the "|" character to get an array of variations.
-          const items = match[1].split('|');
-
-          // Get the selected variant based on the "variation" param.
-          const num = params.variant === 'random' ? Math.floor(Math.random() * items.length) : params.variant;
+    // Resolve every `[a|b|c]` group, whether or not params were passed, so brackets
+    // never leak into the rendered string.
+    const variant = params?.variant;
+    str = str.replace(/\[(.*?)\]/g, (_match, group: string) => {
+      // Split the group by the "|" character to get an array of variations.
+      const items = group.split('|');
 
-          // Replace the original string with the selected variant
-          str = str.replace(match[0], items[num]);
-        }
+      if (variant === 'random') {
+        return items[Math.floor(Math.random() * items.length)];
       }
 
+      // A number picks that index for every group, clamped to the group's last item.
+      const num = typeof variant === 'number' ? Math.min(Math.max(variant, 0), items.length - 1) : 0;
+      return items[num];
+    });
+
+    if (params) {
       // Iterate over all params to replace placeholders in the string.
       for (const f in params) {
         // Create a regular expression to match the placeholder for the current param.
@@ -221,6 +239,27 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
     return this.t(key, params, locale);
   }
 
+  /**
+   * Translates a pluralised key using the locale's own plural rules.
+   * The CLDR plural category for `count` (`one`, `other`, `few`, ...) is resolved against
+   * `<key>.<category>`, falling back to `<key>.other` when that leaf does not exist.
+   * `count` is passed through as a param, so `{count}` interpolates and variants still apply.
+   * @param key The base key holding the plural leaves.
+   * @param count The count used to pick the plural category.
+   * @param params Additional parameters to replace in the string.
+   * @param locale The locale to use for translation.
+   * @returns The translated string.
+   */
+  tCount(key: PluralLocaleKey, count: number, params?: i18nTParams, locale: string = this._locale): string {
+    const category = new Intl.PluralRules(locale).select(count);
+    const dict = this._dicts[locale];
+    let pluralKey = `${key}.${category}`;
+    if (!dict || typeof resolveLocalePath(dict, pluralKey) !== 'string') {
+      pluralKey = `${key}.other`;
+    }
+    return this.t(pluralKey, { count, ...params }, locale);
+  }
+
   /**
    * Parses the input string and replaces anything in between {} braces, assuming it is a key in the dictionary.
    * @param {string} input
@@ -263,7 +302,7 @@ export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
   }
 
   protected getCoreFunctions(): string[] {
-    return ['t', 'translate', 'setLocale'];
+    return ['t', 'translate', 'tCount', 'setLocale'];
   }
 
   protected getCoreSignals(): string[] {

package/src/plugins/input/keyboard/KeyboardContols.ts

@@ -1,5 +1,5 @@
 import { Application } from '../../../core/Application';
-import { WithSignals } from '../../../mixins';
+import { WithSignals } from '../../../mixins/signals';
 import { bindAllMethods } from '../../../utils';
 import type { Action } from '../../actions';
 import { normalizeKey, type KeyboardEventDetail } from '../../KeyboardPlugin';

package/src/plugins/input/touch/VirtualControls.ts

@@ -3,8 +3,8 @@ import type { ControlsActionMap, JoystickControlsScheme, TouchControlsMap, Touch
 
 import { JoystickDirection } from '..';
 import { Application } from '../../../core/Application';
-import { WithSignals } from '../../../mixins';
-import { type IButton, type IJoystick } from '../../../ui';
+import { WithSignals } from '../../../mixins/signals';
+import type { IButton, IJoystick } from '../../../ui';
 import type { Action } from '../../actions';
 import { AbstractControls } from '../AbstractControls';
 

package/src/plugins/spine/pixi-spine/require-shim.ts

@@ -28,7 +28,9 @@
  *****************************************************************************/
 
 declare global {
-  var require: any;
+  // @types/node (present via typeRoots) already declares `require: Require`;
+  // redeclaring it as `any` is a TS2403 conflict, so declare only what node
+  // doesn't, and keep the shim's loose typing at the use sites below.
   var PIXI: any;
 }