@colyseus/schema 4.0.20 → 5.0.1

package/build/types/HelperTypes.d.ts

@@ -1,9 +1,11 @@
-import type { Definition, DefinitionType, PrimitiveType, RawPrimitiveType } from "../annotations.js";
+import type { PrimitiveType, RawPrimitiveType } from "../annotations.js";
 import type { Schema } from "../Schema.js";
 import type { ArraySchema } from "./custom/ArraySchema.js";
 import type { CollectionSchema } from "./custom/CollectionSchema.js";
 import type { MapSchema } from "./custom/MapSchema.js";
 import type { SetSchema } from "./custom/SetSchema.js";
+import type { StreamSchema } from "./custom/StreamSchema.js";
+import type { FieldBuilder } from "./builder.js";
 export type Constructor<T = {}> = new (...args: any[]) => T;
 type PrimitiveStringToType<T> = T extends "string" ? string : T extends "number" | "int8" | "uint8" | "int16" | "uint16" | "int32" | "uint32" | "int64" | "uint64" | "float32" | "float64" ? number : T extends "boolean" ? boolean : T;
 export interface Collection<K = any, V = any, IT = V> {
@@ -11,7 +13,7 @@ export interface Collection<K = any, V = any, IT = V> {
     forEach(callback: Function): void;
     entries(): IterableIterator<[K, V]>;
 }
-export type InferValueType<T extends DefinitionType> = T extends "string" ? string : T extends "number" ? number : T extends "int8" ? number : T extends "uint8" ? number : T extends "int16" ? number : T extends "uint16" ? number : T extends "int32" ? number : T extends "uint32" ? number : T extends "int64" ? number : T extends "uint64" ? number : T extends "float32" ? number : T extends "float64" ? number : T extends "boolean" ? boolean : T extends {
+export type InferValueType<T> = T extends FieldBuilder<infer V> ? V : T extends "string" ? string : T extends "number" ? number : T extends "int8" ? number : T extends "uint8" ? number : T extends "int16" ? number : T extends "uint16" ? number : T extends "int32" ? number : T extends "uint32" ? number : T extends "int64" ? number : T extends "uint64" ? number : T extends "float32" ? number : T extends "float64" ? number : T extends "boolean" ? boolean : T extends {
     type: infer ChildType extends PrimitiveType;
 } ? InferValueType<ChildType> : T extends {
     type: infer ChildType extends Constructor;
@@ -30,6 +32,14 @@ export type InferValueType<T extends DefinitionType> = T extends "string" ? stri
         collection: infer ChildType;
     };
 } ? (ChildType extends Record<string | number, string | number> ? CollectionSchema<ChildType[keyof ChildType]> : CollectionSchema<ChildType>) : T extends {
+    type: {
+        stream: infer ChildType extends Constructor;
+    };
+} ? StreamSchema<InstanceType<ChildType>> : T extends {
+    type: {
+        stream: infer ChildType;
+    };
+} ? StreamSchema<ChildType> : T extends {
     type: infer ChildType;
 } ? (ChildType extends Record<string | number, string | number> ? ChildType[keyof ChildType] : ChildType) : T extends Array<infer ChildType extends Constructor> ? ArraySchema<InstanceType<ChildType>> : T extends Array<infer ChildType> ? (ChildType extends Record<string | number, string | number> ? ArraySchema<ChildType[keyof ChildType]> : ArraySchema<PrimitiveStringToType<ChildType>>) : T extends {
     array: infer ChildType extends Constructor;
@@ -51,9 +61,19 @@ export type InferValueType<T extends DefinitionType> = T extends "string" ? stri
     collection: infer ChildType extends RawPrimitiveType;
 } ? CollectionSchema<InferValueType<ChildType>> : T extends {
     collection: infer ChildType;
-} ? (ChildType extends Record<string | number, string | number> ? CollectionSchema<ChildType[keyof ChildType]> : CollectionSchema<ChildType>) : T extends Constructor ? InstanceType<T> : T extends Record<string | number, string | number> ? T[keyof T] : T extends PrimitiveType ? T : never;
-export type InferSchemaInstanceType<T extends Definition> = {
-    [K in keyof T]: T[K] extends (...args: any[]) => any ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K]) : InferValueType<T[K]>;
+} ? (ChildType extends Record<string | number, string | number> ? CollectionSchema<ChildType[keyof ChildType]> : CollectionSchema<ChildType>) : T extends {
+    stream: infer ChildType extends Constructor;
+} ? StreamSchema<InstanceType<ChildType>> : T extends {
+    stream: infer ChildType;
+} ? StreamSchema<ChildType> : T extends Constructor ? InstanceType<T> : T extends Record<string | number, string | number> ? T[keyof T] : T extends PrimitiveType ? T : never;
+type OptionalBuilderKeys<T> = {
+    [K in keyof T]: T[K] extends FieldBuilder<infer V> ? (undefined extends V ? K : never) : never;
+}[keyof T];
+type RequiredBuilderKeys<T> = Exclude<keyof T, OptionalBuilderKeys<T>>;
+export type InferSchemaInstanceType<T> = {
+    [K in RequiredBuilderKeys<T>]: T[K] extends FieldBuilder<any> ? InferValueType<T[K]> : T[K] extends (...args: any[]) => any ? (T[K] extends new (...args: any[]) => any ? InferValueType<T[K]> : T[K]) : InferValueType<T[K]>;
+} & {
+    [K in OptionalBuilderKeys<T>]?: T[K] extends FieldBuilder<infer V> ? V : never;
 } & Schema;
 export type NonFunctionProps<T> = Omit<T, {
     [K in keyof T]: T[K] extends Function ? K : never;
@@ -65,9 +85,18 @@ export type NonFunctionNonPrimitivePropNames<T> = {
     [K in keyof T]: T[K] extends Function ? never : T[K] extends number | string | boolean ? never : K;
 }[keyof T];
 type ToJSONValue<U> = U extends Schema ? ToJSON<U> : PrimitiveStringToType<U>;
-export type ToJSON<T> = {
-    [K in keyof T as T[K] extends Function ? never : K]: T[K] extends MapSchema<infer U> ? Record<string, ToJSONValue<U>> : T[K] extends Map<string, infer U> ? Record<string, ToJSONValue<U>> : T[K] extends ArraySchema<infer U> ? ToJSONValue<U>[] : T[K] extends SetSchema<infer U> ? ToJSONValue<U>[] : T[K] extends CollectionSchema<infer U> ? ToJSONValue<U>[] : T[K] extends Schema ? ToJSON<T[K]> : T[K];
-};
+type ToJSONField<X> = X extends MapSchema<infer U> ? Record<string, ToJSONValue<U>> : X extends Map<string, infer U> ? Record<string, ToJSONValue<U>> : X extends ArraySchema<infer U> ? ToJSONValue<U>[] : X extends SetSchema<infer U> ? ToJSONValue<U>[] : X extends CollectionSchema<infer U> ? ToJSONValue<U>[] : X extends Schema ? ToJSON<X> : X;
+type ToJSONRequiredKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? never : K;
+}[keyof T];
+type ToJSONOptionalKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? K : never;
+}[keyof T];
+export type ToJSON<T> = NonFunctionProps<{
+    [K in ToJSONRequiredKeys<T>]: ToJSONField<T[K]>;
+} & {
+    [K in ToJSONOptionalKeys<T>]?: ToJSONField<Exclude<T[K], undefined>>;
+}>;
 export type IsNever<T> = [T] extends [never] ? true : false;
 /**
  * Type helper for .assign() method - allows assigning values in a flexible way
@@ -76,6 +105,35 @@ export type IsNever<T> = [T] extends [never] ? true : false;
  * - Collections can be assigned from their JSON representations
  */
 export type AssignableProps<T> = {
-    [K in NonFunctionPropNames<T>]?: T[K] extends MapSchema<infer U> ? MapSchema<U> | Record<string, U extends Schema ? (U | AssignableProps<U>) : U> : T[K] extends ArraySchema<infer U> ? ArraySchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : T[K] extends SetSchema<infer U> ? SetSchema<U> | Set<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : T[K] extends CollectionSchema<infer U> ? CollectionSchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : T[K] extends Schema ? T[K] | AssignableProps<T[K]> : T[K];
+    [K in NonFunctionPropNames<T>]?: AssignableValue<T[K]>;
+};
+/**
+ * Value-level assignment shape shared by `AssignableProps` and
+ * `BuilderInitProps`. Captures the "you can pass the real instance, or the
+ * plain-object / array shape" pattern.
+ */
+export type AssignableValue<V> = V extends MapSchema<infer U> ? MapSchema<U> | Record<string, U extends Schema ? (U | AssignableProps<U>) : U> : V extends ArraySchema<infer U> ? ArraySchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : V extends SetSchema<infer U> ? SetSchema<U> | Set<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : V extends CollectionSchema<infer U> ? CollectionSchema<U> | (U extends Schema ? (U | AssignableProps<U>)[] : U[]) : V extends Schema ? V | AssignableProps<V> : V;
+export type RefHasDefault<C> = C extends {
+    prototype: {
+        initialize(...args: infer P): any;
+    };
+} ? (P extends readonly [] ? true : false) : true;
+type FieldValue<F> = F extends FieldBuilder<infer V, boolean, boolean> ? V : F extends new (...args: any[]) => infer I ? (I extends Schema ? I : never) : never;
+type KeyClass<T, K extends keyof T> = T[K] extends FieldBuilder<unknown, infer D extends boolean, infer O extends boolean> ? (D extends true ? "optional" : O extends true ? "optional" : "required") : T[K] extends new (...args: any[]) => Schema ? (RefHasDefault<T[K]> extends true ? "optional" : "required") : "none";
+export type BuilderRequiredKeys<T> = {
+    [K in keyof T]-?: KeyClass<T, K> extends "required" ? K : never;
+}[keyof T];
+export type BuilderOptionalKeys<T> = {
+    [K in keyof T]-?: KeyClass<T, K> extends "optional" ? K : never;
+}[keyof T];
+/**
+ * Constructor/init-props type for a schema() fields map. Required fields
+ * (primitives without `.default()` or `.optional()`, and Schema refs with
+ * non-zero-arg `initialize()`) are `:`; everything else is `?:`.
+ */
+export type BuilderInitProps<T> = {
+    [K in BuilderRequiredKeys<T>]: AssignableValue<FieldValue<T[K]>>;
+} & {
+    [K in BuilderOptionalKeys<T>]?: AssignableValue<Exclude<FieldValue<T[K]>, undefined>>;
 };
 export {};

