murow 0.1.1 → 0.1.3

package/dist/netcode/esm/index.js

@@ -68,7 +68,7 @@ import { defineRPC as defineRPC2 } from "murow/protocol";
 
 // src/codec/delta-codec.ts
 var HEADER_BYTES = 4 + 4 + 2 + 2;
-function encodeDelta(world, tick, entities, components, numMaskWords, despawned = [], clientAckTick = 0) {
+function encodeDelta(world, tick, entities, components, numMaskWords, despawned = [], clientAckTick = 0, includeComponent = () => true) {
   const perEntityMasks = new Array(entities.length);
   const perEntityBitmaskBytes = numMaskWords * 4;
   let bodyBytes = 0;
@@ -80,6 +80,8 @@ function encodeDelta(world, tick, entities, components, numMaskWords, despawned
       const c = components[ci];
       if (!world.has(eid, c))
         continue;
+      if (!includeComponent(eid, c))
+        continue;
       const wordIndex = ci >>> 5;
       const bitIndex = ci & 31;
       mask[wordIndex] |= 1 << bitIndex;
@@ -231,6 +233,18 @@ function decodeDelta(world, buf, components, numMaskWords, ensureEntity, shouldA
   };
 }
 
+// src/components/sync-spec.ts
+function networked(spec) {
+  return spec;
+}
+function rateIncludes(rate, dirty, tick) {
+  if (rate === "every-tick")
+    return true;
+  if (rate === "on-change")
+    return dirty;
+  return dirty || rate.every > 0 && tick % rate.every === 0;
+}
+
 // src/ctx.ts
 function makeFieldsAccessor(world, entity) {
   return function fields(component) {
@@ -461,6 +475,7 @@ var GameServer = class extends Network {
       }
       if (current.length === 0 && despawned.length === 0 && !peer.needsBaseline)
         continue;
+      const include = peer.needsBaseline ? void 0 : (eid, c) => rateIncludes(c.__sync.rate, this.world.isDirty(eid, c), this.tickCounter);
       const buf = encodeDelta(
         this.world,
         this.tickCounter,
@@ -468,7 +483,8 @@ var GameServer = class extends Network {
         this.syncedComponents,
         this.syncedNumMaskWords,
         despawned,
-        peer.lastAckedClientTick
+        peer.lastAckedClientTick,
+        include
       );
       const framed = new Uint8Array(buf.length + 1);
       framed[0] = MSG_SNAPSHOT;
@@ -810,67 +826,67 @@ var LagCompensation = class {
 // src/client/game-client.ts
 import { u16 as u162 } from "murow/core/binary-codec";
 import { SimpleRNG as SimpleRNG2 } from "murow/core/simple-rng";
+import { Reconciler } from "murow/core/prediction";
 import { defineRPC as defineRPC3 } from "murow/protocol";
 
-// src/client/interpolation-buffer.ts
+// src/client/strategies/snapshot-interpolation.ts
 import { lerp } from "murow/core/lerp";
+import { Timeline } from "murow/core/timeline";
+import { SlewClock } from "murow/core/clock";
 function modeFor(c) {
   const sync = c.__sync;
   return sync?.interp ?? "lerp";
 }
-var InterpolationBuffer = class {
-  constructor(serverToLocal, capacity, delayMs, staleWindowMs) {
-    this.buffer = [];
-    this.renderTick = -Infinity;
-    this.latestReceivedAt = -Infinity;
-    this.smoothedTickRateMs = 0;
+var DEFAULT_MAX_DESYNC = 500;
+var DEFAULT_MAX_BRIDGE_GAP = 250;
+var SnapshotInterpolation = class {
+  constructor(serverToLocal, capacity, delayMs, staleWindowMs, maxDesyncMs = DEFAULT_MAX_DESYNC, nominalTickMs = 0, maxBridgeGapMs = DEFAULT_MAX_BRIDGE_GAP) {
+    this.clock = new SlewClock();
     this.serverToLocal = serverToLocal;
-    this.capacity = capacity;
+    this.timeline = new Timeline(capacity, staleWindowMs);
     this.delay = delayMs;
-    this.staleWindow = staleWindowMs;
+    this.maxDesync = maxDesyncMs;
+    this.nominalTickMs = nominalTickMs;
+    this.smoothedTickRateMs = nominalTickMs;
+    this.maxBridgeGap = maxBridgeGapMs;
+  }
+  get staleWindow() {
+    return this.timeline.staleWindow;
   }
   setDelay(delayMs) {
     this.delay = delayMs;
   }
   setStaleWindow(staleWindowMs) {
-    this.staleWindow = staleWindowMs;
+    this.timeline.setStaleWindow(staleWindowMs);
+  }
+  setMaxDesync(maxDesyncMs) {
+    this.maxDesync = maxDesyncMs;
+  }
+  setMaxBridgeGap(maxBridgeGapMs) {
+    this.maxBridgeGap = maxBridgeGapMs;
   }
   record(snapshot) {
-    const gap = snapshot.receivedAt - this.latestReceivedAt;
-    if (this.buffer.length > 0 && gap > this.staleWindow) {
-      this.buffer.length = 0;
-      this.renderTick = -Infinity;
-      this.latestReceivedAt = -Infinity;
-      this.smoothedTickRateMs = 0;
-    }
-    if (snapshot.receivedAt > this.latestReceivedAt) {
-      this.latestReceivedAt = snapshot.receivedAt;
+    const reset = this.timeline.record(snapshot.serverTick, snapshot.receivedAt, snapshot);
+    if (reset) {
+      this.smoothedTickRateMs = this.nominalTickMs;
+      this.clock.reset();
     }
-    let insertAt = this.buffer.length;
-    while (insertAt > 0 && this.buffer[insertAt - 1].serverTick >= snapshot.serverTick) {
-      if (this.buffer[insertAt - 1].serverTick === snapshot.serverTick)
-        return;
-      insertAt--;
-    }
-    this.buffer.splice(insertAt, 0, snapshot);
-    while (this.buffer.length > this.capacity)
-      this.buffer.shift();
   }
   clear() {
-    this.buffer.length = 0;
-    this.renderTick = -Infinity;
-    this.latestReceivedAt = -Infinity;
-    this.smoothedTickRateMs = 0;
+    this.timeline.clear();
+    this.clock.reset();
+    this.smoothedTickRateMs = this.nominalTickMs;
   }
   apply(world, now, components, shouldSkip) {
-    if (this.buffer.length === 0)
+    const tl = this.timeline;
+    if (tl.length === 0)
       return;
-    const newest = this.buffer[this.buffer.length - 1];
-    const oldest = this.buffer[0];
+    const newest = tl.newest().sample;
+    const oldest = tl.oldest().sample;
     let tickRateMs = 0;
-    if (this.buffer.length >= 2) {
+    if (tl.length >= 2) {
       const tickSpan = newest.serverTick - oldest.serverTick;
-      const wallSpan = this.latestReceivedAt - oldest.receivedAt;
+      const wallSpan = tl.latestReceivedAt - oldest.receivedAt;
       const rawTickRateMs = tickSpan > 0 && wallSpan > 0 ? wallSpan / tickSpan : 0;
       if (rawTickRateMs > 0) {
         if (this.smoothedTickRateMs === 0)
@@ -888,42 +904,23 @@ var InterpolationBuffer = class {
     }
     const ageBeyondDelay = now - newest.receivedAt - this.delay;
     const targetTick = newest.serverTick + ageBeyondDelay / tickRateMs;
-    if (this.renderTick === -Infinity) {
-      this.renderTick = targetTick;
-    } else {
-      const drift = targetTick - this.renderTick;
-      if (drift > 2) {
-        this.renderTick = targetTick;
-      } else {
-        const warp = Math.max(0.9, Math.min(1.1, 1 + drift * 0.05));
-        this.renderTick += warp;
-      }
-    }
-    const renderTick = this.renderTick;
-    let a = null;
-    let b = null;
-    for (let i = 0; i < this.buffer.length - 1; i++) {
-      const s0 = this.buffer[i];
-      const s1 = this.buffer[i + 1];
-      if (s0.serverTick <= renderTick && renderTick <= s1.serverTick) {
-        a = s0;
-        b = s1;
-        break;
-      }
-    }
-    if (a === null || b === null) {
+    const renderTick = this.clock.advance(targetTick, this.maxDesync / tickRateMs);
+    const straddle = tl.straddle(renderTick);
+    if (straddle === null) {
       if (renderTick < oldest.serverTick)
         return;
       this.writeSnapshot(world, newest, components, shouldSkip);
       return;
     }
+    const [aIndex, bIndex] = straddle;
+    const a = tl.at(aIndex).sample;
+    const b = tl.at(bIndex).sample;
     const seen = /* @__PURE__ */ new Set();
     for (const eid of a.entityIds)
       seen.add(eid);
     for (const eid of b.entityIds)
       seen.add(eid);
-    const aIndex = this.buffer.indexOf(a);
-    const bIndex = this.buffer.indexOf(b);
+    const maxBridgeTicks = this.maxBridgeGap / tickRateMs;
     for (const serverEid of seen) {
       const localEid = this.serverToLocal.get(serverEid);
       if (localEid === void 0)
@@ -935,13 +932,13 @@ var InterpolationBuffer = class {
         let va = a.componentValuesByEntity.get(serverEid)?.get(c);
         while (va === void 0 && aIdx > 0) {
           aIdx--;
-          va = this.buffer[aIdx].componentValuesByEntity.get(serverEid)?.get(c);
+          va = tl.at(aIdx).sample.componentValuesByEntity.get(serverEid)?.get(c);
         }
         let bIdx = bIndex;
         let vb = b.componentValuesByEntity.get(serverEid)?.get(c);
-        while (vb === void 0 && bIdx < this.buffer.length - 1) {
+        while (vb === void 0 && bIdx < tl.length - 1) {
           bIdx++;
-          vb = this.buffer[bIdx].componentValuesByEntity.get(serverEid)?.get(c);
+          vb = tl.at(bIdx).sample.componentValuesByEntity.get(serverEid)?.get(c);
         }
         if (va === void 0 && vb === void 0)
           continue;
@@ -955,8 +952,10 @@ var InterpolationBuffer = class {
           if (mode === "none") {
             toWrite = vb;
           } else {
-            const aTick = this.buffer[aIdx].serverTick;
-            const bTick = this.buffer[bIdx].serverTick;
+            const bTick = tl.at(bIdx).sample.serverTick;
+            let aTick = tl.at(aIdx).sample.serverTick;
+            if (bTick - aTick > maxBridgeTicks)
+              aTick = bTick - 1;
             const wideSpan = bTick - aTick;
             const wideT = wideSpan > 0 ? Math.min(1, Math.max(0, (renderTick - aTick) / wideSpan)) : 0;
             if (mode === "step") {
@@ -1033,7 +1032,6 @@ var GameClient = class extends Network {
       "error"
     ]);
     this.predictionMap = null;
-    this.predictionHistory = [];
     this.localTick = 0;
     this.intentSequence = 0;
     this.lastServerTick = 0;
@@ -1044,6 +1042,8 @@ var GameClient = class extends Network {
     this.predictedEntities = /* @__PURE__ */ new Set();
     /** Set when MSG_ASSIGN_ENTITY lands before the matching spawn. */
     this.pendingAssignedServerEid = null;
+    /** Spawns discovered during a decode, emitted once values are written. */
+    this.deferredSpawns = [];
     /** Resolved local entity for the server's assignment. Default for sendIntent. */
     this._assignedEntity = null;
     this._rttMs = null;
@@ -1064,12 +1064,60 @@ var GameClient = class extends Network {
     this.rng = new SimpleRNG2(1);
     this.lastDt = opts.loop.ticker.intervalMs / 1e3;
     this.now = opts.now ?? (() => performance.now());
-    this.interpBuffer = new InterpolationBuffer(
+    this.interpBuffer = new SnapshotInterpolation(
       this.serverToLocal,
       16,
       interpolationDelay,
-      staleWindowMs
+      staleWindowMs,
+      strategy.maxDesync,
+      opts.loop.ticker.intervalMs,
+      strategy.maxBridgeGap
     );
+    this.reconciler = new Reconciler({
+      bufferSize: this.predictionBufferSize,
+      restore: ({ decoded, resetEntities }) => {
+        for (const serverEid of decoded.serverEntityIds) {
+          const localEid = this.serverToLocal.get(serverEid);
+          if (localEid === void 0)
+            continue;
+          if (!this.predictedEntities.has(localEid))
+            continue;
+          const comps = decoded.valuesByServerEntity.get(serverEid);
+          if (comps === void 0)
+            continue;
+          for (const [c, value] of comps) {
+            if (this.world.has(localEid, c)) {
+              this.world.update(localEid, c, value);
+            } else {
+              this.world.add(localEid, c, value);
+            }
+          }
+          resetEntities.add(localEid);
+        }
+      },
+      replay: (preds, { decoded, resetEntities }) => {
+        let replayedCount = 0;
+        for (const pred of preds) {
+          if (!resetEntities.has(pred.entity))
+            continue;
+          const predFn = this.predictionMap?.[pred.name];
+          if (predFn === void 0)
+            continue;
+          const ctx = {
+            world: this.world,
+            entity: pred.entity,
+            tick: pred.tick,
+            deltaTime: pred.deltaTime,
+            rng: this.rng,
+            fields: makeFieldsAccessor(this.world, pred.entity),
+            markDirty: makeMarkDirty(this.world, pred.entity)
+          };
+          predFn(pred.payload, ctx);
+          replayedCount++;
+        }
+        this.emit("reconciled", { rewindTick: decoded.clientAckTick, replayed: replayedCount });
+      }
+    });
     this.discoverSyncedComponents();
     this.wireTransport();
     this.wireLoop();
@@ -1156,6 +1204,7 @@ var GameClient = class extends Network {
   }
   handleSnapshot(payload) {
     try {
+      this.deferredSpawns.length = 0;
       const decoded = decodeDelta(
         this.world,
         payload,
@@ -1169,6 +1218,12 @@ var GameClient = class extends Network {
         () => false
       );
       this.lastServerTick = decoded.tick;
+      for (const spawn of this.deferredSpawns) {
+        this.emit("spawn", { entity: spawn.entity, components: spawn.components });
+        if (spawn.assigned)
+          this.emit("assigned", { entity: spawn.entity });
+      }
+      this.deferredSpawns.length = 0;
       this.emit("snapshot", { tick: decoded.tick, byteSize: payload.length + 1 });
       this.interpBuffer.record({
         receivedAt: this.now(),
@@ -1201,13 +1256,14 @@ var GameClient = class extends Network {
       const components = {};
       for (const c of present)
         components[c.name] = true;
-      this.emit("spawn", { entity: localEid, components });
+      let assigned = false;
       if (this.pendingAssignedServerEid === serverEid) {
         this.pendingAssignedServerEid = null;
         this.predictedEntities.add(localEid);
         this._assignedEntity = localEid;
-        this.emit("assigned", { entity: localEid });
+        assigned = true;
       }
+      this.deferredSpawns.push({ entity: localEid, components, assigned });
     }
     return localEid;
   }
@@ -1226,60 +1282,9 @@ var GameClient = class extends Network {
    * the server has acked, replay the rest on top.
    */
   reconcile(decoded) {
-    const resetEntities = /* @__PURE__ */ new Set();
-    for (const serverEid of decoded.serverEntityIds) {
-      const localEid = this.serverToLocal.get(serverEid);
-      if (localEid === void 0)
-        continue;
-      if (!this.predictedEntities.has(localEid))
-        continue;
-      const comps = decoded.valuesByServerEntity.get(serverEid);
-      if (comps === void 0)
-        continue;
-      for (const [c, value] of comps) {
-        if (this.world.has(localEid, c)) {
-          this.world.update(localEid, c, value);
-        } else {
-          this.world.add(localEid, c, value);
-        }
-      }
-      resetEntities.add(localEid);
-    }
-    const ackSequence = decoded.clientAckTick;
-    let cut = 0;
-    while (cut < this.predictionHistory.length && this.predictionHistory[cut].sequence <= ackSequence) {
-      cut++;
-    }
-    if (cut > 0)
-      this.predictionHistory.splice(0, cut);
-    const remaining = this.predictionHistory.length;
-    if (remaining === 0) {
-      this.emit("reconciled", { rewindTick: ackSequence, replayed: 0 });
-      return;
-    }
-    let replayedCount = 0;
-    for (let i = 0; i < remaining; i++) {
-      const pred = this.predictionHistory[i];
-      if (!resetEntities.has(pred.entity))
-        continue;
-      const predFn = this.predictionMap?.[pred.name];
-      if (predFn === void 0)
-        continue;
-      const ctx = {
-        world: this.world,
-        entity: pred.entity,
-        tick: pred.tick,
-        deltaTime: pred.deltaTime,
-        rng: this.rng,
-        fields: makeFieldsAccessor(this.world, pred.entity),
-        markDirty: makeMarkDirty(this.world, pred.entity)
-      };
-      predFn(pred.payload, ctx);
-      replayedCount++;
-    }
-    this.emit("reconciled", {
-      rewindTick: ackSequence,
-      replayed: replayedCount
+    this.reconciler.reconcile(decoded.clientAckTick, {
+      decoded,
+      resetEntities: /* @__PURE__ */ new Set()
     });
   }
   handleRpc(payload) {
@@ -1353,7 +1358,7 @@ var GameClient = class extends Network {
         markDirty: makeMarkDirty(this.world, entity)
       };
       predFn(payload, ctx);
-      this.predictionHistory.push({
+      this.reconciler.record(sequence, {
         tick: this.localTick,
         sequence,
         name,
@@ -1362,9 +1367,6 @@ var GameClient = class extends Network {
         deltaTime
       });
       this.predictedEntities.add(entity);
-      while (this.predictionHistory.length > this.predictionBufferSize) {
-        this.predictionHistory.shift();
-      }
     }
     return true;
   }
@@ -1395,7 +1397,7 @@ var GameClient = class extends Network {
     return this.localTick;
   }
   getPredictionDepth() {
-    return this.predictionHistory.length;
+    return this.reconciler.pending;
   }
   get interpolationDelay() {
     return this.interpBuffer.delay;
@@ -1403,6 +1405,12 @@ var GameClient = class extends Network {
   setInterpolationDelay(ms) {
     this.interpBuffer.setDelay(ms);
   }
+  setMaxDesync(ms) {
+    this.interpBuffer.setMaxDesync(ms);
+  }
+  setMaxBridgeGap(ms) {
+    this.interpBuffer.setMaxBridgeGap(ms);
+  }
 };
 
 // src/transports/memory-transport.ts
@@ -1505,11 +1513,6 @@ var MemoryPeerTransport = class {
     queueMicrotask(() => this.clientOpenHandler?.());
   }
 };
-
-// src/components/sync-spec.ts
-function networked(spec) {
-  return spec;
-}
 export {
   AoiGrid,
   GameClient,
@@ -1526,5 +1529,6 @@ export {
   encodeDelta,
   makeFieldsAccessor,
   makeMarkDirty,
-  networked
+  networked,
+  rateIncludes
 };

package/dist/netcode/types/client/game-client.d.ts

@@ -2,7 +2,7 @@ import type { Entity, World } from 'murow/ecs';
 import type { GameLoop } from 'murow/game';
 import type { TransportAdapter } from 'murow/net';
 import { Network } from '../network/base';
-import { InterpolationBuffer } from './interpolation-buffer';
+import { SnapshotInterpolation } from './strategies/snapshot-interpolation';
 import type { DefinedIntents, IntentPayload, IntentSchemaMap } from '../intents/define-intents';
 import type { DefinedRpcs, RpcPayload, RpcSchemaMap } from '../rpcs/define-rpcs';
 import type { DefinedPredictions } from '../predictions/define-predictions';
@@ -22,6 +22,16 @@ export interface SnapshotInterpolationStrategy {
      * Defaults to `delay * 2 + 100`.
      */
     staleWindow?: number;
+    /**
+     * Desync past which the play-out clock snaps instead of warping, ms.
+     * Scaled by tick rate internally. Default 500.
+     */
+    maxDesync?: number;
+    /**
+     * Largest data gap a peer may have before its value is held instead of
+     * interpolated across, ms. Smaller gaps are bridged. Default 250.
+     */
+    maxBridgeGap?: number;
 }
 /**
  * How peer entities are rendered on the client. Local-player rendering
@@ -59,7 +69,7 @@ export declare class GameClient<I extends IntentSchemaMap = IntentSchemaMap, R e
     readonly rpcs: DefinedRpcs<R>;
     private predictionMap;
     private predictionBufferSize;
-    private predictionHistory;
+    private reconciler;
     private localTick;
     private intentSequence;
     private lastServerTick;
@@ -72,9 +82,11 @@ export declare class GameClient<I extends IntentSchemaMap = IntentSchemaMap, R e
     private predictedEntities;
     /** Set when MSG_ASSIGN_ENTITY lands before the matching spawn. */
     private pendingAssignedServerEid;
+    /** Spawns discovered during a decode, emitted once values are written. */
+    private deferredSpawns;
     /** Resolved local entity for the server's assignment. Default for sendIntent. */
     private _assignedEntity;
-    interpBuffer: InterpolationBuffer;
+    interpBuffer: SnapshotInterpolation;
     private _rttMs;
     private now;
     /**
@@ -122,4 +134,6 @@ export declare class GameClient<I extends IntentSchemaMap = IntentSchemaMap, R e
     getPredictionDepth(): number;
     get interpolationDelay(): number;
     setInterpolationDelay(ms: number): void;
+    setMaxDesync(ms: number): void;
+    setMaxBridgeGap(ms: number): void;
 }

package/dist/netcode/types/client/strategies/snapshot-interpolation.d.ts

@@ -0,0 +1,33 @@
+import type { Component, Entity, World } from 'murow/ecs';
+export interface BufferedSnapshot {
+    receivedAt: number;
+    serverTick: number;
+    entityIds: number[];
+    componentValuesByEntity: Map<number, Map<Component<any>, Record<string, number>>>;
+}
+/**
+ * Snapshot-interpolation strategy: renders peer entities `delay` ms behind the
+ * newest snapshot, lerping between the two snapshots straddling that past time.
+ * Composes a core `Timeline` (snapshot history) and a core `SlewClock`
+ * (play-out clock). Predicted entities are skipped; reconciliation drives them.
+ */
+export declare class SnapshotInterpolation {
+    private serverToLocal;
+    private timeline;
+    private clock;
+    private smoothedTickRateMs;
+    private nominalTickMs;
+    delay: number;
+    maxDesync: number;
+    maxBridgeGap: number;
+    constructor(serverToLocal: Map<number, Entity>, capacity: number, delayMs: number, staleWindowMs: number, maxDesyncMs?: number, nominalTickMs?: number, maxBridgeGapMs?: number);
+    get staleWindow(): number;
+    setDelay(delayMs: number): void;
+    setStaleWindow(staleWindowMs: number): void;
+    setMaxDesync(maxDesyncMs: number): void;
+    setMaxBridgeGap(maxBridgeGapMs: number): void;
+    record(snapshot: BufferedSnapshot): void;
+    clear(): void;
+    apply(world: World, now: number, components: Component<any>[], shouldSkip: (entity: Entity) => boolean): void;
+    private writeSnapshot;
+}

package/dist/netcode/types/codec/delta-codec.d.ts

@@ -1,5 +1,5 @@
 import type { Component, World } from 'murow/ecs';
-export declare function encodeDelta(world: World, tick: number, entities: number[], components: Component<any>[], numMaskWords: number, despawned?: number[], clientAckTick?: number): Uint8Array;
+export declare function encodeDelta(world: World, tick: number, entities: number[], components: Component<any>[], numMaskWords: number, despawned?: number[], clientAckTick?: number, includeComponent?: (entity: number, component: Component<any>) => boolean): Uint8Array;
 export interface DecodedDelta {
     tick: number;
     clientAckTick: number;

package/dist/netcode/types/components/sync-spec.d.ts

@@ -41,3 +41,9 @@ export interface SyncSpec {
  * });
  */
 export declare function networked(spec: SyncSpec): SyncSpec;
+/**
+ * Whether a component's value rides along in the snapshot for the given
+ * tick. `every-tick` always; `on-change` only when the field changed
+ * since the last snapshot; `{ every: N }` on every Nth tick or on change.
+ */
+export declare function rateIncludes(rate: SyncRate, dirty: boolean, tick: number): boolean;

package/dist/types/core/clock/clock.d.ts

@@ -0,0 +1,37 @@
+export interface SlewClockOptions {
+    /** Drift under this advances at nominal rate instead of warping. Default 0.25. */
+    deadZone?: number;
+    /** Step bounds while warping to close a gap. */
+    warp?: {
+        /** Minimum step when warping to close a gap. Default 0.6. */
+        min?: number;
+        /** Maximum step when warping to close a gap. Default 1.4. */
+        max?: number;
+    };
+    /** Per-unit-of-drift warp gain. Default 0.1. */
+    gain?: number;
+}
+/**
+ * A scalar that advances one nominal step per `advance` toward a moving
+ * target, slewing within a band to close drift, holding steady inside a
+ * dead-zone, and snapping when the forward gap is too large to chase.
+ *
+ * Domain-agnostic: the caller supplies the target and the snap threshold.
+ */
+export declare class SlewClock {
+    private _value;
+    private readonly deadZone;
+    private readonly warpMin;
+    private readonly warpMax;
+    private readonly gain;
+    constructor(opts?: SlewClockOptions);
+    get value(): number;
+    get initialized(): boolean;
+    reset(): void;
+    /**
+     * Advance toward `target`. Seeds to `target` on first call. Forward drift
+     * beyond `snap` jumps to `target`; drift inside the dead-zone advances one
+     * nominal step; otherwise the step warps within the band to close the gap.
+     */
+    advance(target: number, snap: number): number;
+}

package/dist/types/core/clock/index.d.ts

@@ -0,0 +1 @@
+export { SlewClock, type SlewClockOptions } from './clock';

package/dist/types/core/hitbox/hitbox-library.d.ts

@@ -0,0 +1,29 @@
+import { Hitbox } from './hitbox';
+/**
+ * HitboxLibrary — a named, mode-typed registry of `Hitbox` definitions.
+ *
+ * The canonical set of collision archetypes a game uses, declared once in
+ * shared code and read by the renderer (client picking), game logic, and a
+ * headless server alike. Resolves by name (`get`, serializable/authoring)
+ * or by index (`at`, for ECS components that store a numeric archetype).
+ *
+ * `add` accumulates the name union, so `bucket.hitboxes(lib)` can offer the
+ * registered names as an autocompleting, typo-checked literal type.
+ */
+export declare class HitboxLibrary<M extends '2d' | '3d' = '3d', Names extends string = never> {
+    readonly mode: M;
+    private readonly names;
+    private readonly boxes;
+    private readonly index;
+    constructor(mode: M);
+    /** Register a hitbox under `name`. Returns a library whose type carries the new name. */
+    add<const N extends string>(name: N, hitbox: Hitbox<M>): HitboxLibrary<M, Names | N>;
+    /** Resolve by name. Throws on an unknown name. */
+    get(name: Names): Hitbox<M>;
+    /** Resolve by index — the fast path for ECS components storing a numeric archetype. */
+    at(index: number): Hitbox<M>;
+    /** Numeric index for a name, for storing on an entity. Throws on an unknown name. */
+    indexOf(name: Names): number;
+    /** Registered names, in insertion order. */
+    keys(): readonly string[];
+}