request-iframe 0.1.0 → 0.2.0

package/library/stream/readable-stream.js

@@ -17,9 +17,10 @@ require("core-js/modules/es.promise.finally.js");
 require("core-js/modules/web.dom-collections.iterator.js");
 var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
-var _utils = require("../utils");
+var _protocol = require("../utils/protocol");
 var _constants = require("../constants");
 var _streamCore = require("./stream-core");
+var _error = require("./error");
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { (0, _defineProperty2.default)(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 /**
@@ -49,9 +50,18 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
     this.messageHandler.registerStreamHandler(streamId, this.handleStreamMessage.bind(this));
     // Initial pull to start the stream (pull protocol)
     this.requestMore(1);
+
+    // Observable: constructed and ready to receive data
+    this.emit(_constants.StreamEvent.START, {
+      streamId: this.streamId,
+      type: this.type,
+      chunked: this.chunked,
+      mode: this.mode,
+      metadata: this.metadata
+    });
   }
   postControl(type, body) {
-    var message = (0, _utils.createPostMessage)(type, this.requestId, {
+    var message = (0, _protocol.createPostMessage)(type, this.requestId, {
       secretKey: this.secretKey,
       body: _objectSpread({
         streamId: this.streamId
@@ -66,6 +76,9 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
       this.postControl(_constants.MessageType.STREAM_PULL, {
         credit
       });
+      this.emit(_constants.StreamEvent.PULL, {
+        credit
+      });
     } catch (_unused) {
       /** ignore */
     }
@@ -102,13 +115,17 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
         this.handleEnd();
         break;
       case _constants.StreamInternalMessageType.ERROR:
-        this.handleError(new Error(data.error || _constants.Messages.STREAM_ERROR));
+        this.handleError(new _error.RequestIframeStreamError({
+          message: data.error || _constants.Messages.STREAM_ERROR,
+          code: _constants.ErrorCode.STREAM_ERROR,
+          streamId: this.streamId,
+          requestId: this.requestId
+        }));
         break;
       case _constants.StreamInternalMessageType.CANCEL:
         this.handleCancel(data.reason);
         break;
       case _constants.StreamInternalMessageType.PULL:
-      case _constants.StreamInternalMessageType.ACK:
         // Control messages for writer side; ignore in readable stream
         break;
     }
@@ -122,17 +139,14 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
     this._state = _constants.StreamState.STREAMING;
     var decoded = this.decodeData(data);
     this.chunks.push(decoded);
-
-    // Ack this chunk (if seq provided)
-    if (typeof seq === 'number' && seq >= 0) {
-      try {
-        this.postControl(_constants.MessageType.STREAM_ACK, {
-          seq
-        });
-      } catch (_unused2) {
-        /** ignore */
-      }
-    }
+    this.emit(_constants.StreamEvent.DATA, {
+      chunk: decoded,
+      done,
+      seq
+    });
+    this.emit(_constants.StreamEvent.STATE, {
+      state: this._state
+    });
     this.notifyWaiters();
     this.schedulePullIfNeeded();
     if (done) {
@@ -157,6 +171,7 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
     this.messageHandler.unregisterStreamHandler(this.streamId);
     this.notifyWaiters();
     (_this$onEndCallback = this.onEndCallback) === null || _this$onEndCallback === void 0 || _this$onEndCallback.call(this);
+    this.clearAllListeners();
   }
 
   /**
@@ -183,6 +198,7 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
     this.messageHandler.unregisterStreamHandler(this.streamId);
     this.notifyWaiters();
     (_this$onErrorCallback = this.onErrorCallback) === null || _this$onErrorCallback === void 0 || _this$onErrorCallback.call(this, error);
+    this.clearAllListeners();
   }
 
   /**
@@ -201,10 +217,14 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
     if (this._state === _constants.StreamState.ENDED || this._state === _constants.StreamState.ERROR || this._state === _constants.StreamState.CANCELLED) return;
     super.cancel((0, _constants.formatMessage)(_constants.Messages.STREAM_CANCELLED, reason || ''));
     this.notifyWaiters();
+    this.emit(_constants.StreamEvent.CANCEL, {
+      reason,
+      remote: notifyRemote
+    });
     if (notifyRemote) {
       try {
         /** Notify server to cancel */
