@colyseus/schema 4.0.20 → 5.0.1

package/build/encoder/Encoder.d.ts

@@ -3,20 +3,76 @@ import { TypeContext } from "../types/TypeContext.js";
 import type { Iterator } from "../encoding/decode.js";
 import { Root } from "./Root.js";
 import type { StateView } from "./StateView.js";
-import type { ChangeSetName } from "./ChangeTree.js";
 export declare class Encoder<T extends Schema = any> {
     static BUFFER_SIZE: number;
     sharedBuffer: Uint8Array;
     context: TypeContext;
     state: T;
     root: Root;
-    constructor(state: T);
+    constructor(state: T, root?: Root);
     protected setState(state: T): void;
-    encode(it?: Iterator, view?: StateView, buffer?: Uint8Array, changeSetName?: ChangeSetName, isEncodeAll?: boolean, initialOffset?: number): Uint8Array;
+    private _encodeCtx;
+    /**
+     * Monotonic counter bumped at the start of every `encodeFullSync`
+     * call. The new value is copied to `ctx.gen` and stamped into every
+     * tree the walk touches (`tree._fullSyncGen = ctx.gen`); subsequent
+     * revisits of the same tree detect the equality and return early.
+     */
+    private _fullSyncGen;
+    encode(it?: Iterator, view?: StateView, buffer?: Uint8Array, initialOffset?: number): Uint8Array;
+    /**
+     * Per-tick encode of the UNRELIABLE channel. Walks `root.unreliableChanges`
+     * and emits each tree's `unreliableRecorder`. Safe to call at a different
+     * cadence than `encode()` (e.g. 60Hz vs 20Hz) — the two channels are
+     * fully independent.
+     */
+    encodeUnreliable(it?: Iterator, view?: StateView, buffer?: Uint8Array, initialOffset?: number): Uint8Array;
+    private _encodeChannel;
+    /**
+     * Structural DFS walker for full-sync (encodeAll / encodeAllView).
+     * Visits each ChangeTree in DFS preorder starting from the state root,
+     * emitting ADD operations for every currently-populated index via
+     * {@link ChangeTree.forEachLive}.
+     */
+    private encodeFullSync;
+    private _resizeBuffer;
     encodeAll(it?: Iterator, buffer?: Uint8Array): Uint8Array<ArrayBufferLike>;
     encodeAllView(view: StateView, sharedOffset: number, it: Iterator, bytes?: Uint8Array): Uint8Array<ArrayBufferLike>;
     encodeView(view: StateView, sharedOffset: number, it: Iterator, bytes?: Uint8Array): Uint8Array<ArrayBufferLike>;
+    /**
+     * Per-view unreliable encode. Walks `root.unreliableChanges` and emits
+     * only filtered fields visible to this view. Unlike `encodeView`, this
+     * doesn't emit `view.changes` entries — those are used only for
+     * reliable view bootstrap (membership ADDs) and are consumed by
+     * `encodeView` on the reliable channel.
+     */
+    encodeUnreliableView(view: StateView, sharedOffset: number, it: Iterator, bytes?: Uint8Array): Uint8Array<ArrayBufferLike>;
+    /**
+     * Broadcast-mode counterpart to `_emitStreamPriority`. Runs when NO
+     * StateViews are registered — streams fall back to broadcast mode
+     * where up to `maxPerTick` pending ADDs per stream emit to ALL clients
+     * each shared tick. DELETEs always flush (no cap).
+     *
+     * Emits directly to the shared-encode buffer: stream & element trees
+     * are `isFiltered=true` so the main loop would otherwise skip them.
+     * Runs AFTER the main loop so state / parent refs are already encoded
+     * — stream ADD ops reference element refIds, which must be decodable.
+     */
+    private _emitStreamBroadcast;
+    /**
+     * Walk every registered stream, pick up to `maxPerTick` positions from
+     * this view's pending backlog (priority-sorted when the view supplies a
+     * `streamPriority` callback), and hand each element to `view.add()`.
+     * `view.add()` seeds `view.changes` so the subsequent drain emits both
+     * the stream-link (position → refId) and the element's field data.
+     *
+     * Designed to run at the very top of `encodeView`, BEFORE the
+     * view.changes drain loop.
+     */
+    private _emitStreamPriority;
     discardChanges(): void;
+    discardUnreliableChanges(): void;
     tryEncodeTypeId(bytes: Uint8Array, baseType: typeof Schema, targetType: typeof Schema, it: Iterator): void;
     get hasChanges(): boolean;
+    get hasUnreliableChanges(): boolean;
 }

