@caperjs/core 0.1.0

package/src/mixins/factory/const.ts

@@ -0,0 +1,363 @@
+import { BitmapText, Graphics, HTMLText, Sprite, Text, TilingSprite } from 'pixi.js';
+
+import { AnimatedSprite, Container, ContainerConfigKeys, SpineAnimation, Svg } from '../../display';
+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 type { EntityId, EntityInstance, EntityProps, UIId, UIInstance, UIProps } from '../../utils';
+import { pluck, resolvePointLike, Spine, WithRequiredProps } from '../../utils';
+
+import type { EntityFactoryProps } from './props';
+import {
+  AnimatedSpriteProps,
+  BitmapTextProps,
+  ButtonProps,
+  ContainerProps,
+  ExistingProps,
+  FlexContainerProps,
+  GraphicsProps,
+  HTMLTextProps,
+  ParticleContainerProps,
+  SpineProps,
+  SpriteProps,
+  SvgProps,
+  TextProps,
+  TilingSpriteProps,
+  UICanvasFactoryProps,
+} from './props';
+import { getEntityCtor, getRegisteredEntityIds } from './registry';
+import { getUICtor, getRegisteredUIIds } from './ui-registry';
+import { buildFactoryMethod } from './schema';
+import {
+  resolveAnchor,
+  resolvePivot,
+  resolvePosition,
+  resolveScale,
+  resolveTexture,
+  resolveUnknownKeys,
+} from './utils';
+
+/**
+ * Keys consumed by text-family factory builds (`text`, `htmlText`,
+ * `bitmapText`). Shared here so the three schemas don't drift — each one
+ * flattens `{text, style, roundPixels, resolution, anchor, pivot}` into
+ * the Pixi constructor options in `build`, so all those keys must be
+ * excluded from the schema's unknown-keys passthrough.
+ */
+const TEXT_CONSUMED_KEYS = ['text', 'roundPixels', 'resolution', 'style', 'anchor', 'pivot'] as const;
+
+/**
+ * Factory method table consumed by the `Factory()` mixin. Almost every
+ * entry is built via `buildFactoryMethod({ build, applies, exclude })`:
+ * the `build` callback owns the bespoke constructor call (including any
+ * DX reshaping Caper applies — asset-name resolution, text style
+ * flattening, config-vs-extras splits), and the helper centralizes
+ * position/scale/pivot/anchor + unknown-keys passthrough.
+ *
+ * The five bespoke entries (`existing`, `texture`, `svg`, `toaster`,
+ * `entity`) don't fit the `(props?) → instance` shape — `existing` takes
+ * `(entity, props)`, `texture` is a plain resolver re-bind, `svg` takes
+ * a required `ctx` field, `toaster` takes two config objects, and
+ * `entity` takes `(id, props)` with a generic narrowed to discovered
+ * entity ids — so they stay hand-written.
+ */
+export const defaultFactoryMethods = {
+  existing: <TEntity>(entity: TEntity, props?: Partial<ExistingProps>): TEntity => {
+    if (!props) return entity;
+    const { position, x, y, pivot, scale, scaleX, scaleY, ...rest } = props;
+    resolvePosition({ position, x, y }, entity);
+    resolveScale({ scale, scaleX, scaleY }, entity);
+    resolvePivot(pivot, entity);
+    resolveUnknownKeys(rest, entity);
+    return entity;
+  },
+
+  container: buildFactoryMethod({
+    build: (props?: Partial<ContainerProps>): Container =>
+      new Container(props ? pluck(props, ContainerConfigKeys) : undefined),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: ContainerConfigKeys as readonly string[],
+  }),
+
+  particleContainer: buildFactoryMethod({
+    build: (props?: Partial<ParticleContainerProps>): ParticleContainer =>
+      new ParticleContainer(props ? pluck(props, ParticleContainerConfigKeys) : undefined),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: ParticleContainerConfigKeys as readonly string[],
+  }),
+
+  texture: resolveTexture,
+
+  sprite: buildFactoryMethod({
+    build: (props?: Partial<SpriteProps>) =>
+      new Sprite(props ? resolveTexture(props) : undefined),
+    applies: ['position', 'scale', 'pivot', 'anchor'],
+    exclude: ['asset', 'sheet'],
+  }),
+
+  tilingSprite: buildFactoryMethod({
+    build: (props?: Partial<TilingSpriteProps>) =>
+      new TilingSprite(props ? resolveTexture(props) : undefined),
+    applies: ['position', 'scale', 'pivot', 'anchor'],
+    exclude: ['asset', 'sheet'],
+  }),
+
+  animatedSprite: buildFactoryMethod({
+    // AnimatedSprite's Caper-side constructor consumes the full props bag
+    // (animations, autoPlay, autoUpdate, sheet, texturePrefix, etc.), so
+    // the schema's `build` just forwards them. Position/scale/pivot are
+    // applied by the helper from the same object.
+    build: (props?: Partial<AnimatedSpriteProps>): AnimatedSprite => new AnimatedSprite(props),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: [
+      'sheet',
+      'texturePrefix',
+      'zeroPad',
+      'animations',
+      'autoPlay',
+      'autoUpdate',
+      'defaultAnimation',
+      'reversible',
+      'animationSpeed',
+      'startIndex',
+      'animation',
+    ],
+  }),
+
+  graphics: buildFactoryMethod({
+    build: (_props?: Partial<GraphicsProps>) => new Graphics(),
+    applies: ['position', 'scale', 'pivot'],
+  }),
+
+  svg(props: WithRequiredProps<SvgProps, 'ctx'>) {
+    const entity = new Svg(props.ctx);
+    const { position, x, y, pivot, scale, scaleX, scaleY, ctx: _ctx, ...rest } = props;
+    resolvePosition({ position, x, y }, entity);
+    resolveScale({ scale, scaleX, scaleY }, entity);
+    resolvePivot(pivot, entity);
+    resolveUnknownKeys(rest, entity);
+    return entity;
+  },
+
+  text: buildFactoryMethod({
+    // Text flattens Pixi's nested `style: {...}` into top-level props for
+    // DX (e.g. `{fontFamily, fontSize, fill}` without the `style:` wrapper
+    // — see TextStyle type in props.ts). The build callback rebuilds the
+    // Pixi-shape options object, including `anchor`/`pivot` pre-resolved
+    // via `resolvePointLike(..., true)` the way the hand-written method
+    // did. Post-construct resolvers handle position/scale/pivot.
+    build: (props?: Partial<TextProps>) =>
+      new Text(
+        props
+          ? {
+              text: props.text,
+              roundPixels: props.roundPixels,
+              resolution: props.resolution,
+              style: props.style,
+              anchor: props.anchor ? resolvePointLike(props.anchor, true) : undefined,
+              pivot: props.pivot ? resolvePointLike(props.pivot, true) : undefined,
+            }
+          : {},
+      ),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: [...TEXT_CONSUMED_KEYS],
+  }),
+
+  htmlText: buildFactoryMethod({
+    build: (props?: Partial<HTMLTextProps>) =>
+      new HTMLText(
+        props
+          ? {
+              text: props.text,
+              roundPixels: props.roundPixels,
+              resolution: props.resolution,
+              style: props.style,
+              anchor: props.anchor ? resolvePointLike(props.anchor, true) : undefined,
+              pivot: props.pivot ? resolvePointLike(props.pivot, true) : undefined,
+            }
+          : {},
+      ),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: [...TEXT_CONSUMED_KEYS],
+  }),
+
+  bitmapText: buildFactoryMethod({
+    // BitmapText's ctor doesn't take `resolution` — that's the only field
+    // that differs from Text/HTMLText here.
+    build: (props?: Partial<BitmapTextProps>) =>
+      new BitmapText(
+        props
+          ? {
+              text: props.text,
+              roundPixels: props.roundPixels,
+              style: props.style,
+              anchor: props.anchor ? resolvePointLike(props.anchor, true) : undefined,
+              pivot: props.pivot ? resolvePointLike(props.pivot, true) : undefined,
+            }
+          : {},
+      ),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: [...TEXT_CONSUMED_KEYS],
+  }),
+
+  button: buildFactoryMethod({
+    build: (props?: Partial<ButtonProps>): Button =>
+      new Button((props ? pluck(props, ButtonConfigKeys) : undefined) as Partial<ButtonConfig>),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: ButtonConfigKeys as readonly string[],
+  }),
+
+  flexContainer: buildFactoryMethod({
+    // FlexContainer takes the full props bag (minus position/scale/pivot)
+    // as its constructor config — historical: the hand-written method
+    // passed `props as Partial<FlexContainerConfig>` directly rather than
+    // plucking FlexContainerConfigKeys. Preserving that shape.
+    build: (props?: Partial<FlexContainerProps>): FlexContainer =>
+      new FlexContainer(props as Partial<FlexContainerConfig>),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: FlexContainerConfigKeys as readonly string[],
+  }),
+
+  uiCanvas: buildFactoryMethod({
+    build: (props?: Partial<UICanvasFactoryProps>): UICanvas =>
+      // UICanvas's ctor takes Partial<UICanvasProps>, which is a superset
+      // of UICanvasConfig — the pluck narrows, so cast back.
+      new UICanvas(props ? (pluck(props, UICanvasConfigKeys) as Partial<UICanvasProps>) : ({} as Partial<UICanvasProps>)),
+    applies: ['position', 'scale', 'pivot'],
+    exclude: UICanvasConfigKeys as readonly string[],
+  }),
+
+  spine: buildFactoryMethod({
+    build: (props?: Partial<SpineProps>): Spine => {
+      // Resolve Caper's `{data: 'spine/foo'}` shorthand into the Pixi
+      // `{skeleton, atlas}` pair expected by Spine.from().
+      let spineData: { skeleton: string; atlas: string } | string = '';
+      const data = props?.data;
+      if (typeof data === 'string') {
+        // If the asset name is missing an extension, default to .json. If
+        // it has one, strip it so we can re-append both skeleton + atlas
+        // paths from the base name.
+        let ext = data.slice(-5);
+        if (ext !== '.json' && ext !== '.skel') {
+          ext = '.json';
+        } else {
+          spineData = data.substring(0, data.length - 5);
+        }
+        spineData = { skeleton: data + ext, atlas: data + '.atlas' };
+      }
+      const entity: Spine = (window as unknown as { Spine: { from: (d: unknown) => Spine } }).Spine.from(
+        spineData,
+      );
+      // Spine-specific post-construct setup. Has to happen here (not in
+      // `applies`) because the helper doesn't know about spine state.
+      if (props?.autoUpdate !== undefined) entity.autoUpdate = props.autoUpdate;
+      if (props?.animationName) {
+        entity.state.setAnimation(props.trackIndex ?? 0, props.animationName, props.loop);
+      }
+      return entity;
+    },
+    applies: ['position', 'scale', 'pivot', 'anchor'],
+    exclude: ['data', 'autoUpdate', 'animationName', 'trackIndex', 'loop'],
+  }),
+
+  spineAnimation: <ANames extends string = string>(
+    props?: Partial<SpineProps>,
+  ): SpineAnimation<ANames> => {
+    // Hand-written rather than schema-driven because `buildFactoryMethod`
+    // can't carry the `<ANames>` generic through to the call site —
+    // kitchen-sink's SpineScene narrows the animation-name union via
+    // `this.add.spineAnimation<CharacterAnimations>({...})`, which
+    // requires the method itself to declare the generic.
+    const entity = new SpineAnimation<ANames>(props);
+    if (!props) return entity;
+    const { position, x, y, anchor, pivot, scale, scaleX, scaleY, ...rest } = props;
+    resolvePosition({ position, x, y }, entity);
+    resolveScale({ scale, scaleX, scaleY }, entity);
+    resolveAnchor(anchor, entity);
+    resolvePivot(pivot, entity);
+    resolveUnknownKeys(rest, entity);
+    return entity;
+  },
+
+  toaster: (toasterConfig?: Partial<ToasterConfig>, defaultToastConfig: Partial<ToastConfig> = {}): Toaster => {
+    return new Toaster(toasterConfig, defaultToastConfig);
+  },
+
+  /**
+   * Construct an entity from the auto-discovered registry. `id` is narrowed
+   * to the union of entity ids declared under `src/entities/` (see the
+   * generated `caper-app.d.ts`), and `props` is typed from the entity's
+   * constructor signature via `ConstructorParameters<typeof Entity>[0]`.
+   *
+   * Throws if `id` isn't registered. Discovery runs at build time, so the
+   * only way to hit this at runtime is a stale virtual module — fail loud
+   * and list the known ids so the user can see what's wrong.
+   *
+   * @example
+   *   this.add.entity('actor', { color: 0xff0000, x: 50, y: 100 });
+   */
+  entity: <K extends EntityId>(
+    id: K,
+    props?: EntityProps<K> & EntityFactoryProps,
+  ): EntityInstance<K> => {
+    const Ctor = getEntityCtor(id as string);
+    if (!Ctor) {
+      const known = getRegisteredEntityIds();
+      throw new Error(
+        `[caper] Unknown entity id '${String(id)}'. ` +
+          `Known: ${known.length > 0 ? known.map((k) => `'${k}'`).join(', ') : '(none — discovery may have failed)'}`,
+      );
+    }
+    const instance = new (Ctor as new (props?: EntityProps<K>) => EntityInstance<K>)(props);
+    if (props) {
+      const { position, x, y, pivot, scale, scaleX, scaleY, alpha, visible } = props as EntityFactoryProps;
+      resolvePosition({ position, x, y }, instance);
+      resolveScale({ scale, scaleX, scaleY }, instance);
+      resolvePivot(pivot, instance);
+      if (alpha !== undefined) (instance as unknown as { alpha: number }).alpha = alpha;
+      if (visible !== undefined) (instance as unknown as { visible: boolean }).visible = visible;
+    }
+    return instance;
+  },
+
+  /**
+   * Construct a UI element from the auto-discovered registry. `id` is
+   * narrowed to the union of UI ids declared under `src/ui/` (see the
+   * generated `caper-app.d.ts`), and `props` is typed from the UI
+   * element's constructor signature via `ConstructorParameters<...>[0]`.
+   *
+   * @example
+   *   this.add.ui('close-button', { x: 100, y: 50 });
+   */
+  ui: <K extends UIId>(
+    id: K,
+    props?: UIProps<K> & EntityFactoryProps,
+  ): UIInstance<K> => {
+    const Ctor = getUICtor(id as string);
+    if (!Ctor) {
+      const known = getRegisteredUIIds();
+      throw new Error(
+        `[caper] Unknown ui id '${String(id)}'. ` +
+          `Known: ${known.length > 0 ? known.map((k) => `'${k}'`).join(', ') : '(none — discovery may have failed)'}`,
+      );
+    }
+    const instance = new (Ctor as new (props?: UIProps<K>) => UIInstance<K>)(props);
+    if (props) {
+      const { position, x, y, pivot, scale, scaleX, scaleY, alpha, visible } = props as EntityFactoryProps;
+      resolvePosition({ position, x, y }, instance);
+      resolveScale({ scale, scaleX, scaleY }, instance);
+      resolvePivot(pivot, instance);
+      if (alpha !== undefined) (instance as unknown as { alpha: number }).alpha = alpha;
+      if (visible !== undefined) (instance as unknown as { visible: boolean }).visible = visible;
+    }
+    return instance;
+  },
+};