-        var _message = (0, _utils.createPostMessage)(_constants.MessageType.STREAM_CANCEL, this.requestId, {
+        var _message = (0, _protocol.createPostMessage)(_constants.MessageType.STREAM_CANCEL, this.requestId, {
           secretKey: this.secretKey,
           body: {
             streamId: this.streamId,
@@ -212,7 +232,7 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
           }
         });
         this.messageHandler.postMessage(_message);
-      } catch (_unused3) {
+      } catch (_unused2) {
         /** ignore send failures on cancel/abort */
       }
     }
@@ -222,8 +242,14 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
       (_this$onErrorCallback2 = this.onErrorCallback) === null || _this$onErrorCallback2 === void 0 || _this$onErrorCallback2.call(this, this.terminalError);
     } else {
       var _this$onErrorCallback3;
-      (_this$onErrorCallback3 = this.onErrorCallback) === null || _this$onErrorCallback3 === void 0 || _this$onErrorCallback3.call(this, new Error(_constants.Messages.STREAM_CANCELLED));
+      (_this$onErrorCallback3 = this.onErrorCallback) === null || _this$onErrorCallback3 === void 0 || _this$onErrorCallback3.call(this, new _error.RequestIframeStreamError({
+        message: _constants.Messages.STREAM_CANCELLED,
+        code: _constants.ErrorCode.STREAM_CANCELLED,
+        streamId: this.streamId,
+        requestId: this.requestId
+      }));
     }