package/build/encoder/MapJournal.d.ts

@@ -0,0 +1,62 @@
+/**
+ * MapJournal — owns the change-tracking and wire-protocol identity for a MapSchema.
+ *
+ * Replaces three parallel structures that previously lived on MapSchema:
+ *   - `$indexes: Map<number, K>`        →  `keyByIndex`
+ *   - `_collectionIndexes: { [key]: number }` (+ counter)  →  `indexByKey` + `nextIndex`
+ *   - `deletedItems: { [index]: V }`    →  `snapshots`
+ *
+ * The journal is the single source of truth for:
+ *   - assigning wire-protocol indexes to keys (server side)
+ *   - looking up keys from wire indexes (server + client)
+ *   - holding snapshots of removed values (for view-filter visibility checks)
+ *
+ * The journal does NOT track per-index operation types or maintain enqueue
+ * order — those remain on `ChangeTree` for now. A future iteration may pull
+ * them in too, but this version is intentionally scoped to the data-model
+ * cleanup so we can validate the abstraction before going deeper.
+ */
+export declare class MapJournal<K = any> {
+    /** index → key (was MapSchema.$indexes). Used by encoder and decoder. */
+    keyByIndex: Map<number, K>;
+    /**
+     * key → index (was MapSchema._collectionIndexes — forward direction).
+     * Server-only. Plain object so MapSchema can expose it via a getter
+     * for backwards-compatible `_collectionIndexes?.[key]` access from
+     * ChangeTree.forEachChild and similar polymorphic call sites.
+     */
+    indexByKey: {
+        [key: string]: number;
+    };
+    /** Monotonic counter for assigning new indexes. Server-only. */
+    private nextIndex;
+    /**
+     * Snapshot of values at the moment they were deleted. Lazy — only
+     * allocated on first delete, since most maps are pure-grow and never
+     * touch this. Used by `MapSchema[$filter]` to check view visibility
+     * of a value that's already been removed from `$items` but whose
+     * DELETE op is still in the encode queue.
+     */
+    snapshots?: Map<number, any>;
+    /** Get the index assigned to a key, or undefined if never assigned. */
+    indexOf(key: K): number | undefined;
+    /** Assign and return a new wire index for an unseen key. */
+    assign(key: K): number;
+    /** Stash a value at the moment it's deleted (for filter visibility checks). */
+    snapshot(index: number, value: any): void;
+    /** Discard a snapshot — called when a deleted slot is being re-set. */
+    forgetSnapshot(index: number): void;
+    /** Look up a snapshot. Returns undefined if no DELETE is pending for this index. */
+    snapshotAt(index: number): any;
+    /** Decoder calls this when it sees an ADD/DELETE_AND_ADD on the wire. */
+    setIndex(index: number, key: K): void;
+    /** Reverse lookup: wire index → key. */
+    keyOf(index: number): K | undefined;
+    /**
+     * Called from MapSchema's $onEncodeEnd hook.
+     * Cleans up index/key mappings for entries that were deleted in this tick.
+     */
+    cleanupAfterEncode(): void;
+    /** Reset everything (called on .clear()). */
+    reset(): void;
+}

