@colyseus/schema 5.0.11 → 5.0.12

package/build/index.js

@@ -4,7 +4,7 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.schema = {}));
 })(this, (function (exports) { 'use strict';
 
-    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.
@@ -124,16 +124,10 @@
      * 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";
@@ -143,8 +137,8 @@
     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";
 
@@ -825,6 +819,7 @@
             return;
         st.pendingByView.delete(viewId);
         st.sentByView.delete(viewId);
+        st.priorityByView?.delete(viewId);
     }
 
     const WIRE_BY_BITS = {
@@ -1070,6 +1065,15 @@
         }
     }
 
+    /**
+     * 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:
@@ -1133,10 +1137,12 @@
     }
     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,
@@ -1286,31 +1292,43 @@
             }
             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];
@@ -1474,19 +1492,19 @@
                             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,
@@ -1544,11 +1562,11 @@
         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);
@@ -1559,7 +1577,7 @@
     // 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
@@ -1752,37 +1770,15 @@
      *   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)
@@ -1858,12 +1854,12 @@
             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,
@@ -1999,13 +1995,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`).
      */
     // Adapter that lets `forEachLive(cb)` delegate to `forEachLiveWithCtx(cb, _invokeNoCtx)` —
     // keeps the no-ctx path closure-free and shares one walker implementation.
@@ -2019,10 +2015,10 @@
         // 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)) {
@@ -2051,7 +2047,7 @@
             // 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 —
@@ -2061,13 +2057,13 @@
             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)
@@ -2077,7 +2073,7 @@
     }
 
     /**
-     * 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.
      */
@@ -2090,7 +2086,7 @@
         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.
@@ -2116,7 +2112,7 @@
         }
     }
     /**
-     * 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.
      *
@@ -2155,14 +2151,14 @@
             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;
@@ -2172,7 +2168,7 @@
         // `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();
         }
@@ -2477,7 +2473,7 @@
      *
      *   - 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
@@ -2497,12 +2493,12 @@
     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
@@ -2529,7 +2525,7 @@
      * 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;
         /**
@@ -2548,8 +2544,8 @@
         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.
          */
@@ -2620,10 +2616,10 @@
         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; }
@@ -2632,7 +2628,7 @@
         // @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;
         }
@@ -2656,7 +2652,7 @@
             // 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;
@@ -2666,15 +2662,15 @@
         }
         // @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
@@ -2933,7 +2929,7 @@
             // 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;
@@ -2966,7 +2962,7 @@
                 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, exports.OPERATION.ADD);
@@ -2990,7 +2986,7 @@
             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.
@@ -3020,11 +3016,23 @@
          * 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);
@@ -3091,9 +3099,11 @@
                 }
                 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 ?? exports.OPERATION.DELETE);
             else
@@ -3299,7 +3309,9 @@
      * @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 === exports.OPERATION.DELETE) {
@@ -3495,8 +3507,8 @@
     /**
      * 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) {
@@ -3510,7 +3522,7 @@
      * 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
@@ -3535,11 +3547,11 @@
         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];
@@ -3564,7 +3576,7 @@
         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) {
@@ -5883,7 +5895,7 @@
      * 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 {
@@ -6158,12 +6170,11 @@
         _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;
@@ -6198,38 +6209,43 @@
             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;
         }
         /**
@@ -6241,8 +6257,8 @@
          * 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
@@ -6284,9 +6300,12 @@
          * 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)
          * )
          * ```
          */
@@ -6321,12 +6340,11 @@
                 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,
@@ -6580,25 +6598,44 @@
             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) {
@@ -6970,11 +7007,10 @@
             }
         };
         const viewTagFields = {};
-        const ownedFields = [];
         const unreliableFields = [];
-        const transientFields = [];
+        const patchOnlyFields = [];
         const deprecatedFields = {};
-        const staticFields = [];
+        const fullStateOnlyFields = [];
         const streamFields = [];
         const streamPriorityFields = {};
         const optionalFields = [];
@@ -6986,15 +7022,22 @@
                     // 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)) {
@@ -7005,20 +7048,17 @@
                 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);
@@ -7101,22 +7141,19 @@
         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);
@@ -7765,7 +7802,7 @@
             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
@@ -7855,14 +7892,10 @@
             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;
@@ -7876,16 +7909,18 @@
             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) {
@@ -7907,12 +7942,12 @@
                 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;
             }
@@ -7921,6 +7956,7 @@
                 list.tail.next = node;
                 list.tail = node;
             }
+            node.position = list.nextPosition++;
             return node;
         }
         /**
@@ -8019,6 +8055,7 @@
             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`
@@ -8058,10 +8095,13 @@
         }
         // 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;
@@ -8116,7 +8156,7 @@
             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,
         };
@@ -8173,6 +8213,7 @@
                 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
@@ -8424,7 +8465,7 @@
                     // 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) {
@@ -8503,20 +8544,81 @@
                 // `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();
@@ -9871,6 +9973,31 @@
         _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;
         /**
@@ -10095,12 +10222,12 @@
         }
         _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
             ) {
                 /**
@@ -10381,9 +10508,9 @@
             }
         }
         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 ─────────────────────────────
@@ -10521,32 +10648,47 @@
         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
@@ -10592,7 +10734,7 @@
         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))
@@ -10721,15 +10863,15 @@
     exports.encodeMapEntry = encodeMapEntry;
     exports.encodeSchemaOperation = encodeSchemaOperation;
     exports.entity = entity;
+    exports.fullStateOnly = fullStateOnly;
     exports.getDecoderStateCallbacks = getDecoderStateCallbacks;
     exports.getEncodeDescriptor = getEncodeDescriptor;
     exports.getRawChangesCallback = getRawChangesCallback;
     exports.isBuilder = isBuilder;
-    exports.owned = owned;
+    exports.patchOnly = patchOnly;
     exports.registerType = registerType;
     exports.schema = schema;
     exports.t = t;
-    exports.transient = transient;
     exports.type = type;
     exports.unreliable = unreliable;
     exports.view = view;