CHANGELOG.md

Changelog

0.3.8 (2026-07-16)

Personas now judge whether the page actually works for them, not just how the hero looks — using evidence the collector was already capturing. They read the below-fold screenshots (so "I'd bounce before the CTA" depends on how far down it really is) and the interaction results (did the mobile menu open, does keyboard focus reach everything, are the tap targets thumb-sized). Still fully deterministic — the collector drives the page once; the persona just reads what came back.

Features

• Personas ground in behavior, not just the still — the persona read now uses the scroll-fold screenshots and the collector's interaction evidence (click→verify, keyboard focus, touch targets, hover), so "would this work for me" is answered by whether the flow works. (ffd9b18)

0.3.7 (2026-07-16)

When a project has no audience description to work from, the tailored persona used to fall back to generic built-ins. Now Pixelslop can read one off the page's own hero — but only when the hero actually pitches to a specific audience. A search box or a generic splash produces nothing; the built-ins cover those fine.

Features

• Persona from the hero — when setup captured no audience, infer a project persona from the landing hero, gated to pitch-forward heroes and tagged as an unconfirmed hypothesis. Explicit audience text always wins; this only fires when there was none. (3ee4a26)

0.3.6 (2026-07-14)

This is the release where Pixelslop stops just measuring design and starts reading it.

The headline: personas now open the screenshots and react to the page like the humans they stand for — the five-second gut read, where the eye lands, whether they'd trust it or bounce — instead of narrating the measured findings in a voice. Only the personas that matter for the page type run, each as its own independent read. And that read co-headlines the report now, in its own section above the score, so "how this actually lands for a person" sits next to the /20 instead of buried under it.

Around that: typography is finally measured at mobile too (it was grading every page on its widest, most forgiving viewport), there's a detector for the copy-pasted card hover-zoom that gives a template away, the reviewer learns whether a surface is a brand or a product and judges it accordingly, and every report now declares how it was assembled so a weakened run is never silent.

The /20 stays measured-only. The design read is judgment, grounded in what was actually seen — never a competing number.

Features

• Vision-first personas — personas open the screenshots and react to the page as that human (first impression, eye-path, would-I-bounce), then ground it in measured evidence. Only the page-relevant personas run, each an independent read. (2ffde00)
• The Read — the design-director's verdict and the sharpest persona reactions co-headline the report: a section above the score, a Reads as: line, and a card beside the /20. Judgment grounded in what was seen, never a number. (2ffde00)
• Design register — the reviewer learns whether it's judging a brand surface or a product surface and calibrates the perceptual read to match; the measured pillars stay register-blind. (ff29f6d)
• Critique provenance — the report's Method: line declares whether the evaluators ran isolated or inline, with a visible DEGRADED banner so a weakened run never looks clean. (ff29f6d)
• Uniform image hover-zoom (slop pattern 26) — catches the copy-pasted card that zooms identically across a whole grid, while leaving a legit single product-zoom alone. (7ca8572)

Bug Fixes

• Typography measured at mobile too — line-length and tiny body text fail at 375px first, but the metrics only ran on desktop, so pages were graded on their most forgiving viewport. (0a4b0ba)

0.3.5 (2026-06-16)

Features

• add a doctor self-check so stale/broken installs self-diagnose (92e20fb)
• add a doctor self-check so stale/broken installs self-diagnose (6c88fb6)

0.3.4 (2026-06-10)

Bug Fixes

• rewrite skill paths on install so /pixelslop works in any project (59394da)
• rewrite skill paths on install so /pixelslop works in any project (a09e43a)

0.3.3 (2026-06-10)

Features

• add the design-director pass for subjective findings (2fb915e)
• exhaustive-by-default scans with a design-judgment layer (7c8d0b3)
• generate and evaluate project-specific personas (6dcd540)
• generate native Codex TOML agents at install time (92cfb7e)
• make every option discoverable from the skill, guarded against drift (5c01132)
• make scans exhaustive by default (26468b9)
• make the skill advise the user, not just run (011391b)
• split report findings into measured and judgment layers (aeaaf6f)

Bug Fixes

• make agent spawning work under Codex (inline fallback + native TOML) (5f9f850)
• make the user-asking protocol work under Codex, not just Claude Code (3bc3920)
• run agents inline when the harness can't spawn them (Codex) (c7dd90e)

0.3.2 (2026-06-09)

Features