package/build/encoder/RefIdAllocator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Allocates monotonically-increasing refIds with a reuse pool.
+ *
+ * `acquire()` pops from the free pool when available, otherwise bumps a
+ * counter. `release()` queues a refId for reuse; the id doesn't become
+ * acquirable until `flushReleases()` runs — the one-tick defer is what
+ * lets the encoder guarantee a DELETE for the old instance reaches the
+ * wire before the refId is handed to a new one.
+ *
+ * `reclaim()` handles "resurrection": a ref that was released but whose
+ * JS instance is still alive can be re-added to the tree, in which case
+ * the encoder must pull the refId back out of the pool before it's
+ * handed to an unrelated instance.
+ */
+export declare class RefIdAllocator {
+    protected nextUniqueId: number;
+    private _free;
+    private _pending;
+    private _pooled;
+    constructor(startRefId?: number);
+    acquire(): number;
+    release(refId: number): void;
+    isPooled(refId: number): boolean;
+    /**
+     * Remove a refId from the pool. Called when a ref whose refId was
+     * released is being resurrected. O(n) scan of the relevant array,
+     * but resurrection is rare.
+     */
+    reclaim(refId: number): void;
+    /**
+     * Promote this tick's releases into the acquirable set. Called from
+     * `Encoder.discardChanges()` — never mid-encode.
+     */
+    flushReleases(): void;
+}

package/build/encoder/Root.d.ts

@@ -1,28 +1,109 @@
 import { TypeContext } from "../types/TypeContext.js";
