csstruth CLAUDE.md

csstruth — Agent Context

Hard ground truth for CSS: extracts the browser's actual rendered layout as deterministic, diffable text so agents stop guessing. Chromium-only, via the Chrome DevTools Protocol. Public (MIT): github.com/ikraamg/csstruth · npm: csstruth.

Architecture (learn this first)

• One core, two skins. All logic lives in src/core/*. src/cli.ts and src/mcp.ts are thin wrappers that call identical core functions. Never put logic in a skin — if both skins need it, it goes in core.
• The seam is withPage(url, fn, opts) in src/core/connect.ts: opens a page, sets viewport, navigates, settles, runs fn, always tears down. Almost everything flows through it. Opts compose (captureAnimations, beforeNavigate, skipSettle) — mirror that pattern for new connection concerns.
• The LayoutTree (tree.ts) is the core representation: one line per element, byte-identical across runs. Determinism is the whole thesis — never add timestamps, key-order dependence, or randomness to rendered output.
• 12 CLI commands (10 also MCP tools; watch is CLI-only). Core modules: connect, extract, tree, invariants, explain, inspect, snapshot, verify, matrix, baseline, interact, animate, stability, state, fix, blame, watch, serve.

The invariant checks (src/core/invariants.ts)

Six rules power check/verify, each tuned so a violation is a REAL bug — the exemptions are deliberate, not laziness, and each is tagged field #N / NEXT-* in a comment (grep them for the rationale):

• viewport-overflow — content wider than the viewport.
• parent-bleed — a child past its container's padding box, BOTH axes (checkBleed mirrors horizontal/vertical, clamped by the nearest overflow-x/y). Exempts absolute/fixed and deliberately-displaced children (displaced(): negative margin, a translating transform via translatesBox — translateZ(0) and other no-op transforms still flag — or non-static position with a real inset).
• zero-size / off-screen — interactive element with a 0 dimension or parked off-screen (unless inside a scroll/clip ancestor).
• text-clip — text past a hidden-overflow box with no ellipsis opt-in.
• overlap — two un-layered siblings overlapping. Exempts SVG internals, sr-only, empty async placeholders (isPlaceholderOverlap), and a descendant that escaped an intermediate container and lapped a cousin (escapesIntermediateContainer — parent-bleed owns that defect).
• tap-target — sub-24px interactive element. Measures an input's <label> not the sr-only input; exempts a text link inline in a sentence (WCAG 2.5.8 — requires its own text, display:inline, and real parent text — an icon-only link still flags).