webtap-tool 0.3.0__tar.gz → 0.5.0__tar.gz

{webtap_tool-0.3.0 → webtap_tool-0.5.0}/CHANGELOG.md

@@ -15,15 +15,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+## [0.5.0] - 2025-10-09
+
+### Added
+- **Real-time SSE streaming**: API endpoint `/events` for Server-Sent Events broadcasting full state to extension
+- **Element selection**: CDP-native `Overlay.setInspectMode` with visual badges on page
+  - New `DOMService` for element inspection via CDP
+  - `selections()` command for viewing selected elements with preview and data extraction
+  - `content.js` for badge rendering on page
+  - Thread-safe selection processing via background ThreadPoolExecutor
+  - Auto-clear selections on disconnect and frame navigation
+- **Error state management**: Persistent error banner in extension with dismiss endpoint `/errors/dismiss`
+- **Broadcast queue**: Cross-thread signaling from WebSocket thread → FastAPI event loop via `asyncio.Queue`
+- **Progress indicators**: Extension shows pending count during async element selection
+- **Auto-refresh**: Page list updates on tab activate/create/remove/move events
+- **CDP event callbacks**: `register_event_callback()` system for real-time event handling
+- **js() element integration**: New `selection` parameter to run JavaScript on selected elements
+
+### Changed
+- **Extension architecture**: Migrated from popup (popup.html/popup.js) to side panel (sidepanel.html/sidepanel.js)
+- **State propagation**: Replaced 2-second polling with SSE streaming (<100ms latency vs 2s worst-case)
+- **API server**: Hybrid REST + SSE architecture with broadcast processor and graceful SSE client shutdown
+- **Page list**: Increased size from 6 to 15 rows, auto-highlights connected page
+- **CDP session**: Increased ping timeout from 10s to 20s, added 1-second debounce on event broadcasts
+- **Response builders**: Consolidated `_errors.py` functionality into `_builders.py` with enhanced helpers
+- **Cleanup flow**: `app.cleanup()` now calls `service.disconnect()` for proper state cleanup
+- **Thread safety**: All blocking CDP calls in API endpoints wrapped in `asyncio.to_thread()`
+- **Queue initialization**: Uses `threading.Event` for synchronization instead of sleep
+
+### Removed
+- **popup.html** and **popup.js**: Replaced by side panel architecture
+- **_errors.py**: Merged into `_builders.py` for cleaner response builder consolidation
+- **2-second polling**: Extension no longer polls `/status` endpoint
+
+## [0.4.0] - 2025-09-28
+
+### Added
+- Filter mode support: `include` and `exclude` modes for fine-grained request filtering
+- TypedDict for filter configuration ensuring type safety
+- Filter tip in `network()` command showing example usage
+- Markdown table display for filter categories replacing code blocks
+- CDP resource types documentation in filter command
+
+### Changed
+- **BREAKING**: Filter categories now require explicit `mode` field ("include" or "exclude")
+- **BREAKING**: Updated to ReplKit2 v0.12.0 - using `mcp_config` instead of `fastmcp` parameter
+- Filter core returns data (`get_categories_summary()`) instead of formatted strings
+- Presentation logic moved from FilterManager to command layer
+- Server command uses assistant prefill to prevent LLM commentary
+
+### Fixed
+- Alert element in network command now uses correct `message` field instead of `content`
+- Type annotations for optional parameters properly use `str | None`
+
+### Removed
+- Backward compatibility for filters without mode field
+- Emoji icons in filter display, using plain text indicators instead
+
 ## [0.3.0] - 2025-09-19
 
 ### Added
+- New `server` command for explicit API server management (start/stop/restart/status)
+- Server command implemented as MCP prompt returning markdown status information
 
 ### Changed
+- **BREAKING**: API server no longer starts automatically - must be started explicitly with `server('start')`
+- API server management is now explicit and user-controlled
 
 ### Fixed
 
 ### Removed
+- Automatic API server startup on webtap launch
+- `/release` endpoint from API (no longer needed with explicit server management)
 
 ## [0.2.4] - 2025-09-19
 

