Pagespec

Pagespec is a headless command line utility and Model Context Protocol server. It extracts structural, visual, and layout states from web applications to provide autonomous coding agents with a feedback loop for what actually rendered on the Document Object Model.

The Core Problem

Current agentic coding assistants operate blindly. They lack intrinsic visual feedback loops when editing UI code. When an agent modifies a React component or writes styling rules, it cannot independently verify if the resulting changes look correct. It might unknowingly introduce an accessibility error or block a button. Pagespec fixes this gap. The software acts as a synthetic eye for your agent.

How It Works

Pagespec spins up a headless Chromium instance using Playwright. It bypasses conventional DOM parsing by directly injecting a client side object walker into the active page context. This custom script runs against the live DOM after all rendering finishes.

The tool captures several vital full stack metrics:

• Component Bounds: The precise X, Y, Width, and Height coordinate geometry of elements.
• Computed Styles: Live CSS values including opacity and zIndex to identify invisible elements.
• Event Interception: Hooking into EventTarget prototype methods to catalog attached listeners like clicks and hovers.
• Target Occlusion: Firing simulated interaction events to map elements that are structurally present but visually blocked by layering issues.
• Network and Console Output: Capturing asynchronous request failures and error logs natively.

The output is processed through a serialization engine to collapse empty formatting wrappers and produce an optimized JSON tree tailored to fit strictly within language model token limits.

Installation

Pagespec is published as an NPM package and is designed to be used globally locally or through npx.

For global installation:

npm install -g pagespec

Alternatively, you can run commands directly without a permanent installation:

npx pagespec --help

Development and Testing

If you would like to contribute and test the extraction logic locally:

git clone https://github.com/sachhg/pagespec.git
cd pagespec
npm install
npx tsc
npx vitest run

Usage Instructions

Command Line Interface

The CLI interfaces perfectly for manual intervention or custom scripted workflows.

Taking a Snapshot Generate a full structural tree of any target page. This output trims unnecessary wrapper nodes and highlights actionable layout warnings.

pagespec snapshot http://localhost:3000 --format json

You can cap the total tokenizer count using optional CLI flags. Run pagespec snapshot --help for all arguments.

Component-Level Isolation Extract a targeted UI component entirely isolated from its parent application using the --focus <selector> parameter. This natively clips the parsed Document Object Model exclusively to that element and its children.

pagespec snapshot http://localhost:3000 --focus "#my-interactive-button" --format json

Because Pagespec captures live browser styles, focusing a component automatically maps a fully reconstructed isolatedHtml snippet inside the output payload. You can strictly output this isolated extraction to disk to preview it natively using the export flag:

pagespec snapshot http://localhost:3000 --focus "#my-interactive-button" --out-html button-preview.html

Calculating Diffs Compare your live application against a stored JSON snapshot baseline. The diff engine utilizes graph logic to return exclusively the nodes that were modified, added, or removed.

pagespec diff http://localhost:3000 --baseline default

Live Development Watcher Create an interactive live reloading session. Pagespec utilizes Chokidar to observe your source code file paths locally. When a file is modified in your text editor, the tool recalculates the visual diff automatically and prints the output to your terminal.

pagespec watch http://localhost:3000 --on-change "**/*.tsx"

Model Context Protocol Server

Configuration for autonomous agents involves utilizing the MCP server feature. Programs like Claude Desktop or Cursor can connect locally to request precise visual feedback queries on demand without human supervision.

Start the server using standard input and output streams:

pagespec serve

Agents gain native capabilities to use the snapshot, diff, warning, and baseline tools directly. This workflow unlocks fully autonomous UI debugging for modern client frameworks.