webtap-tool 0.7.1__py3-none-any.whl → 0.8.1__py3-none-any.whl

webtap/__init__.py

@@ -9,10 +9,14 @@ PUBLIC API:
   - main: Entry point function for CLI
 """
 
+import atexit
 import sys
 
 from webtap.app import app
 
+# Register cleanup on exit to shutdown DB thread
+atexit.register(lambda: app.state.cleanup() if hasattr(app, "state") and app.state else None)
+
 
 def main():
     """Entry point for the WebTap REPL.

webtap/api.py

@@ -119,9 +119,6 @@ async def connect(request: ConnectRequest) -> Dict[str, Any]:
     # Wrap blocking CDP calls (connect + enable domains) in thread
     result = await asyncio.to_thread(app_state.service.connect_to_page, page_id=request.page_id)
 
-    # Broadcast state change
-    await broadcast_state()
-
     return result
 
 
@@ -134,9 +131,6 @@ async def disconnect() -> Dict[str, Any]:
     # Wrap blocking CDP calls (fetch.disable + disconnect) in thread
     result = await asyncio.to_thread(app_state.service.disconnect)
 
-    # Broadcast state change
-    await broadcast_state()
-
     return result
 
 
@@ -146,7 +140,10 @@ async def clear_events() -> Dict[str, Any]:
     if not app_state:
         return {"error": "WebTap not initialized"}
 
-    return app_state.service.clear_events()
+    # Wrap blocking DB operation in thread
+    result = await asyncio.to_thread(app_state.service.clear_events)
+
+    return result
 
 
 @api.post("/fetch")
@@ -164,7 +161,7 @@ async def set_fetch_interception(request: FetchRequest) -> Dict[str, Any]:
         result = await asyncio.to_thread(app_state.service.fetch.disable)
 
     # Broadcast state change
-    await broadcast_state()
+    app_state.service._trigger_broadcast()
 
     return result
 
@@ -200,7 +197,7 @@ async def toggle_filter_category(category: str) -> Dict[str, Any]:
     fm.save()
 
     # Broadcast state change
-    await broadcast_state()
+    app_state.service._trigger_broadcast()
 
     return {"category": category, "enabled": enabled, "total_enabled": len(fm.enabled_categories)}
 
@@ -216,7 +213,7 @@ async def enable_all_filters() -> Dict[str, Any]:
     fm.save()
 
     # Broadcast state change
-    await broadcast_state()
+    app_state.service._trigger_broadcast()
 
     return {"enabled": list(fm.enabled_categories), "total": len(fm.enabled_categories)}
 
@@ -232,7 +229,7 @@ async def disable_all_filters() -> Dict[str, Any]:
     fm.save()
 
     # Broadcast state change
-    await broadcast_state()
+    app_state.service._trigger_broadcast()
 
     return {"enabled": [], "total": 0}
 
@@ -249,9 +246,6 @@ async def start_inspect() -> Dict[str, Any]:
     # Wrap blocking CDP calls (DOM.enable, CSS.enable, Overlay.enable, setInspectMode) in thread
     result = await asyncio.to_thread(app_state.service.dom.start_inspect)
 
-    # Broadcast state change
-    await broadcast_state()
-
     return result
 
 
@@ -264,9 +258,6 @@ async def stop_inspect() -> Dict[str, Any]:
     # Wrap blocking CDP call (Overlay.setInspectMode) in thread
     result = await asyncio.to_thread(app_state.service.dom.stop_inspect)
 
-    # Broadcast state change
-    await broadcast_state()
-
     return result
 
 
@@ -278,9 +269,6 @@ async def clear_selections() -> Dict[str, Any]:
 
     app_state.service.dom.clear_selections()
 
-    # Broadcast state change
-    await broadcast_state()
-
     return {"success": True, "selections": {}}
 
 
@@ -293,7 +281,7 @@ async def dismiss_error() -> Dict[str, Any]:
     app_state.error_state = None
 
     # Broadcast state change
-    await broadcast_state()
+    app_state.service._trigger_broadcast()
 
     return {"success": True}
 
