@ricsam/r5d-browser 0.0.0 → 0.0.44

package/README.md

@@ -1,45 +1,10 @@
-# @ricsam/r5d-browser
+# r5d-browser
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+`r5d-browser` starts a dedicated, persistent Chromium profile on a Mac and connects it to r5d.dev. Sign in to sites in the opened browser normally; agents use Chromium's automation protocol without moving the real system pointer or taking keyboard focus.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+```sh
+npm install -g @ricsam/r5d-browser
+r5d-browser start
+```
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@ricsam/r5d-browser`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+The profile is stored under `~/.r5d/browser/profile`. Browser screenshots are session artifacts in r5d.dev and are not retained by the browser process.

package/dist/cjs/main.cjs

@@ -0,0 +1,440 @@
+#!/usr/bin/env bun
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_os = __toESM(require("node:os"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_child_process = require("node:child_process");
+var import_promises = require("node:timers/promises");
+var import_ws = __toESM(require("ws"), 1);
+var import_playwright_install = require("./playwright-install.cjs");
+const DEFAULT_BASE_URL = "https://r5d.dev";
+const PACKAGE_NAME = "@ricsam/r5d-browser";
+const RECONNECT_DELAY_MS = 2e3;
+const SERVER_HEARTBEAT_TIMEOUT_MS = 45e3;
+function browserRoot() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".r5d", "browser");
+}
+function defaultConfigPath() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".config", "r5d", "r5dctl", "config.json");
+}
+function printHelp() {
+  process.stdout.write(`Usage:
+  r5d-browser start [--base-url <url>] [--token <token>] [--api-key <key>]
+  r5d-browser install
+  r5d-browser --version
+
+Options:
+  --base-url <url>      r5d.dev base URL (default from r5dctl config or ${DEFAULT_BASE_URL})
+  --token <token>       Interactive r5d token
+  --api-key <key>       r5d API key
+  --config <path>       Shared r5dctl config path
+  --profile <path>      Chromium profile path (default ~/.r5d/browser/profile)
+  --browsers-path <dir> Playwright browser binaries (default ~/.r5d/browser/browsers)
+  -v, --version         Show r5d-browser version
+  -h, --help            Show this help
+`);
+}
+function findVersion() {
+  let current = process.argv[1] ? import_node_path.default.dirname(import_node_path.default.resolve(process.argv[1])) : process.cwd();
+  for (let index = 0; index < 12; index += 1) {
+    try {
+      const parsed = JSON.parse(import_node_fs.default.readFileSync(import_node_path.default.join(current, "package.json"), "utf8"));
+      if (parsed.name === PACKAGE_NAME && parsed.version) return parsed.version;
+    } catch {
+    }
+    try {
+      const sourceVersion = import_node_fs.default.readFileSync(import_node_path.default.join(current, "VERSION.txt"), "utf8").trim();
+      if (sourceVersion && import_node_path.default.basename(current) === "packages") return sourceVersion;
+    } catch {
+    }
+    const parent = import_node_path.default.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return "unknown";
+}
+function parseArgs(argv) {
+  const options = { configPath: defaultConfigPath(), help: false, version: false };
+  const rest = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) continue;
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "-v" || arg === "--version") {
+      options.version = true;
+      continue;
+    }
+    const readOption = (name) => {
+      if (arg === name) {
+        index += 1;
+        const value = argv[index];
+        if (!value) throw new Error(`Missing value for ${name}`);
+        return value;
+      }
+      return arg.startsWith(`${name}=`) ? arg.slice(name.length + 1) : void 0;
+    };
+    const entries = [
+      ["--base-url", "baseUrl"],
+      ["--token", "token"],
+      ["--api-key", "apiKey"],
+      ["--config", "configPath"],
+      ["--profile", "profilePath"],
+      ["--browsers-path", "browsersPath"]
+    ];
+    let matched = false;
+    for (const [name, key] of entries) {
+      const value = readOption(name);
+      if (value !== void 0) {
+        options[key] = value;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) rest.push(arg);
+  }
+  if (options.version) return { command: "version", options };
+  if (options.help || rest.length === 0) return { command: "help", options };
+  if (rest[0] !== "start" && rest[0] !== "install") throw new Error(`Unknown command: ${rest[0]}`);
+  return { command: rest[0], options };
+}
+function readConfig(configPath) {
+  if (!import_node_fs.default.existsSync(configPath)) return {};
+  const parsed = JSON.parse(import_node_fs.default.readFileSync(configPath, "utf8"));
+  return {
+    baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
+    token: typeof parsed.token === "string" ? parsed.token : void 0,
+    apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0
+  };
+}
+function resolveConnection(options) {
+  const config = readConfig(options.configPath);
+  const token = options.token ?? process.env.R5D_BROWSER_TOKEN ?? process.env.R5D_TOKEN ?? process.env.R5DCTL_TOKEN ?? config.token ?? options.apiKey ?? process.env.R5D_API_KEY ?? process.env.R5DCTL_API_KEY ?? config.apiKey;
+  if (!token) throw new Error("Authentication required. Run `r5dctl auth login` or pass --token/--api-key.");
+  return {
+    baseUrl: (options.baseUrl ?? process.env.R5D_BASE_URL ?? process.env.R5DCTL_BASE_URL ?? config.baseUrl ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    ),
+    token
+  };
+}
+function installChromium(browsersPath) {
+  import_node_fs.default.mkdirSync(browsersPath, { recursive: true });
+  process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  const cliPath = (0, import_playwright_install.resolvePlaywrightCliPath)();
+  process.stdout.write(`[r5d-browser] Installing Chromium under ${browsersPath}...
+`);
+  const result = (0, import_node_child_process.spawnSync)(process.execPath, [cliPath, "install", "chromium"], {
+    stdio: "inherit",
+    env: { ...process.env, PLAYWRIGHT_BROWSERS_PATH: browsersPath }
+  });
+  if (result.status !== 0) throw new Error(`Chromium installation failed with exit code ${result.status ?? "unknown"}.`);
+}
+function loadInstanceId() {
+  const instancePath = import_node_path.default.join(browserRoot(), "instance-id");
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(instancePath), { recursive: true });
+  try {
+    const id2 = import_node_fs.default.readFileSync(instancePath, "utf8").trim();
+    if (id2) return id2;
+  } catch {
+  }
+  const id = crypto.randomUUID();
+  import_node_fs.default.writeFileSync(instancePath, `${id}
+`, { mode: 384 });
+  return id;
+}
+class BrowserRuntime {
+  constructor(context) {
+    this.context = context;
+    for (const page of context.pages()) this.track(page);
+    context.on("page", (page) => this.track(page));
+  }
+  context;
+  ids = /* @__PURE__ */ new WeakMap();
+  pages = /* @__PURE__ */ new Map();
+  cursor = /* @__PURE__ */ new Map();
+  track(page) {
+    const existing = this.ids.get(page);
+    if (existing) return existing;
+    const id = crypto.randomUUID();
+    this.ids.set(page, id);
+    this.pages.set(id, page);
+    page.once("close", () => {
+      this.pages.delete(id);
+      this.cursor.delete(id);
+    });
+    return id;
+  }
+  page(tabId) {
+    if (typeof tabId !== "string") throw new Error("tabId is required.");
+    const page = this.pages.get(tabId);
+    if (!page || page.isClosed()) throw new Error(`Browser tab ${tabId} is no longer open.`);
+    return page;
+  }
+  async tabInfo(page) {
+    const tabId = this.track(page);
+    let windowId = "unknown";
+    try {
+      const cdp = await this.context.newCDPSession(page);
+      const result = await cdp.send("Browser.getWindowForTarget");
+      windowId = String(result.windowId);
+      await cdp.detach();
+    } catch {
+    }
+    return { tabId, windowId, title: await page.title().catch(() => ""), url: page.url() };
+  }
+  async listTabs() {
+    return await Promise.all([...this.pages.values()].filter((page) => !page.isClosed()).map((page) => this.tabInfo(page)));
+  }
+  async execute(action, input) {
+    if (action === "list_tabs") return { tabs: await this.listTabs() };
+    if (action === "open_tab") {
+      const previous = this.context.pages().findLast((candidate) => !candidate.isClosed());
+      let page2;
+      if (previous) {
+        const cdp = await this.context.newCDPSession(previous);
+        const pagePromise = this.context.waitForEvent("page");
+        await cdp.send("Target.createTarget", {
+          url: "about:blank",
+          newWindow: input.disposition === "window",
+          background: true
+        });
+        page2 = await pagePromise;
+        await cdp.detach();
+        if (input.disposition === "window") {
+          const pageCdp = await this.context.newCDPSession(page2);
+          const { windowId } = await pageCdp.send("Browser.getWindowForTarget");
+          await pageCdp.send("Browser.setWindowBounds", { windowId, bounds: { windowState: "minimized" } });
+          await pageCdp.detach();
+        }
+      } else {
+        page2 = await this.context.newPage();
+      }
+      const url = typeof input.url === "string" ? input.url : "about:blank";
+      if (url !== "about:blank") await page2.goto(url, { waitUntil: "domcontentloaded" });
+      return { tab: await this.tabInfo(page2) };
+    }
+    const page = this.page(input.tabId);
+    const tabId = input.tabId;
+    switch (action) {
+      case "close_tab":
+        await page.close();
+        return { closed: true, tabId };
+      case "navigate":
+        await page.goto(String(input.url), { waitUntil: "domcontentloaded" });
+        return { tab: await this.tabInfo(page) };
+      case "screenshot": {
+        const bytes = await page.screenshot({ type: "png" });
+        const viewport = page.viewportSize();
+        const cursor = this.cursor.get(tabId);
+        return {
+          base64: bytes.toString("base64"),
+          width: viewport?.width ?? Number(await page.evaluate(() => window.innerWidth)),
+          height: viewport?.height ?? Number(await page.evaluate(() => window.innerHeight)),
+          cursorX: cursor?.x,
+          cursorY: cursor?.y
+        };
+      }
+      case "move_mouse": {
+        const x = Number(input.x);
+        const y = Number(input.y);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error("move_mouse requires numeric x and y coordinates.");
+        await page.mouse.move(x, y);
+        this.cursor.set(tabId, { x, y });
+        return { tabId, x, y };
+      }
+      case "mouse_click": {
+        const cursor = this.cursor.get(tabId);
+        if (!cursor) throw new Error("Move the mouse in this tab before clicking.");
+        const button = input.button === "middle" || input.button === "right" ? input.button : "left";
+        await page.mouse.click(cursor.x, cursor.y, { button, clickCount: input.clickCount === 2 ? 2 : 1 });
+        return { tabId, ...cursor, button };
+      }
+      case "keyboard": {
+        const keys = Array.isArray(input.keys) ? input.keys : [];
+        const modifiers = Array.isArray(input.modifiers) ? input.modifiers.filter((value) => typeof value === "string") : [];
+        for (const modifier of modifiers) await page.keyboard.down(modifier);
+        try {
+          for (const key of keys) {
+            if (typeof key !== "string") throw new Error("keyboard keys must all be strings.");
+            await page.keyboard.press(key);
+          }
+        } finally {
+          for (const modifier of modifiers.toReversed()) await page.keyboard.up(modifier);
+        }
+        return { tabId, keys, modifiers };
+      }
+      case "keyboard_type":
+        if (typeof input.text !== "string") throw new Error("keyboard_type requires text.");
+        await page.keyboard.insertText(input.text);
+        return { tabId, characters: input.text.length };
+      case "run_js": {
+        if (typeof input.code !== "string") throw new Error("run_js requires code.");
+        const result = await page.evaluate(async (code) => {
+          const invoke = new Function(`"use strict"; return (async () => {
+${code}
+})()`);
+          return await invoke();
+        }, input.code);
+        const serialized = JSON.stringify(result);
+        if (serialized && Buffer.byteLength(serialized) > 1024 * 1024) {
+          throw new Error("Browser JavaScript result exceeded the 1 MiB limit.");
+        }
+        return { tabId, result };
+      }
+      default:
+        throw new Error(`Unsupported browser operation: ${action}`);
+    }
+  }
+}
+async function connectLoop(params) {
+  for (; ; ) {
+    const url = new URL("/browser/ws", params.baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("instance", params.instanceId);
+    url.searchParams.set("version", findVersion());
+    let socket = null;
+    try {
+      socket = new import_ws.default(url, { headers: { Authorization: `Bearer ${params.token}` } });
+      await new Promise((resolve, reject) => {
+        socket.addEventListener("open", () => resolve(), { once: true });
+        socket.addEventListener("error", () => reject(new Error("WebSocket connection failed.")), { once: true });
+      });
+      process.stdout.write(`[r5d-browser] connected to ${params.baseUrl}
+`);
+      socket.send(
+        JSON.stringify({
+          type: "hello",
+          hostInfo: {
+            hostname: import_node_os.default.hostname(),
+            platform: process.platform,
+            arch: process.arch,
+            version: findVersion(),
+            chromiumVersion: params.chromiumVersion,
+            profilePath: params.profilePath
+          },
+          tabs: await params.runtime.listTabs()
+        })
+      );
+      let lastServerMessageAt = Date.now();
+      const watchdog = setInterval(() => {
+        if (Date.now() - lastServerMessageAt >= SERVER_HEARTBEAT_TIMEOUT_MS) socket?.close();
+      }, 5e3);
+      await new Promise((resolve) => {
+        socket.addEventListener("message", (event) => {
+          lastServerMessageAt = Date.now();
+          void (async () => {
+            const message = JSON.parse(String(event.data));
+            if (message.type === "ping") {
+              socket?.send(JSON.stringify({ type: "pong" }));
+              return;
+            }
+            if (message.type !== "operation") return;
+            try {
+              const beforeTabs = await params.runtime.listTabs();
+              const operationResult = await params.runtime.execute(message.action, message.input);
+              const tabs = await params.runtime.listTabs();
+              const beforeIds = new Set(beforeTabs.map((tab) => tab.tabId));
+              const openedTabs = tabs.filter((tab) => !beforeIds.has(tab.tabId));
+              const result = operationResult && typeof operationResult === "object" ? { ...operationResult, openedTabs } : { result: operationResult, openedTabs };
+              socket?.send(JSON.stringify({ type: "operation_result", requestId: message.requestId, result }));
+              socket?.send(JSON.stringify({ type: "tabs_snapshot", tabs }));
+            } catch (error) {
+              socket?.send(
+                JSON.stringify({
+                  type: "operation_result",
+                  requestId: message.requestId,
+                  error: error instanceof Error ? error.message : String(error)
+                })
+              );
+            }
+          })();
+        });
+        socket.addEventListener("close", () => resolve(), { once: true });
+      });
+      clearInterval(watchdog);
+    } catch (error) {
+      process.stderr.write(`[r5d-browser] ${error instanceof Error ? error.message : String(error)}
+`);
+    } finally {
+      socket?.close();
+    }
+    process.stdout.write(`[r5d-browser] disconnected; reconnecting...
+`);
+    await (0, import_promises.setTimeout)(RECONNECT_DELAY_MS);
+  }
+}
+async function start(options) {
+  if (process.platform !== "darwin") throw new Error("r5d-browser currently supports macOS only.");
+  const { baseUrl, token } = resolveConnection(options);
+  const browsersPath = import_node_path.default.resolve(options.browsersPath ?? import_node_path.default.join(browserRoot(), "browsers"));
+  const profilePath = import_node_path.default.resolve(options.profilePath ?? import_node_path.default.join(browserRoot(), "profile"));
+  process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  let playwright = await import("playwright");
+  if (!import_node_fs.default.existsSync(playwright.chromium.executablePath())) {
+    installChromium(browsersPath);
+    playwright = await import("playwright");
+  }
+  import_node_fs.default.mkdirSync(profilePath, { recursive: true });
+  const context = await playwright.chromium.launchPersistentContext(profilePath, {
+    headless: false,
+    viewport: { width: 1440, height: 900 },
+    acceptDownloads: true,
+    downloadsPath: import_node_path.default.join(browserRoot(), "downloads")
+  });
+  if (context.pages().length === 0) await context.newPage();
+  const runtime = new BrowserRuntime(context);
+  process.stdout.write(`[r5d-browser] profile: ${profilePath}
+`);
+  process.stdout.write(`[r5d-browser] agents use synthetic Chromium input; your system pointer and keyboard stay untouched.
+`);
+  process.on("SIGINT", () => void context.close().finally(() => process.exit(0)));
+  process.on("SIGTERM", () => void context.close().finally(() => process.exit(0)));
+  return connectLoop({
+    runtime,
+    baseUrl,
+    token,
+    instanceId: loadInstanceId(),
+    profilePath,
+    chromiumVersion: context.browser()?.version() ?? "unknown"
+  });
+}
+async function main() {
+  const { command, options } = parseArgs(process.argv.slice(2));
+  if (command === "help") return printHelp();
+  if (command === "version") return void process.stdout.write(`r5d-browser ${findVersion()}
+`);
+  const browsersPath = import_node_path.default.resolve(options.browsersPath ?? import_node_path.default.join(browserRoot(), "browsers"));
+  if (command === "install") return installChromium(browsersPath);
+  await start(options);
+}
+main().catch((error) => {
+  process.stderr.write(`r5d-browser: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});

package/dist/cjs/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@ricsam/r5d-browser",
+  "version": "0.0.44",
+  "type": "commonjs"
+}

package/dist/cjs/playwright-install.cjs

@@ -0,0 +1,49 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var playwright_install_exports = {};
+__export(playwright_install_exports, {
+  resolvePlaywrightCliPath: () => resolvePlaywrightCliPath
+});
+module.exports = __toCommonJS(playwright_install_exports);
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_module = require("node:module");
+function resolvePlaywrightCliPath(fromPath = process.argv[1] ?? import_node_path.default.join(process.cwd(), "package.json")) {
+  const require2 = (0, import_node_module.createRequire)(fromPath);
+  const packageJsonPath = require2.resolve("playwright/package.json");
+  const cliPath = import_node_path.default.join(import_node_path.default.dirname(packageJsonPath), "cli.js");
+  if (!import_node_fs.default.existsSync(cliPath)) {
+    throw new Error(`The Playwright CLI was not found next to ${packageJsonPath}. Reinstall @ricsam/r5d-browser.`);
+  }
+  return cliPath;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  resolvePlaywrightCliPath
+});

package/dist/mjs/main.mjs

@@ -0,0 +1,417 @@
+#!/usr/bin/env bun
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+import WebSocket from "ws";
+import { resolvePlaywrightCliPath } from "./playwright-install.mjs";
+const DEFAULT_BASE_URL = "https://r5d.dev";
+const PACKAGE_NAME = "@ricsam/r5d-browser";
+const RECONNECT_DELAY_MS = 2e3;
+const SERVER_HEARTBEAT_TIMEOUT_MS = 45e3;
+function browserRoot() {
+  return path.join(os.homedir(), ".r5d", "browser");
+}
+function defaultConfigPath() {
+  return path.join(os.homedir(), ".config", "r5d", "r5dctl", "config.json");
+}
+function printHelp() {
+  process.stdout.write(`Usage:
+  r5d-browser start [--base-url <url>] [--token <token>] [--api-key <key>]
+  r5d-browser install
+  r5d-browser --version
+
+Options:
+  --base-url <url>      r5d.dev base URL (default from r5dctl config or ${DEFAULT_BASE_URL})
+  --token <token>       Interactive r5d token
+  --api-key <key>       r5d API key
+  --config <path>       Shared r5dctl config path
+  --profile <path>      Chromium profile path (default ~/.r5d/browser/profile)
+  --browsers-path <dir> Playwright browser binaries (default ~/.r5d/browser/browsers)
+  -v, --version         Show r5d-browser version
+  -h, --help            Show this help
+`);
+}
+function findVersion() {
+  let current = process.argv[1] ? path.dirname(path.resolve(process.argv[1])) : process.cwd();
+  for (let index = 0; index < 12; index += 1) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(path.join(current, "package.json"), "utf8"));
+      if (parsed.name === PACKAGE_NAME && parsed.version) return parsed.version;
+    } catch {
+    }
+    try {
+      const sourceVersion = fs.readFileSync(path.join(current, "VERSION.txt"), "utf8").trim();
+      if (sourceVersion && path.basename(current) === "packages") return sourceVersion;
+    } catch {
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return "unknown";
+}
+function parseArgs(argv) {
+  const options = { configPath: defaultConfigPath(), help: false, version: false };
+  const rest = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg) continue;
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+      continue;
+    }
+    if (arg === "-v" || arg === "--version") {
+      options.version = true;
+      continue;
+    }
+    const readOption = (name) => {
+      if (arg === name) {
+        index += 1;
+        const value = argv[index];
+        if (!value) throw new Error(`Missing value for ${name}`);
+        return value;
+      }
+      return arg.startsWith(`${name}=`) ? arg.slice(name.length + 1) : void 0;
+    };
+    const entries = [
+      ["--base-url", "baseUrl"],
+      ["--token", "token"],
+      ["--api-key", "apiKey"],
+      ["--config", "configPath"],
+      ["--profile", "profilePath"],
+      ["--browsers-path", "browsersPath"]
+    ];
+    let matched = false;
+    for (const [name, key] of entries) {
+      const value = readOption(name);
+      if (value !== void 0) {
+        options[key] = value;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) rest.push(arg);
+  }
+  if (options.version) return { command: "version", options };
+  if (options.help || rest.length === 0) return { command: "help", options };
+  if (rest[0] !== "start" && rest[0] !== "install") throw new Error(`Unknown command: ${rest[0]}`);
+  return { command: rest[0], options };
+}
+function readConfig(configPath) {
+  if (!fs.existsSync(configPath)) return {};
+  const parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  return {
+    baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
+    token: typeof parsed.token === "string" ? parsed.token : void 0,
+    apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0
+  };
+}
+function resolveConnection(options) {
+  const config = readConfig(options.configPath);
+  const token = options.token ?? process.env.R5D_BROWSER_TOKEN ?? process.env.R5D_TOKEN ?? process.env.R5DCTL_TOKEN ?? config.token ?? options.apiKey ?? process.env.R5D_API_KEY ?? process.env.R5DCTL_API_KEY ?? config.apiKey;
+  if (!token) throw new Error("Authentication required. Run `r5dctl auth login` or pass --token/--api-key.");
+  return {
+    baseUrl: (options.baseUrl ?? process.env.R5D_BASE_URL ?? process.env.R5DCTL_BASE_URL ?? config.baseUrl ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    ),
+    token
+  };
+}
+function installChromium(browsersPath) {
+  fs.mkdirSync(browsersPath, { recursive: true });
+  process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  const cliPath = resolvePlaywrightCliPath();
+  process.stdout.write(`[r5d-browser] Installing Chromium under ${browsersPath}...
+`);
+  const result = spawnSync(process.execPath, [cliPath, "install", "chromium"], {
+    stdio: "inherit",
+    env: { ...process.env, PLAYWRIGHT_BROWSERS_PATH: browsersPath }
+  });
+  if (result.status !== 0) throw new Error(`Chromium installation failed with exit code ${result.status ?? "unknown"}.`);
+}
+function loadInstanceId() {
+  const instancePath = path.join(browserRoot(), "instance-id");
+  fs.mkdirSync(path.dirname(instancePath), { recursive: true });
+  try {
+    const id2 = fs.readFileSync(instancePath, "utf8").trim();
+    if (id2) return id2;
+  } catch {
+  }
+  const id = crypto.randomUUID();
+  fs.writeFileSync(instancePath, `${id}
+`, { mode: 384 });
+  return id;
+}
+class BrowserRuntime {
+  constructor(context) {
+    this.context = context;
+    for (const page of context.pages()) this.track(page);
+    context.on("page", (page) => this.track(page));
+  }
+  context;
+  ids = /* @__PURE__ */ new WeakMap();
+  pages = /* @__PURE__ */ new Map();
+  cursor = /* @__PURE__ */ new Map();
+  track(page) {
+    const existing = this.ids.get(page);
+    if (existing) return existing;
+    const id = crypto.randomUUID();
+    this.ids.set(page, id);
+    this.pages.set(id, page);
+    page.once("close", () => {
+      this.pages.delete(id);
+      this.cursor.delete(id);
+    });
+    return id;
+  }
+  page(tabId) {
+    if (typeof tabId !== "string") throw new Error("tabId is required.");
+    const page = this.pages.get(tabId);
+    if (!page || page.isClosed()) throw new Error(`Browser tab ${tabId} is no longer open.`);
+    return page;
+  }
+  async tabInfo(page) {
+    const tabId = this.track(page);
+    let windowId = "unknown";
+    try {
+      const cdp = await this.context.newCDPSession(page);
+      const result = await cdp.send("Browser.getWindowForTarget");
+      windowId = String(result.windowId);
+      await cdp.detach();
+    } catch {
+    }
+    return { tabId, windowId, title: await page.title().catch(() => ""), url: page.url() };
+  }
+  async listTabs() {
+    return await Promise.all([...this.pages.values()].filter((page) => !page.isClosed()).map((page) => this.tabInfo(page)));
+  }
+  async execute(action, input) {
+    if (action === "list_tabs") return { tabs: await this.listTabs() };
+    if (action === "open_tab") {
+      const previous = this.context.pages().findLast((candidate) => !candidate.isClosed());
+      let page2;
+      if (previous) {
+        const cdp = await this.context.newCDPSession(previous);
+        const pagePromise = this.context.waitForEvent("page");
+        await cdp.send("Target.createTarget", {
+          url: "about:blank",
+          newWindow: input.disposition === "window",
+          background: true
+        });
+        page2 = await pagePromise;
+        await cdp.detach();
+        if (input.disposition === "window") {
+          const pageCdp = await this.context.newCDPSession(page2);
+          const { windowId } = await pageCdp.send("Browser.getWindowForTarget");
+          await pageCdp.send("Browser.setWindowBounds", { windowId, bounds: { windowState: "minimized" } });
+          await pageCdp.detach();
+        }
+      } else {
+        page2 = await this.context.newPage();
+      }
+      const url = typeof input.url === "string" ? input.url : "about:blank";
+      if (url !== "about:blank") await page2.goto(url, { waitUntil: "domcontentloaded" });
+      return { tab: await this.tabInfo(page2) };
+    }
+    const page = this.page(input.tabId);
+    const tabId = input.tabId;
+    switch (action) {
+      case "close_tab":
+        await page.close();
+        return { closed: true, tabId };
+      case "navigate":
+        await page.goto(String(input.url), { waitUntil: "domcontentloaded" });
+        return { tab: await this.tabInfo(page) };
+      case "screenshot": {
+        const bytes = await page.screenshot({ type: "png" });
+        const viewport = page.viewportSize();
+        const cursor = this.cursor.get(tabId);
+        return {
+          base64: bytes.toString("base64"),
+          width: viewport?.width ?? Number(await page.evaluate(() => window.innerWidth)),
+          height: viewport?.height ?? Number(await page.evaluate(() => window.innerHeight)),
+          cursorX: cursor?.x,
+          cursorY: cursor?.y
+        };
+      }
+      case "move_mouse": {
+        const x = Number(input.x);
+        const y = Number(input.y);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error("move_mouse requires numeric x and y coordinates.");
+        await page.mouse.move(x, y);
+        this.cursor.set(tabId, { x, y });
+        return { tabId, x, y };
+      }
+      case "mouse_click": {
+        const cursor = this.cursor.get(tabId);
+        if (!cursor) throw new Error("Move the mouse in this tab before clicking.");
+        const button = input.button === "middle" || input.button === "right" ? input.button : "left";
+        await page.mouse.click(cursor.x, cursor.y, { button, clickCount: input.clickCount === 2 ? 2 : 1 });
+        return { tabId, ...cursor, button };
+      }
+      case "keyboard": {
+        const keys = Array.isArray(input.keys) ? input.keys : [];
+        const modifiers = Array.isArray(input.modifiers) ? input.modifiers.filter((value) => typeof value === "string") : [];
+        for (const modifier of modifiers) await page.keyboard.down(modifier);
+        try {
+          for (const key of keys) {
+            if (typeof key !== "string") throw new Error("keyboard keys must all be strings.");
+            await page.keyboard.press(key);
+          }
+        } finally {
+          for (const modifier of modifiers.toReversed()) await page.keyboard.up(modifier);
+        }
+        return { tabId, keys, modifiers };
+      }
+      case "keyboard_type":
+        if (typeof input.text !== "string") throw new Error("keyboard_type requires text.");
+        await page.keyboard.insertText(input.text);
+        return { tabId, characters: input.text.length };
+      case "run_js": {
+        if (typeof input.code !== "string") throw new Error("run_js requires code.");
+        const result = await page.evaluate(async (code) => {
+          const invoke = new Function(`"use strict"; return (async () => {
+${code}
+})()`);
+          return await invoke();
+        }, input.code);
+        const serialized = JSON.stringify(result);
+        if (serialized && Buffer.byteLength(serialized) > 1024 * 1024) {
+          throw new Error("Browser JavaScript result exceeded the 1 MiB limit.");
+        }
+        return { tabId, result };
+      }
+      default:
+        throw new Error(`Unsupported browser operation: ${action}`);
+    }
+  }
+}
+async function connectLoop(params) {
+  for (; ; ) {
+    const url = new URL("/browser/ws", params.baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("instance", params.instanceId);
+    url.searchParams.set("version", findVersion());
+    let socket = null;
+    try {
+      socket = new WebSocket(url, { headers: { Authorization: `Bearer ${params.token}` } });
+      await new Promise((resolve, reject) => {
+        socket.addEventListener("open", () => resolve(), { once: true });
+        socket.addEventListener("error", () => reject(new Error("WebSocket connection failed.")), { once: true });
+      });
+      process.stdout.write(`[r5d-browser] connected to ${params.baseUrl}
+`);
+      socket.send(
+        JSON.stringify({
+          type: "hello",
+          hostInfo: {
+            hostname: os.hostname(),
+            platform: process.platform,
+            arch: process.arch,
+            version: findVersion(),
+            chromiumVersion: params.chromiumVersion,
+            profilePath: params.profilePath
+          },
+          tabs: await params.runtime.listTabs()
+        })
+      );
+      let lastServerMessageAt = Date.now();
+      const watchdog = setInterval(() => {
+        if (Date.now() - lastServerMessageAt >= SERVER_HEARTBEAT_TIMEOUT_MS) socket?.close();
+      }, 5e3);
+      await new Promise((resolve) => {
+        socket.addEventListener("message", (event) => {
+          lastServerMessageAt = Date.now();
+          void (async () => {
+            const message = JSON.parse(String(event.data));
+            if (message.type === "ping") {
+              socket?.send(JSON.stringify({ type: "pong" }));
+              return;
+            }
+            if (message.type !== "operation") return;
+            try {
+              const beforeTabs = await params.runtime.listTabs();
+              const operationResult = await params.runtime.execute(message.action, message.input);
+              const tabs = await params.runtime.listTabs();
+              const beforeIds = new Set(beforeTabs.map((tab) => tab.tabId));
+              const openedTabs = tabs.filter((tab) => !beforeIds.has(tab.tabId));
+              const result = operationResult && typeof operationResult === "object" ? { ...operationResult, openedTabs } : { result: operationResult, openedTabs };
+              socket?.send(JSON.stringify({ type: "operation_result", requestId: message.requestId, result }));
+              socket?.send(JSON.stringify({ type: "tabs_snapshot", tabs }));
+            } catch (error) {
+              socket?.send(
+                JSON.stringify({
+                  type: "operation_result",
+                  requestId: message.requestId,
+                  error: error instanceof Error ? error.message : String(error)
+                })
+              );
+            }
+          })();
+        });
+        socket.addEventListener("close", () => resolve(), { once: true });
+      });
+      clearInterval(watchdog);
+    } catch (error) {
+      process.stderr.write(`[r5d-browser] ${error instanceof Error ? error.message : String(error)}
+`);
+    } finally {
+      socket?.close();
+    }
+    process.stdout.write(`[r5d-browser] disconnected; reconnecting...
+`);
+    await sleep(RECONNECT_DELAY_MS);
+  }
+}
+async function start(options) {
+  if (process.platform !== "darwin") throw new Error("r5d-browser currently supports macOS only.");
+  const { baseUrl, token } = resolveConnection(options);
+  const browsersPath = path.resolve(options.browsersPath ?? path.join(browserRoot(), "browsers"));
+  const profilePath = path.resolve(options.profilePath ?? path.join(browserRoot(), "profile"));
+  process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
+  let playwright = await import("playwright");
+  if (!fs.existsSync(playwright.chromium.executablePath())) {
+    installChromium(browsersPath);
+    playwright = await import("playwright");
+  }
+  fs.mkdirSync(profilePath, { recursive: true });
+  const context = await playwright.chromium.launchPersistentContext(profilePath, {
+    headless: false,
+    viewport: { width: 1440, height: 900 },
+    acceptDownloads: true,
+    downloadsPath: path.join(browserRoot(), "downloads")
+  });
+  if (context.pages().length === 0) await context.newPage();
+  const runtime = new BrowserRuntime(context);
+  process.stdout.write(`[r5d-browser] profile: ${profilePath}
+`);
+  process.stdout.write(`[r5d-browser] agents use synthetic Chromium input; your system pointer and keyboard stay untouched.
+`);
+  process.on("SIGINT", () => void context.close().finally(() => process.exit(0)));
+  process.on("SIGTERM", () => void context.close().finally(() => process.exit(0)));
+  return connectLoop({
+    runtime,
+    baseUrl,
+    token,
+    instanceId: loadInstanceId(),
+    profilePath,
+    chromiumVersion: context.browser()?.version() ?? "unknown"
+  });
+}
+async function main() {
+  const { command, options } = parseArgs(process.argv.slice(2));
+  if (command === "help") return printHelp();
+  if (command === "version") return void process.stdout.write(`r5d-browser ${findVersion()}
+`);
+  const browsersPath = path.resolve(options.browsersPath ?? path.join(browserRoot(), "browsers"));
+  if (command === "install") return installChromium(browsersPath);
+  await start(options);
+}
+main().catch((error) => {
+  process.stderr.write(`r5d-browser: ${error instanceof Error ? error.message : String(error)}
+`);
+  process.exit(1);
+});

package/dist/mjs/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@ricsam/r5d-browser",
+  "version": "0.0.44",
+  "type": "module"
+}

package/dist/mjs/playwright-install.mjs

@@ -0,0 +1,15 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+function resolvePlaywrightCliPath(fromPath = process.argv[1] ?? path.join(process.cwd(), "package.json")) {
+  const require2 = createRequire(fromPath);
+  const packageJsonPath = require2.resolve("playwright/package.json");
+  const cliPath = path.join(path.dirname(packageJsonPath), "cli.js");
+  if (!fs.existsSync(cliPath)) {
+    throw new Error(`The Playwright CLI was not found next to ${packageJsonPath}. Reinstall @ricsam/r5d-browser.`);
+  }
+  return cliPath;
+}
+export {
+  resolvePlaywrightCliPath
+};

package/dist/types/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/types/playwright-install.d.ts

@@ -0,0 +1 @@
+export declare function resolvePlaywrightCliPath(fromPath?: string): string;

package/package.json

@@ -1,10 +1,39 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.0",
-  "description": "OIDC trusted publishing setup package for @ricsam/r5d-browser",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+  "version": "0.0.44",
+  "type": "module",
+  "main": "./dist/cjs/main.cjs",
+  "module": "./dist/mjs/main.mjs",
+  "types": "./dist/types/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/main.d.ts",
+      "import": "./dist/mjs/main.mjs",
+      "require": "./dist/cjs/main.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/r5d-dev.git",
+    "directory": "packages/r5d-browser"
+  },
+  "bin": {
+    "r5d-browser": "dist/cjs/main.cjs"
+  },
+  "dependencies": {
+    "playwright": "1.62.1",
+    "ws": "^8.18.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.0",
+    "node": ">=18"
+  },
+  "sideEffects": false
 }