@mpgd/target-config 0.19.0 → 0.21.0

package/README.md

@@ -0,0 +1,45 @@
+# Target configuration
+
+Target-specific feature availability, effective configuration and viewport helpers.
+
+## Responsive game shell
+
+`@mpgd/target-config/adaptive-shell` is an opt-in DOM entrypoint over the existing
+viewport composition APIs. Import `@mpgd/target-config/adaptive-shell/base.css`
+before application paint styles; every selector has zero specificity.
+
+```ts
+import { mountAdaptiveGameShell, waitForAdaptiveShellViewport } from '@mpgd/target-config/adaptive-shell';
+const initialMeasurement = await waitForAdaptiveShellViewport(gameRoot);
+const shell = mountAdaptiveGameShell({ gameRoot, runtime,
+  initialMeasurement, policy: { gameAspectRatio: 3 / 4, minRailWidth: 160 } });
+const stop = shell.subscribe(({ composition }) => resizeGame(composition.gameBounds));
+// Teardown: stop(); shell.destroy();
+```
+
+The shell applies safe bounds to the stage and optional left/right rails. Aspect
+ratio, rail threshold, panel slots (at most 64), element IDs/classes and all visual
+content remain consumer-owned. Authored slots define a readiness data attribute,
+a CSS variable prefix, min/max width, gutter and minimum rail height; their
+left/top/width variables are written on the owning document root. Inputs are
+snapshotted before observation starts and invalid policy/slot/measurement inputs
+fail before DOM restructuring.
+Each live controller reserves its slot variable prefixes in the owning document.
+Another stage using one of those prefixes fails before either stage is changed;
+destroy releases them, and replacing the same stage transfers ownership. Separate
+documents may reuse the same prefixes.
+
+ResizeObserver, window and visual-viewport events coalesce through one animation
+frame. A new controller for the same stage disposes its previous owner. Destroy
+is idempotent, detaches observers/listeners, ignores late callbacks and clears
+slot variables. It leaves the shell/stage/rails and their bounds in the DOM;
+remove those elements separately if the page outlives the game. Embedded stages
+use their own document/window. Subscriber errors do not skip other listeners and
+are rethrown in a microtask for the host's error reporting. Importing the module
+creates no observers, elements or listeners and does not load a platform SDK.
+
+Startup waits accept `{ signal }` so teardown can cancel a still-unmeasurable
+surface and detach observation. Fixed shells prefer visual-viewport dimensions
+and follow its resize/scroll offsets; document-root panel variables include those
+offsets. This covers keyboard/zoom changes that leave layout-viewport dimensions
+unchanged ([VisualViewport reference](https://developer.mozilla.org/en-US/docs/Web/API/VisualViewport)).

package/adaptive-shell.css

@@ -0,0 +1,46 @@
+/* @mpgd/target-config/adaptive-shell base geometry.
+ *
+ * Only the layout mechanism lives here: a fixed full-viewport shell, an absolutely positioned
+ * stage and rails whose inline bounds are written by `mountAdaptiveGameShell`, and the safe-area
+ * tokens it reads back. Every selector is wrapped in :where() so any game rule overrides it
+ * without specificity work. Backgrounds, borders, shadows, touch policy and container names
+ * are game-owned. */
+
+:where(:root) {
+  --mpgd-safe-area-top: env(safe-area-inset-top, 0px);
+  --mpgd-safe-area-right: env(safe-area-inset-right, 0px);
+  --mpgd-safe-area-bottom: env(safe-area-inset-bottom, 0px);
+  --mpgd-safe-area-left: env(safe-area-inset-left, 0px);
+}
+
+:where([data-game-shell]) {
+  position: fixed;
+  inset: 0;
+  overflow: hidden;
+  isolation: isolate;
+}
+
+:where([data-game-shell-stage]) {
+  position: absolute;
+  z-index: 2;
+  box-sizing: border-box;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  isolation: isolate;
+  /* Stage-relative cq* units resolve against the stage, not the outer window. */
+  container-type: size;
+}
+
+:where([data-game-shell-stage] canvas) {
+  display: block;
+  width: 100%;
+  height: 100%;
+}
+
+:where([data-game-shell-rail]) {
+  position: absolute;
+  z-index: 1;
+  box-sizing: border-box;
+  overflow: hidden;
+}

package/dist/adaptive-shell/index.d.ts

@@ -0,0 +1,2 @@
+export { assertAdaptiveShellPolicy, assertAdaptiveShellRailSlot, assertAdaptiveShellRailSlots, resolveAdaptiveShellComposition, resolveAdaptiveShellRailBounds, resolveAdaptiveShellRailSlot, type AdaptiveShellPolicy, type AdaptiveShellRailSide, type AdaptiveShellRailSlot, type AdaptiveShellRailSlotPlacement, type AdaptiveShellReservedNames, } from './policy.js';
+export { adaptiveShellAttributes, adaptiveShellReservedVariablePrefixes, defaultAdaptiveShellId, mountAdaptiveGameShell, waitForAdaptiveShellViewport, type AdaptiveGameShellController, type AdaptiveGameShellState, type AdaptiveShellElementNames, type MountAdaptiveGameShellInput, } from './shell.js';

package/dist/adaptive-shell/index.js

@@ -0,0 +1,2 @@
+export { assertAdaptiveShellPolicy, assertAdaptiveShellRailSlot, assertAdaptiveShellRailSlots, resolveAdaptiveShellComposition, resolveAdaptiveShellRailBounds, resolveAdaptiveShellRailSlot, } from './policy.js';
+export { adaptiveShellAttributes, adaptiveShellReservedVariablePrefixes, defaultAdaptiveShellId, mountAdaptiveGameShell, waitForAdaptiveShellViewport, } from './shell.js';

package/dist/adaptive-shell/policy.d.ts

@@ -0,0 +1,60 @@
+import { type TargetViewportBounds, type TargetViewportComposition, type TargetViewportOrientationPolicy, type TargetViewportSnapshot } from '../viewport.js';
+/**
+* Game-owned stage policy. The shell owns the mechanism; each game adapter owns these numbers.
+*/
+export interface AdaptiveShellPolicy {
+  /** Stage width divided by height when expanded viewports render side rails, e.g. `3 / 4`. */
+  readonly gameAspectRatio: number;
+  /** Narrowest rail that still justifies side rails; narrower viewports use the full bounds. */
+  readonly minRailWidth: number;
+  /** Orientation policy passed to the viewport snapshot. Defaults to `responsive`. */
+  readonly orientationPolicy?: TargetViewportOrientationPolicy;
+}
+export type AdaptiveShellRailSide = 'left' | 'right';
+/**
+* A centered panel slot inside one rail, such as a tutorial popover or an idle-game upgrade list.
+* The slot is ready only when the rail can hold `minWidth` plus the inline gutter and is at least
+* `minRailHeight` tall; its width then grows with the rail up to `maxWidth`.
+*/
+export interface AdaptiveShellRailSlot {
+  readonly rail: AdaptiveShellRailSide;
+  /** Shell attribute set to `"true"` while the slot is placed, e.g. `data-tutorial-rail-ready`. */
+  readonly readyAttribute: `data-${string}`;
+  /** Root custom-property prefix; the shell writes `<prefix>-left`, `-top` and `-width`. */
+  readonly cssVariablePrefix: `--${string}`;
+  readonly minWidth: number;
+  readonly maxWidth: number;
+  /** Total horizontal space kept free around the slot (split evenly on both sides). */
+  readonly inlineGutter: number;
+  readonly minRailHeight: number;
+}
+/** Viewport-pixel placement of a ready rail slot: centered on `left + width / 2` and on `top`. */
+export interface AdaptiveShellRailSlotPlacement {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+}
+/**
+* Reject a policy the shared composition would refuse, using the same rules as
+* `@mpgd/target-config`, so mount can fail before it restructures the DOM.
+*/
+export declare function assertAdaptiveShellPolicy(policy: Pick<AdaptiveShellPolicy, 'gameAspectRatio' | 'minRailWidth'>): void;
+/** Apply a game's stage aspect and rail policy to shared target viewport geometry. */
+export declare function resolveAdaptiveShellComposition(viewport: TargetViewportSnapshot, policy: Pick<AdaptiveShellPolicy, 'gameAspectRatio' | 'minRailWidth'>): TargetViewportComposition;
+/** Rail bounds for one side, or `undefined` when the composition renders no side rails. */
+export declare function resolveAdaptiveShellRailBounds(composition: TargetViewportComposition, side: AdaptiveShellRailSide): TargetViewportBounds | undefined;
+/** Fit a centered slot into rail bounds, or return `undefined` when the rail is too small. */
+export declare function resolveAdaptiveShellRailSlot(railBounds: TargetViewportBounds | undefined, slot: Pick<AdaptiveShellRailSlot, 'minWidth' | 'maxWidth' | 'inlineGutter' | 'minRailHeight'>): AdaptiveShellRailSlotPlacement | undefined;
+/** Reject slot definitions that could never place, or that would write unscoped names. */
+export declare function assertAdaptiveShellRailSlot(slot: AdaptiveShellRailSlot): void;
+/** Names a slot must not take because the shell itself writes or reads them. */
+export interface AdaptiveShellReservedNames {
+  readonly attributes?: readonly string[];
+  readonly variablePrefixes?: readonly string[];
+}
+/**
+* Validate a slot set. Slots share the shell element and the document root, so a repeated ready
+* attribute or variable prefix, or one the shell reserves, would overwrite or clear another
+* slot's placement or the shell's own state.
+*/
+export declare function assertAdaptiveShellRailSlots(slots: readonly AdaptiveShellRailSlot[], reserved?: AdaptiveShellReservedNames): void;

package/dist/adaptive-shell/policy.js

@@ -0,0 +1,86 @@
+import { resolveTargetViewportComposition, } from '../viewport.js';
+/**
+ * Reject a policy the shared composition would refuse, using the same rules as
+ * `@mpgd/target-config`, so mount can fail before it restructures the DOM.
+ */
+export function assertAdaptiveShellPolicy(policy) {
+    if (!Number.isFinite(policy.gameAspectRatio) || policy.gameAspectRatio <= 0) {
+        throw new RangeError('Adaptive shell gameAspectRatio must be a positive finite number.');
+    }
+    if (!Number.isFinite(policy.minRailWidth) || policy.minRailWidth < 0) {
+        throw new RangeError('Adaptive shell minRailWidth must be a non-negative finite number.');
+    }
+}
+/** Apply a game's stage aspect and rail policy to shared target viewport geometry. */
+export function resolveAdaptiveShellComposition(viewport, policy) {
+    return resolveTargetViewportComposition({
+        viewport,
+        expandedLayout: 'side-rails',
+        gameAspectRatio: policy.gameAspectRatio,
+        minRailWidth: policy.minRailWidth,
+    });
+}
+/** Rail bounds for one side, or `undefined` when the composition renders no side rails. */
+export function resolveAdaptiveShellRailBounds(composition, side) {
+    if (composition.mode !== 'side-rails') {
+        return undefined;
+    }
+    return side === 'left' ? composition.leftRailBounds : composition.rightRailBounds;
+}
+/** Fit a centered slot into rail bounds, or return `undefined` when the rail is too small. */
+export function resolveAdaptiveShellRailSlot(railBounds, slot) {
+    if (railBounds === undefined
+        || railBounds.width < slot.minWidth + slot.inlineGutter
+        || railBounds.height < slot.minRailHeight) {
+        return undefined;
+    }
+    const width = Math.min(slot.maxWidth, railBounds.width - slot.inlineGutter);
+    return {
+        left: railBounds.x + (railBounds.width - width) / 2,
+        top: railBounds.y + railBounds.height / 2,
+        width,
+    };
+}
+/** Reject slot definitions that could never place, or that would write unscoped names. */
+export function assertAdaptiveShellRailSlot(slot) {
+    if (slot.rail !== 'left' && slot.rail !== 'right') {
+        throw new TypeError(`Rail slot ${slot.readyAttribute} rail must be 'left' or 'right': ${String(slot.rail)}`);
+    }
+    for (const key of ['minWidth', 'maxWidth', 'inlineGutter', 'minRailHeight']) {
+        if (!Number.isFinite(slot[key]) || slot[key] < 0) {
+            throw new RangeError(`Rail slot ${slot.readyAttribute} ${key} must be a finite non-negative number.`);
+        }
+    }
+    if (slot.maxWidth < slot.minWidth) {
+        throw new RangeError(`Rail slot ${slot.readyAttribute} maxWidth must not be less than minWidth.`);
+    }
+    if (!/^data-[a-z][a-z0-9-]*$/u.test(slot.readyAttribute)) {
+        throw new TypeError(`Rail slot readyAttribute must be a lower-case data-* name: ${slot.readyAttribute}`);
+    }
+    if (!/^--[a-zA-Z][\w-]*$/u.test(slot.cssVariablePrefix)) {
+        throw new TypeError(`Rail slot cssVariablePrefix must be a custom-property name: ${slot.cssVariablePrefix}`);
+    }
+}
+/**
+ * Validate a slot set. Slots share the shell element and the document root, so a repeated ready
+ * attribute or variable prefix, or one the shell reserves, would overwrite or clear another
+ * slot's placement or the shell's own state.
+ */
+export function assertAdaptiveShellRailSlots(slots, reserved = {}) {
+    if (slots.length > 64) {
+        throw new RangeError('Adaptive shell supports at most 64 rail slots.');
+    }
+    const readyAttributes = new Set(reserved.attributes);
+    const variablePrefixes = new Set(reserved.variablePrefixes);
+    for (const slot of slots) {
+        assertAdaptiveShellRailSlot(slot);
+        if (readyAttributes.has(slot.readyAttribute)) {
+            throw new TypeError(`Rail slot readyAttribute is already in use: ${slot.readyAttribute}`);
+        }
+        if (variablePrefixes.has(slot.cssVariablePrefix)) {
+            throw new TypeError(`Rail slot cssVariablePrefix is already in use: ${slot.cssVariablePrefix}`);
+        }
+        readyAttributes.add(slot.readyAttribute);
+        variablePrefixes.add(slot.cssVariablePrefix);
+    }
+}

package/dist/adaptive-shell/shell.d.ts

@@ -0,0 +1,71 @@
+import type { TargetRuntimeKind } from '../runtime.js';
+import { type TargetViewportComposition, type TargetViewportMeasurement, type TargetViewportSnapshot } from '../viewport.js';
+import { type AdaptiveShellPolicy, type AdaptiveShellRailSlot } from './policy.js';
+/**
+* DOM attributes the shell owns. `base.css` selects the marker attributes; game stylesheets may
+* select the state attributes. Element ids and class names stay game-owned.
+*/
+export declare const adaptiveShellAttributes: {
+  /** Marker on the outer full-viewport shell element. */
+  readonly shell: 'data-game-shell';
+  /** Marker on the game mount (the stage). */
+  readonly stage: 'data-game-shell-stage';
+  /** `left` or `right` on each rail element. */
+  readonly rail: 'data-game-shell-rail';
+  /** Shell: `side-rails`, `bottom-controls` or `compact-portrait`. */
+  readonly compositionMode: 'data-composition-mode';
+  /** Shell: where primary controls belong for the current composition. */
+  readonly primaryControls: 'data-primary-controls';
+  /** Stage: the same composition mode, for selectors scoped under the game mount. */
+  readonly layoutMode: 'data-layout-mode';
+  /** Stage: `portrait` or `landscape` from the measured viewport layout. */
+  readonly viewportOrientation: 'data-viewport-orientation';
+};
+/** Element naming for a shell the package creates. Defaults to `#game-shell` with no classes. */
+export interface AdaptiveShellElementNames {
+  readonly shellId?: string;
+  readonly shellClassName?: string;
+  readonly railClassName?: string;
+}
+export declare const defaultAdaptiveShellId = "game-shell";
+/**
+* Root custom-property prefixes the shell reads back (`--mpgd-safe-area-top`, ...). A rail slot
+* using one would shadow the safe-area tokens and skew every composition.
+*/
+export declare const adaptiveShellReservedVariablePrefixes: readonly ['--mpgd-safe-area'];
+export interface AdaptiveGameShellState {
+  readonly composition: TargetViewportComposition;
+  readonly viewport: TargetViewportSnapshot;
+}
+export interface AdaptiveGameShellController {
+  readonly shell: HTMLElement;
+  readonly stage: HTMLElement;
+  readonly leftRail: HTMLElement;
+  readonly rightRail: HTMLElement;
+  readonly state: AdaptiveGameShellState;
+  readonly subscribe: (listener: (state: AdaptiveGameShellState) => void) => () => void;
+  /**
+  * Stop observing and clear rail slots. The shell, rails, attributes and inline bounds stay in
+  * the DOM; the game owns unmounting them, usually by unloading the page.
+  */
+  readonly destroy: () => void;
+}
+export interface MountAdaptiveGameShellInput {
+  /** The game mount. It becomes the stage between the two rails. */
+  readonly gameRoot: HTMLElement;
+  readonly runtime: TargetRuntimeKind;
+  readonly policy: AdaptiveShellPolicy;
+  /** Measurement already obtained from `waitForAdaptiveShellViewport`. */
+  readonly initialMeasurement?: TargetViewportMeasurement | undefined;
+  readonly elements?: AdaptiveShellElementNames;
+  readonly railSlots?: readonly AdaptiveShellRailSlot[];
+}
+/** Wait for host layout instead of booting the engine with a zero-sized viewport. */
+export declare function waitForAdaptiveShellViewport(container: HTMLElement, options?: {
+  readonly signal?: AbortSignal;
+}): Promise<TargetViewportMeasurement>;
+/**
+* Mount the full-viewport shell around `gameRoot` and keep stage/rail bounds in sync.
+* An existing ancestor with the shell id is reused when it already contains both rails.
+*/
+export declare function mountAdaptiveGameShell(input: MountAdaptiveGameShellInput): AdaptiveGameShellController;