@caperjs/core 0.7.2 → 0.7.4

package/lib/ui/UICanvas.d.ts

@@ -29,17 +29,23 @@ export type UICanvasConfig = {
     padding: Padding;
     size: Size;
     useAppSize: boolean;
-    useSafeArea: boolean;
+    useSafeArea: UICanvasSafeArea;
     layout?: Omit<LayoutOptions, 'target'> | null | boolean;
     autoLayoutChildren?: boolean;
 };
+/**
+ * Which device safe-area insets the canvas pads by: `true` (all four, the default), `false`
+ * (none), or per edge, where an edge left out stays on. `{ top: false }` lets top-row UI sit
+ * in the camera strip of a punch-hole phone while the bottom still clears the gesture bar.
+ */
+export type UICanvasSafeArea = boolean | Partial<Record<keyof Padding, boolean>>;
 export declare const UICanvasConfigKeys: (keyof UICanvasConfig)[];
 export type UICanvasProps = {
     debug: boolean;
     padding: Partial<Padding> | PointLike;
     size?: SizeLike;
     useAppSize?: boolean;
-    useSafeArea?: boolean;
+    useSafeArea?: UICanvasSafeArea;
     layout?: Omit<LayoutOptions, 'target'> | null | boolean;
     autoLayoutChildren?: boolean;
 };