package/build/types/TypeContext.d.ts

@@ -8,6 +8,15 @@ export declare class TypeContext {
     parentFiltered: {
         [typeIdAndParentIndex: string]: boolean;
     };
+    /**
+     * True iff `parentFiltered` has at least one entry. Flipped on by
+     * `registerFilteredByParent` and read in `checkInheritedFlags` as a
+     * cheap gate to skip the string-keyed `parentFiltered[key]` lookup
+     * when no class has registered filter inheritance via ancestry — the
+     * common case when @view tags exist only on sibling fields, not
+     * along any attachment chain.
+     */
+    hasParentFilteredEntries: boolean;
     /**
      * For inheritance support
      * Keeps track of which classes extends which. (parent -> children)

package/build/types/builder.d.ts

@@ -0,0 +1,192 @@
+import type { ArraySchema } from "./custom/ArraySchema.js";
+import type { MapSchema } from "./custom/MapSchema.js";
+import type { SetSchema } from "./custom/SetSchema.js";
+import type { CollectionSchema } from "./custom/CollectionSchema.js";
+import type { StreamSchema } from "./custom/StreamSchema.js";
+import type { Schema } from "../Schema.js";
+import type { DefinitionType, RawPrimitiveType } from "../annotations.js";
+import type { InferValueType, Constructor } from "./HelperTypes.js";
+import { $builder } from "./symbols.js";
+/**
+ * Internal record produced by FieldBuilder#toDefinition() and consumed by schema().
+ */
+export interface BuilderDefinition {
+    type: DefinitionType;
+    default?: any;
+    hasDefault: boolean;
+    view?: number;
+    owned?: boolean;
+    unreliable?: boolean;
+    transient?: boolean;
+    deprecated?: boolean;
+    deprecatedThrows?: boolean;
+    static?: boolean;
+    stream?: boolean;
+    optional?: boolean;
+    /** Declaration-scope priority callback for `.stream()` fields. */
+    streamPriority?: (view: any, element: any) => number;
+}
+/**
+ * Type-function that infers the instance value for a builder.
+ */
+export type BuilderOf<T> = FieldBuilder<T>;
+/**
+ * Chainable field builder. Instances are produced by `t.*()` factories.
+ *
+ * Generics:
+ *  - `T` is the runtime/JS type of the field (e.g. `number`, `string`,
+ *    `ArraySchema<Item>`). `.optional()` widens it to `T | undefined`
+ *    so the inferred instance/toJSON shapes reflect absence.
+ *  - `HasDefault` is a compile-time flag that the field carries a
+ *    construction-time default — either an explicit `.default(v)` or an
+ *    auto-default from a collection factory (`t.array`, `t.map`, …) or a
+ *    Schema ref whose `initialize` takes zero args.
+ *  - `IsOptional` is a compile-time brand for `.optional()`. Both
+ *    `HasDefault` and `IsOptional` make the field omittable in
+ *    `BuilderInitProps<T>`. A separate brand (rather than reading
+ *    `undefined extends V`) sidesteps a TypeScript quirk where
+ *    class-generic-inferred `V` resolves `undefined extends V` as `true`
+ *    even for non-undefined types.
+ *
+ * schema() reads the internal configuration via `toDefinition()` and wires
+ * up metadata through the existing pipeline.
+ */
+export declare class FieldBuilder<T = unknown, HasDefault extends boolean = false, IsOptional extends boolean = false> {
+    readonly [$builder]: true;
+    _type: DefinitionType;
+    _default: any;
+    _hasDefault: boolean;
+    _view: number | undefined;
+    _owned: boolean;
+    _unreliable: boolean;
+    _transient: boolean;
+    _deprecated: boolean;
+    _deprecatedThrows: boolean;
+    _static: boolean;
+    _stream: boolean;
+    _optional: boolean;
+    _streamPriority: ((view: any, element: any) => number) | undefined;
+    constructor(type: DefinitionType);
+    /** Provide a default value for this field. */
+    default(value: T): FieldBuilder<T, true, IsOptional>;
+    /** Tag this field with a view tag (DEFAULT_VIEW_TAG when called without arg). */
+    view(tag?: number): this;
+    /** Mark this field as owned (encoder-side ownership filtering). */
+    owned(): 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()`.
+     */
+    unreliable(): 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()`.
+     */
+    transient(): 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.
+     */
+    static(): this;
+    /**
+     * Opt a collection field into priority-batched streaming delivery —
+     * ADDs drain at most `maxPerTick` per tick per view (or per broadcast
+     * tick without a view). Applies to `t.map(X)` / `t.set(X)` /
+     * `t.collection(X)`. Redundant on `t.stream(X)` (the factory already
+     * sets this flag).
+     *
+     * **Not supported on `t.array(X)`.** Array positional operations
+     * (`splice`, `unshift`, `reverse`) shift every subsequent index —
+     * holding some ADDs back for a later tick while indexes mutate
+     * underneath would produce a decoder-side state that doesn't match
+     * the server. Use `t.stream(X)` (stable monotonic positions) or
+     * `t.map(X).stream()` (keys never shift) instead.
+     */
+    stream(): this;
+    /**
+     * Attach a priority callback for per-view `encodeView` delivery. The
+     * callback receives the client's StateView and the candidate element;
+     * higher return values emit first. Does nothing in broadcast mode
+     * (shared `encode()` drains FIFO). Only meaningful on stream fields.
+     *
+     * ```ts
+     * t.stream(Enemy).priority((view, enemy) =>
+     *     -dist2(view.anchor, enemy)
+     * )
+     * ```
+     */
+    priority<V = any>(fn: (view: any, element: V) => number): this;
+    /** Mark this field as deprecated. Pass `false` to silence the access error. */
+    deprecated(throws?: boolean): this;
+    /**
+     * Mark this field as optional — inferred instance type becomes
+     * `T | undefined` and the property becomes omittable in initialization
+     * props. Skips the auto-instantiation of collection / Schema-ref
+     * defaults, so the field starts as `undefined` at runtime.
+     */
+    optional(): FieldBuilder<T | undefined, HasDefault, true>;
+    toDefinition(): BuilderDefinition;
+}
+export declare function isBuilder(value: any): value is FieldBuilder<any>;
+export type ChildType = RawPrimitiveType | Constructor<Schema> | FieldBuilder<any>;
+interface ArrayFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<ArraySchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<ArraySchema<V>, true, false>;
+}
+interface MapFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<MapSchema<V>, true, false>;
+}
+interface SetFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<SetSchema<V>, true, false>;
+}
+interface CollectionFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>, true, false>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>, true, false>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<CollectionSchema<V>, true, false>;
+}
+interface StreamFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<StreamSchema<InstanceType<C>>, true, false>;
+}
+type RefHasDefault<C> = C extends {
+    prototype: {
+        initialize(...args: infer P): any;
+    };
+} ? (P extends readonly [] ? true : false) : true;
+interface RefFactory {
+    <C extends Constructor<Schema>>(ctor: C): FieldBuilder<InstanceType<C>, RefHasDefault<C>, false>;
+}
+export declare const t: Readonly<{
+    string: () => FieldBuilder<string, false, false>;
+    number: () => FieldBuilder<number, false, false>;
+    boolean: () => FieldBuilder<boolean, false, false>;
+    int8: () => FieldBuilder<number, false, false>;
+    uint8: () => FieldBuilder<number, false, false>;
+    int16: () => FieldBuilder<number, false, false>;
+    uint16: () => FieldBuilder<number, false, false>;
+    int32: () => FieldBuilder<number, false, false>;
+    uint32: () => FieldBuilder<number, false, false>;
+    int64: () => FieldBuilder<number, false, false>;
+    uint64: () => FieldBuilder<number, false, false>;
+    float32: () => FieldBuilder<number, false, false>;
+    float64: () => FieldBuilder<number, false, false>;
+    bigint64: () => FieldBuilder<bigint, false, false>;
+    biguint64: () => FieldBuilder<bigint, false, false>;
+    /** Reference to a Schema subtype. `t.array(Item)` usually reads better, but this is available when a plain ref is needed. */
+    ref: RefFactory;
+    array: ArrayFactory;
+    map: MapFactory;
+    set: SetFactory;
+    collection: CollectionFactory;
+    stream: StreamFactory;
+}>;
+export {};

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

