@jgengine/core 0.10.0 → 0.12.0

package/dist/time/calendarClock.js

@@ -1,6 +1,7 @@
 import { getCurrentGameTimestamp, sanitizeGameTimeScale } from "@jgengine/core/time/gameClock";
 const MONTH_NAMES_SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 const MONTH_NAMES_FULL = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+/** @internal */
 export function computeGameTime(gameTimestamp) {
     const d = new Date(gameTimestamp);
     const year = d.getFullYear();
@@ -33,9 +34,11 @@ export function computeGameTime(gameTimestamp) {
         formatted,
     };
 }
+/** @internal */
 export function computeClientServerOffset(serverNow, clientNow) {
     return serverNow - clientNow;
 }
+/** @internal */
 export function getGameClockTimestamp(createdAt, serverNow, clientNow, gameTimeScale) {
     const clientOffsetMs = computeClientServerOffset(serverNow, clientNow);
     return getCurrentGameTimestamp(createdAt, clientNow + clientOffsetMs, sanitizeGameTimeScale(gameTimeScale));

package/dist/time/idleProgress.d.ts

@@ -7,6 +7,7 @@ export interface IdleWindow {
     effectiveSeconds: number;
     capped: boolean;
 }
+/** @internal */
 export declare function idleWindow(lastSeenMs: number, nowMs: number, config?: IdleWindowConfig): IdleWindow;
 export interface LinearCatchUpInput {
     current: number;
@@ -14,6 +15,7 @@ export interface LinearCatchUpInput {
     min?: number;
     max?: number;
 }
+/** @internal */
 export declare function linearCatchUp(seconds: number, input: LinearCatchUpInput): number;
 export interface ExponentialCatchUpInput {
     current: number;
@@ -21,9 +23,11 @@ export interface ExponentialCatchUpInput {
     min?: number;
     max?: number;
 }
+/** @internal */
 export declare function exponentialCatchUp(seconds: number, input: ExponentialCatchUpInput): number;
 export interface SteppedCatchUpResult {
     steps: number;
     remainderSeconds: number;
 }
+/** @internal */
 export declare function steppedCatchUp(seconds: number, stepSeconds: number, step: (index: number) => void, maxSteps?: number): SteppedCatchUpResult;

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

@@ -23,17 +23,29 @@ export interface LayoutRect {
     right: number;
     bottom: number;
 }
-/** Width of a rect (clamped to ≥0). */
+/** Width of a rect (clamped to ≥0).
+ * @internal
+ */
 export declare function rectWidth(rect: LayoutRect): number;
-/** Height of a rect (clamped to ≥0). */
+/** Height of a rect (clamped to ≥0).
+ * @internal
+ */
 export declare function rectHeight(rect: LayoutRect): number;
-/** Area of a rect in px². */
+/** 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. */
+/** 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. */
+/** 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. */
+/** Portrait when taller than wide, else landscape.
+ * @internal
+ */
 export declare function orientationOf(width: number, height: number): LayoutOrientation;
 /** Inputs to `resolveLayoutMode`. */
 export interface LayoutModeInput {
@@ -52,9 +64,12 @@ export interface LayoutModeInput {
  * 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. */
+/** 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";
@@ -97,15 +112,19 @@ export interface DetectCollisionsOptions {
  * 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). */
+/** 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 {

package/dist/ui/gameLayout.js

@@ -6,29 +6,41 @@
  */
 /** All-zero insets. */
 export const ZERO_INSETS = { top: 0, right: 0, bottom: 0, left: 0 };
-/** Width of a rect (clamped to ≥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). */
+/** 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². */
+/** 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. */
+/** 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. */
+/** 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. */
+/** Portrait when taller than wide, else landscape.
+ * @internal
+ */
 export function orientationOf(width, height) {
     return height > width ? "portrait" : "landscape";
 }
@@ -38,7 +50,8 @@ const DEFAULT_COMPACT_WIDTH = 900;
  * 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);
@@ -47,7 +60,9 @@ export function resolveLayoutMode(input) {
     const compactWidth = input.compactWidth ?? DEFAULT_COMPACT_WIDTH;
     return input.width < compactWidth ? "desktop-compact" : "desktop-wide";
 }
-/** Whether a mode is one of the phone modes. */
+/** Whether a mode is one of the phone modes.
+ * @internal
+ */
 export function isMobileMode(mode) {
     return mode === "mobile-portrait" || mode === "mobile-landscape";
 }
@@ -66,7 +81,8 @@ const DEFAULT_MIN_AREA = 64;
  * 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 = [];
@@ -92,7 +108,9 @@ function withThousands(n) {
         .toString()
         .replace(/\B(?=(\d{3})+(?!\d))/g, ",");
 }
-/** Human-readable diagnostic block for a set of collisions (empty string when there are none). */
+/** 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 "";
@@ -103,7 +121,8 @@ export function formatLayoutCollisions(collisions) {
  * 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;