@microbt/pwa 0.0.0-stage → 0.1.0

package/dist/esm/shared/chunk-error-recovery.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ChunkLoadError 应用层兜底（白屏的最后一道防线）。
+ *
+ * SW 侧已做缓存准入校验与生命周期对齐，但 chunk 加载失败仍可能发生
+ * （弱网、CDN 旧版本清理、HTML 与 chunk 版本错配）。这里监听三类信号：
+ * 1. 本应用 script/stylesheet 加载失败（error 不冒泡，必须捕获阶段监听）；
+ * 2. 运行时错误消息命中 ChunkLoadError 特征；
+ * 3. 动态 import 的 unhandledrejection（webpack/vite 的 chunk 失败形态）。
+ * 防死循环：时间窗内只允许自动刷新一次；离线时刷新无意义，交给
+ * SW/Native 缓存兜底，不刷新。
+ *
+ * 遥测通过 bootstrap 注入同步回调，不再为了记日志动态下载 chunk。
+ * 刷新前发送仍可能丢失；sessionStorage 留下脱敏记录，下一次 bootstrap 补报重新进入。
+ * ROUTE-READY 只证明刷新后的路由 Suspense 边界已提交，不保证所有业务请求成功。
+ * 入口 JS 自身无法运行时仍无法观测，不能把没有结果记录当作恢复成功。
+ *
+ * 完成信号的语义分层（console-master 双层探针，与 support-center 单探针不同）：
+ * - ROUTE-READY：本地静态路由页面（/login、/settings 等）的叶子组件已提交；
+ * - MICRO-APP-READY：qiankun 子应用 entry 加载+执行+挂载完成（afterMount），
+ *   不保证子应用内部异步资源全部成功；
+ * - ROUTE-REDIRECTED：恢复目标已变更/失效（典型：恢复中跳登录页、切换到
+ *   其他页面、超期），不结算为原页面恢复成功。路由监听在首次离开待恢复
+ *   路径时立即结算并清空记录，之后返回原路径不恢复——qiankun 切页不取消
+ *   未完成挂载，迟到 afterMount 到达时 previous 已空，不会误归因。
+ *
+ * 注意：依赖链不得含加载期读 window/document 的模块。
+ */
+type RecoverySource = 'resource' | 'runtime' | 'rejection';
+type RecoveryOutcome = 'RELOAD' | 'SKIP-OFFLINE' | 'SKIP-GUARD' | 'SKIP-STORAGE' | 'REENTERED' | 'ROUTE-READY' | 'MICRO-APP-READY' | 'ROUTE-REDIRECTED' | 'RECURRED';
+export type RecoveryCompletionKind = 'page' | 'micro-app';
+interface RecoveryAttempt {
+    attemptId: string;
+    at: number;
+    page: string;
+    resource: string;
+    source: RecoverySource;
+}
+export interface ChunkRecoveryEvent extends RecoveryAttempt {
+    outcome: RecoveryOutcome;
+    occurredAt: number;
+    observedResource?: string;
+    observedSource?: RecoverySource;
+}
+/** 由完成探针调用：本地叶子路由传 'page'，qiankun afterMount 传 'micro-app'。 */
+export declare function markChunkRecoveryRouteReady(kind?: RecoveryCompletionKind): void;
+export declare function isChunkErrorMessage(message: string): boolean;
+export declare function isChunkErrorReason(reason: unknown): boolean;
+/** 防死循环闸门：时间窗内只允许自动刷新一次；通过则记录本次时间 */
+export declare function shouldReloadForChunkError(storage: Pick<Storage, 'getItem' | 'setItem'>, now: number): boolean;
+export declare function setupChunkErrorRecovery(report?: (event: ChunkRecoveryEvent) => void): (() => void) | undefined;
+export {};

package/dist/esm/shared/chunk-error-recovery.js

