nothing-browser 0.0.2 → 0.0.4

package/README.md

@@ -1,3 +1,6 @@
+Here's the updated README with the `exposeFunction` feature documented:
+
+```markdown
 <p align="center">
   <img src="nothing_browser_pig_pink.svg" width="160" alt="Nothing Browser logo"/>
 </p>
@@ -7,24 +10,55 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/nothing-browser"><img src="https://img.shields.io/npm/v/nothing-browser" alt="npm version"/></a>
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/ernest-tech-house-co-operation/nothing-browser" alt="license"/></a>
-  <a href="https://github.com/BunElysiaReact/nothing-browser/releases"><img src="https://img.shields.io/github/v/release/BunElysiaReact/nothing-browser" alt="binary releases"/></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/BunElysiaReact/nothing-browser" alt="license"/></a>
+  <a href="https://github.com/BunElysiaReact/nothing-browser/releases"><img src="https://img.shields.io/github/v/release/BunElysiaReact/nothing-browser" alt="releases"/></a>
 </p>
 
 ---
 
 A scraper-first headless browser library powered by the Nothing Browser Qt6/Chromium engine. Control real browser tabs, intercept network traffic, spoof fingerprints, capture WebSockets — all from Bun + TypeScript.
 
-> **Two repos:**
-> - This package (npm lib) → [ernest-tech-house-co-operation/nothing-browser](https://github.com/ernest-tech-house-co-operation/nothing-browser)
-> - Headless binary → [BunElysiaReact/nothing-browser](https://github.com/BunElysiaReact/nothing-browser/releases)
+---
+
+## Why nothing-browser
+
+Yes, we are bragging. Here's why.
+
+| | nothing-browser | Puppeteer | Playwright |
+|---|---|---|---|
+| Imports | **1** | 5–10 | 5–10 |
+| Lines to scrape a site | **~20** | 80–200 | 80–200 |
+| Fingerprint spoofing | ✅ built in | ❌ plugin needed | ❌ plugin needed |
+| Network capture | ✅ built in | ❌ manual | ❌ manual |
+| Built-in API server | ✅ | ❌ | ❌ |
+| Cloudflare bypass | ✅ passes | ⚠️ often blocked | ⚠️ often blocked |
+| Headless detection bypass | ✅ built in | ❌ manual | ❌ manual |
+| Session persistence | ✅ built in | ❌ manual | ❌ manual |
+| Human mode | ✅ built in | ❌ manual | ❌ manual |
+| **Browser → Node.js RPC** | ✅ **exposeFunction** | ✅ page.exposeFunction | ✅ page.exposeFunction |
+
+One import. No middleware soup. No 47 plugins to avoid detection. No CAPTCHAs on sites that Puppeteer chokes on. Just write your scraper and go.
 
 ---
 
 ## Requirements
 
 - [Bun](https://bun.sh) ≥ 1.0
-- Nothing Browser headless binary (see below)
+- A Nothing Browser binary placed in your **project root** (see below)
+
+---
+
+## Binaries
+
+There are three binaries. All downloaded from the same place — [GitHub Releases](https://github.com/BunElysiaReact/nothing-browser/releases).
+
+| Binary | What it is | Where it goes |
+|--------|-----------|---------------|
+| `nothing-browser` | Full UI browser app — DevTools, YouTube tab, Plugins, etc. | Install system-wide |
+| `nothing-browser-headless` | No window, no GPU. Runs as a background daemon for the scraping lib. | **Your project root** |
+| `nothing-browser-headful` | Visible browser window, script-controlled. Useful when a site needs a real display. | **Your project root** |
+
+The lib talks to whichever binary is in your project root over a local socket. You pick headless or headful depending on your use case.
 
 ---
 
@@ -34,17 +68,34 @@ A scraper-first headless browser library powered by the Nothing Browser Qt6/Chro
 bun add nothing-browser
 ```
 