@@ -1,4 +1,4 @@
-import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $refId } from "../symbols.js";
+import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $onDecodeEnd, $proxyTarget, $refId } from "../symbols.js";
 import type { Schema } from "../../Schema.js";
 import { type IRef, ChangeTree } from "../../encoder/ChangeTree.js";
 import { OPERATION } from "../../encoding/spec.js";
@@ -8,15 +8,16 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
     [n: number]: V;
     [$changes]: ChangeTree;
     [$refId]?: number;
+    [$proxyTarget]: this;
     protected [$childType]: string | typeof Schema;
     protected items: V[];
     protected tmpItems: V[];
-    protected deletedIndexes: {
-        [index: number]: boolean;
-    };
+    protected deletedIndexes: boolean[];
     protected isMovingItems: boolean;
     static [$encoder]: import("../../encoder/EncodeOperation.js").EncodeOperation<any>;
     static [$decoder]: import("../../decoder/DecodeOperation.js").DecodeOperation<any>;
+    /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
+    static readonly COLLECTION_KIND: 2;
     /**
      * Determine if a property must be filtered.
      * - If returns false, the property is NOT going to be encoded.
@@ -30,8 +31,22 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
     static is(type: any): boolean;
     static from<T>(iterable: Iterable<T> | ArrayLike<T>): ArraySchema<T>;
     constructor(...items: V[]);
+    /**
+     * Decoder-side factory. Skips the `ChangeTree` allocation and
+     * replicates the class-field initializers by hand (since `Object.create`
+     * bypasses them). Must stay in sync with the class-field declarations
+     * and the constructor body above.
+     *
+     * Pass the Proxy to `installUntrackedChangeTree` as the public identity
+     * so children set their parent to the Proxy, not the raw target.
+     */
+    static initializeForDecoder<V = any>(): ArraySchema<V>;
     set length(newLength: number);
     get length(): number;
