@jgengine/core 0.10.0 → 0.12.0

package/dist/store/observableKeyedStore.js

@@ -1,28 +1,45 @@
+/** @internal */
 export function createObservableKeyedStore(areEqual) {
     const store = new Map();
     const listeners = new Set();
+    const membershipListeners = new Set();
     const EMPTY = [];
+    const EMPTY_KEYS = [];
     let arrayCache = EMPTY;
     let arrayDirty = false;
+    let keysCache = EMPTY_KEYS;
+    let keysDirty = false;
+    let mapCache = new Map();
+    let mapDirty = false;
     function emit() {
         arrayDirty = true;
+        mapDirty = true;
         for (const listener of listeners)
             listener();
     }
+    function emitMembership() {
+        keysDirty = true;
+        for (const listener of membershipListeners)
+            listener();
+    }
     return {
         set(key, value) {
+            const had = store.has(key);
             const previous = store.get(key);
-            if (previous !== undefined && areEqual?.(previous, value))
+            if (had && areEqual?.(previous, value))
                 return;
             if (previous !== value)
                 store.set(key, value);
             emit();
+            if (!had)
+                emitMembership();
         },
         delete(key) {
             if (!store.has(key))
                 return;
             store.delete(key);
             emit();
+            emitMembership();
         },
         get(key) {
             return store.get(key);
@@ -34,8 +51,16 @@ export function createObservableKeyedStore(areEqual) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
+        subscribeMembership(listener) {
+            membershipListeners.add(listener);
+            return () => membershipListeners.delete(listener);
+        },
         mapSnapshot() {
-            return store;
+            if (mapDirty) {
+                mapCache = new Map(store);
+                mapDirty = false;
+            }
+            return mapCache;
         },
         arraySnapshot() {
             if (arrayDirty) {
@@ -44,6 +69,13 @@ export function createObservableKeyedStore(areEqual) {
             }
             return arrayCache;
         },
+        keysSnapshot() {
+            if (keysDirty) {
+                keysCache = store.size === 0 ? EMPTY_KEYS : Array.from(store.keys());
+                keysDirty = false;
+            }
+            return keysCache;
+        },
         snapshot() {
             return Array.from(store.entries());
         },
@@ -52,6 +84,7 @@ export function createObservableKeyedStore(areEqual) {
             for (const [key, value] of data)
                 store.set(key, value);
             emit();
+            emitMembership();
         },
     };
 }

package/dist/survival/decayMeter.d.ts

@@ -32,6 +32,7 @@ export interface DecayMeterState {
     /** 0..1 fill. */
     fraction: number;
 }
+/** Set of named survival meters (hunger/thirst/…) that drain and refill over game time. */
 export interface DecayMeterSet {
     /** Drain/fill every meter by `rate * rateModifier * dt`. Call once per game tick. */
     tick(dt: number): void;
@@ -49,11 +50,65 @@ export interface DecayMeterSet {
     snapshot(): Record<string, DecayMeterState>;
     ids(): readonly string[];
 }
+/**
+ * Plain-data meter values: `meter id → current value`. This is the whole serialized
+ * form — it drops straight into a `defineGame` state record and round-trips through
+ * save/load and multiplayer sync with no closure to rebuild.
+ */
+export type DecayMeterValues = Record<string, number>;
+/**
+ * Rate multiplier for {@link decayMeters}: one scalar applied to every meter (a member's
+ * metabolism, a game-mode harshness dial) or a per-meter record (cold biome → warmth only).
+ * `1` / omitted leaves the base rates unscaled.
+ */
+export type DecayModifier = number | Record<string, number>;
+/**
+ * Starting values for `defs` — each meter's `start ?? max`, clamped to its range. Seed a
+ * serialized state record with this instead of holding a {@link createDecayMeterSet} closure.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export declare function initDecayMeters(defs: readonly DecayMeterConfig[]): DecayMeterValues;
+/**
+ * Pure per-tick decay over plain data: drain (or fill) every meter by `rate * modifier * dt`,
+ * clamped to its range, returning a new `id → value` record. Returns `values` unchanged when
+ * `dt <= 0`. The serializable counterpart to {@link DecayMeterSet.tick}.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export declare function decayMeters(values: DecayMeterValues, defs: readonly DecayMeterConfig[], dt: number, modifier?: DecayModifier): DecayMeterValues;
+/**
+ * Refill (or drain, if negative) one meter by `amount`, clamped to its range. Returns a new
+ * record; throws on an unknown id. The pure counterpart to {@link DecayMeterSet.refill}.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export declare function refillMeter(values: DecayMeterValues, defs: readonly DecayMeterConfig[], id: string, amount: number): DecayMeterValues;
+/**
+ * Numeric state (value, bounds, 0..1 fraction) for one meter. Throws on an unknown id.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export declare function decayMeterState(values: DecayMeterValues, defs: readonly DecayMeterConfig[], id: string): DecayMeterState;
+/**
+ * Numeric state for every meter, keyed by id — the pure counterpart to {@link DecayMeterSet.snapshot}.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export declare function decayMeterSnapshot(values: DecayMeterValues, defs: readonly DecayMeterConfig[]): Record<string, DecayMeterState>;
+/**
+ * Moodles for every crossed threshold, worst-first per meter in declared order.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export declare function decayMeterMoodles(values: DecayMeterValues, defs: readonly DecayMeterConfig[]): Moodle[];
 /**
  * Named decay meters — hunger, thirst, oxygen, sanity, warmth, stamina. Each drains
  * (or recovers) on game-time `dt` at a configurable rate, refills from consumables or
  * actions, and raises moodle statuses at thresholds. Rate modifiers let the environment
  * drive them (colder → faster warmth loss; toxic biome → oxygen drops), so a game reads
  * an environment field then calls `setRateModifier`.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
  */
 export declare function createDecayMeterSet(configs: readonly DecayMeterConfig[]): DecayMeterSet;

package/dist/survival/decayMeter.js

@@ -1,91 +1,164 @@
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
+import { clamp } from "../math/scalar.js";
+function meterMin(def) {
+    return def.min ?? 0;
 }
-function toState(runtime) {
-    const span = runtime.max - runtime.min;
+function initialValue(def) {
+    return clamp(def.start ?? def.max, meterMin(def), def.max);
+}
+function valueOf(values, def) {
+    const current = values[def.id];
+    return current === undefined ? initialValue(def) : current;
+}
+function modifierFor(modifier, id) {
+    if (modifier === undefined)
+        return 1;
+    if (typeof modifier === "number")
+        return modifier;
+    return modifier[id] ?? 1;
+}
+function findDef(defs, id) {
+    const def = defs.find((candidate) => candidate.id === id);
+    if (def === undefined)
+        throw new Error(`unknown decay meter "${id}"`);
+    return def;
+}
+function stateOf(def, value) {
+    const min = meterMin(def);
+    const span = def.max - min;
     return {
-        id: runtime.config.id,
-        value: runtime.value,
-        max: runtime.max,
-        min: runtime.min,
-        fraction: span > 0 ? (runtime.value - runtime.min) / span : 0,
+        id: def.id,
+        value,
+        max: def.max,
+        min,
+        fraction: span > 0 ? (value - min) / span : 0,
     };
 }
 function crossed(threshold, value) {
     return threshold.when === "below" ? value < threshold.at : value > threshold.at;
 }
+/**
+ * Starting values for `defs` — each meter's `start ?? max`, clamped to its range. Seed a
+ * serialized state record with this instead of holding a {@link createDecayMeterSet} closure.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export function initDecayMeters(defs) {
+    const out = {};
+    for (const def of defs)
+        out[def.id] = initialValue(def);
+    return out;
+}
+/**
+ * Pure per-tick decay over plain data: drain (or fill) every meter by `rate * modifier * dt`,
+ * clamped to its range, returning a new `id → value` record. Returns `values` unchanged when
+ * `dt <= 0`. The serializable counterpart to {@link DecayMeterSet.tick}.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export function decayMeters(values, defs, dt, modifier) {
+    if (dt <= 0)
+        return values;
+    const out = {};
+    for (const def of defs) {
+        out[def.id] = clamp(valueOf(values, def) - def.rate * modifierFor(modifier, def.id) * dt, meterMin(def), def.max);
+    }
+    return out;
+}
+/**
+ * Refill (or drain, if negative) one meter by `amount`, clamped to its range. Returns a new
+ * record; throws on an unknown id. The pure counterpart to {@link DecayMeterSet.refill}.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export function refillMeter(values, defs, id, amount) {
+    const def = findDef(defs, id);
+    return { ...values, [id]: clamp(valueOf(values, def) + amount, meterMin(def), def.max) };
+}
+/**
+ * Numeric state (value, bounds, 0..1 fraction) for one meter. Throws on an unknown id.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export function decayMeterState(values, defs, id) {
+    const def = findDef(defs, id);
+    return stateOf(def, valueOf(values, def));
+}
+/**
+ * Numeric state for every meter, keyed by id — the pure counterpart to {@link DecayMeterSet.snapshot}.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export function decayMeterSnapshot(values, defs) {
+    const out = {};
+    for (const def of defs)
+        out[def.id] = stateOf(def, valueOf(values, def));
+    return out;
+}
+/**
+ * Moodles for every crossed threshold, worst-first per meter in declared order.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
+ */
+export function decayMeterMoodles(values, defs) {
+    const out = [];
+    for (const def of defs) {
+        const value = valueOf(values, def);
+        for (const threshold of def.thresholds ?? []) {
+            if (!crossed(threshold, value))
+                continue;
+            out.push({
+                id: threshold.id,
+                label: threshold.label,
+                severity: threshold.severity ?? "warning",
+                source: "meter",
+                stacks: 1,
+                ...(threshold.icon === undefined ? {} : { icon: threshold.icon }),
+                fraction: stateOf(def, value).fraction,
+            });
+        }
+    }
+    return out;
+}
 /**
  * Named decay meters — hunger, thirst, oxygen, sanity, warmth, stamina. Each drains
  * (or recovers) on game-time `dt` at a configurable rate, refills from consumables or
  * actions, and raises moodle statuses at thresholds. Rate modifiers let the environment
  * drive them (colder → faster warmth loss; toxic biome → oxygen drops), so a game reads
  * an environment field then calls `setRateModifier`.
+ *
+ * @capability decay-meter survival meters that drain/refill over game time (hunger, water, oxygen, stamina)
  */
 export function createDecayMeterSet(configs) {
-    const meters = new Map();
-    const order = [];
-    for (const config of configs) {
-        const min = config.min ?? 0;
-        const max = config.max;
-        const value = clamp(config.start ?? max, min, max);
-        meters.set(config.id, { config, min, max, value, rate: config.rate, modifier: 1 });
-        order.push(config.id);
-    }
-    const require = (id) => {
-        const runtime = meters.get(id);
-        if (runtime === undefined)
-            throw new Error(`unknown decay meter "${id}"`);
-        return runtime;
-    };
+    // Mutable copy so setRate can override a meter's base rate without mutating the caller's defs.
+    const defs = configs.map((config) => ({ ...config }));
+    const order = defs.map((def) => def.id);
+    const modifiers = {};
+    let values = initDecayMeters(defs);
     return {
         tick(dt) {
-            if (dt <= 0)
-                return;
-            for (const runtime of meters.values()) {
-                runtime.value = clamp(runtime.value - runtime.rate * runtime.modifier * dt, runtime.min, runtime.max);
-            }
+            values = decayMeters(values, defs, dt, modifiers);
         },
         value(id) {
-            return require(id).value;
+            return decayMeterState(values, defs, id).value;
         },
         state(id) {
-            return toState(require(id));
+            return decayMeterState(values, defs, id);
         },
         refill(id, amount) {
-            const runtime = require(id);
-            runtime.value = clamp(runtime.value + amount, runtime.min, runtime.max);
+            values = refillMeter(values, defs, id, amount);
         },
         setRate(id, rate) {
-            require(id).rate = rate;
+            findDef(defs, id).rate = rate;
         },
         setRateModifier(id, multiplier) {
-            require(id).modifier = multiplier;
+            findDef(defs, id);
+            modifiers[id] = multiplier;
         },
         moodles() {
-            const out = [];
-            for (const id of order) {
-                const runtime = meters.get(id);
-                for (const threshold of runtime.config.thresholds ?? []) {
-                    if (!crossed(threshold, runtime.value))
-                        continue;
-                    out.push({
-                        id: threshold.id,
-                        label: threshold.label,
-                        severity: threshold.severity ?? "warning",
-                        source: "meter",
-                        stacks: 1,
-                        ...(threshold.icon === undefined ? {} : { icon: threshold.icon }),
-                        fraction: toState(runtime).fraction,
-                    });
-                }
-            }
-            return out;
+            return decayMeterMoodles(values, defs);
         },
         snapshot() {
-            const out = {};
-            for (const id of order)
-                out[id] = toState(meters.get(id));
-            return out;
+            return decayMeterSnapshot(values, defs);
         },
         ids() {
             return order;

package/dist/survival/moodle.d.ts

@@ -1,5 +1,6 @@
 export type MoodleSeverity = "good" | "neutral" | "warning" | "critical";
 export type MoodleSource = "meter" | "ailment" | "buff";
+/** One survival moodle (status icon) — severity, source, and label for HUD chips. */
 export interface Moodle {
     id: string;
     label: string;
@@ -29,6 +30,7 @@ export interface TimedMoodleInput {
     /** Game-seconds until the moodle drops. Omit for a moodle that stays until removed. */
     duration?: number;
 }
+/** Ordered stack of active moodles derived from meters/ailments/buffs. */
 export interface MoodleStack {
     /** Add or refresh a timed moodle (Valheim food buff, a temporary shelter status). */
     add(input: TimedMoodleInput): void;

package/dist/survival/regionHealth.d.ts

@@ -49,6 +49,7 @@ export interface TreatResult {
     /** Ailment ids fully or partially cleared by the item. */
     treated: readonly string[];
 }
+/** Per-limb / per-region health track with treat/damage/heal APIs. */
 export interface MultiRegionHealth {
     damage(regionId: string, amount: number): DamageResult;
     heal(regionId: string, amount: number): RegionHealthState;
@@ -69,4 +70,9 @@ export interface MultiRegionHealth {
     ailmentMoodles(): Moodle[];
     readonly dead: boolean;
 }
+/**
+ * Per-region/limb health tracked separately, so each body part takes and heals damage on its own.
+ *
+ * @capability limb-health per-body-part/region health tracked separately
+ */
 export declare function createMultiRegionHealth(config: MultiRegionHealthConfig): MultiRegionHealth;

package/dist/survival/regionHealth.js

@@ -1,6 +1,9 @@
-function clamp(value, min, max) {
-    return value < min ? min : value > max ? max : value;
-}
+import { clamp } from "../math/scalar.js";
+/**
+ * Per-region/limb health tracked separately, so each body part takes and heals damage on its own.
+ *
+ * @capability limb-health per-body-part/region health tracked separately
+ */
 export function createMultiRegionHealth(config) {
     if (config.regions.length === 0) {
         throw new Error("createMultiRegionHealth: regions must be non-empty");

package/dist/tactics/fallingGrid.d.ts

@@ -51,12 +51,14 @@ export interface GravityIntervalConfig {
  * Gravity tick interval for a given level: linear speed-up with a floor, generalizing
  * a falling-block `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
  * with configurable base/step/floor.
- */
+  * @internal
+  */
 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 falling-block tetris
  * logic so any falling-block game can adopt it instead of reimplementing the grid.
- */
+  * @internal
+  */
 export declare function createFallingGrid<TCell>(config: FallingGridConfig): FallingGrid<TCell>;

package/dist/tactics/fallingGrid.js

@@ -2,7 +2,8 @@
  * Gravity tick interval for a given level: linear speed-up with a floor, generalizing
  * a falling-block `gravityInterval` (`max(0.05, 0.8 - level * 0.07)` seconds) to milliseconds
  * with configurable base/step/floor.
- */
+  * @internal
+  */
 export function gravityIntervalMs(level, config = {}) {
     const baseMs = config.baseMs ?? 800;
     const perLevel = config.perLevel ?? 70;
@@ -14,7 +15,8 @@ export function gravityIntervalMs(level, config = {}) {
  * footprint placement/collision, line-clear collapse, column-gravity settle (for match-3/sand
  * 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.
- */
+  * @internal
+  */
 export function createFallingGrid(config) {
     const cols = config.cols;
     const rows = config.rows;

package/dist/tactics/predictiveQuery.d.ts

@@ -23,7 +23,9 @@ export interface ArcPredictInput {
     effect?: string;
     requireReceive?: boolean;
 }
+/** @internal */
 export declare function predictAreaEffect(deps: PredictiveDeps, input: AreaPredictInput): PredictedTarget[];
+/** @internal */
 export declare function predictArcEffect(deps: PredictiveDeps, input: ArcPredictInput): PredictedTarget[];
 export interface TilePredictInput {
     at: EntityPosition;
@@ -31,4 +33,5 @@ export interface TilePredictInput {
     originTile: Tile;
     tileSize: number;
 }
+/** @internal */
 export declare function predictTiles(input: TilePredictInput): Tile[];

package/dist/tactics/predictiveQuery.js

@@ -5,10 +5,12 @@ function receiveGate(deps, effect, requireReceive) {
     const gate = deps.canReceive;
     return (instanceId) => gate(instanceId, effect) === null;
 }
+/** @internal */
 export function predictAreaEffect(deps, input) {
     const requireReceive = input.requireReceive ?? true;
     return resolveAreaTargets(deps.spatial, input, receiveGate(deps, input.effect, requireReceive));
 }
+/** @internal */
 export function predictArcEffect(deps, input) {
     const requireReceive = input.requireReceive ?? true;
     const gate = receiveGate(deps, input.effect, requireReceive);
@@ -26,6 +28,7 @@ export function predictArcEffect(deps, input) {
     }
     return targets;
 }
+/** @internal */
 export function predictTiles(input) {
     const reach = Math.ceil(input.radius / input.tileSize);
     const tiles = [];

package/dist/tactics/snapshot.d.ts

@@ -14,5 +14,7 @@ export interface SnapshotStore {
     depth(): number;
     clear(): void;
 }
+/** @internal */
 export declare function deepClone<T>(value: T): T;
+/** @internal */
 export declare function createSnapshotStore(): SnapshotStore;

package/dist/tactics/snapshot.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function deepClone(value) {
     if (value === null || typeof value !== "object")
         return value;
@@ -20,6 +21,7 @@ export function deepClone(value) {
         clone[k] = deepClone(v);
     return clone;
 }
+/** @internal */
 export function createSnapshotStore() {
     const slices = new Map();
     const stack = [];

package/dist/tactics/surface.d.ts

@@ -49,4 +49,5 @@ export interface SurfaceLayer {
     capture(): SurfaceLayerSnapshot;
     restore(snapshot: SurfaceLayerSnapshot): void;
 }
+/** @internal */
 export declare function createSurfaceLayer(config: SurfaceLayerConfig): SurfaceLayer;

package/dist/tactics/surface.js

@@ -8,6 +8,7 @@ function parseKey(k) {
 function pairKey(a, b) {
     return `${a}|${b}`;
 }
+/** @internal */
 export function createSurfaceLayer(config) {
     const durations = new Map();
     for (const k of config.kinds)

package/dist/tactics/tacticalGrid.d.ts

@@ -65,4 +65,5 @@ export interface TacticalGrid {
     /** A tile's world-space center. Requires `config.world`. */
     tileToWorld(tile: Tile): readonly [number, number];
 }
+/** @internal */
 export declare function createTacticalGrid(config: TacticalGridConfig): TacticalGrid;

package/dist/tactics/tacticalGrid.js

@@ -5,6 +5,7 @@ function parseKey(k) {
     const [c, r] = k.split(",");
     return [Number(c), Number(r)];
 }
+/** @internal */
 export function createTacticalGrid(config) {
     const width = config.width;
     const height = config.height;

package/dist/time/beatClock.d.ts

@@ -21,8 +21,11 @@ export interface BeatClock {
     beatDurationSec(): number;
     bpm(): number;
 }
+/** @internal */
 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). */
+/** Signed offset (game-seconds) from `nowSec` to the nearest beat boundary — negative = early, positive = late (#286.12).
+ * @internal
+ */
 export declare function nearestBeatDelta(nowSec: number, beatDurationSec: number): number;
 export interface BeatAccuracyTier {
     id: string;
@@ -36,11 +39,17 @@ export interface BeatJudgement {
     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. */
+/** Classify a press against the nearest beat into tiered judgements (perfect/good/miss by default). Tiers must be ordered tightest-first.
+ * @internal
+ */
 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). */
+/** Whether a snapshot sits inside a bar-relative open window `[fromBeat, toBeat)` — e.g. "act on beats 2-4 of every bar" (#286.12).
+ * @internal
+ */
 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. */
+/** 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.
+ * @internal
+ */
 export declare function nextBeatTime(nowSec: number, beatDurationSec: number, epsilon?: number): number;
 export interface BufferedAction<T> {
     action: T;
@@ -55,4 +64,5 @@ export interface BeatInputBuffer<T> {
     pendingCount(): number;
     clear(): void;
 }
+/** @internal */
 export declare function createBeatInputBuffer<T>(beatDurationSec: number): BeatInputBuffer<T>;

package/dist/time/beatClock.js

@@ -1,4 +1,5 @@
 const MAX_BEAT_FIRES = 10_000;
+/** @internal */
 export function createBeatClock(config, onBeat) {
     const beatsPerBar = config.beatsPerBar !== undefined && config.beatsPerBar > 0 ? config.beatsPerBar : 4;
     const beatDurationSec = 60 / config.bpm;
@@ -35,7 +36,9 @@ 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). */
+/** Signed offset (game-seconds) from `nowSec` to the nearest beat boundary — negative = early, positive = late (#286.12).
+ * @internal
+ */
 export function nearestBeatDelta(nowSec, beatDurationSec) {
     const beatIndex = Math.round(nowSec / beatDurationSec);
     return nowSec - beatIndex * beatDurationSec;
@@ -44,7 +47,9 @@ 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. */
+/** Classify a press against the nearest beat into tiered judgements (perfect/good/miss by default). Tiers must be ordered tightest-first.
+ * @internal
+ */
 export function classifyBeatAccuracy(nowSec, beatDurationSec, tiers = DEFAULT_BEAT_TIERS) {
     const deltaSec = nearestBeatDelta(nowSec, beatDurationSec);
     const magnitude = Math.abs(deltaSec);
@@ -54,13 +59,17 @@ export function classifyBeatAccuracy(nowSec, beatDurationSec, tiers = DEFAULT_BE
     }
     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). */
+/** Whether a snapshot sits inside a bar-relative open window `[fromBeat, toBeat)` — e.g. "act on beats 2-4 of every bar" (#286.12).
+ * @internal
+ */
 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. */
+/** 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.
+ * @internal
+ */
 export function nextBeatTime(nowSec, beatDurationSec, epsilon = QUANTIZE_EPSILON) {
     const beatIndex = nowSec / beatDurationSec;
     const rounded = Math.round(beatIndex);
@@ -68,6 +77,7 @@ export function nextBeatTime(nowSec, beatDurationSec, epsilon = QUANTIZE_EPSILON
         return rounded * beatDurationSec;
     return Math.ceil(beatIndex) * beatDurationSec;
 }
+/** @internal */
 export function createBeatInputBuffer(beatDurationSec) {
     const pending = [];
     return {

package/dist/time/calendarClock.d.ts

@@ -12,6 +12,9 @@ export interface GameTime {
     formattedTime: string;
     formatted: string;
 }
+/** @internal */
 export declare function computeGameTime(gameTimestamp: number): GameTime;
+/** @internal */
 export declare function computeClientServerOffset(serverNow: number, clientNow: number): number;
+/** @internal */
 export declare function getGameClockTimestamp(createdAt: number, serverNow: number, clientNow: number, gameTimeScale?: number): number;