@colyseus/schema 5.0.6 → 5.0.9

package/build/index.cjs

@@ -59,6 +59,13 @@ const $decoder = "~decoder";
 const $filter = "~filter";
 const $getByIndex = "~getByIndex";
 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.
+ */
+const $resyncPrune = "~resyncPrune";
 /**
  * Used to hold ChangeTree instances whitin the structures.
  *
@@ -83,6 +90,14 @@ const $proxyTarget = Symbol.for("$proxyTarget");
  * (Discards changes for next serialization)
  */
 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().
+ */
+const $reset = "~reset";
 /**
  * When decoding, this method is called after the instance is fully decoded
  */
@@ -808,6 +823,92 @@ function streamDropView(s, viewId) {
     st.sentByView.delete(viewId);
 }
 
+const WIRE_BY_BITS = {
+    8: "uint8",
+    16: "uint16",
+    32: "uint32",
+};
+/** Validate options and precompute the wire codec + scale span. */
+function resolveQuantize(opts) {
+    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. */
+function isQuantizedType(type) {
+    return type !== null && typeof type === "object" && type.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).
+ */
+function quantize(desc, value) {
+    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. */
+function dequantize(desc, q) {
+    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.
+ */
+function makeQuantizedEncoder(desc) {
+    const writeWire = encode[desc.wire];
+    return (bytes, value, it) => writeWire(bytes, quantize(desc, value), it);
+}
+/** Decode a quantized field: read the unsigned-int wire value, then dequantize. */
+function decodeQuantized(desc, bytes, it) {
+    const readWire = decode[desc.wire];
+    return dequantize(desc, readWire(bytes, it));
+}
+
 class TypeContext {
     types = {};
     schemas = new Map();
@@ -910,6 +1011,11 @@ class TypeContext {
             if (typeof (fieldType) === "string") {
                 continue;
             }
+            // Quantized fields are scalar — their object `type` only carries the
+            // descriptor, there's no child Schema to discover.
+            if (isQuantizedType(fieldType)) {
+                continue;
+            }
             if (typeof (fieldType) === "function") {
                 this.discoverTypes(fieldType, klass, index, parentHasViewTag || fieldHasViewTag);
             }
@@ -978,6 +1084,14 @@ function getNormalizedType(type) {
     if (Array.isArray(type)) {
         return { array: getNormalizedType(type[0]) };
     }
+    else if (isQuantizedType(type)) {
+        // `{ quantized: ... }` — a scalar wire type, NOT a collection/ref. Resolve
+        // raw options (the `@type({quantized:{min,max}})` path) once; an already-
+        // resolved descriptor (the `t.quantized()` builder path) passes through.
+        return (typeof type.quantized.wire === "string")
+            ? type
+            : { quantized: resolveQuantize(type.quantized) };
+    }
     else if (typeof (type['type']) !== "undefined") {
         return type['type'];
     }
@@ -1056,8 +1170,9 @@ const Metadata = {
             enumerable: false,
             configurable: true,
         });
-        // if child Ref/complex type, add to -4
-        if (typeof (metadata[index].type) !== "string") {
+        // if child Ref/complex type, add to -4. Quantized fields are scalar (their
+        // `type` is an object only to carry the descriptor) — not refs, so skip them.
+        if (typeof (metadata[index].type) !== "string" && !isQuantizedType(metadata[index].type)) {
             if (metadata[$refTypeFieldIndexes] === undefined) {
                 Object.defineProperty(metadata, $refTypeFieldIndexes, {
                     value: [],
@@ -1119,10 +1234,25 @@ const Metadata = {
             });
         }
         metadata[$viewFieldIndexes].push(index);
-        if (!metadata[$fieldIndexesByViewTag][tag]) {
-            metadata[$fieldIndexesByViewTag][tag] = [];
+        // Populate $fieldIndexesByViewTag: for a bitmask tag, register the field
+        // index under each individual set bit so that view.add(obj, Tag.ONE) finds
+        // fields tagged @view(Tag.ONE|Tag.TWO).
+        // Negative tags (i.e. DEFAULT_VIEW_TAG = -1) are stored as-is.
+        if (tag < 0) {
+            if (!metadata[$fieldIndexesByViewTag][tag]) {
+                metadata[$fieldIndexesByViewTag][tag] = [];
+            }
+            metadata[$fieldIndexesByViewTag][tag].push(index);
+        }
+        else {
+            for (let bits = tag; bits > 0; bits &= bits - 1) {
+                const bit = bits & (-bits); // isolate lowest set bit
+                if (!metadata[$fieldIndexesByViewTag][bit]) {
+                    metadata[$fieldIndexesByViewTag][bit] = [];
+                }
+                metadata[$fieldIndexesByViewTag][bit].push(index);
+            }
         }
-        metadata[$fieldIndexesByViewTag][tag].push(index);
     },
     setUnreliable(metadata, fieldName) {
         const index = metadata[fieldName];
@@ -1228,8 +1358,8 @@ const Metadata = {
         if (metadata[$descriptors][fieldName]) {
             Object.defineProperty(target.prototype, fieldName, metadata[$descriptors][fieldName]);
         }
-        // Pre-compute encoder function for primitive types.
-        if (typeof normalized === "string") {
+        // Pre-compute encoder function for primitive + quantized types.
+        if (typeof normalized === "string" || isQuantizedType(normalized)) {
             if (!metadata[$encoders]) {
                 Object.defineProperty(metadata, $encoders, {
                     value: [],
@@ -1238,7 +1368,9 @@ const Metadata = {
                     writable: true,
                 });
             }
-            metadata[$encoders][fieldIndex] = encode[normalized];
+            metadata[$encoders][fieldIndex] = (typeof normalized === "string")
+                ? encode[normalized]
+                : makeQuantizedEncoder(normalized.quantized);
         }
     },
     setFields(target, fields) {
@@ -1884,6 +2016,8 @@ function forEachLiveWithCtx(tree, ctx, cb) {
     const ref = tree.refTarget;
     if (ref[$childType] !== undefined) {
         // Collection inheriting @transient from parent field: skip entirely.
+        // The resync sweep (decoder/Resync.ts) relies on this: a collection
+        // absent from full-sync output is never pruned client-side.
         if (tree.isTransient)
             return;
         // Collection types: dispatch by shape.
@@ -1913,6 +2047,8 @@ function forEachLiveWithCtx(tree, ctx, cb) {
         // Schema: walk declared fields. `null` is treated as absent —
         // the setter records a DELETE when a field is set to null or
         // undefined, so it should not appear in full-sync output.
+        // (@transient skips below matter to the resync sweep — see
+        // decoder/Resync.ts: absent-from-payload means never pruned.)
         //
         // Read names from the per-class descriptor's parallel array —
         // saves the `metadata[i]` (per-field obj) + `.name` chain on
@@ -2176,6 +2312,12 @@ function propagateNewChildToSubscribers(parentTree, childIndex, childRef, root)
     }
 }
 
+/**
+ * Tree-attachment helpers: setRoot / setParent + child-iteration recursion.
+ * Hot path: every new Schema/Collection instance attached to the root
+ * goes through here, which is why the recursive walk uses a hoisted
+ * callback + ctx-pool instead of per-call closures.
+ */
 function setRoot(tree, root) {
     tree.root = root;
     const isNewChangeTree = root.add(tree);
@@ -2228,30 +2370,10 @@ function setParent(tree, parent, root, parentIndex) {
     }
 }
 function forEachChild(tree, callback) {
-    //
-    // assign same parent on child structures
-    //
-    if (tree.ref[$childType]) {
-        if (typeof (tree.ref[$childType]) !== "string") {
-            // MapSchema / ArraySchema, etc.
-            for (const [key, value] of tree.ref.entries()) {
-                if (!value) {
-                    continue;
-                } // sparse arrays can have undefined values
-                callback(value[$changes], tree.ref._collectionIndexes?.[key] ?? key);
-            }
-        }
-    }
-    else {
-        const names = tree.encDescriptor.names;
-        for (const index of tree.metadata?.[$refTypeFieldIndexes] ?? []) {
-            const value = tree.ref[names[index]];
-            if (!value) {
-                continue;
-            }
-            callback(value[$changes], index);
-        }
-    }
+    forEachChildWithCtx(tree, callback, _forEachChildTrampoline);
+}
+function _forEachChildTrampoline(cb, change, at) {
+    cb(change, at);
 }
 /**
  * Closure-free variant of {@link forEachChild}. Hot setRoot / setParent
@@ -2270,12 +2392,35 @@ function forEachChildWithCtx(tree, ctx, callback) {
     const ref = tree.refTarget;
     if (ref[$childType]) {
         if (typeof ref[$childType] !== "string") {
-            const collectionIndexes = ref._collectionIndexes;
-            for (const [key, value] of ref.entries()) {
-                if (!value) {
-                    continue;
+            const items = ref.items;
+            if (items !== undefined) {
+                // ArraySchema (raw target): dense index loop — the previous
+                // `for..of entries()` allocated an iterator + a [key, value]
+                // pair array per child (top-10 allocation site in the
+                // stateview and deep-nested heap profiles).
+                for (let i = 0, len = items.length; i < len; i++) {
+                    const value = items[i];
+                    if (!value) {
+                        continue;
+                    } // sparse arrays can have undefined values
+                    callback(ctx, value[$changes], i);
+                }
+            }
+            else {
+                // Map-backed collections (MapSchema/SetSchema/CollectionSchema/
+                // StreamSchema all store `$items: Map`): keys() loop skips the
+                // per-child [key, value] pair arrays of entries(), with no
+                // closure either (a forEach closure showed up as a GC
+                // regression on the construct bench).
+                const $items = ref.$items;
+                const collectionIndexes = ref._collectionIndexes;
+                for (const key of $items.keys()) {
+                    const value = $items.get(key);
+                    if (!value) {
+                        continue;
+                    }
+                    callback(ctx, value[$changes], collectionIndexes?.[key] ?? key);
                 }
-                callback(ctx, value[$changes], collectionIndexes?.[key] ?? key);
             }
         }
     }
@@ -2360,6 +2505,12 @@ const IS_UNRELIABLE = 8, IS_TRANSIENT = 16, IS_STATIC = 32;
 // `t.map(X).stream()` / `t.set(X).stream()` route through the same
 // emission machinery.
 const IS_STREAM_COLLECTION = 64;
+// Set by `recycle()` (Schema.reset / pooling): the tree's values are live
+// but its dirty buckets were cleared, so `Root.add` must re-stage every
+// populated field as ADD when the instance re-enters a tree. Without this,
+// only fields assigned after `pool.acquire()` would reach the wire — the
+// retained ones (constructor-initialized children) would never be encoded.
+const NEEDS_RESTAGE = 128;
 /**
  * Flags a child inherits from its parent's own transitive state via
  * `checkInheritedFlags`. Read as a bitwise mask so the inheritance step
@@ -2472,6 +2623,8 @@ class ChangeTree {
     set isStatic(v) { this.flags = v ? (this.flags | IS_STATIC) : (this.flags & ~IS_STATIC); }
     get isStreamCollection() { return (this.flags & IS_STREAM_COLLECTION) !== 0; }
     set isStreamCollection(v) { this.flags = v ? (this.flags | IS_STREAM_COLLECTION) : (this.flags & ~IS_STREAM_COLLECTION); }
+    get needsRestage() { return (this.flags & NEEDS_RESTAGE) !== 0; }
+    set needsRestage(v) { this.flags = v ? (this.flags | NEEDS_RESTAGE) : (this.flags & ~NEEDS_RESTAGE); }
     // True iff tree inherits `isFiltered` OR its Schema class declares any
     // @view-tagged fields. StateView.addParentOf uses this to decide whether
     // a parent must be included in a view's bootstrap. Reads the class-level
@@ -2755,6 +2908,48 @@ class ChangeTree {
         if (this.collPureOps !== undefined)
             this.collPureOps.length = 0;
     }
+    /**
+     * Full reset to construction defaults so the owning ref can be returned to
+     * a pool and reused for a different logical entity (see encoder/Pool.ts +
+     * Schema.reset). Unlike `reset()` / `endEncode()` (which only clear the
+     * dirty bucket for the next encode), this also drops parent links, queue
+     * nodes and per-view bitmaps, and re-arms IS_NEW.
+     *
+     * Precondition: the tree must already be detached from the encoder
+     * (`root === undefined`) — i.e. the ref was removed from its parent
+     * collection/field, which `Root.remove` does before this runs.
+     */
+    recycle() {
+        if (this.root !== undefined) {
+            throw new Error(`@colyseus/schema: cannot recycle an attached ChangeTree ` +
+                `(${this.ref?.constructor?.name}). Remove the instance from its ` +
+                `parent collection before releasing it to a pool.`);
+        }
+        // dirty/ops buckets (Schema: dirtyLow/High + ops; Collection: collDirty/collPureOps)
+        this.reset();
+        // keep the recorder object allocated (re-alloc is the cost we avoid), clear contents
+        this.unreliableRecorder?.reset();
+        // back to a freshly-constructed tree: IS_NEW, no inherited flags
+        // (FILTERED/TRANSIENT/STATIC/STREAM are re-derived on the next setParent).
+        // NEEDS_RESTAGE makes the next Root.add re-stage retained field values.
+        this.flags = IS_NEW | NEEDS_RESTAGE;
+        this._fullSyncGen = 0;
+        // drop parent links — Root.remove clears `root` and the CHILDREN's
+        // parent links, but leaves this tree's own parentRef dangling.
+        this.parentRef = undefined;
+        this._parentIndex = undefined;
+        this.extraParents = undefined;
+        // queue nodes (already nulled by Root.remove's queue removal; defensive)
+        this.changesNode = undefined;
+        this.unreliableChangesNode = undefined;
+        this.paused = false;
+        // per-view visibility lives on the tree (NOT keyed by refId), so a
+        // recycled tree must not inherit its previous life's view membership.
+        this.visibleViews = undefined;
+        this.invisibleViews = undefined;
+        this.tagViews = undefined;
+        this.subscribedViews = undefined;
+    }
     shift(shiftIndex) {
         if (this._isSchema)
             throw new Error("ChangeTree (Schema): shift is not supported");
@@ -3210,6 +3405,165 @@ const encodeArray = function (encoder, bytes, changeTree, field, operation, it,
     encodeValue(encoder, bytes, type, value, operation, it);
 };
 
+/**
+ * Resync ("full-snapshot reconciliation") support for {@link Decoder.decodeResync}.
+ *
+ * A rejoin snapshot is authoritative for everything it contains — but the
+ * plain decode path is additive: entries deleted (or hidden by a view)
+ * while the client was off the wire survive as ghosts. This module owns the
+ * generic reconciliation algorithm:
+ *
+ * - during the decode walk, the collection DecodeOperation functions report
+ *   every entry the payload touches ({@link resyncRecordVisit}) and every
+ *   collection that appears at all ({@link resyncMarkPresent});
+ * - after the walk, {@link resyncSweep} removes whatever was never reported,
+ *   through the same DELETE bookkeeping the regular decode path uses
+ *   (DataChange DELETE → onRemove; removeRef → GC).
+ *
+ * Storage-specific pruning (journal upkeep, array compaction, stream
+ * exemption) lives on each collection class as `[$resyncPrune]` — declared
+ * on the `Collection` interface, so every collection kind must state its
+ * own sweep semantics.
+ *
+ * All entry points are guarded by `decoder.resyncVisited !== null` at the
+ * call sites — the normal decode path never pays for any of this.
+ */
+/**
+ * Record that the current structure's entry at `identity` (map string key /
+ * element index) appeared in the payload — even when its value is unchanged
+ * (`allChanges` cannot serve as this record: its pushes are guarded by
+ * `previousValue !== value`, so unchanged entries would look unvisited).
+ *
+ * Also releases a replaced occupant: full-sync emits plain ADD (never
+ * DELETE_AND_ADD), so an entry whose instance changed while this client was
+ * off the wire would otherwise leak its previous ref (no onRemove, never
+ * GC'd). This release is correct ONLY under a full snapshot — a live patch's
+ * plain ADD over a different instance can be a positional rewrite (array
+ * shift/unshift) where the occupant *moved* and is still alive; a snapshot
+ * re-adds moved instances elsewhere, so the refcounts balance.
+ */
+function resyncTouchEntry(decoder, ref, operation, identity, previousValue, value, allChanges) {
+    const visited = decoder.resyncVisited;
+    let set = visited.get(decoder.currentRefId);
+    if (set === undefined) {
+        visited.set(decoder.currentRefId, set = new Set());
+    }
+    set.add(identity);
+    if (previousValue !== undefined && operation === exports.OPERATION.ADD && previousValue !== value) {
+        const previousRefId = previousValue[$refId];
+        if (previousRefId !== undefined) {
+            decoder.root.removeRef(previousRefId);
+            allChanges?.push({
+                ref,
+                refId: decoder.currentRefId,
+                op: exports.OPERATION.DELETE,
+                dynamicIndex: identity,
+                value: undefined,
+                previousValue,
+            });
+        }
+    }
+}
+/**
+ * Mark a collection as present in the payload — even with zero entries.
+ * The sweep only prunes collections reported here: absence means "not part
+ * of full-sync" (@transient, view-invisible), where pruning would destroy
+ * live data. Reflected clients have no @transient metadata, so payload
+ * presence is the only reliable signal.
+ */
+function resyncMarkPresent(decoder, refId) {
+    const visited = decoder.resyncVisited;
+    if (!visited.has(refId)) {
+        visited.set(refId, new Set());
+    }
+}
+/**
+ * Post-decode phase of {@link Decoder.decodeResync}: remove every collection
+ * entry the snapshot did not visit.
+ *
+ * Walks the tree from the root — NOT `root.refs` — for three reasons:
+ * `@transient` fields are never part of a snapshot and must be left alone;
+ * entries of subtrees removed by the sweep itself are left to the GC's
+ * transitive walk (sweeping them directly would double-decrement shared
+ * children); and collections the snapshot never mentions (emptied
+ * server-side) are still reachable and get pruned.
+ */
+function resyncSweep(decoder, allChanges) {
+    if (decoder.resyncDamaged) {
+        console.warn("@colyseus/schema: resync sweep skipped — parts of the payload could not be decoded. " +
+            "Stale entries may persist until the next resync.");
+        return;
+    }
+    sweepSchema(decoder, decoder.state, new Set(), allChanges);
+}
+function sweepSchema(decoder, ref, seen, allChanges) {
+    const refId = ref[$refId];
+    if (refId === undefined || seen.has(refId)) {
+        return;
+    }
+    seen.add(refId);
+    const metadata = ref.constructor[Symbol.metadata];
+    const refIndexes = metadata?.[$refTypeFieldIndexes];
+    if (refIndexes === undefined) {
+        return;
+    }
+    const transient = metadata[$transientFieldIndexes];
+    for (let i = 0; i < refIndexes.length; i++) {
+        const fieldIndex = refIndexes[i];
+        // @transient fields are never in a snapshot — leave them alone.
+        if (transient !== undefined && transient.includes(fieldIndex)) {
+            continue;
+        }
+        const field = metadata[fieldIndex];
+        const value = ref[field.name];
+        if (!value) {
+            continue;
+        }
+        if (Schema.is(field.type)) {
+            sweepSchema(decoder, value, seen, allChanges);
+        }
+        else {
+            sweepCollection(decoder, value, seen, allChanges);
+        }
+    }
+}
+function sweepCollection(decoder, coll, seen, allChanges) {
+    const tgt = coll[$proxyTarget] ?? coll;
+    const refId = tgt[$refId];
+    if (refId === undefined || seen.has(refId)) {
+        return;
+    }
+    seen.add(refId);
+    // `undefined` = the collection never appeared in the payload at all
+    // (not even as its parent's field op) — it is not part of full-sync
+    // (@transient, view-invisible) and must be left alone. An empty Set
+    // means "present with zero entries" → prune everything.
+    const visited = decoder.resyncVisited.get(refId);
+    if (visited === undefined) {
+        return;
+    }
+    const $root = decoder.root;
+    tgt[$resyncPrune](visited, (value, identity) => {
+        allChanges?.push({
+            ref: coll,
+            refId,
+            op: exports.OPERATION.DELETE,
+            dynamicIndex: identity,
+            value: undefined,
+            previousValue: value,
+        });
+        const childRefId = value?.[$refId];
+        if (childRefId !== undefined) {
+            $root.removeRef(childRefId);
+        }
+    }, (value) => {
+        // recurse so nested collections of retained entries sweep too
+        if (Schema.isSchema(value)) {
+            sweepSchema(decoder, value, seen, allChanges);
+        }
+    });
+}
+
 const DEFINITION_MISMATCH = -1;
 /**
  * Collection-kind discriminator declared on each collection class as
@@ -3267,6 +3621,12 @@ function decodeValue(decoder, operation, ref, index, previousValue, type, bytes,
         //
         value = decode[type](bytes, it);
     }
+    else if (isQuantizedType(type)) {
+        // Quantized scalar: read the unsigned-int wire value, then dequantize so
+        // the instance holds (and yields) the wire-exact float — `decodeSchema-
+        // Operation` writes it through the snapping setter (idempotent here).
+        value = decodeQuantized(type.quantized, bytes, it);
+    }
     else if (Schema.is(type)) {
         const refId = decode.number(bytes, it);
         value = $root.refs.get(refId);
@@ -3283,6 +3643,10 @@ function decodeValue(decoder, operation, ref, index, previousValue, type, bytes,
     else {
         const typeDef = getType(Object.keys(type)[0]);
         const refId = decode.number(bytes, it);
+        // resync bookkeeping — see Resync.ts
+        if (decoder.resyncVisited !== null) {
+            resyncMarkPresent(decoder, refId);
+        }
         // `initializeForDecoder` is a static on every registered collection
         // class — it does `Object.create(Class.prototype)` + the class-
         // field init + assigns an untracked `$changes` directly. Keeps
@@ -3295,17 +3659,25 @@ function decodeValue(decoder, operation, ref, index, previousValue, type, bytes,
         if (previousValue) {
             let previousRefId = previousValue[$refId];
             if (previousRefId !== undefined && refId !== previousRefId) {
+                // Collection field replaced by a different instance.
                 //
-                // enqueue onRemove if structure has been replaced.
-                //
+                // Don't decrement children here: GC (`garbageCollectDeletedRefs`)
+                // removes them once the previous collection's refId hits zero.
+                // Doing it here too would double-decrement a *shared* child and
+                // drop it while still referenced ("refId not found").
+                if ((operation & exports.OPERATION.DELETE) !== exports.OPERATION.DELETE) {
+                    // Replacement not tagged DELETE (e.g. pending ADD not upgraded
+                    // to DELETE_AND_ADD), so the previous refId wasn't decremented
+                    // above. Release it here, else it never gets GC'd (leak).
+                    $root.removeRef(previousRefId);
+                }
+                // enqueue onRemove callbacks for the previous collection's children.
                 const entries = previousValue.entries();
                 let iter;
                 while ((iter = entries.next()) && !iter.done) {
                     const [key, value] = iter.value;
-                    // if value is a schema, remove its reference
                     if (typeof (value) === "object") {
                         previousRefId = value[$refId];
-                        $root.removeRef(previousRefId);
                     }
                     allChanges?.push({
                         ref: previousValue,
@@ -3397,6 +3769,10 @@ const decodeKeyValueOperation = function (decoder, bytes, it, ref, allChanges) {
     }
     const previousValue = tgt[$getByIndex](index);
     const value = decodeValue(decoder, operation, ref, index, previousValue, type, bytes, it, allChanges);
+    // resync bookkeeping — see Resync.ts
+    if (decoder.resyncVisited !== null) {
+        resyncTouchEntry(decoder, ref, operation, dynamicIndex, previousValue, value, allChanges);
+    }
     if (value !== null && value !== undefined) {
         switch (kind) {
             case CollectionKind.Map:
@@ -3473,6 +3849,16 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
         // TODO: refactor here, try to follow same flow as below
         const refId = decode.number(bytes, it);
         const previousValue = decoder.root.refs.get(refId);
+        // Decrement the removed child's ref-count so it can be garbage
+        // collected — this refId-based branch returns early and never reaches
+        // decodeValue(), so it must do the same DELETE bookkeeping itself.
+        // Without this the refId leaks; a later encoder reuse then aliases a
+        // different type → "field not defined" / "definition mismatch"
+        // (surfaces under StateView when a filtered ArraySchema element is
+        // spliced while its parent moves through view membership churn).
+        if (previousValue !== undefined) {
+            decoder.root.removeRef(refId);
+        }
         index = tgt.findIndex((value) => value === previousValue);
         tgt[$deleteByIndex](index);
         allChanges?.push({
@@ -3507,6 +3893,12 @@ const decodeArray = function (decoder, bytes, it, ref, allChanges) {
     // maintain). The decoder's authoritative state is `items`.
     const previousValue = tgt.items[index];
     const value = decodeValue(decoder, operation, ref, index, previousValue, type, bytes, it, allChanges);
+    // resync bookkeeping — see Resync.ts. `index` is the RESOLVED position
+    // (ADD_BY_REFID lands on the instance's current client-side index), so
+    // visited entries form a sparse set.
+    if (decoder.resyncVisited !== null) {
+        resyncTouchEntry(decoder, ref, operation, index, previousValue, value, allChanges);
+    }
     if (value !== null && value !== undefined &&
         value !== previousValue // avoid setting same value twice (if index === 0 it will result in a "unshift" for ArraySchema)
     ) {
@@ -3632,6 +4024,8 @@ class ArraySchema {
     tmpItems = [];
     deletedIndexes = [];
     isMovingItems = false;
+    /** Decode-side: `items` has holes (delete or gap-write) — `$onDecodeEnd` must compact. */
+    _needsCompaction = false;
     static [$encoder] = encodeArray;
     static [$decoder] = decodeArray;
     /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
@@ -3646,9 +4040,11 @@ class ArraySchema {
      * - Then, the encoder iterates over all "owned" properties per instance and encodes them.
      */
     static [$filter](ref, index, view) {
-        return (!view ||
-            typeof (ref[$childType]) === "string" ||
-            view.isChangeTreeVisible(ref['tmpItems'][index]?.[$changes]));
+        if (!view)
+            return true; // must stay first — encodeAll hits this per element
+        const self = ref[$proxyTarget] ?? ref; // ref arrives proxied — skip traps below
+        return (typeof (self[$childType]) === "string" ||
+            view.isChangeTreeVisible(self['tmpItems'][index]?.[$changes]));
     }
     static is(type) {
         return (
@@ -3692,6 +4088,7 @@ class ArraySchema {
         // 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;
         const proxy = new Proxy(self, ARRAY_PROXY_HANDLER);
@@ -3819,6 +4216,9 @@ class ArraySchema {
             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;
         }
     }
@@ -3839,6 +4239,27 @@ class ArraySchema {
         self.items.length = 0;
         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]?.[$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.
@@ -4238,21 +4659,51 @@ class ArraySchema {
      * `$deleteByIndex` below.
      */
     [$getByIndex](index, isEncodeAll = false) {
+        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) {
-        this.items[index] = undefined;
+        const self = this[$proxyTarget] ?? this;
+        self.items[index] = undefined;
+        self._needsCompaction = true;
     }
     [$onEncodeEnd]() {
-        this.tmpItems = this.items.slice();
-        this.deletedIndexes.length = 0;
+        const self = this[$proxyTarget] ?? this;
+        self.tmpItems = self.items.slice();
+        self.deletedIndexes.length = 0;
     }
     [$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, prune, keep) {
+        // `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() {
         return this.items.slice(0);
@@ -4619,6 +5070,24 @@ class MapSchema {
         this.$items.clear();
         changeTree.operation(exports.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) => value?.[$reset]?.());
+        this.$items.clear();
+        this.journal.reset();
+        changeTree.recycle();
+        this[$refId] = undefined; // assign (not delete) to avoid V8 dictionary-mode deopt
+    }
     has(key) {
         return this.$items.has(key);
     }
@@ -4659,6 +5128,36 @@ class MapSchema {
             this.journal.keyByIndex.delete(index);
         }
     }
+    [$resyncPrune](visited, prune, keep) {
+        // maps prune by string key, NOT wire index — the decoder-side
+        // journal never evicts stale index→key mappings on re-indexing.
+        let deletedKeys = 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);
+                delete this.journal.indexByKey[key];
+            });
+            // drop index→key mappings of swept keys — including stale ones
+            // left behind by re-indexing.
+            const staleIndexes = [];
+            this.journal.keyByIndex.forEach((key, index) => {
+                if (deletedKeys.has(key)) {
+                    staleIndexes.push(index);
+                }
+            });
+            for (let i = 0; i < staleIndexes.length; i++) {
+                this.journal.keyByIndex.delete(staleIndexes[i]);
+            }
+        }
+    }
     [$onEncodeEnd]() {
         this.journal.cleanupAfterEncode();
     }
@@ -4851,6 +5350,24 @@ class CollectionSchema {
         this.$items.clear();
         changeTree.operation(exports.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) => 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) {
         return Array.from(this.$items.values()).some((v) => v === value);
     }
@@ -4889,6 +5406,22 @@ class CollectionSchema {
     [$deleteByIndex](index) {
         this.$items.delete(index);
     }
+    [$resyncPrune](visited, prune, keep) {
+        let toDelete = 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]);
+            }
+        }
+    }
     [$onEncodeEnd]() {
         for (const key in this.deletedItems) {
             delete this.deletedItems[key];
@@ -5090,6 +5623,24 @@ class SetSchema {
         this.$items.clear();
         changeTree.operation(exports.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) => 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) {
         const values = this.$items.values();
         let has = false;
@@ -5140,6 +5691,22 @@ class SetSchema {
     [$deleteByIndex](index) {
         this.$items.delete(index);
     }
+    [$resyncPrune](visited, prune, keep) {
+        let toDelete = 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]);
+            }
+        }
+    }
     [$onEncodeEnd]() {
         for (const key in this.deletedItems) {
             delete this.deletedItems[key];
@@ -5401,6 +5968,11 @@ class StreamSchema {
             this.$items.delete(index);
         }
     }
+    [$resyncPrune]() {
+        // 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.
+    }
     [$onEncodeEnd]() {
         // No per-tick cleanup: pending/sent state spans encode ticks by design.
     }
@@ -5481,7 +6053,22 @@ class FieldBuilder {
     constructor(type) {
         this._type = type;
     }
-    /** Provide a default value for this field. */
+    /**
+     * Provide a default value for this field.
+     *
+     * Pass a **factory function** `() => T` to build a FRESH value per instance
+     * (invoked once per construction) instead of sharing a single default — the
+     * clean way to default a ref to a plain custom class, or any field that must
+     * not share a mutable default across instances:
+     *
+     * ```ts
+     * acc: t.ref(GunAccuracy).noSync().default(() => new GunAccuracy()),
+     * ```
+     *
+     * Schema fields are never function-typed, so a function is always treated as a
+     * factory. A non-function value is shared (and cloned per instance if it is
+     * clone-able, e.g. a Schema/collection).
+     */
     default(value) {
         this._default = value;
         this._hasDefault = true;
@@ -5652,6 +6239,20 @@ const streamFactory = ((child) => {
     return b;
 });
 const refFactory = ((ctor) => new FieldBuilder(ctor));
+/**
+ * A bounded float carried on the wire as a fixed-width unsigned integer. App code
+ * reads/writes the FLOAT; the wire carries the quantized int and the field only
+ * ever yields `dequant(q)`, so client predict and server sim read the same value
+ * (no full-precision path to leak ⇒ no shot misprediction). See
+ * {@link QuantizeOptions} for the precision/wire trade-offs.
+ *
+ *     yaw:      t.quantized({ min: 0, max: TWO_PI, mode: "wrap" }), // 16-bit
+ *     pitch:    t.quantized({ min: -PITCH_LIMIT, max: PITCH_LIMIT }), // clamp (default)
+ *     throttle: t.quantized({ min: 0, max: 1, bits: 8 }),           // 1 byte
+ */
+function quantizedFactory(opts) {
+    return new FieldBuilder({ quantized: resolveQuantize(opts) });
+}
 const t = Object.freeze({
     // Primitives
     string: primitive("string"),
@@ -5669,16 +6270,46 @@ const t = Object.freeze({
     float64: primitive("float64"),
     bigint64: primitive("bigint64"),
     biguint64: primitive("biguint64"),
-    /** Reference to a Schema subtype. `t.array(Item)` usually reads better, but this is available when a plain ref is needed. */
+    /**
+     * Reference to a Schema subtype — `t.array(Item)` usually reads better, but
+     * this is available when a plain ref is needed.
+     *
+     * The target may also be a **non-Schema custom class**. A synced ref still
+     * requires it to be encodable — a `Schema` subclass, or a class retrofitted
+     * with `Metadata.setFields(...)` (both carry `[Symbol.metadata]`); a bare
+     * custom class is rejected at `schema()` time. A `.noSync()` (local-only)
+     * field accepts ANY zero-arg class and auto-instantiates one per parent.
+     */
     ref: refFactory,
     array: arrayFactory,
     map: mapFactory,
     set: setFactory,
     collection: collectionFactory,
     stream: streamFactory,
+    /**
+     * A bounded float quantized to a fixed-width unsigned int on the wire — half
+     * (or a quarter) the bytes of a `float32` at a precision you pick. The field
+     * reads/writes the float and only ever yields `dequant(q)`. {@see QuantizeOptions}
+     */
+    quantized: quantizedFactory,
+    /**
+     * Sugar for a full-circle wrapping angle in radians:
+     * `t.quantized({ min: 0, max: 2π, mode: "wrap", bits })` (default 16-bit,
+     * ~0.0055°/step). Any input angle is range-reduced into `[0, 2π)`. Render note:
+     * lerp interpolated remotes shortest-arc (`attach({ angle: true })`) — the
+     * wrap fixes the WIRE seam, not interpolation (see {@link QuantizeOptions.mode}).
+     */
+    angle: (opts) => quantizedFactory({ min: 0, max: Math.PI * 2, mode: "wrap", bits: opts?.bits ?? 16 }),
 });
 
 const DEFAULT_VIEW_TAG = -1;
+/**
+ * Class decorator that registers a `@type`-style Schema class with the
+ * TypeContext (required for reflection / cross-language codegen).
+ *
+ *     @entity
+ *     class Player extends Schema { ... }
+ */
 function entity(constructor) {
     TypeContext.register(constructor);
     return constructor;
@@ -5910,8 +6541,8 @@ function type(type, options) {
         if (metadata[$descriptors][field]) {
             Object.defineProperty(target, field, metadata[$descriptors][field]);
         }
-        // Pre-compute encoder function for primitive types.
-        if (typeof type === "string") {
+        // Pre-compute encoder function for primitive + quantized types.
+        if (typeof type === "string" || isQuantizedType(type)) {
             if (!metadata[$encoders]) {
                 Object.defineProperty(metadata, $encoders, {
                     value: [],
@@ -5920,7 +6551,9 @@ function type(type, options) {
                     writable: true,
                 });
             }
-            metadata[$encoders][fieldIndex] = encode[type];
+            metadata[$encoders][fieldIndex] = (typeof type === "string")
+                ? encode[type]
+                : makeQuantizedEncoder(type.quantized);
         }
     };
 }
@@ -6031,6 +6664,38 @@ function makeCollectionSetter(_fieldName, fieldIndex, type, complexTypeKlass) {
         values[fieldIndex] = value;
     };
 }
+/**
+ * Setter for a `t.quantized()` field. SNAPS the assigned float to the wire-exact
+ * value (`dequant(quant(x))`) on write, so the stored value — and every read,
+ * including the reconciler's live step off the staged input — is identical to
+ * what the server decodes off the wire. This is the half that kills the
+ * predict-from-the-wrong-value footgun; the encoder re-quantizes the snapped
+ * value at send (a lossless round-trip). Change tracking keys on the SNAPPED
+ * value, so a sub-step jitter that quantizes to the same integer emits no delta.
+ */
+function makeQuantizedSetter(fieldName, fieldIndex, desc) {
+    return function (value) {
+        const values = this[$values];
+        const previousValue = values[fieldIndex];
+        if (value !== undefined && value !== null) {
+            if (typeof value !== "number") {
+                throw new EncodeSchemaError(`a 'number' was expected, but '${JSON.stringify(value)}' was provided in ${this.constructor.name}#${fieldName}`);
+            }
+            value = dequantize(desc, quantize(desc, value)); // snap to wire-exact
+            if (value === previousValue)
+                return;
+            this.constructor[$track](this[$changes], fieldIndex, exports.OPERATION.ADD);
+        }
+        else {
+            if (value === previousValue)
+                return; // undefined === undefined
+            if (previousValue !== undefined && previousValue !== null) {
+                this[$changes].delete(fieldIndex);
+            }
+        }
+        values[fieldIndex] = value;
+    };
+}
 function getPropertyDescriptor(fieldName, fieldIndex, type, complexTypeKlass) {
     let setter;
     if (complexTypeKlass) {
@@ -6039,10 +6704,15 @@ function getPropertyDescriptor(fieldName, fieldIndex, type, complexTypeKlass) {
     else if (typeof type === "string") {
         setter = makePrimitiveSetter(fieldName, fieldIndex, type);
     }
+    else if (isQuantizedType(type)) {
+        setter = makeQuantizedSetter(fieldName, fieldIndex, type.quantized);
+    }
     else {
         setter = makeSchemaRefSetter(fieldName, fieldIndex, type);
     }
     return {
+        // Quantized stores the already-snapped float, so the getter is the plain
+        // $values read — the field yields dequant(q) with no per-read math.
         get: function () { return this[$values][fieldIndex]; },
         set: setter,
         enumerable: true,
@@ -6077,32 +6747,51 @@ function deprecated(throws = true) {
         });
     };
 }
+let defineTypesWarned = false;
+/**
+ * Adds synchronizable fields to an existing `Schema` subclass — the pre-5.0
+ * helper for plain JavaScript users.
+ *
+ * @deprecated Use `schema()` with `t.*` field builders instead:
+ * https://docs.colyseus.io/state/schema
+ */
+function defineTypes(target, fields, options) {
+    if (!defineTypesWarned) {
+        defineTypesWarned = true;
+        console.warn("@colyseus/schema: defineTypes() is deprecated and will be removed in a future release. Use schema() with t.* field builders instead → https://docs.colyseus.io/state/schema");
+    }
+    for (let field in fields) {
+        type(fields[field], options)(target.prototype, field);
+    }
+    return target;
+}
 /**
- * Produce the auto-instantiated construction default for a builder type
- * (empty collection or zero-arg Schema ref), or `undefined` when the type
- * has no auto-default. Shared by synced and `.noSync()` field handling.
+ * Build a per-construction factory for a builder type's auto-instantiated
+ * default (empty collection or zero-arg Schema ref), or `undefined` when the
+ * type has no auto-default. Returning a factory lets each construction `new` a
+ * fresh value directly instead of cloning a shared prototype instance.
  */
-function autoInstantiateDefault(rawType) {
+function makeAutoDefaultFactory(rawType) {
     if (rawType && typeof rawType === "object") {
         if (rawType.array !== undefined) {
-            return new ArraySchema();
+            return () => new ArraySchema();
         }
         if (rawType.map !== undefined) {
-            return new MapSchema();
+            return () => new MapSchema();
         }
         if (rawType.set !== undefined) {
-            return new SetSchema();
+            return () => new SetSchema();
         }
         if (rawType.collection !== undefined) {
-            return new CollectionSchema();
+            return () => new CollectionSchema();
         }
         if (rawType.stream !== undefined) {
-            return new StreamSchema();
+            return () => new StreamSchema();
         }
     }
     else if (typeof rawType === "function" && Schema.is(rawType)) {
         if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
-            return new rawType();
+            return () => new rawType();
         }
     }
     return undefined;
@@ -6129,7 +6818,39 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
     }
     const fields = {};
     const methods = {};
+    // Two buckets, both keyed by field name and applied at construction:
+    //  - `defaultValues`: static values copied as-is (shared reference).
+    //  - `defaultFactories`: invoked per construction for a fresh value —
+    //    `.default(fn)`, clone-able defaults, and auto-instantiated collections/refs.
     const defaultValues = {};
+    const defaultFactories = {};
+    // Decide once (at definition time) how each `.default(v)` materializes per
+    // construction: a function is a factory; a clone-able value clones fresh;
+    // anything else is a shared static value.
+    const assignDefault = (field, value) => {
+        if (typeof value === "function") {
+            defaultFactories[field] = value;
+        }
+        else if (value && typeof value.clone === "function") {
+            defaultFactories[field] = () => value.clone();
+        }
+        else {
+            defaultValues[field] = value;
+        }
+    };
+    // Seed a field's construction default: explicit `.default(v)`, else the
+    // auto-instantiated empty collection / zero-arg ref (skipped for `.optional()`).
+    const seedDefault = (field, def) => {
+        if (def.hasDefault) {
+            assignDefault(field, def.default);
+        }
+        else if (!def.optional) {
+            const factory = makeAutoDefaultFactory(def.type);
+            if (factory) {
+                defaultFactories[field] = factory;
+            }
+        }
+    };
     const viewTagFields = {};
     const ownedFields = [];
     const unreliableFields = [];
@@ -6153,18 +6874,16 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
                         `together with a sync-only modifier (.view/.owned/.unreliable/.transient/.static/.stream). ` +
                         `A local-only field cannot be synchronized.`);
                 }
-                if (def.hasDefault) {
-                    defaultValues[fieldName] = def.default;
-                }
-                else if (!def.optional) {
-                    const autoDefault = autoInstantiateDefault(def.type);
-                    if (autoDefault !== undefined) {
-                        defaultValues[fieldName] = autoDefault;
-                    }
-                }
+                seedDefault(fieldName, def);
                 continue;
             }
-            fields[fieldName] = getNormalizedType(def.type);
+            const normalizedType = getNormalizedType(def.type);
+            // A synced ref must be encodable (a Schema, or Metadata.setFields()'d) — reject a bare class.
+            if (typeof normalizedType === "function" && !Schema.is(normalizedType)) {
+                throw new Error(`schema(${name ? `'${name}'` : ""}): field '${fieldName}' is a synced ref to non-Schema ` +
+                    `class '${normalizedType.name || "(anonymous)"}' — use .noSync(), or Metadata.setFields().`);
+            }
+            fields[fieldName] = normalizedType;
             if (def.view !== undefined) {
                 viewTagFields[fieldName] = def.view;
             }
@@ -6192,24 +6911,14 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
             if (def.optional) {
                 optionalFields.push(fieldName);
             }
-            if (def.hasDefault) {
-                defaultValues[fieldName] = def.default;
-            }
-            else if (!def.optional) {
-                // Auto-instantiate collection/Schema defaults when none is provided.
-                // `.optional()` opts out — field starts as undefined.
-                const autoDefault = autoInstantiateDefault(def.type);
-                if (autoDefault !== undefined) {
-                    defaultValues[fieldName] = autoDefault;
-                }
-            }
+            seedDefault(fieldName, def);
         }
         else if (typeof value === "function") {
             if (Schema.is(value)) {
                 // Convenience: allow a bare Schema subclass (equivalent to `t.ref(Class)`).
                 fields[fieldName] = getNormalizedType(value);
                 if (!value.prototype.initialize || value.prototype.initialize.length === 0) {
-                    defaultValues[fieldName] = new value();
+                    defaultFactories[fieldName] = () => new value();
                 }
             }
             else {
@@ -6221,17 +6930,19 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
                 `Schema subclass, or method (got ${typeof value}).`);
         }
     }
-    const getDefaultValues = () => {
-        const defaults = {};
+    // Write construction defaults onto `target` — either the instance directly
+    // (no-args fast path) or a throwaway object that gets merged with props.
+    const applyDefaults = (target) => {
         for (const fieldName in defaultValues) {
-            const defaultValue = defaultValues[fieldName];
-            if (defaultValue && typeof defaultValue.clone === "function") {
-                defaults[fieldName] = defaultValue.clone();
-            }
-            else {
-                defaults[fieldName] = defaultValue;
-            }
+            target[fieldName] = defaultValues[fieldName];
         }
+        for (const fieldName in defaultFactories) {
+            target[fieldName] = defaultFactories[fieldName]();
+        }
+    };
+    const getDefaultValues = () => {
+        const defaults = {};
+        applyDefaults(defaults);
         return defaults;
     };
     const getParentProps = (props) => {
@@ -6244,18 +6955,26 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
         }
         return parentProps;
     };
+    const hasInitialize = typeof methods.initialize === "function";
     /** @codegen-ignore */
     const klass = Metadata.setFields(class extends inherits {
         constructor(...args) {
-            if (methods.initialize && typeof methods.initialize === "function") {
-                super(Object.assign({}, getDefaultValues(), getParentProps(args[0] || {})));
-                // Only call initialize() on the exact target class, not parents.
-                if (new.target === klass) {
-                    methods.initialize.apply(this, args);
-                }
+            const props = args[0];
+            if (props === undefined) {
+                // No-args: write defaults straight onto the instance — skips the
+                // throwaway defaults object + Object.assign + assignProps walk.
+                super();
+                applyDefaults(this);
             }
             else {
-                super(Object.assign({}, getDefaultValues(), args[0] || {}));
+                // With props: merge into the fresh defaults object in place (no
+                // extra `{}` target); the super chain runs assignProps once. An
+                // `initialize()` owns the schema fields, so only parent props flow up.
+                super(Object.assign(getDefaultValues(), hasInitialize ? getParentProps(props) : props));
+            }
+            // Only call initialize() on the exact target class, not parents.
+            if (hasInitialize && new.target === klass) {
+                methods.initialize.apply(this, args);
             }
         }
     }, fields);
@@ -6382,6 +7101,60 @@ class Schema {
         inst[$values] = [];
         return inst;
     }
+    /**
+     * Reset a DETACHED instance to construction defaults so it can be returned
+     * to a {@link SchemaPool} and reused, avoiding the cost of `new`. Recurses
+     * into ref-type fields (child Schemas / collections).
+     *
+     * Preconditions (enforced):
+     * - The instance must be tracked (encoder-side), not a decoder mirror.
+     * - The instance must NOT be shared across multiple parents.
+     * - The instance must already be removed from its parent collection/field
+     *   (so the encoder detached it: `root === undefined`).
+     *
+     * NOTE: primitive field values are NOT reset to class defaults — re-assign
+     * the fields you care about when you reuse the instance (standard
+     * object-pool discipline).
+     */
+    static reset(instance) {
+        const changeTree = instance?.[$changes];
+        // Only tracked (encoder-side) instances are poolable. Decoder-side
+        // instances carry an UntrackedChangeTree, which has no recycle().
+        if (changeTree === undefined || typeof changeTree.recycle !== "function") {
+            throw new Error(`@colyseus/schema: Schema.reset() requires a tracked (encoder-side) instance.`);
+        }
+        // Instances reachable through more than one parent are unsafe to pool:
+        // another owner may still hold this instance.
+        if (changeTree.extraParents !== undefined) {
+            throw new Error(`@colyseus/schema: cannot reset a shared instance (${instance.constructor.name}) with multiple parents.`);
+        }
+        instance[$reset]();
+    }
+    /**
+     * Per-instance reset primitive (the recursive worker behind
+     * {@link Schema.reset}). Resets ref-type children first (depth-first),
+     * then recycles this instance's ChangeTree and drops its `$refId` so a
+     * re-add is assigned a fresh refId exactly like a freshly constructed
+     * instance. Dropping `$refId` is what makes instance reuse
+     * wire-format-identical to `new T()`.
+     */
+    [$reset]() {
+        const metadata = this.constructor[Symbol.metadata];
+        const refIndexes = metadata?.[$refTypeFieldIndexes] ?? [];
+        const values = this[$values];
+        for (let i = 0; i < refIndexes.length; i++) {
+            const child = values[refIndexes[i]];
+            // ref fields hold a child Schema or collection (both implement
+            // [$reset]); skip undefined/null. Optional-chain is a cheap guard.
+            child?.[$reset]?.();
+        }
+        this[$changes].recycle();
+        // Clear the refId by ASSIGNMENT (not `delete`): `delete` would force the
+        // instance into V8 dictionary mode, making release() as expensive as the
+        // construction it saves. `=== undefined` in Root.add still assigns a fresh
+        // refId exactly like a freshly-constructed instance.
+        this[$refId] = undefined;
+    }
     /**
      * Check whether `type` describes a Schema *class* (a subclass
      * constructor carrying `Symbol.metadata`, as installed by `@type`).
@@ -6444,7 +7217,8 @@ class Schema {
             return view.isChangeTreeVisible(ref[$changes]);
         }
         else {
-            // view pass: custom tag
+            // view pass: custom tag (bitmask) — field's stored mask matches
+            // if it shares any bit with a tag this view was add()ed with.
             return view.hasTagOnTree(ref[$changes], tag);
         }
     }
@@ -6749,83 +7523,18 @@ class Schema {
     }
 }
 
-/**
- * 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.
- */
-class RefIdAllocator {
-    nextUniqueId;
-    _free = [];
-    _pending = [];
-    _pooled = new Set();
-    constructor(startRefId = 0) {
-        this.nextUniqueId = startRefId;
-    }
-    acquire() {
-        if (this._free.length > 0) {
-            const id = this._free.pop();
-            this._pooled.delete(id);
-            return id;
-        }
-        return this.nextUniqueId++;
-    }
-    release(refId) {
-        this._pending.push(refId);
-        this._pooled.add(refId);
-    }
-    isPooled(refId) {
-        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) {
-        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() {
-        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;
-    }
-}
-
+// Reused across Root.add calls — defineProperty is unavoidable ($refId must
+// stay non-enumerable for deepStrictEqual) but the descriptor literal isn't.
+const $refIdDescriptor$1 = { value: 0, enumerable: false, writable: true };
 class Root {
     types;
     /**
-     * Allocates and recycles refIds. See `RefIdAllocator` for the reuse
-     * pool semantics (one-tick defer + resurrection).
+     * Monotonic refId counter. RefIds are never recycled — a refId is a
+     * stable identity for the lifetime of the room, so a client that
+     * missed DELETEs (reconnect) can never see an old id rebound to a
+     * different instance. DevMode reads/writes this across HMR cycles.
      */
-    refIds;
+    nextUniqueId = 0;
     refCount = {};
     changeTrees = {};
     /**
@@ -6918,7 +7627,7 @@ class Root {
     }
     constructor(types, startRefId = 0) {
         this.types = types;
-        this.refIds = new RefIdAllocator(startRefId);
+        this.nextUniqueId = startRefId;
     }
     add(changeTree) {
         const ref = changeTree.ref;
@@ -6927,31 +7636,27 @@ class Root {
         // *enumerable* own Symbols, so we keep defineProperty(enumerable:false)
         // to keep $refId hidden from deep-equal comparisons in tests.
         if (ref[$refId] === undefined) {
-            Object.defineProperty(ref, $refId, {
-                value: this.refIds.acquire(),
-                enumerable: false,
-                writable: true
-            });
+            $refIdDescriptor$1.value = this.nextUniqueId++;
+            Object.defineProperty(ref, $refId, $refIdDescriptor$1);
         }
         const refId = ref[$refId];
         const isNewChangeTree = (this.changeTrees[refId] === undefined);
         if (isNewChangeTree) {
             this.changeTrees[refId] = changeTree;
         }
-        // Resurrection path: a ref whose refId is still queued for reuse
-        // is being re-added. Pull the refId out of the pool before it gets
-        // handed out to someone else.
-        if (this.refIds.isPooled(refId)) {
-            this.refIds.reclaim(refId);
-        }
         const previousRefCount = this.refCount[refId];
-        if (previousRefCount === 0) {
+        if (previousRefCount === 0 || changeTree.needsRestage) {
             //
-            // When a ChangeTree is re-added, it means that it was previously
-            // removed. Re-stage every currently-populated non-transient index
-            // as a fresh ADD in the matching dirty bucket so the next encode
-            // re-emits it on the correct channel.
+            // Re-stage every currently-populated non-transient index as a
+            // fresh ADD in the matching dirty bucket so the next encode
+            // re-emits it on the correct channel. Two triggers:
+            // - refCount 0: a previously-removed tree re-added under the
+            //   same refId (its ops were consumed by an earlier encode).
+            // - NEEDS_RESTAGE: a `Schema.reset` instance re-entering under
+            //   a fresh refId (reset cleared the buckets; its retained
+            //   values would otherwise never be encoded).
             //
+            changeTree.needsRestage = false;
             changeTree.forEachLive((fieldIndex) => {
                 if (changeTree.isFieldUnreliable(fieldIndex)) {
                     changeTree.ensureUnreliableRecorder().record(fieldIndex, exports.OPERATION.ADD);
@@ -6984,15 +7689,6 @@ class Root {
             this.removeFromQueue(changeTree);
             this.removeFromUnreliableQueue(changeTree);
             this.refCount[refId] = 0;
-            // Return refId to the reuse pool (deferred to end-of-tick via
-            // the allocator's pending set). Stream collections are excluded
-            // because their per-view delivery bookkeeping is harder to
-            // audit for reuse safety and the savings there are negligible.
-            // If the ref is later resurrected, `add()` evicts the refId
-            // from the pool before it's handed to another instance.
-            if (!changeTree.isStreamCollection) {
-                this.refIds.release(refId);
-            }
             changeTree.forEachChild((child, _) => {
                 if (child.removeParent(changeTree.ref)) {
                     if ((child.parentRef === undefined || // no parent, remove it
@@ -7165,6 +7861,12 @@ function ensureStructSwitch(ctx) {
  * Module-level adapter for `forEachLiveWithCtx`. Full-sync emits every live
  * field as ADD, so we re-enter `encodeChangeCb` with that fixed op — keeps
  * the callback closure-free across the entire DFS walk.
+ *
+ * The resync sweep (decoder/Resync.ts) depends on this shape: full-sync
+ * output is dense plain ADDs — no DELETEs, no gap-writes (so decoding it
+ * never compacts arrays mid-walk), and replaced occupants arrive as plain
+ * ADD (the sweep's touch hook releases them). Changing full-sync emission
+ * means revisiting the sweep.
  */
 function encodeFullSyncCb(ctx, fieldIndex) {
     encodeChangeCb(ctx, fieldIndex, exports.OPERATION.ADD);
@@ -7270,7 +7972,18 @@ function concatBytes(a, b) {
     return result;
 }
 class Encoder {
-    static BUFFER_SIZE = 8 * 1024; // 8KB
+    /**
+     * Per-encoder shared output buffer size. The encoder auto-grows on
+     * overflow and logs a one-time warning suggesting a higher value, so
+     * the default just needs to comfortably cover typical room state.
+     *
+     * Sized to fit ~100 items in a `MapSchema<{x,y,z}>` keyed by
+     * `nanoid(9)` (~4.5 KB worst-case full encode, float64-heavy) with
+     * ~3-4× headroom for surrounding state (player list, world refs,
+     * etc.). Raise per app via `Encoder.BUFFER_SIZE = N * 1024` before
+     * constructing any Encoder.
+     */
+    static BUFFER_SIZE = 16 * 1024;
     sharedBuffer = new Uint8Array(Encoder.BUFFER_SIZE);
     context;
     state;
@@ -7374,7 +8087,12 @@ class Encoder {
         }
         if (it.offset > buffer.byteLength) {
             buffer = this._resizeBuffer(buffer, it.offset);
-            return this._encodeChannel({ offset: initialOffset }, view, buffer, initialOffset, unreliable);
+            // Reuse `it` (reset its offset) instead of a fresh iterator so the
+            // caller's `it.offset` ends at the true final offset. A fresh one
+            // strands `it.offset` at the overflow value and corrupts the next
+            // view's region in a multi-view encode.
+            it.offset = initialOffset;
+            return this._encodeChannel(it, view, buffer, initialOffset, unreliable);
         }
         return buffer.subarray(0, it.offset);
     }
@@ -7406,7 +8124,8 @@ class Encoder {
         _fullSyncWalk(ctx, rootChangeTree);
         if (it.offset > buffer.byteLength) {
             buffer = this._resizeBuffer(buffer, it.offset);
-            return this.encodeFullSync({ offset: initialOffset }, buffer, emitFiltered, view);
+            it.offset = initialOffset; // reuse `it` so the caller's offset stays accurate
+            return this.encodeFullSync(it, buffer, emitFiltered, view, initialOffset);
         }
         return buffer.subarray(0, it.offset);
     }
@@ -7429,9 +8148,24 @@ class Encoder {
     }
     encodeAllView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
-        this.encodeFullSync(it, bytes, /* emitFiltered */ true, view, viewOffset);
+        // encodeFullSync() may reallocate the buffer on overflow — keep its
+        // return, not the stale `bytes`, or the concat below reads a dead buffer.
+        bytes = this.encodeFullSync(it, bytes, /* emitFiltered */ true, view, viewOffset);
         return concatBytes(bytes.subarray(0, sharedOffset), bytes.subarray(viewOffset, it.offset));
     }
+    /** Grow `buffer` to keep BUFFER_SIZE free bytes past `offset`, preserving `[0, offset)`. */
+    ensureCapacity(buffer, offset) {
+        if (offset + Encoder.BUFFER_SIZE <= buffer.byteLength) {
+            return buffer;
+        }
+        const size = Math.ceil((offset + Encoder.BUFFER_SIZE) / Encoder.BUFFER_SIZE) * Encoder.BUFFER_SIZE;
+        const grown = new Uint8Array(size);
+        grown.set(buffer.subarray(0, offset));
+        if (buffer === this.sharedBuffer) {
+            this.sharedBuffer = grown;
+        }
+        return grown;
+    }
     encodeView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
         // Stream priority pass: drain up to `maxPerTick` per-view entries
@@ -7469,6 +8203,9 @@ class Encoder {
             // `[$getByIndex]` lookup that runs once per change.
             const ref = changeTree.ref;
             const refTarget = changeTree.refTarget;
+            // These writes are unguarded and unrecoverable (view.changes is cleared
+            // below), so unlike encode() they can't re-encode on overflow — grow ahead.
+            bytes = this.ensureCapacity(bytes, it.offset);
             bytes[it.offset++] = SWITCH_TO_STRUCTURE & 255;
             encode.number(bytes, ref[$refId], it);
             // Iterate entries directly — the inner Map gives us the (index, op)
@@ -7487,9 +8224,14 @@ class Encoder {
         // (to allow re-using StateView's for multiple clients)
         //
         view.changes.clear();
-        // per-tick view-scoped pass: walks the same `changes` queue as the
+        // Per-tick view-scoped pass: walks the same `changes` queue as the
         // shared pass, but `encodeChangeCb` emits only filtered fields.
-        this.encode(it, view, bytes, viewOffset);
+        // encode() may reallocate the buffer on overflow — keep its return,
+        // not the stale `bytes`. Anchor the re-encode at the current offset
+        // (the default `initialOffset = it.offset`), NOT `viewOffset`: a
+        // resize must not clobber the view.changes already written at
+        // [viewOffset, it.offset).
+        bytes = this.encode(it, view, bytes);
         return concatBytes(bytes.subarray(0, sharedOffset), bytes.subarray(viewOffset, it.offset));
     }
     /**
@@ -7501,7 +8243,9 @@ class Encoder {
      */
     encodeUnreliableView(view, sharedOffset, it, bytes = this.sharedBuffer) {
         const viewOffset = it.offset;
-        this.encodeUnreliable(it, view, bytes, viewOffset);
+        // Capture the return: a resize on overflow reallocates the buffer, and
+        // the concat below must read from the live one, not the stale `bytes`.
+        bytes = this.encodeUnreliable(it, view, bytes, viewOffset);
         return concatBytes(bytes.subarray(0, sharedOffset), bytes.subarray(viewOffset, it.offset));
     }
     /**
@@ -7727,10 +8471,6 @@ class Encoder {
         }
         list.next = undefined;
         list.tail = undefined;
-        // End-of-tick: refIds released during this tick have now had their
-        // DELETEs emitted through `encode()` / `encodeView()`, so they are
-        // safe to recycle on the next tick.
-        root.refIds.flushReleases();
     }
     discardUnreliableChanges() {
         const list = this.root.unreliableChanges;
@@ -7784,6 +8524,8 @@ class DecodingWarning extends Error {
         this.name = "DecodingWarning";
     }
 }
+// Reused across addRef calls — saves a descriptor object per decoded ref.
+const $refIdDescriptor = { value: 0, enumerable: false, writable: true };
 class ReferenceTracker {
     //
     // Relation of refId => Schema structure
@@ -7804,11 +8546,13 @@ class ReferenceTracker {
         // on decoded instances, which WOULD walk enumerable Symbol-keyed
         // properties and include `$refId` in the comparison. Keep the
         // descriptor dance for semantic compatibility.
-        Object.defineProperty(ref, $refId, {
-            value: refId,
-            enumerable: false,
-            writable: true
-        });
+        if (ref[$refId] === undefined) {
+            $refIdDescriptor.value = refId;
+            Object.defineProperty(ref, $refId, $refIdDescriptor);
+        }
+        else if (ref[$refId] !== refId) {
+            ref[$refId] = refId; // property exists (writable) — plain write keeps flags
+        }
         if (incrementCount) {
             this.refCount[refId] = (this.refCount[refId] || 0) + 1;
         }
@@ -7922,6 +8666,18 @@ class Decoder {
     root;
     currentRefId = 0;
     triggerChanges;
+    /**
+     * @internal Non-null only while a `decodeResync()` walk is in progress:
+     * collection refId → entry identities the payload visited (map string
+     * keys; array/set/collection/stream indexes). Written by the collection
+     * DecodeOperation functions, read by the post-decode sweep.
+     */
+    resyncVisited = null;
+    /**
+     * @internal Set when a structure had to be skipped during a resync
+     * decode — visited data is incomplete, so the sweep must not delete.
+     */
+    resyncDamaged = false;
     constructor(root, context) {
         this.setState(root);
         this.context = context || new TypeContext(root.constructor);
@@ -7986,6 +8742,12 @@ class Decoder {
         // currently hooks it; the dual call sites stay as-is rather
         // than being extracted into a helper for a one-line body.
         ref[$onDecodeEnd]?.();
+        // resync mode: prune everything the snapshot didn't visit. Runs
+        // before triggerChanges (DELETE changes fire onRemove with the real
+        // previousValue) and before GC (removeRef feeds deletedRefs).
+        if (this.resyncVisited !== null) {
+            resyncSweep(this, allChanges);
+        }
         // trigger changes
         if (allChanges !== null)
             this.triggerChanges?.(allChanges);
@@ -7993,7 +8755,37 @@ class Decoder {
         $root.garbageCollectDeletedRefs();
         return allChanges;
     }
+    /**
+     * Full-snapshot reconciliation ("resync") decode.
+     *
+     * Behaves exactly like {@link decode}, plus: every collection entry the
+     * payload does NOT mention is removed through the regular DELETE path —
+     * `onRemove` callbacks fire with the real previous value and released
+     * refs are garbage-collected. Use it to apply a rejoin/reconnect full
+     * state over an existing decoded tree: DELETEs that happened while the
+     * client was off the wire are reconciled as if they had been received,
+     * while surviving entries keep their instance identity and callbacks.
+     *
+     * ONLY valid for full-snapshot payloads (`encodeAll` / `encodeAllView`
+     * output). Calling it on an incremental patch would prune everything
+     * the patch doesn't touch.
+     */
+    decodeResync(bytes, it = { offset: 0 }) {
+        this.resyncVisited = new Map();
+        this.resyncDamaged = false;
+        try {
+            return this.decode(bytes, it);
+        }
+        finally {
+            this.resyncVisited = null;
+        }
+    }
     skipCurrentStructure(bytes, it, totalBytes) {
+        // A skipped range can swallow other structures' ops (their ADDs are
+        // never applied), so resync visited data is no longer trustworthy.
+        if (this.resyncVisited !== null) {
+            this.resyncDamaged = true;
+        }
         //
         // keep skipping next bytes until reaches a known structure
         // by local decoder.
@@ -8043,10 +8835,27 @@ class Decoder {
 /**
  * Reflection
  */
+/**
+ * `t.quantized()` field descriptor as it rides the reflection handshake —
+ * schema-typed (bit-exact float64 bounds), NOT a string grammar, so every
+ * language port decodes it with the schema decoder it already has.
+ */
+const QuantizedDescriptor = schema({
+    min: t.float64(),
+    max: t.float64(),
+    bits: t.uint8(),
+    mode: t.uint8(), // 0 = clamp, 1 = wrap
+}, "QuantizedDescriptor");
 const ReflectionField = schema({
     name: t.string(),
     type: t.string(),
     referencedType: t.number(),
+    /** Primitive child of a collection (`array`/`map`/... of "string" etc.) —
+     *  its own slot, replacing the legacy `"array:string"` colon packing. */
+    childPrimitive: t.string(),
+    /** Set only on `t.quantized()` fields (`.optional()` — no auto-instantiated
+     *  default; its absence is the "not quantized" signal on decode). */
+    quantized: t.ref(QuantizedDescriptor).optional(),
 }, "ReflectionField");
 const ReflectionType = schema({
     id: t.number(),
@@ -8116,6 +8925,18 @@ Reflection.encode = function (encoder, it = { offset: 0 }) {
                 if (typeof (field.type) === "string") {
                     fieldType = field.type;
                 }
+                else if (isQuantizedType(field.type)) {
+                    // Params ride as a schema-typed descriptor (bit-exact float64) —
+                    // no string grammar for the peer (or a language port) to parse.
+                    const d = field.type.quantized;
+                    fieldType = "quantized";
+                    const desc = new QuantizedDescriptor();
+                    desc.min = d.min;
+                    desc.max = d.max;
+                    desc.bits = d.bits;
+                    desc.mode = d.wrap ? 1 : 0;
+                    reflectionField.quantized = desc;
+                }
                 else {
                     let childTypeSchema;
                     //
@@ -8128,7 +8949,8 @@ Reflection.encode = function (encoder, it = { offset: 0 }) {
                     else {
                         fieldType = Object.keys(field.type)[0];
                         if (typeof (field.type[fieldType]) === "string") {
-                            fieldType += ":" + field.type[fieldType]; // array:string
+                            // primitive child gets its own slot (was packed as "array:string")
+                            reflectionField.childPrimitive = field.type[fieldType];
                         }
                         else {
                             childTypeSchema = field.type[fieldType];
@@ -8169,15 +8991,20 @@ Reflection.decode = function (bytes, it) {
     const addFields = (metadata, reflectionType, parentFieldIndex) => {
         reflectionType.fields.forEach((field, i) => {
             const fieldIndex = parentFieldIndex + i;
-            if (field.referencedType !== undefined) {
-                let fieldType = field.type;
-                let refType = typeContext.get(field.referencedType);
-                // map or array of primitive type (-1)
-                if (!refType) {
-                    const typeInfo = field.type.split(":");
-                    fieldType = typeInfo[0];
-                    refType = typeInfo[1]; // string
-                }
+            if (field.quantized !== undefined) {
+                // Schema-typed descriptor → resolved codec (validation stays in
+                // resolveQuantize, same as the builder path).
+                const q = field.quantized;
+                Metadata.addField(metadata, fieldIndex, field.name, {
+                    quantized: resolveQuantize({ min: q.min, max: q.max, bits: q.bits, mode: q.mode === 1 ? "wrap" : "clamp" }),
+                });
+            }
+            else if (field.referencedType !== undefined) {
+                const fieldType = field.type;
+                // Schema child by type id; a primitive child (referencedType -1)
+                // rides its own childPrimitive slot.
+                const refType = typeContext.get(field.referencedType)
+                    ?? field.childPrimitive;
                 if (fieldType === "ref") {
                     Metadata.addField(metadata, fieldIndex, field.name, refType);
                 }
@@ -8860,6 +9687,48 @@ const Callbacks = {
     }
 };
 
+/**
+ * Object pool for Schema instances. Exported as a **type only** — construct one
+ * via {@link createPool}, which is the public entry point. The class is public
+ * for typing (`SchemaPool<Entity>` annotations) and `instanceof` checks.
+ */
+class SchemaPool {
+    _free = [];
+    _factory;
+    _maxSize;
+    constructor(factory, opts = {}) {
+        this._factory = factory;
+        this._maxSize = opts.maxSize ?? Infinity;
+        const preallocate = opts.preallocate ?? 0;
+        for (let i = 0; i < preallocate; i++) {
+            this._free.push(factory());
+        }
+    }
+    /** Pop a pre-reset free instance, or construct a fresh one. */
+    acquire() {
+        return this._free.length > 0 ? this._free.pop() : this._factory();
+    }
+    /**
+     * Reset `instance` to construction defaults and return it to the pool.
+     * PRECONDITION: the instance must already be detached from the state tree
+     * (removed from its parent collection/field, so the encoder released it).
+     */
+    release(instance) {
+        Schema.reset(instance);
+        if (this._free.length < this._maxSize) {
+            this._free.push(instance);
+        }
+    }
+    /** Number of instances currently available for reuse. */
+    get size() {
+        return this._free.length;
+    }
+}
+/** Convenience factory: `createPool(Entity, { preallocate: 64 })`. */
+function createPool(ctor, opts = {}) {
+    return new SchemaPool(() => new ctor(), opts);
+}
+
 /**
  * Clear the bit for `(slot, bit)` on every ChangeTree in `root`. Called
  * from `dispose()` and from the FinalizationRegistry callback so a view's
@@ -9062,42 +9931,66 @@ class StateView {
     // `tags: WeakMap<ChangeTree, Set<number>>` storage. Hot read site is
     // `Schema.ts` filter check — `hasTagOnTree` is O(1) bitwise.
     // ──────────────────────────────────────────────────────────────────
-    /** True iff this view has `tag` associated with `tree`. */
+    /**
+     * True iff this view shares at least one tag bit with `tree`.
+     *
+     * `tagViews` is keyed by individual power-of-two bits (custom tags must
+     * be powers of two; `@view(A|B)` field masks are decomposed on store).
+     * A field whose mask is `tag` is visible if the view was `add()`ed with
+     * any overlapping bit — so we walk `tag`'s set bits and return on the
+     * first match. Passing DEFAULT_VIEW_TAG (-1, all bits) answers "does
+     * this view hold ANY custom tag on the tree".
+     */
     hasTagOnTree(tree, tag) {
         const map = tree.tagViews;
         if (map === undefined)
             return false;
-        const arr = map.get(tag);
         const slot = this._slot;
-        return arr !== undefined && slot < arr.length && (arr[slot] & this._bit) !== 0;
+        const bit = this._bit;
+        for (let bits = tag; bits !== 0; bits &= bits - 1) {
+            const arr = map.get(bits & -bits); // isolate lowest set bit
+            if (arr !== undefined && slot < arr.length && (arr[slot] & bit) !== 0)
+                return true;
+        }
+        return false;
     }
-    /** Mark `tree` as carrying `tag` for this view. */
+    /** Mark `tree` as carrying `tag` (each of its bits) for this view. */
     addTag(tree, tag) {
+        // DEFAULT_VIEW_TAG visibility lives in `visibleViews`, not here.
+        if (tag === DEFAULT_VIEW_TAG)
+            return;
         let map = tree.tagViews;
         if (map === undefined) {
             map = tree.tagViews = new Map();
         }
-        let arr = map.get(tag);
-        if (arr === undefined) {
-            arr = [];
-            map.set(tag, arr);
-        }
         const slot = this._slot;
-        while (arr.length <= slot)
-            arr.push(0);
-        arr[slot] |= this._bit;
+        const bit = this._bit;
+        for (let bits = tag; bits > 0; bits &= bits - 1) {
+            const b = bits & -bits; // isolate lowest set bit
+            let arr = map.get(b);
+            if (arr === undefined) {
+                arr = [];
+                map.set(b, arr);
+            }
+            while (arr.length <= slot)
+                arr.push(0);
+            arr[slot] |= bit;
+        }
     }
-    /** Clear this view's `tag` bit on `tree`. */
+    /** Clear each of `tag`'s bits for this view on `tree`. */
     removeTag(tree, tag) {
+        if (tag === DEFAULT_VIEW_TAG)
+            return;
         const map = tree.tagViews;
         if (map === undefined)
             return;
-        const arr = map.get(tag);
-        if (arr === undefined)
-            return;
         const slot = this._slot;
-        if (slot < arr.length)
-            arr[slot] &= ~this._bit;
+        const clearMask = ~this._bit;
+        for (let bits = tag; bits > 0; bits &= bits - 1) {
+            const arr = map.get(bits & -bits);
+            if (arr !== undefined && slot < arr.length)
+                arr[slot] &= clearMask;
+        }
     }
     /** Clear ALL tag bits this view holds on `tree` (used when the per-tag isn't known). */
     removeAllTagsOnTree(tree) {
@@ -9229,10 +10122,16 @@ class StateView {
         // direct array index instead of a per-field-object hop.
         const tags = changeTree.encDescriptor.tags;
         changeTree.forEachChild((change, index) => {
-            // Do not ADD children that don't have the same tag
+            // Do not ADD children whose field tag shares no bit with `tag`.
+            // DEFAULT_VIEW_TAG fields are visible to all clients; custom-tag
+            // fields only when bits overlap, and never to default-tag clients.
             const fieldTag = tags[index];
-            if (fieldTag !== undefined && fieldTag !== tag) {
-                return;
+            if (fieldTag !== undefined) {
+                const tagMatch = fieldTag === DEFAULT_VIEW_TAG ||
+                    (tag !== DEFAULT_VIEW_TAG && (fieldTag & tag) !== 0);
+                if (!tagMatch) {
+                    return;
+                }
             }
             if (this.add(change.ref, tag, false)) {
                 isChildAdded = true;
@@ -9241,12 +10140,19 @@ class StateView {
         // set tag
         if (tag !== DEFAULT_VIEW_TAG) {
             this.addTag(changeTree, tag);
-            // Ref: add tagged properties
-            metadata?.[$fieldIndexesByViewTag]?.[tag]?.forEach((index) => {
-                if (changeTree.getChange(index) !== exports.OPERATION.DELETE) {
-                    changes.set(index, exports.OPERATION.ADD);
+            // Ref: add tagged properties. `$fieldIndexesByViewTag` is keyed
+            // per-bit, so a combined add-tag (`view.add(obj, A|B)`) must look
+            // up each set bit to force-ADD every field that shares a bit.
+            const byTag = metadata?.[$fieldIndexesByViewTag];
+            if (byTag !== undefined) {
+                for (let bits = tag; bits > 0; bits &= bits - 1) {
+                    byTag[bits & -bits]?.forEach((index) => {
+                        if (changeTree.getChange(index) !== exports.OPERATION.DELETE) {
+                            changes.set(index, exports.OPERATION.ADD);
+                        }
+                    });
                 }
-            });
+            }
         }
         else if (!changeTree.isNew || isChildAdded) {
             // new structures will be added as part of .encode() call, no need to force it to .encodeView()
@@ -9262,7 +10168,8 @@ class StateView {
                 const tagAtIndex = tags[index];
                 if (isInvisible || // if "invisible", include all
                     tagAtIndex === undefined || // "all change" with no tag
-                    tagAtIndex === tag // tagged property
+                    tagAtIndex === DEFAULT_VIEW_TAG || // visible to all clients
+                    (tag !== DEFAULT_VIEW_TAG && (tagAtIndex & tag) !== 0) // tag bits overlap
                 ) {
                     changes.set(index, exports.OPERATION.ADD);
                     isChildAdded = true;
@@ -9292,8 +10199,12 @@ class StateView {
         const tags = tree.encDescriptor.tags;
         tree.forEachChild((child, index) => {
             const fieldTag = tags[index];
-            if (fieldTag !== undefined && fieldTag !== tag)
-                return;
+            if (fieldTag !== undefined) {
+                const tagMatch = fieldTag === DEFAULT_VIEW_TAG ||
+                    (tag !== DEFAULT_VIEW_TAG && (fieldTag & tag) !== 0);
+                if (!tagMatch)
+                    return;
+            }
             if (child.isNew) {
                 this.markVisible(child);
                 this._markSubtreeVisible(child, tag);
@@ -9309,20 +10220,25 @@ class StateView {
         if (!this.isVisible(changeTree)) {
             // view must have all "changeTree" parent tree
             this.markVisible(changeTree);
-            // Recurse all the way to the root regardless of whether the
-            // parent is filtered. Walking the full chain is what makes
-            // `view.changes` topologically ordered by construction — any
-            // filtered ancestor up the chain is touched here, before the
-            // descendant's entry. The actual entry-write below is gated
-            // on `hasFilteredFields` so non-filtered ancestors don't
-            // emit redundant wire bytes (the decoder already knows them
-            // via the shared encode pass). Marking them visible is
-            // still useful: it makes this short-circuit fire on the next
-            // `view.add` instead of re-walking the chain.
-            const parentChangeTree = changeTree.parent?.[$changes];
-            if (parentChangeTree) {
-                this.addParentOf(changeTree, tag);
-            }
+        }
+        // Recurse all the way to the root REGARDLESS of whether this parent
+        // is already visible. Walking the full chain keeps `view.changes`
+        // topologically ordered by construction (ancestors touched before
+        // the descendant's entry), and — crucially — re-queues the ancestor
+        // binding ops every time: visibility bits are per-VIEW, but the ADD
+        // ops they once queued are consumed per-ENCODE. With a shared view,
+        // an earlier encode (for other clients) or a dropped backlog leaves
+        // an already-visible ancestor whose binding a late-attached client
+        // never received — its filtered-container refId would then arrive
+        // unbound ("refId not found"). Re-writing the entry ops is cheap
+        // (Map.set dedupes within a patch) and decodes as a no-op for
+        // clients that already hold the refs. The entry-write below is
+        // still gated on `hasFilteredFields` so non-filtered ancestors
+        // don't emit redundant wire bytes (the decoder already knows them
+        // via the shared encode pass).
+        const parentChangeTree = changeTree.parent?.[$changes];
+        if (parentChangeTree) {
+            this.addParentOf(changeTree, tag);
         }
         // Skip the entry-write for non-filtered ancestors: their refIds
         // are already known to the decoder through the shared pass, and
@@ -9488,19 +10404,25 @@ class StateView {
             }
         }
         else {
-            // delete only tagged properties
+            // delete only tagged properties. `$fieldIndexesByViewTag` is
+            // keyed per-bit, so a combined tag iterates each set bit.
             const names = changeTree.encDescriptor.names;
-            metadata?.[$fieldIndexesByViewTag][tag].forEach((index) => {
-                changes.set(index, exports.OPERATION.DELETE);
-                // Remove child structures from visible set
-                const value = changeTree.ref[names[index]];
-                if (value?.[$changes]) {
-                    this.unmarkVisible(value[$changes]);
-                    this._recursiveDeleteVisibleChangeTree(value[$changes]);
+            const byTag = metadata?.[$fieldIndexesByViewTag];
+            if (byTag !== undefined) {
+                for (let bits = tag; bits > 0; bits &= bits - 1) {
+                    byTag[bits & -bits]?.forEach((index) => {
+                        changes.set(index, exports.OPERATION.DELETE);
+                        // Remove child structures from visible set
+                        const value = changeTree.ref[names[index]];
+                        if (value?.[$changes]) {
+                            this.unmarkVisible(value[$changes]);
+                            this._recursiveDeleteVisibleChangeTree(value[$changes]);
+                        }
+                    });
                 }
-            });
+            }
         }
-        // remove tag bit for this view
+        // remove tag bits for this view
         if (tag === undefined) {
             this.removeAllTagsOnTree(changeTree);
         }
@@ -9677,8 +10599,10 @@ exports.$deleteByIndex = $deleteByIndex;
 exports.$encoder = $encoder;
 exports.$filter = $filter;
 exports.$getByIndex = $getByIndex;
+exports.$numFields = $numFields;
 exports.$refId = $refId;
 exports.$track = $track;
+exports.$values = $values;
 exports.ArraySchema = ArraySchema;
 exports.Callbacks = Callbacks;
 exports.ChangeTree = ChangeTree;
@@ -9698,10 +10622,12 @@ exports.StateCallbackStrategy = StateCallbackStrategy;
 exports.StateView = StateView;
 exports.StreamSchema = StreamSchema;
 exports.TypeContext = TypeContext;
+exports.createPool = createPool;
 exports.decode = decode;
 exports.decodeKeyValueOperation = decodeKeyValueOperation;
 exports.decodeSchemaOperation = decodeSchemaOperation;
 exports.defineCustomTypes = defineCustomTypes;
+exports.defineTypes = defineTypes;
 exports.deprecated = deprecated;
 exports.dumpChanges = dumpChanges;
 exports.encode = encode;
@@ -9712,6 +10638,7 @@ exports.encodeMapEntry = encodeMapEntry;
 exports.encodeSchemaOperation = encodeSchemaOperation;
 exports.entity = entity;
 exports.getDecoderStateCallbacks = getDecoderStateCallbacks;
+exports.getEncodeDescriptor = getEncodeDescriptor;
 exports.getRawChangesCallback = getRawChangesCallback;
 exports.isBuilder = isBuilder;
 exports.owned = owned;