@jgengine/core 0.14.0 → 0.15.0

package/dist/ai/flock.js

@@ -88,40 +88,28 @@ export function flockSteer(agent, neighbors, config, target) {
     return [steerX * scale, steerY * scale, steerZ * scale];
 }
 const CELL_KEY_STRIDE = 1_048_576;
-const gridCells = new Map();
-const freeBuckets = [];
-const neighborScratch = [];
-let steerScratch = new Float64Array(0);
 function cellKey(cx, cz) {
     return cx * CELL_KEY_STRIDE + cz;
 }
-function takeBucket() {
-    return freeBuckets.pop() ?? [];
-}
-function ensureSteerCapacity(agentCount) {
-    const needed = agentCount * 3;
-    if (steerScratch.length < needed) {
-        steerScratch = new Float64Array(needed);
-    }
-}
+/**
+ * Per-call spatial index + scratch — never module-global.
+ * Two `stepFlock` worlds in one process must not share a grid (#1545 / sdk remediation Phase 3a).
+ */
 function buildAgentGrid(agents, invCell) {
-    for (const bucket of gridCells.values()) {
-        bucket.length = 0;
-        freeBuckets.push(bucket);
-    }
-    gridCells.clear();
+    const gridCells = new Map();
     for (let i = 0; i < agents.length; i += 1) {
         const position = agents[i].position;
         const key = cellKey(Math.floor(position[0] * invCell), Math.floor(position[2] * invCell));
         let bucket = gridCells.get(key);
         if (bucket === undefined) {
-            bucket = takeBucket();
+            bucket = [];
             gridCells.set(key, bucket);
         }
         bucket.push(i);
     }
+    return gridCells;
 }
