@colyseus/schema 5.0.9 → 5.0.11

package/build/types/custom/ArraySchema.d.ts

@@ -55,7 +55,15 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
      */
     pop(): V | undefined;
     at(index: number): V;
-    protected $changeAt(index: number, value: V): void;
+    /**
+     * items-index → wire (tmpItems) index. Identity while no deletions are
+     * staged this tick; otherwise maps to the index-th live (non-deleted)
+     * tmpItems slot — the same live-index walk `splice()` uses. Without the
+     * translation, index writes recorded after a same-tick `shift()`/`splice()`
+     * land on the wrong wire slots.
+     */
+    protected $wireIndex(index: number): number;
+    protected $changeAt(index: number, value: V): number | undefined;
     protected $deleteAt(index: number, operation?: OPERATION): void;
     protected $setAt(index: number, value: V, operation: OPERATION): void;
     clear(): void;

package/build/types/custom/MapSchema.d.ts

@@ -71,11 +71,28 @@ export declare class MapSchema<V = any, K extends string = string> implements Ma
      */
     static initializeForDecoder<V = any, K extends string = string>(): MapSchema<V, K>;
     /** Iterator */
-    [Symbol.iterator](): IterableIterator<[K, V]>;
+    [Symbol.iterator](): ReturnType<Map<K, V>[typeof Symbol.iterator]>;
     get [Symbol.toStringTag](): string;
     static get [Symbol.species](): typeof MapSchema;
     set(key: K, value: V): this;
     get(key: K): V | undefined;
+    /**
+     * Returns the value for `key` if present. Otherwise inserts `defaultValue`
+     * (tracked as an ADD change, like `set()`) and returns it.
+     *
+     * Mirrors `Map.prototype.getOrInsert` (TC39 "upsert" proposal, typed in
+     * TypeScript 6's standard library).
+     */
+    getOrInsert(key: K, defaultValue: V): V;
+    /**
+     * Returns the value for `key` if present. Otherwise computes a value via
+     * `callbackfn(key)`, inserts it (tracked as an ADD change, like `set()`)
+     * and returns it. The callback is only invoked when the key is missing.
+     *
+     * Mirrors `Map.prototype.getOrInsertComputed` (TC39 "upsert" proposal,
+     * typed in TypeScript 6's standard library).
+     */
+    getOrInsertComputed(key: K, callbackfn: (key: K) => V): V;
     delete(key: K): boolean;
     clear(): void;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colyseus/schema",
