@microbt/pwa 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @microbt/pwa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+帮助中心（cinmoore-support-center 0.15.16）的 Service Worker 运行时与页面端注册，原样抽成的 npm 包。行为契约与原实现逐字一致（缓存名、消息类型、注册地址格式、计数名、退避参数）。
+
+## 安装
+
+```bash
+pnpm add @microbt/pwa
+```
+
+需要 peer 依赖 `@microbt/environment`（ARMS 上报）。构建侧仍由接入方自备 workbox 的 `InjectManifest` 插件（配置不用改，见下）。
+
+三个入口：`.`（页面端注册）、`./protocol`（诊断协议，纯常量与纯函数，依赖链不含 `@microbt/environment`）、`./sw`（SW 端运行时）。
+
+## 接入
+
+**1. SW 侧**：`src/sw.ts` 三行写法（`InjectManifest` 仍由接入方配置，注入点保持在接入方产物中，包内不含 `__WB_MANIFEST`）：
+
+```ts
+import { setupServiceWorker } from '@microbt/pwa/sw';
+
+declare const RELEASE: string;
+console.log(self.__WB_MANIFEST); // InjectManifest 注入点，保留原样
+setupServiceWorker({ release: typeof RELEASE === 'undefined' ? '' : RELEASE });
+```
+
+**2. 页面侧**（如 `bootstrap.ts`，原 `schedulePwaRegistration()` 无参调用改为传参）：
+
+```ts
+import { schedulePwaRegistration } from '@microbt/pwa';
+
+schedulePwaRegistration({ version: RELEASE, log });
+```
+
+**3. 协议符号**（诊断协议 `CHUNK_TRACE_MESSAGE`、`sanitizeChunkUrl`、`createChunkDiagnosticId`、`type ChunkRequestTrace`）从子入口导入：
+
+```ts
+import { CHUNK_TRACE_MESSAGE } from '@microbt/pwa/protocol';
+```
+
+## 行为契约
+
+以下字符串/参数与帮助中心 0.15.16 一字不差：
+
+- 缓存名前缀 `cache-pages-`、`cache-static-assets-`、`cache-js-css-`；激活时 `caches.delete('pages')`
+- 消息类型 `SW_ERROR`、`SW_UNHANDLED_REJECTION`、`SW_CHUNK_REQUEST_TRACE`
+- 注册地址 `/sw.js?baseUrl=<CDN 版本目录>&v=<构建版本>`（`v` 随构建版本变化是离线 SW 更新通道）
+- 计数名 `PWA-*` 全系；行为名 `pwa-register-retry`（退避 30s → 2min → 8min，共 3 次）
+- 导航请求 networkTimeoutSeconds 3；`requestIdleCallback` 超时 3000ms
+- `schedulePwaRegistration` 单例语义：同一页面第二次调用不重复调度
+
+## 开发
+
+```bash
+pnpm install
+pnpm test     # vitest run
+pnpm build    # father build（dist/esm）
+pnpm lint     # eslint
+```

package/dist/esm/index.d.ts

@@ -0,0 +1,2 @@
+export { schedulePwaRegistration } from './shared/pwa';
+export { SW_REJECTION_METRICS } from './sw-error-filter';

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+// src/index.ts
+import { schedulePwaRegistration } from "./shared/pwa";
+import { SW_REJECTION_METRICS } from "./sw-error-filter";
+export {
+  SW_REJECTION_METRICS,
+  schedulePwaRegistration
+};

package/dist/esm/protocol.d.ts

@@ -0,0 +1,2 @@
+export { CHUNK_TRACE_MESSAGE, createChunkDiagnosticId, sanitizeChunkUrl, } from './shared/chunk-diagnostics';
+export type { ChunkRequestTrace } from './shared/chunk-diagnostics';

package/dist/esm/protocol.js

@@ -0,0 +1,11 @@
+// src/protocol.ts
+import {
+  CHUNK_TRACE_MESSAGE,
+  createChunkDiagnosticId,
+  sanitizeChunkUrl
+} from "./shared/chunk-diagnostics";
+export {
+  CHUNK_TRACE_MESSAGE,
+  createChunkDiagnosticId,
+  sanitizeChunkUrl
+};

