@colyseus/schema 5.0.11 → 5.0.13

package/build/index.mjs

@@ -1,4 +1,4 @@
-const SWITCH_TO_STRUCTURE = 255; // (decoding collides with DELETE_AND_ADD + fieldIndex = 63)
+const SWITCH_TO_STRUCTURE = 255; // same byte as `DELETE_AND_ADD | 63`, which is why field index 63 is unassignable (Metadata.MAX_FIELDS)
 const TYPE_ID = 213;
 /**
  * Encoding Schema field operations.
@@ -118,16 +118,10 @@ const $builder = "~builder";
  * Metadata
  */
 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.
- */
-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.
  */
 const $encodeDescriptor = "~__encodeDescriptor";
@@ -137,8 +131,8 @@ const $refTypeFieldIndexes = "~__refTypeFieldIndexes";
 const $viewFieldIndexes = "~__viewFieldIndexes";
 const $fieldIndexesByViewTag = "$__fieldIndexesByViewTag";
 const $unreliableFieldIndexes = "~__unreliableFieldIndexes";
-const $transientFieldIndexes = "~__transientFieldIndexes";
-const $staticFieldIndexes = "~__staticFieldIndexes";
+const $patchOnlyFieldIndexes = "~__patchOnlyFieldIndexes";
+const $fullStateOnlyFieldIndexes = "~__fullStateOnlyFieldIndexes";
 const $streamFieldIndexes = "~__streamFieldIndexes";
 const $streamPriorities = "~__streamPriorities";
 
@@ -819,6 +813,7 @@ function streamDropView(s, viewId) {
         return;
     st.pendingByView.delete(viewId);
     st.sentByView.delete(viewId);
+    st.priorityByView?.delete(viewId);
 }
 
 const WIRE_BY_BITS = {
@@ -1064,6 +1059,15 @@ class TypeContext {
     }
 }
 
+/**
+ * Field indexes ride in the low 6 bits of the operation byte
+ * (`(index | operation) & 255`), which leaves room for 0..63. Index 63 is
+ * given up: `DELETE_AND_ADD | 63` is 255, the same byte the decoder claims
+ * as SWITCH_TO_STRUCTURE before any field decoder sees it. Every nullable
+ * field can produce that operation (delete-then-set in one tick merges to
+ * DELETE_AND_ADD), so the slot is unusable rather than partly usable.
+ */
+const MAX_FIELDS = 63;
 /**
  * Given a normalized field type (`"number"`, `{ map: Foo }`, `Player`,
  * etc.), split into the collection-type descriptor (`{ constructor:
@@ -1127,10 +1131,12 @@ function isTSEnum(_enum) {
 }
 const Metadata = {
     addField(metadata, index, name, type, descriptor) {
-        if (index > 64) {
-            throw new Error(`Can't define field '${name}'.\nSchema instances may only have up to 64 fields.`);
+        // `index` is 0-based, so 62 is the last usable slot — see MAX_FIELDS
+        // for why 63 is off limits.
+        if (index >= MAX_FIELDS) {
+            throw new Error(`Can't define field '${name}'.\nSchema instances may only have up to ${MAX_FIELDS} fields.`);
         }
-        metadata[index] = Object.assign(metadata[index] || {}, // avoid overwriting previous field metadata (@owned / @deprecated)
+        metadata[index] = Object.assign(metadata[index] || {}, // avoid overwriting previous field metadata (@deprecated / @unreliable)
         {
             type: getNormalizedType(type),
             index,
@@ -1280,31 +1286,43 @@ const Metadata = {
         }
         metadata[$unreliableFieldIndexes].push(index);
     },
-    setTransient(metadata, fieldName) {
+    setPatchOnly(metadata, fieldName) {
         const index = metadata[fieldName];
-        metadata[index].transient = true;
-        if (!metadata[$transientFieldIndexes]) {
-            Object.defineProperty(metadata, $transientFieldIndexes, {
+        // patchOnly + fullStateOnly are the only two delivery channels —
+        // excluding a field from both would silently never reach a client.
+        // (The builder validates earlier; this guards the decorator path.)
+        if (metadata[index].fullStateOnly) {
+            throw new Error(`field "${fieldName}" cannot be both patchOnly and fullStateOnly — ` +
+                `those are the only two delivery channels, so the field would never reach a client.`);
+        }
+        metadata[index].patchOnly = true;
+        if (!metadata[$patchOnlyFieldIndexes]) {
+            Object.defineProperty(metadata, $patchOnlyFieldIndexes, {
                 value: [],
                 enumerable: false,
                 configurable: true,
                 writable: true,
             });
         }
-        metadata[$transientFieldIndexes].push(index);
+        metadata[$patchOnlyFieldIndexes].push(index);
     },
-    setStatic(metadata, fieldName) {
+    setFullStateOnly(metadata, fieldName) {
         const index = metadata[fieldName];
-        metadata[index].static = true;
-        if (!metadata[$staticFieldIndexes]) {
-            Object.defineProperty(metadata, $staticFieldIndexes, {
+        // Mirror of the guard in setPatchOnly — covers both decorator orders.
+        if (metadata[index].patchOnly) {
+            throw new Error(`field "${fieldName}" cannot be both patchOnly and fullStateOnly — ` +
+                `those are the only two delivery channels, so the field would never reach a client.`);
+        }
+        metadata[index].fullStateOnly = true;
+        if (!metadata[$fullStateOnlyFieldIndexes]) {
+            Object.defineProperty(metadata, $fullStateOnlyFieldIndexes, {
                 value: [],
                 enumerable: false,
                 configurable: true,
                 writable: true,
             });
         }
-        metadata[$staticFieldIndexes].push(index);
+        metadata[$fullStateOnlyFieldIndexes].push(index);
     },
     setStream(metadata, fieldName) {
         const index = metadata[fieldName];
@@ -1468,19 +1486,19 @@ const Metadata = {
                         writable: true,
                     });
                 }
-                // $transientFieldIndexes
-                if (parentMetadata[$transientFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $transientFieldIndexes, {
-                        value: [...parentMetadata[$transientFieldIndexes]],
+                // $patchOnlyFieldIndexes
+                if (parentMetadata[$patchOnlyFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $patchOnlyFieldIndexes, {
+                        value: [...parentMetadata[$patchOnlyFieldIndexes]],
                         enumerable: false,
                         configurable: true,
                         writable: true,
                     });
                 }
-                // $staticFieldIndexes
-                if (parentMetadata[$staticFieldIndexes] !== undefined) {
-                    Object.defineProperty(metadata, $staticFieldIndexes, {
-                        value: [...parentMetadata[$staticFieldIndexes]],
+                // $fullStateOnlyFieldIndexes
+                if (parentMetadata[$fullStateOnlyFieldIndexes] !== undefined) {
+                    Object.defineProperty(metadata, $fullStateOnlyFieldIndexes, {
+                        value: [...parentMetadata[$fullStateOnlyFieldIndexes]],
                         enumerable: false,
                         configurable: true,
                         writable: true,
@@ -1538,11 +1556,11 @@ const Metadata = {
     hasUnreliableAtIndex(metadata, index) {
         return metadata?.[$unreliableFieldIndexes]?.includes(index);
     },
-    hasTransientAtIndex(metadata, index) {
-        return metadata?.[$transientFieldIndexes]?.includes(index);
+    hasPatchOnlyAtIndex(metadata, index) {
+        return metadata?.[$patchOnlyFieldIndexes]?.includes(index);
     },
-    hasStaticAtIndex(metadata, index) {
-        return metadata?.[$staticFieldIndexes]?.includes(index);
+    hasFullStateOnlyAtIndex(metadata, index) {
+        return metadata?.[$fullStateOnlyFieldIndexes]?.includes(index);
     },
     hasStreamAtIndex(metadata, index) {
         return metadata?.[$streamFieldIndexes]?.includes(index);
@@ -1553,7 +1571,7 @@ const Metadata = {
 // by passing the user's callback as ctx. No per-call allocation.
 const _invokeNoCtx$2 = (cb, index, op) => cb(index, op);
 // ──────────────────────────────────────────────────────────────────────────
-// SchemaChangeRecorder — bitmask + Uint8Array, for Schema types (≤64 fields)
+// SchemaChangeRecorder — bitmask + Uint8Array, for Schema types (≤63 fields)
 // ──────────────────────────────────────────────────────────────────────────
 /**
  * Schema field operations are limited to ADD(128), DELETE(64), and
@@ -1746,37 +1764,15 @@ function popcount32(n) {
  *   ctor[$filter]
  *   ctor[Symbol.metadata]
  *   Metadata.isValidInstance(ref)
- *   getFilterBitmask(metadata)
  *
  * Lives in its own file to break the Encoder.ts ↔ ChangeTree.ts import
  * cycle (ChangeTree caches descriptors at construction; Encoder reads them
  * during encode).
  */
