@colyseus/core 0.18.0 → 0.18.1

package/build/Rewind.d.ts

@@ -0,0 +1,291 @@
+import { type MapSchema, type ArraySchema, type SetSchema } from "@colyseus/schema";
+/** Keys of T whose value type is `number` — the only rewindable fields. */
+type NumericKeys<T> = {
+    [K in keyof T]-?: T[K] extends number ? K : never;
+}[keyof T] & string;
+/** A Colyseus collection whose element type is `E`. Inferring `E` from the live
+ *  collection the caller passes is what lets `fields` narrow with zero state-type
+ *  plumbing. */
+type Collection<E> = MapSchema<E> | ArraySchema<E> | SetSchema<E>;
+/** Options for {@link Rewind.get} / {@link Room.allowRewindState}. */
+export interface RewindOptions {
+    /** Default rewind window (ms) for attaches that don't pass their own — sizes the
+     *  per-entity history ring. Per-attach `maxRewindMs` overrides it. Default 500. */
+    maxRewindMs?: number;
+}
+/** The lag-comp technique an attach-group rewinds to — the TIMELINE the client
+ *  displays those targets on. `"snapshot"` (default): the renderTime stamp (what
+ *  a lerping/damped client shows, behind real time). `"reckon"`: the reckonTime
+ *  stamp (what a forward-extrapolated client shows, ≈ serverNow). Declared at
+ *  {@link Rewind.attachAll}, not on the schema. */
+export type RewindMode = "snapshot" | "reckon";
+/** How `valueAt` reconstructs a value between recorded samples: `linear` interp
+ *  (continuous motion) or `step` = hold the last sample (discrete motion). */
+type Interp = "linear" | "step";
+/**
+ * A read-only view of the tracked world at ONE past time — the rewound state a
+ * hit test reads instead of live positions. Created by {@link Rewind.at} /
+ * {@link Rewind.lastSeenBy}, which bake in the `maxRewindMs` clamp and the
+ * live-fallback so callers never re-implement either.
+ *
+ * The view assumes NOTHING about your schema's field names — you name the
+ * fields (and therefore the shape) at the call site:
+ *
+ * ```ts
+ * const seen = rewind.lastSeenBy(shooterSessionId);
+ * // read fields directly…
+ * overlaps(bullet, seen.value(target, "x"), seen.value(target, "y"));
+ * // …or batch them into an object shaped by YOUR field list:
+ * const pos = seen.read(target, ["x", "y"]);        // { x, y }
+ * seen.read(enemy, ["x", "y"], this.seenScratch);   // fill + return a reused scratch
+ * ```
+ *
+ * By default `at`/`lastSeenBy` re-aim and return the Rewind's own internal
+ * view — the usual "one view at a time, read it right away" flow is zero-alloc
+ * AND zero-setup (the server is single-threaded; nothing interleaves a
+ * synchronous read). Need more than one view alive at once (compare two
+ * shooters' perspectives, A/B a rewind window)? Pass your own instance as
+ * their `out` — it is re-aimed and returned instead of the shared one:
+ *
+ * ```ts
+ * const a = rewind.lastSeenBy(shooterA);                      // shared default view
+ * const b = rewind.lastSeenBy(shooterB, new RewindView());    // independent second view
+ * ```
+ *
+ * Don't store a view across calls or ticks: the default is re-aimed by the
+ * next `at`/`lastSeenBy`, and ANY view's clamp was computed against
+ * `lastRecordedAt`, so it goes stale at the next `record()` regardless.
+ */
+export declare class RewindView {
+    /** Bound (and re-bound) by {@link _retarget} — a bare `new RewindView()` is
+     *  un-aimed scratch until it first passes through at()/lastSeenBy(). */
+    private rewind?;
+    private _time;
+    private _reckonTime;
+    /** The clamped server-time (ms) this view reads at — after the maxRewindMs
+     *  clamp and the live (newest-sample) fallback. Mostly for logging/debug. */
+    get time(): number;
+    /** The clamped server-time (ms) `mode: "reckon"` groups read at — the
+     *  client's reconstructed simulation instant, not the raw stamp (see
+     *  {@link Rewind.at}). Always a resolved instant: a clamped direct stamp,
+     *  or the midpoint/live reconstruction when unstamped. `0` only before the
+     *  first `record()`. */
+    get reckonTime(): number;
+    /** @internal Aim at a rewind + clamped times ({@link Rewind.at} owns the clamps). */
+    _retarget(rewind: Rewind, at: number, reckonAt: number): this;
+    /** Rewound value of a numeric `field` on `entity` (live if it isn't tracked). */
+    value<T extends object>(entity: T, field: NumericKeys<T>): number;
+    /**
+     * Batch {@link value} reads: the `fields` YOU list define the result's shape
+     * (`Record<field, number>`). Pass `out` to fill (and return) a reused scratch
+     * instead of allocating — its properties beyond `fields` are left untouched,
+     * so a scratch can carry extra context (an `alive` flag, say).
+     */
+    read<T extends object, F extends NumericKeys<T>, O extends Record<F, number> = Record<F, number>>(entity: T, fields: readonly F[], out?: O): O;
+}
+/**
+ * Per-attach options for {@link Rewind.attachAll} / {@link Rewind.attach}.
+ */
+interface AttachOptions<E> {
+    /** Numeric fields to record per tick. An array applies to every type in the
+     *  collection (fields a type lacks are skipped — they read live); a per-entity
+     *  fn picks the list per entity, mirroring `interpolate`'s fn form. */
+    fields: readonly NumericKeys<E>[] | ((entity: E) => readonly NumericKeys<E>[]);
+    maxRewindMs?: number;
+    /** How `valueAt` reconstructs between samples (a mode or a per-entity fn,
+     *  default `linear`) — use `step` for discrete motion (e.g. teleporters). */
+    interpolate?: Interp | ((entity: E) => Interp);
+    /**
+     * The lag-comp TIMELINE these fields rewind to — must match how the CLIENT
+     * displays this target ("what you see is what you hit"):
+     *   - `"snapshot"` (default): rewind to the client's `renderTime` — for
+     *     targets it shows INTERPOLATED (Predict `lerp`/`damped`), behind real
+     *     time by its interp buffer + rtt/2.
+     *   - `"reckon"`: rewind to the client's `reckonTime` (≈ its serverNow) — for
+     *     targets it forward-extrapolates (Predict `reckon`).
+     * Attach the same collection twice with disjoint `fields` to mix techniques.
+     * The room ships exactly the stamp(s) its attached groups need (see the
+     * handshake derivation in `Room`).
+     */
+    mode?: RewindMode;
+}
+/**
+ * Server-side lag compensation — the dual of the client's `Predict`. Where
+ * `Predict` forward-reckons entities it RECEIVES, `Rewind` records the recent
+ * positions of entities it OWNS and rewinds field reads to a past (client
+ * render) time, so a hit test judges against where the client actually SAW an
+ * entity — not where it has slid to ~RTT later.
+ *
+ * Prefer {@link Room.allowRewindState}, which creates a `Rewind` and records it
+ * automatically each simulation tick:
+ *
+ * @example
+ * ```ts
+ * onCreate() {
+ *   const rewind = this.allowRewindState({ maxRewindMs: 500 });
+ *   rewind.attachAll(this.state.enemies, { fields: ["x", "y"] });  // fields ← Enemy's numeric keys
+ *   this.setTimestep((dt) => { ...move enemies... }, 1000 / 30);
+ *   // framework calls rewind.record() after each tick.
+ * }
+ * // in your hit test, with the client's renderTime:
+ * const seenX = rewind.valueAt(enemy, renderTime, "x");
+ * ```
+ *
+ * `attachAll` takes the live collection (not a string key), so the element type
+ * — and the legal `fields` / `valueAt` field names — are inferred with no
+ * state-type generic. Entities are keyed by object identity — removed entities
+ * and their history are reclaimed automatically.
+ *
+ * The rewind TIMELINE is declared per attach-group via `attachAll(coll, { mode })`:
+ * `"snapshot"` (default) reads at the client's `renderTime` stamp, `"reckon"` at
+ * its `reckonTime` (see {@link at}). Not-attached = not rewound (reads are live)
+ * — there is no "none". The same collection may be attached more than once with
+ * disjoint `fields` to put different fields on different timelines. The room
+ * ships exactly the stamp(s) these groups need (handshake derivation reads
+ * {@link timelineMode}); the client declares its display mode independently.
+ */
+export declare class Rewind {
+    private static readonly byRoom;
+    /** One `Rewind` per room (idempotent). `room` is only the cache key. */
+    static get(room: object, opts?: RewindOptions): Rewind;
+    private readonly groups;
+    private readonly defaultMaxRewindMs;
+    private _sampleIntervalMs;
+    private _lastRecordedAt;
+    /** Resolves a client's auto-stamped render time (set by `Room.allowRewindState`
+     *  when a `mode:"snapshot"` group is attached); powers {@link lastSeenBy}. */
+    private _renderTimeOf?;
+    /** Resolves a client's auto-stamped reckon-display instant (its serverNow
+     *  estimate at input-sample time). When present (> 0), {@link lastSeenBy}
+     *  reads `mode:"reckon"` groups AT this stamp directly — exact regardless
+     *  of the client's clock/RTT-estimation error (it displayed f(est), we read
+     *  f(est)) — instead of reconstructing it via the midpoint. */
+    private _reckonTimeOf?;
+    /** Resolves the CURRENT server time (set by `Room.allowRewindState`) — the
+     *  reckon midpoint's "now" anchor in {@link at}. Without it, the anchor falls
+     *  back to `lastRecordedAt`, which is one tick stale at hit-test time. */
+    private _nowOf?;
+    /** Default view returned by at/lastSeenBy when no `out` is given — one per
+     *  Rewind, re-aimed per call (zero alloc, zero userland setup). */
+    private readonly _view;
+    private constructor();
+    /** The default rewind window (ms). Use it to bound a hit test:
+     *  `Math.max(renderTime, now - rewind.maxRewindMs)`. */
+    get maxRewindMs(): number;
+    /** Server time of the last {@link record} (or -1). The auto-record skips a tick
+     *  whose time was already recorded manually — your `record()` wins. */
+    get lastRecordedAt(): number;
+    /** Track every entity in a collection (Map/Array/Set schema). `fields` narrows
+     *  to its element's numeric fields. `interpolate` (a mode or a per-entity fn,
+     *  default `linear`) picks how `valueAt` reconstructs between samples — use
+     *  `step` for discrete-motion entities (e.g. teleporters). `mode` picks the
+     *  lag-comp timeline (default `"snapshot"`; see {@link AttachOptions}). */
+    attachAll<E extends object>(collection: Collection<E>, opts: AttachOptions<E>): this;
+    /** Track a single entity (e.g. a boss). `fields` narrows to its numeric fields. */
+    attach<E extends object>(instance: E, opts: AttachOptions<E>): this;
+    /**
+     * Snapshot every tracked entity at `now`. Call once per tick, AFTER they move —
+     * {@link Room.allowRewindState} does this for you. `sampleIntervalMs` (the gap
+     * between records) sizes the history rings; the framework passes the sim
+     * interval. Calling this yourself during a tick suppresses that tick's
+     * auto-record (see {@link lastRecordedAt}).
+     */
+    record(now: number, sampleIntervalMs?: number): void;
+    /** Cold path — first time an entity is seen by `record()` for a given group.
+     *  Resolves the field→`$values` indices (cached per constructor for array-form
+     *  `fields`; fn-form resolves per entity) and bakes in the group's `mode`. */
+    private createHistory;
+    /** Keep only the fields this entity's type declares (unknown → read live). */
+    private resolveFields;
+    /**
+     * `instance`'s `field` value at past `time` (interpolated from history). Falls
+     * back to the live value when the entity has no history yet, or the field
+     * isn't tracked.
+     */
+    valueAt<T extends object>(instance: T, time: number, field: NumericKeys<T>): number;
+    /**
+     * Which timeline(s) the attached groups rewind to — `reckon` true iff any
+     * group is `mode:"reckon"`, `snapshot` true iff any is `mode:"snapshot"`. The
+     * room reads this once (groups are declared in `onCreate`, before any join) to
+     * pick which stamp(s) the client must ship: reckon-only / render-only / both /
+     * none. @internal
+     */
+    timelineMode(): {
+        reckon: boolean;
+        snapshot: boolean;
+    };
+    /**
+     * @internal Wire a resolver from sessionId → that client's auto-stamped
+     * `renderTime`. Called by {@link Room.allowRewindState} so {@link lastSeenBy}
+     * works for `mode:"snapshot"` groups; auto-enabled by attaching one.
+     */
+    bindRenderTime(resolver: (sessionId: string) => number): void;
+    /**
+     * @internal Wire a resolver for the CURRENT server time (ms, same epoch as
+     * `record` times). Called by {@link Room.allowRewindState}; standalone users
+     * (tests/harnesses) should bind their own. Anchors the reckon midpoint in
+     * {@link at} at the true processing instant — the `lastRecordedAt` fallback
+     * is one tick stale by hit-test time, biasing the aim ~half a tick early:
+     * imperceptible on slow horizontal motion, but enough to flip knife-edge
+     * stomp/hit verdicts on fast vertical movers (a bobbing jumper).
+     */
+    bindNow(resolver: () => number): void;
+    /**
+     * @internal Wire a resolver from sessionId → that client's auto-stamped
+     * reckon-display instant (`input(sid).reckonTime`). Called by
+     * {@link Room.allowRewindState}. With it, {@link lastSeenBy} aims
+     * `mode:"reckon"` groups at the EXACT instant the client displayed them
+     * (immune to its RTT-estimation error); without it (or while the stamp is
+     * still 0), the midpoint reconstruction in {@link at} is the fallback.
+     */
+    bindReckonTime(resolver: (sessionId: string) => number): void;
+    /**
+     * A {@link RewindView} of the tracked world at `time` (an acting client's render
+     * time), with the two things every hit test re-implements baked in:
+     *  - **clamp** to `[lastRecordedAt − maxRewindMs, lastRecordedAt]` — an
+     *    anti-spoof / clock-skew bound (a client can't rewind arbitrarily far), and
+     *  - **live fallback**: `time <= 0` (the client's clock hasn't synced) → the
+     *    newest recorded sample (≈ current position).
+     *
+     * Sugar over {@link valueAt}; pass the render time yourself (e.g. from
+     * `input(sid).renderTime`, or a value stored on the entity). For the common
+     * "rewind to a specific client's view" case use {@link lastSeenBy}.
+     *
+     * Re-aims and returns this Rewind's internal view by default — zero alloc,
+     * nothing to declare. Pass `out` to aim a view of your own instead; needed
+     * only to hold several views at once — see the {@link RewindView} doc.
+     */
+    at(time: number, out?: RewindView): RewindView;
+    /**
+     * Shared aiming: clamp the snapshot-timeline `time`, and resolve the reckon
+     * timeline either from the DIRECT `reckonStamp` (the instant the client's
+     * forward-reckoned entities were displayed at — exact, immune to the
+     * client's RTT-estimation error) or, when absent (0), by reconstruction.
+     */
+    private _aim;
+    /**
+     * A {@link RewindView} of the world as session `sessionId` LAST saw it —
+     * resolves the render time stamped on that client's most recently CONSUMED
+     * input (hence "last": under a multi-frame `drain()` it is the newest frame's
+     * stamp) and hands off to {@link at}. This is the "what you see is what you
+     * hit" path:
+     *
+     * ```ts
+     * const seen = this.rewind.lastSeenBy(shooterSessionId);
+     * const hit = overlaps(bullet, seen.value(target, "x"), seen.value(target, "y"));
+     * ```
+     *
+     * Requires the room's framework input (`this.defineInput(Input)`) — the
+     * per-client stamp auto-enables from the `attachAll` `mode` of the groups you
+     * rewind (declaration order vs `allowRewindState` doesn't matter). A client
+     * that merely hasn't stamped yet (clock still syncing, unknown sessionId) is
+     * NOT an error — it reads 0 and the view falls back to live. Use
+     * {@link at} with an explicit time if you stamp render times yourself.
+     *
+     * Re-aims and returns this Rewind's internal view by default — zero alloc,
+     * nothing to declare. Pass `out` to aim a view of your own instead; needed
+     * only to hold several views at once — see the {@link RewindView} doc.
+     */
+    lastSeenBy(sessionId: string, out?: RewindView): RewindView;
+}
+export {};