+    pauseTracking(): void;
+    resumeTracking(): void;
+    untracked<T>(fn: () => T): T;
+    get isTrackingPaused(): boolean;
     push(...values: V[]): number;
     /**
      * Removes the last element from an array and returns it.
@@ -260,6 +275,12 @@ export declare class ArraySchema<V = any> implements Array<V>, Collection<number
      * @returns
      */
     move(cb: (arr: this) => void): this;
+    /**
+     * Encoder-only. Reads the staged-snapshot (`tmpItems`) so the encoder can
+     * resolve a wire-index even after the user has mutated `items` mid-tick.
+     * The decoder reads `items[index]` directly — see `decodeArray` and
+     * `$deleteByIndex` below.
+     */
     [$getByIndex](index: number, isEncodeAll?: boolean): any;
     [$deleteByIndex](index: number): void;
     protected [$onEncodeEnd](): void;

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

@@ -1,6 +1,7 @@
 import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
 import { ChangeTree, type IRef } from "../../encoder/ChangeTree.js";
 import { Collection } from "../HelperTypes.js";
+import { type StreamableState } from "../../encoder/streaming.js";
 import type { StateView } from "../../encoder/StateView.js";
 import type { Schema } from "../../Schema.js";
 type K = number;
@@ -8,14 +9,28 @@ export declare class CollectionSchema<V = any> implements Collection<K, V>, IRef
     [$changes]: ChangeTree;
     [$refId]?: number;
     protected [$childType]: string | typeof Schema;
