@colyseus/schema 5.0.6 → 5.0.8

package/src/types/custom/ArraySchema.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $proxyTarget, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $proxyTarget, $refId, $reset, $resyncPrune } from "../symbols.js";
 import type { Schema } from "../../Schema.js";
 import { type IRef, ChangeTree, installUntrackedChangeTree } from "../../encoder/ChangeTree.js";
 import { OPERATION } from "../../encoding/spec.js";
@@ -120,6 +120,8 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
     protected tmpItems: V[] = [];
     protected deletedIndexes: boolean[] = [];
     protected isMovingItems = false;
+    /** Decode-side: `items` has holes (delete or gap-write) — `$onDecodeEnd` must compact. */
+    protected _needsCompaction = false;
 
     static [$encoder] = encodeArray;
     static [$decoder] = decodeArray;
@@ -136,10 +138,11 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * - Then, the encoder iterates over all "owned" properties per instance and encodes them.
      */
     static [$filter] (ref: ArraySchema, index: number, view: StateView) {
+        if (!view) return true; // must stay first — encodeAll hits this per element
+        const self = ref[$proxyTarget] ?? ref; // ref arrives proxied — skip traps below
         return (
-            !view ||
-            typeof (ref[$childType]) === "string" ||
-            view.isChangeTreeVisible(ref['tmpItems'][index]?.[$changes])
+            typeof (self[$childType]) === "string" ||
+            view.isChangeTreeVisible(self['tmpItems'][index]?.[$changes])
         );
     }
 
@@ -194,6 +197,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         // staged-snapshot path in `$getByIndex`, `$onEncodeEnd`, etc.). The
         // decoder reads from `items` directly and never maintains them.
         self.isMovingItems = false;
+        self._needsCompaction = false;
         self[$childType] = undefined;
         self[$proxyTarget] = self;
 
@@ -344,6 +348,9 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
             this.items[index] = value;
 
         } else {
+            if (index > this.items.length) {
+                this._needsCompaction = true; // gap-write (filtered/out-of-order ADD) leaves holes
+            }
             this.items[index] = value;
         }
     }
@@ -370,6 +377,27 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         self.tmpItems.length = 0;
     }
 
+    /**
+     * Pool reset: empty this array and recycle its ChangeTree WITHOUT recording
+     * any wire op (the parent field's ADD/DELETE owns the wire). Recurses into
+     * ref-type children. Called by Schema.reset when a pooled entity has an
+     * array field. The instance must already be detached from the encoder.
+     */
+    [$reset]() {
+        const self = this[$proxyTarget] ?? this;
+        const changeTree = self[$changes];
+        if (changeTree.isStreamCollection) {
+            throw new Error(`@colyseus/schema: cannot reset a streamed ArraySchema (pooling not supported).`);
+        }
+        const items = self.items;
+        for (let i = 0; i < items.length; i++) (items[i] as any)?.[$reset]?.();
+        self.items.length = 0;
+        self.tmpItems.length = 0;
+        self.deletedIndexes.length = 0;
+        changeTree.recycle();
+        self[$refId] = undefined; // assign (not delete) to avoid V8 dictionary-mode deopt
+    }
+
     /**
      * Combines two or more arrays.
      * @param items Additional items to add to the end of array1.
@@ -847,24 +875,54 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
      * `$deleteByIndex` below.
      */
     [$getByIndex](index: number, isEncodeAll: boolean = false): any {
+        const self = this[$proxyTarget] ?? this; // called via Proxy — one trap here beats one per field read
         return (isEncodeAll)
-            ? this.items[index]
-            : this.deletedIndexes[index]
-                ? this.items[index]
-                : this.tmpItems[index] || this.items[index];
+            ? self.items[index]
+            : self.deletedIndexes[index]
+                ? self.items[index]
+                : self.tmpItems[index] || self.items[index];
     }
 
     [$deleteByIndex](index: number): void {
-        this.items[index] = undefined;
+        const self = this[$proxyTarget] ?? this;
+        self.items[index] = undefined;
+        self._needsCompaction = true;
     }
 
     protected [$onEncodeEnd]() {
-        this.tmpItems = this.items.slice();
-        this.deletedIndexes.length = 0;
+        const self = this[$proxyTarget] ?? this;
+        self.tmpItems = self.items.slice();
+        self.deletedIndexes.length = 0;
     }
 
     protected [$onDecodeEnd]() {
-        this.items = this.items.filter((item) => item !== undefined);
+        const self = this[$proxyTarget] ?? this;
+        if (self._needsCompaction) {
+            self._needsCompaction = false;
+            self.items = self.items.filter((item) => item !== undefined);
+        }
+    }
+
+    [$resyncPrune](
+        visited: Set<number | string>,
+        prune: (value: V, identity: number | string) => void,
+        keep: (value: V) => void,
+    ): void {
+        // `items` is hole-free here: the decode loop's $onDecodeEnd already
+        // ran, and a full-sync emits dense ADDs (no DELETEs, no gap-writes)
+        // so no compaction happened mid-decode. Visited indexes may still be
+        // sparse (ADD_BY_REFID resolves to the current client-side index).
+        const self = this[$proxyTarget] ?? this;
+        const items = self.items;
+        let removed = false;
+        for (let i = 0; i < items.length; i++) {
+            const value = items[i];
+            if (visited.has(i)) { keep(value); continue; }
+            removed = true;
+            prune(value, i);
+            self[$deleteByIndex](i);
+        }
+        if (removed) { self[$onDecodeEnd](); } // compact the holes
     }
 
     toArray() {

package/src/types/custom/CollectionSchema.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId, $reset, $resyncPrune } from "../symbols.js";
 import { ChangeTree, installUntrackedChangeTree, type IRef } from "../../encoder/ChangeTree.js";
 import { OPERATION } from "../../encoding/spec.js";
 import { registerType } from "../registry.js";
