@colyseus/schema 5.0.3 → 5.0.5

package/build/index.js

@@ -2114,11 +2114,24 @@
             const refType = Metadata.isValidInstance(tree.ref)
                 ? tree.ref.constructor
                 : tree.ref[$childType];
+            // #218: nested Schema fields inherit visibility from a @view-gated
+            // parent regardless of whether the parent is a collection. The
+            // `parentIsCollection` constraint that used to live here blocked
+            // nested-Schema-field-of-@view-tagged-Schema from sharing visibility,
+            // forcing users to wrap the child in an ArraySchema as a workaround.
+            //
+            // #226 (4.0.25): items inside a non-default-tag `@view(N)` collection
+            // also inherit visibility from the parent collection, so items
+            // pushed/set after `view.add(state, N)` show up automatically.
+            // Default-tag `@view()` collections keep per-item gating —
+            // `view.add(item)` is still required to opt each one in.
+            // The `parentMetadata[parentIndex].tag` access is safe inside the
+            // `fieldHasViewTag` short-circuit (the metadata entry and its `tag`
+            // are guaranteed to exist when that flag is set).
             tree.isVisibilitySharedWithParent = (parentChangeTree.isFiltered
                 && typeof refType !== "string"
-                && !fieldHasViewTag
                 && !fieldHasStream
-                && parentIsCollection);
+                && (!fieldHasViewTag || (parentIsCollection && parentMetadata[parentIndex].tag !== DEFAULT_VIEW_TAG)));
         }
     }
 
@@ -5451,8 +5464,10 @@
      */
     class FieldBuilder {
         [$builder] = true;
-        // Internal configuration. Public so schema() and tests can read it, but not
-        // meant to be mutated by users directly.
+        // Internal configuration. Declared `private` (soft-private): hidden from
+        // editor autocomplete and from normal external `.field` access, but still
+        // reachable at runtime via element access (e.g. `builder['_noSync']`) for
+        // internal tooling/tests. Not meant to be mutated by end users.
         _type;
         _default = undefined;
         _hasDefault = false;
@@ -5465,6 +5480,7 @@
         _static = false;
         _stream = false;
         _optional = false;
+        _noSync = false;
         _streamPriority = undefined;
         constructor(type) {
             this._type = type;
@@ -5515,6 +5531,30 @@
             this._static = true;
             return this;
         }
+        /**
+         * Mark this field as **local-only** — it is typed and initialized on the
+         * instance (so `.default()` and the inferred instance type still apply),
+         * but is never registered for synchronization: it never enters change
+         * tracking, never goes over the wire, and decoders never receive it.
+         *
+         * Useful for server-side scratch state, per-peer UI state, or values you
+         * want on the class for typing convenience without paying any sync cost.
+         *
+         * Mutually exclusive with the sync-only modifiers (`.view()`, `.owned()`,
+         * `.unreliable()`, `.transient()`, `.static()`, `.stream()`) — combining
+         * them throws at `schema()` time.
+         *
+         * ```ts
+         * const Player = schema({
+         *     hp: t.uint8().default(100),          // synchronized
+         *     lastInputTick: t.number().noSync(),  // local-only
+         * }, 'Player');
+         * ```
+         */
+        noSync() {
+            this._noSync = true;
+            return this;
+        }
         /**
          * Opt a collection field into priority-batched streaming delivery —
          * ADDs drain at most `maxPerTick` per tick per view (or per broadcast
@@ -5569,6 +5609,11 @@
             this._optional = true;
             return this;
         }
+        /**
+         * @internal — snapshot of the builder's configuration consumed by
+         * `schema()`. `private` keeps it out of autocomplete; internal callers
+         * reach it via element access (`builder['toDefinition']()`).
+         */
         toDefinition() {
             return {
                 type: this._type,
@@ -5583,6 +5628,7 @@
                 static: this._static,
                 stream: this._stream,
                 optional: this._optional,
+                noSync: this._noSync,
                 streamPriority: this._streamPriority,
             };
         }
@@ -5590,15 +5636,13 @@
     function isBuilder(value) {
         return value != null && value[$builder] === true;
     }
-    // ---------------------------------------------------------------------------
-    // Factory helpers
-    // ---------------------------------------------------------------------------
     function primitive(name) {
-        return () => new FieldBuilder(name);
+        return (() => new FieldBuilder(name));
     }
     function resolveChild(child) {
         if (isBuilder(child)) {
-            return child._type;
+            // `_type` is private; element access bypasses the visibility check.
+            return child['_type'];
         }
         return child;
     }
@@ -5608,7 +5652,7 @@
     const collectionFactory = ((child) => new FieldBuilder({ collection: resolveChild(child) }));
     const streamFactory = ((child) => {
         const b = new FieldBuilder({ stream: resolveChild(child) });
-        b._stream = true;
+        b['_stream'] = true; // element access bypasses `private`
         return b;
     });
     const refFactory = ((ctor) => new FieldBuilder(ctor));
@@ -6037,6 +6081,36 @@
             });
         };
     }
