hypha-debugger 0.1.3 → 0.1.5

package/dist/debugger.d.ts

@@ -45,9 +45,21 @@ export declare class HyphaDebugger {
     private cursor;
     private server;
     private serviceInfo;
+    private boundBeforeUnload;
     constructor(config: DebuggerConfig);
     start(): Promise<DebugSession>;
     destroy(): Promise<void>;
+    /**
+     * Persist debugger config to sessionStorage so the debugger can
+     * auto-reconnect after a page reload (soft reload injects the script,
+     * autoStart() reads this config).
+     */
+    private saveConfigToStorage;
+    /**
+     * Detect the URL of the currently loaded hypha-debugger script.
+     * Used by navigate.ts to inject the correct script after soft reload.
+     */
+    private detectScriptUrl;
     /**
      * Generate token, build service URL, update overlay instructions, and
      * return a DebugSession.
@@ -66,13 +78,13 @@ export declare class HyphaDebugger {
     /** Build the instruction block for the overlay panel. */
     private buildInstructionBlock;
     /**
-     * Wrap a service function with logging and correct parameter names.
+     * Wrap a service function with overlay logging + correct parameter names.
      *
-     * Uses new Function() to create a wrapper whose parameter names match
-     * the __schema__ property names. This is critical for production builds
-     * where Babel/Terser minifies parameter names — hypha-rpc's
-     * getParamNames() parses Function.toString() to map kwargs to positional
-     * args, so the wrapper must have the real (unminified) parameter names.
+     * Adds logging around the function, then applies baseWrapFn() which uses
+     * new Function() to create a wrapper with unminified parameter names from
+     * __schema__. This is critical for production builds where Babel/Terser
+     * minifies parameter names — hypha-rpc's getParamNames() parses
+     * Function.toString() to map kwargs to positional args.
      */
     private wrapFn;
     private summarizeArgs;

package/dist/hypha-debugger.js

@@ -9199,6 +9199,31 @@
           },
       },
   };
+  function getConsoleLogs(options) {
+      const logs = window.__HYPHA_DEBUGGER__?.consoleLogs ?? [];
+      const level = options?.level;
+      const limit = options?.limit ?? 100;
+      let filtered = level ? logs.filter((l) => l.level === level) : logs;
+      return filtered.slice(-limit);
+  }
+  getConsoleLogs.__schema__ = {
+      name: "getConsoleLogs",
+      description: "Retrieve captured console output (log, warn, error, info).",
+      parameters: {
+          type: "object",
+          properties: {
+              level: {
+                  type: "string",
+                  description: 'Filter by log level: "log", "warn", "error", "info". Omit for all levels.',
+                  enum: ["log", "warn", "error", "info"],
+              },
+              limit: {
+                  type: "number",
+                  description: "Maximum number of log entries to return (most recent). Default: 100.",
+              },
+          },
+      },
+  };
   /** Install console interceptor to capture logs. */
   function installConsoleCapture(maxEntries = 500) {
       var _a;
@@ -9398,6 +9423,88 @@
           required: ["target"],
       },
   };