@@ -195,6 +195,25 @@ export class CollectionSchema<V=any> implements Collection<K, V>, IRef {
         changeTree.operation(OPERATION.CLEAR);
     }
 
+    /**
+     * Pool reset: empty this collection and recycle its ChangeTree WITHOUT
+     * recording any wire op (the parent field's ADD/DELETE owns the wire).
+     * Recurses into ref-type children. Called by Schema.reset when a pooled
+     * entity has a collection field. Must already be detached from the encoder.
+     */
+    [$reset]() {
+        const changeTree = this[$changes];
+        if (changeTree.isStreamCollection) {
+            throw new Error(`@colyseus/schema: cannot reset a streamed CollectionSchema (pooling not supported).`);
+        }
+        this.$items.forEach((value: any) => value?.[$reset]?.());
+        this.$items.clear();
+        this.deletedItems = {};
+        this.$refId = 0; // reset the monotonic index counter (field, not the symbol)
+        changeTree.recycle();
+        this[$refId] = undefined; // drop encoder ref identity by assign (not delete: avoids dict-mode deopt)
+    }
+
     has (value: V): boolean {
         return Array.from(this.$items.values()).some((v) => v === value);
     }
@@ -244,6 +263,22 @@ export class CollectionSchema<V=any> implements Collection<K, V>, IRef {
         this.$items.delete(index);
     }
 
+    [$resyncPrune](
+        visited: Set<number | string>,
+        prune: (value: V, identity: number | string) => void,
+        keep: (value: V) => void,
+    ): void {
+        let toDelete: number[] | null = null;
+        this.$items.forEach((value, index) => {
+            if (visited.has(index)) { keep(value); return; }
+            (toDelete ??= []).push(index);
+            prune(value, index);
+        });
+        if (toDelete !== null) {
+            for (let i = 0; i < toDelete.length; i++) { this[$deleteByIndex](toDelete[i]); }
+        }
+    }
+
     protected [$onEncodeEnd]() {
         for (const key in this.deletedItems) { delete this.deletedItems[key]; }
     }

package/src/types/custom/MapSchema.ts

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $refId, $reset, $resyncPrune } from "../symbols.js";
 import { ChangeTree, installUntrackedChangeTree, IRef } from "../../encoder/ChangeTree.js";
 import { OPERATION } from "../../encoding/spec.js";
 import { registerType } from "../registry.js";