+    /** The user-visible data, keyed directly by the wire-protocol index. */
     protected $items: Map<number, V>;
-    protected $indexes: Map<number, number>;
+    /** Snapshots of values that were deleted this tick (for filter visibility). */
     protected deletedItems: {
         [field: string]: V;
     };
+    /** Monotonic counter for assigning indexes to newly-added items. */
     protected $refId: number;
+    /**
+     * Streamable state — lazily allocated when the field is opted into
+     * streaming via `t.collection(X).stream()`. See MapSchema for the
+     * same pattern / rationale.
+     */
+    _stream?: StreamableState;
+    get maxPerTick(): number;
+    set maxPerTick(n: number);
+    get priority(): ((view: any, element: V) => number) | undefined;
+    set priority(fn: ((view: any, element: V) => number) | undefined);
     static [$encoder]: import("../../encoder/EncodeOperation.js").EncodeOperation<any>;
     static [$decoder]: import("../../decoder/DecodeOperation.js").DecodeOperation<any>;
+    /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
+    static readonly COLLECTION_KIND: 4;
     /**
      * Determine if a property must be filtered.
      * - If returns false, the property is NOT going to be encoded.
@@ -28,6 +43,13 @@ export declare class CollectionSchema<V = any> implements Collection<K, V>, IRef
     static [$filter](ref: CollectionSchema, index: number, view: StateView): boolean;
     static is(type: any): boolean;
     constructor(initialValues?: Array<V>);
+    /**
+     * Decoder-side factory. Skips the tracking `ChangeTree` allocation;
+     * `Object.create` also bypasses the class-field initializers, so we
+     * replicate the minimum slot init here. Must stay in sync with the
+     * class-field declarations above.
+     */
+    static initializeForDecoder<V = any>(): CollectionSchema<V>;
     add(value: V): number;
     at(index: number): V | undefined;
     entries(): MapIterator<[number, V]>;
