webtap-tool 0.4.0__py3-none-any.whl → 0.5.1__py3-none-any.whl

webtap/commands/DEVELOPER_GUIDE.md

@@ -173,7 +173,7 @@ def command(state, param: int = 0)
 @app.command(display="markdown", fastmcp={"type": "resource", "mime_type": "text/markdown"})
 def pages(state) -> dict:
     """List available pages."""
-    return build_table_response(
+    return table_response(
         title="Chrome Pages",
         headers=["Index", "Title", "URL"],
         rows=rows,
@@ -187,7 +187,7 @@ def pages(state) -> dict:
 def navigate(state, url: str) -> dict:
     """Navigate to URL."""
     # Perform action
-    return build_info_response(
+    return info_response(
         title="Navigation Complete",
         fields={"URL": url, "Status": "Success"}
     )
@@ -195,37 +195,75 @@ def navigate(state, url: str) -> dict:
 
 ## Error Handling
 
-Always use the error utilities from `_errors.py`:
+Always use the error utilities from `_builders.py`:
 
 ```python
-from webtap.commands._errors import check_connection, error_response
+from webtap.commands._builders import check_connection, error_response
 
 def my_command(state, ...):
     # Check connection first for commands that need it
     if error := check_connection(state):
         return error
-    
+
     # Validate parameters
     if not valid:
-        return error_response("invalid_param", "Parameter X must be Y")
-    
-    # Custom errors
-    return error_response("custom", custom_message="Specific error message")
+        return error_response("Parameter X must be Y", suggestions=["Try this", "Or that"])
+
+    # Simple errors
+    return error_response("Specific error message")
 ```
 
-## Utility Functions
+## Response Builders
 
-Use helpers from `_utils.py`:
+Use builders from `_builders.py`:
 
 ```python
-from webtap.commands._utils import (
-    build_table_response,    # For tables
-    build_info_response,     # For key-value info
-    parse_options,          # Parse dict with defaults
-    extract_option,         # Extract single option
-    truncate_string,        # Truncate long strings
-    format_size,           # Format byte sizes
-    format_id,             # Format IDs
+from webtap.commands._builders import (
+    # Table responses
+    table_response,         # Tables with headers, warnings, tips
+
+    # Info displays
+    info_response,          # Key-value pairs with optional heading
+
+    # Status responses
+    error_response,         # Errors with suggestions
+    success_response,       # Success messages with details
+    warning_response,       # Warnings with suggestions
+
+    # Code results
+    code_result_response,   # Code execution with result display
+    code_response,          # Simple code block display
+
+    # Connection helpers
+    check_connection,       # Helper for CDP connection validation
+    check_fetch_enabled,    # Helper for fetch interception validation
+)
+```
+
+### Usage Examples
+
+```python
+# Table with tips
+return table_response(
+    title="Network Requests",
+    headers=["ID", "URL", "Status"],
+    rows=rows,
+    summary=f"{len(rows)} requests",
+    tips=["Use body(ID) to fetch response body"]
+)
+
+# Code execution result
+return code_result_response(
+    "JavaScript Result",
+    code="2 + 2",
+    language="javascript",
+    result=4
+)
+
+# Error with suggestions
+return error_response(
+    "Not connected to Chrome",
+    suggestions=["Run pages()", "Use connect(0)"]
 )
 ```
 
@@ -300,15 +338,63 @@ Use explicit text instead of symbols for clarity:
 4. **MCP mode**: Test with `webtap --mcp` command
 5. **Markdown rendering**: Verify output displays correctly
 
+## TIPS.md Integration
+
+All commands should be documented in `TIPS.md` for consistent help and MCP descriptions:
+
+```python
+from webtap.commands._tips import get_tips, get_mcp_description
+
+# Get MCP description (for fastmcp metadata)
+mcp_desc = get_mcp_description("mycommand")
+
+@app.command(
+    display="markdown",
+    fastmcp={"type": "tool", "description": mcp_desc} if mcp_desc else {"type": "tool"}
+)
+def mycommand(state, param: str) -> dict:
+    """My command description."""
+    # ... implementation ...
+
+    # Include tips in response
+    tips = get_tips("mycommand", context={"id": some_id})
+    return table_response(
+        headers=headers,
+        rows=rows,
+        tips=tips  # Automatically shown as "Next Steps"
+    )
+```
+
+### Adding to TIPS.md
+
+Add a section for your command:
+
+```markdown
+### mycommand
+Brief description of what the command does.
+
+#### Examples
+\```python
+mycommand("param1")              # Basic usage
+mycommand("param2", flag=True)   # With options
+\```
+
+#### Tips
+- **Related command:** `other_command()` - does related thing
+- **Advanced usage:** Use with `yet_another()` for X
+- **Context aware:** Tips support {id} placeholders from context dict
+```
+
 ## Checklist for New Commands
 
 - [ ] Use `@app.command()` decorator with `display="markdown"`
 - [ ] Add `fastmcp` metadata (type: "resource" or "tool")
 - [ ] Use simple types only (no unions, no Optional)
 - [ ] Add `# pyright: ignore[reportArgumentType]` for `dict = None`
-- [ ] Import utilities from `_utils.py` and `_errors.py`
-- [ ] Use `build_table_response()` or `build_info_response()`
+- [ ] Import builders from `_builders.py`
+- [ ] Use `table_response()`, `info_response()`, or `code_result_response()`
 - [ ] Check connection with `check_connection()` if needed
+- [ ] Add command section to `TIPS.md` with examples and tips
+- [ ] Use `get_tips()` to show tips in response
 - [ ] Document parameters clearly in docstring
-- [ ] Provide usage examples in docstring
 - [ ] Test in both REPL and MCP modes

webtap/commands/TIPS.md

@@ -150,4 +150,27 @@ Show paused requests and responses.
 - **Analyze body:** `body({id})` - fetch and examine response body
 - **Resume request:** `resume({id})` - continue the request
 - **Modify request:** `resume({id}, modifications={'url': '...'})`
-- **Fail request:** `fail({id}, 'BlockedByClient')` - block the request
+- **Fail request:** `fail({id}, 'BlockedByClient')` - block the request
+
+### selections
+Browser element selections with prompt and analysis.
+
+Access selected DOM elements and their properties via Python expressions. Elements are selected using the Chrome extension's selection mode.
+
+#### Examples
+```python
+selections()                                    # View all selections
+selections(expr="data['prompt']")              # Get prompt text
+selections(expr="data['selections']['1']")     # Get element #1 data
+selections(expr="data['selections']['1']['styles']")  # Get styles
+selections(expr="len(data['selections'])")     # Count selections
+selections(expr="{k: v['selector'] for k, v in data['selections'].items()}")  # All selectors
+```
+
+#### Tips
+- **Extract HTML:** `selections(expr="data['selections']['1']['outerHTML']")` - get element HTML
+- **Get CSS selector:** `selections(expr="data['selections']['1']['selector']")` - unique selector
+- **Use with js():** `js("element.offsetWidth", selection=1)` - integrate with JavaScript execution
+- **Access styles:** `selections(expr="data['selections']['1']['styles']['display']")` - computed CSS
+- **Get attributes:** `selections(expr="data['selections']['1']['preview']")` - tag, id, classes
+- **Inspect in prompts:** Use `@webtap:webtap://selections` resource in Claude Code for AI analysis

webtap/commands/_builders.py

@@ -1,4 +1,36 @@
-"""Response builders using ReplKit2 v0.10.0+ markdown elements."""
+"""Response builders using ReplKit2 v0.10.0+ markdown elements.
+
+USAGE GUIDELINES:
+
+Use builders for:
+  ✅ Simple responses (error, info, success, warning)
+  ✅ Tables with standard format
+  ✅ Code execution results
+  ✅ Repeated patterns across commands
+
+Use manual building for:
+  ❌ Complex multi-section layouts (>20 lines)
+  ❌ Conditional sections with deep nesting
+  ❌ Custom workflows (wizards, dashboards)
+  ❌ Dual-mode resource views with tutorials
+
+Examples:
+  - network() - Simple table → Use table_response()
+  - javascript() - Code result → Use code_result_response()
+  - server() - Custom dashboard → Manual OK
+  - selections() resource mode - Tutorial layout → Manual OK
+
+Available builders:
+  - table_response() - Tables with headers, warnings, tips
+  - info_response() - Key-value pairs with optional heading
+  - error_response() - Errors with suggestions
+  - success_response() - Success messages with details
+  - warning_response() - Warnings with suggestions
+  - check_connection() - Helper for CDP connection validation
+  - check_fetch_enabled() - Helper for fetch interception validation
+  - code_result_response() - Code execution with result display
+  - code_response() - Simple code block display
+"""
 
 from typing import Any
 
@@ -125,3 +157,109 @@ def warning_response(message: str, suggestions: list[str] | None = None) -> dict
         elements.append({"type": "list", "items": suggestions})
 
     return {"elements": elements}
+
+
+# Connection helpers
+
+
+def check_connection(state):
+    """Check CDP connection, return error response if not connected.
+
+    Returns error_response() if not connected, None otherwise.
+    Use pattern: `if error := check_connection(state): return error`
+
+    Args:
+        state: Application state containing CDP session.
+
+    Returns:
+        Error response dict if not connected, None if connected.
+    """
+    if not (state.cdp and state.cdp.is_connected):
+        return error_response(
+            "Not connected to Chrome",
+            suggestions=[
+                "Run `pages()` to see available tabs",
+                "Use `connect(0)` to connect to first tab",
+                "Or `connect(page_id='...')` for specific tab",
+            ],
+        )
+    return None
+
+
+def check_fetch_enabled(state):
+    """Check fetch interception, return error response if not enabled.
+
+    Args:
+        state: Application state containing fetch service.
+
+    Returns:
+        Error response dict if not enabled, None if enabled.
+    """
+    if not state.service.fetch.enabled:
+        return error_response(
+            "Fetch interception not enabled", suggestions=["Enable with `fetch('enable')` to pause requests"]
+        )
+    return None
+
+
+# Code result builders
+
+
+def code_result_response(
+    title: str,
+    code: str,
+    language: str,
+    result: Any = None,
+) -> dict:
+    """Build code execution result display.
+
+    Args:
+        title: Result heading (e.g. "JavaScript Result")
+        code: Source code executed
+        language: Syntax highlighting language
+        result: Execution result (supports dict/list/str/None)
+
+    Returns:
+        Markdown response with code and result
+    """
+    import json
+
+    elements = [
+        {"type": "heading", "content": title, "level": 2},
+        {"type": "code_block", "content": code, "language": language},
+    ]
+
+    if result is not None:
+        if isinstance(result, (dict, list)):
+            elements.append({"type": "code_block", "content": json.dumps(result, indent=2), "language": "json"})
+        else:
+            elements.append({"type": "text", "content": f"**Result:** `{result}`"})
+    else:
+        elements.append({"type": "text", "content": "**Result:** _(no return value)_"})
+
+    return {"elements": elements}
+
+
+def code_response(
+    content: str,
+    language: str = "",
+    title: str | None = None,
+) -> dict:
+    """Build simple code block response.
+
+    Args:
+        content: Code content to display
+        language: Syntax highlighting language
+        title: Optional heading above code block
+
+    Returns:
+        Markdown response with code block
+    """
+    elements = []
+
+    if title:
+        elements.append({"type": "heading", "content": title, "level": 2})
+
+    elements.append({"type": "code_block", "content": content, "language": language})
+
+    return {"elements": elements}

webtap/commands/body.py

@@ -3,8 +3,7 @@
 import json
 from webtap.app import app
 from webtap.commands._utils import evaluate_expression, format_expression_result
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import info_response, error_response
+from webtap.commands._builders import check_connection, info_response, error_response
 from webtap.commands._tips import get_mcp_description
 
 

webtap/commands/connection.py

@@ -1,8 +1,7 @@
 """Chrome browser connection management commands."""
 
 from webtap.app import app
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import info_response, table_response, error_response
+from webtap.commands._builders import check_connection, info_response, table_response, error_response
 
 
 @app.command(display="markdown", fastmcp={"type": "tool"})

webtap/commands/console.py

@@ -1,8 +1,7 @@
 """Browser console message monitoring and display commands."""
 
 from webtap.app import app
-from webtap.commands._builders import table_response
-from webtap.commands._errors import check_connection
+from webtap.commands._builders import check_connection, table_response
 from webtap.commands._tips import get_tips
 
 

webtap/commands/events.py

@@ -2,8 +2,7 @@
 
 from webtap.app import app
 from webtap.cdp import build_query
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import table_response
+from webtap.commands._builders import check_connection, table_response
 from webtap.commands._tips import get_tips, get_mcp_description
 
 

webtap/commands/fetch.py

@@ -1,8 +1,7 @@
 """HTTP fetch request interception and debugging commands."""
 
 from webtap.app import app
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import error_response, info_response, table_response
+from webtap.commands._builders import check_connection, error_response, info_response, table_response
 from webtap.commands._tips import get_tips
 
 

webtap/commands/inspect.py

@@ -4,8 +4,7 @@ import json
 
 from webtap.app import app
 from webtap.commands._utils import evaluate_expression, format_expression_result
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import error_response
+from webtap.commands._builders import check_connection, error_response
 from webtap.commands._tips import get_mcp_description
 
 

webtap/commands/javascript.py

@@ -1,9 +1,7 @@
 """JavaScript code execution in browser context."""
 
-import json
 from webtap.app import app
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import info_response, error_response
+from webtap.commands._builders import check_connection, info_response, error_response, code_result_response
 from webtap.commands._tips import get_mcp_description
 
 
@@ -17,35 +15,86 @@ mcp_desc = get_mcp_description("js")
     },
     fastmcp={"type": "tool", "description": mcp_desc} if mcp_desc else {"type": "tool"},
 )
-def js(state, code: str, wait_return: bool = True, await_promise: bool = False) -> dict:
-    """Execute JavaScript in the browser.
+def js(
+    state,
+    code: str,
+    selection: int = None,
+    persist: bool = False,
+    wait_return: bool = True,
+    await_promise: bool = False,
+) -> dict:  # pyright: ignore[reportArgumentType]
+    """Execute JavaScript in the browser with optional element selection.
 
     Args:
-        code: JavaScript code to execute
+        code: JavaScript code to execute (use 'element' variable if selection provided)
+        selection: Browser element selection number (e.g., 1 for #1) - makes element available
+        persist: Keep variables in global scope across calls (default: False, uses fresh scope)
         wait_return: Wait for and return result (default: True)
         await_promise: Await promises before returning (default: False)
 
     Examples:
+        # Default: fresh scope (no redeclaration errors)
+        js("const x = 1")                              # ✓ x isolated
+        js("const x = 2")                              # ✓ No error, fresh scope
         js("document.title")                           # Get page title
-        js("document.body.innerText.length")           # Get text length
-        js("console.log('test')", wait_return=False)   # Fire and forget
         js("[...document.links].map(a => a.href)")    # Get all links
 
+        # With browser element selection (always fresh scope)
+        js("element.offsetWidth", selection=1)         # Use element #1
+        js("element.classList", selection=2)           # Use element #2
+        js("element.getBoundingClientRect()", selection=1)
+
+        # Persistent scope: keep variables across calls
+        js("var data = fetch('/api')", persist=True)   # data persists
+        js("data.json()", persist=True)                # Access data from previous call
+
         # Async operations
         js("fetch('/api').then(r => r.json())", await_promise=True)
 
         # DOM manipulation (no return needed)
         js("document.querySelectorAll('.ad').forEach(e => e.remove())", wait_return=False)
 
-        # Install interceptors
-        js("window.fetch = new Proxy(window.fetch, {get: (t, p) => console.log(p)})", wait_return=False)
-
     Returns:
         The evaluated result if wait_return=True, otherwise execution status
     """
     if error := check_connection(state):
         return error
 
+    # Handle browser element selection
+    if selection is not None:
+        # Check if browser data exists
+        if not hasattr(state, "browser_data") or not state.browser_data:
+            return error_response(
+                "No browser selections available",
+                suggestions=[
+                    "Use browser() to select elements first",
+                    "Or omit the selection parameter to run code directly",
+                ],
+            )
+
+        # Get the jsPath for the selected element
+        selections = state.browser_data.get("selections", {})
+        sel_key = str(selection)
+
+        if sel_key not in selections:
+            available = ", ".join(selections.keys()) if selections else "none"
+            return error_response(
+                f"Selection #{selection} not found",
+                suggestions=[f"Available selections: {available}", "Use browser() to see all selections"],
+            )
+
+        js_path = selections[sel_key].get("jsPath")
+        if not js_path:
+            return error_response(f"Selection #{selection} has no jsPath")
+
+        # Wrap code with element variable in fresh scope (IIFE)
+        # Selection always uses fresh scope to avoid element redeclaration errors
+        code = f"(() => {{ const element = {js_path}; return ({code}); }})()"
+    elif not persist:
+        # Default: wrap in IIFE for fresh scope (avoids const/let redeclaration errors)
+        code = f"(() => {{ return ({code}); }})()"
+    # else: persist=True, use code as-is (global scope)
+
     result = state.cdp.execute(
         "Runtime.evaluate", {"expression": code, "returnByValue": wait_return, "awaitPromise": await_promise}
     )
@@ -60,23 +109,7 @@ def js(state, code: str, wait_return: bool = True, await_promise: bool = False)
     # Return based on wait_return flag
     if wait_return:
         value = result.get("result", {}).get("value")
-
-        # Format the result in markdown
-        elements = [
-            {"type": "heading", "content": "JavaScript Result", "level": 2},
-            {"type": "code_block", "content": code, "language": "javascript"},  # Full code
-        ]
-
-        # Add the result
-        if value is not None:
-            if isinstance(value, (dict, list)):
-                elements.append({"type": "code_block", "content": json.dumps(value, indent=2), "language": "json"})
-            else:
-                elements.append({"type": "text", "content": f"**Result:** `{value}`"})
-        else:
-            elements.append({"type": "text", "content": "**Result:** _(no return value)_"})
-
-        return {"elements": elements}
+        return code_result_response("JavaScript Result", code, "javascript", result=value)
     else:
         return info_response(
             title="JavaScript Execution",

webtap/commands/navigation.py

@@ -1,8 +1,7 @@
 """Browser page navigation and history commands."""
 
 from webtap.app import app
-from webtap.commands._errors import check_connection
-from webtap.commands._builders import info_response, table_response, error_response
+from webtap.commands._builders import check_connection, info_response, table_response, error_response
 
 
 @app.command(display="markdown", fastmcp={"type": "tool"})

webtap/commands/network.py

@@ -3,7 +3,7 @@
 from typing import List
 
 from webtap.app import app
-from webtap.commands._errors import check_connection
+from webtap.commands._builders import check_connection, table_response
 from webtap.commands._tips import get_tips
 
 
@@ -68,40 +68,22 @@ def network(state, limit: int = 20, filters: List[str] = None, no_filters: bool
     if limit and len(results) == limit:
         warnings.append(f"Showing first {limit} results (use limit parameter to see more)")
 
-    # Get tips from TIPS.md with context
-    tips = None
-    if rows:
-        example_id = rows[0]["ID"]
-        tips = get_tips("network", context={"id": example_id})
-
-    # Build response elements manually to add filter tip
-    elements = []
-    elements.append({"type": "heading", "content": "Network Requests", "level": 2})
-
-    for warning in warnings or []:
-        elements.append({"type": "alert", "message": warning, "level": "warning"})
+    # Get tips from TIPS.md with context, and add filter guidance
+    combined_tips = [
+        "Reduce noise with `filters()` - filter by type (XHR, Fetch) or domain (*/api/*)",
+    ]
 
     if rows:
-        elements.append(
-            {"type": "table", "headers": ["ID", "ReqID", "Method", "Status", "URL", "Type", "Size"], "rows": rows}
-        )
-    else:
-        elements.append({"type": "text", "content": "_No data available_"})
-
-    if f"{len(rows)} requests":
-        elements.append({"type": "text", "content": f"_{len(rows)} requests_"})
-
-    # Always show filter tip demonstrating both type AND domain filtering
-    elements.append(
-        {
-            "type": "alert",
-            "message": "Tip: Reduce noise with filters by type or domain. Example: `filters('update', {'category': 'api-only', 'mode': 'include', 'types': ['XHR', 'Fetch'], 'domains': ['*/api/*', '*/graphql/*']})`",
-            "level": "info",
-        }
+        example_id = rows[0]["ID"]
+        context_tips = get_tips("network", context={"id": example_id})
+        if context_tips:
+            combined_tips.extend(context_tips)
+
+    return table_response(
+        title="Network Requests",
+        headers=["ID", "ReqID", "Method", "Status", "URL", "Type", "Size"],
+        rows=rows,
+        summary=f"{len(rows)} requests" if rows else None,
+        warnings=warnings,
+        tips=combined_tips,
     )
-
-    if tips:
-        elements.append({"type": "heading", "content": "Next Steps", "level": 3})
-        elements.append({"type": "list", "items": tips})
-
-    return {"elements": elements}