hypha-debugger 0.1.10 → 0.2.0

package/dist/hypha-debugger.mjs

@@ -1968,27 +1968,95 @@ async function toJpeg(node, options = {}) {
 
 /**
  * Screenshot capture service using html-to-image.
+ *
+ * Images are downscaled before being returned so agents don't receive
+ * multi-megabyte base64 payloads that can crash their context window.
  */
-async function takeScreenshot(selector, format, quality, scale, max_width, max_height) {
-    const fmt = format ?? "png";
-    const qual = quality ?? 0.92;
-    const scl = scale ?? 1;
-    const target = selector ? document.querySelector(selector) : document.body;
-    if (!target) {
-        return { error: `No element found for selector: ${selector}` };
+/**
+ * Resize an image data URL via a canvas. Returns a new data URL at the
+ * requested format/quality. Maintains aspect ratio: fits within
+ * (maxWidth × maxHeight) without distortion.
+ */
+async function resizeDataUrl(dataUrl, maxWidth, maxHeight, format, quality) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.onload = () => {
+            const srcW = img.naturalWidth;
+            const srcH = img.naturalHeight;
+            // Compute scale to fit within bounds (but never upscale)
+            const scale = Math.min(maxWidth / srcW, maxHeight / srcH, 1);
+            const dstW = Math.max(1, Math.round(srcW * scale));
+            const dstH = Math.max(1, Math.round(srcH * scale));
+            const canvas = document.createElement("canvas");
+            canvas.width = dstW;
+            canvas.height = dstH;
+            const ctx = canvas.getContext("2d");
+            if (!ctx) {
+                reject(new Error("Could not get 2D canvas context"));
+                return;
+            }
+            // Fill white background for JPEG (no alpha support)
+            if (format === "jpeg") {
+                ctx.fillStyle = "#ffffff";
+                ctx.fillRect(0, 0, dstW, dstH);
+            }
+            ctx.drawImage(img, 0, 0, dstW, dstH);
+            const mime = format === "jpeg" ? "image/jpeg" : "image/png";
+            const out = canvas.toDataURL(mime, quality);
+            resolve({ dataUrl: out, width: dstW, height: dstH });
+        };
+        img.onerror = () => reject(new Error("Failed to load image for resizing"));
+        img.src = dataUrl;
+    });
+}
+async function takeScreenshot(selector, format, quality, max_width, max_height, full_page) {
+    // Agent-friendly defaults: JPEG, moderate quality, capped at 1024px,
+    // viewport-only (not the entire scrollable page).
+    const fmt = format ?? "jpeg";
+    const qual = quality ?? 0.75;
+    const maxW = max_width ?? 1024;
+    const maxH = max_height ?? 1024;
+    const capturePage = full_page ?? false;
+    // Pick target:
+    //   - explicit selector → that element
+    //   - full_page=true → document.documentElement (the entire scrollable page)
+    //   - default → viewport-sized region (clipped to window size)
+    let target;
+    if (selector) {
+        target = document.querySelector(selector);
+        if (!target) {
+            return { error: `No element found for selector: ${selector}` };
+        }
+    }
+    else if (capturePage) {
+        target = document.documentElement;
+    }
+    else {
+        target = document.body;
     }
     try {
         const node = target;
+        // For viewport-only captures, limit html-to-image's output size
+        // to the viewport dimensions.
+        const viewportW = window.innerWidth;
+        const viewportH = window.innerHeight;
         const captureOptions = {
             quality: qual,
-            pixelRatio: scl,
+            pixelRatio: 1, // always capture at 1x — we'll resize after
             cacheBust: true,
             skipAutoScale: true,
-            // Filter out the debugger overlay itself
             filter: (el) => {
-                return el.id !== "hypha-debugger-host";
+                // Exclude the debugger overlay and cursor from screenshots
+                return (el.id !== "hypha-debugger-host" &&
+                    el.id !== "hypha-debugger-cursor" &&
+                    el.id !== "playwright-highlight-container");
             },
         };
+        if (!selector && !capturePage) {
+            // Viewport-only capture: constrain canvas to window size
+            captureOptions.width = viewportW;
+            captureOptions.height = viewportH;
+        }
         let dataUrl;
         if (fmt === "jpeg") {
             dataUrl = await toJpeg(node, captureOptions);
@@ -1996,26 +2064,15 @@ async function takeScreenshot(selector, format, quality, scale, max_width, max_h
         else {
             dataUrl = await toPng(node, captureOptions);
         }
-        // Get dimensions
-        const rect = node.getBoundingClientRect();
-        let width = Math.round(rect.width * scl);
-        let height = Math.round(rect.height * scl);
-        // Optionally resize if too large
-        if (max_width && width > max_width) {
-            const ratio = max_width / width;
-            width = max_width;
-            height = Math.round(height * ratio);
-        }
-        if (max_height && height > max_height) {
-            const ratio = max_height / height;
-            height = max_height;
-            width = Math.round(width * ratio);
-        }
+        // Resize down to fit within (maxW × maxH) and re-encode
+        const resized = await resizeDataUrl(dataUrl, maxW, maxH, fmt, qual);
+        const sizeKb = Math.round((resized.dataUrl.length * 0.75) / 1024); // rough base64 → bytes
         return {
-            data: dataUrl,
+            data: resized.dataUrl,
             format: fmt,
-            width,
-            height,
+            width: resized.width,
+            height: resized.height,
+            size_kb: sizeKb,
         };
     }
     catch (err) {
@@ -2024,34 +2081,37 @@ async function takeScreenshot(selector, format, quality, scale, max_width, max_h
 }
 takeScreenshot.__schema__ = {
     name: "takeScreenshot",
-    description: "Capture a screenshot of the entire page or a specific element. Returns a base64-encoded data URL.",
+    description: "Capture a screenshot of the current viewport, a specific element, or the full page. " +
+        "Returns a base64-encoded data URL, downscaled to fit within max_width × max_height " +
+        "(default 1024px) to keep the payload small enough for AI agents. Defaults to JPEG " +
+        "format at 0.75 quality for reasonable file size.",
     parameters: {
         type: "object",
         properties: {
             selector: {
                 type: "string",
-                description: "CSS selector of the element to capture. Omit to capture the entire page body.",
+                description: "CSS selector of the element to capture. Omit to capture the viewport (or full page if full_page=true).",
             },
             format: {
                 type: "string",
                 enum: ["png", "jpeg"],
-                description: 'Image format. Default: "png".',
+                description: 'Image format. Default: "jpeg" (much smaller than PNG). Use "png" for sharp text.',
             },
             quality: {
                 type: "number",
-                description: "Image quality (0-1) for JPEG. Default: 0.92.",
-            },
-            scale: {
-                type: "number",
-                description: "Pixel ratio / scale factor. Default: 1. Use 2 for retina.",
+                description: "JPEG quality (0–1). Default: 0.75. Ignored for PNG. Lower = smaller payload.",
             },
             max_width: {
                 type: "number",
-                description: "Maximum width in pixels. Image will be scaled down if larger.",
+                description: "Maximum output width in pixels. Default: 1024. Image is scaled down preserving aspect ratio.",
             },
             max_height: {
                 type: "number",
-                description: "Maximum height in pixels. Image will be scaled down if larger.",
+                description: "Maximum output height in pixels. Default: 1024. Image is scaled down preserving aspect ratio.",
+            },
+            full_page: {
+                type: "boolean",
+                description: "If true, capture the entire scrollable page instead of just the viewport. Default: false.",
             },
         },
     },