-Then download the **headless binary** for your platform from [BunElysiaReact/nothing-browser releases](https://github.com/BunElysiaReact/nothing-browser/releases) and place it in your project root.
+Then download the binary for your platform from [GitHub Releases](https://github.com/BunElysiaReact/nothing-browser/releases) and place it in your project root.
+
+### Linux
 
-**Linux**
+**Headless** (no visible window — most common for scraping)
 ```bash
 tar -xzf nothing-browser-headless-*-linux-x86_64.tar.gz
 chmod +x nothing-browser-headless
 ```
 
-**Windows** — extract the `.zip`, place `nothing-browser-headless.exe` in project root.
+**Headful** (visible window, script-controlled)
+```bash
+tar -xzf nothing-browser-headful-*-linux-x86_64.tar.gz
+chmod +x nothing-browser-headful
+```
 
-**macOS** — extract the `.tar.gz`, place `nothing-browser-headless` in project root.
+**Full browser** (system-wide install, for using the UI)
+```bash
+sudo dpkg -i nothing-browser_*_amd64.deb
+```
+
+### Windows
+
+Download the `.zip` → extract → place the exe in your project root.
+
+### macOS
+
+Download the `.tar.gz` → extract → place the binary in your project root.
 
 ---
 
@@ -70,28 +121,144 @@ console.log(books);
 await piggy.close();
 ```
 
+That's it. One import, one register, scrape, done.
+
 ---
 
-## Modes
+## Headless vs Headful
 
-### Tab mode (default)
-All sites share one browser process, each in its own tab.
+**Headless** — no display needed, runs anywhere including CI.
 
 ```ts
-await piggy.launch({ mode: "tab" });
+await piggy.launch({ mode: "tab", binary: "headless" }); // default
 ```
 
-### Process mode
-Each site gets its own browser process on a dedicated socket. More isolation, more RAM.
+**Headful** — opens a real visible Chromium window your script drives. Use this when a site detects headless or requires a real display.
 
 ```ts
-await piggy.launch({ mode: "process" });
+await piggy.launch({ mode: "tab", binary: "headful" });
 ```
 
+Same API either way. Switching is just changing one word.
+
 ---
 
 ## Examples
 
+### 🔥 NEW: Browser → Node.js RPC with `exposeFunction`
+
+Call Node.js functions directly from browser JavaScript. Perfect for:
+- Processing data in real-time as the user navigates
+- Handling authentication callbacks
+- Streaming WebSocket messages to your backend
+- Building browser extensions with Node.js power
+
+```ts
+import piggy from "nothing-browser";
+
+await piggy.launch({ mode: "tab" });
+await piggy.register("whatsapp", "https://web.whatsapp.com");
+
+// Expose a function that WhatsApp Web can call
+await piggy.whatsapp.exposeFunction("onNewMessage", async (message) => {
+  console.log("📱 New message:", message);
+  
+  // Save to database
+  await db.messages.insert({
+    text: message.text,
+    sender: message.sender,
+    timestamp: message.timestamp,
+  });
+  
+  // Return value goes back to the browser
+  return { saved: true, id: crypto.randomUUID() };
+});
+
+// Inject the listener that calls our exposed function
+await piggy.whatsapp.evaluate(() => {
+  const observer = new MutationObserver(() => {
+    document.querySelectorAll('.message-in:not([data-seen])').forEach(el => {
+      el.dataset.seen = '1';
+      
+      // Call the exposed function - returns a Promise!
+      window.onNewMessage({
+        text: el.innerText,
+        timestamp: Date.now(),
+        sender: el.querySelector('.sender')?.innerText,
+      }).then(result => {
+        console.log('Message saved with ID:', result.id);
+        el.style.borderLeft = '3px solid green';
+      });
+    });
+  });
+  
+  observer.observe(document.body, { childList: true, subtree: true });
+});
+
+console.log("Listening for WhatsApp messages...");
+```
+
+### Expose + Inject convenience method
+
+```ts
+await piggy.whatsapp.exposeAndInject(
+  "onNewMessage",
+  async (message) => {
+    await saveToDatabase(message);
+    return { ok: true };
+  },
+  (fnName) => `
+    // This runs in the browser
+    setInterval(() => {
+      const msgs = document.querySelectorAll('.new-message');
+      msgs.forEach(msg => {
+        window.${fnName}({ text: msg.innerText });
+      });
+    }, 2000);
+  `
+);
+```
+
+### Structured API with multiple methods
+
+```ts
+import { createExposedAPI } from "nothing-browser/register";
+
+await createExposedAPI(piggy.whatsapp, "whatsappAPI", {
+  onMessage: async (msg) => {
+    await db.messages.insert(msg);
+    return { saved: true };
+  },
+  
+  getContacts: async () => {
+    return await db.contacts.findAll();
+  },
+  
+  sendReply: async ({ to, text }) => {
+    // Your sending logic here
+    return { sent: true };
+  }
+});
+
+// In browser JS:
+const result = await window.whatsappAPI({ 
+  method: 'sendReply', 
+  args: { to: '+1234567890', text: 'Hello!' } 
+});
+```
+
+### Global expose (available to all sites)
+
+```ts
+await piggy.expose("logToServer", async (data) => {
+  console.log("[Browser]", data);
+  await analytics.track(data.event, data.properties);
+  return { logged: true };
+});
+
+// Any page can call: window.logToServer({ event: 'pageview' })
+```
+
 ### Scrape a site and expose it as an API
 
 ```ts
@@ -102,7 +269,6 @@ await piggy.register("books", "https://books.toscrape.com");
 
 await piggy.books.intercept.block("*google-analytics*");
 await piggy.books.intercept.block("*doubleclick*");
-await piggy.books.intercept.block("*facebook*");
 
 piggy.books.api("/list", async (_params, query) => {
   const page = query.page ? parseInt(query.page) : 1;
@@ -139,39 +305,16 @@ await piggy.serve(3000);
 ### Middleware — auth + logging
 
 ```ts
-const logMiddleware = async ({ query, params }: any) => {
-  console.log("[middleware] incoming request", { params, query });
-};
-
 const authMiddleware = async ({ headers, set }: any) => {
-  const key = headers["x-api-key"];
-  if (!key || key !== "piggy-secret") {
+  if (headers["x-api-key"] !== "secret") {
     set.status = 401;
-    throw new Error("Unauthorized: missing or invalid x-api-key");
+    throw new Error("Unauthorized");
   }
 };
 
 piggy.books.api("/search", async (_params, query) => {
-  if (!query.q) return { error: "query param 'q' required" };
-
-  await piggy.books.navigate("https://books.toscrape.com");
-  await piggy.books.waitForSelector(".product_pod", 10000);
-
-  const books = await piggy.books.evaluate((q: string) =>
-    Array.from(document.querySelectorAll(".product_pod"))
-      .filter(el =>
-        el.querySelector("h3 a")?.getAttribute("title")?.toLowerCase().includes(q.toLowerCase())
-      )
-      .map(el => ({
-        title: el.querySelector("h3 a")?.getAttribute("title") ?? "",
-        price: el.querySelector(".price_color")?.textContent?.trim() ?? "",
-      }))
-  , query.q);
-
-  return { query: query.q, count: books.length, books };
-}, { ttl: 120_000, before: [logMiddleware, authMiddleware] });
-
-// curl -H 'x-api-key: piggy-secret' 'http://localhost:3000/books/search?q=light'
+  // handler
+}, { ttl: 120_000, before: [authMiddleware] });
 ```
 
 ---
@@ -181,18 +324,18 @@ piggy.books.api("/search", async (_params, query) => {
 ```ts
 await piggy.books.capture.clear();
 await piggy.books.capture.start();
-await piggy.books.wait(300); // ensure capture is active before nav
+await piggy.books.wait(300);
 
 await piggy.books.navigate("https://books.toscrape.com");
 await piggy.books.waitForSelector("body", 10000);
-await piggy.books.wait(2000); // let async XHR/fetch calls settle
+await piggy.books.wait(2000);
 
 await piggy.books.capture.stop();
 
 const requests = await piggy.books.capture.requests();
 const ws       = await piggy.books.capture.ws();
-const storage  = await piggy.books.capture.storage();
 const cookies  = await piggy.books.capture.cookies();
+const storage  = await piggy.books.capture.storage();
 
 console.log(`${requests.length} requests, ${ws.length} WS frames`);
 ```
@@ -206,13 +349,11 @@ import { existsSync, readFileSync, writeFileSync } from "fs";
 
 const SESSION_FILE = "./session.json";
 
-// Restore on startup
 if (existsSync(SESSION_FILE)) {
   const saved = JSON.parse(readFileSync(SESSION_FILE, "utf8"));
   await piggy.books.session.import(saved);
 }
 
-// Save on shutdown — always BEFORE piggy.close()
 process.on("SIGINT", async () => {
   const session = await piggy.books.session.export();
   writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
@@ -233,7 +374,7 @@ await piggy.books.type("#search", "mystery novels");
 await piggy.books.scroll.by(400);
 ```
 
-Affects: `click`, `type`, `hover`, `scroll.by`, `wait`.
+Affects `click`, `type`, `hover`, `scroll.by`, `wait` — random delays, simulated typos, self-correction.
 
 ---
 
@@ -243,8 +384,7 @@ Affects: `click`, `type`, `hover`, `scroll.by`, `wait`.
 await piggy.books.screenshot("./out/page.png");
 await piggy.books.pdf("./out/page.pdf");
 
-// or base64
-const b64 = await piggy.books.screenshot();
+const b64 = await piggy.books.screenshot(); // base64
 ```
 
 ---
@@ -256,8 +396,7 @@ await piggy.register("site1", "https://example.com");
 await piggy.register("site2", "https://example.org");
 
 const titles = await piggy.all([piggy.site1, piggy.site2]).title();
-
-const h1s = await piggy.diff([piggy.site1, piggy.site2]).fetchText("h1");
+const h1s    = await piggy.diff([piggy.site1, piggy.site2]).fetchText("h1");
 // → { site1: "...", site2: "..." }
 ```
 
@@ -270,13 +409,20 @@ const h1s = await piggy.diff([piggy.site1, piggy.site2]).fetchText("h1");
 | Option | Type | Default |
 |--------|------|---------|
 | `mode` | `"tab" \| "process"` | `"tab"` |
+| `binary` | `"headless" \| "headful"` | `"headless"` |
 
 ### `piggy.register(name, url)`
-Registers a site. Accessible as `piggy.<n>` after registration.
+Registers a site. Accessible as `piggy.<name>` after registration.
 
 ### `piggy.actHuman(enable)`
 Toggles human-like interaction timing globally.
 
+### `piggy.expose(name, handler, tabId?)`
+Exposes a function globally (available to all tabs). The handler receives data from the browser and can return a value that resolves the Promise in the browser.
+
+### `piggy.unexpose(name, tabId?)`
+Removes a globally exposed function.
+
 ### `piggy.serve(port, opts?)`
 Starts the Elysia HTTP server. Built-in routes: `GET /health`, `GET /cache/keys`, `DELETE /cache`.
 
@@ -286,7 +432,7 @@ Returns all registered API routes with method, path, TTL, and middleware count.
 ### `piggy.close(opts?)`
 
 ```ts
-await piggy.close();                // graceful — respects noclose()
+await piggy.close();                // graceful
 await piggy.close({ force: true }); // kills everything immediately
 ```
 
@@ -307,10 +453,10 @@ site.wait(ms)
 ```ts
 site.click(selector, opts?)
 site.doubleClick(selector) / site.hover(selector)
-site.type(selector, text, opts?)     // opts: { delay?, wpm?, fact? }
+site.type(selector, text, opts?)
 site.select(selector, value)
 site.keyboard.press(key)
-site.keyboard.combo(combo)           // e.g. "Ctrl+A"
+site.keyboard.combo(combo)
 site.mouse.move(x, y)
 site.mouse.drag(from, to)
 site.scroll.to(selector) / site.scroll.by(px)
@@ -318,13 +464,30 @@ site.scroll.to(selector) / site.scroll.by(px)
 
 #### Data
 ```ts
-site.fetchText(selector)             // → string | null
-site.fetchLinks(selector)            // → string[]
-site.fetchImages(selector)           // → string[]
+site.fetchText(selector)
+site.fetchLinks(selector)
+site.fetchImages(selector)
 site.search.css(query) / site.search.id(query)
 site.evaluate(js | fn, ...args)
 ```
 
+#### 🔥 Expose Function (RPC)
+```ts
+// Expose a function that browser JS can call
+site.exposeFunction(name, handler)
+// handler: (data: any) => Promise<any> | any
+
+// Remove an exposed function
+site.unexposeFunction(name)
+
+// Remove all exposed functions for this site
+site.clearExposedFunctions()
+
+// Expose and inject in one call
+site.exposeAndInject(name, handler, injectionJs)
+// injectionJs: string | ((fnName: string) => string)
+```
+
 #### Network
 ```ts
 site.capture.start() / .stop() / .clear()
@@ -347,27 +510,53 @@ site.session.export() / site.session.import(data)
 ```ts
 site.api(path, handler, opts?)
 // opts: { ttl?, method?, before?: middleware[] }
-// handler: (params, query, body) => Promise<any>
 
 site.noclose()
 site.screenshot(filePath?) / site.pdf(filePath?)
 ```
 
+### Helper Functions
+
+```ts
+import { createExposedAPI } from "nothing-browser/register";
+
+// Create a structured API with multiple methods
+await createExposedAPI(site, apiName, {
+  method1: async (args) => { /* ... */ },
+  method2: async (args) => { /* ... */ },
+});
+
+// Browser calls: window[apiName]({ method: 'method1', args: {...} })
+```
+
+---
+
+## How `exposeFunction` Works
+
+1. **Browser injects stub**: `window.fnName` becomes a Promise-returning function
+2. **Browser queues calls**: Arguments are pushed to `__NOTHING_QUEUE__`
+3. **C++ picks up queue**: 250ms poll timer reads the queue
+4. **Signal to Node.js**: Server broadcasts event to all connected clients
+5. **Your handler runs**: TypeScript handler processes the data
+6. **Result returns**: Promise in browser resolves with your return value
+
+The function survives page navigations (injected at `DocumentCreation`) and works with both tab and process modes.
+
 ---
 
 ## Binary download
 
-| Platform | File |
-|----------|------|
-| Linux x86_64 (deb) | `nothing-browser-headless_*_amd64.deb` |
-| Linux x86_64 (tar.gz) | `nothing-browser-headless-*-linux-x86_64.tar.gz` |
-| Windows x64 | `nothing-browser-headless-*.zip` |
-| macOS | `nothing-browser-headless-*.tar.gz` |
+| Platform | Headless | Headful | Full Browser |
+|----------|----------|---------|--------------|
+| Linux x86_64 (deb) | `nothing-browser-headless_*_amd64.deb` | `nothing-browser-headful_*_amd64.deb` | `nothing-browser_*_amd64.deb` |
+| Linux x86_64 (tar.gz) | `nothing-browser-headless-*-linux-x86_64.tar.gz` | `nothing-browser-headful-*-linux-x86_64.tar.gz` | `nothing-browser-*-linux-x86_64.tar.gz` |
+| Windows x64 | `nothing-browser-headless-*-windows-x64.zip` | `nothing-browser-headful-*-windows-x64.zip` | `nothing-browser-*-windows-x64.zip` |
+| macOS | `nothing-browser-headless-*-macos.tar.gz` | `nothing-browser-headful-*-macos.tar.gz` | `nothing-browser-*-macos.dmg` |
 
-→ [BunElysiaReact/nothing-browser releases](https://github.com/BunElysiaReact/nothing-browser/releases)
+→ [All releases](https://github.com/BunElysiaReact/nothing-browser/releases)
 
 ---
 
 ## License
 
-MIT © [Ernest Tech House](https://github.com/ernest-tech-house-co-operation)
+MIT © [Ernest Tech House](https://github.com/BunElysiaReact/nothing-browser)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nothing-browser",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Scraper-first headless browser library — control real tabs, intercept network traffic, capture WebSockets, spoof fingerprints. Powered by Qt6/Chromium.",
   "module": "piggy.ts",
   "main": "piggy.ts",

package/piggy/client/index.ts

@@ -10,9 +10,12 @@ export class PiggyClient {
   private reqId = 0;
   private pending = new Map<string, { resolve: (v: any) => void; reject: (e: Error) => void }>();
   private buf = "";
+  private eventBuffer = "";
+  private eventHandlers = new Map<string, Map<string, (data: any) => Promise<any>>>();
 
   constructor(socketPath = "/tmp/piggy") {
     this.socketPath = socketPath;
+    this.eventHandlers.set("default", new Map());
   }
 
   connect(): Promise<void> {
@@ -28,13 +31,22 @@ export class PiggyClient {
       });
 
       sock.on("data", (chunk: string) => {
-        this.buf += chunk;
-        const lines = this.buf.split("\n");
-        this.buf = lines.pop()!;
+        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);
+            
+            // Handle events
+            if (msg.type === "event") {
+              this.handleEvent(msg);
+              continue;
+            }
+            
+            // Handle command responses
             const p = this.pending.get(msg.id);
             if (p) {
               this.pending.delete(msg.id);
@@ -59,6 +71,56 @@ export class PiggyClient {
     });
   }
 
+  private handleEvent(event: any) {
+    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}`));
+              }
+            } else {
+              // Handler returned raw value
+              this.send("exposed.result", {
+                tabId: effectiveTabId,
+                callId,
+                result: JSON.stringify(response),
+                isError: false
+              }).catch(e => logger.error(`Failed to send exposed result: ${e}`));
+            }
+          })
+          .catch(err => {
+            this.send("exposed.result", {
+              tabId: effectiveTabId,
+              callId,
+              result: err.message || "Handler error",
+              isError: true
+            }).catch(e => logger.error(`Failed to send exposed error: ${e}`));
+          });
+      } else {
+        logger.warn(`No handler for exposed function: ${name} in tab ${effectiveTabId}`);
+      }
+    }
+  }
+
   disconnect() {
     this.socket?.destroy();
     this.socket = null;
@@ -327,4 +389,48 @@ export class PiggyClient {
   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> {
+    // Initialize handlers map for this tab if needed
+    if (!this.eventHandlers.has(tabId)) {
+      this.eventHandlers.set(tabId, new Map());
+    }
+    
+    // Store the handler
+    this.eventHandlers.get(tabId)!.set(name, async (data: any) => {
+      try {
+        const result = await handler(data);
+        // Return in expected format
+        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) };
+      }
+    });
+    
+    // Register with server
+    await this.send("expose.function", { name, tabId });
+    logger.success(`[${tabId}] exposed function: ${name}`);
+  }
+
+  async unexposeFunction(name: string, tabId = "default"): Promise<void> {
+    const handlers = this.eventHandlers.get(tabId);
+    if (handlers) {
+      handlers.delete(name);
+    }
+    logger.info(`[${tabId}] unexposed function: ${name}`);
+  }
+
+  async clearExposedFunctions(tabId = "default"): Promise<void> {
+    this.eventHandlers.set(tabId, new Map());
+    logger.info(`[${tabId}] cleared all exposed functions`);
+  }
 }

