agentleFS
naomiaronaomiaro/waveform-playlist/.claude/skills/browser-probes/SKILL.md

browser-probes

Skill1.7k starsChanged yesterdayMITView on GitHub

Use when measuring or checking behaviour in a real browser outside the e2e suite - an ad-hoc Playwright script, the probes/ scripts, a chrome-devtools, claude-in-chrome or Playwright MCP session - to count React renders or engine rebuilds, time a drag, compare two branches, tap the audio graph, verify exported audio, or check keyboard and focus behaviour.

Trending

Quiet this year.thin dataabout the whole repository

Dec 2025: 0 mentionsJan 2026: 0 mentionsFeb 2026: 0 mentionsMar 2026: 0 mentionsApr 2026: 0 mentionsMay 2026: 0 mentionsJun 2026: 0 mentionsJul 2026: 0 mentionsAug 2026: 0 mentionsSep 2026: 0 mentionsOct 2026: 0 mentionsNov 2026: 0 mentions
Dec 2025Jun 2026Nov 2026
Mentions a month of the naomiaro/waveform-playlist repository that our weekly crawl found: only 11 in all, so this is a hint, not a trend. There is no adoption data for this file yet.

Who's talking about naomiaro/waveform-playlist

The biggest 5 of 11 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 11

Talked about on GitHub, Stack Overflow and Hacker News (11 times).

On GitHub · 8

3 more on GitHub

On Stack Overflow · 2

On Hacker News · 1

The file

Files
SKILL.md

Browser probes

For specs in e2e/ and the rules for dev servers during a test run see the skill e2e-playwright. The port 3000 check in root CLAUDE.md applies before any server is started.