package/src/mixins/factory/index.ts

@@ -0,0 +1,7 @@
+export * from './methods';
+export * from './const';
+export * from './props';
+export * from './utils';
+export * from './Factory';
+export { getRegisteredEntityIds } from './registry';
+export { getRegisteredUIIds } from './ui-registry';

package/src/mixins/factory/methods.ts

@@ -0,0 +1,21 @@
+import { defaultFactoryMethods } from './index';
+
+export function createFactoryMethods<T extends typeof defaultFactoryMethods = typeof defaultFactoryMethods>(
+  methods: Partial<T>,
+  instance: any,
+  addToStage: boolean,
+): T {
+  const factoryMethods: any = {};
+  for (const key in methods) {
+    factoryMethods[key] = (...args: any[]) => {
+      // @ts-expect-error - this is fine
+      const obj = methods[key](...args);
+      if (addToStage) {
+        instance.addChild(obj);
+        // instance.addChild(obj);
+      }
+      return obj;
+    };
+  }
+  return factoryMethods as T;
+}

package/src/mixins/factory/props.ts

@@ -0,0 +1,207 @@
+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 {
+  BitmapFontFamilyAsset,
+  FontFamilyAsset,
+  PointLike,
+  SpineAsset,
+  SpritesheetAsset,
+  TextureAsset,
+  WithRequiredProps,
+} from '../../utils';
+
+export interface AbstractProps {
+  [key: string]: any;
+}
+
+export interface TextureProps {
+  asset: TextureAsset;
+  sheet: SpritesheetAsset;
+}
+
+export interface PositionProps {
+  x: number;
+  y: number;
+  position: PointLike;
+}
+
+export interface ScaleProps {
+  scaleX: number;
+  scaleY: number;
+  scale: PointLike;
+}
+
+export interface PivotProps {
+  pivot: PointLike;
+}
+
+export interface VisibilityProps {
+  alpha: number;
+  visible: boolean;
+}
+
+export interface LayoutProps {
+  layout?: Omit<LayoutOptions, 'target'> | null | boolean;
+}
+
+export interface ExistingProps extends AbstractProps, PositionProps, ScaleProps, VisibilityProps, LayoutProps {}
+
+/**
+ * Layout-ish props the `this.add.entity(id, props)` factory applies after
+ * construction — intentionally narrow (no `AbstractProps` index signature)
+ * so TypeScript can still narrow entity-specific props at the call site.
+ */
+export interface EntityFactoryProps
+  extends Partial<PositionProps>,
+    Partial<ScaleProps>,
+    Partial<PivotProps>,
+    Partial<VisibilityProps> {}
+
+export interface GraphicsProps extends AbstractProps, PositionProps, ScaleProps, PivotProps, VisibilityProps {}
+
+export interface SvgProps extends GraphicsProps {
+  ctx: string | GraphicsContext;
+}
+
+export interface SpriteProps
+  extends AbstractProps,
+    TextureProps,
+    ScaleProps,
+    PositionProps,
+    VisibilityProps,
+    LayoutProps {
+  anchor: PointLike;
+}
+
+export interface TilingSpriteProps extends SpriteProps {
+  tilePosition?: PointLike;
+  /**
+   * Scaling of the image that is being tiled.
+   * @default {x: 1, y: 1}
+   */
+  tileScale?: PointLike;
+  /**
+   * The rotation of the image that is being tiled.
+   * @default 0
+   */
+  tileRotation?: number;
+  /**
+   * The texture to use for the sprite.
+   * @default Texture.WHITE
+   */
+  /**
+   * The width of the tiling sprite. #
+   * @default 256
+   */
+  width?: number;
+  /**
+   * The height of the tiling sprite.
+   * @default 256
+   */
+  height?: number;
+  /**
+   * @default false
+   */
+  applyAnchorToTexture?: boolean;
+  /** Whether or not to round the x/y position. */
+  roundPixels?: boolean;
+}
+
+export interface AnimatedSpriteAnimationProps
+  extends AbstractProps,
+    ScaleProps,
+    PositionProps,
+    VisibilityProps,
+    LayoutProps {
+  texturePrefix: string;
+  sheet: SpritesheetAsset;
+  startIndex: number;
+  numFrames: number;
+  zeroPad: number;
+  autoUpdate: boolean;
+  updateAnchor: boolean;
+  loop: boolean;
+  animationSpeed: number;
+}
+
+export interface AnimatedSpriteProps extends AbstractProps, ScaleProps, PositionProps, VisibilityProps, LayoutProps {
+  sheet: SpritesheetAsset;
+  texturePrefix: string;
+  zeroPad: number;
+  animations: { [animationName: string]: Partial<AnimatedSpriteAnimationProps> };
+  autoPlay: boolean;
+  autoUpdate: boolean;
+  defaultAnimation: string;
+  reversible: boolean;
+  animationSpeed: number;
+  startIndex: number;
+}
+
+export type TextStyle = Partial<Omit<TextStyleOptions, 'fontFamily'> & { fontFamily: FontFamilyAsset }>;
+
+export interface TextProps extends AbstractProps, PositionProps, ScaleProps, VisibilityProps, LayoutProps {
+  text: string;
+  anchor: PointLike;
+  resolution: number;
+  roundPixels: boolean;
+  style: TextStyle;
+}
+
+export interface BitmapTextProps extends AbstractProps, PositionProps, ScaleProps, VisibilityProps, LayoutProps {
+  text: string;
+  anchor: PointLike;
+  resolution: number;
+  roundPixels: boolean;
+  style: Partial<Omit<TextStyleOptions, 'fontFamily'> & { fontFamily: BitmapFontFamilyAsset }>;
+}
+
+export interface HTMLTextProps extends AbstractProps, PositionProps, ScaleProps, VisibilityProps, LayoutProps {
+  text: string;
+  anchor: PointLike;
+  resolution: number;
+  roundPixels: boolean;
+  style: Partial<Omit<HTMLTextStyleOptions, 'fontFamily'> & { fontFamily: FontFamilyAsset }>;
+}
+
+export interface OmittedTextProps extends AbstractProps, PositionProps, ScaleProps, VisibilityProps {}
+
+export const TextPropsKeys: (keyof TextProps)[] = ['text', 'anchor', 'roundPixels', 'style', 'pivot'];
+
+export interface ContainerProps
+  extends AbstractProps,
+    PositionProps,
+    ScaleProps,
+    PivotProps,
+    VisibilityProps,
+    LayoutProps,
+    ContainerConfig {}
+
+export interface ParticleContainerProps extends AbstractProps, ParticleContainerConfig {}
+
+export interface FlexContainerProps extends ContainerProps, FlexContainerConfig {}
+
+export interface UICanvasFactoryProps extends ContainerProps, UICanvasProps {}
+
+// spine
+export interface SpineProps extends AbstractProps, ScaleProps, PositionProps, VisibilityProps, LayoutProps {
+  data: SpineAsset;
+  autoUpdate: boolean;
+  animationName: string;
+  trackIndex: number;
+  loop: boolean;
+  paused: boolean;
+}
+
+interface _ButtonProps
+  extends AbstractProps,
+    ScaleProps,
+    PositionProps,
+    PivotProps,
+    VisibilityProps,
+    ButtonConfig,
+    LayoutProps {}
+
+export type ButtonProps = WithRequiredProps<_ButtonProps, 'textures'>;

