nothing-browser 0.0.10 → 0.0.11

package/piggy/client/index.ts

@@ -5,7 +5,7 @@ import { dirname } from "path";
 import { platform } from "os";
 import logger from "../logger";
 
-const SOCKET_PATH = platform() === 'win32' 
+const SOCKET_PATH = platform() === 'win32'
   ? '\\\\.\\pipe\\piggy'
   : '/tmp/piggy';
 
@@ -18,6 +18,9 @@ export class PiggyClient {
   private eventBuffer = "";
   private eventHandlers = new Map<string, Map<string, (data: any) => Promise<any>>>();
 
+  // ── Global event emitter for navigate / etc ───────────────────────────────
+  private globalEventHandlers = new Map<string, Set<(data: any) => void>>();
+
   constructor(socketPath = SOCKET_PATH) {
     this.socketPath = socketPath;
     this.eventHandlers.set("default", new Map());
@@ -39,17 +42,17 @@ export class PiggyClient {
         this.eventBuffer += chunk;
         const lines = this.eventBuffer.split("\n");
         this.eventBuffer = lines.pop()!;
-        
+
         for (const line of lines) {
           if (!line.trim()) continue;
           try {
             const msg = JSON.parse(line);
-            
+
             if (msg.type === "event") {
               this.handleEvent(msg);
               continue;
             }
-            
+
             const p = this.pending.get(msg.id);
             if (p) {
               this.pending.delete(msg.id);
@@ -75,31 +78,23 @@ export class PiggyClient {
   }
 
   private handleEvent(event: any) {
+    // ── exposed_call ──────────────────────────────────────────────────────────
     if (event.event === "exposed_call") {
       const { tabId, name, callId, data } = event;
       const effectiveTabId = tabId || "default";
       const handlers = this.eventHandlers.get(effectiveTabId);
       const handler = handlers?.get(name);
-      
+
       if (handler) {
         Promise.resolve(handler(JSON.parse(data || "null")))
           .then(response => {
             if (response && typeof response === "object" && "success" in response) {
-              if (response.success) {
-                this.send("exposed.result", {
-                  tabId: effectiveTabId,
-                  callId,
-                  result: JSON.stringify(response.result),
-                  isError: false
-                }).catch(e => logger.error(`Failed to send exposed result: ${e}`));
-              } else {
-                this.send("exposed.result", {
-                  tabId: effectiveTabId,
-                  callId,
-                  result: response.error || "Unknown error",
-                  isError: true
-                }).catch(e => logger.error(`Failed to send exposed error: ${e}`));
-              }
+              this.send("exposed.result", {
+                tabId: effectiveTabId,
+                callId,
+                result: response.success ? JSON.stringify(response.result) : (response.error || "Unknown error"),
+                isError: !response.success
+              }).catch(e => logger.error(`Failed to send exposed result: ${e}`));
             } else {
               this.send("exposed.result", {
                 tabId: effectiveTabId,
@@ -120,7 +115,37 @@ export class PiggyClient {
       } else {
         logger.warn(`No handler for exposed function: ${name} in tab ${effectiveTabId}`);
       }
+      return;
+    }
+
+    // ── navigate ──────────────────────────────────────────────────────────────
+    if (event.event === "navigate") {
+      const handlers = this.globalEventHandlers.get(`navigate:${event.tabId}`);
+      if (handlers) {
+        for (const h of handlers) {
+          try { h(event.url); } catch (e) { logger.error(`navigate handler error: ${e}`); }
+        }
+      }
+      // Also fire wildcard listeners (no tabId filter)
+      const wildcard = this.globalEventHandlers.get("navigate:*");
+      if (wildcard) {
+        for (const h of wildcard) {
+          try { h({ url: event.url, tabId: event.tabId }); } catch {}
+        }
+      }
+      return;
+    }
+  }
+
+  // ── Global event subscription ─────────────────────────────────────────────
+  onEvent(eventName: string, tabId: string, handler: (data: any) => void): () => void {
+    const key = `${eventName}:${tabId}`;
+    if (!this.globalEventHandlers.has(key)) {
+      this.globalEventHandlers.set(key, new Set());
     }
+    this.globalEventHandlers.get(key)!.add(handler);
+    // Return unsubscribe fn
+    return () => this.globalEventHandlers.get(key)?.delete(handler);
   }
 
   disconnect() {
@@ -128,7 +153,7 @@ export class PiggyClient {
     this.socket = null;
   }
 
-  private send<T = any>(cmd: string, payload: Record<string, any> = {}): Promise<T> {
+  send<T = any>(cmd: string, payload: Record<string, any> = {}): Promise<T> {
     return new Promise((resolve, reject) => {
       if (!this.socket) return reject(new Error("Not connected"));
       const id = String(++this.reqId);
@@ -137,118 +162,43 @@ export class PiggyClient {
     });
   }
 
-  // ── Tabs ─────────────────────────────────────────────────────────────────────
-
-  async newTab(): Promise<string> {
-    return this.send<string>("tab.new", {});
-  }
-
-  async closeTab(tabId: string): Promise<void> {
-    await this.send("tab.close", { tabId });
-  }
-
-  async listTabs(): Promise<string[]> {
-    return this.send<string[]>("tab.list", {});
-  }
-
-  // ── Navigation ───────────────────────────────────────────────────────────────
-
-  async navigate(url: string, tabId = "default"): Promise<void> {
-    await this.send("navigate", { url, tabId });
-  }
-
-  async reload(tabId = "default"): Promise<void> {
-    await this.send("reload", { tabId });
-  }
-
-  async goBack(tabId = "default"): Promise<void> {
-    await this.send("go.back", { tabId });
-  }
-
-  async goForward(tabId = "default"): Promise<void> {
-    await this.send("go.forward", { tabId });
-  }
-
-  // ── Page info ─────────────────────────────────────────────────────────────────
-
-  async getTitle(tabId = "default"): Promise<string> {
-    return this.send<string>("page.title", { tabId });
-  }
-
-  async getUrl(tabId = "default"): Promise<string> {
-    return this.send<string>("page.url", { tabId });
-  }
-
-  async content(tabId = "default"): Promise<string> {
-    return this.send<string>("page.content", { tabId });
-  }
-
-  // ── Eval / JS ─────────────────────────────────────────────────────────────────
-
-  async evaluate(js: string, tabId = "default"): Promise<any> {
-    return this.send("evaluate", { js, tabId });
-  }
-
-  // ── Init Script ───────────────────────────────────────────────────────────────
-  // HERE IT IS - ADD THIS METHOD TO THE CLIENT
-  async addInitScript(js: string, tabId = "default"): Promise<void> {
-    await this.send("addInitScript", { js, tabId });
-  }
-
-  // ── Interactions ──────────────────────────────────────────────────────────────
-
-  async click(selector: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("click", { selector, tabId });
-  }
-
-  async doubleClick(selector: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("dblclick", { selector, tabId });
-  }
-
-  async hover(selector: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("hover", { selector, tabId });
-  }
-
-  async type(selector: string, text: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("type", { selector, text, tabId });
-  }
-
-  async select(selector: string, value: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("select", { selector, value, tabId });
-  }
-
-  async keyPress(key: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("keyboard.press", { key, tabId });
-  }
-
-  async keyCombo(combo: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("keyboard.combo", { combo, tabId });
-  }
-
-  async mouseMove(x: number, y: number, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("mouse.move", { x, y, tabId });
-  }
-
-  async mouseDrag(from: { x: number; y: number }, to: { x: number; y: number }, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("mouse.drag", { from, to, tabId });
-  }
-
-  // ── Scroll ────────────────────────────────────────────────────────────────────
-
-  async scrollTo(selector: string, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("scroll.to", { selector, tabId });
-  }
-
-  async scrollBy(px: number, tabId = "default"): Promise<boolean> {
-    return this.send<boolean>("scroll.by", { px, tabId });
-  }
-
-  // ── Fetch ─────────────────────────────────────────────────────────────────────
-
-  async fetchText(query: string, tabId = "default"): Promise<string | null> {
-    return this.send<string | null>("fetch.text", { query, tabId });
-  }
-
+  // ── Tabs ──────────────────────────────────────────────────────────────────
+  async newTab(): Promise<string> { return this.send<string>("tab.new", {}); }
+  async closeTab(tabId: string): Promise<void> { await this.send("tab.close", { tabId }); }
+  async listTabs(): Promise<string[]> { return this.send<string[]>("tab.list", {}); }
+
+  // ── Navigation ────────────────────────────────────────────────────────────
+  async navigate(url: string, tabId = "default"): Promise<void> { await this.send("navigate", { url, tabId }); }
+  async reload(tabId = "default"): Promise<void> { await this.send("reload", { tabId }); }
+  async goBack(tabId = "default"): Promise<void> { await this.send("go.back", { tabId }); }
+  async goForward(tabId = "default"): Promise<void> { await this.send("go.forward", { tabId }); }
+
+  // ── Page info ─────────────────────────────────────────────────────────────
+  async getTitle(tabId = "default"): Promise<string> { return this.send<string>("page.title", { tabId }); }
+  async getUrl(tabId = "default"): Promise<string> { return this.send<string>("page.url", { tabId }); }
+  async content(tabId = "default"): Promise<string> { return this.send<string>("page.content", { tabId }); }
+
+  // ── Eval / JS ─────────────────────────────────────────────────────────────
+  async evaluate(js: string, tabId = "default"): Promise<any> { return this.send("evaluate", { js, tabId }); }
+  async addInitScript(js: string, tabId = "default"): Promise<void> { await this.send("addInitScript", { js, tabId }); }
+
+  // ── Interactions ──────────────────────────────────────────────────────────
+  async click(selector: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("click", { selector, tabId }); }
+  async doubleClick(selector: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("dblclick", { selector, tabId }); }
+  async hover(selector: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("hover", { selector, tabId }); }
+  async type(selector: string, text: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("type", { selector, text, tabId }); }
+  async select(selector: string, value: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("select", { selector, value, tabId }); }
+  async keyPress(key: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("keyboard.press", { key, tabId }); }
+  async keyCombo(combo: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("keyboard.combo", { combo, tabId }); }
+  async mouseMove(x: number, y: number, tabId = "default"): Promise<boolean> { return this.send<boolean>("mouse.move", { x, y, tabId }); }
+  async mouseDrag(from: { x: number; y: number }, to: { x: number; y: number }, tabId = "default"): Promise<boolean> { return this.send<boolean>("mouse.drag", { from, to, tabId }); }
+
+  // ── Scroll ────────────────────────────────────────────────────────────────
+  async scrollTo(selector: string, tabId = "default"): Promise<boolean> { return this.send<boolean>("scroll.to", { selector, tabId }); }
+  async scrollBy(px: number, tabId = "default"): Promise<boolean> { return this.send<boolean>("scroll.by", { px, tabId }); }
+
+  // ── Fetch ─────────────────────────────────────────────────────────────────
+  async fetchText(query: string, tabId = "default"): Promise<string | null> { return this.send<string | null>("fetch.text", { query, tabId }); }
   async fetchLinks(query: string, tabId = "default"): Promise<string[]> {
     if (query === "a" || query === "body") {
       const result = await this.send<string[]>("fetch.links.all", { tabId });
@@ -257,148 +207,68 @@ export class PiggyClient {
     const result = await this.send<string[]>("fetch.links", { query, tabId });
     return Array.isArray(result) ? result : [];
   }
-
   async fetchImages(query: string, tabId = "default"): Promise<string[]> {
     const result = await this.send<string[]>("fetch.image", { query, tabId });
     return Array.isArray(result) ? result : [];
   }
 
-  // ── Search ────────────────────────────────────────────────────────────────────
-
-  async searchCss(query: string, tabId = "default"): Promise<any> {
-    return this.send("search.css", { query, tabId });
-  }
-
-  async searchId(query: string, tabId = "default"): Promise<any> {
-    return this.send("search.id", { query, tabId });
-  }
+  // ── Search ────────────────────────────────────────────────────────────────
+  async searchCss(query: string, tabId = "default"): Promise<any> { return this.send("search.css", { query, tabId }); }
+  async searchId(query: string, tabId = "default"): Promise<any> { return this.send("search.id", { query, tabId }); }
 
-  // ── Wait ──────────────────────────────────────────────────────────────────────
-
-  async waitForSelector(selector: string, timeout = 30000, tabId = "default"): Promise<void> {
-    await this.send("wait.selector", { selector, timeout, tabId });
-  }
-
-  async waitForNavigation(tabId = "default"): Promise<void> {
-    await this.send("wait.navigation", { tabId });
-  }
-
-  async waitForResponse(urlPattern: string, timeout = 30000, tabId = "default"): Promise<void> {
-    await this.send("wait.response", { url: urlPattern, timeout, tabId });
-  }
-
-  // ── Screenshot ────────────────────────────────────────────────────────────────
+  // ── Wait ──────────────────────────────────────────────────────────────────
+  async waitForSelector(selector: string, timeout = 30000, tabId = "default"): Promise<void> { await this.send("wait.selector", { selector, timeout, tabId }); }
+  async waitForNavigation(tabId = "default"): Promise<void> { await this.send("wait.navigation", { tabId }); }
+  async waitForResponse(urlPattern: string, timeout = 30000, tabId = "default"): Promise<void> { await this.send("wait.response", { url: urlPattern, timeout, tabId }); }
 
+  // ── Screenshot / PDF ──────────────────────────────────────────────────────
   async screenshot(filePath?: string, tabId = "default"): Promise<string> {
     const b64 = await this.send<string>("screenshot", { tabId });
-    if (filePath) {
-      mkdirSync(dirname(filePath), { recursive: true });
-      writeFileSync(filePath, Buffer.from(b64, "base64"));
-    }
+    if (filePath) { mkdirSync(dirname(filePath), { recursive: true }); writeFileSync(filePath, Buffer.from(b64, "base64")); }
     return filePath ?? b64;
   }
-
-  // ── PDF ───────────────────────────────────────────────────────────────────────
-
   async pdf(filePath?: string, tabId = "default"): Promise<string> {
     const b64 = await this.send<string>("pdf", { tabId });
-    if (filePath) {
-      mkdirSync(dirname(filePath), { recursive: true });
-      writeFileSync(filePath, Buffer.from(b64, "base64"));
-    }
+    if (filePath) { mkdirSync(dirname(filePath), { recursive: true }); writeFileSync(filePath, Buffer.from(b64, "base64")); }
     return filePath ?? b64;
   }
 
-  // ── Image blocking ────────────────────────────────────────────────────────────
-
-  async blockImages(tabId = "default"): Promise<void> {
-    await this.send("intercept.block.images", { tabId });
-  }
-
-  async unblockImages(tabId = "default"): Promise<void> {
-    await this.send("intercept.unblock.images", { tabId });
-  }
-
-  // ── Cookies ───────────────────────────────────────────────────────────────────
+  // ── Image blocking ────────────────────────────────────────────────────────
+  async blockImages(tabId = "default"): Promise<void> { await this.send("intercept.block.images", { tabId }); }
+  async unblockImages(tabId = "default"): Promise<void> { await this.send("intercept.unblock.images", { tabId }); }
 
-  async setCookie(name: string, value: string, domain: string, path = "/", tabId = "default"): Promise<void> {
-    await this.send("cookie.set", { name, value, domain, path, tabId });
-  }
-
-  async getCookie(name: string, tabId = "default"): Promise<any> {
-    return this.send("cookie.get", { name, tabId });
-  }
-
-  async deleteCookie(name: string, tabId = "default"): Promise<void> {
-    await this.send("cookie.delete", { name, tabId });
-  }
-
-  async listCookies(tabId = "default"): Promise<any[]> {
-    return this.send<any[]>("cookie.list", { tabId });
-  }
-
-  // ── Interception ──────────────────────────────────────────────────────────────
+  // ── Cookies ───────────────────────────────────────────────────────────────
+  async setCookie(name: string, value: string, domain: string, path = "/", tabId = "default"): Promise<void> { await this.send("cookie.set", { name, value, domain, path, tabId }); }
+  async getCookie(name: string, tabId = "default"): Promise<any> { return this.send("cookie.get", { name, tabId }); }
+  async deleteCookie(name: string, tabId = "default"): Promise<void> { await this.send("cookie.delete", { name, tabId }); }
+  async listCookies(tabId = "default"): Promise<any[]> { return this.send<any[]>("cookie.list", { tabId }); }
 
+  // ── Interception ──────────────────────────────────────────────────────────
   async addInterceptRule(action: "block" | "redirect" | "modifyHeaders", pattern: string, options: { redirectUrl?: string; headers?: Record<string, string> } = {}, tabId = "default"): Promise<void> {
     await this.send("intercept.rule.add", { action, pattern, ...options, tabId });
   }
+  async clearInterceptRules(tabId = "default"): Promise<void> { await this.send("intercept.rule.clear", { tabId }); }
 
-  async clearInterceptRules(tabId = "default"): Promise<void> {
-    await this.send("intercept.rule.clear", { tabId });
-  }
-
-  // ── Network capture ───────────────────────────────────────────────────────────
-
-  async captureStart(tabId = "default"): Promise<void> {
-    await this.send("capture.start", { tabId });
-  }
+  // ── Network capture ───────────────────────────────────────────────────────
+  async captureStart(tabId = "default"): Promise<void> { await this.send("capture.start", { tabId }); }
+  async captureStop(tabId = "default"): Promise<void> { await this.send("capture.stop", { tabId }); }
+  async captureRequests(tabId = "default"): Promise<any[]> { return this.send<any[]>("capture.requests", { tabId }); }
+  async captureWs(tabId = "default"): Promise<any[]> { return this.send<any[]>("capture.ws", { tabId }); }
+  async captureCookies(tabId = "default"): Promise<any[]> { return this.send<any[]>("capture.cookies", { tabId }); }
+  async captureStorage(tabId = "default"): Promise<any> { return this.send("capture.storage", { tabId }); }
+  async captureClear(tabId = "default"): Promise<void> { await this.send("capture.clear", { tabId }); }
 
-  async captureStop(tabId = "default"): Promise<void> {
-    await this.send("capture.stop", { tabId });
-  }
-
-  async captureRequests(tabId = "default"): Promise<any[]> {
-    return this.send<any[]>("capture.requests", { tabId });
-  }
-
-  async captureWs(tabId = "default"): Promise<any[]> {
-    return this.send<any[]>("capture.ws", { tabId });
-  }
-
-  async captureCookies(tabId = "default"): Promise<any[]> {
-    return this.send<any[]>("capture.cookies", { tabId });
-  }
-
-  async captureStorage(tabId = "default"): Promise<any> {
-    return this.send("capture.storage", { tabId });
-  }
-
-  async captureClear(tabId = "default"): Promise<void> {
-    await this.send("capture.clear", { tabId });
-  }
-
-  // ── Session ───────────────────────────────────────────────────────────────────
-
-  async sessionExport(tabId = "default"): Promise<any> {
-    return this.send("session.export", { tabId });
-  }
-
-  async sessionImport(data: any, tabId = "default"): Promise<void> {
-    await this.send("session.import", { data, tabId });
-  }
-
-  // ── Expose Function ───────────────────────────────────────────────────────────
+  // ── Session ───────────────────────────────────────────────────────────────
+  async sessionExport(tabId = "default"): Promise<any> { return this.send("session.export", { tabId }); }
+  async sessionImport(data: any, tabId = "default"): Promise<void> { await this.send("session.import", { data, tabId }); }
 
+  // ── Expose Function ───────────────────────────────────────────────────────
   async exposeFunction(name: string, handler: (data: any) => Promise<any> | any, tabId = "default"): Promise<void> {
-    if (!this.eventHandlers.has(tabId)) {
-      this.eventHandlers.set(tabId, new Map());
-    }
+    if (!this.eventHandlers.has(tabId)) this.eventHandlers.set(tabId, new Map());
     this.eventHandlers.get(tabId)!.set(name, async (data: any) => {
       try {
         const result = await handler(data);
-        if (result && typeof result === "object" && ("success" in result || "error" in result)) {
-          return result;
-        }
+        if (result && typeof result === "object" && ("success" in result || "error" in result)) return result;
         return { success: true, result };
       } catch (err: any) {
         return { success: false, error: err.message || String(err) };

package/piggy/intercept/scripts.ts

@@ -0,0 +1,153 @@
+// piggy/intercept/scripts.ts
+// JS injection helpers for intercept.respond and intercept.modifyResponse.
+// Both work purely in the browser's JS layer — no C++ changes needed.
+
+/**
+ * Generates a script that short-circuits matching fetch/XHR requests
+ * and returns a static fake response — the request never hits the network.
+ */
+export function buildRespondScript(
+  pattern: string,
+  status: number,
+  contentType: string,
+  body: string
+): string {
+  const safePattern     = pattern.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  const safeBody        = body.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$/g, "\\$");
+  const safeContentType = contentType.replace(/'/g, "\\'");
+
+  return `
+(function() {
+  'use strict';
+  if (!window.__PIGGY_RESPOND_RULES__) window.__PIGGY_RESPOND_RULES__ = [];
+  window.__PIGGY_RESPOND_RULES__.push({
+    pattern: '${safePattern}',
+    status: ${status},
+    contentType: '${safeContentType}',
+    body: \`${safeBody}\`
+  });
+
+  function _piggyMatchUrl(url, pattern) {
+    try { return url.includes(pattern) || new RegExp(pattern).test(url); }
+    catch { return url.includes(pattern); }
+  }
+
+  // Only install wrappers once per page
+  if (window.__PIGGY_RESPOND_INSTALLED__) return;
+  window.__PIGGY_RESPOND_INSTALLED__ = true;
+
+  // ── fetch wrapper ──────────────────────────────────────────────────────────
+  const _origFetch = window.fetch;
+  window.fetch = function(input, init) {
+    const url = typeof input === 'string' ? input : (input?.url ?? String(input));
+    const rules = window.__PIGGY_RESPOND_RULES__ || [];
+    for (const rule of rules) {
+      if (_piggyMatchUrl(url, rule.pattern)) {
+        return Promise.resolve(new Response(rule.body, {
+          status: rule.status,
+          headers: { 'Content-Type': rule.contentType }
+        }));
+      }
+    }
+    return _origFetch.apply(this, arguments);
+  };
+
+  // ── XHR wrapper ────────────────────────────────────────────────────────────
+  const _origOpen = XMLHttpRequest.prototype.open;
+  const _origSend = XMLHttpRequest.prototype.send;
+
+  XMLHttpRequest.prototype.open = function(method, url) {
+    this.__piggy_url__ = String(url);
+    return _origOpen.apply(this, arguments);
+  };
+
+  XMLHttpRequest.prototype.send = function() {
+    const url = this.__piggy_url__ || '';
+    const rules = window.__PIGGY_RESPOND_RULES__ || [];
+    for (const rule of rules) {
+      if (_piggyMatchUrl(url, rule.pattern)) {
+        const self = this;
+        Object.defineProperty(self, 'readyState',   { get: () => 4,            configurable: true });
+        Object.defineProperty(self, 'status',       { get: () => rule.status,  configurable: true });
+        Object.defineProperty(self, 'responseText', { get: () => rule.body,    configurable: true });
+        Object.defineProperty(self, 'response',     { get: () => rule.body,    configurable: true });
+        setTimeout(() => {
+          if (typeof self.onreadystatechange === 'function') self.onreadystatechange();
+          self.dispatchEvent(new Event('readystatechange'));
+          self.dispatchEvent(new Event('load'));
+          self.dispatchEvent(new Event('loadend'));
+        }, 0);
+        return;
+      }
+    }
+    return _origSend.apply(this, arguments);
+  };
+})();
+`;
+}
+
+/**
+ * Generates a script that lets the request hit the network, then calls
+ * an exposed function with { body, status, headers }.
+ * The exposed function returns { body?, status?, headers? } modifications
+ * or an empty object {} to pass through unchanged.
+ */
+export function buildModifyResponseScript(pattern: string, exposedFnName: string): string {
+  const safePattern = pattern.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  const safeFnName  = exposedFnName.replace(/'/g, "\\'");
+
+  return `
+(function() {
+  'use strict';
+  if (!window.__PIGGY_MODIFY_RULES__) window.__PIGGY_MODIFY_RULES__ = [];
+  window.__PIGGY_MODIFY_RULES__.push({ pattern: '${safePattern}', fn: '${safeFnName}' });
+
+  function _piggyMatchUrl(url, pattern) {
+    try { return url.includes(pattern) || new RegExp(pattern).test(url); }
+    catch { return url.includes(pattern); }
+  }
+
+  // Only install wrappers once per page
+  if (window.__PIGGY_MODIFY_INSTALLED__) return;
+  window.__PIGGY_MODIFY_INSTALLED__ = true;
+
+  const _origFetch = window.fetch;
+  window.fetch = async function(input, init) {
+    const url = typeof input === 'string' ? input : (input?.url ?? String(input));
+    const rules = window.__PIGGY_MODIFY_RULES__ || [];
+
+    let matchedFn = null;
+    for (const rule of rules) {
+      if (_piggyMatchUrl(url, rule.pattern)) { matchedFn = rule.fn; break; }
+    }
+
+    // No match — pass through untouched
+    const resp = await _origFetch.apply(this, arguments);
+    if (!matchedFn) return resp;
+
+    try {
+      const bodyText = await resp.clone().text();
+      const headers  = {};
+      resp.headers.forEach((v, k) => { headers[k] = v; });
+
+      const handlerFn = window[matchedFn];
+      if (typeof handlerFn !== 'function') return resp;
+
+      // Call Node.js handler via exposeFunction bridge
+      const mod = await handlerFn({ body: bodyText, status: resp.status, headers });
+      if (!mod || typeof mod !== 'object' || Object.keys(mod).length === 0) return resp;
+
+      return new Response(
+        mod.body    !== undefined ? mod.body    : bodyText,
+        {
+          status:  mod.status  !== undefined ? mod.status  : resp.status,
+          headers: mod.headers !== undefined ? mod.headers : headers,
+        }
+      );
+    } catch {
+      return resp; // On any error, pass through original response
+    }
+  };
+})();
+`;
+}