• add broken-image, oversized-h1, edge-text, and clipped-content detectors (1d09945)
• add humanName to persona schema for narrative reports (5271af0)
• add scan save-results command for deterministic data handoff (4c24136)
• classify content pages and harden loopback resolution (34afc4e)
• extended detectors and per-target score trends (2247768)
• fix toward the project's design tokens (f66114e)
• generate HTML report with plan data after fix loop (ac260a3)
• measure typography readability and score it (e0a581d)
• multi-section HTML report with CSS-only tab navigation (3c19d29)
• narrative persona report format with human names (ce3be25)
• page-type heuristic for smart persona selection (f803be2)
• persist per-issue details and show them in the HTML report (15ca62c)
• report generate command in pixelslop-tools (6b5982e)
• run-time config step with --quick bypass and precedence spec (7468029)
• self-contained HTML report template (b4be84c)
• show pillar evidence and slop patterns in HTML report (c20110b)
• support checkpoint operations without git for non-repo projects (2bf093d)
• track per-target score trends across runs (4ec641d)
• typography readability metrics and fix-toward-tokens (93dadcb)

Bug Fixes

• force light mode on HTML report, drop broken dark mode (d4c92c0)
• harden checkpoints against path traversal, fix scan-results resolution (adb4239)
• harden HTML report against XSS, path traversal, and unsafe URLs (ba548de)
• pin playwright-core to an exact version for deterministic installs (915903b)
• template resolution for installed layout, symlink refresh, test coverage (ee9a228)
• update installer resource count for report-template.html (3357b3c)

Refactoring

• redesign HTML report with Command Folio design system (61cb281)

0.3.1 (2026-03-30)

Features

• add interactive settings flow to /pixelslop skill (db13482)
• add settings commands to pixelslop-tools (d70a8d7)
• interactive project settings for /pixelslop (9015c5e)

Bug Fixes

• address Codex review — 5 settings bugs + test gaps (369b7c9)
• correct action-semantic-pull-request commit hash pin (60b2ce6)
• fence-aware section parser for settings read/write (9827117)

0.3.0 (2026-03-30)

Pixelslop 0.3.0 is a ground-up rework of how design quality gets measured. The scanner that used to be one monolithic agent is now a collector feeding 6 specialist evaluators. The browser runtime that depended on Playwright MCP is now direct Playwright execution. And the collector doesn't just look at static screenshots anymore — it scrolls, hovers, tabs through elements, and clicks interactive widgets to verify they actually work.

The /20 scoring model hasn't changed. The 5 pillars are the same. But the evidence behind each score is substantially deeper, and the evaluators are sharper about what they penalize.

Scanner Architecture

The old scanner was a single agent that captured screenshots, extracted styles, and scored everything in one pass. That's gone.

• Evidence collector — pixelslop-browser.cjs captures screenshots, computed styles, contrast ratios, typography, spacing, a11y snapshots, and persona checks across 3 viewports (1440px, 768px, 375px). Outputs a structured evidence bundle.
• 6 specialist evaluators — hierarchy, typography, color, responsiveness, accessibility, and slop. Each reads the evidence bundle, applies its rubric from scoring.md, and returns a scored JSON finding. They run in parallel, they're read-only, and they can't see each other's work.
• Evidence schema — evidence-schema.md is the formal contract between collector and evaluators. Defines every field, its type, which evaluator owns it, and confidence flags.

Direct Browser Runtime

Replaced Playwright MCP tool declarations with direct Playwright execution via pixelslop-tools browser * commands. The collector, fixer, and checker call Playwright directly — no MCP middleware, no tool-call overhead, no dependency on the host runtime having Playwright MCP configured.

Interaction Evidence Layer

The collector now runs 4 interaction passes after the static evidence capture:

• Scroll pass — scrolls the page fold by fold. Screenshots each fold, tracks sticky/fixed elements, detects lazy-loaded images, samples below-fold typography. Pages with scroll ratio > 8 get flagged for content priority issues.
• Hover pass — hovers up to 15 interactive elements at desktop, captures before/after computed style diffs. Detects buttons and links with zero hover feedback.
• Focus pass — tabs through up to 30 focusable elements, checks each for a visible focus indicator (outline, box-shadow, or border change). Identifies non-semantic clickables: divs and spans with cursor:pointer or onclick that should be <button> or <a>.
• Promise verification — clicks mobile menu triggers, anchor links, and tabs/accordions, then checks whether the expected outcome happened. Binary pass/fail: did the nav open? Did the page scroll to the anchor? Did aria-expanded change? Skipped probes (ambiguous or unclickable triggers) are classified as unverifiable, not broken.

Each pass has its own time budget (scroll 8s, hover 5s, focus 3s, promises 12s) and graceful bailout. A timeout stores partial results, flags confidence, and continues — one noisy pass never contaminates the rest.

--deep mode doubles all budgets and raises caps for complex pages.

Evaluator Wiring

Interaction evidence feeds into the existing pillar evaluators:

