@microbt/pwa 0.0.0-stage → 0.0.1

package/dist/esm/shared/sw-script-url.js

@@ -0,0 +1,49 @@
+// src/shared/sw-script-url.ts
+function buildSwRegisterUrl(baseUrl, version) {
+  return `/sw.js?baseUrl=${encodeURIComponent(baseUrl)}&v=${encodeURIComponent(version)}`;
+}
+function getSwScriptVersion(scriptUrl, pageOrigin) {
+  try {
+    return new URL(scriptUrl, pageOrigin).searchParams.get("v");
+  } catch {
+    return null;
+  }
+}
+function isSameOriginSwScriptUrl(scriptUrl, pageOrigin) {
+  try {
+    const url = new URL(scriptUrl, pageOrigin);
+    return url.origin === pageOrigin && url.pathname === "/sw.js";
+  } catch {
+    return false;
+  }
+}
+function normalizeScriptUrl(url, pageOrigin) {
+  try {
+    return new URL(url, pageOrigin).toString();
+  } catch {
+    return url;
+  }
+}
+function resolveSwScriptUrl({
+  publicPath,
+  existingScriptUrls,
+  version,
+  pageOrigin
+}) {
+  if (typeof publicPath === "string" && (publicPath.startsWith("//") || /^https?:\/\//.test(publicPath))) {
+    return buildSwRegisterUrl(publicPath, version);
+  }
+  for (const scriptUrl of existingScriptUrls) {
+    if (isSameOriginSwScriptUrl(scriptUrl, pageOrigin) && getSwScriptVersion(scriptUrl, pageOrigin) === version) {
+      return scriptUrl;
+    }
+  }
+  return buildSwRegisterUrl("undefined", version);
+}
+export {
+  buildSwRegisterUrl,
+  getSwScriptVersion,
+  isSameOriginSwScriptUrl,
+  normalizeScriptUrl,
+  resolveSwScriptUrl
+};

package/dist/esm/sw-cache-validation.d.ts

@@ -0,0 +1,51 @@
+/**
+ * ServiceWorker 资源缓存的响应校验。
+ *
+ * 背景：support 根域源站的 SPA fallback 会对任意路径（含 .js/.css）返回
+ * 200 + text/html 骨架页（响应头含 x-content-type-options: nosniff）。
+ * 当离线包拦截放行（站点禁用 / 包校验失败 / 版本未激活）时，SW 直接落网，
+ * 会把 HTML 响应写入 JS/CSS 缓存；StaleWhileRevalidate 之后先返回坏条目，
+ * 浏览器严格 MIME 检查拒绝执行，触发 ChunkLoadError 白屏（坏条目随后台
+ * revalidate 逐个自愈，表现为间歇性白屏）。
+ * 因此缓存前必须校验响应 MIME 与资源扩展名匹配，并在激活时清理历史坏条目。
+ */
+/**
+ * 资源缓存名前缀。sw.ts 两条路由的 cacheName 必须复用这两个常量构造
+ * （`${PREFIX}${origin}`），否则 activate 清理会因名字漂移静默失效
+ */
+export declare const JS_CSS_CACHE_NAME_PREFIX = "cache-js-css-";
+export declare const STATIC_ASSETS_CACHE_NAME_PREFIX = "cache-static-assets-";
+interface RequestLike {
+    readonly url: string;
+}
+interface ResponseLike {
+    readonly headers: {
+        get(name: string): string | null;
+    };
+}
+export interface CacheLike {
+    keys(): Promise<readonly Request[]>;
+    match(request: Request): Promise<Response | undefined>;
+    delete(request: Request): Promise<boolean>;
+}
+export interface CacheStorageLike {
+    keys(): Promise<string[]>;
+    open(cacheName: string): Promise<CacheLike>;
+}
+/**
+ * 判断响应 MIME 是否与请求 URL 扩展名不匹配（例如 .js 请求拿到 text/html）。
+ * 未知扩展名 / 无法解析的 URL 不校验，维持原有放行行为。
+ */
+export declare function isMimeMismatch(request: RequestLike, response: ResponseLike): boolean;
+export declare class ValidateResponsePlugin {
+    cacheWillUpdate({ request, response }: {
+        request: Request;
+        response: Response;
+    }): Promise<Response | null>;
+}
+/**
+ * 清理历史坏条目：旧版本 SW 可能把源站 HTML 存进了 JS/CSS/静态资源缓存。
+ * 每个坏条目原本要“再白屏一次”才被后台 revalidate 修复，激活时统一清理可立即自愈。
+ */
+export declare function purgeMismatchedCacheEntries(cacheStorage?: CacheStorageLike): Promise<void>;
+export {};

package/dist/esm/sw-cache-validation.js

@@ -0,0 +1,111 @@
+// src/sw-cache-validation.ts
+var JS_MIME_TYPES = [
+  "application/javascript",
+  "text/javascript",
+  "application/x-javascript",
+  "application/ecmascript",
+  "text/ecmascript"
+];
+var STATIC_MIME_RULES = {
+  js: JS_MIME_TYPES,
+  mjs: JS_MIME_TYPES,
+  css: ["text/css"],
+  png: ["image/png"],
+  jpg: ["image/jpeg"],
+  jpeg: ["image/jpeg"],
+  gif: ["image/gif"],
+  webp: ["image/webp"],
+  svg: ["image/svg+xml"],
+  ico: ["image/x-icon", "image/vnd.microsoft.icon"],
+  // 字体除 IANA 新型（font/*，2017 年注册）外，CDN/OSS 常见旧型
+  // application/font-* 与 application/x-font-* 一并放行，避免合法字体
+  // 被误判为不匹配而永远进不了缓存
+  woff: ["font/woff", "application/font-woff", "application/x-font-woff"],
+  woff2: ["font/woff2", "application/font-woff2", "application/x-font-woff2"],
+  ttf: ["font/ttf", "application/font-ttf", "application/x-font-ttf"],
+  otf: ["font/otf", "application/font-otf", "application/x-font-otf"],
+  eot: ["application/vnd.ms-fontobject"]
+};
+var JS_CSS_CACHE_NAME_PREFIX = "cache-js-css-";
+var STATIC_ASSETS_CACHE_NAME_PREFIX = "cache-static-assets-";
+var ASSET_CACHE_NAME_PREFIXES = [
+  JS_CSS_CACHE_NAME_PREFIX,
+  STATIC_ASSETS_CACHE_NAME_PREFIX
+];
+function normalizeMimeType(contentType) {
+  return (contentType ?? "").split(";")[0].trim().toLowerCase();
+}
+function getKnownStaticExtension(url) {
+  let pathname;
+  try {
+    pathname = new URL(url).pathname;
+  } catch {
+    return null;
+  }
+  const lastSegment = pathname.slice(pathname.lastIndexOf("/") + 1);
+  const dotIndex = lastSegment.lastIndexOf(".");
+  if (dotIndex <= 0) {
+    return null;
+  }
+  const extension = lastSegment.slice(dotIndex + 1).toLowerCase();
+  return Object.prototype.hasOwnProperty.call(STATIC_MIME_RULES, extension) ? extension : null;
+}
+function isMimeMismatch(request, response) {
+  const extension = getKnownStaticExtension(request.url);
+  if (!extension) {
+    return false;
+  }
+  const mimeType = normalizeMimeType(response.headers.get("content-type"));
+  if (!mimeType) {
+    return true;
+  }
+  return !STATIC_MIME_RULES[extension].includes(mimeType);
+}
+var ValidateResponsePlugin = class {
+  async cacheWillUpdate({ request, response }) {
+    if (!response) {
+      console.warn("不缓存失败的响应", request.url, "No Response");
+      return null;
+    }
+    if (response.status === 0) {
+      return response;
+    }
+    if (!response.ok) {
+      console.warn("不缓存失败的响应", request.url, response.status);
+      return null;
+    }
+    if (isMimeMismatch(request, response)) {
+      console.warn(
+        "MIME 类型与资源扩展名不匹配，不缓存",
+        request.url,
+        response.headers.get("content-type")
+      );
+      return null;
+    }
+    return response;
+  }
+};
+async function purgeMismatchedCacheEntries(cacheStorage = caches) {
+  const cacheNames = await cacheStorage.keys();
+  const assetCacheNames = cacheNames.filter(
+    (name) => ASSET_CACHE_NAME_PREFIXES.some((prefix) => name.startsWith(prefix))
+  );
+  for (const cacheName of assetCacheNames) {
+    const cache = await cacheStorage.open(cacheName);
+    const requests = await cache.keys();
+    for (const request of requests) {
+      const cachedResponse = await cache.match(request);
+      if (cachedResponse && isMimeMismatch(request, cachedResponse)) {
+        await cache.delete(request);
+        console.warn("[ServiceWorker] 清理 MIME 不匹配的缓存条目", cacheName, request.url);
+      }
+    }
+  }
+}
+export {
+  JS_CSS_CACHE_NAME_PREFIX,
+  STATIC_ASSETS_CACHE_NAME_PREFIX,
+  ValidateResponsePlugin,
+  isMimeMismatch,
+  purgeMismatchedCacheEntries
+};

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

@@ -0,0 +1,19 @@
+import type { CachedResponseWillBeUsedCallbackParam, FetchDidFailCallbackParam, FetchDidSucceedCallbackParam, HandlerDidCompleteCallbackParam, HandlerDidRespondCallbackParam, HandlerWillStartCallbackParam, RequestWillFetchCallbackParam, WorkboxPlugin } from 'workbox-core/types';
+/**
+ * 仅观察 script/style 的原始 SWR 请求。state 由 Workbox 为每个 handler
+ * 单独创建；不要把请求状态挂到共享 plugin 实例上。
+ */
+export declare class ChunkDiagnosticsPlugin implements WorkboxPlugin {
+    private readonly options;
+    constructor(options: {
+        release: string;
+    });
+    handlerWillStart({ request, state }: HandlerWillStartCallbackParam): Promise<void>;
+    requestWillFetch({ request, state }: RequestWillFetchCallbackParam): Promise<Request>;
+    cachedResponseWillBeUsed({ cachedResponse, state }: CachedResponseWillBeUsedCallbackParam): Promise<Response | undefined>;
+    fetchDidSucceed({ response, state }: FetchDidSucceedCallbackParam): Promise<Response>;
+    fetchDidFail({ error, state }: FetchDidFailCallbackParam): Promise<void>;
+    handlerDidRespond(options: HandlerDidRespondCallbackParam): Promise<void>;
+    handlerDidComplete(options: HandlerDidCompleteCallbackParam): Promise<void>;
+    private report;
+}

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

@@ -0,0 +1,124 @@
+// src/sw-chunk-diagnostics.ts
+import {
+  CHUNK_TRACE_MESSAGE,
+  createChunkDiagnosticId,
+  sanitizeChunkUrl
+} from "./shared/chunk-diagnostics";
+function safeErrorName(error) {
+  return /^(Error|TypeError|RangeError|AbortError|NetworkError|TimeoutError|SecurityError|InvalidStateError|QuotaExceededError|no-response)$/.test(
+    error.name
+  ) ? error.name : "Error";
+}
+function responseMime(response) {
+  return (response.headers.get("content-type") || "").split(";", 1)[0].trim();
+}
+var ChunkDiagnosticsPlugin = class {
+  constructor(options) {
+    this.options = options;
+  }
+  async handlerWillStart({ request, state }) {
+    try {
+      if (!state || request.destination !== "script" && request.destination !== "style") {
+        return;
+      }
+      state.trace = {
+        requestId: createChunkDiagnosticId(),
+        at: Date.now(),
+        resource: sanitizeChunkUrl(request.url),
+        phase: "response",
+        destination: request.destination,
+        mode: request.mode,
+        credentials: request.credentials,
+        cache: "unknown",
+        network: "pending",
+        swRelease: this.options.release
+      };
+    } catch {
+    }
+  }
+  async requestWillFetch({ request, state }) {
+    try {
+      const trace = state == null ? void 0 : state.trace;
+      if (trace) {
+        trace.mode = request.mode;
+        trace.credentials = request.credentials;
+      }
+    } catch {
+    }
+    return request;
+  }
+  async cachedResponseWillBeUsed({ cachedResponse, state }) {
+    try {
+      const trace = state == null ? void 0 : state.trace;
+      if (trace)
+        trace.cache = cachedResponse ? "hit" : "miss";
+    } catch {
+    }
+    return cachedResponse;
+  }
+  async fetchDidSucceed({ response, state }) {
+    try {
+      const trace = state == null ? void 0 : state.trace;
+      if (trace) {
+        trace.network = "response";
+        trace.networkStatus = response.status;
+        trace.networkType = response.type;
+        trace.networkMime = responseMime(response);
+      }
+    } catch {
+    }
+    return response;
+  }
+  async fetchDidFail({ error, state }) {
+    try {
+      const trace = state == null ? void 0 : state.trace;
+      if (trace) {
+        trace.network = "error";
+        trace.errorName = safeErrorName(error);
+      }
+    } catch {
+    }
+  }
+  async handlerDidRespond(options) {
+    this.report(options, "response");
+  }
+  async handlerDidComplete(options) {
+    this.report(options, "complete");
+  }
+  report({ event, response, state }, phase) {
+    try {
+      const diagnostic = state;
+      const trace = diagnostic == null ? void 0 : diagnostic.trace;
+      const sentKey = phase === "response" ? "responseSent" : "completeSent";
+      if (!diagnostic || !trace || diagnostic[sentKey])
+        return;
+      diagnostic[sentKey] = true;
+      const snapshot = {
+        ...trace,
+        phase,
+        ...phase === "complete" ? { completedAt: Date.now() } : {},
+        servedFrom: response ? trace.cache === "hit" ? "cache" : "network" : "none",
+        ...response ? {
+          responseStatus: response.status,
+          responseType: response.type,
+          responseMime: responseMime(response)
+        } : {}
+      };
+      const clientId = event.clientId;
+      if (!clientId)
+        return;
+      const delivery = (async () => {
+        try {
+          const client = await self.clients.get(clientId);
+          client == null ? void 0 : client.postMessage({ type: CHUNK_TRACE_MESSAGE, payload: snapshot });
+        } catch {
+        }
+      })();
+      event.waitUntil(delivery);
+    } catch {
+    }
+  }
+};
+export {
+  ChunkDiagnosticsPlugin
+};

package/dist/esm/sw-error-filter.d.ts

@@ -0,0 +1,58 @@
+/** 固定计数项，避免把 URL、错误文案等高基数内容用作监控指标名。 */
+export declare const SW_REJECTION_METRICS: {
+    readonly 'cache-write-network': "SW-CACHE-WRITE-NETWORK";
+    readonly 'cache-entry-exists': "SW-CACHE-ENTRY-EXISTS";
+    readonly 'cache-expiration-cursor': "SW-CACHE-EXPIRATION-CURSOR";
+    readonly 'feedback-media-no-response': "SW-FEEDBACK-MEDIA-NO-RESPONSE";
+};
+export interface SwRejectionDetails {
+    name: string;
+    message: string;
+    stack: string;
+}
+/** 在 SW 内转成纯字符串再 postMessage，保留 DOMException 信息并避免克隆失败。 */
+export declare function serializeSwRejection(reason: unknown): SwRejectionDetails;
+/**
+ * SW unhandledrejection 上报原则：影响不明就保留异常，已知重复故障才减少 error 频率。
+ * 本策略只处理未被业务捕获的 Promise 拒绝；SW 的 error 事件仍走独立的全量上报。
+ *
+ * 哪些上报：
+ * 1. 普通 NetworkError、Failed to fetch、AbortError、非反馈媒体的
+ *    no-response 和所有未知错误：每次报 error。全局事件不能证明主动取消
+ *    或缓存已兜底；网络失败也可能是配置问题，非反馈媒体的 no-response
+ *    （CDN chunk、页面导航）可能是资源最终加载失败（白屏信号），不能
+ *    当成用户断网直接忽略。
+ *    cache-put-with-no-response 是另一种错误，同样每次报，不能用子串混为一类。
+ * 2. getCategory 精确匹配的四类故障：Cache.put 网络写入失败、缓存条目已存在、
+ *    IndexedDB 游标异常、签名反馈媒体 URL 的 no-response（反馈图片/视频
+ *    请求失败，原因未明——日志只有 error:{}，无法区分网络、取消或 CORS；
+ *    此类失败不伤 app 外壳）。每次通知页面记 sum；每类首次及距离上次允许
+ *    上报满 60 秒的下一次故障，同时报 error。其他错误名或文案变体回到第 1 条。
+ *
+ * 哪些不报 error：只有第 2 条中距上次允许上报不足 60 秒的同类重复故障。
+ * 此时仍通知页面记 sum，并非完全丢弃；当前没有仅凭错误名就彻底忽略的类别。
+ * 60 秒是控制重复量的固定窗口，不代表故障已恢复；重复事件不会推迟窗口，
+ * 到期也不会主动补报，必须有下一次故障才再次报 error。
+ *
+ * 限频的本质是故障详情抽样，不是"重复去重、信号不丢"：限频键只有
+ * category，同类中不同 URL 的故障共享窗口——视频 A 首次报错后，视频 B
+ * 在一分钟内首次失败只剩 sum，B 的 URL 和堆栈不会上报。同时 SW 仍向
+ * 所有页面广播，多页面打开时一次故障可能产生多份 error/sum，本策略不
+ * 解决广播重复。接受这两个取舍的理由是此类故障原因未明且不伤外壳，
+ * 保留频次与代表性样本即可，不需要每一次详情。
+ *
+ * 为什么仍保留缓存故障：写入失败影响后续离线使用，游标异常可能中断缓存淘汰。
+ * 即使源于浏览器问题，也需保留频次和代表性堆栈；本策略不负责修复底层故障。
+ * 限频按 SW 实例、按类别独立保存，重启或时钟回拨后重新允许上报。
+ * sum 是页面接收通知的次数，多页面会重复、无客户端会漏收，不是准确的故障总数。
+ * 新旧 SW/页面共存时，旧页面不识别限频字段会继续全量报 error，待页面更新后生效。
+ * 若以后要忽略主动取消或成功兜底的请求，应在掌握请求结果的调用点处理，
+ * 不应在这里扩充关键词黑名单。NetworkFirst 超时只尝试缓存兜底，不会 abort 请求。
+ */
+export declare function createSwRejectionPolicy(): (details: SwRejectionDetails, now?: number) => {
+    reportError: boolean;
+    category?: undefined;
+} | {
+    category: "cache-write-network" | "cache-entry-exists" | "cache-expiration-cursor" | "feedback-media-no-response";
+    reportError: boolean;
+};

package/dist/esm/sw-error-filter.js

@@ -0,0 +1,87 @@
+// src/sw-error-filter.ts
+var SW_REJECTION_METRICS = {
+  "cache-write-network": "SW-CACHE-WRITE-NETWORK",
+  "cache-entry-exists": "SW-CACHE-ENTRY-EXISTS",
+  "cache-expiration-cursor": "SW-CACHE-EXPIRATION-CURSOR",
+  "feedback-media-no-response": "SW-FEEDBACK-MEDIA-NO-RESPONSE"
+};
+function serializeSwRejection(reason) {
+  try {
+    if (reason !== null && typeof reason === "object") {
+      const error = reason;
+      return {
+        name: typeof error.name === "string" ? error.name : "",
+        message: typeof error.message === "string" ? error.message : JSON.stringify(reason) || String(reason),
+        stack: typeof error.stack === "string" ? error.stack : ""
+      };
+    }
+    return { name: "", message: String(reason), stack: "" };
+  } catch {
+    return {
+      name: "",
+      message: "[Unserializable rejection reason]",
+      stack: ""
+    };
+  }
+}
+var NO_RESPONSE_MESSAGE_PREFIX = "no-response :: ";
+var FEEDBACK_MEDIA_HOST = "super-acme-online.oss-cn-hangzhou.aliyuncs.com";
+var FEEDBACK_MEDIA_PATH_PREFIXES = ["/saas/feedbackVideo/", "/user-center/feedback/"];
+function isSignedFeedbackMediaNoResponse(message) {
+  var _a;
+  if (!message.startsWith(NO_RESPONSE_MESSAGE_PREFIX)) {
+    return false;
+  }
+  try {
+    const details = JSON.parse(message.slice(NO_RESPONSE_MESSAGE_PREFIX.length));
+    const url = Array.isArray(details) ? (_a = details[0]) == null ? void 0 : _a.url : void 0;
+    if (typeof url !== "string") {
+      return false;
+    }
+    const parsed = new URL(url);
+    if (parsed.hostname !== FEEDBACK_MEDIA_HOST) {
+      return false;
+    }
+    if (!FEEDBACK_MEDIA_PATH_PREFIXES.some((prefix) => parsed.pathname.startsWith(prefix))) {
+      return false;
+    }
+    return parsed.searchParams.has("Expires") && parsed.searchParams.has("Signature");
+  } catch {
+    return false;
+  }
+}
+function getCategory({ name, message }) {
+  if (name === "NetworkError" && message === "Failed to execute 'put' on 'Cache': Cache.put() encountered a network error") {
+    return "cache-write-network";
+  }
+  if (name === "InvalidAccessError" && message === "Failed to execute 'put' on 'Cache': Entry already exists.") {
+    return "cache-entry-exists";
+  }
+  if (name === "UnknownError" && message === "Attempt to iterate a cursor that doesn't exist") {
+    return "cache-expiration-cursor";
+  }
+  if (name === "no-response" && isSignedFeedbackMediaNoResponse(message)) {
+    return "feedback-media-no-response";
+  }
+  return void 0;
+}
+function createSwRejectionPolicy() {
+  const lastReported = /* @__PURE__ */ new Map();
+  return (details, now = Date.now()) => {
+    const category = getCategory(details);
+    if (!category) {
+      return { reportError: true };
+    }
+    const previous = lastReported.get(category);
+    const reportError = previous === void 0 || now < previous || now - previous >= 6e4;
+    if (reportError) {
+      lastReported.set(category, now);
+    }
+    return { category, reportError };
+  };
+}
+export {
+  SW_REJECTION_METRICS,
+  createSwRejectionPolicy,
+  serializeSwRejection
+};

package/dist/esm/sw-polyfills.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/sw-polyfills.js

@@ -0,0 +1,14 @@
+// src/sw-polyfills.ts
+if (typeof Promise.allSettled !== "function") {
+  Promise.allSettled = function(values) {
+    return Promise.all(
+      Array.from(
+        values,
+        (item) => Promise.resolve(item).then(
+          (value) => ({ status: "fulfilled", value }),
+          (reason) => ({ status: "rejected", reason })
+        )
+      )
+    );
+  };
+}

package/dist/esm/sw-request-filter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * SW 缓存路由的协议守卫：仅 http(s) 请求允许进入 workbox 缓存路由。
+ *
+ * 注：workbox-routing 已在路由匹配前排除非 http(s) 请求——
+ * Router.handleRequest 中 `!url.protocol.startsWith('http')` 直接 return，
+ * blob:/data: 不会 respondWith，由浏览器本地解析。本守卫与框架行为等价，
+ * 属防御性加固：防止未来改用自定义 fetch 监听或路由重构时，blob:/data:
+ * 被误引入缓存语义。
+ *
+ * 线上 blob: 图片加载失败（SLS 202609，Android WebView ×3）与本守卫无关，
+ * 根因未定位，需单独排查。
+ */
+export declare function isHttpOrHttpsRequest(url: string): boolean;

package/dist/esm/sw-request-filter.js

@@ -0,0 +1,7 @@
+// src/sw-request-filter.ts
+function isHttpOrHttpsRequest(url) {
+  return url.startsWith("https://") || url.startsWith("http://");
+}
+export {
+  isHttpOrHttpsRequest
+};

package/dist/esm/sw.d.ts

@@ -0,0 +1,4 @@
+import './sw-polyfills';
+export declare function setupServiceWorker(options: {
+    release: string;
+}): void;