feat(css-trace): inspect CSS rules affecting a DOM element

[JonasJesus42]

Summary

New parity css-trace command that uses Chrome DevTools Protocol (CSS.getMatchedStylesForNode) to enumerate every CSS rule contributing to a target element, grouped by stylesheet source. Two modes:

• Single URL: parity css-trace --url <url> --selector <sel> — lists all matched rules + computed styles.
• Compare: parity css-trace --prod <url> --cand <url> --selector <sel> — traces both and diffs computed style values.

--filter <prop1,prop2,...> scopes the output to specific properties.

Why

Real bug encountered debugging the Bagaggio TanStack migration: the delivery drawer hung short of the viewport's right edge on desktop. Root cause was daisyUI v5's :root { scrollbar-gutter: var(--page-scroll-gutter, unset) } paired with the drawer-toggle rule flipping --page-scroll-gutter to stable when any drawer opens — reserving ~15px on the right that the position: fixed; width: 100% drawer couldn't reach.

Finding this required grep -h scrollbar-gutter node_modules/daisyui/**/*.css to enumerate library rules. parity css-trace --url <site> --selector html --filter scrollbar-gutter would have surfaced the rule and its source in seconds.

Example

$ parity css-trace --url http://localhost:5173 --selector html --filter scrollbar-gutter

── RESULT ────────────────────────────────────────────
URL: http://localhost:5173
Selector: html

  Computed:
    scrollbar-gutter: auto

  Rules (ordered by CDP — most specific last):
    stylesheet#... (/*! tailwindcss v4.2.4 ...)
      html {
        scrollbar-gutter: auto !important;
      }
    stylesheet#... (/*! tailwindcss v4.2.4 ...)
      (no selector text) {
        scrollbar-gutter: var(--page-scroll-gutter, unset);
      }

Implementation notes

• Uses Playwright's page.context().newCDPSession(page) — no extra deps.
• CSS.getStyleSheetText previews the first ~100 chars of each stylesheet to disambiguate sources (daisyUI vs app.css vs Tailwind utilities) since CDP doesn't return the URL.
• Strips trailing !important baked into CDP property values and infers the flag, so output doesn't render !important !important.
• :where(...) / anonymous-selector rules print as (no selector text) instead of an empty {.
• --viewport mobile|tablet|desktop reuses the existing presets so viewport-dependent rules (media queries, viewport-units) line up with the regular run flow.

Test plan

• bun run check passes
• Single-URL mode runs against localhost and lists matched rules with source attribution
• Compare mode against two URLs prints prod/cand sides + computed-style diff
• Try on the live Bagaggio repro (drawer not flush-right) before the fix lands — confirms the daisyUI scrollbar-gutter rule shows up

🤖 Generated with Claude Code

---

Summary by cubic

Adds a new parity css-trace command to inspect which CSS rules affect a DOM element and optionally diff computed styles between two URLs. Now also traces inherited rules and marks their ancestor level for clearer debugging.

• New Features

  • Modes: Single URL and Compare; shows computed styles and matched rules grouped by stylesheet.
  • Inheritance: includes rules from ancestors and labels them as "↑ inherited from ancestor (N)".
  • Filters & output: --filter to limit properties, --json for machine-readable output; --viewport presets and --settle <ms> to wait after load.
  • CDP: Uses Chrome DevTools via playwright; strips !important duplicates and prints anonymous selectors as (no selector text).

• Bug Fixes

  • CLI validation: enforce --url is mutually exclusive with --prod/--cand; require both for comparison; clear error messages.
  • Replaced unused template literals with strings to satisfy Biome and restore CI.

^{Written for commit afe2a9a. Summary will update on new commits. Review in cubic}

[cubic-dev-ai]

2 issues found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/cli.ts">

<violation number="1" location="src/cli.ts:205">
P2: Documented mutual-exclusion constraint between --url and --prod/--cand is not enforced in the action handler. Add a validation check that exits with a clear error message if conflicting options are provided, and that requires at least one URL mode.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: Documented mutual-exclusion constraint between --url and --prod/--cand is not enforced in the action handler. Add a validation check that exits with a clear error message if conflicting options are provided, and that requires at least one URL mode.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/cli.ts, line 205:

<comment>Documented mutual-exclusion constraint between --url and --prod/--cand is not enforced in the action handler. Add a validation check that exits with a clear error message if conflicting options are provided, and that requires at least one URL mode.</comment>

<file context>
@@ -196,6 +197,37 @@ program
+  .description(
+    "Inspect which CSS rules (from which stylesheets) are affecting a DOM element. Single URL mode lists every matched rule; --prod + --cand mode diffs computed styles between Fresh and TanStack sides.",
+  )
+  .option("--url <url>", "Single URL to inspect (mutually exclusive with --prod/--cand)")
+  .option("--prod <url>", "Production URL (for comparison mode)")
+  .option("--cand <url>", "Candidate URL (for comparison mode)")
</file context>