package/dist/esm/shared/chunk-diagnostics.d.ts

@@ -0,0 +1,26 @@
+/** 页面与 SW 共用的有限、脱敏诊断协议；不携带请求头、正文或查询参数。 */
+export interface ChunkRequestTrace {
+    requestId: string;
+    at: number;
+    completedAt?: number;
+    resource: string;
+    phase: 'response' | 'complete';
+    destination: string;
+    mode: string;
+    credentials: string;
+    cache: 'hit' | 'miss' | 'unknown';
+    network: 'pending' | 'response' | 'error';
+    networkStatus?: number;
+    networkType?: string;
+    networkMime?: string;
+    responseStatus?: number;
+    responseType?: string;
+    responseMime?: string;
+    servedFrom?: 'cache' | 'network' | 'none';
+    errorName?: string;
+    swRelease: string;
+}
+export declare const CHUNK_TRACE_MESSAGE = "SW_CHUNK_REQUEST_TRACE";
+/** URL 凭证、query、hash 均不出本地；未知协议不记录。 */
+export declare function sanitizeChunkUrl(value: string, base?: string): string;
+export declare function createChunkDiagnosticId(): string;

package/dist/esm/shared/chunk-diagnostics.js

@@ -0,0 +1,18 @@
+// src/shared/chunk-diagnostics.ts
+var CHUNK_TRACE_MESSAGE = "SW_CHUNK_REQUEST_TRACE";
+function sanitizeChunkUrl(value, base) {
+  try {
+    const url = new URL(value, base);
+    return /^https?:$/.test(url.protocol) ? `${url.origin}${url.pathname}`.slice(0, 512) : "";
+  } catch {
+    return "";
+  }
+}
+function createChunkDiagnosticId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+export {
+  CHUNK_TRACE_MESSAGE,
+  createChunkDiagnosticId,
+  sanitizeChunkUrl
+};

package/dist/esm/shared/pwa-registration-telemetry.d.ts

@@ -0,0 +1,4 @@
+export type RegistrationStage = 'load-workbox' | 'resolve-url' | 'register-sw';
+export declare function registrationErrorMessage(reason: unknown): string;
+export declare function createRegistrationError(reason: unknown, stage: RegistrationStage): Error;
+export declare function countRegistrationFailure(stage: RegistrationStage): void;

package/dist/esm/shared/pwa-registration-telemetry.js

@@ -0,0 +1,38 @@
+// src/shared/pwa-registration-telemetry.ts
+import { arms } from "@microbt/environment";
+var STAGE_COUNTERS = {
+  "load-workbox": "PWA-REGISTER-FAILED-LOAD-WORKBOX",
+  "resolve-url": "PWA-REGISTER-FAILED-RESOLVE-URL",
+  "register-sw": "PWA-REGISTER-FAILED-REGISTER-SW"
+};
+function registrationErrorMessage(reason) {
+  if (reason instanceof Error && reason.message)
+    return reason.message;
+  if (typeof reason === "string" && reason.trim())
+    return reason;
+  if (reason && typeof reason === "object" && "message" in reason) {
+    try {
+      if (typeof reason.message === "string" && reason.message.trim()) {
+        return reason.message;
+      }
+    } catch {
+    }
+  }
+  return "Unknown registration failure";
+}
+function createRegistrationError(reason, stage) {
+  const error = new Error(`PWA Register Error [${stage}]: ${registrationErrorMessage(reason)}`, {
+    cause: reason
+  });
+  error.name = "ServiceWorkerRegistrationError";
+  return error;
+}
+function countRegistrationFailure(stage) {
+  arms.sum("PWA-REGISTER-FAILED");
+  arms.sum(STAGE_COUNTERS[stage]);
+}
+export {
+  countRegistrationFailure,
+  createRegistrationError,
+  registrationErrorMessage
+};

package/dist/esm/shared/pwa-retry.d.ts