{webtap_tool-0.3.0 → webtap_tool-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webtap-tool
-Version: 0.3.0
+Version: 0.5.0
 Summary: Terminal-based web page inspector for AI debugging sessions
 Author-email: Fredrik Angelsen <fredrikangelsen@gmail.com>
 Classifier: Development Status :: 3 - Alpha
@@ -21,7 +21,7 @@ Requires-Dist: platformdirs>=4.4.0
 Requires-Dist: protobuf>=6.32.0
 Requires-Dist: pyjwt>=2.10.1
 Requires-Dist: pyyaml>=6.0.2
-Requires-Dist: replkit2[all]>=0.11.0
+Requires-Dist: replkit2[all]>=0.12.0
 Requires-Dist: requests>=2.32.4
 Requires-Dist: uvicorn>=0.35.0
 Requires-Dist: websocket-client>=1.8.0

webtap_tool-0.5.0/extension/content.js

@@ -0,0 +1,97 @@
+// WebTap Badge Renderer - Displays element selection badges only
+// All element selection logic moved to CDP backend
+
+console.log("[WebTap] Badge renderer loaded");
+
+// Track rendered badges - Map<selectionId, badgeElement>
+const renderedBadges = new Map();
+
+// Listen for badge updates from side panel
+chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
+  console.log("[WebTap] Received message:", msg.action);
+
+  if (msg.action === "ping") {
+    // Health check - respond immediately
+    sendResponse({ ready: true });
+  } else if (msg.action === "updateBadges") {
+    updateBadges(msg.selections);
+    sendResponse({ success: true });
+  } else if (msg.action === "clearBadges") {
+    clearAllBadges();
+    sendResponse({ success: true });
+  }
+
+  return true; // Keep channel open for async response
+});
+
+/**
+ * Update badges incrementally - add new, remove deleted
+ */
+function updateBadges(selections) {
+  const selectionIds = new Set(Object.keys(selections));
+
+  // Add new badges
+  Object.entries(selections).forEach(([id, data]) => {
+    if (!renderedBadges.has(id) && data.badge) {
+      const badge = createBadge(id, data.badge.x, data.badge.y);
+      renderedBadges.set(id, badge);
+    }
+  });
+
+  // Remove badges for deleted selections
+  renderedBadges.forEach((badge, id) => {
+    if (!selectionIds.has(id)) {
+      badge.remove();
+      renderedBadges.delete(id);
+    }
+  });
+
+  console.log(`[WebTap] Badges updated: ${renderedBadges.size} active`);
+}
+
+/**
+ * Create a badge element at specified position
+ */
+function createBadge(id, x, y) {
+  const badge = document.createElement("div");
+  badge.className = "webtap-badge";
+  badge.dataset.selectionId = id;
+  badge.textContent = `#${id}`;
+
+  // Position with scroll offset
+  badge.style.cssText = `
+    position: absolute;
+    top: ${y + window.scrollY}px;
+    left: ${x}px;
+    background: #4CAF50;
+    color: white;
+    padding: 4px 8px;
+    border-radius: 4px;
+    font: bold 12px monospace;
+    z-index: 2147483647;
+    pointer-events: none;
+    box-shadow: 0 2px 4px rgba(0,0,0,0.3);
+    transition: opacity 0.2s;
+  `;
+
+  document.body.appendChild(badge);
+  return badge;
+}
+
+/**
+ * Clear all badges from page
+ */
+function clearAllBadges() {
+  renderedBadges.forEach((badge) => {
+    if (badge.parentNode) {
+      badge.parentNode.removeChild(badge);
+    }
+  });
+  renderedBadges.clear();
+  console.log("[WebTap] All badges cleared");
+}
+
+// Clear badges on navigation
+window.addEventListener("beforeunload", () => {
+  clearAllBadges();
+});

webtap_tool-0.5.0/extension/manifest.json

