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.

tests/test_api.py

@@ -160,7 +160,7 @@ class TestNavigation:
     b.nav.open("https://example.com")
     mock_send.assert_called_once_with(
       "navigate.open",
-      {"url": "https://example.com", "background": False, "window": None, "group": None},
+      {"url": "https://example.com", "background": True, "focus": False, "window": None, "group": None},
       profile=None, remote=None, key=None,
     )
 
@@ -173,6 +173,10 @@ class TestNavigation:
     b.nav.open("https://x.com", group="Work")
     assert mock_send.call_args[0][1]["group"] == "Work"
 
+  def test_open_focus_is_explicit(self, b, mock_send):
+    b.nav.open("https://example.com", focus=True)
+    assert mock_send.call_args[0][1]["focus"] is True
+
   def test_tabs_open_returns_bound_tab(self, b, mock_send):
     mock_send.return_value = {"id": 123, "url": "https://example.com"}
 
@@ -183,7 +187,7 @@ class TestNavigation:
     assert tab._browser is b
     mock_send.assert_called_once_with(
       "navigate.open",
-      {"url": "https://example.com", "background": True, "window": None, "group": None},
+      {"url": "https://example.com", "background": True, "focus": False, "window": None, "group": None},
       profile=None,
       remote=None,
       key=None,
@@ -197,7 +201,7 @@ class TestNavigation:
     assert tab.id == 10
     mock_send.assert_called_once_with(
       "navigate.open_wait",
-      {"url": "https://example.com", "timeout": 1500, "background": False, "window": None, "group": None},
+      {"url": "https://example.com", "timeout": 1500, "background": True, "focus": False, "window": None, "group": None},
       profile=None,
       remote=None,
       key=None,
@@ -1031,7 +1035,7 @@ class TestSDKDecorators:
     assert mock_send.mock_calls == [
       call(
         "navigate.open_wait",
-        {"url": "https://example.com", "timeout": 1500, "background": False, "window": None, "group": None},
+        {"url": "https://example.com", "timeout": 1500, "background": True, "focus": False, "window": None, "group": None},
         profile=None,
         remote=None,
         key=None,
@@ -1190,7 +1194,7 @@ class TestAsyncBrowserCLI:
       assert mock_send_async.mock_calls == [
         call(
           "navigate.open",
-          {"url": "https://example.com", "background": False, "window": None, "group": None},
+          {"url": "https://example.com", "background": True, "focus": False, "window": None, "group": None},
           profile=None,
           remote=None,
           key=None,

tests/test_commands_cli.py

@@ -346,14 +346,43 @@ def test_cli_perf_profile_ultra():
 from browser_cli.commands.navigate import nav_group
 
 def test_cli_nav_open():
-    result = _run(nav_group, ["open", "https://example.com"], {"id": 42, "url": "https://example.com"})
-    assert result.exit_code == 0
-    assert "Opened" in result.output
+    with patch("browser_cli.send_command", return_value={"id": 42, "url": "https://example.com"}) as send_command:
+        result = CliRunner().invoke(nav_group, ["open", "https://example.com"])
 
-def test_cli_nav_open_bg():
-    result = _run(nav_group, ["open", "https://example.com", "--bg"], {"id": 42})
     assert result.exit_code == 0
     assert "Opened" in result.output
+    send_command.assert_called_once_with(
+        "navigate.open",
+        {"url": "https://example.com", "background": True, "focus": False, "window": None, "group": None},
+        profile=None,
+        remote=None,
+        key=None,
+    )
+
+def test_cli_nav_open_has_no_bg_option():
+    result = CliRunner().invoke(nav_group, ["open", "--help"])
+
+    assert result.exit_code == 0
+    assert "--bg" not in result.output
+
+def test_cli_nav_open_wait_has_no_bg_option():
+    result = CliRunner().invoke(nav_group, ["open-wait", "--help"])
+
+    assert result.exit_code == 0
+    assert "--bg" not in result.output
+
+def test_cli_nav_open_focus_is_explicit():
+    with patch("browser_cli.send_command", return_value={"id": 42}) as send_command:
+        result = CliRunner().invoke(nav_group, ["open", "https://example.com", "--focus"])
+
+    assert result.exit_code == 0
+    send_command.assert_called_once_with(
+        "navigate.open",
+        {"url": "https://example.com", "background": False, "focus": True, "window": None, "group": None},
+        profile=None,
+        remote=None,
+        key=None,
+    )
 
 def test_cli_nav_open_with_group():
     result = _run(nav_group, ["open", "https://example.com", "--group", "work"], {"id": 42})
@@ -412,6 +441,18 @@ def test_cli_nav_wait():
     assert result.exit_code == 0
     assert "Ready" in result.output
 
+# ---------------------------------------------------------------------------
+# search commands
+# ---------------------------------------------------------------------------
+
+from browser_cli.commands.search import search_group
+
+def test_cli_search_has_no_bg_option():
+    result = CliRunner().invoke(search_group, ["google", "--help"])
+
+    assert result.exit_code == 0
+    assert "--bg" not in result.output
+
 # ---------------------------------------------------------------------------
 # navigate commands — with tab_id argument
 # ---------------------------------------------------------------------------

tests/test_extension_error_page_handling.py

@@ -111,10 +111,12 @@ def test_large_extension_operations_yield_between_batches():
     assert "perf.set_profile" in perf
     assert "__background" in connection
 
-def test_tab_activation_and_merge_do_not_steal_audible_video_window():
+def test_tab_activation_open_and_merge_do_not_steal_audible_video_window():
     tabs = (ROOT / "extension" / "src" / "commands" / "tabs.ts").read_text()
+    navigation = (ROOT / "extension" / "src" / "commands" / "navigation.ts").read_text()
 
     assert "await chrome.windows.update(tab.windowId, { focused: true });" not in tabs
+    assert "active: Boolean(focus) && !background" in navigation
     assert "windowHasAudibleTabs" in tabs
     assert "!this.windowHasAudibleTabs(w)" in tabs
     assert "skippedAudibleWindows" in tabs