@jgengine/core 0.8.0 → 0.10.0

package/dist/sensor/visionCone.d.ts

@@ -0,0 +1,31 @@
+export type VisionPoint = readonly [number, number];
+/** Structurally matches `world/walls` `WallSegment` — pass those straight in as occluders. */
+export interface VisionWall {
+    from: VisionPoint;
+    to: VisionPoint;
+}
+export interface VisionConeConfig {
+    range: number;
+    /** Full cone opening angle in radians (matches `TelegraphShape`'s cone `angle`). */
+    angle: number;
+}
+/** 2D segment intersection on the XZ plane (collinear overlaps count) — the LoS building block `revealQuery`/`frustumSensor` never shipped (#286.5). */
+export declare function segmentsIntersect(a1: VisionPoint, a2: VisionPoint, b1: VisionPoint, b2: VisionPoint): boolean;
+/** True when no wall segment crosses the sight line. */
+export declare function hasWallLineOfSight(from: VisionPoint, to: VisionPoint, walls: readonly VisionWall[]): boolean;
+/** Angle + range test only — no occlusion. `heading` is engine yaw (radians, `atan2(dx, dz)`). */
+export declare function pointInCone(origin: VisionPoint, heading: number, config: VisionConeConfig, point: VisionPoint): boolean;
+export interface VisionTarget<TId extends string = string> {
+    id: TId;
+    at: VisionPoint;
+}
+/**
+ * The guard-sight primitive every stealth game hand-rolled: an angle+range cone on the XZ plane
+ * whose sight lines are blocked by 2D wall segments (`world/walls` segments fit structurally).
+ * Pure math — feed entity positions and heading each tick.
+ */
+export interface VisionCone {
+    canSee(origin: VisionPoint, heading: number, target: VisionPoint): boolean;
+    visibleTargets<TId extends string>(origin: VisionPoint, heading: number, targets: readonly VisionTarget<TId>[]): TId[];
+}
+export declare function createVisionCone(config: VisionConeConfig, walls?: readonly VisionWall[]): VisionCone;

package/dist/sensor/visionCone.js

@@ -0,0 +1,72 @@
+function orientation(ax, az, bx, bz, cx, cz) {
+    const value = (bz - az) * (cx - bx) - (bx - ax) * (cz - bz);
+    if (value > 1e-9)
+        return 1;
+    if (value < -1e-9)
+        return -1;
+    return 0;
+}
+function onSegment(ax, az, bx, bz, cx, cz) {
+    return (Math.min(ax, bx) - 1e-9 <= cx &&
+        cx <= Math.max(ax, bx) + 1e-9 &&
+        Math.min(az, bz) - 1e-9 <= cz &&
+        cz <= Math.max(az, bz) + 1e-9);
+}
+/** 2D segment intersection on the XZ plane (collinear overlaps count) — the LoS building block `revealQuery`/`frustumSensor` never shipped (#286.5). */
+export function segmentsIntersect(a1, a2, b1, b2) {
+    const o1 = orientation(a1[0], a1[1], a2[0], a2[1], b1[0], b1[1]);
+    const o2 = orientation(a1[0], a1[1], a2[0], a2[1], b2[0], b2[1]);
+    const o3 = orientation(b1[0], b1[1], b2[0], b2[1], a1[0], a1[1]);
+    const o4 = orientation(b1[0], b1[1], b2[0], b2[1], a2[0], a2[1]);
+    if (o1 !== o2 && o3 !== o4)
+        return true;
+    if (o1 === 0 && onSegment(a1[0], a1[1], a2[0], a2[1], b1[0], b1[1]))
+        return true;
+    if (o2 === 0 && onSegment(a1[0], a1[1], a2[0], a2[1], b2[0], b2[1]))
+        return true;
+    if (o3 === 0 && onSegment(b1[0], b1[1], b2[0], b2[1], a1[0], a1[1]))
+        return true;
+    if (o4 === 0 && onSegment(b1[0], b1[1], b2[0], b2[1], a2[0], a2[1]))
+        return true;
+    return false;
+}
+/** True when no wall segment crosses the sight line. */
+export function hasWallLineOfSight(from, to, walls) {
+    for (const wall of walls) {
+        if (segmentsIntersect(from, to, wall.from, wall.to))
+            return false;
+    }
+    return true;
+}
+/** Angle + range test only — no occlusion. `heading` is engine yaw (radians, `atan2(dx, dz)`). */
+export function pointInCone(origin, heading, config, point) {
+    const dx = point[0] - origin[0];
+    const dz = point[1] - origin[1];
+    const distance = Math.hypot(dx, dz);
+    if (distance > config.range)
+        return false;
+    if (distance < 1e-9)
+        return true;
+    let delta = Math.atan2(dx, dz) - heading;
+    while (delta > Math.PI)
+        delta -= Math.PI * 2;
+    while (delta < -Math.PI)
+        delta += Math.PI * 2;
+    return Math.abs(delta) <= config.angle / 2;
+}
+export function createVisionCone(config, walls = []) {
+    function canSee(origin, heading, target) {
+        return pointInCone(origin, heading, config, target) && hasWallLineOfSight(origin, target, walls);
+    }
+    return {
+        canSee,
+        visibleTargets(origin, heading, targets) {
+            const seen = [];
+            for (const target of targets) {
+                if (canSee(origin, heading, target.at))
+                    seen.push(target.id);
+            }
+            return seen;
+        },
+    };
+}

