Cls

Lab CLS

Load CLS.md before touching critical CSS for shift. Measure with npm run profile:cls rather than asking the user for DevTools.

This is not Argos and not window.profiler:

• Argos is post-hydrate screenshots at 390 / 834 / 1440. CLS mobile is 412×823. Visual checks: visual-test.
• profile:app / profile:load are timing. Layout shift is this skill. performance-profiling.

Measure

npm run profile:cls
npm run profile:cls -- --preset mobile
npm run profile:cls:check
npm run profile:cls:delayed
npm run profile:cls:baseline:delayed
npm run profile:cls:check:delayed

Production vite preview with ?debug=false. Default port 4179. Culprits are in the JSON layout-shifts nodes, not the CLS audit debugdata.

Two labs:

• Un-delayed profile:cls:check is the hydrate floor (cls-budgets.json).
• Delayed profile:cls:check:delayed (--delay-css-ms 3000) is the jump gate (cls-budgets-delayed.json). A delayed run with delayedStylesheetHits 0 is a broken proxy, not a green jump. --check --preset gates only that viewport. Do not paste delayed medians into cls-budgets.json.

diff:cls-profile always exits 0. A hostUserAgent warning is Chrome-build churn (chrome-version: latest), not a layout regression.

Both budget files are slack around a CI median, never Google's 0.1. Delayed tablet sits above 0.1 today; green there means the jump has not grown, not that it is fixed.

See CLS.md.

Do not hand-edit scripts/profile/cls-budgets.json or delayed budgets without the matching CI cls-profile artifact. Local macOS medians will not match Linux CI.

After a Lighthouse bump, refresh tests/fixtures/lighthouse/lhr-delayed.json via the recipe in CLS.md (trimmed --save-lhr dump). Do not reshape the JSON by eye.

Debug

1. Hydrate floor: layout-shifts nodes in tmp/cls-profile.json. Jump: tmp/cls-profile-delayed.json or profile:cls:delayed at the same --preset. If culprits are empty or you need the raw audits, --save-lhr locally with the same delay as that lab — the GitHub artifact is not an LHR. CLS.md section 6.
2. Dump the matching viewport: CLS mobile → npm run compute-style-dump:lighthouse-mobile (412×823), not compute-style-dump:mobile (Argos 390). Tablet / mediumDesktop use the same-named dump presets.
3. Dumps are post-hydrate. A hydrate-only jump will not show as a single-URL dump diff.

After a CSS change run un-delayed and delayed profile:cls and npm run test:visual. New skill folder: npm run skills:link so .claude/skills/cls exists (gitignored).