@botim/mp-debug-sdk 0.3.1 → 0.5.2

package/dist/index.d.cts

@@ -45,9 +45,11 @@ interface BuiltinHostHooks {
     /**
      * Capture a screenshot. Two return shapes are accepted:
      *   - a raw base64 string  → assumed PNG (legacy form)
-     *   - `{ data, format }`   → format is one of 'png-base64' | 'jpeg-base64'
-     *     so the admin viewer can pick the right MIME for the data URL.
-     * The SDK enforces a 1 MB base64 cap regardless.
+     *   - `{ data, format }`   → format is one of:
+     *       'png-base64' | 'jpeg-base64' — raw bitmap, viewer renders as <img>
+     *       'rrweb-snapshot'             — `data` is JSON the viewer rebuilds
+     *       'html-snapshot'              — legacy `data` JSON: { html, … }
+     * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
     screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
 }
@@ -55,10 +57,17 @@ type ScreenshotResult = string | {
     data: string;
     format?: 'png-base64' | 'jpeg-base64'
     /**
-     * Self-contained HTML+CSS snapshot — `data` is a JSON string with
-     * the shape `{ html, viewport, url, capturedAt }`. Admin viewers
-     * render `html` inside a sandboxed `<iframe srcdoc>` so the result
-     * looks pixel-identical to the live page without any pixel encoding.
+     * rrweb-snapshot tree, JSON-stringified. `data` parses to:
+     *   { snapshot, viewport: { w, h }, url, capturedAt }
+     * The admin viewer calls `rrwebSnapshot.rebuild(snapshot, …)` into
+     * an iframe to re-materialize the page with full shadow DOM /
+     * adoptedStyleSheets / cross-origin CSS fidelity.
+     */
+     | 'rrweb-snapshot'
+    /**
+     * Legacy self-contained HTML snapshot (pre-0.4). `data` JSON shape
+     * is `{ html, viewport, url, capturedAt }`. Kept on the wire for
+     * back-compat; admin viewers still know how to render it.
      */
      | 'html-snapshot';
 };

package/dist/index.d.ts

@@ -45,9 +45,11 @@ interface BuiltinHostHooks {
     /**
      * Capture a screenshot. Two return shapes are accepted:
      *   - a raw base64 string  → assumed PNG (legacy form)
-     *   - `{ data, format }`   → format is one of 'png-base64' | 'jpeg-base64'
-     *     so the admin viewer can pick the right MIME for the data URL.
-     * The SDK enforces a 1 MB base64 cap regardless.
+     *   - `{ data, format }`   → format is one of:
+     *       'png-base64' | 'jpeg-base64' — raw bitmap, viewer renders as <img>
+     *       'rrweb-snapshot'             — `data` is JSON the viewer rebuilds
+     *       'html-snapshot'              — legacy `data` JSON: { html, … }
+     * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
     screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
 }
@@ -55,10 +57,17 @@ type ScreenshotResult = string | {
     data: string;
     format?: 'png-base64' | 'jpeg-base64'
     /**
-     * Self-contained HTML+CSS snapshot — `data` is a JSON string with
-     * the shape `{ html, viewport, url, capturedAt }`. Admin viewers
-     * render `html` inside a sandboxed `<iframe srcdoc>` so the result
-     * looks pixel-identical to the live page without any pixel encoding.
+     * rrweb-snapshot tree, JSON-stringified. `data` parses to:
+     *   { snapshot, viewport: { w, h }, url, capturedAt }
+     * The admin viewer calls `rrwebSnapshot.rebuild(snapshot, …)` into
+     * an iframe to re-materialize the page with full shadow DOM /
+     * adoptedStyleSheets / cross-origin CSS fidelity.
+     */
+     | 'rrweb-snapshot'
+    /**
+     * Legacy self-contained HTML snapshot (pre-0.4). `data` JSON shape
+     * is `{ html, viewport, url, capturedAt }`. Kept on the wire for
+     * back-compat; admin viewers still know how to render it.
      */
      | 'html-snapshot';
 };