+  function getComputedStyles(selector, properties) {
+      const el = document.querySelector(selector);
+      if (!el) {
+          return { error: `No element found for selector: ${selector}` };
+      }
+      const computed = getComputedStyle(el);
+      const result = {};
+      const props = properties ??
+          [
+              "display",
+              "position",
+              "width",
+              "height",
+              "color",
+              "background-color",
+              "font-size",
+              "font-family",
+              "margin",
+              "padding",
+              "border",
+              "opacity",
+              "visibility",
+              "overflow",
+              "z-index",
+          ];
+      for (const prop of props) {
+          result[prop] = computed.getPropertyValue(prop);
+      }
+      return result;
+  }
+  getComputedStyles.__schema__ = {
+      name: "getComputedStyles",
+      description: "Get computed CSS styles for an element.",
+      parameters: {
+          type: "object",
+          properties: {
+              selector: {
+                  type: "string",
+                  description: "CSS selector of the element.",
+              },
+              properties: {
+                  type: "array",
+                  items: { type: "string" },
+                  description: 'CSS property names to retrieve, e.g. ["color", "font-size"]. Omit for common defaults.',
+              },
+          },
+          required: ["selector"],
+      },
+  };
+  function getElementBounds(selector) {
+      const el = document.querySelector(selector);
+      if (!el) {
+          return { error: `No element found for selector: ${selector}` };
+      }
+      const rect = el.getBoundingClientRect();
+      return {
+          bounds: {
+              x: Math.round(rect.x),
+              y: Math.round(rect.y),
+              width: Math.round(rect.width),
+              height: Math.round(rect.height),
+          },
+          visible: rect.width > 0 &&
+              rect.height > 0 &&
+              getComputedStyle(el).visibility !== "hidden" &&
+              getComputedStyle(el).display !== "none",
+      };
+  }
+  getElementBounds.__schema__ = {
+      name: "getElementBounds",
+      description: "Get the bounding rectangle and visibility of a DOM element.",
+      parameters: {
+          type: "object",
+          properties: {
+              selector: {
+                  type: "string",
+                  description: "CSS selector of the element.",
+              },
+          },
+          required: ["selector"],
+      },
+  };
   function getHtml(selector, outer, max_length) {
       const useOuter = outer ?? true;
       const maxLen = max_length ?? 50000;
@@ -10477,20 +10584,123 @@
   };
 
   /**
-   * Navigation service.
+   * Navigation service with auto-reconnect support.
+   *
+   * For agent-triggered reload() and same-origin navigate(), we use a "soft"
+   * approach: fetch the target HTML, inject the debugger <script> tag, then
+   * replace the document via document.write(). The injected script auto-starts
+   * from sessionStorage config, so the debugger reconnects with the same
+   * workspace and service ID. The agent's URL stays stable.
+   *
+   * For cross-origin navigate(), goBack(), and goForward(), we fall back to
+   * normal navigation. The debugger config is saved to sessionStorage so
+   * re-clicking the bookmarklet reconnects seamlessly.
+   */
+  const STORAGE_KEY$1 = "__hypha_debugger_config__";
+  /** Read the saved script URL from sessionStorage, or fall back to CDN. */
+  function getScriptUrl() {
+      try {
+          const raw = sessionStorage.getItem(STORAGE_KEY$1);
+          if (raw) {
+              const config = JSON.parse(raw);
+              if (config.script_url)
+                  return config.script_url;
+          }
+      }
+      catch {
+          // ignore
+      }
+      return "https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js";
+  }
+  /**
+   * Inject the debugger loader script into HTML before </body> (or append).
+   * Also injects a tiny inline script that reads sessionStorage and passes
+   * config to the debugger via a global, so autoStart() picks it up.
+   */
+  function injectLoader(html, scriptUrl) {
+      const loader = `<script src="${scriptUrl}"><\/script>`;
+      if (html.includes("</body>")) {
+          return html.replace("</body>", loader + "\n</body>");
+      }
+      if (html.includes("</html>")) {
+          return html.replace("</html>", loader + "\n</html>");
+      }
+      return html + "\n" + loader;
+  }
+  /**
+   * Perform a soft page replacement: fetch HTML, inject debugger script,
+   * replace the document. Returns false if it can't be done (caller should
+   * fall back to hard navigation).
    */
