@jgengine/core 0.9.0 → 0.11.0

package/dist/ai/interestScheduler.js

@@ -0,0 +1,118 @@
+import { hashString } from "../random/rng.js";
+/**
+ * A deterministic `[0,1)` cadence phase derived from a stable id, for staggering sibling gates so a
+ * batch of agents spawned together does not fire their first active tick on the same frame. Pass the
+ * result as the `phase` argument to {@link createInterestGateState}.
+ *
+ * @capability interest-stagger deterministic per-id cadence phase that spreads sibling gate ticks across frames
+ */
+export function interestPhase(seed) {
+    const hashed = typeof seed === "number" ? hashString(String(seed)) : hashString(seed);
+    return (hashed % 100000) / 100000;
+}
+function nominalInterval(config) {
+    return config.activeInterval ?? config.tiers?.[0]?.interval ?? 0;
+}
+/**
+ * Create a dormant gate state, staggered by `phase` (`[0,1)`, typically {@link interestPhase} of the
+ * agent id) so siblings created together do not all fire their first active tick on the same frame.
+ *
+ * @capability interest-gate per-agent sleep/wake + cadence gate state so far agents skip expensive ticks
+ */
+export function createInterestGateState(config, phase = 0) {
+    const clamped = phase - Math.floor(phase);
+    return {
+        state: "dormant",
+        clock: clamped * nominalInterval(config),
+        awakeHold: 0,
+        phase: clamped,
+    };
+}
+function intervalFor(config, proximity) {
+    if (config.tiers !== undefined && proximity !== null) {
+        for (const tier of config.tiers) {
+            if (proximity <= tier.within)
+                return Math.max(0, tier.interval);
+        }
+    }
+    return Math.max(0, config.activeInterval ?? 0);
+}
+/**
+ * Advance one gate by `dt` seconds against this tick's `input`, mutating `state` in place and
+ * returning what the caller should do. Sleeping skips the expensive work (`active: false`) while the
+ * gate's timers keep advancing, so state is preserved; a `wake` signal or crossing `wakeRadius`
+ * flips it back to active and fires an immediate tick.
+ *
+ * @capability interest-scheduler advance a sleep/wake gate with hysteresis, cadence tiers, and stagger
+ */
+export function advanceInterestGate(state, config, dt, input = {}) {
+    const wakeRadius = config.wakeRadius;
+    const sleepRadius = Math.max(config.sleepRadius ?? wakeRadius, wakeRadius);
+    const proximity = input.proximity ?? null;
+    const prev = state.state;
+    if (input.wake === true) {
+        state.awakeHold = Math.max(state.awakeHold, config.stayAwakeSeconds ?? 0);
+    }
+    let want;
+    if (input.wake === true || state.awakeHold > 0) {
+        want = "active";
+    }
+    else if (proximity === null) {
+        want = prev;
+    }
+    else if (prev === "dormant") {
+        want = proximity <= wakeRadius ? "active" : "dormant";
+    }
+    else {
+        want = proximity > sleepRadius ? "dormant" : "active";
+    }
+    state.state = want;
+    const woke = prev === "dormant" && want === "active";
+    const slept = prev === "active" && want === "dormant";
+    let active = false;
+    if (want === "active") {
+        const interval = intervalFor(config, proximity);
+        if (interval <= 0 || woke || input.wake === true) {
+            active = true;
+            state.clock = 0;
+        }
+        else {
+            state.clock += dt;
+            if (state.clock >= interval) {
+                active = true;
+                state.clock -= interval;
+            }
+        }
+    }
+    else {
+        // Dormant: expensive work is skipped, but the gate keeps its timers so a later wake resumes cleanly.
+        state.clock = 0;
+    }
+    if (state.awakeHold > 0)
+        state.awakeHold = Math.max(0, state.awakeHold - dt);
+    return { state: want, active, woke, slept };
+}
+/**
+ * Create a census accumulator so the caller can tally active/dormant gates during the loop it already
+ * runs, avoiding any separate full-world scan just to report scheduler metrics.
+ *
+ * @capability interest-census running active/dormant gate tally folded into the caller's tick loop
+ */
+export function createInterestCensus() {
+    let active = 0;
+    let dormant = 0;
+    return {
+        record(state) {
+            const value = typeof state === "string" ? state : state.state;
+            if (value === "active")
+                active += 1;
+            else
+                dormant += 1;
+        },
+        snapshot: () => ({ active, dormant, total: active + dormant }),
+        reset() {
+            active = 0;
+            dormant = 0;
+        },
+    };
+}