@@ -283,6 +283,25 @@ export class MapSchema<V=any, K extends string = string> implements Map<K, V>, C
         changeTree.operation(OPERATION.CLEAR);
     }
 
+    /**
+     * Pool reset: empty this map and recycle its ChangeTree WITHOUT recording
+     * any wire op (the parent field's ADD/DELETE owns the wire). Recurses into
+     * ref-type children. Called by Schema.reset when a pooled entity has a
+     * map field. The instance must already be detached from the encoder.
+     */
+    [$reset]() {
+        const changeTree = this[$changes];
+        if (changeTree.isStreamCollection) {
+            throw new Error(`@colyseus/schema: cannot reset a streamed MapSchema (pooling not supported).`);
+        }
+        // reset ref-type children first (primitives optional-chain away)
+        this.$items.forEach((value: any) => value?.[$reset]?.());
+        this.$items.clear();
+        this.journal.reset();
+        changeTree.recycle();
+        this[$refId] = undefined; // assign (not delete) to avoid V8 dictionary-mode deopt
+    }
+
     has (key: K) {
         return this.$items.has(key);
     }
@@ -334,6 +353,36 @@ export class MapSchema<V=any, K extends string = string> implements Map<K, V>, C
         }
     }
 
+    [$resyncPrune](
+        visited: Set<number | string>,
+        prune: (value: V, identity: number | string) => void,
+        keep: (value: V) => void,
+    ): void {
+        // maps prune by string key, NOT wire index — the decoder-side
+        // journal never evicts stale index→key mappings on re-indexing.
+        let deletedKeys: Set<string> | null = null;
+        this.$items.forEach((value, key) => {
+            if (visited.has(key)) { keep(value); return; }
+            (deletedKeys ??= new Set()).add(key);
+            prune(value, key);
+        });
+        if (deletedKeys !== null) {
+            deletedKeys.forEach((key) => {
+                this.$items.delete(key as K);
+                delete this.journal.indexByKey[key];
+            });
+            // drop index→key mappings of swept keys — including stale ones
+            // left behind by re-indexing.
+            const staleIndexes: number[] = [];
+            this.journal.keyByIndex.forEach((key, index) => {
+                if (deletedKeys!.has(key as unknown as string)) { staleIndexes.push(index); }
+            });
+            for (let i = 0; i < staleIndexes.length; i++) {
+                this.journal.keyByIndex.delete(staleIndexes[i]);
+            }
+        }
+    }
+
     protected [$onEncodeEnd]() {
         this.journal.cleanupAfterEncode();
     }

package/src/types/custom/SetSchema.ts

@@ -1,6 +1,6 @@
 import { OPERATION } from "../../encoding/spec.js";
 import { registerType } from "../registry.js";
-import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId, $reset, $resyncPrune } from "../symbols.js";
 import { Collection } from "../HelperTypes.js";
 import { ChangeTree, installUntrackedChangeTree, type IRef } from "../../encoder/ChangeTree.js";
 import { encodeIndexedEntry } from "../../encoder/EncodeOperation.js";
@@ -195,6 +195,25 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
         changeTree.operation(OPERATION.CLEAR);
     }
 
