@jgengine/core 0.8.0 → 0.10.0

package/dist/time/idleProgress.js

@@ -0,0 +1,31 @@
+export function idleWindow(lastSeenMs, nowMs, config = {}) {
+    const elapsedSeconds = Math.max(0, (nowMs - lastSeenMs) / 1000);
+    const capped = config.maxSeconds !== undefined && elapsedSeconds > config.maxSeconds;
+    const boundedSeconds = Math.min(elapsedSeconds, config.maxSeconds ?? Number.POSITIVE_INFINITY);
+    const efficiency = Math.max(0, config.efficiency ?? 1);
+    return {
+        elapsedSeconds,
+        effectiveSeconds: boundedSeconds * efficiency,
+        capped,
+    };
+}
+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));
+}
+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));
+}
+export function steppedCatchUp(seconds, stepSeconds, step, maxSteps) {
+    if (stepSeconds <= 0 || seconds <= 0) {
+        return { steps: 0, remainderSeconds: Math.max(0, seconds) };
+    }
+    const steps = Math.min(Math.floor(seconds / stepSeconds), maxSteps ?? Number.POSITIVE_INFINITY);
+    for (let index = 0; index < steps; index++)
+        step(index);
+    return { steps, remainderSeconds: seconds - steps * stepSeconds };
+}

package/dist/time/serverTick.d.ts

@@ -9,8 +9,14 @@ export interface ServerTickPlan<TSystemId extends string = string> {
     due: TSystemId[];
     anchors: TickAnchors;
 }
+export type PlanServerTickOptions = {
+    /** Cap catch-up runs per system per heartbeat to avoid spiral-of-death. Default 3. */
+    maxCatchUp?: number;
+};
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
+ * When wall time stalls past multiple intervals, the system id is repeated (bounded by
+ * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
-export declare function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number): ServerTickPlan<TSystemId>;
+export declare function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number, options?: PlanServerTickOptions): ServerTickPlan<TSystemId>;

package/dist/time/serverTick.js

