@microbt/pwa 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,88 @@
-# 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 端运行时）、`./recovery`（chunk 恢复与诊断上报，见下节）。
+
+## 接入
+
+**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';
+```
+
+## 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 一字不差：
+
+- 缓存名前缀 `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/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-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
+};