package/piggy/launch/detect.ts

@@ -2,32 +2,42 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import logger from '../logger';
 
-export function detectBinary(): string | null {
-    const cwd = process.cwd();
-    
-    // Windows
-    const windowsPath = join(cwd, 'nothing-browser-headless.exe');
-    if (process.platform === 'win32' && existsSync(windowsPath)) {
-        logger.success(`Binary found! Platform: Windows`);
-        return windowsPath;
-    }
-    
-    // Linux / macOS
-    const unixPath = join(cwd, 'nothing-browser-headless');
-    if (existsSync(unixPath)) {
-        logger.success(`Binary found at: ${unixPath}`);
-        return unixPath;
-    }
-    
-    logger.error("❌ Binary not found in project root");
-    logger.error("");
-    logger.error("Download from:");
-    logger.error("  https://github.com/BunElysiaReact/nothing-browser/releases/");
-    logger.error("");
-    logger.error(`Place in: ${cwd}/nothing-browser-headless${process.platform === 'win32' ? '.exe' : ''}`);
-    if (process.platform !== 'win32') {
-        logger.error("Then run: chmod +x nothing-browser-headless");
+export type BinaryMode = 'headless' | 'headful';
+
+const BINARY_NAMES: Record<BinaryMode, string> = {
+  headless: 'nothing-browser-headless',
+  headful:  'nothing-browser-headful',
+};
+
+export function detectBinary(mode: BinaryMode = 'headless'): string | null {
+  const cwd = process.cwd();
+  const name = BINARY_NAMES[mode];
+
+  // Windows
+  if (process.platform === 'win32') {
+    const p = join(cwd, `${name}.exe`);
+    if (existsSync(p)) {
+      logger.success(`Binary found (${mode}): ${p}`);
+      return p;
     }
-    
-    return null;
+  }
+
+  // Linux / macOS
+  const p = join(cwd, name);
+  if (existsSync(p)) {
+    logger.success(`Binary found (${mode}): ${p}`);
+    return p;
+  }
+
+  logger.error(`❌ Binary not found in project root: ${name}`);
+  logger.error('');
+  logger.error('Download from:');
+  logger.error('  https://github.com/BunElysiaReact/nothing-browser/releases/');
+  logger.error('');
+  logger.error(`Place in: ${cwd}/${name}${process.platform === 'win32' ? '.exe' : ''}`);
+  if (process.platform !== 'win32') {
+    logger.error(`Then run: chmod +x ${name}`);
+  }
+
+  return null;
 }

package/piggy/launch/spawn.ts

@@ -1,101 +1,99 @@
 import { spawn } from 'bun';
 import { execSync } from 'child_process';
-import { detectBinary } from './detect';
+import { detectBinary, type BinaryMode } from './detect';
 import logger from '../logger';
 
 let activeProcess: any = null;
 const extraProcesses: any[] = [];
 
 export function killAllBrowsers(): void {
-    try {
-        logger.info("Cleaning up existing browser processes...");
-        execSync('pkill -f nothing-browser-headless 2>/dev/null || true', { stdio: 'ignore' });
-        execSync('pkill -f QtWebEngineProcess 2>/dev/null || true', { stdio: 'ignore' });
-        execSync('rm -f /tmp/piggy', { stdio: 'ignore' });
-    } catch {
-        // Ignore errors - no processes to kill
-    }
+  try {
+    logger.info('Cleaning up existing browser processes...');
+    execSync('pkill -f nothing-browser-headless 2>/dev/null || true', { stdio: 'ignore' });
+    execSync('pkill -f nothing-browser-headful 2>/dev/null || true', { stdio: 'ignore' });
+    execSync('pkill -f QtWebEngineProcess 2>/dev/null || true', { stdio: 'ignore' });
+    execSync('rm -f /tmp/piggy', { stdio: 'ignore' });
+  } catch {
+    // no processes to kill
+  }
 }
 
-export async function spawnBrowser(): Promise<string> {
-    killAllBrowsers();
-
-    // Give OS time to release the socket
-    await new Promise(resolve => setTimeout(resolve, 500));
-
-    const binaryPath = detectBinary();
-    if (!binaryPath) {
-        throw new Error("Binary not found. Cannot launch.");
-    }
-
-    logger.info(`Spawning Nothing Browser from: ${binaryPath}`);
-
-    activeProcess = spawn([binaryPath], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        env: process.env
-    });
-
-    if (activeProcess.stdout) {
-        const reader = activeProcess.stdout.getReader();
-        const read = async () => {
-            const { done, value } = await reader.read();
-            if (!done) {
-                const output = new TextDecoder().decode(value);
-                logger.debug(`[Browser] ${output}`);
-                read();
-            }
-        };
+export async function spawnBrowser(mode: BinaryMode = 'headless'): Promise<string> {
+  killAllBrowsers();
+  await new Promise(resolve => setTimeout(resolve, 500));
+
+  const binaryPath = detectBinary(mode);
+  if (!binaryPath) {
+    throw new Error(`Binary not found (${mode}). Cannot launch.`);
+  }
+
+  logger.info(`Spawning Nothing Browser (${mode}) from: ${binaryPath}`);
+
+  activeProcess = spawn([binaryPath], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: process.env,
+  });
+
+  if (activeProcess.stdout) {
+    const reader = activeProcess.stdout.getReader();
+    const read = async () => {
+      const { done, value } = await reader.read();
+      if (!done) {
+        logger.debug(`[Browser] ${new TextDecoder().decode(value)}`);
         read();
-    }
+      }
+    };
+    read();
+  }
 
-    activeProcess.exited.then((code: number | null) => {
-        logger.warn(`Browser process exited with code: ${code}`);
-        activeProcess = null;
-    });
+  activeProcess.exited.then((code: number | null) => {
+    logger.warn(`Browser process exited with code: ${code}`);
+    activeProcess = null;
+  });
 
-    await new Promise(resolve => setTimeout(resolve, 2000));
+  await new Promise(resolve => setTimeout(resolve, 2000));
 
-    if (activeProcess) {
-        logger.success("Browser spawned and running");
-    } else {
-        logger.error("Browser started but exited immediately");
-    }
+  if (activeProcess) {
+    logger.success(`Browser spawned and running (${mode})`);
+  } else {
+    logger.error('Browser started but exited immediately');
+  }
 
-    return binaryPath;
+  return binaryPath;
 }
 
-export async function spawnBrowserOnSocket(socketName: string): Promise<void> {
-    const binaryPath = detectBinary();
-    if (!binaryPath) {
-        throw new Error("Binary not found. Cannot launch.");
-    }
+export async function spawnBrowserOnSocket(
+  socketName: string,
+  mode: BinaryMode = 'headless'
+): Promise<void> {
+  const binaryPath = detectBinary(mode);
+  if (!binaryPath) {
+    throw new Error(`Binary not found (${mode}). Cannot launch.`);
+  }
 
-    logger.info(`Spawning browser on socket: ${socketName}`);
+  logger.info(`Spawning browser (${mode}) on socket: ${socketName}`);
 
-    const proc = spawn([binaryPath], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        env: { ...process.env, PIGGY_SOCKET: socketName }
-    });
+  const proc = spawn([binaryPath], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...process.env, PIGGY_SOCKET: socketName },
+  });
 