@@ -0,0 +1,26 @@
+import type { PwaLog } from './pwa';
+/**
+ * SW 注册失败的重试调度与上报去重。
+ * - 退避重试：仅提供恢复机会，实际恢复以成功注册为准
+ * - 会话内去重上报：网关故障期间每个 PV 刷新都会注册失败，不去重会按
+ *   PV 刷出大量重复 error（实测 8 天 8865 条 / 5656 用户）
+ */
+export declare class SwRegistrationRetry {
+    private readonly isRegistrationCompleted;
+    private readonly retryRegistration;
+    private readonly log;
+    private retryCount;
+    private retryHandle;
+    private waitingForReadiness;
+    private stopped;
+    private firstFailureAt;
+    constructor(isRegistrationCompleted: () => boolean, retryRegistration: () => void, log: PwaLog);
+    reportErrorOnce(error: Error): void;
+    scheduleRetry(): void;
+    private runWhenReady;
+    private handleReadiness;
+    private detachReadiness;
+    private reportOutcome;
+    stop(): void;
+    onSuccess(): void;
+}

package/dist/esm/shared/pwa-retry.js

@@ -0,0 +1,133 @@
+// src/shared/pwa-retry.ts
+import { arms } from "@microbt/environment";
+import { sanitizeChunkUrl } from "./chunk-diagnostics";
+var RETRY_DELAYS_MS = [3e4, 12e4, 48e4];
+var BEHAVIOR_NAME = "pwa-register-retry";
+function reportRetryBehavior(detail) {
+  var _a;
+  const logger = window.__bl;
+  try {
+    if (typeof (logger == null ? void 0 : logger.addBehavior) === "function" && typeof logger.reportBehavior === "function") {
+      logger.addBehavior({
+        data: {
+          name: BEHAVIOR_NAME,
+          message: JSON.stringify(detail)
+        },
+        // URL 凭证、query、hash 不出本地：page 只带 origin+pathname。
+        page: sanitizeChunkUrl(((_a = window.location) == null ? void 0 : _a.href) ?? "")
+      });
+      logger.reportBehavior();
+    }
+  } catch {
+  }
+}
+var SwRegistrationRetry = class {
+  constructor(isRegistrationCompleted, retryRegistration, log) {
+    this.isRegistrationCompleted = isRegistrationCompleted;
+    this.retryRegistration = retryRegistration;
+    this.log = log;
+    this.retryCount = 0;
+    this.retryHandle = null;
+    this.waitingForReadiness = false;
+    this.stopped = false;
+    this.firstFailureAt = null;
+    this.runWhenReady = () => {
+      if (this.stopped || this.isRegistrationCompleted()) {
+        this.stop();
+        return;
+      }
+      if (document.visibilityState !== "visible" || !navigator.onLine) {
+        if (!this.waitingForReadiness) {
+          this.waitingForReadiness = true;
+          window.addEventListener("online", this.handleReadiness);
+          document.addEventListener("visibilitychange", this.handleReadiness);
+        }
+        return;
+      }
+      this.detachReadiness();
+      this.retryCount += 1;
+      this.log(`Service Worker registration retry #${this.retryCount}`);
+      this.retryRegistration();
+    };
+    this.handleReadiness = () => {
+      if (this.waitingForReadiness)
+        this.runWhenReady();
+    };
+  }
+  reportErrorOnce(error) {
+    const key = `pwa-register-error:${error.message}`;
+    try {
+      if (window.sessionStorage.getItem(key) !== null) {
+        return;
+      }
+      window.sessionStorage.setItem(key, "1");
+    } catch {
+    }
+    arms.error(error);
+  }
+  scheduleRetry() {
+    if (this.stopped || this.isRegistrationCompleted()) {
+      this.stop();
+      return;
+    }
+    this.firstFailureAt ??= Date.now();
+    if (this.retryCount >= RETRY_DELAYS_MS.length) {
+      this.stop();
+      this.reportOutcome("exhausted", "PWA-REGISTER-RETRY-EXHAUSTED");
+      return;
+    }
+    if (this.retryHandle !== null || this.waitingForReadiness) {
+      return;
+    }
+    const delay = RETRY_DELAYS_MS[this.retryCount];
+    this.retryHandle = window.setTimeout(() => {
+      this.retryHandle = null;
+      this.runWhenReady();
+    }, delay);
+  }
+  detachReadiness() {
+    if (!this.waitingForReadiness)
+      return;
+    this.waitingForReadiness = false;
+    window.removeEventListener("online", this.handleReadiness);
+    document.removeEventListener("visibilitychange", this.handleReadiness);
+  }
+  reportOutcome(outcome, counter) {
+    const detail = {
+      outcome,
+      attempts: this.retryCount + 1,
+      elapsedMs: Date.now() - (this.firstFailureAt ?? Date.now())
+    };
+    for (const report of [
+      () => arms.sum(counter),
+      () => reportRetryBehavior(detail),
+      () => this.log(
+        `Service Worker retry ${outcome}: attempts=${detail.attempts}, elapsedMs=${detail.elapsedMs}`
+      )
+    ]) {
+      try {
+        report();
+      } catch {
+      }
+    }
+  }
+  stop() {
+    this.stopped = true;
+    if (this.retryHandle !== null) {
+      window.clearTimeout(this.retryHandle);
+      this.retryHandle = null;
+    }
+    this.detachReadiness();
+  }
+  onSuccess() {
+    if (this.stopped)
+      return;
+    this.stop();
+    if (this.retryCount > 0) {
+      this.reportOutcome("recovered", "PWA-REGISTER-RETRY-SUCCESS");
+    }
+  }
+};
+export {
+  SwRegistrationRetry
+};