@@ -0,0 +1,22 @@
+{
+  "manifest_version": 3,
+  "name": "WebTap DevTools",
+  "version": "0.2.0",
+  "description": "Chrome DevTools Protocol debugger via WebTap",
+  "permissions": ["activeTab", "tabs", "scripting", "sidePanel"],
+  "side_panel": {
+    "default_path": "sidepanel.html"
+  },
+  "action": {
+    "default_title": "WebTap - Open side panel"
+  },
+  "host_permissions": ["http://localhost:8765/*", "<all_urls>"],
+  "content_scripts": [
+    {
+      "matches": ["<all_urls>"],
+      "js": ["content.js"],
+      "run_at": "document_idle",
+      "all_frames": false
+    }
+  ]
+}

webtap_tool-0.5.0/extension/sidepanel.html

@@ -0,0 +1,317 @@
+<!doctype html>
+<html>
+  <head>
+    <style>
+      body {
+        margin: 0;
+        padding: 12px;
+        font-family:
+          system-ui,
+          -apple-system,
+          sans-serif;
+        font-size: 13px;
+      }
+      h3 {
+        margin: 0 0 12px 0;
+        font-size: 15px;
+      }
+      h4 {
+        margin: 12px 0 8px 0;
+        font-size: 13px;
+      }
+      select {
+        width: 100%;
+        padding: 6px;
+        margin-bottom: 8px;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        font-size: 12px;
+      }
+      button {
+        padding: 8px;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        background: white;
+        cursor: pointer;
+        font-size: 12px;
+      }
+      button:hover {
+        background: #f0f0f0;
+      }
+      button:disabled {
+        opacity: 0.5;
+        cursor: not-allowed;
+      }
+      .button-row {
+        display: flex;
+        gap: 5px;
+        margin-bottom: 8px;
+      }
+      .button-row button {
+        flex: 1;
+      }
+      #status {
+        padding: 8px;
+        font-size: 12px;
+        background: #f5f5f5;
+        border-radius: 4px;
+        margin-bottom: 8px;
+      }
+      .error {
+        color: #d00;
+      }
+      .connected {
+        color: #080;
+        font-weight: bold;
+      }
+      .divider {
+        border-top: 1px solid #ddd;
+        margin: 12px 0;
+      }
+      .fetch-row {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: 5px 0;
+      }
+      .fetch-status {
+        font-size: 12px;
+      }
+      .toggle {
+        background: #e0e0e0;
+        border: 1px solid #ccc;
+        border-radius: 4px;
+        padding: 4px 12px;
+        cursor: pointer;
+      }
+      .toggle.on {
+        background: #4caf50;
+        color: white;
+      }
+      .filter-section label {
+        display: block;
+        padding: 4px 0;
+        font-size: 12px;
+        cursor: pointer;
+      }
+      .filter-section input[type="checkbox"] {
+        margin-right: 6px;
+      }
+      .filter-count {
+        color: #666;
+        font-size: 11px;
+        margin-left: 4px;
+      }
+      .selection-list {
+        max-height: 150px;
+        overflow-y: auto;
+        margin: 8px 0;
+        border: 1px solid #ddd;
+        border-radius: 4px;
+        background: #fafafa;
+      }
+      .selection-item {
+        display: flex;
+        align-items: center;
+        padding: 6px 8px;
+        font-size: 11px;
+        border-bottom: 1px solid #eee;
+      }
+      .selection-item:last-child {
+        border-bottom: none;
+      }
+      .selection-badge {
+        background: #4caf50;
+        color: white;
+        padding: 2px 5px;
+        border-radius: 3px;
+        font-weight: bold;
+        margin-right: 8px;
+        font-size: 10px;
+      }
+      .selection-preview {
+        flex: 1;
+        color: #333;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+      .selection-remove {
+        background: #f44336;
+        color: white;
+        border: none;
+        padding: 2px 6px;
+        border-radius: 3px;
+        cursor: pointer;
+        font-size: 10px;
+      }
+      .selection-remove:hover {
+        background: #d32f2f;
+      }
+      .help-text {
+        font-size: 11px;
+        color: #666;
+        margin-top: 8px;
+        padding: 8px;
+        background: #f9f9f9;
+        border-radius: 4px;
+        border: 1px solid #e0e0e0;
+      }
+      .help-text code {
+        background: #e8e8e8;
+        padding: 2px 4px;
+        border-radius: 2px;
+        font-family: monospace;
+        font-size: 10px;
+      }
+      .error-banner {
+        display: none;
+        background: #ffebee;
+        border: 1px solid #ef5350;
+        border-radius: 4px;
+        padding: 10px;
+        margin-bottom: 12px;
+        font-size: 12px;
+      }
+      .error-banner.visible {
+        display: block;
+      }
+      .error-banner-header {
+        display: flex;
+        justify-content: space-between;
+        align-items: flex-start;
+      }
+      .error-banner-message {
+        color: #c62828;
+        flex: 1;
+        margin-right: 8px;
+      }
+      .error-banner-dismiss {
+        background: transparent;
+        border: none;
+        color: #c62828;
+        cursor: pointer;
+        padding: 0;
+        font-size: 16px;
+        line-height: 1;
+        font-weight: bold;
+      }
+      .error-banner-dismiss:hover {
+        color: #b71c1c;
+      }
+    </style>
+  </head>
+  <body>
+    <h3>WebTap DevTools</h3>
+
+    <div id="errorBanner" class="error-banner">
+      <div class="error-banner-header">
+        <div class="error-banner-message" id="errorMessage"></div>
+        <button
+          class="error-banner-dismiss"
+          id="dismissError"
+          title="Dismiss error"
+        >
+          ✕
+        </button>
+      </div>
+    </div>
+
+    <select id="pageList" size="15">
+      <option disabled>Loading pages...</option>
+    </select>
+
+    <div class="button-row">
+      <button id="connect">Connect</button>
+      <button id="disconnect">Disconnect</button>
+    </div>
+
+    <div id="status">Not connected</div>
+
+    <div class="divider"></div>
+
+    <div class="fetch-row">
+      <span class="fetch-status"
+        >Intercept: <span id="fetchStatus">OFF</span></span
+      >
+      <button id="fetchToggle" class="toggle">Toggle</button>
+    </div>
+
+    <div style="margin-top: 5px; font-size: 11px">
+      <label style="cursor: pointer">
+        <input type="checkbox" id="responseStage" style="margin-right: 4px" />
+        Also pause at Response stage
+      </label>
+    </div>
+
+    <div class="button-row" style="margin-top: 8px">
+      <button id="clear" style="width: 100%">Clear Events</button>
+    </div>
+
+    <div class="divider"></div>
+
+    <div class="filter-section">
+      <div
+        style="
+          display: flex;
+          justify-content: space-between;
+          align-items: center;
+        "
+      >
+        <h4 style="margin: 5px 0">Filters</h4>
+        <span id="filterStats" style="font-size: 11px; color: #666"
+          >Loading...</span
+        >
+      </div>
+      <div id="filterList" style="margin: 8px 0"></div>
+      <div class="button-row" style="margin-top: 8px">
+        <button id="enableAllFilters" style="font-size: 11px">
+          Enable All
+        </button>
+        <button id="disableAllFilters" style="font-size: 11px">
+          Disable All
+        </button>
+      </div>
+    </div>
+
+    <div class="divider"></div>
+
+    <div class="filter-section">
+      <h4 style="margin: 5px 0">Element Selection</h4>
+
+      <button id="startSelection" style="width: 100%; margin: 8px 0">
+        Start Selection Mode
+      </button>
+
+      <div id="selectionStatus" style="display: none">
+        <div
+          style="
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            margin-bottom: 4px;
+          "
+        >
+          <span style="font-size: 12px"
+            >Selected: <strong id="selectionCount">0</strong> elements</span
+          >
+          <button
+            id="clearSelections"
+            style="padding: 4px 8px; font-size: 11px"
+          >
+            Clear
+          </button>
+        </div>
+
+        <div id="selectionList" class="selection-list"></div>
+
+        <div class="help-text">
+          Use <code>@webtap:webtap://selections</code> in Claude Code prompts to
+          analyze selected elements. Reference elements as #1, #2, etc.
+        </div>
+      </div>
+    </div>
+
+    <script src="sidepanel.js"></script>
+  </body>
+</html>