package/build/Rewind.mjs

@@ -0,0 +1,359 @@
+// packages/core/src/Rewind.ts
+import { $values } from "@colyseus/schema";
+import { $METADATA } from "./utils/Utils.mjs";
+var DEFAULT_MAX_REWIND_MS = 500;
+var DEFAULT_SAMPLE_INTERVAL_MS = 1e3 / 60;
+var $HISTORY = /* @__PURE__ */ Symbol("rewind.history");
+function fieldIndexOf(instance, field) {
+  const md = instance.constructor[$METADATA];
+  const idx = md?.[field];
+  return typeof idx === "number" ? idx : -1;
+}
+var EntityHistory = class {
+  constructor(fields, fieldIdx, maxRewindMs, sampleIntervalMs, step, reckoned, groupId) {
+    // hold (vs lerp) between samples
+    this.head = 0;
+    // next write slot
+    this.count = 0;
+    this.fields = fields;
+    this.fieldIdx = fieldIdx;
+    this.step = step;
+    this.reckoned = reckoned;
+    this.groupId = groupId;
+    this.cap = Math.max(2, Math.ceil(maxRewindMs / sampleIntervalMs) + 4);
+    this.t = new Float64Array(this.cap);
+    this.cols = fields.map(() => new Float64Array(this.cap));
+  }
+  /** `values` = the entity's dense `$values` array. Direct array reads — no
+   *  per-field megamorphic accessor. */
+  record(time, values) {
+    const fieldIdx = this.fieldIdx;
+    this.t[this.head] = time;
+    for (let f = 0; f < fieldIdx.length; f++) this.cols[f][this.head] = values[fieldIdx[f]];
+    this.head = (this.head + 1) % this.cap;
+    if (this.count < this.cap) this.count++;
+  }
+  /** Interpolated value of column `col` at `time`, clamped to the retained range. */
+  valueAt(time, col) {
+    const c = this.cols[col];
+    const oldest = (this.head - this.count + this.cap) % this.cap;
+    if (time <= this.t[oldest]) return c[oldest];
+    const newest = (this.head - 1 + this.cap) % this.cap;
+    if (time >= this.t[newest]) return c[newest];
+    let prev = oldest;
+    for (let i = 1; i < this.count; i++) {
+      const idx = (oldest + i) % this.cap;
+      if (this.t[idx] >= time) {
+        if (this.step) return c[prev];
+        const t0 = this.t[prev], t1 = this.t[idx];
+        const a = t1 > t0 ? (time - t0) / (t1 - t0) : 0;
+        return c[prev] + (c[idx] - c[prev]) * a;
+      }
+      prev = idx;
+    }
+    return c[newest];
+  }
+};
+function historyForField(instance, field) {
+  const arr = instance[$HISTORY];
+  if (arr === void 0) return void 0;
+  for (let i = 0; i < arr.length; i++) {
+    if (arr[i].fields.indexOf(field) >= 0) return arr[i];
+  }
+  return void 0;
+}
+var RewindView = class {
+  constructor() {
+    this._time = 0;
+    this._reckonTime = 0;
+  }
+  /** The clamped server-time (ms) this view reads at — after the maxRewindMs
+   *  clamp and the live (newest-sample) fallback. Mostly for logging/debug. */
+  get time() {
+    return this._time;
+  }
+  /** The clamped server-time (ms) `mode: "reckon"` groups read at — the
+   *  client's reconstructed simulation instant, not the raw stamp (see
+   *  {@link Rewind.at}). Always a resolved instant: a clamped direct stamp,
+   *  or the midpoint/live reconstruction when unstamped. `0` only before the
+   *  first `record()`. */
+  get reckonTime() {
+    return this._reckonTime;
+  }
+  /** @internal Aim at a rewind + clamped times ({@link Rewind.at} owns the clamps). */
+  _retarget(rewind, at, reckonAt) {
+    this.rewind = rewind;
+    this._time = at;
+    this._reckonTime = reckonAt;
+    return this;
+  }
+  /** Rewound value of a numeric `field` on `entity` (live if it isn't tracked). */
+  value(entity, field) {
+    if (this.rewind === void 0) {
+      throw new Error("RewindView is not aimed \u2014 obtain it from rewind.at()/lastSeenBy(), or pass it to them as `out`.");
+    }
+    const h = historyForField(entity, field);
+    if (h === void 0) return entity[field];
+    return h.valueAt(h.reckoned ? this._reckonTime : this._time, h.fields.indexOf(field));
+  }
+  /**
+   * Batch {@link value} reads: the `fields` YOU list define the result's shape
+   * (`Record<field, number>`). Pass `out` to fill (and return) a reused scratch
+   * instead of allocating — its properties beyond `fields` are left untouched,
+   * so a scratch can carry extra context (an `alive` flag, say).
+   */
+  read(entity, fields, out) {
+    const o = out ?? {};
+    for (let i = 0; i < fields.length; i++) o[fields[i]] = this.value(entity, fields[i]);
+    return o;
+  }
+};
+var Rewind = class _Rewind {
+  constructor(defaultMaxRewindMs) {
+    this.groups = [];
+    this._sampleIntervalMs = DEFAULT_SAMPLE_INTERVAL_MS;
+    this._lastRecordedAt = -1;
+    /** Default view returned by at/lastSeenBy when no `out` is given — one per
+     *  Rewind, re-aimed per call (zero alloc, zero userland setup). */
+    this._view = new RewindView();
+    this.defaultMaxRewindMs = defaultMaxRewindMs;
+  }
+  static {
+    this.byRoom = /* @__PURE__ */ new WeakMap();
+  }
+  /** One `Rewind` per room (idempotent). `room` is only the cache key. */
+  static get(room, opts) {
+    let r = _Rewind.byRoom.get(room);
+    if (r === void 0) {
+      r = new _Rewind(opts?.maxRewindMs ?? DEFAULT_MAX_REWIND_MS);
+      _Rewind.byRoom.set(room, r);
+    }
+    return r;
+  }
+  /** The default rewind window (ms). Use it to bound a hit test:
+   *  `Math.max(renderTime, now - rewind.maxRewindMs)`. */
+  get maxRewindMs() {
+    return this.defaultMaxRewindMs;
+  }
+  /** Server time of the last {@link record} (or -1). The auto-record skips a tick
+   *  whose time was already recorded manually — your `record()` wins. */
+  get lastRecordedAt() {
+    return this._lastRecordedAt;
+  }
+  /** Track every entity in a collection (Map/Array/Set schema). `fields` narrows
+   *  to its element's numeric fields. `interpolate` (a mode or a per-entity fn,
+   *  default `linear`) picks how `valueAt` reconstructs between samples — use
+   *  `step` for discrete-motion entities (e.g. teleporters). `mode` picks the
+   *  lag-comp timeline (default `"snapshot"`; see {@link AttachOptions}). */
+  attachAll(collection, opts) {
+    const c = collection;
+    this.groups.push({ entities: () => c.values(), fields: opts.fields, resolvedByCtor: /* @__PURE__ */ new Map(), maxRewindMs: opts.maxRewindMs ?? this.defaultMaxRewindMs, interpolate: opts.interpolate ?? "linear", reckoned: opts.mode === "reckon", groupId: this.groups.length });
+    return this;
+  }
+  /** Track a single entity (e.g. a boss). `fields` narrows to its numeric fields. */
+  attach(instance, opts) {
+    const one = [instance];
+    this.groups.push({ entities: () => one, fields: opts.fields, resolvedByCtor: /* @__PURE__ */ new Map(), maxRewindMs: opts.maxRewindMs ?? this.defaultMaxRewindMs, interpolate: opts.interpolate ?? "linear", reckoned: opts.mode === "reckon", groupId: this.groups.length });
+    return this;
+  }
+  /**
+   * Snapshot every tracked entity at `now`. Call once per tick, AFTER they move —
+   * {@link Room.allowRewindState} does this for you. `sampleIntervalMs` (the gap
+   * between records) sizes the history rings; the framework passes the sim
+   * interval. Calling this yourself during a tick suppresses that tick's
+   * auto-record (see {@link lastRecordedAt}).
+   */
+  record(now, sampleIntervalMs) {
+    if (sampleIntervalMs !== void 0 && sampleIntervalMs > 0) this._sampleIntervalMs = sampleIntervalMs;
+    this._lastRecordedAt = now;
+    for (const g of this.groups) {
+      for (const e of g.entities()) {
+        const t = e;
+        let arr = t[$HISTORY];
+        if (arr === void 0) {
+          arr = [];
+          t[$HISTORY] = arr;
+        }
+        let h;
+        for (let i = 0; i < arr.length; i++) {
+          if (arr[i].groupId === g.groupId) {
+            h = arr[i];
+            break;
+          }
+        }
+        if (h === void 0) {
+          h = this.createHistory(g, e);
+          arr.push(h);
+        }
+        h.record(now, t[$values]);
+      }
+    }
+  }
+  /** Cold path — first time an entity is seen by `record()` for a given group.
+   *  Resolves the field→`$values` indices (cached per constructor for array-form
+   *  `fields`; fn-form resolves per entity) and bakes in the group's `mode`. */
+  createHistory(g, e) {
+    let rf;
+    if (typeof g.fields === "function") {
+      rf = this.resolveFields(e, g.fields(e));
+    } else {
+      let cached = g.resolvedByCtor.get(e.constructor);
+      if (cached === void 0) {
+        cached = this.resolveFields(e, g.fields);
+        g.resolvedByCtor.set(e.constructor, cached);
+      }
+      rf = cached;
+    }
+    const interp = typeof g.interpolate === "function" ? g.interpolate(e) : g.interpolate;
+    return new EntityHistory(rf.fields, rf.idx, g.maxRewindMs, this._sampleIntervalMs, interp === "step", g.reckoned, g.groupId);
+  }
+  /** Keep only the fields this entity's type declares (unknown → read live). */
+  resolveFields(e, names) {
+    const fields = [];
+    const idx = [];
+    for (const name of names) {
+      const i = fieldIndexOf(e, name);
+      if (i >= 0) {
+        fields.push(name);
+        idx.push(i);
+      }
+    }
+    return { fields, idx };
+  }
+  /**
+   * `instance`'s `field` value at past `time` (interpolated from history). Falls
+   * back to the live value when the entity has no history yet, or the field
+   * isn't tracked.
+   */
+  valueAt(instance, time, field) {
+    const h = historyForField(instance, field);
+    if (h === void 0) return instance[field];
+    return h.valueAt(time, h.fields.indexOf(field));
+  }
+  /**
+   * Which timeline(s) the attached groups rewind to — `reckon` true iff any
+   * group is `mode:"reckon"`, `snapshot` true iff any is `mode:"snapshot"`. The
+   * room reads this once (groups are declared in `onCreate`, before any join) to
+   * pick which stamp(s) the client must ship: reckon-only / render-only / both /
+   * none. @internal
+   */
+  timelineMode() {
+    let reckon = false, snapshot = false;
+    for (const g of this.groups) {
+      if (g.reckoned) reckon = true;
+      else snapshot = true;
+    }
+    return { reckon, snapshot };
+  }
+  /**
+   * @internal Wire a resolver from sessionId → that client's auto-stamped
+   * `renderTime`. Called by {@link Room.allowRewindState} so {@link lastSeenBy}
+   * works for `mode:"snapshot"` groups; auto-enabled by attaching one.
+   */
+  bindRenderTime(resolver) {
+    this._renderTimeOf = resolver;
+  }
+  /**
+   * @internal Wire a resolver for the CURRENT server time (ms, same epoch as
+   * `record` times). Called by {@link Room.allowRewindState}; standalone users
+   * (tests/harnesses) should bind their own. Anchors the reckon midpoint in
+   * {@link at} at the true processing instant — the `lastRecordedAt` fallback
+   * is one tick stale by hit-test time, biasing the aim ~half a tick early:
+   * imperceptible on slow horizontal motion, but enough to flip knife-edge
+   * stomp/hit verdicts on fast vertical movers (a bobbing jumper).
+   */
+  bindNow(resolver) {
+    this._nowOf = resolver;
+  }
+  /**
+   * @internal Wire a resolver from sessionId → that client's auto-stamped
+   * reckon-display instant (`input(sid).reckonTime`). Called by
+   * {@link Room.allowRewindState}. With it, {@link lastSeenBy} aims
+   * `mode:"reckon"` groups at the EXACT instant the client displayed them
+   * (immune to its RTT-estimation error); without it (or while the stamp is
+   * still 0), the midpoint reconstruction in {@link at} is the fallback.
+   */
+  bindReckonTime(resolver) {
+    this._reckonTimeOf = resolver;
+  }
+  /**
+   * A {@link RewindView} of the tracked world at `time` (an acting client's render
+   * time), with the two things every hit test re-implements baked in:
+   *  - **clamp** to `[lastRecordedAt − maxRewindMs, lastRecordedAt]` — an
+   *    anti-spoof / clock-skew bound (a client can't rewind arbitrarily far), and
+   *  - **live fallback**: `time <= 0` (the client's clock hasn't synced) → the
+   *    newest recorded sample (≈ current position).
+   *
+   * Sugar over {@link valueAt}; pass the render time yourself (e.g. from
+   * `input(sid).renderTime`, or a value stored on the entity). For the common
+   * "rewind to a specific client's view" case use {@link lastSeenBy}.
+   *
+   * Re-aims and returns this Rewind's internal view by default — zero alloc,
+   * nothing to declare. Pass `out` to aim a view of your own instead; needed
+   * only to hold several views at once — see the {@link RewindView} doc.
+   */
+  at(time, out) {
+    return this._aim(time, 0, out);
+  }
+  /**
+   * Shared aiming: clamp the snapshot-timeline `time`, and resolve the reckon
+   * timeline either from the DIRECT `reckonStamp` (the instant the client's
+   * forward-reckoned entities were displayed at — exact, immune to the
+   * client's RTT-estimation error) or, when absent (0), by reconstruction.
+   */
+  _aim(time, reckonStamp, out) {
+    const newest = this._lastRecordedAt;
+    const oldest = newest - this.defaultMaxRewindMs;
+    const at = time <= 0 ? newest : time < oldest ? oldest : time > newest ? newest : time;
+    let reckonAt;
+    if (reckonStamp > 0) {
+      reckonAt = reckonStamp < oldest ? oldest : reckonStamp > newest ? newest : reckonStamp;
+    } else if (time <= 0) {
+      reckonAt = newest;
+    } else {
+      const anchor = this._nowOf !== void 0 ? this._nowOf() : newest;
+      const mid = (time + anchor) / 2;
+      reckonAt = mid < oldest ? oldest : mid > newest ? newest : mid;
+    }
+    return (out ?? this._view)._retarget(this, at, reckonAt);
+  }
+  /**
+   * A {@link RewindView} of the world as session `sessionId` LAST saw it —
+   * resolves the render time stamped on that client's most recently CONSUMED
+   * input (hence "last": under a multi-frame `drain()` it is the newest frame's
+   * stamp) and hands off to {@link at}. This is the "what you see is what you
+   * hit" path:
+   *
+   * ```ts
+   * const seen = this.rewind.lastSeenBy(shooterSessionId);
+   * const hit = overlaps(bullet, seen.value(target, "x"), seen.value(target, "y"));
+   * ```
+   *
+   * Requires the room's framework input (`this.defineInput(Input)`) — the
+   * per-client stamp auto-enables from the `attachAll` `mode` of the groups you
+   * rewind (declaration order vs `allowRewindState` doesn't matter). A client
+   * that merely hasn't stamped yet (clock still syncing, unknown sessionId) is
+   * NOT an error — it reads 0 and the view falls back to live. Use
+   * {@link at} with an explicit time if you stamp render times yourself.
+   *
+   * Re-aims and returns this Rewind's internal view by default — zero alloc,
+   * nothing to declare. Pass `out` to aim a view of your own instead; needed
+   * only to hold several views at once — see the {@link RewindView} doc.
+   */
+  lastSeenBy(sessionId, out) {
+    if (this._renderTimeOf === void 0) {
+      throw new Error(
+        "Rewind.lastSeenBy(sessionId) needs the framework input API. Declare `this.defineInput(Input)` (stamps auto-enable from your attachAll `mode`), or call `at(time)` and pass the render time yourself."
+      );
+    }
+    return this._aim(
+      this._renderTimeOf(sessionId),
+      this._reckonTimeOf !== void 0 ? this._reckonTimeOf(sessionId) : 0,
+      out
+    );
+  }
+};
+export {
+  Rewind,
+  RewindView
+};