@colyseus/schema 5.0.14 → 5.0.19

package/src/encoder/Encoder.ts

@@ -9,11 +9,12 @@ import type { Iterator } from "../encoding/decode.js";
 import { OPERATION, SWITCH_TO_STRUCTURE, TYPE_ID } from '../encoding/spec.js';
 import { Root } from "./Root.js";
 
-import type { StateView } from "./StateView.js";
+import { ARRAY_SNAPSHOT, type StateView } from "./StateView.js";
 import type { ChangeTree, ChangeTreeList, ChangeTreeNode } from "./ChangeTree.js";
 import type { EncodeOperation } from "./EncodeOperation.js";
 import { forEachLiveWithCtx as _forEachLiveWithCtx } from "./changeTree/liveIteration.js";
 import { forEachChildWithCtx as _forEachChildWithCtx } from "./changeTree/treeAttachment.js";
+import { drainFilterRefresh } from "./changeTree/inheritedFlags.js";
 
 /**
  * Reusable context passed to the recorder's forEachWithCtx to iterate changes
@@ -296,6 +297,10 @@ export class Encoder<T extends Schema = any> {
         initialOffset: number,
         unreliable: boolean,
     ): Uint8Array {
+        // Settle any pending per-edge filter re-derivations before routing
+        // fields to channels (see inheritedFlags.drainFilterRefresh).
+        if (this.root.pendingFilterRefresh.length > 0) drainFilterRefresh(this.root);
+
         const hasView = (view !== undefined);
         const rootChangeTree = this.state[$changes];
 
@@ -379,6 +384,9 @@ export class Encoder<T extends Schema = any> {
         view?: StateView,
         initialOffset: number = it.offset
     ): Uint8Array {
+        // Full-sync splits fields by the same isFiltered classification.
+        if (this.root.pendingFilterRefresh.length > 0) drainFilterRefresh(this.root);
+
         const hasView = (view !== undefined);
         const rootChangeTree = this.state[$changes];
 
@@ -521,7 +529,49 @@ export class Encoder<T extends Schema = any> {
 
             // Iterate entries directly — the inner Map gives us the (index, op)
             // pair without an intermediate keys array or Number() parse.
-            for (const [index, op] of changes) {
+            for (const [key, op] of changes) {
+                // Element-binding entries under a collection parent are keyed
+                // by the child's ChangeTree — resolve its CURRENT wire slot
+                // here (a slot captured at view.add() time goes stale when
+                // the array reindexes later in the same tick).
+                let index: number;
+                if (key === ARRAY_SNAPSHOT) {
+                    // Whole-array snapshot: emit an ADD per live element at
+                    // its CURRENT slot. Structural walk at drain time — a
+                    // reindex after view.add() cannot go stale, and staged
+                    // holes (recorder DELETEs) are skipped by construction.
+                    const tmpItems = refTarget.tmpItems;
+                    const deletedIndexes = refTarget.deletedIndexes;
+                    for (let slot = 0; slot < tmpItems.length; slot++) {
+                        if (tmpItems[slot] === undefined || deletedIndexes[slot] === true) { continue; }
+                        encoder(this, bytes, changeTree, slot, OPERATION.ADD, it, false, true, metadata);
+                    }
+                    continue;
+                }
+                if (typeof key === "number") {
+                    index = key;
+                } else {
+                    const resolved = key.indexInParent(ref);
+                    if (resolved === undefined) { continue; } // detached and re-parented elsewhere
+                    index = resolved;
+
+                    // SAME PATCH view.add + state-removal: the element is
+                    // leaving the array (recorder DELETE at its slot), so the
+                    // binding is moot — and `$getByIndex` on a staged hole
+                    // reads a DIFFERENT element (compacted `items`), which
+                    // would ship a mismatched value payload. Cancel the
+                    // binding AND the child's own pending entry (its refId
+                    // was never introduced to this client). Topological
+                    // drain order guarantees the child entry hasn't been
+                    // visited yet. A recorder ADD at the slot needs no such
+                    // guard — both channels emit ADD_BY_REFID and the
+                    // decoder dedups by identity.
+                    if (op === OPERATION.ADD && changeTree.getChange(index) === OPERATION.DELETE) {
+                        view.changes.delete(key.ref[$refId]);
+                        continue;
+                    }
+                }
+
                 // workaround when using view.add() on item that has been deleted from state
                 // (see test "adding to view item that has been removed from state")
                 const value = refTarget[$getByIndex](index);

package/src/encoder/Root.ts

@@ -1,6 +1,7 @@
 import { OPERATION } from "../encoding/spec.js";
 import { TypeContext } from "../types/TypeContext.js";
-import { ChangeTree, ChangeTreeList, createChangeTreeList, type ChangeTreeNode } from "./ChangeTree.js";
+import { ChangeTree, ChangeTreeList, createChangeTreeList, PENDING_FILTER_REFRESH, type ChangeTreeNode } from "./ChangeTree.js";
+import { restageLiveCb } from "./changeTree/liveIteration.js";
 import { $changes, $refId } from "../types/symbols.js";
 import type { StateView } from "./StateView.js";
 import type { StreamSchema } from "../types/custom/StreamSchema.js";
@@ -53,6 +54,22 @@ export class Root {
      */
     unreliableChanges: ChangeTreeList = createChangeTreeList();
 