MCP browsers and ad-hoc scripts

  • Ad-hoc headless Playwright smoke scripts from the scratchpad — NODE_PATH=$PWD/node_modules node <scratch>/smoke.cjs (the script lives outside the repo, so require('@playwright/test') fails without it). Start the site with cd website && pnpm exec docusaurus start --port 3000 --no-open first; stop it (lsof -tiTCP:3000 -sTCP:LISTEN | xargs kill — plain -ti: also lists CLIENT sockets and killed a Chrome helper once) before pnpm --filter website build — they share the compile cache.
  • Refresh between scenarios when using browser_evaluate — the page persists across eval calls in one MCP session; state from prior interactions can silently invalidate assertions (e.g. "first M-click reports muted=false" because a prior eval already toggled it). Call browser_navigate to the same URL to reset before each independent reproduction.
  • Example pages that restore persisted state (e.g. dawcore-wam's localStorage chains) shift layout after load — pointer clicks can land on moved elements and silently miss. Drive verification with element.click() inside browser_evaluate, or clear storage / wait for restore before clicking.
  • MCP-automated browser tabs are usually backgrounded (document.visibilityState === 'hidden') → requestAnimationFrame is throttled to ~0, freezing the rAF-driven playhead/time regardless of code. When debugging playback/recording via chrome-devtools or claude-in-chrome MCP, check visibilityState/rAF liveness FIRST; assert on rAF-independent state (currentTime from setState, clip DOM left, console logs) or have the user foreground the tab. A "frozen playhead" in a hidden tab is almost always this, not a bug. Hidden tabs ALSO throttle setTimeout to ~1s, so setTimeout-based waits crawl — the recording stop-handshake/drain loop can take tens of seconds to finalize a clip in automation; verify record→stop on a foreground tab.
  • No browser automation here can HIDE a tab — claude-in-chrome activates a tab only for the duration of an action and restores the previous one, and headless Playwright's bringToFront() leaves every page visible; document.visibilityState === 'hidden' behaviour (timer throttling, Worker-vs-rAF) needs a human switching tabs.
  • Playwright MCP element screenshots (target:) can capture a stale frame disagreeing with live DOM state during rAF-driven animation (playhead/progress) — use viewport screenshots (no target) for animated-UI evidence, and assert positions by sampling the DOM (el.style.transform) rather than trusting the image.
  • Playwright MCP screenshots with relative filenames land in the repo root (plus logs in .playwright-mcp/) — untracked clutter that can slip into git add -A. Delete them before committing, or pass absolute scratchpad paths.
  • Keyboard and focus behaviour: what automation can and cannot show. (1) In Chromium :focus-visible matches the focused element as soon as any key is pressed, including during the keydown being handled, so it cannot tell pointer focus from keyboard focus in a key handler; use it for styling only. (2) Headless browsers open no real <select> popup, and claude-in-chrome's key presses are injected through the debugger: they reach the page but bypass a native macOS dropdown menu (the value does not change, select:open stays false). What a key does with a native popup open needs a human. (3) happy-dom does not retarget event.target across a shadow boundary and neither happy-dom nor jsdom implements checkVisibility(); shadow-DOM key handling is proven by e2e/dawcore-keyboard-focus.spec.ts, not by unit tests. (4) A button that becomes disabled while focused drops focus to <body> in Chromium (the React Play button relies on this; Firefox and Safari unverified).
  • A screenshot of a Storybook story, both themes, without the Storybook UI: from packages/ui-components, pnpm exec storybook dev -p 6016 --no-open --exact-port (it reads source, no build; about a minute to the first page), then load http://localhost:6016/iframe.html?id=components-clip--placeholder-with-peaks&viewMode=story&globals=theme:dark in a Playwright script (require @playwright/test from the repo's node_modules) and wait for a selector of the component. The id is the story's title and export name in kebab case. Stop it by its listener: lsof -nP -iTCP:6016 -sTCP:LISTEN -t | xargs kill.
  • "The picture mid-drag equals the picture after release" proves nothing when both can be stale. On #812 a spectrogram under a trim preview was the pre-trim picture drawn from the clip's new edge, during the drag AND after release; comparing those two called it fine. Compare against a reference that cannot be stale (the picture from BEFORE the action at the same timeline position, and the same picture shifted by the drag distance: one of the two differences must be 0), and run the same probe on the parent commit.
  • Comparing screenshots without an image library (no PIL, no pngjs here): take the screenshots with a fixed clip rectangle, pass them as base64 into page.evaluate, draw each onto a canvas through an Image and read getImageData; sum the colour differences over a band of the picture (trim5/spectro2.cjs in the session scratchpad of #812 did this; copy the approach, the file is not kept).
  • A combination no example page has (spectrogram plus trim handles) is probed with a throwaway edit of an example, asserted (python3 with a match count per replacement), run under my own dev server, and removed with git checkout -- <file> before anything else; git status --short must be empty before the next agent is dispatched. For the parent commit's behaviour: stop the server, git checkout <parent> -- packages/<pkg>/src, start the server, measure, stop it, git restore --source=HEAD --staged --worktree -- packages.

Measuring React work

  • Measuring React work in the browser without the Profiler (dev build only): page.addInitScript a stub window.__REACT_DEVTOOLS_GLOBAL_HOOK__ (supportsFiber, inject, onCommitFiberRoot, onCommitFiberUnmount, onPostCommitFiberRoot, checkDCE); onCommitFiberRoot(_, root) fires per commit. To count which components rendered, walk root.current and count function/memo fibers with alternate === null || flags & 1, but do NOT descend into a fiber whose child === alternate.child: that subtree bailed out and its fibers carry stale flags (without this the whole page counts as rendered). Wrap CanvasRenderingContext2D.prototype.clearRect to count canvas redraws. Used for #692 (trim) and #693 (selection drag). A render count is not a cost. To answer "would a user notice", add time to the same probe (#733): fiber.selfBaseDuration summed per component name (which components the time goes to), root.current.actualDuration per commit, and over CDP (page.context().newCDPSession(page)) Performance.getMetrics ScriptDuration/TaskDuration before and after the moves, run again under Emulation.setCPUThrottlingRate 4. Run it on the page with the heaviest consumers, not only the one the issue names: #733 looked not worth doing on multi-clip (1.1 ms per move) and clearly was on annotations (19.8 ms at 4x throttle). Measure both directions of a drag: a leftward selection drag also moves the cursor and takes a different path through the contexts. For work that happens with no input at all (meters, a recording in progress), count per SECOND over a fixed window in each steady state instead of per pointer move: reset the counters, wait 3 s, read (#695: idle, recording, playing on /examples/recording). A state that should be quiet reads exactly 0 commits, which is also a cheap e2e assertion (e2e/recording.spec.ts installs the same stub hook and bounds commits over 2 s).
  • Counting engine builds in a browser: not with waveform-playlist:ready since #812. The event fires once per provider mount (useReadyOnce), so it no longer counts builds; that a track change builds no engine is pinned in packages/browser/src/__tests__/engineLifetime.test.tsx with a counting adapter factory. data-playlist-state was never a count either: it goes ready → loading → ready only when React commits in between, and a rebuild whose adapter resolves within one batch never shows loading (an e2e test that watched the attribute passed against the code it was written to catch, #752).
  • In the fiber-walk probe, a context consumer rendered directly under the provider (no component in between, e.g. <MediaElementWaveform> as a child of the provider) is charged to the provider (the provider renders on its own state change and passes the flag down through its stable children). "Everything is under the provider root" therefore does not mean the provider's parent re-rendered; once the consumers stop following the value they appear as their own roots.
  • A probe can only show a gain the page lets it show. #767 made the controls value stable; on /examples/multi-clip the count was 259 components per trim move before and after, because the example component holds tracks and re-renders its toolbar anyway. Say in the design what the example pages can show, and when the answer is "nothing", measure the claim where it holds (a unit render count with children passed through as one constant element). Also on that page: five clips end at 20 s, so trimming "the last clip" does not change duration until the other four are shortened (probes/trim767.cjs does that first).
  • Prototype two candidates on one build with a URL switch. A ?proto=a|b read at module scope in the example component, a throwaway local branch, the probes run with the query in the route argument (trim767.cjs 3077 'multi-clip?proto=slot'), then git diff saved to the scratchpad and the branch deleted. #685: per-clip children written inline rendered 384 components per trim move against 94 for markers.
  • "It may paint unpositioned for a frame" can be measured. A reviewer read that a playhead mounted as playback starts has no transform until its first frame callback. probes/flash688.cjs installs a MutationObserver for the element and records its style.transform when added and in the next three animation frames: by the first frame it was at the range start, 8 loads of 8 on both kinds of page (Chromium). Run that before proposing a fix for a first-frame concern.

The probe scripts

  • A page that loads is not a page that works: press its controls. probes/exercise685.cjs [port] [route…] loads each of the 21 React example pages, clicks the waveform and every button and checkbox, and reports page errors, the error boundary's text and misplaced-part warnings. The e2e routes cover 16 of those pages and probes/shotsAll685.cjs <tag> <outdir> [port] [route…] records geometry only (give it NEWTRACKS_FILE=<audio file> for /examples/newtracks, which has no playlist until a file is added). Run both after converting examples.
  • probes/shotsAll685.cjs records 17 pages by default, not 21. For the other four pass them as routes: … <tag> <outdir> 3077 beats-and-bars minimal newtracks stereo (with NEWTRACKS_FILE). exercise687.cjs does cover all 21.
  • Comparing probe logs between two runs: strip the timings and sort the lines before diff; the root lines of one commit come out in a different order from run to run, and draggables in the geometry file is the dnd-kit count that differs between loads.
  • The count of dnd-kit aria-roledescription="draggable" attributes on a page differs between loads on pages without a ClipInteractionProvider (effects: 3 or 4; stem-tracks: 21 to 24; ten loads each on main and on the branch). Do not compare it in a before/after probe.
  • To see "peak data that cannot be read" in a browser, serve the .dat with its samples_per_pixel field multiplied (probes/emptyrow685.cjs: a page.route handler that fetches the file and rewrites bytes 12 to 15); the resample to the provider's finer zoom then throws.
  • Probes for annotations: probes/cont686.cjs (box and row click against continuous play), probes/kbd686.cjs (keyboard drag of an edge handle), probes/mutate686.py (mutants across two packages, per-file test lists; takes a name filter), probes/proto686/ (the prototype diff with its URL switches).

Audio

  • Pages importing tone have ≥2 AudioContexts — Tone's orphaned default (created at import, before getGlobalContext()/configureGlobalContext replaces it) coexists with the app's global one; in native mode both are native AudioContexts and the orphan can even report running. When instrumenting the graph (analyser taps, context probes), select by MEASURED SIGNAL (RMS > 0), never by constructor name or state.
  • Tapping master output in apps that don't expose their graph (React provider pages): page.addInitScript a shim wrapping AudioNode.prototype.connect that reroutes destination-bound connects through a created AnalyserNode (analysers are pass-throughs) — captures the true final mix for RMS/spectral assertions. Must be injected BEFORE page load.
  • An AudioWorkletProcessor that returns false while nothing is connected does not run again in Chrome when it is reconnected (#751: a tremolo bypassed by disconnection stayed silent after un-bypass, 5 runs of 5; a reviewer had recommended return false so removed effects stop). Return true until a 'dispose' message arrives on the port. Review advice about audio behaviour gets a real-browser test before it is taken.
  • An AnalyserNode reading contains the last 2048 samples (about 43 ms). An assertion made right after a click can pass on audio from before it. Wait for context.currentTime to advance past the buffer first (waitForFreshAudio in e2e/custom-effects.spec.ts), or assert a value only fresh audio can produce (exactly 0 on a tap whose input was just cut).
  • Tapping one node's output: an init script that wraps AudioNode.prototype.connect and, when this is the node of interest, also connects it to an analyser kept on window. Re-tap on every call: a chain that rewires disconnects all of the node's outputs, the tap included. Exclude offline contexts (this.context instanceof AudioContext).
  • Verifying WAV-export output in a live browser: wrap URL.createObjectURL and filter captured blobs by type === 'audio/wav' — WAM hosting also creates text/javascript worklet blobs (a fresh set appearing per export is direct evidence of offline plugin re-instantiation). For per-track effect A/B, SOLO the affected track before comparing: a single-stem diff diluted across N stems can fall below a whole-mix RMS threshold (8.1% full-mix vs 51.9% soloed, identical absolute diff) — strengthen the measurement, never weaken the threshold. Sanity baseline: two fully-bypassed exports must be byte-identical (diff-RMS exactly 0).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.