@lokvis/runtime 0.2.1 → 0.4.1

package/src/batch-progress.ts

@@ -0,0 +1,228 @@
+/**
+ * BatchProgressEmitter - 批量作业进度聚合与事件发射(W4.4 拆分)
+ *
+ * 职责:
+ * - 托管批量公开接口(BatchProgress / BatchItemInput / BatchItem / BatchJob / EnqueueOptions)
+ * - 管理 onProgress 订阅 + 发射所有 batch:* 事件
+ * - waitForCompletion:事件等待 + 超时(泛型,不依赖 BatchJob)
+ *
+ * 设计原则:无状态,不持有 job 引用,所有数据通过参数传入。
+ */
+import type {
+  AssetId,
+  AssetSource,
+  BatchItemStatus,
+  BatchJobStatus,
+  LokvisEvent,
+  Workflow,
+} from '@lokvis/schema';
+import type { EventBus } from '@lokvis/schema';
+
+/** 进度回调载荷 */
+export interface BatchProgress {
+  jobId: string;
+  completed: number;
+  failed: number;
+  total: number;
+}
+
+/** 批量项输入(每个文件一个) */
+export interface BatchItemInput {
+  source: AssetSource;
+  workflow: Workflow;
+  maxRetries?: number;
+}
+
+/** 批量项运行时状态(对外只读视图) */
+export interface BatchItem {
+  id: string;
+  index: number;
+  status: BatchItemStatus;
+  source: AssetSource;
+  workflow: Workflow;
+  outputAssetId?: AssetId;
+  error?: Error;
+  attempts: number;
+  maxRetries: number;
+  duration?: number;
+}
+
+/** 批量作业运行时状态(对外只读视图) */
+export interface BatchJob {
+  id: string;
+  status: BatchJobStatus;
+  items: BatchItem[];
+  completed: number;
+  failed: number;
+  total: number;
+  startedAt: number;
+  endedAt?: number;
+}
+
+/** enqueue 选项 */
+export interface EnqueueOptions {
+  items: BatchItemInput[];
+  maxRetries?: number;
+  concurrency?: number;
+}
+
+/** 批量进度发射器:统一管理 batch:* 事件与 progress 订阅。 */
+export class BatchProgressEmitter {
+  private readonly eventBus: EventBus;
+  private readonly progressSubs = new Map<string, Set<(p: BatchProgress) => void>>();
+
+  constructor(eventBus: EventBus) {
+    this.eventBus = eventBus;
+  }
+
+  /** 订阅 job 进度(返回取消订阅函数) */
+  onProgress(jobId: string, handler: (p: BatchProgress) => void): () => void {
+    let subs = this.progressSubs.get(jobId);
+    if (!subs) {
+      subs = new Set();
+      this.progressSubs.set(jobId, subs);
+    }
+    subs.add(handler);
+    return () => {
+      subs!.delete(handler);
+      if (subs!.size === 0) this.progressSubs.delete(jobId);
+    };
+  }
+
+  /** 发出 progress 事件 + 通知订阅者 */
+  emitProgress(jobId: string, completed: number, failed: number, total: number): void {
+    const payload: BatchProgress = { jobId, completed, failed, total };
+    this.emit({ type: 'batch:progress', ...payload });
+    const subs = this.progressSubs.get(jobId);
+    if (subs) {
+      // M1:遍历副本,防止 handler 内 unsubscribe mutate 正在迭代的 Set
+      for (const fn of [...subs]) {
+        try {
+          fn(payload);
+        } catch (err) {
+          // 单个订阅者异常不阻断其他订阅者(与 event-bus.ts onAny 隔离策略一致)
+          console.error(`[lokvis] batch-progress subscriber threw for job ${jobId}:`, err);
+        }
+      }
+    }
+  }
+
+  emitStarted(jobId: string, total: number): void {
+    this.emit({ type: 'batch:started', jobId, total });
+  }
+
+  emitItemStarted(jobId: string, itemId: string, index: number, total: number): void {
+    this.emit({ type: 'batch:item:started', jobId, itemId, index, total });
+  }
+
+  emitItemFinished(
+    jobId: string, itemId: string, index: number, total: number,
+    outputAssetId: AssetId, duration: number
+  ): void {
+    this.emit({ type: 'batch:item:finished', jobId, itemId, index, total, outputAssetId, duration });
+  }
+
+  emitItemFailed(
+    jobId: string, itemId: string, index: number, total: number,
+    error: Error, attempts: number
+  ): void {
+    this.emit({ type: 'batch:item:failed', jobId, itemId, index, total, error, attempts });
+  }
+
+  /** batch:completed(无论 completed 还是 failed 状态都发此事件) */
+  emitCompleted(
+    jobId: string, total: number, completed: number, failed: number, duration: number
+  ): void {
+    this.emit({ type: 'batch:completed', jobId, total, completed, failed, duration });
+  }
+
+  emitCancelled(jobId: string, cancelled: number): void {
+    this.emit({ type: 'batch:cancelled', jobId, cancelled });
+  }
+
+  emitPaused(jobId: string): void {
+    this.emit({ type: 'batch:paused', jobId });
+  }
+
+  emitResumed(jobId: string): void {
+    this.emit({ type: 'batch:resumed', jobId });
+  }
+
+  /** 清理 job 的所有进度订阅(终态时调用,避免泄漏) */
+  cleanupJobSubs(jobId: string): void {
+    this.progressSubs.delete(jobId);
+  }
+
+  /**
+   * 等待 job 完成(completed/failed/cancelled 任一)。
+   *
+   * M5:timeoutMs 默认 5min,超时 reject + 调用 onTimeout(cancel job),避免坏 job
+   * 永久挂起泄漏订阅。batch:completed 涵盖 failed(maybeComplete 对 failed>0 同样发),
+   * 故只需监听 completed + cancelled。resolve 后立即解绑订阅。
+   *
+   * 泛型 T 不依赖 BatchJob,由调用方提供 resolveJob 回调构造视图。
+   */
+  async waitForCompletion<T>(
+    jobId: string,
+    opts: {
+      timeoutMs?: number;
+      isTerminal: () => boolean;
+      resolveJob: () => T;
+      onTimeout: () => Promise<void>;
+    }
+  ): Promise<T> {
+    if (opts.isTerminal()) return opts.resolveJob();
+    const timeoutMs = opts.timeoutMs ?? 5 * 60 * 1000;
+
+    return new Promise<T>((resolve, reject) => {
+      let settled = false;
+      let offCompleted: () => void;
+      let offCancelled: () => void;
+      let timer: ReturnType<typeof setTimeout>;
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        offCompleted();
+        offCancelled();
+        fn();
+      };
+      offCompleted = this.eventBus.on('batch:completed', (e) => {
+        if (e.jobId !== jobId) return;
+        finish(() => resolve(opts.resolveJob()));
+      });
+      offCancelled = this.eventBus.on('batch:cancelled', (e) => {
+        if (e.jobId !== jobId) return;
+        finish(() => resolve(opts.resolveJob()));
+      });
+      timer = setTimeout(() => {
+        // 先 finish(reject + 取消订阅),再 onTimeout(cancel)。
+        // 顺序重要:finish 内 offCancelled() 解除订阅,此后 cancel 触发的
+        // batch:cancelled 不会被本 Promise 监听,避免抢先 resolve。
+        finish(() =>
+          reject(
+            new Error(
+              `BatchProcessor.waitForCompletion timed out after ${timeoutMs}ms (jobId=${jobId})`
+            )
+          )
+        );
+        void opts.onTimeout().catch((err) => {
+          console.warn(
+            `[lokvis] BatchProcessor: cancel(${jobId}) after timeout failed:`,
+            err
+          );
+        });
+      }, timeoutMs);
+    });
+  }
+
+  /** 安全 emit(EventBus 异常不阻断批量逻辑) */
+  private emit(event: LokvisEvent): void {
+    try {
+      this.eventBus.emit(event);
+    } catch (err) {
+      // EventBus 异常不阻断批量逻辑,但需记录便于调试
+      console.warn(`[lokvis] batch-progress emit("${event.type}") threw:`, err);
+    }
+  }
+}

