@colyseus/schema 5.0.3 → 5.0.5

package/build/types/builder.d.ts

@@ -23,6 +23,8 @@ export interface BuilderDefinition {
     static?: boolean;
     stream?: boolean;
     optional?: boolean;
+    /** Local-only field: typed + initialized, but never registered for sync. */
+    noSync?: boolean;
     /** Declaration-scope priority callback for `.stream()` fields. */
     streamPriority?: (view: any, element: any) => number;
 }
@@ -53,19 +55,20 @@ export type BuilderOf<T> = FieldBuilder<T>;
  */
 export declare class FieldBuilder<T = unknown, HasDefault extends boolean = false, IsOptional extends boolean = false> {
     readonly [$builder]: true;
-    _type: DefinitionType;
-    _default: any;
-    _hasDefault: boolean;
-    _view: number | undefined;
-    _owned: boolean;
-    _unreliable: boolean;
-    _transient: boolean;
-    _deprecated: boolean;
-    _deprecatedThrows: boolean;
-    _static: boolean;
-    _stream: boolean;
-    _optional: boolean;
-    _streamPriority: ((view: any, element: any) => number) | undefined;
+    private _type;
+    private _default;
+    private _hasDefault;
+    private _view;
+    private _owned;
+    private _unreliable;
+    private _transient;
+    private _deprecated;
+    private _deprecatedThrows;
+    private _static;
+    private _stream;
+    private _optional;
+    private _noSync;
+    private _streamPriority;
     constructor(type: DefinitionType);
     /** Provide a default value for this field. */
     default(value: T): FieldBuilder<T, true, IsOptional>;
@@ -93,6 +96,27 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
      *   after add — post-add field mutations on elements become no-ops.
      */
     static(): 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;
     /**
      * Opt a collection field into priority-batched streaming delivery —
      * ADDs drain at most `maxPerTick` per tick per view (or per broadcast
@@ -130,9 +154,39 @@ export declare class FieldBuilder<T = unknown, HasDefault extends boolean = fals
      * defaults, so the field starts as `undefined` at runtime.
      */
     optional(): FieldBuilder<T | undefined, HasDefault, true>;
-    toDefinition(): BuilderDefinition;
+    /**
+     * @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']()`).
+     */
+    private toDefinition;
 }
 export declare function isBuilder(value: any): value is FieldBuilder<any>;