+    /**
+     * Pool reset: empty this set and recycle its ChangeTree WITHOUT recording
+     * any wire op (the parent field's ADD/DELETE owns the wire). Recurses into
+     * ref-type children. Called by Schema.reset when a pooled entity has a set
+     * field. The instance must already be detached from the encoder.
+     */
+    [$reset]() {
+        const changeTree = this[$changes];
+        if (changeTree.isStreamCollection) {
+            throw new Error(`@colyseus/schema: cannot reset a streamed SetSchema (pooling not supported).`);
+        }
+        this.$items.forEach((value: any) => value?.[$reset]?.());
+        this.$items.clear();
+        this.deletedItems = {};
+        this.$refId = 0; // reset the monotonic index counter (field, not the symbol)
+        changeTree.recycle();
+        this[$refId] = undefined; // drop encoder ref identity by assign (not delete: avoids dict-mode deopt)
+    }
+
     has (value: V): boolean {
         const values = this.$items.values();
 
@@ -257,6 +276,22 @@ export class SetSchema<V=any> implements Collection<number, V>, IRef {
         this.$items.delete(index);
     }
 
+    [$resyncPrune](
+        visited: Set<number | string>,
+        prune: (value: V, identity: number | string) => void,
+        keep: (value: V) => void,
+    ): void {
+        let toDelete: number[] | null = null;
+        this.$items.forEach((value, index) => {
+            if (visited.has(index)) { keep(value); return; }
+            (toDelete ??= []).push(index);
+            prune(value, index);
+        });
+        if (toDelete !== null) {
+            for (let i = 0; i < toDelete.length; i++) { this[$deleteByIndex](toDelete[i]); }
+        }
+    }
+
     protected [$onEncodeEnd]() {
         for (const key in this.deletedItems) { delete this.deletedItems[key]; }
     }

package/src/types/custom/StreamSchema.ts

@@ -10,6 +10,7 @@ import {
     $getByIndex,
     $onEncodeEnd,
     $refId,
+    $resyncPrune,
 } from "../symbols.js";
 import { ChangeTree, installUntrackedChangeTree, type IRef } from "../../encoder/ChangeTree.js";
 import { encodeIndexedEntry } from "../../encoder/EncodeOperation.js";
@@ -266,6 +267,12 @@ export class StreamSchema<V = any> implements IRef {
         }
     }
 
+    [$resyncPrune](): void {
+        // Stream contents are delivered by the trickle/priority pass, NOT
+        // by full-sync (encodeAll carries none of them) — a snapshot is not
+        // authoritative for streams, so absence ≠ deleted. Never prune.
+    }
+
     protected [$onEncodeEnd](): void {
         // No per-tick cleanup: pending/sent state spans encode ticks by design.
     }

package/src/types/quantize.ts