+    /**
+     * Trees whose parent-edge set changed this tick (instance sharing
+     * gained or lost an edge). The encoder drains this before emission —
+     * `inheritedFlags.drainFilterRefresh` re-derives each tree's filter
+     * state against the then-settled containers. Only populated when the
+     * TypeContext has any @view/@stream field.
+     */
+    public pendingFilterRefresh: ChangeTree[] = [];
+
+    public enqueueFilterRefresh(tree: ChangeTree): void {
+        if (!this.types.hasFilters) return;
+        if (tree.flags & PENDING_FILTER_REFRESH) return;
+        tree.flags |= PENDING_FILTER_REFRESH;
+        this.pendingFilterRefresh.push(tree);
+    }
+
     /**
      * Free-list of ChangeTreeNode objects. Both queues share this pool —
      * a node carries no queue affinity, only `{ changeTree, prev, next, position }`.
@@ -172,17 +189,16 @@ export class Root {
             //   values would otherwise never be encoded).
             //
             changeTree.needsRestage = false;
-            changeTree.forEachLive((fieldIndex) => {
-                if (changeTree.isFieldUnreliable(fieldIndex)) {
-                    changeTree.ensureUnreliableRecorder().record(fieldIndex, OPERATION.ADD);
-                } else {
-                    changeTree.record(fieldIndex, OPERATION.ADD);
-                }
-            });
+            changeTree.forEachLiveWithCtx(changeTree, restageLiveCb);
         }
 
         this.refCount[refId] = (previousRefCount || 0) + 1;
 
+        // Gained a 2nd+ parent edge (instance sharing / re-assignment) —
+        // re-derive filter state before the next encode. Chokepoint for
+        // every attach path; mirrors the edge-loss enqueue in `remove()`.
+        if (previousRefCount > 0) this.enqueueFilterRefresh(changeTree);
+
         return isNewChangeTree;
     }
 
@@ -229,6 +245,10 @@ export class Root {
         } else {
             this.refCount[refId] = refCount;
 
+            // Lost one of several parent edges — the surviving edge set may
+            // no longer include a public path (or may have gained one).
+            this.enqueueFilterRefresh(changeTree);
+
             //
             // When losing a reference to an instance, it is best to move the
             // ChangeTree next to its parent in the encoding queue.

package/src/encoder/StateView.ts

@@ -1,5 +1,5 @@
 import { ChangeTree, Ref } from "./ChangeTree.js";
-import { $changes, $fieldIndexesByViewTag, $refId, $viewFieldIndexes } from "../types/symbols.js";
+import { $changes, $childType, $fieldIndexesByViewTag, $refId, $viewFieldIndexes } from "../types/symbols.js";
 import { DEFAULT_VIEW_TAG } from "../annotations.js";
 import { OPERATION } from "../encoding/spec.js";
 import { Metadata } from "../Metadata.js";
@@ -61,6 +61,16 @@ const _disposeRegistry = new FinalizationRegistry<{ root: Root; id: number; slot
  * populated collection inspects into dozens of lines of encoder
  * internals and buries the message that matters.
  */