package/src/mixins/factory/registry.test.ts

@@ -0,0 +1,83 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { _resetEntityRegistry, getEntityCtor, getRegisteredEntityIds } from './registry';
+
+// The registry reads from `globalThis.Caper.get('entityList')` on first
+// access — the caper-runtime virtual module normally populates this. In
+// tests we stub it manually.
+function stubGlobalEntityList(list: unknown): void {
+  (globalThis as unknown as { Caper: { get: (key: string) => unknown } }).Caper = {
+    get: (key: string) => (key === 'entityList' ? list : undefined),
+  };
+}
+
+class FakeActor {
+  constructor(public props?: { color?: number }) {}
+}
+
+class FakeBoy {
+  constructor() {}
+}
+
+describe('entity registry', () => {
+  beforeEach(() => {
+    _resetEntityRegistry();
+    delete (globalThis as unknown as { Caper?: unknown }).Caper;
+  });
+
+  it('registers static-import entities from globalThis.Caper.entityList on first access', () => {
+    stubGlobalEntityList([
+      { id: 'actor', active: true, module: FakeActor },
+      { id: 'boy', active: true, module: FakeBoy },
+    ]);
+    expect(getRegisteredEntityIds().sort()).toEqual(['actor', 'boy']);
+    expect(getEntityCtor('actor')).toBe(FakeActor);
+    expect(getEntityCtor('boy')).toBe(FakeBoy);
+  });
+
+  it('skips inactive entries', () => {
+    stubGlobalEntityList([
+      { id: 'actor', active: true, module: FakeActor },
+      { id: 'inactive', active: false, module: FakeBoy },
+    ]);
+    expect(getRegisteredEntityIds()).toEqual(['actor']);
+    expect(getEntityCtor('inactive')).toBeUndefined();
+  });
+
+  it('skips dynamic-import entries (arrow functions without prototypes)', () => {
+    const dynamicLoader = () => Promise.resolve({ default: FakeBoy });
+    stubGlobalEntityList([
+      { id: 'actor', active: true, module: FakeActor },
+      { id: 'lazy', active: true, module: dynamicLoader },
+    ]);
+    // Only the static-import entry is registered — sync `this.add.entity`
+    // can't wait for a dynamic import.
+    expect(getRegisteredEntityIds()).toEqual(['actor']);
+    expect(getEntityCtor('lazy')).toBeUndefined();
+  });
+
+  it('returns undefined for unknown ids without throwing', () => {
+    stubGlobalEntityList([{ id: 'actor', active: true, module: FakeActor }]);
+    expect(getEntityCtor('nonexistent')).toBeUndefined();
+  });
+
+  it('handles missing globalThis.Caper gracefully (empty registry)', () => {
+    // No stub set — Caper is undefined.
+    expect(getRegisteredEntityIds()).toEqual([]);
+    expect(getEntityCtor('anything')).toBeUndefined();
+  });
+
+  it('caches the registry after first lookup (list only read once)', () => {
+    let readCount = 0;
+    (globalThis as unknown as { Caper: { get: (key: string) => unknown } }).Caper = {
+      get: (key: string) => {
+        if (key === 'entityList') readCount++;
+        return [{ id: 'actor', active: true, module: FakeActor }];
+      },
+    };
+    getEntityCtor('actor');
+    getEntityCtor('actor');
+    getRegisteredEntityIds();
+    expect(readCount).toBe(1);
+  });
+});