@@ -363,11 +351,11 @@ async def stream_events():
 def get_full_state() -> Dict[str, Any]:
     """Get complete WebTap state for broadcasting.
 
-    Returns real-time state only (no blocking I/O).
-    Page list excluded - fetch via /info endpoint on-demand.
+    Thread-safe, zero-lock reads from immutable snapshot.
+    No blocking I/O - returns cached snapshot immediately.
 
     Returns:
-        Dictionary with all state information
+        Dictionary with all state information for SSE clients
     """
     if not app_state:
         return {
@@ -375,40 +363,35 @@ def get_full_state() -> Dict[str, Any]:
             "events": {"total": 0},
             "fetch": {"enabled": False, "paused_count": 0},
             "filters": {"enabled": [], "disabled": []},
-            "browser": {"inspect_active": False, "selections": {}, "prompt": ""},
+            "browser": {"inspect_active": False, "selections": {}, "prompt": "", "pending_count": 0},
             "error": None,
         }
 
-    # Get connection status
-    connected = app_state.cdp.is_connected
-    page_info = app_state.cdp.page_info or {}
-
-    # Get event counts
-    event_count = app_state.service.event_count
-
-    # Get fetch status
-    fetch_enabled = app_state.service.fetch.enabled
-    paused_count = app_state.service.fetch.paused_count if fetch_enabled else 0
-
-    # Get filter status
-    fm = app_state.service.filters
-    filter_categories = list(fm.filters.keys())
-    enabled_filters = list(fm.enabled_categories)
-    disabled_filters = [cat for cat in filter_categories if cat not in enabled_filters]
-
-    # Get browser/DOM state (includes pending_count for progress indicator)
-    browser_state = app_state.service.dom.get_state()
+    # Get immutable snapshot (NO LOCKS NEEDED - inherently thread-safe)
+    snapshot = app_state.service.get_state_snapshot()
 
+    # Convert snapshot to frontend format
     return {
-        "connected": connected,
-        "page": {"id": page_info.get("id", ""), "title": page_info.get("title", ""), "url": page_info.get("url", "")}
-        if connected
+        "connected": snapshot.connected,
+        "page": {
+            "id": snapshot.page_id,
+            "title": snapshot.page_title,
+            "url": snapshot.page_url,
+        }
+        if snapshot.connected
+        else None,
+        "events": {"total": snapshot.event_count},
+        "fetch": {"enabled": snapshot.fetch_enabled, "paused_count": snapshot.paused_count},
+        "filters": {"enabled": list(snapshot.enabled_filters), "disabled": list(snapshot.disabled_filters)},
+        "browser": {
+            "inspect_active": snapshot.inspect_active,
+            "selections": snapshot.selections,
+            "prompt": snapshot.prompt,
+            "pending_count": snapshot.pending_count,
+        },
+        "error": {"message": snapshot.error_message, "timestamp": snapshot.error_timestamp}
+        if snapshot.error_message
         else None,
-        "events": {"total": event_count},
-        "fetch": {"enabled": fetch_enabled, "paused_count": paused_count},
-        "filters": {"enabled": enabled_filters, "disabled": disabled_filters},
-        "browser": browser_state,  # Contains inspect_active, selections, prompt, pending_count
-        "error": app_state.error_state,  # Current error or None
     }
 
 
@@ -429,7 +412,14 @@ async def broadcast_state():
         try:
             queue.put_nowait(state)
         except asyncio.QueueFull:
-            logger.warning("SSE client queue full, skipping broadcast")
+            # Client is falling behind - discard oldest state and retry with latest
+            logger.warning(f"SSE client queue full ({queue.qsize()}/{queue.maxsize}), discarding oldest state")
+            try:
+                queue.get_nowait()  # Discard oldest
+                queue.put_nowait(state)  # Retry with latest
+            except Exception as retry_err:
+                logger.debug(f"Failed to recover full queue: {retry_err}")
+                dead_queues.add(queue)
         except Exception as e:
             logger.debug(f"Failed to broadcast to client: {e}")
             dead_queues.add(queue)
@@ -470,7 +460,9 @@ async def broadcast_processor():
     async with _sse_clients_lock:
         for queue in list(_sse_clients):
             try:
