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.

browser_cli/sdk/navigation.py

@@ -4,8 +4,8 @@ from __future__ import annotations
 from browser_cli.models import Tab
 from browser_cli.sdk.base import Namespace, sdk_command
 
-def _open_args(self, url, *, background=False, window=None, group=None):
-  return {"url": url, "background": background, "window": window, "group": group}
+def _open_args(self, url, *, background=False, focus=False, window=None, group=None):
+  return {"url": url, "background": background or not focus, "focus": focus, "window": window, "group": group}
 
 def _tab_args(self, tab_id=None):
   return {"tabId": tab_id}
@@ -14,8 +14,16 @@ class NavigationNS(Namespace):
   """Open URLs, navigate history, and focus tabs."""
 
   @sdk_command("navigate.open", _open_args)
-  def open(self, url: str, *, background: bool = False, window: str | None = None, group: str | None = None) -> None:
-    """Open *url* in a new tab."""
+  def open(
+    self,
+    url: str,
+    *,
+    background: bool = False,
+    focus: bool = False,
+    window: str | None = None,
+    group: str | None = None,
+  ) -> None:
+    """Open *url* in a new tab without stealing OS focus by default."""
 
   def open_wait(
     self,
@@ -23,6 +31,7 @@ class NavigationNS(Namespace):
     *,
     timeout: float = 30.0,
     background: bool = False,
+    focus: bool = False,
     window: str | None = None,
     group: str | None = None,
   ) -> Tab:
@@ -30,7 +39,7 @@ class NavigationNS(Namespace):
     return self.require_tab(
       self.command("navigate.open_wait", {
         "url": url, "timeout": int(timeout * 1000),
-        "background": background, "window": window, "group": group,
+        "background": background or not focus, "focus": focus, "window": window, "group": group,
       }),
       "navigate.open_wait returned unexpected data",
     )
@@ -61,7 +70,7 @@ class NavigationNS(Namespace):
 
   def search(
     self, engine: str, query: str, *,
-    background: bool = False, window: str | None = None, group: str | None = None,
+    background: bool = False, focus: bool = False, window: str | None = None, group: str | None = None,
   ) -> None:
     """Open a search query in the given engine (e.g. 'google', 'youtube', 'ddg')."""
     from urllib.parse import quote_plus
@@ -70,4 +79,4 @@ class NavigationNS(Namespace):
     if template is None:
       raise ValueError(f"Unknown search engine '{engine}'. Available: {', '.join(ENGINES)}")
     url = template.format(query=quote_plus(query))
-    self.command("navigate.open", {"url": url, "background": background, "window": window, "group": group})
+    self.command("navigate.open", {"url": url, "background": background or not focus, "focus": focus, "window": window, "group": group})

browser_cli/sdk/tabs.py

@@ -24,17 +24,19 @@ class TabsNS(Namespace):
     wait: bool = False,
     timeout: float = 30.0,
     background: bool = False,
+    focus: bool = False,
     window: str | None = None,
     group: str | None = None,
   ) -> Tab:
     """Open *url* in a new tab and return a bound :class:`Tab`.
 
     Set ``wait=True`` to block until the page reaches ``readyState=complete``.
+    Pass ``focus=True`` to explicitly bring the created tab/window forward.
     """
     if wait:
-      return self._c.nav.open_wait(url, timeout=timeout, background=background, window=window, group=group)
+      return self._c.nav.open_wait(url, timeout=timeout, background=background, focus=focus, window=window, group=group)
     return self.require_tab(
-      self.command("navigate.open", {"url": url, "background": background, "window": window, "group": group}),
+      self.command("navigate.open", {"url": url, "background": background or not focus, "focus": focus, "window": window, "group": group}),
       "navigate.open returned unexpected data",
     )
 

browser_cli/sdk/workflow_decorators.py

@@ -81,6 +81,7 @@ class WorkflowDecoratorsMixin:
     wait: bool = False,
     timeout: float = 30.0,
     background: bool = False,
+    focus: bool = False,
     window: str | None = None,
     group: str | None = None,
     close: bool = False,
@@ -97,6 +98,7 @@ class WorkflowDecoratorsMixin:
         wait=wait,
         timeout=timeout,
         background=background,
+        focus=focus,
         window=window,
         group=group,
       )