package/src/batch-scheduler.ts

@@ -0,0 +1,209 @@
+/**
+ * BatchScheduler - 批量作业调度与重试(W4.4 拆分)
+ *
+ * 职责:
+ * - 调度循环:schedule 把 pending 项填入空闲槽位(ConcurrencyController)
+ * - 项处理:processItem 导入 → run → 导出 output AssetId
+ * - 失败重试:maxRetries 内回 pending,达上限标 failed
+ * - 完成检测:maybeComplete
+ * - cancel 竞态守卫(B1)
+ *
+ * 不持有 jobs Map(由 Facade 持有),通过参数接收 job。
+ */
+import type {
+  AssetId,
+  AssetSource,
+  BatchItemStatus,
+  BatchJobStatus,
+  Workflow,
+  WorkflowResult,
+} from '@lokvis/schema';
+import type { LokvisRuntime } from './types.js';
+import type { BatchProgressEmitter } from './batch-progress.js';
+import type { ConcurrencyController } from './concurrency-controller.js';
+
+/** BatchItem 内部可变状态 */
+export interface BatchItemInternal {
+  id: string;
+  index: number;
+  status: BatchItemStatus;
+  source: AssetSource;
+  workflow: Workflow;
+  outputAssetId?: AssetId;
+  error?: Error;
+  attempts: number;
+  maxRetries: number;
+  duration?: number;
+}
+
+/** BatchJob 内部可变状态 */
+export interface BatchJobInternal {
+  id: string;
+  status: BatchJobStatus;
+  baseConcurrency: number;
+  maxRetries: number;
+  items: BatchItemInternal[];
+  completed: number;
+  failed: number;
+  startedAt: number;
+  endedAt?: number;
+  scheduleLock: boolean;
+  paused: boolean;
+  cancelled: boolean;
+}
+
+/** 批量调度器:负责 job 的调度循环、项处理、重试与完成检测。 */
+export class BatchScheduler {
+  private readonly runtime: LokvisRuntime;
+  private readonly progress: BatchProgressEmitter;
+  private readonly concurrency: ConcurrencyController;
+
+  constructor(opts: {
+    runtime: LokvisRuntime;
+    progress: BatchProgressEmitter;
+    concurrency: ConcurrencyController;
+  }) {
+    this.runtime = opts.runtime;
+    this.progress = opts.progress;
+    this.concurrency = opts.concurrency;
+  }
+
+  /** 启动 job:发 batch:started,进入 running,触发首次 schedule */
+  async runJob(job: BatchJobInternal): Promise<void> {
+    if (job.cancelled) return;
+    job.status = 'running';
+    this.progress.emitStarted(job.id, job.items.length);
+    await this.schedule(job);
+  }
+
+  /**
+   * 调度循环:把 pending 项填入空闲槽位,直到无可用槽位或无 pending 项。
+   * 重入保护:scheduleLock 防并发 schedule 超限。
+   */
+  async schedule(job: BatchJobInternal): Promise<void> {
+    if (job.scheduleLock) return;
+    if (job.cancelled || job.paused) return;
+    if (this.isTerminal(job.status)) return;
+
+    job.scheduleLock = true;
+    try {
+      while (!job.cancelled && !job.paused) {
+        const running = job.items.filter((i) => i.status === 'processing').length;
+        const cap = this.concurrency.current(job.baseConcurrency);
+        if (running >= cap) break;
+
+        const next = job.items.find((i) => i.status === 'pending');
+        if (!next) break;
+
+        next.status = 'processing';
+        void this.processItem(job, next);
+      }
+      this.maybeComplete(job);
+    } finally {
+      job.scheduleLock = false;
+    }
+  }
+
+  /** 处理单个项:导入 → run workflow → 导出 output AssetId */
+  private async processItem(job: BatchJobInternal, item: BatchItemInternal): Promise<void> {
+    const start = Date.now();
+    const wfId = this.itemWorkflowId(job.id, item.id);
+    this.progress.emitItemStarted(job.id, item.id, item.index, job.items.length);
+
+    // B1:cancel 已同步标 item=cancelled,此处短路避免竞态
+    if (job.cancelled || item.status === 'cancelled') return;
+
+    let inputAssetId: AssetId | undefined;
+    let result: WorkflowResult | undefined;
+    try {
+      inputAssetId = await this.runtime.importAsset(item.source);
+
+      // B1:import 期间可能被 cancel
+      if (job.cancelled) {
+        item.status = 'cancelled';
+        // TD-3.3: asset-store remove 已对 NotFoundError 静默忽略,此处 catch 到的
+        // 都是真实错误,用 error 级别记录便于排查
+        void this.runtime.removeAsset(inputAssetId).catch((err) => {
+          console.error(`[lokvis] BatchProcessor: cleanup input(${inputAssetId}) on cancel failed:`, err);
+        });
+        return;
+      }
+
+      const wf: Workflow = { ...item.workflow, id: wfId };
+      result = await this.runtime.run(wf, [inputAssetId]);
+
+      // B1:run 期间可能被 cancel
+      if (job.cancelled) {
+        item.status = 'cancelled';
+        return;
+      }
+
+      if (result.status !== 'completed' || result.outputs.length === 0) {
+        throw new Error(result.error || `Workflow ${result.status}`);
+      }
+
+      const outputAssetId = result.outputs[0]!;
+      const duration = Date.now() - start;
+      item.status = 'completed';
+      item.outputAssetId = outputAssetId;
+      item.duration = duration;
+      job.completed++;
+      this.progress.emitItemFinished(job.id, item.id, item.index, job.items.length, outputAssetId, duration);
+      this.progress.emitProgress(job.id, job.completed, job.failed, job.items.length);
+    } catch (err) {
+      // B1:被 cancel 的 workflow 抛错不计入 failed
+      if (job.cancelled) {
+        item.status = 'cancelled';
+        return;
+      }
+      item.attempts++;
+      if (item.attempts <= item.maxRetries) {
+        // 重试:回 pending(不重置 attempts),清理本次 input 避免孤儿累积
+        item.status = 'pending';
+        if (inputAssetId !== undefined) {
+          void this.runtime.removeAsset(inputAssetId).catch((err) => {
+            console.error(`[lokvis] BatchProcessor: cleanup input(${inputAssetId}) on retry failed:`, err);
+          });
+        }
+      } else {
+        item.status = 'failed';
+        item.error = err instanceof Error ? err : new Error(String(err));
+        job.failed++;
+        // M4:最终失败时清理 input asset
+        if (inputAssetId !== undefined) {
+          void this.runtime.removeAsset(inputAssetId).catch((err) => {
+            console.error(`[lokvis] BatchProcessor: cleanup input(${inputAssetId}) on final fail failed:`, err);
+          });
+        }
+        this.progress.emitItemFailed(job.id, item.id, item.index, job.items.length, item.error, item.attempts);
+        this.progress.emitProgress(job.id, job.completed, job.failed, job.items.length);
+      }
+    } finally {
+      if (!job.cancelled && !job.paused && !this.isTerminal(job.status)) {
+        void this.schedule(job);
+      }
+    }
+  }
+
+  /** 检查 job 是否全部完成,如是则发 batch:completed */
+  maybeComplete(job: BatchJobInternal): void {
+    if (this.isTerminal(job.status)) return;
+    const pending = job.items.some((i) => i.status === 'pending' || i.status === 'processing');
+    if (pending) return;
+
+    job.endedAt = Date.now();
+    job.status = job.failed > 0 ? 'failed' : 'completed';
+    // 无论 completed 还是 failed 都发 batch:completed(waitForCompletion 依赖此行为)
+    this.progress.emitCompleted(job.id, job.items.length, job.completed, job.failed, job.endedAt - job.startedAt);
+    this.progress.cleanupJobSubs(job.id);
+  }
+
+  isTerminal(status: BatchJobStatus): boolean {
+    return status === 'completed' || status === 'cancelled' || status === 'failed';
+  }
+
+  /** 派生每项的 workflow id(独立于其他项,便于 cancel) */
+  itemWorkflowId(jobId: string, itemId: string): string {
+    return `${jobId}__${itemId}`;
+  }
+}