+    this.clearAllListeners();
   }
   performHeartbeat() {
     var _this = this;
@@ -309,7 +335,15 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
             return _context2.abrupt("return");
           case 8:
             // Connection likely dead: fail the stream
-            _this2.handleError(new Error((0, _constants.formatMessage)(_constants.Messages.STREAM_TIMEOUT, _this2.idleTimeout)));
+            _this2.emit(_constants.StreamEvent.TIMEOUT, {
+              timeout: _this2.idleTimeout
+            });
+            _this2.handleError(new _error.RequestIframeStreamError({
+              message: (0, _constants.formatMessage)(_constants.Messages.STREAM_TIMEOUT, _this2.idleTimeout),
+              code: _constants.ErrorCode.STREAM_TIMEOUT,
+              streamId: _this2.streamId,
+              requestId: _this2.requestId
+            }));
           case 9:
           case "end":
             return _context2.stop();
@@ -324,6 +358,7 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
   read() {
     var _this3 = this;
     return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee3() {
+      var merged, _merged;
       return _regenerator.default.wrap(function (_context3) {
         while (1) switch (_context3.prev = _context3.next) {
           case 0:
@@ -331,13 +366,22 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
               _context3.next = 1;
               break;
             }
-            return _context3.abrupt("return", _this3.mergeChunks());
+            merged = _this3.mergeChunks();
+            _this3.emit(_constants.StreamEvent.READ, {
+              value: merged
+            });
+            return _context3.abrupt("return", merged);
           case 1:
             if (!(_this3._state === _constants.StreamState.ERROR || _this3._state === _constants.StreamState.CANCELLED)) {
               _context3.next = 2;
               break;
             }
-            throw _this3.terminalError || new Error(_constants.Messages.STREAM_READ_ERROR);
+            throw _this3.terminalError || new _error.RequestIframeStreamError({
+              message: _constants.Messages.STREAM_READ_ERROR,
+              code: _constants.ErrorCode.STREAM_READ_ERROR,
+              streamId: _this3.streamId,
+              requestId: _this3.requestId
+            });
           case 2:
             if (!(_this3._state === _constants.StreamState.PENDING || _this3._state === _constants.StreamState.STREAMING)) {
               _context3.next = 4;
@@ -356,9 +400,18 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
               _context3.next = 5;
               break;
             }
-            return _context3.abrupt("return", _this3.mergeChunks());
+            _merged = _this3.mergeChunks();
+            _this3.emit(_constants.StreamEvent.READ, {
+              value: _merged
+            });
+            return _context3.abrupt("return", _merged);
           case 5:
-            throw _this3.terminalError || new Error(_constants.Messages.STREAM_READ_ERROR);
+            throw _this3.terminalError || new _error.RequestIframeStreamError({
+              message: _constants.Messages.STREAM_READ_ERROR,
+              code: _constants.ErrorCode.STREAM_READ_ERROR,
+              streamId: _this3.streamId,
+              requestId: _this3.requestId
+            });
           case 6:
           case "end":
             return _context3.stop();
@@ -373,6 +426,7 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
   readAll() {
     var _this4 = this;
     return (0, _asyncToGenerator2.default)(/*#__PURE__*/_regenerator.default.mark(function _callee4() {
+      var list, _list;
       return _regenerator.default.wrap(function (_context4) {
         while (1) switch (_context4.prev = _context4.next) {
           case 0:
@@ -380,13 +434,22 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
               _context4.next = 1;
               break;
             }
-            return _context4.abrupt("return", _this4.chunks.slice());
+            list = _this4.chunks.slice();
+            _this4.emit(_constants.StreamEvent.READ, {
+              value: list
+            });
+            return _context4.abrupt("return", list);
           case 1:
             if (!(_this4._state === _constants.StreamState.ERROR || _this4._state === _constants.StreamState.CANCELLED)) {
               _context4.next = 2;
               break;
             }
-            throw _this4.terminalError || new Error(_constants.Messages.STREAM_READ_ERROR);
+            throw _this4.terminalError || new _error.RequestIframeStreamError({
+              message: _constants.Messages.STREAM_READ_ERROR,
+              code: _constants.ErrorCode.STREAM_READ_ERROR,
+              streamId: _this4.streamId,
+              requestId: _this4.requestId
+            });
           case 2:
             if (!(_this4._state === _constants.StreamState.PENDING || _this4._state === _constants.StreamState.STREAMING)) {
               _context4.next = 4;
@@ -403,9 +466,18 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
               _context4.next = 5;
               break;
             }
-            return _context4.abrupt("return", _this4.chunks.slice());
+            _list = _this4.chunks.slice();
+            _this4.emit(_constants.StreamEvent.READ, {
+              value: _list
+            });
+            return _context4.abrupt("return", _list);
           case 5:
-            throw _this4.terminalError || new Error(_constants.Messages.STREAM_READ_ERROR);
+            throw _this4.terminalError || new _error.RequestIframeStreamError({
+              message: _constants.Messages.STREAM_READ_ERROR,
+              code: _constants.ErrorCode.STREAM_READ_ERROR,
+              streamId: _this4.streamId,
+              requestId: _this4.requestId
+            });
           case 6:
           case "end":
             return _context4.stop();
@@ -449,6 +521,9 @@ class IframeReadableStream extends _streamCore.IframeStreamCore {
                 break;
               case 3:
                 value = stream.chunks[index++];
+                stream.emit(_constants.StreamEvent.READ, {
+                  value
+                });
                 if (stream.consume) {
                   /**
                    * Drop already-consumed chunks to reduce memory usage.

package/library/stream/stream-core.d.ts

@@ -1,4 +1,4 @@
-import type { StreamState, StreamType, StreamMessageData, WritableStreamMode } from './types';
+import type { StreamState, StreamType, StreamMessageData, WritableStreamMode, StreamEventName, StreamEventListener } from './types';
 /**
  * Shared stream core (internal).
  *
@@ -20,8 +20,29 @@ export declare class IframeStreamCore<T = any> {
     protected chunks: T[];
     protected waiters: Array<() => void>;
     protected consume: boolean;
+    private listeners;
     constructor(streamId: string, type: StreamType, chunked: boolean, metadata: Record<string, any> | undefined, consume: boolean, mode?: WritableStreamMode);
     get state(): StreamState;
+    /**
+     * Subscribe to stream events.
+     *
+     * This is designed for observability (debugging / metrics / UI progress),
+     * and should not be used to drive protocol-critical logic.
+     *
+     * Returns an unsubscribe function.
+     */
+    on<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): () => void;
+    on(event: string, listener: (payload: any) => void): () => void;
+    once<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): () => void;
+    once(event: string, listener: (payload: any) => void): () => void;
+    /**
+     * Unsubscribe from stream events.
+     */
+    off<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): void;
+    off(event: string, listener: (payload: any) => void): void;
+    protected emit(event: string, payload?: any): void;
+    protected clearAllListeners(): void;
+    private safeCall;
     protected notifyWaiters(): void;
     protected waitForChange(): Promise<void>;
     protected fail(error: Error): void;

package/library/stream/stream-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-core.d.ts","sourceRoot":"","sources":["../../src/stream/stream-core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAG9F;;;;;;;;;GASG;AACH,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,IAAI,EAAE,UAAU,CAAC;IACjC,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/C,SAAgB,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAE1C,SAAS,CAAC,MAAM,EAAE,WAAW,CAA+B;IAC5D,SAAS,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC;IAEhC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAM;IAC3B,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAM;IAE1C,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC;gBAGzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EACzC,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,kBAAkB;IAU3B,IAAW,KAAK,IAAI,WAAW,CAE9B;IAED,SAAS,CAAC,aAAa,IAAI,IAAI;IAa/B,SAAS,CAAC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAaxC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAOlC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAWvC;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAOnC;;OAEG;IACH,SAAS,CAAC,GAAG,IAAI,IAAI;IAMrB;;;;OAIG;IACI,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;CAG5D"}
+{"version":3,"file":"stream-core.d.ts","sourceRoot":"","sources":["../../src/stream/stream-core.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;GASG;AACH,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG;IACnC,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,IAAI,EAAE,UAAU,CAAC;IACjC,SAAgB,OAAO,EAAE,OAAO,CAAC;IACjC,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/C,SAAgB,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAE1C,SAAS,CAAC,MAAM,EAAE,WAAW,CAA+B;IAC5D,SAAS,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC;IAEhC,SAAS,CAAC,MAAM,EAAE,CAAC,EAAE,CAAM;IAC3B,SAAS,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAM;IAE1C,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC;IAE3B,OAAO,CAAC,SAAS,CAAoD;gBAGnE,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,EACzC,OAAO,EAAE,OAAO,EAChB,IAAI,CAAC,EAAE,kBAAkB;IAU3B,IAAW,KAAK,IAAI,WAAW,CAE9B;IAED;;;;;;;OAOG;IACI,EAAE,CAAC,CAAC,SAAS,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IACrF,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI;IAmB/D,IAAI,CAAC,CAAC,SAAS,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IACvF,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM,IAAI;IAuBxE;;OAEG;IACI,GAAG,CAAC,CAAC,SAAS,eAAe,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI;IAChF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,IAAI,GAAG,IAAI;IAUjE,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI;IAQlD,SAAS,CAAC,iBAAiB,IAAI,IAAI;IAInC,OAAO,CAAC,QAAQ;IAQhB,SAAS,CAAC,aAAa,IAAI,IAAI;IAa/B,SAAS,CAAC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAaxC,SAAS,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IASlC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAiBvC;;OAEG;IACH,SAAS,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IASnC;;OAEG;IACH,SAAS,CAAC,GAAG,IAAI,IAAI;IAQrB;;;;OAIG;IACI,oBAAoB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI;CAG5D"}

package/library/stream/stream-core.js

@@ -5,10 +5,16 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.IframeStreamCore = void 0;
+require("core-js/modules/es.array.from.js");
+require("core-js/modules/es.array.iterator.js");
+require("core-js/modules/es.map.js");
 require("core-js/modules/es.promise.js");
+require("core-js/modules/es.set.js");
 require("core-js/modules/web.dom-collections.for-each.js");
+require("core-js/modules/web.dom-collections.iterator.js");
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _constants = require("../constants");
+var _error = require("./error");
 /**
  * Shared stream core (internal).
  *
@@ -24,6 +30,7 @@ class IframeStreamCore {
     (0, _defineProperty2.default)(this, "_state", _constants.StreamState.PENDING);
     (0, _defineProperty2.default)(this, "chunks", []);
     (0, _defineProperty2.default)(this, "waiters", []);
+    (0, _defineProperty2.default)(this, "listeners", new Map());
     this.streamId = streamId;
     this.type = type;
     this.chunked = chunked;
@@ -34,6 +41,90 @@ class IframeStreamCore {
   get state() {
     return this._state;
   }
+
+  /**
+   * Subscribe to stream events.
+   *
+   * This is designed for observability (debugging / metrics / UI progress),
+   * and should not be used to drive protocol-critical logic.
+   *
+   * Returns an unsubscribe function.
+   */
+
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event).add(listener);
+
+    // Terminal events: if already reached, fire once immediately for convenience.
+    if (event === _constants.StreamEvent.END && this._state === _constants.StreamState.ENDED) {
+      this.safeCall(listener);
+    } else if (event === _constants.StreamEvent.ERROR && this._state === _constants.StreamState.ERROR) {
+      this.safeCall(listener, {
+        error: this.terminalError
+      });
+    } else if (event === _constants.StreamEvent.CANCEL && this._state === _constants.StreamState.CANCELLED) {
+      this.safeCall(listener, {
+        error: this.terminalError
+      });
+    }
+    return () => this.off(event, listener);
+  }
+  once(event, listener) {
+    // If already terminal, behave like a synchronous one-shot.
+    if (event === _constants.StreamEvent.END && this._state === _constants.StreamState.ENDED) {
+      this.safeCall(listener);
+      return () => {};
+    }
+    if (event === _constants.StreamEvent.ERROR && this._state === _constants.StreamState.ERROR) {
+      this.safeCall(listener, {
+        error: this.terminalError
+      });
+      return () => {};
+    }
+    if (event === _constants.StreamEvent.CANCEL && this._state === _constants.StreamState.CANCELLED) {
+      this.safeCall(listener, {
+        error: this.terminalError
+      });
+      return () => {};
+    }
+    var wrapped = payload => {
+      this.off(event, wrapped);
+      this.safeCall(listener, payload);
+    };
+    return this.on(event, wrapped);
+  }
+
+  /**
+   * Unsubscribe from stream events.
+   */
+
+  off(event, listener) {
+    var set = this.listeners.get(event);
+    if (!set) return;
+    set.delete(listener);
+    if (set.size === 0) {
+      this.listeners.delete(event);
+    }
+  }
+  emit(event, payload) {
+    var set = this.listeners.get(event);
+    if (!set || set.size === 0) return;
+    // Snapshot to avoid issues if listeners mutate subscriptions.
+    var list = Array.from(set);
+    list.forEach(fn => this.safeCall(fn, payload));
+  }
+  clearAllListeners() {
+    this.listeners.clear();
+  }
+  safeCall(fn, payload) {
+    try {
+      fn(payload);
+    } catch (_unused) {
+      /** ignore user listener errors */
+    }
+  }
   notifyWaiters() {
     if (this.waiters.length === 0) return;
     var list = this.waiters;
@@ -41,7 +132,7 @@ class IframeStreamCore {
     list.forEach(fn => {
       try {
         fn();
-      } catch (_unused) {
+      } catch (_unused2) {
         /** ignore */
       }
     });
@@ -58,12 +149,29 @@ class IframeStreamCore {
     if (this._state === _constants.StreamState.ENDED || this._state === _constants.StreamState.ERROR) return;
     this._state = _constants.StreamState.ERROR;
     this.terminalError = error;
+    this.emit(_constants.StreamEvent.ERROR, {
+      error
+    });
+    this.emit(_constants.StreamEvent.STATE, {
+      state: this._state
+    });
     this.notifyWaiters();
   }
   cancel(reason) {
     if (this._state === _constants.StreamState.ENDED || this._state === _constants.StreamState.ERROR || this._state === _constants.StreamState.CANCELLED) return;
     this._state = _constants.StreamState.CANCELLED;
-    this.terminalError = new Error(reason || _constants.Messages.STREAM_CANCELLED);
+    this.terminalError = new _error.RequestIframeStreamError({
+      message: reason || _constants.Messages.STREAM_CANCELLED,
+      code: _constants.ErrorCode.STREAM_CANCELLED,
+      streamId: this.streamId
+    });
+    this.emit(_constants.StreamEvent.CANCEL, {
+      reason,
+      error: this.terminalError
+    });
+    this.emit(_constants.StreamEvent.STATE, {
+      state: this._state
+    });
     this.notifyWaiters();
   }
 
@@ -74,6 +182,12 @@ class IframeStreamCore {
     if (this._state !== _constants.StreamState.PENDING && this._state !== _constants.StreamState.STREAMING) return;
     this._state = _constants.StreamState.STREAMING;
     this.chunks.push(chunk);
+    this.emit(_constants.StreamEvent.DATA, {
+      chunk
+    });
+    this.emit(_constants.StreamEvent.STATE, {
+      state: this._state
+    });
     this.notifyWaiters();
   }
 
@@ -83,6 +197,10 @@ class IframeStreamCore {
   end() {
     if (this._state === _constants.StreamState.ENDED) return;
     this._state = _constants.StreamState.ENDED;
+    this.emit(_constants.StreamEvent.END);
+    this.emit(_constants.StreamEvent.STATE, {
+      state: this._state
+    });
     this.notifyWaiters();
   }
 

package/library/stream/types.d.ts

@@ -1,4 +1,4 @@
-import { StreamType as StreamTypeConstant, StreamState as StreamStateConstant, StreamMode as StreamModeConstant } from '../constants';
+import { StreamType as StreamTypeConstant, StreamState as StreamStateConstant, StreamMode as StreamModeConstant, StreamEvent as StreamEventConstant } from '../constants';
 import type { MessageChannel } from '../message';
 /**
  * Stream type
@@ -6,6 +6,80 @@ import type { MessageChannel } from '../message';
 export type StreamType = typeof StreamTypeConstant[keyof typeof StreamTypeConstant];
 /** Writable stream mode */
 export type WritableStreamMode = typeof StreamModeConstant[keyof typeof StreamModeConstant];
+/**
+ * Stream event name
+ */
+export type StreamEventName = typeof StreamEventConstant[keyof typeof StreamEventConstant];
+/**
+ * Stream event payload map (for stream.on/once/off typing)
+ */
+export type StreamEventPayloadMap = {
+    start: {
+        streamId: string;
+        type: StreamType;
+        chunked: boolean;
+        mode?: WritableStreamMode;
+        metadata?: Record<string, any>;
+    };
+    data: {
+        chunk: any;
+        done?: boolean;
+        seq?: number;
+    };
+    read: {
+        value: any;
+    };
+    write: {
+        data: any;
+        done?: boolean;
+    };
+    send: {
+        seq: number;
+        done?: boolean;
+    };
+    pull: {
+        credit: number;
+        totalCredit?: number;
+    };
+    ack: {
+        seq?: number;
+    };
+    end: void;
+    cancel: {
+        reason?: string;
+        remote?: boolean;
+        error?: Error;
+    };
+    error: {
+        error?: Error;
+    };
+    timeout: {
+        timeout?: number;
+    };
+    expired: {
+        timeout: number;
+    };
+    state: {
+        state: StreamState;
+    };
+};
+export type StreamEventListener<E extends StreamEventName = StreamEventName> = (payload: StreamEventPayloadMap[E]) => void;
+/**
+ * Per-frame send/receive options (optional).
+ */
+export interface StreamFrameOptions {
+    /**
+     * Whether to require delivery acknowledgment for this frame.
+     *
+     * When enabled:
+     * - the sender attaches `requireAck: true` to the underlying postMessage
+     * - the receiver (MessageDispatcher) auto-replies with `ack` after it accepts the message
+     * - the returned Promise resolves to true/false
+     */
+    requireAck?: boolean;
+    /** Acknowledgment timeout (ms). Default: DefaultTimeout.ACK */
+    ackTimeout?: number;
+}
 /**
  * Stream data chunk
  */
@@ -52,6 +126,28 @@ export interface WritableStreamOptions {
      * If true, client will automatically read the stream and return fileData instead of stream
      */
     autoResolve?: boolean;
+    /**
+     * Maximum number of pending (unsent) chunks kept in memory on the writer side.
+     *
+     * This is especially useful for long-lived `push` streams when the receiver stops pulling
+     * (e.g. tab hidden/backgrounded): the writer-side `pendingQueue` may grow without bound if
+     * user code keeps calling write().
+     *
+     * - When enabled (value > 0), exceeding the limit will cause write()/producer to throw.
+     * - Default: unlimited.
+     */
+    maxPendingChunks?: number;
+    /**
+     * Maximum bytes of pending (unsent) chunks kept in memory on the writer side.
+     *
+     * Notes:
+     * - Only counts well-defined types: string / ArrayBuffer / TypedArray(DataView) / Blob / File.
+     * - For other values (plain objects), the size is treated as 0 (not counted). If you need
+     *   byte-level backpressure for objects, stringify them yourself before write().
+     *
+     * Default: unlimited.
+     */
+    maxPendingBytes?: number;
 }
 /**
  * Readable stream configuration options
@@ -167,6 +263,8 @@ export interface IIframeWritableStream {
      * @param done Whether this is the last chunk
      */
     write(data: any, done?: boolean): void;
+    write(data: any, options: StreamFrameOptions): Promise<boolean>;
+    write(data: any, done: boolean | undefined, options: StreamFrameOptions): Promise<boolean>;
     /**
      * End the stream (only meaningful when mode === 'push').
      */
@@ -175,6 +273,13 @@ export interface IIframeWritableStream {
     abort(reason?: string): void;
     /** Cancel stream transfer */
     cancel(reason?: string): void;
+    /**
+     * Subscribe to stream events (debug/observability).
+     * Returns an unsubscribe function.
+     */
+    on<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): () => void;
+    once<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): () => void;
+    off<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): void;
 }
 /**
  * Readable stream interface (client-side)
@@ -215,6 +320,13 @@ export interface IIframeReadableStream<T = any> {
     onEnd(callback: () => void): void;
     /** Listen for stream error */
     onError(callback: (error: Error) => void): void;
+    /**
+     * Subscribe to stream events (debug/observability).
+     * Returns an unsubscribe function.
+     */
+    on<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): () => void;
+    once<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): () => void;
+    off<E extends StreamEventName>(event: E, listener: StreamEventListener<E>): void;
 }
 /**
  * File readable stream interface
@@ -249,12 +361,13 @@ export interface StreamMessageData {
     mode?: WritableStreamMode;
     /** Data chunk */
     data?: any;
-    /** Chunk sequence number (used by pull/ack protocol) */
+    /** Chunk sequence number (used for data chunk identification) */
     seq?: number;
     /** Whether this is the last chunk */
     done?: boolean;
     /** Pull credit (how many chunks requested) */
     credit?: number;
+    /** reserved */
     /** Error message */
     error?: string;
     /** Cancel reason */