package/dist/esm/shared/pwa.d.ts

@@ -0,0 +1,5 @@
+export type PwaLog = (message: string, ...args: unknown[]) => void;
+export declare const schedulePwaRegistration: (options: {
+    version: string;
+    log: PwaLog;
+}) => void;

package/dist/esm/shared/pwa.js

@@ -0,0 +1,231 @@
+// src/shared/pwa.ts
+import { arms } from "@microbt/environment";
+import {
+  countRegistrationFailure,
+  createRegistrationError,
+  registrationErrorMessage
+} from "./pwa-registration-telemetry";
+import { SwRegistrationRetry } from "./pwa-retry";
+import { removeInvalidRegistrations, resolveSwRegisterUrl } from "./sw-registration";
+var PwaRegistrationScheduler = class {
+  constructor(options) {
+    this.options = options;
+    this.scheduleStarted = false;
+    this.firstPaintQueued = false;
+    this.registrationCompleted = false;
+    this.registrationInFlight = null;
+    this.idleHandle = null;
+    this.timeoutHandle = null;
+    this.visibilityListenerAttached = false;
+    this.onlineListenerAttached = false;
+    this.retry = new SwRegistrationRetry(
+      () => this.registrationCompleted,
+      () => {
+        void this.registerServiceWorker();
+      },
+      (message, ...args) => this.options.log(message, ...args)
+    );
+    this.clearPendingRegistrationTask = () => {
+      const idleWindow = this.getIdleWindow();
+      if (this.idleHandle !== null && idleWindow.cancelIdleCallback) {
+        idleWindow.cancelIdleCallback(this.idleHandle);
+        this.idleHandle = null;
+      }
+      if (this.timeoutHandle !== null) {
+        window.clearTimeout(this.timeoutHandle);
+        this.timeoutHandle = null;
+      }
+    };
+    this.detachReadinessListeners = () => {
+      if (this.visibilityListenerAttached) {
+        document.removeEventListener("visibilitychange", this.handleReadinessChange);
+        this.visibilityListenerAttached = false;
+      }
+      if (this.onlineListenerAttached) {
+        window.removeEventListener("online", this.handleReadinessChange);
+        this.onlineListenerAttached = false;
+      }
+    };
+    this.attachReadinessListeners = () => {
+      if (!this.visibilityListenerAttached) {
+        document.addEventListener("visibilitychange", this.handleReadinessChange);
+        this.visibilityListenerAttached = true;
+      }
+      if (!this.onlineListenerAttached) {
+        window.addEventListener("online", this.handleReadinessChange);
+        this.onlineListenerAttached = true;
+      }
+    };
+    this.queueRegistrationWhenIdle = () => {
+      if (this.registrationCompleted || this.registrationInFlight) {
+        this.detachReadinessListeners();
+        return;
+      }
+      if (document.visibilityState !== "visible" || !navigator.onLine) {
+        this.waitUntilPageReady();
+        return;
+      }
+      if (this.idleHandle !== null || this.timeoutHandle !== null) {
+        return;
+      }
+      const runRegistration = () => {
+        this.idleHandle = null;
+        this.timeoutHandle = null;
+        if (document.visibilityState !== "visible" || !navigator.onLine) {
+          this.waitUntilPageReady();
+          return;
+        }
+        void this.registerServiceWorker();
+      };
+      const idleWindow = this.getIdleWindow();
+      if (idleWindow.requestIdleCallback) {
+        this.idleHandle = idleWindow.requestIdleCallback(runRegistration, {
+          timeout: 3e3
+        });
+        return;
+      }
+      this.timeoutHandle = window.setTimeout(runRegistration, 3e3);
+    };
+    this.scheduleAfterFirstPaint = () => {
+      if (this.firstPaintQueued || this.registrationCompleted || this.registrationInFlight) {
+        return;
+      }
+      this.firstPaintQueued = true;
+      window.requestAnimationFrame(() => {
+        window.requestAnimationFrame(() => {
+          this.firstPaintQueued = false;
+          this.queueRegistrationWhenIdle();
+        });
+      });
+    };
+    this.waitUntilPageReady = () => {
+      this.clearPendingRegistrationTask();
+      if (document.visibilityState === "visible" && navigator.onLine) {
+        this.detachReadinessListeners();
+        this.scheduleAfterFirstPaint();
+        return;
+      }
+      this.attachReadinessListeners();
+    };
+    this.handleReadinessChange = () => {
+      if (this.registrationCompleted || this.registrationInFlight) {
+        this.detachReadinessListeners();
+        return;
+      }
+      this.waitUntilPageReady();
+    };
+    this.registerServiceWorker = async () => {
+      if (this.registrationCompleted) {
+        return;
+      }
+      if (this.registrationInFlight) {
+        await this.registrationInFlight;
+        return;
+      }
+      this.registrationInFlight = (async () => {
+        var _a;
+        let swRegisterUrl = null;
+        let stage = "load-workbox";
+        try {
+          const { Workbox } = await import("workbox-window");
+          stage = "resolve-url";
+          swRegisterUrl = await resolveSwRegisterUrl({
+            version: this.options.version
+          });
+          stage = "register-sw";
+          const wb = new Workbox(swRegisterUrl);
+          const startTime = +/* @__PURE__ */ new Date();
+          wb.addEventListener("installed", () => {
+            const endTime = +/* @__PURE__ */ new Date();
+            this.options.log(
+              `Service Worker installed:${endTime}, time taken:${endTime - startTime}`
+            );
+          });
+          wb.addEventListener("activated", () => {
+            this.options.log(
+              `Service Worker activated:${+/* @__PURE__ */ new Date()}, online status: ${navigator.onLine}`
+            );
+            if (!navigator.onLine) {
+              arms.sum("PWA-ACTIVATED-OFFLINE");
+            }
+          });
+          wb.addEventListener("controlling", () => {
+            this.options.log(`Service Worker has taken control of the current client:${+/* @__PURE__ */ new Date()}`);
+          });
+          wb.addEventListener("waiting", () => {
+            this.options.log(`Service Worker is waiting:${+/* @__PURE__ */ new Date()}`);
+          });
+          const res = await wb.register();
+          this.options.log(
+            `Service Worker registration successful:${startTime}, state: ${(_a = res == null ? void 0 : res.active) == null ? void 0 : _a.state}, installing: ${res == null ? void 0 : res.installing}, host:${location.host}`
+          );
+          arms.sum("PWA-REGISTER-SUCCESS");
+          this.retry.onSuccess();
+          this.registrationCompleted = true;
+        } catch (e) {
+          if (this.shouldIgnoreError(e)) {
+            this.retry.stop();
+            this.options.log(
+              `Service Worker registration restricted (report ignored): ${registrationErrorMessage(
+                e
+              )}`
+            );
+            return;
+          }
+          const error = createRegistrationError(e, stage);
+          this.retry.reportErrorOnce(error);
+          countRegistrationFailure(stage);
+          this.retry.scheduleRetry();
+          this.options.log(`Service Worker registration failed: ${error.message}`, error);
+        } finally {
+          this.registrationInFlight = null;
+          this.clearPendingRegistrationTask();
+          this.detachReadinessListeners();
+        }
+        if (this.registrationCompleted && swRegisterUrl !== null) {
+          try {
+            await removeInvalidRegistrations(
+              swRegisterUrl,
+              (message, ...args) => this.options.log(message, ...args)
+            );
+          } catch (e) {
+            this.options.log(`清理历史 SW 注册失败（不影响本次注册）: ${e.message}`);
+          }
+        }
+      })();
+      await this.registrationInFlight;
+    };
+    this.schedule = () => {
+      if (this.scheduleStarted) {
+        return;
+      }
+      if (typeof window === "undefined" || typeof document === "undefined" || // WebView / opaque origin 下 serviceWorker 属性存在但值为 null，
+      // 必须用真值检查而非 'serviceWorker' in navigator
+      !navigator.serviceWorker) {
+        return;
+      }
+      this.scheduleStarted = true;
+      this.waitUntilPageReady();
+    };
+  }
+  shouldIgnoreError(error) {
+    const errorMessages = [
+      "Job rejected for non app-bound domain"
+      // iOS PWA注册限制错误
+      // 'The operation is insecure', // 某些浏览器安全限制错误
+      // 'Failed to register a ServiceWorker', // 通用注册失败错误
+    ];
+    return errorMessages.some((msg) => registrationErrorMessage(error).includes(msg));
+  }
+  getIdleWindow() {
+    return window;
+  }
+};
+var pwaRegistrationScheduler = null;
+var schedulePwaRegistration = (options) => {
+  pwaRegistrationScheduler ??= new PwaRegistrationScheduler(options);
+  pwaRegistrationScheduler.schedule();
+};
+export {
+  schedulePwaRegistration
+};

