webgpu-inspector-cli 0.1.0__py3-none-any.whl

webgpu_inspector_cli/js/collector.js

@@ -0,0 +1,439 @@
+/**
+ * collector.js - Injected into the page to collect WebGPU Inspector messages.
+ *
+ * Listens for __WebGPUInspector CustomEvents and accumulates GPU object state,
+ * validation errors, frame timing, and capture results. Exposes a query API
+ * on window.__wgi that the Python bridge calls via page.evaluate().
+ */
+(function () {
+  "use strict";
+
+  if (window.__wgi) return; // Already injected
+
+  // --- Action constants (mirrors src/utils/actions.js) ---
+  const Actions = {
+    AddObject: "webgpu_inspect_add_object",
+    DeleteObject: "webgpu_inspect_delete_object",
+    DeleteObjects: "webgpu_inspect_delete_objects",
+    ObjectSetLabel: "webgpu_inspect_object_set_label",
+    ResolveAsyncObject: "webgpu_inspect_resolve_async_object",
+    ValidationError: "webgpu_inspect_validation_error",
+    MemoryLeakWarning: "webgpu_inspect_memory_leak_warning",
+    DeltaTime: "webgpu_inspect_delta_time",
+    CaptureFrameResults: "webgpu_inspect_capture_frame_results",
+    CaptureFrameCommands: "webgpu_inspect_capture_frame_commands",
+    CaptureTextureData: "webgpu_inspect_capture_texture_data",
+    CaptureBufferData: "webgpu_inspect_capture_buffer_data",
+    CaptureTextureFrames: "webgpu_inspect_capture_texture_frames",
+    Recording: "webgpu_record_recording",
+  };
+
+  const PanelActions = {
+    RequestTexture: "webgpu_inspect_request_texture",
+    CompileShader: "webgpu_inspect_compile_shader",
+    RevertShader: "webgpu_inspect_revert_shader",
+    Capture: "webgpu_inspector_capture",
+    InitializeInspector: "webgpu_initialize_inspector",
+  };
+
+  // --- State ---
+  const objects = new Map(); // id -> { id, type, descriptor, label, stacktrace, parent, pending }
+  const errors = [];         // [{ id, objectId, message, stacktrace, timestamp }]
+  const memoryLeaks = [];
+  let errorCount = 0;
+  let deltaFrameTime = -1;
+  let totalTextureMemory = 0;
+  let totalBufferMemory = 0;
+
+  // Capture state
+  let captureStatus = "idle"; // "idle" | "pending" | "complete"
+  let capturedFrameResults = null;
+  let capturedCommands = null;
+  let capturedTextures = new Map(); // id -> { chunks: [], totalChunks, assembled }
+  let capturedBuffers = new Map();  // id -> { data }
+
+  // --- Texture memory calculation ---
+  const FORMAT_SIZES = {
+    "r8unorm": 1, "r8snorm": 1, "r8uint": 1, "r8sint": 1,
+    "r16uint": 2, "r16sint": 2, "r16float": 2,
+    "rg8unorm": 2, "rg8snorm": 2, "rg8uint": 2, "rg8sint": 2,
+    "r32uint": 4, "r32sint": 4, "r32float": 4,
+    "rg16uint": 4, "rg16sint": 4, "rg16float": 4,
+    "rgba8unorm": 4, "rgba8unorm-srgb": 4, "rgba8snorm": 4,
+    "rgba8uint": 4, "rgba8sint": 4,
+    "bgra8unorm": 4, "bgra8unorm-srgb": 4,
+    "rgb10a2uint": 4, "rgb10a2unorm": 4, "rg11b10ufloat": 4,
+    "rg32uint": 8, "rg32sint": 8, "rg32float": 8,
+    "rgba16uint": 8, "rgba16sint": 8, "rgba16float": 8,
+    "rgba32uint": 16, "rgba32sint": 16, "rgba32float": 16,
+    "depth16unorm": 2, "depth24plus": 4, "depth24plus-stencil8": 4,
+    "depth32float": 4, "depth32float-stencil8": 5,
+    "stencil8": 1,
+  };
+
+  function getTextureGpuSize(descriptor) {
+    if (!descriptor) return 0;
+    const format = descriptor.format;
+    const bpp = FORMAT_SIZES[format];
+    if (bpp === undefined) return 0;
+    const w = descriptor.size?.[0] ?? descriptor.size?.width ?? 1;
+    const h = descriptor.size?.[1] ?? descriptor.size?.height ?? 1;
+    const d = descriptor.size?.[2] ?? descriptor.size?.depthOrArrayLayers ?? 1;
+    const mips = descriptor.mipLevelCount ?? 1;
+    let total = 0;
+    for (let m = 0; m < mips; m++) {
+      const mw = Math.max(1, w >> m);
+      const mh = Math.max(1, h >> m);
+      total += mw * mh * d * bpp;
+    }
+    return total;
+  }
+
+  // --- Message handler ---
+  function handleMessage(detail) {
+    if (!detail || !detail.__webgpuInspector || !detail.__webgpuInspectorPage) {
+      return;
+    }
+    const action = detail.action;
+
+    switch (action) {
+      case Actions.AddObject: {
+        let descriptor = null;
+        try {
+          descriptor = detail.descriptor ? JSON.parse(detail.descriptor) : null;
+        } catch (e) {
+          descriptor = null;
+        }
+        const obj = {
+          id: detail.id,
+          type: detail.type,
+          descriptor: descriptor,
+          label: descriptor?.label || null,
+          stacktrace: detail.stacktrace || "",
+          parent: detail.parent ?? null,
+          pending: !!detail.pending,
+        };
+
+        // Track memory
+        if (detail.type === "Buffer") {
+          obj.size = descriptor?.size ?? 0;
+          totalBufferMemory += obj.size;
+        } else if (detail.type === "Texture") {
+          // If texture already exists (reconfigured), update it
+          const prev = objects.get(detail.id);
+          if (prev && prev.type === "Texture") {
+            totalTextureMemory -= prev.gpuSize || 0;
+          }
+          obj.gpuSize = getTextureGpuSize(descriptor);
+          totalTextureMemory += obj.gpuSize;
+        } else if (detail.type === "ShaderModule") {
+          obj.code = descriptor?.code || null;
+          obj.size = descriptor?.code?.length ?? 0;
+        }
+
+        objects.set(detail.id, obj);
+        break;
+      }
+
+      case Actions.DeleteObject: {
+        const obj = objects.get(detail.id);
+        if (obj) {
+          if (obj.type === "Buffer") totalBufferMemory -= obj.size || 0;
+          if (obj.type === "Texture") totalTextureMemory -= obj.gpuSize || 0;
+          objects.delete(detail.id);
+        }
+        break;
+      }
+
+      case Actions.DeleteObjects: {
+        const ids = detail.idList || [];
+        for (const id of ids) {
+          const obj = objects.get(id);
+          if (obj) {
+            if (obj.type === "Buffer") totalBufferMemory -= obj.size || 0;
+            if (obj.type === "Texture") totalTextureMemory -= obj.gpuSize || 0;
+            objects.delete(id);
+          }
+        }
+        break;
+      }
+
+      case Actions.ObjectSetLabel: {
+        const obj = objects.get(detail.id);
+        if (obj) obj.label = detail.label;
+        break;
+      }
+
+      case Actions.ResolveAsyncObject: {
+        const obj = objects.get(detail.id);
+        if (obj) obj.pending = false;
+        break;
+      }
+
+      case Actions.ValidationError: {
+        errorCount++;
+        errors.push({
+          id: errorCount,
+          objectId: detail.id ?? 0,
+          message: detail.message,
+          stacktrace: detail.stacktrace || "",
+          timestamp: Date.now(),
+        });
+        break;
+      }
+
+      case Actions.MemoryLeakWarning: {
+        memoryLeaks.push({
+          id: detail.id,
+          type: detail.type,
+          message: detail.message,
+          timestamp: Date.now(),
+        });
+        break;
+      }
+
+      case Actions.DeltaTime: {
+        deltaFrameTime = detail.deltaTime;
+        break;
+      }
+
+      case Actions.CaptureFrameResults: {
+        capturedFrameResults = {
+          frame: detail.frame,
+          count: detail.count,
+          batches: detail.batches,
+        };
+        captureStatus = "complete";
+        break;
+      }
+
+      case Actions.CaptureFrameCommands: {
+        capturedCommands = detail;
+        break;
+      }
+
+      case Actions.CaptureTextureData: {
+        const texId = detail.id;
+        if (!capturedTextures.has(texId)) {
+          capturedTextures.set(texId, { chunks: [], totalChunks: 0, complete: false });
+        }
+        const entry = capturedTextures.get(texId);
+        if (detail.index !== undefined) {
+          entry.chunks[detail.index] = detail.data;
+          entry.totalChunks = detail.count || entry.totalChunks;
+          // Check if all chunks received
+          const received = entry.chunks.filter(c => c !== undefined).length;
+          if (received >= entry.totalChunks && entry.totalChunks > 0) {
+            entry.complete = true;
+          }
+        } else {
+          // Single chunk
+          entry.chunks = [detail.data];
+          entry.totalChunks = 1;
+          entry.complete = true;
+        }
+        break;
+      }
+
+      case Actions.CaptureBufferData: {
+        const bufId = detail.id;
+        capturedBuffers.set(bufId, {
+          data: detail.data,
+          offset: detail.offset || 0,
+          size: detail.size || 0,
+        });
+        break;
+      }
+    }
+  }
+
+  // --- Listen for inspector messages ---
+  window.addEventListener("__WebGPUInspector", (event) => {
+    handleMessage(event.detail);
+  });
+
+  // --- Query API ---
+  window.__wgi = {
+    getObjects(type) {
+      const result = [];
+      for (const obj of objects.values()) {
+        if (!type || obj.type === type) {
+          result.push({
+            id: obj.id,
+            type: obj.type,
+            label: obj.label,
+            descriptor: obj.descriptor,
+            stacktrace: obj.stacktrace,
+            parent: obj.parent,
+            pending: obj.pending,
+            size: obj.size,
+            gpuSize: obj.gpuSize,
+          });
+        }
+      }
+      return result;
+    },
+
+    getObject(id) {
+      const obj = objects.get(id);
+      if (!obj) return null;
+      return {
+        id: obj.id,
+        type: obj.type,
+        label: obj.label,
+        descriptor: obj.descriptor,
+        stacktrace: obj.stacktrace,
+        parent: obj.parent,
+        pending: obj.pending,
+        size: obj.size,
+        gpuSize: obj.gpuSize,
+        code: obj.code,
+      };
+    },
+
+    getObjectCount() {
+      return objects.size;
+    },
+
+    getErrors() {
+      return errors.slice();
+    },
+
+    getErrorCount() {
+      return errors.length;
+    },
+
+    clearErrors() {
+      errors.length = 0;
+      errorCount = 0;
+    },
+
+    getFrameRate() {
+      if (deltaFrameTime <= 0) return { fps: 0, deltaTime: -1 };
+      return {
+        fps: Math.round(1000 / deltaFrameTime),
+        deltaTime: deltaFrameTime,
+      };
+    },
+
+    getMemoryUsage() {
+      return {
+        totalTextureMemory: totalTextureMemory,
+        totalBufferMemory: totalBufferMemory,
+        totalMemory: totalTextureMemory + totalBufferMemory,
+      };
+    },
+
+    getSummary() {
+      const typeCounts = {};
+      for (const obj of objects.values()) {
+        typeCounts[obj.type] = (typeCounts[obj.type] || 0) + 1;
+      }
+      const fr = deltaFrameTime > 0 ? Math.round(1000 / deltaFrameTime) : 0;
+      return {
+        objectCount: objects.size,
+        typeCounts: typeCounts,
+        errorCount: errors.length,
+        fps: fr,
+        deltaTime: deltaFrameTime,
+        totalTextureMemory: totalTextureMemory,
+        totalBufferMemory: totalBufferMemory,
+        totalMemory: totalTextureMemory + totalBufferMemory,
+      };
+    },
+
+    // --- Capture ---
+
+    requestCapture(options) {
+      captureStatus = "pending";
+      capturedFrameResults = null;
+      capturedCommands = null;
+      capturedTextures = new Map();
+      capturedBuffers = new Map();
+
+      const data = options || {};
+      window.dispatchEvent(new CustomEvent("__WebGPUInspector", {
+        detail: {
+          __webgpuInspector: true,
+          action: "webgpu_inspector_capture",
+          data: JSON.stringify(data),
+        }
+      }));
+      return true;
+    },
+
+    getCaptureStatus() {
+      return captureStatus;
+    },
+
+    getCapturedFrameResults() {
+      return capturedFrameResults;
+    },
+
+    getCapturedCommands() {
+      return capturedCommands;
+    },
+
+    requestTexture(id, mipLevel) {
+      window.dispatchEvent(new CustomEvent("__WebGPUInspector", {
+        detail: {
+          __webgpuInspector: true,
+          action: "webgpu_inspect_request_texture",
+          id: id,
+          mipLevel: mipLevel || 0,
+        }
+      }));
+      return true;
+    },
+
+    getTextureData(id) {
+      const entry = capturedTextures.get(id);
+      if (!entry) return null;
+      return {
+        complete: entry.complete,
+        totalChunks: entry.totalChunks,
+        receivedChunks: entry.chunks.filter(c => c !== undefined).length,
+        data: entry.complete ? entry.chunks.join("") : null,
+      };
+    },
+
+    getBufferData(id) {
+      return capturedBuffers.get(id) || null;
+    },
+
+    // --- Shaders ---
+
+    getShaderCode(id) {
+      const obj = objects.get(id);
+      if (!obj || obj.type !== "ShaderModule") return null;
+      return obj.code || (obj.descriptor?.code ?? null);
+    },
+
+    compileShader(id, code) {
+      window.dispatchEvent(new CustomEvent("__WebGPUInspector", {
+        detail: {
+          __webgpuInspector: true,
+          action: "webgpu_inspect_compile_shader",
+          id: id,
+          code: code,
+        }
+      }));
+      return true;
+    },
+
+    revertShader(id) {
+      window.dispatchEvent(new CustomEvent("__WebGPUInspector", {
+        detail: {
+          __webgpuInspector: true,
+          action: "webgpu_inspect_revert_shader",
+          id: id,
+        }
+      }));
+      return true;
+    },
+
+    getMemoryLeaks() {
+      return memoryLeaks.slice();
+    },
+  };
+})();

