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

webgpu_inspector_cli/commands/status.py

@@ -0,0 +1,79 @@
+"""Runtime monitoring commands."""
+
+import json
+import click
+
+from webgpu_inspector_cli.core.bridge import require_bridge
+
+
+def _format_bytes(n):
+    if n is None or n == 0:
+        return "0 B"
+    for unit in ("B", "KB", "MB", "GB"):
+        if abs(n) < 1024:
+            return f"{n:.1f} {unit}" if unit != "B" else f"{n} {unit}"
+        n /= 1024
+    return f"{n:.1f} TB"
+
+
+@click.group()
+def status():
+    """Runtime monitoring."""
+    pass
+
+
+@status.command()
+@click.pass_context
+def summary(ctx):
+    """Overall GPU state summary."""
+    bridge = require_bridge()
+    result = bridge.query("getSummary")
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps(result, indent=2))
+    else:
+        click.echo(f"Objects: {result['objectCount']}")
+        if result.get("typeCounts"):
+            for t, c in sorted(result["typeCounts"].items()):
+                click.echo(f"  {t}: {c}")
+        click.echo(f"Errors: {result['errorCount']}")
+        fps = result.get("fps", 0)
+        dt = result.get("deltaTime", -1)
+        if dt > 0:
+            click.echo(f"FPS: {fps} ({dt:.1f}ms)")
+        else:
+            click.echo("FPS: -- (no frame data)")
+        click.echo(f"Texture memory: {_format_bytes(result['totalTextureMemory'])}")
+        click.echo(f"Buffer memory:  {_format_bytes(result['totalBufferMemory'])}")
+        click.echo(f"Total memory:   {_format_bytes(result['totalMemory'])}")
+
+
+@status.command()
+@click.pass_context
+def fps(ctx):
+    """Show current frame rate."""
+    bridge = require_bridge()
+    result = bridge.query("getFrameRate")
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps(result))
+    else:
+        if result["deltaTime"] <= 0:
+            click.echo("FPS: -- (no frame data yet)")
+        else:
+            click.echo(f"FPS: {result['fps']} ({result['deltaTime']:.1f}ms per frame)")
+
+
+@status.command("memory")
+@click.pass_context
+def memory_cmd(ctx):
+    """Show GPU memory breakdown."""
+    bridge = require_bridge()
+    mem = bridge.query("getMemoryUsage")
+
+    if ctx.obj.get("json"):
+        click.echo(json.dumps(mem, indent=2))
+    else:
+        click.echo(f"Texture memory: {_format_bytes(mem['totalTextureMemory'])}")
+        click.echo(f"Buffer memory:  {_format_bytes(mem['totalBufferMemory'])}")
+        click.echo(f"Total:          {_format_bytes(mem['totalMemory'])}")

webgpu_inspector_cli/core/bridge.py

