Skip to content

Improve browser selection and add Helium support - #3

Merged
pxlarified merged 2 commits into
mainfrom
development
Aug 18, 2026
Merged

Improve browser selection and add Helium support#3
pxlarified merged 2 commits into
mainfrom
development

Conversation

@pxlarified

@pxlarified pxlarified commented Aug 18, 2026

Copy link
Copy Markdown
Member

Summary

This PR makes browser selection local, discoverable, and mostly automatic. It adds Helium support, keeps Chrome and Zen support, introduces one shared browser catalog, and updates the CLI/agent skill so daily commands no longer need a hard-coded --browser flag.

Version is bumped to 2.2.0.

Setup after this PR is merged

Each user runs setup once on their own machine. The selection is stored in that user's ~/OpenBrowser/config.json; it is not stored in the repository and does not affect other users.

Helium

npx @pxlarified/browser browsers
npx @pxlarified/browser setup helium

On macOS, setup will:

  1. Install the Helium-specific native-host launcher under ~/OpenBrowser/native-host/.
  2. Write the native-messaging manifest under Helium's application-support directory (net.imput.helium/NativeMessagingHosts/).
  3. Stage the shared Chromium MV3 extension under ~/OpenBrowser/extensions/helium/.
  4. Save helium as the local default browser.

Because Chromium browsers do not allow this package to install an unpacked extension directly into a profile, the user then opens Helium's extensions page, enables Developer mode, chooses Load unpacked, and selects the staged path reported by setup. Once the extension is loaded, the bridge is ready.

Chrome

The flow is identical:

npx @pxlarified/browser setup chrome

Chrome receives its own native-host launcher, browser-specific Windows registry entry/manifest when applicable, staged extension directory, and bridge socket. It reuses the same Chromium extension artifact as Helium. Setting up Chrome and Helium on the same Windows machine no longer overwrites either browser's native-host manifest.

Zen

npx @pxlarified/browser setup zen

Zen uses the Firefox-family flow: the bundled XPI is copied to detected Zen profiles and the native-messaging manifest/launcher are installed. Zen must be opened once first so its profile can be discovered. Partial installs are not treated as configured until the native host, manifest, and profile extension are all present.

All Firefox and Chromium artifacts now include PNG extension icons at the standard sizes.

Normal daily usage

After setup, commands are browser-neutral:

npx @pxlarified/browser open https://example.com
npx @pxlarified/browser state
npx @pxlarified/browser click e_1
npx @pxlarified/browser close

The explicit override remains available for multi-browser workflows:

npx @pxlarified/browser state --browser helium

The friendly default command is also available:

npx @pxlarified/browser use helium
npx @pxlarified/browser use chrome
npx @pxlarified/browser use zen
npx @pxlarified/browser use auto

Selection behavior

Selection precedence is:

  1. --browser <id>
  2. OPENBROWSER_BROWSER
  3. The configured local browser, when its setup is complete
  4. A single active OpenBrowser session
  5. Automatic discovery when exactly one browser is available

A configured default now short-circuits discovery and does not probe unrelated browser bridge sockets on every daily command. If the configured target is incomplete, OpenBrowser falls back to discovery and provides setup guidance. If multiple active, configured, or detected browsers are possible, OpenBrowser reports the choices instead of silently defaulting to Zen. OpenBrowser browsers --json provides machine-readable status for automation.

Review fixes included

  • Reject unexpected positional arguments for OpenBrowser browsers.
  • Use browser-specific Windows Chromium native-host manifest files and registry entries, preventing Chrome/Helium collisions.
  • Restore Chrome's Windows registry root and add Helium's Windows registry root.
  • Treat a Firefox target as configured only when its native host, manifest, and profile extension all exist.
  • Wait for wrapper launch commands such as macOS open -a to exit successfully before trying the next candidate.
  • Avoid bridge discovery when a configured default is already complete.
  • Add PNG extension icons to the source and generated Firefox/Chromium artifacts.