package/dist/esm/shared/sw-registration.d.ts

@@ -0,0 +1,11 @@
+import type { PwaLog } from './pwa';
+/** 解析本次应注册的 SW 地址（在线/离线/同构建复用，见 sw-script-url.ts） */
+export declare function resolveSwRegisterUrl(options: {
+    version: string;
+}): Promise<string>;
+/**
+ * 历史注册清理：注销与本次注册地址不同（规范化比较，消除绝对/相对差异）
+ * 的本站 /sw.js 注册。必须在 register 成功之后调用——若 register 失败
+ * 直接跳过，保证任何时候不把正在使用的注册注销掉。
+ */
+export declare function removeInvalidRegistrations(keepScriptUrl: string, log: PwaLog): Promise<void>;

package/dist/esm/shared/sw-registration.js

@@ -0,0 +1,35 @@
+// src/shared/sw-registration.ts
+import { isSameOriginSwScriptUrl, normalizeScriptUrl, resolveSwScriptUrl } from "./sw-script-url";
+function getRegistrationScriptUrl(registration) {
+  var _a, _b, _c;
+  return ((_a = registration.active) == null ? void 0 : _a.scriptURL) ?? ((_b = registration.waiting) == null ? void 0 : _b.scriptURL) ?? ((_c = registration.installing) == null ? void 0 : _c.scriptURL) ?? "";
+}
+async function resolveSwRegisterUrl(options) {
+  const publicPath = window.publicPath;
+  const registrations = await navigator.serviceWorker.getRegistrations();
+  const existingScriptUrls = registrations.map((registration) => getRegistrationScriptUrl(registration)).filter((scriptUrl) => scriptUrl !== "");
+  return resolveSwScriptUrl({
+    publicPath: typeof publicPath === "string" ? publicPath : void 0,
+    existingScriptUrls,
+    version: options.version,
+    pageOrigin: window.location.origin
+  });
+}
+async function removeInvalidRegistrations(keepScriptUrl, log) {
+  const pageOrigin = window.location.origin;
+  const keepUrl = normalizeScriptUrl(keepScriptUrl, pageOrigin);
+  const registrations = await navigator.serviceWorker.getRegistrations();
+  const staleRegistrations = registrations.filter((registration) => {
+    const scriptUrl = getRegistrationScriptUrl(registration);
+    return scriptUrl !== "" && normalizeScriptUrl(scriptUrl, pageOrigin) !== keepUrl && isSameOriginSwScriptUrl(scriptUrl, pageOrigin);
+  });
+  if (staleRegistrations.length === 0) {
+    return;
+  }
+  await Promise.all(staleRegistrations.map((registration) => registration.unregister()));
+  log(`已注销 ${staleRegistrations.length} 个非当前地址的 SW 注册`);
+}
+export {
+  removeInvalidRegistrations,
+  resolveSwRegisterUrl
+};