-                await queue.put(None)  # Signal shutdown to client
+                queue.put_nowait(None)  # Non-blocking shutdown signal
+            except asyncio.QueueFull:
+                pass  # Client is hung, skip
             except Exception:
                 pass
         _sse_clients.clear()
@@ -521,11 +513,12 @@ def start_api_server(state, host: str = "127.0.0.1", port: int = 8765) -> thread
         logger.error("Broadcast queue initialization timed out")
         return thread
 
-    # Wire queue to DOM service and CDP session after event loop starts
+    # Wire queue to service and CDP session after event loop starts
+    # Note: DOMService uses callback to service._trigger_broadcast instead of direct queue access
     if _broadcast_queue and app_state:
-        app_state.service.dom.set_broadcast_queue(_broadcast_queue)
+        app_state.service.set_broadcast_queue(_broadcast_queue)
         app_state.cdp.set_broadcast_queue(_broadcast_queue)
-        logger.info("Broadcast queue wired to DOMService and CDPSession")
+        logger.info("Broadcast queue wired to WebTapService and CDPSession")
 
     logger.info(f"API server started on http://{host}:{port}")
     return thread

webtap/app.py

@@ -57,6 +57,10 @@ class WebTapState:
             # Give server 1.5s to close SSE connections and shutdown gracefully
             self.api_thread.join(timeout=1.5)
 