• Accessibility — focusPass.missingIndicators (>30% missing = score cap at 2), focusPass.nonSemanticClickables (>3 = score cap at 2), broken tabs/accordion ARIA state from promise verification
• Responsiveness — broken mobile menu from promise verification (score cap at 2), anchor-link failures scoped to mobile context with no sticky nav (warn only)
• Hierarchy — scroll fold count and ratio for content priority (CTAs buried past fold 5)

Prompt contract tests lock the scoring rules — if someone weakens the evaluator thresholds, the test suite catches it.

Interactive Installer

npx pixelslop install is now an interactive wizard. Detects Claude Code and Codex CLI, lets you pick runtimes and scope, supports project-local Codex installs in .codex/, rewrites agent paths, configures MCP, and installs skills via symlink or copy. npx pixelslop@latest update upgrades with backup + diff.

Code Check Mode

--code-check runs source-only analysis without opening a browser. 6 additional source patterns (S11-S16), cognitive load scoring, usability heuristics, and interaction design checks.

Release Infrastructure

• PR titles validated as conventional commits via amannn/action-semantic-pull-request
• Release PRs open as drafts for changelog review before publishing
• Changelog sections group features/fixes/refactoring, hide test/chore/ci/docs noise
• CI matrix: Node 18, 20, 22. npm publish with OIDC provenance.

Tests

781 tests (was 470 at 0.2.0). Coverage includes:

• 7 interaction test fixtures (ref-map, sticky-header, lazy-images, focus-visible, broken-mobile-menu, tabs-accordion, anchor-links)
• Prompt contract tests for accessibility and responsiveness evaluators
• Evidence schema validation
• Installer path rewriting, MCP config, manifest structure
• Browser runtime integration tests
• Persona schema validation

Breaking Changes

None. The /20 scoring model, report format, plan format, and CLI interface are all unchanged. Scores may shift slightly because evaluators now have more evidence to work with — that's the point.

---

0.2.7 (2026-03-30)

Release infrastructure: PR title linting, changelog section grouping, draft release PRs for review before publish. No functional changes.

0.2.6 (2026-03-30)

Interaction evidence inside the existing evaluators. The browser collector now scrolls, hovers, tabs, and clicks interactive elements — then feeds what it finds into the accessibility, responsiveness, and hierarchy evaluators. No new pillar, no scoring model change. The existing /20 score gets sharper because evaluators can see things they couldn't before: missing focus indicators, divs masquerading as buttons, broken hamburger menus.

Features

• Scroll pass — fold-by-fold page analysis with screenshots, sticky element tracking, lazy image detection, and below-fold typography sampling. Pages that scroll for 8+ viewport heights get flagged for content priority issues.
• Hover pass — before/after computed style diffs on up to 15 interactive elements at desktop. Detects elements with no hover feedback.
• Focus pass — keyboard Tab-through that tests up to 30 elements for visible focus indicators. Identifies non-semantic clickables (divs/spans with cursor:pointer or onclick that should be buttons).
• Promise verification — click→verify loop for mobile menus, anchor links, and tabs/accordions. Binary pass/fail outcomes — if the nav doesn't open or the anchor doesn't scroll, that's a measurable failure.
• --deep flag — doubles all time budgets and raises element caps for extended collection on complex pages.
• Evaluator wiring — accessibility evaluator now caps score at 2 when >30% of focused elements lack visible indicators, or when >3 non-semantic clickables are found. Responsiveness evaluator caps at 2 for broken mobile menus. Hierarchy evaluator uses scroll data for content priority.
• Skipped probe handling — ambiguous or unclickable triggers classified as "skipped" (unverifiable), not "failed" (broken). Evaluators only penalize real click-action failures.

Architecture

• Element ref system assigns stable selectors to interactive elements — buttons, links, tabs, divs-acting-as-buttons — with semantic classification.
• Probe isolation: resetProbeState() between every interaction, resetBetweenPasses() between every pass and before viewport switches. A noisy probe never contaminates subsequent collection.
• Per-pass time budgets (scroll 8s, hover 5s, focus 3s, promises 12s) with graceful bailout — partial results stored, confidence flagged, scan continues.
• Evidence schema updated with formal field specifications and evaluator routing rules.

Tests

• 781 tests (was 616). 7 new test fixtures, 3 new test files, prompt contract tests for accessibility and responsiveness evaluators locking the skipped-probe exclusion rules.

0.2.5 (2026-03-26)

Features

• replace Playwright MCP with direct browser runtime (0a9d42e)

Bug Fixes

• CI installs playwright-core and Chromium before running tests (7a7461c)

0.2.4 (2026-03-26)

Features

• evidence schema, 6 specialist evaluator agents, evaluator tests (35c6e93)
• scanner decomposition into evidence collector + specialist fan-out (4e89083)
• specialist agent architecture — scanner decomposition (67faf02)

Bug Fixes