package/dist/ai/jobBoard.d.ts

@@ -46,4 +46,5 @@ export interface JobBoard {
     active(): readonly Job[];
     list(): readonly Job[];
 }
+/** @internal */
 export declare function createJobBoard(): JobBoard;

package/dist/ai/jobBoard.js

@@ -2,6 +2,7 @@ const DEFAULT_ARRIVE_RADIUS = 0.75;
 function idleWorker() {
     return { jobId: null, phase: "idle", worked: 0, cycles: 0 };
 }
+/** @internal */
 export function createJobBoard() {
     const jobs = new Map();
     const workers = new Map();

package/dist/ai/laneSelect.d.ts

@@ -15,7 +15,10 @@ export interface PickLaneOptions<TId extends string = string> {
  * Live cost-based selection over parallel corridors (#286.7) — the racing-line / lane-merge pick
  * every AI driver hand-rolled. Evaluate each lane's cost this tick (crowding, hazards, distance)
  * and let stickiness hysteresis stop the agent flip-flopping between near-equal lanes.
- */
+  * @internal
+  */
 export declare function pickLane<TId extends string>(candidates: readonly LaneCandidate<TId>[], options?: PickLaneOptions<TId>): TId | null;
-/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`. */
+/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`.
+ * @internal
+ */
 export declare function corridorCost(points: readonly (readonly [number, number])[], costAt: (x: number, z: number) => number): number;

package/dist/ai/laneSelect.js

@@ -2,7 +2,8 @@
  * Live cost-based selection over parallel corridors (#286.7) — the racing-line / lane-merge pick
  * every AI driver hand-rolled. Evaluate each lane's cost this tick (crowding, hazards, distance)
  * and let stickiness hysteresis stop the agent flip-flopping between near-equal lanes.
- */
+  * @internal
+  */
 export function pickLane(candidates, options = {}) {
     if (candidates.length === 0)
         return null;
@@ -28,7 +29,9 @@ export function pickLane(candidates, options = {}) {
     }
     return best.id;
 }
-/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`. */
+/** Sum a live cost function over a corridor's sample points — the standard way to build `LaneCandidate.cost`.
+ * @internal
+ */
 export function corridorCost(points, costAt) {
     let total = 0;
     for (const [x, z] of points)

package/dist/ai/mobBrain.d.ts

@@ -65,4 +65,5 @@ export interface MobBrain {
     /** Back to idle at full rest (respawn) — clears threat, evade, and wander state. */
     reset(): void;
 }
+/** @internal */
 export declare function createMobBrain(config: MobBrainConfig, deps: MobBrainDeps): MobBrain;

package/dist/ai/mobBrain.js

@@ -9,6 +9,7 @@ const HOLD = {
 function distance(a, b) {
     return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
 }
+/** @internal */
 export function createMobBrain(config, deps) {
     const threat = createThreatTable(config.threat);
     const stickiness = config.stickiness ?? 1.15;

package/dist/ai/spawnDirector.d.ts

@@ -1,4 +1,5 @@
 import type { NavPoint } from "../nav/navGrid.js";
+import { type RandomSeed } from "../random/rng.js";
 export interface SpawnEntry {
     id: string;
     cost: number;
@@ -32,7 +33,8 @@ export interface SpawnDirectorState {
     alert: number;
     spawnedThisWave: number;
     spawnedTotal: number;
-    rng: number;
+    /** Opaque PRNG cursor — round-trip it as part of the state, never read or set it directly. */
+    rng: RandomSeed;
     done: boolean;
 }
 export interface DirectorContext {
@@ -47,6 +49,19 @@ export interface SpawnRequest {
     point?: NavPoint;
     laneId?: number;
 }
+/** Preference for picking a spawn point relative to `avoid` positions: closer, farther, or unweighted. */
+export type SpawnPointDistanceBias = "near" | "far" | "none";
+/** How strongly `distanceBias` weights candidates by distance from `avoid` — a named intent, not a weighting exponent. */
+export type SpawnPointBiasStrength = "subtle" | "moderate" | "strong";
+/** Semantic options for selecting a spawn point without exposing weighting internals. */
+export interface SpawnPointSelectionOptions {
+    candidates: readonly NavPoint[];
+    avoid?: readonly NavPoint[];
+    random: () => number;
+    distanceBias?: SpawnPointDistanceBias;
+    /** Default `"moderate"`. */
+    biasStrength?: SpawnPointBiasStrength;
+}
 export interface DirectorStep {
     state: SpawnDirectorState;
     spawns: SpawnRequest[];
@@ -55,6 +70,9 @@ export declare function createSpawnDirectorState(config: SpawnDirectorConfig): S
 export declare function raiseAlert(state: SpawnDirectorState, amount: number): SpawnDirectorState;
 export declare function advanceWave(config: SpawnDirectorConfig, state: SpawnDirectorState): SpawnDirectorState;
 export declare function advanceSpawnDirector(config: SpawnDirectorConfig, state: SpawnDirectorState, dt: number, ctx: DirectorContext): DirectorStep;
+/** Selects a candidate spawn point using a semantic distance preference and caller-supplied randomness. */
+export declare function pickSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null;
+/** @deprecated Pass one SpawnPointSelectionOptions object instead. */
 export declare function pickSpawnPoint(points: readonly NavPoint[], players: readonly NavPoint[], options: {
     roll: number;
     bias?: number;

package/dist/ai/spawnDirector.js

@@ -1,12 +1,14 @@
+import { randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+const BIAS_STRENGTH_EXPONENT = {
+    subtle: 0.5,
+    moderate: 1,
+    strong: 2,
+};
+function biasStrengthFromMagnitude(magnitude) {
+    return magnitude <= 0.5 ? "subtle" : magnitude >= 1.5 ? "strong" : "moderate";
+}
 const DEFAULT_MAX_SPAWNS_PER_TICK = 64;
 const DEFAULT_ALERT_DECAY = 0.1;
-function nextRandom(seed) {
-    const next = (seed + 0x6d2b79f5) | 0;
-    let t = Math.imul(next ^ (next >>> 15), 1 | next);
-    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-    const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    return [value, next];
-}
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -20,7 +22,7 @@ export function createSpawnDirectorState(config) {
         alert: 0,
         spawnedThisWave: 0,
         spawnedTotal: 0,
-        rng: (config.seed ?? 1) | 0,
+        rng: randomSeedFrom(config.seed ?? 1),
         done: config.waves.length === 0,
     };
 }
@@ -56,7 +58,7 @@ function pickEntry(entries, wave, budget, rng) {
     }
     if (affordable.length === 0 || total <= 0)
         return null;
-    const [roll, nextRng] = nextRandom(rng);
+    const [roll, nextRng] = stepRandomSeed(rng);
     let cursor = roll * total;
     for (const entry of affordable) {
         cursor -= entry.weight ?? 1;
@@ -116,9 +118,16 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
         budget -= picked.entry.cost;
         const spawn = { entryId: picked.entry.id, cost: picked.entry.cost, wave };
         if (spawnPoints !== undefined && spawnPoints.length > 0) {
-            const [roll, nextRng] = nextRandom(rng);
+            const [roll, nextRng] = stepRandomSeed(rng);
             rng = nextRng;
-            const point = pickSpawnPoint(spawnPoints, playerPositions, { roll, bias: config.spawnPointBias });
+            const bias = config.spawnPointBias ?? 1;
+            const point = pickSpawnPoint({
+                candidates: spawnPoints,
+                avoid: playerPositions,
+                random: () => roll,
+                distanceBias: bias < 0 ? "far" : bias > 0 ? "near" : "none",
+                biasStrength: biasStrengthFromMagnitude(Math.abs(bias)),
+            });
             if (point !== null) {
                 spawn.point = point;
                 spawn.laneId = spawnPoints.indexOf(point);
@@ -134,29 +143,47 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
         spawns,
     };
 }
-export function pickSpawnPoint(points, players, options) {
-    if (points.length === 0)
+export function pickSpawnPoint(optionsOrPoints, legacyPlayers = [], legacyOptions = { roll: 0 }) {
+    let options;
+    if (Array.isArray(optionsOrPoints)) {
+        const legacyBias = legacyOptions.bias ?? 1;
+        options = {
+            candidates: optionsOrPoints,
+            avoid: legacyPlayers,
+            random: () => legacyOptions.roll,
+            distanceBias: legacyBias < 0 ? "far" : legacyBias > 0 ? "near" : "none",
+            biasStrength: biasStrengthFromMagnitude(Math.abs(legacyBias)),
+        };
+    }
+    else {
+        options = optionsOrPoints;
+    }
+    const { candidates, avoid = [], random, distanceBias = "near", biasStrength = "moderate" } = options;
+    if (candidates.length === 0)
         return null;
-    const bias = options.bias ?? 1;
+    if (distanceBias === "none" || avoid.length === 0) {
+        return candidates[Math.min(candidates.length - 1, Math.floor(clamp01(random()) * candidates.length))];
+    }
+    const strength = BIAS_STRENGTH_EXPONENT[biasStrength];
+    const exponent = distanceBias === "far" ? strength : -strength;
     const weights = [];
     let total = 0;
-    for (const point of points) {
+    for (const point of candidates) {
         let nearest = Number.POSITIVE_INFINITY;
-        for (const player of players) {
-            const d = Math.hypot(point[0] - player[0], point[1] - player[1]);
-            if (d < nearest)
-                nearest = d;
+        for (const avoidedPoint of avoid) {
+            const distance = Math.hypot(point[0] - avoidedPoint[0], point[1] - avoidedPoint[1]);
+            if (distance < nearest)
+                nearest = distance;
         }
-        const distance = nearest === Number.POSITIVE_INFINITY ? 0 : nearest;
-        const weight = Math.max(1e-6, (1 + distance) ** -bias);
+        const weight = Math.max(1e-6, (1 + nearest) ** exponent);
         weights.push(weight);
         total += weight;
     }
-    let cursor = clamp01(options.roll) * total;
-    for (let i = 0; i < points.length; i += 1) {
-        cursor -= weights[i];
+    let cursor = clamp01(random()) * total;
+    for (let index = 0; index < candidates.length; index += 1) {
+        cursor -= weights[index];
         if (cursor <= 0)
-            return points[i];
+            return candidates[index];
     }
-    return points[points.length - 1];
+    return candidates[candidates.length - 1];
 }

package/dist/ai/spawnPoint.d.ts

@@ -0,0 +1,7 @@
+import type { NavPoint } from "../nav/navGrid.js";
+import { type SpawnPointDistanceBias, type SpawnPointSelectionOptions } from "./spawnDirector.js";
+export type { SpawnPointDistanceBias, SpawnPointSelectionOptions };
+/** Selects a spawn point by game intent while keeping weighting mechanics internal.
+ * @internal
+ */
+export declare function selectSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null;

package/dist/ai/spawnPoint.js

@@ -0,0 +1,7 @@
+import { pickSpawnPoint, } from "./spawnDirector.js";
+/** Selects a spawn point by game intent while keeping weighting mechanics internal.
+ * @internal
+ */
+export function selectSpawnPoint(options) {
+    return pickSpawnPoint(options);
+}

package/dist/ai/targetAcquisition.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Composable target acquisition: the "which enemy do I lock onto?" decision split into the
+ * independent concerns every aggro system tangles together — a bounded candidate provider, an
+ * eligibility filter, a per-pair acquisition envelope (dynamic range), a perception/LOS gate,
+ * scoring, deterministic tie-break, and retention hysteresis. This owns *policy*; threat, brains,
+ * and movement stay separate. Feed `candidates` a spatial-index query, never a full-world scan.
+ */
+/** A per-pair acquisition range: a static radius, or a function that varies range by pair. */
+export type AcquisitionEnvelope = number | ((selfId: string, candidateId: string) => number);
+/** Retention hysteresis that keeps an already-held target from flickering under churn. */
+export interface AcquisitionRetention {
+    /**
+     * A challenger's score must beat the held target's by at least this additive margin to steal
+     * acquisition. Keeps the lock stable when scores are near-tied. Default `0` (any win switches).
+     */
+    readonly switchMargin?: number;
+    /**
+     * The held target keeps acquisition out to `range * dropRangeScale` before it is dropped, so a
+     * target does not un-acquire the instant it steps past the acquisition edge. Default `1`.
+     */
+    readonly dropRangeScale?: number;
+}
+/**
+ * A fully composed acquisition policy. Every concern is an independent, injectable seam; the only
+ * required pieces are the bounded `candidates` provider and the `distance` metric. Omit the rest to
+ * fall back to the thin default — a static/unbounded range, everything eligible and perceptible,
+ * nearest-wins scoring, id tie-break, no hysteresis — which matches a plain proximity aggro radius.
+ */
+export interface AcquisitionPolicy {
+    /** Bounded candidate ids for `selfId` — wire a spatial-index query here, not a whole-world list. */
+    readonly candidates: (selfId: string) => Iterable<string>;
+    /** Distance self→candidate; `null` rejects the candidate (despawned / unmeasurable). */
+    readonly distance: (selfId: string, candidateId: string) => number | null;
+    /** Per-pair acquisition range (the dynamic envelope). Default `Infinity` (range-unbounded). */
+    readonly range?: AcquisitionEnvelope;
+    /** Eligibility filter run first — faction, alive, targetable, stealth, ownership. Default: all pass. */
+    readonly eligible?: (selfId: string, candidateId: string) => boolean;
+    /** Perception / line-of-sight gate run last (after range) because it is the costly check. */
+    readonly perceptible?: (selfId: string, candidateId: string, distance: number) => boolean;
+    /** Score of an in-range candidate; the highest wins. Default: nearest (`-distance`). */
+    readonly score?: (selfId: string, candidateId: string, distance: number) => number;
+    /** Deterministic tie-break when scores are equal (return <0 to prefer `a`). Default: id order. */
+    readonly tieBreak?: (a: string, b: string) => number;
+    /** Retention/hysteresis for an already-held target. Omit for no stickiness. */
+    readonly retention?: AcquisitionRetention;
+}
+/** Outcome of one acquisition pass. */
+export interface AcquisitionResult {
+    /** The chosen target, or `null` when nothing qualifies. */
+    readonly targetId: string | null;
+    /** True when `targetId` differs from the `held` target passed in (a fresh acquire or a switch). */
+    readonly changed: boolean;
+    /** Candidates that passed eligibility + range + perception this pass — a cheap tuning/metric signal. */
+    readonly considered: number;
+}
+/**
+ * Run one acquisition pass and pick the best target under `policy`. Pass the currently `held` target
+ * so retention hysteresis (`switchMargin`, `dropRangeScale`) can keep the lock stable; pass `null`
+ * for a cold acquire. Pure and allocation-light — the caller owns the held-target state.
+ *
+ * @capability target-acquisition composable candidate/eligibility/range/perception/score/tie-break/retention target pick
+ */
+export declare function acquireTarget(policy: AcquisitionPolicy, selfId: string, held?: string | null): AcquisitionResult;
+/** A stateful acquirer that holds the current target across passes — sugar over {@link acquireTarget}. */
+export interface TargetAcquirer {
+    /** Re-run acquisition for `selfId`, update the held target, and return it. */
+    acquire(selfId: string): string | null;
+    /** The held target without re-running acquisition. */
+    target(): string | null;
+    /** Candidates considered on the last {@link acquire} pass. */
+    considered(): number;
+    /** Force the held target — external override for taunt, script, or ownership handoff. */
+    hold(targetId: string | null): void;
+    /** Drop back to unacquired. */
+    clear(): void;
+}
+/**
+ * Wrap an {@link AcquisitionPolicy} in a small object that remembers the held target between passes,
+ * so callers get retention hysteresis for free without threading the previous target by hand. The
+ * only state is the held id (a string) — trivially serializable; round-trip it with {@link TargetAcquirer.hold}.
+ *
+ * @capability target-acquirer stateful held-target wrapper over an acquisition policy with retention
+ */
+export declare function createTargetAcquirer(policy: AcquisitionPolicy): TargetAcquirer;

package/dist/ai/targetAcquisition.js

@@ -0,0 +1,92 @@
+/**
+ * Composable target acquisition: the "which enemy do I lock onto?" decision split into the
+ * independent concerns every aggro system tangles together — a bounded candidate provider, an
+ * eligibility filter, a per-pair acquisition envelope (dynamic range), a perception/LOS gate,
+ * scoring, deterministic tie-break, and retention hysteresis. This owns *policy*; threat, brains,
+ * and movement stay separate. Feed `candidates` a spatial-index query, never a full-world scan.
+ */
+function resolveRange(range, selfId, candidateId) {
+    if (range === undefined)
+        return Number.POSITIVE_INFINITY;
+    return typeof range === "number" ? range : range(selfId, candidateId);
+}
+function defaultTieBreak(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Run one acquisition pass and pick the best target under `policy`. Pass the currently `held` target
+ * so retention hysteresis (`switchMargin`, `dropRangeScale`) can keep the lock stable; pass `null`
+ * for a cold acquire. Pure and allocation-light — the caller owns the held-target state.
+ *
+ * @capability target-acquisition composable candidate/eligibility/range/perception/score/tie-break/retention target pick
+ */
+export function acquireTarget(policy, selfId, held = null) {
+    const tieBreak = policy.tieBreak ?? defaultTieBreak;
+    const dropScale = Math.max(0, policy.retention?.dropRangeScale ?? 1);
+    const switchMargin = policy.retention?.switchMargin ?? 0;
+    let considered = 0;
+    let bestId = null;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    let heldSeen = false;
+    let heldScore = Number.NEGATIVE_INFINITY;
+    for (const candidateId of policy.candidates(selfId)) {
+        if (candidateId === selfId)
+            continue;
+        if (policy.eligible !== undefined && !policy.eligible(selfId, candidateId))
+            continue;
+        const d = policy.distance(selfId, candidateId);
+        if (d === null)
+            continue;
+        const range = resolveRange(policy.range, selfId, candidateId);
+        const effectiveRange = candidateId === held ? range * dropScale : range;
+        if (d > effectiveRange)
+            continue;
+        if (policy.perceptible !== undefined && !policy.perceptible(selfId, candidateId, d))
+            continue;
+        considered += 1;
+        const score = policy.score === undefined ? -d : policy.score(selfId, candidateId, d);
+        if (candidateId === held) {
+            heldSeen = true;
+            heldScore = score;
+        }
+        if (bestId === null ||
+            score > bestScore ||
+            (score === bestScore && tieBreak(candidateId, bestId) < 0)) {
+            bestId = candidateId;
+            bestScore = score;
+        }
+    }
+    // Retention: an in-range held target keeps the lock unless a challenger clears the switch margin.
+    if (heldSeen && held !== null && bestId !== held && bestScore < heldScore + switchMargin) {
+        return { targetId: held, changed: false, considered };
+    }
+    return { targetId: bestId, changed: bestId !== held, considered };
+}
+/**
+ * Wrap an {@link AcquisitionPolicy} in a small object that remembers the held target between passes,
+ * so callers get retention hysteresis for free without threading the previous target by hand. The
+ * only state is the held id (a string) — trivially serializable; round-trip it with {@link TargetAcquirer.hold}.
+ *
+ * @capability target-acquirer stateful held-target wrapper over an acquisition policy with retention
+ */
+export function createTargetAcquirer(policy) {
+    let held = null;
+    let considered = 0;
+    return {
+        acquire(selfId) {
+            const result = acquireTarget(policy, selfId, held);
+            held = result.targetId;
+            considered = result.considered;
+            return held;
+        },
+        target: () => held,
+        considered: () => considered,
+        hold(targetId) {
+            held = targetId;
+        },
+        clear() {
+            held = null;
+            considered = 0;
+        },
+    };
+}

package/dist/anim/easing.d.ts

@@ -1,14 +1,33 @@
 export type Easing = (t: number) => number;
+/** Linearly interpolate from `from` to `to` by fraction `t` (unclamped).
+ * @internal
+ */
 export declare function lerp(from: number, to: number, t: number): number;
+/** Constrain `t` to the unit range `[0, 1]`.
+ * @internal
+ */
 export declare function clamp01(t: number): number;
+/** Smooth Hermite interpolation of `t` across `[0, 1]`, easing both ends.
+ * @internal
+ */
 export declare function smoothstep(t: number): number;
+/** @internal */
 export declare function easeInQuad(t: number): number;
+/** @internal */
 export declare function easeOutQuad(t: number): number;
+/** @internal */
 export declare function easeInOutQuad(t: number): number;
+/** @internal */
 export declare function easeInCubic(t: number): number;
+/** @internal */
 export declare function easeOutCubic(t: number): number;
+/** @internal */
 export declare function easeInOutCubic(t: number): number;
+/** @internal */
 export declare function easeOutBack(t: number): number;
+/** @internal */
 export declare function easeOutElastic(t: number): number;
+/** @internal */
 export declare function tween(from: number, to: number, t: number, easing?: Easing): number;
+/** @internal */
 export declare function timedProgress(startedAt: number, now: number, durationMs: number): number;

package/dist/anim/easing.js

@@ -1,53 +1,72 @@
+/** Linearly interpolate from `from` to `to` by fraction `t` (unclamped).
+ * @internal
+ */
 export function lerp(from, to, t) {
     return from + (to - from) * t;
 }
+/** Constrain `t` to the unit range `[0, 1]`.
+ * @internal
+ */
 export function clamp01(t) {
     return t < 0 ? 0 : t > 1 ? 1 : t;
 }
+/** Smooth Hermite interpolation of `t` across `[0, 1]`, easing both ends.
+ * @internal
+ */
 export function smoothstep(t) {
     const c = clamp01(t);
     return c * c * (3 - 2 * c);
 }
+/** @internal */
 export function easeInQuad(t) {
     const c = clamp01(t);
     return c * c;
 }
+/** @internal */
 export function easeOutQuad(t) {
     const c = clamp01(t);
     return 1 - (1 - c) * (1 - c);
 }
+/** @internal */
 export function easeInOutQuad(t) {
     const c = clamp01(t);
     return c < 0.5 ? 2 * c * c : 1 - ((-2 * c + 2) ** 2) / 2;
 }
+/** @internal */
 export function easeInCubic(t) {
     const c = clamp01(t);
     return c * c * c;
 }
+/** @internal */
 export function easeOutCubic(t) {
     const c = clamp01(t);
     return 1 - (1 - c) ** 3;
 }
+/** @internal */
 export function easeInOutCubic(t) {
     const c = clamp01(t);
     return c < 0.5 ? 4 * c * c * c : 1 - ((-2 * c + 2) ** 3) / 2;
 }
 const BACK_OVERSHOOT = 1.70158;
+/** @internal */
 export function easeOutBack(t) {
     const c = clamp01(t);
     const s = BACK_OVERSHOOT + 1;
     return 1 + s * (c - 1) ** 3 + BACK_OVERSHOOT * (c - 1) ** 2;
 }
 const ELASTIC_PERIOD = (2 * Math.PI) / 3;
+/** @internal */
 export function easeOutElastic(t) {
     const c = clamp01(t);
     if (c === 0 || c === 1)
         return c;
     return 2 ** (-10 * c) * Math.sin((c * 10 - 0.75) * ELASTIC_PERIOD) + 1;
 }
+/** @internal */
 export function tween(from, to, t, easing = smoothstep) {
     return lerp(from, to, easing(clamp01(t)));
 }
+/** @internal */
 export function timedProgress(startedAt, now, durationMs) {
     if (durationMs <= 0)
         return now >= startedAt ? 1 : 0;

package/dist/anim/oscillator.d.ts

@@ -0,0 +1,12 @@
+/** Sawtooth ramp: rises 0→1 over each `period` then resets, for looping sweeps and scrolls.
+ * @internal
+ */
+export declare function sawWave(time: number, period: number): number;
+/** Triangle wave: ramps 0→1→0 across each `period`, for patrols, searchlights, and pulsing glows.
+ * @internal
+ */
+export declare function triangleWave(time: number, period: number): number;
+/** Ping-pong a value across `[0, length]`, bouncing at each edge — the index/position analog of {@link triangleWave}.
+ * @internal
+ */
+export declare function pingPong(value: number, length: number): number;