@jgengine/core 0.9.0 → 0.10.0

package/dist/scene/colliders.js

@@ -1,12 +1,20 @@
 export const DEFAULT_ENTITY_HIT_RADIUS = 0.5;
 export const DEFAULT_OBJECT_HALF_EXTENTS = [0.5, 0.5, 0.5];
+/** Matches the shell's fallback actor capsule (~0.7m wide, feet at y=0 to head at ~1.8m). */
+export const DEFAULT_ENTITY_BODY_HALF_EXTENTS = [0.35, 0.9, 0.35];
+/** Entity-local center of the default body hitbox (half its height above the feet). */
+export const DEFAULT_ENTITY_BODY_OFFSET = [0, 0.9, 0];
 export function defaultEntityColliders() {
     return {
         hitboxes: [
             {
                 name: "body",
                 purpose: "damage",
-                shape: { kind: "sphere", radius: DEFAULT_ENTITY_HIT_RADIUS },
+                shape: {
+                    kind: "aabb",
+                    halfExtents: DEFAULT_ENTITY_BODY_HALF_EXTENTS,
+                    offset: DEFAULT_ENTITY_BODY_OFFSET,
+                },
                 damageEligible: true,
                 blocks: false,
             },
@@ -24,6 +32,22 @@ export function defaultObjectColliders(halfExtents = DEFAULT_OBJECT_HALF_EXTENTS
         },
     };
 }
+/** Blocking physical body derived from an object's rendered scale: a grounded box spanning the visual (base at y=0, matching the shell's fallback mesh). */
+export function scaledObjectColliders(scale) {
+    return {
+        body: {
+            name: "body",
+            purpose: "physical",
+            shape: {
+                kind: "aabb",
+                halfExtents: [scale[0] / 2, scale[1] / 2, scale[2] / 2],
+                offset: [0, scale[1] / 2, 0],
+            },
+            damageEligible: false,
+            blocks: true,
+        },
+    };
+}
 export function resolveColliders(set) {
     if (set === null || set === undefined)
         return [];

package/dist/scene/entityStats.d.ts

@@ -28,6 +28,10 @@ export declare function getStatValue(map: StatValueMap, statId: string): StatVal
 export declare function setStatValue(map: StatValueMap, statId: string, patch: StatValuePatch): StatValueMap;
 export declare function applyPoolDelta(map: StatValueMap, statId: string, amount: number): PoolDeltaResult;
 export declare function seedStatValues(catalogStats: StatCatalog): StatValueMap;
+/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}. */
+export declare function snapshotEntityStats(store: ReadonlyMap<string, StatValueMap>): Record<string, StatValueMap>;
+/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it. */
+export declare function hydrateEntityStats(store: Map<string, StatValueMap>, data: Record<string, StatValueMap>): void;
 export interface EntityStatsApi {
     get(instanceId: string, statId: string): StatValue | null;
     set(instanceId: string, statId: string, patch: StatValuePatch): boolean;

package/dist/scene/entityStats.js

@@ -35,6 +35,27 @@ export function seedStatValues(catalogStats) {
     }
     return map;
 }
+/** Deep-copy the per-entity stat maps into a serializable record — the transport counterpart of {@link hydrateEntityStats}. */
+export function snapshotEntityStats(store) {
+    const out = {};
+    for (const [instanceId, map] of store) {
+        const copy = {};
+        for (const [statId, value] of Object.entries(map))
+            copy[statId] = { ...value };
+        out[instanceId] = copy;
+    }
+    return out;
+}
+/** Replace a live stat store with deep copies of a snapshot, clearing entities absent from it. */
+export function hydrateEntityStats(store, data) {
+    store.clear();
+    for (const [instanceId, map] of Object.entries(data)) {
+        const copy = {};
+        for (const [statId, value] of Object.entries(map))
+            copy[statId] = { ...value };
+        store.set(instanceId, copy);
+    }
+}
 export function createEntityStatsApi(resolve) {
     return {
         get(instanceId, statId) {

package/dist/scene/entityStore.d.ts

@@ -65,6 +65,28 @@ export type EntityUpdatePatch<TMeta = unknown> = Partial<Pick<SceneEntity<TMeta>
     /** Accepts the same friendly shapes as `spawn`/`setPose` (#286.13). Raw patch semantics — velocity is not derived; use `setPose` with `dt` for that. */
     position?: SpawnPositionInput;
 };
+/**
+ * Per-entity scratch and cooldown timers, auto-cleared on despawn (#533.8) — the home for AI state
+ * (next-shot-at, alert level) that would otherwise be smuggled through the serializable `meta` or a
+ * hand-pruned module-level map. Keys share one namespace per entity: `arm`/`ready`/`remaining` store a
+ * deadline under a key, `get`/`set` store arbitrary scratch.
+ */
+export interface EntityBlackboard {
+    /** Read a scratch value; `undefined` if unset or the entity has despawned. */
+    get<T>(id: string, key: string): T | undefined;
+    /** Write a scratch value; does not notify subscribers, and clears when the entity despawns. */
+    set(id: string, key: string, value: unknown): void;
+    has(id: string, key: string): boolean;
+    delete(id: string, key: string): void;
+    /** Drop all scratch and timers for one entity. */
+    clear(id: string): void;
+    /** Arm a cooldown for `key` that stays busy until absolute time `untilMs`. */
+    arm(id: string, key: string, untilMs: number): void;
+    /** True when no cooldown is armed for `key`, or its deadline has passed. */
+    ready(id: string, key: string, nowMs: number): boolean;
+    /** Milliseconds until the armed cooldown elapses; 0 when ready. */
+    remaining(id: string, key: string, nowMs: number): number;
+}
 export interface EntityStore<TMeta = unknown> {
     spawn(name: string, options?: SpawnOptions<TMeta>): string;
     despawn(id: string): boolean;
@@ -77,7 +99,14 @@ export interface EntityStore<TMeta = unknown> {
     clear(): void;
     subscribe(listener: () => void): () => void;
     snapshot(): readonly SceneEntity<TMeta>[];
+    /**
+     * Apply a `snapshot()` (e.g. from an authoritative host) to this store — the counterpart of `snapshot()`
+     * for host→client world mirroring: spawns entities present in the snapshot but not here, overwrites
+     * existing ones field-for-field (including velocity), and despawns any local entity absent from it.
+     */
+    hydrate(entities: readonly SceneEntity<TMeta>[]): void;
     spawnPoseOf(id: string): SpawnPose | null;
     resetToSpawn(id: string): boolean;
+    blackboard: EntityBlackboard;
 }
 export declare function createEntityStore<TMeta = unknown>(): EntityStore<TMeta>;

package/dist/scene/entityStore.js

@@ -21,7 +21,34 @@ export function createEntityStore() {
     const store = createObservableKeyedStore();
     const spawnPoses = new Map();
     const constraints = new Map();
+    const blackboards = new Map();
     let nextCounter = 1;
+    const blackboard = {
+        get: (id, key) => blackboards.get(id)?.get(key),
+        set(id, key, value) {
+            const board = blackboards.get(id) ?? new Map();
+            board.set(key, value);
+            blackboards.set(id, board);
+        },
+        has: (id, key) => blackboards.get(id)?.has(key) ?? false,
+        delete(id, key) {
+            blackboards.get(id)?.delete(key);
+        },
+        clear(id) {
+            blackboards.delete(id);
+        },
+        arm(id, key, untilMs) {
+            this.set(id, key, untilMs);
+        },
+        ready(id, key, nowMs) {
+            const until = blackboards.get(id)?.get(key);
+            return typeof until !== "number" || nowMs >= until;
+        },
+        remaining(id, key, nowMs) {
+            const until = blackboards.get(id)?.get(key);
+            return typeof until === "number" ? Math.max(0, until - nowMs) : 0;
+        },
+    };
     function generateId() {
         let id = `entity-${nextCounter}`;
         while (store.has(id)) {
@@ -39,6 +66,7 @@ export function createEntityStore() {
                     return options.id;
                 if (onExisting === "throw")
                     throw new Error(`Scene entity id "${options.id}" is already spawned.`);
+                blackboards.delete(options.id);
             }
             const id = options.id ?? generateId();
             const position = toEntityPosition(options.position);
@@ -64,6 +92,7 @@ export function createEntityStore() {
             store.delete(id);
             spawnPoses.delete(id);
             constraints.delete(id);
+            blackboards.delete(id);
             return existed;
         },
         update(id, patch) {
@@ -143,6 +172,7 @@ export function createEntityStore() {
                 store.delete(entity.id);
             }
             constraints.clear();
+            blackboards.clear();
         },
         subscribe(listener) {
             return store.subscribe(listener);
@@ -150,6 +180,35 @@ export function createEntityStore() {
         snapshot() {
             return store.arraySnapshot();
         },
+        hydrate(entities) {
+            const incoming = new Set(entities.map((entity) => entity.id));
+            for (const current of store.arraySnapshot()) {
+                if (!incoming.has(current.id)) {
+                    store.delete(current.id);
+                    spawnPoses.delete(current.id);
+                    constraints.delete(current.id);
+                    blackboards.delete(current.id);
+                }
+            }
+            for (const entity of entities) {
+                store.set(entity.id, {
+                    id: entity.id,
+                    name: entity.name,
+                    position: entity.position,
+                    rotationY: entity.rotationY,
+                    rotationX: entity.rotationX,
+                    rotationZ: entity.rotationZ,
+                    velocity: entity.velocity,
+                    role: entity.role,
+                    movement: entity.movement,
+                    behaviors: entity.behaviors,
+                    meta: entity.meta,
+                });
+                if (!spawnPoses.has(entity.id)) {
+                    spawnPoses.set(entity.id, { position: entity.position, rotationY: entity.rotationY });
+                }
+            }
+        },
         spawnPoseOf(id) {
             return spawnPoses.get(id) ?? null;
         },
@@ -164,5 +223,6 @@ export function createEntityStore() {
             store.set(id, current);
             return true;
         },
+        blackboard,
     };
 }

package/dist/store/observableKeyedStore.d.ts

@@ -6,5 +6,9 @@ export interface ObservableKeyedStore<T> {
     subscribe(listener: () => void): () => void;
     mapSnapshot(): ReadonlyMap<string, T>;
     arraySnapshot(): readonly T[];
+    /** Serializable `[key, value]` entries — the transport counterpart of {@link hydrate} for host→client mirroring. */
+    snapshot(): readonly (readonly [string, T])[];
+    /** Replace all entries with `data` (clears keys absent from it), emitting once. */
+    hydrate(data: readonly (readonly [string, T])[]): void;
 }
 export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>;

package/dist/store/observableKeyedStore.js

@@ -44,5 +44,14 @@ export function createObservableKeyedStore(areEqual) {
             }
             return arrayCache;
         },
+        snapshot() {
+            return Array.from(store.entries());
+        },
+        hydrate(data) {
+            store.clear();
+            for (const [key, value] of data)
+                store.set(key, value);
+            emit();
+        },
     };
 }

package/dist/tactics/fallingGrid.d.ts

@@ -49,14 +49,14 @@ export interface GravityIntervalConfig {
 }
 /**
  * Gravity tick interval for a given level: linear speed-up with a floor, generalizing
- * `Games/block-stacker`'s `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
+ * a falling-block `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
  * with configurable base/step/floor.
  */
 export declare function gravityIntervalMs(level: number, config?: GravityIntervalConfig): number;
 /**
  * A game-agnostic cell grid for gravity-driven falling-block mechanics: bounded occupancy,
  * footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand
- * style cascades), and a pure lock-delay helper. Extracted from `Games/block-stacker`'s tetris
+ * style cascades), and a pure lock-delay helper. Extracted from falling-block tetris
  * logic so any falling-block game can adopt it instead of reimplementing the grid.
  */
 export declare function createFallingGrid<TCell>(config: FallingGridConfig): FallingGrid<TCell>;

package/dist/tactics/fallingGrid.js

@@ -1,6 +1,6 @@
 /**
  * Gravity tick interval for a given level: linear speed-up with a floor, generalizing
- * `Games/block-stacker`'s `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
+ * a falling-block `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
  * with configurable base/step/floor.
  */
 export function gravityIntervalMs(level, config = {}) {
@@ -12,7 +12,7 @@ export function gravityIntervalMs(level, config = {}) {
 /**
  * A game-agnostic cell grid for gravity-driven falling-block mechanics: bounded occupancy,
  * footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand
- * style cascades), and a pure lock-delay helper. Extracted from `Games/block-stacker`'s tetris
+ * style cascades), and a pure lock-delay helper. Extracted from falling-block tetris
  * logic so any falling-block game can adopt it instead of reimplementing the grid.
  */
 export function createFallingGrid(config) {

package/dist/ui/gameLayout.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Shared mobile-composition geometry. Every UI subsystem (HUD, touch controls,
+ * system chrome, screens) registers the physical rectangle it occupies; the
+ * engine allocates the viewport once and detects when two subsystems collide,
+ * instead of each independently claiming an edge. Pure math — no DOM, no React.
+ */
+import type { LayoutOrientation } from "./orientation.js";
+/** The explicit composition mode a game renders for — not a scaled desktop layout. */
+export type GameLayoutMode = "desktop-wide" | "desktop-compact" | "mobile-landscape" | "mobile-portrait";
+/** Edge insets in CSS pixels (safe areas, reservations). */
+export interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** All-zero insets. */
+export declare const ZERO_INSETS: Insets;
+/** Axis-aligned rectangle in CSS pixels (origin top-left). Structurally compatible with a `DOMRect`'s edge fields. */
+export interface LayoutRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** Width of a rect (clamped to ≥0). */
+export declare function rectWidth(rect: LayoutRect): number;
+/** Height of a rect (clamped to ≥0). */
+export declare function rectHeight(rect: LayoutRect): number;
+/** Area of a rect in px². */
+export declare function rectArea(rect: LayoutRect): number;
+/** Do the two rectangles share any interior area? Touching edges do not count. */
+export declare function intersects(a: LayoutRect, b: LayoutRect): boolean;
+/** Overlapping area in px²; 0 when the rectangles don't intersect. */
+export declare function overlapArea(a: LayoutRect, b: LayoutRect): number;
+/** Portrait when taller than wide, else landscape. */
+export declare function orientationOf(width: number, height: number): LayoutOrientation;
+/** Inputs to `resolveLayoutMode`. */
+export interface LayoutModeInput {
+    /** Live visible viewport dimensions (prefer `visualViewport`). */
+    width: number;
+    height: number;
+    /** Touchscreen is the primary input (`(pointer: coarse)`). */
+    coarsePointer: boolean;
+    /** Does the game support phones at all (`platforms` includes `"mobile"`)? Default true. */
+    mobileSupported?: boolean;
+    /** Desktop width below which the layout is "compact". Default 900. */
+    compactWidth?: number;
+}
+/**
+ * Resolve the explicit composition mode. A mobile layout is not a scaled
+ * desktop layout: a coarse-pointer device on a game that supports mobile is
+ * always a `mobile-*` mode, split by live orientation; everything else is a
+ * desktop mode split by width.
+ */
+export declare function resolveLayoutMode(input: LayoutModeInput): GameLayoutMode;
+/** Whether a mode is one of the phone modes. */
+export declare function isMobileMode(mode: GameLayoutMode): boolean;
+/** What kind of UI a registered region belongs to. */
+export type LayoutRegionKind = "hud" | "control" | "system" | "screen";
+/** How a region participates in collision reporting. */
+export type LayoutCollisionPolicy = "forbid" | "allow" | "warn";
+/** Gameplay-importance tier of a HUD element. */
+export type HudPriority = "critical" | "secondary" | "tertiary";
+/** How a HUD element adapts on phones. */
+export type MobileHudBehavior = "persistent" | "compact" | "icon" | "transient" | "hidden" | "sheet" | "modal";
+/** A physical rectangle a UI subsystem occupies, published to the shared registry. */
+export interface LayoutRegion {
+    id: string;
+    kind: LayoutRegionKind;
+    rect: LayoutRect;
+    /** `forbid` reports any overlap, `warn` reports softly, `allow` opts this region out of collision reporting entirely. */
+    collisionPolicy: LayoutCollisionPolicy;
+    priority?: HudPriority;
+    /** Region ids this one may overlap without a report. */
+    allowOverlapWith?: readonly string[];
+    /** Regions sharing a non-empty group never report against each other. */
+    collisionGroup?: string;
+}
+/** One detected forbidden/warned overlap between two regions. */
+export interface LayoutCollision {
+    a: string;
+    b: string;
+    kindA: LayoutRegionKind;
+    kindB: LayoutRegionKind;
+    /** Overlapping area in px². */
+    area: number;
+    severity: "forbid" | "warn";
+}
+/** Options for `detectLayoutCollisions`. */
+export interface DetectCollisionsOptions {
+    /** Ignore overlaps smaller than this many px² — avoids meaningless sub-pixel warnings. Default 64. */
+    minArea?: number;
+}
+/**
+ * Every forbidden or warned rectangle intersection across the registered
+ * regions. A pair is skipped when either side's policy is `allow`, when either
+ * opts into the other via `allowOverlapWith`, when they share a
+ * `collisionGroup`, or when the overlap is below `minArea`.
+ */
+export declare function detectLayoutCollisions(regions: readonly LayoutRegion[], options?: DetectCollisionsOptions): LayoutCollision[];
+/** Human-readable diagnostic block for a set of collisions (empty string when there are none). */
+export declare function formatLayoutCollisions(collisions: readonly LayoutCollision[]): string;
+/**
+ * The usable gameplay rectangle after reserving physical zones for touch
+ * controls and system UI. Starts from the safe-area-inset viewport and carves
+ * each reserved zone from whichever edge it hugs.
+ */
+export declare function computeGameplayRect(viewport: LayoutRect, safeArea: Insets, reserved: readonly LayoutRect[]): LayoutRect;
+/** The shared live geometry the engine allocates once and every UI subsystem reads. */
+export interface GameViewportLayout {
+    /** The layout (CSS-pixel) viewport. */
+    viewport: LayoutRect;
+    /** The live visible viewport (`window.visualViewport`), which excludes mobile browser chrome. */
+    visualViewport: LayoutRect;
+    safeArea: Insets;
+    mode: GameLayoutMode;
+    orientation: LayoutOrientation;
+    /** All registered regions with their live rects. */
+    regions: readonly LayoutRegion[];
+    /** Rects reserved by touch controls and system UI. */
+    controlZones: readonly LayoutRect[];
+    /** Usable world/gameplay area after reservations. */
+    gameplayRect: LayoutRect;
+}

package/dist/ui/gameLayout.js

@@ -0,0 +1,129 @@
+/**
+ * Shared mobile-composition geometry. Every UI subsystem (HUD, touch controls,
+ * system chrome, screens) registers the physical rectangle it occupies; the
+ * engine allocates the viewport once and detects when two subsystems collide,
+ * instead of each independently claiming an edge. Pure math — no DOM, no React.
+ */
+/** All-zero insets. */
+export const ZERO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
+/** Width of a rect (clamped to ≥0). */
+export function rectWidth(rect) {
+    return Math.max(0, rect.right - rect.left);
+}
+/** Height of a rect (clamped to ≥0). */
+export function rectHeight(rect) {
+    return Math.max(0, rect.bottom - rect.top);
+}
+/** Area of a rect in px². */
+export function rectArea(rect) {
+    return rectWidth(rect) * rectHeight(rect);
+}
+/** Do the two rectangles share any interior area? Touching edges do not count. */
+export function intersects(a, b) {
+    return a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top;
+}
+/** Overlapping area in px²; 0 when the rectangles don't intersect. */
+export function overlapArea(a, b) {
+    const w = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+    const h = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+    return w > 0 && h > 0 ? w * h : 0;
+}
+/** Portrait when taller than wide, else landscape. */
+export function orientationOf(width, height) {
+    return height > width ? "portrait" : "landscape";
+}
+const DEFAULT_COMPACT_WIDTH = 900;
+/**
+ * Resolve the explicit composition mode. A mobile layout is not a scaled
+ * desktop layout: a coarse-pointer device on a game that supports mobile is
+ * always a `mobile-*` mode, split by live orientation; everything else is a
+ * desktop mode split by width.
+ */
+export function resolveLayoutMode(input) {
+    const orientation = orientationOf(input.width, input.height);
+    const mobile = input.coarsePointer && (input.mobileSupported ?? true);
+    if (mobile)
+        return orientation === "portrait" ? "mobile-portrait" : "mobile-landscape";
+    const compactWidth = input.compactWidth ?? DEFAULT_COMPACT_WIDTH;
+    return input.width < compactWidth ? "desktop-compact" : "desktop-wide";
+}
+/** Whether a mode is one of the phone modes. */
+export function isMobileMode(mode) {
+    return mode === "mobile-portrait" || mode === "mobile-landscape";
+}
+function allowsOverlap(a, b) {
+    if (a.allowOverlapWith?.includes(b.id) === true)
+        return true;
+    if (b.allowOverlapWith?.includes(a.id) === true)
+        return true;
+    if (a.collisionGroup !== undefined && a.collisionGroup === b.collisionGroup)
+        return true;
+    return false;
+}
+const DEFAULT_MIN_AREA = 64;
+/**
+ * Every forbidden or warned rectangle intersection across the registered
+ * regions. A pair is skipped when either side's policy is `allow`, when either
+ * opts into the other via `allowOverlapWith`, when they share a
+ * `collisionGroup`, or when the overlap is below `minArea`.
+ */
+export function detectLayoutCollisions(regions, options) {
+    const minArea = options?.minArea ?? DEFAULT_MIN_AREA;
+    const out = [];
+    for (let i = 0; i < regions.length; i += 1) {
+        for (let j = i + 1; j < regions.length; j += 1) {
+            const a = regions[i];
+            const b = regions[j];
+            if (a.collisionPolicy === "allow" || b.collisionPolicy === "allow")
+                continue;
+            if (allowsOverlap(a, b))
+                continue;
+            const area = overlapArea(a.rect, b.rect);
+            if (area < minArea)
+                continue;
+            const severity = a.collisionPolicy === "forbid" || b.collisionPolicy === "forbid" ? "forbid" : "warn";
+            out.push({ a: a.id, b: b.id, kindA: a.kind, kindB: b.kind, area: Math.round(area), severity });
+        }
+    }
+    return out;
+}
+function withThousands(n) {
+    return Math.round(n)
+        .toString()
+        .replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+/** Human-readable diagnostic block for a set of collisions (empty string when there are none). */
+export function formatLayoutCollisions(collisions) {
+    if (collisions.length === 0)
+        return "";
+    const lines = collisions.map((c) => `${c.a} intersects ${c.b} by ${withThousands(c.area)} px²`);
+    return ["JGENGINE MOBILE LAYOUT COLLISION", ...lines].join("\n");
+}
+/**
+ * The usable gameplay rectangle after reserving physical zones for touch
+ * controls and system UI. Starts from the safe-area-inset viewport and carves
+ * each reserved zone from whichever edge it hugs.
+ */
+export function computeGameplayRect(viewport, safeArea, reserved) {
+    let top = viewport.top + safeArea.top;
+    let bottom = viewport.bottom - safeArea.bottom;
+    let left = viewport.left + safeArea.left;
+    let right = viewport.right - safeArea.right;
+    const midX = (viewport.left + viewport.right) / 2;
+    const midY = (viewport.top + viewport.bottom) / 2;
+    for (const zone of reserved) {
+        const zoneMidX = (zone.left + zone.right) / 2;
+        const zoneMidY = (zone.top + zone.bottom) / 2;
+        const spanX = zone.right - zone.left;
+        const spanY = zone.bottom - zone.top;
+        if (zoneMidY > midY)
+            bottom = Math.min(bottom, zone.top);
+        else if (zoneMidY < midY && spanX >= spanY)
+            top = Math.max(top, zone.bottom);
+        else if (zoneMidX < midX)
+            left = Math.max(left, zone.right);
+        else
+            right = Math.min(right, zone.left);
+    }
+    return { left, top, right: Math.max(left, right), bottom: Math.max(top, bottom) };
+}

package/dist/ui/orientation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The game-level orientation contract. A game declares how it supports phone
+ * orientations; the shell resolves that against the live orientation to decide
+ * whether to show a dismissible rotate hint (advisory) or a full-screen gate
+ * that blocks gameplay until the device is turned (required).
+ */
+/** How a game supports a phone orientation on coarse-pointer displays. */
+export type MobileOrientationRule = "any" | "portrait" | "landscape" | "portrait-required" | "landscape-required" | "unsupported";
+/** Object form of the `orientation` field: the strict per-platform contract. */
+export interface GameOrientationConfig {
+    /** Orientation contract on coarse-pointer / phone displays. Default `"any"`. */
+    mobile?: MobileOrientationRule;
+}
+/**
+ * The `orientation` field of a game definition. Legacy shorthand `"landscape"`
+ * / `"portrait"` stays advisory (a dismissible rotate hint, never a gate). The
+ * object form `{ mobile: "landscape-required" }` is the strict contract that
+ * blocks gameplay behind the rotate screen until the device is turned.
+ */
+export type GameOrientation = "landscape" | "portrait" | GameOrientationConfig;
+/** A concrete device orientation. */
+export type LayoutOrientation = "portrait" | "landscape";
+/** The resolved orientation contract for a platform: whether it's supported, gated, or merely preferred. */
+export interface OrientationRequirement {
+    /** False only for `"unsupported"` — the game declares it isn't built for phones. */
+    supported: boolean;
+    /** Orientation gameplay is hard-gated to; `null` when there is no gate. */
+    required: LayoutOrientation | null;
+    /** Orientation the game reads best in; drives an advisory hint when not required. */
+    preferred: LayoutOrientation | null;
+}
+/** Normalize the `orientation` field (legacy string or object) to a single mobile rule. */
+export declare function resolveMobileOrientationRule(orientation: GameOrientation | undefined): MobileOrientationRule;
+/** Resolve the game's orientation declaration into a concrete requirement for a platform. Desktop is always unconstrained. */
+export declare function resolveOrientationRequirement(orientation: GameOrientation | undefined, platform: "mobile" | "desktop"): OrientationRequirement;
+/** The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy. */
+export declare function orientationGateActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean;
+/** An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy. */
+export declare function orientationHintActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean;

package/dist/ui/orientation.js

@@ -0,0 +1,49 @@
+/**
+ * The game-level orientation contract. A game declares how it supports phone
+ * orientations; the shell resolves that against the live orientation to decide
+ * whether to show a dismissible rotate hint (advisory) or a full-screen gate
+ * that blocks gameplay until the device is turned (required).
+ */
+/** Normalize the `orientation` field (legacy string or object) to a single mobile rule. */
+export function resolveMobileOrientationRule(orientation) {
+    if (orientation === undefined)
+        return "any";
+    if (orientation === "landscape")
+        return "landscape";
+    if (orientation === "portrait")
+        return "portrait";
+    return orientation.mobile ?? "any";
+}
+/** Resolve the game's orientation declaration into a concrete requirement for a platform. Desktop is always unconstrained. */
+export function resolveOrientationRequirement(orientation, platform) {
+    if (platform === "desktop")
+        return { supported: true, required: null, preferred: null };
+    const rule = resolveMobileOrientationRule(orientation);
+    switch (rule) {
+        case "unsupported":
+            return { supported: false, required: null, preferred: null };
+        case "landscape-required":
+            return { supported: true, required: "landscape", preferred: "landscape" };
+        case "portrait-required":
+            return { supported: true, required: "portrait", preferred: "portrait" };
+        case "landscape":
+            return { supported: true, required: null, preferred: "landscape" };
+        case "portrait":
+            return { supported: true, required: null, preferred: "portrait" };
+        case "any":
+            return { supported: true, required: null, preferred: null };
+    }
+}
+/** The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy. */
+export function orientationGateActive(requirement, liveOrientation) {
+    if (!requirement.supported)
+        return true;
+    return requirement.required !== null && requirement.required !== liveOrientation;
+}
+/** An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy. */
+export function orientationHintActive(requirement, liveOrientation) {
+    return (requirement.supported &&
+        requirement.required === null &&
+        requirement.preferred !== null &&
+        requirement.preferred !== liveOrientation);
+}