@@ -37,13 +59,19 @@ export declare class CollectionSchema<V = any> implements Collection<K, V>, IRef
     forEach(callbackfn: (value: V, key: K, collection: CollectionSchema<V>) => void): void;
     values(): MapIterator<V>;
     get size(): number;
+    pauseTracking(): void;
+    resumeTracking(): void;
+    untracked<T>(fn: () => T): T;
+    get isTrackingPaused(): boolean;
     /** Iterator */
     [Symbol.iterator](): IterableIterator<V>;
-    protected setIndex(index: number, key: number): void;
+    protected setIndex(_index: number, _key: number): void;
     protected getIndex(index: number): number;
     [$getByIndex](index: number): any;
     [$deleteByIndex](index: number): void;
     protected [$onEncodeEnd](): void;
+    _dropView(viewId: number): void;
+    _unregister(): void;
     toArray(): V[];
     toJSON(): V[];
     clone(isDecoding?: boolean): CollectionSchema<V>;

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

@@ -1,6 +1,8 @@
 import { $changes, $childType, $decoder, $deleteByIndex, $onEncodeEnd, $encoder, $filter, $getByIndex, $refId } from "../symbols.js";
 import { ChangeTree, IRef } from "../../encoder/ChangeTree.js";
 import { Collection } from "../HelperTypes.js";
