@colyseus/schema 4.0.20 → 5.0.1

package/build/decoder/DecodeOperation.d.ts

@@ -7,17 +7,60 @@ export interface DataChange<T = any, F = string> {
     ref: IRef;
     refId: number;
     op: OPERATION;
-    field: F;
+    /** Set for Schema field changes; omitted for collection item changes (which carry a `dynamicIndex` instead). */
+    field?: F;
     dynamicIndex?: number | string;
     value: T;
     previousValue: T;
 }
 export declare const DEFINITION_MISMATCH = -1;
-export type DecodeOperation<T extends Schema = any> = (decoder: Decoder<T>, bytes: Uint8Array, it: Iterator, ref: IRef, allChanges: DataChange[]) => number | void;
-export declare function decodeValue<T extends Ref>(decoder: Decoder, operation: OPERATION, ref: T, index: number, type: any, bytes: Uint8Array, it: Iterator, allChanges: DataChange[]): {
-    value: any;
-    previousValue: T;
+/**
+ * When no `triggerChanges` subscriber is attached, `Decoder.decode` passes
+ * `null` so the per-field change objects are never allocated. Every push
+ * site uses `allChanges?.push(...)` — optional chaining also short-circuits
+ * the object literal, so there's nothing to collect and nothing to throw
+ * away.
+ */
+export type DecodeOperation<T extends Schema = any> = (decoder: Decoder<T>, bytes: Uint8Array, it: Iterator, ref: IRef, allChanges: DataChange[] | null) => number | void;
+/**
+ * Collection-kind discriminator declared on each collection class as
+ * `static COLLECTION_KIND = CollectionKind.X`. The decoder's key/value
+ * dispatch used to make three back-to-back `typeof(ref.method) ===
+ * "function"` checks per entry; those collapse into one switch on the
+ * target's class tag. Missing / `undefined` on a ref hits the switch's
+ * `default` branch and logs a warning — a guard for future collection
+ * types that land without a tag.
+ *
+ * Declared as a `const` object (not a TS `enum`) so the codegen parser —
+ * which picks up every `EnumDeclaration` in the lib source via transitive
+ * imports — doesn't emit a generated .cs file for it.
+ */
+export declare const CollectionKind: {
+    readonly Map: 1;
+    readonly Array: 2;
+    readonly Set: 3;
+    readonly Collection: 4;
+    readonly Stream: 5;
 };
+export type CollectionKind = typeof CollectionKind[keyof typeof CollectionKind];
+/**
+ * Structural type for any class that participates in the `decodeKeyValue-
+ * Operation` dispatch. Lets the hot-path read `tgt.constructor.COLLECTION_KIND`
+ * without an `any` cast.
+ */
+export interface CollectionCtor {
+    readonly COLLECTION_KIND: CollectionKind;
+}
+/**
+ * Decode the next wire value for `ref[index]`. Returns the decoded value.
+ *
+ * Callers pass `previousValue` explicitly — it's the current value at the
+ * slot before decoding and is needed for ref-count bookkeeping (on DELETE)
+ * and for the DELETE_AND_ADD self-reassign case. Keeping it as a parameter
+ * lets this function return a single primitive instead of a pair, so the
+ * hot call path allocates nothing.
+ */
+export declare function decodeValue<T extends Ref>(decoder: Decoder, operation: OPERATION, ref: T, index: number, previousValue: any, type: any, bytes: Uint8Array, it: Iterator, allChanges: DataChange[] | null): any;
 export declare const decodeSchemaOperation: DecodeOperation;
 export declare const decodeKeyValueOperation: DecodeOperation;
 export declare const decodeArray: DecodeOperation;

package/build/decoder/Decoder.d.ts

@@ -1,6 +1,6 @@
 import { TypeContext } from "../types/TypeContext.js";
 import { Schema } from "../Schema.js";
-import type { IRef } from "../encoder/ChangeTree.js";
+import { type IRef } from "../encoder/ChangeTree.js";
 import type { Iterator } from "../encoding/decode.js";
 import { ReferenceTracker } from "./ReferenceTracker.js";
 import { type DataChange } from "./DecodeOperation.js";
@@ -17,5 +17,5 @@ export declare class Decoder<T extends IRef = any> {
     skipCurrentStructure(bytes: Uint8Array, it: Iterator, totalBytes: number): void;
     getInstanceType(bytes: Uint8Array, it: Iterator, defaultType: typeof Schema): typeof Schema;
     createInstanceOfType(type: typeof Schema): Schema;
-    removeChildRefs(ref: Collection, allChanges: DataChange[]): void;
+    removeChildRefs(ref: Collection, allChanges: DataChange[] | null): void;
 }

package/build/decoder/strategy/Callbacks.d.ts

@@ -36,7 +36,7 @@ export declare class StateCallbackStrategy<TState extends IRef> {
     /**
      * Listen to property changes on a nested instance.
      */
-    listen<TInstance, K extends PublicPropNames<TInstance>>(instance: TInstance, property: K, handler: PropertyChangeCallback<TInstance[K]>, immediate?: boolean): () => void;
+    listen<TInstance extends Schema, K extends PublicPropNames<TInstance>>(instance: TInstance, property: K, handler: PropertyChangeCallback<TInstance[K]>, immediate?: boolean): () => void;
     protected listenInstance<TInstance extends IRef>(instance: TInstance, propertyName: string, handler: PropertyChangeCallback<any>, immediate?: boolean): () => void;
     /**
      * Listen to any property change on an instance.

package/build/encoder/ChangeRecorder.d.ts

@@ -0,0 +1,107 @@
+import { OPERATION } from "../encoding/spec.js";
+/**
+ * ChangeRecorder — "what changed this tick" for a single ref.
+ *
+ * This file holds the two standalone recorder classes used for the
+ * unreliable channel (lazy, opt-in). The reliable channel is inlined on
+ * `ChangeTree` for perf; see `ChangeTree._isSchema` dispatch.
+ *
+ * Interface design (ISP):
+ *   - {@link ChangeRecorder}: common ops, implemented by both Schema and
+ *     Collection recorders.
+ *   - {@link ICollectionChangeRecorder}: extends with `recordPure` +
+ *     `shift` — collection-only. Schema recorders do NOT carry these.
+ *
+ * Per-field filter/visibility is decided at encode time, not record time.
+ * Full-sync output is derived structurally via `ChangeTree.forEachLive`.
+ */
+export interface ChangeRecorder {
+    /**
+     * Record a change at the given index. Handles op merge
+     * (DELETE followed by ADD becomes DELETE_AND_ADD).
+     */
+    record(index: number, op: OPERATION): void;
+    /** Record a DELETE at the given index. */
+    recordDelete(index: number, op: OPERATION): void;
+    /**
+     * Record an operation without op-merge semantics. Used by ArraySchema
+     * positional writes where DELETE→ADD merge is undesirable.
+     */
+    recordRaw(index: number, op: OPERATION): void;
+    /** Current operation at index, or undefined if none. */
+    operationAt(index: number): OPERATION | undefined;
+    /** Overwrite the operation at index. */
+    setOperationAt(index: number, op: OPERATION): void;
+    /**
+     * Iterate (index, op) pairs in record order.
+     * Pure operations emit with index = -op (wire convention).
+     */
+    forEach(cb: (index: number, op: OPERATION) => void): void;
+    /** Closure-free forEach variant for the hot encode path. */
+    forEachWithCtx<T>(ctx: T, cb: (ctx: T, index: number, op: OPERATION) => void): void;
+    size(): number;
+    has(): boolean;
+    reset(): void;
+}
+/**
+ * Extended recorder for collection types — adds `recordPure` (CLEAR /
+ * REVERSE) and `shift` (ArraySchema.unshift support).
+ */
+export interface ICollectionChangeRecorder extends ChangeRecorder {
+    /**
+     * Record a pure operation (CLEAR / REVERSE) with no index.
+     * Interleaves with indexed ops at record order.
+     */
+    recordPure(op: OPERATION): void;
+    /** Shift current-tick dirty indexes by `shiftIndex`. */
+    shift(shiftIndex: number): void;
+}
+/**
+ * Schema field operations are limited to ADD(128), DELETE(64), and
+ * DELETE_AND_ADD(192). REPLACE(0) is collection-only, so `ops[i] === 0`
+ * is a safe "no operation" sentinel.
+ */
+export declare class SchemaChangeRecorder implements ChangeRecorder {
+    private dirtyLow;
+    private dirtyHigh;
+    private readonly ops;
+    constructor(numFields: number);
+    record(index: number, op: OPERATION): void;
+    recordDelete(index: number, op: OPERATION): void;
+    recordRaw(index: number, op: OPERATION): void;
+    operationAt(index: number): OPERATION | undefined;
+    setOperationAt(index: number, op: OPERATION): void;
+    forEach(cb: (index: number, op: OPERATION) => void): void;
+    forEachWithCtx<T>(ctx: T, cb: (ctx: T, index: number, op: OPERATION) => void): void;
+    size(): number;
+    has(): boolean;
+    reset(): void;
+}
+/**
+ * Collection items have sparse indexes (e.g. 0, 7, 1024) exceeding the
+ * 64-field cap Schema imposes. Map-based storage handles arbitrary
+ * indexes; the value at each entry is the OPERATION.
+ *
+ * Pure operations (CLEAR, REVERSE) live in `pureOps` as `[position, op]`
+ * entries where `position` is `dirty.size` at record time — preserves
+ * insertion-order interleaving with indexed ops (e.g. CLEAR must emit
+ * BEFORE subsequent ADDs).
+ */
+export declare class CollectionChangeRecorder implements ICollectionChangeRecorder {
+    private dirty;
+    private pureOps;
+    record(index: number, op: OPERATION): void;
+    recordDelete(index: number, op: OPERATION): void;
+    recordRaw(index: number, op: OPERATION): void;
+    recordPure(op: OPERATION): void;
+    operationAt(index: number): OPERATION | undefined;
+    setOperationAt(index: number, op: OPERATION): void;
+    forEach(cb: (index: number, op: OPERATION) => void): void;
+    forEachWithCtx<T>(ctx: T, cb: (ctx: T, index: number, op: OPERATION) => void): void;
+    size(): number;
+    has(): boolean;
+    reset(): void;
+    shift(shiftIndex: number): void;
+}
+/** 32-bit Hamming weight (popcount). */
+export declare function popcount32(n: number): number;

package/build/encoder/ChangeTree.d.ts

@@ -1,3 +1,20 @@
+/**
+ * ChangeTree — the per-`Ref` mutation tracker attached via `$changes`.
+ *
+ * This file owns: class shape (fields, flags, ctor), inline
+ * ChangeRecorder implementation (record / forEach / …), mutation API
+ * (change / delete / operation / …), and encode lifecycle (endEncode /
+ * discard / …). Helpers split out into ./changeTree/:
+ *
+ *   - parentChain.ts     addParent / removeParent / find / has / getAll
+ *   - liveIteration.ts   forEachLive
+ *   - inheritedFlags.ts  filter / unreliable / transient / static inheritance
+ *   - treeAttachment.ts  setRoot / setParent / forEachChild(+WithCtx)
+ *
+ * Public surface on ChangeTree is unchanged — methods are thin pass-throughs
+ * into the helpers. V8 inlines the pass-throughs; the runtime shape stays
+ * a single class to preserve hidden-class + IC behavior.
+ */
 import { OPERATION } from "../encoding/spec.js";
 import { Schema } from "../Schema.js";
 import { $changes, $decoder, $encoder, $getByIndex, $refId, type $deleteByIndex } from "../types/symbols.js";
@@ -5,9 +22,12 @@ import type { MapSchema } from "../types/custom/MapSchema.js";
 import type { ArraySchema } from "../types/custom/ArraySchema.js";
 import type { CollectionSchema } from "../types/custom/CollectionSchema.js";
 import type { SetSchema } from "../types/custom/SetSchema.js";
+import type { StreamSchema } from "../types/custom/StreamSchema.js";
 import { Root } from "./Root.js";
 import { Metadata } from "../Metadata.js";
+import { type ChangeRecorder } from "./ChangeRecorder.js";
 import type { EncodeOperation } from "./EncodeOperation.js";
+import { type EncodeDescriptor } from "./EncodeDescriptor.js";
 import type { DecodeOperation } from "../decoder/DecodeOperation.js";
 declare global {
     interface Object {
@@ -18,14 +38,10 @@ declare global {
 }
 export interface IRef {
     [$refId]?: number;
-    [$getByIndex]?: (index: number, isEncodeAll?: boolean) => any;
-    [$deleteByIndex]?: (index: number) => void;
-}
-export type Ref = Schema | ArraySchema | MapSchema | CollectionSchema | SetSchema;
-export type ChangeSetName = "changes" | "allChanges" | "filteredChanges" | "allFilteredChanges";
-export interface IndexedOperations {
-    [index: number]: OPERATION;
+    [$getByIndex](index: number, isEncodeAll?: boolean): any;
+    [$deleteByIndex](index: number): void;
 }
+export type Ref = Schema | ArraySchema | MapSchema | CollectionSchema | SetSchema | StreamSchema;
 export interface ChangeTreeNode {
     changeTree: ChangeTree;
     next?: ChangeTreeNode;
@@ -36,99 +52,232 @@ export interface ChangeTreeList {
     next?: ChangeTreeNode;
     tail?: ChangeTreeNode;
 }
-export interface ChangeSet {
-    indexes: {
-        [index: number]: number;
-    };
-    operations: number[];
-    queueRootNode?: ChangeTreeNode;
-}
 export declare function createChangeTreeList(): ChangeTreeList;
-export declare function setOperationAtIndex(changeSet: ChangeSet, index: number): void;
-export declare function deleteOperationAtIndex(changeSet: ChangeSet, index: number | string): void;
-export declare function debugChangeSet(label: string, changeSet: ChangeSet): void;
 export interface ParentChain {
     ref: Ref;
     index: number;
     next?: ParentChain;
 }
-export declare class ChangeTree<T extends Ref = any> {
+export declare const IS_FILTERED = 1, IS_VISIBILITY_SHARED = 2, IS_NEW = 4;
+export declare const IS_UNRELIABLE = 8, IS_TRANSIENT = 16, IS_STATIC = 32;
+export declare const IS_STREAM_COLLECTION = 64;
+/**
+ * Flags a child inherits from its parent's own transitive state via
+ * `checkInheritedFlags`. Read as a bitwise mask so the inheritance step
+ * is a single OR instead of three getter/setter pairs.
+ *
+ * `IS_UNRELIABLE` is intentionally excluded: `@unreliable` is rejected
+ * at decoration time for ref-type fields (see `Metadata.setUnreliable`)
+ * because an unreliable ADD/DELETE could leave the decoder unable to
+ * interpret later packets referencing an orphan refId. Tree-level
+ * unreliable is therefore dead on every Schema/Collection tree today;
+ * the bit and its machinery are kept in place so this can be
+ * reconsidered if a safe semantics (e.g. reliable ADD + unreliable
+ * field mutations only) is designed later.
+ */
+export declare const INHERITABLE_FLAGS: number;
+export declare class ChangeTree<T extends Ref = any> implements ChangeRecorder {
     ref: T;
+    /**
+     * Non-Proxy target of `ref` for encoder hot-path reads. For
+     * `ArraySchema`, `ref` is the Proxy users interact with; every property
+     * access on it runs through the `get` trap (even for symbol keys, which
+     * fall through to `Reflect.get` — one extra hop per lookup). The encoder
+     * loop reads `[$getByIndex]`, `[$childType]`, `.items`, `.tmpItems` at
+     * high frequency during `encode()` / `encodeAll()`; going through
+     * `refTarget` skips all of those traps.
+     *
+     * For non-proxied types (Schema, MapSchema, SetSchema, CollectionSchema,
+     * StreamSchema), `refTarget === ref`. Consumers that need the user-
+     * facing identity (debug output, callback parents) keep using `ref`.
+     */
+    refTarget: T;
     metadata: Metadata;
+    /**
+     * Per-class cache of encoder fn / filter fn / isSchema / filterBitmask /
+     * metadata, looked up once at construction. The encode loop reads
+     * `tree.encDescriptor` and never touches `ref.constructor` again. See
+     * EncodeDescriptor.ts.
+     */
+    encDescriptor: EncodeDescriptor;
     root?: Root;
-    parentChain?: ParentChain;
+    parentRef?: Ref;
+    _parentIndex?: number;
+    extraParents?: ParentChain;
+    flags: number;
     /**
-     * Whether this structure is parent of a filtered structure.
+     * Per-walk visit stamp written by `Encoder.encodeFullSync`'s DFS. A
+     * tree is considered "already visited by the current walk" iff
+     * `tree._fullSyncGen === ctx.gen` — the encoder bumps its generation
+     * counter once per walk, then stamps each tree with that value on
+     * first visit; any later encounter of the same tree (shared refs
+     * reachable through multiple parents) short-circuits on the equality
+     * check instead of recursing again.
      */
-    isFiltered: boolean;
-    isVisibilitySharedWithParent?: boolean;
-    indexedOperations: IndexedOperations;
-    changes: ChangeSet;
-    allChanges: ChangeSet;
-    filteredChanges: ChangeSet;
-    allFilteredChanges: ChangeSet;
-    indexes: {
-        [index: string]: any;
-    };
+    _fullSyncGen: number;
+    _isSchema: boolean;
+    dirtyLow: number;
+    dirtyHigh: number;
+    opsLow: number;
+    opsHigh: number;
+    ops?: Uint8Array;
+    collDirty?: Map<number, OPERATION>;
+    collPureOps?: Array<[number, OPERATION]>;
+    unreliableRecorder?: ChangeRecorder;
+    paused: boolean;
+    changesNode?: ChangeTreeNode;
+    unreliableChangesNode?: ChangeTreeNode;
+    visibleViews?: number[];
+    invisibleViews?: number[];
+    tagViews?: Map<number, number[]>;
     /**
-     * Is this a new instance? Used on ArraySchema to determine OPERATION.MOVE_AND_ADD operation.
+     * Per-view subscription bitmap — same layout as `visibleViews`. Set by
+     * `StateView.subscribe(collection)` to mark the view as persistently
+     * interested in this collection's contents. When a new child is
+     * attached to a subscribed collection (setParent hook), it's
+     * auto-propagated to every subscribed view (force-shipped for
+     * Array/Map/Set/Collection; enqueued into per-view pending for
+     * streams). Undefined until the first subscribe.
      */
-    isNew: boolean;
+    subscribedViews?: number[];
+    get isFiltered(): boolean;
+    set isFiltered(v: boolean);
+    get isVisibilitySharedWithParent(): boolean;
+    set isVisibilitySharedWithParent(v: boolean);
+    get isNew(): boolean;
+    set isNew(v: boolean);
+    get isUnreliable(): boolean;
+    set isUnreliable(v: boolean);
+    get isTransient(): boolean;
+    set isTransient(v: boolean);
+    get isStatic(): boolean;
+    set isStatic(v: boolean);
+    get isStreamCollection(): boolean;
+    set isStreamCollection(v: boolean);
+    get hasFilteredFields(): boolean;
+    ensureUnreliableRecorder(): ChangeRecorder;
+    isFieldUnreliable(index: number): boolean;
+    isFieldStatic(index: number): boolean;
+    isFieldStream(index: number): boolean;
     constructor(ref: T);
+    private _opAt;
+    private _opPut;
+    private _markDirty;
+    record(index: number, op: OPERATION): void;
+    recordDelete(index: number, op: OPERATION): void;
+    recordRaw(index: number, op: OPERATION): void;
+    recordPure(op: OPERATION): void;
+    operationAt(index: number): OPERATION | undefined;
+    setOperationAt(index: number, op: OPERATION): void;
+    forEach(cb: (index: number, op: OPERATION) => void): void;
+    forEachWithCtx<C>(ctx: C, cb: (ctx: C, index: number, op: OPERATION) => void): void;
+    size(): number;
+    has(): boolean;
+    reset(): void;
+    shift(shiftIndex: number): void;
     setRoot(root: Root): void;
     setParent(parent: Ref, root?: Root, parentIndex?: number): void;
-    forEachChild(callback: (change: ChangeTree, at: any) => void): void;
+    forEachChild(cb: (change: ChangeTree, at: any) => void): void;
+    forEachChildWithCtx<C>(ctx: C, cb: (ctx: C, change: ChangeTree, at: any) => void): void;
+    forEachLive(cb: (index: number) => void): void;
+    forEachLiveWithCtx<C>(ctx: C, cb: (ctx: C, index: number) => void): void;
     operation(op: OPERATION): void;
+    /**
+     * Route a field-level mutation to the reliable or unreliable channel
+     * and enqueue into the matching queue. Shared by `change` and
+     * `indexedOperation`; `raw=true` bypasses DELETE→ADD merge
+     * (ArraySchema positional writes), `raw=false` merges inside `record`.
+     *
+     * Note: record() on both channels handles DELETE→ADD merge internally,
+     * so callers do not need to pre-compute the merged op.
+     *
+     * `@unreliable` is decoration-time-validated to apply only to primitive
+     * 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.
+     */
+    private _routeAndRecord;
     change(index: number, operation?: OPERATION): void;
+    indexedOperation(index: number, operation: OPERATION): void;
     shiftChangeIndexes(shiftIndex: number): void;
-    shiftAllChangeIndexes(shiftIndex: number, startIndex?: number): void;
-    private _shiftAllChangeIndexes;
-    indexedOperation(index: number, operation: OPERATION, allChangesIndex?: number): void;
-    getType(index?: number): any;
     getChange(index: number): OPERATION;
+    pause(): void;
+    resume(): void;
+    untracked<T>(fn: () => T): T;
+    markDirty(index: number, operation?: OPERATION): void;
     getValue(index: number, isEncodeAll?: boolean): any;
-    delete(index: number, operation?: OPERATION, allChangesIndex?: number): any;
-    endEncode(changeSetName: ChangeSetName): void;
-    discard(discardAll?: boolean): void;
-    /**
-     * Recursively discard all changes from this, and child structures.
-     * (Used in tests only)
-     */
+    delete(index: number, operation?: OPERATION): any;
+    endEncode(): void;
+    endEncodeUnreliable(): void;
+    discard(): void;
     discardAll(): void;
     get changed(): boolean;
-    protected checkIsFiltered(parent: Ref, parentIndex: number, isNewChangeTree: boolean): void;
-    protected _checkFilteredByParent(parent: Ref, parentIndex: number): void;
-    /**
-     * Get the immediate parent
-     */
+    /** Immediate parent (primary). See `extraParents` for the 2nd+ chain. */
     get parent(): Ref | undefined;
-    /**
-     * Get the immediate parent index
-     */
     get parentIndex(): number | undefined;
-    /**
-     * Add a parent to the chain
-     */
     addParent(parent: Ref, index: number): void;
-    /**
-     * Remove a parent from the chain
-     * @param parent - The parent to remove
-     * @returns true if parent was removed
-     */
+    /** @returns true if parent was found and removed */
     removeParent(parent?: Ref): boolean;
-    /**
-     * Find a specific parent in the chain
-     */
     findParent(predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined;
-    /**
-     * Check if this ChangeTree has a specific parent
-     */
     hasParent(predicate: (parent: Ref, index: number) => boolean): boolean;
-    /**
-     * Get all parents as an array (for debugging/testing)
-     */
     getAllParents(): Array<{
         ref: Ref;
         index: number;
     }>;
 }
+/**
+ * Lightweight per-instance no-op ChangeTree used for instances the decoder
+ * builds. Those instances never feed back into an Encoder, so the full
+ * `ChangeTree` machinery (EncodeDescriptor lookup, recorder state, Maps /
+ * Uint8Arrays for change slots) is pure overhead — this stub carries only a
+ * `ref` back-pointer and no-op methods, so tree walkers and debug tooling
+ * continue to work.
+ *
+ * Plug-in contract: each collection class and the `Decoder` pick between
+ * `new ChangeTree(ref)` and `createUntrackedChangeTree(ref)` explicitly via
+ * dedicated factories (`initializeForDecoder` on collections,
+ * `createInstanceOfType` on the `Decoder`). There is no global state — every
+ * decision is local to the call site.
+ */
+export declare class UntrackedChangeTree {
+    ref: Ref;
+    root: undefined;
+    parentRef: undefined;
+    paused: boolean;
+    isNew: boolean;
+    flags: number;
+    constructor(ref: Ref);
+    change(): void;
+    delete(): void;
+    indexedOperation(): void;
+    operation(): void;
+    setParent(): void;
+    addParent(): void;
+    removeParent(): boolean;
+    getChange(): number;
+    discard(): void;
+    discardAll(): void;
+    pause(): void;
+    resume(): void;
+    untracked<T>(fn: () => T): T;
+    markDirty(): void;
+    forEachChild(callback: (change: any, at: any) => void): void;
+    forEachChildWithCtx<C>(ctx: C, callback: (ctx: C, change: any, at: any) => void): void;
+    forEachLive(): void;
+    forEachLiveWithCtx(): void;
+    forEach(): void;
+}
+export declare function createUntrackedChangeTree(ref: Ref): ChangeTree;
+/**
+ * Install a non-enumerable `$changes: UntrackedChangeTree` on `target`.
+ * Shared by `Schema.initializeForDecoder` and every collection's
+ * `initializeForDecoder`. `publicRef` defaults to `target` — pass a Proxy
+ * instead (ArraySchema) so children attached to this tree see the Proxy
+ * as their parent, not the raw target.
+ *
+ * `enumerable: false` is load-bearing — tests use `deepStrictEqual` on
+ * decoded instances and walking into `$changes` would recurse through
+ * circular refs. Same descriptor shape as the tracked `Schema.initialize`
+ * + collection ctors.
+ */
+export declare function installUntrackedChangeTree(target: object, publicRef?: object): void;

package/build/encoder/EncodeDescriptor.d.ts

@@ -0,0 +1,63 @@
+import type { StateView } from "./StateView.js";
+import type { EncodeOperation } from "./EncodeOperation.js";
+export interface EncodeDescriptor {
+    encoder: EncodeOperation;
+    filter: ((ref: any, index: number, view?: StateView) => boolean) | undefined;
+    metadata: any;
+    isSchema: boolean;
+    /**
+     * Bit i set iff field i has a @view tag. 0 for collection trees.
+     * Lets `encodeChangeCb` do a single bitwise op instead of a
+     * per-field metadata[i]?.tag chase.
+     */
+    filterBitmask: number;
+    /**
+     * Class-level "any field has the flag" booleans + per-field bitmasks.
+     * Hot path: per-mutation `_routeAndRecord` calls `isFieldStatic` and
+     * `isFieldUnreliable`. The common case is "no static/unreliable fields
+     * anywhere on this class" (booleans short-circuit before the symbol-keyed
+     * metadata lookup); the secondary common case is "this class has some
+     * such fields and we need to know if THIS field is one" — the bitmask
+     * answers in one bitwise op instead of an `Array.includes` linear scan.
+     *
+     * Bitmasks cover fields 0–31 only (matches the `filterBitmask` limitation).
+     * Fields ≥32 fall back to `Metadata.hasXAtIndex` — same handling as the
+     * filter-bitmask path.
+     */
+    hasAnyStatic: boolean;
+    hasAnyUnreliable: boolean;
+    hasAnyStream: boolean;
+    /**
+     * Class-level "any field carries a `@view` tag" — covers fields both
+     * within and beyond index 31 (unlike `filterBitmask`, which only
+     * captures the low 32). Read by `ChangeTree.hasFilteredFields` to
+     * decide whether a parent tree must be included in a view's bootstrap.
+     */
+    hasAnyView: boolean;
+    staticBitmask: number;
+    unreliableBitmask: number;
+    /**
+     * Bit i set iff field i holds a `t.stream(...)` collection. Hot encode
+     * path reads this to dispatch stream fields into the priority/budget
+     * gate instead of the normal recorder iteration.
+     */
+    streamBitmask: number;
+    /**
+     * Per-field parallel arrays — Schemas only (empty arrays for
+     * collections). Replaces hot-path `metadata[i].name` / `metadata[i].type`
+     * / `metadata[i].tag` chains with direct array indexing on a small
+     * fixed-shape object.
+     *
+     * Sparse where natural: `tags[i]` is undefined unless field i carries
+     * a @view tag; readers should null-check before comparing.
+     *
+     * `encoders[i]` mirrors `metadata[$encoders]` — the pre-computed
+     * encoder fn for primitive-typed fields. Cached here so encode loops
+     * skip a `metadata[$encoders]?.[i]` symbol-chain per emission.
+     */
+    names: string[];
+    types: any[];
+    tags: (number | undefined)[];
+    encoders: (((bytes: Uint8Array, value: any, it: any) => void) | undefined)[];
+}
+export declare function getEncodeDescriptor(ref: any): EncodeDescriptor;

package/build/encoder/EncodeOperation.d.ts

@@ -4,16 +4,39 @@ import type { Encoder } from "./Encoder.js";
 import type { Iterator } from "../encoding/decode.js";
 import type { Metadata } from "../Metadata.js";
 export type EncodeOperation<T extends Ref = any> = (encoder: Encoder, bytes: Uint8Array, changeTree: ChangeTree<T>, index: number, operation: OPERATION, it: Iterator, isEncodeAll: boolean, hasView: boolean, metadata?: Metadata) => void;
-export declare function encodeValue(encoder: Encoder, bytes: Uint8Array, type: any, value: any, operation: OPERATION, it: Iterator): void;
+export declare function encodeValue(encoder: Encoder, bytes: Uint8Array, type: any, value: any, operation: OPERATION, it: Iterator, encoderFn?: (bytes: Uint8Array, value: any, it: Iterator) => void): void;
 /**
  * Used for Schema instances.
  * @private
  */
 export declare const encodeSchemaOperation: EncodeOperation;
 /**
- * Used for collections (MapSchema, CollectionSchema, SetSchema)
+ * Encode a single MapSchema entry. Splits the legacy
+ * `encodeKeyValueOperation` so the per-emission `typeof ref['set']` check
+ * is gone — MapSchema instances are routed here via their `[$encoder]`
+ * static, the dynamic-key string emission is unconditional on ADD.
+ *
  * @private
  */
+export declare const encodeMapEntry: EncodeOperation;
+/**
+ * Encode a single SetSchema / CollectionSchema entry. Wire format is the
+ * same as MapSchema minus the dynamic-key string, so this path skips the
+ * legacy `typeof ref['set']` check entirely.
+ *
+ * @private
+ */
+export declare const encodeIndexedEntry: EncodeOperation;
+/**
+ * Unified encoder kept for back-compat with external consumers that may
+ * have registered it directly via `static [$encoder] =
+ * encodeKeyValueOperation`. New code (and all internal collections)
+ * should use the split variants — `encodeMapEntry` for MapSchema and
+ * `encodeIndexedEntry` for SetSchema / CollectionSchema.
+ *
+ * The runtime `typeof ref['set']` check below is the per-emission cost
+ * the split is designed to remove.
+ */
 export declare const encodeKeyValueOperation: EncodeOperation;
 /**
  * Used for collections (MapSchema, ArraySchema, etc.)