-    extraProcesses.push(proc);
+  extraProcesses.push(proc);
 
-    proc.exited.then((code: number | null) => {
-        logger.warn(`Browser on socket ${socketName} exited with code: ${code}`);
-    });
+  proc.exited.then((code: number | null) => {
+    logger.warn(`Browser on socket ${socketName} exited with code: ${code}`);
+  });
 
-    await new Promise(resolve => setTimeout(resolve, 1000));
-    logger.success(`Browser spawned on socket: ${socketName}`);
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  logger.success(`Browser spawned (${mode}) on socket: ${socketName}`);
 }
 
 export function killBrowser(): void {
-    if (activeProcess) {
-        logger.info("Killing browser process...");
-        activeProcess.kill();
-        activeProcess = null;
-    }
-
-    for (const proc of extraProcesses) {
-        proc.kill();
-    }
-    extraProcesses.length = 0;
+  if (activeProcess) {
+    logger.info('Killing browser process...');
+    activeProcess.kill();
+    activeProcess = null;
+  }
+  for (const proc of extraProcesses) proc.kill();
+  extraProcesses.length = 0;
 }

package/piggy/register/index.ts

@@ -278,6 +278,42 @@ export function createSiteObject(
       },
     },
 
+    // ── Expose Function ─────────────────────────────────────────────────────────
+
+    exposeFunction: async (fnName: string, handler: (data: any) => Promise<any> | any) => {
+      await client.exposeFunction(fnName, handler, tabId);
+      logger.success(`[${name}] exposed function: ${fnName}`);
+      return site;
+    },
+
+    unexposeFunction: async (fnName: string) => {
+      await client.unexposeFunction(fnName, tabId);
+      logger.info(`[${name}] unexposed function: ${fnName}`);
+      return site;
+    },
+
+    clearExposedFunctions: async () => {
+      await client.clearExposedFunctions(tabId);
+      logger.info(`[${name}] cleared all exposed functions`);
+      return site;
+    },
+
+    exposeAndInject: async (
+      fnName: string,
+      handler: (data: any) => Promise<any> | any,
+      injectionJs: string | ((fnName: string) => string)
+    ) => {
+      await client.exposeFunction(fnName, handler, tabId);
+      
+      const js = typeof injectionJs === "function" 
+        ? injectionJs(fnName) 
+        : injectionJs;
+        
+      await client.evaluate(js, tabId);
+      logger.success(`[${name}] exposed and injected: ${fnName}`);
+      return site;
+    },
+
     // ── Elysia API ─────────────────────────────────────────────────────────────
 
     api: (
@@ -313,4 +349,30 @@ export function createSiteObject(
   };
 
   return site;
+}
+
+// ── Helper for creating structured APIs ───────────────────────────────────────
+
+export function createExposedAPI<T extends Record<string, (data: any) => any>>(
+  site: any,
+  apiName: string,
+  handlers: T
+): Promise<void> {
+  const wrappedHandler = async (call: any) => {
+    const { method, args } = call;
+    const handler = handlers[method as keyof T];
+    
+    if (!handler) {
+      throw new Error(`Unknown method: ${method}`);
+    }
+    
+    try {
+      return await handler(args);
+    } catch (err) {
+      logger.error(`[${site._name}] API error in ${method}:`, err);
+      throw err;
+    }
+  };
+  
+  return site.exposeFunction(apiName, wrappedHandler);
 }

