web-performance

Name: web-performance
Author: millionco

3installs12forks

How to install web-performance?

millionco/debug-agent/web-performance

$npx -y skills add millionco/debug-agent --skill web-performance

Installs into the current project.

Summary

Use when the user reports jank, dropped frames, janky scrolling, slow click or typing response, poor INP, slow LCP, layout shifts (CLS), unresponsive pages, or asks to debug rendering, animation, or interaction performance in a browser app.

Files · 1

View on GitHub

SKILL.md

1	# Web Performance
2
3	## Overview
4
5	Browser performance debugging via `PerformanceObserver`, with LoAF (`long-animation-frame`) as the primary signal. LoAF is the only entry type that, in one record, attributes a slow frame to a specific `sourceURL` + `sourceFunctionName` + `sourceCharPosition` + `invokerType`, with per-script `forcedStyleAndLayoutDuration` (sync reflow), `pauseDuration` (sync XHR / `alert`), and `blockingDuration`. Code inspection and `performance.now()` cannot reach this. Start with LoAFs, conclude from LoAFs.
6
7	## When to use
8
9	Symptoms:
10
11	- Jank, dropped frames, janky scroll/swipe, complaints about frame rate
12	- Slow click / keypress / touch response, "unresponsive" complaints, poor INP
13	- Slow LCP, layout shifts (CLS)
14	- Animation stutter, transition jank, expensive renders during interaction
15
16	Do NOT use for:
17
18	- Backend / non-browser perf — use raw NDJSON file appends from your server runtime
19	- Memory leaks, bundle-size regressions — heap snapshots / bundle analyzers
20	- Logic bugs unrelated to timing — use raw fetch instrumentation
21
22	## Core pattern
23
24	Before — manual `performance.now()` (wrong):
25
26	```js
27	const t0 = performance.now();
28	drawSeries(data);
29	console.log("drawSeries took", performance.now() - t0);
30	```
31
32	Tells you a number. Doesn't tell you the function caused a long frame, what scheduled it, or whether it forced sync layout. Requires you to _already suspect_ `drawSeries`.
33
34	After — LoAF observer (right):
35
36	```js
37	new PerformanceObserver((list) => {
38	for (const loaf of list.getEntries()) send(loaf);
39	}).observe({ type: "long-animation-frame", buffered: true });
40	```
41
42	Reports every frame `> 50ms` across the whole page, with `scripts[].sourceURL` + `sourceFunctionName` + `sourceCharPosition` + `invokerType` + `forcedStyleAndLayoutDuration` for each script that ran in the frame. You don't need to know where the bug is in advance.
43
44	## Workflow
45
46	1. Generate 3-5 hypotheses about what's slow and where.
47	2. Start the logging server (Implementation → STEP 0).
48	3. Inject the LoAF observer as the first script in `<head>` or top of SPA entry.
49	4. Reproduce — automate via Playwright/Puppeteer if possible; otherwise give numbered steps and ask the user to confirm in their UI (do NOT ask them to type "done").
50	5. Clear the log file before each run via the deletion tool (NOT `rm`).
51	6. Analyze LoAFs first; consult secondary signals only if LoAF is silent. Mark hypotheses CONFIRMED / REJECTED / INCONCLUSIVE with cited entries.
52	7. Fix only with 100% confidence. Keep instrumentation in place; tag post-fix runs with `runId="post-fix"`.
53	8. Verify by re-running and comparing before/after LoAFs with cited lines. If failed, revert rejected-hypothesis code (keep instrumentation), generate new hypotheses, iterate.
54	9. Cleanup — remove the `#region debug log` block only after verified success + explicit user confirmation.
55
56	## Implementation
57
58	### STEP 0: Start the logging server (background-only)
59
60	```bash
61	npx debug-agent@latest --json --daemon
62	```
63
64	`--daemon` forks the server into a detached process and exits immediately (your shell unblocks instantly — no need for `&`/`nohup`). `--json` makes the parent emit one machine-readable JSON line (without it you get a colored spinner). It prints one JSON line on startup:
65
66	```json
67	{
68	"sessionId": "a1b2c3",
69	"endpoint": "http://127.0.0.1:54321/ingest/a1b2c3",
70	"logPath": "/tmp/debug-agent/debug-a1b2c3.log"
71	}
72	```
73
74	Capture `endpoint` (POST traces here), `logPath` (NDJSON written here on macOS at `/var/folders/.../T/debug-agent/debug-<sessionId>.log`), `sessionId` (in every payload). The log file is auto-created on first write — do NOT pre-create. Server is idempotent: re-running `--json --daemon` returns the same `sessionId`/`port`/`logPath` of the existing server, so it's safe to call at the start of every session. If startup fails, STOP and inform the user.
75
76	To clear the log file via HTTP without deleting/recreating it: `curl -X DELETE <endpoint>` returns `{"ok":true,"cleared":true}`.
77
78	### STEP 1: Inject the LoAF observer
79
80	Replace `__ENDPOINT__` and `__SESSION_ID__`. Paste once as the very first script in `<head>` (above framework bootstrap), or top of the SPA entry module (`main.tsx`, `index.ts`, `app.tsx`). One IIFE in one `#region debug log` block.
81
82	```html
83	<script>
84	// #region debug log
85	(() => {
86	const ENDPOINT = "__ENDPOINT__";
87	const SESSION_ID = "__SESSION_ID__";
88	const send = (kind, payload) =>
89	fetch(ENDPOINT, {
90	method: "POST",
91	headers: { "Content-Type": "application/json" },
92	body: JSON.stringify({
93	sessionId: SESSION_ID,
94	location: "PerformanceObserver:" + kind,
95	message: kind,

People who liked this also viewed

6 picks

Type

web-performance

3installs12forks

View on GitHub

How to install web-performance?

millionco/debug-agent/web-performance

$npx -y skills add millionco/debug-agent --skill web-performance

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Web Performance
2
3	## Overview
4
5	Browser performance debugging via `PerformanceObserver`, with LoAF (`long-animation-frame`) as the primary signal. LoAF is the only entry type that, in one record, attributes a slow frame to a specific `sourceURL` + `sourceFunctionName` + `sourceCharPosition` + `invokerType`, with per-script `forcedStyleAndLayoutDuration` (sync reflow), `pauseDuration` (sync XHR / `alert`), and `blockingDuration`. Code inspection and `performance.now()` cannot reach this. Start with LoAFs, conclude from LoAFs.
6
7	## When to use
8
9	Symptoms:
10
11	- Jank, dropped frames, janky scroll/swipe, complaints about frame rate
12	- Slow click / keypress / touch response, "unresponsive" complaints, poor INP
13	- Slow LCP, layout shifts (CLS)
14	- Animation stutter, transition jank, expensive renders during interaction
15
16	Do NOT use for:
17
18	- Backend / non-browser perf — use raw NDJSON file appends from your server runtime
19	- Memory leaks, bundle-size regressions — heap snapshots / bundle analyzers
20	- Logic bugs unrelated to timing — use raw fetch instrumentation
21
22	## Core pattern
23
24	Before — manual `performance.now()` (wrong):
25
26	```js
27	const t0 = performance.now();
28	drawSeries(data);
29	console.log("drawSeries took", performance.now() - t0);
30	```
31
32	Tells you a number. Doesn't tell you the function caused a long frame, what scheduled it, or whether it forced sync layout. Requires you to _already suspect_ `drawSeries`.
33
34	After — LoAF observer (right):
35
36	```js
37	new PerformanceObserver((list) => {
38	for (const loaf of list.getEntries()) send(loaf);
39	}).observe({ type: "long-animation-frame", buffered: true });
40	```
41
42	Reports every frame `> 50ms` across the whole page, with `scripts[].sourceURL` + `sourceFunctionName` + `sourceCharPosition` + `invokerType` + `forcedStyleAndLayoutDuration` for each script that ran in the frame. You don't need to know where the bug is in advance.
43
44	## Workflow
45
46	1. Generate 3-5 hypotheses about what's slow and where.
47	2. Start the logging server (Implementation → STEP 0).
48	3. Inject the LoAF observer as the first script in `<head>` or top of SPA entry.
49	4. Reproduce — automate via Playwright/Puppeteer if possible; otherwise give numbered steps and ask the user to confirm in their UI (do NOT ask them to type "done").
50	5. Clear the log file before each run via the deletion tool (NOT `rm`).
51	6. Analyze LoAFs first; consult secondary signals only if LoAF is silent. Mark hypotheses CONFIRMED / REJECTED / INCONCLUSIVE with cited entries.
52	7. Fix only with 100% confidence. Keep instrumentation in place; tag post-fix runs with `runId="post-fix"`.
53	8. Verify by re-running and comparing before/after LoAFs with cited lines. If failed, revert rejected-hypothesis code (keep instrumentation), generate new hypotheses, iterate.
54	9. Cleanup — remove the `#region debug log` block only after verified success + explicit user confirmation.
55
56	## Implementation
57
58	### STEP 0: Start the logging server (background-only)
59
60	```bash
61	npx debug-agent@latest --json --daemon
62	```
63
64	`--daemon` forks the server into a detached process and exits immediately (your shell unblocks instantly — no need for `&`/`nohup`). `--json` makes the parent emit one machine-readable JSON line (without it you get a colored spinner). It prints one JSON line on startup:
65
66	```json
67	{
68	"sessionId": "a1b2c3",
69	"endpoint": "http://127.0.0.1:54321/ingest/a1b2c3",
70	"logPath": "/tmp/debug-agent/debug-a1b2c3.log"
71	}
72	```
73
74	Capture `endpoint` (POST traces here), `logPath` (NDJSON written here on macOS at `/var/folders/.../T/debug-agent/debug-<sessionId>.log`), `sessionId` (in every payload). The log file is auto-created on first write — do NOT pre-create. Server is idempotent: re-running `--json --daemon` returns the same `sessionId`/`port`/`logPath` of the existing server, so it's safe to call at the start of every session. If startup fails, STOP and inform the user.
75
76	To clear the log file via HTTP without deleting/recreating it: `curl -X DELETE <endpoint>` returns `{"ok":true,"cleared":true}`.
77
78	### STEP 1: Inject the LoAF observer
79
80	Replace `__ENDPOINT__` and `__SESSION_ID__`. Paste once as the very first script in `<head>` (above framework bootstrap), or top of the SPA entry module (`main.tsx`, `index.ts`, `app.tsx`). One IIFE in one `#region debug log` block.
81
82	```html
83	<script>
84	// #region debug log
85	(() => {
86	const ENDPOINT = "__ENDPOINT__";
87	const SESSION_ID = "__SESSION_ID__";
88	const send = (kind, payload) =>
89	fetch(ENDPOINT, {
90	method: "POST",
91	headers: { "Content-Type": "application/json" },
92	body: JSON.stringify({
93	sessionId: SESSION_ID,
94	location: "PerformanceObserver:" + kind,
95	message: kind,

People who liked this also viewed

6 picks

Type