+        # Shutdown DB thread (this is the only place where DB thread should stop)
+        if hasattr(self, "cdp") and self.cdp:
+            self.cdp.cleanup()
+
 
 # Must be created before command imports for decorator registration
 app = App(
@@ -90,6 +94,7 @@ else:
     from webtap.commands import fetch  # noqa: E402, F401
     from webtap.commands import body  # noqa: E402, F401
     from webtap.commands import to_model  # noqa: E402, F401
+    from webtap.commands import quicktype  # noqa: E402, F401
     from webtap.commands import selections  # noqa: E402, F401
     from webtap.commands import server  # noqa: E402, F401
     from webtap.commands import setup  # noqa: E402, F401

webtap/cdp/session.py

@@ -78,8 +78,9 @@ class CDPSession:
 
         # Broadcast queue for SSE state updates (set by API server)
         self._broadcast_queue: "Any | None" = None
-        self._last_broadcast_time = 0.0
-        self._broadcast_debounce = 1.0  # 1 second debounce
+
+        # Disconnect callback for service-level cleanup
+        self._disconnect_callback: "Any | None" = None
 
     def _db_worker(self) -> None:
         """Dedicated thread for all database operations.
@@ -218,7 +219,7 @@ class CDPSession:
             kwargs={
                 "ping_interval": 30,  # Ping every 30s
                 "ping_timeout": 20,  # Wait 20s for pong (increased from 10s for heavy CDP load)
-                "reconnect": 5,  # Auto-reconnect with max 5s delay
+                # No auto-reconnect - make disconnects explicit
                 "skip_utf8_validation": True,  # Faster
             },
         )
@@ -231,24 +232,46 @@ class CDPSession:
             raise TimeoutError("Failed to connect to Chrome")
 
     def disconnect(self) -> None:
-        """Disconnect WebSocket and clean up resources."""
-        if self.ws_app:
-            self.ws_app.close()
+        """Disconnect WebSocket while preserving events and DB thread.
+
+        Events and DB thread persist across connection cycles.
+        Use cleanup() on app exit to shutdown DB thread.
+        """
+        # Atomically clear ws_app to signal manual disconnect
+        # This prevents _on_close from triggering service callback
+        with self._lock:
+            ws_app = self.ws_app
             self.ws_app = None
 
+        if ws_app:
+            ws_app.close()
+
         if self.ws_thread and self.ws_thread.is_alive():
             self.ws_thread.join(timeout=2)
             self.ws_thread = None
 
+        # Keep DB thread running - events preserved for reconnection
+        # DB cleanup happens in cleanup() on app exit only
+
+        self.connected.clear()
+        self.page_info = None
+
+    def cleanup(self) -> None:
+        """Shutdown DB thread and disconnect (call on app exit only).
+
+        This is the only place where DB thread should be stopped.
+        Events are lost when DB thread stops (in-memory database).
+        """
+        # Disconnect WebSocket if connected
+        if self.ws_app:
+            self.disconnect()
+
         # Shutdown database thread
         self._db_running = False
         self._db_work_queue.put(None)  # Signal shutdown
         if self._db_thread.is_alive():
             self._db_thread.join(timeout=2)
 
-        self.connected.clear()
-        self.page_info = None
-
     def send(self, method: str, params: dict | None = None) -> Future:
         """Send CDP command asynchronously.
 
@@ -351,15 +374,39 @@ class CDPSession:
 
     def _on_close(self, ws, code, reason):
         """Handle WebSocket closure and cleanup."""
-        logger.info(f"WebSocket closed: {code} {reason}")
+        logger.info(f"WebSocket closed: code={code} reason={reason}")
+
+        # Mark as disconnected
+        was_connected = self.connected.is_set()
         self.connected.clear()
 
-        # Fail pending commands
+        # Fail pending commands and check if this is unexpected disconnect
+        is_unexpected = False
         with self._lock:
             for future in self._pending.values():
-                future.set_exception(RuntimeError("Connection closed"))
+                future.set_exception(RuntimeError(f"Connection closed: {reason or 'Unknown'}"))
             self._pending.clear()
 
+            # Unexpected disconnect: was connected and ws_app still set (not manual disconnect)
+            is_unexpected = was_connected and self.ws_app is not None
+
+            # Clear state to allow reconnection (DB thread and events preserved)
+            self.ws_app = None
+            self.page_info = None
+
+        # Trigger service-level cleanup if this was unexpected
+        if is_unexpected and self._disconnect_callback:
+            try:
+                # Call in background to avoid blocking WebSocket thread
+                threading.Thread(
+                    target=self._disconnect_callback, args=(code, reason), daemon=True, name="cdp-disconnect-handler"
+                ).start()
+            except Exception as e:
+                logger.error(f"Error calling disconnect callback: {e}")
+
+        # Trigger SSE broadcast immediately
+        self._trigger_state_broadcast()
+
     def _extract_paths(self, obj, parent_key=""):
         """Extract all JSON paths from nested dict structure.
 
@@ -466,6 +513,18 @@ class CDPSession:
         """
         return self.connected.is_set()
 
+    def set_disconnect_callback(self, callback) -> None:
+        """Register callback for unexpected disconnect events.
+
+        Called when WebSocket closes externally (tab close, crash, etc).
+        NOT called on manual disconnect() to avoid duplicate cleanup.
+
+        Args:
+            callback: Function called with (code: int, reason: str)
+        """
+        self._disconnect_callback = callback
+        logger.debug("Disconnect callback registered")
+
     def register_event_callback(self, method: str, callback) -> None:
         """Register callback for specific CDP event.
 
@@ -532,21 +591,14 @@ class CDPSession:
         logger.debug("Broadcast queue set on CDPSession")
 
     def _trigger_state_broadcast(self) -> None:
-        """Trigger SSE broadcast with 1s debounce.
+        """Trigger SSE broadcast immediately.
 
-        Called after CDP events are stored. Debounces rapid-fire events
-        to avoid overwhelming SSE clients during heavy network activity.
+        Called after CDP events are stored. Queue naturally buffers rapid-fire events.
         """
         if not self._broadcast_queue:
             return
 
-        import time
-
-        now = time.time()
-        if now - self._last_broadcast_time > self._broadcast_debounce:
-            self._last_broadcast_time = now
-            try:
-                self._broadcast_queue.put_nowait({"type": "cdp_event"})
-                logger.debug("State broadcast triggered")
-            except Exception as e:
-                logger.debug(f"Failed to queue broadcast: {e}")
+        try:
+            self._broadcast_queue.put_nowait({"type": "cdp_event"})
+        except Exception as e:
+            logger.debug(f"Failed to queue broadcast: {e}")

webtap/commands/TIPS.md

@@ -12,13 +12,21 @@ All commands have these pre-imported (no imports needed!):
 ## Commands
 
 ### body
-Fetch and analyze HTTP response bodies with Python expressions.
+Fetch and analyze HTTP request or response bodies with Python expressions. Automatically detects event type.
 
 #### Examples
 ```python
-body(123)                                  # Get body
-body(123, "json.loads(body)")              # Parse JSON
+# Response bodies
+body(123)                                  # Get response body
+body(123, "json.loads(body)")              # Parse JSON response
 body(123, "bs4(body, 'html.parser').find('title').text")  # HTML title
+
+# Request bodies (POST/PUT/PATCH)
+body(456)                                  # Get request POST data
+body(456, "json.loads(body)")              # Parse JSON request body
+body(456, "json.loads(body)['customerId']")  # Extract request field
+
+# Analysis
 body(123, "jwt.decode(body, options={'verify_signature': False})")  # Decode JWT
 body(123, "re.findall(r'/api/[^\"\\s]+', body)[:10]")  # Find API endpoints
 body(123, "httpx.get(json.loads(body)['next_url']).json()")  # Chain requests
@@ -26,7 +34,10 @@ body(123, "msgpack.unpackb(body)")         # Binary formats
 ```
 
 #### Tips
+- **Auto-detect type:** Command automatically detects request vs response events
+- **Find request events:** `events({"method": "Network.requestWillBeSent", "url": "*WsJobCard/Post*"})` - POST requests
 - **Generate models:** `to_model({id}, "models/model.py", "Model")` - create Pydantic models from JSON
+- **Generate types:** `quicktype({id}, "types.ts", "Type")` - TypeScript/other languages
 - **Chain requests:** `body({id}, "httpx.get(json.loads(body)['next_url']).text[:100]")`
 - **Parse XML:** `body({id}, "ElementTree.fromstring(body).find('.//title').text")`
 - **Extract forms:** `body({id}, "[f['action'] for f in bs4(body, 'html.parser').find_all('form')]")`
@@ -34,22 +45,62 @@ body(123, "msgpack.unpackb(body)")         # Binary formats
 - **Find related:** `events({'requestId': request_id})` - related events
 
 ### to_model
-Generate Pydantic v2 models from JSON response bodies for reverse engineering APIs.
+Generate Pydantic v2 models from request or response bodies.
 
 #### Examples
 ```python
-to_model(123, "models/product.py", "Product")                              # Generate from full response
-to_model(123, "models/customers/group.py", "CustomerGroup", "Data[0]")     # Extract nested + domain structure
-to_model(123, "/tmp/item.py", "Item", "items[0]")                          # Extract array items
+# Response bodies
+to_model(123, "models/product.py", "Product")                              # Full response
+to_model(123, "models/customers/group.py", "CustomerGroup", json_path="data[0]")  # Extract nested
+
+# Request bodies (POST/PUT/PATCH)
+to_model(172, "models/form.py", "JobCardForm", expr="dict(urllib.parse.parse_qsl(body))")  # Form data
+to_model(180, "models/request.py", "CreateOrder")                          # JSON POST body
+
+# Advanced transformations
+to_model(123, "models/clean.py", "Clean", expr="{k: v for k, v in json.loads(body).items() if k != 'meta'}")
+to_model(123, "models/merged.py", "Merged", expr="{**json.loads(body), 'url': event['params']['response']['url']}")
 ```
 
 #### Tips
-- **Check structure first:** `body({id})` - preview JSON before generating
-- **Domain organization:** Use paths like `"models/customers/group.py"` for structure
-- **Extract nested data:** Use `json_path="Data[0]"` to extract specific objects
-- **Array items:** Extract first item with `json_path="items[0]"` for model generation
-- **Auto-cleanup:** Generated models use snake_case fields and modern type hints (list, dict, | None)
-- **Edit after:** Add `Field(alias="...")` manually for API field mapping
+- **Check structure:** `body({id})` - preview body before generating
+- **Find requests:** `events({"method": "Network.requestWillBeSent", "url": "*api/orders*"})` - locate POST events
+- **Form data:** `expr="dict(urllib.parse.parse_qsl(body))"` for application/x-www-form-urlencoded
+- **Nested extraction:** `json_path="data[0]"` for JSON with wrapper objects
+- **Custom transforms:** `expr` has `body` (str) and `event` (dict) variables available
+- **Organization:** Paths like `"models/customers/group.py"` create directory structure automatically
+- **Field mapping:** Add `Field(alias="...")` after generation for API field names
+
+### quicktype
+Generate types from request or response bodies. Supports TypeScript, Go, Rust, Python, and 10+ other languages.
+
+#### Examples
+```python
+# Response bodies
+quicktype(123, "types/User.ts", "User")                                    # TypeScript
+quicktype(123, "api.go", "ApiResponse")                                    # Go struct
+quicktype(123, "schema.json", "Schema")                                    # JSON Schema
+quicktype(123, "types.ts", "User", json_path="data[0]")                    # Extract nested
+
+# Request bodies (POST/PUT/PATCH)
+quicktype(172, "types/JobCard.ts", "JobCardForm", expr="dict(urllib.parse.parse_qsl(body))")  # Form data
+quicktype(180, "types/CreateOrder.ts", "CreateOrderRequest")               # JSON POST body
+
+# Advanced options
+quicktype(123, "types.ts", "User", options={"readonly": True})             # TypeScript readonly
+quicktype(123, "types.ts", "Clean", expr="{k: v for k, v in json.loads(body).items() if k != 'meta'}")
+```
+
+#### Tips
+- **Check structure:** `body({id})` - preview body before generating
+- **Find requests:** `events({"method": "Network.requestWillBeSent", "url": "*api*"})` - locate POST events
+- **Form data:** `expr="dict(urllib.parse.parse_qsl(body))"` for application/x-www-form-urlencoded
+- **Nested extraction:** `json_path="data[0]"` for JSON with wrapper objects
+- **Languages:** .ts/.go/.rs/.java/.kt/.swift/.cs/.cpp/.dart/.rb/.json extensions set language
+- **Options:** Dict keys map to CLI flags: `{"readonly": True}` → `--readonly`, `{"nice_property_names": True}` → `--nice-property-names`. See `quicktype --help` for language-specific flags
+- **Common options:** TypeScript: `{"readonly": True, "prefer_types": True}`, Go: `{"omit_empty": True}`, Python: `{"pydantic_base_model": True}`
+- **Install:** `npm install -g quicktype` if command not found
+- **Pydantic models:** Use `to_model({id}, "models/model.py", "Model")` for Pydantic v2 instead
 
 ### inspect
 Inspect CDP events with full Python debugging.
@@ -123,25 +174,54 @@ events({"level": "error"})                # Console errors
 - **Decode data:** `inspect({id}, "base64.b64decode(data.get('params', {}).get('body', ''))")`
 
 ### js
-Execute JavaScript in the browser with optional promise handling.
+Execute JavaScript in the browser. Uses fresh scope by default to avoid redeclaration errors.
+
+#### Scope Behavior
+**Default (fresh scope)** - Each call runs in isolation:
+```python
+js("const x = 1")    # ✓ x isolated
+js("const x = 2")    # ✓ No error, fresh scope
+```
+
+**Persistent scope** - Variables survive across calls:
+```python
+js("var data = {count: 0}", persist=True)    # data persists
+js("data.count++", persist=True)              # Modifies data
+js("data.count", persist=True)                # Returns 1
+```
+
+**With browser element** - Always fresh scope:
+```python
+js("element.offsetWidth", selection=1)       # Use element #1
+js("element.classList", selection=2)         # Use element #2
+```
 
 #### Examples
 ```python
+# Basic queries
 js("document.title")                           # Get page title
-js("document.body.innerText.length")           # Get text length
 js("[...document.links].map(a => a.href)")    # Get all links
-js("fetch('/api').then(r => r.json())", await_promise=True)  # Async
+js("document.body.innerText.length")           # Text length
+
+# Async operations
+js("fetch('/api').then(r => r.json())", await_promise=True)
+
+# DOM manipulation (no return)
 js("document.querySelectorAll('.ad').forEach(e => e.remove())", wait_return=False)
-js("window.fetch = new Proxy(window.fetch, {get: (t, p) => console.log(p)})", wait_return=False)
+
+# Persistent state for multi-step operations
+js("var apiData = null", persist=True)
+js("fetch('/api').then(r => r.json()).then(d => apiData = d)", persist=True, await_promise=True)
+js("apiData.users.length", persist=True)
 ```
 
 #### Tips
-- **Extract all links:** `js("[...document.links].map(a => a.href)")`
-- **Get page text:** `js("document.body.innerText")`
-- **Find data attributes:** `js("[...document.querySelectorAll('[data-id]')].map(e => e.dataset)")`
-- **Monitor DOM:** `js("new MutationObserver(console.log).observe(document, {childList: true, subtree: true})", wait_return=False)`
-- **Hook fetch:** `js("window.fetch = new Proxy(fetch, {apply: (t, _, a) => {console.log(a); return t(...a)}})", wait_return=False)`
+- **Fresh scope:** Default behavior prevents const/let redeclaration errors
+- **Persistent state:** Use `persist=True` for multi-step operations or global hooks
+- **No return needed:** Set `wait_return=False` for DOM manipulation or hooks
+- **Browser selections:** Use `selection=N` with browser() to operate on selected elements
 - **Check console:** `console()` - see logged messages from JS execution
+- **Hook fetch:** `js("window.fetch = new Proxy(fetch, {apply: (t, _, a) => {console.log(a); return t(...a)}})", persist=True, wait_return=False)`
 
 ### fetch
 Control request interception for debugging and modification.
@@ -172,6 +252,29 @@ Show paused requests and responses.
 - **Modify request:** `resume({id}, modifications={'url': '...'})`
 - **Fail request:** `fail({id}, 'BlockedByClient')` - block the request
 
+### page
+Get current page information and navigate.
+
+#### Tips
+- **Navigate:** `navigate("https://example.com")` - go to URL
+- **Reload:** `reload()` or `reload(ignore_cache=True)` - refresh page
+- **History:** `back()`, `forward()`, `history()` - navigate history
+- **Execute JS:** `js("document.title")` - run JavaScript in page
+- **Monitor traffic:** `network()` - see requests, `console()` - see messages
+- **Switch page:** `pages()` then `connect(page=N)` - change to another tab
+- **Full status:** `status()` - connection details and event count
+
+### pages
+List available Chrome pages and manage connections.
+
+#### Tips
+- **Connect to page:** `connect(page={index})` - connect by index number
+- **Connect by ID:** `connect(page_id="{page_id}")` - stable across tab reordering
+- **Switch pages:** Just call `connect()` again - no need to disconnect first
+- **Check status:** `status()` - see current connection and event count
+- **Reconnect:** If connection lost, select page and `connect()` again
+- **Find page:** Look for title/URL in table - index stays consistent
+
 ### selections
 Browser element selections with prompt and analysis.
 

webtap/commands/_builders.py

@@ -22,7 +22,7 @@ Examples:
 
 Available builders:
   - table_response() - Tables with headers, warnings, tips
-  - info_response() - Key-value pairs with optional heading
+  - info_response() - Key-value pairs with optional heading and tips
   - error_response() - Errors with suggestions
   - success_response() - Success messages with details
   - warning_response() - Warnings with suggestions
@@ -83,6 +83,7 @@ def info_response(
     title: str | None = None,
     fields: dict | None = None,
     extra: str | None = None,
+    tips: list[str] | None = None,
 ) -> dict:
     """Build info display with key-value pairs.
 
@@ -90,6 +91,7 @@ def info_response(
         title: Optional info title
         fields: Dict of field names to values
         extra: Optional extra content (raw markdown)
+        tips: Optional developer tips/guidance
     """
     elements = []
 
@@ -107,6 +109,10 @@ def info_response(
     if not elements:
         elements.append({"type": "text", "content": "_No information available_"})
 
+    if tips:
+        elements.append({"type": "heading", "content": "Next Steps", "level": 3})
+        elements.append({"type": "list", "items": tips})
+
     return {"elements": elements}