webgpu_inspector_cli/skills/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "webgpu-inspector-cli"
+description: "Debug WebGPU applications from the command line - inspect GPU objects, view shaders, capture frames, check validation errors"
+---
+
+# webgpu-inspector-cli
+
+CLI tool for debugging WebGPU applications. Launches a browser, injects the WebGPU Inspector, and provides commands to inspect GPU state.
+
+## Prerequisites
+
+```bash
+git clone --recurse-submodules https://github.com/scasekar/webgpu-inspector-cli
+cd webgpu-inspector-cli/agent-harness && pip install -e .
+python -m playwright install chromium
+```
+
+## Quick Start
+
+```bash
+# 1. Launch browser with your WebGPU app
+webgpu-inspector-cli browser launch --url https://your-app.com
+
+# 2. Check for problems
+webgpu-inspector-cli --json errors list
+webgpu-inspector-cli --json status summary
+
+# 3. Inspect GPU objects
+webgpu-inspector-cli --json objects list
+webgpu-inspector-cli --json objects inspect --id 8
+
+# 4. View shader code
+webgpu-inspector-cli shaders view --id 8
+
+# 5. Capture a frame
+webgpu-inspector-cli --json capture frame
+
+# 6. Clean up
+webgpu-inspector-cli browser close
+```
+
+## Command Groups
+
+### browser - Session lifecycle
+- `browser launch --url URL [--headless] [--gpu-backend BACKEND]`
+- `browser close`
+- `browser navigate --url URL`
+- `browser screenshot -o PATH`
+- `browser status`
+
+### objects - GPU object inspection
+- `objects list [--type TYPE]` - List all GPU objects (Adapter, Device, Buffer, Texture, ShaderModule, RenderPipeline, etc.)
+- `objects inspect --id ID` - Full details including descriptor and creation stacktrace
+- `objects search --label PATTERN` - Find objects by label
+- `objects memory` - GPU memory breakdown
+
+### capture - Frame capture
+- `capture frame [--timeout N]` - Capture next frame's GPU commands
+- `capture commands [--pass-index N]` - List commands from captured frame
+- `capture texture --id ID [-o PATH]` - Read texture pixels, optionally save as PNG
+- `capture buffer --id ID [--format hex|float32|uint32]` - Read buffer data
+
+### shaders - Shader inspection
+- `shaders list` - List all shader modules
+- `shaders view --id ID` - View WGSL source code
+- `shaders compile --id ID --file PATH` - Hot-replace shader code
+- `shaders revert --id ID` - Revert to original
+
+### errors - Validation errors
+- `errors list` - All validation errors with stacktraces
+- `errors watch [--timeout N]` - Stream errors in real-time
+- `errors clear` - Reset error history
+
+### status - Runtime monitoring
+- `status summary` - Object counts, memory, FPS, error count
+- `status fps` - Current frame rate
+- `status memory` - Memory breakdown
+
+## Agent Guidance
+
+- Always use `--json` flag for machine-readable output
+- Launch browser first with `browser launch --url URL`
+- Close browser when done with `browser close`
+- For debugging workflow: check `errors list` first, then `objects list` to understand GPU state
+- Shader IDs are integers - get them from `shaders list` before using `shaders view`
+- Frame capture is async - `capture frame` polls until complete (default 30s timeout)
+- Texture data can be saved as PNG with `capture texture --id ID -o output.png`

