API Reference

Parsing and validation

Function	Signature	Description
`parseCapture`	`(json: string, limits?: Partial<WebSketchLimits>) => WebSketchCapture`	Parse and validate a JSON capture string. Throws `WebSketchException` on error.
`validateCapture`	`(data: unknown, limits?: Partial<WebSketchLimits>) => WebSketchValidationIssue[]`	Validate a capture object against the schema. Returns an array of issues (empty = valid). Does not throw.
`isSupportedSchemaVersion`	`(version: unknown) => version is string`	Check whether a schema version string is supported by this library.

Rendering

Function	Signature	Description
`renderAscii`	`(capture: WebSketchCapture, options?: AsciiRenderOptions) => string`	Render a capture as an ASCII wireframe (default 80x24 grid with box-drawing borders).
`renderNodeAscii`	`(node: UINode, options?: AsciiRenderOptions) => string`	Render a single node subtree to ASCII without capture metadata.
`renderForLLM`	`(capture: WebSketchCapture) => string`	LLM-optimized view with URL, viewport header, ASCII body, and legend footer.
`renderStructure`	`(capture: WebSketchCapture, width?: number, height?: number) => string`	Compact structure-only view (no text, no semantics, ASCII-style borders).
`generateLegend`	`() => string`	Generate a compact legend mapping role abbreviations to full names.
`renderJSON`	`(capture: WebSketchCapture, options?: RenderJSONOptions) => string`	Minimal JSON tree for LLM tool-calling. Strips internal fields, keeps role/bbox/text/interactive. Available from main entry and `/codegen`.
`renderMarkdown`	`(capture: WebSketchCapture, options?: RenderMarkdownOptions) => string`	Readable Markdown mapping roles to idiomatic constructs (headings, tables, blockquotes). Available from `/codegen`.

AsciiRenderOptions

Option	Type	Default	Description
`width`	`number`	`80`	Grid width in characters
`height`	`number`	`24`	Grid height in characters
`showRoles`	`UIRole[]`	Important roles	Which roles to render
`showSemantics`	`boolean`	`true`	Show semantic labels
`showTextLen`	`boolean`	`true`	Show text length indicators
`borderStyle`	`"box" \| "ascii" \| "none"`	`"box"`	Border drawing style
`showLegend`	`boolean`	`false`	Append role abbreviation legend

Diffing

Function	Signature	Description
`diff`	`(a: WebSketchCapture, b: WebSketchCapture, options?: DiffOptions) => DiffResult`	Structural diff between two captures. Matches by geometry + role + semantics.
`formatDiff`	`(result: DiffResult) => string`	Human-readable diff report with change counts and top changes.
`formatDiffJson`	`(result: DiffResult) => string`	Machine-readable JSON diff report.
`formatDiffForLLM`	`(result: DiffResult) => string`	Concise one-line change summary for LLM context windows. Available from `@mcptoolshop/websketch-ir/codegen`.
`prepareDiff`	`(capture: WebSketchCapture) => PreparedCapture`	Pre-flatten and pre-fingerprint a capture for repeated diffing against many variants.

PreparedCapture

Returned by prepareDiff. Contains the original capture, a pre-computed flat node list, and its fingerprint. Pass to diff() instead of a raw capture to skip redundant work.

DiffOptions

Option	Type	Default	Description
`includeText`	`boolean`	`true`	Include text hash in matching
`includeName`	`boolean`	`true`	Include name hash in matching
`matchThreshold`	`number`	`0.5`	Minimum similarity to consider a match
`topChangesLimit`	`number`	`10`	Max changes in `topChanges`
`moveThreshold`	`number`	`0.01`	Bbox movement below this is noise
`resizeThreshold`	`number`	`0.01`	Bbox resize below this is noise

Fingerprinting and hashing

Function	Signature	Description
`fingerprintCapture`	`(capture: WebSketchCapture) => string`	Full structural fingerprint – roles + geometry + text + viewport aspect.
`fingerprintLayout`	`(capture: WebSketchCapture) => string`	Layout-only fingerprint that ignores text content changes.
`hashNodeShallow`	`(node: UINode, options?: HashOptions) => string`	Hash a single node without children.
`hashNodeDeep`	`(node: UINode, options?: HashOptions) => string`	Hash a node and its entire subtree.
`generateNodeId`	`(node: UINode, parentPath?: string) => string`	Generate a content-addressed node ID.
`assignNodeIds`	`(node: UINode, parentPath?: string) => void`	Assign IDs to all nodes in a tree (mutates in place).
`nodeSimilarity`	`(a: UINode, b: UINode) => number`	Compute similarity score (0-1) between two nodes.
`bboxSimilarity`	`(a: BBox01, b: BBox01) => number`	Compute IoU-like overlap between two bounding boxes.
`quantizeBbox`	`(bbox: BBox01, step?: number) => BBox01`	Quantize bbox values to reduce subpixel noise.
`bboxToString`	`(bbox: BBox01, precision?: number) => string`	Serialize bbox for hashing.

Text processing

