nothing-browser 0.0.1 → 0.0.3

package/README.md

@@ -20,7 +20,21 @@ A scraper-first headless browser library powered by the Nothing Browser Qt6/Chro
 ## 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 are 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 `nothingbrowser` npm/Bun lib talks to whichever binary is in your project root over a local socket. You pick headless or headful depending on your use case.
 
 ---
 
@@ -30,17 +44,38 @@ 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 [GitHub 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
+```
+
+**Full browser** (system-wide install, for using the UI)
+```bash
+sudo dpkg -i nothing-browser_*_amd64.deb
+# or
+tar -xzf nothing-browser-*-linux-x86_64.tar.gz
+cd nothing-browser-*-linux-x86_64
+./nothing-browser
+```
+
+### Windows
+
+Download the `.zip` for your chosen binary → extract → place `nothing-browser-headless.exe` or `nothing-browser-headful.exe` in your project root. The JRE is bundled in the full browser zip.
 
-**macOS** — extract the `.tar.gz`, place `nothing-browser-headless` in project root.
+### macOS
+
+Download the `.tar.gz` for your chosen binary → extract → place the binary in your project root.
 
 ---
 
@@ -86,6 +121,24 @@ await piggy.launch({ mode: "process" });
 
 ---
 
+## Headless vs Headful
+
+**Headless** — no display needed, runs anywhere including CI. Use this by default.
+
+```
+nothing-browser-headless        ← in your project root
+```
+
+**Headful** — opens a real visible Chromium window that your script drives. Use this when a site detects headless mode or requires a real display (canvas fingerprinting, certain login flows, etc).
+
+```
+nothing-browser-headful         ← in your project root
+```
+
+Both binaries expose the exact same socket API. Switching is just swapping which binary is in your project root.
+
+---
+
 ## Examples
 
 ### Scrape a site and expose it as an API
@@ -96,7 +149,6 @@ import piggy from "nothing-browser";
 await piggy.launch({ mode: "tab" });
 await piggy.register("books", "https://books.toscrape.com");
 
-// Block ads/trackers before any navigation
 await piggy.books.intercept.block("*google-analytics*");
 await piggy.books.intercept.block("*doubleclick*");
 await piggy.books.intercept.block("*facebook*");
@@ -127,8 +179,6 @@ piggy.books.api("/list", async (_params, query) => {
 
 piggy.books.noclose();
 await piggy.serve(3000);
-// GET http://localhost:3000/books/list
-// GET http://localhost:3000/books/list?page=2
 ```
 
 ---
@@ -167,8 +217,6 @@ piggy.books.api("/search", async (_params, query) => {
 
   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'
 ```
 
 ---
@@ -178,11 +226,11 @@ 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();
 
@@ -203,13 +251,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));
@@ -222,8 +268,6 @@ process.on("SIGINT", async () => {
 
 ### Human mode
 
-Makes interactions look less robotic — random delays, simulated typos + self-correction.
-
 ```ts
 piggy.actHuman(true);
 
@@ -232,18 +276,14 @@ await piggy.books.type("#search", "mystery novels");
 await piggy.books.scroll.by(400);
 ```
 
-Affects: `click`, `type`, `hover`, `scroll.by`, `wait`.
-
 ---
 
 ### Screenshot / PDF
 
 ```ts
-// Save to disk
 await piggy.books.screenshot("./out/page.png");
 await piggy.books.pdf("./out/page.pdf");
 
-// Or get base64
 const b64 = await piggy.books.screenshot();
 ```
 
@@ -255,11 +295,8 @@ const b64 = await piggy.books.screenshot();
 await piggy.register("site1", "https://example.com");
 await piggy.register("site2", "https://example.org");
 
-// Same method on both sites in parallel
 const titles = await piggy.all([piggy.site1, piggy.site2]).title();
-
-// Keyed results by site name
-const h1s = await piggy.diff([piggy.site1, piggy.site2]).fetchText("h1");
+const h1s    = await piggy.diff([piggy.site1, piggy.site2]).fetchText("h1");
 // → { site1: "...", site2: "..." }
 ```
 
@@ -351,7 +388,7 @@ site.api(path, handler, opts?)
 // opts: { ttl?, method?, before?: middleware[] }
 // handler: (params, query, body) => Promise<any>
 
-site.noclose()                       // keep site alive across piggy.close()
+site.noclose()
 site.screenshot(filePath?) / site.pdf(filePath?)
 ```
 
@@ -359,12 +396,12 @@ site.screenshot(filePath?) / site.pdf(filePath?)
 
 ## 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` |
 
 → [All releases](https://github.com/BunElysiaReact/nothing-browser/releases)
 
@@ -372,4 +409,4 @@ site.screenshot(filePath?) / site.pdf(filePath?)
 
 ## License
 
-MIT © [Ernest Tech House](https://github.com/BunElysiaReact)
+MIT © [Ernest Tech House](https://github.com/BunElysiaReact/nothing-browser)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nothing-browser",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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",
@@ -24,15 +24,15 @@
     "fingerprint-spoofing",
     "network-interception"
   ],
-  "author": "Ernest Tech House <BunElysiaReact>",
+  "author": "Ernest Tech House",
   "license": "MIT",
-  "homepage": "https://github.com/BunElysiaReact/nothing-browser#readme",
+  "homepage": "https://github.com/ernest-tech-house-co-operation/nothing-browser#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/BunElysiaReact/nothing-browser.git"
+    "url": "https://github.com/ernest-tech-house-co-operation/nothing-browser.git"
   },
   "bugs": {
-    "url": "https://github.com/BunElysiaReact/nothing-browser/issues"
+    "url": "https://github.com/ernest-tech-house-co-operation/nothing-browser/issues"
   },
   "files": [
     "piggy.ts",

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.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,7 @@ const piggy: any = {
     return piggy;
   },
 
-  mode: (m: BrowserMode) => { _mode = m; return piggy; },
+  mode: (m: TabMode) => { _tabMode = m; return piggy; },
 
   // ── Elysia server ────────────────────────────────────────────────────────────