@colyseus/schema 5.0.6 → 5.0.9

package/build/index.js

@@ -63,6 +63,13 @@
     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.
      *
@@ -87,6 +94,14 @@
      * (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
      */
@@ -812,6 +827,92 @@
         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();
@@ -914,6 +1015,11 @@
                 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);
                 }
@@ -982,6 +1088,14 @@
         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'];
         }
@@ -1060,8 +1174,9 @@
                 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: [],
@@ -1123,10 +1238,25 @@
                 });
             }
             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];
@@ -1232,8 +1362,8 @@
             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: [],
@@ -1242,7 +1372,9 @@
                         writable: true,
                     });
                 }
-                metadata[$encoders][fieldIndex] = encode[normalized];
+                metadata[$encoders][fieldIndex] = (typeof normalized === "string")
+                    ? encode[normalized]
+                    : makeQuantizedEncoder(normalized.quantized);
             }
         },
         setFields(target, fields) {
@@ -1888,6 +2020,8 @@
         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.
@@ -1917,6 +2051,8 @@
             // 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
@@ -2180,6 +2316,12 @@
         }
     }
 
+    /**
+     * 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);
@@ -2232,30 +2374,10 @@
         }
     }
     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
@@ -2274,12 +2396,35 @@
         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);
                 }
             }
         }
@@ -2364,6 +2509,12 @@
     // `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
@@ -2476,6 +2627,8 @@
         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
@@ -2759,6 +2912,48 @@
             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");
@@ -3214,6 +3409,165 @@
         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
@@ -3271,6 +3625,12 @@
             //
             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);
@@ -3287,6 +3647,10 @@
         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
@@ -3299,17 +3663,25 @@
             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,
@@ -3401,6 +3773,10 @@
         }
         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:
@@ -3477,6 +3853,16 @@
             // 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({
@@ -3511,6 +3897,12 @@
         // 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)
         ) {
@@ -3636,6 +4028,8 @@
         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`. */
@@ -3650,9 +4044,11 @@
          * - 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 (
@@ -3696,6 +4092,7 @@
             // 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);
@@ -3823,6 +4220,9 @@
                 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;
             }
         }
@@ -3843,6 +4243,27 @@
             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.
@@ -4242,21 +4663,51 @@
          * `$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);
@@ -4623,6 +5074,24 @@
             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);
         }
@@ -4663,6 +5132,36 @@
                 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();
         }
@@ -4855,6 +5354,24 @@
             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);
         }
@@ -4893,6 +5410,22 @@
         [$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];
@@ -5094,6 +5627,24 @@
             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;
@@ -5144,6 +5695,22 @@
         [$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];
@@ -5405,6 +5972,11 @@
                 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.
         }
@@ -5485,7 +6057,22 @@
         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;
@@ -5656,6 +6243,20 @@
         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"),
@@ -5673,16 +6274,46 @@
         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;
@@ -5914,8 +6545,8 @@
             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: [],
@@ -5924,7 +6555,9 @@
                         writable: true,
                     });
                 }
-                metadata[$encoders][fieldIndex] = encode[type];
+                metadata[$encoders][fieldIndex] = (typeof type === "string")
+                    ? encode[type]
+                    : makeQuantizedEncoder(type.quantized);
             }
         };
     }
@@ -6035,6 +6668,38 @@
             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) {
@@ -6043,10 +6708,15 @@
         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,
@@ -6081,32 +6751,51 @@
             });
         };
     }
+    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;
@@ -6133,7 +6822,39 @@
         }
         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 = [];
@@ -6157,18 +6878,16 @@
                             `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;
                 }
@@ -6196,24 +6915,14 @@
                 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 {
@@ -6225,17 +6934,19 @@
                     `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) => {
@@ -6248,18 +6959,26 @@
             }
             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);
@@ -6386,6 +7105,60 @@
             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`).
@@ -6448,7 +7221,8 @@
                 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);
             }
         }
@@ -6753,83 +7527,18 @@
         }
     }
 
-    /**
-     * 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 = {};
         /**
@@ -6922,7 +7631,7 @@
         }
         constructor(types, startRefId = 0) {
             this.types = types;
-            this.refIds = new RefIdAllocator(startRefId);
+            this.nextUniqueId = startRefId;
         }
         add(changeTree) {
             const ref = changeTree.ref;
@@ -6931,31 +7640,27 @@
             // *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);
@@ -6988,15 +7693,6 @@
                 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
@@ -7169,6 +7865,12 @@
      * 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);
@@ -7274,7 +7976,18 @@
         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;
@@ -7378,7 +8091,12 @@
             }
             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);
         }
@@ -7410,7 +8128,8 @@
             _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);
         }
@@ -7433,9 +8152,24 @@
         }
         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
@@ -7473,6 +8207,9 @@
                 // `[$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)
@@ -7491,9 +8228,14 @@
             // (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));
         }
         /**
@@ -7505,7 +8247,9 @@
          */
         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));
         }
         /**
@@ -7731,10 +8475,6 @@
             }
             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;
@@ -7788,6 +8528,8 @@
             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
@@ -7808,11 +8550,13 @@
             // 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;
             }
@@ -7926,6 +8670,18 @@
         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);
@@ -7990,6 +8746,12 @@
             // 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);
@@ -7997,7 +8759,37 @@
             $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.
@@ -8047,10 +8839,27 @@
     /**
      * 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(),
@@ -8120,6 +8929,18 @@
                     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;
                         //
@@ -8132,7 +8953,8 @@
                         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];
@@ -8173,15 +8995,20 @@
         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);
                     }
@@ -8864,6 +9691,48 @@
         }
     };
 
+    /**
+     * 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
@@ -9066,42 +9935,66 @@
         // `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) {
@@ -9233,10 +10126,16 @@
             // 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;
@@ -9245,12 +10144,19 @@
             // 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()
@@ -9266,7 +10172,8 @@
                     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;
@@ -9296,8 +10203,12 @@
             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);
@@ -9313,20 +10224,25 @@
             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
@@ -9492,19 +10408,25 @@
                 }
             }
             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);
             }
@@ -9681,8 +10603,10 @@
     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;
@@ -9702,10 +10626,12 @@
     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;
@@ -9716,6 +10642,7 @@
     exports.encodeSchemaOperation = encodeSchemaOperation;
     exports.entity = entity;
     exports.getDecoderStateCallbacks = getDecoderStateCallbacks;
+    exports.getEncodeDescriptor = getEncodeDescriptor;
     exports.getRawChangesCallback = getRawChangesCallback;
     exports.isBuilder = isBuilder;
     exports.owned = owned;