framewatch-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FrameWatch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,537 @@
+# FrameWatch MCP Server
+
+> An MCP server that gives AI coding agents visual eyes — smart frame capture, diffing, and interaction replay for web apps.
+
+An AI coding agent can write a CSS transition but not watch it run. It can read the DOM but not see that the modal opened behind the header. FrameWatch closes that gap: it launches a real (headless Chromium) browser and returns what it sees as images an MCP client such as Claude Code looks at natively — alongside the console output, network requests, DOM mutations and paint timings from the same moment.
+
+The problem with screenshots as a debugging tool is volume. A five-second recording at 10fps is fifty near-identical images, and fifty images is a flooded context window. So FrameWatch records everything and returns almost none of it: only the frames where something meaningful actually changed, each cropped to the region that changed, each carrying the context that explains why.
+
+| Tool | Use it for |
+| --- | --- |
+| [`framewatch_screenshot`](#framewatch_screenshot) | What does this page look like right now? |
+| [`framewatch_capture`](#framewatch_capture) | What happens over the next few seconds — animations, loading, a replayed user flow? |
+| [`framewatch_interact`](#framewatch_interact) | Click this, then let me look; then click the next thing. |
+| [`framewatch_responsive`](#framewatch_responsive) | Does it hold up at phone, tablet and desktop widths? |
+| [`framewatch_accessibility`](#framewatch_accessibility) | What would an accessibility auditor flag? |
+| [`framewatch_compare`](#framewatch_compare) | What changed between before and after? |
+| [`framewatch_start_server`](#framewatch_start_server--framewatch_stop_server) / [`framewatch_stop_server`](#framewatch_start_server--framewatch_stop_server) | Get the dev server up so there is something to point at. |
+
+## Install
+
+```bash
+# Run directly
+npx framewatch-mcp-server
+
+# Register with Claude Code
+claude mcp add framewatch npx framewatch-mcp-server
+```
+
+From a checkout:
+
+```bash
+npm install
+npm run build
+claude mcp add framewatch node /absolute/path/to/framewatch/dist/index.js
+```
+
+### Requirements
+
+- **Node 20.9+**.
+- **Chromium**, via Playwright. `npm install` normally fetches it; if it did not, run `npx playwright install chromium` once. Every tool detects a missing browser and answers with that exact command rather than a stack trace.
+- **No network access needed** beyond whatever the pages under test require — FrameWatch only ever talks to the URLs it is given.
+
+FrameWatch speaks stdio only, and the client spawns it: nothing listens on a port, and there is nothing to configure beyond the line above.
+
+## Tools
+
+### `framewatch_screenshot`
+
+Take a single screenshot of a page (or of one element on it). Returns a PNG image content block (resized to max 800px wide) plus a one-line text summary.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | string (URL) | — | Page to screenshot, e.g. `http://localhost:3000` |
+| `wait_ms` | integer | `1000` | Wait after page load before capturing |
+| `viewport` | `{ width, height }` | `1280×720` | Viewport size |
+| `selector` | string | — | CSS selector: screenshot only this element |
+| `wait_for` | string | — | CSS selector to wait for (visible) before capturing |
+| `wait_for_timeout_ms` | integer ≥ 1 | `10000` | Max wait for `wait_for` / `selector` |
+
+**Example call** — the whole page, then one element of it:
+
+```json
+{ "url": "http://localhost:3000/pricing", "wait_ms": 1500 }
+```
+```json
+{ "url": "http://localhost:3000/pricing", "selector": ".plan-card--pro", "wait_for": ".plan-card--pro" }
+```
+
+Failures (unreachable URL, selector never appears, invalid input) come back as MCP error results with a readable message rather than crashing the server. Error pages still produce a screenshot, with the HTTP status noted in the summary.
+
+### `framewatch_capture`
+
+Record a page for a few seconds and return only the frames where something meaningful changed. Each kept frame is a *diff card*: the full frame as a PNG (max 800px wide), a metadata line, and a crop of the changed region with its position. Good for animations, splash/loading screens, transitions, and anything else that changes over time.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | string (URL) | — | Page to record, e.g. `http://localhost:3000` |
+| `duration_ms` | integer 500–30000 | `5000` | How long to record |
+| `sensitivity` | number 0–1 | `0.06` | Change threshold per frame: fraction of an 8×8 grid that must change (`0` keeps every frame, `1` keeps none beyond first/last) |
+| `max_frames` | integer 1–30 | `20` | Maximum diff cards to return |
+| `interval_ms` | integer 16–2000 | `100` | Raw frame capture interval (100 = 10 fps) |
+| `viewport` | `{ width, height }` | `1280×720` | Viewport size |
+| `wait_for` | string | — | CSS selector to wait for (visible) before recording starts |
+| `wait_for_timeout_ms` | integer ≥ 1 | `10000` | Max wait for `wait_for` |
+| `interactions` | array (≤ 50) | — | Interaction script to replay while recording (see below) |
+| `interaction_timeout_ms` | integer ≥ 1 | `10000` | Max time one step may wait for its target element |
+| `include_console` | boolean | `true` | Attach console output and uncaught errors (see [Context layers](#context-layers)) |
+| `include_network` | boolean | `false` | Attach network requests |
+| `include_dom` | boolean | `false` | Attach a summary of the DOM mutations between frames |
+| `include_performance` | boolean | `false` | Attach paint timing, LCP and layout shifts |
+
+**Example call** — record a splash screen, keeping more frames than usual because the interesting parts of an animation are small:
+
+```json
+{ "url": "http://localhost:3000", "duration_ms": 5000, "sensitivity": 0.04, "include_console": true }
+```
+
+Recording starts as soon as the navigation commits (not after `load`), so loading and splash animations are captured from their first frame.
+
+Returns one summary text block (`Captured 5 meaningful frames from 26 raw frames (2514ms recording) of http://… — "Title"`), then for each card:
+
+1. the full frame as a PNG image block;
+2. a text block, e.g. `Frame 2 @ 501ms [animation]` followed by `Changed: 20.0% — region: 80,40 240x160` (percentage of pixels that changed versus the previous card, and the padded bounding box in full-resolution viewport coordinates);
+3. a PNG crop of that region — omitted when the change covers nearly the whole frame.
+
+Which raw frames become cards:
+
+- the first frame (`[initial]`) and the last frame are always kept;
+- a frame is kept when more than `sensitivity` of the 8×8 grid cells differ from the last kept frame (compared at 320×240 grayscale);
+- frames the recorder captured because of an event (e.g. a `[navigation]`) are always kept;
+- kept frames closer than 200ms are merged, keeping the later, settled one — a continuous animation is thinned to roughly every 200ms;
+- if there are still more than `max_frames`, the first, last and event frames are kept and the rest are sampled evenly by position among the remaining kept frames.
+
+The recorder bounds every screenshot, because Chromium blocks them while a navigation is pending or the main thread is busy. A navigation tags the next frame the loop captures rather than requesting an extra screenshot at commit time — that frame reliably shows the new page, and a `history.replaceState` on every animation frame (the usual scroll-spy or router pattern) cannot flood the recording. Fragment-only URL changes are not treated as navigations, and a crashed or closed page ends the recording early with the frames captured so far.
+
+Failures come back as MCP error results, like `framewatch_screenshot`.
+
+#### Context layers
+
+A frame tells you *that* something changed. The context layers tell you *why*. Each one collects timestamped events while the page records, and each diff card is given the events from its own window — everything after the previous card, up to and including its own timestamp. All four start collecting **before** the navigation, so a script that throws on load, the request that never comes back and first paint all land on the first card instead of being missed.
+
+| Layer | Flag | What lands on a card |
+| --- | --- | --- |
+| Console | `include_console` (on) | `console.*` calls, uncaught exceptions, unhandled rejections, and the tab crashing |
+| Network | `include_network` | One line per request that settled — method, url, status, duration — plus any still in flight when the recording ended |
+| DOM | `include_dom` | Grouped mutations: elements added, removed, restyled, and text edited |
+| Performance | `include_performance` | First Contentful Paint, Largest Contentful Paint, and layout shifts with their summed score |
+
+```
+Frame 3 @ 1204ms [interaction]
+Changed: 12.4% — region: 40,220 320x180
+Console:
+  [error] TypeError: Cannot read properties of null (reading 'id') (at submit (http://localhost:3000/app.js:88:14))
+Network:
+  POST http://localhost:3000/api/login → 500 (312ms)
+  GET http://localhost:3000/api/me → pending (1204ms)
+Performance:
+  layout shifts 2 (score 0.1875)
+DOM:
+  + div.error-banner in form#login
+  ~ button#submit [disabled]
+  ~ #spinner [style] ×18
+```
+
+Paint and LCP are reported in milliseconds since that document's navigation start (the same numbers Lighthouse gives), and only on the card where they were measured — a value that never changes is not repeated down the page. Layout shifts are counted whether or not they followed user input, unlike Chrome's CLS: a jump right after a click is often the one being hunted.
+
+Console and network are Playwright events, so they survive a page that has frozen, navigated away or crashed. The DOM and performance layers inject an observer that pushes what it sees back out as it goes, so a navigation mid-recording does not take the old document's records with it. Both skip subframes, and the DOM layer ignores `<head>`, script/link/meta elements and whitespace-only text — none of it says anything about what the page looks like.
+
+Every layer is capped so one page cannot flood the response: console keeps 100 entries and network 100 events, evicting ordinary ones to make room for errors and failures; the DOM keeps 500 mutations and renders at most 12 lines per card. The summary says what was collected and what had to be dropped:
+
+```
+Context — console: 12 entries; network: 8 requests (1 still pending); DOM: 340 mutations
+DOM log was capped — 51 mutations dropped.
+```
+
+#### Replaying an interaction script
+
+Pass `interactions` to drive the page while it records. Each step is `{ action, ... }`, where `delay_ms` is a wait **before** that action, so the delays accumulate over the recording:
+
+```json
+{
+  "url": "http://localhost:3000/login",
+  "duration_ms": 8000,
+  "interactions": [
+    { "action": "type",  "selector": "#email",    "value": "test@example.com", "delay_ms": 1000 },
+    { "action": "type",  "selector": "#password", "value": "password123",      "delay_ms": 500 },
+    { "action": "click", "selector": "button[type=submit]",                    "delay_ms": 500 },
+    { "action": "wait",                                                        "delay_ms": 3000 }
+  ]
+}
+```
+
+`framewatch_capture` accepts `click`, `tap`, `type`, `scroll`, `swipe`, `wait` and `navigate`. A frame is forced right after every step, so the result of each action is always kept as an `[interaction]` card. The summary gains a line such as:
+
+```
+Interactions: 4/4 replayed — type "test@example.com" into "#email", type "password123" into "#password", click "button[type=submit]", wait 3000ms
+```
+
+Typed values are echoed in that line (elided only when long) and are visible in the frames themselves, so drive these flows with throwaway test credentials — a real password ends up in the tool output and therefore in the model's context.
+
+A step that fails ends the script but **not** the capture — the frames recorded up to that point are the most useful thing FrameWatch can hand back, since they show the state the page was actually in. The failure is reported in the summary and the moment it happened is kept as an `[error]` card:
+
+```
+Interactions: 1/3 replayed — click "#btn". Step 2: click "#nope" failed: locator.click: Timeout 10000ms exceeded.
+```
+
+Touch is enabled automatically (and only) for scripts containing `tap` or `swipe`, because `hasTouch` puts `ontouchstart` on `window` and would otherwise change what a plain capture records. A `swipe` is dispatched as a real finger drag — `touchstart`, ten `touchmove`s about a frame apart, `touchend` — so velocity-sensitive UI (carousels, pull-to-refresh) behaves as it would under a thumb.
+
+### `framewatch_interact`
+
+Perform **one** interaction and see what it did: before frame, after frame, and a crop of the change. Unlike the other tools this one is stateful on purpose — the page stays open between calls, so you can click, look, type, and look again without replaying the whole flow.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `action` | enum | — | `click`, `tap`, `type`, `scroll`, `swipe`, `navigate`, `select`, `hover` |
+| `selector` | string | — | CSS selector for the target |
+| `value` | string | — | Text to type, option to select, or URL to navigate to |
+| `x`, `y` | number | — | Coordinates for `click`/`tap`/`swipe` when no selector is given |
+| `delta_x`, `delta_y` | number | — | Distance for `scroll` / `swipe` |
+| `url` | string (URL) | — | Open this page first. Omit to act on the page left open by the previous call. |
+| `wait_ms` | integer ≥ 0 | `500` | Settle time after the action, before the "after" screenshot |
+| `timeout_ms` | integer ≥ 1 | `10000` | Max wait for the target element |
+| `viewport` | `{ width, height }` | — | Resize the page (omit to leave it as it is) |
+| `include_console` | boolean | `true` | Report console output and uncaught errors the action caused |
+| `include_network` | boolean | `false` | Report network requests the action caused |
+| `include_dom` | boolean | `false` | Report the DOM mutations the action caused |
+| `include_performance` | boolean | `false` | Report paint timing and layout shifts around the action |
+
+**Example call** — a session, one call at a time. Only the first needs a `url`:
+
+```json
+{ "url": "http://localhost:3000/settings", "action": "click", "selector": "nav a[href='/settings/billing']" }
+```
+```json
+{ "action": "type", "selector": "#card-number", "value": "4242424242424242" }
+```
+```json
+{ "action": "click", "selector": "button[type=submit]", "wait_ms": 1500, "include_network": true }
+```
+
+Returns a summary line (`click "#btn" on http://localhost:3000/ — 8.4% of the frame changed`), the before frame, the after frame with its `Changed: …` metadata, and a crop of the changed region.
+
+The same [context layers](#context-layers) as `framewatch_capture` are available here, split over the two frames: the **before** frame carries how the page got into this state (anything it logged or fetched while loading), and the **after** frame carries what the action itself caused. That is usually the fastest way to answer "why did my click do nothing":
+
+```
+click "#submit" on http://localhost:3000/login — 0.4% of the frame changed
+Context — console: 1 entry; network: 1 request
+After — Frame 2 @ 612ms [interaction]
+Changed: 0.4% — region: 300,180 60x24
+Console:
+  [error] TypeError: Cannot read properties of null (reading 'value')
+Network:
+  POST http://localhost:3000/api/login → 422 (88ms)
+```
+
+Because the page is reused between calls, the layers are installed on it once and **emptied at the start of every call**, so each call reports only what it caused. A layer can be switched on mid-session — it is attached to the document that is already open, no reload needed — but one that was on for an earlier call keeps running silently, since a page cannot un-expose an injected observer.
+
+Calls are serialised — they all drive the same page, so they queue rather than interleave. The first call needs a `url`; later calls can omit it. Cookies, storage, scroll position and in-page state all carry over. The one thing that cannot change in place is touch support, so the first `tap` or `swipe` on a page opened without it reopens the page — the summary says so, because that resets page state. The session closes when the MCP server shuts down; `framewatch_capture` and `framewatch_screenshot` are unaffected by it, as they always use a fresh, isolated browser context.
+
+### `framewatch_responsive`
+
+Screenshot one page at several viewport sizes in a single call. Each size loads in its own fresh browser context and they load concurrently, so three 2s waits cost about 2s — and a mobile shot is what a phone would really get, not a resized desktop layout that already ran its `matchMedia` listeners at 1440px.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | string (URL) | — | Page to capture |
+| `viewports` | array (1–8) | mobile 375×812, tablet 768×1024, desktop 1440×900 | `{ name, width, height }` per size |
+| `wait_ms` | integer ≥ 0 | `2000` | Settle time after load, per viewport |
+| `wait_for` | string | — | CSS selector to wait for (visible) at each viewport |
+| `wait_for_timeout_ms` | integer ≥ 1 | `10000` | Max wait for `wait_for` |
+
+**Example call** — the three defaults, or your own breakpoints:
+
+```json
+{ "url": "http://localhost:3000" }
+```
+```json
+{
+  "url": "http://localhost:3000",
+  "viewports": [
+    { "name": "iphone-se", "width": 375, "height": 667 },
+    { "name": "ipad-portrait", "width": 768, "height": 1024 },
+    { "name": "macbook", "width": 1440, "height": 900 },
+    { "name": "wide", "width": 1920, "height": 1080 }
+  ],
+  "wait_for": "main"
+}
+```
+
+Returns a summary, then one labelled image per viewport. Each label also reports **horizontal overflow** — content wider than its viewport — which is the commonest responsive bug and one a screenshot hides, because the part that sticks out is simply cropped off:
+
+```
+Captured http://localhost:3000/ at 3 of 3 viewports: mobile 375x812, tablet 768x1024, desktop 1440x900
+Horizontal overflow at mobile — content is wider than the viewport, so something is sticking out past the right edge.
+
+mobile 375x812 — image 375x812 — horizontal overflow: content is 640px wide in a 375px viewport (+265px) — page scrolls to 1420px (1.7 screens)
+```
+
+A viewport that fails is reported next to the ones that worked, rather than failing the call — "desktop is fine, mobile times out" is itself the finding. Only a run where *every* viewport failed comes back as an error.
+
+### `framewatch_accessibility`
+
+Run an [axe-core](https://github.com/dequelabs/axe-core) audit and report the violations. axe is the engine behind most commercial accessibility tooling, so a violation reported here is one an auditor would raise too.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | string (URL) | — | Page to audit |
+| `standard` | `wcag2a` \| `wcag2aa` \| `wcag21aa` | `wcag2aa` | Conformance level to test against |
+| `wait_ms` | integer ≥ 0 | `1000` | Settle time after load, so the app can finish rendering |
+| `wait_for` | string | — | CSS selector to wait for (visible) before auditing |
+| `wait_for_timeout_ms` | integer ≥ 1 | `10000` | Max wait for `wait_for` |
+| `max_violations` | integer 1–25 | `25` | Violation types to report (worst impact first) |
+| `max_elements` | integer 1–20 | `3` | Offending elements listed under each violation |
+| `viewport` | `{ width, height }` | `1280×720` | Some rules (reflow, target size) depend on it |
+
+```
+4 WCAG2AA (axe-core 4.13.0) violation types on http://localhost:3000/, affecting 7 elements — 3 critical, 1 serious.
+11 rules passed, 2 need a human to check, 49 did not apply.
+
+1. [critical] Images must have alternate text (image-alt) — 2 elements
+   Ensures <img> elements have alternate text or a role of none or presentation
+   • .hero > img
+     <img src="/hero.png" width="800">
+     Fix any of the following: Element does not have an alt attribute
+   https://dequeuniversity.com/rules/axe/4.13/image-alt
+```
+
+**Example call** — audit at the level you are targeting, waiting for the app to render first:
+
+```json
+{ "url": "http://localhost:3000/checkout", "standard": "wcag21aa", "wait_for": "form#checkout" }
+```
+
+Violations are sorted worst impact first (critical → serious → moderate → minor), then by how many elements each affects. Passing rules are counted rather than listed — a list of two hundred rules that did not fire is noise — but "need a human to check" is worth reading: those are the checks axe could not decide on its own, typically colour contrast over an image.
+
+The audit runs in a context with CSP bypassed and injects axe into the main frame and every child frame, so an app with a strict `Content-Security-Policy`, or one that embeds an iframe, is audited rather than refused.
+
+### `framewatch_compare`
+
+Diff two pages — two URLs, or the same URL before and after a code change — and show what moved.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url_a` | string (URL) or `"current"` | — | The "before" side |
+| `url_b` | string (URL) or `"current"` | — | The "after" side |
+| `wait_ms` | integer ≥ 0 | `2000` | Settle time after load, per side |
+| `wait_for` | string | — | CSS selector to wait for (visible) on both sides |
+| `wait_for_timeout_ms` | integer ≥ 1 | `10000` | Max wait for `wait_for` |
+| `viewport` | `{ width, height }` | `1280×720` | Viewport for both sides |
+
+Returns the summary, both frames, and a **diff overlay**: side B with every differing pixel tinted, which is what turns "3.4% changed" into something you can act on.
+
+```
+Compared http://localhost:3000/ "Dashboard" against http://localhost:3001/ "Dashboard" at 1280x720 —
+3.42% of pixels differ, all of it within 220,140 480x260.
+
+Diff overlay — B with every differing pixel tinted. 31533 of 921600 pixels changed (3.42%), within 220,140 480x260.
+```
+
+**Example call** — two URLs, or the page `framewatch_interact` has open against a fresh one:
+
+```json
+{ "url_a": "http://localhost:3000", "url_b": "https://staging.example.com" }
+```
+```json
+{ "url_a": "current", "url_b": "http://localhost:3000/checkout" }
+```
+
+The comparison is the same pixel comparison the capture engine uses between frames, so a change region here means what it means there. The two sides are captured one after the other rather than at once, so both get an unloaded machine and `wait_ms` means the same thing for each.
+
+Pass `"current"` as `url_a` to compare against the page `framewatch_interact` has open, in whatever state your interactions left it — three clicks into a flow, against a plain URL. That page is read, never touched: it is not reloaded, and an explicit `viewport` is ignored for it (with a note saying so), because resizing it would destroy the state being compared. Both sides are then captured at the open page's size, since frames of different sizes cannot be compared pixel for pixel.
+
+### `framewatch_start_server` / `framewatch_stop_server`
+
+Start the app's dev server so the rest of FrameWatch has something to point at, and stop it again.
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `command` | string | — | Shell command, e.g. `npm run dev` |
+| `port` | integer 1–65535 | — | Port the server will listen on |
+| `ready_pattern` | string (regex) | `ready\|started\|listening\|Local:` | Matched against the server's output; the matching line is reported back |
+| `cwd` | string | current directory | Working directory for the command |
+| `env` | object | — | Extra environment variables |
+| `timeout_ms` | integer 100–300000 | `30000` | Max wait for the port to start answering |
+
+```json
+{ "status": "running", "port": 3000, "pid": 51234, "url": "http://localhost:3000", "ready_ms": 2140,
+  "ready_line": "  ready in 812 ms — Local: http://localhost:3000/" }
+```
+
+**Example call:**
+
+```json
+{ "command": "npm run dev", "port": 5173, "cwd": "/Users/me/code/my-app" }
+```
+
+**Readiness is the port, not the log line.** `ready_pattern` is matched and quoted back — dev servers print the URL they actually bound to, which is worth repeating — but what makes a server "running" is that something answers on its port. That is the condition the next tool call depends on, and a pattern that fires early (or a regex that never matches a server working perfectly) would report the wrong thing in both directions. Both loopback addresses are probed, so a server bound only to `::1` is not mistaken for one that never started.
+
+If the command exits first, or the port never opens, the error carries the server's own output — which is where the reason actually is:
+
+```
+Start server failed: `npm run dev` on port 3000 — the server exited before port 3000 opened (exit code 1).
+Last output from the server:
+  npm ERR! Missing script: "dev"
+```
+
+One server runs at a time. Starting the same command and port again is a no-op that reports the running server; starting a *different* one while it is up is an error naming what to stop first. A port already in use by something else is refused up front, rather than reported as an instant success. `framewatch_stop_server` takes no arguments and reports `not_running` rather than failing when there is nothing to stop; it signals the whole process group, so `npm run dev` → node → bundler all go together. FrameWatch also stops the server when the MCP server shuts down.
+
+## Putting it together
+
+A typical session — the agent brings the app up, records a flow, drives the page by hand, then checks the result. The output below is the real shape of what comes back, image blocks omitted:
+
+```
+framewatch_start_server  { "command": "npm run dev", "port": 5173 }
+  → { "status": "running", "port": 5173, "url": "http://localhost:5173", "ready_ms": 1840,
+      "ready_line": "  VITE v6.0.3  ready in 812 ms — Local: http://localhost:5173/" }
+
+framewatch_capture       { "url": "http://localhost:5173/login", "duration_ms": 6000,
+                           "interactions": [
+                             { "action": "type",  "selector": "#email",    "value": "test@example.com", "delay_ms": 1000 },
+                             { "action": "type",  "selector": "#password", "value": "hunter2",          "delay_ms": 500 },
+                             { "action": "click", "selector": "#submit",                                "delay_ms": 500 },
+                             { "action": "wait",                                                        "delay_ms": 2000 }
+                           ],
+                           "include_network": true, "include_dom": true }
+
+  → Captured 7 meaningful frames from 66 raw frames (6040ms recording) of http://localhost:5173/login — "Sign in"
+    Interactions: 4/4 replayed — type "test@example.com" into "#email", type "hunter2" into "#password", click "#submit", wait 2000ms
+    Context — console: 2 entries; network: 2 requests; DOM: 282 mutations
+
+    Frame 1 @ 30ms [initial]
+    Network:
+      GET http://localhost:5173/login → 200 (4ms)
+    DOM:
+      + form#login in body
+      + input#email in form#login
+      … and 4 more changes across 4 elements
+
+    …
+
+    Frame 4 @ 2147ms [interaction]
+    Changed: 3.7% — region: 20,115 397x128
+    DOM:
+      ~ button#submit [disabled]
+      ~ div#spinner [class]
+
+    Frame 5 @ 2316ms [animation]
+    Changed: 10.3% — region: 20,20 397x275
+    Console:
+      [error] Failed to load resource: the server responded with a status of 401 (Unauthorized)
+      [error] login failed: Invalid email or password
+    Network:
+      POST http://localhost:5173/api/login → 401 (123ms)
+    DOM:
+      ~ div#spinner [class]
+      ~ button#submit [disabled]
+
+framewatch_interact      { "url": "http://localhost:5173/login", "action": "type", "selector": "#email", "value": "test@example.com" }
+framewatch_interact      { "action": "type", "selector": "#password", "value": "correct-horse" }
+framewatch_interact      { "action": "click", "selector": "#submit", "wait_ms": 1500 }
+  → click "#submit" on http://localhost:5173/login — 74.2% of the frame changed
+
+framewatch_accessibility { "url": "http://localhost:5173/dashboard", "standard": "wcag21aa" }
+framewatch_stop_server   {}
+```
+
+Two things worth noticing. The agent did not get 66 screenshots and a guess: it got the seven moments the page actually changed, the 401 that caused frame 5, and the `#spinner` and `#submit` changes that came with it. And the failure landed on an `[animation]` frame rather than an `[interaction]` one — the click is what FrameWatch forces a frame for, but the response arrived 170ms later, and the change detector caught it on its own.
+
+`framewatch_interact` starts its own session and does not inherit the page `framewatch_capture` used, so its first call carries a `url`; the ones after it do not need one.
+
+## Troubleshooting
+
+**"Playwright's Chromium browser is not installed."** Run `npx playwright install chromium`. Every tool returns this message with the command in it rather than a stack trace.
+
+**A capture came back with only two frames.** The page changed less than `sensitivity` between them. Lower it — `0.02` catches subtle fades, `0.06` (the default) is tuned to ignore cursor blinks. If the page genuinely settles instantly, two frames is the correct answer.
+
+**A capture came back with `max_frames` frames of noise.** Something is animating continuously — a spinner, a video, a carousel. Raise `sensitivity` so only larger changes qualify, shorten `duration_ms`, or capture the specific moment with `framewatch_interact` instead.
+
+**The frames are blank or show a loading skeleton.** Recording starts at navigation commit, which is the point for splash screens but not when you wanted the finished page. Pass `wait_for` with a selector that only exists once the app has rendered.
+
+**An accessibility audit found nothing on a page you know is broken.** axe ran before the app rendered. Add `wait_for`, or raise `wait_ms` past the point where the content appears.
+
+**`framewatch_interact` says the page was reopened.** Touch support cannot be switched on in place, so the first `tap` or `swipe` on a page opened without it reopens the page and resets its state. Put the `tap` in the first call, or drive the flow with `framewatch_capture` instead.
+
+**`framewatch_start_server` refuses with "port already in use".** Something is already listening — often a dev server from an earlier session. Stop it, or point FrameWatch at it directly and skip `framewatch_start_server` altogether.
+
+**Everything times out on a page behind a login.** Use `framewatch_interact` to sign in first; the session page keeps cookies and storage between calls, and `framewatch_compare` can read it with `"url_a": "current"`.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # builds + type-checks, then runs vitest (unit + stdio integration tests)
+npm run typecheck  # type-check src/ and test/ without emitting
+npm run coverage   # vitest with v8 coverage
+npm run dev        # tsc --watch
+```
+
+Tests launch real Chromium against local fixture pages in `test/fixtures/`, served over HTTP by `test/helpers/fixture-server.ts` (which also answers the `/api/*` endpoints the fixtures call, including one request that is deliberately never answered):
+
+| Fixture | What it is for |
+| --- | --- |
+| `basic.html`, `busy.html` | A still page, and one that never stops repainting |
+| `splash.html` | A deterministic JS-timed animation — the frame-selection tests |
+| `interactive.html` | Click/type/select/hover/touch/scroll targets, each a fixed-size solid block |
+| `login.html` | A real form: validation, a POST that 401s, an error banner, a transition on success |
+| `console.html`, `network.html`, `dom.html`, `perf.html` | One context layer each |
+| `interact-context.html` | The layers on the long-lived `framewatch_interact` page |
+| `recorder-flip.html`, `recorder-spa.html`, `recorder-target.html`, `redirect.html` | Navigation, `history.pushState`, and redirects |
+| `responsive.html`, `responsive-late.html` | Breakpoints and overflow, at load and 400ms after it |
+| `a11y-good.html`, `a11y-bad.html`, `a11y-frame.html`, `a11y-late.html`, `csp.html` | Clean, broken, broken-inside-an-iframe, broken-after-render, and behind a strict CSP |
+| `compare-a.html` / `compare-b.html` | Two pages that differ in one region |
+
+The dev-server tests drive `test/helpers/fake-dev-server.mjs`, a stand-in that can be told to start slowly, never open its port, exit with an error, or ignore SIGTERM. `test/packaging.test.ts` packs the tarball, unpacks it and speaks MCP to the binary inside, which is the closest thing to testing `npx framewatch-mcp-server` without publishing. The stdio integration test screenshots `https://example.com`, so that one needs network access.
+
+Two things the coverage report will not show you. The DOM and performance probes run *inside* Chromium, so Node's V8 coverage cannot see them even though `context.test.ts` asserts on everything they emit; and `src/index.ts` plus the `register*Tool` functions run in a child process, so `server.test.ts` exercises them without registering a line. Read those numbers as "uninstrumented", not "untested".
+
+## Architecture
+
+```
+MCP client (Claude Code) ◄─stdio─► FrameWatch server ◄──► Playwright Chromium
+                                        │
+                                 recorder → smart diff
+                                        │
+                                  sharp (resize / crop)
+                                        │
+                        context layers (console / network / DOM / performance)
+```
+
+- `src/index.ts` — McpServer + stdio transport; shuts the browser down on stdin EOF / SIGINT / SIGTERM / SIGHUP
+- `src/engine/browser.ts` — one shared Chromium: a fresh context per tool call, plus the long-lived page `framewatch_interact` works on
+- `src/engine/recorder.ts` — captures raw PNG frames at a fixed interval (plus forced frames on navigation)
+- `src/engine/differ.ts` — grid-based frame selection, pixel-level change regions, crops
+- `src/engine/interaction.ts` — validates and executes one interaction step (click, tap, type, scroll, swipe, hover, select, navigate)
+- `src/engine/layers/` — the context layers: `console.ts`, `network.ts` (Playwright events), `dom.ts`, `performance.ts` (injected observers), `probe.ts` (the injection plumbing they share), `session.ts` (layers for the long-lived interact page), and `index.ts` (attach, drain, split across cards)
+- `src/utils/image.ts` — sharp wrappers, including the compare overlay
+- `src/utils/bounded-log.ts` — capped log that evicts ordinary entries to keep errors
+- `src/utils/server-process.ts` — dev server process manager (spawn, port readiness, process-group kill)
+- `src/utils/format.ts` — turns diff cards into MCP content blocks
+- `src/tools/screenshot.ts` — the screenshot tool
+- `src/tools/capture.ts` — the capture tool, including interaction replay
+- `src/tools/interact.ts` — the single-interaction tool
+- `src/tools/responsive.ts` — multi-viewport capture with the overflow check
+- `src/tools/accessibility.ts` — the axe-core audit
+- `src/tools/compare.ts` — before/after comparison and the diff overlay
+- `src/tools/server.ts` — the two dev-server tools
+
+All diagnostics go to stderr; stdout is reserved for the MCP protocol.
+
+## Contributing
+
+Issues and pull requests are welcome at [github.com/kekoDev/framewatch](https://github.com/kekoDev/framewatch). `npm test` builds, type-checks and runs the whole suite against real Chromium; please make sure it is green, and add a fixture rather than a mock when the behaviour involves a page.
+
+## License
+
+[MIT](LICENSE)