package/dist/esm/shared/sw-script-url.d.ts

@@ -0,0 +1,42 @@
+/**
+ * SW 注册地址（scriptURL）的构造与解析。
+ *
+ * 注册地址形如 `/sw.js?baseUrl=<CDN 版本目录>&v=<构建版本>`：
+ * - baseUrl：服务端转发层的版本路由参数（nginx location = /sw.js 按
+ *   $arg_baseUrl proxy_pass 到 CDN 版本目录取 sw.js），在线 HTML 由 render
+ *   服务注入 window.publicPath，离线包 HTML 无 publicPath，按设计兜底为
+ *   字面量 'undefined'，由 Native 按 path 命中本地包内 sw.js。
+ * - v：构建版本（RELEASE）。这是离线场景 SW 更新的关键通道——实测
+ *   Chrome 91 WebView 中，register() 携带新 scriptURL 的安装 fetch 会被
+ *   ServiceWorkerClient 拦截并命中 Native 本地包，而 update()/自然软更新
+ *   的 fetch 不经过任何 Java 拦截、直落 nginx（baseUrl=undefined 时 500）。
+ *   因此 scriptURL 必须随构建版本变化：新包的页面以新 URL 注册，经安装
+ *   通道取得新 SW 并接管；同构建重复打开时注册同一 URL，不触发重装。
+ */
+/** 按转发层认识的格式拼 SW 注册地址（含构建版本参数） */
+export declare function buildSwRegisterUrl(baseUrl: string, version: string): string;
+/** 解析注册地址中的构建版本参数；无 v 参数（历史注册）返回 null */
+export declare function getSwScriptVersion(scriptUrl: string, pageOrigin: string): string | null;
+/** 判定注册地址是否为本站 /sw.js（用于历史注册清理的范围判断） */
+export declare function isSameOriginSwScriptUrl(scriptUrl: string, pageOrigin: string): boolean;
+/** 用同一 origin 规范化注册地址，消除绝对/相对形式差异后比较 */
+export declare function normalizeScriptUrl(url: string, pageOrigin: string): string;
+/**
+ * 解析本次应注册的 SW 地址（纯函数，便于单测）：
+ * 1. 在线入口（publicPath 为协议相对或绝对 http(s) URL）：注册
+ *    baseUrl=publicPath 的当前构建地址，保持 nginx 版本转发链路。
+ * 2. 离线入口：若已有同构建版本（v 一致）的本站 /sw.js 注册——无论其
+ *    baseUrl 是 CDN 基址还是 undefined 兜底——原样复用其 scriptURL，
+ *    在线/离线交替打开时不重装、不产生 registration 抖动。
+ * 3. 其余情况（仅旧构建/无 v 历史注册，或无注册）：注册
+ *    baseUrl=undefined 兜底地址 + 当前构建 v。scriptURL 与历史注册不同，
+ *    触发安装 fetch（被 ServiceWorkerClient 拦截、命中 Native 当前包的
+ *    sw.js）完成离线 SW 更新；不回用旧构建的 CDN 基址，避免安装 fetch
+ *    未被拦截时从 CDN 取回旧版本脚本。
+ */
+export declare function resolveSwScriptUrl({ publicPath, existingScriptUrls, version, pageOrigin, }: {
+    publicPath: string | undefined;
+    existingScriptUrls: string[];
+    version: string;
+    pageOrigin: string;
+}): string;