@pxlarified/browser 0.1.0 → 1.9.4

package/README.md

@@ -1,151 +1,232 @@
-# OpenBrowser
+<h1 align="center">
+  <br>
+  OpenBrowser
+  <br>
+</h1>
 
-OpenBrowser is a minimal browser-control skill and CLI. It controls one browser tab that it creates and owns, using a browser extension plus a local, user-scoped native bridge.
+<h4 align="center">A minimal local browser-control CLI and agent skill that drives one owned browser tab through a WebExtension bridge.</h4>
 
-The npm package is intended to be published as `@pxlarified/browser` and used with:
+<p align="center">
+  <img alt="Node.js" src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white">
+  <img alt="Version" src="https://img.shields.io/badge/version-1.9.4-blue?style=flat-square">
+  <img alt="Browser" src="https://img.shields.io/badge/browser-Zen-7F52FF?style=flat-square">
+  <img alt="Firefox Extension" src="https://img.shields.io/badge/Firefox-WebExtension-FF7139?style=flat-square&logo=firefoxbrowser&logoColor=white">
+</p>
 
-```bash
-npx @pxlarified/browser <command>
-```
-
-The OpenBrowser skill lives in `skills/OpenBrowser/` and is not included as an npm-published skill package.
+## Overview
 
-## Status
+OpenBrowser is a JavaScript browser-control package for local automation. It provides a CLI named `OpenBrowser`, a browser extension, and a user-scoped native bridge so tools and agents can control a single browser tab without exposing a public browser-control server.
 
-- Initial browser support: Zen, a Firefox-based browser.
-- Extension artifact for Firefox-based browsers: `.xpi`.
-- Chromium support is intentionally adapter-ready but not implemented yet.
-- The default build creates an unsigned development `.xpi`.
-- Firefox release signing is implemented as a separate `web-ext sign --channel unlisted` step.
+OpenBrowser is intentionally conservative. Each supported browser may have at most one active OpenBrowser session, and that session is exactly one tab created and owned by OpenBrowser. It never closes, reuses, inspects, navigates, or modifies tabs opened manually by the user.
 
-## Security model
+The npm package is published as `@pxlarified/browser` and is intended to be used through `npx`.
 
-The CLI does not expose browser control through a public network service. The extension talks to a native messaging host, and the CLI talks to that host through a user-scoped local bridge:
+```sh
+npx @pxlarified/browser <command>
+```
 
-- Unix/macOS: `~/OpenBrowser/bridge/<browser>.sock` with user-only permissions.
-- Windows: a user-local named pipe.
+The local agent skill lives in `skills/OpenBrowser/` and is not published as a separate npm skill package.
 
-## Session model
+## Features
 
-Each supported browser may have at most one active OpenBrowser session.
+- Provides a minimal `OpenBrowser` CLI for browser session lifecycle, navigation, inspection, screenshots, scrolling, and interaction.
+- Controls exactly one OpenBrowser-owned tab per supported browser.
+- Tracks the owned browser tab ID in extension storage and automatically clears the session if the user closes the tab.
+- Communicates through a local, user-scoped native bridge instead of a publicly accessible network service.
+- Uses temporary OpenBrowser-generated element references such as `e_1`, `e_2`, and `e_3`.
+- Invalidates references after navigation or relevant DOM updates and returns stale-reference errors for old refs.
+- Saves screenshots to `~/OpenBrowser/screenshots/<uuid>.png` or returns Base64 image data.
+- Includes an extensible browser-adapter architecture for future Firefox-family and Chromium-family browsers.
+- Initially supports Zen, a Firefox-based browser.
+- Includes a minimal extension logo and uses it as the Firefox extension icon.
+- Builds the Firefox extension into a bundled `.xpi` artifact.
+- Includes a release-signing pipeline for Mozilla unlisted signing with `web-ext sign --channel unlisted`.
 
-- A session is exactly one browser tab created by OpenBrowser.
-- `open` fails if a session already exists for that browser.
-- `close` closes only the OpenBrowser-owned tab.
-- OpenBrowser never closes, reuses, inspects, navigates, or modifies tabs opened manually by the user.
-- If the user manually closes the owned tab, the session is automatically considered closed.
+## Requirements
 
-## Install and build
+- Node.js 20 or newer.
+- npm access to install or run `@pxlarified/browser`.
+- Zen Browser for the initial supported browser target.
+- A Zen profile created on disk. Open Zen once before running the installer.
+- For signed Firefox releases, Mozilla Add-ons API credentials.
 
-```bash
-npm install
-npm run build
-```
+## Installation
 
-This builds:
+Install the bundled extension and native bridge for Zen.
 