+import { MapJournal } from "../../encoder/MapJournal.js";
+import { type StreamableState } from "../../encoder/streaming.js";
 import type { StateView } from "../../encoder/StateView.js";
 import type { Schema } from "../../Schema.js";
 export declare class MapSchema<V = any, K extends string = string> implements Map<K, V>, Collection<K, V, [K, V]>, IRef {
@@ -9,12 +11,46 @@ export declare class MapSchema<V = any, K extends string = string> implements Ma
     protected childType: new () => V;
     protected [$childType]: string | typeof Schema;
     protected $items: Map<K, V>;
-    protected $indexes: Map<number, K>;
-    protected deletedItems: {
-        [index: string]: V;
+    /**
+     * Wire-protocol identity + change-tracking metadata for this map.
+     *
+     * Owns: index↔key mapping, monotonic index counter, snapshots of removed
+     * values for filter visibility checks. Replaces what used to live as three
+     * separate fields on this class ($indexes, _collectionIndexes, deletedItems).
+     */
+    protected journal: MapJournal<K>;
+    /**
+     * Streamable state — lazily allocated by `inheritedFlags` (or the
+     * `maxPerTick` setter) when streaming actually activates. `undefined`
+     * on every non-streaming MapSchema so the common case pays zero
+     * Map/Set allocation. Single slot → hidden-class shape stays stable
+     * across streaming and non-streaming instances.
+     */
+    _stream?: StreamableState;
+    /** Max ADD ops emitted per tick per view. Ignored outside streaming mode. */
+    get maxPerTick(): number;
+    set maxPerTick(n: number);
+    /**
+     * Per-view priority callback for `.stream()` maps. Initialized from the
+     * schema declaration (`t.map(X).stream().priority(fn)` or `@type({ map,
+     * priority })`); assigning here overrides for this instance. Only fires
+     * during `encodeView` — broadcast mode drains FIFO.
+     */
+    get priority(): ((view: any, element: V) => number) | undefined;
+    set priority(fn: ((view: any, element: V) => number) | undefined);
+    /** Backwards-compat alias for `journal.keyByIndex`. */
+    get $indexes(): Map<number, K>;
+    /**
+     * Backwards-compat alias for `journal.indexByKey`. Plain object so
+     * polymorphic call sites like `ref._collectionIndexes?.[key]` keep working.
+     */
+    get _collectionIndexes(): {
+        [key: string]: number;
     };
     static [$encoder]: import("../../encoder/EncodeOperation.js").EncodeOperation<any>;
     static [$decoder]: import("../../decoder/DecodeOperation.js").DecodeOperation<any>;
+    /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
+    static readonly COLLECTION_KIND: 1;
     /**
      * Determine if a property must be filtered.
      * - If returns false, the property is NOT going to be encoded.
@@ -27,6 +63,13 @@ export declare class MapSchema<V = any, K extends string = string> implements Ma
     static [$filter](ref: MapSchema, index: number, view: StateView): boolean;
     static is(type: any): boolean;
     constructor(initialValues?: Map<K, V> | Record<K, V>);
+    /**
+     * Decoder-side factory. Skips the tracking `ChangeTree` allocation;
+     * `Object.create` also bypasses the class-field initializers, so we
+     * replicate the minimum slot init here. Must stay in sync with the
+     * class-field declarations above and with the constructor body.
+     */
+    static initializeForDecoder<V = any, K extends string = string>(): MapSchema<V, K>;
     /** Iterator */
     [Symbol.iterator](): IterableIterator<[K, V]>;
     get [Symbol.toStringTag](): string;
@@ -41,11 +84,17 @@ export declare class MapSchema<V = any, K extends string = string> implements Ma
     keys(): MapIterator<K>;
     values(): MapIterator<V>;
     get size(): number;
+    pauseTracking(): void;
+    resumeTracking(): void;
+    untracked<T>(fn: () => T): T;
+    get isTrackingPaused(): boolean;
     protected setIndex(index: number, key: K): void;
     protected getIndex(index: number): K;
     [$getByIndex](index: number): V | undefined;
     [$deleteByIndex](index: number): void;
     protected [$onEncodeEnd](): void;
+    _dropView(viewId: number): void;
+    _unregister(): void;
     toJSON(): any;
     clone(isDecoding?: boolean): MapSchema<V>;
 }

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

@@ -1,20 +1,37 @@
 import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.js";
 import { Collection } from "../HelperTypes.js";
 import { ChangeTree, type IRef } from "../../encoder/ChangeTree.js";
+import { type StreamableState } from "../../encoder/streaming.js";
 import type { StateView } from "../../encoder/StateView.js";
 import type { Schema } from "../../Schema.js";
 export declare class SetSchema<V = any> implements Collection<number, V>, IRef {
     [$changes]: ChangeTree;
     [$refId]?: number;
     protected [$childType]: string | typeof Schema;
+    /** The user-visible data, keyed directly by the wire-protocol index. */
     protected $items: Map<number, V>;
-    protected $indexes: Map<number, number>;
+    /** Snapshots of values that were deleted this tick (for filter visibility). */
     protected deletedItems: {
         [field: string]: V;
     };
+    /** Monotonic counter for assigning indexes to newly-added items. */
     protected $refId: number;
+    /**
+     * Streamable state — lazily allocated when the field is opted into
+     * streaming via `t.set(X).stream()`. See MapSchema for the same
+     * pattern / rationale.
+     */
+    _stream?: StreamableState;
+    /** Max ADD ops emitted per tick per view. Ignored outside streaming mode. */
+    get maxPerTick(): number;
+    set maxPerTick(n: number);
+    /** Per-view priority callback — see StreamSchema / MapSchema. */
+    get priority(): ((view: any, element: V) => number) | undefined;
+    set priority(fn: ((view: any, element: V) => number) | undefined);
     static [$encoder]: import("../../encoder/EncodeOperation.js").EncodeOperation<any>;
     static [$decoder]: import("../../decoder/DecodeOperation.js").DecodeOperation<any>;
+    /** Integer tag read by `decodeKeyValueOperation` — see `CollectionKind`. */
+    static readonly COLLECTION_KIND: 3;
     /**
      * Determine if a property must be filtered.
      * - If returns false, the property is NOT going to be encoded.
@@ -27,6 +44,13 @@ export declare class SetSchema<V = any> implements Collection<number, V>, IRef {
     static [$filter](ref: SetSchema, index: number, view: StateView): boolean;
     static is(type: any): boolean;
     constructor(initialValues?: Array<V>);
+    /**
+     * Decoder-side factory. Skips the tracking `ChangeTree` allocation;
+     * `Object.create` also bypasses the class-field initializers, so we
+     * replicate the minimum slot init here. Must stay in sync with the
+     * class-field declarations above.
+     */
+    static initializeForDecoder<V = any>(): SetSchema<V>;
     add(value: V): number | false;
     entries(): MapIterator<[number, V]>;
     delete(item: V): boolean;
@@ -35,13 +59,19 @@ export declare class SetSchema<V = any> implements Collection<number, V>, IRef {
     forEach(callbackfn: (value: V, key: number, collection: SetSchema<V>) => void): void;
     values(): MapIterator<V>;
     get size(): number;
+    pauseTracking(): void;
+    resumeTracking(): void;
+    untracked<T>(fn: () => T): T;
+    get isTrackingPaused(): boolean;
     /** Iterator */
     [Symbol.iterator](): IterableIterator<V>;
-    protected setIndex(index: number, key: number): void;
+    protected setIndex(_index: number, _key: number): void;
     protected getIndex(index: number): number;
     [$getByIndex](index: number): any;
     [$deleteByIndex](index: number): void;
     protected [$onEncodeEnd](): void;
+    _dropView(viewId: number): void;
+    _unregister(): void;
     toArray(): V[];
     toJSON(): V[];
     clone(isDecoding?: boolean): SetSchema<V>;