@actuallab/rpc 12.4.1 → 12.4.7

package/dist/index.d.cts

@@ -990,6 +990,118 @@ declare class RpcSystemCallHandler {
     private _handleReconnect;
 }
 
+/**
+ * Server-side RPC stream producer — sends items to a remote consumer via
+ * $sys.I / $sys.B / $sys.End system calls.
+ *
+ * Wire protocol (server perspective):
+ * - Server returns the stream reference string as $sys.Ok
+ * - Client sends Ack(0, hostId) to start the stream
+ * - Server sends I (single item) / B (batch) messages
+ * - Client acks every ackPeriod items for flow control
+ * - Server sends End to signal completion (with optional error)
+ * - Client sends AckEnd to acknowledge completion
+ *
+ * The pump is ACK-driven: the main loop blocks on `_whenAckReady` until a
+ * client ACK is queued, processes it (updating `_lastAckedIndex`, rewinding
+ * `_index` on mustReset, trimming the replay buffer), then sends items up
+ * to `ack.nextIndex + bufferSize`. While the peer is disconnected no ACKs
+ * arrive, so the source is never pulled — the sender naturally pauses
+ * instead of spinning.
+ *
+ * Direct port of .NET `RpcSharedStream<T>` at
+ * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
+ */
+declare class RpcStreamSender<T> implements IRpcObject {
+    private static readonly _emptyGuid;
+    readonly id: RpcObjectId;
+    readonly kind: 0;
+    readonly allowReconnect: boolean;
+    readonly isRealTime: boolean;
+    readonly canSkipTo: (item: T) => boolean;
+    readonly peer: RpcPeer;
+    readonly ackPeriod: number;
+    readonly bufferSize: number;
+    /**
+     * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
+     * and may honor the AbortSignal to exit gracefully. `disconnect()` first aborts
+     * the signal and gives the source up to `RpcStream.disconnectGracePeriodMs` ms
+     * before force-closing via `iterator.return()`.
+     *
+     * If false, the source is a plain AsyncIterable that cannot observe the signal,
+     * so `disconnect()` force-closes immediately.
+     */
+    readonly sourceUsesAbortSignal: boolean;
+    /** Next stream index that will be sent (matches .NET's `index`). */
+    private _nextIndex;
+    private _ended;
+    private _started;
+    /** Highest `nextIndex` observed in an ACK so far (matches .NET's `lastAckNextIndex` idiom). */
+    private _lastAckedIndex;
+    private _abortController;
+    private _iterator;
+    /** Total items skipped via real-time `canSkipTo` compaction. */
+    private _skipCount;
+    /** Fires after a $sys.Ack has been processed (post-compaction). The
+     *  recorder's quality controller uses this to bump a "last ACK at"
+     *  watchdog so it can distinguish "stuck" (no ACK > N s) from
+     *  "throttled" (ACKs flowing). */
+    onAckProcessed?: () => void;
+    get nextIndex(): number;
+    get lastAckIndex(): number;
+    get skipCount(): number;
+    private _acks;
+    private _whenAckReady;
+    constructor(peer: RpcPeer, ackPeriod?: number, bufferSize?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean);
+    /** AbortSignal that is aborted when the sender is disconnected. */
+    get abortSignal(): AbortSignal;
+    /** Returns the stream reference string for the $sys.Ok response. */
+    toRef(): string;
+    /**
+     * Called by system call handler when $sys.Ack is received from the client.
+     *
+     * Mirrors .NET `RpcSharedStream<T>.OnAck` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:68-101.
+     */
+    onAck(nextIndex: number, hostId: string): void;
+    /** Called by system call handler when $sys.AckEnd is received from the client. */
+    onAckEnd(_hostId: string): void;
+    /**
+     * Send a single item to the client at the current `_nextIndex`.
+     *
+     * Advances `_nextIndex` unconditionally — even if the peer is disconnected
+     * the item is considered "sent" from the pump's perspective so the replay
+     * buffer indexing stays consistent. If a connection is absent, the wire
+     * message is dropped; the item will be resent from the replay buffer
+     * after a reconnect (client sends `Ack(N, mustReset=true)`).
+     */
+    sendItem(item: T): void;
+    /** Send a batch of items to the client. See {@link sendItem} for disconnect semantics. */
+    sendBatch(items: T[]): void;
+    /** Signal stream completion to the client. */
+    sendEnd(error?: Error | null): void;
+    /**
+     * Consume an AsyncIterable and send all items to the client.
+     *
+     * Matches .NET `RpcSharedStream<T>.OnRun` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
+     */
+    writeFrom(source: AsyncIterable<T>): Promise<void>;
+    /**
+     * ACK-driven pump. Non-real-time streams apply normal backpressure at
+     * `bufferSize`; real-time streams may compact the already-buffered unsent
+     * suffix to the latest buffered `canSkipTo` item after the consumer ACKs.
+     */
+    private _run;
+    /** Drain all queued ACKs, returning the most recent one (or null if none). */
+    private _tryProcessAcks;
+    /** Wait for the ACK queue to have at least one entry (or `_ended`). */
+    private _waitAckReady;
+    reconnect(): void;
+    disconnect(): void;
+    private _forceCloseIterator;
+}
+
 /** Parsed stream reference from the server's result payload. */
 interface RpcStreamRef {
     readonly hostId: string;
@@ -1072,6 +1184,9 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
      * Rejects if the source throws. Throws if `toRef()` hasn't been called yet.
      */
     get whenSent(): Promise<void>;
+    /** Local sender backing this stream after `toRef()` has been called.
+     *  `undefined` for remote streams or before `toRef()`. */
+    get sender(): RpcStreamSender<T> | undefined;
     /**
      * For local streams: bind to a peer, create and register an `RpcStreamSender`,
      * start pumping items from the local source in the background, and return the
@@ -1108,108 +1223,6 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
  */
 declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
 
-/**
- * Server-side RPC stream producer — sends items to a remote consumer via
- * $sys.I / $sys.B / $sys.End system calls.
- *
- * Wire protocol (server perspective):
- * - Server returns the stream reference string as $sys.Ok
- * - Client sends Ack(0, hostId) to start the stream
- * - Server sends I (single item) / B (batch) messages
- * - Client acks every ackPeriod items for flow control
- * - Server sends End to signal completion (with optional error)
- * - Client sends AckEnd to acknowledge completion
- *
- * The pump is ACK-driven: the main loop blocks on `_whenAckReady` until a
- * client ACK is queued, processes it (updating `_lastAckedIndex`, rewinding
- * `_index` on mustReset, trimming the replay buffer), then sends items up
- * to `ack.nextIndex + bufferSize`. While the peer is disconnected no ACKs
- * arrive, so the source is never pulled — the sender naturally pauses
- * instead of spinning.
- *
- * Direct port of .NET `RpcSharedStream<T>` at
- * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
- */
-declare class RpcStreamSender<T> implements IRpcObject {
-    private static readonly _emptyGuid;
-    readonly id: RpcObjectId;
-    readonly kind: 0;
-    readonly allowReconnect: boolean;
-    readonly isRealTime: boolean;
-    readonly canSkipTo: (item: T) => boolean;
-    readonly peer: RpcPeer;
-    readonly ackPeriod: number;
-    readonly bufferSize: number;
-    /**
-     * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
-     * and may honor the AbortSignal to exit gracefully. `disconnect()` first aborts
-     * the signal and gives the source up to `RpcStream.disconnectGracePeriodMs` ms
-     * before force-closing via `iterator.return()`.
-     *
-     * If false, the source is a plain AsyncIterable that cannot observe the signal,
-     * so `disconnect()` force-closes immediately.
-     */
-    readonly sourceUsesAbortSignal: boolean;
-    /** Next stream index that will be sent (matches .NET's `index`). */
-    private _nextIndex;
-    private _ended;
-    private _started;
-    /** Highest `nextIndex` observed in an ACK so far (matches .NET's `lastAckNextIndex` idiom). */
-    private _lastAckedIndex;
-    private _abortController;
-    private _iterator;
-    private _acks;
-    private _whenAckReady;
-    constructor(peer: RpcPeer, ackPeriod?: number, bufferSize?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean);
-    /** AbortSignal that is aborted when the sender is disconnected. */
-    get abortSignal(): AbortSignal;
-    /** Returns the stream reference string for the $sys.Ok response. */
-    toRef(): string;
-    /**
-     * Called by system call handler when $sys.Ack is received from the client.
-     *
-     * Mirrors .NET `RpcSharedStream<T>.OnAck` at
-     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:68-101.
-     */
-    onAck(nextIndex: number, hostId: string): void;
-    /** Called by system call handler when $sys.AckEnd is received from the client. */
-    onAckEnd(_hostId: string): void;
-    /**
-     * Send a single item to the client at the current `_nextIndex`.
-     *
-     * Advances `_nextIndex` unconditionally — even if the peer is disconnected
-     * the item is considered "sent" from the pump's perspective so the replay
-     * buffer indexing stays consistent. If a connection is absent, the wire
-     * message is dropped; the item will be resent from the replay buffer
-     * after a reconnect (client sends `Ack(N, mustReset=true)`).
-     */
-    sendItem(item: T): void;
-    /** Send a batch of items to the client. See {@link sendItem} for disconnect semantics. */
-    sendBatch(items: T[]): void;
-    /** Signal stream completion to the client. */
-    sendEnd(error?: Error | null): void;
-    /**
-     * Consume an AsyncIterable and send all items to the client.
-     *
-     * Matches .NET `RpcSharedStream<T>.OnRun` at
-     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
-     */
-    writeFrom(source: AsyncIterable<T>): Promise<void>;
-    /**
-     * ACK-driven pump. Non-real-time streams apply normal backpressure at
-     * `bufferSize`; real-time streams may compact the already-buffered unsent
-     * suffix to the latest buffered `canSkipTo` item after the consumer ACKs.
-     */
-    private _run;
-    /** Drain all queued ACKs, returning the most recent one (or null if none). */
-    private _tryProcessAcks;
-    /** Wait for the ACK queue to have at least one entry (or `_ended`). */
-    private _waitAckReady;
-    reconnect(): void;
-    disconnect(): void;
-    private _forceCloseIterator;
-}
-
 declare class RpcPeerRefBuilder {
     /** Build a client peer ref from a WebSocket URL, optionally baking in the
      *  serialization format as a `f=` query parameter.

package/dist/index.d.ts

@@ -990,6 +990,118 @@ declare class RpcSystemCallHandler {
     private _handleReconnect;
 }
 
+/**
+ * Server-side RPC stream producer — sends items to a remote consumer via
+ * $sys.I / $sys.B / $sys.End system calls.
+ *
+ * Wire protocol (server perspective):
+ * - Server returns the stream reference string as $sys.Ok
+ * - Client sends Ack(0, hostId) to start the stream
+ * - Server sends I (single item) / B (batch) messages
+ * - Client acks every ackPeriod items for flow control
+ * - Server sends End to signal completion (with optional error)
+ * - Client sends AckEnd to acknowledge completion
+ *
+ * The pump is ACK-driven: the main loop blocks on `_whenAckReady` until a
+ * client ACK is queued, processes it (updating `_lastAckedIndex`, rewinding
+ * `_index` on mustReset, trimming the replay buffer), then sends items up
+ * to `ack.nextIndex + bufferSize`. While the peer is disconnected no ACKs
+ * arrive, so the source is never pulled — the sender naturally pauses
+ * instead of spinning.
+ *
+ * Direct port of .NET `RpcSharedStream<T>` at
+ * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
+ */
+declare class RpcStreamSender<T> implements IRpcObject {
+    private static readonly _emptyGuid;
+    readonly id: RpcObjectId;
+    readonly kind: 0;
+    readonly allowReconnect: boolean;
+    readonly isRealTime: boolean;
+    readonly canSkipTo: (item: T) => boolean;
+    readonly peer: RpcPeer;
+    readonly ackPeriod: number;
+    readonly bufferSize: number;
+    /**
+     * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
+     * and may honor the AbortSignal to exit gracefully. `disconnect()` first aborts
+     * the signal and gives the source up to `RpcStream.disconnectGracePeriodMs` ms
+     * before force-closing via `iterator.return()`.
+     *
+     * If false, the source is a plain AsyncIterable that cannot observe the signal,
+     * so `disconnect()` force-closes immediately.
+     */
+    readonly sourceUsesAbortSignal: boolean;
+    /** Next stream index that will be sent (matches .NET's `index`). */
+    private _nextIndex;
+    private _ended;
+    private _started;
+    /** Highest `nextIndex` observed in an ACK so far (matches .NET's `lastAckNextIndex` idiom). */
+    private _lastAckedIndex;
+    private _abortController;
+    private _iterator;
+    /** Total items skipped via real-time `canSkipTo` compaction. */
+    private _skipCount;
+    /** Fires after a $sys.Ack has been processed (post-compaction). The
+     *  recorder's quality controller uses this to bump a "last ACK at"
+     *  watchdog so it can distinguish "stuck" (no ACK > N s) from
+     *  "throttled" (ACKs flowing). */
+    onAckProcessed?: () => void;
+    get nextIndex(): number;
+    get lastAckIndex(): number;
+    get skipCount(): number;
+    private _acks;
+    private _whenAckReady;
+    constructor(peer: RpcPeer, ackPeriod?: number, bufferSize?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean);
+    /** AbortSignal that is aborted when the sender is disconnected. */
+    get abortSignal(): AbortSignal;
+    /** Returns the stream reference string for the $sys.Ok response. */
+    toRef(): string;
+    /**
+     * Called by system call handler when $sys.Ack is received from the client.
+     *
+     * Mirrors .NET `RpcSharedStream<T>.OnAck` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:68-101.
+     */
+    onAck(nextIndex: number, hostId: string): void;
+    /** Called by system call handler when $sys.AckEnd is received from the client. */
+    onAckEnd(_hostId: string): void;
+    /**
+     * Send a single item to the client at the current `_nextIndex`.
+     *
+     * Advances `_nextIndex` unconditionally — even if the peer is disconnected
+     * the item is considered "sent" from the pump's perspective so the replay
+     * buffer indexing stays consistent. If a connection is absent, the wire
+     * message is dropped; the item will be resent from the replay buffer
+     * after a reconnect (client sends `Ack(N, mustReset=true)`).
+     */
+    sendItem(item: T): void;
+    /** Send a batch of items to the client. See {@link sendItem} for disconnect semantics. */
+    sendBatch(items: T[]): void;
+    /** Signal stream completion to the client. */
+    sendEnd(error?: Error | null): void;
+    /**
+     * Consume an AsyncIterable and send all items to the client.
+     *
+     * Matches .NET `RpcSharedStream<T>.OnRun` at
+     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
+     */
+    writeFrom(source: AsyncIterable<T>): Promise<void>;
+    /**
+     * ACK-driven pump. Non-real-time streams apply normal backpressure at
+     * `bufferSize`; real-time streams may compact the already-buffered unsent
+     * suffix to the latest buffered `canSkipTo` item after the consumer ACKs.
+     */
+    private _run;
+    /** Drain all queued ACKs, returning the most recent one (or null if none). */
+    private _tryProcessAcks;
+    /** Wait for the ACK queue to have at least one entry (or `_ended`). */
+    private _waitAckReady;
+    reconnect(): void;
+    disconnect(): void;
+    private _forceCloseIterator;
+}
+
 /** Parsed stream reference from the server's result payload. */
 interface RpcStreamRef {
     readonly hostId: string;
@@ -1072,6 +1184,9 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
      * Rejects if the source throws. Throws if `toRef()` hasn't been called yet.
      */
     get whenSent(): Promise<void>;
+    /** Local sender backing this stream after `toRef()` has been called.
+     *  `undefined` for remote streams or before `toRef()`. */
+    get sender(): RpcStreamSender<T> | undefined;
     /**
      * For local streams: bind to a peer, create and register an `RpcStreamSender`,
      * start pumping items from the local source in the background, and return the
@@ -1108,108 +1223,6 @@ declare class RpcStream<T> implements AsyncIterable<T>, IRpcObject {
  */
 declare function resolveStreamRefs(value: unknown, peer: RpcPeer): unknown;
 
-/**
- * Server-side RPC stream producer — sends items to a remote consumer via
- * $sys.I / $sys.B / $sys.End system calls.
- *
- * Wire protocol (server perspective):
- * - Server returns the stream reference string as $sys.Ok
- * - Client sends Ack(0, hostId) to start the stream
- * - Server sends I (single item) / B (batch) messages
- * - Client acks every ackPeriod items for flow control
- * - Server sends End to signal completion (with optional error)
- * - Client sends AckEnd to acknowledge completion
- *
- * The pump is ACK-driven: the main loop blocks on `_whenAckReady` until a
- * client ACK is queued, processes it (updating `_lastAckedIndex`, rewinding
- * `_index` on mustReset, trimming the replay buffer), then sends items up
- * to `ack.nextIndex + bufferSize`. While the peer is disconnected no ACKs
- * arrive, so the source is never pulled — the sender naturally pauses
- * instead of spinning.
- *
- * Direct port of .NET `RpcSharedStream<T>` at
- * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
- */
-declare class RpcStreamSender<T> implements IRpcObject {
-    private static readonly _emptyGuid;
-    readonly id: RpcObjectId;
-    readonly kind: 0;
-    readonly allowReconnect: boolean;
-    readonly isRealTime: boolean;
-    readonly canSkipTo: (item: T) => boolean;
-    readonly peer: RpcPeer;
-    readonly ackPeriod: number;
-    readonly bufferSize: number;
-    /**
-     * If true, the source was produced by a factory `(abortSignal) => AsyncIterable<T>`
-     * and may honor the AbortSignal to exit gracefully. `disconnect()` first aborts
-     * the signal and gives the source up to `RpcStream.disconnectGracePeriodMs` ms
-     * before force-closing via `iterator.return()`.
-     *
-     * If false, the source is a plain AsyncIterable that cannot observe the signal,
-     * so `disconnect()` force-closes immediately.
-     */
-    readonly sourceUsesAbortSignal: boolean;
-    /** Next stream index that will be sent (matches .NET's `index`). */
-    private _nextIndex;
-    private _ended;
-    private _started;
-    /** Highest `nextIndex` observed in an ACK so far (matches .NET's `lastAckNextIndex` idiom). */
-    private _lastAckedIndex;
-    private _abortController;
-    private _iterator;
-    private _acks;
-    private _whenAckReady;
-    constructor(peer: RpcPeer, ackPeriod?: number, bufferSize?: number, allowReconnect?: boolean, isRealTime?: boolean, canSkipTo?: (item: T) => boolean, sourceUsesAbortSignal?: boolean);
-    /** AbortSignal that is aborted when the sender is disconnected. */
-    get abortSignal(): AbortSignal;
-    /** Returns the stream reference string for the $sys.Ok response. */
-    toRef(): string;
-    /**
-     * Called by system call handler when $sys.Ack is received from the client.
-     *
-     * Mirrors .NET `RpcSharedStream<T>.OnAck` at
-     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs:68-101.
-     */
-    onAck(nextIndex: number, hostId: string): void;
-    /** Called by system call handler when $sys.AckEnd is received from the client. */
-    onAckEnd(_hostId: string): void;
-    /**
-     * Send a single item to the client at the current `_nextIndex`.
-     *
-     * Advances `_nextIndex` unconditionally — even if the peer is disconnected
-     * the item is considered "sent" from the pump's perspective so the replay
-     * buffer indexing stays consistent. If a connection is absent, the wire
-     * message is dropped; the item will be resent from the replay buffer
-     * after a reconnect (client sends `Ack(N, mustReset=true)`).
-     */
-    sendItem(item: T): void;
-    /** Send a batch of items to the client. See {@link sendItem} for disconnect semantics. */
-    sendBatch(items: T[]): void;
-    /** Signal stream completion to the client. */
-    sendEnd(error?: Error | null): void;
-    /**
-     * Consume an AsyncIterable and send all items to the client.
-     *
-     * Matches .NET `RpcSharedStream<T>.OnRun` at
-     * src/ActualLab.Rpc/Infrastructure/RpcSharedStream.cs.
-     */
-    writeFrom(source: AsyncIterable<T>): Promise<void>;
-    /**
-     * ACK-driven pump. Non-real-time streams apply normal backpressure at
-     * `bufferSize`; real-time streams may compact the already-buffered unsent
-     * suffix to the latest buffered `canSkipTo` item after the consumer ACKs.
-     */
-    private _run;
-    /** Drain all queued ACKs, returning the most recent one (or null if none). */
-    private _tryProcessAcks;
-    /** Wait for the ACK queue to have at least one entry (or `_ended`). */
-    private _waitAckReady;
-    reconnect(): void;
-    disconnect(): void;
-    private _forceCloseIterator;
-}
-
 declare class RpcPeerRefBuilder {
     /** Build a client peer ref from a WebSocket URL, optionally baking in the
      *  serialization format as a `f=` query parameter.

package/dist/index.js

@@ -900,6 +900,23 @@ var RpcStreamSender = class _RpcStreamSender {
   _lastAckedIndex = 0;
   _abortController = new AbortController();
   _iterator = null;
+  // -- Recorder-controller metrics (Step 9.1) --
+  /** Total items skipped via real-time `canSkipTo` compaction. */
+  _skipCount = 0;
+  /** Fires after a $sys.Ack has been processed (post-compaction). The
+   *  recorder's quality controller uses this to bump a "last ACK at"
+   *  watchdog so it can distinguish "stuck" (no ACK > N s) from
+   *  "throttled" (ACKs flowing). */
+  onAckProcessed;
+  get nextIndex() {
+    return this._nextIndex;
+  }
+  get lastAckIndex() {
+    return this._lastAckedIndex;
+  }
+  get skipCount() {
+    return this._skipCount;
+  }
   // -- ACK queue (analog of .NET's Channel<(long, bool)>) --
   _acks = [];
   _whenAckReady = null;
@@ -1134,8 +1151,16 @@ var RpcStreamSender = class _RpcStreamSender {
           if (bufferIndex >= buffer.count && !isFullyBuffered && buffer.hasRemainingCapacity && this._acks.length === 0) {
             await bufferNext(false, true);
           }
-          if (ack.nextIndex > 0)
-            bufferIndex = _compactBufferedUnsentSuffix(buffer, bufferIndex, this.canSkipTo);
+          if (ack.nextIndex > 0) {
+            const result = _compactBufferedUnsentSuffix(
+              buffer,
+              bufferIndex,
+              this.canSkipTo
+            );
+            bufferIndex = result.newIndex;
+            if (result.skipped > 0)
+              this._skipCount += result.skipped;
+          }
           if (this._acks.length > 0) break;
         }
         while (this._nextIndex < maxIndex && bufferIndex < buffer.count) {
@@ -1171,6 +1196,10 @@ var RpcStreamSender = class _RpcStreamSender {
         this._nextIndex = a.nextIndex;
       }
     }
+    try {
+      this.onAckProcessed?.();
+    } catch {
+    }
     return last;
   }
   /** Wait for the ACK queue to have at least one entry (or `_ended`). */
@@ -1230,14 +1259,16 @@ function _compactBufferedUnsentSuffix(buffer, firstUnsentIndex, canSkipTo) {
       skipToIndex = i;
   }
   if (skipToIndex <= firstUnsentIndex)
-    return firstUnsentIndex;
+    return { newIndex: firstUnsentIndex, skipped: 0 };
+  const cutFrom = firstUnsentIndex;
+  const cutTo = skipToIndex;
   const items = buffer.toArray();
   buffer.clear();
-  for (let i = 0; i < firstUnsentIndex; i++)
+  for (let i = 0; i < cutFrom; i++)
     buffer.pushTail(items[i]);
-  for (let i = skipToIndex; i < items.length; i++)
+  for (let i = cutTo; i < items.length; i++)
     buffer.pushTail(items[i]);
-  return firstUnsentIndex;
+  return { newIndex: firstUnsentIndex, skipped: skipToIndex - firstUnsentIndex };
 }
 
 // src/rpc-stream.ts
@@ -1343,6 +1374,11 @@ var RpcStream = class _RpcStream {
       throw new Error("toRef() must be called before awaiting whenSent.");
     return this._whenSent;
   }
+  /** Local sender backing this stream after `toRef()` has been called.
+   *  `undefined` for remote streams or before `toRef()`. */
+  get sender() {
+    return this._sender;
+  }
   /**
    * For local streams: bind to a peer, create and register an `RpcStreamSender`,
    * start pumping items from the local source in the background, and return the