web-performance-debugger AGENTS.md

Driving wpd from an agent

For an agent consuming wpd. wpd finds and investigates; it does not grade, rank, or recommend. It hands you typed, measurement-tagged numbers and a clean exit code; the judgment stays with you.

The loop

1. Record. wpd record <module> [flags] writes a recording plus siblings. One record is one capture pass.
2. Query. Read the recording through the query verbs. Never read the recording file directly -- it can be many MB. Drill instead:

query spans <file>              # overview: one row per span, one shape across chrome/firefox/node
  -> query span <file> <kind:label>   # one span's full anatomy
       -> query get <file> <id>       # one raw event (stack + args); needs --deep or firefox

• Every verb takes latest in place of <file> (a cwd-keyed pointer, never resolved by mtime).
• Span identity is kind + label. A bare label that matches more than one kind is a collision; qualify it (run, step:first increment, measure:hydrate).
• query spans --label X with no match is a filter: it reports the empty result and exits 0. query span X with no match is a lookup: it exits 1. Pick the verb for the branch you want.
• Other verbs: query cpu (hot functions + rollup), query frame <id> (one function's callers and callees), query blame --forced (forced-layout read sites), query events (the raw log).

Output

• Always pass --format json or --format toon. Both are plain: no ANSI, whatever the TTY. TOON is a compact, JSON-shaped text format that spends fewer tokens than JSON.
• The view shapes are typed and exported from the package root (SpansResult, SpanAnatomy, CpuOverview, CpuDiffResult, ...). Import them; do not hand-roll a shape.

Reading the numbers: three traps

• null is not 0. A count or slice the capture could not observe is an explicit null (not-measured), never 0 (measured clean). Do not coerce it. A gate on such a metric is a loud n/a FAIL, never a silent pass: assert --max-forced 0 on a --breakdown recording FAILs, because forced counts need --deep.
• jsSelfMs is the JS headline. Do not denominate a package share on activeMs -- the larger non-idle total (js + gc + engine).
• A function's display name is fn, not name (its self time is selfMs, its source source).
• The full field reference: README, Consuming the JSON.