+  function softReplace(url, pushState) {
+      const scriptUrl = getScriptUrl();
+      fetch(url, { credentials: "same-origin", cache: "reload" })
+          .then((response) => {
+          if (!response.ok)
+              throw new Error(`HTTP ${response.status}`);
+          const contentType = response.headers.get("content-type") ?? "";
+          if (!contentType.includes("text/html")) {
+              throw new Error("Not HTML");
+          }
+          return response.text();
+      })
+          .then((html) => {
+          const modified = injectLoader(html, scriptUrl);
+          document.open();
+          document.write(modified);
+          document.close();
+          if (pushState) {
+              try {
+                  history.pushState({}, "", pushState);
+              }
+              catch {
+                  // ignore — URL might already match
+              }
+          }
+      })
+          .catch(() => {
+          // Soft replace failed — fall back to hard navigation
+          if (pushState) {
+              window.location.href = pushState;
+          }
+          else {
+              window.location.reload();
+          }
+      });
+  }
+  // ── navigate ──────────────────────────────────────────────────────────
   function navigate(url) {
       try {
-          window.location.href = url;
-          return { success: true, message: `Navigating to ${url}` };
+          const targetUrl = new URL(url, location.href);
+          const sameOrigin = targetUrl.origin === location.origin;
+          if (sameOrigin) {
+              // Soft navigate: fetch + inject + document.write, then pushState
+              // Schedule after RPC response is sent
+              setTimeout(() => softReplace(targetUrl.href, targetUrl.href), 150);
+              return {
+                  success: true,
+                  message: `Navigating to ${url} (debugger will auto-reconnect)`,
+              };
+          }
+          else {
+              // Cross-origin: can't soft navigate, fall back to hard
+              window.location.href = url;
+              return {
+                  success: true,
+                  message: `Navigating to ${url} (cross-origin, debugger will disconnect)`,
+              };
+          }
       }
       catch (err) {
-          return { success: false, message: `Navigation failed: ${err.message ?? err}` };
+          return {
+              success: false,
+              message: `Navigation failed: ${err.message ?? err}`,
+          };
       }
   }
   navigate.__schema__ = {
       name: "navigate",
-      description: "Navigate the browser to a new URL.",
+      description: "Navigate the browser to a new URL. For same-origin URLs, the debugger auto-reconnects. Cross-origin navigation will disconnect the debugger.",
       parameters: {
           type: "object",
           properties: {
@@ -10502,6 +10712,75 @@
           required: ["url"],
       },
   };
+  // ── goBack / goForward ───────────────────────────────────────────────
+  function goBack() {
+      try {
+          window.history.back();
+          return {
+              success: true,
+              message: "Navigated back (re-click bookmarklet to reconnect if needed)",
+          };
+      }
+      catch (err) {
+          return {
+              success: false,
+              message: `Back navigation failed: ${err.message ?? err}`,
+          };
+      }
+  }
+  goBack.__schema__ = {
+      name: "goBack",
+      description: "Navigate back in browser history. The debugger may disconnect — re-click the bookmarklet to reconnect.",
+      parameters: {
+          type: "object",
+          properties: {},
+      },
+  };
+  function goForward() {
+      try {
+          window.history.forward();
+          return {
+              success: true,
+              message: "Navigated forward (re-click bookmarklet to reconnect if needed)",
+          };
+      }
+      catch (err) {
+          return {
+              success: false,
+              message: `Forward navigation failed: ${err.message ?? err}`,
+          };
+      }
+  }
+  goForward.__schema__ = {
+      name: "goForward",
+      description: "Navigate forward in browser history. The debugger may disconnect — re-click the bookmarklet to reconnect.",
+      parameters: {
+          type: "object",
+          properties: {},
+      },
+  };
+  // ── reload ───────────────────────────────────────────────────────────
+  function reload() {
+      try {
+          // Schedule soft reload after RPC response is sent
+          setTimeout(() => softReplace(location.href), 150);
+          return {
+              success: true,
+              message: "Reloading page (debugger will auto-reconnect)",
+          };
+      }
+      catch (err) {
+          return { success: false, message: `Reload failed: ${err.message ?? err}` };
+      }
+  }
+  reload.__schema__ = {
+      name: "reload",
+      description: "Reload the current page. The debugger auto-reconnects after reload using soft page replacement.",
+      parameters: {
+          type: "object",
+          properties: {},
+      },
+  };
 
   /**
    * React component tree inspection service.
@@ -10844,6 +11123,33 @@
       return [frontmatter, intro, functionDocs.join("\n"), tips].join("\n");
   }
 
+  /**
+   * Wrap a function with correct, unminified parameter names for hypha-rpc.
+   *
+   * In production builds, Babel/Terser minifies parameter names (e.g. 'code' → 'e').
+   * hypha-rpc's getParamNames() parses Function.toString() to map kwargs to
+   * positional args. With minified names, kwargs like {code: '...'} can't be
+   * mapped and args are silently dropped.
+   *
+   * This helper uses new Function() to create a wrapper whose parameter names
+   * are taken from the function's __schema__ property, so hypha-rpc always sees
+   * the real parameter names regardless of minification.
+   */
+  function wrapFn(fn) {
+      const schema = fn.__schema__;
+      const paramNames = schema?.parameters?.properties
+          ? Object.keys(schema.parameters.properties)
+          : [];
+      if (paramNames.length === 0) {
+          return fn;
+      }
+      const paramList = paramNames.join(", ");
+      const wrapper = new Function("fn", `return async function(${paramList}) { return fn(${paramList}); }`)(fn);
+      if (schema)
+          wrapper.__schema__ = schema;
+      return wrapper;
+  }
+
   /**
    * @file port from browser-use
    * @see https://github.com/browser-use/browser-use/commits/main/browser_use/dom/dom_tree/index.js
@@ -13580,12 +13886,15 @@
       crypto.getRandomValues(arr);
       return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("");
   }
+  /** sessionStorage key for persisting debugger config across reloads. */
+  const STORAGE_KEY = "__hypha_debugger_config__";
   class HyphaDebugger {
       constructor(config) {
           this.overlay = null;
           this.cursor = null;
           this.server = null;
           this.serviceInfo = null;
+          this.boundBeforeUnload = null;
           const requireToken = config.require_token ?? false;
           // Always append random suffix unless user provided a custom id.
           let serviceId = config.service_id ?? "web-debugger";
@@ -13645,6 +13954,10 @@
               // Store globally
               w.__HYPHA_DEBUGGER__ = w.__HYPHA_DEBUGGER__ ?? {};
               w.__HYPHA_DEBUGGER__.instance = this;
+              // Persist config to sessionStorage for auto-reconnect after reload
+              this.saveConfigToStorage();
+              this.boundBeforeUnload = () => this.saveConfigToStorage();
+              window.addEventListener("beforeunload", this.boundBeforeUnload);
               return session;
           }
           catch (err) {
@@ -13660,6 +13973,11 @@
           }
       }
       async destroy() {
+          // Remove beforeunload listener
+          if (this.boundBeforeUnload) {
+              window.removeEventListener("beforeunload", this.boundBeforeUnload);
+              this.boundBeforeUnload = null;
+          }
           try {
               if (this.serviceInfo && this.server) {
                   await this.server.unregisterService(this.serviceInfo.id);
@@ -13668,6 +13986,13 @@
           catch {
               // Ignore unregister errors on cleanup
           }
+          // Clear sessionStorage config (explicit destroy = user wants to stop)
+          try {
+              sessionStorage.removeItem(STORAGE_KEY);
+          }
+          catch {
+              // ignore
+          }
           disposeController();
           this.cursor?.destroy();
           this.cursor = null;
@@ -13679,6 +14004,48 @@
               delete w.__HYPHA_DEBUGGER__.session;
           }
       }
+      /**
+       * Persist debugger config to sessionStorage so the debugger can
+       * auto-reconnect after a page reload (soft reload injects the script,
+       * autoStart() reads this config).
+       */
+      saveConfigToStorage() {
+          try {
+              const data = {
+                  server_url: this.config.server_url,
+                  workspace: this.server?.config?.workspace ?? this.config.workspace,
+                  token: this.config.token,
+                  service_id: this.config.service_id,
+                  service_name: this.config.service_name,
+                  show_ui: this.config.show_ui,
+                  visibility: this.config.visibility,
+                  require_token: this.config.require_token,
+                  script_url: this.detectScriptUrl(),
+              };
+              sessionStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+          }
+          catch {
+              // sessionStorage might be unavailable (private browsing, full quota)
+          }
+      }
+      /**
+       * Detect the URL of the currently loaded hypha-debugger script.
+       * Used by navigate.ts to inject the correct script after soft reload.
+       */
+      detectScriptUrl() {
+          try {
+              const scripts = document.querySelectorAll("script[src]");
+              for (const s of Array.from(scripts)) {
+                  if (s.src && s.src.includes("hypha-debugger")) {
+                      return s.src;
+                  }
+              }
+          }
+          catch {
+              // ignore
+          }
+          return "https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js";
+      }
       /**
        * Generate token, build service URL, update overlay instructions, and
        * return a DebugSession.
@@ -13848,21 +14215,17 @@
           return lines.join("\n");
       }
       /**
-       * Wrap a service function with logging and correct parameter names.
+       * Wrap a service function with overlay logging + correct parameter names.
        *
-       * Uses new Function() to create a wrapper whose parameter names match
-       * the __schema__ property names. This is critical for production builds
-       * where Babel/Terser minifies parameter names — hypha-rpc's
-       * getParamNames() parses Function.toString() to map kwargs to positional
-       * args, so the wrapper must have the real (unminified) parameter names.
+       * Adds logging around the function, then applies baseWrapFn() which uses
+       * new Function() to create a wrapper with unminified parameter names from
+       * __schema__. This is critical for production builds where Babel/Terser
+       * minifies parameter names — hypha-rpc's getParamNames() parses
+       * Function.toString() to map kwargs to positional args.
        */
       wrapFn(fn, name) {
-          const schema = fn.__schema__;
-          const paramNames = schema?.parameters?.properties
-              ? Object.keys(schema.parameters.properties)
-              : [];
           const self = this;
-          const callAndLog = async (args) => {
+          const logged = async (...args) => {
               self.overlay?.addLog(`${name}(${self.summarizeArgs(args)})`, "call");
               try {
                   const result = await fn(...args);
@@ -13880,19 +14243,10 @@
                   throw err;
               }
           };
-          let wrapper;
-          if (paramNames.length === 0) {
-              wrapper = async (...args) => callAndLog(args);
-          }
-          else {
-              // Create a function with explicit, unminified parameter names so
-              // hypha-rpc can parse them from Function.toString().
-              const paramList = paramNames.join(", ");
-              wrapper = new Function("callAndLog", `return async function(${paramList}) { return callAndLog([${paramList}]); }`)(callAndLog);
-          }
-          if (schema)
-              wrapper.__schema__ = schema;
-          return wrapper;
+          // Preserve __schema__ so baseWrapFn can read parameter names
+          if (fn.__schema__)
+              logged.__schema__ = fn.__schema__;
+          return wrapFn(logged);
       }
       summarizeArgs(args) {
           if (args.length === 0)
@@ -13922,7 +14276,11 @@
    * Programmatic usage:
    *   import { startDebugger } from 'hypha-debugger';
    *   const session = await startDebugger({ server_url: 'https://hypha.aicell.io' });
+   *
+   * Library usage (import individual functions):
+   *   import { getPageInfo, clickElement, wrapFn, PageController } from 'hypha-debugger';
    */
+  // ── Core debugger ──
   /**
    * Start the Hypha debugger. Connects to a Hypha server and registers
    * a debug service that remote clients can use to inspect and interact
@@ -13943,6 +14301,26 @@
   function autoStart() {
       if (typeof window === "undefined" || typeof document === "undefined")
           return;
+      // Skip if already started
+      if (window.__HYPHA_DEBUGGER__?.instance)
+          return;
+      // Check sessionStorage for saved config (auto-reconnect after soft reload)
+      try {
+          const saved = sessionStorage.getItem("__hypha_debugger_config__");
+          if (saved) {
+              const savedConfig = JSON.parse(saved);
+              if (savedConfig.server_url) {
+                  console.log("[hypha-debugger] Reconnecting from saved session...");
+                  startDebugger(savedConfig).catch((err) => {
+                      console.error("[hypha-debugger] Auto-reconnect failed:", err);
+                  });
+                  return;
+              }
+          }
+      }
+      catch {
+          // sessionStorage not available or parse error — continue to script tag detection
+      }
       // Find our own script tag
       const scripts = document.querySelectorAll("script[src]");
       let scriptEl = null;
@@ -13955,9 +14333,6 @@
       // Skip if data-manual is set
       if (scriptEl?.hasAttribute("data-manual"))
           return;
-      // Skip if already started
-      if (window.__HYPHA_DEBUGGER__?.instance)
-          return;
       const serverUrl = scriptEl?.getAttribute("data-server-url") ?? "https://hypha.aicell.io";
       const config = {
           server_url: serverUrl,
@@ -13991,8 +14366,36 @@
       }
   }
 
+  exports.AICursor = AICursor;
   exports.HyphaDebugger = HyphaDebugger;
+  exports.PageController = PageController;
+  exports.clickElement = clickElement$1;
+  exports.clickElementByIndex = clickElementByIndex;
+  exports.disposeController = disposeController;
+  exports.executeScript = executeScript;
+  exports.fillInput = fillInput;
+  exports.generateSkillMd = generateSkillMd;
+  exports.getBrowserState = getBrowserState;
+  exports.getComputedStyles = getComputedStyles;
+  exports.getConsoleLogs = getConsoleLogs;
+  exports.getElementBounds = getElementBounds;
+  exports.getHtml = getHtml;
+  exports.getPageInfo = getPageInfo;
+  exports.getReactTree = getReactTree;
+  exports.goBack = goBack;
+  exports.goForward = goForward;
+  exports.inputText = inputText;
+  exports.installConsoleCapture = installConsoleCapture;
+  exports.navigate = navigate;
+  exports.queryDom = queryDom;
+  exports.reload = reload;
+  exports.removeHighlights = removeHighlights;
+  exports.scroll = scroll;
+  exports.scrollTo = scrollTo;
+  exports.selectOption = selectOption;
   exports.startDebugger = startDebugger;
+  exports.takeScreenshot = takeScreenshot;
+  exports.wrapFn = wrapFn;
 
 }));
 //# sourceMappingURL=hypha-debugger.js.map