Function	Signature	Description
`normalizeText`	`(text: string) => string`	Trim, collapse whitespace, lowercase, strip invisible characters.
`sha256`	`(text: string) => Promise<string>`	Async SHA-256 hash (browser SubtleCrypto or Node crypto).
`hashSync`	`(text: string) => string`	Synchronous FNV-1a 64-bit hash for structural fingerprinting.
`classifyText`	`(normalizedText: string) => TextKind`	Classify text as `none`, `short`, `sentence`, or `paragraph`.
`isMixedContent`	`(rawText: string) => boolean`	Check if text contains multiple paragraphs.
`createTextSignal`	`(rawText: string) => Promise<TextSignal>`	Generate a TextSignal from raw text (async).
`createTextSignalSync`	`(rawText: string) => TextSignal`	Generate a TextSignal from raw text (sync).
`isMeaningfulText`	`(text: string) => boolean`	Check if text has at least one alphanumeric character.

Error handling

Function	Signature	Description
`formatWebSketchError`	`(err: WebSketchError) => string`	Multi-line, human-readable error string with code, message, details, and hint.
`isWebSketchException`	`(err: unknown) => err is WebSketchException`	Type guard for `WebSketchException`.

Codegen exports

import { emitHTML, emitNodeHTML, roleToElement } from '@mcptoolshop/websketch-ir/codegen';

Function	Signature	Description
`emitHTML`	`(capture: WebSketchCapture, options?: EmitHTMLOptions) => string`	Generate semantic HTML from a capture with `data-wsk-*` attributes.
`emitNodeHTML`	`(node: UINode, options?: EmitHTMLOptions) => string`	Generate HTML for a single node and its children.
`roleToElement`	`(role: UIRole) => string`	Get the HTML element name mapped to a UIRole.

EmitHTMLOptions

Option	Type	Default	Description
`indent`	`string`	`" "`	Indentation string (2 spaces)
`includeBbox`	`boolean`	`true`	Include `data-wsk-bbox` geometry attributes
`includeHandlers`	`boolean`	`true`	Emit `data-wsk-on-*` for event handlers
`includeBindings`	`boolean`	`true`	Emit `data-wsk-bind-*` for reactive bindings
`includeState`	`boolean`	`true`	Emit `data-wsk-state` for state signals
`includeStyle`	`boolean`	`true`	Emit `data-wsk-style` for visual intent
`includePattern`	`boolean`	`true`	Emit `data-wsk-pattern` for recognized patterns
`includeSemantics`	`boolean`	`true`	Emit `data-wsk-semantic` for semantic hints
`includeRoleClass`	`boolean`	`true`	Include CSS class with role name (e.g., `wsk-button`)
`fullDocument`	`boolean`	`false`	Wrap output in full HTML document with head/body

Import sub-paths

The main entry point re-exports everything you need for typical usage:

// Main entry point — parsing, rendering, diffing, fingerprinting, errors
import { parseCapture, renderAscii, diff, WebSketchException } from '@mcptoolshop/websketch-ir';

Optional sub-path imports are available for tree-shaking or when you only need a specific module:

// Types only — no runtime code pulled in
import type { UINode, UIRole, PatternSignal, HandlerSignal } from '@mcptoolshop/websketch-ir/grammar';

// Just the codegen module
import { emitHTML, emitNodeHTML, roleToElement } from '@mcptoolshop/websketch-ir/codegen';

// Error types only (also re-exported from the main entry point)
import { WebSketchException, isWebSketchException } from '@mcptoolshop/websketch-ir/errors';

Exported constants

Constant	Value	Description
`CURRENT_SCHEMA_VERSION`	`"0.1"`	Schema version produced by this library
`SUPPORTED_SCHEMA_VERSIONS`	`Set(["0.1"])`	All versions this library can read
`DEFAULT_LIMITS`	`{ maxNodes: 10000, maxDepth: 50, maxStringLength: 10000 }`	Default resource limits for validation
`MAX_DEPTH`	`8`	Maximum tree depth
`MAX_CHILDREN`	`200`	Maximum children per node
`BBOX_QUANT_STEP`	`0.001`	Quantization step for bbox hashing
`COLLAPSE_TOLERANCE`	`0.002`	Collapse tolerance for near-equal bboxes
`VALID_EVENT_TYPES`	`ReadonlySet<string>`	All valid `EventType` values (`click`, `hover`, `focus`, `blur`, `submit`, `change`, `input`, `keydown`, `scroll`, `drag`, `custom`)
`VALID_STATE_ACCESS_KINDS`	`ReadonlySet<string>`	All valid `StateAccessKind` values (`read`, `write`, `readwrite`, `condition`)
`VALID_STATE_SCOPES`	`ReadonlySet<string>`	All valid state scope values (`local`, `global`, `url`)
`VALID_STYLE_INTENT_TOKENS`	`ReadonlySet<string>`	All valid `StyleIntentToken` values
`VALID_DENSITIES`	`ReadonlySet<string>`	Valid density values (`compact`, `normal`, `spacious`)
`VALID_SIZES`	`ReadonlySet<string>`	Valid size values (`xs`, `sm`, `md`, `lg`, `xl`)
`VALID_PATTERN_KINDS`	`ReadonlySet<string>`	All valid `PatternKind` values