@colyseus/schema 5.0.5 → 5.0.8

package/src/codegen/types.ts

@@ -23,21 +23,11 @@ export class Context {
     enums: Enum[] = [];
 
     getStructures() {
+        // `isSchemaClass` already walks the full ancestor chain, so a class is
+        // emitted iff it (or any ancestor) descends from Schema — no need to
+        // re-walk parents here.
         return {
-            classes: this.classes.filter(klass => {
-                if (this.isSchemaClass(klass)) {
-                    return true;
-
-                } else {
-                    let parentClass = klass;
-                    while (parentClass = this.getParentClass(parentClass)) {
-                        if (this.isSchemaClass(parentClass)) {
-                            return true;
-                        }
-                    }
-                }
-                return false;
-            }),
+            classes: this.classes.filter(klass => this.isSchemaClass(klass)),
             interfaces: this.interfaces,
             enums: this.enums,
         };
@@ -56,37 +46,25 @@ export class Context {
         }
     }
 
-    private getParentClass(klass: Class) {
-        return this.classes.find(c => c.name === klass.extends);
-    }
-
     private isSchemaClass(klass: Class) {
-        let isSchema: boolean = false;
-
-        let currentClass = klass;
-        while (!isSchema && currentClass) {
-            //
-            // TODO: ideally we should check for actual @colyseus/schema module
-            // reference rather than arbitrary strings.
-            //
-            isSchema = (
-                currentClass.extends === "Schema" ||
-                currentClass.extends === "schema.Schema" ||
-                currentClass.extends === "Schema.Schema"
+        // True if `klass` or any ancestor extends Schema (directly or via the
+        // `schema.Schema` / `Schema.Schema` aliases).
+        //
+        // TODO: ideally we should check for the actual @colyseus/schema module
+        // reference rather than arbitrary strings.
+        for (const current of [klass, ...eachAncestor(klass, this.classes)]) {
+            const isSchema = (
+                current.extends === "Schema" ||
+                current.extends === "schema.Schema" ||
+                current.extends === "Schema.Schema"
             );
-
-            //
-            // When extending from `schema.Schema`, it is required to
-            // normalize as "Schema" for code generation.
-            //
-            if (currentClass === klass && isSchema) {
-                klass.extends = "Schema";
+            if (isSchema) {
+                // Normalize a `schema.Schema`-style base on the queried class itself.
+                if (current === klass) { klass.extends = "Schema"; }
+                return true;
             }
-
-            currentClass = this.getParentClass(currentClass);
         }
-
-        return isSchema;
+        return false;
     }
 }
 
@@ -127,17 +105,11 @@ export class Class implements IStructure {
     }
 
     postProcessing() {
-        /**
-         * Ensure the proprierties `index` are correct using inheritance
-         */
-        let parentKlass: Class = this;
-
-        while (
-            parentKlass &&
-            (parentKlass = this.context.classes.find(k => k.name === parentKlass.extends))
-        ) {
+        // Offset each property's `index` by the field count of every ancestor,
+        // so indexes stay correct across inheritance.
+        for (const parent of eachAncestor(this, this.context.classes)) {
             this.properties.forEach(prop => {
-                prop.index += parentKlass.properties.length;
+                prop.index += parent.properties.length;
             });
         }
     }
@@ -181,18 +153,28 @@ export interface GeneratedFile {
     body: string;
 }
 
-export function getInheritanceTree(klass: Class, allClasses: Class[], includeSelf: boolean = true) {
-    let currentClass = klass;
-    let inheritanceTree: Class[] = [];
-
-    if (includeSelf) {
-        inheritanceTree.push(currentClass);
-    }
-
-    while (currentClass.extends !== "Schema") {
-        currentClass = allClasses.find(klass => klass.name == currentClass.extends);
-        inheritanceTree.push(currentClass);
+/**
+ * Walk `klass`'s `extends` chain, parent-first, yielding each ancestor class
+ * (not `klass` itself). The single safe ancestor traversal every inheritance
+ * query is built on: it stops at the Schema root, an unresolved base, or a
+ * cycle — so a malformed class graph can never spin forever. This is why the
+ * `seen` cycle-guard lives here and nowhere else.
+ */
+function* eachAncestor(klass: Class, allClasses: Class[]): Generator<Class> {
+    const seen = new Set<Class>([klass]);
+    let current = klass;
+    while (current.extends && current.extends !== "Schema") {
+        const parent = allClasses.find(c => c.name === current.extends);
+        if (!parent || seen.has(parent)) { return; }
+        seen.add(parent);
+        yield parent;
+        current = parent;
     }
+}
 
-    return inheritanceTree;
+export function getInheritanceTree(klass: Class, allClasses: Class[], includeSelf: boolean = true) {
+    return [
+        ...(includeSelf ? [klass] : []),
+        ...eachAncestor(klass, allClasses),
+    ];
 }

package/src/decoder/DecodeOperation.ts

@@ -10,6 +10,8 @@ import type { ArraySchema } from "../types/custom/ArraySchema.js";
 
 import { getType } from "../types/registry.js";
 import { Collection } from "../types/HelperTypes.js";
+import { decodeQuantized, isQuantizedType } from "../types/quantize.js";
+import { resyncMarkPresent, resyncTouchEntry } from "./Resync.js";
 
 export interface DataChange<T = any, F = string> {
     ref: IRef,
@@ -124,6 +126,12 @@ export function decodeValue<T extends Ref>(
         //
         value = (decode as any)[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);
@@ -148,6 +156,9 @@ export function decodeValue<T extends Ref>(
         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
@@ -163,18 +174,27 @@ export function decodeValue<T extends Ref>(
             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 & OPERATION.DELETE) !== 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: IterableIterator<[any, any]> = (previousValue as any).entries();
                 let iter: IteratorResult<[any, any]>;
                 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({
@@ -317,6 +337,11 @@ export const decodeKeyValueOperation: DecodeOperation = function (
         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:
@@ -408,6 +433,16 @@ export const decodeArray: DecodeOperation = function (
         // 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: any) => value === previousValue);
         tgt[$deleteByIndex](index);
         allChanges?.push({
@@ -459,6 +494,13 @@ export const decodeArray: DecodeOperation = function (
         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)

package/src/decoder/Decoder.ts

@@ -7,6 +7,7 @@ import { type IRef, type Ref } from "../encoder/ChangeTree.js";
 import type { Iterator } from "../encoding/decode.js";
 import { ReferenceTracker } from "./ReferenceTracker.js";
 import { DEFINITION_MISMATCH, type DataChange, type DecodeOperation } from "./DecodeOperation.js";
+import { resyncSweep } from "./Resync.js";
 import { Collection } from "../types/HelperTypes.js";
 
 export class Decoder<T extends IRef = any> {
@@ -19,6 +20,20 @@ export class Decoder<T extends IRef = any> {
 
     triggerChanges?: (allChanges: DataChange[]) => void;
 
+    /**
+     * @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: Map<number, Set<number | string>> | null = 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: boolean = false;
+
     constructor(root: T, context?: TypeContext) {
         this.setState(root);
 
@@ -103,6 +118,11 @@ export class Decoder<T extends IRef = any> {
         // than being extracted into a helper for a one-line body.
         (ref as any)[$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);
 
@@ -112,7 +132,35 @@ export class Decoder<T extends IRef = any> {
         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: Uint8Array, it: Iterator = { offset: 0 }) {
+        this.resyncVisited = new Map();
+        this.resyncDamaged = false;
+        try {
+            return this.decode(bytes, it);
+        } finally {
+            this.resyncVisited = null;
+        }
+    }
+
     skipCurrentStructure(bytes: Uint8Array, it: Iterator, totalBytes: number) {
+        // 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.

package/src/decoder/ReferenceTracker.ts

@@ -20,6 +20,9 @@ class DecodingWarning extends Error {
 
 export type SchemaCallbacks = { [field: string | number]: Function[] };
 
+// Reused across addRef calls — saves a descriptor object per decoded ref.
+const $refIdDescriptor = { value: 0, enumerable: false, writable: true };
+
 export class ReferenceTracker {
     //
     // Relation of refId => Schema structure
@@ -45,11 +48,12 @@ export class ReferenceTracker {
         // on decoded instances, which WOULD walk enumerable Symbol-keyed
         // properties and include `$refId` in the comparison. Keep the
         // descriptor dance for semantic compatibility.
-        Object.defineProperty(ref, $refId, {
-            value: refId,
-            enumerable: false,
-            writable: true
-        });
+        if (ref[$refId] === undefined) {
+            $refIdDescriptor.value = refId;
+            Object.defineProperty(ref, $refId, $refIdDescriptor);
+        } else if (ref[$refId] !== refId) {
+            ref[$refId] = refId; // property exists (writable) — plain write keeps flags
+        }
 
         if (incrementCount) {
             this.refCount[refId] = (this.refCount[refId] || 0) + 1;

package/src/decoder/Resync.ts

@@ -0,0 +1,170 @@
+import { OPERATION } from "../encoding/spec.js";
+import { Schema } from "../Schema.js";
+import { $proxyTarget, $refId, $refTypeFieldIndexes, $resyncPrune, $transientFieldIndexes } from "../types/symbols.js";
+import type { Metadata } from "../Metadata.js";
+import type { Decoder } from "./Decoder.js";
+import type { DataChange } from "./DecodeOperation.js";
+
+/**
+ * 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.
+ */
+export function resyncTouchEntry(
+    decoder: Decoder,
+    ref: any,
+    operation: OPERATION,
+    identity: number | string,
+    previousValue: any,
+    value: any,
+    allChanges: DataChange[] | null,
+) {
+    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 === OPERATION.ADD && previousValue !== value) {
+        const previousRefId = previousValue[$refId];
+        if (previousRefId !== undefined) {
+            decoder.root.removeRef(previousRefId);
+            allChanges?.push({
+                ref,
+                refId: decoder.currentRefId,
+                op: 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.
+ */
+export function resyncMarkPresent(decoder: Decoder, refId: number) {
+    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.
+ */
+export function resyncSweep(decoder: Decoder, allChanges: DataChange[] | null) {
+    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 as unknown as Schema, new Set(), allChanges);
+}
+
+function sweepSchema(decoder: Decoder, ref: Schema, seen: Set<number>, allChanges: DataChange[] | null) {
+    const refId = (ref as any)[$refId];
+    if (refId === undefined || seen.has(refId)) { return; }
+    seen.add(refId);
+
+    const metadata: Metadata = (ref.constructor as typeof Schema)[Symbol.metadata];
+    const refIndexes = metadata?.[$refTypeFieldIndexes] as number[] | undefined;
+    if (refIndexes === undefined) { return; }
+    const transient = metadata[$transientFieldIndexes] as number[] | undefined;
+
+    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 as any)[field.name];
+        if (!value) { continue; }
+
+        if (Schema.is(field.type)) {
+            sweepSchema(decoder, value, seen, allChanges);
+        } else {
+            sweepCollection(decoder, value, seen, allChanges);
+        }
+    }
+}
+
+function sweepCollection(decoder: Decoder, coll: any, seen: Set<number>, allChanges: DataChange[] | null) {
+    const tgt: any = 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: any, identity: number | string) => {
+            allChanges?.push({
+                ref: coll,
+                refId,
+                op: OPERATION.DELETE,
+                dynamicIndex: identity,
+                value: undefined,
+                previousValue: value,
+            });
+            const childRefId = value?.[$refId];
+            if (childRefId !== undefined) { $root.removeRef(childRefId); }
+        },
+        (value: any) => {
+            // recurse so nested collections of retained entries sweep too
+            if (Schema.isSchema(value)) { sweepSchema(decoder, value, seen, allChanges); }
+        },
+    );
+}

package/src/encoder/ChangeTree.ts

@@ -127,6 +127,12 @@ export const IS_UNRELIABLE = 8, IS_TRANSIENT = 16, IS_STATIC = 32;
 // `t.map(X).stream()` / `t.set(X).stream()` route through the same
 // emission machinery.
 export 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.
+export 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
@@ -258,6 +264,8 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     set isStatic(v: boolean) { this.flags = v ? (this.flags | IS_STATIC) : (this.flags & ~IS_STATIC); }
     get isStreamCollection() { return (this.flags & IS_STREAM_COLLECTION) !== 0; }
     set isStreamCollection(v: boolean) { this.flags = v ? (this.flags | IS_STREAM_COLLECTION) : (this.flags & ~IS_STREAM_COLLECTION); }
+    get needsRestage() { return (this.flags & NEEDS_RESTAGE) !== 0; }
+    set needsRestage(v: boolean) { 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
@@ -532,6 +540,57 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         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(): void {
+        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: number): void {
         if (this._isSchema) throw new Error("ChangeTree (Schema): shift is not supported");
         const src = this.collDirty!;