-import { ChangeTree, ChangeTreeList, ChangeSetName, type ChangeTreeNode } from "./ChangeTree.js";
+import { ChangeTree, ChangeTreeList, type ChangeTreeNode } from "./ChangeTree.js";
+import { $changes, $refId } from "../types/symbols.js";
+import { RefIdAllocator } from "./RefIdAllocator.js";
+import type { StateView } from "./StateView.js";
+import type { StreamableState } from "./streaming.js";
+/**
+ * Minimal shape the encoder needs from a streamable collection. Both
+ * `StreamSchema` and `.stream()`-decorated `MapSchema`/`SetSchema` etc.
+ * satisfy this via a single lazily-allocated `_stream` slot — the
+ * per-view / broadcast bookkeeping lives on that object, not directly
+ * on the collection, so non-streaming instances pay zero Map/Set
+ * allocation cost.
+ */
+export interface Streamable {
+    [$refId]?: number;
+    [$changes]: ChangeTree;
+    _stream?: StreamableState;
+    _dropView(viewId: number): void;
+    _unregister(): void;
+}
 export declare class Root {
     types: TypeContext;
-    protected nextUniqueId: number;
+    /**
+     * Allocates and recycles refIds. See `RefIdAllocator` for the reuse
+     * pool semantics (one-tick defer + resurrection).
+     */
+    readonly refIds: RefIdAllocator;
     refCount: {
         [id: number]: number;
     };
     changeTrees: {
         [refId: number]: ChangeTree;
     };
-    allChanges: ChangeTreeList;
-    allFilteredChanges: ChangeTreeList;
+    /**
+     * Queue of all ChangeTrees with reliable dirty state. Per-tick encode()
+     * walks this queue; per-view encodeView() walks it too (filtering at
+     * emission time via tree.isFiltered + per-field @view tag).
+     */
     changes: ChangeTreeList;
-    filteredChanges: ChangeTreeList;
-    constructor(types: TypeContext);
-    getNextUniqueId(): number;
+    /**
+     * Queue of all ChangeTrees with unreliable dirty state. Walked by
+     * `Encoder.encodeUnreliable` / `encodeUnreliableView`. A tree may live
+     * in both queues when the Schema has both reliable and unreliable
+     * fields dirty at the same time.
+     */
+    unreliableChanges: ChangeTreeList;
+    /**
+     * Free-list of ChangeTreeNode objects. Both queues share this pool —
+     * a node carries no queue affinity, only `{ changeTree, prev, next, position }`.
+     * Reusing nodes turns ~1,250 per-tick allocations (in bench) into 0.
+     */
+    private _nodePool;
+    /**
+     * View ID allocator for StateView visibility bitmaps on ChangeTree.
+     * Each new StateView claims the lowest free ID; releaseViewId() puts
+     * the ID back. Avoids unbounded bitmap growth across long-running rooms
+     * with view churn (clients joining/leaving).
+     */
+    private _nextViewId;
+    private _freeViewIds;
+    /** Allocate a fresh view ID (lowest available). */
+    acquireViewId(): number;
+    /** Return a view ID to the freelist for reuse. */
+    releaseViewId(id: number): void;
+    /**
+     * Currently-bound StateViews, keyed by view ID and held via `WeakRef`
+     * so the FinalizationRegistry backstop in StateView still works when
+     * the user forgets `dispose()`. Callers must iterate via
+     * `forEachActiveView`, which prunes dead entries.
+     */
+    activeViews: Map<number, WeakRef<StateView>>;
+    /**
+     * Streamable collections attached under this Root — `StreamSchema`
+     * plus any collection opted into streaming via `.stream()` on the
+     * builder. Encoder.encodeView / broadcast pass iterates this set to
+     * dispatch per-view / per-tick budget gates.
+     */
+    streamTrees: Set<Streamable>;
+    registerView(view: StateView): void;
+    unregisterView(view: StateView): void;
+    /**
+     * Iterate all live StateViews bound to this Root. Prunes entries
+     * whose underlying view has been garbage collected without an
+     * explicit `dispose()`.
+     */
+    forEachActiveView(cb: (view: StateView) => void): void;
+    registerStream(stream: Streamable): void;
+    unregisterStream(stream: Streamable): void;
+    constructor(types: TypeContext, startRefId?: number);
     add(changeTree: ChangeTree): boolean;
     remove(changeTree: ChangeTree): number;
     recursivelyMoveNextToParent(changeTree: ChangeTree): void;
     moveNextToParent(changeTree: ChangeTree): void;
-    moveNextToParentInChangeTreeList(changeSetName: ChangeSetName, changeTree: ChangeTree): void;
-    enqueueChangeTree(changeTree: ChangeTree, changeSet: 'changes' | 'filteredChanges' | 'allFilteredChanges' | 'allChanges', queueRootNode?: ChangeTreeNode): void;
-    protected addToChangeTreeList(list: ChangeTreeList, changeTree: ChangeTree): ChangeTreeNode;
-    protected updatePositionsAfterRemoval(list: ChangeTreeList, removedPosition: number): void;
-    protected updatePositionsAfterMove(list: ChangeTreeList, node: ChangeTreeNode, newPosition: number): void;
-    removeChangeFromChangeSet(changeSetName: ChangeSetName, changeTree: ChangeTree): boolean;
+    private _moveNextToParentInList;
+    enqueueChangeTree(changeTree: ChangeTree, existingNode?: ChangeTreeNode): void;
+    enqueueUnreliable(changeTree: ChangeTree, existingNode?: ChangeTreeNode): void;
+    private _appendToList;
+    /**
+     * Release a detached node back to the free-list. Caller must have
+     * already unlinked it from any list and cleared the changeTree's
+     * pointer to it. Clears `changeTree`/`prev`/`next` so the pool
+     * doesn't retain references through the GC root.
+     */
+    releaseNode(node: ChangeTreeNode): void;
+    removeFromQueue(changeTree: ChangeTree): boolean;
+    removeFromUnreliableQueue(changeTree: ChangeTree): boolean;
+    private _removeNode;
 }

package/build/encoder/StateView.d.ts