@@ -0,0 +1,189 @@
+"""Playwright CDP bridge for WebGPU Inspector injection and communication."""
+
+import json
+import os
+import time
+from pathlib import Path
+
+from playwright.sync_api import sync_playwright, Browser, Page, BrowserContext
+
+
+def _find_inspector_js():
+    """Locate the built webgpu_inspector_loader.js from the submodule."""
+    # Walk up from this file to find the repo root
+    pkg_dir = Path(__file__).resolve().parent.parent  # webgpu_inspector_cli/
+    repo_root = pkg_dir.parent.parent  # webgpu-inspector-cli/
+    loader_path = repo_root / "webgpu_inspector" / "extensions" / "chrome" / "webgpu_inspector_loader.js"
+    if loader_path.exists():
+        return loader_path
+    raise FileNotFoundError(
+        f"Could not find webgpu_inspector_loader.js at {loader_path}. "
+        "Make sure the webgpu_inspector submodule is initialized: "
+        "git submodule update --init"
+    )
+
+
+def _find_collector_js():
+    """Locate the collector.js script bundled with this package."""
+    js_dir = Path(__file__).resolve().parent.parent / "js"
+    collector_path = js_dir / "collector.js"
+    if collector_path.exists():
+        return collector_path
+    raise FileNotFoundError(f"Could not find collector.js at {collector_path}")
+
+
+class Bridge:
+    """Manages browser lifecycle, inspector injection, and communication."""
+
+    def __init__(self):
+        self._playwright = None
+        self._browser: Browser | None = None
+        self._context: BrowserContext | None = None
+        self._page: Page | None = None
+        self._inspector_injected = False
+
+    @property
+    def page(self) -> Page | None:
+        return self._page
+
+    @property
+    def is_connected(self) -> bool:
+        return self._page is not None and not self._page.is_closed()
+
+    def launch(self, url: str, headless: bool = False, gpu_backend: str | None = None):
+        """Launch browser, navigate to URL, and inject the inspector."""
+        self._playwright = sync_playwright().start()
+
+        args = [
+            "--enable-unsafe-webgpu",
+            "--enable-features=Vulkan",
+        ]
+        if gpu_backend:
+            args.append(f"--use-gl={gpu_backend}")
+
+        self._browser = self._playwright.chromium.launch(
+            headless=headless,
+            args=args,
+        )
+        self._context = self._browser.new_context()
+        self._page = self._context.new_page()
+        self._page.goto(url, wait_until="domcontentloaded")
+        self._inject()
+
+    def navigate(self, url: str):
+        """Navigate to a new URL and re-inject the inspector."""
+        if not self.is_connected:
+            raise RuntimeError("No browser session. Call launch() first.")
+        self._inspector_injected = False
+        self._page.goto(url, wait_until="domcontentloaded")
+        self._inject()
+
+    def close(self):
+        """Shut down the browser and clean up resources."""
+        if self._browser:
+            self._browser.close()
+            self._browser = None
+        if self._playwright:
+            self._playwright.stop()
+            self._playwright = None
+        self._page = None
+        self._context = None
+        self._inspector_injected = False
+
+    def screenshot(self, output_path: str, full_page: bool = False) -> str:
+        """Take a screenshot of the current page."""
+        if not self.is_connected:
+            raise RuntimeError("No browser session.")
+        self._page.screenshot(path=output_path, full_page=full_page)
+        return output_path
+
+    def _inject(self):
+        """Inject the inspector and collector scripts into the page."""
+        if self._inspector_injected:
+            return
+
+        # 1. Inject the built webgpu_inspector_loader.js
+        loader_js = _find_inspector_js().read_text()
+        self._page.evaluate(loader_js)
+
+        # 2. Inject our collector.js
+        collector_js = _find_collector_js().read_text()
+        self._page.evaluate(collector_js)
+
+        # 3. Dispatch the start_inspection event to activate the inspector
+        self._page.evaluate("""() => {
+            window.dispatchEvent(new CustomEvent("__WebGPUInspector", {
+                detail: {
+                    __webgpuInspector: true,
+                    action: "webgpu_inspector_start_inspection"
+                }
+            }));
+        }""")
+
+        self._inspector_injected = True
+
+    def query(self, fn_name: str, *args) -> object:
+        """Call a collector query function and return the result."""
+        if not self.is_connected:
+            raise RuntimeError("No browser session.")
+        args_json = json.dumps(args)
+        result = self._page.evaluate(f"() => window.__wgi.{fn_name}(...{args_json})")
+        return result
+
+    def send_action(self, action: str, data: dict | None = None):
+        """Dispatch a PanelAction to the inspector running in the page."""
+        if not self.is_connected:
+            raise RuntimeError("No browser session.")
+        message = {
+            "__webgpuInspector": True,
+            "action": action,
+        }
+        if data:
+            message.update(data)
+        self._page.evaluate("""(msg) => {
+            window.dispatchEvent(new CustomEvent("__WebGPUInspector", {
+                detail: msg
+            }));
+        }""", message)
+
+    def wait_for_condition(self, js_expression: str, timeout: float = 30.0) -> object:
+        """Wait for a JS expression to return a truthy value."""
+        if not self.is_connected:
+            raise RuntimeError("No browser session.")
+        self._page.wait_for_function(js_expression, timeout=timeout * 1000)
+        return self._page.evaluate(js_expression)
+
+    def get_browser_info(self) -> dict:
+        """Get browser and GPU information."""
+        if not self.is_connected:
+            raise RuntimeError("No browser session.")
+        return self._page.evaluate("""() => {
+            return {
+                url: window.location.href,
+                title: document.title,
+                userAgent: navigator.userAgent,
+                gpu: navigator.gpu ? 'available' : 'unavailable',
+            };
+        }""")
+
+
+# Singleton bridge instance shared across CLI commands
+_bridge: Bridge | None = None
+
+
+def get_bridge() -> Bridge:
+    """Get or create the global bridge instance."""
+    global _bridge
+    if _bridge is None:
+        _bridge = Bridge()
+    return _bridge
+
+
+def require_bridge() -> Bridge:
+    """Get the bridge, raising an error if no session is active."""
+    bridge = get_bridge()
+    if not bridge.is_connected:
+        raise RuntimeError(
+            "No active browser session. Run 'browser launch --url <URL>' first."
+        )
+    return bridge

webgpu_inspector_cli/core/session.py

@@ -0,0 +1,40 @@
+"""Session state management with undo/redo for shader edits."""
+
+
+class Session:
+    """Tracks mutable state (shader edits) for undo/redo support."""
+
+    def __init__(self):
+        # shader_id -> list of previous code versions (stack)
+        self._shader_history: dict[int, list[str]] = {}
+
+    def push_shader_edit(self, shader_id: int, original_code: str):
+        """Save the original code before a shader edit for undo."""
+        if shader_id not in self._shader_history:
+            self._shader_history[shader_id] = []
+        self._shader_history[shader_id].append(original_code)
+
+    def pop_shader_edit(self, shader_id: int) -> str | None:
+        """Pop the last saved code for undo. Returns None if no history."""
+        stack = self._shader_history.get(shader_id, [])
+        if stack:
+            return stack.pop()
+        return None
+
+    def clear_shader_edits(self, shader_id: int):
+        """Clear edit history for a shader."""
+        self._shader_history.pop(shader_id, None)
+
+    def has_shader_edits(self, shader_id: int) -> bool:
+        return bool(self._shader_history.get(shader_id))
+
+
+_session: Session | None = None
+
+
+def get_session() -> Session:
+    """Get or create the global session instance."""
+    global _session
+    if _session is None:
+        _session = Session()
+    return _session