diff --git a/README.md b/README.md index 4c430d3..46a4f7f 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@

Node.js - Version - Browser + Version + Browser WebExtension

@@ -41,9 +41,10 @@ This project uses the custom GREED-1 license. It grants permission only to fork - Invalidates references after navigation or relevant DOM updates and returns stale-reference errors for old refs. - Saves screenshots to `~/OpenBrowser/screenshots/.png` or returns Base64 image data. - Includes an extensible browser-adapter architecture covering Firefox-family and Chromium-family browsers. -- Supports Zen (Firefox-based) and Chrome (Chromium-based). -- Lets you set a default browser with `config browser ` so `--browser` is optional. -- Includes a minimal extension logo and uses it as the Firefox extension icon. +- Supports Helium and Chrome (Chromium-based) plus Zen (Firefox-based). +- Detects supported browsers and lets you configure a local default so `--browser` is optional. +- Reports installed, configured, and active browser targets with `browsers`. +- Includes PNG extension icons for Firefox and Chromium-family browsers. - Builds the Firefox extension into a bundled `.xpi` artifact. - Includes a release-signing pipeline for Mozilla unlisted signing with `web-ext sign --channel unlisted`. @@ -51,54 +52,41 @@ This project uses the custom GREED-1 license. It grants permission only to fork - Node.js 20 or newer. - npm access to install or run `@pxlarified/browser`. -- A supported browser: Zen (Firefox-based) or Chrome (Chromium-based). -- For Zen, a Zen profile created on disk. Open Zen once before running the installer. -- For Chrome, Developer mode enabled so the staged extension can be loaded unpacked. +- A supported browser: Helium or Chrome (Chromium-based), or Zen (Firefox-based). +- For Zen, a Zen profile created on disk. Open Zen once before running setup. +- For Helium and Chrome, Developer mode enabled so the staged extension can be loaded unpacked. - For signed Firefox releases, Mozilla Add-ons API credentials. ## Installation -Install the bundled extension and native bridge for a browser. +The recommended first-run setup detects the local browser targets and remembers the one you choose. ```sh -npx @pxlarified/browser install zen -npx @pxlarified/browser install chrome +npx @pxlarified/browser browsers +npx @pxlarified/browser setup helium +# or: setup chrome / setup zen ``` -For Zen (Firefox-family) the installer does the following. +`setup` installs the native bridge and extension for the selected browser. For Zen it copies the Firefox `.xpi` into detected profiles. For Chromium browsers it stages one shared MV3 extension artifact under `~/OpenBrowser/extensions//` and writes the browser-specific native-messaging manifest. -1. Copies the bundled Firefox `.xpi` into detected Zen profiles as `openbrowser@mizius.com.xpi`. -2. Installs the user-scoped native messaging manifest. -3. Installs the native host launcher under `~/OpenBrowser/native-host/`. -4. Replaces an existing staged OpenBrowser extension with the bundled version. +Chromium browsers cannot side-load a packed extension from a profile. After setup, open the browser's extensions page, enable Developer mode, choose "Load unpacked", and select the path reported by setup. Helium and Chrome use the same extension artifact, but keep separate native-host launchers and bridge sockets. -Restart Zen if the extension update does not load immediately. +The setup command stores the selected browser in `~/OpenBrowser/config.json`. Each user has their own selection; no browser preference is stored in the repository. -For Chrome (Chromium-family) the installer does the following. +### Browser selection -1. Installs the native host launcher under `~/OpenBrowser/native-host/`. -2. Writes the Chromium native messaging manifest (using `allowed_origins`) into Chrome's `NativeMessagingHosts` directory. -3. Stages the unpacked extension under `~/OpenBrowser/extensions/chrome/`. - -Chromium browsers cannot side-load a packed extension from a profile, so load the staged extension manually: open `chrome://extensions`, enable Developer mode, choose "Load unpacked", and select `~/OpenBrowser/extensions/chrome/`. The bundled extension ships a fixed `key`, so it always loads with the same extension id that the native messaging manifest allows. - -### Default browser - -Set the browser used when `--browser` is omitted. +Use the friendly `use` command to change the local default: ```sh -npx @pxlarified/browser config browser chrome -npx @pxlarified/browser config browser zen +npx @pxlarified/browser use helium +npx @pxlarified/browser use chrome +npx @pxlarified/browser use zen +npx @pxlarified/browser use auto ``` -Show the current configuration. - -```sh -npx @pxlarified/browser config browser -npx @pxlarified/browser config -``` +`config browser ` remains available as an equivalent configuration command. `auto` uses a configured, ready browser first, then an active browser, then the only detected browser. If the detected browser is not set up, OpenBrowser tells you to run setup. If multiple browsers are possible, OpenBrowser reports the choices instead of silently selecting Zen. -The default is stored in `~/OpenBrowser/config.json`. Resolution order is `--browser`, then the configured default, then Zen. +Selection precedence is `--browser`, `OPENBROWSER_BROWSER`, the configured local browser when setup is complete, an active session, then automatic discovery. Configured daily commands avoid probing unrelated browser bridges. Use `browsers --json` for machine-readable discovery information. ### Agent skill installation @@ -114,38 +102,47 @@ If `--to` points at an agent directory such as `.pi/agent`, OpenBrowser writes ` ## Usage -`--browser ` selects the target browser. It is optional and defaults to the browser set with `config browser`, or Zen when none is configured. +After setup, browser selection is automatic and commands do not need a browser flag. ```sh -npx @pxlarified/browser open https://example.com --browser zen -npx @pxlarified/browser state --browser chrome -npx @pxlarified/browser click e_1 --browser zen +npx @pxlarified/browser open https://example.com +npx @pxlarified/browser state +npx @pxlarified/browser click e_1 +npx @pxlarified/browser screenshot +npx @pxlarified/browser close +``` + +Use `--browser ` when deliberately controlling a specific browser: + +```sh +npx @pxlarified/browser state --browser helium npx @pxlarified/browser screenshot --browser chrome -npx @pxlarified/browser close --browser zen ``` -### Session lifecycle +### Browser status and session lifecycle ```sh -npx @pxlarified/browser install zen -npx @pxlarified/browser open --browser zen -npx @pxlarified/browser close --browser zen -npx @pxlarified/browser status --browser zen +npx @pxlarified/browser browsers +npx @pxlarified/browser browsers --json +npx @pxlarified/browser setup helium +npx @pxlarified/browser open +npx @pxlarified/browser close +npx @pxlarified/browser status ``` ### Navigation ```sh -npx @pxlarified/browser navigate --browser zen -npx @pxlarified/browser reload --browser zen -npx @pxlarified/browser back --browser zen -npx @pxlarified/browser forward --browser zen +npx @pxlarified/browser navigate +npx @pxlarified/browser reload +npx @pxlarified/browser back +npx @pxlarified/browser forward ``` ### Page state ```sh -npx @pxlarified/browser state --browser zen +npx @pxlarified/browser state ``` `state` returns the current URL, page title, viewport information, and actionable elements. @@ -157,8 +154,8 @@ npx @pxlarified/browser state --browser zen ### Screenshots ```sh -npx @pxlarified/browser screenshot --browser zen -npx @pxlarified/browser screenshot --base64 --browser zen +npx @pxlarified/browser screenshot +npx @pxlarified/browser screenshot --base64 ``` `screenshot` saves a PNG file under the user OpenBrowser directory and prints only the absolute file path to stdout. @@ -172,25 +169,25 @@ npx @pxlarified/browser screenshot --base64 --browser zen ### Interaction ```sh -npx @pxlarified/browser click --browser zen -npx @pxlarified/browser keys --browser zen -npx @pxlarified/browser press --browser zen -npx @pxlarified/browser select