@net-mesh/browser 0.42.0 → 0.44.0

package/dist/netcode/wire.d.ts

@@ -40,22 +40,43 @@ export interface WireInput<I> {
     readonly data: I;
 }
 export type Frame<E, I> = 
-/** Player → host: join (repeated until the first snapshot). */
+/**
+ * Player → host: join (repeated until the first snapshot). `f` is the
+ * player's entity-codec fingerprint, if it has one: the host sends binary
+ * snapshots only when it matches its own (`codec.ts`).
+ */
 {
     readonly n: string;
     readonly k: 'h';
+    readonly f?: string;
 }
-/** Player → host: the newest inputs, the unacknowledged ones repeated. */
+/**
+ * Player → host: the newest inputs, the unacknowledged ones repeated.
+ * `ep`: the assignment epoch the player sent them under (sharded
+ * matches); a host at another epoch drops them.
+ */
  | {
     readonly n: string;
     readonly k: 'i';
     readonly i: readonly WireInput<I>[];
+    readonly ep?: number;
 }
-/** Player → host: clock ping. */
+/** Player → host: clock ping, repeating the codec fingerprint (a lost join must not pin a player to JSON). */
  | {
     readonly n: string;
     readonly k: 'p';
     readonly t0: number;
+    readonly f?: string;
+}
+/**
+ * Player → host: binary-snapshot indexes it has no name for; the host
+ * names them again (only indexes it showed that player, and an index at
+ * most once per 100 ms).
+ */
+ | {
+    readonly n: string;
+    readonly k: 'u';
+    readonly u: readonly number[];
 }
 /**
  * Player → host: the interest keys it wants, version `v` (repeated until a
@@ -93,10 +114,23 @@ export type Frame<E, I> =
     readonly of?: number;
     /** The interest version this snapshot was filtered by, if any. */
     readonly iv?: number;
+    /** The assignment epoch the host sent it under (sharded matches). */
+    readonly ep?: number;
 };
 /** Interest keys a player may name, and the longest key, in UTF-16 units. */
 export declare const MAX_NETCODE_INTEREST_KEYS = 256;
 export declare const MAX_NETCODE_INTEREST_KEY_LENGTH = 64;
+/** Indexes one `u` frame may ask to have named. */
+export declare const MAX_NAME_REQUESTS = 256;
+/**
+ * A binary-snapshot name not used for this long, ms, is forgotten: by the
+ * host for an id no player has been shown (it gets a fresh index if it
+ * comes back, named again), and by the host for one player once that
+ * player has not been shown it. A player keeps a name three times as long
+ * from the last frame that carried the index, so it never forgets one the
+ * host still counts as known to it; forgetting early would only cost a `u`.
+ */
+export declare const NAME_FORGET_MS = 10000;
 /** Chunks a snapshot may be split into, at most. */
 export declare const MAX_SNAPSHOT_CHUNKS = 256;
 /**

package/dist/netcode/wire.js

@@ -11,6 +11,17 @@
 /** Interest keys a player may name, and the longest key, in UTF-16 units. */
 export const MAX_NETCODE_INTEREST_KEYS = 256;
 export const MAX_NETCODE_INTEREST_KEY_LENGTH = 64;