+    /**
+     * 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.
+     */
+    function autoInstantiateDefault(rawType) {
+        if (rawType && typeof rawType === "object") {
+            if (rawType.array !== undefined) {
+                return new ArraySchema();
+            }
+            if (rawType.map !== undefined) {
+                return new MapSchema();
+            }
+            if (rawType.set !== undefined) {
+                return new SetSchema();
+            }
+            if (rawType.collection !== undefined) {
+                return new CollectionSchema();
+            }
+            if (rawType.stream !== undefined) {
+                return new StreamSchema();
+            }
+        }
+        else if (typeof rawType === "function" && Schema.is(rawType)) {
+            if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
+                return new rawType();
+            }
+        }
+        return undefined;
+    }
     /**
      * Define a Schema class declaratively.
      *
@@ -6072,7 +6146,28 @@
         for (const fieldName in fieldsAndMethods) {
             const value = fieldsAndMethods[fieldName];
             if (isBuilder(value)) {
-                const def = value.toDefinition();
+                const def = value['toDefinition'](); // private; element access bypasses visibility
+                if (def.noSync) {
+                    // Local-only field: skip metadata registration entirely so it is
+                    // never encoded/decoded, but still seed its construction default
+                    // (honoring `.default()` and collection/ref auto-instantiation).
+                    if (def.view !== undefined || def.owned || def.unreliable ||
+                        def.transient || def.static || def.stream) {
+                        throw new Error(`schema(${name ? `'${name}'` : ""}): field '${fieldName}' uses .noSync() ` +
+                            `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;
+                        }
+                    }
+                    continue;
+                }
                 fields[fieldName] = getNormalizedType(def.type);
                 if (def.view !== undefined) {
                     viewTagFields[fieldName] = def.view;
@@ -6107,28 +6202,9 @@
                 else if (!def.optional) {
                     // Auto-instantiate collection/Schema defaults when none is provided.
                     // `.optional()` opts out — field starts as undefined.
-                    const rawType = def.type;
-                    if (rawType && typeof rawType === "object") {
-                        if (rawType.array !== undefined) {
-                            defaultValues[fieldName] = new ArraySchema();
-                        }
-                        else if (rawType.map !== undefined) {
-                            defaultValues[fieldName] = new MapSchema();
-                        }
-                        else if (rawType.set !== undefined) {
-                            defaultValues[fieldName] = new SetSchema();
-                        }
-                        else if (rawType.collection !== undefined) {
-                            defaultValues[fieldName] = new CollectionSchema();
-                        }
-                        else if (rawType.stream !== undefined) {
-                            defaultValues[fieldName] = new StreamSchema();
-                        }
-                    }
-                    else if (typeof rawType === "function" && Schema.is(rawType)) {
-                        if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
-                            defaultValues[fieldName] = new rawType();
-                        }
+                    const autoDefault = autoInstantiateDefault(def.type);
+                    if (autoDefault !== undefined) {
+                        defaultValues[fieldName] = autoDefault;
                     }
                 }
             }
@@ -7367,8 +7443,19 @@
             // selected element is passed to `view.add()` which populates
             // view.changes with the stream-link ADD + element-field ADDs.
             this._emitStreamPriority(view);
-            // encode visibility-triggered changes collected by view.add()
-            for (const [refId, changes] of view.changes) {
+            //
+            // `view.changes` Map insertion order IS topological order:
+            //   - `view.add` walks the parent chain to root via `addParentOf`
+            //     (depth-first ancestor-first), inserting every ancestor's
+            //     entry before the descendant's.
+            //   - `view.remove` calls `_touchAncestorsOf` before its own
+            //     write to insert any missing ancestors at the front of the
+            //     chain — empty entries that get skipped by the size==0
+            //     check below but establish Map position.
+            // No per-encode topo sort needed.
+            //
+            for (const refId of view.changes.keys()) {
+                const changes = view.changes.get(refId);
                 const changeTree = this.root.changeTrees[refId];
                 if (changeTree === undefined) {
                     // detached instance, remove from view and skip.
@@ -8770,6 +8857,7 @@
             else if ('decoder' in roomOrDecoder.serializer) {
                 return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
             }
+            throw new Error('Invalid room or decoder');
         },
         getRawChanges(decoder, callback) {
             return getRawChangesCallback(decoder, callback);
@@ -9225,12 +9313,27 @@
             if (!this.isVisible(changeTree)) {
                 // view must have all "changeTree" parent tree
                 this.markVisible(changeTree);
-                // add parent's parent
+                // 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 && parentChangeTree.hasFilteredFields) {
+                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
+            // an extra ADD on a non-filtered field's index would only emit
+            // bytes for a no-op (`value === previousValue` on the decoder).
+            if (!changeTree.hasFilteredFields)
+                return;
             // add parent's tag properties
             if (changeTree.getChange(parentIndex) !== exports.OPERATION.DELETE) {
                 let changes = this.changes.get(changeTree.ref[$refId]);
@@ -9242,6 +9345,45 @@
                 changes.set(parentIndex, exports.OPERATION.ADD);
             }
         }
+        /**
+         * Walk `tree`'s parent chain to root and insert an empty entry into
+         * `view.changes` for any ancestor not already present. Empty entries
+         * are skipped by `encodeView` (`changes.size === 0` continue), so no
+         * wire bytes are emitted — but the Map's insertion order now puts
+         * each ancestor BEFORE the descendant entry that the caller is about
+         * to write. Combined with `addParentOf`'s full-recursion walk on
+         * `view.add`, this preserves the global invariant that
+         * `view.changes` iteration order is topological.
+         *
+         * Iterative (not recursive) so the stack is bounded by tree depth
+         * regardless of call patterns. Stops the walk as soon as it hits an
+         * ancestor that's already in `view.changes` — at that point the
+         * remainder of the chain is guaranteed to also be present (invariant
+         * upheld by every prior caller).
+         */
+        _touchAncestorsOf(tree) {
+            let cursor = tree.parent?.[$changes];
+            if (cursor === undefined)
+                return;
+            // Collect the missing prefix of the chain, deepest-first. Only
+            // FILTERED ancestors need entries — non-filtered ones never
+            // appear in `view.changes` (mirrors the addParentOf gate), so
+            // they don't need a Map slot reserved either.
+            const stack = [];
+            while (cursor !== undefined) {
+                if (cursor.hasFilteredFields) {
+                    const refId = cursor.ref[$refId];
+                    if (this.changes.has(refId))
+                        break;
+                    stack.push(cursor);
+                }
+                cursor = cursor.parent?.[$changes];
+            }
+            // Insert root-first so Map order is topological.
+            for (let i = stack.length - 1; i >= 0; i--) {
+                this.changes.set(stack[i].ref[$refId], new Map());
+            }
+        }
         remove(obj, tag = DEFAULT_VIEW_TAG, _isClear = false) {
             const changeTree = obj[$changes];
             if (!changeTree) {
@@ -9302,6 +9444,11 @@
             const ref = changeTree.ref;
             const metadata = ref.constructor[Symbol.metadata]; // ArraySchema/MapSchema do not have metadata
             const refId = ref[$refId];
+            // Pre-insert any missing ancestors into view.changes so the Map's
+            // iteration order stays topological — the entries we're about to
+            // write (either on this obj, or on its parent collection below)
+            // must come AFTER every ancestor in the chain on the wire.
+            this._touchAncestorsOf(changeTree);
             let changes = this.changes.get(refId);
             if (changes === undefined) {
                 changes = new Map();

package/build/index.mjs

@@ -2108,11 +2108,24 @@ function checkInheritedFlags(tree, parent, parentIndex) {
         const refType = Metadata.isValidInstance(tree.ref)
             ? tree.ref.constructor
             : tree.ref[$childType];
+        // #218: nested Schema fields inherit visibility from a @view-gated
+        // parent regardless of whether the parent is a collection. The
+        // `parentIsCollection` constraint that used to live here blocked
+        // nested-Schema-field-of-@view-tagged-Schema from sharing visibility,
+        // forcing users to wrap the child in an ArraySchema as a workaround.
+        //
+        // #226 (4.0.25): items inside a non-default-tag `@view(N)` collection
+        // also inherit visibility from the parent collection, so items
+        // pushed/set after `view.add(state, N)` show up automatically.
+        // Default-tag `@view()` collections keep per-item gating —
+        // `view.add(item)` is still required to opt each one in.
+        // The `parentMetadata[parentIndex].tag` access is safe inside the
+        // `fieldHasViewTag` short-circuit (the metadata entry and its `tag`
+        // are guaranteed to exist when that flag is set).
         tree.isVisibilitySharedWithParent = (parentChangeTree.isFiltered
             && typeof refType !== "string"
-            && !fieldHasViewTag
             && !fieldHasStream
-            && parentIsCollection);
+            && (!fieldHasViewTag || (parentIsCollection && parentMetadata[parentIndex].tag !== DEFAULT_VIEW_TAG)));
     }
 }
 
@@ -5445,8 +5458,10 @@ registerType("stream", { constructor: StreamSchema });
  */
 class FieldBuilder {
     [$builder] = true;
-    // Internal configuration. Public so schema() and tests can read it, but not
-    // meant to be mutated by users directly.
+    // Internal configuration. Declared `private` (soft-private): hidden from
+    // editor autocomplete and from normal external `.field` access, but still
+    // reachable at runtime via element access (e.g. `builder['_noSync']`) for
+    // internal tooling/tests. Not meant to be mutated by end users.
     _type;
     _default = undefined;
     _hasDefault = false;
@@ -5459,6 +5474,7 @@ class FieldBuilder {
     _static = false;
     _stream = false;
     _optional = false;
+    _noSync = false;
     _streamPriority = undefined;
     constructor(type) {
         this._type = type;
@@ -5509,6 +5525,30 @@ class FieldBuilder {
         this._static = true;
         return this;
     }
+    /**
+     * Mark this field as **local-only** — it is typed and initialized on the
+     * instance (so `.default()` and the inferred instance type still apply),
+     * but is never registered for synchronization: it never enters change
+     * tracking, never goes over the wire, and decoders never receive it.
+     *
+     * Useful for server-side scratch state, per-peer UI state, or values you
+     * want on the class for typing convenience without paying any sync cost.
+     *
+     * Mutually exclusive with the sync-only modifiers (`.view()`, `.owned()`,
+     * `.unreliable()`, `.transient()`, `.static()`, `.stream()`) — combining
+     * them throws at `schema()` time.
+     *
+     * ```ts
+     * const Player = schema({
+     *     hp: t.uint8().default(100),          // synchronized
+     *     lastInputTick: t.number().noSync(),  // local-only
+     * }, 'Player');
+     * ```
+     */
+    noSync() {
+        this._noSync = true;
+        return this;
+    }
     /**
      * Opt a collection field into priority-batched streaming delivery —
      * ADDs drain at most `maxPerTick` per tick per view (or per broadcast
@@ -5563,6 +5603,11 @@ class FieldBuilder {
         this._optional = true;
         return this;
     }
+    /**
+     * @internal — snapshot of the builder's configuration consumed by
+     * `schema()`. `private` keeps it out of autocomplete; internal callers
+     * reach it via element access (`builder['toDefinition']()`).
+     */
     toDefinition() {
         return {
             type: this._type,
@@ -5577,6 +5622,7 @@ class FieldBuilder {
             static: this._static,
             stream: this._stream,
             optional: this._optional,
+            noSync: this._noSync,
             streamPriority: this._streamPriority,
         };
     }
@@ -5584,15 +5630,13 @@ class FieldBuilder {
 function isBuilder(value) {
     return value != null && value[$builder] === true;
 }
-// ---------------------------------------------------------------------------
-// Factory helpers
-// ---------------------------------------------------------------------------
 function primitive(name) {
-    return () => new FieldBuilder(name);
+    return (() => new FieldBuilder(name));
 }
 function resolveChild(child) {
     if (isBuilder(child)) {
-        return child._type;
+        // `_type` is private; element access bypasses the visibility check.
+        return child['_type'];
     }
     return child;
 }
@@ -5602,7 +5646,7 @@ const setFactory = ((child) => new FieldBuilder({ set: resolveChild(child) }));
 const collectionFactory = ((child) => new FieldBuilder({ collection: resolveChild(child) }));
 const streamFactory = ((child) => {
     const b = new FieldBuilder({ stream: resolveChild(child) });
-    b._stream = true;
+    b['_stream'] = true; // element access bypasses `private`
     return b;
 });
 const refFactory = ((ctor) => new FieldBuilder(ctor));
@@ -6031,6 +6075,36 @@ function deprecated(throws = true) {
         });
     };
 }
+/**
+ * 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.
+ */
+function autoInstantiateDefault(rawType) {
+    if (rawType && typeof rawType === "object") {
+        if (rawType.array !== undefined) {
+            return new ArraySchema();
+        }
+        if (rawType.map !== undefined) {
+            return new MapSchema();
+        }
+        if (rawType.set !== undefined) {
+            return new SetSchema();
+        }
+        if (rawType.collection !== undefined) {
+            return new CollectionSchema();
+        }
+        if (rawType.stream !== undefined) {
+            return new StreamSchema();
+        }
+    }
+    else if (typeof rawType === "function" && Schema.is(rawType)) {
+        if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
+            return new rawType();
+        }
+    }
+    return undefined;
+}
 /**
  * Define a Schema class declaratively.
  *
@@ -6066,7 +6140,28 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
     for (const fieldName in fieldsAndMethods) {
         const value = fieldsAndMethods[fieldName];
         if (isBuilder(value)) {
-            const def = value.toDefinition();
+            const def = value['toDefinition'](); // private; element access bypasses visibility
+            if (def.noSync) {
+                // Local-only field: skip metadata registration entirely so it is
+                // never encoded/decoded, but still seed its construction default
+                // (honoring `.default()` and collection/ref auto-instantiation).
+                if (def.view !== undefined || def.owned || def.unreliable ||
+                    def.transient || def.static || def.stream) {
+                    throw new Error(`schema(${name ? `'${name}'` : ""}): field '${fieldName}' uses .noSync() ` +
+                        `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;
+                    }
+                }
+                continue;
+            }
             fields[fieldName] = getNormalizedType(def.type);
             if (def.view !== undefined) {
                 viewTagFields[fieldName] = def.view;
@@ -6101,28 +6196,9 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
             else if (!def.optional) {
                 // Auto-instantiate collection/Schema defaults when none is provided.
                 // `.optional()` opts out — field starts as undefined.
-                const rawType = def.type;
-                if (rawType && typeof rawType === "object") {
-                    if (rawType.array !== undefined) {
-                        defaultValues[fieldName] = new ArraySchema();
-                    }
-                    else if (rawType.map !== undefined) {
-                        defaultValues[fieldName] = new MapSchema();
-                    }
-                    else if (rawType.set !== undefined) {
-                        defaultValues[fieldName] = new SetSchema();
-                    }
-                    else if (rawType.collection !== undefined) {
-                        defaultValues[fieldName] = new CollectionSchema();
-                    }
-                    else if (rawType.stream !== undefined) {
-                        defaultValues[fieldName] = new StreamSchema();
-                    }
-                }
-                else if (typeof rawType === "function" && Schema.is(rawType)) {
-                    if (!rawType.prototype.initialize || rawType.prototype.initialize.length === 0) {
-                        defaultValues[fieldName] = new rawType();
-                    }
+                const autoDefault = autoInstantiateDefault(def.type);
+                if (autoDefault !== undefined) {
+                    defaultValues[fieldName] = autoDefault;
                 }
             }
         }
@@ -7361,8 +7437,19 @@ class Encoder {
         // selected element is passed to `view.add()` which populates
         // view.changes with the stream-link ADD + element-field ADDs.
         this._emitStreamPriority(view);
-        // encode visibility-triggered changes collected by view.add()
-        for (const [refId, changes] of view.changes) {
+        //
+        // `view.changes` Map insertion order IS topological order:
+        //   - `view.add` walks the parent chain to root via `addParentOf`
+        //     (depth-first ancestor-first), inserting every ancestor's
+        //     entry before the descendant's.
+        //   - `view.remove` calls `_touchAncestorsOf` before its own
+        //     write to insert any missing ancestors at the front of the
+        //     chain — empty entries that get skipped by the size==0
+        //     check below but establish Map position.
+        // No per-encode topo sort needed.
+        //
+        for (const refId of view.changes.keys()) {
+            const changes = view.changes.get(refId);
             const changeTree = this.root.changeTrees[refId];
             if (changeTree === undefined) {
                 // detached instance, remove from view and skip.
@@ -8764,6 +8851,7 @@ const Callbacks = {
         else if ('decoder' in roomOrDecoder.serializer) {
             return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
         }
+        throw new Error('Invalid room or decoder');
     },
     getRawChanges(decoder, callback) {
         return getRawChangesCallback(decoder, callback);
@@ -9219,12 +9307,27 @@ class StateView {
         if (!this.isVisible(changeTree)) {
             // view must have all "changeTree" parent tree
             this.markVisible(changeTree);
-            // add parent's parent
+            // 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 && parentChangeTree.hasFilteredFields) {
+            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
+        // an extra ADD on a non-filtered field's index would only emit
+        // bytes for a no-op (`value === previousValue` on the decoder).
+        if (!changeTree.hasFilteredFields)
+            return;
         // add parent's tag properties
         if (changeTree.getChange(parentIndex) !== OPERATION.DELETE) {
             let changes = this.changes.get(changeTree.ref[$refId]);
@@ -9236,6 +9339,45 @@ class StateView {
             changes.set(parentIndex, OPERATION.ADD);
         }
     }
+    /**
+     * Walk `tree`'s parent chain to root and insert an empty entry into
+     * `view.changes` for any ancestor not already present. Empty entries
+     * are skipped by `encodeView` (`changes.size === 0` continue), so no
+     * wire bytes are emitted — but the Map's insertion order now puts
+     * each ancestor BEFORE the descendant entry that the caller is about
+     * to write. Combined with `addParentOf`'s full-recursion walk on
+     * `view.add`, this preserves the global invariant that
+     * `view.changes` iteration order is topological.
+     *
+     * Iterative (not recursive) so the stack is bounded by tree depth
+     * regardless of call patterns. Stops the walk as soon as it hits an
+     * ancestor that's already in `view.changes` — at that point the
+     * remainder of the chain is guaranteed to also be present (invariant
+     * upheld by every prior caller).
+     */
+    _touchAncestorsOf(tree) {
+        let cursor = tree.parent?.[$changes];
+        if (cursor === undefined)
+            return;
+        // Collect the missing prefix of the chain, deepest-first. Only
+        // FILTERED ancestors need entries — non-filtered ones never
+        // appear in `view.changes` (mirrors the addParentOf gate), so
+        // they don't need a Map slot reserved either.
+        const stack = [];
+        while (cursor !== undefined) {
+            if (cursor.hasFilteredFields) {
+                const refId = cursor.ref[$refId];
+                if (this.changes.has(refId))
+                    break;
+                stack.push(cursor);
+            }
+            cursor = cursor.parent?.[$changes];
+        }
+        // Insert root-first so Map order is topological.
+        for (let i = stack.length - 1; i >= 0; i--) {
+            this.changes.set(stack[i].ref[$refId], new Map());
+        }
+    }
     remove(obj, tag = DEFAULT_VIEW_TAG, _isClear = false) {
         const changeTree = obj[$changes];
         if (!changeTree) {
@@ -9296,6 +9438,11 @@ class StateView {
         const ref = changeTree.ref;
         const metadata = ref.constructor[Symbol.metadata]; // ArraySchema/MapSchema do not have metadata
         const refId = ref[$refId];
+        // Pre-insert any missing ancestors into view.changes so the Map's
+        // iteration order stays topological — the entries we're about to
+        // write (either on this obj, or on its parent collection below)
+        // must come AFTER every ancestor in the chain on the wire.
+        this._touchAncestorsOf(changeTree);
         let changes = this.changes.get(refId);
         if (changes === undefined) {
             changes = new Map();