@colyseus/schema 5.0.11 → 5.0.13

package/src/encoder/StateView.ts

@@ -4,7 +4,11 @@ import { DEFAULT_VIEW_TAG } from "../annotations.js";
 import { OPERATION } from "../encoding/spec.js";
 import { Metadata } from "../Metadata.js";
 import { spliceOne } from "../types/utils.js";
-import { streamDequeueForView, streamEnqueueForView } from "./streaming.js";
+import { ensureStreamState, streamDequeueForView, streamEnqueueForView } from "./streaming.js";
+import type { StreamSchema } from "../types/custom/StreamSchema.js";
+import type { MapSchema } from "../types/custom/MapSchema.js";
+import type { SetSchema } from "../types/custom/SetSchema.js";
+import type { CollectionSchema } from "../types/custom/CollectionSchema.js";
 import type { Schema } from "../Schema.js";
 import type { Root, Streamable } from "./Root.js";
 
@@ -51,6 +55,24 @@ const _disposeRegistry = new FinalizationRegistry<{ root: Root; id: number; slot
     },
 );
 
+/**
+ * Compact description of a rejected argument, for warning messages.
+ * Passing the value itself to `console.warn` is not an option — a
+ * populated collection inspects into dozens of lines of encoder
+ * internals and buries the message that matters.
+ */
+function describeArg(value: any): string {
+    if (value === undefined) { return "undefined"; }
+    if (value === null) { return "null"; }
+    const type = typeof value;
+    if (type === "string") {
+        return JSON.stringify(value.length > 30 ? `${value.slice(0, 30)}…` : value);
+    }
+    if (type !== "object" && type !== "function") { return `${type} ${String(value)}`; }
+    if (Array.isArray(value)) { return `Array(${value.length})`; }
+    return value.constructor?.name ?? "Object";
+}
+
 export class StateView {
     /**
      * Iterable list of items that are visible to this view
@@ -282,13 +304,16 @@ export class StateView {
 
     private _add(obj: Ref, tag: number, checkIncludeParent: boolean, _skipStreamRouting: boolean) {
         const changeTree: ChangeTree = obj?.[$changes];
-        const parentChangeTree = changeTree.parent;
-
         if (!changeTree) {
-            console.warn("StateView#add(), invalid object:", obj);
+            console.warn(
+                `StateView#add(): expected a Schema instance or collection, received ${describeArg(obj)}`,
+            );
             return false;
+        }
+
+        const parentChangeTree = changeTree.parent;
 
-        } else if (
+        if (
             !parentChangeTree &&
             obj[$refId] !== 0 // allow root object
         ) {
@@ -603,9 +628,11 @@ export class StateView {
     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 {
-        const changeTree: ChangeTree = obj[$changes];
+        const changeTree: ChangeTree = obj?.[$changes];
         if (!changeTree) {
-            console.warn("StateView#remove(), invalid object:", obj);
+            console.warn(
+                `StateView#remove(): expected a Schema instance or collection, received ${describeArg(obj)}`,
+            );
             return this;
         }
 
@@ -780,18 +807,79 @@ export class StateView {
      *   enqueued into `_pendingByView` so the priority pass drains them
      *   respecting `maxPerTick`.
      *
-     * Idempotent on re-subscribe. Subscribing to an already-subscribed
-     * collection is a no-op.
+     * On a streaming collection, pass a `priority` callback to order THIS
+     * client's backlog. It receives only the element, so whatever the
+     * client sorts by is captured in the closure — nothing is attached to
+     * the view, and both the element and the captured entity stay typed:
+     *
+     * ```ts
+     * onJoin(client) {
+     *     const player = this.state.players.get(client.sessionId);
+     *     client.view.subscribe(this.state.enemies, (enemy) =>
+     *         -((enemy.x - player.x) ** 2 + (enemy.y - player.y) ** 2));
+     * }
+     * ```
+     *
+     * A per-view callback overrides the collection's declaration-scope
+     * `.priority()` for this client only.
+     *
+     * Idempotent on re-subscribe: subscribing to an already-subscribed
+     * collection is a no-op, EXCEPT that a supplied `priority` always
+     * replaces the previous one — re-subscribe to retarget the ordering.
+     * Omitting the argument leaves any existing callback in place; pass
+     * `null` to drop it and fall back to the declaration-scope callback.
      */
-    subscribe(collection: Ref): this {
+    subscribe<V>(
+        collection: StreamSchema<V> | MapSchema<V, any> | SetSchema<V> | CollectionSchema<V>,
+        priority?: ((element: V) => number) | null,
+    ): this;
+    subscribe(collection: Ref): this;
+    subscribe(collection: Ref, priority?: ((element: any) => number) | null): this {
         const tree: ChangeTree = collection?.[$changes];
         if (!tree) {
-            console.warn("StateView#subscribe(), invalid collection:", collection);
+            console.warn(
+                `StateView#subscribe(): expected a Schema collection, received ${describeArg(collection)}`,
+            );
             return this;
         }
         if (this._root === undefined && tree.root !== undefined) {
             this._bindRoot(tree.root);
         }
+
+        if (priority !== undefined) {
+            if (!tree.isStreamCollection) {
+                // Name the field rather than dumping the collection — a
+                // populated MapSchema inspects into dozens of lines of
+                // internals and buries the message.
+                const kind = (collection as any)?.constructor?.name ?? "collection";
+                const parent: any = tree.parent;
+                if (parent === undefined) {
+                    console.warn(
+                        `StateView#subscribe(): \`priority\` ignored — this ${kind} is not ` +
+                        `attached to a state yet, so it cannot be identified as a stream. ` +
+                        `Subscribe after assigning it to the state.`,
+                    );
+                } else {
+                    const field = parent?.constructor?.[Symbol.metadata]?.[tree.parentIndex]?.name;
+                    const where = field ? `${parent.constructor.name}#${field}` : kind;
+                    console.warn(
+                        `StateView#subscribe(): \`priority\` ignored — ${where} is a ${kind}, ` +
+                        `not a streaming collection. Declare the field with .stream() ` +
+                        `(e.g. t.map(X).stream()) or use t.stream(X) to enable priority batching.`,
+                    );
+                }
+            } else {
+                // Set before the idempotency return below, so re-subscribing
+                // is the documented way to retarget this view's ordering.
+                const st = ensureStreamState(collection as unknown as Streamable);
+                if (priority === null) {
+                    st.priorityByView?.delete(this.id);
+                } else {
+                    (st.priorityByView ??= new Map()).set(this.id, priority);
+                }
+            }
+        }
+
         if (this.isSubscribed(tree)) return this;
 
         // Mark collection visible so its own ADD/DELETE ops emit in the
@@ -839,7 +927,9 @@ export class StateView {
     unsubscribe(collection: Ref): this {
         const tree: ChangeTree = collection?.[$changes];
         if (!tree) {
-            console.warn("StateView#unsubscribe(), invalid collection:", collection);
+            console.warn(
+                `StateView#unsubscribe(): expected a Schema collection, received ${describeArg(collection)}`,
+            );
             return this;
         }
         if (!this.isSubscribed(tree)) return this;

package/src/encoder/changeTree/inheritedFlags.ts

@@ -1,5 +1,5 @@
 /**
- * Filter / unreliable / transient / static inheritance helpers for
+ * Filter / unreliable / patchOnly / static inheritance helpers for
  * ChangeTree. Called by setRoot / setParent to derive child flags from
  * the parent field's annotation + the parent tree's own state.
  */
@@ -7,15 +7,15 @@ import { Metadata } from "../../Metadata.js";
 import { DEFAULT_VIEW_TAG } from "../../annotations.js";
 import {
     $changes, $childType,
-    $staticFieldIndexes, $streamFieldIndexes,
-    $transientFieldIndexes, $viewFieldIndexes,
+    $fullStateOnlyFieldIndexes, $streamFieldIndexes,
+    $patchOnlyFieldIndexes, $viewFieldIndexes,
     // $unreliableFieldIndexes — tree-level unreliable currently disabled
     // (see INHERITABLE_FLAGS comment in ChangeTree.ts). Per-field unreliable
     // routing on primitive fields still uses it via `isFieldUnreliable()`.
 } from "../../types/symbols.js";
 import type { Schema } from "../../Schema.js";
 import {
-    INHERITABLE_FLAGS, IS_STATIC, IS_TRANSIENT,
+    INHERITABLE_FLAGS, IS_FULL_STATE_ONLY, IS_PATCH_ONLY,
     // IS_UNRELIABLE — tree-level unreliable currently disabled; see
     // INHERITABLE_FLAGS comment in ChangeTree.ts.
     type ChangeTree, type Ref,
@@ -39,7 +39,7 @@ export function checkIsFiltered(
 
     // Static trees never track per-tick changes — skip the queue entirely.
     // Full-sync reaches them via structural walk (forEachChild).
-    if (tree.isStatic) return;
+    if (tree.isFullStateOnly) return;
 
     // Mutations that happened before setRoot (e.g. class-field initializers)
     // recorded into the appropriate recorder but couldn't enqueue yet.
@@ -66,7 +66,7 @@ export function checkIsFiltered(
 }
 
 /**
- * Inherit filter / unreliable / transient / static classification from
+ * Inherit filter / unreliable / patchOnly / static classification from
  * the parent field's annotation. Collections (MapSchema / ArraySchema /
  * etc.) inherit these from the Schema field that holds them.
  *
@@ -106,15 +106,15 @@ export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex:
 
     const parentMetadata: any = (parent as any)?.constructor?.[Symbol.metadata];
 
-    // Flag inheritance — pack the transient/static annotation checks into
+    // Flag inheritance — pack the patchOnly/static annotation checks into
     // flag bits alongside the parent's own transitive flags, then OR onto
     // `tree.flags` in one write. The bit diff tells us which flag just
     // went from 0→1, cheaper than the prior `becameX = !tree.isX && (...)`
     // pairs. IS_UNRELIABLE is omitted from both sides — tree-level
     // unreliable is disabled (see INHERITABLE_FLAGS in ChangeTree.ts).
     const fieldBits =
-        (parentMetadata?.[$transientFieldIndexes]?.includes(parentIndex) ? IS_TRANSIENT : 0)
-        | (parentMetadata?.[$staticFieldIndexes]?.includes(parentIndex) ? IS_STATIC : 0);
+        (parentMetadata?.[$patchOnlyFieldIndexes]?.includes(parentIndex) ? IS_PATCH_ONLY : 0)
+        | (parentMetadata?.[$fullStateOnlyFieldIndexes]?.includes(parentIndex) ? IS_FULL_STATE_ONLY : 0);
     const inheritedBits = (parentChangeTree.flags & INHERITABLE_FLAGS) | fieldBits;
     const beforeFlags = tree.flags;
     tree.flags = beforeFlags | inheritedBits;
@@ -125,7 +125,7 @@ export function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex:
     // `new Config().assign({...})` populates the recorder before the
     // Config instance is attached). Static trees ship state via structural
     // walk only; per-tick dirty entries would leak post-first-sync.
-    if (gainedBits & IS_STATIC) {
+    if (gainedBits & IS_FULL_STATE_ONLY) {
         tree.reset();
         tree.unreliableRecorder?.reset();
     }

package/src/encoder/changeTree/liveIteration.ts

@@ -1,13 +1,13 @@
 /**
- * Walk all currently-populated non-transient indexes on a tree, emitting
+ * Walk all currently-populated non-patchOnly indexes on a tree, emitting
  * each index once. Used by Root.add (re-stage), Encoder.encodeAll, and
  * StateView.add to derive full-sync output from the live structure.
  *
- * Transient fields (`@transient`) are skipped — they're delivered only on
+ * Patch-only fields (`@patchOnly`) are skipped — they're delivered only on
  * tick patches and not persisted to snapshots. Collections whose parent
- * field is @transient inherit the skip (`tree.isTransient`).
+ * field is @patchOnly inherit the skip (`tree.isPatchOnly`).
  */
-import { $childType, $numFields, $transientFieldIndexes } from "../../types/symbols.js";
+import { $childType, $numFields, $patchOnlyFieldIndexes } from "../../types/symbols.js";
 import type { ChangeTree } from "../ChangeTree.js";
 
 // Adapter that lets `forEachLive(cb)` delegate to `forEachLiveWithCtx(cb, _invokeNoCtx)` —
@@ -29,10 +29,10 @@ export function forEachLiveWithCtx<C>(
     const ref = tree.refTarget as any;
 
     if (ref[$childType] !== undefined) {
-        // Collection inheriting @transient from parent field: skip entirely.
+        // Collection inheriting @patchOnly from parent field: skip entirely.
         // The resync sweep (decoder/Resync.ts) relies on this: a collection
         // absent from full-sync output is never pruned client-side.
-        if (tree.isTransient) return;
+        if (tree.isPatchOnly) return;
 
         // Collection types: dispatch by shape.
         if (Array.isArray(ref.items)) {
@@ -56,7 +56,7 @@ export function forEachLiveWithCtx<C>(
         // Schema: walk declared fields. `null` is treated as absent —
         // the setter records a DELETE when a field is set to null or
         // undefined, so it should not appear in full-sync output.
-        // (@transient skips below matter to the resync sweep — see
+        // (@patchOnly skips below matter to the resync sweep — see
         // decoder/Resync.ts: absent-from-payload means never pruned.)
         //
         // Read names from the per-class descriptor's parallel array —
@@ -65,12 +65,12 @@ export function forEachLiveWithCtx<C>(
         const metadata = tree.metadata;
         if (!metadata) return;
         const numFields = (metadata[$numFields] ?? -1) as number;
-        const transientIndexes = metadata[$transientFieldIndexes];
+        const patchOnlyIndexes = metadata[$patchOnlyFieldIndexes];
         const names = tree.encDescriptor.names;
         for (let i = 0; i <= numFields; i++) {
             const name = names[i];
             if (name === undefined) continue;
-            if (transientIndexes && transientIndexes.includes(i)) continue;
+            if (patchOnlyIndexes && patchOnlyIndexes.includes(i)) continue;
             const value = ref[name];
             if (value !== undefined && value !== null) cb(ctx, i);
         }

package/src/encoder/changeTree/parentChain.ts

@@ -45,6 +45,35 @@ export function addParent(tree: ChangeTree, parent: Ref, index: number): void {
     }
 }
 
+/**
+ * Move `parent`'s existing chain entry to `index`, skipping the attachment
+ * work `addParent` does. `parent` must already be a parent of `tree`.
+ *
+ * Called by collections whose wire slots shift (ArraySchema): StateView
+ * addresses per-view ADD/DELETE by that index, so it has to follow the
+ * element it names.
+ */
+export function setParentIndex(tree: ChangeTree, parent: Ref, index: number): void {
+    if (tree.extraParents === undefined) {
+        tree._parentIndex = index; // sole parent, so it is `parent`
+        return;
+    }
+    // Shared instance — move only the entry `parent` owns. Matching goes
+    // through `$changes` because ArraySchema arrives proxied (see removeParent
+    // below), and `extraParents` only ever fills by demoting `parentRef`, so
+    // the inline parent is set here.
+    if (tree.parentRef[$changes] === parent[$changes]) {
+        tree._parentIndex = index;
+        return;
+    }
+    for (let entry = tree.extraParents; entry !== undefined; entry = entry.next) {
+        if (entry.ref[$changes] === parent[$changes]) {
+            entry.index = index;
+            return;
+        }
+    }
+}
+
 /**
  * Remove a parent from the chain.
  * @returns true if parent was found and removed (Root.remove relies on this).

package/src/encoder/streaming.ts

@@ -53,6 +53,13 @@ export interface StreamableState {
      * Instance-level override: assign to `stream.priority`.
      */
     priority?: (view: any, element: any) => number;
+    /**
+     * Per-view priority registered by `StateView.subscribe(collection, fn)`.
+     * Takes precedence over the declaration-scope `priority` for that view.
+     * Receives only the element — the client's own entity is captured in
+     * the closure, so nothing has to be attached to the view.
+     */
+    priorityByView?: Map<number, (element: any) => number>;
 }
 
 export function createStreamableState(): StreamableState {
@@ -229,4 +236,5 @@ export function streamDropView(s: Streamable, viewId: number): void {
     if (st === undefined) return;
     st.pendingByView.delete(viewId);
     st.sentByView.delete(viewId);
+    st.priorityByView?.delete(viewId);
 }

package/src/encoding/spec.ts

@@ -1,4 +1,4 @@
-export const SWITCH_TO_STRUCTURE = 255; // (decoding collides with DELETE_AND_ADD + fieldIndex = 63)
+export const SWITCH_TO_STRUCTURE = 255; // same byte as `DELETE_AND_ADD | 63`, which is why field index 63 is unassignable (Metadata.MAX_FIELDS)
 export const TYPE_ID = 213;
 
 /**

package/src/index.ts

@@ -50,9 +50,9 @@ export {
     type,
     deprecated,
     defineTypes,
-    owned,
     unreliable,
-    transient,
+    patchOnly,
+    fullStateOnly,
     view,
     schema,
     entity,

package/src/types/builder.ts

@@ -20,12 +20,11 @@ export interface BuilderDefinition {
     default?: any;
     hasDefault: boolean;
     view?: number;    // tag value; undefined = no view
-    owned?: boolean;
     unreliable?: boolean;
-    transient?: boolean;
+    patchOnly?: boolean;
     deprecated?: boolean;
     deprecatedThrows?: boolean;
-    static?: boolean;
+    fullStateOnly?: boolean;
     stream?: boolean;
     optional?: boolean;
     /** Local-only field: typed + initialized, but never registered for sync. */
@@ -75,12 +74,11 @@ export class FieldBuilder<
     private _default: any = undefined;
     private _hasDefault = false;
     private _view: number | undefined = undefined;
-    private _owned = false;
     private _unreliable = false;
-    private _transient = false;
+    private _patchOnly = false;
     private _deprecated = false;
     private _deprecatedThrows = true;
-    private _static = false;
+    private _fullStateOnly = false;
     private _stream = false;
     private _optional = false;
     private _noSync = false;
@@ -119,16 +117,16 @@ export class FieldBuilder<
         return this;
     }
 
-    /** Mark this field as owned (encoder-side ownership filtering). */
-    owned(): this {
-        this._owned = true;
-        return this;
-    }
-
     /**
      * Mark this field as unreliable — tick patches emit it on the unreliable
      * transport channel. Still persisted to full-sync snapshots unless also
-     * tagged with `.transient()`.
+     * tagged with `.patchOnly()`. Primitive fields only.
+     *
+     * The field's FIRST value still travels the reliable channel, as part of
+     * the owning instance's ADD; only later mutations become unreliable. A
+     * decoder cannot apply a write to a ref it has not been told about, so a
+     * value emitted ahead of that ADD would be dropped — and lost for good if
+     * the field is never written again.
      */
     unreliable(): this {
         this._unreliable = true;
@@ -136,24 +134,28 @@ export class FieldBuilder<
     }
 
     /**
-     * Mark this field as transient — NOT persisted to full-sync snapshots
-     * (`encodeAll` / `encodeAllView`). Late-joining clients see the field
-     * only after its next mutation is emitted on a tick patch. Orthogonal
-     * to `.unreliable()`.
+     * Deliver this field on tick patches ONLY — it is never written to a
+     * full-state sync (`encodeAll` / `encodeAllView`). Late-joining clients
+     * see the field only after its next mutation is emitted on a patch.
+     * The mirror of `.fullStateOnly()`, and orthogonal to `.unreliable()`.
      */
-    transient(): this {
-        this._transient = true;
+    patchOnly(): this {
+        this._patchOnly = true;
         return this;
     }
 
     /**
-     * Mark this field as static.
-     * - Primitive / Schema fields: synchronized once, skips change tracking.
-     * - Stream fields (`t.stream(X).static()`): child elements are frozen
-     *   after add — post-add field mutations on elements become no-ops.
+     * Deliver this field in the full state sync ONLY (`encodeAll` /
+     * `encodeAllView`) — it never enters a tick patch. A client receives it
+     * on join (and again on a resync); writes after that are not tracked.
+     * The mirror of `.patchOnly()`.
+     *
+     * The field itself is NOT frozen — it stays mutable server-side, only
+     * its propagation stops. On a stream field (`t.stream(X).fullStateOnly()`)
+     * the same rule applies per element: post-add mutations are no-ops.
      */
-    static(): this {
-        this._static = true;
+    fullStateOnly(): this {
+        this._fullStateOnly = true;
         return this;
     }
 
@@ -166,8 +168,8 @@ export class FieldBuilder<
      * 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
+     * Mutually exclusive with the sync-only modifiers (`.view()`,
+     * `.unreliable()`, `.patchOnly()`, `.fullStateOnly()`, `.stream()`) — combining
      * them throws at `schema()` time.
      *
      * ```ts
@@ -211,9 +213,12 @@ export class FieldBuilder<
      * higher return values emit first. Does nothing in broadcast mode
      * (shared `encode()` drains FIFO). Only meaningful on stream fields.
      *
+     * `StateView` carries no position of its own — attach whatever the
+     * callback needs to sort by (`view` is loosely typed for this).
+     *
      * ```ts
      * t.stream(Enemy).priority((view, enemy) =>
-     *     -dist2(view.anchor, enemy)
+     *     -((enemy.x - view.x) ** 2 + (enemy.y - view.y) ** 2)
      * )
      * ```
      */
@@ -251,12 +256,11 @@ export class FieldBuilder<
             default: this._default,
             hasDefault: this._hasDefault,
             view: this._view,
-            owned: this._owned,
             unreliable: this._unreliable,
-            transient: this._transient,
+            patchOnly: this._patchOnly,
             deprecated: this._deprecated,
             deprecatedThrows: this._deprecatedThrows,
-            static: this._static,
+            fullStateOnly: this._fullStateOnly,
             stream: this._stream,
             optional: this._optional,
             noSync: this._noSync,

package/src/types/custom/ArraySchema.ts

@@ -331,6 +331,35 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         return tmpItems.length + (index - live);
     }
 
+    /**
+     * Re-point children at their wire slot. `ChangeTree._parentIndex` caches
+     * the slot a child holds in `tmpItems`, and StateView addresses per-view
+     * ADD/DELETE with it — so a reorder that leaves it behind aims those ops
+     * at whichever element inherited the slot (issue #231).
+     *
+     * The filter check is a correctness boundary, not a tunable: StateView is
+     * the only reader and reaches the index only through a filtered array
+     * (`addParentOf` bails on `hasFilteredFields`, `remove` on the child's
+     * `isFiltered`). Everything else stops at the flag read instead of walking
+     * its children every tick.
+     *
+     * Callers name the lowest slot that moved as `from`. Compaction cannot, so
+     * it hands over the pre-compaction layout as `staged` and the unchanged
+     * prefix is skipped instead. Either way tail churn walks nothing.
+     */
+    protected $reindexChildren(from: number, staged?: V[]) {
+        if (!this[$changes].hasFilteredFields) { return; } // nothing will read the cache
+        if (typeof this[$childType] === "string") { return; } // primitives have no child tree
+        const tmpItems = this.tmpItems;
+        const length = tmpItems.length;
+        if (staged !== undefined) {
+            while (from < length && tmpItems[from] === staged[from]) { from++; }
+        }
+        for (let i = from; i < length; i++) {
+            tmpItems[i]?.[$changes]?.setParentIndex(this, i);
+        }
+    }
+
     // encoding only. Returns the wire index the change was recorded at
     // (undefined when nothing was recorded).
     protected $changeAt(index: number, value: V): number | undefined {
@@ -460,6 +489,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         self[$changes].operation(OPERATION.REVERSE);
         self.items.reverse();
         self.tmpItems.reverse();
+        self.$reindexChildren(0);
         return this;
     }
 
@@ -515,6 +545,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         sortedItems.forEach((_, i) => changeTree.change(i, OPERATION.REPLACE));
 
         self.tmpItems.sort(compareFn);
+        self.$reindexChildren(0);
 
         self.isMovingItems = false;
         return this;
@@ -620,6 +651,7 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         }
 
         self.tmpItems.unshift(...items);
+        self.$reindexChildren(items.length); // survivors only — the loop above placed the new items
 
         return self.items.unshift(...items);
     }
@@ -938,8 +970,15 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
 
     protected [$onEncodeEnd]() {
         const self = this[$proxyTarget] ?? this;
+        const staged = self.tmpItems;
         self.tmpItems = self.items.slice();
-        self.deletedIndexes.length = 0;
+
+        if (self.deletedIndexes.length > 0) {
+            // compaction just closed the staged holes — everything above the
+            // lowest one slid down a slot
+            self.$reindexChildren(0, staged);
+            self.deletedIndexes.length = 0;
+        }
     }
 
     protected [$onDecodeEnd]() {

package/src/types/custom/StreamSchema.ts

@@ -34,7 +34,7 @@ import type { Schema } from "../../Schema.js";
  * per-client and drained in priority order (callback on StateView) up to
  * `maxPerTick` per encode pass. Field mutations on already-sent elements
  * propagate through the normal reliable channel without consuming the
- * per-tick budget. Chain `.static()` on the field builder to suppress
+ * per-tick budget. Chain `.fullStateOnly()` on the field builder to suppress
  * post-add mutation tracking entirely.
  */
 export class StreamSchema<V = any> implements IRef {

package/src/types/symbols.ts

@@ -117,17 +117,10 @@ export const $builder = "~builder";
  */
 export const $descriptors = "~descriptors";
 
-/**
- * Per-class bitmask: bit i set iff field i carries a @view tag.
- * Lazily computed from $viewFieldIndexes on first encode pass.
- * Skips the per-field metadata[i].tag property chase in the hot encode loop.
- */
-export const $filterBitmask = "~__filterBitmask";
-
 /**
  * Cached per-class encode descriptor: bundles encoder fn, filter fn,
- * metadata, isSchema flag, and filterBitmask into one object stashed on
- * the constructor. Replaces 5 separate per-tree property chases /
+ * metadata, isSchema flag and the per-field arrays into one object stashed
+ * on the constructor. Replaces several separate per-tree property chases /
  * function calls in the encode loop with a single property load.
  */
 export const $encodeDescriptor = "~__encodeDescriptor";
@@ -137,7 +130,7 @@ export const $refTypeFieldIndexes = "~__refTypeFieldIndexes";
 export const $viewFieldIndexes = "~__viewFieldIndexes";
 export const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
 export const $unreliableFieldIndexes = "~__unreliableFieldIndexes";
-export const $transientFieldIndexes = "~__transientFieldIndexes";
-export const $staticFieldIndexes = "~__staticFieldIndexes";
+export const $patchOnlyFieldIndexes = "~__patchOnlyFieldIndexes";
+export const $fullStateOnlyFieldIndexes = "~__fullStateOnlyFieldIndexes";
 export const $streamFieldIndexes = "~__streamFieldIndexes";
 export const $streamPriorities = "~__streamPriorities";