+/** Indexes one `u` frame may ask to have named. */
+export const MAX_NAME_REQUESTS = 256;
+/**
+ * A binary-snapshot name not used for this long, ms, is forgotten: by the
+ * host for an id no player has been shown (it gets a fresh index if it
+ * comes back, named again), and by the host for one player once that
+ * player has not been shown it. A player keeps a name three times as long
+ * from the last frame that carried the index, so it never forgets one the
+ * host still counts as known to it; forgetting early would only cost a `u`.
+ */
+export const NAME_FORGET_MS = 10_000;
 /** Chunks a snapshot may be split into, at most. */
 export const MAX_SNAPSHOT_CHUNKS = 256;
 /**
@@ -25,6 +36,10 @@ export function chunkOf(id, of) {
     }
     return (hash >>> 0) % of;
 }
+/** An `ep` field: absent, or a non-negative safe integer. */
+function epochField(ep) {
+    return ep === undefined || (Number.isSafeInteger(ep) && ep >= 0);
+}
 const encoder = new TextEncoder();
 const decoder = new TextDecoder('utf-8', { fatal: true });
 export function encodeFrame(frame) {
@@ -47,11 +62,22 @@ export function decodeFrame(payload, label) {
     const frame = value;
     if (frame.n !== label || typeof frame.k !== 'string')
         return null;
+    const fingerprint = frame.f;
+    if (fingerprint !== undefined && (typeof fingerprint !== 'string' || fingerprint.length > 64))
+        return null;
     switch (frame.k) {
         case 'h':
             return frame;
+        case 'u': {
+            const u = frame.u;
+            return Array.isArray(u) && u.length <= MAX_NAME_REQUESTS && u.every(index => Number.isSafeInteger(index) && index >= 0)
+                ? frame
+                : null;
+        }
         case 'i':
-            return Array.isArray(frame.i) ? frame : null;
+            return Array.isArray(frame.i) && epochField(frame.ep)
+                ? frame
+                : null;
         case 'p':
             return typeof frame.t0 === 'number' ? frame : null;
         case 'w': {
@@ -73,6 +99,7 @@ export function decodeFrame(payload, label) {
         case 's': {
             const s = frame;
             if ((s.iv !== undefined && !Number.isSafeInteger(s.iv)) ||
+                !epochField(s.ep) ||
                 typeof s.tick !== 'number' ||
                 typeof s.t !== 'number' ||
                 typeof s.ack !== 'number' ||

package/dist/node.d.ts

@@ -257,6 +257,19 @@ export interface ConnectOptions extends WasmSource {
      * an entity but not a static key.
      */
     noiseSecretHex?: string;
+    /**
+     * Hold this identity exclusively while the node is open (default
+     * `true`; only read with {@link ConnectOptions.entitySecretHex}).
+     *
+     * Two tabs connected as the same node evict each other at the anchor,
+     * so stores and lobbies in both flap — the hazard `openSession()`
+     * avoids by electing one leader. `connect()` takes a Web Lock named
+     * after a hash of the identity (never the secret) and refuses a second
+     * holder with an {@link IdentityError} instead; `close()` releases it.
+     * Where Web Locks are unavailable the lock is skipped. Pass `false` to
+     * run without it (SDK audit 2026-10-11).
+     */
+    lockIdentity?: boolean;
     /**
      * The `rtc_addr` the anchor publishes, supplied out of band.
      *
@@ -312,6 +325,8 @@ export declare class BrowserNode {
     private anchorRtcAddrs;
     /** Set once the leaf reports a session — a bootstrap that demonstrably worked. */
     private bootstrapObserved;
+    /** Releases the identity's Web Lock (`connect({ lockIdentity })`). */
+    private releaseIdentity;
     /** This node's mesh id, hex. */
     nodeIdHex(): string;
     /** The anchor's mesh id, hex. */
@@ -868,6 +883,11 @@ export interface RetryReport {
     readonly online: string;
     /** Triggers filed by the ICE `disconnected` → `failed` watcher. */
     readonly iceFailed: string;
+    /**
+     * Triggers filed because the far end closed a DataChannel a session
+     * rode. One channel's loss counts once, here or under `iceFailed`.
+     */
+    readonly channelClosed: string;
     /** Every trigger seen, whatever the owner decided. */
     readonly triggers: string;
     /** Re-attempts STARTED. One per network change, per peer. */

package/dist/node.js

@@ -83,6 +83,12 @@ export class BrowserNode {
     anchorRtcAddrs = [];
     /** Set once the leaf reports a session — a bootstrap that demonstrably worked. */
     bootstrapObserved = false;
+    /** Releases the identity's Web Lock (`connect({ lockIdentity })`). */
+    releaseIdentity = null;
+    /** @internal — `connect()` hands over the identity lock it took. */
+    releaseIdentityOnClose(release) {
+        this.releaseIdentity = release;
+    }
     /** @internal — use {@link connect}. */
     constructor(inner, bootstrapUrl, failureTyping, anchorRtcAddr) {
         this.inner = inner;
@@ -787,6 +793,10 @@ export class BrowserNode {
         if (this.closed)
             return;
         this.closed = true;
+        // Whatever else fails below, the identity is free for another tab.
+        const releaseIdentity = this.releaseIdentity;
+        this.releaseIdentity = null;
+        queueMicrotask(() => releaseIdentity?.());
         const failures = [];
         // Ownership retirement first, while the node can still put a
         // CANCEL on the wire (plan §4.5): one per dropped caller handle,
@@ -851,11 +861,17 @@ export async function connect(options) {
     const request = buildConnectRequest(options);
     const failureTyping = options.failureTyping ?? {};
     const wasm = await loadLeafWasm(options);
+    const release = request.entitySecretHex !== undefined && options.lockIdentity !== false
+        ? await lockIdentity(request.entitySecretHex)
+        : null;
     try {
         const inner = await wasm.LeafNode.connect(request);
-        return new BrowserNode(inner, options.bootstrapUrl ?? null, failureTyping, options.anchorRtcAddr ?? null);
+        const node = new BrowserNode(inner, options.bootstrapUrl ?? null, failureTyping, options.anchorRtcAddr ?? null);
+        node.releaseIdentityOnClose(release);
+        return node;
     }
     catch (error) {
+        release?.();
         throw await refineIceFailure(fromWasmError(error), {
             bootstrapUrl: options.bootstrapUrl ?? null,
             bootstrapObserved: false,
@@ -864,6 +880,64 @@ export async function connect(options) {
         });
     }
 }
+/**
+ * The Web Lock name for one custodial identity, or `null` where
+ * `crypto.subtle` is unavailable. A hash of the secret, never the secret.
+ *
+ * Shared by `connect()` and `openSession()`: a session with a custodial
+ * secret names its election lock with this too, so a `connect()` tab and
+ * an `openSession()` tab given one secret contend for ONE lock instead of
+ * each running a node with that identity (cubic review of PR #1228).
+ *
+ * @internal
+ */
+export async function identityLockName(entitySecretHex) {
+    const subtle = globalThis.crypto?.subtle;
+    if (subtle === undefined)
+        return null;
+    // Lowercased: the secret parses case-insensitively, so "AB…" and "ab…" are
+    // one identity and must contend for one lock (code review 2026-10-11,
+    // BROWSER-3).
+    const canonical = entitySecretHex.toLowerCase();
+    const digest = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(`net-mesh:identity:${canonical}`)));
+    return `net-mesh:identity:${Array.from(digest.subarray(0, 16), b => b.toString(16).padStart(2, '0')).join('')}`;
+}
+/**
+ * Take the exclusive Web Lock for one custodial identity, or throw an
+ * {@link IdentityError} when another tab or window holds it. Returns the
+ * release, or `null` where Web Locks (or `crypto.subtle`, for the hashed
+ * name) are unavailable.
+ */
+async function lockIdentity(entitySecretHex) {
+    const locks = globalThis.navigator?.locks;
+    if (locks === undefined)
+        return null;
+    const name = await identityLockName(entitySecretHex);
+    if (name === null)
+        return null;
+    const acquired = await new Promise((resolve, reject) => {
+        let release;
+        const held = new Promise(done => {
+            release = done;
+        });
+        locks
+            .request(name, { ifAvailable: true }, async (lock) => {
+            if (lock === null) {
+                resolve('busy');
+                return;
+            }
+            resolve(release);
+            await held;
+        })
+            .catch(reject);
+    });
+    if (acquired === 'busy') {
+        throw new IdentityError('this identity is already connected in another tab or window of this browser; ' +
+            'two nodes with one identity evict each other at the anchor (use openSession() to share one ' +
+            'node across tabs, or pass lockIdentity: false)');
+    }
+    return acquired;
+}
 /**
  * Build exactly the options object `LeafNode.connect` reads, credential
  * resolved, origin defaulted, custodial identity validated.
@@ -1001,6 +1075,7 @@ export function parseRetryReport(json) {
         armed: raw.armed === true,
         online: String(raw.online ?? '0'),
         iceFailed: String(raw.iceFailed ?? '0'),
+        channelClosed: String(raw.channelClosed ?? '0'),
         triggers: String(raw.triggers ?? '0'),
         started: String(raw.started ?? '0'),
         coalesced: String(raw.coalesced ?? '0'),

package/dist/store/host.js

@@ -64,16 +64,22 @@ export const FAREWELL_DEADLINE_MS = 500;
 export function peerHexOf(peer) {
     const decimal = /^\d+$/.test(peer);
     const hex = /^(0x)?[0-9a-f]{1,16}$/i.test(peer);
+    let out;
     try {
         if (decimal)
-            return BigInt(peer).toString(16).padStart(16, '0');
-        if (hex)
-            return BigInt(peer.startsWith('0x') ? peer : `0x${peer}`).toString(16).padStart(16, '0');
+            out = BigInt(peer).toString(16).padStart(16, '0');
+        else if (hex)
+            out = BigInt(peer.startsWith('0x') ? peer : `0x${peer}`).toString(16).padStart(16, '0');
+        else
+            return null;
     }
     catch {
         return null;
     }
-    return null;
+    // A decimal above u64 renders as 17+ hex digits: no node has that id, so
+    // it is not one — `kick('18446744073709551616')` used to target nobody
+    // without an error (cubic review of PR #1228).
+    return out.length === 16 ? out : null;
 }
 /**
  * A node id the CALLER holds, in the same spelling: 16 lowercase hex.

package/dist/store/join.js

@@ -119,6 +119,14 @@ export function joinStore(options) {
     let closed = false;
     let upstream = null;
     let opening = null;
+    /**
+     * Bumped by `reconnect()`. An open started under an older epoch belongs
+     * to the lost session: it never publishes `upstream` and never clears a
+     * newer `opening`, so `reconnect()` can start fresh instead of inheriting
+     * that open's late rejection — or waiting on one that never settles
+     * (code review 2026-10-11, BROWSER-2).
+     */
+    let openEpoch = 0;
     const readyWaiters = [];
     /** The transition in flight and its callers (§2). */
     let transition = null;
@@ -141,6 +149,7 @@ export function joinStore(options) {
         // the relay is installed before the direct half is even tried, so
         // the open below is the thing that decides, and its refusal is
         // typed.
+        const epoch = openEpoch;
         opening = Promise.resolve(options.transport.connectPeer?.(hostHex))
             .catch(() => undefined)
             .then(() => options.transport.openStream({
@@ -149,6 +158,16 @@ export function joinStore(options) {
             label: streamId,
         }))
             .then(open => {
+            if (epoch !== openEpoch) {
+                // Superseded by `reconnect()`: reclaim, never publish.
+                try {
+                    open.close();
+                }
+                catch {
+                    // Already gone.
+                }
+                throw new StoreError('aborted', 'the stream open was superseded by reconnect()');
+            }
             opening = null;
             // An open that resolves after `close()` is reclaimed, never
             // published.
@@ -170,7 +189,8 @@ export function joinStore(options) {
             // answered from it with the same stale error until the caller
             // happens to call `reconnect()`. A transient failure is a retry,
             // not a verdict on the peer.
-            opening = null;
+            if (epoch === openEpoch)
+                opening = null;
             throw error;
         });
         return opening;
@@ -669,9 +689,25 @@ export function joinStore(options) {
         reconnect: async () => {
             if (closed)
                 throw new StoreError('closed', 'this store handle is closed');
-            // The old stream belongs to the lost session.
+            // The old stream belongs to the lost session: CLOSE it, never just
+            // drop it — a dropped LeafStream stays registered with the node and
+            // its wasm listener, so every reconnect leaked one (SDK audit
+            // 2026-10-11). An open still in flight is detached by the epoch
+            // bump: it can no longer overwrite the new stream (it is closed on
+            // arrival instead), and this reconnect no longer inherits its
+            // rejection or its hang.
+            const old = upstream;
             upstream = null;
+            openEpoch += 1;
             opening = null;
+            if (old !== null) {
+                try {
+                    old.close();
+                }
+                catch {
+                    // Already gone with its session.
+                }
+            }
             let requests;
             try {
                 requests = replica.reconnect();

package/dist/store/owner.d.ts

@@ -39,6 +39,15 @@ import { type Hex } from './wire.js';
 export declare const MAX_PENDING_ACTIONS = 32;
 /** Handles one owner will hold (brief §2). */
 export declare const MAX_HANDLES = 256;
+/**
+ * Handles one authenticated peer may hold at once. Room for siblings and
+ * for a reconnect that overlaps its predecessor's lease, but never the
+ * whole table: one peer could otherwise take all {@link MAX_HANDLES} and
+ * lock every other player out — the lobby's capacity rule counts distinct
+ * peers, so a seated player's repeat joins bypassed it (SDK audit
+ * 2026-10-11).
+ */
+export declare const MAX_HANDLES_PER_PEER = 16;
 /** How long a handle lives without an accepted authenticated message. */
 export declare const HANDLE_LEASE_MS = 60000;
 /** What the owner needs from its host. */
@@ -189,6 +198,8 @@ export interface OwnerHandle {
     /** The authenticated peer this handle is bound to (§1.3). */
     readonly peer: string;
     readonly audience: readonly string[];
+    /** The opaque key the `join` carried; every read decision passes it on. */
+    readonly key?: string;
     /** Highest generation allocated for this handle; monotone (§1.7a). */
     readonly generation: number;
     /**

package/dist/store/owner.js

@@ -41,6 +41,15 @@ import { decimalValue, decodeMessage, encodeMessage, utf8Length, HANDLE_HEX_LENG
 export const MAX_PENDING_ACTIONS = 32;
 /** Handles one owner will hold (brief §2). */
 export const MAX_HANDLES = 256;
+/**
+ * Handles one authenticated peer may hold at once. Room for siblings and
+ * for a reconnect that overlaps its predecessor's lease, but never the
+ * whole table: one peer could otherwise take all {@link MAX_HANDLES} and
+ * lock every other player out — the lobby's capacity rule counts distinct
+ * peers, so a seated player's repeat joins bypassed it (SDK audit
+ * 2026-10-11).
+ */
+export const MAX_HANDLES_PER_PEER = 16;
 /** How long a handle lives without an accepted authenticated message. */
 export const HANDLE_LEASE_MS = 60_000;
 /** How many hook runs one drain may perform before it stops (see `drainEvents`). */
@@ -245,7 +254,7 @@ export class StoreOwner {
             // having been checked once at admission. The handle goes with the
             // refusal here because the feed is the grant: leaving it alive would
             // let `alive` renew the lease of a peer the policy now forbids.
-            if (!this.permitsRead(handle.peer, handle.audience)) {
+            if (!this.permitsRead(handle.peer, handle.audience, handle.key)) {
                 this.forget(handle.h, 'refused');
                 // `closed`, the wire's legal unsolicited refusal (§1.12 admits
                 // exactly `closed` and `owner-lost` without a `q`): it closes
@@ -505,7 +514,7 @@ export class StoreOwner {
                 // must not be served because the handle is still warm. The
                 // handle survives the refusal: the request was refused, not
                 // the subscription.
-                if (!this.permitsRead(peer, bound.audience)) {
+                if (!this.permitsRead(peer, bound.audience, bound.key)) {
                     return this.refuse('resync-forbidden', [this.no(peer, bound.h, 'forbidden', message.q)]);
                 }
                 const renewed = { ...bound, lastSeen: now };
@@ -532,7 +541,7 @@ export class StoreOwner {
                 // `audience-too-many` at rung 6 (wire.ts, witnessed in
                 // wire.test.ts), so a frame carrying more than the bound never
                 // reaches dispatch. Re-checking it would be a claim.
-                if (!this.permitsRead(peer, message.aud)) {
+                if (!this.permitsRead(peer, message.aud, bound.key)) {
                     return this.refuse(`${message.k}-forbidden`, [this.no(peer, bound.h, 'forbidden', message.q)]);
                 }
                 // The audience is rebound BEFORE the projection, so the
@@ -1000,7 +1009,7 @@ export class StoreOwner {
     reauthorize() {
         const out = [];
         for (const handle of [...this.handles.values()]) {
-            if (this.permitsRead(handle.peer, handle.audience))
+            if (this.permitsRead(handle.peer, handle.audience, handle.key))
                 continue;
             this.forget(handle.h, 'refused');
             out.push(this.no(handle.peer, handle.h, 'closed', null));
@@ -1152,9 +1161,16 @@ export class StoreOwner {
         if (this.handles.size >= MAX_HANDLES) {
             return this.refuse('join-capacity', [this.no(peer, null, 'capacity', message.q)]);
         }
+        let held = 0;
+        for (const existing of this.handles.values())
+            if (existing.peer === peer)
+                held += 1;
+        if (held >= MAX_HANDLES_PER_PEER) {
+            return this.refuse('join-capacity', [this.no(peer, null, 'capacity', message.q)]);
+        }
         // `authorize` receives the AUTHENTICATED peer and the audience it
         // asked to read. A refusal is `forbidden` and allocates nothing.
-        if (!this.permitsRead(peer, message.aud)) {
+        if (!this.permitsRead(peer, message.aud, message.key)) {
             return this.refuse('join-forbidden', [this.no(peer, null, 'forbidden', message.q)]);
         }
         const h = this.newHandle();
@@ -1166,6 +1182,7 @@ export class StoreOwner {
             inc: this.incarnation,
             peer,
             audience: [...message.aud],
+            key: message.key,
             interest: message.int === undefined ? null : [...message.int],
             generation: 0,
             revision: this.core.revision,
@@ -1233,8 +1250,11 @@ export class StoreOwner {
      *
      * A throwing policy is a refusal, never an admission.
      */
-    permitsRead(peer, audience) {
-        const request = { type: 'read', peer, audience: [...audience] };
+    permitsRead(peer, audience, key) {
+        // `key` is the join's opaque key, which `joinStore({ key })` documents
+        // as read by the host's policy; it was dropped here, so a key-gated
+        // room refused everyone (SDK audit 2026-10-11).
+        const request = (key === undefined ? { type: 'read', peer, audience: [...audience] } : { type: 'read', peer, audience: [...audience], key });
         try {
             return this.deps.authorize(request) === true;
         }

package/dist/store/types.d.ts

@@ -159,6 +159,12 @@ export type AccessRequest<A extends ActionSpec, I extends InputSpec> = {
     readonly type: 'read';
     readonly peer: string;
     readonly audience: readonly string[];
+    /**
+     * The opaque key the replica joined with (`joinStore({ key })`),
+     * carried on every later read decision for that subscription.
+     * Absent for the host's own player, which joins no wire.
+     */
+    readonly key?: string;
 } | {
     [K in keyof A]: {
         readonly type: 'action';

package/dist/stream.d.ts

@@ -97,13 +97,24 @@ export interface OpenStreamOptions {
      */
     lossy?: boolean;
 }
+/** Most frames a {@link LeafStream} buffers before its first consumer. */
+export declare const LEAF_STREAM_PENDING_MAX_FRAMES = 1024;
+/** Most bytes a {@link LeafStream} buffers before its first consumer. */
+export declare const LEAF_STREAM_PENDING_MAX_BYTES: number;
 /**
  * One open stream.
  *
  * Inbound payloads are delivered to `for await` consumers and to
  * {@link LeafStream.onMessage} listeners. Payloads that arrive before
  * anyone consumes them are buffered in arrival order, so a page that
- * opens a stream and awaits it a tick later loses nothing.
+ * opens a stream and awaits it a tick later loses nothing — up to
+ * {@link LEAF_STREAM_PENDING_MAX_FRAMES} frames and
+ * {@link LEAF_STREAM_PENDING_MAX_BYTES} bytes. Past either bound the
+ * OLDEST buffered frame is dropped and counted in
+ * {@link LeafStream.droppedBeforeConsumer} (a single frame larger than the
+ * byte bound is never buffered, and is counted there too): a stream used only to send
+ * (the store, netcode and region-link layers read inbound traffic
+ * elsewhere) must not keep every frame the peer sends for its lifetime.
  */
 export declare class LeafStream implements AsyncIterable<Uint8Array> {
     private readonly inner;
@@ -111,7 +122,11 @@ export declare class LeafStream implements AsyncIterable<Uint8Array> {
     private readonly queues;
     private readonly listeners;
     private readonly pending;
+    private pendingBytes;
+    private dropped;
     private closed;
+    /** Why the SESSION closed this stream, when it did so for a leader change. */
+    private retiredBy;
     /**
      * This stream's wire id as a number, or `null` when the inner
      * object's `stream_id_hex()` was not hex.
@@ -144,6 +159,11 @@ export declare class LeafStream implements AsyncIterable<Uint8Array> {
      * either would fail the id comparison too, loudly.
      */
     private readonly peerId;
+    /**
+     * Frames dropped from the pre-consumer buffer because no `for await`
+     * consumer or `onMessage` listener was attached and it was full.
+     */
+    get droppedBeforeConsumer(): number;
     /** The authenticated peer this stream is with, 16 lowercase hex. */
     get peerNode(): string;
     /**
@@ -169,6 +189,14 @@ export declare class LeafStream implements AsyncIterable<Uint8Array> {
      * taken as an already-decoded payload, which is what a
      * host-supplied {@link LeafWasmStreamLike} may deliver.
      */
+    /**
+     * Hand the pre-consumer buffer over, emptying it — count included. The
+     * byte count stayed at the drained total, so after a consumer drained the
+     * buffer and detached, rebuffering tripped the byte cap almost at once
+     * and evicted all but the newest frame on nearly every arrival (code
+     * review 2026-10-11, BROWSER-1).
+     */
+    private drainPending;
     private receive;
     private decode;
 }