Implementation details

  • Added a data-driven browser catalog with aliases, platform paths, profile roots, executable candidates, launch commands, and native-messaging roots.
  • Added Helium as a Chromium-family browser, including its macOS bundle/profile identifier.
  • Kept Firefox-family and Chromium-family adapters responsible for installation and runtime behavior.
  • Kept browser-specific native-host launchers and bridge sockets so sessions cannot be mixed across browsers.
  • Added browser discovery/status reporting (not detected, installed, configured, ready, and active).
  • Added setup, browsers, and use CLI commands while preserving --browser, install <browser>, and config browser.
  • Updated the bundled browser skill and README to avoid hard-coded Zen examples.
  • Kept the legacy Chromium constant names as aliases for existing consumers.

Verification

  • npm test — 30 tests passed.
  • npm run build — Firefox and Chromium artifacts built successfully.
  • npx web-ext lint --source-dir extensions — no errors, notices, or warnings.
  • npm pack --dry-run — package contents include the new catalog, discovery, Helium adapter, icons, CLI, skill, and version 2.2.0.

@greptile-apps

greptile-apps Bot commented Aug 18, 2026

Copy link
Copy Markdown

Greptile Summary

The PR adds Helium, centralizes browser metadata, and introduces automatic browser discovery and selection.

  • Adds shared Firefox- and Chromium-family discovery and setup behavior.
  • Adds setup, browsers, and use CLI workflows.
  • Updates extension artifacts, documentation, tests, and package version to 2.2.0.

Confidence Score: 4/5

The Windows Chrome setup regression must be fixed before merging because newly configured installations cannot register or start the native host.

The catalog refactor removes the registry root consumed by the only Windows Chromium registration loop, leaving Chrome unable to discover the generated native-host manifest.

Files Needing Attention: src/browsers/catalog.js

Reviews (1): Last reviewed commit: "Improve browser selection and add Helium..." | Re-trigger Greptile

Comment thread src/browsers/catalog.js
family: "chromium",
profileRoots: [path.join(localAppData, "Google", "Chrome", "User Data")],
nativeManifestRoots: [],
applicationPaths: windowsApplicationPaths("Google", "Chrome", "Application", "chrome.exe"),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Windows Chrome host registration missing

When a Windows user runs OpenBrowser setup chrome or OpenBrowser install chrome, the new catalog definition supplies no registryRoots, so the installer writes the native-host manifest without registering it under Chrome's NativeMessagingHosts key. Chrome therefore cannot discover or launch the native host, leaving the extension unable to establish the bridge even though setup reports completion.

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found across 25 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/browsers/shared.js">

<violation number="1" location="src/browsers/shared.js:92">
P2: When a wrapper command such as macOS `open -a` starts but cannot find its target application, `launchBrowser` treats it as successful and skips later candidates. Validate the wrapper's result or model wrapper commands separately before returning success.</violation>
</file>

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread src/browsers/chromium-family.js Outdated
Comment thread src/browsers/firefox-family.js Outdated
Comment thread src/cli.js
Comment thread src/browsers/shared.js
}

child.once("error", () => finish(false));
child.once("spawn", () => {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: When a wrapper command such as macOS open -a starts but cannot find its target application, launchBrowser treats it as successful and skips later candidates. Validate the wrapper's result or model wrapper commands separately before returning success.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At src/browsers/shared.js, line 92:

<comment>When a wrapper command such as macOS `open -a` starts but cannot find its target application, `launchBrowser` treats it as successful and skips later candidates. Validate the wrapper's result or model wrapper commands separately before returning success.</comment>

<file context>
@@ -17,17 +18,88 @@ export function installNativeHost(browser) {
+      }
+
+      child.once("error", () => finish(false));
+      child.once("spawn", () => {
+        child.unref();
+        finish(true);
</file context>

Comment thread src/browsers/selection.js Outdated
Comment thread src/browsers/catalog.js
@pxlarified

Copy link
Copy Markdown
Member Author

Addressed in commit e1bb4d5:

  • browsers now rejects unexpected positional arguments.
  • Windows Chromium native-host manifests are browser-specific, with matching Chrome and Helium registry roots.
  • Firefox targets are only marked configured when the native host, manifest, and profile extension all exist.
  • macOS wrapper launch commands wait for a successful exit status before accepting the candidate.
  • A complete configured default now skips full browser/bridge discovery on daily commands.
  • Added PNG extension icons to the source manifest and generated Firefox/Chromium artifacts.

Local verification passes: 30 tests, both extension builds, WebExtension lint, and package dry-run.

@pxlarified
pxlarified merged commit 33c4244 into main Aug 18, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant