@spacecorexdev/core 0.0.2 → 0.0.5

package/src/utils/polyfills.ts

@@ -0,0 +1,928 @@
+/**
+ * 运行时能力兜底：
+ *  - Promise.allSettled（部分旧 Safari 缺失）
+ *  - Web Streams 相关构造器与 ReadableStream#pipeTo：
+ *      ReadableStream / WritableStream / TransformStream / ReadableByteStreamController
+ *      / ReadableStreamDefaultController / ReadableStreamDefaultReader
+ *      / WritableStreamDefaultWriter / ByteLengthQueuingStrategy / CountQueuingStrategy
+ *      / TextDecoderStream / TextEncoderStream
+ *
+ * 实现目标：避免 Safari 旧版本因 `typeof ReadableByteStreamController` 为 undefined 或
+ * 缺少 ReadableStream#pipeTo / WritableStream 时导致第三方库（文件预览、docx、压缩包等）报错。
+ * 只在缺失时赋值，不覆盖浏览器原生实现。
+ *
+ * 【经验】不要在顶层直接向 globalThis 注入大体积的 Web Streams polyfill：
+ * 第三方 stream polyfill 的 prototype patch 曾与 React dispatcher 的内部状态冲突，
+ * 导致懒加载 chunk 运行时 dispatcher.useState 为 null。因此：
+ *   1) 下面为轻量、最小可用的实现；
+ *   2) 仅在缺失时赋值；
+ *   3) 不修改 Promise / async generator 相关内置原型。
+ */
+
+/* =========================================================
+ * 0. 本文件内部使用的 DOM 类型别名（避免因 tsconfig lib 缺项导致编译错误）
+ * ========================================================= */
+type R<T> = { done: false; value: T } | { done: true; value?: undefined };
+type ByteR<T> = { done: false; value: T } | { done: true; value: T | undefined };
+type SPipeOptions = {
+  preventClose?: boolean;
+  preventAbort?: boolean;
+  preventCancel?: boolean;
+  signal?: AbortSignal;
+};
+
+/* =========================================================
+ * 1. Promise.allSettled polyfill（直接挂载到 Promise.allSettled）
+ * ========================================================= */
+(function installPromiseAllSettled() {
+  if (typeof Promise === 'undefined') return;
+  if (typeof (Promise as any).allSettled === 'function') return;
+
+  type PolyfillSettled<T> =
+    | { status: 'fulfilled'; value: T }
+    | { status: 'rejected'; reason: unknown };
+
+  const allSettledImpl = function <T>(values: Iterable<T | PromiseLike<T>>) {
+    const items = Array.isArray(values)
+      ? (values as Array<T | PromiseLike<T>>)
+      : Array.from(values as Iterable<T | PromiseLike<T>>);
+    if (items.length === 0) return Promise.resolve([] as any);
+    return new Promise((resolve) => {
+      const results: PolyfillSettled<Awaited<T>>[] = new Array(items.length);
+      let remaining = items.length;
+      const done = () => {
+        remaining -= 1;
+        if (remaining === 0) resolve(results);
+      };
+      items.forEach((input, index) => {
+        Promise.resolve(input).then(
+          (value) => {
+            results[index] = { status: 'fulfilled', value } as any;
+            done();
+          },
+          (reason) => {
+            results[index] = { status: 'rejected', reason };
+            done();
+          }
+        );
+      });
+    });
+  };
+
+  try {
+    Object.defineProperty(Promise, 'allSettled', {
+      configurable: true,
+      writable: true,
+      value: allSettledImpl,
+    });
+  } catch (e) {
+    // 严格冻结对象：尝试直接赋值兜底
+    try { (Promise as any).allSettled = allSettledImpl; } catch (_) { /* skip */ }
+  }
+  // Safari 个别版本：内置构造器上的 defineProperty 既不抛错，也不生效（静默失败）
+  // 这里再次检测，强制赋值兜底。
+  try {
+    if (typeof (Promise as any).allSettled !== 'function') {
+      (Promise as any).allSettled = allSettledImpl;
+    }
+  } catch (_) { /* skip */ }
+})();
+
+/**
+ * 业务代码使用 Promise.allSettled 前的「自愈式」守卫。
+ * 即便 index.html 内联脚本 + 本文件顶层 IIFE 在极端 Safari/缓存/ServiceWorker 组合下
+ * 都没能生效，调用该函数会再次尝试安装。设计为多次调用零成本。
+ *
+ * 使用示例：
+ *   import { ensurePromiseAllSettled } from './polyfills';
+ *   ensurePromiseAllSettled();
+ *   const results = await Promise.allSettled(jobs);
+ */
+export function ensurePromiseAllSettled(): void {
+  try {
+    if (typeof Promise === 'undefined') return;
+    if (typeof (Promise as any).allSettled === 'function') return;
+
+    type PolyfillSettled<T> =
+      | { status: 'fulfilled'; value: T }
+      | { status: 'rejected'; reason: unknown };
+
+    const impl = <T>(values: Iterable<T | PromiseLike<T>>) => {
+      const items = Array.isArray(values)
+        ? (values as Array<T | PromiseLike<T>>)
+        : Array.from(values as Iterable<T | PromiseLike<T>>);
+      if (items.length === 0) return Promise.resolve([] as any);
+      return new Promise((resolve) => {
+        const results: PolyfillSettled<Awaited<T>>[] = new Array(items.length);
+        let remaining = items.length;
+        const done = () => { if (--remaining === 0) resolve(results); };
+        items.forEach((input, index) => {
+          Promise.resolve(input).then(
+            (value) => { results[index] = { status: 'fulfilled', value } as any; done(); },
+            (reason) => { results[index] = { status: 'rejected', reason }; done(); }
+          );
+        });
+      });
+    };
+
+    try {
+      Object.defineProperty(Promise, 'allSettled', { configurable: true, writable: true, value: impl });
+    } catch (_) { /* skip */ }
+    if (typeof (Promise as any).allSettled !== 'function') {
+      try { (Promise as any).allSettled = impl; } catch (_) { /* skip */ }
+    }
+  } catch (_) { /* 极端情况下任何抛错都不能阻断业务执行 */ }
+}
+
+/**
+ * ReadableByteStreamController 自愈守卫：对「ReadableByteStreamController is not implemented」
+ * 这条显式错误字符串做兜底。第三方库在做 feature detection 时会以
+ * `typeof globalThis.ReadableByteStreamController === 'function'` 为前提，
+ * 如果检测通过但实际构造函数抛错，就会把这句抛出来，因此我们确保构造函数真正可用。
+ */
+export function ensureWebStreamsPolyfill(): void {
+  try { installWebStreamsPolyfill(); } catch (_) { /* skip */ }
+}
+
+/* =========================================================
+ * 2. QueuingStrategy
+ * ========================================================= */
+class ByteLengthQueuingStrategy {
+  public highWaterMark: number;
+  constructor({ highWaterMark }: { highWaterMark: number }) {
+    this.highWaterMark = highWaterMark;
+  }
+  size(chunk: ArrayBufferView) {
+    return chunk?.byteLength ?? 0;
+  }
+}
+
+class CountQueuingStrategy {
+  public highWaterMark: number;
+  constructor({ highWaterMark }: { highWaterMark: number }) {
+    this.highWaterMark = highWaterMark;
+  }
+  size() {
+    return 1;
+  }
+}
+
+/* =========================================================
+ * 3. ReadableStream (支持 default / pull / cancel 与 BYOB 控制器空壳)
+ *    注意：类不写 implements，避免 tsconfig lib 未声明的接口造成协变/逆变报错。
+ * ========================================================= */
+type QueueItem<T> =
+  | { type: 'chunk'; value: T }
+  | { type: 'close' }
+  | { type: 'error'; error: unknown };
+
+interface StreamState {
+  closed: boolean;
+  errored: boolean;
+  error: unknown;
+}
+
+class PolyfillReadableStreamDefaultController<T = any> {
+  public readonly desiredSize: number | null = 0;
+  public readonly byobRequest: any = null;
+  private _stream: PolyfillReadableStream<T>;
+  constructor(stream: PolyfillReadableStream<T>) {
+    this._stream = stream;
+  }
+  enqueue(chunk: T) {
+    this._stream._push(chunk);
+  }
+  close() {
+    this._stream._close();
+  }
+  error(e?: unknown) {
+    this._stream._error(e ?? new Error('ReadableStream errored'));
+  }
+  get desiredSizeInternal() {
+    return this._stream._chunks ? 1 : 0;
+  }
+}
+
+class PolyfillReadableByteStreamController {
+  public readonly byobRequest: any = null;
+  public readonly desiredSize: number | null = 0;
+  private _stream: PolyfillReadableStream<Uint8Array>;
+  constructor(stream: PolyfillReadableStream<Uint8Array>) {
+    this._stream = stream;
+  }
+  close() {
+    this._stream._close();
+  }
+  enqueue(chunk: ArrayBufferView) {
+    this._stream._push(new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength));
+  }
+  error(e?: unknown) {
+    this._stream._error(e ?? new Error('ReadableByteStream errored'));
+  }
+}
+
+class PolyfillReadableStreamDefaultReader<T = any> {
+  public readonly closed: Promise<undefined>;
+  private _stream: PolyfillReadableStream<T>;
+  private _resolveClosed!: (value: undefined) => void;
+  constructor(stream: PolyfillReadableStream<T>) {
+    this._stream = stream;
+    this._stream._reader = this;
+    this.closed = new Promise((resolve) => {
+      this._resolveClosed = resolve;
+    });
+  }
+  read(): Promise<R<T>> {
+    return this._stream._read();
+  }
+  releaseLock() {
+    if (this._stream._reader === this) this._stream._reader = null;
+  }
+  cancel(reason?: unknown): Promise<void> {
+    return this._stream.cancel(reason);
+  }
+  _onClosed() {
+    this._resolveClosed(undefined);
+  }
+}
+
+class PolyfillReadableStreamBYOBReader {
+  public readonly closed: Promise<undefined>;
+  private _stream: PolyfillReadableStream<any>;
+  private _resolveClosed!: (value: undefined) => void;
+  constructor(stream: PolyfillReadableStream<any>) {
+    this._stream = stream;
+    this._stream._byobReader = this;
+    this.closed = new Promise((resolve) => {
+      this._resolveClosed = resolve;
+    });
+  }
+  read<T extends ArrayBufferView>(view: T): Promise<ByteR<T>> {
+    // 最小实现：合并 bytes chunks 到传入 buffer 中
+    return this._stream._readInto(view);
+  }
+  releaseLock() {
+    if (this._stream._byobReader === this) this._stream._byobReader = null;
+  }
+  cancel(reason?: unknown): Promise<void> {
+    return this._stream.cancel(reason);
+  }
+  _onClosed() {
+    this._resolveClosed(undefined);
+  }
+}
+
+class PolyfillReadableStream<T = any> {
+  public locked = false;
+  // 内部字段用包内可见访问
+  _chunks: QueueItem<T>[] = [];
+  _waiting: null | ((value: R<T>) => void) = null;
+  _byobWaiting: null | ((value: any) => void) = null;
+  _reader: PolyfillReadableStreamDefaultReader<T> | null = null;
+  _byobReader: PolyfillReadableStreamBYOBReader | null = null;
+  _state: StreamState = { closed: false, errored: false, error: undefined };
+  _source: any = null;
+  _cancelCallback: null | ((reason: unknown) => void | PromiseLike<void>) = null;
+  _controller: any = null;
+  _pulling = false;
+  _pullScheduled = false;
+  _type: undefined | 'bytes' = undefined;
+  _autoAllocateChunkSize: number | undefined;
+
+  constructor(underlyingSource?: any, _strategy?: any) {
+    this._source = underlyingSource ?? null;
+    this._cancelCallback = underlyingSource?.cancel ?? null;
+    if (underlyingSource && underlyingSource.type === 'bytes') {
+      this._type = 'bytes';
+      this._autoAllocateChunkSize = underlyingSource.autoAllocateChunkSize;
+      this._controller = new PolyfillReadableByteStreamController(
+        this as unknown as PolyfillReadableStream<Uint8Array>
+      );
+    } else {
+      this._controller = new PolyfillReadableStreamDefaultController<T>(this);
+    }
+    const start = underlyingSource?.start;
+    if (typeof start === 'function') {
+      Promise.resolve(start.call(underlyingSource, this._controller)).catch((e: unknown) => {
+        this._error(e);
+      });
+    }
+  }
+
+  getReader(): any {
+    // 为避免签名冲突，运行时根据 options.mode 判断；不写 overload 防止与 lib.dom 不一致
+    // eslint-disable-next-line prefer-rest-params
+    const options = arguments[0] as { mode?: 'byob' } | undefined;
+    if (options?.mode === 'byob') {
+      if (this._byobReader) throw new TypeError('ReadableStream is locked');
+      return new PolyfillReadableStreamBYOBReader(this);
+    }
+    if (this._reader) throw new TypeError('ReadableStream is locked');
+    return new PolyfillReadableStreamDefaultReader<T>(this);
+  }
+
+  tee(): [any, any] {
+    const left = this._branch();
+    const right = this._branch();
+    return [left, right];
+  }
+
+  pipeThrough(transform: { readable: any; writable: any }, options?: SPipeOptions): any {
+    void this.pipeTo(transform.writable, options);
+    return transform.readable;
+  }
+
+  async pipeTo(dest: any, options?: SPipeOptions): Promise<void> {
+    const preventClose = !!options?.preventClose;
+    const preventAbort = !!options?.preventAbort;
+    const preventCancel = !!options?.preventCancel;
+    const writer = dest && typeof dest.getWriter === 'function' ? dest.getWriter() : null;
+    try {
+      const reader: any = this.getReader();
+      try {
+        while (true) {
+          const { done, value } = (await reader.read()) as { done: boolean; value: T };
+          if (done) break;
+          if (writer && typeof writer.ready !== 'undefined') await writer.ready;
+          if (writer && typeof writer.write === 'function') {
+            await writer.write(value);
+          } else if (dest && typeof dest.write === 'function') {
+            dest.write(value);
+          }
+        }
+      } finally {
+        try {
+          reader.releaseLock();
+        } catch {
+          /* ignore */
+        }
+      }
+      if (!preventClose) {
+        if (writer && typeof writer.close === 'function') await writer.close();
+        else if (dest && typeof dest.close === 'function') dest.close();
+      }
+    } catch (error) {
+      if (!preventAbort) {
+        try {
+          if (writer && typeof writer.abort === 'function') await writer.abort(error);
+          else if (dest && typeof dest.abort === 'function') dest.abort(error);
+        } catch {
+          /* ignore */
+        }
+      }
+      if (!preventCancel) {
+        try {
+          await this.cancel(error);
+        } catch {
+          /* ignore */
+        }
+      }
+      throw error;
+    } finally {
+      if (writer && typeof writer.releaseLock === 'function') {
+        try {
+          writer.releaseLock();
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  }
+
+  async cancel(reason?: unknown): Promise<void> {
+    if (this._state.closed || this._state.errored) return;
+    this._state.closed = true;
+    try {
+      if (this._cancelCallback) await this._cancelCallback(reason);
+    } finally {
+      this._finalizeClose();
+    }
+  }
+
+  // --- 内部接口 ----------------------------------------------------------
+  _branch(): PolyfillReadableStream<T> {
+    const self = this;
+    const out = new PolyfillReadableStream<T>({
+      start: async (controller: any) => {
+        const reader: any = self.getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            controller.enqueue(value);
+          }
+          controller.close();
+        } catch (e) {
+          controller.error(e);
+        } finally {
+          try {
+            reader.releaseLock();
+          } catch {
+            /* ignore */
+          }
+        }
+      },
+    });
+    return out;
+  }
+
+  _push(chunk: T) {
+    if (this._state.closed || this._state.errored) return;
+    if (this._waiting) {
+      const resolve = this._waiting;
+      this._waiting = null;
+      resolve({ done: false, value: chunk });
+      this._schedulePullIfNeeded();
+      return;
+    }
+    if (this._byobWaiting) {
+      const resolve = this._byobWaiting;
+      this._byobWaiting = null;
+      resolve(this._buildByobResult(chunk as unknown as ArrayBufferView));
+      this._schedulePullIfNeeded();
+      return;
+    }
+    this._chunks.push({ type: 'chunk', value: chunk });
+    this._schedulePullIfNeeded();
+  }
+
+  _close() {
+    if (this._state.closed || this._state.errored) return;
+    this._state.closed = true;
+    this._chunks.push({ type: 'close' });
+    if (this._waiting) {
+      const resolve = this._waiting;
+      this._waiting = null;
+      resolve({ done: true, value: undefined });
+    }
+    this._finalizeClose();
+  }
+
+  _error(error: unknown) {
+    if (this._state.closed || this._state.errored) return;
+    this._state.errored = true;
+    this._state.error = error;
+    this._chunks.push({ type: 'error', error });
+    if (this._waiting) {
+      const resolve = this._waiting;
+      this._waiting = null;
+      resolve(Promise.reject(error) as any);
+    }
+    this._finalizeClose();
+  }
+
+  _finalizeClose() {
+    if (this._reader) this._reader._onClosed();
+    if (this._byobReader) this._byobReader._onClosed();
+  }
+
+  _schedulePullIfNeeded() {
+    if (this._pullScheduled) return;
+    const pull = this._source?.pull;
+    if (typeof pull !== 'function') return;
+    if (this._state.closed || this._state.errored) return;
+    if (this._chunks.length > 0 || this._waiting || this._byobWaiting) return;
+    this._pullScheduled = true;
+    queueMicrotask(() => {
+      this._pullScheduled = false;
+      if (this._pulling) return;
+      if (this._state.closed || this._state.errored) return;
+      this._pulling = true;
+      Promise.resolve(pull.call(this._source, this._controller))
+        .catch((e: unknown) => this._error(e))
+        .finally(() => {
+          this._pulling = false;
+        });
+    });
+  }
+
+  _read(): Promise<R<T>> {
+    if (this._state.errored) return Promise.reject(this._state.error);
+    if (this._state.closed) return Promise.resolve({ done: true, value: undefined });
+    while (this._chunks.length) {
+      const item = this._chunks.shift()!;
+      if (item.type === 'chunk') {
+        this._schedulePullIfNeeded();
+        return Promise.resolve({ done: false, value: item.value });
+      }
+      if (item.type === 'close') {
+        return Promise.resolve({ done: true, value: undefined });
+      }
+      if (item.type === 'error') {
+        return Promise.reject(item.error);
+      }
+    }
+    return new Promise<R<T>>((resolve, reject) => {
+      this._waiting = (value: R<T>) => {
+        if (this._state.errored) reject(this._state.error);
+        else resolve(value);
+      };
+      this._schedulePullIfNeeded();
+    });
+  }
+
+  _readInto<T extends ArrayBufferView>(view: T): Promise<ByteR<T>> {
+    if (this._state.errored) return Promise.reject(this._state.error);
+    if (this._state.closed) return Promise.resolve({ done: true, value: view });
+    let written = 0;
+    const target = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    while (this._chunks.length && written < target.byteLength) {
+      const item = this._chunks[0];
+      if (item.type === 'chunk') {
+        const src = this._toUint8(item.value as unknown as ArrayBufferView);
+        const toCopy = Math.min(src.length, target.byteLength - written);
+        target.set(src.subarray(0, toCopy), written);
+        written += toCopy;
+        if (toCopy < src.length) {
+          (this._chunks[0] as any).value = src.subarray(toCopy);
+        } else {
+          this._chunks.shift();
+        }
+      } else if (item.type === 'close') {
+        this._chunks.shift();
+        const outView =
+          written === 0
+            ? view
+            : (new DataView(view.buffer, view.byteOffset, written) as unknown as T);
+        return Promise.resolve({ done: true, value: (written ? outView : view) as T });
+      } else if (item.type === 'error') {
+        this._chunks.shift();
+        return Promise.reject(item.error);
+      }
+    }
+    if (written > 0) {
+      const newView = new DataView(view.buffer, view.byteOffset, written) as unknown as T;
+      this._schedulePullIfNeeded();
+      return Promise.resolve({ done: false, value: newView });
+    }
+    return new Promise<ByteR<T>>((resolve, reject) => {
+      this._byobWaiting = (res: any) => {
+        if (this._state.errored) reject(this._state.error);
+        else resolve(res);
+      };
+      this._schedulePullIfNeeded();
+    });
+  }
+
+  _buildByobResult(chunk: ArrayBufferView): any {
+    const src = this._toUint8(chunk);
+    const out = new Uint8Array(src.length);
+    out.set(src);
+    return { done: false, value: out };
+  }
+
+  _toUint8(chunk: any): Uint8Array {
+    if (chunk instanceof Uint8Array) return chunk;
+    if (ArrayBuffer.isView(chunk)) {
+      return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+    }
+    if (chunk instanceof ArrayBuffer) return new Uint8Array(chunk);
+    if (typeof chunk === 'string') {
+      const enc = new TextEncoder();
+      return enc.encode(chunk);
+    }
+    if (Array.isArray(chunk)) return new Uint8Array(chunk);
+    return new Uint8Array(0);
+  }
+}
+
+/* =========================================================
+ * 4. WritableStream
+ * ========================================================= */
+class PolyfillWritableStreamDefaultWriter<W = any> {
+  public readonly closed: Promise<undefined>;
+  public readonly ready: Promise<undefined>;
+  public readonly desiredSize: number | null = 1;
+  private _stream: PolyfillWritableStream<W>;
+  private _resolveClosed!: (v: undefined) => void;
+  private _resolveReady!: (v: undefined) => void;
+  constructor(stream: PolyfillWritableStream<W>) {
+    this._stream = stream;
+    this._stream._writer = this;
+    this.closed = new Promise((res) => {
+      this._resolveClosed = res;
+    });
+    this.ready = new Promise((res) => {
+      this._resolveReady = res;
+    });
+    Promise.resolve().then(() => this._resolveReady(undefined));
+  }
+  abort(reason?: unknown): Promise<void> {
+    return this._stream.abort(reason);
+  }
+  close(): Promise<void> {
+    return this._stream.close();
+  }
+  releaseLock() {
+    if (this._stream._writer === this) this._stream._writer = null;
+  }
+  write(chunk: W): Promise<void> {
+    return this._stream.write(chunk);
+  }
+  _onClosed() {
+    this._resolveClosed(undefined);
+  }
+}
+
+class PolyfillWritableStream<W = any> {
+  public locked = false;
+  _writer: PolyfillWritableStreamDefaultWriter<W> | null = null;
+  _state: StreamState = { closed: false, errored: false, error: undefined };
+  _sink: any = {};
+  _controller: any = null;
+  constructor(underlyingSink?: any, _strategy?: any) {
+    this._sink = underlyingSink ?? {};
+    const start = this._sink.start;
+    this._controller = {
+      error: (e?: unknown) => this._error(e ?? new Error('WritableStream errored')),
+      signal: { aborted: false, reason: undefined as unknown },
+    };
+    if (typeof start === 'function') {
+      Promise.resolve(start.call(this._sink, this._controller)).catch((e: unknown) => this._error(e));
+    }
+  }
+  getWriter() {
+    if (this._writer) throw new TypeError('WritableStream is locked');
+    return new PolyfillWritableStreamDefaultWriter<W>(this);
+  }
+  async abort(reason?: unknown): Promise<void> {
+    if (this._state.closed || this._state.errored) return;
+    this._controller.signal.aborted = true;
+    this._controller.signal.reason = reason;
+    this._state.errored = true;
+    this._state.error = reason;
+    const abort = this._sink.abort;
+    if (typeof abort === 'function') await abort.call(this._sink, reason);
+    this._finalize();
+  }
+  async close(): Promise<void> {
+    if (this._state.closed || this._state.errored) return;
+    this._state.closed = true;
+    const closeFn = this._sink.close;
+    if (typeof closeFn === 'function') await closeFn.call(this._sink);
+    this._finalize();
+  }
+  async write(chunk: W): Promise<void> {
+    if (this._state.errored) throw this._state.error;
+    if (this._state.closed) throw new TypeError('WritableStream is closed');
+    const writeFn = this._sink.write;
+    if (typeof writeFn === 'function') {
+      const result = writeFn.call(this._sink, chunk, this._controller);
+      await Promise.resolve(result);
+    }
+  }
+  _finalize() {
+    if (this._writer) this._writer._onClosed();
+  }
+  _error(e: unknown) {
+    if (this._state.closed || this._state.errored) return;
+    this._state.errored = true;
+    this._state.error = e;
+    this._finalize();
+  }
+}
+
+/* =========================================================
+ * 5. TransformStream
+ * ========================================================= */
+class PolyfillTransformStream<I = any, O = any> {
+  public readonly readable: any;
+  public readonly writable: any;
+  constructor(transformer?: any, _writableStrategy?: any, _readableStrategy?: any) {
+    let readableController: any;
+    this.readable = new PolyfillReadableStream<O>({
+      start: (controller: any) => {
+        readableController = controller;
+        const startFn = transformer?.start;
+        if (typeof startFn === 'function') {
+          Promise.resolve(startFn.call(transformer, readableController)).catch((e: unknown) =>
+            readableController.error(e)
+          );
+        }
+      },
+    });
+    this.writable = new PolyfillWritableStream<I>({
+      write: async (chunk: I, _controller: any) => {
+        const fn = transformer?.transform;
+        if (typeof fn === 'function') {
+          await Promise.resolve(fn.call(transformer, chunk, readableController));
+        } else {
+          readableController.enqueue(chunk as unknown as O);
+        }
+      },
+      close: async () => {
+        const flush = transformer?.flush;
+        if (typeof flush === 'function') {
+          await Promise.resolve(flush.call(transformer, readableController));
+        }
+        readableController.close();
+      },
+      abort: async (reason: unknown) => {
+        readableController.error(reason);
+        const abort = transformer?.abort;
+        if (typeof abort === 'function') await abort.call(transformer, reason);
+      },
+    });
+  }
+}
+
+/* =========================================================
+ * 6. TextDecoderStream / TextEncoderStream
+ * ========================================================= */
+class PolyfillTextDecoderStream {
+  public readonly readable: any;
+  public readonly writable: any;
+  public readonly encoding: string;
+  public readonly fatal: boolean;
+  public readonly ignoreBOM: boolean;
+  constructor(label?: string, options?: TextDecoderOptions) {
+    const decoder = new TextDecoder(label, options);
+    this.encoding = decoder.encoding;
+    this.fatal = decoder.fatal;
+    this.ignoreBOM = decoder.ignoreBOM;
+    const ts = new PolyfillTransformStream<ArrayBufferView, string>({
+      transform(chunk: ArrayBufferView, controller: any) {
+        controller.enqueue(decoder.decode(chunk, { stream: true }));
+      },
+      flush(controller: any) {
+        const tail = decoder.decode();
+        if (tail) controller.enqueue(tail);
+      },
+    });
+    this.readable = ts.readable;
+    this.writable = ts.writable;
+  }
+}
+
+class PolyfillTextEncoderStream {
+  public readonly readable: any;
+  public readonly writable: any;
+  public readonly encoding: string = 'utf-8';
+  constructor() {
+    const encoder = new TextEncoder();
+    const ts = new PolyfillTransformStream<string, Uint8Array>({
+      transform(chunk: string, controller: any) {
+        controller.enqueue(encoder.encode(chunk));
+      },
+    });
+    this.readable = ts.readable;
+    this.writable = ts.writable;
+  }
+}
+
+/* =========================================================
+ * 7. 安装：先处理 Safari「半残实现」再按缺失情况挂载
+ * ========================================================= */
+function forceDefineOnGlobal(key: string, value: unknown): void {
+  const glb = globalThis as any;
+  try {
+    Object.defineProperty(glb, key, {
+      configurable: true,
+      writable: true,
+      enumerable: false,
+      value,
+    });
+  } catch (_) {
+    try { glb[key] = value; } catch (__) { /* skip */ }
+  }
+  // defineProperty 静默失败兜底
+  try { if (glb[key] !== value) glb[key] = value; } catch (_) { /* skip */ }
+}
+
+function installIfMissing(key: string, value: unknown) {
+  const glb = globalThis as any;
+  try {
+    if (typeof glb[key] === 'undefined') {
+      forceDefineOnGlobal(key, value);
+    }
+  } catch {
+    /* ignore strict-mode redefine errors */
+  }
+}
+
+/**
+ * 老版本 Safari「半残实现」探测器：
+ *   ReadableStream 作为函数挂在全局，但 ReadableByteStreamController 缺失，
+ *   或 new ReadableStream({ type:'bytes' }) / getReader({mode:'byob'}) 直接抛出
+ *   "ReadableByteStreamController is not implemented"。
+ * React 18 renderToReadableStream 会进入 bytes 分支，最终抛截图所示错误。
+ * 命中迹象即返回 true，调用方应当整体覆盖 Readable/Writable/TransformStream 三个构造器。
+ */
+function detectBrokenWebStreamsImplementation(): boolean {
+  try {
+    const RS = (globalThis as any).ReadableStream;
+    const RBC = (globalThis as any).ReadableByteStreamController;
+    const WS = (globalThis as any).WritableStream;
+    const TS = (globalThis as any).TransformStream;
+    if (typeof RS !== 'function') return false;
+
+    if (typeof RBC !== 'function') return true;
+
+    try {
+      const src = {
+        type: 'bytes' as const,
+        start(c: any) { try { c.close(); } catch (_) { /* ignore */ } },
+      };
+      const tmp: any = new RS(src);
+      try {
+        const byob = tmp.getReader({ mode: 'byob' as const });
+        if (!byob) return true;
+        try { byob.releaseLock(); } catch (_) { /* ignore */ }
+      } catch (brErr: any) {
+        const msg = String(brErr?.message ?? '');
+        if (/not implemented|ReadableByteStreamController|byob|not supported|invalid mode/i.test(msg)) return true;
+      }
+      try { tmp.cancel && tmp.cancel(); } catch (_) { /* ignore */ }
+    } catch (e: any) {
+      const msg = String(e?.message ?? '');
+      if (/ReadableByteStreamController is not implemented|is not implemented|not supported|type bytes|invalid type/i.test(msg)) return true;
+    }
+
+    const proto = RS.prototype;
+    if (!proto || typeof proto.pipeTo !== 'function' || typeof proto.pipeThrough !== 'function' || typeof proto.tee !== 'function') {
+      if (typeof WS !== 'function') return true;
+    }
+    if (typeof TS !== 'undefined' && typeof TS !== 'function') return true;
+
+    return false;
+  } catch (_) {
+    return false;
+  }
+}
+
+export function installWebStreamsPolyfill(): void {
+  if (typeof globalThis === 'undefined') return;
+
+  const needsFullOverride = detectBrokenWebStreamsImplementation();
+
+  if (needsFullOverride) {
+    // 整体替换：把 Safari 的半残实现整个清洗掉，用我们的 polyfill 替换
+    forceDefineOnGlobal('ReadableStream', PolyfillReadableStream);
+    forceDefineOnGlobal('ReadableByteStreamController', PolyfillReadableByteStreamController);
+    forceDefineOnGlobal('ReadableStreamDefaultController', PolyfillReadableStreamDefaultController);
+    forceDefineOnGlobal('ReadableStreamDefaultReader', PolyfillReadableStreamDefaultReader);
+    forceDefineOnGlobal('ReadableStreamBYOBReader', PolyfillReadableStreamBYOBReader);
+    forceDefineOnGlobal('WritableStream', PolyfillWritableStream);
+    forceDefineOnGlobal('WritableStreamDefaultWriter', PolyfillWritableStreamDefaultWriter);
+    forceDefineOnGlobal('TransformStream', PolyfillTransformStream);
+    forceDefineOnGlobal('TextDecoderStream', PolyfillTextDecoderStream);
+    forceDefineOnGlobal('TextEncoderStream', PolyfillTextEncoderStream);
+    forceDefineOnGlobal('ByteLengthQueuingStrategy', ByteLengthQueuingStrategy);
+    forceDefineOnGlobal('CountQueuingStrategy', CountQueuingStrategy);
+  } else {
+    installIfMissing('ByteLengthQueuingStrategy', ByteLengthQueuingStrategy);
+    installIfMissing('CountQueuingStrategy', CountQueuingStrategy);
+
+    installIfMissing('ReadableStream', PolyfillReadableStream);
+    installIfMissing('WritableStream', PolyfillWritableStream);
+    installIfMissing('TransformStream', PolyfillTransformStream);
+
+    installIfMissing('ReadableByteStreamController', PolyfillReadableByteStreamController);
+    installIfMissing('ReadableStreamDefaultController', PolyfillReadableStreamDefaultController);
+    installIfMissing('ReadableStreamDefaultReader', PolyfillReadableStreamDefaultReader);
+    installIfMissing('ReadableStreamBYOBReader', PolyfillReadableStreamBYOBReader);
+    installIfMissing('WritableStreamDefaultWriter', PolyfillWritableStreamDefaultWriter);
+
+    installIfMissing('TextDecoderStream', PolyfillTextDecoderStream);
+    installIfMissing('TextEncoderStream', PolyfillTextEncoderStream);
+  }
+
+  // 浏览器自带 ReadableStream 但原型上没有 pipeTo（极个别老版本）
+  try {
+    const GlbReadable = (globalThis as any).ReadableStream;
+    if (typeof GlbReadable === 'function') {
+      const proto = GlbReadable.prototype;
+      if (proto && typeof proto.pipeTo !== 'function') {
+        Object.defineProperty(proto, 'pipeTo', {
+          configurable: true,
+          writable: true,
+          value: PolyfillReadableStream.prototype.pipeTo,
+        });
+        Object.defineProperty(proto, 'pipeThrough', {
+          configurable: true,
+          writable: true,
+          value: PolyfillReadableStream.prototype.pipeThrough,
+        });
+        Object.defineProperty(proto, 'tee', {
+          configurable: true,
+          writable: true,
+          value: PolyfillReadableStream.prototype.tee,
+        });
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+}
+
+/**
+ * 立即尝试安装。
+ * 严格遵循 Lessons Learned：不触碰 Promise / Generator 原型，
+ * 从而避免与 React dispatcher 冲突。
+ */
+try {
+  installWebStreamsPolyfill();
+} catch (e) {
+   
+  console.warn('[polyfills] 安装 Web Streams polyfill 失败：', e);
+}