-```text
-dist/extensions/firefox/openbrowser-dev.xpi
-```
-
-The Firefox development artifact is unsigned. It is useful for local development and for browser builds/profiles that allow unsigned extensions.
-
-## Install the extension and native bridge
-
-```bash
+```sh
 npx @pxlarified/browser install zen
 ```
 
-The installer:
+The installer does the following.
 
 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.
 
-If an OpenBrowser extension is already staged in a Zen profile, it is overwritten with the bundled version. Restart Zen if the update does not load immediately.
+Restart Zen if the extension update does not load immediately.
 
-## CLI commands
+## Usage
 
 `--browser zen` is optional while Zen is the only supported browser.
 
-```bash
-# Installation and session lifecycle
+```sh
+npx @pxlarified/browser open https://example.com --browser zen
+npx @pxlarified/browser state --browser zen
+npx @pxlarified/browser click e_1 --browser zen
+npx @pxlarified/browser screenshot --browser zen
+npx @pxlarified/browser close --browser zen
+```
+
+### Session lifecycle
+
+```sh
 npx @pxlarified/browser install zen
 npx @pxlarified/browser open <url> --browser zen
 npx @pxlarified/browser close --browser zen
 npx @pxlarified/browser status --browser zen
+```
+
+### Navigation
 
-# Navigation
+```sh
 npx @pxlarified/browser navigate <url> --browser zen
 npx @pxlarified/browser reload --browser zen
 npx @pxlarified/browser back --browser zen
 npx @pxlarified/browser forward --browser zen
+```
+
+### Page state
 
-# Page state
+```sh
 npx @pxlarified/browser state --browser zen
+```
+
+`state` returns the current URL, page title, viewport information, and actionable elements.
+
+```json
+{"url":"https://example.com","title":"Example Domain","elements":[{"ref":"e_1","role":"link","name":"More information"}]}
+```
+
+### Screenshots
 
-# Screenshots
+```sh
 npx @pxlarified/browser screenshot --browser zen
 npx @pxlarified/browser screenshot --base64 --browser zen
+```
+
+`screenshot` saves a PNG file under the user OpenBrowser directory and prints only the absolute file path to stdout.
 
-# Interaction
+```text
+~/OpenBrowser/screenshots/<8-character-uuid>.png
+```
+
+`screenshot --base64` prints only the Base64-encoded PNG data to stdout. Diagnostic logs are written to stderr.
+
+### Interaction
+
+```sh
 npx @pxlarified/browser click <ref> --browser zen
 npx @pxlarified/browser keys <text> --browser zen
 npx @pxlarified/browser press <key> --browser zen
 npx @pxlarified/browser select <ref> <option> --browser zen
+```
+
+### Content inspection
 
-# Content inspection
+```sh
 npx @pxlarified/browser get --html --browser zen
 npx @pxlarified/browser get --html --ref <ref> --browser zen
+```
+
+### Scrolling
 
-# Scrolling
+```sh
 npx @pxlarified/browser scroll up [pixels] --browser zen
 npx @pxlarified/browser scroll down [pixels] --browser zen
 npx @pxlarified/browser scroll --to <ref> --browser zen
 ```
 
-Most commands print JSON to stdout. Screenshot commands are special:
+## Session model
 
-- `screenshot` saves a PNG to `~/OpenBrowser/screenshots/<8-char-uuid>.png` and prints only the absolute file path to stdout.
-- `screenshot --base64` prints only the Base64 PNG data to stdout.
-- Diagnostics are written to stderr.
+OpenBrowser follows a strict ownership model.
 
-## Page state and references
+1. Creating a session opens one new browser tab.
+2. A session may never contain more than one tab.
+3. `open` fails if an OpenBrowser session already exists for that browser.
+4. `close` closes only the tab owned by OpenBrowser.
+5. OpenBrowser never controls tabs the user opened manually.
+6. If the user manually closes the OpenBrowser-owned tab, the session is considered closed automatically.
+7. Opening a new session requires the existing OpenBrowser session to be closed first.
 
-`state` returns the current URL, title, viewport, and actionable elements. Element references are generated by OpenBrowser and do not depend on raw webpage IDs.
+## References
 
-```json
-{"url":"https://example.com","title":"Example Domain","elements":[{"ref":"e_1","role":"link","name":"More information"}]}
-```
+Actionable elements use temporary OpenBrowser-generated references. These references do not depend on raw webpage HTML IDs.
+
+References become invalid after navigation or relevant DOM updates. Commands that use invalid references return a `STALE_REFERENCE` error. Run `state` again to get fresh references.
+
+## Browser support
+
+OpenBrowser uses browser-specific adapters so additional browsers can be added later.
+
+Currently supported:
+
+- Zen - Firefox-based browser.
 