-function computeFilterBitmask(metadata) {
-    if (metadata === undefined)
-        return 0;
-    let bm = metadata[$filterBitmask];
-    if (bm !== undefined)
-        return bm;
-    bm = 0;
-    const tagged = metadata[$viewFieldIndexes];
-    if (tagged !== undefined) {
-        for (let i = 0, len = tagged.length; i < len; i++)
-            bm |= (1 << tagged[i]);
-    }
-    // Non-enumerable so `for (const k in metadata)` iteration in TypeContext
-    // and elsewhere doesn't mistake this cache for a real field index.
-    Object.defineProperty(metadata, $filterBitmask, {
-        value: bm,
-        enumerable: false,
-        writable: true,
-        configurable: true,
-    });
-    return bm;
-}
 /**
  * Bitmask of field indexes 0–31 in `indexes`. For fields ≥32 callers must
- * fall back to the array lookup (same as `filterBitmask`).
+ * fall back to the array lookup — shift counts wrap at 32, so an unguarded
+ * `1 << 40` would set bit 8 and misclassify field 8.
  */
 function indexesToBitmask(indexes) {
     if (indexes === undefined)
@@ -1852,12 +1848,12 @@ function getEncodeDescriptor(ref) {
         filter,
         metadata,
         isSchema,
-        filterBitmask: isSchema ? computeFilterBitmask(metadata) : 0,
-        hasAnyStatic: (metadata?.[$staticFieldIndexes]?.length ?? 0) > 0,
+        filterBitmask: isSchema ? indexesToBitmask(metadata?.[$viewFieldIndexes]) : 0,
+        hasAnyFullStateOnly: (metadata?.[$fullStateOnlyFieldIndexes]?.length ?? 0) > 0,
         hasAnyUnreliable: (metadata?.[$unreliableFieldIndexes]?.length ?? 0) > 0,
         hasAnyStream: (metadata?.[$streamFieldIndexes]?.length ?? 0) > 0,
         hasAnyView,
-        staticBitmask: indexesToBitmask(metadata?.[$staticFieldIndexes]),
+        fullStateOnlyBitmask: indexesToBitmask(metadata?.[$fullStateOnlyFieldIndexes]),
         unreliableBitmask: indexesToBitmask(metadata?.[$unreliableFieldIndexes]),
         streamBitmask: indexesToBitmask(metadata?.[$streamFieldIndexes]),
         names: arrays.names,
@@ -1916,6 +1912,34 @@ function addParent(tree, parent, index) {
         tree._parentIndex = index;
     }
 }
+/**
+ * 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.
+ */
+function setParentIndex(tree, parent, index) {
+    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).
@@ -1993,13 +2017,13 @@ function getAllParents(tree) {
 }
 
 /**
- * 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`).
  */
 // Adapter that lets `forEachLive(cb)` delegate to `forEachLiveWithCtx(cb, _invokeNoCtx)` —
 // keeps the no-ctx path closure-free and shares one walker implementation.
@@ -2013,10 +2037,10 @@ function forEachLiveWithCtx(tree, ctx, cb) {
     // types. See `ChangeTree.refTarget` doc.
     const ref = tree.refTarget;
     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)
+        if (tree.isPatchOnly)
             return;
         // Collection types: dispatch by shape.
         if (Array.isArray(ref.items)) {
@@ -2045,7 +2069,7 @@ function forEachLiveWithCtx(tree, ctx, cb) {
         // 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 —
@@ -2055,13 +2079,13 @@ function forEachLiveWithCtx(tree, ctx, cb) {
         if (!metadata)
             return;
         const numFields = (metadata[$numFields] ?? -1);
-        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))
+            if (patchOnlyIndexes && patchOnlyIndexes.includes(i))
                 continue;
             const value = ref[name];
             if (value !== undefined && value !== null)
@@ -2071,7 +2095,7 @@ function forEachLiveWithCtx(tree, ctx, cb) {
 }
 
 /**
- * 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.
  */
@@ -2084,7 +2108,7 @@ function checkIsFiltered(tree, parent, parentIndex, _isNewChangeTree) {
     checkInheritedFlags(tree, parent, parentIndex);
     // Static trees never track per-tick changes — skip the queue entirely.
     // Full-sync reaches them via structural walk (forEachChild).
-    if (tree.isStatic)
+    if (tree.isFullStateOnly)
         return;
     // Mutations that happened before setRoot (e.g. class-field initializers)
     // recorded into the appropriate recorder but couldn't enqueue yet.
@@ -2110,7 +2134,7 @@ function checkIsFiltered(tree, parent, parentIndex, _isNewChangeTree) {
     }
 }
 /**
- * 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.
  *
@@ -2149,14 +2173,14 @@ function checkInheritedFlags(tree, parent, parentIndex) {
         parentIndex = parentChangeTree.parentIndex;
     }
     const parentMetadata = parent?.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);
+    const fieldBits = (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;
@@ -2166,7 +2190,7 @@ function checkInheritedFlags(tree, parent, 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();
     }
@@ -2471,7 +2495,7 @@ function _setParentChildCb(ctx, child, index) {
  *
  *   - parentChain.ts     addParent / removeParent / find / has / getAll
  *   - liveIteration.ts   forEachLive
- *   - inheritedFlags.ts  filter / unreliable / transient / static inheritance
+ *   - inheritedFlags.ts  filter / unreliable / patchOnly / static inheritance
  *   - treeAttachment.ts  setRoot / setParent / forEachChild(+WithCtx)
  *
  * Public surface on ChangeTree is unchanged — methods are thin pass-throughs
@@ -2491,12 +2515,12 @@ function readInlineOpByte(low, high, index) {
 const _invokeNoCtx = (cb, index, op) => cb(index, op);
 // Linked list helper functions
 function createChangeTreeList() {
-    return { next: undefined, tail: undefined };
+    return { next: undefined, tail: undefined, nextPosition: 0 };
 }
-// Flags bitfield. *_UNRELIABLE / _TRANSIENT / _STATIC mirror the parent
+// Flags bitfield. *_UNRELIABLE / _PATCH_ONLY / _STATIC mirror the parent
 // field's annotation — inherited at setParent/setRoot time.
 const IS_FILTERED = 1, IS_VISIBILITY_SHARED = 2, IS_NEW = 4;
-const IS_UNRELIABLE = 8, IS_TRANSIENT = 16, IS_STATIC = 32;
+const IS_UNRELIABLE = 8, IS_PATCH_ONLY = 16, IS_FULL_STATE_ONLY = 32;
 // Collection tree attached to a parent field annotated `.stream()` —
 // drives the encoder's priority/broadcast pass. Set in inheritedFlags
 // so both `t.stream(X)` (via StreamSchema's `$isStream` brand) and
@@ -2523,7 +2547,7 @@ const NEEDS_RESTAGE = 128;
  * reconsidered if a safe semantics (e.g. reliable ADD + unreliable
  * field mutations only) is designed later.
  */
-const INHERITABLE_FLAGS = IS_TRANSIENT | IS_STATIC;
+const INHERITABLE_FLAGS = IS_PATCH_ONLY | IS_FULL_STATE_ONLY;
 class ChangeTree {
     ref;
     /**
@@ -2542,8 +2566,8 @@ class ChangeTree {
     refTarget;
     metadata;
     /**
-     * Per-class cache of encoder fn / filter fn / isSchema / filterBitmask /
-     * metadata, looked up once at construction. The encode loop reads
+     * Per-class cache of encoder fn / filter fn / isSchema / metadata /
+     * per-field arrays, looked up once at construction. The encode loop reads
      * `tree.encDescriptor` and never touches `ref.constructor` again. See
      * EncodeDescriptor.ts.
      */
@@ -2614,10 +2638,10 @@ class ChangeTree {
     set isNew(v) { this.flags = v ? (this.flags | IS_NEW) : (this.flags & ~IS_NEW); }
     get isUnreliable() { return (this.flags & IS_UNRELIABLE) !== 0; }
     set isUnreliable(v) { this.flags = v ? (this.flags | IS_UNRELIABLE) : (this.flags & ~IS_UNRELIABLE); }
-    get isTransient() { return (this.flags & IS_TRANSIENT) !== 0; }
-    set isTransient(v) { this.flags = v ? (this.flags | IS_TRANSIENT) : (this.flags & ~IS_TRANSIENT); }
-    get isStatic() { return (this.flags & IS_STATIC) !== 0; }
-    set isStatic(v) { this.flags = v ? (this.flags | IS_STATIC) : (this.flags & ~IS_STATIC); }
+    get isPatchOnly() { return (this.flags & IS_PATCH_ONLY) !== 0; }
+    set isPatchOnly(v) { this.flags = v ? (this.flags | IS_PATCH_ONLY) : (this.flags & ~IS_PATCH_ONLY); }
+    get isFullStateOnly() { return (this.flags & IS_FULL_STATE_ONLY) !== 0; }
+    set isFullStateOnly(v) { this.flags = v ? (this.flags | IS_FULL_STATE_ONLY) : (this.flags & ~IS_FULL_STATE_ONLY); }
     get isStreamCollection() { return (this.flags & IS_STREAM_COLLECTION) !== 0; }
     set isStreamCollection(v) { this.flags = v ? (this.flags | IS_STREAM_COLLECTION) : (this.flags & ~IS_STREAM_COLLECTION); }
     get needsRestage() { return (this.flags & NEEDS_RESTAGE) !== 0; }
@@ -2626,7 +2650,7 @@ class ChangeTree {
     // @view-tagged fields. StateView.addParentOf uses this to decide whether
     // a parent must be included in a view's bootstrap. Reads the class-level
     // "any viewed field" flag that `EncodeDescriptor` precomputes — same
-    // pattern as `hasAnyStatic` / `hasAnyUnreliable` / `hasAnyStream`.
+    // pattern as `hasAnyFullStateOnly` / `hasAnyUnreliable` / `hasAnyStream`.
     get hasFilteredFields() {
         return this.isFiltered || this.encDescriptor.hasAnyView;
     }
@@ -2650,7 +2674,7 @@ class ChangeTree {
         // metadata lookup. For schemas that DO have unreliable fields, the
         // bitmask answers fields 0-31 in one bitwise op (no Array.includes
         // linear scan). Fields ≥32 always fall back to the metadata lookup
-        // (same limitation as filterBitmask — bitmask only covers low 32).
+        // (shift counts wrap at 32, so the bitmask only covers the low 32).
         const desc = this.encDescriptor;
         if (!desc.hasAnyUnreliable)
             return false;
@@ -2660,15 +2684,15 @@ class ChangeTree {
     }
     // @static fields sync once via full-sync; post-init mutations are ignored
     // by the tracker (the value still lives on the instance).
-    isFieldStatic(index) {
-        if (this.isStatic)
+    isFieldFullStateOnly(index) {
+        if (this.isFullStateOnly)
             return true;
         const desc = this.encDescriptor;
-        if (!desc.hasAnyStatic)
+        if (!desc.hasAnyFullStateOnly)
             return false;
         if (index < 32)
-            return (desc.staticBitmask & (1 << index)) !== 0;
-        return Metadata.hasStaticAtIndex(this.metadata, index);
+            return (desc.fullStateOnlyBitmask & (1 << index)) !== 0;
+        return Metadata.hasFullStateOnlyAtIndex(this.metadata, index);
     }
     // `t.stream(...)` collection fields — encoded via per-view priority/budget
     // gate instead of emitting all dirty ADDs in one tick. Class-level short
@@ -2927,7 +2951,7 @@ class ChangeTree {
         // keep the recorder object allocated (re-alloc is the cost we avoid), clear contents
         this.unreliableRecorder?.reset();
         // back to a freshly-constructed tree: IS_NEW, no inherited flags
-        // (FILTERED/TRANSIENT/STATIC/STREAM are re-derived on the next setParent).
+        // (FILTERED/PATCH_ONLY/STATIC/STREAM are re-derived on the next setParent).
         // NEEDS_RESTAGE makes the next Root.add re-stage retained field values.
         this.flags = IS_NEW | NEEDS_RESTAGE;
         this._fullSyncGen = 0;
@@ -2960,7 +2984,7 @@ class ChangeTree {
             throw new Error("ChangeTree (Schema): unshift is not supported");
         const src = this.collDirty;
         const dst = new Map();
-        const track = !this.paused && !this.isStatic;
+        const track = !this.paused && !this.isFullStateOnly;
         if (track) {
             for (let i = 0; i < count; i++)
                 dst.set(i, OPERATION.ADD);
@@ -2984,7 +3008,7 @@ class ChangeTree {
         forEachLiveWithCtx(this, ctx, cb);
     }
     operation(op) {
-        if (this.paused || this.isStatic)
+        if (this.paused || this.isFullStateOnly)
             return;
         // Pure ops (CLEAR/REVERSE) only emit from collection trees — the
         // recorder here is always a CollectionChangeRecorder by construction.
@@ -3014,11 +3038,23 @@ class ChangeTree {
      * fields (see annotations.ts), so the per-field unreliable flag here
      * always means "primitive value updates" — the structural-ADD-routes-
      * reliable footgun for ref-type fields can't reach this code path.
+     *
+     * `!isNew` holds an `@unreliable` field on the RELIABLE channel until this
+     * tree's own ADD has shipped there. A decoder can only apply a field write
+     * to a ref it already knows, so a value emitted before the ADD is dropped —
+     * permanently, if the field is never written again. `isNew` clears in
+     * `endEncode()`, i.e. after a reliable pass, and recording reliably is
+     * itself what enqueues the tree for that pass; the state is self-clearing
+     * and no tree can be stranded on the wrong channel. Mirrors `encodeAll`,
+     * which has always seeded these fields for late joiners.
+     *
+     * Ordering matters: `isFieldUnreliable` short-circuits on the class-level
+     * `hasAnyUnreliable`, so schemas without the modifier never read `flags`.
      */
     _routeAndRecord(index, op, raw) {
-        if (this.paused || this.isFieldStatic(index))
+        if (this.paused || this.isFieldFullStateOnly(index))
             return;
-        if (this.isFieldUnreliable(index)) {
+        if (this.isFieldUnreliable(index) && !this.isNew) {
             const r = this.ensureUnreliableRecorder();
             if (raw)
                 r.recordRaw(index, op);
@@ -3085,9 +3121,11 @@ class ChangeTree {
             }
             return;
         }
-        if (this.paused || this.isFieldStatic(index))
+        if (this.paused || this.isFieldFullStateOnly(index))
             return this.getValue(index);
-        const unreliable = this.isFieldUnreliable(index);
+        // Same pre-ADD hold as `_routeAndRecord` — a DELETE naming a ref the
+        // decoder hasn't seen is dropped just like a field write.
+        const unreliable = this.isFieldUnreliable(index) && !this.isNew;
         if (unreliable)
             this.ensureUnreliableRecorder().recordDelete(index, operation ?? OPERATION.DELETE);
         else
@@ -3146,6 +3184,8 @@ class ChangeTree {
     get parent() { return this.parentRef; }
     get parentIndex() { return this._parentIndex; }
     addParent(parent, index) { addParent(this, parent, index); }
+    /** Re-point an existing parent's cached index after the parent reindexed. */
+    setParentIndex(parent, index) { setParentIndex(this, parent, index); }
     /** @returns true if parent was found and removed */
     removeParent(parent = this.parent) { return removeParent(this, parent); }
     findParent(predicate) {
@@ -3190,6 +3230,7 @@ class UntrackedChangeTree {
     operation() { }
     setParent() { }
     addParent() { }
+    setParentIndex() { }
     removeParent() { return false; }
     getChange() { return 0; }
     discard() { }
@@ -3293,7 +3334,9 @@ function encodeValue(encoder, bytes, type, value, operation, it, encoderFn) {
  * @private
  */
 const encodeSchemaOperation = function (encoder, bytes, changeTree, index, operation, it, _, __) {
-    // "compress" field index + operation
+    // "compress" field index + operation. Can't collide with
+    // SWITCH_TO_STRUCTURE (255): that needs `DELETE_AND_ADD | 63`, and
+    // `Metadata.MAX_FIELDS` keeps index 63 unassignable.
     bytes[it.offset++] = (index | operation) & 255;
     // Do not encode value for DELETE operations
     if (operation === OPERATION.DELETE) {
@@ -3489,8 +3532,8 @@ function resyncTouchEntry(decoder, ref, operation, identity, previousValue, valu
 /**
  * Mark a collection as present in the payload — even with zero entries.
  * The sweep only prunes collections reported here: absence means "not part
- * of full-sync" (@transient, view-invisible), where pruning would destroy
- * live data. Reflected clients have no @transient metadata, so payload
+ * of full-sync" (@patchOnly, view-invisible), where pruning would destroy
+ * live data. Reflected clients have no @patchOnly metadata, so payload
  * presence is the only reliable signal.
  */
 function resyncMarkPresent(decoder, refId) {
@@ -3504,7 +3547,7 @@ function resyncMarkPresent(decoder, refId) {
  * entry the snapshot did not visit.
  *
  * Walks the tree from the root — NOT `root.refs` — for three reasons:
- * `@transient` fields are never part of a snapshot and must be left alone;
+ * `@patchOnly` fields are never part of a snapshot and must be left alone;
  * entries of subtrees removed by the sweep itself are left to the GC's
  * transitive walk (sweeping them directly would double-decrement shared
  * children); and collections the snapshot never mentions (emptied
@@ -3529,11 +3572,11 @@ function sweepSchema(decoder, ref, seen, allChanges) {
     if (refIndexes === undefined) {
         return;
     }
-    const transient = metadata[$transientFieldIndexes];
+    const patchOnly = metadata[$patchOnlyFieldIndexes];
     for (let i = 0; i < refIndexes.length; i++) {
         const fieldIndex = refIndexes[i];
-        // @transient fields are never in a snapshot — leave them alone.
-        if (transient !== undefined && transient.includes(fieldIndex)) {
+        // @patchOnly fields are never in a snapshot — leave them alone.
+        if (patchOnly !== undefined && patchOnly.includes(fieldIndex)) {
             continue;
         }
         const field = metadata[fieldIndex];
@@ -3558,7 +3601,7 @@ function sweepCollection(decoder, coll, seen, allChanges) {
     seen.add(refId);
     // `undefined` = the collection never appeared in the payload at all
     // (not even as its parent's field op) — it is not part of full-sync
-    // (@transient, view-invisible) and must be left alone. An empty Set
+    // (@patchOnly, view-invisible) and must be left alone. An empty Set
     // means "present with zero entries" → prune everything.
     const visited = decoder.resyncVisited.get(refId);
     if (visited === undefined) {
@@ -4243,6 +4286,40 @@ class ArraySchema {
         // beyond the live range: appends land after the staged tmpItems tail
         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.
+     */
+    $reindexChildren(from, staged) {
+        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).
     $changeAt(index, value) {
@@ -4354,6 +4431,7 @@ class ArraySchema {
         self[$changes].operation(OPERATION.REVERSE);
         self.items.reverse();
         self.tmpItems.reverse();
+        self.$reindexChildren(0);
         return this;
     }
     /**
@@ -4405,6 +4483,7 @@ class ArraySchema {
         // wouldn't OPERATION.MOVE make more sense here?
         sortedItems.forEach((_, i) => changeTree.change(i, OPERATION.REPLACE));
         self.tmpItems.sort(compareFn);
+        self.$reindexChildren(0);
         self.isMovingItems = false;
         return this;
     }
@@ -4486,6 +4565,7 @@ class ArraySchema {
             deletedIndexes.unshift(...new Array(items.length).fill(false));
         }
         self.tmpItems.unshift(...items);
+        self.$reindexChildren(items.length); // survivors only — the loop above placed the new items
         return self.items.unshift(...items);
     }
     /**
@@ -4754,8 +4834,14 @@ class ArraySchema {
     }
     [$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;
+        }
     }
     [$onDecodeEnd]() {
         const self = this[$proxyTarget] ?? this;
@@ -5877,7 +5963,7 @@ registerType("set", { constructor: SetSchema });
  * 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.
  */
 class StreamSchema {
@@ -6152,12 +6238,11 @@ class FieldBuilder {
     _default = undefined;
     _hasDefault = false;
     _view = undefined;
-    _owned = false;
     _unreliable = false;
-    _transient = false;
+    _patchOnly = false;
     _deprecated = false;
     _deprecatedThrows = true;
-    _static = false;
+    _fullStateOnly = false;
     _stream = false;
     _optional = false;
     _noSync = false;
@@ -6192,38 +6277,43 @@ class FieldBuilder {
         this._view = tag ?? -1;
         return this;
     }
-    /** Mark this field as owned (encoder-side ownership filtering). */
-    owned() {
-        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._unreliable = true;
         return this;
     }
     /**
-     * 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._transient = true;
+    patchOnly() {
+        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._static = true;
+    fullStateOnly() {
+        this._fullStateOnly = true;
         return this;
     }
     /**
@@ -6235,8 +6325,8 @@ 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
@@ -6278,9 +6368,12 @@ 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)
      * )
      * ```
      */
@@ -6315,12 +6408,11 @@ 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,
@@ -6574,25 +6666,44 @@ function view(tag = DEFAULT_VIEW_TAG) {
         Metadata.setTag(metadata, fieldName, tag);
     };
 }
-function owned(target, field) {
-    const metadata = Metadata.initialize(target.constructor);
-    metadata[metadata[field]].owned = true;
-}
+/**
+ * `@unreliable` — route a field onto the unreliable transport channel, so a
+ * dropped update costs one stale value instead of stalling the ordered stream
+ * behind a retransmit. Primitive fields only (see `Metadata.setUnreliable`).
+ *
+ * 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.
+ */
 function unreliable(target, field) {
     const metadata = Metadata.initialize(target.constructor);
     Metadata.setUnreliable(metadata, field);
 }
 /**
- * @transient — mark a field as not persisted to snapshots (encodeAll /
- * encodeAllView). Transient fields are still emitted on per-tick patches
+ * @patchOnly — mark a field as not persisted to snapshots (encodeAll /
+ * encodeAllView). PatchOnly fields are still emitted on per-tick patches
  * (reliable or unreliable), but late-joining clients won't see them until
  * the next mutation.
  *
  * Orthogonal to @unreliable: a field can be either, both, or neither.
  */
-function transient(target, field) {
+function patchOnly(target, field) {
+    const metadata = Metadata.initialize(target.constructor);
+    Metadata.setPatchOnly(metadata, field);
+}
+/**
+ * @fullStateOnly — mark a field as delivered in the full state sync only
+ * (encodeAll / encodeAllView), never on per-tick patches. Writes after a
+ * client has joined are not propagated to it — populate these fields
+ * before clients connect (e.g. during onCreate).
+ *
+ * The exact mirror of @patchOnly — the two are mutually exclusive.
+ */
+function fullStateOnly(target, field) {
     const metadata = Metadata.initialize(target.constructor);
-    Metadata.setTransient(metadata, field);
+    Metadata.setFullStateOnly(metadata, field);
 }
 function type(type, options) {
     return function (target, field) {
@@ -6964,11 +7075,10 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
         }
     };
     const viewTagFields = {};
-    const ownedFields = [];
     const unreliableFields = [];
-    const transientFields = [];
+    const patchOnlyFields = [];
     const deprecatedFields = {};
-    const staticFields = [];
+    const fullStateOnlyFields = [];
     const streamFields = [];
     const streamPriorityFields = {};
     const optionalFields = [];
@@ -6980,15 +7090,22 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
                 // 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) {
+                if (def.view !== undefined || def.unreliable ||
+                    def.patchOnly || def.fullStateOnly || def.stream) {
                     throw new Error(`schema(${name ? `'${name}'` : ""}): field '${fieldName}' uses .noSync() ` +
-                        `together with a sync-only modifier (.view/.owned/.unreliable/.transient/.static/.stream). ` +
+                        `together with a sync-only modifier (.view/.unreliable/.patchOnly/.fullStateOnly/.stream). ` +
                         `A local-only field cannot be synchronized.`);
                 }
                 seedDefault(fieldName, def);
                 continue;
             }
+            // The two delivery channels are exhaustive: excluding a field from
+            // both leaves it with nowhere to go — a silent .noSync().
+            if (def.patchOnly && def.fullStateOnly) {
+                throw new Error(`schema(${name ? `'${name}'` : ""}): field '${fieldName}' uses .patchOnly() ` +
+                    `together with .fullStateOnly(). Those are the only two delivery channels, ` +
+                    `so the field would never reach a client — use .noSync() if that is intended.`);
+            }
             const normalizedType = getNormalizedType(def.type);
             // A synced ref must be encodable (a Schema, or Metadata.setFields()'d) — reject a bare class.
             if (typeof normalizedType === "function" && !Schema.is(normalizedType)) {
@@ -6999,20 +7116,17 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
             if (def.view !== undefined) {
                 viewTagFields[fieldName] = def.view;
             }
-            if (def.owned) {
-                ownedFields.push(fieldName);
-            }
             if (def.unreliable) {
                 unreliableFields.push(fieldName);
             }
-            if (def.transient) {
-                transientFields.push(fieldName);
+            if (def.patchOnly) {
+                patchOnlyFields.push(fieldName);
             }
             if (def.deprecated) {
                 deprecatedFields[fieldName] = def.deprecatedThrows;
             }
-            if (def.static) {
-                staticFields.push(fieldName);
+            if (def.fullStateOnly) {
+                fullStateOnlyFields.push(fieldName);
             }
             if (def.stream) {
                 streamFields.push(fieldName);
@@ -7095,22 +7209,19 @@ function schema(fieldsAndMethods, name, inherits = Schema) {
     for (const fieldName in viewTagFields) {
         view(viewTagFields[fieldName])(klass.prototype, fieldName);
     }
-    for (const fieldName of ownedFields) {
-        owned(klass.prototype, fieldName);
-    }
     for (const fieldName of unreliableFields) {
         unreliable(klass.prototype, fieldName);
     }
-    for (const fieldName of transientFields) {
-        transient(klass.prototype, fieldName);
+    for (const fieldName of patchOnlyFields) {
+        patchOnly(klass.prototype, fieldName);
     }
     for (const fieldName in deprecatedFields) {
         deprecated(deprecatedFields[fieldName])(klass.prototype, fieldName);
     }
-    if (staticFields.length > 0 || streamFields.length > 0) {
+    if (fullStateOnlyFields.length > 0 || streamFields.length > 0) {
         const metadata = klass[Symbol.metadata];
-        for (const fieldName of staticFields) {
-            Metadata.setStatic(metadata, fieldName);
+        for (const fieldName of fullStateOnlyFields) {
+            Metadata.setFullStateOnly(metadata, fieldName);
         }
         for (const fieldName of streamFields) {
             Metadata.setStream(metadata, fieldName);
@@ -7759,7 +7870,7 @@ class Root {
         const previousRefCount = this.refCount[refId];
         if (previousRefCount === 0 || changeTree.needsRestage) {
             //
-            // Re-stage every currently-populated non-transient index as a
+            // Re-stage every currently-populated non-patchOnly index as a
             // fresh ADD in the matching dirty bucket so the next encode
             // re-emits it on the correct channel. Two triggers:
             // - refCount 0: a previously-removed tree re-added under the
@@ -7849,14 +7960,10 @@ class Root {
         const parentNode = parent[$changes][nodeField];
         if (!parentNode || parentNode === node)
             return;
-        // Check if child is already after parent by walking from parent
-        let cursor = parentNode.next;
-        while (cursor) {
-            if (cursor === node)
-                return; // already after parent
-            cursor = cursor.next;
-        }
-        // If we reach here, node is before parent — need to move
+        // Positions are strictly increasing along the list, so this is an
+        // exact O(1) "is child already after parent" test — no queue scan.
+        if (node.position > parentNode.position)
+            return;
         // Remove node from current position
         if (node.prev) {
             node.prev.next = node.next;
@@ -7870,16 +7977,18 @@ class Root {
         else {
             changeSet.tail = node.prev;
         }
-        // Insert node right after parent
-        node.prev = parentNode;
-        node.next = parentNode.next;
-        if (parentNode.next) {
-            parentNode.next.prev = node;
-        }
-        else {
-            changeSet.tail = node;
-        }
-        parentNode.next = node;
+        // Re-append at the tail: after `parentNode` AND after every other
+        // queued parent of a multi-referenced instance — relinking next to
+        // the *primary* parent could jump the child ahead of a 2nd/3rd
+        // parent whose ADD the decoder must see first. Tail placement gets
+        // a fresh max position, keeping the invariant append-only.
+        // (`recursivelyMoveNextToParent` visits pre-order, so a moved
+        // subtree re-serializes parent-first behind it.)
+        node.prev = changeSet.tail;
+        node.next = undefined;
+        changeSet.tail.next = node; // parentNode remains in the list — never empty here
+        changeSet.tail = node;
+        node.position = changeSet.nextPosition++;
     }
     enqueueChangeTree(changeTree, existingNode = changeTree.changesNode) {
         if (existingNode) {
@@ -7901,12 +8010,12 @@ class Root {
             node.changeTree = changeTree;
             node.next = undefined;
             node.prev = undefined;
-            node.position = 0;
         }
         else {
             node = { changeTree, next: undefined, prev: undefined, position: 0 };
         }
         if (!list.next) {
+            list.nextPosition = 0; // list drained — restart sequence (stays SMI)
             list.next = node;
             list.tail = node;
         }
@@ -7915,6 +8024,7 @@ class Root {
             list.tail.next = node;
             list.tail = node;
         }
+        node.position = list.nextPosition++;
         return node;
     }
     /**
@@ -8013,6 +8123,7 @@ function _fullSyncWalk(ctx, changeTree) {
         ctx.treeIsFiltered = changeTree.isFiltered;
         ctx.isSchema = desc.isSchema;
         ctx.filterBitmask = desc.filterBitmask;
+        ctx.tags = desc.tags;
         ctx.structSwitchEmitted = false;
         ctx.shouldEmitSwitch = (ctx.hasView || ctx.it.offset > ctx.initialOffset || changeTree !== ctx.rootChangeTree);
         // Call the module function directly — the `forEachLiveWithCtx`
@@ -8052,10 +8163,13 @@ function encodeChangeCb(ctx, fieldIndex, op) {
     }
     // Per-field filter decision (same rule as ChangeTree.change()):
     // a field is filtered iff the tree inherits isFiltered OR the field
-    // itself carries a @view tag. Schema trees check via the precomputed
-    // bitmask; collection trees inherit tree-level (bitmask is 0).
+    // itself carries a @view tag. The bitmask only spans 0–31 — `1 << 40`
+    // wraps onto bit 8 — so fields past it read their tag directly. Reaching
+    // that arm needs a Schema with more than 32 fields.
     const fieldFiltered = ctx.isSchema
-        ? (ctx.treeIsFiltered || (ctx.filterBitmask & (1 << fieldIndex)) !== 0)
+        ? (ctx.treeIsFiltered || (fieldIndex < 32
+            ? (ctx.filterBitmask & (1 << fieldIndex)) !== 0
+            : ctx.tags[fieldIndex] !== undefined))
         : ctx.treeIsFiltered;
     if (fieldFiltered !== ctx.emitFiltered)
         return;
@@ -8110,7 +8224,7 @@ class Encoder {
         ref: undefined, encoder: undefined, filter: undefined, metadata: undefined,
         view: undefined, isEncodeAll: false, hasView: false,
         treeIsFiltered: false, isSchema: false, emitFiltered: false,
-        filterBitmask: 0,
+        filterBitmask: 0, tags: undefined,
         structSwitchEmitted: false, isRootTree: false, shouldEmitSwitch: false,
         gen: 0, initialOffset: 0, rootChangeTree: undefined,
     };
@@ -8167,6 +8281,7 @@ class Encoder {
             ctx.treeIsFiltered = changeTree.isFiltered;
             ctx.isSchema = desc.isSchema;
             ctx.filterBitmask = desc.filterBitmask;
+            ctx.tags = desc.tags;
             ctx.structSwitchEmitted = false;
             ctx.isRootTree = (changeTree === rootChangeTree);
             // Root's struct switch is skipped at the very start of the shared
@@ -8418,7 +8533,7 @@ class Encoder {
                 // Emit each element's full state — forEachLive walks populated
                 // fields structurally, mirroring encodeAllView's bootstrap.
                 // Covers both static elements (dirty state was reset by
-                // inheritedFlags' becameStatic branch) and non-static (still
+                // inheritedFlags' becameFullStateOnly branch) and non-static (still
                 // has dirty state but the main loop skipped them because
                 // they're filtered).
                 for (const element of emittedElements) {
@@ -8497,20 +8612,81 @@ class Encoder {
             // `t.stream(X).priority(fn)` or the decorator form) and seeded
             // into `_stream.priority` when the stream was attached. Users
             // can also override per-instance by assigning to the setter.
+            // A per-view callback (registered by `subscribe(coll, fn)`)
+            // wins over the declaration-scope one: it closes over the
+            // client's own entity, so it needs no view-carried anchor.
+            const perView = st.priorityByView?.get(viewId);
+            const usePerView = perView !== undefined;
             const priority = st.priority;
-            // Materialize pending into an array so we can sort + slice.
-            // Small sets (typical: tens to low hundreds) — allocation is
-            // negligible compared to the priority sort and element walk.
+            const max = st.maxPerTick;
+            // Select the `max` highest-priority candidates.
+            //
+            // A comparator-based sort invokes the callback twice per
+            // comparison, each with its own `$getByIndex` lookup — ~2·n·log n
+            // of each to pick `max` entries (38k calls to select 8 out of a
+            // 2000-entry backlog). Scoring every candidate once and keeping a
+            // bounded top-`max` window costs n invocations instead, and sizes
+            // the scratch by `max` rather than by the backlog.
+            //
+            // Ties keep the earlier position (both comparisons below are
+            // strict), so equal-priority entries still drain in insertion
+            // order.
             const positions = [];
-            for (const p of pending)
-                positions.push(p);
-            if (priority !== undefined) {
-                // Use the symbol-keyed accessor so Map/Set/Stream all route
-                // through the same lookup regardless of $items layout.
-                positions.sort((a, b) => priority(view, s[$getByIndex](b)) - priority(view, s[$getByIndex](a)));
+            const stale = [];
+            if (usePerView || priority !== undefined) {
+                const bestPos = [];
+                const bestScore = [];
+                let filled = 0;
+                for (const pos of pending) {
+                    // Symbol-keyed accessor so Map/Set/Stream all route
+                    // through the same lookup regardless of $items layout.
+                    const element = s[$getByIndex](pos);
+                    if (element === undefined) {
+                        // Removed after being queued — drop it below without
+                        // spending budget on it.
+                        stale.push(pos);
+                        continue;
+                    }
+                    const score = usePerView
+                        ? perView(element)
+                        : priority(view, element);
+                    // Window not yet full: always insert.
+                    if (filled < max) {
+                        let j = filled++;
+                        while (j > 0 && bestScore[j - 1] < score) {
+                            bestScore[j] = bestScore[j - 1];
+                            bestPos[j] = bestPos[j - 1];
+                            j--;
+                        }
+                        bestScore[j] = score;
+                        bestPos[j] = pos;
+                        // Otherwise only a strictly better score displaces the tail.
+                    }
+                    else if (score > bestScore[max - 1]) {
+                        let j = max - 1;
+                        while (j > 0 && bestScore[j - 1] < score) {
+                            bestScore[j] = bestScore[j - 1];
+                            bestPos[j] = bestPos[j - 1];
+                            j--;
+                        }
+                        bestScore[j] = score;
+                        bestPos[j] = pos;
+                    }
+                }
+                for (let i = 0; i < filled; i++)
+                    positions.push(bestPos[i]);
             }
-            const max = st.maxPerTick;
-            const count = Math.min(positions.length, max);
+            else {
+                // FIFO — take the head of the backlog, no scoring needed.
+                for (const pos of pending) {
+                    if (positions.length >= max)
+                        break;
+                    positions.push(pos);
+                }
+            }
+            for (const pos of stale)
+                pending.delete(pos);
+            const count = positions.length;
             let sent = st.sentByView.get(viewId);
             if (sent === undefined) {
                 sent = new Set();
@@ -9865,6 +10041,31 @@ const _disposeRegistry = new FinalizationRegistry(({ root, id, slot, bit }) => {
     _clearViewBitFromAllTrees(root, slot, bit);
     root.releaseViewId(id);
 });
+/**
+ * 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) {
+    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";
+}
 class StateView {
     iterable;
     /**
@@ -10089,12 +10290,12 @@ class StateView {
     }
     _add(obj, tag, checkIncludeParent, _skipStreamRouting) {
         const 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;
         }
-        else if (!parentChangeTree &&
+        const parentChangeTree = changeTree.parent;
+        if (!parentChangeTree &&
             obj[$refId] !== 0 // allow root object
         ) {
             /**
@@ -10375,9 +10576,9 @@ class StateView {
         }
     }
     remove(obj, tag = DEFAULT_VIEW_TAG, _isClear = false) {
-        const changeTree = obj[$changes];
+        const 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;
         }
         // ── Streamable-element unsubscribe ─────────────────────────────
@@ -10515,32 +10716,47 @@ class StateView {
     hasTag(ob, tag = DEFAULT_VIEW_TAG) {
         return this.hasTagOnTree(ob[$changes], tag);
     }
-    /**
-     * Persistent subscription to a collection's contents. Unlike `add()`,
-     * which is a one-shot bootstrap, `subscribe()` enrolls this view in
-     * future content changes — every subsequent push / set / add to the
-     * collection automatically flows to this view, and every removal
-     * queues a DELETE op. Works on every collection type:
-     *
-     * - `ArraySchema` / `MapSchema` / `SetSchema` / `CollectionSchema`:
-     *   new children are force-shipped immediately (equivalent to
-     *   `view.add(child)` per item).
-     * - `StreamSchema` (or `.stream()` maps/sets): new positions are
-     *   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.
-     */
-    subscribe(collection) {
+    subscribe(collection, priority) {
         const tree = 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?.constructor?.name ?? "collection";
+                const parent = 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);
+                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
@@ -10586,7 +10802,7 @@ class StateView {
     unsubscribe(collection) {
         const tree = 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))
@@ -10670,5 +10886,5 @@ registerType("array", { constructor: ArraySchema });
 registerType("set", { constructor: SetSchema });
 registerType("collection", { constructor: CollectionSchema, });
 
-export { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $numFields, $refId, $track, $values, ArraySchema, Callbacks, ChangeTree, CollectionSchema, Decoder, Encoder, FieldBuilder, MapSchema, Metadata, OPERATION, Reflection, ReflectionField, ReflectionType, Root, Schema, SetSchema, StateCallbackStrategy, StateView, StreamSchema, TypeContext, createPool, decode, decodeKeyValueOperation, decodeSchemaOperation, defineCustomTypes, defineTypes, deprecated, dumpChanges, encode, encodeArray, encodeIndexedEntry, encodeKeyValueOperation, encodeMapEntry, encodeSchemaOperation, entity, getDecoderStateCallbacks, getEncodeDescriptor, getRawChangesCallback, isBuilder, owned, registerType, schema, t, transient, type, unreliable, view };
+export { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $numFields, $refId, $track, $values, ArraySchema, Callbacks, ChangeTree, CollectionSchema, Decoder, Encoder, FieldBuilder, MapSchema, Metadata, OPERATION, Reflection, ReflectionField, ReflectionType, Root, Schema, SetSchema, StateCallbackStrategy, StateView, StreamSchema, TypeContext, createPool, decode, decodeKeyValueOperation, decodeSchemaOperation, defineCustomTypes, defineTypes, deprecated, dumpChanges, encode, encodeArray, encodeIndexedEntry, encodeKeyValueOperation, encodeMapEntry, encodeSchemaOperation, entity, fullStateOnly, getDecoderStateCallbacks, getEncodeDescriptor, getRawChangesCallback, isBuilder, patchOnly, registerType, schema, t, type, unreliable, view };
 //# sourceMappingURL=index.mjs.map