package/src/browser-detect.ts

@@ -0,0 +1,221 @@
+/**
+ * 浏览器能力检测(W22.3)
+ *
+ * 提供 Safari / Firefox 等浏览器的特性降级路径所需的能力探测:
+ * - 存储类:OPFS / IndexedDB / navigator.storage.estimate
+ * - 编解码类:WebCodecs(ImageDecoder/VideoDecoder/AudioDecoder/VideoEncoder) /
+ *   OffscreenCanvas / createImageBitmap
+ * - 并发类:SharedArrayBuffer / crossOriginIsolated(WASM 线程所需)
+ * - 其他:WebWorker / ServiceWorker / WebAssembly
+ *
+ * 设计原则:
+ * 1. 优先 feature detection(typeof X !== 'undefined' / 'function'),
+ *    不依赖 UA 嗅探(UA 易伪装且不未来兼容)
+ * 2. UA 嗅探仅作辅助,用于已知 Safari/ Firefox 版本的特定 workaround
+ * 3. 所有检测在 SSR(Node)环境下安全返回 false / unknown
+ * 4. 探测结果可被 Runtime 初始化 + Playground UI 复用
+ *
+ * 现有降级链(已在其他模块实现,本模块仅提供能力探测供调用方决策):
+ * - AssetStore:OPFS → IndexedDB → Memory(createAssetStore 工厂,W2.8)
+ * - engine-image:纯 Canvas 2D API(无 WebCodecs 需要降级)
+ * - canvas-engine.decodeResized:Safari 16.4+ 支持 createImageBitmap resize
+ *   选项,不支持时回退到普通 decode + drawImage(已实现)
+ */
+
+import { isOpfsSupported } from './opfs-asset-store.js';
+import { isIdbSupported } from './idb-asset-store.js';
+
+/** 浏览器能力检测结果 */
+export interface BrowserCapabilities {
+  /** OPFS(Origin Private File System)——大文件持久化存储 */
+  opfs: boolean;
+  /** IndexedDB——元数据 + blob 持久化(OPFS 不可用时的降级) */
+  indexedDB: boolean;
+  /** navigator.storage.estimate——存储配额查询 */
+  storageEstimate: boolean;
+  /** WebCodecs ImageDecoder——图像解码(未来引擎,当前未实装) */
+  webCodecsImageDecoder: boolean;
+  /** WebCodecs VideoDecoder——视频解码(Phase 2 engine-video) */
+  webCodecsVideoDecoder: boolean;
+  /** WebCodecs VideoEncoder——视频编码(Phase 2 engine-video) */
+  webCodecsVideoEncoder: boolean;
+  /** WebCodecs AudioDecoder——音频解码(Phase 2 engine-audio) */
+  webCodecsAudioDecoder: boolean;
+  /** OffscreenCanvas——离屏 canvas 渲染(engine-image 编解码核心依赖) */
+  offscreenCanvas: boolean;
+  /** createImageBitmap——图像位图创建(engine-image 解码核心依赖) */
+  createImageBitmap: boolean;
+  /** SharedArrayBuffer——WASM 多线程(ffmpeg.wasm 等 Phase 2 引擎) */
+  sharedArrayBuffer: boolean;
+  /** crossOriginIsolated——WASM 线程所需的安全上下文 */
+  crossOriginIsolated: boolean;
+  /** WebAssembly——WASM 引擎基础依赖 */
+  webAssembly: boolean;
+  /** WebWorker——Worker 内执行引擎(runtime worker-host) */
+  webWorker: boolean;
+  /** ServiceWorker——PWA 离线缓存 */
+  serviceWorker: boolean;
+}
+
+/** 浏览器 UA 识别结果(辅助用,优先用 BrowserCapabilities) */
+export interface BrowserInfo {
+  /** 浏览器名(基于 UA 嗅探,可能不准确) */
+  name: 'safari' | 'firefox' | 'chrome' | 'edge' | 'unknown';
+  /** 浏览器主版本号(基于 UA 嗅探,可能不准确) */
+  version: number;
+  /** 是否为 Safari(iOS Safari / macOS Safari) */
+  isSafari: boolean;
+  /** 是否为 Firefox */
+  isFirefox: boolean;
+  /** 是否为 Chrome(含 Chromium 内核,Edge 单独识别) */
+  isChrome: boolean;
+  /** 是否为 Microsoft Edge(Chromium 内核) */
+  isEdge: boolean;
+  /** 是否为移动端 */
+  isMobile: boolean;
+}
+
+/** 缓存能力探测结果(同一会话内不变,避免重复检测) */
+let cachedCapabilities: BrowserCapabilities | undefined;
+/** 缓存 UA 识别结果(同一会话内不变) */
+let cachedBrowserInfo: BrowserInfo | undefined;
+
+/**
+ * 探测当前环境(浏览器/Node)的能力。
+ *
+ * 在 SSR(Node)环境下,所有浏览器 API 检测返回 false。
+ *
+ * 结果在首次调用后缓存,同一会话内重复调用返回同一对象。
+ * 如需强制重新探测(测试场景),传 { force: true }。
+ */
+export function detectBrowserCapabilities(
+  options: { force?: boolean } = {}
+): BrowserCapabilities {
+  if (cachedCapabilities && !options.force) return cachedCapabilities;
+  const g = globalThis as Record<string, unknown>;
+  const nav = typeof navigator !== 'undefined' ? navigator : undefined;
+  cachedCapabilities = {
+    opfs: isOpfsSupported(),
+    indexedDB: isIdbSupported(),
+    storageEstimate:
+      !!nav && typeof nav.storage?.estimate === 'function',
+    webCodecsImageDecoder: typeof g.ImageDecoder !== 'undefined',
+    webCodecsVideoDecoder: typeof g.VideoDecoder !== 'undefined',
+    webCodecsVideoEncoder: typeof g.VideoEncoder !== 'undefined',
+    webCodecsAudioDecoder: typeof g.AudioDecoder !== 'undefined',
+    offscreenCanvas: typeof g.OffscreenCanvas !== 'undefined',
+    createImageBitmap: typeof g.createImageBitmap === 'function',
+    sharedArrayBuffer: typeof g.SharedArrayBuffer !== 'undefined',
+    crossOriginIsolated:
+      typeof g.crossOriginIsolated === 'boolean' ? g.crossOriginIsolated : false,
+    webAssembly: typeof g.WebAssembly !== 'undefined',
+    webWorker: typeof g.Worker !== 'undefined',
+    serviceWorker: !!nav && typeof nav.serviceWorker !== 'undefined',
+  };
+  return cachedCapabilities;
+}
+
+/** UA 嗅探正则(仅作辅助,优先用 detectBrowserCapabilities) */
+const SAFARI_REGEX = /Version\/(\d+)\.\d+.*Safari\/[\d.]+/;
+const FIREFOX_REGEX = /Firefox\/(\d+)\.\d+/;
+const EDGE_REGEX = /Edg\/(\d+)\.\d+/;
+const CHROME_REGEX = /Chrome\/(\d+)\.\d+/;
+const MOBILE_REGEX = /Mobi|Android|iPhone|iPad|iPod/i;
+
+/**
+ * 识别当前浏览器(基于 UA 嗅探)。
+ *
+ * 注意:UA 嗅探不可靠,浏览器可伪装 UA。优先用 detectBrowserCapabilities()
+ * 检测实际能力。本函数仅用于已知浏览器的特定 workaround(如 Safari 的
+ * createImageBitmap resize 选项兼容性)。
+ *
+ * 结果在首次调用后缓存,同一会话内重复调用返回同一对象。
+ * 如需强制重新识别(测试场景),传 { force: true }。
+ */
+export function detectBrowserInfo(
+  options: { force?: boolean } = {}
+): BrowserInfo {
+  if (cachedBrowserInfo && !options.force) return cachedBrowserInfo;
+  if (typeof navigator === 'undefined') {
+    cachedBrowserInfo = {
+      name: 'unknown', version: 0,
+      isSafari: false, isFirefox: false, isChrome: false, isEdge: false,
+      isMobile: false,
+    };
+    return cachedBrowserInfo;
+  }
+  const ua = navigator.userAgent;
+  // Edge 必须先检测(含 Chrome 字样)
+  const edgeMatch = ua.match(EDGE_REGEX);
+  if (edgeMatch && edgeMatch[1]) {
+    cachedBrowserInfo = {
+      name: 'edge', version: parseInt(edgeMatch[1], 10),
+      isSafari: false, isFirefox: false, isChrome: false, isEdge: true,
+      isMobile: MOBILE_REGEX.test(ua),
+    };
+    return cachedBrowserInfo;
+  }
+  // Safari 必须在 Chrome 之前检测(排除 Chrome:Chrome UA 含 Chrome/ 但不含 Version/X Safari/X)
+  const safariMatch = ua.match(SAFARI_REGEX);
+  if (safariMatch && safariMatch[1] && !ua.includes('Chrome/')) {
+    cachedBrowserInfo = {
+      name: 'safari', version: parseInt(safariMatch[1], 10),
+      isSafari: true, isFirefox: false, isChrome: false, isEdge: false,
+      isMobile: MOBILE_REGEX.test(ua),
+    };
+    return cachedBrowserInfo;
+  }
+  const firefoxMatch = ua.match(FIREFOX_REGEX);
+  if (firefoxMatch && firefoxMatch[1]) {
+    cachedBrowserInfo = {
+      name: 'firefox', version: parseInt(firefoxMatch[1], 10),
+      isSafari: false, isFirefox: true, isChrome: false, isEdge: false,
+      isMobile: MOBILE_REGEX.test(ua),
+    };
+    return cachedBrowserInfo;
+  }
+  const chromeMatch = ua.match(CHROME_REGEX);
+  if (chromeMatch && chromeMatch[1]) {
+    cachedBrowserInfo = {
+      name: 'chrome', version: parseInt(chromeMatch[1], 10),
+      isSafari: false, isFirefox: false, isChrome: true, isEdge: false,
+      isMobile: MOBILE_REGEX.test(ua),
+    };
+    return cachedBrowserInfo;
+  }
+  cachedBrowserInfo = {
+    name: 'unknown', version: 0,
+    isSafari: false, isFirefox: false, isChrome: false, isEdge: false,
+    isMobile: MOBILE_REGEX.test(ua),
+  };
+  return cachedBrowserInfo;
+}
+
+/**
+ * 判断当前浏览器是否为 Safari(基于 UA 嗅探)。
+ *
+ * 用于已知 Safari 版本的特定 workaround,如:
+ * - Safari 16.4 以下不支持 createImageBitmap resize 选项
+ * - Safari 的 OffscreenCanvas 在 Worker 中行为不一致
+ *
+ * 优先用 detectBrowserCapabilities().offscreenCanvas 等能力检测。
+ */
+export function isSafari(): boolean {
+  return detectBrowserInfo().isSafari;
+}
+
+/**
+ * 判断当前浏览器是否为 Firefox(基于 UA 嗅探)。
+ *
+ * 用于 Firefox 特定 workaround(如某些 CSS / API 差异)。
+ * 优先用 detectBrowserCapabilities() 检测实际能力。
+ */
+export function isFirefox(): boolean {
+  return detectBrowserInfo().isFirefox;
+}
+
+/** 测试专用:重置缓存(确保下次 detectBrowserXxx 重新探测) */
+export function _resetBrowserDetectCache(): void {
+  cachedCapabilities = undefined;
+  cachedBrowserInfo = undefined;
+}