@jgengine/core 0.8.0 → 0.9.0

package/dist/time/idleProgress.d.ts

@@ -0,0 +1,29 @@
+export interface IdleWindowConfig {
+    maxSeconds?: number;
+    efficiency?: number;
+}
+export interface IdleWindow {
+    elapsedSeconds: number;
+    effectiveSeconds: number;
+    capped: boolean;
+}
+export declare function idleWindow(lastSeenMs: number, nowMs: number, config?: IdleWindowConfig): IdleWindow;
+export interface LinearCatchUpInput {
+    current: number;
+    ratePerSecond: number;
+    min?: number;
+    max?: number;
+}
+export declare function linearCatchUp(seconds: number, input: LinearCatchUpInput): number;
+export interface ExponentialCatchUpInput {
+    current: number;
+    factorPerSecond: number;
+    min?: number;
+    max?: number;
+}
+export declare function exponentialCatchUp(seconds: number, input: ExponentialCatchUpInput): number;
+export interface SteppedCatchUpResult {
+    steps: number;
+    remainderSeconds: number;
+}
+export declare function steppedCatchUp(seconds: number, stepSeconds: number, step: (index: number) => void, maxSteps?: number): SteppedCatchUpResult;

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/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;

package/dist/ui/hudLayout.js

@@ -0,0 +1,207 @@
+export function isPanelDraggable(state, id) {
+    return state.panels[id] !== undefined && (state.editing || !state.locked);
+}
+export const HUD_ANCHOR_FRACTIONS = {
+    "top-left": { fx: 0, fy: 0 },
+    top: { fx: 0.5, fy: 0 },
+    "top-right": { fx: 1, fy: 0 },
+    left: { fx: 0, fy: 0.5 },
+    center: { fx: 0.5, fy: 0.5 },
+    right: { fx: 1, fy: 0.5 },
+    "bottom-left": { fx: 0, fy: 1 },
+    bottom: { fx: 0.5, fy: 1 },
+    "bottom-right": { fx: 1, fy: 1 },
+};
+const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+export function isHudAnchor(value) {
+    return typeof value === "string" && value in HUD_ANCHOR_FRACTIONS;
+}
+export function anchoredPlacement(anchor, inset) {
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+    return {
+        anchor,
+        dx: fx === 1 ? -inset.x : inset.x,
+        dy: fy === 1 ? -inset.y : inset.y,
+    };
+}
+export function nearestAnchor(rect, viewport) {
+    const cx = viewport.width > 0 ? (rect.x + rect.width / 2) / viewport.width : 0.5;
+    const cy = viewport.height > 0 ? (rect.y + rect.height / 2) / viewport.height : 0.5;
+    let best = "center";
+    let bestDist = Infinity;
+    for (const anchor of HUD_ANCHORS) {
+        const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+        const dist = (cx - fx) * (cx - fx) + (cy - fy) * (cy - fy);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = anchor;
+        }
+    }
+    return best;
+}
+export function clampRect(rect, viewport) {
+    return {
+        x: Math.max(0, Math.min(rect.x, viewport.width - rect.width)),
+        y: Math.max(0, Math.min(rect.y, viewport.height - rect.height)),
+        width: rect.width,
+        height: rect.height,
+    };
+}
+export function placementFromRect(rect, viewport, snap = 1) {
+    const clamped = clampRect(rect, viewport);
+    const anchor = nearestAnchor(clamped, viewport);
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+    const step = snap > 0 ? snap : 1;
+    const dx = clamped.x + fx * clamped.width - fx * viewport.width;
+    const dy = clamped.y + fy * clamped.height - fy * viewport.height;
+    return {
+        anchor,
+        dx: Math.round(dx / step) * step,
+        dy: Math.round(dy / step) * step,
+    };
+}
+export function rectFromPlacement(placement, size, viewport) {
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[placement.anchor];
+    return {
+        x: fx * viewport.width + placement.dx - fx * size.width,
+        y: fy * viewport.height + placement.dy - fy * size.height,
+        width: size.width,
+        height: size.height,
+    };
+}
+function parseSerialized(raw) {
+    const out = new Map();
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return out;
+    }
+    if (typeof data !== "object" || data === null)
+        return out;
+    const panels = data.panels;
+    if (typeof panels !== "object" || panels === null)
+        return out;
+    for (const [id, value] of Object.entries(panels)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const { anchor, dx, dy } = value;
+        if (!isHudAnchor(anchor))
+            continue;
+        if (typeof dx !== "number" || !Number.isFinite(dx))
+            continue;
+        if (typeof dy !== "number" || !Number.isFinite(dy))
+            continue;
+        out.set(id, { anchor, dx, dy });
+    }
+    return out;
+}
+export function createHudLayout(options) {
+    const snap = options?.snap ?? 1;
+    const defaults = new Map();
+    const pending = new Map();
+    let topZ = 0;
+    let state = { panels: {}, locked: options?.locked ?? true, editing: false };
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of [...listeners])
+            listener(state);
+    };
+    const setPanel = (panel) => {
+        state = { ...state, panels: { ...state.panels, [panel.id]: panel } };
+    };
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        register(id, placement) {
+            defaults.set(id, placement);
+            if (state.panels[id] !== undefined)
+                return;
+            const override = pending.get(id);
+            setPanel({
+                id,
+                placement: override ?? placement,
+                z: ++topZ,
+                moved: override !== undefined,
+            });
+        },
+        move(id, rect, viewport) {
+            const panel = state.panels[id];
+            if (panel === undefined)
+                return;
+            const placement = placementFromRect(rect, viewport, snap);
+            setPanel({ ...panel, placement, moved: true });
+            emit();
+        },
+        bringToFront(id) {
+            const panel = state.panels[id];
+            if (panel === undefined || panel.z === topZ)
+                return;
+            setPanel({ ...panel, z: ++topZ });
+            emit();
+        },
+        setLocked(locked) {
+            if (state.locked === locked)
+                return;
+            state = { ...state, locked };
+            emit();
+        },
+        setEditing(editing) {
+            if (state.editing === editing)
+                return;
+            state = { ...state, editing };
+            emit();
+        },
+        reset(id) {
+            const ids = id === undefined ? Object.keys(state.panels) : [id];
+            let changed = false;
+            for (const panelId of ids) {
+                pending.delete(panelId);
+                const panel = state.panels[panelId];
+                const fallback = defaults.get(panelId);
+                if (panel === undefined || fallback === undefined || !panel.moved)
+                    continue;
+                setPanel({ ...panel, placement: fallback, moved: false });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+        serialize() {
+            const panels = {};
+            for (const panel of Object.values(state.panels)) {
+                if (panel.moved)
+                    panels[panel.id] = panel.placement;
+            }
+            for (const [id, placement] of pending) {
+                if (state.panels[id] === undefined)
+                    panels[id] = placement;
+            }
+            const data = { v: 1, panels };
+            return JSON.stringify(data);
+        },
+        hydrate(raw) {
+            if (raw === null || raw === undefined || raw === "")
+                return;
+            const parsed = parseSerialized(raw);
+            if (parsed.size === 0)
+                return;
+            let changed = false;
+            for (const [id, placement] of parsed) {
+                const panel = state.panels[id];
+                if (panel === undefined) {
+                    pending.set(id, placement);
+                    continue;
+                }
+                setPanel({ ...panel, placement, moved: true });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+    };
+}

package/dist/ui/hudScale.d.ts

@@ -0,0 +1,44 @@
+import type { HudRect, HudSize } from "./hudLayout.js";
+/** Where a game is meant to be played. `"web"` alone keeps today's desktop-first HUD; adding `"mobile"` turns on design-resolution fit scaling on compact displays. */
+export type HudPlatform = "web" | "mobile";
+/**
+ * Design-resolution fit for the HUD surface. The game authors its UI against
+ * `designSize`; on smaller viewports the whole HUD scales down by the limiting
+ * axis ratio, clamped to `[minScale, maxScale]`, so panels keep their layout
+ * and simply shrink instead of overflowing.
+ */
+export interface HudFitConfig {
+    designSize?: HudSize;
+    /** Floor for the computed scale — below this, shrinking further makes text unreadable. Default 0.4. */
+    minScale?: number;
+    /** Ceiling for the computed scale. Default 1 (never upscale past authored size). */
+    maxScale?: number;
+}
+/** Per-game HUD viewport declaration carried on `PlayableGame.hudFit`; `mobile` overrides the fit on compact displays so the owner can tune the phone layout separately. */
+export interface HudViewportConfig extends HudFitConfig {
+    mobile?: HudFitConfig;
+}
+export declare const DEFAULT_HUD_DESIGN_SIZE: HudSize;
+export declare const DEFAULT_HUD_MIN_SCALE = 0.4;
+export declare const DEFAULT_HUD_MAX_SCALE = 1;
+export declare function resolveHudFit(config: HudViewportConfig | undefined, mobile: boolean): Required<HudFitConfig>;
+/**
+ * The one scaling rule for every display: the ratio of the live viewport to
+ * the authored design size along the limiting axis, clamped. 1 on a viewport
+ * at or above design size; smoothly below 1 down to `minScale` on phones.
+ */
+export declare function hudScaleForViewport(fit: Required<HudFitConfig>, viewport: HudSize): number;
+export interface HudOverflow {
+    id: string;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
+export declare function rectOverflow(rect: HudRect, viewport: HudSize, tolerance?: number): Omit<HudOverflow, "id"> | null;
+/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+export declare function overflowingPanels(panels: readonly {
+    id: string;
+    rect: HudRect;
+}[], viewport: HudSize, tolerance?: number): HudOverflow[];