+/**
+ * Primitive field factory. Calling it bare (`t.int8()`) yields the natural type
+ * for the wire codec (`number` for the int/float formats, plus `string` /
+ * `boolean` / `bigint`). Pass an explicit type argument to refine the inferred
+ * value at the TYPE level, while the wire encoding is unchanged:
+ *
+ *     moveX: t.int8<-1 | 0 | 1>(),       // typed -1|0|1, still encoded as int8
+ *     team:  t.string<"red" | "blue">(),
+ *
+ * Two call signatures, NOT a defaulted generic `<T extends TBase = TBase>`: the
+ * bare form must return a CONCRETE `FieldBuilder<TBase>` so `schema({ x:
+ * t.number() })` still infers `x: number`. A defaulted free type parameter gets
+ * captured as `any` during `schema()`'s self-referential field inference (and
+ * `undefined extends any` then flips every field optional).
+ *
+ * NOTE: the refinement is a TYPE-LEVEL assertion, not a runtime guarantee — the
+ * wire still carries the codec's full range and the DECODER writes whatever
+ * bytes arrive. Sound for server-authored state; for INPUT schemas the value
+ * comes from an untrusted client (the type reads `-1|0|1` while a peer can send
+ * any int8), so keep validating/clamping on the receiving side.
+ */
+interface PrimitiveFactory<TBase> {
+    (): FieldBuilder<TBase>;
+    <T extends TBase>(): FieldBuilder<T>;
+}
 export type ChildType = RawPrimitiveType | Constructor<Schema> | FieldBuilder<any>;
 interface ArrayFactory {
     <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
@@ -166,21 +220,21 @@ interface RefFactory {
     <C extends Constructor<Schema>>(ctor: C): FieldBuilder<InstanceType<C>, RefHasDefault<C>, false>;
 }
 export declare const t: Readonly<{
-    string: () => FieldBuilder<string, false, false>;
-    number: () => FieldBuilder<number, false, false>;
-    boolean: () => FieldBuilder<boolean, false, false>;
-    int8: () => FieldBuilder<number, false, false>;
-    uint8: () => FieldBuilder<number, false, false>;
-    int16: () => FieldBuilder<number, false, false>;
-    uint16: () => FieldBuilder<number, false, false>;
-    int32: () => FieldBuilder<number, false, false>;
-    uint32: () => FieldBuilder<number, false, false>;
-    int64: () => FieldBuilder<number, false, false>;
-    uint64: () => FieldBuilder<number, false, false>;
-    float32: () => FieldBuilder<number, false, false>;
-    float64: () => FieldBuilder<number, false, false>;
-    bigint64: () => FieldBuilder<bigint, false, false>;
-    biguint64: () => FieldBuilder<bigint, false, false>;
+    string: PrimitiveFactory<string>;
+    number: PrimitiveFactory<number>;
+    boolean: PrimitiveFactory<boolean>;
+    int8: PrimitiveFactory<number>;
+    uint8: PrimitiveFactory<number>;
+    int16: PrimitiveFactory<number>;
+    uint16: PrimitiveFactory<number>;
+    int32: PrimitiveFactory<number>;
+    uint32: PrimitiveFactory<number>;
+    int64: PrimitiveFactory<number>;
+    uint64: PrimitiveFactory<number>;
+    float32: PrimitiveFactory<number>;
+    float64: PrimitiveFactory<number>;
+    bigint64: PrimitiveFactory<bigint>;
+    biguint64: PrimitiveFactory<bigint>;
     /** Reference to a Schema subtype. `t.array(Item)` usually reads better, but this is available when a plain ref is needed. */
     ref: RefFactory;
     array: ArrayFactory;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.3",
+  "version": "5.0.5",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {
@@ -10,8 +10,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
     "watch": "tsc -p tsconfig.build.json -w",
-    "typecheck": "tsc -p tsconfig.build.json --noEmit",
-    "test": "tsx --tsconfig tsconfig.test.json ./node_modules/.bin/mocha test/*.test.ts test/**/*.test.ts",
+    "typecheck:build": "tsc -p tsconfig.build.json --noEmit",
+    "test": "tsx --tsconfig tsconfig.test.json ./node_modules/mocha/bin/mocha.js \"test/*.test.ts\" \"test/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.test.json",
     "coverage": "c8 npm run test",
     "generate-test-1": "bin/schema-codegen test-external/PrimitiveTypes.ts --namespace SchemaTest.PrimitiveTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/PrimitiveTypes",
     "generate-test-2": "bin/schema-codegen test-external/ChildSchemaTypes.ts --namespace SchemaTest.ChildSchemaTypes --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/ChildSchemaTypes",
@@ -25,7 +26,7 @@
     "generate-test-10": "bin/schema-codegen test-external/Callbacks.ts --namespace SchemaTest.Callbacks --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/Callbacks",
     "generate-test-11": "bin/schema-codegen test-external/MapSchemaMoveNullifyType.ts --namespace SchemaTest.MapSchemaMoveNullifyType --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/MapSchemaMoveNullifyType",
     "generate-test-12": "bin/schema-codegen test-external/ArraySchemaClear --namespace SchemaTest.ArraySchemaClear --output ../colyseus-unity-sdk/Assets/Colyseus/Tests/Editor/ColyseusTests/Schema/ArraySchemaClear",
-    "prepublishOnly": "npm run build"
+    "prepare": "npm run build"
   },
   "files": [
     "src",
@@ -88,7 +89,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^5.0.0 || ^6.0.0"
   },
   "c8": {
     "include": [

package/src/annotations.ts

@@ -619,6 +619,26 @@ export interface SchemaWithExtendsConstructor<
     };
 }
 
+/**
+ * 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: any): any {
+    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.
  *
@@ -664,7 +684,31 @@ export function schema<
         const value: any = (fieldsAndMethods as any)[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; }
@@ -682,23 +726,9 @@ export function schema<
             } else if (!def.optional) {
                 // Auto-instantiate collection/Schema defaults when none is provided.
                 // `.optional()` opts out — field starts as undefined.
-                const rawType: any = 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;
                 }
             }
 

package/src/codegen/languages/csharp.ts

@@ -122,10 +122,34 @@ ${namespace ? "}" : ""}
 `;
 }
 
+/**
+ * Check if all enum members resolve to non-negative integers,
+ * allowing emission as a native C# `enum` (which only supports integral types).
+ */
+function canUseNativeEnum(_enum: Enum): boolean {
+    return _enum.properties.every((prop) => {
+        if (!prop.type) return true;
+        const n = Number(prop.type);
+        return Number.isInteger(n) && n >= 0;
+    });
+}
+
 /**
  * Generate just the enum body (without imports/namespace) for bundling
  */
 function generateEnumBody(_enum: Enum, indent: string = ""): string {
+    if (canUseNativeEnum(_enum)) {
+        const members = _enum.properties
+            .map((prop, i) => {
+                const value = prop.type ? Number(prop.type) : i;
+                return `${indent}\t${prop.name} = ${value},`;
+            })
+            .join("\n");
+        return `${indent}public enum ${_enum.name} : int {
+${members}
+${indent}}`;
+    }
+
     return `${indent}public struct ${_enum.name} {
 
 ${_enum.properties

package/src/decoder/strategy/Callbacks.ts

@@ -88,13 +88,13 @@ export class StateCallbackStrategy<TState extends IRef> {
         if (!collection || collection[$refId] === undefined) {
             let removePropertyCallback: () => void;
             removePropertyCallback = this.addCallback(
-                instance[$refId],
+                instance[$refId]!,
                 propertyName,
                 (value: TReturn, _: TReturn) => {
                     if (value !== null && value !== undefined) {
                         // Remove the property listener now that collection is available
                         removePropertyCallback();
-                        removeHandler = this.addCallback(value[$refId], operation, handler);
+                        removeHandler = this.addCallback(value[$refId]!, operation, handler);
                     }
                 }
             );
@@ -113,7 +113,7 @@ export class StateCallbackStrategy<TState extends IRef> {
                 });
             }
 
-            return this.addCallback(collection[$refId], operation, handler);
+            return this.addCallback(collection[$refId]!, operation, handler);
         }
     }
 
@@ -129,7 +129,7 @@ export class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to property changes on a nested instance.
      */
-    listen<TInstance extends Schema, K extends PublicPropNames<TInstance>>(
+    listen<TInstance, K extends PublicPropNames<TInstance>>(
         instance: TInstance,
         property: K,
         handler: PropertyChangeCallback<TInstance[K]>,
@@ -162,13 +162,13 @@ export class StateCallbackStrategy<TState extends IRef> {
             handler(currentValue, undefined as any);
         }
 
-        return this.addCallback(instance[$refId], propertyName, handler);
+        return this.addCallback(instance[$refId]!, propertyName, handler);
     }
 
     /**
      * Listen to any property change on an instance.
      */
-    onChange<TInstance extends Schema>(
+    onChange<TInstance extends object>(
         instance: TInstance,
         handler: InstanceChangeCallback
     ): () => void;
@@ -184,7 +184,7 @@ export class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to item changes in a nested collection.
      */
-    onChange<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(
+    onChange<TInstance extends object, K extends CollectionPropNames<TInstance>>(
         instance: TInstance,
         property: K,
         handler: KeyValueCallback<CollectionKeyType<TInstance, K>, CollectionValueType<TInstance, K>>
@@ -195,7 +195,7 @@ export class StateCallbackStrategy<TState extends IRef> {
             // onChange(instance, handler) - instance change
             const instance = args[0] as Schema;
             const handler = args[1] as InstanceChangeCallback;
-            return this.addCallback(instance[$refId], OPERATION.REPLACE, handler);
+            return this.addCallback(instance[$refId]!, OPERATION.REPLACE, handler);
         }
 
         if (typeof args[0] === 'string') {
@@ -229,7 +229,7 @@ export class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to items added to a nested collection.
      */
-    onAdd<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(
+    onAdd<TInstance, K extends CollectionPropNames<TInstance>>(
         instance: TInstance,
         property: K,
         handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>,
@@ -269,7 +269,7 @@ export class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to items removed from a nested collection.
      */
-    onRemove<TInstance extends Schema, K extends CollectionPropNames<TInstance>>(
+    onRemove<TInstance, K extends CollectionPropNames<TInstance>>(
         instance: TInstance,
         property: K,
         handler: ValueKeyCallback<CollectionValueType<TInstance, K>, CollectionKeyType<TInstance, K>>
@@ -299,7 +299,7 @@ export class StateCallbackStrategy<TState extends IRef> {
      * Bind properties from a Schema instance to a target object.
      * Changes will be automatically reflected on the target object.
      */
-    bindTo<TInstance extends Schema, TTarget>(
+    bindTo<TInstance, TTarget>(
         from: TInstance,
         to: TTarget,
         properties?: string[],
@@ -327,7 +327,7 @@ export class StateCallbackStrategy<TState extends IRef> {
             action();
         }
 
-        return this.addCallback(from[$refId], OPERATION.REPLACE, action);
+        return this.addCallback((from as IRef)[$refId]!, OPERATION.REPLACE, action);
     }
 
     protected triggerChanges(allChanges: DataChange[]): void {
@@ -357,7 +357,7 @@ export class StateCallbackStrategy<TState extends IRef> {
                 (change.op & OPERATION.DELETE) === OPERATION.DELETE &&
                 Schema.isSchema(change.previousValue)
             ) {
-                const childRefId = (change.previousValue as Ref)[$refId];
+                const childRefId = (change.previousValue as Ref)[$refId]!;
                 const deleteCallbacks = this.callbacks[childRefId]?.[OPERATION.DELETE];
                 if (deleteCallbacks) {
                     for (let j = deleteCallbacks.length - 1; j >= 0; j--) {
@@ -522,8 +522,10 @@ export const Callbacks = {
             return getDecoderStateCallbacks(roomOrDecoder);
 
         } else if ('decoder' in roomOrDecoder.serializer) {
-            return getDecoderStateCallbacks(roomOrDecoder.serializer.decoder);
+            return getDecoderStateCallbacks((roomOrDecoder.serializer as { decoder: Decoder<T> }).decoder);
         }
+
+        throw new Error('Invalid room or decoder');
     },
 
     getRawChanges(decoder: Decoder, callback: (changes: DataChange[]) => void) {

package/src/encoder/Encoder.ts

@@ -442,8 +442,19 @@ export class Encoder<T extends Schema = any> {
         // 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: ChangeTree = this.root.changeTrees[refId];
 
             if (changeTree === undefined) {

package/src/encoder/StateView.ts

@@ -498,13 +498,28 @@ export class StateView {
             // 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 = 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]);
@@ -519,6 +534,46 @@ export class StateView {
         }
     }
 
+    /**
+     * 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).
+     */
+    private _touchAncestorsOf(tree: ChangeTree): void {
+        let cursor = tree.parent?.[$changes] as ChangeTree | undefined;
+        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: ChangeTree[] = [];
+        while (cursor !== undefined) {
+            if (cursor.hasFilteredFields) {
+                const refId = cursor.ref[$refId];
+                if (this.changes.has(refId)) break;
+                stack.push(cursor);
+            }
+            cursor = cursor.parent?.[$changes] as ChangeTree | undefined;
+        }
+
+        // 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: Ref, tag?: number): this; // hide _isClear parameter from public API
     remove(obj: Ref, tag?: number, _isClear?: boolean): this;
     remove(obj: Ref, tag: number = DEFAULT_VIEW_TAG, _isClear: boolean = false): this {
@@ -594,6 +649,12 @@ export class StateView {
 
         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<number, OPERATION>();

package/src/encoder/changeTree/inheritedFlags.ts

@@ -4,6 +4,7 @@
  * the parent field's annotation + the parent tree's own state.
  */
 import { Metadata } from "../../Metadata.js";
+import { DEFAULT_VIEW_TAG } from "../../annotations.js";
 import {
     $changes, $childType,
     $staticFieldIndexes, $streamFieldIndexes,
@@ -206,12 +207,25 @@ export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex:
         const refType = Metadata.isValidInstance(tree.ref)
             ? tree.ref.constructor
             : (tree.ref as any)[$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))
         );
     }
 }