@@ -1,18 +1,41 @@
+const DEFAULT_MAX_CATCH_UP = 3;
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
+ * When wall time stalls past multiple intervals, the system id is repeated (bounded by
+ * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
-export function planServerTick(systems, anchors, now) {
+export function planServerTick(systems, anchors, now, options) {
+    const maxCatchUp = options?.maxCatchUp ?? DEFAULT_MAX_CATCH_UP;
     const due = [];
     const nextAnchors = {};
     for (const system of systems) {
         const lastRunAt = anchors[system.id];
-        if (lastRunAt !== undefined && now - lastRunAt < system.intervalMs) {
+        if (lastRunAt === undefined) {
+            due.push(system.id);
+            nextAnchors[system.id] = now;
+            continue;
+        }
+        if (system.intervalMs <= 0) {
+            due.push(system.id);
+            nextAnchors[system.id] = now;
+            continue;
+        }
+        const elapsed = now - lastRunAt;
+        if (elapsed < system.intervalMs) {
             nextAnchors[system.id] = lastRunAt;
             continue;
         }
-        due.push(system.id);
-        nextAnchors[system.id] = now;
+        const missed = Math.floor(elapsed / system.intervalMs);
+        if (missed > maxCatchUp) {
+            for (let i = 0; i < maxCatchUp; i += 1)
+                due.push(system.id);
+            nextAnchors[system.id] = now;
+            continue;
+        }
+        for (let i = 0; i < missed; i += 1)
+            due.push(system.id);
+        nextAnchors[system.id] = lastRunAt + missed * system.intervalMs;
     }
     return { due, anchors: nextAnchors };
 }

package/dist/time/stateSchedule.d.ts

@@ -0,0 +1,57 @@
+export interface SchedulePhase<T> {
+    state: T;
+    durationSeconds: number;
+}
+export interface StateScheduleConfig<T> {
+    phases: readonly SchedulePhase<T>[];
+    /** Repeat the phase list forever (default); `false` clamps to the last phase after one pass. */
+    loop?: boolean;
+    /** Shifts the whole timeline so `t = 0` lands `offsetSeconds` into the cycle — staggers identical schedules. */
+    offsetSeconds?: number;
+}
+export interface ScheduleSample<T> {
+    state: T;
+    /** Index into `phases`. */
+    index: number;
+    elapsedSeconds: number;
+    /** Seconds until this phase ends; `Infinity` on the clamped final phase of a non-looping schedule. */
+    remainingSeconds: number;
+    /** Elapsed fraction of the phase in `[0, 1]`; `1` on the clamped final phase. */
+    fraction: number;
+}
+export interface ScheduleWindow {
+    start: number;
+    end: number;
+}
+/**
+ * A deterministic timeline of states — position-in-schedule is a pure function of absolute time,
+ * so a forecast preview and the live state can never disagree. One primitive behind zoned weather
+ * shifts, hazard cycles, and timetabled machinery: `stateAt`/`sampleAt` for the live state,
+ * `nextTransitionAt` for countdowns, `windowsOf`/`nextWindow` for "when is it safe" forecasts.
+ */
+export interface StateSchedule<T> {
+    /** Sum of all phase durations — one full cycle. */
+    readonly cycleSeconds: number;
+    stateAt(t: number): T;
+    sampleAt(t: number): ScheduleSample<T>;
+    /** Absolute time of the next phase boundary after `t`; `Infinity` once a non-looping schedule ends. */
+    nextTransitionAt(t: number): number;
+    /** All windows within `[fromT, fromT + horizonSeconds]` where the state matches. */
+    windowsOf(match: (state: T) => boolean, fromT: number, horizonSeconds: number): ScheduleWindow[];
+    /** The first matching window at or after `fromT` (looking ahead `horizonSeconds`, default one full cycle). */
+    nextWindow(match: (state: T) => boolean, fromT: number, horizonSeconds?: number): ScheduleWindow | null;
+}
+export declare function createStateSchedule<T>(config: StateScheduleConfig<T>): StateSchedule<T>;
+export interface ClearWindowScan {
+    fromSeconds: number;
+    horizonSeconds: number;
+    /** Sampling resolution; smaller catches shorter gaps. */
+    stepSeconds: number;
+    /** Reject windows shorter than this; default `0`. */
+    minDurationSeconds?: number;
+}
+/**
+ * Forward-scan any predicate-of-time — a timetable mover's "is the crossing clear at `t`" — for the
+ * next open window. Sampling-based: pick `stepSeconds` at or below half the shortest gap that matters.
+ */
+export declare function nextClearWindow(isClear: (t: number) => boolean, scan: ClearWindowScan): ScheduleWindow | null;

package/dist/time/stateSchedule.js

@@ -0,0 +1,121 @@
+export function createStateSchedule(config) {
+    if (config.phases.length === 0)
+        throw new Error("state schedule needs at least one phase");
+    const phases = config.phases.map((phase) => {
+        if (!(phase.durationSeconds > 0)) {
+            throw new Error(`schedule phase duration must be positive, got ${phase.durationSeconds}`);
+        }
+        return phase;
+    });
+    const loop = config.loop ?? true;
+    const offset = config.offsetSeconds ?? 0;
+    const starts = [];
+    let cycleSeconds = 0;
+    for (const phase of phases) {
+        starts.push(cycleSeconds);
+        cycleSeconds += phase.durationSeconds;
+    }
+    function localTime(t) {
+        const shifted = t + offset;
+        if (loop)
+            return ((shifted % cycleSeconds) + cycleSeconds) % cycleSeconds;
+        return Math.max(0, shifted);
+    }
+    function sampleAt(t) {
+        const local = localTime(t);
+        if (!loop && local >= cycleSeconds) {
+            const index = phases.length - 1;
+            const phase = phases[index];
+            return {
+                state: phase.state,
+                index,
+                elapsedSeconds: local - starts[index],
+                remainingSeconds: Number.POSITIVE_INFINITY,
+                fraction: 1,
+            };
+        }
+        let index = phases.length - 1;
+        for (let i = 0; i < phases.length; i += 1) {
+            if (local < starts[i] + phases[i].durationSeconds) {
+                index = i;
+                break;
+            }
+        }
+        const phase = phases[index];
+        const elapsed = local - starts[index];
+        return {
+            state: phase.state,
+            index,
+            elapsedSeconds: elapsed,
+            remainingSeconds: phase.durationSeconds - elapsed,
+            fraction: Math.max(0, Math.min(1, elapsed / phase.durationSeconds)),
+        };
+    }
+    function nextTransitionAt(t) {
+        const sample = sampleAt(t);
+        if (!Number.isFinite(sample.remainingSeconds))
+            return Number.POSITIVE_INFINITY;
+        return t + sample.remainingSeconds;
+    }
+    function windowsOf(match, fromT, horizonSeconds) {
+        const windows = [];
+        const end = fromT + horizonSeconds;
+        let cursor = fromT;
+        let open = null;
+        let guard = phases.length * (Math.ceil(horizonSeconds / cycleSeconds) + 2) + 2;
+        while (cursor < end && guard > 0) {
+            guard -= 1;
+            const sample = sampleAt(cursor);
+            const matches = match(sample.state);
+            if (matches && open === null)
+                open = cursor;
+            const boundary = Number.isFinite(sample.remainingSeconds) ? cursor + sample.remainingSeconds : end;
+            const stop = Math.min(boundary, end);
+            if (!matches && open !== null) {
+                windows.push({ start: open, end: cursor });
+                open = null;
+            }
+            cursor = stop;
+            if (!Number.isFinite(sample.remainingSeconds))
+                break;
+        }
+        if (open !== null)
+            windows.push({ start: open, end: Math.min(cursor, end) });
+        return windows;
+    }
+    return {
+        cycleSeconds,
+        stateAt: (t) => sampleAt(t).state,
+        sampleAt,
+        nextTransitionAt,
+        windowsOf,
+        nextWindow(match, fromT, horizonSeconds = cycleSeconds) {
+            const windows = windowsOf(match, fromT, horizonSeconds);
+            return windows.length > 0 ? windows[0] : null;
+        },
+    };
+}
+/**
+ * Forward-scan any predicate-of-time — a timetable mover's "is the crossing clear at `t`" — for the
+ * next open window. Sampling-based: pick `stepSeconds` at or below half the shortest gap that matters.
+ */
+export function nextClearWindow(isClear, scan) {
+    const minDuration = scan.minDurationSeconds ?? 0;
+    const end = scan.fromSeconds + scan.horizonSeconds;
+    let open = null;
+    for (let t = scan.fromSeconds; t <= end; t += scan.stepSeconds) {
+        if (isClear(t)) {
+            if (open === null)
+                open = t;
+            continue;
+        }
+        if (open !== null) {
+            if (t - open >= minDuration)
+                return { start: open, end: t };
+            open = null;
+        }
+    }
+    if (open !== null && end - open >= minDuration)
+        return { start: open, end };
+    return null;
+}

package/dist/turn/commit.d.ts

@@ -1,4 +1,4 @@
-export type CommitMode = "immediate" | "simultaneous" | "rewind";
+export type CommitMode = "immediate" | "simultaneous" | "resealable";
 export interface SubmittedAction<TAction> {
     participant: string;
     action: TAction;
@@ -21,7 +21,7 @@ export interface CommitController<TAction> {
     pending(): SubmittedAction<TAction>[];
     reveal(): SubmittedAction<TAction>[];
     commit(): SubmittedAction<TAction>[];
-    rewind(): SubmittedAction<TAction>[];
+    discard(): SubmittedAction<TAction>[];
     clear(): void;
 }
 export declare function createCommitController<TAction>(config: CommitControllerConfig): CommitController<TAction>;

package/dist/turn/commit.js

@@ -31,7 +31,7 @@ export function createCommitController(config) {
             if (mode === "immediate") {
                 return { status: "committed", committed: [{ participant, action }] };
             }
-            if (sealed.has(participant) && !(mode === "rewind")) {
+            if (sealed.has(participant) && mode !== "resealable") {
                 return { status: "rejected", committed: [], reason: "already-submitted" };
             }
             sealed.set(participant, action);
@@ -62,7 +62,7 @@ export function createCommitController(config) {
             clear();
             return out;
         },
-        rewind() {
+        discard() {
             const discarded = orderedSubmissions();
             clear();
             return discarded;

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/hudLayout.d.ts

@@ -0,0 +1,58 @@
+export type HudAnchor = "top-left" | "top" | "top-right" | "left" | "center" | "right" | "bottom-left" | "bottom" | "bottom-right";
+export interface HudPlacement {
+    anchor: HudAnchor;
+    dx: number;
+    dy: number;
+}
+export interface HudRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface HudSize {
+    width: number;
+    height: number;
+}
+export interface HudPanelState {
+    id: string;
+    placement: HudPlacement;
+    z: number;
+    moved: boolean;
+}
+export interface HudLayoutState {
+    panels: Record<string, HudPanelState>;
+    locked: boolean;
+    editing: boolean;
+}
+export interface HudLayoutOptions {
+    snap?: number;
+    locked?: boolean;
+}
+export declare function isPanelDraggable(state: HudLayoutState, id: string): boolean;
+export interface HudLayoutStore {
+    getState(): HudLayoutState;
+    subscribe(listener: (state: HudLayoutState) => void): () => void;
+    register(id: string, placement: HudPlacement): void;
+    move(id: string, rect: HudRect, viewport: HudSize): void;
+    bringToFront(id: string): void;
+    setLocked(locked: boolean): void;
+    setEditing(editing: boolean): void;
+    reset(id?: string): void;
+    serialize(): string;
+    hydrate(raw: string | null | undefined): void;
+}
+export declare const HUD_ANCHOR_FRACTIONS: Record<HudAnchor, {
+    fx: number;
+    fy: number;
+}>;
+export declare function isHudAnchor(value: unknown): value is HudAnchor;
+export declare function anchoredPlacement(anchor: HudAnchor, inset: {
+    x: number;
+    y: number;
+}): HudPlacement;
+export declare function nearestAnchor(rect: HudRect, viewport: HudSize): HudAnchor;
+export declare function clampRect(rect: HudRect, viewport: HudSize): HudRect;
+export declare function placementFromRect(rect: HudRect, viewport: HudSize, snap?: number): HudPlacement;
+export declare function rectFromPlacement(placement: HudPlacement, size: HudSize, viewport: HudSize): HudRect;
+export declare function createHudLayout(options?: HudLayoutOptions): HudLayoutStore;