webgpu_inspector_cli/tests/test_core.py

@@ -0,0 +1,151 @@
+"""Unit tests for WebGPU Inspector CLI core modules."""
+
+import os
+import sys
+import json
+import pytest
+from pathlib import Path
+
+
+# --- Session Tests ---
+
+class TestSession:
+    def setup_method(self):
+        from webgpu_inspector_cli.core.session import Session
+        self.session = Session()
+
+    def test_push_pop_shader_edit(self):
+        self.session.push_shader_edit(1, "original code")
+        result = self.session.pop_shader_edit(1)
+        assert result == "original code"
+
+    def test_pop_empty_returns_none(self):
+        result = self.session.pop_shader_edit(999)
+        assert result is None
+
+    def test_clear_shader_edits(self):
+        self.session.push_shader_edit(1, "v1")
+        self.session.push_shader_edit(1, "v2")
+        self.session.clear_shader_edits(1)
+        assert not self.session.has_shader_edits(1)
+
+    def test_has_shader_edits(self):
+        assert not self.session.has_shader_edits(1)
+        self.session.push_shader_edit(1, "code")
+        assert self.session.has_shader_edits(1)
+
+    def test_multiple_edits_stack(self):
+        """Edits should pop in LIFO order."""
+        self.session.push_shader_edit(1, "v1")
+        self.session.push_shader_edit(1, "v2")
+        self.session.push_shader_edit(1, "v3")
+        assert self.session.pop_shader_edit(1) == "v3"
+        assert self.session.pop_shader_edit(1) == "v2"
+        assert self.session.pop_shader_edit(1) == "v1"
+        assert self.session.pop_shader_edit(1) is None
+
+    def test_separate_shader_histories(self):
+        """Different shader IDs should have independent histories."""
+        self.session.push_shader_edit(1, "shader1_v1")
+        self.session.push_shader_edit(2, "shader2_v1")
+        assert self.session.pop_shader_edit(1) == "shader1_v1"
+        assert self.session.pop_shader_edit(2) == "shader2_v1"
+
+
+# --- Bridge Path Resolution Tests ---
+
+class TestBridgePaths:
+    def test_find_inspector_js(self):
+        from webgpu_inspector_cli.core.bridge import _find_inspector_js
+        path = _find_inspector_js()
+        assert path.exists()
+        assert path.name == "webgpu_inspector_loader.js"
+
+    def test_find_collector_js(self):
+        from webgpu_inspector_cli.core.bridge import _find_collector_js
+        path = _find_collector_js()
+        assert path.exists()
+        assert path.name == "collector.js"
+
+    def test_bridge_not_connected(self):
+        from webgpu_inspector_cli.core.bridge import Bridge
+        bridge = Bridge()
+        assert not bridge.is_connected
+        with pytest.raises(RuntimeError, match="No browser session"):
+            bridge.query("getSummary")
+
+    def test_bridge_require_not_connected(self):
+        from webgpu_inspector_cli.core.bridge import require_bridge, Bridge
+        import webgpu_inspector_cli.core.bridge as bridge_mod
+        # Reset global singleton
+        bridge_mod._bridge = Bridge()
+        with pytest.raises(RuntimeError, match="No active browser session"):
+            require_bridge()
+        bridge_mod._bridge = None
+
+
+# --- Format Helpers Tests ---
+
+class TestFormatHelpers:
+    def test_format_bytes_zero(self):
+        from webgpu_inspector_cli.commands.objects import _format_bytes
+        assert _format_bytes(0) == "0 B"
+
+    def test_format_bytes_small(self):
+        from webgpu_inspector_cli.commands.objects import _format_bytes
+        assert _format_bytes(512) == "512 B"
+
+    def test_format_bytes_kb(self):
+        from webgpu_inspector_cli.commands.objects import _format_bytes
+        result = _format_bytes(2048)
+        assert "KB" in result
+
+    def test_format_bytes_mb(self):
+        from webgpu_inspector_cli.commands.objects import _format_bytes
+        result = _format_bytes(4608000)
+        assert "MB" in result
+
+    def test_format_bytes_none(self):
+        from webgpu_inspector_cli.commands.objects import _format_bytes
+        assert _format_bytes(None) == "0 B"
+
+
+# --- Collector JS Content Tests ---
+
+class TestCollectorJS:
+    def test_collector_js_exists_and_valid(self):
+        from webgpu_inspector_cli.core.bridge import _find_collector_js
+        path = _find_collector_js()
+        content = path.read_text()
+        # Check it defines window.__wgi
+        assert "window.__wgi" in content
+        # Check it handles key actions
+        assert "AddObject" in content
+        assert "DeleteObject" in content
+        assert "ValidationError" in content
+        assert "DeltaTime" in content
+        assert "CaptureFrameResults" in content
+
+    def test_collector_has_query_api(self):
+        from webgpu_inspector_cli.core.bridge import _find_collector_js
+        content = _find_collector_js().read_text()
+        # Check all query functions exist
+        for fn in ["getObjects", "getObject", "getErrors", "getFrameRate",
+                    "getMemoryUsage", "getSummary", "requestCapture",
+                    "getCaptureStatus", "getShaderCode", "compileShader",
+                    "revertShader"]:
+            assert fn in content, f"Missing query function: {fn}"
+
+
+# --- CLI Entry Point Tests ---
+
+class TestCLIStructure:
+    def test_cli_import(self):
+        from webgpu_inspector_cli.webgpu_inspector_cli import cli
+        assert cli is not None
+
+    def test_cli_has_commands(self):
+        from webgpu_inspector_cli.webgpu_inspector_cli import cli
+        command_names = set(cli.commands.keys())
+        expected = {"browser", "objects", "capture", "shaders", "errors", "status", "repl"}
+        assert expected.issubset(command_names)