package/dist/session/extraction.d.ts

@@ -38,11 +38,11 @@ export interface RaidPlayerSnapshot {
     remaining: number;
 }
 export interface RaidSession {
-    beginExtract(userId: string, extractId: string, team?: string): ContestedEvent | null;
+    beginExtract(userId: string, extractId: string, position: RingPoint, team?: string): ContestedEvent | null;
     tickExtract(userId: string, dt: number, occupants?: Record<string, number>): ContestedEvent[];
     damage(userId: string, reason?: string): ContestedEvent | null;
     cancelExtract(userId: string): void;
-    resolveExtraction(userId: string, containers: readonly ContainerSnapshot[]): ExtractionResult;
+    resolveExtraction(userId: string, containers: readonly ContainerSnapshot[]): ExtractionResult | null;
     resolveDeath(userId: string, containers: readonly ContainerSnapshot[], now: number, rng?: () => number): DeathResult;
     claimDeliveries(now: number): readonly DeliveryEntry[];
     pendingDeliveries(userId?: string): readonly DeliveryEntry[];

package/dist/session/extraction.js

@@ -1,5 +1,10 @@
 import { createDeliveryQueue, insureLost, partitionOnDeath, resolveConsolation, } from "../inventory/storageTier.js";
 import { createContestedChannel, } from "./contestedChannel.js";
+function inExtractZone(point, position) {
+    const dx = position[0] - point.center[0];
+    const dz = position[1] - point.center[1];
+    return dx * dx + dz * dz <= point.radius * point.radius;
+}
 function mergeAll(containers) {
     const totals = new Map();
     for (const container of containers) {
@@ -24,12 +29,14 @@ export function createRaidSession(config) {
         return statuses.get(userId) ?? "in-raid";
     }
     return {
-        beginExtract(userId, extractId, team) {
+        beginExtract(userId, extractId, position, team) {
             const point = points.get(extractId);
             if (point === undefined)
                 return null;
             if (statusOf(userId) === "extracted" || statusOf(userId) === "dead")
                 return null;
+            if (!inExtractZone(point, position))
+                return null;
             const channel = createContestedChannel({
                 duration: point.holdSeconds,
                 interruptOnDamage: point.interruptOnDamage ?? true,
@@ -65,7 +72,11 @@ export function createRaidSession(config) {
         },
         resolveExtraction(userId, containers) {
             const attempt = attempts.get(userId);
-            const extractId = attempt?.extractId ?? "";
+            if (attempt === undefined)
+                return null;
+            if (attempt.channel.phase() !== "complete" && statusOf(userId) !== "extracted")
+                return null;
+            const extractId = attempt.extractId;
             attempts.delete(userId);
             statuses.set(userId, "extracted");
             return { userId, extractId, banked: mergeAll(containers) };

package/dist/settings/settingsModel.d.ts

@@ -0,0 +1,97 @@
+import type { GameContext } from "../runtime/gameContext.js";
+export type SettingValue = number | boolean | string;
+export type SettingKind = "slider" | "toggle" | "select";
+export type BuiltInSettingCategory = "sound" | "graphics" | "gameplay" | "controls";
+/** Built-in category ids keep autocomplete; any other string makes a fresh category. */
+export type SettingCategory = BuiltInSettingCategory | (string & {});
+export declare const BUILT_IN_SETTING_CATEGORIES: readonly BuiltInSettingCategory[];
+export interface SettingOption {
+    value: string;
+    label: string;
+}
+/** Declares or relabels/reorders a category tab; use it for a custom category or to reshape the built-ins. */
+export interface SettingCategoryDef {
+    id: SettingCategory;
+    label: string;
+    order?: number;
+}
+/** Extra setting a game appends to a built-in category via `defineGame({ settings: { extra } })`. */
+export interface GameSettingDef {
+    id: string;
+    label: string;
+    category: SettingCategory;
+    kind: SettingKind;
+    default: SettingValue;
+    /** Slider bounds — always pass both for a `slider`; omitted defaults (0..1) collapse the thumb. */
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: readonly SettingOption[];
+    /** Applies the new value to game state; the value is already persisted before this runs. */
+    onChange?: (value: SettingValue, ctx: GameContext) => void;
+}
+/** `quick` shows compact on-screen volume/graphics buttons; `false` (default) mounts no engine trigger — open the menu from your own UI with `<SettingsTrigger>` or `useSettings().open()`. */
+export type SettingsSurface = "quick";
+/** The four themed settings layouts, chosen with `defineGame({ settings: { variant } })`. All read the game's `--jg-*` theme tokens. */
+export type SettingsVariant = "panel" | "sheet" | "sidebar" | "fullscreen";
+/** A game-state action (Restart, Quit to menu, …) shown as rows in the first "Game" settings tab — never a floating button or a rebindable key. */
+export interface SettingsActionDef {
+    id: string;
+    label: string;
+    /** `danger` styles destructive actions (restart, quit) apart from neutral ones. */
+    kind?: "default" | "danger";
+    /** Optional one-line hint under the label. */
+    description?: string;
+    /** Runs the action; the menu closes right after. */
+    run: (ctx: GameContext) => void;
+}
+export interface GameSettingsConfig {
+    /** Layout + skin of the menu; all four theme off `--jg-*`. Default `panel`. */
+    variant?: SettingsVariant;
+    /** `quick` shows compact on-screen volume/graphics buttons; omitted mounts no engine trigger — open the menu yourself with `<SettingsTrigger>` / `useSettings().open()`, or render `useSettings().categories` your own way. */
+    surface?: SettingsSurface | false;
+    /** Rows appended to any category — built-in or a brand-new one named by `category`. */
+    extra?: readonly GameSettingDef[];
+    /** Declare custom category tabs, or relabel/reorder the built-ins. */
+    categories?: readonly SettingCategoryDef[];
+    /** Built-in categories to hide. */
+    hide?: readonly SettingCategory[];
+    /** Game-state actions (Restart, Quit…) — become the first "Game" tab, shown before anything else. */
+    actions?: readonly SettingsActionDef[];
+    /** Input actions to drop from the rebindable Controls list — game-state keys like `restart` that belong in `actions`, not the rebind grid. */
+    hideBindings?: readonly string[];
+}
+export declare const SETTINGS_STORAGE_PREFIX = "jgengine:setting:";
+export declare const SETTING_IDS: {
+    readonly masterVolume: "sound.master";
+    readonly graphicsQuality: "graphics.quality";
+    readonly graphicsShadows: "graphics.shadows";
+    readonly graphicsUiScale: "graphics.uiScale";
+};
+export type GraphicsQuality = "low" | "medium" | "high";
+export declare const GRAPHICS_QUALITY_OPTIONS: readonly SettingOption[];
+export declare const DEFAULT_MASTER_VOLUME = 1;
+export declare const DEFAULT_GRAPHICS_QUALITY: GraphicsQuality;
+export declare const DEFAULT_GRAPHICS_SHADOWS = true;
+/** Player-controlled multiplier on the HUD's computed fit scale — one lever on desktop and mobile alike. */
+export declare const DEFAULT_UI_SCALE = 1;
+export declare const UI_SCALE_MIN = 0.5;
+export declare const UI_SCALE_MAX = 1.5;
+/** Device-pixel-ratio ceiling per quality tier — the shell's `Canvas` dpr cap. */
+export declare const GRAPHICS_QUALITY_DPR: Record<GraphicsQuality, number>;
+export declare function busVolumeSettingId(busId: string): string;
+export declare function settingStorageKey(id: string): string;
+interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+export declare function loadSettingValue<T extends SettingValue>(id: string, fallback: T, storage?: Pick<WebStorageLike, "getItem"> | null | undefined): T;
+export declare function saveSettingValue(id: string, value: SettingValue, storage?: Pick<WebStorageLike, "setItem"> | null | undefined): void;
+export interface SettingsStore {
+    get<T extends SettingValue>(id: string, fallback: T): T;
+    set(id: string, value: SettingValue): void;
+    subscribe(listener: () => void): () => void;
+}
+/** Reactive, localStorage-backed settings store shared by the shell wiring and React hooks. */
+export declare function createSettingsStore(storage?: Pick<WebStorageLike, "getItem" | "setItem"> | null | undefined): SettingsStore;
+export {};

package/dist/settings/settingsModel.js

@@ -0,0 +1,100 @@
+import { createObservableKeyedStore } from "../store/observableKeyedStore.js";
+export const BUILT_IN_SETTING_CATEGORIES = [
+    "sound",
+    "graphics",
+    "gameplay",
+    "controls",
+];
+export const SETTINGS_STORAGE_PREFIX = "jgengine:setting:";
+export const SETTING_IDS = {
+    masterVolume: "sound.master",
+    graphicsQuality: "graphics.quality",
+    graphicsShadows: "graphics.shadows",
+    graphicsUiScale: "graphics.uiScale",
+};
+export const GRAPHICS_QUALITY_OPTIONS = [
+    { value: "low", label: "Low" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High" },
+];
+export const DEFAULT_MASTER_VOLUME = 1;
+export const DEFAULT_GRAPHICS_QUALITY = "high";
+export const DEFAULT_GRAPHICS_SHADOWS = true;
+/** Player-controlled multiplier on the HUD's computed fit scale — one lever on desktop and mobile alike. */
+export const DEFAULT_UI_SCALE = 1;
+export const UI_SCALE_MIN = 0.5;
+export const UI_SCALE_MAX = 1.5;
+/** Device-pixel-ratio ceiling per quality tier — the shell's `Canvas` dpr cap. */
+export const GRAPHICS_QUALITY_DPR = {
+    low: 1,
+    medium: 1.5,
+    high: 2,
+};
+export function busVolumeSettingId(busId) {
+    return `sound.bus.${busId}`;
+}
+export function settingStorageKey(id) {
+    return `${SETTINGS_STORAGE_PREFIX}${id}`;
+}
+function defaultStorage() {
+    try {
+        if (typeof globalThis !== "undefined" && "localStorage" in globalThis) {
+            return globalThis.localStorage ?? null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function coerce(raw, fallback) {
+    if (typeof fallback === "number") {
+        const n = typeof raw === "number" ? raw : Number(raw);
+        return (Number.isFinite(n) ? n : fallback);
+    }
+    if (typeof fallback === "boolean") {
+        if (typeof raw === "boolean")
+            return raw;
+        return (raw === "true" ? true : raw === "false" ? false : fallback);
+    }
+    return (typeof raw === "string" ? raw : fallback);
+}
+export function loadSettingValue(id, fallback, storage = defaultStorage()) {
+    if (storage == null)
+        return fallback;
+    try {
+        const raw = storage.getItem(settingStorageKey(id));
+        if (raw === null)
+            return fallback;
+        return coerce(JSON.parse(raw), fallback);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function saveSettingValue(id, value, storage = defaultStorage()) {
+    if (storage == null)
+        return;
+    try {
+        storage.setItem(settingStorageKey(id), JSON.stringify(value));
+    }
+    catch {
+        /* ignore quota / private-mode failures */
+    }
+}
+/** Reactive, localStorage-backed settings store shared by the shell wiring and React hooks. */
+export function createSettingsStore(storage = defaultStorage()) {
+    const mem = createObservableKeyedStore();
+    return {
+        get(id, fallback) {
+            if (mem.has(id))
+                return coerce(mem.get(id), fallback);
+            return loadSettingValue(id, fallback, storage ?? undefined);
+        },
+        set(id, value) {
+            saveSettingValue(id, value, storage ?? undefined);
+            mem.set(id, value);
+        },
+        subscribe: mem.subscribe,
+    };
+}

package/dist/stats/statModifiers.d.ts

@@ -3,6 +3,9 @@ export interface StatModifier {
     multiply?: number;
 }
 export type StatModifierSet<TStat extends string> = Partial<Record<TStat, StatModifier>>;
+export interface CreateStatsOptions {
+    now?: () => number;
+}
 export interface Stats<TStat extends string> {
     setBase(stat: TStat, value: number): void;
     getBase(stat: TStat): number;
@@ -10,9 +13,9 @@ export interface Stats<TStat extends string> {
         expiresAtMs?: number;
     }): void;
     removeSource(sourceId: string): void;
-    hasSource(sourceId: string): boolean;
+    hasSource(sourceId: string, nowMs?: number): boolean;
     get(stat: TStat, nowMs?: number): number;
     pruneExpired(nowMs: number): string[];
     sources(): string[];
 }
-export declare function createStats<TStat extends string>(base: Record<TStat, number>): Stats<TStat>;
+export declare function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat>;

package/dist/stats/statModifiers.js

@@ -1,9 +1,23 @@
-export function createStats(base) {
+export function createStats(base, options) {
     const baseValues = { ...base };
     const sourceEntries = new Map();
+    const clock = options?.now;
+    function resolveNow(nowMs) {
+        return nowMs ?? clock?.();
+    }
     function isExpired(entry, nowMs) {
         return nowMs !== undefined && entry.expiresAtMs !== undefined && entry.expiresAtMs <= nowMs;
     }
+    function dropExpired(nowMs) {
+        const pruned = [];
+        for (const [sourceId, entry] of sourceEntries) {
+            if (isExpired(entry, nowMs)) {
+                sourceEntries.delete(sourceId);
+                pruned.push(sourceId);
+            }
+        }
+        return pruned;
+    }
     function resolve(stat, nowMs) {
         let total = baseValues[stat];
         let multiplier = 1;
@@ -27,27 +41,31 @@ export function createStats(base) {
         getBase(stat) {
             return baseValues[stat];
         },
-        addSource(sourceId, modifiers, options) {
-            sourceEntries.set(sourceId, { modifiers, expiresAtMs: options?.expiresAtMs });
+        addSource(sourceId, modifiers, sourceOptions) {
+            sourceEntries.set(sourceId, { modifiers, expiresAtMs: sourceOptions?.expiresAtMs });
         },
         removeSource(sourceId) {
             sourceEntries.delete(sourceId);
         },
-        hasSource(sourceId) {
-            return sourceEntries.has(sourceId);
+        hasSource(sourceId, nowMs) {
+            const entry = sourceEntries.get(sourceId);
+            if (entry === undefined)
+                return false;
+            const time = resolveNow(nowMs);
+            if (isExpired(entry, time)) {
+                sourceEntries.delete(sourceId);
+                return false;
+            }
+            return true;
         },
         get(stat, nowMs) {
-            return resolve(stat, nowMs);
+            const time = resolveNow(nowMs);
+            if (time !== undefined)
+                dropExpired(time);
+            return resolve(stat, time);
         },
         pruneExpired(nowMs) {
-            const pruned = [];
-            for (const [sourceId, entry] of sourceEntries) {
-                if (isExpired(entry, nowMs)) {
-                    sourceEntries.delete(sourceId);
-                    pruned.push(sourceId);
-                }
-            }
-            return pruned;
+            return dropExpired(nowMs);
         },
         sources() {
             return Array.from(sourceEntries.keys());

package/dist/store/observableKeyedStore.d.ts

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

package/dist/store/observableKeyedStore.js

@@ -3,8 +3,9 @@ export function createObservableKeyedStore(areEqual) {
     const listeners = new Set();
     const EMPTY = [];
     let arrayCache = EMPTY;
+    let arrayDirty = false;
     function emit() {
-        arrayCache = store.size === 0 ? EMPTY : Array.from(store.values());
+        arrayDirty = true;
         for (const listener of listeners)
             listener();
     }
@@ -13,7 +14,8 @@ export function createObservableKeyedStore(areEqual) {
             const previous = store.get(key);
             if (previous !== undefined && areEqual?.(previous, value))
                 return;
-            store.set(key, value);
+            if (previous !== value)
+                store.set(key, value);
             emit();
         },
         delete(key) {
@@ -36,7 +38,20 @@ export function createObservableKeyedStore(areEqual) {
             return store;
         },
         arraySnapshot() {
+            if (arrayDirty) {
+                arrayCache = store.size === 0 ? EMPTY : Array.from(store.values());
+                arrayDirty = false;
+            }
             return arrayCache;
         },
+        snapshot() {
+            return Array.from(store.entries());
+        },
+        hydrate(data) {
+            store.clear();
+            for (const [key, value] of data)
+                store.set(key, value);
+            emit();
+        },
     };
 }

package/dist/survival/decayMeter.d.ts

@@ -41,7 +41,7 @@ export interface DecayMeterSet {
     refill(id: string, amount: number): void;
     /** Overwrite the base drain rate (e.g. a game mode with harsher hunger). */
     setRate(id: string, rate: number): void;
-    /** Multiply the drain rate this tick onward — cold biome speeds warmth loss, sprint burns stamina. */
+    /** Multiply drain until cleared via `setRateModifier(id, 1)` — cold biome, sprint, etc. */
     setRateModifier(id: string, multiplier: number): void;
     /** Moodles for every crossed threshold, worst-first per meter. */
     moodles(): Moodle[];

package/dist/survival/decayMeter.js

@@ -43,7 +43,6 @@ export function createDecayMeterSet(configs) {
                 return;
             for (const runtime of meters.values()) {
                 runtime.value = clamp(runtime.value - runtime.rate * runtime.modifier * dt, runtime.min, runtime.max);
-                runtime.modifier = 1;
             }
         },
         value(id) {

package/dist/tactics/fallingGrid.d.ts

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

package/dist/tactics/fallingGrid.js

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

package/dist/time/beatClock.d.ts

@@ -22,6 +22,24 @@ export interface BeatClock {
     bpm(): number;
 }
 export declare function createBeatClock(config: BeatClockConfig, onBeat?: (beatIndex: number) => void): BeatClock;
+/** Signed offset (game-seconds) from `nowSec` to the nearest beat boundary — negative = early, positive = late (#286.12). */
+export declare function nearestBeatDelta(nowSec: number, beatDurationSec: number): number;
+export interface BeatAccuracyTier {
+    id: string;
+    /** Maximum absolute delta (game-seconds) from the beat that still earns this tier. */
+    windowSec: number;
+}
+export interface BeatJudgement {
+    /** The matched tier id, or `"miss"` beyond every tier. */
+    tier: string;
+    /** Signed delta to the nearest beat — negative = early, positive = late. */
+    deltaSec: number;
+}
+export declare const DEFAULT_BEAT_TIERS: readonly BeatAccuracyTier[];
+/** Classify a press against the nearest beat into tiered judgements (perfect/good/miss by default). Tiers must be ordered tightest-first. */
+export declare function classifyBeatAccuracy(nowSec: number, beatDurationSec: number, tiers?: readonly BeatAccuracyTier[]): BeatJudgement;
+/** Whether a snapshot sits inside a bar-relative open window `[fromBeat, toBeat)` — e.g. "act on beats 2-4 of every bar" (#286.12). */
+export declare function inBarWindow(snapshot: BeatSnapshot, fromBeat: number, toBeat: number): boolean;
 /** The absolute beat-time (game-seconds) that a press at `nowSec` quantizes to: the same instant if it lands on a beat boundary, else the next one. */
 export declare function nextBeatTime(nowSec: number, beatDurationSec: number, epsilon?: number): number;
 export interface BufferedAction<T> {

package/dist/time/beatClock.js

@@ -35,6 +35,30 @@ export function createBeatClock(config, onBeat) {
         bpm: () => config.bpm,
     };
 }
+/** Signed offset (game-seconds) from `nowSec` to the nearest beat boundary — negative = early, positive = late (#286.12). */
+export function nearestBeatDelta(nowSec, beatDurationSec) {
+    const beatIndex = Math.round(nowSec / beatDurationSec);
+    return nowSec - beatIndex * beatDurationSec;
+}
+export const DEFAULT_BEAT_TIERS = [
+    { id: "perfect", windowSec: 0.06 },
+    { id: "good", windowSec: 0.14 },
+];
+/** Classify a press against the nearest beat into tiered judgements (perfect/good/miss by default). Tiers must be ordered tightest-first. */
+export function classifyBeatAccuracy(nowSec, beatDurationSec, tiers = DEFAULT_BEAT_TIERS) {
+    const deltaSec = nearestBeatDelta(nowSec, beatDurationSec);
+    const magnitude = Math.abs(deltaSec);
+    for (const tier of tiers) {
+        if (magnitude <= tier.windowSec)
+            return { tier: tier.id, deltaSec };
+    }
+    return { tier: "miss", deltaSec };
+}
+/** Whether a snapshot sits inside a bar-relative open window `[fromBeat, toBeat)` — e.g. "act on beats 2-4 of every bar" (#286.12). */
+export function inBarWindow(snapshot, fromBeat, toBeat) {
+    const barBeat = snapshot.beatInBar + snapshot.phase;
+    return barBeat >= fromBeat && barBeat < toBeat;
+}
 const QUANTIZE_EPSILON = 1e-6;
 /** The absolute beat-time (game-seconds) that a press at `nowSec` quantizes to: the same instant if it lands on a beat boundary, else the next one. */
 export function nextBeatTime(nowSec, beatDurationSec, epsilon = QUANTIZE_EPSILON) {

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;