@microbt/pwa 0.0.1 → 0.1.0

package/README.md

@@ -10,7 +10,7 @@ pnpm add @microbt/pwa
 
 需要 peer 依赖 `@microbt/environment`（ARMS 上报）。构建侧仍由接入方自备 workbox 的 `InjectManifest` 插件（配置不用改，见下）。
 
-三个入口：`.`（页面端注册）、`./protocol`（诊断协议，纯常量与纯函数，依赖链不含 `@microbt/environment`）、`./sw`（SW 端运行时）。
+四个入口：`.`（页面端注册）、`./protocol`（诊断协议，纯常量与纯函数，依赖链不含 `@microbt/environment`）、`./sw`（SW 端运行时）、`./recovery`（chunk 恢复与诊断上报，见下节）。
 
 ## 接入
 
@@ -38,6 +38,35 @@ schedulePwaRegistration({ version: RELEASE, log });
 import { CHUNK_TRACE_MESSAGE } from '@microbt/pwa/protocol';
 ```
 
+## chunk 恢复与诊断上报（`./recovery`）
+
+在 `bootstrap` 里尽早调用 `setupChunkErrorRecovery`，把恢复事件交给 `createChunkDiagnosticReporter`；ARMS 计数（`arms.sum`）由接入方回调自己做：
+
+```ts
+import { createChunkDiagnosticReporter, setupChunkErrorRecovery } from '@microbt/pwa/recovery';
+
+const reporter = createChunkDiagnosticReporter({
+  release: RELEASE,
+  appVersion: () => appVersion().version,
+});
+setupChunkErrorRecovery((event) => {
+  arms.sum(`CHUNK-RECOVERY-${event.outcome}`); // 计数留在接入方
+  reporter.report(event);
+});
+```
+
+完成信号探针由接入方写：Umi 叶子路由提交时调 `markChunkRecoveryRouteReady('page')`；qiankun 子应用 `afterMount` 调 `markChunkRecoveryRouteReady('micro-app')`。
+
+行为契约（以下字符串/数值一字不差）：
+
+- sessionStorage 键：`chunk-error-last-reload-at`、`chunk-error-pending-recovery`、`chunk-diagnostic-outbox-v1`
+- chunk 失败识别正则 `CHUNK_ERROR_PATTERN` 原文：`/ChunkLoadError|CSS_CHUNK_LOAD_FAILED|Loading (?:CSS )?chunk \S+ failed|error loading dynamically imported module/i`
+- reload 闸门 60 秒；待恢复记录 5 分钟；诊断有效期 5 分钟；发件箱 16 条、补发重试 30 次 × 1 秒；SW 请求记录 40 条；关联窗口 120 秒取最近 3 条；单条载荷 < 16,000 字符；去重集合上限 128
+- 结果名：`RELOAD`、`SKIP-OFFLINE`、`SKIP-GUARD`、`SKIP-STORAGE`、`REENTERED`、`ROUTE-READY`、`MICRO-APP-READY`、`ROUTE-REDIRECTED`、`RECURRED`；SW 侧 `SW-REQUEST`
+- ARMS：`custom` 的 `kind: 'chunk-diagnostic'`、`schema: 1`、`eventId`、`attemptId`、`outcome`、`replay`、`payload`；行为日志 `name: 'chunk-recovery'`、正文只有 `{id, outcome}`；`correlation: 'resource-time-window'`；`reconstructedFrom: 'REENTERED'`
+
+依赖链约束：`./recovery` 的依赖链（含 side-effect import）不含 `@microbt/environment`、任何 `workbox-*`，也不含模块加载期就读 `window`/`document` 的模块——它要在首屏最早加载，自己不能被别的依赖拖垮。
+
 ## 行为契约
 
 以下字符串/参数与帮助中心 0.15.16 一字不差：

package/dist/esm/recovery.d.ts

@@ -0,0 +1,3 @@
+export { createChunkDiagnosticReporter } from './shared/chunk-diagnostic-reporter';
+export { markChunkRecoveryRouteReady, setupChunkErrorRecovery, } from './shared/chunk-error-recovery';
+export type { ChunkRecoveryEvent, RecoveryCompletionKind } from './shared/chunk-error-recovery';

package/dist/esm/recovery.js

@@ -0,0 +1,11 @@
+// src/recovery.ts
+import { createChunkDiagnosticReporter } from "./shared/chunk-diagnostic-reporter";
+import {
+  markChunkRecoveryRouteReady,
+  setupChunkErrorRecovery
+} from "./shared/chunk-error-recovery";
+export {
+  createChunkDiagnosticReporter,
+  markChunkRecoveryRouteReady,
+  setupChunkErrorRecovery
+};

package/dist/esm/shared/chunk-diagnostic-outbox.d.ts

@@ -0,0 +1,13 @@
+export interface DiagnosticRecord {
+    eventId: string;
+    attemptId: string;
+    at: number;
+    outcome: string;
+    payload: string;
+}
+/** custom() 不提供服务端 ACK：当前记录保留到下个文档再发一次，由 eventId 去重。 */
+export declare function createDiagnosticOutbox(): {
+    has: (eventId: string) => boolean;
+    enqueue(record: DiagnosticRecord, replay?: boolean): void;
+    dispose(): void;
+};

package/dist/esm/shared/chunk-diagnostic-outbox.js

@@ -0,0 +1,137 @@
+// src/shared/chunk-diagnostic-outbox.ts
+import { DIAGNOSTIC_ID, DIAGNOSTIC_TTL, sanitizeStoredPayload } from "./chunk-diagnostic-payload";
+var OUTBOX_KEY = "chunk-diagnostic-outbox-v1";
+var MAX_RECORDS = 16;
+var OUTCOMES = /* @__PURE__ */ new Set([
+  "RELOAD",
+  "REENTERED",
+  "ROUTE-READY",
+  "MICRO-APP-READY",
+  "ROUTE-REDIRECTED",
+  "RECURRED",
+  "SKIP-OFFLINE",
+  "SKIP-GUARD",
+  "SKIP-STORAGE",
+  "SW-REQUEST"
+]);
+function restore() {
+  try {
+    const saved = JSON.parse(window.sessionStorage.getItem(OUTBOX_KEY) || "[]");
+    if (!Array.isArray(saved))
+      return [];
+    const records = [];
+    for (const r of saved.slice(-MAX_RECORDS)) {
+      try {
+        if (!r || typeof r.eventId !== "string" || !DIAGNOSTIC_ID.test(r.eventId) || typeof r.attemptId !== "string" || !DIAGNOSTIC_ID.test(r.attemptId) || !Number.isFinite(r.at) || Date.now() < r.at || Date.now() - r.at >= DIAGNOSTIC_TTL || !OUTCOMES.has(r.outcome) || typeof r.payload !== "string" || r.payload.length >= 16e3)
+          continue;
+        records.push({
+          eventId: r.eventId,
+          attemptId: r.attemptId,
+          at: r.at,
+          outcome: r.outcome,
+          payload: sanitizeStoredPayload(r.payload)
+        });
+      } catch {
+      }
+    }
+    return records;
+  } catch {
+    return [];
+  }
+}
+function createDiagnosticOutbox() {
+  const delivered = /* @__PURE__ */ new Set();
+  const breadcrumbs = /* @__PURE__ */ new Set();
+  let queue = restore();
+  const restored = new Set(queue.map((r) => r.eventId));
+  let timer;
+  let retries = 0;
+  let disposed = false;
+  const persist = () => {
+    try {
+      window.sessionStorage.setItem(OUTBOX_KEY, JSON.stringify(queue));
+    } catch {
+    }
+  };
+  const needsBehavior = (r) => r.outcome !== "SW-REQUEST" && !breadcrumbs.has(r.eventId);
+  const flush = () => {
+    if (disposed)
+      return;
+    queue = queue.filter((r) => Date.now() - r.at < DIAGNOSTIC_TTL && Date.now() >= r.at);
+    for (const record of queue) {
+      const logger = window.__bl;
+      try {
+        if (!delivered.has(record.eventId) && typeof (logger == null ? void 0 : logger.custom) === "function") {
+          logger.custom(
+            {
+              kind: "chunk-diagnostic",
+              schema: 1,
+              eventId: record.eventId,
+              attemptId: record.attemptId,
+              outcome: record.outcome,
+              replay: restored.has(record.eventId) ? 1 : 0,
+              payload: record.payload
+            },
+            1
+          );
+          delivered.add(record.eventId);
+        }
+      } catch {
+      }
+      try {
+        if (needsBehavior(record) && typeof (logger == null ? void 0 : logger.addBehavior) === "function" && typeof logger.reportBehavior === "function") {
+          logger.addBehavior({
+            data: {
+              name: "chunk-recovery",
+              message: JSON.stringify({
+                id: record.attemptId,
+                outcome: record.outcome
+              })
+            },
+            page: JSON.parse(record.payload).page || ""
+          });
+          logger.reportBehavior();
+          breadcrumbs.add(record.eventId);
+        }
+      } catch {
+      }
+    }
+    queue = queue.filter(
+      (r) => !(restored.has(r.eventId) && delivered.has(r.eventId) && !needsBehavior(r))
+    );
+    persist();
+    if (queue.some((r) => !delivered.has(r.eventId) || needsBehavior(r)) && retries < 30 && !timer) {
+      retries += 1;
+      timer = setTimeout(() => {
+        timer = void 0;
+        flush();
+      }, 1e3);
+    }
+    for (const set of [delivered, breadcrumbs, restored])
+      while (set.size > 128)
+        set.delete(set.values().next().value);
+  };
+  const has = (eventId) => delivered.has(eventId) || queue.some((r) => r.eventId === eventId);
+  flush();
+  return {
+    has,
+    enqueue(record, replay = false) {
+      if (disposed || has(record.eventId))
+        return;
+      if (replay)
+        restored.add(record.eventId);
+      queue = [...queue, record].slice(-MAX_RECORDS);
+      retries = 0;
+      persist();
+      flush();
+    },
+    dispose() {
+      disposed = true;
+      if (timer)
+        clearTimeout(timer);
+    }
+  };
+}
+export {
+  createDiagnosticOutbox
+};

package/dist/esm/shared/chunk-diagnostic-payload.d.ts

@@ -0,0 +1,17 @@
+import { type ChunkRequestTrace } from './chunk-diagnostics';
+export declare const DIAGNOSTIC_TTL: number;
+export declare const DIAGNOSTIC_ID: RegExp;
+/** 可选浏览器/WebView API 不可用时仍保留核心错误事件。 */
+export declare function diagnosticContext(release: string, appVersion: () => string): {
+    release: string;
+    appVersion: string;
+    online: boolean;
+    visibility: string;
+    swControlled: boolean;
+    swScript: string;
+    nativeResourceSource: string;
+};
+export declare function diagnosticTiming(resource: string, occurredAt: number): Record<string, string | number> | undefined;
+/** 消息和 storage 都只接受协议字段，不夹带 token、正文或任意扩展属性。 */
+export declare function readChunkTrace(value: unknown): ChunkRequestTrace | undefined;
+export declare function sanitizeStoredPayload(payload: string): string;

package/dist/esm/shared/chunk-diagnostic-payload.js

@@ -0,0 +1,162 @@
+// src/shared/chunk-diagnostic-payload.ts
+import { sanitizeChunkUrl } from "./chunk-diagnostics";
+var DIAGNOSTIC_TTL = 5 * 6e4;
+var DIAGNOSTIC_ID = /^[a-zA-Z0-9_-]{1,100}$/;
+var safeVersion = (value) => typeof value === "string" ? value.replace(/[^\w.-]/g, "").slice(0, 80) : "unknown";
+var visibility = (value) => value === "visible" || value === "hidden" ? value : "unknown";
+function diagnosticContext(release, appVersion) {
+  var _a;
+  let version = "unknown";
+  let controller;
+  try {
+    version = safeVersion(appVersion());
+  } catch {
+  }
+  try {
+    controller = (_a = navigator.serviceWorker) == null ? void 0 : _a.controller;
+  } catch {
+  }
+  return {
+    release: safeVersion(release),
+    appVersion: version,
+    online: navigator.onLine,
+    visibility: typeof document === "undefined" ? "unknown" : visibility(document.visibilityState),
+    swControlled: Boolean(controller),
+    swScript: controller ? sanitizeChunkUrl(controller.scriptURL) : "",
+    nativeResourceSource: "unavailable"
+  };
+}
+function safeTiming(value) {
+  const result = {
+    visibility: "may-be-redacted"
+  };
+  for (const key of [
+    "startTime",
+    "duration",
+    "transferSize",
+    "encodedBodySize",
+    "decodedBodySize",
+    "workerStart",
+    "status",
+    "completedAt"
+  ]) {
+    const number = value[key];
+    if (typeof number === "number" && Number.isFinite(number) && number >= 0)
+      result[key] = number;
+  }
+  if (typeof value.initiatorType === "string" && /^(link|script|css|fetch|other)$/.test(value.initiatorType))
+    result.initiatorType = value.initiatorType;
+  return result;
+}
+function diagnosticTiming(resource, occurredAt) {
+  var _a;
+  try {
+    const origin = performance.timeOrigin || ((_a = performance.timing) == null ? void 0 : _a.navigationStart);
+    if (!Number.isFinite(origin) || origin <= 0)
+      return void 0;
+    const entries = performance.getEntriesByType("resource");
+    const entry = entries.filter(
+      (e) => sanitizeChunkUrl(e.name) === resource && Number.isFinite(e.startTime) && Number.isFinite(e.duration) && Math.abs(origin + e.startTime + e.duration - occurredAt) < 12e4
+    ).pop();
+    if (!entry)
+      return void 0;
+    return safeTiming({
+      startTime: entry.startTime,
+      duration: entry.duration,
+      completedAt: origin + entry.startTime + entry.duration,
+      transferSize: entry.transferSize,
+      encodedBodySize: entry.encodedBodySize,
+      decodedBodySize: entry.decodedBodySize,
+      workerStart: entry.workerStart,
+      initiatorType: entry.initiatorType,
+      status: entry.responseStatus
+    });
+  } catch {
+    return void 0;
+  }
+}
+function readChunkTrace(value) {
+  if (!value || typeof value !== "object")
+    return;
+  const r = value;
+  if (typeof r.requestId !== "string" || !DIAGNOSTIC_ID.test(r.requestId) || !Number.isFinite(r.at) || Math.abs(Date.now() - r.at) > DIAGNOSTIC_TTL || !["response", "complete"].includes(r.phase))
+    return;
+  const resource = sanitizeChunkUrl(r.resource);
+  if (!resource)
+    return;
+  const result = {
+    requestId: r.requestId,
+    at: r.at,
+    resource,
+    phase: r.phase,
+    destination: ["script", "style"].includes(r.destination) ? r.destination : "unknown",
+    mode: ["cors", "no-cors", "same-origin"].includes(r.mode) ? r.mode : "unknown",
+    credentials: ["include", "omit", "same-origin"].includes(r.credentials) ? r.credentials : "unknown",
+    cache: ["hit", "miss"].includes(r.cache) ? r.cache : "unknown",
+    network: ["pending", "response", "error"].includes(r.network) ? r.network : "pending",
+    swRelease: safeVersion(r.swRelease)
+  };
+  for (const key of ["networkStatus", "responseStatus"])
+    if (Number.isInteger(r[key]) && r[key] >= 0 && r[key] <= 599)
+      result[key] = r[key];
+  if (Number.isFinite(r.completedAt) && r.completedAt >= r.at && r.completedAt <= Date.now() + 1e3)
+    result.completedAt = r.completedAt;
+  for (const key of ["networkType", "responseType"])
+    if (["basic", "cors", "default", "error", "opaque", "opaqueredirect"].includes(r[key] || ""))
+      result[key] = r[key];
+  for (const key of ["networkMime", "responseMime"]) {
+    const mime = typeof r[key] === "string" ? r[key].split(";", 1)[0].trim() : "";
+    if (/^[\w.+-]+\/[\w.+-]+$/.test(mime))
+      result[key] = mime.slice(0, 80);
+  }
+  if (/^(Error|TypeError|RangeError|AbortError|NetworkError|TimeoutError|SecurityError|InvalidStateError|QuotaExceededError|no-response)$/.test(
+    r.errorName || ""
+  ))
+    result.errorName = r.errorName;
+  if (["cache", "network", "none"].includes(r.servedFrom || ""))
+    result.servedFrom = r.servedFrom;
+  return result;
+}
+function sanitizeStoredPayload(payload) {
+  const r = JSON.parse(payload);
+  if (!r || typeof r !== "object" || Array.isArray(r))
+    throw new Error("Invalid diagnostic payload");
+  const result = {};
+  for (const key of ["page", "resource", "observedResource", "diagnosticResource"])
+    if (typeof r[key] === "string")
+      result[key] = sanitizeChunkUrl(r[key]);
+  for (const key of ["attemptId", "outcome", "source", "observedSource"])
+    if (typeof r[key] === "string" && DIAGNOSTIC_ID.test(r[key]))
+      result[key] = r[key];
+  for (const key of ["at", "occurredAt"])
+    if (Number.isFinite(r[key]))
+      result[key] = r[key];
+  if (r.reconstructedFrom === "REENTERED")
+    result.reconstructedFrom = "REENTERED";
+  if (r.context && typeof r.context === "object")
+    result.context = {
+      release: safeVersion(r.context.release),
+      appVersion: safeVersion(r.context.appVersion),
+      online: typeof r.context.online === "boolean" ? r.context.online : void 0,
+      visibility: visibility(r.context.visibility),
+      swControlled: r.context.swControlled === true,
+      swScript: sanitizeChunkUrl(r.context.swScript || ""),
+      nativeResourceSource: "unavailable"
+    };
+  if (r.timing && typeof r.timing === "object")
+    result.timing = safeTiming(r.timing);
+  if (Array.isArray(r.swTraces))
+    result.swTraces = r.swTraces.slice(-3).map(readChunkTrace).filter(Boolean);
+  if (r.trace)
+    result.trace = readChunkTrace(r.trace);
+  result.correlation = "resource-time-window";
+  return JSON.stringify(result);
+}
+export {
+  DIAGNOSTIC_ID,
+  DIAGNOSTIC_TTL,
+  diagnosticContext,
+  diagnosticTiming,
+  readChunkTrace,
+  sanitizeStoredPayload
+};

package/dist/esm/shared/chunk-diagnostic-reporter.d.ts

@@ -0,0 +1,9 @@
+import type { ChunkRecoveryEvent } from './chunk-error-recovery';
+/** 完整诊断走 t=custom / x-* 字段，不制造 error 或 API 指标。 */
+export declare function createChunkDiagnosticReporter(options: {
+    release: string;
+    appVersion?: () => string;
+}): {
+    report: (event: ChunkRecoveryEvent) => void;
+    dispose: () => void;
+};

package/dist/esm/shared/chunk-diagnostic-reporter.js

@@ -0,0 +1,114 @@
+// src/shared/chunk-diagnostic-reporter.ts
+import { createDiagnosticOutbox } from "./chunk-diagnostic-outbox";
+import {
+  DIAGNOSTIC_TTL,
+  diagnosticContext,
+  diagnosticTiming,
+  readChunkTrace
+} from "./chunk-diagnostic-payload";
+import { CHUNK_TRACE_MESSAGE, sanitizeChunkUrl } from "./chunk-diagnostics";
+function createChunkDiagnosticReporter(options) {
+  const { release, appVersion = () => "unknown" } = options;
+  const outbox = createDiagnosticOutbox();
+  let traces = [];
+  let active;
+  const diagnosticResource = (event) => sanitizeChunkUrl(event.observedResource || event.resource);
+  const matching = (event) => traces.filter(
+    (trace) => trace.resource === diagnosticResource(event) && Math.abs((trace.completedAt ?? trace.at) - event.occurredAt) < 12e4
+  ).slice(-3);
+  const report = (event) => {
+    try {
+      active = event;
+      const safeEvent = {
+        attemptId: event.attemptId,
+        at: event.at,
+        occurredAt: event.occurredAt,
+        outcome: event.outcome,
+        source: event.source,
+        observedSource: event.observedSource,
+        page: sanitizeChunkUrl(event.page),
+        resource: sanitizeChunkUrl(event.resource),
+        observedResource: event.observedResource ? sanitizeChunkUrl(event.observedResource) : void 0
+      };
+      if (event.outcome === "REENTERED" && !outbox.has(`${event.attemptId}-RELOAD`)) {
+        outbox.enqueue(
+          {
+            eventId: `${event.attemptId}-RELOAD`,
+            attemptId: event.attemptId,
+            at: Date.now(),
+            outcome: "RELOAD",
+            payload: JSON.stringify({
+              attemptId: event.attemptId,
+              at: event.at,
+              page: safeEvent.page,
+              resource: safeEvent.resource,
+              source: event.source,
+              outcome: "RELOAD",
+              reconstructedFrom: "REENTERED"
+            })
+          },
+          true
+        );
+      }
+      outbox.enqueue({
+        eventId: `${event.attemptId}-${event.outcome}`,
+        attemptId: event.attemptId,
+        at: Date.now(),
+        outcome: event.outcome,
+        payload: JSON.stringify({
+          ...safeEvent,
+          diagnosticResource: diagnosticResource(event),
+          context: diagnosticContext(release, appVersion),
+          timing: diagnosticTiming(diagnosticResource(event), event.occurredAt),
+          swTraces: matching(event),
+          correlation: "resource-time-window"
+        })
+      });
+    } catch {
+    }
+  };
+  const onMessage = (message) => {
+    var _a, _b;
+    try {
+      if (!message.source || message.source !== ((_a = navigator.serviceWorker) == null ? void 0 : _a.controller) || ((_b = message.data) == null ? void 0 : _b.type) !== CHUNK_TRACE_MESSAGE)
+        return;
+      const trace = readChunkTrace(message.data.payload);
+      if (!trace)
+        return;
+      traces = traces.filter(
+        (r) => r.requestId !== trace.requestId && Date.now() - r.at < DIAGNOSTIC_TTL
+      );
+      traces.push(trace);
+      traces = traces.slice(-40);
+      if (active && Date.now() - active.occurredAt < DIAGNOSTIC_TTL && matching(active).includes(trace)) {
+        outbox.enqueue({
+          eventId: `${trace.requestId}-${trace.phase}`,
+          attemptId: active.attemptId,
+          at: Date.now(),
+          outcome: "SW-REQUEST",
+          payload: JSON.stringify({
+            attemptId: active.attemptId,
+            page: sanitizeChunkUrl(active.page),
+            resource: sanitizeChunkUrl(active.resource),
+            diagnosticResource: diagnosticResource(active),
+            trace,
+            correlation: "resource-time-window"
+          })
+        });
+      }
+    } catch {
+    }
+  };
+  const serviceWorker = navigator.serviceWorker;
+  serviceWorker == null ? void 0 : serviceWorker.addEventListener("message", onMessage);
+  return {
+    report,
+    dispose: () => {
+      outbox.dispose();
+      serviceWorker == null ? void 0 : serviceWorker.removeEventListener("message", onMessage);
+    }
+  };
+}
+export {
+  createChunkDiagnosticReporter
+};

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microbt/pwa",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "microbt service worker runtime and page-side registration for web apps",
   "keywords": [
     "microbt",
@@ -21,6 +21,10 @@
     "./sw": {
       "types": "./dist/esm/sw.d.ts",
       "import": "./dist/esm/sw.js"
+    },
+    "./recovery": {
+      "types": "./dist/esm/recovery.d.ts",
+      "import": "./dist/esm/recovery.js"
     }
   },
   "main": "dist/esm/index.js",