-  "version": "5.0.9",
+  "version": "5.0.11",
   "description": "Binary state serializer with delta encoding for games",
   "type": "module",
   "bin": {
@@ -17,7 +17,8 @@
     "build": "tsc -p tsconfig.build.json && rollup -c rollup.config.mjs",
     "watch": "tsc -p tsconfig.build.json -w",
     "typecheck:build": "tsc -p tsconfig.build.json --noEmit",
-    "test": "tsx --tsconfig tsconfig.test.json ./node_modules/mocha/bin/mocha.js \"test/*.test.ts\" \"test/**/*.test.ts\"",
+    "test": "npm run test:types && tsx --tsconfig tsconfig.test.json ./node_modules/mocha/bin/mocha.js \"test/*.test.ts\" \"test/**/*.test.ts\"",
+    "test:types": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
     "test:exports": "node test/verify-exports.mjs",
     "typecheck": "tsc -p tsconfig.test.json",
     "coverage": "c8 npm run test",
@@ -96,7 +97,12 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "typescript": "^5.0.0 || ^6.0.0"
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "c8": {
     "include": [

package/src/codegen/cli.ts

@@ -1,7 +1,7 @@
 import argv from "./argv.js";
 import { generate, generators } from "./api.js";
 
-function displayHelp() {
+function displayHelp(exitCode: number = 0) {
     console.log(`\nschema-codegen [path/to/Schema.ts]
 
 Usage (C#/Unity)
@@ -22,7 +22,7 @@ ${Object.
 Optional:
     --namespace: generate namespace on output code
     --decorator: custom name for @type decorator to scan for`);
-    process.exit();
+    process.exit(exitCode);
 }
 
 const args = argv(process.argv.slice(2));
@@ -39,7 +39,7 @@ for (let target in generators) {
 
 if (!args.output) {
     console.error("You must provide a valid --output directory.");
-    displayHelp();
+    displayHelp(1);
 }
 
 try {
@@ -55,5 +55,5 @@ try {
 } catch (e) {
     console.error(e.message);
     console.error(e.stack);
-    displayHelp();
+    displayHelp(1);
 }

package/src/codegen/parser.ts

@@ -419,6 +419,14 @@ export function parseFiles(
     decoratorName: string = "type",
     context: Context = new Context()
 ) {
+    if (typeof ts.createSourceFile !== "function") {
+        // typescript@7+ (native) no longer ships the JS compiler API
+        throw new Error(
+            `schema-codegen requires the TypeScript compiler API, which the installed "typescript@${(ts as any).version}" package does not provide.\n` +
+            `TypeScript 7+ no longer ships the JS compiler API — install typescript 5.x or 6.x (e.g. \`npm install --save-dev typescript@6\`) to use schema-codegen.`
+        );
+    }
+
     /**
      * Re-set globalContext for each test case
      */
@@ -469,7 +477,8 @@ export function parseFiles(
 
                 break;
             } catch (e) {
-                // console.log(`${fileNameAlternatives[i]} => ${e.message}`);
+                // only swallow fs errors (ENOENT/EISDIR) while probing alternatives
+                if (!e?.code) { throw e; }
             }
         }
 

package/src/decoder/DecodeOperation.ts

@@ -349,7 +349,11 @@ export const decodeKeyValueOperation: DecodeOperation = function (
                 break;
 
             case CollectionKind.Array:
-                tgt.$setAt(index, value, operation);
+                // resync snapshot ADDs are positional overwrites, not inserts
+                tgt.$setAt(index, value,
+                    (decoder.resyncVisited !== null && operation === OPERATION.ADD)
+                        ? OPERATION.REPLACE
+                        : operation);
                 break;
 
             // SetSchema / CollectionSchema / StreamSchema — use the wire-
@@ -430,9 +434,13 @@ export const decodeArray: DecodeOperation = function (
         return;
 
     } else if (operation === OPERATION.DELETE_BY_REFID) {
-        // TODO: refactor here, try to follow same flow as below
         const refId = decode.number(bytes, it);
         const previousValue = decoder.root.refs.get(refId);
+
+        // Stale DELETE — refId unknown to this decoder (e.g. it
+        // bootstrapped via encodeAll after the item was already removed).
+        if (previousValue === undefined) { return; }
+
         // Decrement the removed child's ref-count so it can be garbage
         // collected — this refId-based branch returns early and never reaches
         // decodeValue(), so it must do the same DELETE bookkeeping itself.
@@ -440,10 +448,14 @@ export const decodeArray: DecodeOperation = function (
         // different type → "field not defined" / "definition mismatch"
         // (surfaces under StateView when a filtered ArraySchema element is
         // spliced while its parent moves through view membership churn).
-        if (previousValue !== undefined) {
-            decoder.root.removeRef(refId);
-        }
+        // Must run even when the item is absent from THIS array (view churn).
+        decoder.root.removeRef(refId);
+
         index = tgt.findIndex((value: any) => value === previousValue);
+
+        // Item not present in this decoder's array — nothing to remove locally.
+        if (index === -1) { return; }
+
         tgt[$deleteByIndex](index);
         allChanges?.push({
             ref,
@@ -503,9 +515,13 @@ export const decodeArray: DecodeOperation = function (
 
     if (
         value !== null && value !== undefined &&
-        value !== previousValue // avoid setting same value twice (if index === 0 it will result in a "unshift" for ArraySchema)
+        value !== previousValue // avoid setting same value twice (an ADD at an occupied index would splice-insert)
     ) {
-        tgt.$setAt(index, value, operation);
+        // resync snapshot ADDs are positional overwrites, not inserts
+        tgt.$setAt(index, value,
+            (decoder.resyncVisited !== null && operation === OPERATION.ADD)
+                ? OPERATION.REPLACE
+                : operation);
     }
 
     // add change

package/src/encoder/ChangeTree.ts

@@ -232,7 +232,6 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     // per-view WeakSet lookups with direct bitwise ops.
     // Lazy: undefined until the tree participates in any view.
     visibleViews?: number[];
-    invisibleViews?: number[];
 
     // Per-(view, tag) bitmap, indexed by tag. Custom tags only —
     // DEFAULT_VIEW_TAG visibility lives in `visibleViews`.
@@ -586,17 +585,31 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         // per-view visibility lives on the tree (NOT keyed by refId), so a
         // recycled tree must not inherit its previous life's view membership.
         this.visibleViews = undefined;
-        this.invisibleViews = undefined;
         this.tagViews = undefined;
         this.subscribedViews = undefined;
     }
 
-    shift(shiftIndex: number): void {
-        if (this._isSchema) throw new Error("ChangeTree (Schema): shift is not supported");
+    /**
+     * ArraySchema#unshift(): re-key pending ops on both channels by
+     * `+count`, then record ADDs for the new items at indexes 0..count-1.
+     *
+     * The rebuilt map's insertion order IS the wire order: new ADDs first
+     * (ascending — the decoder splice-inserts each one, which only works
+     * lowest-index-first), then prior ops in their original relative order
+     * at their shifted positions. See ArraySchema#$setAt.
+     */
+    unshift(count: number): void {
+        if (this._isSchema) throw new Error("ChangeTree (Schema): unshift is not supported");
         const src = this.collDirty!;
         const dst = new Map<number, OPERATION>();
-        for (const [idx, val] of src) dst.set(idx + shiftIndex, val);
+        const track = !this.paused && !this.isStatic;
+        if (track) {
+            for (let i = 0; i < count; i++) dst.set(i, OPERATION.ADD);
+        }
+        for (const [idx, val] of src) dst.set(idx + count, val);
         this.collDirty = dst;
+        (this.unreliableRecorder as ICollectionChangeRecorder | undefined)?.shift(count);
+        if (track) this.root?.enqueueChangeTree(this);
     }
 
     // Tree attachment + child iteration — see ./changeTree/treeAttachment.ts.
@@ -665,13 +678,6 @@ export class ChangeTree<T extends Ref = any> implements ChangeRecorder {
         this._routeAndRecord(index, operation, true);
     }
 
-    // ArraySchema#unshift(): apply shift to both channels.
-    // Unreliable recorder on an array is always a CollectionChangeRecorder.
-    shiftChangeIndexes(shiftIndex: number) {
-        this.shift(shiftIndex);
-        (this.unreliableRecorder as ICollectionChangeRecorder | undefined)?.shift(shiftIndex);
-    }
-
     getChange(index: number) {
         return this.operationAt(index);
     }

package/src/encoder/EncodeOperation.ts

@@ -224,7 +224,8 @@ export const encodeArray: EncodeOperation = function (
     // ArraySchema stores its per-instance child type at `$childType`.
     // This encoder is array-only — there's no Schema fallback to consider.
     const type = ref[$childType];
-    const useOperationByRefId = hasView && changeTree.isFiltered && typeof type !== "string";
+    const isSchemaChild = typeof type !== "string";
+    const useOperationByRefId = hasView && changeTree.isFiltered && isSchemaChild;
 
     let refOrIndex: number;
 
@@ -243,6 +244,18 @@ export const encodeArray: EncodeOperation = function (
             operation = OPERATION.ADD_BY_REFID;
         }
 
+    } else if (operation === OPERATION.DELETE && isSchemaChild) {
+        //
+        // DELETE by identity: idempotent, so a stale positional DELETE
+        // (pending in the shared queue when a client bootstraps via
+        // encodeAll) can't corrupt that client — its snapshot no longer
+        // holds the item, the refId is unknown, and the decoder skips.
+        //
+        const item = ref.tmpItems[field];
+        if (!item) { return; }
+        refOrIndex = item[$refId];
+        operation = OPERATION.DELETE_BY_REFID;
+
     } else {
         refOrIndex = field;
     }

package/src/encoder/Encoder.ts

@@ -119,16 +119,7 @@ function _fullSyncWalk(ctx: EncodeCtx, changeTree: ChangeTree): void {
     // Visibility gate: when a view is active, a non-visible tree contributes
     // nothing itself but we still recurse so descendants (possibly added to
     // the view explicitly) are reachable.
-    let visibleHere = true;
-    if (ctx.hasView) {
-        const view = ctx.view!;
-        if (!view.isChangeTreeVisible(changeTree)) {
-            view.markInvisible(changeTree);
-            visibleHere = false;
-        } else {
-            view.unmarkInvisible(changeTree);
-        }
-    }
+    const visibleHere = !ctx.hasView || ctx.view!.isChangeTreeVisible(changeTree);
 
     if (visibleHere) {
         const desc = changeTree.encDescriptor;
@@ -313,12 +304,8 @@ export class Encoder<T extends Schema = any> {
         while (current = current.next) {
             const changeTree = (current as ChangeTreeNode).changeTree;
 
-            if (hasView) {
-                if (!view.isChangeTreeVisible(changeTree)) {
-                    view.markInvisible(changeTree);
-                    continue;
-                }
-                view.unmarkInvisible(changeTree);
+            if (hasView && !view.isChangeTreeVisible(changeTree)) {
+                continue;
             }
 
             const recorder = unreliable ? changeTree.unreliableRecorder : changeTree;

package/src/encoder/StateView.ts

@@ -28,8 +28,6 @@ function _clearViewBitFromAllTrees(root: Root, slot: number, bit: number): void
         const tree = trees[refId];
         const v = tree.visibleViews;
         if (v !== undefined && slot < v.length) v[slot] &= clearMask;
-        const i = tree.invisibleViews;
-        if (i !== undefined && slot < i.length) i[slot] &= clearMask;
         const s = tree.subscribedViews;
         if (s !== undefined && slot < s.length) s[slot] &= clearMask;
         const t = tree.tagViews;
@@ -192,32 +190,6 @@ export class StateView {
         if (slot < arr.length) arr[slot] &= ~this._bit;
     }
 
-    /** True iff this view has previously marked `tree` as invisible. */
-    public isInvisible(tree: ChangeTree): boolean {
-        const arr = tree.invisibleViews;
-        const slot = this._slot;
-        return arr !== undefined && slot < arr.length && (arr[slot] & this._bit) !== 0;
-    }
-
-    /** Mark `tree` as invisible to this view (used by encode loop). */
-    public markInvisible(tree: ChangeTree): void {
-        const slot = this._slot;
-        let arr = tree.invisibleViews;
-        if (arr === undefined) {
-            arr = tree.invisibleViews = [];
-        }
-        while (arr.length <= slot) arr.push(0);
-        arr[slot] |= this._bit;
-    }
-
-    /** Clear invisible bit. */
-    public unmarkInvisible(tree: ChangeTree): void {
-        const arr = tree.invisibleViews;
-        if (arr === undefined) return;
-        const slot = this._slot;
-        if (slot < arr.length) arr[slot] &= ~this._bit;
-    }
-
     // ──────────────────────────────────────────────────────────────────
     // Per-tag, per-view bitmap. Replaces the legacy
     // `tags: WeakMap<ChangeTree, Set<number>>` storage. Hot read site is
@@ -371,13 +343,20 @@ export class StateView {
         // subclasses yield a real Metadata object.
         const metadata: Metadata = (obj.constructor as typeof Schema)[Symbol.metadata];
 
-        this.markVisible(changeTree);
-
-        // add to iterable list (only the explicitly added items)
-        if (this.iterable && checkIncludeParent) {
+        // Add to iterable list (only the explicitly added items), deduping
+        // re-adds of an already-visible instance. isVisible must be read
+        // BEFORE markVisible; indexOf runs only on the re-add path.
+        // NOTE: dedup applies to `items` only — a re-add still re-queues the
+        // full snapshot on purpose (shared-view bootstrap re-add: a
+        // late-attached client may not have consumed earlier drains).
+        // Callers wanting cheap idempotence can guard with `view.has(obj)`.
+        if (this.iterable && checkIncludeParent
+            && (!this.isVisible(changeTree) || this.items.indexOf(obj) === -1)) {
             this.items.push(obj);
         }
 
+        this.markVisible(changeTree);
+
         // add parent ChangeTree's
         // - if it was invisible to this view
         // - if it were previously filtered out
@@ -468,7 +447,6 @@ export class StateView {
 
         } else if (!changeTree.isNew || isChildAdded) {
             // new structures will be added as part of .encode() call, no need to force it to .encodeView()
-            const isInvisible = this.isInvisible(changeTree);
 
             // Full-sync snapshot: walk the live ref structurally instead of
             // iterating a cumulative recorder bucket. Every populated index
@@ -476,11 +454,14 @@ export class StateView {
             // at encode time). Per-field tags come from the descriptor's
             // precomputed `tags[]` array — direct index vs a metadata[i].tag
             // object hop.
+            //
+            // Non-matching custom-tagged fields are NEVER included here —
+            // `view.changes` is drained without a per-field tag re-check,
+            // so anything added leaks straight to the wire.
             const tags = changeTree.encDescriptor.tags;
             changeTree.forEachLive((index) => {
                 const tagAtIndex = tags[index];
                 if (
-                    isInvisible || // if "invisible", include all
                     tagAtIndex === undefined || // "all change" with no tag
                     tagAtIndex === DEFAULT_VIEW_TAG || // visible to all clients
                     (tag !== DEFAULT_VIEW_TAG && (tagAtIndex & tag) !== 0) // tag bits overlap
@@ -652,7 +633,7 @@ export class StateView {
 
         // ── Streamable-collection unsubscribe (the stream itself) ─────
         // Flush DELETE for every sent position and drop pending. After
-        // this, the stream is marked invisible to this view — any future
+        // this, the stream is no longer visible to this view — any future
         // `stream.add()` would still seed broadcast pending (if no views)
         // but would NOT re-seed per-view pending (user must re-subscribe).
         if (changeTree.isStreamCollection) {

package/src/types/custom/ArraySchema.ts

@@ -44,33 +44,40 @@ const ARRAY_PROXY_HANDLER: ProxyHandler<any> = {
                 obj.$deleteAt(key as unknown as number);
 
             } else {
+                // wire slot the write was recorded at; undefined = nothing
+                // recorded (same value / skipped) — must NOT touch tmpItems
+                // then, or a same-tick shifted layout gets clobbered.
+                let wireIndex: number | undefined;
+
                 if (setValue[$changes]) {
                     assertInstanceType(setValue, obj[$childType] as typeof Schema, obj, key);
 
                     const previousValue = obj.items[key as unknown as number];
 
                     if (!obj.isMovingItems) {
-                        obj.$changeAt(Number(key), setValue);
+                        wireIndex = obj.$changeAt(Number(key), setValue);
 
                     } else {
+                        wireIndex = obj.$wireIndex(Number(key));
+
                         if (previousValue !== undefined) {
                             if (setValue[$changes].isNew) {
-                                obj[$changes].indexedOperation(Number(key), OPERATION.MOVE_AND_ADD);
+                                obj[$changes].indexedOperation(wireIndex, OPERATION.MOVE_AND_ADD);
 
                             } else {
-                                if ((obj[$changes].getChange(Number(key)) & OPERATION.DELETE) === OPERATION.DELETE) {
-                                    obj[$changes].indexedOperation(Number(key), OPERATION.DELETE_AND_MOVE);
+                                if ((obj[$changes].getChange(wireIndex) & OPERATION.DELETE) === OPERATION.DELETE) {
+                                    obj[$changes].indexedOperation(wireIndex, OPERATION.DELETE_AND_MOVE);
 
                                 } else {
-                                    obj[$changes].indexedOperation(Number(key), OPERATION.MOVE);
+                                    obj[$changes].indexedOperation(wireIndex, OPERATION.MOVE);
                                 }
                             }
 
                         } else if (setValue[$changes].isNew) {
-                            obj[$changes].indexedOperation(Number(key), OPERATION.ADD);
+                            obj[$changes].indexedOperation(wireIndex, OPERATION.ADD);
                         }
 
-                        setValue[$changes].setParent(obj, obj[$changes].root, key);
+                        setValue[$changes].setParent(obj, obj[$changes].root, wireIndex);
                     }
 
                     if (previousValue !== undefined) {
@@ -79,11 +86,13 @@ const ARRAY_PROXY_HANDLER: ProxyHandler<any> = {
                     }
 
                 } else {
-                    obj.$changeAt(Number(key), setValue);
+                    wireIndex = obj.$changeAt(Number(key), setValue);
                 }
 
                 obj.items[key as unknown as number] = setValue;
-                obj.tmpItems[key as unknown as number] = setValue;
+                if (wireIndex !== undefined) {
+                    obj.tmpItems[wireIndex] = setValue;
+                }
             }
 
             return true;
@@ -300,16 +309,39 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         return this.items[index];
     }
 
-    // encoding only
-    protected $changeAt(index: number, value: V) {
+    /**
+     * items-index → wire (tmpItems) index. Identity while no deletions are
+     * staged this tick; otherwise maps to the index-th live (non-deleted)
+     * tmpItems slot — the same live-index walk `splice()` uses. Without the
+     * translation, index writes recorded after a same-tick `shift()`/`splice()`
+     * land on the wrong wire slots.
+     */
+    protected $wireIndex(index: number): number {
+        const deletedIndexes = this.deletedIndexes;
+        if (deletedIndexes.length === 0) { return index; }
+        const tmpItems = this.tmpItems;
+        let live = 0;
+        for (let i = 0; i < tmpItems.length; i++) {
+            if (deletedIndexes[i] !== true) {
+                if (live === index) { return i; }
+                live++;
+            }
+        }
+        // beyond the live range: appends land after the staged tmpItems tail
+        return tmpItems.length + (index - live);
+    }
+
+    // encoding only. Returns the wire index the change was recorded at
+    // (undefined when nothing was recorded).
+    protected $changeAt(index: number, value: V): number | undefined {
         if (value === undefined || value === null) {
-            console.error("ArraySchema items cannot be null nor undefined; Use `deleteAt(index)` instead.");
-            return;
+            console.error("ArraySchema items cannot be null nor undefined; Use `splice(index, 1)` instead.");
+            return undefined;
         }
 
         // skip if the value is the same as cached.
         if (this.items[index] === value) {
-            return;
+            return undefined;
         }
 
         const operation = (this.items[index] !== undefined)
@@ -318,30 +350,34 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
                 : OPERATION.REPLACE // primitive
             : OPERATION.ADD;
 
+        const wireIndex = this.$wireIndex(index);
+
         const changeTree = this[$changes];
-        changeTree.change(index, operation);
+        changeTree.change(wireIndex, operation);
 
         //
         // set value's parent after the value is set
         // (to avoid encoding "refId" operations before parent's "ADD" operation)
         //
-        value[$changes]?.setParent(this, changeTree.root, index);
+        value[$changes]?.setParent(this, changeTree.root, wireIndex);
+
+        return wireIndex;
     }
 
     // encoding only
     protected $deleteAt(index: number, operation?: OPERATION) {
-        this[$changes].delete(index, operation);
+        this[$changes].delete(this.$wireIndex(index), operation);
     }
 
     // decoding only
     protected $setAt(index: number, value: V, operation: OPERATION) {
         if (
-            index === 0 &&
             operation === OPERATION.ADD &&
             this.items[index] !== undefined
         ) {
-            // handle decoding unshift
-            this.items.unshift(value);
+            // ADD at an occupied index = insert (unshift / splice-insert):
+            // shift existing items up instead of overwriting.
+            this.items.splice(index, 0, value);
 
         } else if (operation === OPERATION.DELETE_AND_MOVE) {
             this.items.splice(index, 1);
@@ -436,10 +472,14 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         if (items.length === 0) { return undefined; }
 
         const changeTree = self[$changes];
-        const first = items[0];
-        const index = self.tmpItems.findIndex(item => item === first);
+        // items[0] ≡ first live (non-deleted) tmpItems slot. Value-based
+        // findIndex is unsafe here: same-tick index writes can duplicate a
+        // value across tmp slots and resolve the wrong one.
+        const deletedIndexes = self.deletedIndexes;
+        let index = 0;
+        while (deletedIndexes[index] === true) { index++; }
         changeTree.delete(index, OPERATION.DELETE);
-        self.deletedIndexes[index] = true;
+        deletedIndexes[index] = true;
 
         return items.shift();
     }
@@ -564,13 +604,20 @@ export class ArraySchema<V = any> implements Array<V>, Collection<number, V>, IR
         const self = this[$proxyTarget];
         const changeTree = self[$changes];
 
-        // Existing items shift up — `shiftChangeIndexes` handles their
-        // relocation bookkeeping. The prepended `items` are genuinely new
-        // (no prior existence to MOVE), so each records an ADD.
-        changeTree.shiftChangeIndexes(items.length);
-        items.forEach((_, index) => {
-            changeTree.change(index, OPERATION.ADD)
-        });
+        // single recorder op: shifts pending indexes up and records the new
+        // ADDs lowest-first (the decoder splice-inserts in ascending order).
+        changeTree.unshift(items.length);
+
+        // attach ref-type items — parent set AFTER recording, as in $changeAt
+        for (let i = 0; i < items.length; i++) {
+            items[i]?.[$changes]?.setParent(this, changeTree.root, i);
+        }
+
+        // keep staged-delete flags aligned with the prepended tmp slots
+        const deletedIndexes = self.deletedIndexes;
+        if (deletedIndexes.length > 0) {
+            deletedIndexes.unshift(...new Array(items.length).fill(false));
+        }
 
         self.tmpItems.unshift(...items);