@@ -1,4 +1,5 @@
-import { ChangeTree, IndexedOperations, Ref } from "./ChangeTree.js";
+import { ChangeTree, Ref } from "./ChangeTree.js";
+import { OPERATION } from "../encoding/spec.js";
 export declare function createView(iterable?: boolean): StateView;
 export declare class StateView {
     iterable: boolean;
@@ -8,26 +9,133 @@ export declare class StateView {
      */
     items: Ref[];
     /**
-     * List of ChangeTree's that are visible to this view
+     * Unique ID assigned by the Root that owns this view's encoder. Used
+     * to address per-StateView visibility bits stored on each ChangeTree.
+     * Lazily allocated on first `add()` because the StateView itself
+     * doesn't know its Root until then.
      */
-    visible: WeakSet<ChangeTree>;
+    id: number;
+    private _root?;
+    /** Cached `id >> 5` and `1 << (id & 31)` for the hot encode-loop check. */
+    private _slot;
+    private _bit;
     /**
-     * List of ChangeTree's that are invisible to this view
+     * Per-tree custom-tag membership lives on each ChangeTree's `tagViews`
+     * map (keyed by tag, value is a per-view bitmap). The StateView only
+     * needs its slot/bit pair to read/write it. Replaces the legacy
+     * `tags: WeakMap<ChangeTree, Set<number>>` allocation per (view, tree).
      */
-    invisible: WeakSet<ChangeTree>;
-    tags?: WeakMap<ChangeTree, Set<number>>;
     /**
      * Manual "ADD" operations for changes per ChangeTree, specific to this view.
-     * (This is used to force encoding a property, even if it was not changed)
+     * (Used to force encoding a property even if it was not changed.)
+     *
+     * Inner storage is a Map so the encode loop in `encodeView` can iterate
+     * directly with numeric keys — the legacy `{[index]: OPERATION}` shape
+     * forced an `Object.keys(...)` allocation + `Number(key)` parse per ref.
      */
-    changes: Map<number, IndexedOperations>;
+    changes: Map<number, Map<number, OPERATION>>;
     constructor(iterable?: boolean);
+    /**
+     * Lazily bind this view to a Root and acquire a view ID. Called on
+     * the first add() because StateView is constructed before its target
+     * Root is known.
+     */
+    private _bindRoot;
+    /**
+     * Release this view's ID back to the Root for reuse, AND clear all
+     * visibility bits this view set on any ChangeTree. The clear is
+     * essential — without it, a future view that acquires this same ID
+     * would inherit our visibility state and see things it shouldn't
+     * (privacy bug). Documented in StateViewInternals.test.ts.
+     *
+     * Optional API but strongly recommended on client-leave; otherwise
+     * the FinalizationRegistry backstop runs at GC (non-deterministic).
+     */
+    dispose(): void;
+    /** True iff this view can see `tree`. */
+    isVisible(tree: ChangeTree): boolean;
+    /** Mark `tree` as visible to this view. */
+    markVisible(tree: ChangeTree): void;
+    /** Clear visibility bit. */
+    unmarkVisible(tree: ChangeTree): void;
+    /** True iff this view is subscribed to `tree`. */
+    isSubscribed(tree: ChangeTree): boolean;
+    /** Set the subscription bit on `tree`. */
+    private _setSubscribed;
+    /** Clear the subscription bit on `tree`. */
+    private _clearSubscribed;
+    /** True iff this view has previously marked `tree` as invisible. */
+    isInvisible(tree: ChangeTree): boolean;
+    /** Mark `tree` as invisible to this view (used by encode loop). */
+    markInvisible(tree: ChangeTree): void;
+    /** Clear invisible bit. */
+    unmarkInvisible(tree: ChangeTree): void;
+    /** True iff this view has `tag` associated with `tree`. */
+    hasTagOnTree(tree: ChangeTree, tag: number): boolean;
+    /** Mark `tree` as carrying `tag` for this view. */
+    addTag(tree: ChangeTree, tag: number): void;
+    /** Clear this view's `tag` bit on `tree`. */
+    removeTag(tree: ChangeTree, tag: number): void;
+    /** Clear ALL tag bits this view holds on `tree` (used when the per-tag isn't known). */
+    removeAllTagsOnTree(tree: ChangeTree): void;
     add(obj: Ref, tag?: number, checkIncludeParent?: boolean): boolean;
+    /**
+     * Internal: force-ship an object through `view.changes` without
+     * applying stream-element routing. Called by `Encoder._emitStreamPriority`
+     * when it's draining `_pendingByView` — the element is already out of
+     * pending at that point, so re-routing back into pending would be a
+     * loop. User code should always call `add()`.
+     */
+    _addImmediate(obj: Ref, tag?: number): void;
+    private _add;
+    /**
+     * Walk an isNew subtree marking each descendant visible. Counterpart
+     * to the `_add()` fast path: skips `view.changes` allocations because
+     * the shared encode pass emits the whole fresh subtree structurally
+     * — the view pass just needs visibility bits to let those emissions
+     * through the per-tree filter.
+     *
+     * Preserves the `@view()`-tag filter from `_add`'s forEachChild: a
+     * Schema descendant behind a non-matching field tag is skipped so
+     * tagged fields don't leak into a default-tag view. Collections have
+     * no per-field tags (`encDescriptor.tags` is empty), so the filter
+     * is a no-op for collection children.
+     *
+     * If a descendant has `isNew=false` (rare: a detached sub-collection
+     * was re-attached to a fresh parent), fall back to the full `_add`
+     * path for that branch so its cumulative state is emitted correctly.
+     */
+    private _markSubtreeVisible;
     protected addParentOf(childChangeTree: ChangeTree, tag: number): void;
     remove(obj: Ref, tag?: number): this;
     remove(obj: Ref, tag?: number, _isClear?: boolean): this;
     has(obj: Ref): boolean;
     hasTag(ob: Ref, tag?: number): boolean;
+    /**
+     * Persistent subscription to a collection's contents. Unlike `add()`,
+     * which is a one-shot bootstrap, `subscribe()` enrolls this view in
+     * future content changes — every subsequent push / set / add to the
+     * collection automatically flows to this view, and every removal
+     * queues a DELETE op. Works on every collection type:
+     *
+     * - `ArraySchema` / `MapSchema` / `SetSchema` / `CollectionSchema`:
+     *   new children are force-shipped immediately (equivalent to
+     *   `view.add(child)` per item).
+     * - `StreamSchema` (or `.stream()` maps/sets): new positions are
+     *   enqueued into `_pendingByView` so the priority pass drains them
+     *   respecting `maxPerTick`.
+     *
+     * Idempotent on re-subscribe. Subscribing to an already-subscribed
+     * collection is a no-op.
+     */
+    subscribe(collection: Ref): this;
+    /**
+     * End a persistent subscription. Queues DELETE for every already-sent
+     * child and clears any pending. After this call, future content
+     * changes on the collection no longer auto-flow to this view (though
+     * direct `view.add(element)` calls still work for per-entity use).
+     */
+    unsubscribe(collection: Ref): this;
     clear(): void;
     isChangeTreeVisible(changeTree: ChangeTree): boolean;
     protected _recursiveDeleteVisibleChangeTree(changeTree: ChangeTree): void;

package/build/encoder/changeTree/inheritedFlags.d.ts

@@ -0,0 +1,34 @@
+import { type ChangeTree, type Ref } from "../ChangeTree.js";
+/**
+ * Reconcile queue membership + inherited flags for a tree that just had
+ * its root/parent assigned. See `_checkInheritedFlags` for the flag
+ * inheritance logic.
+ */
+export declare function checkIsFiltered(tree: ChangeTree, parent: Ref, parentIndex: number, _isNewChangeTree: boolean): void;
+/**
+ * Inherit filter / unreliable / transient / static classification from
+ * the parent field's annotation. Collections (MapSchema / ArraySchema /
+ * etc.) inherit these from the Schema field that holds them.
+ *
+ * The common case — fresh tree attached to a parent field that carries
+ * none of the inheritable annotations — produces no flag change, no
+ * queue update, and no `parentFiltered` hit. Two small structural
+ * choices keep that case cheap without any precomputed descriptor
+ * bitmask:
+ *
+ *  1) Flag inheritance is a single bitwise OR onto `tree.flags`. The
+ *     three per-annotation reads pack into `fieldBits`, the parent's
+ *     inherited bits come from `parentChangeTree.flags` directly; one
+ *     read-modify-write replaces three getter/setter cycles, and the
+ *     bit diff against `beforeFlags` gives us the "just became static /
+ *     unreliable" signal for the side-effect branches.
+ *
+ *  2) The `parentFiltered` string-key lookup is gated on
+ *     `types.hasParentFilteredEntries`, which is only flipped true when
+ *     `registerFilteredByParent` actually records an entry — i.e. when
+ *     some @view-tagged field reaches this (child, parent, index)
+ *     triple through the ancestry walk. Schemas with @view tags only on
+ *     sibling fields (not along any attachment chain) skip the string
+ *     concat + hash lookup entirely.
+ */
+export declare function checkInheritedFlags(tree: ChangeTree, parent: Ref, parentIndex: number): void;

package/build/encoder/changeTree/liveIteration.d.ts

@@ -0,0 +1,3 @@
+import type { ChangeTree } from "../ChangeTree.js";
+export declare function forEachLive(tree: ChangeTree, callback: (index: number) => void): void;
+export declare function forEachLiveWithCtx<C>(tree: ChangeTree, ctx: C, cb: (ctx: C, index: number) => void): void;

package/build/encoder/changeTree/parentChain.d.ts

@@ -0,0 +1,24 @@
+import type { ChangeTree, ParentChain, Ref } from "../ChangeTree.js";
+/**
+ * Add a parent to the chain. If `parent` already exists anywhere in the
+ * chain, update the primary parent's index instead (matches legacy
+ * behavior).
+ */
+export declare function addParent(tree: ChangeTree, parent: Ref, index: number): void;
+/**
+ * Remove a parent from the chain.
+ * @returns true if parent was found and removed (Root.remove relies on this).
+ */
+export declare function removeParent(tree: ChangeTree, parent: Ref): boolean;
+/**
+ * Find the first parent in the chain matching `predicate`.
+ */
+export declare function findParent(tree: ChangeTree, predicate: (parent: Ref, index: number) => boolean): ParentChain | undefined;
+export declare function hasParent(tree: ChangeTree, predicate: (parent: Ref, index: number) => boolean): boolean;
+/**
+ * Return all parents as an array (debug/test helper).
+ */
+export declare function getAllParents(tree: ChangeTree): Array<{
+    ref: Ref;
+    index: number;
+}>;

package/build/encoder/changeTree/treeAttachment.d.ts

@@ -0,0 +1,13 @@
+import { Root } from "../Root.js";
+import type { ChangeTree, Ref } from "../ChangeTree.js";
+export declare function setRoot(tree: ChangeTree, root: Root): void;
+export declare function setParent(tree: ChangeTree, parent: Ref, root?: Root, parentIndex?: number): void;
+export declare function forEachChild(tree: ChangeTree, callback: (change: ChangeTree, at: any) => void): void;
+/**
+ * Closure-free variant of {@link forEachChild}. Hot setRoot / setParent
+ * recursion calls this once per new Schema instance attached to the
+ * tree — the per-call closure was the #1 JS hotspot in profile-baseline.
+ * Pass an explicit `ctx` so callers can hoist the callback to module
+ * scope and avoid the allocation.
+ */
+export declare function forEachChildWithCtx<C>(tree: ChangeTree, ctx: C, callback: (ctx: C, change: ChangeTree, at: any) => void): void;

package/build/encoder/streaming.d.ts

@@ -0,0 +1,73 @@
+import type { Root, Streamable } from "./Root.js";
+/**
+ * Thrown (from both the `FieldBuilder` chainable and the decorator's
+ * `addField` auto-flag) when a user attempts to stream an ArraySchema.
+ * Centralized so the two callsites emit the same diagnostic.
+ */
+export declare const ARRAY_STREAM_NOT_SUPPORTED: string;
+/**
+ * Per-instance bookkeeping for a streamable collection. Lazily allocated
+ * by `ensureStreamState` when the collection's ChangeTree picks up the
+ * `isStreamCollection` flag (or when the user touches `maxPerTick`).
+ */
+export interface StreamableState {
+    /** Per-view ADD backlog: wire-indexes not yet sent to that view. */
+    pendingByView: Map<number, Set<number>>;
+    /** Per-view SENT set — decides whether `remove()` emits a DELETE. */
+    sentByView: Map<number, Set<number>>;
+    /** Broadcast-mode ADD backlog (no active views). */
+    broadcastPending: Set<number>;
+    /** Broadcast-mode SENT set. */
+    sentBroadcast: Set<number>;
+    /** Broadcast-mode DELETE queue — flushes next shared tick. */
+    broadcastDeletes: Set<number>;
+    /** Max ADD ops emitted per tick per view (or per shared tick). */
+    maxPerTick: number;
+    /**
+     * Priority callback seeded from the schema declaration. Receives the
+     * client's StateView and the candidate element; higher return values
+     * emit first. Broadcast `encode()` ignores this and drains FIFO.
+     * Instance-level override: assign to `stream.priority`.
+     */
+    priority?: (view: any, element: any) => number;
+}
+export declare function createStreamableState(): StreamableState;
+/** Allocate `_stream` on first use (idempotent). Returns the state. */
+export declare function ensureStreamState(s: Streamable): StreamableState;
+/**
+ * Route an ADD into the pending backlogs.
+ * - No active views: push into broadcast pending (shared encode drains up
+ *   to `maxPerTick` per tick).
+ * - With views: push into per-view pending for every currently-bound view.
+ */
+export declare function streamRouteAdd(s: Streamable, root: Root, index: number): void;
+/**
+ * Route a REMOVE: silent-drop if never sent, force DELETE if already sent.
+ * Returns `true` iff no wire op reached any channel (caller can skip
+ * follow-on work like snapshotting the deleted value).
+ */
+export declare function streamRouteRemove(s: Streamable, root: Root, refId: number, index: number): boolean;
+/**
+ * Queue DELETE ops for every already-sent entry on all channels and
+ * reset pending. Caller is responsible for actually clearing its own
+ * storage and releasing any element refs it owns.
+ */
+export declare function streamRouteClear(s: Streamable, root: Root, refId: number): void;
+/**
+ * Push a single position into `_pendingByView[viewId]` — the building
+ * block for `StateView.add(element)` when the element lives under a
+ * streamable collection. Idempotent for already-pending positions.
+ */
+export declare function streamEnqueueForView(s: Streamable, viewId: number, index: number): void;
+/**
+ * Unsubscribe a single position from a view. Returns true iff the
+ * element had already been sent and a DELETE op was queued on
+ * `view.changes`; false if it was only pending (silent drop) or not
+ * present at all.
+ */
+export declare function streamDequeueForView(s: Streamable, viewId: number, refId: number, index: number, viewChanges: Map<number, Map<number, number>>): boolean;
+/**
+ * Drop all per-view state for a disposing/GC'd StateView. Keeps memory
+ * bounded in long-running rooms with client churn.
+ */
+export declare function streamDropView(s: Streamable, viewId: number): void;

package/build/encoder/subscriptions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-view collection subscriptions — `view.subscribe(collection)` opts
+ * a view into ALL future content changes of a collection, not just a
+ * one-shot snapshot. Covers every collection type:
+ *
+ * - `ArraySchema` / `MapSchema` / `SetSchema` / `CollectionSchema`: new
+ *   children are force-shipped immediately via `view._addImmediate(child)`.
+ *   Subsequent field mutations on those children emit via the normal
+ *   view pass (the children are now visible).
+ * - `StreamSchema` (or a `.stream()` map/set): new positions are
+ *   enqueued into `_pendingByView` so the encoder's priority pass
+ *   drains them respecting `maxPerTick`.
+ *
+ * The propagation hook is in `changeTree/treeAttachment.ts setParent`
+ * — every new child attachment to a collection checks the parent tree's
+ * `subscribedViews` bitmap and fans out to subscribed views.
+ */
+import type { ChangeTree, Ref } from "./ChangeTree.js";
+import type { Root } from "./Root.js";
+/**
+ * Walk the `subscribedViews` bitmap of `parentTree` and propagate a new
+ * child attachment to every subscribed view. Streams route through the
+ * priority/pending queue; all other collections force-ship immediately.
+ */
+export declare function propagateNewChildToSubscribers(parentTree: ChangeTree, childIndex: number, childRef: Ref, root: Root): void;