package/dist/index.js

@@ -1,3 +1,5 @@
+import { snapshot } from 'rrweb-snapshot';
+
 // src/types.ts
 var SCHEMA_VERSION = 2;
 
@@ -268,7 +270,7 @@ function resolveAgainstEndpoint(url, base) {
 function detectDeviceInfo(app, override) {
   const ua = typeof navigator !== "undefined" ? navigator.userAgent : void 0;
   return {
-    deviceId: override?.deviceId ?? generateDeviceId(),
+    deviceId: override?.deviceId ?? loadOrCreateDeviceId(),
     platform: override?.platform ?? detectPlatform(ua),
     osVersion: override?.osVersion,
     appName: override?.appName ?? app.name,
@@ -284,6 +286,21 @@ function detectPlatform(ua) {
   if (/Mozilla|Chrome|Safari|Firefox/i.test(ua)) return "web";
   return "unknown";
 }
+var DEVICE_ID_STORAGE_KEY = "botim-debug-sdk:device-id";
+function loadOrCreateDeviceId() {
+  try {
+    const ls = typeof localStorage !== "undefined" ? localStorage : null;
+    if (ls) {
+      const stored = ls.getItem(DEVICE_ID_STORAGE_KEY);
+      if (stored && stored.length > 0) return stored;
+      const fresh = generateDeviceId();
+      ls.setItem(DEVICE_ID_STORAGE_KEY, fresh);
+      return fresh;
+    }
+  } catch {
+  }
+  return generateDeviceId();
+}
 function generateDeviceId() {
   const c = typeof crypto !== "undefined" ? crypto : void 0;
   if (c?.randomUUID) return c.randomUUID();
@@ -558,6 +575,11 @@ function wrapFetch(opts) {
         method,
         url,
         status: res.status,
+        // statusText carries the human label ("OK", "Not Found"). Pre-HTTP/2
+        // responses always have it; HTTP/2+ defines it as empty by spec but
+        // most browsers synthesize one from the code, so this is reliable
+        // enough to display alongside the status code.
+        statusText: res.statusText || void 0,
         durationMs: Date.now() - start,
         resHeaders: headersFromResponse(res),
         resBody
@@ -571,7 +593,14 @@ function wrapFetch(opts) {
         url,
         durationMs: Date.now() - start,
         errorMessage: err instanceof Error ? err.message : String(err),
-        errorName: err instanceof Error ? err.name : void 0
+        errorName: err instanceof Error ? err.name : void 0,
+        // Stack from the rejected promise — points into fetch internals
+        // and (when present) the call site that issued the request.
+        errorStack: err instanceof Error ? err.stack : void 0,
+        // undici frequently wraps the real reason in `cause` (e.g.
+        // `TypeError: fetch failed` outside, `Error: ECONNREFUSED` inside).
+        // Flatten the chain so operators don't have to dig.
+        errorCause: collectCauseChain(err)
       });
       throw err;
     }
@@ -580,6 +609,24 @@ function wrapFetch(opts) {
     target.fetch = original;
   };
 }
+function collectCauseChain(err) {
+  if (!err || typeof err !== "object") return void 0;
+  const lines = [];
+  let cur = err.cause;
+  const seen = /* @__PURE__ */ new Set();
+  while (cur && lines.length < 5) {
+    if (seen.has(cur)) break;
+    seen.add(cur);
+    if (cur instanceof Error) {
+      lines.push(`${cur.name}: ${cur.message}`);
+      cur = cur.cause;
+    } else {
+      lines.push(String(cur));
+      cur = cur?.cause;
+    }
+  }
+  return lines.length ? lines.join("\n") : void 0;
+}
 function wrapXHR(opts) {
   if (typeof XMLHttpRequest === "undefined") return () => {
   };
@@ -615,6 +662,7 @@ function wrapXHR(opts) {
     }
     s.start = Date.now();
     s.reqBody = typeof body === "string" ? body : void 0;
+    const sendSiteStack = captureCallSiteStack();
     opts.emit({
       phase: "request",
       reqId: s.reqId,
@@ -632,25 +680,32 @@ function wrapXHR(opts) {
         method: s.method,
         url: s.url,
         status: this.status,
+        // XHR exposes statusText directly; same display purpose as fetch.
+        statusText: this.statusText || void 0,
         durationMs: Date.now() - s.start,
         resHeaders: headers,
         resBody
       });
     };
-    const onError = () => {
+    const onError = (kind) => () => {
       opts.emit({
         phase: "error",
         reqId: s.reqId,
         method: s.method,
         url: s.url,
         durationMs: Date.now() - s.start,
-        errorMessage: this.statusText || "xhr error"
+        // Distinguish error/timeout/abort in the message — the standard
+        // XHR `statusText` is empty for `error` and unhelpful for the
+        // others, so we synthesise a clear label.
+        errorMessage: this.statusText || `xhr ${kind}`,
+        errorName: `XHR${kind[0].toUpperCase()}${kind.slice(1)}`,
+        errorStack: sendSiteStack
       });
     };
     this.addEventListener("load", onLoad);
-    this.addEventListener("error", onError);
-    this.addEventListener("timeout", onError);
-    this.addEventListener("abort", onError);
+    this.addEventListener("error", onError("error"));
+    this.addEventListener("timeout", onError("timeout"));
+    this.addEventListener("abort", onError("abort"));
     return origSend.apply(this, [body]);
   };
   return () => {
@@ -659,6 +714,15 @@ function wrapXHR(opts) {
     proto.setRequestHeader = origSetReqHeader;
   };
 }
+function captureCallSiteStack() {
+  try {
+    throw new Error("xhr-callsite");
+  } catch (err) {
+    if (!(err instanceof Error) || !err.stack) return void 0;
+    const lines = err.stack.split("\n");
+    return lines.slice(2).join("\n") || void 0;
+  }
+}
 function parseXhrHeaders(raw) {
   const out = {};
   if (!raw) return out;
@@ -751,8 +815,6 @@ var CommandRegistry = class {
     }
   }
 };
-
-// src/commands/builtins.ts
 var MAX_DUMP_BYTES = 64 * 1024;
 var MAX_SCREENSHOT_BYTES = 1024 * 1024;
 async function defaultDomScreenshot() {
@@ -761,163 +823,107 @@ async function defaultDomScreenshot() {
       "[@botim/debug-sdk] default screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
     );
   }
+  const injected = injectAdoptedStyleSheets();
+  let tree;
   try {
-    return await captureViaSvgForeignObject();
-  } catch (err) {
-    try {
-      console.warn(
-        "[@botim/debug-sdk] SVG/canvas screenshot failed, falling back to HTML snapshot:",
-        err instanceof Error ? err.message : err
-      );
-    } catch {
-    }
-    return await captureViaHtmlSnapshot();
-  }
-}
-var VOID_ELEMENTS = /* @__PURE__ */ new Set([
-  "area",
-  "base",
-  "br",
-  "col",
-  "embed",
-  "hr",
-  "img",
-  "input",
-  "link",
-  "meta",
-  "source",
-  "track",
-  "wbr"
-]);
-var SKIP_TAGS = /* @__PURE__ */ new Set(["script", "noscript", "template"]);
-var DEVTOOL_OVERLAY_PREFIXES = ["vite-", "astro-dev-", "next-route-"];
-function isDevtoolOverlay(tag) {
-  return DEVTOOL_OVERLAY_PREFIXES.some((p) => tag.startsWith(p));
-}
-function escapeText(s) {
-  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-function escapeAttr(s) {
-  return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
-}
-function serializeComposed(node, opts, depth) {
-  if (depth > 256) return "";
-  if (node.nodeType === Node.TEXT_NODE) {
-    return escapeText(node.textContent ?? "");
-  }
-  if (node.nodeType === Node.COMMENT_NODE) return "";
-  if (node.nodeType !== Node.ELEMENT_NODE) return "";
-  const el = node;
-  const tag = el.tagName.toLowerCase();
-  if (SKIP_TAGS.has(tag)) return "";
-  if (isDevtoolOverlay(tag)) return "";
-  if (tag === "slot") {
-    const slot = el;
-    let assigned = [];
-    try {
-      assigned = slot.assignedNodes({ flatten: true });
-    } catch {
+    tree = snapshot(document, {
+      inlineStylesheet: true,
+      inlineImages: true,
+      recordCanvas: true,
+      // Deliberately NOT slimming. SlimDOM drops <link rel="preload">,
+      // hidden form metadata, and other "noise" that's actually relevant
+      // when reproducing a layout bug.
+      slimDOM: false,
+      // Don't mask anything by default — debug-relay already runs a
+      // top-level redactor on console payloads, and on-screen text is the
+      // whole point of capturing a screenshot. Hosts that need PII masking
+      // can wire their own builtins.screenshot using rrweb-snapshot's
+      // `maskTextSelector` / `maskInputOptions`.
+      maskAllInputs: false
+    });
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
     }
-    const source = assigned.length > 0 ? assigned : Array.from(el.childNodes);
-    return source.map((c) => serializeComposed(c, opts, depth + 1)).join("");
   }
-  if (tag === "link" && (el.getAttribute("rel") || "").toLowerCase() === "stylesheet") {
-    return "";
+  if (!tree) {
+    throw new Error("[@botim/debug-sdk] rrweb-snapshot returned null tree");
   }
-  if (tag === "style") {
-    return `<style>${el.textContent ?? ""}</style>`;
-  }
-  if (tag === "img" && opts.stripCrossOriginImages) {
-    const src = el.getAttribute("src") || "";
-    if (/^(https?:|\/\/)/i.test(src)) {
+  const payload = {
+    snapshot: tree,
+    viewport: {
+      w: window.innerWidth || document.documentElement.clientWidth || 0,
+      h: window.innerHeight || document.documentElement.clientHeight || 0
+    },
+    url: location.href,
+    capturedAt: Date.now()
+  };
+  return {
+    data: JSON.stringify(payload),
+    format: "rrweb-snapshot"
+  };
+}
+function injectAdoptedStyleSheets() {
+  const injected = [];
+  const collect = (sheets) => {
+    if (!sheets || sheets.length === 0) return "";
+    const chunks = [];
+    for (const sheet of sheets) {
       try {
-        const u = new URL(src, location.href);
-        if (u.origin !== location.origin) return "";
+        const rules = sheet.cssRules;
+        for (const rule of Array.from(rules)) chunks.push(rule.cssText);
       } catch {
-        return "";
       }
     }
-  }
-  if (tag === "canvas") return `<canvas></canvas>`;
-  const attrs = Array.from(el.attributes).filter((a) => !a.name.startsWith("on")).map((a) => ` ${a.name}="${escapeAttr(a.value)}"`).join("");
-  if (VOID_ELEMENTS.has(tag)) return `<${tag}${attrs}>`;
-  const childSource = el.shadowRoot ?? el;
-  const inner = Array.from(childSource.childNodes).map((c) => serializeComposed(c, opts, depth + 1)).join("");
-  return `<${tag}${attrs}>${inner}</${tag}>`;
-}
-function readInlineableStyles() {
-  const chunks = [];
-  for (const sheet of Array.from(document.styleSheets)) {
-    try {
-      const rules = sheet.cssRules;
-      for (const rule of Array.from(rules)) chunks.push(rule.cssText);
-    } catch {
+    return chunks.join("\n");
+  };
+  const inject = (parent, css) => {
+    if (!css) return;
+    const ownerDoc = parent instanceof Document ? parent : parent.ownerDocument;
+    if (!ownerDoc) return;
+    const style = ownerDoc.createElement("style");
+    style.setAttribute("data-botim-adopted", "1");
+    style.textContent = css;
+    const target = parent instanceof Document ? parent.head ?? parent.documentElement ?? parent.body : parent;
+    if (target) {
+      target.insertBefore(style, target.firstChild);
+      injected.push(style);
     }
-  }
-  return chunks.join("\n");
-}
-async function captureViaSvgForeignObject() {
-  const dpr = Math.min(window.devicePixelRatio || 1, 2);
-  const w = Math.max(1, Math.min(window.innerWidth || document.documentElement.clientWidth || 1024, 2400));
-  const h = Math.max(1, Math.min(document.documentElement.scrollHeight, 4e3));
-  const inlinedCss = readInlineableStyles();
-  const bodyHtml = serializeComposed(document.body, { stripCrossOriginImages: true }, 0);
-  const htmlStr = `<html xmlns="http://www.w3.org/1999/xhtml"><body>${bodyHtml}</body></html>`;
-  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}"><foreignObject width="100%" height="100%">` + (inlinedCss ? `<style xmlns="http://www.w3.org/1999/xhtml">${escapeForXml(inlinedCss)}</style>` : "") + htmlStr + `</foreignObject></svg>`;
-  const blobUrl = URL.createObjectURL(
-    new Blob([svg], { type: "image/svg+xml;charset=utf-8" })
-  );
+  };
   try {
-    const img = await loadImage(blobUrl);
-    const canvas = document.createElement("canvas");
-    canvas.width = w * dpr;
-    canvas.height = h * dpr;
-    const ctx = canvas.getContext("2d");
-    if (!ctx) throw new Error("canvas 2D context unavailable");
-    const pageBg = getComputedStyle(document.body).backgroundColor || "#ffffff";
-    ctx.fillStyle = pageBg.startsWith("rgba(0, 0, 0, 0)") ? "#ffffff" : pageBg;
-    ctx.fillRect(0, 0, canvas.width, canvas.height);
-    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
-    const dataUrl = canvas.toDataURL("image/jpeg", 0.85);
-    return { data: dataUrl.split(",")[1], format: "jpeg-base64" };
-  } finally {
-    URL.revokeObjectURL(blobUrl);
+    inject(
+      document,
+      collect(document.adoptedStyleSheets)
+    );
+  } catch {
   }
-}
-function loadImage(src) {
-  return new Promise((resolve, reject) => {
-    const img = new Image();
-    img.crossOrigin = "anonymous";
-    img.onload = () => resolve(img);
-    img.onerror = () => reject(new Error("failed to render snapshot SVG"));
-    img.src = src;
-  });
-}
-function escapeForXml(s) {
-  return s.replace(/]]>/g, "]]&gt;").replace(/<\//g, "&lt;/");
-}
-async function captureViaHtmlSnapshot() {
-  const inlinedCss = readInlineableStyles();
-  const bodyHtml = serializeComposed(document.body, { stripCrossOriginImages: false }, 0);
-  const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1">
-<base href="${escapeAttr(location.href)}">
-` + (inlinedCss ? `<style data-botim-snapshot="1">${inlinedCss}</style>
-` : "") + `</head>
-<body>${bodyHtml}</body>
-</html>`;
-  return {
-    data: JSON.stringify({
-      html,
-      viewport: { w: window.innerWidth, h: window.innerHeight },
-      url: location.href,
-      capturedAt: Date.now()
-    }),
-    format: "html-snapshot"
+  const walkRoot = (root) => {
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT);
+    let n = walker.currentNode;
+    while (n) {
+      const el = n;
+      const sr = el.shadowRoot;
+      if (sr) {
+        try {
+          inject(
+            sr,
+            collect(sr.adoptedStyleSheets)
+          );
+        } catch {
+        }
+        walkRoot(sr);
+      }
+      n = walker.nextNode();
+    }
   };
+  try {
+    walkRoot(document);
+  } catch {
+  }
+  return injected;
 }
 function registerBuiltins(registry, hooks = {}) {
   registry.register("ping", ping);