fix: make navigation no-focus by default

- Change nav open and open-wait to avoid activating newly created tabs unless
  --focus is explicitly requested.
- Send background=true for default opens so older or remote extensions also
  avoid stealing focus even if they ignore the new focus flag.
- Remove the redundant --bg flag from navigation and search CLI commands now
  that no-focus/background behavior is the default.
- Thread focus support through the sync SDK, async SDK, tab helpers, and
  workflow decorators.
- Update README and demo usage to document the new default and --focus opt-in.
- Bump package and extension metadata to 0.12.3.
- Add regression coverage for CLI help, wire payloads, and extension behavior.

extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "browser-cli",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "Control your browser from the terminal or Python SDK",
   "permissions": [
     "tabs",

extension/src/commands/navigation.ts

@@ -17,7 +17,7 @@ export class NavigationCommands extends CommandGroup {
     "navigate.open_wait":   (a: NavOpenWaitArgs) => this.navOpenWait(a),
   };
 
-  private async navOpen({ url, background, window: windowName, windowId: explicitWindowId, group: groupNameOrId }: NavOpenArgs) {
+  private async navOpen({ url, background, focus, window: windowName, windowId: explicitWindowId, group: groupNameOrId }: NavOpenArgs) {
     let windowId: number | undefined;
     if (explicitWindowId != null) {
       windowId = explicitWindowId;
@@ -26,7 +26,7 @@ export class NavigationCommands extends CommandGroup {
       const entry = Object.entries(aliases).find(([, v]) => v === windowName);
       if (entry) windowId = parseInt(entry[0]);
     }
-    const tab = await chrome.tabs.create({ url, active: !background, windowId });
+    const tab = await chrome.tabs.create({ url, active: Boolean(focus) && !background, windowId });
     if (groupNameOrId != null) {
       let groupId;
       try {
@@ -115,8 +115,8 @@ export class NavigationCommands extends CommandGroup {
     throw new Error(`Tab ${tab.id} did not reach status '${readyState}' within ${timeout}ms`);
   }
 
-  private async navOpenWait({ url, timeout = 30000, background, window: windowName, group }: NavOpenWaitArgs = {}) {
-    const opened = await this.navOpen({ url, background, window: windowName, group });
+  private async navOpenWait({ url, timeout = 30000, background, focus, window: windowName, group }: NavOpenWaitArgs = {}) {
+    const opened = await this.navOpen({ url, background, focus, window: windowName, group });
     return await this.navWait({ tabId: opened.id, timeout });
   }
 }

extension/src/types/command-args.ts

@@ -5,6 +5,7 @@ import type { Job } from './jobs';
 export interface NavOpenArgs {
   url?: string;
   background?: boolean;
+  focus?: boolean;
   window?: string;
   windowId?: number;
   group?: string | number;
@@ -18,6 +19,7 @@ export interface NavOpenWaitArgs {
   url?: string;
   timeout?: number;
   background?: boolean;
+  focus?: boolean;
   window?: string;
   group?: string | number;
 }