@@ -0,0 +1,173 @@
+import { encode } from "../encoding/encode.js";
+import { decode } from "../encoding/decode.js";
+
+/**
+ * `t.quantized()` — a bounded float encoded as a fixed-width unsigned integer.
+ *
+ * A float that changes every frame within a known range (look angles, a
+ * normalized scalar, a unit-vector component) costs a full `float32` (4 value
+ * bytes). Mapping it onto `uint8`/`uint16`/`uint32` halves or quarters that at a
+ * precision you choose — e.g. a yaw on `uint16` is ~0.0055°/step, finer than any
+ * mouse, for 2 bytes instead of 4.
+ *
+ * Quantization is LOSSY, but lossy IDENTICALLY on both peers: the field only ever
+ * yields `dequant(q)`, so client prediction and server simulation read the SAME
+ * value and a predicted hitscan ray bit-matches the server's — the lossiness is
+ * vs. the original float, never between the two peers (see the reconciler note in
+ * `predict/reconciler.ts`).
+ *
+ * Portable by construction (a C/C#/Lua client must reproduce it bit-for-bit):
+ * rounding is explicit `floor(x + 0.5)` — NOT the language-default round, which
+ * disagrees on the `.5` case (JS half-up, C# banker's, C half-away) — and a
+ * wrapping range is reduced in the FLOAT domain BEFORE the integer step, so there
+ * is no huge-double→int cast (UB in C, throws in C#). All math is float64.
+ */
+export interface QuantizeOptions {
+    /** Inclusive lower bound of the value domain. */
+    min: number;
+    /** Upper bound of the value domain (inclusive when clamped, exclusive when wrapping). */
+    max: number;
+    /**
+     * Wire width in bits — a typed union, NOT a free integer: schema fields are
+     * byte-aligned, so only 8/16/32 change the wire (`bits: 13` would still occupy
+     * 2 bytes and mislead). Default 16.
+     */
+    bits?: 8 | 16 | 32;
+    /**
+     * Is the value CYCLIC (lives on a circle) or BOUNDED (has hard walls)? That is
+     * the whole choice — the wire size is identical either way.
+     *
+     * `"clamp"` (default) — for a BOUNDED value with hard ends (pitch, a health bar,
+     * a 0–1 throttle). A UNORM over `[min, max]` INCLUSIVE: both endpoints are exact
+     * + distinct, and out-of-range inputs CLAMP to the nearest end (`0` / `2^bits − 1`).
+     * Pitch past the limit stops AT the limit.
+     *
+     * `"wrap"` — for a CYCLIC value where `min` and `max` are the SAME point (an
+     * angle/heading, compass bearing, hue, phase). `[min, max)` over `2^bits` steps
+     * with the top folding onto the bottom; any input is range-reduced modulo
+     * `(max − min)` first, so a large accumulated or negative angle maps into the
+     * domain (yaw keeps spinning, never jams). `min` is exact; `max ≡ min`.
+     *
+     * Decision rule: does one step past the top return you to the bottom as the SAME
+     * physical thing? → `"wrap"`. Is the top a wall you can't cross? → `"clamp"`.
+     * Choosing wrong is a real bug: a clamped heading JAMS at the 0/2π seam; a wrapped
+     * pitch FLIPS the camera the instant you look a hair too far up.
+     *
+     * NB (cyclic fields): `"wrap"` fixes the WIRE seam, not rendering — a wrapped
+     * field that's interpolated must ALSO be lerped shortest-arc (the SDK predict
+     * `attach({ angle: true })`), or it unwinds the long way across the `0 ↔ max` seam.
+     */
+    mode?: "clamp" | "wrap";
+}
+
+/**
+ * Resolved, plain-data quantization descriptor stored on the field metadata as
+ * `{ quantized: QuantizeDescriptor }`. Both encode and decode derive `scale` from
+ * the same fields, so the two sides — and a future cross-language port — agree by
+ * construction. Serializable (no functions) so it can ride schema reflection.
+ */
+export interface QuantizeDescriptor {
+    min: number;
+    max: number;
+    bits: 8 | 16 | 32;
+    wrap: boolean;
+    /** Wire codec name — `"uint8" | "uint16" | "uint32"`, derived from `bits`. */
+    wire: "uint8" | "uint16" | "uint32";
+    /** `max − min`, the domain width. */
+    range: number;
+    /**
+     * The integer span used for the scale:
+     *  - wrapping: `2^bits` (the number of steps; the top step folds onto 0).
+     *  - clamped:  `2^bits − 1` (endpoints inclusive, so the max maps to it).
+     */
+    span: number;
+}
+
+const WIRE_BY_BITS: Record<number, "uint8" | "uint16" | "uint32"> = {
+    8: "uint8",
+    16: "uint16",
+    32: "uint32",
+};
+
+/** Validate options and precompute the wire codec + scale span. */
+export function resolveQuantize(opts: QuantizeOptions): QuantizeDescriptor {
+    if (opts == null || typeof opts !== "object") {
+        throw new Error("t.quantized(): options object with { min, max } is required.");
+    }
+    const { min, max } = opts;
+    if (typeof min !== "number" || typeof max !== "number" || !(max > min)
+        || !Number.isFinite(min) || !Number.isFinite(max)) {
+        throw new Error(`t.quantized(): require finite min < max (got min=${min}, max=${max}).`);
+    }
+    const bits = opts.bits ?? 16;
+    if (bits !== 8 && bits !== 16 && bits !== 32) {
+        throw new Error(`t.quantized(): bits must be 8, 16 or 32 (got ${bits}).`);
+    }
+    const mode = opts.mode ?? "clamp";
+    if (mode !== "clamp" && mode !== "wrap") {
+        throw new Error(`t.quantized(): mode must be "clamp" or "wrap" (got ${JSON.stringify(mode)}).`);
+    }
+    const wrap = mode === "wrap"; // descriptor + wire stay boolean; `mode` is the public knob
+    const steps = Math.pow(2, bits);
+    return {
+        min,
+        max,
+        bits,
+        wrap,
+        wire: WIRE_BY_BITS[bits],
+        range: max - min,
+        // wrapping spreads `2^bits` steps across [min,max) (top ≡ bottom); clamped
+        // maps the endpoints onto `0` and `2^bits − 1` inclusive.
+        span: wrap ? steps : steps - 1,
+    };
+}
+
+/** Type guard for the `{ quantized: QuantizeDescriptor }` field-type shape. */
+export function isQuantizedType(type: any): type is { quantized: QuantizeDescriptor } {
+    return type !== null && typeof type === "object" && (type as any).quantized !== undefined;
+}
+
+/**
+ * Float → unsigned integer. Rounding is explicit half-up `floor(x + 0.5)`;
+ * wrapping ranges are reduced in the float domain first (no huge→int cast).
+ */
+export function quantize(desc: QuantizeDescriptor, value: number): number {
+    if (desc.wrap) {
+        // Non-finite can't be range-reduced (Inf % range = NaN); NaN would flow to
+        // the wire as garbage while the local instance kept NaN — a silent peer
+        // divergence. Pin to q=0 (= min): garbage in, deterministic out, both agree.
+        if (!Number.isFinite(value)) return 0;
+        const range = desc.range;
+        // float-domain range reduction → [0, range)
+        let a = (value - desc.min) % range;
+        if (a < 0) a += range;
+        const steps = desc.span; // 2^bits
+        // `% steps` (not `& mask`) so bits=32 doesn't overflow JS's int32 bitwise.
+        return Math.floor((a / range) * steps + 0.5) % steps;
+    }
+    if (value !== value) return 0; // NaN → min (±Inf clamps naturally below)
+    const v = value < desc.min ? desc.min : value > desc.max ? desc.max : value;
+    return Math.floor(((v - desc.min) / desc.range) * desc.span + 0.5);
+}
+
+/** Unsigned integer → float. Correctly-rounded mul/div ⇒ bit-identical across languages. */
+export function dequantize(desc: QuantizeDescriptor, q: number): number {
+    return desc.min + (q / desc.span) * desc.range;
+}
+
+/**
+ * Pre-baked encoder for a quantized field: quantize the (snapped) float held on
+ * the instance, then write it with the field's unsigned-int wire codec. Stored in
+ * `metadata[$encoders]` so the encode hot path reaches it via the fast lane,
+ * exactly like the pre-computed primitive encoders.
+ */
+export function makeQuantizedEncoder(desc: QuantizeDescriptor) {
+    const writeWire = (encode as any)[desc.wire] as (bytes: any, value: number, it: any) => void;
+    return (bytes: any, value: number, it: any) => writeWire(bytes, quantize(desc, value), it);
+}
+
+/** Decode a quantized field: read the unsigned-int wire value, then dequantize. */
+export function decodeQuantized(desc: QuantizeDescriptor, bytes: any, it: any): number {
+    const readWire = (decode as any)[desc.wire] as (bytes: any, it: any) => number;
+    return dequantize(desc, readWire(bytes, it));
+}

package/src/types/symbols.ts

@@ -46,6 +46,13 @@ export const $filter = "~filter";
 
 export const $getByIndex = "~getByIndex";
 export const $deleteByIndex = "~deleteByIndex";
+/**
+ * Resync-sweep hook (see decoder/Resync.ts): prune every entry the rejoin
+ * snapshot did not visit. Each collection owns its storage-specific
+ * bookkeeping (journal pruning, compaction, item indexes); the generic
+ * DELETE/ref/callback bookkeeping arrives via the `prune`/`keep` callbacks.
+ */
+export const $resyncPrune = "~resyncPrune";
 
 /**
  * Used to hold ChangeTree instances whitin the structures.
@@ -75,6 +82,15 @@ export const $proxyTarget: unique symbol = Symbol.for("$proxyTarget");
  */
 export const $onEncodeEnd = '~onEncodeEnd';
 
+/**
+ * Optional "reset" method on every poolable Ref (Schema + collections).
+ * Empties the instance's backing store and recycles its ChangeTree WITHOUT
+ * emitting any wire op, and recurses into ref-type children — so the instance
+ * can be returned to a SchemaPool and reused, avoiding the cost of `new`.
+ * See encoder/Pool.ts and Schema.reset().
+ */
+export const $reset = "~reset";
+
 /**
  * When decoding, this method is called after the instance is fully decoded
  */