-References become invalid after navigation or relevant DOM updates. Commands that use invalid references return a clear `STALE_REFERENCE` error. Run `state` again to get fresh references.
+Planned architecture support:
 
-## Firefox signing and release pipeline
+- Firefox-family browsers through signed `.xpi` artifacts.
+- Chromium-family browsers through `.zip` extension artifacts.
 
-The development build is unsigned:
+## Extension artifacts
 
-```bash
+The browser extension source lives in `extensions/`.
+
+Build the Firefox development artifact.
+
+```sh
 npm run build:firefox
 ```
 
-When Mozilla Add-ons credentials are available, save them in a local uncommitted `.env` file:
+The unsigned development artifact is written to:
+
+```text
+dist/extensions/firefox/openbrowser-dev.xpi
+```
+
+When a signed release artifact exists, the installer prefers:
+
+```text
+dist/extensions/firefox/openbrowser.xpi
+```
+
+Otherwise it falls back to the unsigned development artifact.
+
+## Firefox signing
+
+Firefox release signing is handled as a separate release step. Save Mozilla Add-ons credentials in a local uncommitted `.env` file.
 
 ```env
 AMO_JWT_ISSUER="..."
 AMO_JWT_SECRET="..."
 ```
 
-Then create the signed unlisted release artifact with:
+Then run:
 
-```bash
+```sh
 npm run release:firefox
 ```
 
-You can also override the `.env` values with shell environment variables.
+The release script submits the extension for Mozilla unlisted signing with `web-ext sign --channel unlisted` and bundles the resulting signed XPI at:
 
-The release script runs the equivalent of:
+```text
+dist/extensions/firefox/openbrowser.xpi
+```
 
-```bash
+Equivalent signing command:
+
+```sh
 npx web-ext sign \
   --source-dir ./extensions/ \
   --channel unlisted \
@@ -153,30 +234,62 @@ npx web-ext sign \
   --api-secret "$AMO_JWT_SECRET"
 ```
 
-It then bundles the resulting signed XPI at:
+## Publishing
 
-```text
-dist/extensions/firefox/openbrowser.xpi
+Build and validate the package before publishing.
+
+```sh
+npm install
+npm run build
+npx web-ext lint --source-dir extensions
+npm pack --dry-run
 ```
 
-That signed `.xpi` is the artifact that should be included in the npm package for Firefox-based browser installs.
+Publish the package publicly.
 
-### Signing information you need to provide
+```sh
+npm publish --access public
+```
 
-Before publishing a signed Firefox release, provide:
+The package is configured with:
 
-1. `AMO_JWT_ISSUER` - the Mozilla Add-ons API key / JWT issuer.
-2. `AMO_JWT_SECRET` - the Mozilla Add-ons API secret / JWT secret.
-3. Confirmation of the final extension ID: `openbrowser@mizius.com`.
-4. Confirmation of the package/version to submit to AMO for unlisted signing.
+```json
+{
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
 
-## Project layout
+The npm package includes the CLI, source, extension source, and bundled extension artifacts. It does not publish `.env`, `node_modules`, build scratch files, or the local `skills/` directory.
 
-```text
-bin/OpenBrowser.js              CLI entry point
-src/                            CLI, browser adapters, installer, native host
-extensions/                      Browser extension source
-scripts/build.js                 Development XPI build
-scripts/sign-firefox.js          Unlisted Firefox signing pipeline
-skills/OpenBrowser/SKILL.md      Local agent skill, not npm-published
+## Development
+
+Install dependencies.
+
+```sh
+npm install
+```
+
+Build the Firefox extension artifact.
+
+```sh
+npm run build
 ```
+
+Run the CLI locally without publishing.
+
+```sh
+npm exec --package . OpenBrowser -- --help
+```
+
+Project entry points:
+
+- Logo source - `assets/logo.svg`
+- CLI - `bin/OpenBrowser.js`
+- CLI implementation - `src/cli.js`
+- Zen adapter - `src/browsers/zen.js`
+- Firefox-family installer - `src/browsers/firefox-family.js`
+- Native bridge host - `src/native-host.cjs`
+- Extension background script - `extensions/background.js`
+- Extension content script - `extensions/content.js`

package/assets/logo.svg

