nothing-browser 0.1.1 → 0.1.3

package/piggy/client/index.ts

@@ -1,4 +1,4 @@
-// piggy/client/index.ts
+//piggy/client/index.ts 
 import { connect, type Socket } from "net";
 import { writeFileSync, mkdirSync } from "fs";
 import { dirname } from "path";
@@ -280,6 +280,23 @@ export class PiggyClient {
         }
       }
     }
+
+    if (event.event === "dialog") {
+      const key = `dialog:${event.tabId ?? "default"}`;
+      const handlers = this.globalEventHandlers.get(key);
+      if (handlers) {
+        for (const h of handlers) {
+          try {
+            h({
+              dialogType:   event.dialogType,
+              message:      event.message,
+              defaultValue: event.defaultValue,
+              tabId:        event.tabId,
+            });
+          } catch (e) { logger.error(`dialog handler error: ${e}`); }
+        }
+      }
+    }
   }
 
   onEvent(eventName: string, tabId: string, handler: (data: any) => void): () => void {
@@ -384,9 +401,9 @@ export class PiggyClient {
 
   // ── 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 }); }
+  async getCookie(name: string, domain = "", tabId = "default"): Promise<any> { return this.send("cookie.get", { name, domain, tabId }); }
+  async deleteCookie(name: string, domain: string, tabId = "default"): Promise<void> { await this.send("cookie.delete", { name, domain, tabId }); }
+  async listCookies(domain = "", tabId = "default"): Promise<any[]> { return this.send<any[]>("cookie.list", { domain, tabId }); }
 
   // ── Interception ──────────────────────────────────────────────────────────
   async addInterceptRule(action: "block" | "redirect" | "modifyHeaders", pattern: string, options: { redirectUrl?: string; headers?: Record<string, string> } = {}, tabId = "default"): Promise<void> {
@@ -407,55 +424,14 @@ export class PiggyClient {
   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 }); }
 
-  // ── Session persistence (opt-in) ──────────────────────────────────────────
-  // WS frames and pings are NOT saved by default — you must opt in.
-  // Files are written to cwd (same folder as cookies.json / profile.json).
-
-  /** Enable or disable saving WebSocket frames to ws.json in cwd */
-  async sessionWsSave(enabled = true): Promise<void> {
-    await this.send("session.ws.save", { enabled });
-  }
-
-  /** Enable or disable saving ping log to pings.json in cwd */
-  async sessionPingsSave(enabled = true): Promise<void> {
-    await this.send("session.pings.save", { enabled });
-  }
-
-  /** Get all data file paths for the current session */
-  async sessionPaths(): Promise<{
-    workDir: string;
-    cookies: string;
-    profile: string;
-    ws: string;
-    pings: string;
-  }> {
-    return this.send("session.paths", {});
-  }
-
-  /** Get path to cookies.json */
-  async sessionCookiesPath(): Promise<string> {
-    return this.send("session.cookies.path", {});
-  }
-
-  /** Get path to profile.json */
-  async sessionProfilePath(): Promise<string> {
-    return this.send("session.profile.path", {});
-  }
-
-  /** Get path to ws.json */
-  async sessionWsPath(): Promise<string> {
-    return this.send("session.ws.path", {});
-  }
-
-  /** Get path to pings.json */
-  async sessionPingsPath(): Promise<string> {
-    return this.send("session.pings.path", {});
-  }
-
-  /** Reload cookies.json and profile.json from disk without restarting */
-  async sessionReload(): Promise<void> {
-    await this.send("session.reload", {});
-  }
+  async sessionWsSave(enabled = true): Promise<void> { await this.send("session.ws.save", { enabled }); }
+  async sessionPingsSave(enabled = true): Promise<void> { await this.send("session.pings.save", { enabled }); }
+  async sessionPaths(): Promise<{ workDir: string; cookies: string; profile: string; ws: string; pings: string; }> { return this.send("session.paths", {}); }
+  async sessionCookiesPath(): Promise<string> { return this.send("session.cookies.path", {}); }
+  async sessionProfilePath(): Promise<string> { return this.send("session.profile.path", {}); }
+  async sessionWsPath(): Promise<string> { return this.send("session.ws.path", {}); }
+  async sessionPingsPath(): Promise<string> { return this.send("session.pings.path", {}); }
+  async sessionReload(): Promise<void> { await this.send("session.reload", {}); }
 
   // ── Expose Function ───────────────────────────────────────────────────────
   async exposeFunction(name: string, handler: (data: any) => Promise<any> | any, tabId = "default"): Promise<void> {
@@ -485,82 +461,28 @@ export class PiggyClient {
   }
 
   // ── Proxy ─────────────────────────────────────────────────────────────────
-
-  async proxyLoad(path: string): Promise<void> {
-    await this.send("proxy.load", { path });
-  }
-
-  async proxyFetch(url: string): Promise<void> {
-    await this.send("proxy.fetch", { url });
-  }
-
-  async proxyOvpn(path: string): Promise<void> {
-    await this.send("proxy.ovpn", { path });
-  }
+  async proxyLoad(path: string): Promise<void> { await this.send("proxy.load", { path }); }
+  async proxyFetch(url: string): Promise<void> { await this.send("proxy.fetch", { url }); }
+  async proxyOvpn(path: string): Promise<void> { await this.send("proxy.ovpn", { path }); }
 
   async proxySet(opts: {
-    host?: string;
-    port?: number;
+    host?: string; port?: number;
     type?: "http" | "https" | "socks5" | "socks4";
-    user?: string;
-    pass?: string;
-    proxy?: string;
-  }): Promise<void> {
-    await this.send("proxy.set", opts as Record<string, any>);
-  }
-
-  async proxyTest(): Promise<void> {
-    await this.send("proxy.test", {});
-  }
-
-  async proxyTestStop(): Promise<void> {
-    await this.send("proxy.test.stop", {});
-  }
-
-  async proxyNext(): Promise<void> {
-    await this.send("proxy.next", {});
-  }
-
-  async proxyDisable(): Promise<void> {
-    await this.send("proxy.disable", {});
-  }
-
-  async proxyEnable(): Promise<void> {
-    await this.send("proxy.enable", {});
-  }
-
-  async proxyCurrent(): Promise<{
-    host: string; port: number; type: string;
-    user?: string; alive: boolean; latencyMs?: number;
-  }> {
-    return this.send("proxy.current", {});
-  }
-
-  async proxyStats(): Promise<{
-    total: number; alive: number; dead: number;
-    index: number; checking: boolean;
-  }> {
-    return this.send("proxy.stats", {});
-  }
-
-  async proxyList(limit?: number): Promise<{
-    host: string; port: number; type: string;
-    alive: boolean; latencyMs?: number;
-  }[]> {
-    return this.send("proxy.list", limit !== undefined ? { limit } : {});
-  }
-
-  async proxyRotation(mode: "none" | "timed" | "perrequest", interval?: number): Promise<void> {
-    await this.send("proxy.rotation", { mode, ...(interval !== undefined ? { interval } : {}) });
-  }
-
-  async proxyConfig(opts: { skipDead?: boolean; autoCheck?: boolean }): Promise<void> {
-    await this.send("proxy.config", opts as Record<string, any>);
-  }
-
-  async proxySave(path: string, filter: "alive" | "dead" | "all" = "all"): Promise<void> {
-    await this.send("proxy.save", { path, filter });
-  }
+    user?: string; pass?: string; proxy?: string;
+  }): Promise<void> { await this.send("proxy.set", opts as Record<string, any>); }
+
+  async proxyTest(): Promise<void> { await this.send("proxy.test", {}); }
+  async proxyTestStop(): Promise<void> { await this.send("proxy.test.stop", {}); }
+  async proxyNext(): Promise<void> { await this.send("proxy.next", {}); }
+  async proxyDisable(): Promise<void> { await this.send("proxy.disable", {}); }
+  async proxyEnable(): Promise<void> { await this.send("proxy.enable", {}); }
+
+  async proxyCurrent(): Promise<{ host: string; port: number; type: string; user?: string; alive: boolean; latencyMs?: number; }> { return this.send("proxy.current", {}); }
+  async proxyStats(): Promise<{ total: number; alive: number; dead: number; index: number; checking: boolean; }> { return this.send("proxy.stats", {}); }
+  async proxyList(limit?: number): Promise<{ host: string; port: number; type: string; alive: boolean; latencyMs?: number; }[]> { return this.send("proxy.list", limit !== undefined ? { limit } : {}); }
+  async proxyRotation(mode: "none" | "timed" | "perrequest", interval?: number): Promise<void> { await this.send("proxy.rotation", { mode, ...(interval !== undefined ? { interval } : {}) }); }
+  async proxyConfig(opts: { skipDead?: boolean; autoCheck?: boolean }): Promise<void> { await this.send("proxy.config", opts as Record<string, any>); }
+  async proxySave(path: string, filter: "alive" | "dead" | "all" = "all"): Promise<void> { await this.send("proxy.save", { path, filter }); }
 
   onProxyEvent(event: string, handler: (data: any) => void): () => void {
     return this.onEvent(event, "*", handler);

package/piggy/expose/index.ts

@@ -0,0 +1,42 @@
+import { PiggyClient } from "../client";
+import logger from "../logger";
+
+export async function exposeFunction(
+  client: PiggyClient,
+  fnName: string,
+  handler: (data: any) => Promise<any> | any,
+  tabId: string
+): Promise<void> {
+  await client.exposeFunction(fnName, handler, tabId);
+  logger.success(`[${tabId}] exposed function: ${fnName}`);
+}
+
+export async function unexposeFunction(
+  client: PiggyClient,
+  fnName: string,
+  tabId: string
+): Promise<void> {
+  await client.unexposeFunction(fnName, tabId);
+  logger.info(`[${tabId}] unexposed function: ${fnName}`);
+}
+
+export async function clearExposedFunctions(
+  client: PiggyClient,
+  tabId: string
+): Promise<void> {
+  await client.clearExposedFunctions(tabId);
+  logger.info(`[${tabId}] cleared all exposed functions`);
+}
+
+export async function exposeAndInject(
+  client: PiggyClient,
+  fnName: string,
+  handler: (data: any) => Promise<any> | any,
+  injectionJs: string | ((fnName: string) => string),
+  tabId: string
+): Promise<void> {
+  await client.exposeFunction(fnName, handler, tabId);
+  const js = typeof injectionJs === "function" ? injectionJs(fnName) : injectionJs;
+  await client.evaluate(js, tabId);
+  logger.success(`[${tabId}] exposed and injected: ${fnName}`);
+}

package/piggy/register/index.ts

@@ -6,7 +6,14 @@ import { routeRegistry, keepAliveSites, type RouteHandler, type BeforeMiddleware
 import { buildRespondScript, buildModifyResponseScript } from "../intercept/scripts";
 import { storeRecord } from "../store";
 import { TabPool } from "../pool";
-
+import { createFindAPI } from "../find";
+import { createProvideAPI } from "../provide";
+import { createHumanAPI } from "../human";
+import { createSessionAPI } from "../session";
+import { DialogClient } from "../dialog";
+import { createIframeAPI } from "../iframe";
+import { exposeFunction, unexposeFunction, clearExposedFunctions, exposeAndInject  } from "../expose";
+import { createCaptchaAPI } from "../captcha";
 let globalClient: PiggyClient | null = null;
 export let humanMode = false;
 
@@ -105,6 +112,18 @@ export function createSiteObject(
         return client.waitForSelector(selector, timeout, t);
       }),
 
+exposeFunction:        (fnName: string, handler: (data: any) => Promise<any> | any) =>
+  exposeFunction(client, fnName, handler, tabId).then(() => site),
+
+unexposeFunction:      (fnName: string) =>
+  unexposeFunction(client, fnName, tabId).then(() => site),
+
+clearExposedFunctions: () =>
+  clearExposedFunctions(client, tabId).then(() => site),
+
+exposeAndInject: (fnName: string, handler: (data: any) => Promise<any> | any, injectionJs: string | ((fnName: string) => string)) =>
+  exposeAndInject(client, fnName, handler, injectionJs, tabId).then(() => site),
+
     waitForVisible:  (selector: string, timeout = 30000) =>
       withTab(t => client.waitForSelector(selector, timeout, t)),
 
@@ -257,6 +276,69 @@ export function createSiteObject(
       css: (query: string) => withTab(t => client.searchCss(query, t)),
       id:  (query: string) => withTab(t => client.searchId(query, t)),
     },
+    captcha: {
+  status:    ()                        => withTab(t => createCaptchaAPI(client).status(t)),
+  resolve:   ()                        => withTab(t => createCaptchaAPI(client).resolve(t)),
+  pause:     ()                        => withTab(t => createCaptchaAPI(client).pause(t)),
+  check:     ()                        => withTab(t => createCaptchaAPI(client).check(t)),
+  autoRetry: (opts: { enabled: boolean }) => withTab(t => createCaptchaAPI(client).setAutoRetry(opts.enabled)),
+  onCaptcha: (handler: any)            => createCaptchaAPI(client).onCaptcha(tabId, handler),
+  onResolved:(handler: any)            => createCaptchaAPI(client).onCaptchaResolved(tabId, handler),
+},
+block: {
+  status:    ()                        => withTab(t => createCaptchaAPI(client).blockStatus(t)),
+  retry:     ()                        => withTab(t => createCaptchaAPI(client).blockRetry(t)),
+  onBlocked: (handler: any)            => createCaptchaAPI(client).onBlocked(tabId, handler),
+  onRetry:   (handler: any)            => createCaptchaAPI(client).onBlockRetry(tabId, handler),
+},
+    find: {
+css: (selector: string) => withTab(t => {
+  console.log("[DEBUG] find.css tabId:", t);
+  return createFindAPI(client).css(selector, t);
+}),
+  all:           (selector: string)                        => withTab(t => createFindAPI(client).all(selector, t)),
+  first:         (selector: string)                        => withTab(t => createFindAPI(client).first(selector, t)),
+  byText:        (text: string)                            => withTab(t => createFindAPI(client).byText(text, t)),
+  byAttr:        (attr: string, value?: string)            => withTab(t => createFindAPI(client).byAttr(attr, value, t)),
+  byTag:         (tag: string)                             => withTab(t => createFindAPI(client).byTag(tag, t)),
+  byPlaceholder: (text: string)                            => withTab(t => createFindAPI(client).byPlaceholder(text, t)),
+  byRole:        (role: string, name?: string)             => withTab(t => createFindAPI(client).byRole(role, name, t)),
+  children:      (selector: string)                        => withTab(t => createFindAPI(client).children(selector, t)),
+  parent:        (selector: string)                        => withTab(t => createFindAPI(client).parent(selector, t)),
+  closest:       (selector: string, ancestor: string)      => withTab(t => createFindAPI(client).closest(selector, ancestor, t)),
+  count:         (selector: string)                        => withTab(t => createFindAPI(client).count(selector, t)),
+  exists:        (selector: string)                        => withTab(t => createFindAPI(client).exists(selector, t)),
+  visible:       (selector: string)                        => withTab(t => createFindAPI(client).visible(selector, t)),
+  enabled:       (selector: string)                        => withTab(t => createFindAPI(client).enabled(selector, t)),
+  checked:       (selector: string)                        => withTab(t => createFindAPI(client).checked(selector, t)),
+},
+
+provide: {
+  text:    (opts: any)              => withTab(t => createProvideAPI(client).text(opts, t)),
+  textAll: (opts: any)              => withTab(t => createProvideAPI(client).textAll(opts, t)),
+  attr:    (opts: any)              => withTab(t => createProvideAPI(client).attr(opts, t)),
+  attrAll: (opts: any)              => withTab(t => createProvideAPI(client).attrAll(opts, t)),
+  html:    (opts: any)              => withTab(t => createProvideAPI(client).html(opts, t)),
+  table:   (opts: any)              => withTab(t => createProvideAPI(client).table(opts, t)),
+  list:    (opts: any)              => withTab(t => createProvideAPI(client).list(opts, t)),
+  links:   (opts: any)              => withTab(t => createProvideAPI(client).links(opts, t)),
+  images:  (opts: any)              => withTab(t => createProvideAPI(client).images(opts, t)),
+  form:    (opts: any)              => withTab(t => createProvideAPI(client).form(opts, t)),
+  page:    ()                       => withTab(t => createProvideAPI(client).page(t)),
+  div:     (opts: any)              => withTab(t => createProvideAPI(client).div(opts, t)),
+  meta:    ()                       => withTab(t => createProvideAPI(client).meta(t)),
+  select:  (opts: any)              => withTab(t => createProvideAPI(client).select(opts, t)),
+  json:    (opts?: any)             => withTab(t => createProvideAPI(client).json(opts, t)),
+},
+iframe: {
+  list:    ()          => withTab(t => createIframeAPI(client).list(t)),
+  evaluate:(opts: any) => withTab(t => createIframeAPI(client).evaluate(opts, t)),
+  click:   (opts: any) => withTab(t => createIframeAPI(client).click(opts, t)),
+  type:    (opts: any) => withTab(t => createIframeAPI(client).type(opts, t)),
+  text:    (opts: any) => withTab(t => createIframeAPI(client).text(opts, t)),
+  html:    (opts: any) => withTab(t => createIframeAPI(client).html(opts, t)),
+  waitSel: (opts: any) => withTab(t => createIframeAPI(client).waitSel(opts, t)),
+},
 
     screenshot: async (filePath?: string) => {
       const r = await withTab(t => client.screenshot(filePath, t));
@@ -269,6 +351,13 @@ export function createSiteObject(
       logger.success(`[${name}] pdf → ${filePath ?? "base64"}`);
       return r;
     },
+        human: {
+      set:   (opts: any)              => withTab(t => createHumanAPI(client).set(opts, t)),
+      get:   ()                       => withTab(t => createHumanAPI(client).get(t)),
+      type:  (opts: any)              => withTab(t => createHumanAPI(client).type(opts, t)),
+      click: (opts: any)              => withTab(t => createHumanAPI(client).click(opts, t)),
+    },
+
 
     blockImages:   () => withTab(async t => { await client.blockImages(t);   logger.info(`[${name}] images blocked`); }),
     unblockImages: () => withTab(async t => { await client.unblockImages(t); logger.info(`[${name}] images unblocked`); }),
@@ -278,14 +367,14 @@ export function createSiteObject(
         await withTab(t => client.setCookie(cookieName, value, domain, path, t));
         logger.info(`[${name}] cookie set: ${cookieName} @ ${domain}`);
       },
-      get:    (cookieName: string) => withTab(t => client.getCookie(cookieName, t)),
-      delete: async (cookieName: string) => {
-        await withTab(t => client.deleteCookie(cookieName, t));
+      get: (cookieName: string, domain = "") => withTab(t => client.getCookie(cookieName, domain, t)),
+      delete: async (cookieName: string, domain?: string) => {
+        const d = domain ?? new URL(registeredUrl).hostname;
+        await withTab(t => client.deleteCookie(cookieName, d, t));
         logger.info(`[${name}] cookie deleted: ${cookieName}`);
       },
-      list: () => withTab(t => client.listCookies(t)),
+      list: (domain = "") => withTab(t => client.listCookies(domain, t)),
     },
-
     intercept: {
       block: async (pattern: string) => {
         await withTab(t => client.addInterceptRule("block", pattern, {}, t));
@@ -385,6 +474,16 @@ export function createSiteObject(
         logger.info(`[${name}] intercept rules cleared`);
       },
     },
+    dialog: {
+      accept:        (tabId = "default", text?: string)                     => new DialogClient(client).accept(tabId, text),
+      dismiss:       (tabId = "default")                                    => new DialogClient(client).dismiss(tabId),
+      status:        (tabId = "default")                                    => new DialogClient(client).status(tabId),
+      setAutoAction: (tabId = "default", action: "accept" | "dismiss" | "") => new DialogClient(client).setAutoAction(tabId, action),
+      upload:        (selector: string, filePath: string, tabId = "default") => new DialogClient(client).upload(selector, filePath, tabId),
+      onDialog:      (tabId: string, handler: (data: any) => void)          => new DialogClient(client).onDialog(tabId, handler),
+      waitAndAccept: (tabId = "default", text?: string, timeoutMs = 30000)  => new DialogClient(client).waitAndAccept(tabId, text, timeoutMs),
+      waitAndDismiss:(tabId = "default", timeoutMs = 30000)                 => new DialogClient(client).waitAndDismiss(tabId, timeoutMs),
+    },  
 
     capture: {
       start:    () => withTab(async t => { await client.captureStart(t);  logger.info(`[${name}] capture started`); }),
@@ -396,40 +495,16 @@ export function createSiteObject(
       clear:    () => withTab(async t => { await client.captureClear(t);  logger.info(`[${name}] capture cleared`); }),
     },
 
-    session: {
-      export: async () => {
-        const data = await withTab(t => client.sessionExport(t));
-        logger.success(`[${name}] session exported`);
-        return data;
-      },
-      import: async (data: any) => {
-        await withTab(t => client.sessionImport(data, t));
-        logger.success(`[${name}] session imported`);
-      },
-    },
-
-    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 withTab(t => client.evaluate(js, t));
-      logger.success(`[${name}] exposed and injected: ${fnName}`);
-      return site;
-    },
+        session: {
+    export:  ()        => withTab(t => createSessionAPI(client).export(t)),
+    import:  (data: any) => withTab(t => createSessionAPI(client).import(data, t)),
+    reload:  ()        => withTab(t => createSessionAPI(client).reload(t)),
+    paths:   ()        => createSessionAPI(client).paths(),
+    cookies: { path: () => createSessionAPI(client).cookiesPath() },
+    profile: { path: () => createSessionAPI(client).profilePath() },
+    ws:      { save: (opts: any) => createSessionAPI(client).setWsSave(opts.enabled) },
+    pings:   { save: (opts: any) => createSessionAPI(client).setPingsSave(opts.enabled) },
+  },
 
     store: async (
       data: Record<string, any> | Record<string, any>[],

package/piggy/tabs/index.ts

@@ -8,7 +8,8 @@ export class TabsClient {
     return this.client.send("tab.new", {});
   }
 
-  close(tabId: string): Promise<void> {
+  close(opts: string | { tabId: string }): Promise<void> {
+    const tabId = typeof opts === "string" ? opts : opts.tabId;
     return this.client.send("tab.close", { tabId });
   }
 

package/piggy.ts

@@ -1,4 +1,4 @@
-// piggy.ts
+// piggy.ts — patched: adds single:true + piggy.extend()
 import { detectBinary, type BinaryMode } from "./piggy/launch/detect";
 import { spawnBrowser, killBrowser, spawnBrowserOnSocket } from "./piggy/launch/spawn";
 import { PiggyClient } from "./piggy/client";
@@ -26,12 +26,19 @@ import logger from "./piggy/logger";
 
 type TabMode = "tab" | "process";
 
+// A plugin installer is an async function that receives a site and enriches it.
+type PluginInstaller = (site: SiteObject) => Promise<any>;
+
 let _client: PiggyClient | null = null;
 let _router: PiggyRouter | null = null;
 let _tabMode: TabMode = "tab";
 const _extraProcs: { socket: string; client: PiggyClient }[] = [];
 const _sites: Record<string, SiteObject> = {};
 
+// ── Single-site tracking for extend() ────────────────────────────────────────
+// Only one site may be registered with { single: true } at a time.
+let _singleSiteName: string | null = null;
+
 // ── Internal guard ────────────────────────────────────────────────────────────
 
 function guardClient(): PiggyClient {
@@ -73,37 +80,57 @@ const piggy: any = {
   },
 
   // ── HTTP client (port 2005 direct) ────────────────────────────────────────
-  // Use when you want to talk to the browser over HTTP without a socket client.
   http: (opts: HttpClientOptions) => createHttpClient(opts),
 
   // ── Register ──────────────────────────────────────────────────────────────
   register: async (
     name: string,
     url: string,
-    opts?: { binary?: BinaryMode; pool?: number }
+    opts?: { binary?: BinaryMode; pool?: number; single?: boolean }
   ) => {
     if (!url?.trim()) throw new Error(`No URL for site "${name}"`);
+
     const binaryMode: BinaryMode = opts?.binary ?? "headless";
-    const poolSize = opts?.pool ?? 0;
+    const poolSize   = opts?.pool ?? 0;
+    const isSingle   = opts?.single === true;
+
+    // ── single: true enforcement ───────────────────────────────────────────
+    // A single-site registration uses the default tab and blocks tab.new so
+    // the binary stays strictly single-tab. Only one site may be single.
+    if (isSingle && _singleSiteName && _singleSiteName !== name) {
+      throw new Error(
+        `piggy: site "${_singleSiteName}" is already registered as single. ` +
+        `Only one site may use { single: true } at a time.`
+      );
+    }
 
     if (_tabMode === "tab") {
       const client = guardClient();
 
       if (poolSize > 1) {
+        if (isSingle) throw new Error('piggy: { single: true } is incompatible with pool > 1');
         const pool = new TabPool(client, poolSize, url, name);
         await pool.init();
         const siteObj = createSiteObject(name, url, client, "default", pool);
         _sites[name] = siteObj;
-        piggy[name] = siteObj;
+        piggy[name]  = siteObj;
         logger.success(`[${name}] registered with pool of ${poolSize} tabs`);
       } else {
-        const tabId = await client.newTab();
+        // single: true  →  reuse the default tab, never call newTab()
+        const tabId = isSingle ? "default" : await client.newTab();
         const siteObj = createSiteObject(name, url, client, tabId);
         _sites[name] = siteObj;
-        piggy[name] = siteObj;
-        logger.success(`[${name}] registered as tab ${tabId}`);
+        piggy[name]  = siteObj;
+
+        if (isSingle) {
+          _singleSiteName = name;
+          logger.success(`[${name}] registered as single-tab site (default tab)`);
+        } else {
+          logger.success(`[${name}] registered as tab ${tabId}`);
+        }
       }
     } else {
+      if (isSingle) throw new Error('piggy: { single: true } is only supported in tab mode');
       const socketName = `piggy_${name}`;
       await spawnBrowserOnSocket(socketName, binaryMode);
       await new Promise(r => setTimeout(r, 500));
@@ -112,16 +139,56 @@ const piggy: any = {
       _extraProcs.push({ socket: socketName, client: c });
       const siteObj = createSiteObject(name, url, c, "default");
       _sites[name] = siteObj;
-      piggy[name] = siteObj;
+      piggy[name]  = siteObj;
       logger.success(`[${name}] registered as process on "${socketName}"`);
     }
 
     return piggy;
   },
 
+  // ── extend() — installs plugins onto the single-flagged site ─────────────
+  //
+  // Each installer is an async function returned by a plugin factory, e.g.:
+  //   innerstorage({ path: './wa-storage.json' })   → installer fn
+  //
+  // Usage:
+  //   await piggy.extend(
+  //     innerstorage({ path: './wa-storage.json' }),
+  //     cookiesinject({ cookieFile: './wa-cookies.json' }),
+  //     mediacapture({ downloadDir: './wa-media/' })
+  //   );
+  extend: async (...installers: PluginInstaller[]) => {
+    if (!_singleSiteName) {
+      throw new Error(
+        'piggy.extend() requires a site registered with { single: true }.\n' +
+        'Example: await piggy.register("mysite", url, { single: true })'
+      );
+    }
+    if (installers.length === 0) {
+      logger.warn('[piggy] extend() called with no plugins — nothing to do');
+      return piggy;
+    }
+
+    const site = _sites[_singleSiteName];
+    if (!site) {
+      throw new Error(`piggy.extend(): site "${_singleSiteName}" not found — register it first`);
+    }
+
+    for (const installer of installers) {
+      if (typeof installer !== 'function') {
+        throw new Error('piggy.extend(): each argument must be a plugin installer function');
+      }
+      await installer(site);
+    }
+
+    logger.success(`[piggy] ${installers.length} plugin(s) installed on "${_singleSiteName}"`);
+    return piggy;
+  },
+
   // ── Sub-APIs (1:1 with C++ files, available after launch/connect) ─────────
 
   get tabs()         { return _router?.tabs         ?? createTabsAPI(guardClient()); },
+  get tab()          { return _router?.tabs         ?? createTabsAPI(guardClient()); },
   get navigation()   { return _router?.navigation   ?? createNavigationAPI(guardClient()); },
   get interactions() { return _router?.interactions ?? createInteractionsAPI(guardClient()); },
   get media()        { return _router?.media        ?? createMediaAPI(guardClient()); },
@@ -144,7 +211,7 @@ const piggy: any = {
     return {
       load:     (path: string)                                              => api.load(path),
       fetch:    (url: string)                                               => api.fetch(url),
-      ovpn:     (path: string)                                              => api.ovpn(path),
+      ovpn:     (path: string)                                             => api.ovpn(path),
       set:      (opts: Parameters<typeof api.set>[0])                       => api.set(opts),
       test:     ()                                                          => api.test(),
       testStop: ()                                                          => api.testStop(),
@@ -158,7 +225,7 @@ const piggy: any = {
       rotation: (mode: "none" | "timed" | "perrequest", interval?: number) => api.rotation(mode, interval),
       config:   (opts: { skipDead?: boolean; autoCheck?: boolean })         => api.config(opts),
       save:     (path: string, filter?: "alive" | "dead" | "all")          => api.save(path, filter),
-      on:       (event: string, handler: (data: any) => void)              => guardClient().onProxyEvent(event, handler),
+      on:       (event: string, handler: (data: any) => void)               => guardClient().onProxyEvent(event, handler),
     };
   },
 
@@ -230,6 +297,7 @@ const piggy: any = {
   // ── Shutdown ──────────────────────────────────────────────────────────────
   close: async (opts?: { force?: boolean }) => {
     stopServer();
+    _singleSiteName = null;
     if (opts?.force) {
       for (const { client: c } of _extraProcs) c.disconnect();
       _client?.disconnect();

package/piggy/cache/memory.d.ts

@@ -1,7 +0,0 @@
-export declare function get(key: string): any | null;
-export declare function set(key: string, data: any, ttlMs: number): void;
-export declare function del(key: string): void;
-export declare function clear(): void;
-export declare function size(): number;
-export declare function keys(): string[];
-//# sourceMappingURL=memory.d.ts.map

package/piggy/cache/memory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["memory.ts"],"names":[],"mappings":"AASA,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAQ3C;AAED,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,QAExD;AAED,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,QAE9B;AAED,wBAAgB,KAAK,SAEpB;AAED,wBAAgB,IAAI,WAEnB;AAED,wBAAgB,IAAI,aAEnB"}