WS WebSketch IR
v2.1.0 · 22 UI primitives · zero runtime deps

WebSketch IR stop treating webpages like pictures.

A grammar-based intermediate representation that compiles DOM soup into a small, fixed vocabulary of semantic UI primitives. LLMs reason about layouts without vision.

Parse

const capture = parseCapture(json);

Render

const ascii = renderAscii(capture);

Diff

const changes = diff(a, b);

Why WebSketch

Structured UI understanding for language models.

Grammar-based

Compiles DOM into 22 fixed UI primitives — BUTTON, NAV, CARD, INPUT, and more. No ambiguity, no DOM noise.

LLM-friendly

ASCII wireframe rendering lets language models reason about page layouts without vision capabilities.

Diffable

Structural diff engine matches nodes by geometry + role + semantics, not DOM identity. Track real UI changes.

Core Capabilities

Typed

Full TypeScript types for every node, capture, and option. Zero runtime dependencies.

Fingerprintable

Content-addressed hashing produces stable fingerprints for fast structural equality checks.

Versioned Schema

Semantic versioning for the capture schema with forward and backward compatibility guarantees.

Usage

Parse & render

import { parseCapture, renderAscii, renderForLLM } from '@mcptoolshop/websketch-ir';

const capture = parseCapture(jsonString);
const wireframe = renderAscii(capture);   // 80x24 ASCII grid
const llmView = renderForLLM(capture);    // URL + viewport + legend

Diff & fingerprint

import { diff, formatDiff, fingerprintCapture } from '@mcptoolshop/websketch-ir';

const result = diff(captureA, captureB);
console.log(formatDiff(result));
// { added: 2, removed: 1, moved: 0, resized: 3 }

const fp = fingerprintCapture(capture);

Ecosystem

WebSketch IR is the core — these tools build on it.

Package
Role
websketch-ir
Core IR grammar and serialization (this repo)
websketch-vscode
VS Code extension — capture pages from your editor
websketch-cli
CLI for rendering, fingerprinting, and diffing
websketch-extension
Chrome extension for capturing pages
websketch-mcp
MCP server for LLM agent integration
websketch-demo
Interactive demo and visualization

Error Codes

Structured errors with typed codes.

Code
Meaning
WS_INVALID_JSON
Input is not valid JSON
WS_INVALID_CAPTURE
Capture fails schema validation
WS_UNSUPPORTED_VERSION
Capture version not supported
WS_LIMIT_EXCEEDED
Node count or depth exceeds limits
WS_INVALID_ARGS
Missing or invalid arguments

API Reference

Core exports from @mcptoolshop/websketch-ir.

parseCapture(json: string): WebSketchCapture

Parse and validate a JSON capture string. Throws WebSketchException on error.

renderAscii(capture, width?, height?): string

Render a capture as an 80x24 ASCII wireframe with box-drawing borders.

renderForLLM(capture): string

LLM-optimized view with URL + viewport header and legend footer.

diff(a, b, options?): DiffResult

Structural diff between two captures. Matches by geometry + role + semantics.

formatDiff(result): string

Human-readable diff report with change counts and top changes.

fingerprintCapture(capture): string

Full structural fingerprint — roles + geometry + text + viewport aspect.

fingerprintLayout(capture): string

Layout-only fingerprint that ignores text content changes.

validateCapture(input): ValidationResult

Validate a capture object against the schema without throwing.