@@ -0,0 +1,225 @@
+// src/shared/chunk-error-recovery.ts
+import { createChunkDiagnosticId, sanitizeChunkUrl } from "./chunk-diagnostics";
+var RELOAD_GUARD_KEY = "chunk-error-last-reload-at";
+var RELOAD_GUARD_MS = 60 * 1e3;
+var PENDING_KEY = "chunk-error-pending-recovery";
+var PENDING_TTL_MS = 5 * 60 * 1e3;
+var reportRouteReady = () => {
+};
+function markChunkRecoveryRouteReady(kind = "page") {
+  reportRouteReady(kind);
+}
+var CHUNK_ERROR_PATTERN = /ChunkLoadError|CSS_CHUNK_LOAD_FAILED|Loading (?:CSS )?chunk \S+ failed|error loading dynamically imported module/i;
+function isChunkErrorMessage(message) {
+  return CHUNK_ERROR_PATTERN.test(message);
+}
+function isChunkErrorReason(reason) {
+  if (reason && typeof reason === "object") {
+    const { message, code, name } = reason;
+    return code === "CSS_CHUNK_LOAD_FAILED" || name === "ChunkLoadError" || typeof message === "string" && isChunkErrorMessage(message);
+  }
+  return typeof reason === "string" && isChunkErrorMessage(reason);
+}
+function safeUrl(value) {
+  return sanitizeChunkUrl(value, window.location.href);
+}
+function readPending(raw, now) {
+  const pending = JSON.parse(raw);
+  if (!pending || typeof pending !== "object" || Array.isArray(pending))
+    return;
+  const value = pending;
+  if (typeof value.at !== "number" || !Number.isFinite(value.at) || value.at <= 0 || now - value.at < 0 || now - value.at >= PENDING_TTL_MS || typeof value.page !== "string" || typeof value.resource !== "string" || value.source !== "resource" && value.source !== "runtime" && value.source !== "rejection" || value.attemptId !== void 0 && (typeof value.attemptId !== "string" || !/^[a-zA-Z0-9_-]{1,80}$/.test(value.attemptId)))
+    return;
+  const page = safeUrl(value.page);
+  if (!page || page !== safeUrl(window.location.href))
+    return;
+  return {
+    attemptId: value.attemptId ?? createChunkDiagnosticId(),
+    at: value.at,
+    page,
+    resource: value.resource ? safeUrl(value.resource) : "",
+    source: value.source
+  };
+}
+function reasonResource(reason) {
+  var _a;
+  const error = reason;
+  if (error && typeof error.request === "string")
+    return safeUrl(error.request);
+  const message = typeof (error == null ? void 0 : error.message) === "string" ? error.message : typeof reason === "string" ? reason : "";
+  const url = (_a = message.match(/https?:\/\/[^\s)]+/)) == null ? void 0 : _a[0];
+  return url ? safeUrl(url) : "";
+}
+function shouldReloadForChunkError(storage, now) {
+  const last = Number(storage.getItem(RELOAD_GUARD_KEY) ?? 0);
+  if (Number.isFinite(last) && last > 0 && now - last < RELOAD_GUARD_MS) {
+    return false;
+  }
+  storage.setItem(RELOAD_GUARD_KEY, String(now));
+  return true;
+}
+function setupChunkErrorRecovery(report = () => {
+}) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  const emit = (outcome, attempt, observed) => {
+    try {
+      report({ ...attempt, ...observed, outcome, occurredAt: Date.now() });
+    } catch {
+    }
+  };
+  let previous;
+  try {
+    const raw = window.sessionStorage.getItem(PENDING_KEY);
+    if (raw) {
+      window.sessionStorage.removeItem(PENDING_KEY);
+      const navigation = performance.getEntriesByType("navigation")[0];
+      if ((navigation == null ? void 0 : navigation.type) === "reload") {
+        previous = readPending(raw, Date.now());
+        if (previous)
+          emit("REENTERED", previous);
+      }
+    }
+  } catch {
+  }
+  let current = previous;
+  let currentExpiresAt = current ? current.at + RELOAD_GUARD_MS : 0;
+  if (current) {
+    try {
+      const lastReloadAt = Number(window.sessionStorage.getItem(RELOAD_GUARD_KEY));
+      if (Number.isFinite(lastReloadAt) && lastReloadAt > 0) {
+        currentExpiresAt = Math.max(currentExpiresAt, lastReloadAt + RELOAD_GUARD_MS);
+      }
+    } catch {
+    }
+  }
+  const settle = (kind) => {
+    if (!previous) {
+      return;
+    }
+    const settled = previous;
+    previous = void 0;
+    if (kind === "redirected") {
+      emit("ROUTE-REDIRECTED", settled);
+      return;
+    }
+    const age = Date.now() - settled.at;
+    if (age >= 0 && age < PENDING_TTL_MS && safeUrl(window.location.href) === settled.page) {
+      emit(kind === "micro-app" ? "MICRO-APP-READY" : "ROUTE-READY", settled);
+    } else {
+      emit("ROUTE-REDIRECTED", settled);
+    }
+  };
+  reportRouteReady = (kind) => settle(kind);
+  let active = true;
+  const handleLocationChange = () => {
+    if (!active)
+      return;
+    if (previous && safeUrl(window.location.href) !== previous.page) {
+      settle("redirected");
+    }
+  };
+  const originalPushState = typeof history !== "undefined" ? history.pushState : void 0;
+  const originalReplaceState = typeof history !== "undefined" ? history.replaceState : void 0;
+  let pushStateWrapper;
+  let replaceStateWrapper;
+  if (originalPushState && originalReplaceState) {
+    pushStateWrapper = function(...args) {
+      const result = originalPushState.apply(this, args);
+      handleLocationChange();
+      return result;
+    };
+    replaceStateWrapper = function(...args) {
+      const result = originalReplaceState.apply(this, args);
+      handleLocationChange();
+      return result;
+    };
+    history.pushState = pushStateWrapper;
+    history.replaceState = replaceStateWrapper;
+    window.addEventListener("popstate", handleLocationChange);
+  }
+  const recover = (source, resource = "") => {
+    const now = Date.now();
+    const observed = { observedSource: source, observedResource: resource };
+    if (previous) {
+      current = previous;
+      emit("RECURRED", previous, observed);
+      previous = void 0;
+    } else if (!current || now >= currentExpiresAt) {
+      current = {
+        attemptId: createChunkDiagnosticId(),
+        at: now,
+        page: safeUrl(window.location.href),
+        source,
+        resource
+      };
+      currentExpiresAt = now + RELOAD_GUARD_MS;
+    }
+    const attempt = current;
+    const observation = attempt.source !== source || attempt.resource !== resource ? observed : void 0;
+    if (!navigator.onLine) {
+      emit("SKIP-OFFLINE", attempt, observation);
+      return;
+    }
+    try {
+      if (!shouldReloadForChunkError(window.sessionStorage, now)) {
+        emit("SKIP-GUARD", attempt, observation);
+        return;
+      }
+      currentExpiresAt = now + RELOAD_GUARD_MS;
+      window.sessionStorage.setItem(PENDING_KEY, JSON.stringify(attempt));
+    } catch {
+      emit("SKIP-STORAGE", attempt, observation);
+      return;
+    }
+    emit("RELOAD", attempt, observation);
+    window.location.reload();
+  };
+  const onError = (event) => {
+    const target = event.target;
+    if (target instanceof HTMLScriptElement || target instanceof HTMLLinkElement && target.rel === "stylesheet") {
+      const url = target instanceof HTMLScriptElement ? target.src : target.href;
+      const assetBase = new URL(window.publicPath || "/", window.location.href);
+      const asset = new URL(url, window.location.href);
+      if (asset.origin === assetBase.origin && asset.pathname.startsWith(assetBase.pathname) && /\.(?:js|css)$/i.test(asset.pathname)) {
+        recover("resource", safeUrl(url));
+      }
+      return;
+    }
+    if (typeof event.message === "string" && isChunkErrorMessage(event.message)) {
+      recover("runtime", reasonResource(event));
+    }
+  };
+  const onRejection = (event) => {
+    const reason = event.reason;
+    if (isChunkErrorReason(reason)) {
+      recover("rejection", reasonResource(reason));
+    }
+  };
+  window.addEventListener("error", onError, true);
+  window.addEventListener("unhandledrejection", onRejection);
+  return () => {
+    active = false;
+    window.removeEventListener("error", onError, true);
+    window.removeEventListener("unhandledrejection", onRejection);
+    if (originalPushState && originalReplaceState) {
+      window.removeEventListener("popstate", handleLocationChange);
+      if (pushStateWrapper && history.pushState === pushStateWrapper) {
+        history.pushState = originalPushState;
+      }
+      if (replaceStateWrapper && history.replaceState === replaceStateWrapper) {
+        history.replaceState = originalReplaceState;
+      }
+    }
+    reportRouteReady = () => {
+    };
+  };
+}
+export {
+  isChunkErrorMessage,
+  isChunkErrorReason,
+  markChunkRecoveryRouteReady,
+  setupChunkErrorRecovery,
+  shouldReloadForChunkError
+};

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;