@@ -49,6 +55,8 @@ export type UICanvasProps = {
  * re-derived on every resize without compounding.
  */
 export declare function computeEffectivePadding(padding: Padding, safeArea: Padding): Padding;
+/** The safe-area insets `useSafeArea` keeps: all, none, or the edges not set to `false`. */
+export declare function resolveSafeArea(safeArea: Padding, useSafeArea: UICanvasSafeArea): Padding;
 declare const _UICanvas: (new () => import('..').IFactory<{
     existing: <TEntity>(entity: TEntity, props?: Partial<import('..').ExistingProps>) => TEntity;
     container: (props?: Partial<import('..').ContainerProps> | undefined) => Container;

package/lib/ui/UICanvas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"UICanvas.d.ts","sourceRoot":"","sources":["../../src/ui/UICanvas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"UICanvas.d.ts","sourceRoot":"","sources":["../../src/ui/UICanvas.ts"],"names":[],"mappings":"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"}

package/lib/utils/index.d.ts

@@ -13,6 +13,7 @@ export * from './math';
 export * from './misc';
 export * from './number';
 export * from './object';
+export * from './orientation';
 export * from './padding';
 export * from './pixi';
 export * from './platform';

package/lib/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,OAAO,CAAC;AACtB,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC"}

package/lib/utils/orientation.d.ts

@@ -0,0 +1,44 @@
+/** The orientation a game is locked to. */
+export type OrientationLock = 'portrait' | 'landscape';
+
+/** `orientation.overlay` in `caper.config.ts`: restyle or replace the web "rotate your device" overlay. */
+export interface OrientationOverlayOptions {
+  /** Default: "Rotate your device" (portrait) / "Turn your device sideways" (landscape). */
+  text?: string;
+  /** CSS background. Default `#000`. */
+  background?: string;
+  /** CSS text color. Default `#fff`. */
+  color?: string;
+  /** CSS font family. Default: the system font. */
+  fontFamily?: string;
+  /** Class(es) added to the overlay so a game can style it with its own CSS. */
+  className?: string;
+  /** Build the whole overlay yourself; replaces the default element. Called once, when first shown. */
+  element?: () => HTMLElement;
+}
+
+/**
+ * `orientation` in `caper.config.ts`: a lock, or `{ lock, overlay }`. The string
+ * form is shorthand for `{ lock }` with the default overlay. `overlay: false`
+ * turns off the web overlay and its pause.
+ */
+export type OrientationConfig =
+  | OrientationLock
+  | {
+      lock: OrientationLock;
+      overlay?: false | OrientationOverlayOptions;
+    };
+
+/** `orientation` normalized by `resolveOrientation`. */
+export interface ResolvedOrientation {
+  lock: OrientationLock;
+  /** `false` (no overlay, no pause) or the overlay options (`{}` for the default look). */
+  overlay: false | OrientationOverlayOptions;
+}
+
+/**
+ * `orientation` as `{ lock, overlay }`, or `null` when unset. The string form is
+ * shorthand for `{ lock }`; a missing `overlay` means the default overlay (`{}`).
+ * Throws a `TypeError` on anything else.
+ */
+export declare function resolveOrientation(orientation: unknown): ResolvedOrientation | null;

package/lib/utils/orientation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=orientation.test.d.ts.map

package/lib/utils/orientation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orientation.test.d.ts","sourceRoot":"","sources":["../../src/utils/orientation.test.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caperjs/core",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "title": "Caper",
   "description": "An opinionated HTML game framework built on PixiJS v8",
   "bin": {

package/src/core/Application.ts

@@ -65,6 +65,7 @@ import { type IDevToolsPlugin } from '../plugins/DevToolsPlugin';
 import { IFullScreenPlugin } from '../plugins/FullScreenPlugin';
 import { type IGSAPPlugin } from '../plugins/GSAPPlugin';
 import { ILookupPlugin } from '../plugins/LookupPlugin';
+import type { IOrientationPlugin } from '../plugins/OrientationPlugin';
 import { ITimerPlugin } from '../plugins/TimerPlugin';
 import { shouldEnableScreenDebug } from '../plugins/screenDebugFlag';
 import { Signal } from '../signals';
@@ -210,6 +211,7 @@ export class Application extends PIXIPApplication implements IApplication {
   protected _focusManager: IFocusManagerPlugin;
   protected _popupManager: IPopupManagerPlugin;
   protected _timerPlugin: ITimerPlugin;
+  protected _orientationPlugin: IOrientationPlugin;
   protected _audioManager: IAudioManagerPlugin;
   protected _voiceoverPlugin: IVoiceOverPlugin;
   protected _captionsPlugin: ICaptionsPlugin;
@@ -560,6 +562,14 @@ export class Application extends PIXIPApplication implements IApplication {
     return this._timerPlugin;
   }
 
+  /** The "rotate your device" guard for `orientation` in caper.config.ts: `mismatched`, `onMismatchChanged`. */
+  public get orientation(): IOrientationPlugin {
+    if (!this._orientationPlugin) {
+      this._orientationPlugin = this.getPlugin<IOrientationPlugin>('orientation');
+    }
+    return this._orientationPlugin;
+  }
+
   public get audio(): IAudioManagerPlugin {
     if (!this._audioManager) {
       this._audioManager = this.getPlugin<IAudioManagerPlugin>('audio');

package/src/core/interfaces/IApplicationOptions.ts

@@ -23,6 +23,7 @@ import type { TextStyle } from '../../mixins/factory/props';
 import type { CaptionsOptions } from '../../plugins/captions';
 import { GSAPPluginOptions } from '../../plugins/GSAPPlugin';
 import type { IDataAdapterOptions } from '../../plugins/DataAdapter';
+import type { OrientationConfig } from '../../utils/orientation';
 import type { PluginConfig } from '../config';
 import { IApplication } from './IApplication';
 
@@ -49,6 +50,26 @@ export interface IApplicationOptions extends ApplicationOptions {
    * @default false
    */
   useWasm?: boolean;
+  /**
+   * Lock the game to one orientation on every target. Unset means no lock.
+   * `'portrait'` / `'landscape'` is shorthand for `{ lock: 'portrait' }` etc.
+   *
+   * - `caper native android` sets `android:screenOrientation` on the
+   *   MainActivity (`portrait`, or `sensorLandscape` for landscape).
+   * - `caper native init` opens a 450x800 desktop window for portrait
+   *   (1280x720 otherwise).
+   * - The PWA web manifest's `orientation` defaults to the lock.
+   * - At runtime, on a mobile browser (never desktop, never Tauri), the
+   *   `orientation` plugin shows a "rotate your device" overlay and pauses the
+   *   game while the device is held the wrong way. `overlay` restyles it
+   *   (`text` / `background` / `color` / `fontFamily`), adds a `className`, or
+   *   replaces it (`element`); `overlay: false` turns off the overlay and its
+   *   pause, and `app.orientation.onMismatchChanged` still fires.
+   *
+   * The build and the CLI read the lock with an AST parse, so write the lock
+   * (the string, or `lock` in the object) as a string literal.
+   */
+  orientation?: OrientationConfig;
   /**
    * Enable the `window.Caper.automation[id]` facade for this app regardless of
    * environment. Automation is also auto-enabled in dev or when

package/src/plugins/OrientationPlugin.test.ts

@@ -0,0 +1,252 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const h = vi.hoisted(() => ({
+  platform: { isMobile: true, isTouch: true, isTauri: false },
+  app: null as any,
+}));
+
+vi.mock('../core', () => ({ coreFunctionRegistry: {}, coreSignalRegistry: {} }));
+vi.mock('../core/Application', () => ({
+  Application: { getInstance: () => h.app },
+}));
+vi.mock('../utils/platform', () => ({
+  get isMobile() {
+    return h.platform.isMobile;
+  },
+  get isTouch() {
+    return h.platform.isTouch;
+  },
+  get isTauri() {
+    return h.platform.isTauri;
+  },
+}));
+
+import { Signal } from '../signals';
+import { OrientationPlugin } from './OrientationPlugin';
+
+/** A `matchMedia('(orientation: portrait)')` whose answer the test flips. */
+function mockMatchMedia(portrait: boolean) {
+  const listeners = new Set<(event: { matches: boolean }) => void>();
+  const query = {
+    matches: portrait,
+    media: '(orientation: portrait)',
+    addEventListener: vi.fn((_type: string, fn: any) => listeners.add(fn)),
+    removeEventListener: vi.fn((_type: string, fn: any) => listeners.delete(fn)),
+  };
+  window.matchMedia = vi.fn(() => query) as any;
+  return {
+    query,
+    listeners,
+    rotate(toPortrait: boolean) {
+      query.matches = toPortrait;
+      for (const fn of [...listeners]) fn({ matches: toPortrait });
+    },
+  };
+}
+
+function makeApp(config: Record<string, unknown>) {
+  const app = {
+    config,
+    paused: false,
+    pause: vi.fn(() => {
+      app.paused = true;
+    }),
+    resume: vi.fn(() => {
+      app.paused = false;
+    }),
+    fullScreen: { onFullScreenChange: new Signal<(isFullscreen: boolean) => void>() },
+  };
+  return app;
+}
+
+const overlay = () => document.querySelector<HTMLElement>('[data-caper-orientation-overlay]');
+
+describe('OrientationPlugin', () => {
+  let plugin: OrientationPlugin;
+  const originalMatchMedia = window.matchMedia;
+
+  async function start(config: Record<string, unknown>) {
+    h.app = makeApp(config);
+    plugin = new OrientationPlugin();
+    // The config key `orientation` is the plugin id, so its value arrives as the options.
+    plugin.initialize(config.orientation as any);
+    await plugin.postInitialize(h.app);
+    return h.app;
+  }
+
+  beforeEach(() => {
+    h.platform = { isMobile: true, isTouch: true, isTauri: false };
+  });
+
+  afterEach(() => {
+    plugin?.destroy();
+    window.matchMedia = originalMatchMedia;
+    document.querySelectorAll('[data-caper-orientation-overlay]').forEach((node) => node.remove());
+  });
+
+  it('shows the overlay and pauses when the device is held the wrong way, from the start', async () => {
+    mockMatchMedia(false);
+    const app = await start({ orientation: 'portrait' });
+
+    expect(plugin.mismatched).toBe(true);
+    expect(app.pause).toHaveBeenCalledTimes(1);
+    expect(overlay()?.textContent).toBe('Rotate your device');
+  });
+
+  it('hides the overlay and resumes when the device turns the right way', async () => {
+    const media = mockMatchMedia(true);
+    const app = await start({ orientation: { lock: 'landscape' } });
+    expect(plugin.orientation).toBe('landscape');
+    expect(overlay()?.textContent).toBe('Turn your device sideways');
+    const changes: boolean[] = [];
+    plugin.onMismatchChanged.connect((mismatched) => changes.push(mismatched));
+
+    media.rotate(false);
+
+    expect(plugin.mismatched).toBe(false);
+    expect(overlay()).toBeNull();
+    expect(app.resume).toHaveBeenCalledTimes(1);
+    expect(app.paused).toBe(false);
+
+    media.rotate(true);
+    expect(overlay()).not.toBeNull();
+    expect(changes).toEqual([false, true]);
+  });
+
+  it('does nothing while the orientation matches', async () => {
+    mockMatchMedia(true);
+    const app = await start({ orientation: 'portrait' });
+    expect(plugin.active).toBe(true);
+    expect(plugin.mismatched).toBe(false);
+    expect(overlay()).toBeNull();
+    expect(app.pause).not.toHaveBeenCalled();
+  });
+
+  it('does not resume a game someone else paused', async () => {
+    const media = mockMatchMedia(true);
+    h.app = makeApp({ orientation: 'portrait' });
+    h.app.paused = true;
+    plugin = new OrientationPlugin();
+    plugin.initialize('portrait');
+    await plugin.postInitialize(h.app);
+
+    media.rotate(false);
+    expect(overlay()).not.toBeNull();
+    expect(h.app.pause).not.toHaveBeenCalled();
+
+    media.rotate(true);
+    expect(overlay()).toBeNull();
+    expect(h.app.resume).not.toHaveBeenCalled();
+    expect(h.app.paused).toBe(true);
+  });
+
+  it('with overlay: false shows no overlay and does not pause, but still signals', async () => {
+    const media = mockMatchMedia(true);
+    const app = await start({ orientation: { lock: 'portrait', overlay: false } });
+    const changes: boolean[] = [];
+    plugin.onMismatchChanged.connect((mismatched) => changes.push(mismatched));
+
+    media.rotate(false);
+
+    expect(plugin.mismatched).toBe(true);
+    expect(changes).toEqual([true]);
+    expect(overlay()).toBeNull();
+    expect(app.pause).not.toHaveBeenCalled();
+  });
+
+  it('is inert when orientation is unset', async () => {
+    mockMatchMedia(false);
+    const app = await start({});
+    expect(plugin.active).toBe(false);
+    expect(window.matchMedia).not.toHaveBeenCalled();
+    expect(overlay()).toBeNull();
+    expect(app.pause).not.toHaveBeenCalled();
+  });
+
+  it('is inert on a desktop browser', async () => {
+    h.platform = { isMobile: false, isTouch: false, isTauri: false };
+    mockMatchMedia(false);
+    const app = await start({ orientation: 'portrait' });
+    expect(plugin.active).toBe(false);
+    expect(overlay()).toBeNull();
+    expect(app.pause).not.toHaveBeenCalled();
+  });
+
+  it('is inert on a touchscreen laptop, which is not a phone or tablet', async () => {
+    h.platform = { isMobile: false, isTouch: true, isTauri: false };
+    mockMatchMedia(false);
+    const app = await start({ orientation: 'portrait' });
+    expect(plugin.active).toBe(false);
+    expect(overlay()).toBeNull();
+    expect(app.pause).not.toHaveBeenCalled();
+  });
+
+  it('is inert inside Tauri, where the manifest locks the orientation', async () => {
+    h.platform = { isMobile: true, isTouch: true, isTauri: true };
+    mockMatchMedia(false);
+    const app = await start({ orientation: 'portrait' });
+    expect(plugin.active).toBe(false);
+    expect(overlay()).toBeNull();
+    expect(app.pause).not.toHaveBeenCalled();
+  });
+
+  it('applies custom text, colors, font and className to the default element', async () => {
+    mockMatchMedia(false);
+    await start({
+      orientation: {
+        lock: 'portrait',
+        overlay: { text: 'Hold it upright', background: 'rgb(10, 20, 30)', color: 'rgb(1, 2, 3)', fontFamily: 'Parlour', className: 'my-rotate' },
+      },
+    });
+
+    const el = overlay()!;
+    expect(el.textContent).toBe('Hold it upright');
+    expect(el.style.background).toContain('rgb(10, 20, 30)');
+    expect(el.style.color).toBe('rgb(1, 2, 3)');
+    expect(el.style.fontFamily).toContain('Parlour');
+    expect(el.classList.contains('my-rotate')).toBe(true);
+    expect(el.style.position).toBe('fixed');
+  });
+
+  it('uses a custom element in place of the default one', async () => {
+    mockMatchMedia(false);
+    const custom = document.createElement('section');
+    custom.textContent = 'custom';
+    const element = vi.fn(() => custom);
+    await start({ orientation: { lock: 'portrait', overlay: { element } } });
+
+    expect(custom.isConnected).toBe(true);
+    expect(custom.dataset.caperOrientationOverlay).toBeDefined();
+    expect(custom.textContent).toBe('custom');
+    expect(element).toHaveBeenCalledTimes(1);
+  });
+
+  it('locks the screen orientation on entering fullscreen, swallowing a rejection', async () => {
+    mockMatchMedia(true);
+    const lock = vi.fn(() => Promise.reject(new Error('not supported')));
+    Object.defineProperty(screen, 'orientation', { configurable: true, value: { lock } });
+    try {
+      const app = await start({ orientation: 'landscape' });
+      app.fullScreen.onFullScreenChange.emit(true);
+      expect(lock).toHaveBeenCalledWith('landscape');
+      app.fullScreen.onFullScreenChange.emit(false);
+      expect(lock).toHaveBeenCalledTimes(1);
+      await Promise.resolve();
+    } finally {
+      delete (screen as any).orientation;
+    }
+  });
+
+  it('cleans up on destroy: removes the overlay, the listener, and resumes what it paused', async () => {
+    const media = mockMatchMedia(false);
+    const app = await start({ orientation: 'portrait' });
+    expect(overlay()).not.toBeNull();
+
+    plugin.destroy();
+
+    expect(overlay()).toBeNull();
+    expect(media.listeners.size).toBe(0);
+    expect(app.resume).toHaveBeenCalledTimes(1);
+    expect(app.fullScreen.onFullScreenChange.hasConnections()).toBe(false);
+  });
+});

package/src/plugins/OrientationPlugin.ts

@@ -0,0 +1,178 @@
+import type { IApplication } from '../core/interfaces/IApplication';
+import { Signal } from '../signals';
+import { isMobile, isTauri } from '../utils/platform';
+import type { OrientationConfig, OrientationLock as Orientation, OrientationOverlayOptions } from '../utils/orientation';
+import { resolveOrientation } from '../utils/orientation';
+import type { IPlugin } from './Plugin';
+import { Plugin } from './Plugin';
+
+export interface IOrientationPlugin extends IPlugin {
+  /** The lock from `caper.config.ts`'s `orientation`, or `undefined` when unset. */
+  readonly orientation: Orientation | undefined;
+  /** Whether the plugin is watching at all: orientation set, a touch/mobile device, not Tauri. */
+  readonly active: boolean;
+  /** Whether the device is currently held the wrong way. */
+  readonly mismatched: boolean;
+  /** Fires when `mismatched` changes. Still fires with `orientation: { lock, overlay: false }`. */
+  onMismatchChanged: Signal<(mismatched: boolean) => void>;
+}
+
+export const ORIENTATION_OVERLAY_TEXT: Readonly<Record<Orientation, string>> = Object.freeze({
+  portrait: 'Rotate your device',
+  landscape: 'Turn your device sideways',
+});
+
+const OVERLAY_ATTRIBUTE = 'data-caper-orientation-overlay';
+
+type LockableOrientation = ScreenOrientation & { lock?: (orientation: string) => Promise<void> };
+
+/**
+ * The web "rotate your device" guard for `orientation` in `caper.config.ts`.
+ *
+ * Only on a touch/mobile browser outside Tauri (native apps are locked by their
+ * manifests; desktop browsers never see it). While the device is held the
+ * wrong way it shows a full-screen DOM overlay and pauses the app, then hides
+ * it and resumes when the device turns back. It only resumes a pause it made
+ * itself. Entering fullscreen also asks `screen.orientation.lock` for the
+ * orientation (works on Android Chrome; a rejection is ignored).
+ */
+export class OrientationPlugin extends Plugin implements IOrientationPlugin {
+  public readonly id = 'orientation';
+
+  public onMismatchChanged: Signal<(mismatched: boolean) => void> = new Signal<(mismatched: boolean) => void>();
+
+  private _orientation: Orientation | undefined;
+  private _overlayOptions: OrientationOverlayOptions | false = {};
+  private _active = false;
+  private _mismatched = false;
+  /** Whether *this* plugin is the one that paused the app. */
+  private _didPause = false;
+  private _query: MediaQueryList | null = null;
+  private _overlay: HTMLElement | null = null;
+
+  public get orientation(): Orientation | undefined {
+    return this._orientation;
+  }
+
+  public get active(): boolean {
+    return this._active;
+  }
+
+  public get mismatched(): boolean {
+    return this._mismatched;
+  }
+
+  /**
+   * `options` is `caper.config.ts`'s `orientation` itself: the config key is
+   * this plugin's id, so `loadPlugin` hands the value over as the options.
+   */
+  public initialize(options?: OrientationConfig | unknown): void {
+    const resolved = resolveOrientation(options);
+    this._orientation = resolved?.lock;
+    this._overlayOptions = resolved?.overlay ?? {};
+  }
+
+  // The work happens in postInitialize: pausing reaches into the audio and timer
+  // plugins, which register after this one.
+  public postInitialize(_app?: IApplication): void {
+    if (!this._orientation) return;
+
+    if (!isMobile || isTauri) return;
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+
+    this._active = true;
+    this._query = window.matchMedia('(orientation: portrait)');
+    this.listen(this._query, 'change', this._check);
+    this.addDisposer(this._teardown);
+
+    const onFullScreenChange = this.app.fullScreen?.onFullScreenChange;
+    if (onFullScreenChange) {
+      this.addSignalConnection(onFullScreenChange.connect(this._onFullScreenChange));
+    }
+
+    this._check();
+  }
+
+  private _check(): void {
+    if (!this._query || !this._orientation) return;
+    const mismatched = this._query.matches !== (this._orientation === 'portrait');
+    if (mismatched === this._mismatched) return;
+    this._mismatched = mismatched;
+
+    if (this._overlayOptions !== false) {
+      if (mismatched) {
+        this._showOverlay();
+        this._pause();
+      } else {
+        this._hideOverlay();
+        this._resume();
+      }
+    }
+
+    this.onMismatchChanged.emit(mismatched);
+  }
+
+  private _onFullScreenChange(isFullscreen: boolean): void {
+    if (!isFullscreen || typeof screen === 'undefined') return;
+    const screenOrientation = screen.orientation as LockableOrientation | undefined;
+    try {
+      void screenOrientation?.lock?.(this._orientation === 'landscape' ? 'landscape' : 'portrait')?.catch?.(() => {});
+    } catch {
+      // No lock on this browser (iOS); the overlay still covers it.
+    }
+  }
+
+  private _showOverlay(): void {
+    if (typeof document === 'undefined') return;
+    if (!this._overlay) this._overlay = this._createOverlay();
+    if (!this._overlay.isConnected) document.body.appendChild(this._overlay);
+  }
+
+  private _hideOverlay(): void {
+    this._overlay?.remove();
+  }
+
+  private _createOverlay(): HTMLElement {
+    const options = this._overlayOptions || {};
+    let el: HTMLElement;
+    if (options.element) {
+      el = options.element();
+    } else {
+      el = document.createElement('div');
+      el.textContent = options.text ?? ORIENTATION_OVERLAY_TEXT[this._orientation!];
+      el.setAttribute('role', 'alert');
+      el.style.cssText =
+        'position:fixed;inset:0;z-index:2147483647;display:flex;align-items:center;justify-content:center;' +
+        'padding:24px;box-sizing:border-box;text-align:center;font-size:24px;line-height:1.3;font-weight:600;' +
+        'touch-action:none;user-select:none;-webkit-user-select:none;pointer-events:auto;';
+      el.style.background = options.background ?? '#000';
+      el.style.color = options.color ?? '#fff';
+      el.style.fontFamily = options.fontFamily ?? 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif';
+    }
+    el.setAttribute(OVERLAY_ATTRIBUTE, '');
+    if (options.className) el.classList.add(...options.className.split(/\s+/).filter(Boolean));
+    return el;
+  }
+
+  /** Pause the app, but only if nothing else already did, and remember that we did. */
+  private _pause(): void {
+    if (this.app.paused) return;
+    this.app.pause();
+    this._didPause = true;
+  }
+
+  /** Resume the app, but only if this plugin is the one that paused it. */
+  private _resume(): void {
+    if (!this._didPause) return;
+    this._didPause = false;
+    this.app.resume();
+  }
+
+  private _teardown(): void {
+    this._hideOverlay();
+    this._overlay = null;
+    this._resume();
+    this._query = null;
+    this._active = false;
+  }
+}

package/src/plugins/defaults.ts

@@ -3,6 +3,7 @@ import { AssetsPlugin } from './AssetsPlugin';
 import { FullScreenPlugin } from './FullScreenPlugin';
 import { KeyboardPlugin } from './KeyboardPlugin';
 import { LookupPlugin } from './LookupPlugin';
+import { OrientationPlugin } from './OrientationPlugin';
 import type { IPlugin } from './Plugin';
 import { PopupManagerPlugin } from './PopupManagerPlugin';
 import { ResizerPlugin } from './ResizerPlugin';
@@ -98,4 +99,9 @@ export const defaultPlugins: ImportList<IPlugin> = [
     module: TimerPlugin,
     namedExport: 'TimerPlugin',
   },
+  {
+    id: 'orientation',
+    module: OrientationPlugin,
+    namedExport: 'OrientationPlugin',
+  },
 ] as const;

package/src/plugins/index.ts

@@ -10,6 +10,7 @@ export * from './i18nPlugin';
 export * from './input';
 export * from './KeyboardPlugin';
 export * from './LookupPlugin';
+export * from './OrientationPlugin';
 export * from './Plugin';
 export * from './PopupManagerPlugin';
 export * from './ResizerPlugin';