@jgengine/core 0.9.0 → 0.11.0

package/dist/time/idleProgress.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function idleWindow(lastSeenMs, nowMs, config = {}) {
     const elapsedSeconds = Math.max(0, (nowMs - lastSeenMs) / 1000);
     const capped = config.maxSeconds !== undefined && elapsedSeconds > config.maxSeconds;
@@ -9,17 +10,20 @@ export function idleWindow(lastSeenMs, nowMs, config = {}) {
         capped,
     };
 }
+/** @internal */
 export function linearCatchUp(seconds, input) {
     const clampedSeconds = Math.max(0, seconds);
     const value = input.current + input.ratePerSecond * clampedSeconds;
     return Math.min(input.max ?? Number.POSITIVE_INFINITY, Math.max(input.min ?? Number.NEGATIVE_INFINITY, value));
 }
+/** @internal */
 export function exponentialCatchUp(seconds, input) {
     const clampedSeconds = Math.max(0, seconds);
     const factor = Math.max(0, input.factorPerSecond);
     const value = input.current * factor ** clampedSeconds;
     return Math.min(input.max ?? Number.POSITIVE_INFINITY, Math.max(input.min ?? Number.NEGATIVE_INFINITY, value));
 }
+/** @internal */
 export function steppedCatchUp(seconds, stepSeconds, step, maxSteps) {
     if (stepSeconds <= 0 || seconds <= 0) {
         return { steps: 0, remainderSeconds: Math.max(0, seconds) };

package/dist/time/simClock.d.ts

@@ -51,6 +51,8 @@ export interface SimClock {
     advance(realDt: number): number;
     now(): number;
     snapshot(): ClockSnapshot;
+    /** Restore clock position — game-time, pause state, and speed multipliers — from a {@link ClockSnapshot} for whole-world save/load. Live timers registered via `after`/`every`/`at` are unaffected. */
+    hydrate(snapshot: ClockSnapshot): void;
     calendar(): CalendarTime;
     isPaused(): boolean;
     speed(): number;

package/dist/time/simClock.js

@@ -1,5 +1,11 @@
 import { SECONDS_PER_GAME_DAY } from "./gameClock.js";
-const MAX_TIMER_FIRES = 10_000;
+const MAX_TIMER_FIRES_PER_ADVANCE = 10_000;
+function requireFiniteTimerValue(label, value) {
+    if (!Number.isFinite(value)) {
+        throw new Error(`SimClock ${label} must be finite, got ${value}`);
+    }
+    return value;
+}
 export function createSimClock(options = {}) {
     const config = options.config ?? {};
     const onChange = options.onChange ?? (() => { });
@@ -62,7 +68,7 @@ export function createSimClock(options = {}) {
             }
             timer.callback();
             fires += 1;
-            if (fires >= MAX_TIMER_FIRES)
+            if (fires >= MAX_TIMER_FIRES_PER_ADVANCE)
                 return;
         }
     }
@@ -121,10 +127,19 @@ export function createSimClock(options = {}) {
             timers.delete(id);
         };
     }
+    function hydrate(state) {
+        now = state.now;
+        paused = state.paused;
+        playSpeed = state.playSpeed;
+        timescale = state.timescale;
+        displayMinute = minuteIndex(now, dayLength);
+        onChange();
+    }
     return {
         advance,
         now: () => now,
         calendar,
+        hydrate,
         snapshot: () => ({
             now,
             paused,
@@ -144,12 +159,12 @@ export function createSimClock(options = {}) {
         cycleSpeed,
         timescale: () => timescale,
         setTimescale,
-        after: (seconds, callback) => register(now + Math.max(0, seconds), null, callback),
+        after: (seconds, callback) => register(now + Math.max(0, requireFiniteTimerValue("after(seconds)", seconds)), null, callback),
         every: (seconds, callback) => {
-            const interval = Math.max(Number.EPSILON, seconds);
+            const interval = Math.max(Number.EPSILON, requireFiniteTimerValue("every(seconds)", seconds));
             return register(now + interval, interval, callback);
         },
-        at: (time, callback) => register(time, null, callback),
+        at: (time, callback) => register(requireFiniteTimerValue("at(time)", time), null, callback),
     };
 }
 function minuteIndex(seconds, dayLength) {

package/dist/ui/actionModel.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Headless view model for a contextual action collection — the data layer behind an RTS command
+ * card, an ability action bar, a build menu, or a radial. It carries *what the buttons mean*
+ * (label, hotkey, cost, cooldown, disabled reasons, toggle state) with zero rendering opinion, so a
+ * game keeps layout, dimensions, hotkeys, catalog-id mapping, renderer, and chrome caller-owned. The
+ * React renderers in `@jgengine/react/actionHud` consume this; a game can swap either without
+ * forking the logic here.
+ */
+/** A spendable-resource line on an action (e.g. `40` mana). `met` is false only when `available` is known and short. */
+export interface ActionCost {
+    resourceId: string;
+    amount: number;
+    /** Current pool, when the caller knows it — drives {@link ActionCost.met}. Omit when unknown. */
+    available?: number;
+    /** True unless `available` is known and below `amount`. */
+    met: boolean;
+}
+/** Cooldown state for an action, expressed so a radial sweep or countdown can render directly. */
+export interface ActionCooldown {
+    remainingMs: number;
+    totalMs: number;
+    /** Remaining share of the cooldown, `0..1` — the fraction a radial wipe should still cover. */
+    fraction: number;
+    ready: boolean;
+}
+/** A single blocking reason: a stable machine `code` plus caller-facing `message`. */
+export interface ActionReason {
+    /** Stable tag for styling/branching, e.g. `"cooldown" | "cost" | "range" | "disabled"`. */
+    code: string;
+    message: string;
+}
+/**
+ * A caller-authored contextual action — the DATA input to the model. Every field except `id` is
+ * optional so a build button, a stance toggle, and a cooldown ability all use the same shape.
+ * Catalog-id mapping (turning `icon`/`label` into art and copy) stays caller-owned.
+ */
+export interface ActionDef {
+    id: string;
+    label?: string;
+    description?: string;
+    /** Icon id / glyph the caller maps to a catalog; the model only carries it through. */
+    icon?: string;
+    /** Human hotkey label (e.g. `"Q"`, `"1"`). Matched case-insensitively by {@link actionByHotkey}. */
+    hotkey?: string;
+    /** Section id for grouping a large card into rows/tabs; caller-owned. */
+    group?: string;
+    cooldown?: ActionCooldown;
+    costs?: readonly ActionCost[];
+    /** Toggle/stance state — a mode that is currently on. */
+    active?: boolean;
+    /** Hard-disable regardless of cost/cooldown (not yet researched, no valid target). */
+    disabled?: boolean;
+    /** Extra caller reasons (out of range, needs tech). Merged after the derived cost/cooldown ones. */
+    reasons?: readonly ActionReason[];
+}
+/**
+ * A resolved action view model — availability computed once from cooldown, cost, `disabled`, and any
+ * caller reasons. `enabled` is the single truth a renderer gates interaction on; `reasons` is the
+ * ordered explanation (cooldown, then unmet costs, then caller reasons, then a generic disable).
+ */
+export interface ResolvedAction {
+    id: string;
+    label: string;
+    description?: string;
+    icon?: string;
+    hotkey?: string;
+    group?: string;
+    active: boolean;
+    enabled: boolean;
+    cooldown: ActionCooldown | null;
+    costs: readonly ActionCost[];
+    reasons: readonly ActionReason[];
+}
+/** Build an {@link ActionCooldown} from remaining/total milliseconds. `ready` when nothing remains. */
+export declare function actionCooldown(remainingMs: number, totalMs: number): ActionCooldown;
+/**
+ * Build an {@link ActionCooldown} from remaining milliseconds and a known remaining fraction — the
+ * shape adapters get from sources (like an ability snapshot) that report a fraction but not a total.
+ */
+export declare function actionCooldownFromFraction(remainingMs: number, fraction: number): ActionCooldown;
+/** Build an {@link ActionCost}. `met` is true unless `available` is provided and below `amount`. */
+export declare function actionCost(resourceId: string, amount: number, available?: number): ActionCost;
+/**
+ * Resolve one {@link ActionDef} into a {@link ResolvedAction}: normalize label, compute `enabled`,
+ * and order the blocking `reasons`. Pure — the same input always yields the same view model.
+ */
+export declare function resolveAction(def: ActionDef): ResolvedAction;
+/** Resolve an ordered list of actions, preserving input order. */
+export declare function resolveActionCollection(defs: readonly ActionDef[]): ResolvedAction[];
+/**
+ * Find the action whose `hotkey` matches `key`, case-insensitively — the keyboard-shortcut router for
+ * an action bar. Returns the first match's id, or null. Matching by hotkey does not consider
+ * `enabled`; the caller decides whether to fire a disabled action's feedback.
+ */
+export declare function actionByHotkey(actions: readonly ResolvedAction[], key: string): string | null;
+/** A focus move for keyboard/controller grid navigation over an action collection. */
+export type FocusDirection = "left" | "right" | "up" | "down" | "next" | "prev" | "first" | "last";
+/** Options for {@link moveGridFocus}. */
+export interface GridFocusOptions {
+    /** Wrap around edges instead of clamping (default false). */
+    wrap?: boolean;
+}
+/**
+ * Pure grid focus math for keyboard and controller navigation of an action card laid out in
+ * `columns`-wide rows. Given the current index (`-1` for none) it returns the next index, clamped to
+ * `[0, count)` — or wrapped when `wrap` is set. `left/right` move within/across columns, `up/down`
+ * across rows, `next/prev` walk the flat order, `first/last` jump to the ends. Renderer-agnostic:
+ * radial and list layouts pass `columns: 1` (or `count`) to get sensible 1-D stepping.
+ */
+export declare function moveGridFocus(current: number, count: number, columns: number, dir: FocusDirection, options?: GridFocusOptions): number;

package/dist/ui/actionModel.js

@@ -0,0 +1,159 @@
+/**
+ * Headless view model for a contextual action collection — the data layer behind an RTS command
+ * card, an ability action bar, a build menu, or a radial. It carries *what the buttons mean*
+ * (label, hotkey, cost, cooldown, disabled reasons, toggle state) with zero rendering opinion, so a
+ * game keeps layout, dimensions, hotkeys, catalog-id mapping, renderer, and chrome caller-owned. The
+ * React renderers in `@jgengine/react/actionHud` consume this; a game can swap either without
+ * forking the logic here.
+ */
+const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
+/** Build an {@link ActionCooldown} from remaining/total milliseconds. `ready` when nothing remains. */
+export function actionCooldown(remainingMs, totalMs) {
+    const remaining = Math.max(0, remainingMs);
+    const total = Math.max(0, totalMs);
+    return {
+        remainingMs: remaining,
+        totalMs: total,
+        fraction: total <= 0 ? 0 : clamp01(remaining / total),
+        ready: remaining <= 0,
+    };
+}
+/**
+ * Build an {@link ActionCooldown} from remaining milliseconds and a known remaining fraction — the
+ * shape adapters get from sources (like an ability snapshot) that report a fraction but not a total.
+ */
+export function actionCooldownFromFraction(remainingMs, fraction) {
+    const remaining = Math.max(0, remainingMs);
+    const frac = clamp01(fraction);
+    return {
+        remainingMs: remaining,
+        totalMs: frac > 0 ? Math.round(remaining / frac) : remaining,
+        fraction: frac,
+        ready: remaining <= 0,
+    };
+}
+/** Build an {@link ActionCost}. `met` is true unless `available` is provided and below `amount`. */
+export function actionCost(resourceId, amount, available) {
+    const cost = {
+        resourceId,
+        amount,
+        met: available === undefined ? true : available >= amount,
+    };
+    if (available !== undefined)
+        cost.available = available;
+    return cost;
+}
+/**
+ * Resolve one {@link ActionDef} into a {@link ResolvedAction}: normalize label, compute `enabled`,
+ * and order the blocking `reasons`. Pure — the same input always yields the same view model.
+ */
+export function resolveAction(def) {
+    const costs = def.costs ?? [];
+    const reasons = [];
+    const cooldown = def.cooldown ?? null;
+    if (cooldown !== null && !cooldown.ready) {
+        reasons.push({ code: "cooldown", message: cooldownMessage(cooldown) });
+    }
+    for (const cost of costs) {
+        if (!cost.met)
+            reasons.push({ code: "cost", message: costMessage(cost) });
+    }
+    for (const reason of def.reasons ?? [])
+        reasons.push(reason);
+    if (def.disabled === true && reasons.length === 0) {
+        reasons.push({ code: "disabled", message: "Unavailable" });
+    }
+    const enabled = def.disabled !== true && reasons.length === 0;
+    const resolved = {
+        id: def.id,
+        label: def.label ?? def.id,
+        active: def.active === true,
+        enabled,
+        cooldown,
+        costs,
+        reasons,
+    };
+    if (def.description !== undefined)
+        resolved.description = def.description;
+    if (def.icon !== undefined)
+        resolved.icon = def.icon;
+    if (def.hotkey !== undefined)
+        resolved.hotkey = def.hotkey;
+    if (def.group !== undefined)
+        resolved.group = def.group;
+    return resolved;
+}
+/** Resolve an ordered list of actions, preserving input order. */
+export function resolveActionCollection(defs) {
+    return defs.map(resolveAction);
+}
+/** @internal Default cooldown reason copy: `Ready in 2.4s`. */
+function cooldownMessage(cooldown) {
+    return `Ready in ${(cooldown.remainingMs / 1000).toFixed(1)}s`;
+}
+/** @internal Default unmet-cost reason copy: `Needs 40 mana`. */
+function costMessage(cost) {
+    return `Needs ${cost.amount} ${cost.resourceId}`;
+}
+/**
+ * Find the action whose `hotkey` matches `key`, case-insensitively — the keyboard-shortcut router for
+ * an action bar. Returns the first match's id, or null. Matching by hotkey does not consider
+ * `enabled`; the caller decides whether to fire a disabled action's feedback.
+ */
+export function actionByHotkey(actions, key) {
+    const needle = key.toLowerCase();
+    for (const action of actions) {
+        if (action.hotkey !== undefined && action.hotkey.toLowerCase() === needle)
+            return action.id;
+    }
+    return null;
+}
+/**
+ * Pure grid focus math for keyboard and controller navigation of an action card laid out in
+ * `columns`-wide rows. Given the current index (`-1` for none) it returns the next index, clamped to
+ * `[0, count)` — or wrapped when `wrap` is set. `left/right` move within/across columns, `up/down`
+ * across rows, `next/prev` walk the flat order, `first/last` jump to the ends. Renderer-agnostic:
+ * radial and list layouts pass `columns: 1` (or `count`) to get sensible 1-D stepping.
+ */
+export function moveGridFocus(current, count, columns, dir, options) {
+    if (count <= 0)
+        return -1;
+    const cols = Math.max(1, Math.floor(columns));
+    const wrap = options?.wrap === true;
+    if (dir === "first")
+        return 0;
+    if (dir === "last")
+        return count - 1;
+    if (current < 0) {
+        return dir === "prev" || dir === "left" || dir === "up" ? count - 1 : 0;
+    }
+    const clampIndex = (index) => Math.max(0, Math.min(count - 1, index));
+    if (dir === "next")
+        return current + 1 >= count ? (wrap ? 0 : count - 1) : current + 1;
+    if (dir === "prev")
+        return current - 1 < 0 ? (wrap ? count - 1 : 0) : current - 1;
+    const row = Math.floor(current / cols);
+    const col = current % cols;
+    if (dir === "right" || dir === "left") {
+        const rowStart = row * cols;
+        const rowEnd = Math.min(count - 1, rowStart + cols - 1);
+        const width = rowEnd - rowStart + 1;
+        if (width <= 1)
+            return current;
+        const nextCol = dir === "right" ? col + 1 : col - 1;
+        if (nextCol < 0)
+            return wrap ? rowEnd : current;
+        if (nextCol > rowEnd - rowStart)
+            return wrap ? rowStart : current;
+        return rowStart + nextCol;
+    }
+    // up / down
+    const nextRow = dir === "down" ? row + 1 : row - 1;
+    const rowCount = Math.ceil(count / cols);
+    if (nextRow < 0)
+        return wrap ? clampIndex((rowCount - 1) * cols + col) : current;
+    if (nextRow > rowCount - 1)
+        return wrap ? col : current;
+    const target = nextRow * cols + col;
+    return target >= count ? (dir === "down" ? current : clampIndex(target)) : target;
+}

package/dist/ui/gameLayout.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 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).
+ * @internal
+ */
+export declare function rectWidth(rect: LayoutRect): number;
+/** Height of a rect (clamped to ≥0).
+ * @internal
+ */
+export declare function rectHeight(rect: LayoutRect): number;
+/** Area of a rect in px².
+ * @internal
+ */
+export declare function rectArea(rect: LayoutRect): number;
+/** Do the two rectangles share any interior area? Touching edges do not count.
+ * @internal
+ */
+export declare function intersects(a: LayoutRect, b: LayoutRect): boolean;
+/** Overlapping area in px²; 0 when the rectangles don't intersect.
+ * @internal
+ */
+export declare function overlapArea(a: LayoutRect, b: LayoutRect): number;
+/** Portrait when taller than wide, else landscape.
+ * @internal
+ */
+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.
+  * @internal
+  */
+export declare function resolveLayoutMode(input: LayoutModeInput): GameLayoutMode;
+/** Whether a mode is one of the phone modes.
+ * @internal
+ */
+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`.
+  * @internal
+  */
+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).
+ * @internal
+ */
+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.
+  * @internal
+  */
+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,148 @@
+/**
+ * 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).
+ * @internal
+ */
+export function rectWidth(rect) {
+    return Math.max(0, rect.right - rect.left);
+}
+/** Height of a rect (clamped to ≥0).
+ * @internal
+ */
+export function rectHeight(rect) {
+    return Math.max(0, rect.bottom - rect.top);
+}
+/** Area of a rect in px².
+ * @internal
+ */
+export function rectArea(rect) {
+    return rectWidth(rect) * rectHeight(rect);
+}
+/** Do the two rectangles share any interior area? Touching edges do not count.
+ * @internal
+ */
+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.
+ * @internal
+ */
+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.
+ * @internal
+ */
+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.
+  * @internal
+  */
+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.
+ * @internal
+ */
+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`.
+  * @internal
+  */
+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).
+ * @internal
+ */
+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.
+  * @internal
+  */
+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) };
+}