@@ -0,0 +1,19 @@
+<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="OpenBrowser logo">
+  <rect width="128" height="128" rx="30" fill="url(#bg)"/>
+  <path d="M28 43C28 35.268 34.268 29 42 29H86C93.732 29 100 35.268 100 43V85C100 92.732 93.732 99 86 99H42C34.268 99 28 92.732 28 85V43Z" fill="#0B1020" fill-opacity="0.74"/>
+  <circle cx="39" cy="38" r="4" fill="#FF6B7A"/>
+  <circle cx="52" cy="38" r="4" fill="#FFD166"/>
+  <circle cx="65" cy="38" r="4" fill="#4BE1A0"/>
+  <path d="M73.863 54.873L49.586 65.072C47.191 66.079 47.307 69.514 49.765 70.357L61.008 74.211L65.025 85.396C65.905 87.846 69.342 87.911 70.312 85.496L80.139 61.03C81.643 57.285 77.582 53.31 73.863 54.873Z" fill="url(#pointer)"/>
+  <defs>
+    <linearGradient id="bg" x1="18" y1="10" x2="112" y2="120" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#7C4DFF"/>
+      <stop offset="0.48" stop-color="#2563EB"/>
+      <stop offset="1" stop-color="#14B8A6"/>
+    </linearGradient>
+    <linearGradient id="pointer" x1="49" y1="54" x2="80" y2="87" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFFFFF"/>
+      <stop offset="1" stop-color="#B8D7FF"/>
+    </linearGradient>
+  </defs>
+</svg>

package/extensions/assets/logo.svg

@@ -0,0 +1,19 @@
+<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="OpenBrowser logo">
+  <rect width="128" height="128" rx="30" fill="url(#bg)"/>
+  <path d="M28 43C28 35.268 34.268 29 42 29H86C93.732 29 100 35.268 100 43V85C100 92.732 93.732 99 86 99H42C34.268 99 28 92.732 28 85V43Z" fill="#0B1020" fill-opacity="0.74"/>
+  <circle cx="39" cy="38" r="4" fill="#FF6B7A"/>
+  <circle cx="52" cy="38" r="4" fill="#FFD166"/>
+  <circle cx="65" cy="38" r="4" fill="#4BE1A0"/>
+  <path d="M73.863 54.873L49.586 65.072C47.191 66.079 47.307 69.514 49.765 70.357L61.008 74.211L65.025 85.396C65.905 87.846 69.342 87.911 70.312 85.496L80.139 61.03C81.643 57.285 77.582 53.31 73.863 54.873Z" fill="url(#pointer)"/>
+  <defs>
+    <linearGradient id="bg" x1="18" y1="10" x2="112" y2="120" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#7C4DFF"/>
+      <stop offset="0.48" stop-color="#2563EB"/>
+      <stop offset="1" stop-color="#14B8A6"/>
+    </linearGradient>
+    <linearGradient id="pointer" x1="49" y1="54" x2="80" y2="87" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#FFFFFF"/>
+      <stop offset="1" stop-color="#B8D7FF"/>
+    </linearGradient>
+  </defs>
+</svg>

package/extensions/manifest.json

@@ -1,8 +1,13 @@
 {
   "manifest_version": 2,
   "name": "OpenBrowser",
-  "version": "0.1.0",
+  "version": "1.9.4",
   "description": "Local user-scoped browser control bridge for the OpenBrowser CLI.",
+  "icons": {
+    "48": "assets/logo.svg",
+    "96": "assets/logo.svg",
+    "128": "assets/logo.svg"
+  },
   "permissions": [
     "nativeMessaging",
     "storage",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pxlarified/browser",
-  "version": "0.1.0",
+  "version": "1.9.4",
   "description": "Minimal local browser-control CLI for OpenBrowser.",
   "type": "module",
   "bin": {
@@ -18,6 +18,8 @@
     "extensions/manifest.json",
     "extensions/background.js",
     "extensions/content.js",
+    "extensions/assets/",
+    "assets/",
     "dist/extensions/",
     "scripts/",
     "README.md",

package/scripts/build.js

@@ -23,6 +23,7 @@ fs.mkdirSync(outDir, { recursive: true });
 copyFile(path.join(sourceDir, "manifest.json"), path.join(buildDir, "manifest.json"));
 copyFile(path.join(sourceDir, "background.js"), path.join(buildDir, "background.js"));
 copyFile(path.join(sourceDir, "content.js"), path.join(buildDir, "content.js"));
+copyDirectory(path.join(sourceDir, "assets"), path.join(buildDir, "assets"));
 
 await zipDirectory(buildDir, outFile);
 console.log(`Built ${path.relative(root, outFile)}`);
@@ -32,6 +33,16 @@ function copyFile(from, to) {
   fs.copyFileSync(from, to);
 }
 
+function copyDirectory(from, to) {
+  if (!fs.existsSync(from)) return;
+  for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+    const source = path.join(from, entry.name);
+    const destination = path.join(to, entry.name);
+    if (entry.isDirectory()) copyDirectory(source, destination);
+    else copyFile(source, destination);
+  }
+}
+
 function zipDirectory(directory, destination) {
   return new Promise((resolve, reject) => {
     const zip = new yazl.ZipFile();