Ship UI that heals its own pixel regressions.
VisorQA renders every pull request on mobile and desktop, segments components with Meta SAM 3.1, and scores visibility and collision math. Muse Spark triages the fault, Muse Wonder diagnoses the cause, and Muse Code proposes a minimal patch — verified before anything lands.
npx visorqa initV_r = 0.45 (target: ≥ 0.98)
Area(M_SAM ∩ B_DOM) / Area(B_DOM)
IoU = 0.16 (target: 0.00)
Area(Mi ∩ Mj) / Area(Mi ∪ Mj)
Δ_x = 37.0px (target: ≤ 2.0px)
max(0, X_max(B_DOM) - W_viewport)
Pixel Segmentation
Zero-shot DOM point-prompts
Fault Localization
LCA DOM tree triage (2M TPM)
Layout Architect
Pydantic RepairSpec JSON
Diff Synthesis
Surgical unified diffs
Sandbox & HMR
Dual-viewport hot reload
<15.0s
Cycle Latency
Webhook trigger to verified PR commit across mobile (375px) and desktop (1440px) sandboxes.
99.2%
Detection Precision
DOM point prompts (cx, cy) fed directly to SAM 3.1 eliminates VLM spatial hallucinations.
88.5%
Context Token Pruning
Lowest Common Ancestor traversal prunes context from ~28,000 to ~3,200 tokens per run.
Max 3x / $0.03
Bounded Self-Healing
Hard-capped 3-strike retry loop with $0.03 average PR spend ($0.15 database-enforced ceiling).
Specifications derived from VisorQA Software Requirements Specification (VQA-SRS-2026-V1) and ADR benchmarks.
01 — DETERMINISTIC FSM PIPELINE
From webhook to verified fix with zero human clicks.
One pure Python state machine drives five async nodes. Every transition is logged, every metric is recomputed, and loopbacks are strictly bounded.
Boots ephemeral Modal container, extracts DOM geometry B_DOM, and prompts SAM 3.1 with center coordinates to compute exact pixel overlap.
PR Branch, Dual viewports (375x812, 1440x900), DOM coordinates (cx, cy)
Binary pixel mask M_SAM, Discrepancy math (Vr = 0.45, IoU = 0.16, Δx = 37px)
02 — PRODUCT PROOF
Built for engineers who read diffs, not dashboards.
Mission Control streams the live state machine, the NumPy discrepancy math behind every verdict, and the exact syntax-valid unified diff that fixed it.
Watch every strike as it happens
The FSM stepper and trace log show which node is computing, what the models concluded, and how many strikes remain — streamed over native WebSocket the moment a pull request webhook lands.
Minimal diffs, verified twice
Every repair is a small unified diff against the diagnosed file — screened against anti-hack CSS rules, re-verified simultaneously on both 375px mobile and 1440px desktop, and auto-committed only when both viewports pass.
03 — ARCHITECTURAL PILLARS
Engineered from first principles for Level 4 autonomy.
Five technical breakthroughs separate VisorQA from generic LLM chat wrappers, ensuring deterministic execution, design-system safety, and reproducible patches.
DOM-Guided SAM 3.1 Prompts
Bypasses blind 4,096-point SAM grid mode by extracting 25–40 interactive DOM bounding boxes and center coordinates (cx, cy) from Playwright, achieving 10.6x faster inference (<450ms) with zero spatial hallucinations.
LCA DOM Hierarchy & Token Pruning
Algorithms traverse upward to find the Lowest Common Ancestor. Automatically classifies atomic primitives (src/components/ui/*) as immutable and localizes repairs to parent layouts, cutting LLM context by 88.5%.
Architect-Coder Separation
Muse Wonder serves strictly as the visual architect, emitting structured Pydantic RepairSpec JSON. Muse Code strictly synthesizes syntax-valid unified diffs. Unconstrained single-shot LLM code rewriting is prohibited.
Modal Sandboxes & 0.3s HMR
PR branches boot in isolated Modal cloud containers. Verified patches are injected directly into running Next.js processes via Hot Module Replacement in 0.3s, avoiding 15-second server reboot delays.
Non-Destructive PR Review Fallback
If verification fails to reach Vr >= 0.98 after 3 strikes, VisorQA never force-commits to the PR branch. It cleanly halts and posts the highest-scoring candidate patch as a suggested GitHub PR review comment.
Rejected manual browser extensions and chat bots; chosen automated webhook pipeline with <1.2s ingress latency and zero human clicks.
Rejected full-repo Vector DB RAG (28K tokens, 40s cold-start); chosen LCA DOM tree triage with 88.5% context token reduction in 0.6s.
Rejected blind 64x64 grid mode (4.8s); chosen DOM point prompts achieving 10.6x speedup (<450ms) and zero spatial hallucinations.
Rejected monolithic LLM rewriting and 15s server restarts; chosen Muse Wonder JSON spec + Muse Code diffs with 0.3s Modal HMR.
04 — ENTERPRISE GUARDRAILS
Autonomous, but never unsupervised in effect.
Six hard constraints bound what the agent may attempt, spend, and ship. Safety policy lives in code and database constraints — not in wishful prompting.
Three strikes, then halt
Failed verifications loop back with feedback at most three times. After strike three the run halts and the highest-scoring patch is attached as a GitHub review comment — never force-committed.
Untouchable shared UI primitives
Files under src/components/ui/* (buttons, inputs, radix primitives) are strictly read-only. Faults inside primitives are localized upward to the consuming layout container.
Dual-viewport gate
A fix must simultaneously achieve Vr ≥ 0.98, IoU = 0.00, and Δx ≤ 2px on both 375px mobile and 1440px desktop viewports, preventing cross-viewport regressions.
Anti-hack CSS policy
Synthesized patches containing !important, z-index: 9999 escalations, or content-hiding shortcuts are screened out and rejected by database CHECK constraints.
Hard cost ceiling ($0.15/run)
Each run is hard-capped at $0.15 of model spend, enforced as a database constraint. Typical runs complete for ~$0.03, eliminating runaway spend risks.
Signed, verified webhooks
GitHub webhook payloads are HMAC-SHA256 verified, deduplicated by delivery ID, and acknowledged within the 1.2s acceptance budget.
05 — TECHNICAL FAQ
Frequently asked engineering questions.
Deep architectural and security answers for engineering leaders and frontend specialists.
How does VisorQA detect layout bugs that Playwright and Cypress completely miss?
Playwright and Cypress assert against DOM properties: they pass if an element exists in HTML, has CSS attributes, and isn't marked display: none. They cannot tell if a checkout button is covered by a sticky banner or obscured by an overlay. VisorQA pairs Playwright DOM bounding boxes (B_DOM) with Meta SAM 3.1 zero-shot segmentation masks (M_SAM) and evaluates deterministic NumPy math: Visibility Ratio (Vr < 0.85), Sibling Collision (IoU > 0.05), and Viewport Bleed (Δx > 2px).
How does VisorQA prevent regressions on other viewports?
Every PR branch is rendered simultaneously at 375px (Mobile) and 1440px (Desktop) inside isolated Modal sandboxes. Under Business Rule BR-3, a patch is accepted if and only if Vr >= 0.98, IoU = 0.00, and Δx <= 2px on both viewports simultaneously. If a mobile banner fix breaks a desktop multi-column grid, the dual-viewport gate fails and feeds cross-viewport error coordinates to Strike 2.
What happens if the agent cannot resolve a defect within 3 attempts?
The 3-Strike safety guardrail immediately terminates the loop. The agent snapshots the highest-scoring candidate patch (best_patch with best_score) and attaches it as a non-destructive GitHub Pull Request review comment with the SAM 3.1 visual overlays. VisorQA never force-commits unverified code to the PR branch.
Can VisorQA break our global design system or shared UI components?
No. Under Business Rule BR-2, shared UI components (src/components/ui/*, such as atomic buttons and inputs) are strictly read-only during triage. When a button is clipped or occluded, the DOM Lowest Common Ancestor algorithm isolates the parent layout container (CheckoutPage.tsx) or colliding sibling (PromoBanner.tsx), keeping cross-page regression rates below 2.0%.
What prevents the AI from using dangerous CSS hacks like !important or z-index: 9999?
VisorQA enforces an Anti-Hack CSS Policy (BR-4) at two independent layers: First, the orchestrator parser screens all generated diffs against banned patterns (!important, z-index: 9999, z-[9999]) and rejects unsafe patches before application. Second, the PostgreSQL database enforces a strict CHECK constraint on repair_attempts.unified_diff, making it impossible to persist brittle global overrides.
What are the compute and API costs per pull request?
Because VisorQA prompts SAM 3.1 with 25–40 DOM center coordinates rather than 4,096 blind grid points, and Muse Spark prunes context tokens by 88.5%, a typical PR run consumes ~3,200 tokens and costs an average of $0.03 in compute and model spend. Furthermore, each run has a hard PostgreSQL CHECK constraint capping total spend at $0.15 USD.
Stop reviewing pixels by hand.
Connect your repository and let VisorQA catch visual regressions and push verified fixes before your reviewers even notice.
- HMAC-SHA256 Webhook
- Webhook in <1.2s
- $0.03 Typical Run
- Max 3x Strike Cap
- Zero Hallucination Math