devharness 0.8.0

package/build/window-sizing.d.ts

@@ -0,0 +1,26 @@
+import type { Page } from 'puppeteer-core';
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface SizeWindowResult {
+    /** The layout viewport the page ended up with. */
+    viewport: Size;
+    /** How the size was applied — emulation pins the page and hides window resizes. */
+    mode: 'window' | 'emulated';
+    /** Set when the window settled at a different size than asked for; the cause (display
+     *  bounds, a window-manager minimum, page zoom) is not distinguishable from here. */
+    clampedTo?: Size;
+}
+/**
+ * Resize the real OS window so the page's viewport becomes `target`.
+ *
+ * Not page.setViewport(): that is Emulation.setDeviceMetricsOverride, which paints the
+ * requested size into whatever window Chrome already has — anything wider renders off the
+ * frame while screenshots (reading the emulated surface) still look correct. The override
+ * also pins the viewport, so the page stops tracking window resizes.
+ *
+ * Headless has no window, so emulation is the only option there.
+ */
+export declare function sizeWindowToViewport(page: Page, target: Size, headless: boolean): Promise<SizeWindowResult>;
+//# sourceMappingURL=window-sizing.d.ts.map

package/build/window-sizing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-sizing.d.ts","sourceRoot":"","sources":["../src/window-sizing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,QAAQ,EAAE,IAAI,CAAC;IACf,mFAAmF;IACnF,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B;yFACqF;IACrF,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAuCD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,IAAI,EACZ,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,gBAAgB,CAAC,CA8C3B"}

package/build/window-sizing.js

@@ -0,0 +1,87 @@
+/**
+ * Chrome's window bounds are outer dimensions — they include the tab strip, the
+ * omnibox and the frame. The caller asks for a *viewport*, so the chrome around it
+ * has to be measured and added back.
+ */
+async function measureChrome(page) {
+    return page.evaluate(() => {
+        const w = globalThis.window;
+        return { width: w.outerWidth - w.innerWidth, height: w.outerHeight - w.innerHeight };
+    });
+}
+async function readViewport(page) {
+    return page.evaluate(() => {
+        const w = globalThis.window;
+        return { width: w.innerWidth, height: w.innerHeight };
+    });
+}
+/**
+ * Window managers apply bounds asynchronously (X11/Wayland) and macOS animates the
+ * restore from minimized, so a read taken straight after setWindowBounds can be
+ * mid-flight. Measuring the frame from a mid-flight outerWidth yields a wrong
+ * correction, so wait for two equal reads before trusting one.
+ */
+async function settledViewport(page, timeoutMs = 400, stepMs = 25) {
+    let previous = await readViewport(page);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await new Promise((resolve) => setTimeout(resolve, stepMs));
+        const next = await readViewport(page);
+        if (next.width === previous.width && next.height === previous.height)
+            return next;
+        previous = next;
+    }
+    return previous;
+}
+/**
+ * Resize the real OS window so the page's viewport becomes `target`.
+ *
+ * Not page.setViewport(): that is Emulation.setDeviceMetricsOverride, which paints the
+ * requested size into whatever window Chrome already has — anything wider renders off the
+ * frame while screenshots (reading the emulated surface) still look correct. The override
+ * also pins the viewport, so the page stops tracking window resizes.
+ *
+ * Headless has no window, so emulation is the only option there.
+ */
+export async function sizeWindowToViewport(page, target, headless) {
+    if (headless) {
+        await page.setViewport(target);
+        return { viewport: target, mode: 'emulated' };
+    }
+    const session = await page.createCDPSession();
+    try {
+        const { windowId } = (await session.send('Browser.getWindowForTarget'));
+        // A maximized, fullscreen or minimized window ignores bounds changes. The protocol
+        // rejects windowState combined with a size, so this has to be its own call.
+        await session.send('Browser.setWindowBounds', { windowId, bounds: { windowState: 'normal' } });
+        await settledViewport(page);
+        const chrome = await measureChrome(page);
+        await session.send('Browser.setWindowBounds', {
+            windowId,
+            bounds: {
+                width: target.width + chrome.width,
+                height: target.height + chrome.height,
+            },
+        });
+        // One correction pass: the frame measured before the resize can be stale once a
+        // scrollbar or bar settles. A single pass cannot oscillate.
+        let viewport = await settledViewport(page);
+        if (viewport.width !== target.width || viewport.height !== target.height) {
+            const correction = await measureChrome(page);
+            await session.send('Browser.setWindowBounds', {
+                windowId,
+                bounds: {
+                    width: target.width + correction.width,
+                    height: target.height + correction.height,
+                },
+            });
+            viewport = await settledViewport(page);
+        }
+        const clamped = viewport.width !== target.width || viewport.height !== target.height;
+        return { viewport, mode: 'window', clampedTo: clamped ? viewport : undefined };
+    }
+    finally {
+        await session.detach().catch(() => { });
+    }
+}
+//# sourceMappingURL=window-sizing.js.map

package/build/window-sizing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-sizing.js","sourceRoot":"","sources":["../src/window-sizing.ts"],"names":[],"mappings":"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"}