• add pixelslop-code-scanner to installer AGENT_FILES (ecd2116)
• address Codex review — paths, schema fields, slop coverage, responsiveness evidence (91c7b49)
• Codex round 2 — schema/snippet alignment, test lockdown, evaluator field refs (19fdb7d)
• remaining Codex review items — schema drift, title, uninstall safety (2034284)

0.2.3 (2026-03-25)

Features

• add interactive multi-runtime installer (58afd63)

0.2.2 (2026-03-25)

Features

• code-check mode for source-only design analysis (f348e16)
• cognitive load, heuristics, interaction design, context caching (1c2ef21)

Bug Fixes

• serve tests wait for TCP socket before fetching (3e6cd06)

0.2.1 (2026-03-24)

Features

• pixelslop v0.1.0 — browser-first design quality scanner (c80a7c3)
• static site support, interactive discovery, two-phase architecture, debug logging (635b314)

Bug Fixes

• add focus-visible outlines for nav links, buttons, CTAs, tabs, and footer links (4b7d653)
• add prefers-reduced-motion query to disable animations for motion-sensitive users (08af8df)
• add screen-reader description for gallery images hidden by aria-hidden track (b87c690)
• add skip navigation link and main landmark for keyboard/screen reader users (6ce17b1)
• add srcset and sizes to hero image for responsive image loading (d3e6129)
• bump minimum font sizes for menu tags and labels (b8a40a8)
• clone gallery images via JS instead of duplicating in HTML (66ec376)
• darken muted text from #7C6D5F to #716356 for AA contrast on cream backgrounds (eb1fee7)
• darken muted text from #8A7B6E to #7C6D5F for AA contrast compliance (5f6bb2a)
• darken terracotta accent from #C4613A to #B25531 for AA contrast compliance (a61be70)
• enforce 44px minimum touch targets on mobile interactive elements (4549354)
• improve form label and placeholder contrast on dark charcoal background (216ea25)
• lighten footer text for AA contrast compliance on dark background (eda8403)
• replace static 2024 copyright with dynamic current year (0772a68)
• replace transition: all with scoped properties on .btn, .menu__tab, .footer__social a (fe61000)

0.2.0 (2026-03-24)

Features

• Static site support — discover static-site detects HTML folders, serve start/stop runs a zero-dependency Node HTTP server on a free port. Plain HTML projects work without a dev server or Python.
• Interactive discovery — SKILL.md uses AskUserQuestion to confirm server selection, temp server startup, and fix strategy before the orchestrator touches anything.
• Two-phase architecture — scan and fix run as separate orchestrator spawns. Plan file (.pixelslop-plan.md) is the handoff contract between phases. No more giant JSON blobs in prompt strings.
• --debug flag — opt-in session logging to .pixelslop-session.log. Auto-logging piggybacks on plan update, checkpoint create/revert, gate run, and init scan so subagent activity gets traced without model cooperation.
• --force on plan begin — replaces stale plans from previous sessions instead of erroring out.
• Per-project state scoping — temp server PID, session log, and plan files resolve via --root, not global CWD. Multiple projects can run concurrent sessions.
• docs/ — five focused docs (getting-started, troubleshooting, architecture, pixelslop-tools reference, personas). README slimmed from 183 to 76 lines.

Bug Fixes

• Plan file created in repo root instead of project dir when --root pointed elsewhere
• Session log wrote to CWD instead of project root
• macOS resource fork files (._index.html) polluted static site detection
• Unix-only sleep 0.1 in temp server startup replaced with cross-platform sync wait
• Stale plan from previous session blocked plan begin with no workaround
• Multiline log messages broke the line-based session log format

Architecture

• Subagents confirmed unable to use AskUserQuestion (Claude Code issues #12890, #18721). Parent session owns all user interaction, orchestrator runs to completion.
• SendMessage relay pattern tested and rejected — too fragile. File-based handoff via .pixelslop-plan.md is reliable.
• Orchestrator split into scan-only and fix-from-plan modes based on plan file presence at startup.

Tests

• 470 tests (was 443). New coverage: static site detection, temp server lifecycle, session logger, --force flag, --debug auto-logging, per-project state scoping.

0.1.1 (2026-03-20)

Features

• pixelslop v0.1.0 — browser-first design quality scanner (c80a7c3)

0.1.0 (2026-03-19)

Features

• Scanner with 5-pillar scoring and 25 AI slop patterns
• Fixer/checker fix-verify-rollback loop with checkpoints
• Orchestrator coordinating full scan→fix→verify workflow
• pixelslop-tools CLI for deterministic state management
• Installer for Claude Code and Codex CLI (npx pixelslop install)
• 8 built-in persona evaluation profiles
• --thorough mode and --personas flag
• Monorepo workspace detection
• 6 additional code check patterns (S11-S16)
• update command with backup and file diff output