package/build/encoder/RefIdAllocator.d.ts

@@ -1,35 +0,0 @@
-/**
- * Allocates monotonically-increasing refIds with a reuse pool.
- *
- * `acquire()` pops from the free pool when available, otherwise bumps a
- * counter. `release()` queues a refId for reuse; the id doesn't become
- * acquirable until `flushReleases()` runs — the one-tick defer is what
- * lets the encoder guarantee a DELETE for the old instance reaches the
- * wire before the refId is handed to a new one.
- *
- * `reclaim()` handles "resurrection": a ref that was released but whose
- * JS instance is still alive can be re-added to the tree, in which case
- * the encoder must pull the refId back out of the pool before it's
- * handed to an unrelated instance.
- */
-export declare class RefIdAllocator {
-    protected nextUniqueId: number;
-    private _free;
-    private _pending;
-    private _pooled;
-    constructor(startRefId?: number);
-    acquire(): number;
-    release(refId: number): void;
-    isPooled(refId: number): boolean;
-    /**
-     * Remove a refId from the pool. Called when a ref whose refId was
-     * released is being resurrected. O(n) scan of the relevant array,
-     * but resurrection is rare.
-     */
-    reclaim(refId: number): void;
-    /**
-     * Promote this tick's releases into the acquirable set. Called from
-     * `Encoder.discardChanges()` — never mid-encode.
-     */
-    flushReleases(): void;
-}

package/src/encoder/RefIdAllocator.ts

@@ -1,68 +0,0 @@
-/**
- * Allocates monotonically-increasing refIds with a reuse pool.
- *
- * `acquire()` pops from the free pool when available, otherwise bumps a
- * counter. `release()` queues a refId for reuse; the id doesn't become
- * acquirable until `flushReleases()` runs — the one-tick defer is what
- * lets the encoder guarantee a DELETE for the old instance reaches the
- * wire before the refId is handed to a new one.
- *
- * `reclaim()` handles "resurrection": a ref that was released but whose
- * JS instance is still alive can be re-added to the tree, in which case
- * the encoder must pull the refId back out of the pool before it's
- * handed to an unrelated instance.
- */
-export class RefIdAllocator {
-    protected nextUniqueId: number;
-
-    private _free: number[] = [];
-    private _pending: number[] = [];
-    private _pooled: Set<number> = new Set();
-
-    constructor(startRefId: number = 0) {
-        this.nextUniqueId = startRefId;
-    }
-
-    acquire(): number {
-        if (this._free.length > 0) {
-            const id = this._free.pop()!;
-            this._pooled.delete(id);
-            return id;
-        }
-        return this.nextUniqueId++;
-    }
-
-    release(refId: number): void {
-        this._pending.push(refId);
-        this._pooled.add(refId);
-    }
-
-    isPooled(refId: number): boolean {
-        return this._pooled.has(refId);
-    }
-
-    /**
-     * Remove a refId from the pool. Called when a ref whose refId was
-     * released is being resurrected. O(n) scan of the relevant array,
-     * but resurrection is rare.
-     */
-    reclaim(refId: number): void {
-        if (!this._pooled.delete(refId)) return;
-        let i = this._free.indexOf(refId);
-        if (i !== -1) { this._free.splice(i, 1); return; }
-        i = this._pending.indexOf(refId);
-        if (i !== -1) { this._pending.splice(i, 1); }
-    }
-
-    /**
-     * Promote this tick's releases into the acquirable set. Called from
-     * `Encoder.discardChanges()` — never mid-encode.
-     */
-    flushReleases(): void {
-        const pending = this._pending;
-        if (pending.length === 0) return;
-        const free = this._free;
-        for (let i = 0; i < pending.length; i++) free.push(pending[i]);
-        pending.length = 0;
-    }
-}