package/build/window-sizing.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tests for sizeWindowToViewport.
+ *
+ * These never launch Chrome. A fake window models the two facts the real thing
+ * imposes: bounds are outer dimensions, and the window manager may refuse a size.
+ */
+export {};
+//# sourceMappingURL=window-sizing.test.d.ts.map

package/build/window-sizing.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-sizing.test.d.ts","sourceRoot":"","sources":["../src/window-sizing.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/build/window-sizing.test.js

@@ -0,0 +1,113 @@
+/**
+ * Tests for sizeWindowToViewport.
+ *
+ * These never launch Chrome. A fake window models the two facts the real thing
+ * imposes: bounds are outer dimensions, and the window manager may refuse a size.
+ */
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { sizeWindowToViewport } from './window-sizing.js';
+function makeFake(options = {}) {
+    const chrome = options.chrome ?? { width: 0, height: 88 };
+    const state = {
+        outerWidth: 1000,
+        outerHeight: 800,
+        chrome,
+        sizedOnce: false,
+    };
+    const win = {
+        get outerWidth() { return state.outerWidth; },
+        get outerHeight() { return state.outerHeight; },
+        get innerWidth() { return state.outerWidth - state.chrome.width; },
+        get innerHeight() { return state.outerHeight - state.chrome.height; },
+    };
+    const sent = [];
+    const send = vi.fn(async (method, params) => {
+        sent.push({ method, params });
+        if (method === 'Browser.getWindowForTarget')
+            return { windowId: 7 };
+        if (method === 'Browser.setWindowBounds') {
+            const bounds = params?.bounds ?? {};
+            if (bounds.width !== undefined) {
+                const cap = options.maxOuter;
+                state.outerWidth = cap ? Math.min(bounds.width, cap.width) : bounds.width;
+                state.outerHeight = cap ? Math.min(bounds.height, cap.height) : bounds.height;
+                if (!state.sizedOnce && options.chromeAfterResize)
+                    state.chrome = options.chromeAfterResize;
+                state.sizedOnce = true;
+            }
+        }
+        return {};
+    });
+    const detach = vi.fn(async () => { });
+    const setViewport = vi.fn(async () => { });
+    const createCDPSession = vi.fn(async () => ({ send, detach }));
+    const page = {
+        setViewport,
+        createCDPSession,
+        evaluate: async (fn) => {
+            globalThis.window = win;
+            return fn();
+        },
+    };
+    const sizedBounds = () => sent.filter((c) => c.method === 'Browser.setWindowBounds' && c.params.bounds.width !== undefined);
+    return { page, sent, sizedBounds, send, detach, setViewport, createCDPSession };
+}
+afterEach(() => {
+    delete globalThis.window;
+});
+describe('sizeWindowToViewport', () => {
+    it('emulates in headless, where there is no window to size', async () => {
+        const fake = makeFake();
+        const result = await sizeWindowToViewport(fake.page, { width: 1280, height: 720 }, true);
+        expect(fake.setViewport).toHaveBeenCalledWith({ width: 1280, height: 720 });
+        expect(fake.createCDPSession).not.toHaveBeenCalled();
+        expect(result).toEqual({ viewport: { width: 1280, height: 720 }, mode: 'emulated' });
+    });
+    it('normalizes the window state before sizing it, in a separate call', async () => {
+        const fake = makeFake();
+        await sizeWindowToViewport(fake.page, { width: 1280, height: 720 }, false);
+        const bounds = fake.sent.filter((c) => c.method === 'Browser.setWindowBounds');
+        expect(fake.sent[0].method).toBe('Browser.getWindowForTarget');
+        expect(bounds[0].params.bounds).toEqual({ windowState: 'normal' });
+        expect(bounds[1].params.bounds.width).toBeDefined();
+    });
+    it('asks for the target plus the measured frame, and never emulates', async () => {
+        const fake = makeFake({ chrome: { width: 12, height: 88 } });
+        const result = await sizeWindowToViewport(fake.page, { width: 1280, height: 720 }, false);
+        expect(fake.sizedBounds()[0].params.bounds).toEqual({ width: 1292, height: 808 });
+        expect(fake.setViewport).not.toHaveBeenCalled();
+        expect(result).toEqual({ viewport: { width: 1280, height: 720 }, mode: 'window', clampedTo: undefined });
+    });
+    it('does not correct when the first size lands', async () => {
+        const fake = makeFake({ chrome: { width: 12, height: 88 } });
+        await sizeWindowToViewport(fake.page, { width: 1280, height: 720 }, false);
+        expect(fake.sizedBounds()).toHaveLength(1);
+    });
+    it('corrects once, re-measuring the frame that changed under it', async () => {
+        const fake = makeFake({
+            chrome: { width: 0, height: 88 },
+            chromeAfterResize: { width: 15, height: 100 },
+        });
+        const result = await sizeWindowToViewport(fake.page, { width: 1280, height: 720 }, false);
+        const sized = fake.sizedBounds();
+        expect(sized).toHaveLength(2);
+        expect(sized[0].params.bounds).toEqual({ width: 1280, height: 808 });
+        expect(sized[1].params.bounds).toEqual({ width: 1295, height: 820 });
+        expect(result.viewport).toEqual({ width: 1280, height: 720 });
+        expect(result.clampedTo).toBeUndefined();
+    });
+    it('reports the size it settled at when the window manager refuses', async () => {
+        const fake = makeFake({ chrome: { width: 0, height: 88 }, maxOuter: { width: 1000, height: 800 } });
+        const result = await sizeWindowToViewport(fake.page, { width: 1600, height: 1000 }, false);
+        expect(result.viewport).toEqual({ width: 1000, height: 712 });
+        expect(result.clampedTo).toEqual({ width: 1000, height: 712 });
+        expect(result.mode).toBe('window');
+    });
+    it('detaches the session even when the protocol throws', async () => {
+        const fake = makeFake();
+        fake.send.mockRejectedValueOnce(new Error('target closed'));
+        await expect(sizeWindowToViewport(fake.page, { width: 1280, height: 720 }, false)).rejects.toThrow('target closed');
+        expect(fake.detach).toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=window-sizing.test.js.map

package/build/window-sizing.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"window-sizing.test.js","sourceRoot":"","sources":["../src/window-sizing.test.ts"],"names":[],"mappings":"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"}

package/docs/README.md

@@ -0,0 +1,74 @@
+# devharness Documentation
+
+Chrome DevTools Protocol tools for AI-assisted debugging and browser automation.
+
+## Why Use devharness?
+
+Instead of just analyzing static code, AI assistants can now:
+- **Debug running applications in real-time** - Set breakpoints and inspect live state
+- **Observe actual runtime behavior** - See how your code actually executes
+- **Test and validate fixes immediately** - Make changes and verify them instantly
+- **Automate browser interactions** - Test UI flows and capture issues
+- **Provide insights based on live execution data** - Understand complex runtime scenarios
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Installation](./installation.md) | Setup for Claude Code, Claude Desktop, and from source |
+| [Debugging](./debugging.md) | Breakpoints, stepping, variables, call stacks, source maps |
+| [Automation](./automation.md) | Navigation, element interaction, screenshots, storage, server management |
+| [Replay](./replay.md) | Record interactions, replay sequences, export Playwright/Puppeteer tests |
+| [Troubleshooting](./troubleshooting.md) | Common issues and solutions |
+| [API Reference](./instructions.md) | Full tool reference and best practices (human-readable) |
+| [Message Templates](./messages.md) | Response format templates |
+
+### Agent Skill
+
+This package also ships an [Agent Skills](https://agentskills.io)-compatible skill at [`skills/devharness/`](../skills/devharness/SKILL.md), containing the same guidance as the API Reference above but structured for progressive disclosure. Copy or symlink it into a scanned skills directory (e.g. `.claude/skills/devharness` or `.agents/skills/devharness`) so Agent-Skills-aware clients load it only when a debugging task is actually underway, instead of paying the full token cost every session. The MCP server's own `instructions` field (`./mcp-instructions.md`) stays intentionally short for this reason - it's sent to every client on connect, whether or not that client supports Agent Skills.
+
+You don't have to set this up by hand: on startup, the server checks whether the skill is already installed anywhere a client would scan for it (project- or user-level, `.claude/skills/` or `.agents/skills/`). If it isn't found, the `instructions` payload asks the connected agent to offer installing it - the agent will propose the symlink command and only run it if you agree. Once installed, this nudge stops appearing.
+
+## Quick Start
+
+```bash
+# Claude Code CLI
+claude mcp add cdp-tools -- npx -y devharness
+```
+
+```javascript
+// Launch Chrome and start debugging
+launchChrome({ reference: 'my debug session' })
+navigate({ action: 'goto', url: 'http://localhost:3000', connectionReason: 'my-debug-session' })
+
+// Set a breakpoint
+breakpoint({ action: 'set', url: 'http://localhost:3000/app.js', lineNumber: 42, connectionReason: 'my-debug-session' })
+
+// When paused, inspect state
+inspect({ action: 'getCallStack', connectionReason: 'my-debug-session' })
+inspect({ action: 'getVariables', callFrameId: '0', connectionReason: 'my-debug-session' })
+```
+
+## Core Concepts
+
+### Connection Management
+
+devharness supports multiple simultaneous connections:
+
+- **Chrome connections**: Each browser tab can have its own connection
+- **Node.js connections**: Debug backend applications separately
+- **Connection references**: Use descriptive 3-word names (e.g., "user profile page")
+
+### Smart Element Caching
+
+When you navigate to a page, cdp-tools automatically:
+
+1. **Caches all clickable elements** - Links, buttons, and inputs are discovered and stored
+2. **Records viewport positions** - Tracks which elements are visible
+3. **Enables instant filtering** - Search cached elements without re-querying the DOM
+4. **Expires after 5 minutes** - Fresh data on subsequent navigations
+
+## Need Help?
+
+- Try the [Test Application](../examples/test-app/README.md) for hands-on practice
+- File issues at https://github.com/InDate/devharness/issues