package/piggy.ts

@@ -1,45 +1,47 @@
 // piggy.ts
-import { detectBinary } from "./piggy/launch/detect";
+import { detectBinary, type BinaryMode } from "./piggy/launch/detect";
 import { spawnBrowser, killBrowser, spawnBrowserOnSocket } from "./piggy/launch/spawn";
 import { PiggyClient } from "./piggy/client";
 import { setClient, setHumanMode, createSiteObject } from "./piggy/register";
 import { routeRegistry, keepAliveSites, startServer, stopServer } from "./piggy/server";
 import logger from "./piggy/logger";
 
-type BrowserMode = "tab" | "process";
+type TabMode = "tab" | "process";
 type SiteObject = ReturnType<typeof createSiteObject>;
 
 let _client: PiggyClient | null = null;
-let _mode: BrowserMode = "tab";
+let _tabMode: TabMode = "tab";
 const _extraProcs: { socket: string; client: PiggyClient }[] = [];
 const _sites: Record<string, SiteObject> = {};
 
 const piggy: any = {
   // ── Lifecycle ───────────────────────────────────────────────────────────────
 
-  launch: async (opts?: { mode?: BrowserMode }) => {
-    _mode = opts?.mode ?? "tab";
-    await spawnBrowser();
+  launch: async (opts?: { mode?: TabMode; binary?: BinaryMode }) => {
+    _tabMode = opts?.mode ?? "tab";
+    const binaryMode: BinaryMode = opts?.binary ?? "headless";
+    await spawnBrowser(binaryMode);
     await new Promise(r => setTimeout(r, 500));
     _client = new PiggyClient();
     await _client.connect();
     setClient(_client);
-    logger.info(`[piggy] launched in "${_mode}" mode`);
+    logger.info(`[piggy] launched — tab mode: "${_tabMode}", binary: "${binaryMode}"`);
     return piggy;
   },
 
-  register: async (name: string, url: string, opts?: any) => {
+  register: async (name: string, url: string, opts?: { binary?: BinaryMode }) => {
     if (!url?.trim()) throw new Error(`No URL for site "${name}"`);
+    const binaryMode: BinaryMode = opts?.binary ?? "headless";
 
     let tabId = "default";
-    if (_mode === "tab") {
+    if (_tabMode === "tab") {
       tabId = await _client!.newTab();
       _sites[name] = createSiteObject(name, url, _client!, tabId);
       piggy[name] = _sites[name];
       logger.success(`[${name}] registered as tab ${tabId}`);
     } else {
       const socketName = `piggy_${name}`;
-      await spawnBrowserOnSocket(socketName);
+      await spawnBrowserOnSocket(socketName, binaryMode);
       await new Promise(r => setTimeout(r, 500));
       const c = new PiggyClient(socketName);
       await c.connect();
@@ -49,7 +51,6 @@ const piggy: any = {
       logger.success(`[${name}] registered as process on "${socketName}"`);
     }
 
-    if (opts?.mode) logger.info(`[${name}] mode: ${opts.mode}`);
     return piggy;
   },
 
@@ -61,7 +62,23 @@ const piggy: any = {
     return piggy;
   },
 
-  mode: (m: BrowserMode) => { _mode = m; return piggy; },
+  mode: (m: TabMode) => { _tabMode = m; return piggy; },
+
+  // ── Expose Function (global) ─────────────────────────────────────────────────
+
+  expose: async (name: string, handler: (data: any) => Promise<any> | any, tabId = "default") => {
+    if (!_client) throw new Error("No client. Call piggy.launch() first.");
+    await _client.exposeFunction(name, handler, tabId);
+    logger.success(`[piggy] exposed global function: ${name}`);
+    return piggy;
+  },
+
+  unexpose: async (name: string, tabId = "default") => {
+    if (!_client) throw new Error("No client. Call piggy.launch() first.");
+    await _client.unexposeFunction(name, tabId);
+    logger.info(`[piggy] unexposed function: ${name}`);
+    return piggy;
+  },
 
   // ── Elysia server ────────────────────────────────────────────────────────────