@botim/mp-debug-sdk 1.2.0 → 1.3.0

package/dist/auto.cjs

@@ -1036,7 +1036,27 @@ var MAX_EXEC_CODE_BYTES = 8 * 1024;
 var DEFAULT_EXEC_TIMEOUT_MS = 5e3;
 var MIN_EXEC_TIMEOUT_MS = 250;
 var MAX_EXEC_TIMEOUT_MS = 3e4;
-async function defaultDomScreenshot() {
+var SCREENSHOT_FORMATS = [
+  "png-base64",
+  "jpeg-base64",
+  "rrweb-snapshot",
+  "html-snapshot"
+];
+var DEFAULT_JPEG_QUALITY = 0.85;
+async function defaultDomScreenshot(requested, quality) {
+  switch (requested) {
+    case "png-base64":
+      return rasterizeDom("image/png");
+    case "jpeg-base64":
+      return rasterizeDom("image/jpeg", quality ?? DEFAULT_JPEG_QUALITY);
+    case "html-snapshot":
+      return domHtmlSnapshot();
+    case "rrweb-snapshot":
+    default:
+      return rrwebDomSnapshot();
+  }
+}
+async function rrwebDomSnapshot() {
   if (typeof document === "undefined" || typeof window === "undefined") {
     throw new Error(
       "[@botim/debug-sdk] default screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
@@ -1085,6 +1105,126 @@ async function defaultDomScreenshot() {
     format: "rrweb-snapshot"
   };
 }
+function domViewport() {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    throw new Error(
+      "[@botim/debug-sdk] screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
+    );
+  }
+  return {
+    w: window.innerWidth || document.documentElement.clientWidth || 0,
+    h: window.innerHeight || document.documentElement.clientHeight || 0
+  };
+}
+async function rasterizeDom(mime, quality) {
+  const { w, h } = domViewport();
+  if (!w || !h) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: viewport has zero size.");
+  }
+  const canvas = document.createElement("canvas");
+  if (typeof canvas.getContext !== "function") {
+    throw new Error(
+      '[@botim/debug-sdk] raster screenshot: <canvas> unavailable in this runtime \u2014 request format "rrweb-snapshot" instead, or wire builtins.screenshot.'
+    );
+  }
+  const injected = injectAdoptedStyleSheets();
+  let svgUrl;
+  try {
+    const css = collectDocumentCss();
+    const bodyClone = document.body.cloneNode(true);
+    bodyClone.querySelectorAll("script, noscript").forEach((n) => n.remove());
+    const bodyXml = new XMLSerializer().serializeToString(bodyClone);
+    const bg = safeBodyBackground();
+    const markup = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}"><foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="width:${w}px;height:${h}px;overflow:hidden;background:${bg}"><style>${css}</style>${bodyXml}</div></foreignObject></svg>`;
+    svgUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  const img = await loadImage(svgUrl);
+  canvas.width = w;
+  canvas.height = h;
+  const cx = canvas.getContext("2d");
+  if (!cx) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: 2D canvas context unavailable.");
+  }
+  cx.drawImage(img, 0, 0, w, h);
+  let dataUrl;
+  try {
+    dataUrl = canvas.toDataURL(mime, quality);
+  } catch (err) {
+    throw new Error(
+      `[@botim/debug-sdk] raster screenshot: canvas tainted by a cross-origin image/font without CORS \u2014 request "rrweb-snapshot" for full fidelity. (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+  const comma = dataUrl.indexOf(",");
+  const data = comma >= 0 ? dataUrl.slice(comma + 1) : "";
+  if (!data) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: encoder returned empty image data.");
+  }
+  return { data, format: mime === "image/png" ? "png-base64" : "jpeg-base64" };
+}
+function loadImage(src) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(
+      new Error(
+        "[@botim/debug-sdk] raster screenshot: the offscreen SVG failed to render (often a non-XML-serializable DOM or a blocked resource)."
+      )
+    );
+    img.src = src;
+  });
+}
+function collectDocumentCss() {
+  const chunks = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    try {
+      for (const rule of Array.from(sheet.cssRules)) chunks.push(rule.cssText);
+    } catch {
+    }
+  }
+  return chunks.join("\n");
+}
+function safeBodyBackground() {
+  try {
+    const bg = getComputedStyle(document.body).backgroundColor;
+    if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") return bg;
+  } catch {
+  }
+  return "#ffffff";
+}
+async function domHtmlSnapshot() {
+  const { w, h } = domViewport();
+  const injected = injectAdoptedStyleSheets();
+  let html;
+  try {
+    const clone = document.documentElement.cloneNode(true);
+    clone.querySelectorAll("script").forEach((n) => n.remove());
+    html = `<!doctype html>
+${clone.outerHTML}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  return {
+    data: JSON.stringify({
+      html,
+      viewport: { w, h },
+      url: location.href,
+      capturedAt: Date.now()
+    }),
+    format: "html-snapshot"
+  };
+}
 function injectAdoptedStyleSheets() {
   const injected = [];
   const collect = (sheets) => {
@@ -1189,10 +1329,18 @@ function makeSetFlag(setFeatureFlag) {
     return { applied: true, key };
   };
 }
+function normalizeFormat(v) {
+  return typeof v === "string" && SCREENSHOT_FORMATS.includes(v) ? v : void 0;
+}
+function normalizeQuality(v) {
+  if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+  return Math.min(1, Math.max(0, v));
+}
 function makeScreenshot(screenshot) {
-  const capture = screenshot ?? defaultDomScreenshot;
-  return async () => {
-    const result = await capture();
+  return async (args) => {
+    const requested = normalizeFormat(args.format);
+    const quality = normalizeQuality(args.quality);
+    const result = screenshot ? await screenshot(requested) : await defaultDomScreenshot(requested, quality);
     let data;
     let format;
     if (typeof result === "string") {
@@ -1863,6 +2011,7 @@ exports.DEFAULT_MAX_BATCH_SIZE = DEFAULT_MAX_BATCH_SIZE;
 exports.DEFAULT_MAX_BODY_BYTES = DEFAULT_MAX_BODY_BYTES;
 exports.DEFAULT_REDACT_HEADERS = DEFAULT_REDACT_HEADERS;
 exports.SCHEMA_VERSION = SCHEMA_VERSION;
+exports.SCREENSHOT_FORMATS = SCREENSHOT_FORMATS;
 exports.clearConsentDecision = clearConsentDecision;
 exports.enableRemoteDebug = enableRemoteDebug;
 exports.getBOT = getBOT;

package/dist/auto.d.cts

@@ -1,2 +1,2 @@
-export { AppInfo, BotimConfigError, BotimConsentError, BuiltinHostHooks, ConsentDecision, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, DedupOptions, ExecOptions, RedactionConfig, RemoteDebugHandle, RemoteDebugOptions, SamplingConfig, SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision } from './index.cjs';
+export { AppInfo, BotimConfigError, BotimConsentError, BuiltinHostHooks, ConsentDecision, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, DedupOptions, ExecOptions, RedactionConfig, RemoteDebugHandle, RemoteDebugOptions, SCREENSHOT_FORMATS, SamplingConfig, ScreenshotFormat, ScreenshotResult, SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision } from './index.cjs';
 export { AttachRequest, AttachResponse, BotimConfig, BotimEnv, BridgePayload, CommandAckPayload, CommandContext, CommandHandler, CommandPollResponse, CommandRejectedPayload, CommandRequest, ConsentInput, ConsentPromptCopy, ConsolePayload, DebugEvent, DebugEventBase, DeviceInfo, ErrorPayload, ErrorSource, EventLevel, EventMeta, EventType, LifecycleEvent, LifecyclePayload, NetworkPayload, NetworkPhase, PerfPayload, SCHEMA_VERSION, SerializedValue, StreamFrame, UploadAck, UploadBatch } from './types.cjs';

package/dist/auto.d.ts

@@ -1,2 +1,2 @@
-export { AppInfo, BotimConfigError, BotimConsentError, BuiltinHostHooks, ConsentDecision, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, DedupOptions, ExecOptions, RedactionConfig, RemoteDebugHandle, RemoteDebugOptions, SamplingConfig, SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision } from './index.js';
+export { AppInfo, BotimConfigError, BotimConsentError, BuiltinHostHooks, ConsentDecision, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, DedupOptions, ExecOptions, RedactionConfig, RemoteDebugHandle, RemoteDebugOptions, SCREENSHOT_FORMATS, SamplingConfig, ScreenshotFormat, ScreenshotResult, SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision } from './index.js';
 export { AttachRequest, AttachResponse, BotimConfig, BotimEnv, BridgePayload, CommandAckPayload, CommandContext, CommandHandler, CommandPollResponse, CommandRejectedPayload, CommandRequest, ConsentInput, ConsentPromptCopy, ConsolePayload, DebugEvent, DebugEventBase, DeviceInfo, ErrorPayload, ErrorSource, EventLevel, EventMeta, EventType, LifecycleEvent, LifecyclePayload, NetworkPayload, NetworkPhase, PerfPayload, SCHEMA_VERSION, SerializedValue, StreamFrame, UploadAck, UploadBatch } from './types.js';

package/dist/auto.js

@@ -1034,7 +1034,27 @@ var MAX_EXEC_CODE_BYTES = 8 * 1024;
 var DEFAULT_EXEC_TIMEOUT_MS = 5e3;
 var MIN_EXEC_TIMEOUT_MS = 250;
 var MAX_EXEC_TIMEOUT_MS = 3e4;
-async function defaultDomScreenshot() {
+var SCREENSHOT_FORMATS = [
+  "png-base64",
+  "jpeg-base64",
+  "rrweb-snapshot",
+  "html-snapshot"
+];
+var DEFAULT_JPEG_QUALITY = 0.85;
+async function defaultDomScreenshot(requested, quality) {
+  switch (requested) {
+    case "png-base64":
+      return rasterizeDom("image/png");
+    case "jpeg-base64":
+      return rasterizeDom("image/jpeg", quality ?? DEFAULT_JPEG_QUALITY);
+    case "html-snapshot":
+      return domHtmlSnapshot();
+    case "rrweb-snapshot":
+    default:
+      return rrwebDomSnapshot();
+  }
+}
+async function rrwebDomSnapshot() {
   if (typeof document === "undefined" || typeof window === "undefined") {
     throw new Error(
       "[@botim/debug-sdk] default screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
@@ -1083,6 +1103,126 @@ async function defaultDomScreenshot() {
     format: "rrweb-snapshot"
   };
 }
+function domViewport() {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    throw new Error(
+      "[@botim/debug-sdk] screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
+    );
+  }
+  return {
+    w: window.innerWidth || document.documentElement.clientWidth || 0,
+    h: window.innerHeight || document.documentElement.clientHeight || 0
+  };
+}
+async function rasterizeDom(mime, quality) {
+  const { w, h } = domViewport();
+  if (!w || !h) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: viewport has zero size.");
+  }
+  const canvas = document.createElement("canvas");
+  if (typeof canvas.getContext !== "function") {
+    throw new Error(
+      '[@botim/debug-sdk] raster screenshot: <canvas> unavailable in this runtime \u2014 request format "rrweb-snapshot" instead, or wire builtins.screenshot.'
+    );
+  }
+  const injected = injectAdoptedStyleSheets();
+  let svgUrl;
+  try {
+    const css = collectDocumentCss();
+    const bodyClone = document.body.cloneNode(true);
+    bodyClone.querySelectorAll("script, noscript").forEach((n) => n.remove());
+    const bodyXml = new XMLSerializer().serializeToString(bodyClone);
+    const bg = safeBodyBackground();
+    const markup = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}"><foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="width:${w}px;height:${h}px;overflow:hidden;background:${bg}"><style>${css}</style>${bodyXml}</div></foreignObject></svg>`;
+    svgUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  const img = await loadImage(svgUrl);
+  canvas.width = w;
+  canvas.height = h;
+  const cx = canvas.getContext("2d");
+  if (!cx) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: 2D canvas context unavailable.");
+  }
+  cx.drawImage(img, 0, 0, w, h);
+  let dataUrl;
+  try {
+    dataUrl = canvas.toDataURL(mime, quality);
+  } catch (err) {
+    throw new Error(
+      `[@botim/debug-sdk] raster screenshot: canvas tainted by a cross-origin image/font without CORS \u2014 request "rrweb-snapshot" for full fidelity. (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+  const comma = dataUrl.indexOf(",");
+  const data = comma >= 0 ? dataUrl.slice(comma + 1) : "";
+  if (!data) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: encoder returned empty image data.");
+  }
+  return { data, format: mime === "image/png" ? "png-base64" : "jpeg-base64" };
+}
+function loadImage(src) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(
+      new Error(
+        "[@botim/debug-sdk] raster screenshot: the offscreen SVG failed to render (often a non-XML-serializable DOM or a blocked resource)."
+      )
+    );
+    img.src = src;
+  });
+}
+function collectDocumentCss() {
+  const chunks = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    try {
+      for (const rule of Array.from(sheet.cssRules)) chunks.push(rule.cssText);
+    } catch {
+    }
+  }
+  return chunks.join("\n");
+}
+function safeBodyBackground() {
+  try {
+    const bg = getComputedStyle(document.body).backgroundColor;
+    if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") return bg;
+  } catch {
+  }
+  return "#ffffff";
+}
+async function domHtmlSnapshot() {
+  const { w, h } = domViewport();
+  const injected = injectAdoptedStyleSheets();
+  let html;
+  try {
+    const clone = document.documentElement.cloneNode(true);
+    clone.querySelectorAll("script").forEach((n) => n.remove());
+    html = `<!doctype html>
+${clone.outerHTML}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  return {
+    data: JSON.stringify({
+      html,
+      viewport: { w, h },
+      url: location.href,
+      capturedAt: Date.now()
+    }),
+    format: "html-snapshot"
+  };
+}
 function injectAdoptedStyleSheets() {
   const injected = [];
   const collect = (sheets) => {
@@ -1187,10 +1327,18 @@ function makeSetFlag(setFeatureFlag) {
     return { applied: true, key };
   };
 }
+function normalizeFormat(v) {
+  return typeof v === "string" && SCREENSHOT_FORMATS.includes(v) ? v : void 0;
+}
+function normalizeQuality(v) {
+  if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+  return Math.min(1, Math.max(0, v));
+}
 function makeScreenshot(screenshot) {
-  const capture = screenshot ?? defaultDomScreenshot;
-  return async () => {
-    const result = await capture();
+  return async (args) => {
+    const requested = normalizeFormat(args.format);
+    const quality = normalizeQuality(args.quality);
+    const result = screenshot ? await screenshot(requested) : await defaultDomScreenshot(requested, quality);
     let data;
     let format;
     if (typeof result === "string") {
@@ -1852,6 +2000,6 @@ async function enableRemoteDebug(options) {
 // src/auto.ts
 setDefaultBotimConfig(botimConfig);
 
-export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };
+export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, SCREENSHOT_FORMATS, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };
 //# sourceMappingURL=auto.js.map
 //# sourceMappingURL=auto.js.map

package/dist/index.cjs

@@ -1033,7 +1033,27 @@ var MAX_EXEC_CODE_BYTES = 8 * 1024;
 var DEFAULT_EXEC_TIMEOUT_MS = 5e3;
 var MIN_EXEC_TIMEOUT_MS = 250;
 var MAX_EXEC_TIMEOUT_MS = 3e4;
-async function defaultDomScreenshot() {
+var SCREENSHOT_FORMATS = [
+  "png-base64",
+  "jpeg-base64",
+  "rrweb-snapshot",
+  "html-snapshot"
+];
+var DEFAULT_JPEG_QUALITY = 0.85;
+async function defaultDomScreenshot(requested, quality) {
+  switch (requested) {
+    case "png-base64":
+      return rasterizeDom("image/png");
+    case "jpeg-base64":
+      return rasterizeDom("image/jpeg", quality ?? DEFAULT_JPEG_QUALITY);
+    case "html-snapshot":
+      return domHtmlSnapshot();
+    case "rrweb-snapshot":
+    default:
+      return rrwebDomSnapshot();
+  }
+}
+async function rrwebDomSnapshot() {
   if (typeof document === "undefined" || typeof window === "undefined") {
     throw new Error(
       "[@botim/debug-sdk] default screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
@@ -1082,6 +1102,126 @@ async function defaultDomScreenshot() {
     format: "rrweb-snapshot"
   };
 }
+function domViewport() {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    throw new Error(
+      "[@botim/debug-sdk] screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
+    );
+  }
+  return {
+    w: window.innerWidth || document.documentElement.clientWidth || 0,
+    h: window.innerHeight || document.documentElement.clientHeight || 0
+  };
+}
+async function rasterizeDom(mime, quality) {
+  const { w, h } = domViewport();
+  if (!w || !h) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: viewport has zero size.");
+  }
+  const canvas = document.createElement("canvas");
+  if (typeof canvas.getContext !== "function") {
+    throw new Error(
+      '[@botim/debug-sdk] raster screenshot: <canvas> unavailable in this runtime \u2014 request format "rrweb-snapshot" instead, or wire builtins.screenshot.'
+    );
+  }
+  const injected = injectAdoptedStyleSheets();
+  let svgUrl;
+  try {
+    const css = collectDocumentCss();
+    const bodyClone = document.body.cloneNode(true);
+    bodyClone.querySelectorAll("script, noscript").forEach((n) => n.remove());
+    const bodyXml = new XMLSerializer().serializeToString(bodyClone);
+    const bg = safeBodyBackground();
+    const markup = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}"><foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="width:${w}px;height:${h}px;overflow:hidden;background:${bg}"><style>${css}</style>${bodyXml}</div></foreignObject></svg>`;
+    svgUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  const img = await loadImage(svgUrl);
+  canvas.width = w;
+  canvas.height = h;
+  const cx = canvas.getContext("2d");
+  if (!cx) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: 2D canvas context unavailable.");
+  }
+  cx.drawImage(img, 0, 0, w, h);
+  let dataUrl;
+  try {
+    dataUrl = canvas.toDataURL(mime, quality);
+  } catch (err) {
+    throw new Error(
+      `[@botim/debug-sdk] raster screenshot: canvas tainted by a cross-origin image/font without CORS \u2014 request "rrweb-snapshot" for full fidelity. (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+  const comma = dataUrl.indexOf(",");
+  const data = comma >= 0 ? dataUrl.slice(comma + 1) : "";
+  if (!data) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: encoder returned empty image data.");
+  }
+  return { data, format: mime === "image/png" ? "png-base64" : "jpeg-base64" };
+}
+function loadImage(src) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(
+      new Error(
+        "[@botim/debug-sdk] raster screenshot: the offscreen SVG failed to render (often a non-XML-serializable DOM or a blocked resource)."
+      )
+    );
+    img.src = src;
+  });
+}
+function collectDocumentCss() {
+  const chunks = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    try {
+      for (const rule of Array.from(sheet.cssRules)) chunks.push(rule.cssText);
+    } catch {
+    }
+  }
+  return chunks.join("\n");
+}
+function safeBodyBackground() {
+  try {
+    const bg = getComputedStyle(document.body).backgroundColor;
+    if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") return bg;
+  } catch {
+  }
+  return "#ffffff";
+}
+async function domHtmlSnapshot() {
+  const { w, h } = domViewport();
+  const injected = injectAdoptedStyleSheets();
+  let html;
+  try {
+    const clone = document.documentElement.cloneNode(true);
+    clone.querySelectorAll("script").forEach((n) => n.remove());
+    html = `<!doctype html>
+${clone.outerHTML}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  return {
+    data: JSON.stringify({
+      html,
+      viewport: { w, h },
+      url: location.href,
+      capturedAt: Date.now()
+    }),
+    format: "html-snapshot"
+  };
+}
 function injectAdoptedStyleSheets() {
   const injected = [];
   const collect = (sheets) => {
@@ -1186,10 +1326,18 @@ function makeSetFlag(setFeatureFlag) {
     return { applied: true, key };
   };
 }
+function normalizeFormat(v) {
+  return typeof v === "string" && SCREENSHOT_FORMATS.includes(v) ? v : void 0;
+}
+function normalizeQuality(v) {
+  if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+  return Math.min(1, Math.max(0, v));
+}
 function makeScreenshot(screenshot) {
-  const capture = screenshot ?? defaultDomScreenshot;
-  return async () => {
-    const result = await capture();
+  return async (args) => {
+    const requested = normalizeFormat(args.format);
+    const quality = normalizeQuality(args.quality);
+    const result = screenshot ? await screenshot(requested) : await defaultDomScreenshot(requested, quality);
     let data;
     let format;
     if (typeof result === "string") {
@@ -1857,6 +2005,7 @@ exports.DEFAULT_MAX_BATCH_SIZE = DEFAULT_MAX_BATCH_SIZE;
 exports.DEFAULT_MAX_BODY_BYTES = DEFAULT_MAX_BODY_BYTES;
 exports.DEFAULT_REDACT_HEADERS = DEFAULT_REDACT_HEADERS;
 exports.SCHEMA_VERSION = SCHEMA_VERSION;
+exports.SCREENSHOT_FORMATS = SCREENSHOT_FORMATS;
 exports.clearConsentDecision = clearConsentDecision;
 exports.enableRemoteDebug = enableRemoteDebug;
 exports.getBOT = getBOT;

package/dist/index.d.cts

@@ -99,15 +99,18 @@ interface BuiltinHostHooks {
     /** Apply a feature flag override. */
     setFeatureFlag?: (key: string, value: unknown) => void | Promise<void>;
     /**
-     * Capture a screenshot. Two return shapes are accepted:
+     * Capture a screenshot. Receives the format the caller requested (the
+     * command's `args.format`, validated to a known value or `undefined`) so
+     * the host can honor it — though the host MAY ignore it and return whatever
+     * it can produce. Two return shapes are accepted:
      *   - a raw base64 string  → assumed PNG (legacy form)
      *   - `{ 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, … }
+     *       'html-snapshot'              — `data` JSON: { html, … }
      * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
-    screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
+    screenshot?: (format?: ScreenshotFormat) => ScreenshotResult | Promise<ScreenshotResult>;
     /**
      * Default-enabled remote-eval command (`exec`). Pass `false` to opt out
      * of registration entirely; pass an object to inject extra locals into
@@ -139,23 +142,22 @@ interface ExecOptions {
      */
     globals?: Record<string, unknown>;
 }
+/**
+ * Wire-level screenshot formats. The caller asks for one via the command's
+ * `args.format`; the capture path produces the matching `data`:
+ *   - 'png-base64' | 'jpeg-base64' — base64 raster bitmap; viewer renders <img>.
+ *   - 'rrweb-snapshot' — JSON `{ snapshot, viewport, 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. This is the default (no format requested).
+ *   - 'html-snapshot' — JSON `{ html, viewport, url, capturedAt }`; viewer
+ *       renders it via `iframe.srcdoc`.
+ */
+declare const SCREENSHOT_FORMATS: readonly ["png-base64", "jpeg-base64", "rrweb-snapshot", "html-snapshot"];
+type ScreenshotFormat = (typeof SCREENSHOT_FORMATS)[number];
 type ScreenshotResult = string | {
     data: string;
-    format?: 'png-base64' | 'jpeg-base64'
-    /**
-     * 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';
+    format?: ScreenshotFormat;
 };
 declare function getBOT(): unknown;
 
@@ -302,4 +304,4 @@ declare const DEFAULT_MAX_BATCH_SIZE = 50;
 declare function setDefaultBotimConfig(config: BotimConfig | null): void;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, SCREENSHOT_FORMATS, type SamplingConfig, type ScreenshotFormat, type ScreenshotResult, type SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };

package/dist/index.d.ts

@@ -99,15 +99,18 @@ interface BuiltinHostHooks {
     /** Apply a feature flag override. */
     setFeatureFlag?: (key: string, value: unknown) => void | Promise<void>;
     /**
-     * Capture a screenshot. Two return shapes are accepted:
+     * Capture a screenshot. Receives the format the caller requested (the
+     * command's `args.format`, validated to a known value or `undefined`) so
+     * the host can honor it — though the host MAY ignore it and return whatever
+     * it can produce. Two return shapes are accepted:
      *   - a raw base64 string  → assumed PNG (legacy form)
      *   - `{ 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, … }
+     *       'html-snapshot'              — `data` JSON: { html, … }
      * The SDK enforces a 1 MB base64/JSON cap regardless.
      */
-    screenshot?: () => ScreenshotResult | Promise<ScreenshotResult>;
+    screenshot?: (format?: ScreenshotFormat) => ScreenshotResult | Promise<ScreenshotResult>;
     /**
      * Default-enabled remote-eval command (`exec`). Pass `false` to opt out
      * of registration entirely; pass an object to inject extra locals into
@@ -139,23 +142,22 @@ interface ExecOptions {
      */
     globals?: Record<string, unknown>;
 }
+/**
+ * Wire-level screenshot formats. The caller asks for one via the command's
+ * `args.format`; the capture path produces the matching `data`:
+ *   - 'png-base64' | 'jpeg-base64' — base64 raster bitmap; viewer renders <img>.
+ *   - 'rrweb-snapshot' — JSON `{ snapshot, viewport, 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. This is the default (no format requested).
+ *   - 'html-snapshot' — JSON `{ html, viewport, url, capturedAt }`; viewer
+ *       renders it via `iframe.srcdoc`.
+ */
+declare const SCREENSHOT_FORMATS: readonly ["png-base64", "jpeg-base64", "rrweb-snapshot", "html-snapshot"];
+type ScreenshotFormat = (typeof SCREENSHOT_FORMATS)[number];
 type ScreenshotResult = string | {
     data: string;
-    format?: 'png-base64' | 'jpeg-base64'
-    /**
-     * 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';
+    format?: ScreenshotFormat;
 };
 declare function getBOT(): unknown;
 
@@ -302,4 +304,4 @@ declare const DEFAULT_MAX_BATCH_SIZE = 50;
 declare function setDefaultBotimConfig(config: BotimConfig | null): void;
 declare function enableRemoteDebug(options: RemoteDebugOptions): Promise<RemoteDebugHandle>;
 
-export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, type SamplingConfig, type SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };
+export { type AppInfo, BotimConfig, BotimConfigError, BotimConsentError, type BuiltinHostHooks, CommandHandler, type ConsentDecision, ConsentInput, ConsentPromptCopy, ConsolePayload, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, type DedupOptions, DeviceInfo, ErrorPayload, EventLevel, EventType, type ExecOptions, NetworkPayload, type RedactionConfig, type RemoteDebugHandle, type RemoteDebugOptions, SCREENSHOT_FORMATS, type SamplingConfig, type ScreenshotFormat, type ScreenshotResult, type SuppressionSummary, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };

package/dist/index.js

@@ -1031,7 +1031,27 @@ var MAX_EXEC_CODE_BYTES = 8 * 1024;
 var DEFAULT_EXEC_TIMEOUT_MS = 5e3;
 var MIN_EXEC_TIMEOUT_MS = 250;
 var MAX_EXEC_TIMEOUT_MS = 3e4;
-async function defaultDomScreenshot() {
+var SCREENSHOT_FORMATS = [
+  "png-base64",
+  "jpeg-base64",
+  "rrweb-snapshot",
+  "html-snapshot"
+];
+var DEFAULT_JPEG_QUALITY = 0.85;
+async function defaultDomScreenshot(requested, quality) {
+  switch (requested) {
+    case "png-base64":
+      return rasterizeDom("image/png");
+    case "jpeg-base64":
+      return rasterizeDom("image/jpeg", quality ?? DEFAULT_JPEG_QUALITY);
+    case "html-snapshot":
+      return domHtmlSnapshot();
+    case "rrweb-snapshot":
+    default:
+      return rrwebDomSnapshot();
+  }
+}
+async function rrwebDomSnapshot() {
   if (typeof document === "undefined" || typeof window === "undefined") {
     throw new Error(
       "[@botim/debug-sdk] default screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
@@ -1080,6 +1100,126 @@ async function defaultDomScreenshot() {
     format: "rrweb-snapshot"
   };
 }
+function domViewport() {
+  if (typeof document === "undefined" || typeof window === "undefined") {
+    throw new Error(
+      "[@botim/debug-sdk] screenshot requires a DOM. Provide builtins.screenshot for non-browser runtimes (e.g. native bridge)."
+    );
+  }
+  return {
+    w: window.innerWidth || document.documentElement.clientWidth || 0,
+    h: window.innerHeight || document.documentElement.clientHeight || 0
+  };
+}
+async function rasterizeDom(mime, quality) {
+  const { w, h } = domViewport();
+  if (!w || !h) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: viewport has zero size.");
+  }
+  const canvas = document.createElement("canvas");
+  if (typeof canvas.getContext !== "function") {
+    throw new Error(
+      '[@botim/debug-sdk] raster screenshot: <canvas> unavailable in this runtime \u2014 request format "rrweb-snapshot" instead, or wire builtins.screenshot.'
+    );
+  }
+  const injected = injectAdoptedStyleSheets();
+  let svgUrl;
+  try {
+    const css = collectDocumentCss();
+    const bodyClone = document.body.cloneNode(true);
+    bodyClone.querySelectorAll("script, noscript").forEach((n) => n.remove());
+    const bodyXml = new XMLSerializer().serializeToString(bodyClone);
+    const bg = safeBodyBackground();
+    const markup = `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}"><foreignObject x="0" y="0" width="100%" height="100%"><div xmlns="http://www.w3.org/1999/xhtml" style="width:${w}px;height:${h}px;overflow:hidden;background:${bg}"><style>${css}</style>${bodyXml}</div></foreignObject></svg>`;
+    svgUrl = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  const img = await loadImage(svgUrl);
+  canvas.width = w;
+  canvas.height = h;
+  const cx = canvas.getContext("2d");
+  if (!cx) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: 2D canvas context unavailable.");
+  }
+  cx.drawImage(img, 0, 0, w, h);
+  let dataUrl;
+  try {
+    dataUrl = canvas.toDataURL(mime, quality);
+  } catch (err) {
+    throw new Error(
+      `[@botim/debug-sdk] raster screenshot: canvas tainted by a cross-origin image/font without CORS \u2014 request "rrweb-snapshot" for full fidelity. (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+  const comma = dataUrl.indexOf(",");
+  const data = comma >= 0 ? dataUrl.slice(comma + 1) : "";
+  if (!data) {
+    throw new Error("[@botim/debug-sdk] raster screenshot: encoder returned empty image data.");
+  }
+  return { data, format: mime === "image/png" ? "png-base64" : "jpeg-base64" };
+}
+function loadImage(src) {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () => reject(
+      new Error(
+        "[@botim/debug-sdk] raster screenshot: the offscreen SVG failed to render (often a non-XML-serializable DOM or a blocked resource)."
+      )
+    );
+    img.src = src;
+  });
+}
+function collectDocumentCss() {
+  const chunks = [];
+  for (const sheet of Array.from(document.styleSheets)) {
+    try {
+      for (const rule of Array.from(sheet.cssRules)) chunks.push(rule.cssText);
+    } catch {
+    }
+  }
+  return chunks.join("\n");
+}
+function safeBodyBackground() {
+  try {
+    const bg = getComputedStyle(document.body).backgroundColor;
+    if (bg && bg !== "transparent" && bg !== "rgba(0, 0, 0, 0)") return bg;
+  } catch {
+  }
+  return "#ffffff";
+}
+async function domHtmlSnapshot() {
+  const { w, h } = domViewport();
+  const injected = injectAdoptedStyleSheets();
+  let html;
+  try {
+    const clone = document.documentElement.cloneNode(true);
+    clone.querySelectorAll("script").forEach((n) => n.remove());
+    html = `<!doctype html>
+${clone.outerHTML}`;
+  } finally {
+    for (const node of injected) {
+      try {
+        node.remove();
+      } catch {
+      }
+    }
+  }
+  return {
+    data: JSON.stringify({
+      html,
+      viewport: { w, h },
+      url: location.href,
+      capturedAt: Date.now()
+    }),
+    format: "html-snapshot"
+  };
+}
 function injectAdoptedStyleSheets() {
   const injected = [];
   const collect = (sheets) => {
@@ -1184,10 +1324,18 @@ function makeSetFlag(setFeatureFlag) {
     return { applied: true, key };
   };
 }
+function normalizeFormat(v) {
+  return typeof v === "string" && SCREENSHOT_FORMATS.includes(v) ? v : void 0;
+}
+function normalizeQuality(v) {
+  if (typeof v !== "number" || !Number.isFinite(v)) return void 0;
+  return Math.min(1, Math.max(0, v));
+}
 function makeScreenshot(screenshot) {
-  const capture = screenshot ?? defaultDomScreenshot;
-  return async () => {
-    const result = await capture();
+  return async (args) => {
+    const requested = normalizeFormat(args.format);
+    const quality = normalizeQuality(args.quality);
+    const result = screenshot ? await screenshot(requested) : await defaultDomScreenshot(requested, quality);
     let data;
     let format;
     if (typeof result === "string") {
@@ -1846,6 +1994,6 @@ async function enableRemoteDebug(options) {
   };
 }
 
-export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };
+export { BotimConfigError, BotimConsentError, DEFAULT_BODY_PATTERNS, DEFAULT_BUFFER_SIZE, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_MAX_BATCH_SIZE, DEFAULT_MAX_BODY_BYTES, DEFAULT_REDACT_HEADERS, SCHEMA_VERSION, SCREENSHOT_FORMATS, clearConsentDecision, enableRemoteDebug, getBOT, promptForConsent, readConsentDecision, setDefaultBotimConfig, writeConsentDecision };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botim/mp-debug-sdk",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Remote-debug SDK for BOTIM mini-programs — streams console, network, and error events to a BOTIM debug-relay for live inspection, with an AI-observable command channel.",
   "type": "module",
   "main": "./dist/index.cjs",