+/**
+ * Sentinel inner-map key: "snapshot every live element of this ref-typed
+ * ArraySchema". Written by `_add`'s bulk path instead of one entry per
+ * element; `encodeView` expands it structurally at drain time, so the
+ * emitted slots reflect any reindex that happened after `view.add()` —
+ * and a whole-array snapshot costs one Map insert instead of N.
+ * Real slots are never negative, so -1 cannot collide.
+ */
+export const ARRAY_SNAPSHOT = -1;
+
 function describeArg(value: any): string {
     if (value === undefined) { return "undefined"; }
     if (value === null) { return "null"; }
@@ -107,8 +117,16 @@ export class StateView {
      * Inner storage is a Map so the encode loop in `encodeView` can iterate
      * directly with numeric keys — the legacy `{[index]: OPERATION}` shape
      * forced an `Object.keys(...)` allocation + `Number(key)` parse per ref.
+     *
+     * Inner keys are numbers (Schema field indexes, MapSchema journal
+     * indexes, Set/Collection indexes, stream positions — all stable within
+     * a tick), EXCEPT element bindings under a ref-typed ArraySchema parent,
+     * which are keyed by the child's ChangeTree. An array wire slot captured
+     * at `view.add()` time goes stale if the array reindexes (unshift /
+     * reverse / move) later in the same tick — identity keys let
+     * `encodeView` resolve the CURRENT slot at drain time instead.
      */
-    changes = new Map<number, Map<number, OPERATION>>();
+    changes = new Map<number, Map<number | ChangeTree, OPERATION>>();
 
     constructor(public iterable: boolean = false) {
         if (iterable) {
@@ -368,15 +386,18 @@ export class StateView {
         // subclasses yield a real Metadata object.
         const metadata: Metadata = (obj.constructor as typeof Schema)[Symbol.metadata];
 
+        const wasVisible = this.isVisible(changeTree);
+
         // Add to iterable list (only the explicitly added items), deduping
-        // re-adds of an already-visible instance. isVisible must be read
-        // BEFORE markVisible; indexOf runs only on the re-add path.
-        // NOTE: dedup applies to `items` only — a re-add still re-queues the
-        // full snapshot on purpose (shared-view bootstrap re-add: a
-        // late-attached client may not have consumed earlier drains).
-        // Callers wanting cheap idempotence can guard with `view.has(obj)`.
+        // re-adds of an already-visible instance; indexOf runs only on the
+        // re-add path.
+        // NOTE: dedup applies to `items` only — a default-tag re-add still
+        // re-queues the full snapshot on purpose (shared-view bootstrap
+        // re-add: a late-attached client may not have consumed earlier
+        // drains). Callers wanting cheap idempotence can guard with
+        // `view.has(obj)`.
         if (this.iterable && checkIncludeParent
-            && (!this.isVisible(changeTree) || this.items.indexOf(obj) === -1)) {
+            && (!wasVisible || this.items.indexOf(obj) === -1)) {
             this.items.push(obj);
         }
 
@@ -469,32 +490,51 @@ export class StateView {
                     });
                 }
             }
+        }
 
-        } else if (!changeTree.isNew || isChildAdded) {
-            // new structures will be added as part of .encode() call, no need to force it to .encodeView()
-
-            // Full-sync snapshot: walk the live ref structurally instead of
-            // iterating a cumulative recorder bucket. Every populated index
-            // is emitted as ADD (matching the op-coercion previously done
-            // at encode time). Per-field tags come from the descriptor's
-            // precomputed `tags[]` array — direct index vs a metadata[i].tag
-            // object hop.
-            //
-            // Non-matching custom-tagged fields are NEVER included here —
-            // `view.changes` is drained without a per-field tag re-check,
-            // so anything added leaks straight to the wire.
-            const tags = changeTree.encDescriptor.tags;
-            changeTree.forEachLive((index) => {
-                const tagAtIndex = tags[index];
-                if (
-                    tagAtIndex === undefined || // "all change" with no tag
-                    tagAtIndex === DEFAULT_VIEW_TAG || // visible to all clients
-                    (tag !== DEFAULT_VIEW_TAG && (tagAtIndex & tag) !== 0) // tag bits overlap
-                ) {
-                    changes.set(index, OPERATION.ADD);
+        // Full-sync snapshot of a non-new tree (fresh ones ship via .encode()).
+        // Also runs for custom tags when bootstrapping the tree for this view
+        // (!wasVisible) — the per-field filter admits untagged fields, and
+        // collections behind tagged fields have no `byTag`: without the
+        // snapshot their elements are never introduced ("refId" not found).
+        // A tagged add on an already-visible tree stays incremental (byTag
+        // only); default-tag re-adds re-snapshot on purpose (see `items`
+        // dedup note above).
+        if ((tag === DEFAULT_VIEW_TAG || !wasVisible) && (!changeTree.isNew || isChildAdded)) {
+            if (changeTree.isArray && typeof (changeTree.refTarget as any)[$childType] !== "string") {
+                // Ref-typed ArraySchema (the only proxied collection): one
+                // sentinel entry — encodeView snapshots the live elements at
+                // drain time, so the slots survive a same-tick reindex (see
+                // `changes` field docs) and the write stays O(1).
+                if ((changeTree.refTarget as any).items.length > 0) {
+                    changes.set(ARRAY_SNAPSHOT, OPERATION.ADD);
                     isChildAdded = true;
                 }
-            });
+
+            } else {
+                // Full-sync snapshot: walk the live ref structurally instead of
+                // iterating a cumulative recorder bucket. Every populated index
+                // is emitted as ADD (matching the op-coercion previously done
+                // at encode time). Per-field tags come from the descriptor's
+                // precomputed `tags[]` array — direct index vs a metadata[i].tag
+                // object hop.
+                //
+                // Non-matching custom-tagged fields are NEVER included here —
+                // `view.changes` is drained without a per-field tag re-check,
+                // so anything added leaks straight to the wire.
+                const tags = changeTree.encDescriptor.tags;
+                changeTree.forEachLive((index) => {
+                    const tagAtIndex = tags[index];
+                    if (
+                        tagAtIndex === undefined || // "all change" with no tag
+                        tagAtIndex === DEFAULT_VIEW_TAG || // visible to all clients
+                        (tag !== DEFAULT_VIEW_TAG && (tagAtIndex & tag) !== 0) // tag bits overlap
+                    ) {
+                        changes.set(index, OPERATION.ADD);
+                        isChildAdded = true;
+                    }
+                });
+            }
         }
 
         return isChildAdded;
@@ -575,13 +615,21 @@ export class StateView {
         if (changeTree.getChange(parentIndex) !== OPERATION.DELETE) {
             let changes = this.changes.get(changeTree.ref[$refId]);
             if (changes === undefined) {
-                changes = new Map<number, OPERATION>();
+                changes = new Map<number | ChangeTree, OPERATION>();
                 this.changes.set(changeTree.ref[$refId], changes);
             }
 
             this.addTag(changeTree, tag);
 
-            changes.set(parentIndex, OPERATION.ADD);
+            // ArraySchema parents: key by the child's identity, not the wire
+            // slot it holds right now — a same-tick unshift()/reverse()/move()
+            // would shift the slot before encodeView drains this entry. Other
+            // parents keep numeric keys (Schema fields, MapSchema journal
+            // indexes and Set/Collection indexes are stable within a tick).
+            changes.set(
+                changeTree.isArray ? childChangeTree : parentIndex,
+                OPERATION.ADD,
+            );
         }
     }
 
@@ -641,8 +689,8 @@ export class StateView {
         // out of the stream's per-view state. If it never made it to the
         // wire (still in pending), silent drop; if already sent, queue
         // DELETE via `view.changes` for the next encodeView drain.
-        const parentStreamTree = changeTree.parent?.[$changes];
-        if (parentStreamTree?.isStreamCollection) {
+        const parentTree = changeTree.parent?.[$changes];
+        if (parentTree?.isStreamCollection) {
             this.unmarkVisible(changeTree);
             if (this.iterable && !_isClear) {
                 spliceOne(this.items, this.items.indexOf(obj));
@@ -718,59 +766,46 @@ export class StateView {
             // parent is collection (Map/Array)
             const parent = changeTree.parent;
             if (parent && !Metadata.isValidInstance(parent) && changeTree.isFiltered) {
+                // ArraySchema parents use identity keys (see `changes` field
+                // docs); Map parents keep the (stable) journal index.
+                const key = parentTree!.isArray
+                    ? changeTree
+                    : changeTree.parentIndex;
                 const parentRefId = parent[$refId];
                 let changes = this.changes.get(parentRefId);
                 if (changes === undefined) {
-                    changes = new Map<number, OPERATION>();
+                    changes = new Map<number | ChangeTree, OPERATION>();
                     this.changes.set(parentRefId, changes);
 
-                } else if (changes.get(changeTree.parentIndex) === OPERATION.ADD) {
+                } else if (changes.get(key) === OPERATION.ADD) {
                     //
                     // SAME PATCH ADD + REMOVE:
-                    // The 'changes' of deleted structure should be ignored.
+                    // cancel the structure's pending ops and its descendants' —
+                    // their introduction never reaches this client.
                     //
-                    this.changes.delete(refId);
+                    this._dropPendingEntries(changeTree);
                 }
 
                 // DELETE / DELETE BY REF ID
-                changes.set(changeTree.parentIndex, OPERATION.DELETE);
+                changes.set(key, OPERATION.DELETE);
 
                 // Remove child schema from visible set
                 this._recursiveDeleteVisibleChangeTree(changeTree);
 
             } else {
                 // delete all "tagged" properties.
-                const names = changeTree.encDescriptor.names;
-                metadata?.[$viewFieldIndexes]?.forEach((index) => {
-                    changes.set(index, OPERATION.DELETE);
-
-                    // Remove child structures of @view() fields from visible set.
-                    // (They were added during view.add() via forEachChild)
-                    const value = changeTree.ref[names[index] as keyof Ref];
-                    if (value?.[$changes]) {
-                        this.unmarkVisible(value[$changes]);
-                        this._recursiveDeleteVisibleChangeTree(value[$changes]);
-                    }
-                });
+                metadata?.[$viewFieldIndexes]?.forEach((index) =>
+                    this._removeViewField(changeTree, changes, index));
             }
 
         } else {
             // delete only tagged properties. `$fieldIndexesByViewTag` is
             // keyed per-bit, so a combined tag iterates each set bit.
-            const names = changeTree.encDescriptor.names;
             const byTag = metadata?.[$fieldIndexesByViewTag];
             if (byTag !== undefined) {
                 for (let bits = tag; bits > 0; bits &= bits - 1) {
-                    byTag[bits & -bits]?.forEach((index) => {
-                        changes.set(index, OPERATION.DELETE);
-
-                        // Remove child structures from visible set
-                        const value = changeTree.ref[names[index] as keyof Ref];
-                        if (value?.[$changes]) {
-                            this.unmarkVisible(value[$changes]);
-                            this._recursiveDeleteVisibleChangeTree(value[$changes]);
-                        }
-                    });
+                    byTag[bits & -bits]?.forEach((index) =>
+                        this._removeViewField(changeTree, changes, index));
                 }
             }
         }
@@ -956,14 +991,16 @@ export class StateView {
         } else {
             // Non-streams: queue DELETE for every current child and
             // unmark their visibility so subsequent mutations stop
-            // reaching this view.
+            // reaching this view. ArraySchema children are keyed by identity
+            // (see `changes` field docs); others by their stable index.
+            const isArray = tree.isArray;
             let changes = this.changes.get(collectionRefId);
             tree.forEachChild((childTree, index) => {
                 if (changes === undefined) {
                     changes = new Map();
                     this.changes.set(collectionRefId, changes);
                 }
-                changes.set(index, OPERATION.DELETE);
+                changes.set(isArray ? childTree : index, OPERATION.DELETE);
                 this.unmarkVisible(childTree);
             });
         }
@@ -999,9 +1036,24 @@ export class StateView {
         // `markVisible` memoizes so the branch fires at most once per
         // (tree, view) pair.
         if (!isVisible && changeTree.isVisibilitySharedWithParent){
+            // Primary grant is intentionally unguarded — pre-existing
+            // semantics; the extras walk below is stricter on purpose.
             if (this.isVisible(changeTree.parent[$changes])) {
                 this.markVisible(changeTree);
                 isVisible = true;
+            } else {
+                // Shared instance: the sharing parent may sit anywhere in the
+                // chain — addParent promotes the LAST container to primary.
+                // Only filtered parents can grant (public ones never share
+                // visibility downward).
+                for (let e = changeTree.extraParents; e !== undefined; e = e.next) {
+                    const parentTree = e.ref[$changes];
+                    if (parentTree.isFiltered && this.isVisible(parentTree)) {
+                        this.markVisible(changeTree);
+                        isVisible = true;
+                        break;
+                    }
+                }
             }
         }
 
@@ -1014,4 +1066,36 @@ export class StateView {
             this._recursiveDeleteVisibleChangeTree(childChangeTree);
         });
     }
+
+    /**
+     * Drop the pending `view.changes` entries of `tree` and every descendant.
+     * Called when a same-patch pending ADD is cancelled: the subtree's
+     * introduction never reaches this client, so its entries would emit
+     * refIds the decoder cannot resolve ("refId" not found).
+     */
+    private _dropPendingEntries(tree: ChangeTree): void {
+        this.changes.delete(tree.ref[$refId]);
+        tree.forEachChild((child) => this._dropPendingEntries(child));
+    }
+
+    /**
+     * Queue DELETE for a @view field on `changes` and hide the field
+     * value's subtree from this view. When the field's ADD is still
+     * pending (same-patch add + remove), the value's introduction never
+     * ships — its pending subtree entries are dropped along with it.
+     */
+    private _removeViewField(changeTree: ChangeTree, changes: Map<number | ChangeTree, OPERATION>, index: number): void {
+        const wasPendingAdd = changes.get(index) === OPERATION.ADD;
+        changes.set(index, OPERATION.DELETE);
+
+        const value = changeTree.ref[changeTree.encDescriptor.names[index] as keyof Ref];
+        const valueTree: ChangeTree = value?.[$changes];
+        if (valueTree) {
+            this.unmarkVisible(valueTree);
+            this._recursiveDeleteVisibleChangeTree(valueTree);
+            if (wasPendingAdd) {
+                this._dropPendingEntries(valueTree);
+            }
+        }
+    }
 }