-function fillNeighbors(agents, agentIndex, invCell) {
+function fillNeighbors(agents, agentIndex, invCell, gridCells, neighborScratch) {
     const agent = agents[agentIndex];
     const cx = Math.floor(agent.position[0] * invCell);
     const cz = Math.floor(agent.position[2] * invCell);
@@ -152,10 +140,12 @@ export function stepFlock(agents, config, dt, target) {
         return;
     const cellSize = config.neighborRadius > 1e-6 ? config.neighborRadius : 1;
     const invCell = 1 / cellSize;
-    buildAgentGrid(agents, invCell);
-    ensureSteerCapacity(count);
+    // All scratch is call-local so concurrent worlds (or re-entrant steps) never share a grid.
+    const gridCells = buildAgentGrid(agents, invCell);
+    const neighborScratch = [];
+    const steerScratch = new Float64Array(count * 3);
     for (let i = 0; i < count; i += 1) {
-        fillNeighbors(agents, i, invCell);
+        fillNeighbors(agents, i, invCell, gridCells, neighborScratch);
         const steer = flockSteer(agents[i], neighborScratch, config, target);
         const base = i * 3;
         steerScratch[base] = steer[0];

package/dist/ai/laneSelect.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 /**
  * 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)
@@ -9,7 +10,7 @@ export function pickLane(candidates, options = {}) {
         return null;
     const stickiness = options.stickiness ?? 1.2;
     const tieEpsilon = options.tieEpsilon ?? 0;
-    const rng = options.rng ?? Math.random;
+    const rng = resolveRng(options.rng, "selectLane");
     let best = candidates[0];
     for (const candidate of candidates) {
         if (candidate.cost < best.cost)

package/dist/ai/mobBrain.js

@@ -1,4 +1,5 @@
 import { createThreatTable } from "./threat.js";
+import { resolveRng } from "../random/resolveRng.js";
 const HOLD = {
     targetId: null,
     moveTo: null,
@@ -18,7 +19,7 @@ export function createMobBrain(config, deps) {
     const wander = config.wander === false || config.wander === undefined ? null : config.wander;
     const wanderInterval = wander?.intervalSeconds ?? 4;
     const wanderArrive = wander?.arriveRadius ?? 0.6;
-    const rng = deps.rng ?? Math.random;
+    const rng = resolveRng(deps.rng, "createMobBrain");
     let currentMode = "idle";
     let currentTarget = null;
     let evading = false;

package/dist/ai/waveRunner.d.ts

@@ -0,0 +1,81 @@
+import { type DirectorContext, type SpawnDirectorConfig, type SpawnDirectorState, type SpawnRequest } from "./spawnDirector.js";
+/**
+ * A callback the wave runner hands each {@link SpawnRequest} the underlying spawn
+ * director emits. The runner never instantiates entities itself — it forwards the
+ * request (a free-string `entryId` "kind", cost, wave, optional point/lane) to the
+ * game, which decides what to build. Keeps the runner genre-agnostic.
+ */
+export type WaveSpawnSink = (request: SpawnRequest) => void;
+/**
+ * Configuration for {@link createWaveRunner}: the full {@link SpawnDirectorConfig}
+ * (escalating waves, budgets, seed, spawn points) plus an optional {@link WaveSpawnSink}.
+ * The runner owns the director state — you never pass a `SpawnDirectorState` here.
+ */
+export interface WaveRunnerConfig extends SpawnDirectorConfig {
+    /** Optional sink invoked once per spawned {@link SpawnRequest} during {@link WaveRunner.update}. */
+    onSpawn?: WaveSpawnSink;
+}
+/**
+ * A pooled, per-frame readout of the current wave — the "brain behind WAVE 3".
+ * Reused across {@link WaveRunner.view} calls (never per-frame allocated), so read
+ * it and render it, don't retain it.
+ */
+export interface WaveView {
+    /** 1-based wave number for display ("WAVE N"). The 0-based index lives on {@link WaveRunner.state}. */
+    wave: number;
+    /**
+     * Progress `0..1` through the current wave: `waveElapsed / duration` when the
+     * wave declares a `duration`, otherwise a budget-drain estimate (`1 - budget /
+     * waveBudget`). A best-effort readout for a progress bar, not an exact schedule.
+     */
+    waveProgress: number;
+    /** Spawn budget currently banked in the director. */
+    budget: number;
+    /** How many entities have spawned during the current wave. */
+    spawnedThisWave: number;
+    /** How many entities have spawned across every wave so far. */
+    spawnedTotal: number;
+    /** Current alert level `0..1` (raised by {@link WaveRunner.raiseAlert}, decays over time). */
+    alert: number;
+    /** True once the final non-looping wave has finished. */
+    done: boolean;
+}
+/** A live, observable, serializable wave/spawn runner over a seeded spawn director. */
+export interface WaveRunner {
+    /**
+     * Advance the director by `dt` seconds: bank budget, roll escalation/alert, cross
+     * wave boundaries, and forward every emitted {@link SpawnRequest} to the configured
+     * `onSpawn` sink. Pass a {@link DirectorContext} (defaults to `{ alive: 0 }`) to feed
+     * back the live alive-count / player positions. Notifies subscribers on change.
+     */
+    update(dt: number, ctx?: DirectorContext): void;
+    /** The pooled current-wave readout to render (do not retain). */
+    view(): WaveView;
+    /** Force an immediate jump to the next wave (delegates to `advanceWave`). Notifies. */
+    forceNextWave(): void;
+    /** Raise the alert level by `amount` (clamped `0..1`), boosting spawn budget. Notifies. */
+    raiseAlert(amount: number): void;
+    /** The raw underlying {@link SpawnDirectorState} (0-based `wave`); read-only snapshot of internals. */
+    state(): SpawnDirectorState;
+    /** Observe changes (update, forceNextWave, raiseAlert, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save — the plain {@link SpawnDirectorState} object. */
+    snapshot(): SpawnDirectorState;
+    /** Restore from a {@link snapshot} (a plain {@link SpawnDirectorState}). Notifies. */
+    restore(snapshot: SpawnDirectorState): void;
+}
+/**
+ * A thin, stateful, observable wrapper around the seeded {@link createSpawnDirectorState}
+ * / {@link advanceSpawnDirector} model. It OWNS a {@link SpawnDirectorState}, ticks it
+ * from `update(dt, ctx?)`, keeps the new state, and forwards each emitted
+ * {@link SpawnRequest} to an optional `onSpawn` sink so the model never instantiates
+ * entities. `view()` returns a pooled per-frame readout — the "brain behind WAVE 3":
+ * the 1-based wave number, wave progress `0..1`, banked budget, per-wave and total
+ * spawn counts, alert, and done flag. `forceNextWave` / `raiseAlert` drive it,
+ * `subscribe` observes it, and `snapshot`/`restore` round-trip the plain serializable
+ * state object through a save. Nothing here is genre-specific: spawn-entry `kind`s
+ * (the director's `entryId`s) stay free strings the runner never interprets.
+ *
+ * @capability wave-runner observable serializable wave/spawn runner over the seeded spawn director — WAVE N, wave progress, budget/alert readout, onSpawn sink, snapshot/restore
+ */
+export declare function createWaveRunner(config: WaveRunnerConfig): WaveRunner;

package/dist/ai/waveRunner.js

@@ -0,0 +1,104 @@
+import { advanceSpawnDirector, advanceWave, createSpawnDirectorState, raiseAlert as raiseDirectorAlert, } from "./spawnDirector.js";
+const DEFAULT_CONTEXT = { alive: 0 };
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+/**
+ * A thin, stateful, observable wrapper around the seeded {@link createSpawnDirectorState}
+ * / {@link advanceSpawnDirector} model. It OWNS a {@link SpawnDirectorState}, ticks it
+ * from `update(dt, ctx?)`, keeps the new state, and forwards each emitted
+ * {@link SpawnRequest} to an optional `onSpawn` sink so the model never instantiates
+ * entities. `view()` returns a pooled per-frame readout — the "brain behind WAVE 3":
+ * the 1-based wave number, wave progress `0..1`, banked budget, per-wave and total
+ * spawn counts, alert, and done flag. `forceNextWave` / `raiseAlert` drive it,
+ * `subscribe` observes it, and `snapshot`/`restore` round-trip the plain serializable
+ * state object through a save. Nothing here is genre-specific: spawn-entry `kind`s
+ * (the director's `entryId`s) stay free strings the runner never interprets.
+ *
+ * @capability wave-runner observable serializable wave/spawn runner over the seeded spawn director — WAVE N, wave progress, budget/alert readout, onSpawn sink, snapshot/restore
+ */
+export function createWaveRunner(config) {
+    const onSpawn = config.onSpawn;
+    let state = createSpawnDirectorState(config);
+    const listeners = new Set();
+    // Pooled readout — reused across view() calls, never per-frame allocated.
+    const readout = {
+        wave: 1,
+        waveProgress: 0,
+        budget: 0,
+        spawnedThisWave: 0,
+        spawnedTotal: 0,
+        alert: 0,
+        done: false,
+    };
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** True if any field a HUD cares about differs between two states. */
+    function changed(a, b) {
+        return (a.wave !== b.wave ||
+            a.budget !== b.budget ||
+            a.spawnedThisWave !== b.spawnedThisWave ||
+            a.spawnedTotal !== b.spawnedTotal ||
+            a.alert !== b.alert ||
+            a.done !== b.done);
+    }
+    function waveProgress() {
+        const manifest = config.waves[state.wave];
+        if (manifest === undefined)
+            return state.done ? 1 : 0;
+        if (manifest.duration !== undefined && manifest.duration > 0) {
+            return clamp01(state.waveElapsed / manifest.duration);
+        }
+        if (manifest.budget > 0) {
+            return clamp01(1 - state.budget / manifest.budget);
+        }
+        return state.done ? 1 : 0;
+    }
+    return {
+        update(dt, ctx = DEFAULT_CONTEXT) {
+            const previous = state;
+            const step = advanceSpawnDirector(config, state, dt, ctx);
+            state = step.state;
+            if (onSpawn !== undefined) {
+                for (const spawn of step.spawns)
+                    onSpawn(spawn);
+            }
+            if (step.spawns.length > 0 || changed(previous, state))
+                notify();
+        },
+        view() {
+            readout.wave = state.wave + 1;
+            readout.waveProgress = waveProgress();
+            readout.budget = state.budget;
+            readout.spawnedThisWave = state.spawnedThisWave;
+            readout.spawnedTotal = state.spawnedTotal;
+            readout.alert = state.alert;
+            readout.done = state.done;
+            return readout;
+        },
+        forceNextWave() {
+            state = advanceWave(config, state);
+            notify();
+        },
+        raiseAlert(amount) {
+            state = raiseDirectorAlert(state, amount);
+            notify();
+        },
+        state() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return state;
+        },
+        restore(snapshot) {
+            state = snapshot;
+            notify();
+        },
+    };
+}

package/dist/audio/musicState.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Hysteretic music-state selector: turns a continuous intensity signal (nearby threat,
+ * alert count, chase proximity) into a stable theme id. The engine can already crossfade
+ * a soundtrack; this decides *when*, without the flapping a bare threshold produces when
+ * one enemy walks in and out of range.
+ */
+export interface MusicTier {
+    id: string;
+    /** Theme id passed to `ctx.game.audio.music`; null silences the soundtrack in this tier. */
+    theme: string | null;
+    /** Intensity at or above which this tier may be entered. */
+    enter: number;
+    /** Minimum time in this tier before it may drop to a lower one. Default 0. */
+    holdMs?: number;
+}
+/** The tier ladder plus the release margin that keeps a hovering intensity from flapping between tiers. */
+export interface MusicStateConfig {
+    /** Ordered or unordered; the highest `enter` at or below the intensity wins. */
+    tiers: readonly MusicTier[];
+    /** Intensity must fall this far below a tier's `enter` before leaving it. Default 0.2. */
+    release?: number;
+}
+/** Which tier is playing and when it was entered, on the caller's clock. Serialisable. */
+export interface MusicStateSnapshot {
+    tierId: string | null;
+    /** Timestamp the current tier was entered, on the caller's clock. */
+    sinceMs: number;
+}
+/** The current intensity signal and clock reading for one resolve. */
+export interface MusicStateInput {
+    intensity: number;
+    nowMs: number;
+}
+/** Next state, the theme that should be playing, and whether this advance is the one that changed it. */
+export interface MusicStateResult {
+    state: MusicStateSnapshot;
+    theme: string | null;
+    /** True only on the advance the tier changed — the caller's cue to crossfade. */
+    changed: boolean;
+}
+/** Fresh state with no tier entered, so the first resolve always settles and reports `changed`. */
+export declare function createMusicState(): MusicStateSnapshot;
+/**
+ * Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the
+ * tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
+ */
+export declare function resolveMusicState(state: MusicStateSnapshot, input: MusicStateInput, config: MusicStateConfig): MusicStateResult;

package/dist/audio/musicState.js

@@ -0,0 +1,38 @@
+/** Fresh state with no tier entered, so the first resolve always settles and reports `changed`. */
+export function createMusicState() {
+    return { tierId: null, sinceMs: 0 };
+}
+function tierById(config, id) {
+    return id === null ? undefined : config.tiers.find((tier) => tier.id === id);
+}
+function highestTierAt(config, intensity) {
+    let best;
+    for (const tier of config.tiers) {
+        if (intensity < tier.enter)
+            continue;
+        if (best === undefined || tier.enter > best.enter)
+            best = tier;
+    }
+    return best;
+}
+/**
+ * Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the
+ * tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
+ */
+export function resolveMusicState(state, input, config) {
+    const current = tierById(config, state.tierId);
+    const candidate = highestTierAt(config, input.intensity) ?? config.tiers.find((tier) => tier.enter <= 0);
+    if (current !== undefined && candidate !== undefined && candidate.enter < current.enter) {
+        const release = config.release ?? 0.2;
+        const heldLongEnough = input.nowMs - state.sinceMs >= (current.holdMs ?? 0);
+        if (!heldLongEnough || input.intensity > current.enter - release) {
+            return { state, theme: current.theme, changed: false };
+        }
+    }
+    const next = candidate ?? current;
+    if (next === undefined)
+        return { state, theme: null, changed: false };
+    if (next.id === state.tierId)
+        return { state, theme: next.theme, changed: false };
+    return { state: { tierId: next.id, sinceMs: input.nowMs }, theme: next.theme, changed: true };
+}

package/dist/audio/stepCadence.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Distance-driven footstep cadence. Pure state-in/state-out: feed it how far a mover
+ * travelled this frame and it tells you how many steps landed, so foley stays locked to
+ * ground distance instead of a wall-clock timer that desyncs when speed changes.
+ */
+export interface StepCadenceConfig {
+    /** World units travelled per step at `strideScale` 1. */
+    strideDistance: number;
+    /**
+     * Fraction of a stride the first step after standing still lands at, so walking off
+     * from rest is heard immediately rather than half a stride later. Default 0.5.
+     */
+    firstStepFraction?: number;
+}
+/** Cadence bookkeeping between advances — banked distance, last moving state, and the step count whose parity is the foot. */
+export interface StepCadenceState {
+    /** Distance banked toward the next step. */
+    travelled: number;
+    /** Whether the mover was moving last advance — drives the from-rest first step. */
+    moving: boolean;
+    /** Monotonic step counter; its parity is the left/right foot. */
+    steps: number;
+}
+/** What the mover did this advance: ground distance covered, whether feet are planting, and the stride multiplier. */
+export interface StepCadenceInput {
+    /** Ground distance covered since the last advance, in world units. */
+    distance: number;
+    /** False when the mover is airborne, downed, or otherwise not planting feet. */
+    moving: boolean;
+    /** Multiplies `strideDistance` — crouch shortens it, sprint lengthens it. Default 1. */
+    strideScale?: number;
+}
+/** Outcome of one advance: the next state plus how many steps landed and which foot led. */
+export interface StepCadenceResult {
+    state: StepCadenceState;
+    /** Steps that landed this advance — 0 or 1 normally, more only on a very long frame. */
+    steps: number;
+    /** Parity of the first step landed this advance: 0 = left, 1 = right. */
+    foot: 0 | 1;
+}
+/** Fresh cadence state for a mover that is standing still. */
+export declare function createStepCadenceState(): StepCadenceState;
+/**
+ * Bank this advance's distance and report the steps it completed. Pure — same state and input
+ * always give the same result, so footstep timing is testable headless and replays identically.
+ */
+export declare function advanceStepCadence(state: StepCadenceState, input: StepCadenceInput, config: StepCadenceConfig): StepCadenceResult;

package/dist/audio/stepCadence.js

@@ -0,0 +1,29 @@
+/** Fresh cadence state for a mover that is standing still. */
+export function createStepCadenceState() {
+    return { travelled: 0, moving: false, steps: 0 };
+}
+/**
+ * Bank this advance's distance and report the steps it completed. Pure — same state and input
+ * always give the same result, so footstep timing is testable headless and replays identically.
+ */
+export function advanceStepCadence(state, input, config) {
+    const stride = Math.max(config.strideDistance * (input.strideScale ?? 1), Number.EPSILON);
+    if (!input.moving) {
+        return { state: { travelled: 0, moving: false, steps: state.steps }, steps: 0, foot: (state.steps % 2) };
+    }
+    const fromRest = !state.moving;
+    const threshold = fromRest ? stride * (config.firstStepFraction ?? 0.5) : stride;
+    let travelled = state.travelled + Math.max(0, input.distance);
+    let steps = 0;
+    let remaining = threshold;
+    while (travelled >= remaining) {
+        travelled -= remaining;
+        steps += 1;
+        remaining = stride;
+    }
+    return {
+        state: { travelled, moving: true, steps: state.steps + steps },
+        steps,
+        foot: (state.steps % 2),
+    };
+}

package/dist/audio/synth.d.ts

@@ -23,6 +23,13 @@ export interface ToneVoice {
     slideTo?: number;
     /** Attack ramp in seconds. Default 0.012. */
     attack?: number;
+    /**
+     * Seconds held at full gain after the attack, before the decay to silence at `duration`.
+     * Default 0 — a plain percussive decay. Set it to `duration` for a flat, sustained bed:
+     * a looped buffer only reads as continuous if its amplitude does not fall across the loop,
+     * so ambient hums and wind beds need this or they pulse once per loop.
+     */
+    sustain?: number;
 }
 /**
  * A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised
@@ -43,6 +50,11 @@ export interface NoiseVoice {
     decay?: number;
     /** Start offset in seconds from the cue trigger. Default 0. */
     delay?: number;
+    /**
+     * Seconds held at full gain before the decay begins. Default 0. Set it to `duration` for a
+     * flat noise bed (wind, rain, machine roar) that loops without pulsing.
+     */
+    sustain?: number;
 }
 /** One layered voice of a synth cue. */
 export type SynthVoice = ToneVoice | NoiseVoice;

package/dist/authoring.d.ts

@@ -1,9 +1,11 @@
 /**
- * Task-first JGEngine authoring surface.
+ * Core-side convenience barrel for pure authored helpers (loot, world features, ownership,
+ * spawn selection, RNG). **Not the game entrypoint** — game projects start at
+ * `@jgengine/shell/gameKit` (`defineGame`, `GameHost`, stores, systems, HUD). Prefer that
+ * surface; import from here only when you need a core helper the kit does not re-export.
  *
- * Game code should begin here. Domain and runtime deep imports remain available for
- * advanced composition, but this module intentionally exposes common authored
- * concepts without requiring callers to understand the repository layout.
+ * @deprecated Prefer `@jgengine/shell/gameKit` as the start-here surface for games. This
+ * module remains for deep core helpers and existing pure-import consumers; it is not removed.
  */
 export { type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
 export { lootTable, type LootTableDef, type LootEntry, type Drop, } from "./game/lootTable.js";

package/dist/authoring.js

@@ -1,9 +1,11 @@
 /**
- * Task-first JGEngine authoring surface.
+ * Core-side convenience barrel for pure authored helpers (loot, world features, ownership,
+ * spawn selection, RNG). **Not the game entrypoint** — game projects start at
+ * `@jgengine/shell/gameKit` (`defineGame`, `GameHost`, stores, systems, HUD). Prefer that
+ * surface; import from here only when you need a core helper the kit does not re-export.
  *
- * Game code should begin here. Domain and runtime deep imports remain available for
- * advanced composition, but this module intentionally exposes common authored
- * concepts without requiring callers to understand the repository layout.
+ * @deprecated Prefer `@jgengine/shell/gameKit` as the start-here surface for games. This
+ * module remains for deep core helpers and existing pure-import consumers; it is not removed.
  */
 export {} from "./game/defineGame.js";
 export { lootTable, } from "./game/lootTable.js";

package/dist/combat/castRunner.d.ts

@@ -3,6 +3,15 @@ export interface CastConfig {
     castTimeMs: number;
     /** Total movement distance tolerated before the cast auto-interrupts; default `0.04`. `Infinity` allows casting on the move. */
     moveTolerance?: number;
+    /**
+     * Per-tick movement at or below this is ignored rather than added to the running total — the
+     * caster's noise floor. A 3D game's pose jitters every frame from terrain-following ground snap
+     * and float drift; since `moveTolerance` accumulates, feeding those raw deltas straight in will
+     * silently cancel casts the player never interrupted, and the failure is intermittent rather than
+     * obvious. Only the game knows its own noise floor, so declare it once here instead of filtering
+     * at every `tick` call site. Default `0` (count every reported movement).
+     */
+    moveDeadzone?: number;
 }
 export interface CastBarSnapshot {
     abilityId: string;
@@ -34,7 +43,10 @@ export interface CastRunner {
     state(): CastBarSnapshot | null;
     /** Interrupt the in-flight cast now; returns the interruption event, or `null` when idle. */
     interrupt(reason?: CastInterruptReason): CastEvent | null;
-    /** Advance by `dtSeconds`; `movedDistance` accumulates toward the config's `moveTolerance`. */
+    /**
+     * Advance by `dtSeconds`; `movedDistance` accumulates toward the config's `moveTolerance`, except
+     * for per-tick movement at or below `moveDeadzone`, which is treated as jitter and ignored.
+     */
     tick(dtSeconds: number, movedDistance?: number): CastEvent | null;
 }
 /**

package/dist/combat/castRunner.js

@@ -26,6 +26,7 @@ export function createCastRunner() {
                 abilityId: config.abilityId,
                 castTimeMs: Math.max(0, config.castTimeMs),
                 moveTolerance: config.moveTolerance ?? DEFAULT_MOVE_TOLERANCE,
+                moveDeadzone: Math.max(0, config.moveDeadzone ?? 0),
                 elapsedMs: 0,
                 movedTotal: 0,
             };
@@ -43,7 +44,10 @@ export function createCastRunner() {
         tick(dtSeconds, movedDistance = 0) {
             if (active === null)
                 return null;
-            active.movedTotal += Math.max(0, movedDistance);
+            const moved = Math.max(0, movedDistance);
+            // Below the caster's noise floor this is jitter, not travel — do not accumulate it.
+            if (moved > active.moveDeadzone)
+                active.movedTotal += moved;
             if (active.movedTotal > active.moveTolerance) {
                 const abilityId = active.abilityId;
                 active = null;