@colyseus/schema 4.0.20 → 5.0.0

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,13 @@ 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;
+export type InferSchemaInstanceType<T> = {
+    [K in keyof 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]>;
 } & Schema;
 export type NonFunctionProps<T> = Omit<T, {
     [K in keyof T]: T[K] extends Function ? K : never;
@@ -65,9 +79,9 @@ 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];
-};
+export type ToJSON<T> = NonFunctionProps<{
+    [K in keyof T]: 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];
+}>;
 export type IsNever<T> = [T] extends [never] ? true : false;
 /**
  * Type helper for .assign() method - allows assigning values in a flexible way

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,162 @@
+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;
+    /** 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.
+ *
+ * The generic parameter T is the runtime/JS type of the field (e.g. `number`,
+ * `string`, `ArraySchema<Item>`). schema() reads the internal configuration
+ * via `toDefinition()` and wires up metadata through the existing pipeline.
+ */
+export declare class FieldBuilder<T = unknown> {
+    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;
+    _streamPriority: ((view: any, element: any) => number) | undefined;
+    constructor(type: DefinitionType);
+    /** Provide a default value for this field. */
+    default(value: T): this;
+    /** 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;
+    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>>>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<ArraySchema<InferValueType<P>>>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<ArraySchema<V>>;
+}
+interface MapFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<MapSchema<InstanceType<C>>>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<MapSchema<InferValueType<P>>>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<MapSchema<V>>;
+}
+interface SetFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<SetSchema<InstanceType<C>>>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<SetSchema<InferValueType<P>>>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<SetSchema<V>>;
+}
+interface CollectionFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<CollectionSchema<InstanceType<C>>>;
+    <P extends RawPrimitiveType>(child: P): FieldBuilder<CollectionSchema<InferValueType<P>>>;
+    <V>(child: FieldBuilder<V>): FieldBuilder<CollectionSchema<V>>;
+}
+interface StreamFactory {
+    <C extends Constructor<Schema>>(child: C): FieldBuilder<StreamSchema<InstanceType<C>>>;
+}
+declare function refFactory<C extends Constructor<Schema>>(ctor: C): FieldBuilder<InstanceType<C>>;
+export declare const t: Readonly<{
+    string: () => FieldBuilder<string>;
+    number: () => FieldBuilder<number>;
+    boolean: () => FieldBuilder<boolean>;
+    int8: () => FieldBuilder<number>;
+    uint8: () => FieldBuilder<number>;
+    int16: () => FieldBuilder<number>;
+    uint16: () => FieldBuilder<number>;
+    int32: () => FieldBuilder<number>;
+    uint32: () => FieldBuilder<number>;
+    int64: () => FieldBuilder<number>;
+    uint64: () => FieldBuilder<number>;
+    float32: () => FieldBuilder<number>;
+    float64: () => FieldBuilder<number>;
+    bigint64: () => FieldBuilder<bigint>;
+    biguint64: () => FieldBuilder<bigint>;
+    /** Reference to a Schema subtype. `t.array(Item)` usually reads better, but this is available when a plain ref is needed. */
+    ref: typeof 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>;

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

@@ -0,0 +1,114 @@
+import { $changes, $childType, $decoder, $deleteByIndex, $encoder, $filter, $getByIndex, $onEncodeEnd, $refId } from "../symbols.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";
+/**
+ * `t.stream(Entity)` — priority-batched collection of Schema instances.
+ *
+ * Designed for ECS-style use cases where many entities spawn/despawn each
+ * tick and the full set won't fit in one encode budget. Adds are queued
+ * 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
+ * post-add mutation tracking entirely.
+ */
+export declare class StreamSchema<V = any> implements IRef {
+    [$changes]: ChangeTree;
+    [$refId]?: number;
+    protected [$childType]: string | typeof Schema;
+    /**
+     * Wire-keyed storage: `position → element`. Position is a monotonic
+     * counter assigned by `add()` — stable identity even when elements
+     * are removed, so pending/sent view state can keep using the same
+     * keys across ticks. Map (not Array) so `$items.keys()` / `.values()`
+     * skip removed positions without a sparse-slot check.
+     */
+    protected $items: Map<number, V>;
+    /** Monotonic position counter. Incremented on every `add()`. */
+    protected $nextPosition: number;
+    /** Reverse lookup for O(1) `remove(el)`. */
+    protected _itemIndex: Map<V, number>;
+    /**
+     * Streamable state — holds per-view and broadcast bookkeeping. Lazily
+     * allocated when the stream is attached to a Root (or when the user
+     * touches `maxPerTick`). `undefined` on detached streams so
+     * construction is cheap.
+     */
+    _stream?: StreamableState;
+    /** Max element ADDs emitted per encode tick (per view, or broadcast). */
+    get maxPerTick(): number;
+    set maxPerTick(n: number);
+    /**
+     * Per-view priority callback. Initialized from the schema declaration
+     * (`.priority(fn)` or `@type({ stream, priority })`); assigning here
+     * overrides the class-level default 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);
+    /**
+     * Brand used by Root / StateView to detect stream trees without
+     * importing this class (avoids circular deps). The `isStreamCollection`
+     * ChangeTree flag (set via `inheritedFlags`) is the preferred runtime
+     * check — this brand is kept for back-compat.
+     */
+    static readonly $isStream: true;
+    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: 5;
+    /**
+     * Element-level visibility. Identical to SetSchema's filter: stream
+     * elements are always per-view, the filter just defers to the view's
+     * per-tree visibility bitmap.
+     */
+    static [$filter](ref: StreamSchema, index: number, view: StateView): boolean;
+    static is(type: any): boolean;
+    constructor();
+    /**
+     * 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>(): StreamSchema<V>;
+    /**
+     * Append an element to the stream. Returns the assigned position,
+     * or -1 if the element was already in the stream.
+     */
+    add(value: V): number;
+    /**
+     * Remove an element by reference. If the element was pending (never sent
+     * to a view), the pending entry is dropped silently. If already sent,
+     * a DELETE op is forced on next `encodeView` for that view.
+     */
+    remove(value: V): boolean;
+    has(value: V): boolean;
+    /** Remove every element; queue DELETE wire ops for already-sent items. */
+    clear(): void;
+    forEach(callback: (value: V, index: number, collection: StreamSchema<V>) => void): void;
+    values(): IterableIterator<V>;
+    /**
+     * Iterate `[position, value]` pairs in insertion order. Used by
+     * `setParent` recursion when the stream is reassigned to a new parent.
+     */
+    entries(): IterableIterator<[number, V]>;
+    [Symbol.iterator](): IterableIterator<V>;
+    /** Live element count. */
+    get size(): number;
+    /** Alias for `size`. */
+    get length(): number;
+    protected setIndex(_index: number, _key: number): void;
+    protected getIndex(index: number): number;
+    [$getByIndex](index: number): V;
+    [$deleteByIndex](index: number): void;
+    protected [$onEncodeEnd](): void;
+    toArray(): V[];
+    toJSON(): any[];
+    clone(isDecoding?: boolean): StreamSchema<V>;
+    _dropView(viewId: number): void;
+    /** Called by Root.remove when the stream's refcount hits zero. */
+    _unregister(): void;
+}