@buoy-gg/mcp 7.0.52 → 7.0.54

package/dist/index.mjs

@@ -1 +1 @@
-import{ALL_DEVICES as e,BROKER_PORT as o,BROKER_URL as r,DASHBOARD_NAME as t,DEFAULT_ACTION_TIMEOUT_MS as s,DEFAULT_SNAPSHOT_TIMEOUT_MS as i,PACKAGE_NAME as T,SyncClient as n,VERSION as a,buildAutomationConfig as g,compareReportStats as l,createMcpServer as E,estimateBatchMs as R,formatRankingMarkdown as A,getUpdateNotice as S,rankBatchFromIndex as _,registerConsoleTools as c,registerEventsTools as M,registerGenericTools as m,registerJotaiTools as O,registerPerfMonitorTools as p,registerReactQueryTools as u,registerReduxTools as I,registerRoutesTools as d,registerScreenshotTools as C,registerStorageTools as N,registerZustandTools as U,runInit as B}from"./chunk-JULJYHPG.mjs";import"./chunk-RYFN5J56.mjs";import"./chunk-EKM5ZZKU.mjs";export{e as ALL_DEVICES,o as BROKER_PORT,r as BROKER_URL,t as DASHBOARD_NAME,s as DEFAULT_ACTION_TIMEOUT_MS,i as DEFAULT_SNAPSHOT_TIMEOUT_MS,T as PACKAGE_NAME,n as SyncClient,a as VERSION,g as buildAutomationConfig,l as compareReportStats,E as createMcpServer,R as estimateBatchMs,A as formatRankingMarkdown,S as getUpdateNotice,_ as rankBatchFromIndex,c as registerConsoleTools,M as registerEventsTools,m as registerGenericTools,O as registerJotaiTools,p as registerPerfMonitorTools,u as registerReactQueryTools,I as registerReduxTools,d as registerRoutesTools,C as registerScreenshotTools,N as registerStorageTools,U as registerZustandTools,B as runInit};
+import{ALL_DEVICES as e,BROKER_PORT as o,BROKER_URL as r,DASHBOARD_NAME as t,DEFAULT_ACTION_TIMEOUT_MS as s,DEFAULT_SNAPSHOT_TIMEOUT_MS as i,PACKAGE_NAME as T,SyncClient as n,VERSION as a,buildAutomationConfig as g,compareReportStats as l,createMcpServer as E,estimateBatchMs as R,formatRankingMarkdown as A,getUpdateNotice as S,rankBatchFromIndex as _,registerConsoleTools as c,registerEventsTools as M,registerGenericTools as m,registerJotaiTools as O,registerPerfMonitorTools as p,registerReactQueryTools as u,registerReduxTools as I,registerRoutesTools as d,registerScreenshotTools as C,registerStorageTools as N,registerZustandTools as U,runInit as B}from"./chunk-C2Y7M7JN.mjs";import"./chunk-RYFN5J56.mjs";import"./chunk-ALXRBSW6.mjs";export{e as ALL_DEVICES,o as BROKER_PORT,r as BROKER_URL,t as DASHBOARD_NAME,s as DEFAULT_ACTION_TIMEOUT_MS,i as DEFAULT_SNAPSHOT_TIMEOUT_MS,T as PACKAGE_NAME,n as SyncClient,a as VERSION,g as buildAutomationConfig,l as compareReportStats,E as createMcpServer,R as estimateBatchMs,A as formatRankingMarkdown,S as getUpdateNotice,_ as rankBatchFromIndex,c as registerConsoleTools,M as registerEventsTools,m as registerGenericTools,O as registerJotaiTools,p as registerPerfMonitorTools,u as registerReactQueryTools,I as registerReduxTools,d as registerRoutesTools,C as registerScreenshotTools,N as registerStorageTools,U as registerZustandTools,B as runInit};

package/dist/webBench-2IFT74EV.mjs

@@ -0,0 +1 @@
+import{GPU_RENDERER_JS as e,PLAYWRIGHT_MISSING as a,aggregateCase as t,caseUrl as r,cdpDeltas as s,checkBudgets as o,closeCall as i,closeWithin as c,expectFailureFrom as n,formatWebBenchMarkdown as l,isSoftwareGpu as m,keyMatches as h,loadChromium as p,locateStepTargets as d,mergeInteractions as u,missedInput as g,oneLine as f,percentile as k,runWebBench as R,shuffled as b,snapRefreshRate as w,summarizeFrameTrace as B,summarizeProbe as F,takeHostLock as I,tiedPairs as S,validateWebBenchOptions as W,waitForHostLock as G,webBenchFlags as L,withDeadline as P}from"./chunk-ALXRBSW6.mjs";export{e as GPU_RENDERER_JS,a as PLAYWRIGHT_MISSING,t as aggregateCase,r as caseUrl,s as cdpDeltas,o as checkBudgets,i as closeCall,c as closeWithin,n as expectFailureFrom,l as formatWebBenchMarkdown,m as isSoftwareGpu,h as keyMatches,p as loadChromium,d as locateStepTargets,u as mergeInteractions,g as missedInput,f as oneLine,k as percentile,R as runWebBench,b as shuffled,w as snapRefreshRate,B as summarizeFrameTrace,F as summarizeProbe,I as takeHostLock,S as tiedPairs,W as validateWebBenchOptions,G as waitForHostLock,L as webBenchFlags,P as withDeadline};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@buoy-gg/mcp",
   "mcpName": "io.github.Buoy-gg/mcp",
-  "version": "7.0.52",
+  "version": "7.0.54",
   "buoy": {
     "dashboardAuthVersion": 1
   },
@@ -35,8 +35,8 @@
     "socket.io-client": "^4.8.1",
     "zod": "^3.25.0",
     "ws": "^8.18.0",
-    "@buoy-gg/sync-broker": "^7.0.52",
-    "@buoy-gg/license": "^7.0.52"
+    "@buoy-gg/sync-broker": "^7.0.54",
+    "@buoy-gg/license": "^7.0.54"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/skill/buoy-optimize/MEASURING.md

@@ -0,0 +1,100 @@
+# Measuring with Buoy
+
+How to measure in the Buoy Optimize loop. The loop itself is in [SKILL.md](SKILL.md).
+
+## Fair comparisons
+
+- Keep the browser mode, build, window size, pixel ratio, load and settings fixed all session.
+- Measure one thing at a time. Only one Buoy web benchmark runs per machine; a second one waits for the first.
+- Mix up the order, and keep the baseline and current best in every batch as anchors. If the anchors move between batches, the machine drifted. Measure again.
+- Rank on a production build when you can. Dev builds can pick a different winner. If you ranked on a dev build, say so.
+- Keep DevTools closed while ranking.
+- A failed or partial run is not a result. A missing number can't pass a limit.
+
+## Web
+
+All web tools open the app in their own Chromium and ask it to use the GPU. They need Playwright in the project, but no Buoy setup in the app. Each report names the GPU that drew. If it says software, the numbers mean little for drawing-heavy pages.
+
+### `find_web_ceiling`: the score
+
+The most load each variant holds at a target frame rate. It times main-thread `requestAnimationFrame` callbacks, the same way most in-app fps meters do. Use it as the score when your contract's score is that kind of frame rate. If the app has its own judge with a different rule, the app's judge wins.
+
+Before you trust a ceiling, make sure the page really is ready and drawing the requested load: pass a `readySelector` that appears only after the first real frame, and check the screenshots. A canvas that stopped updating can still show a high rate. Never lower the target to suit the test setup.
+
+```json
+{
+  "url": "http://localhost:3000",
+  "cases": [
+    { "name": "baseline", "params": { "variant": "baseline" } },
+    { "name": "atlas", "params": { "variant": "atlas" } }
+  ],
+  "param": "count",
+  "targetFps": 55,
+  "readySelector": "canvas",
+  "viewport": { "width": 1440, "height": 900, "deviceScaleFactor": 2 }
+}
+```
+
+- It loads each step fresh with `param` set, settles 1 s, times frames for 2 s, and raises the load ~30% until a real sample misses. It repeats that miss once to rule out noise, then bisects until the pass and the miss are within 4% (`precisionPct`). If the first load misses, it searches down.
+- A page error or a failed measurement marks the round **invalid**. It never counts as a miss. Fix the page and run again.
+- "At least" means the round hit `max` (default 1,000,000,000) or the time limit before any miss. Raise `max` and run again.
+- `rounds: 3` gives a median when two variants are close. Ceilings within about 10% are a tie until more rounds agree. Two-second samples are for screening; confirm your final pick with `rounds: 3`.
+- `cpuSlowdown: 4` repeats it with the CPU slowed. It's a CPU stress test. It doesn't slow the GPU, memory or heat, so it isn't a phone.
+- The report shows the browser's idle frame rate. Headless Chrome is often 60 Hz. If your target is close to it, use `headed: true` on a faster screen.
+
+### `screenshot_web_variants`: the looks
+
+```json
+{ "url": "http://localhost:3000", "cases": [ ... same cases, same count ... ], "atMs": [500, 1500, 3000], "outDir": "shots/round-2", "clipSelector": "canvas" }
+```
+
+Put the baseline first in `cases`. Each call saves into a new folder, with the real capture time of each shot, and reports how much each variant differs from the baseline at the same moment. A variant flagged as an outlier differs far more than the rest: lights not drawn, wrong colors or frozen motion. Open it first, and never let a flagged variant win until you've seen it's right. Open the PNGs and compare each variant with the baseline at about the same moment. Animated scenes won't match pixel for pixel, so compare shapes, colors, glow and layout, and use several moments to catch frozen motion.
+
+### `run_web_benchmark`: smoothness and cost at one load
+
+Use it to see why a variant wins: Dropped % (Chrome's own count of frames that hurt smoothness), frame gaps, long tasks, the scripts behind slow frames, main thread %, script, style and layout time, DOM size and JS heap.
+
+- Compare only variants doing the same work at the same load.
+- Dropped % ranges that overlap, or middles within 1.5 points, are a tie. `extraRoundsWhenClose: 2` adds runs for the top two.
+- To test taps or typing, pass `steps` and end them with an `expect` step, so a run that skipped the work fails.
+- Pass `budgets` for hard limits, like `{"droppedPct": 2, "inputMs": 200}`. A limit that wasn't measured counts as not met.
+- Mark a case that does different work (like an empty page) with `"control": true`. It's shown, never ranked.
+- `traceDir` saves a Chrome trace per case, for a deep look.
+- `outFile` keeps the full result.
+
+### Web traps
+
+- On react-native-web, `Animated` with `useNativeDriver` and Reanimated worklets still run on the main thread.
+- Skia on web loads a large WASM file. Count its load time.
+- A pixel ratio of 2 draws 4 times the pixels of 1. Keep it fixed.
+
+### Phones, when they're in scope
+
+Open the dev server's network URL on a phone on the same Wi-Fi (for Vite, `vite --host`). In development, the page finds the Buoy broker on port 42831, so the phone shows in `list_devices`. Then use the app's own Bench with `run_benchmark_batch`. Keep the phone awake and the tab in front. Say it was a dev build.
+
+## React Native
+
+- `list_devices`: pick the device with `perf-monitor`. Benchmarking needs Buoy Pro. Don't work around account checks.
+- `get_benchmark_settings` with `pages` = the number of cases: read back the settings and time estimate. Don't call `set_benchmark_settings` unless the user asked to save settings.
+- `run_benchmark_batch` with `targetRoute`, `deviceId` and `cases`. The first case is the baseline. The route reads each case's `params`. Pass `captureRenders: false` while ranking; render capture adds work that differs by variant.
+- If a batch times out, check `get_automation_status` before starting another.
+- Read UI FPS, JS FPS, CPU, memory and jank together. A UI-thread flag is close to disqualifying. `balanced` means no flag fired; missing data can also fire no flag.
+- `get_batch_report` takes a `batchId`. `compare_reports` takes report IDs. They're different IDs.
+- `measure_renders` with `steps` counts renders in one interaction. Compare with `compareToPrevious: true`.
+- A remount doesn't reset module state or storage. If you use `reloadBetweenCases`, make sure `AutomationResumer` is mounted.
+- A simulator result holds for that simulator. Confirm on real hardware before claiming phone speed.
+
+## Tool list
+
+| Tool | Use |
+| --- | --- |
+| `start_optimize_session` | Only when the user gives a time limit: every Buoy result then shows the time left. |
+| `find_web_ceiling` | The most load each web variant holds at a target fps. The score. |
+| `screenshot_web_variants` | Screenshots of each web variant at the same moments. |
+| `run_web_benchmark` | Smoothness and cost of web variants at one load. |
+| `list_devices` | Find the connected app and its tools. |
+| `get_benchmark_settings` / `set_benchmark_settings` | Read settings and the time estimate, or save them. |
+| `run_benchmark_batch` / `get_automation_status` | Measure variants in the app with Bench. |
+| `get_batch_report` / `compare_reports` | Read or compare saved runs. |
+| `measure_renders` | Count renders in one interaction. |
+| `navigate` | Open a route in the app. |

package/skill/buoy-optimize/SKILL.md

@@ -1,149 +1,151 @@
 ---
 name: buoy-optimize
-description: Use when the user asks to investigate a slow React Native or web screen or compare rendering approaches with a connected Buoy MCP server. Measure a baseline and selected variants, check visual behavior, and explain the observed performance trade-offs. Triggers include "buoy optimize", "optimize this screen", "find the fastest way to render X", and "why is this laggy".
+description: Use when the user wants a slow screen made faster, or the most performant way to build something heavy (lists, animations, light grids, canvases, maps) in a React Native or web app, with the Buoy MCP server connected. Runs a search loop that keeps going until it hits a wall - brainstorm many ideas, build the most promising side by side, measure them all, research, fork the winners, combine them, and repeat. Triggers include "buoy optimize", "optimize this screen", "find the fastest way to render X", "why is this laggy".
 ---
 
-# Optimize React Native rendering with Buoy
+# Buoy Optimize
 
-Use repeatable measurements to investigate the user's workload. Keep a working baseline, compare a small set of plausible changes, and report which devices and conditions the results cover.
+You run a performance search. The goal is the best result you can find in the time you have, not a small fix.
 
-## Check setup and scope
+Say a screen draws Christmas lights with CSS and it's slow. Don't just tune the CSS. Ask: what are all the ways to draw this? Canvas, WebGL, Skia, a shader, a sprite sheet, a video, a worker, and more. Build the most promising ones. Measure them all the same way. Keep what wins. Go again. Keep going until your time runs out.
 
-If the target is a web app, you can start with `run_web_benchmark`. It opens the app in its own browser and needs no connected app (see "When the target is a browser"). Otherwise, call `list_devices` and select the intended device. Benchmarking requires a connected app exposing `perf-monitor`, configured account access and Buoy Pro. If a requirement is missing, explain the setup needed. Do not bypass account checks.
+Measuring details and tool tips are in [MEASURING.md](MEASURING.md). Read it before your first measurement.
 
-Infer the target screen, existing harness, rendering libraries and workload from the project and conversation. Ask only for missing details that would change the experiment: workload size, required visual behavior, target devices, performance limits or a time budget. Continue work already authorized without asking the user to approve each routine prune or iteration.
+## The loop
 
-Start on the user's target platform and available device. Record whether it is physical hardware or a simulator, the build type and available device information. Keep comparisons on the same setup. Simulator results apply to that environment; confirm relevant candidates on target hardware before making hardware claims. Do not assume one operating system or device class is faster, or require platforms outside the user's scope.
+```
+1 contract → 2 baseline → 3 idea bank → 4 pick a wide round → 5 build (time-boxed)
+  → 6 check looks, then measure → 7 find each ceiling → 8 record + research
+  → 9 next round (forks, combos, new families, old ideas) → back to 4
+  → 10 at the wall: confirm and install the best checked version, then report
+```
 
-For a specific interaction that causes excess renders, start with `measure_renders` and the relevant `steps`. This may answer the question without a new test route. Compare the same steps after editing with `compareToPrevious: true`. Treat reported render reasons and wasted-render counts as diagnostics to investigate, not proof that a render is unnecessary.
+### 1. Write the contract
 
-## Choose a baseline and candidates
+Write these down before you build anything:
 
-Use the current implementation with the representative workload as the baseline for a fix. An empty screen can be a separate control for harness overhead; it does not do equivalent work and cannot establish an improvement to the feature.
+- **The score.** One number with an exact pass rule. For "as many lights as possible", the score is the most lights that hold the target frame rate (say 55 fps) in the main setup.
+- **The load knob.** The param that sets the work, like `?count=`. The score comes from turning it up until the frame rate drops.
+- **What must stay the same.** The look, the motion, the timing, every pattern or mode, the interactions. A variant that changes these can't win.
+- **The setup.** Browser or device, build type, window size and pixel ratio. Keep it fixed all session.
+- **No time limit unless the user gives one.** You keep going until you hit the wall (step 9). If the user does give a time limit, call `start_optimize_session` with it so every Buoy tool result shows the time left.
 
-When comparing approaches needs a harness, use a route whose parameters select isolated variants. Keep workload, visual output and interactions comparable. Include a way to open each variant for inspection. Follow the project's development-only route and build conventions; `__DEV__` guards alone do not prove a route or dependency is absent from the shipped bundle.
+**An app's own test cap is not the ceiling.** If the app's test stops at 50,000, the score has no cap. Measure past it (see step 7). Keep the app's own test as a second check, and confirm both agree below its cap.
 
-Check that the target and bounce routes exist and navigation resets the intended state. A remount does not reset module state or persistent storage. If using `reloadBetweenCases`, confirm that `AutomationResumer` is mounted and that the app can resume the batch after reload.
+This holds even when the user says "your score is the app's test". Maxing out a capped test means you have reached the cap, not the wall. Reaching the cap is when the real search starts: find the uncapped ceiling and keep raising it.
 
-Start with a few candidates supported by the observed problem. Add variants when a result suggests a useful next experiment. Keep the original implementation available for comparison.
+### 2. Measure the baseline
 
-## Read settings and run the batch
+- Save the current code as the `baseline` variant.
+- Make one test page where a URL param picks the variant, like `?variant=atlas&count=50000`. Every idea becomes a variant here. **Never edit the current best in place.** Old variants stay, so you can compare and combine them.
+- Check that the load knob really changes the work.
+- Find the baseline's ceiling. Profile it near its limit to see what is slow.
+- Estimate the **hardware limit**: roughly how much work the GPU and CPU could do per frame (pixels drawn, draw calls, bytes sent, math per item). Far below that limit means bold ideas are worth it. Near it means small gains.
 
-Call `get_benchmark_settings` with `pages` equal to the total case count, including the baseline, and the selected `deviceId`. Summarize the returned settings and time estimate. The tool reports either a saved device profile or defaults; do not describe defaults as the user's chosen settings.
+### 3. Build the idea bank
 
-Use per-run overrides for a temporary change. Call `set_benchmark_settings` only when the user has asked to persist settings. Explain relevant measurement conditions, including warmup, repeats, cooldown, case order and render instrumentation. Consistent settings help comparisons but do not eliminate measurement noise or thermal effects.
+Make `OPTIMIZE_IDEAS.md` in the project. It is your memory. **Read it before every round,** and after any break.
 
-Call `run_benchmark_batch` with `targetRoute`, `deviceId` and `cases`. Each case has a `name` and optional `params`; the first case is the baseline for deltas. The route must interpret those parameters. The call waits for completion or its wait cap, which can take minutes.
+Write down at least 20 different ideas in about 10 minutes. Go wide on purpose, across families:
 
-Read the returned warnings, failures and partial-result note before comparing rows. A timed-out wait can leave runs saving or automation active; inspect `get_automation_status` before starting another batch. Do not count failed or missing cases as successful tests. Check the current screen afterward instead of assuming navigation restored it.
+- **Other technology.** For drawing: DOM, CSS animations, Canvas 2D, WebGL or WebGPU, Skia (`drawAtlas`, `drawVertices`, runtime shaders, pictures), one big shader, a sprite sheet, a video, a worker with OffscreenCanvas, native views. For lists: windowing, recycling, flattening.
+- **Doing less work.** Draw once and reuse. Cache. Batch into one draw call. Move math to the GPU. Compute once per item instead of once per pixel. Skip work nobody can see.
+- **Hacks.** Draw blur at low resolution and scale it up. Bake glows into textures. Lookup tables. Pack data into textures. Split still and moving layers. Spatial grids.
+- **The runtime.** No React work per frame. No allocations per frame. No layout reads after writes. Better blend modes and texture formats.
 
-## Check behavior and interpret measurements
+Give each idea one row: ID, family, parent ideas, what it is, why it might win, the bottleneck it attacks, rough build time, status, score range, report IDs and the next test. Statuses: `untried`, `building`, `valid`, `invalid` (looks or acts wrong), `failed-build`, `deferred` (with what would make it worth another try), `blocked`.
 
-Inspect visual behavior and the relevant interactions using available screenshots, UI tools and project checks. Ask the user when the required appearance is subjective or cannot be checked with available tools. Record unverified behavior explicitly. Exclude a visibly incorrect variant from performance recommendations, while retaining its result as evidence of what was tested.
+Keep a **current best** line at the top. Also keep the best variant of each family, not just the overall leader. A family that loses now can win after a fork.
 
-Compare the available UI/JS FPS, CPU, memory and jank measurements together. Check missing values before interpreting a low value or an absent warning. The report's per-metric leaders and `balanced` list are summaries of recorded data. `balanced` means no configured risk flag was triggered; missing measurements can also produce no flag. It does not establish that a case meets every performance requirement.
+**Never delete an idea.** A loss at one load, or a bug, doesn't prove an idea is bad. Write what happened and move on.
 
-Use `get_batch_report` with a `batchId` to read a saved batch. Use `compare_reports` with `reportIdA` and `reportIdB` to compare two saved runs; report IDs are different from batch IDs. Inspect available averages, p95 values and render data in the context of the same workload. A lower wasted-render count alone does not prove a fix or an overall speed improvement.
+### 4. Pick a wide round
 
-Explain trade-offs against the user's requirements. For example, a candidate may use less memory while producing more frame drops. Repeat close or noisy comparisons before choosing between them. Do not translate CPU measurements into battery-life claims without separate evidence.
+- **First round:** about 6 ideas from at least 3 families. Include at least one bold idea that changes the technology.
+- **Every round tests several ideas,** never just one tweak. At least one must be new, untried or deferred, from outside the current best's family.
+- **Later rounds:** spend about half the effort on forks and combinations of what's winning. Spend the other half on new families, ideas from research and deferred ideas. Don't let one family eat all your time.
+- Keep one variant that scales differently when the early ranking isn't clear. It may win at a higher load.
+- Keep the baseline and the current best in every comparison.
+- Write one line on why each pick is worth its build time.
 
-## Iterate and report
+### 5. Build each one, time-boxed
 
-Keep candidates that meet the behavior requirements and offer a useful measured trade-off. Refine a specific hypothesis or combine compatible changes, then rerun the same workload. Stay within the agreed scope and time budget; seek direction when a decision would materially change either.
+- Give each idea a build budget, about 5 to 8 minutes. A bold idea can get more. If a build blows its budget, mark it `deferred` with what went wrong and move on.
+- Smoke-test each variant as soon as it runs.
+- **Every picked idea gets an outcome:** measured, `invalid`, `failed-build`, `deferred` or `blocked`. Never drop one silently.
+- Inactive variants must not run work in the background.
 
-Stop when the requested issue is resolved with appropriate checks, the agreed budget is reached, or further measurements require unavailable hardware or input. Report the selected implementation, baseline, workload, device/build conditions, settings, observed differences, failures and remaining uncertainty. Distinguish completed checks from proposed follow-up tests. Validation on one device does not establish results for all devices on that platform.
+### 6. Check looks, then measure
 
-## When the target is a browser
+**A fast variant that looks wrong is worthless.** Check before you trust any number.
 
-`list_devices` shows `platform: "web"` for a browser tab. There, Bench measures the page's own main thread. The report uses a browser table with different columns.
+- If the user is around, ask them to look.
+- If not, check it yourself with `screenshot_web_variants` (web) or screenshots (app). Put the baseline first; the tool flags variants that differ from it far more than the rest. Use the same count and settings for every case. Take several moments, so frozen or broken motion shows. Check a sparse scene, where each item is visible, and a dense one. Compare each variant with the baseline side by side: shapes, colors, glow, layout, motion. Watch it run live too. A still image can't prove motion.
+- Mark wrong ones `invalid` and say what was wrong.
 
-Read it this way:
+Then measure every valid variant the same way. Screen them at a few loads (one low, one near the current best's ceiling, one above), because a variant can lose small and win big. Before you prune, raise the load so the top ones don't all tie at the frame cap.
 
-- FPS is the main thread's frame rate from `requestAnimationFrame`. It can't see frames the GPU or compositor drops later. It shows once, because a page has one main thread.
-- p95 frame gap, worst gap and long frames come from the time between frames in that run. A gap over 1.5 frames missed at least one frame.
-- Long tasks % is the share of the run the main thread spent in tasks over 50 ms. It is not CPU use, and it misses many shorter tasks.
-- A metric the browser can't measure shows as —. Safari and Firefox have no long tasks or JS heap. A — can't win or lose.
-- "Why frames were slow" names the scripts behind slow frames, plus style, layout and forced layout time. Start your next idea there. It only sees frames over 50 ms, and it can't see work in workers.
-- "DOM grew every run" is a hint of a leak, not proof. Confirm it with a heap snapshot after the screen unmounts.
-- "Too close to call" means the top cases overlap across runs. Run more repeats before you pick.
-- A page load table shows up only when each case ran on its own fresh page load (the batch reloads between cases with `reloadBetweenCases`). Use it for load-time work.
+### 7. Find each ceiling
 
-Set up the run:
+The ceiling is the score.
 
-- Keep the tab in front and the window the same size. A run with a hidden tab or a resize is saved as a failure.
-- Rank on a production build when you can. Dev React is slower and can pick a different winner. Put the test page behind its own bench flag, not just `__DEV__`. Keep it out of public builds. If you ranked on a dev build, say so in the report.
-- Keep DevTools closed while ranking. Record the screen size and pixel ratio. A pixel ratio of 3 draws 9 times the canvas pixels of 1.
-- Pass `captureRenders: false` to `run_benchmark_batch` while ranking. Render capture adds work, and the cost differs by variant. Turn it on in a separate pass to explain a slow case.
+- On web, use `find_web_ceiling`. It raises the load about 30% a step until the frame rate misses the target, then narrows the gap to a few percent. It has no cap by default (up to 1,000,000,000).
+- On React Native, ramp the count with `run_benchmark_batch` cases.
+- Record the highest pass and the lowest miss. A single miss can be noise; run the boundary again before you call it.
+- If nothing missed, the score is "at least" that load. Raise the max and run again.
+- **Rank on the score.** Dropped frames, frame times, CPU, memory and profiles explain why a variant won. They only rank when the contract says so.
 
-Two tools can run a web batch:
+### 8. Record and research
 
-- `run_benchmark_batch` runs inside the app's own tab through Bench. Use it when the app has Bench and the user's browser is open.
-- `run_web_benchmark` opens the app in its own headless Chromium. It needs Playwright in the project, but no Buoy setup in the app. Each run gets a fresh browser context, and the tab is always in front. It adds Chrome's own main-thread, script, style and layout time. Pass a `readySelector` the page adds once it has drawn.
+- Write every outcome into the bank: the score range, what the profile showed, and **why** it won or lost. Keep what you saw separate from what you guess.
+- Research for about 3 minutes after **every** round, even one where every build failed. Search the web, docs, source code and issues for the bottleneck you just saw. Examples: "WebGL draw 1 million sprites", "Skia drawAtlas performance", "CanvasKit flush cost". Add new ideas and their sources to the bank.
+- Keep a research log in the bank: each round's search, the sources, what you learned and the experiment it suggests.
+- After a big win, profile again. The bottleneck moves.
 
-In `run_web_benchmark`, rank on Dropped % first, and only across variants doing the same work. It counts frames Chrome dropped or only partly made that hurt smoothness, from its own count. Deltas are in percentage points (pp). Headless Chrome shows nothing on a screen, so these are frames Chrome produced, not frames a person saw. Shown FPS only counts frames with new content, so an animation that changes 16 times a second needs just 16. Don't compare Shown FPS across variants that update at different rates. Main-thread FPS can be low while nothing drops. That happens when the compositor runs a CSS animation and JavaScript is slow. The animation looks smooth, but taps will feel slow.
+### 9. Next round
 
-To test taps, typing or scrolling, pass `steps`. For example: `[{"wait": 300}, {"click": "#add"}, {"type": {"selector": "#search", "text": "lights"}}]`. The report then shows input response for each case. Under 200 ms is good. Click targets must be on screen when the run starts and must not move. Leave at least 300 ms after the last step (a `wait`), so its paint lands inside the run. If not, the report says the input timing is incomplete and won't pass an input budget.
+Build the next round from forks of the winners, combinations of tricks that worked, new ideas from research and untried or deferred ideas from the bank. Then go back to step 4.
 
-End every step list with an `expect` step, like `{"expect": {"selector": "#cart-count", "text": "1"}}`. A run that skipped the work then fails instead of ranking as fast.
+- If every idea in a round lost, pick the next best ideas from the bank. Write more ideas if the bank runs thin.
+- **A plateau means change direction, not stop.** Try another family, a deferred idea with new evidence, or attack the current bottleneck another way.
+- Keep going until you hit the wall. Stop sooner only if the user says so, their time limit runs out, or something outside your control blocks all useful work.
 
-When the user gave limits, pass them as `budgets`. For "almost no dropped frames, taps under 200 ms", use `{"droppedPct": 2, "inputMs": 200}`. The report says which cases meet every limit. Input and freeze limits use the worst run, and an input limit needs a click, key or typing step. A limit that wasn't measured counts as not met.
+Tell the user where you are each round in a line or two: round number, what you tried, the new best score.
 
-Mark a case that does different work as a control: `{"name": "empty", "control": true}`. It shows in the table, but it is never the baseline and never a candidate.
+**The wall.** You have hit it only when all of these are true:
 
-If the two best cases come out too close to call, pass `extraRoundsWhenClose: 2`. It adds runs only for those two. Pass `outFile` to save the whole result, so you can read it again later.
+1. Your score is an uncapped ceiling with a real miss, not "at least" and not the app's own cap.
+2. The last 3 rounds each raised it by less than 3%.
+3. Those 3 rounds tried at least 3 different families of ideas, not 3 tweaks of one.
+4. You researched after each of those rounds and wrote what you found.
+5. Every idea still in the bank has a written reason it won't help. "It changes the look" or "too slow" only counts if you measured it. A guess doesn't.
 
-Test in this order, and tell the user which step you are on:
+If any one is false, you are not at the wall. Start another round. Hitting a good number, writing `RESULTS.md` or running long are never reasons to stop.
 
-1. Desktop Chrome, with `run_web_benchmark` and `cpuSlowdown: [1]`.
-2. The same cases with `cpuSlowdown: [4, 6]`. This slows the CPU only, not the GPU, memory or heat.
-3. A real iPhone in Safari.
-4. A real mid-range Android phone in Chrome.
+Work in one long session. Don't end your turn to wait for a long command. Wait for it, then keep going.
 
-For steps 3 and 4, use the app's own Bench and `run_benchmark_batch`. Start the dev server so other devices can reach it (for Vite, `vite --host`). Open its network URL on the phone, on the same Wi-Fi as this computer. In development, the page finds the broker at its own host on port 42831, so the phone shows up in `list_devices`. Keep the phone awake and the tab in front, or runs fail as hidden. This is a dev build, so say so in the report. A production build on a phone needs `externalSync` settings; see the web install guide.
-5. Desktop Firefox and Safari, if the user supports them.
+### 10. At the wall: lock in the best
 
-Take a quick look in Safari early, so you don't spend rounds on an idea that breaks there.
+When you hit the wall:
 
-Ideas to try for heavy drawing on web:
+- Measure the top 2 or 3 again with fresh runs, and confirm the ceilings.
+- Put the winner on the real screen. Check its looks and interactions again there.
+- Run the app's own test too, if it has one.
+- Leave the best checked version in place, never an untested experiment.
 
-- Canvas2D with pre-drawn sprites.
-- WebGL with one draw call for many items.
-- An OffscreenCanvas in a worker.
-- CSS or Web Animations API transforms. The compositor can run these.
-- List windowing, and `content-visibility` for things off screen.
+Writing a report or `RESULTS.md` along the way is fine. Update it after each win. It doesn't end the session; the wall does.
 
-Picking a winner on web:
+Then report:
 
-Don't pick a winner when any of these is true:
+- Baseline and final score, with the range, and the exact setup.
+- The winning approach and the tricks that mattered most.
+- What each family scored, and the ideas still untried.
+- How you checked the looks.
+- Why you stopped: show the wall check (the last 3 rounds, their families, the research, and why each idea left in the bank won't help). Say "best found", not "the maximum possible".
 
-- You can't show both cases do the same work, or you don't know which build was served.
-- Runs failed, frame data is missing, or a case has fewer than 2 good runs.
-- The Dropped % ranges touch or overlap, or the middle values are within 1.5 points.
-- An input limit matters and its timing was incomplete or unknown. A missed or unknown budget can't back a "meets the goal" pick.
+## Rules
 
-When you do pick, say all of this with it:
-
-- It's a smoothness pick for this build on this desktop setup. Give the Chrome mode, screen size, scale, CPU slowdown, run count, recorded time, Dropped % for each case, their ranges and the gap.
-- Headless Chrome made the frames but showed nothing on a screen. This doesn't prove phone speed.
-- Input times come from the scripted steps, not real users. A missing time is unknown. The tie rule is a guide, not proof.
-
-Traps on react-native-web:
-
-- `Animated` with `useNativeDriver` still runs on the main thread.
-- Reanimated worklets run as plain JS on the main thread.
-- Skia on web loads CanvasKit, a large WASM file. Count its load time and first draw.
-
-## Tool reference
-
-| Tool | Use |
-| --- | --- |
-| `list_devices` | Select the connected device and inspect its tools. |
-| `measure_renders` | Measure a supported interaction before and after a change. |
-| `get_benchmark_settings` / `set_benchmark_settings` | Read the profile and estimate, or explicitly persist settings. |
-| `run_benchmark_batch` / `get_automation_status` | Run the case matrix and inspect automation status. |
-| `run_web_benchmark` | Run web cases in a fresh headless Chromium, with optional CPU slowdown. |
-| `get_batch_report` | Read a saved batch using its `batchId`. |
-| `compare_reports` | Compare saved runs using `reportIdA` and `reportIdB`. |
-| `navigate` | Open a supported app route using `path`. |
-
-Keep summaries focused on the decision and its evidence. Include report IDs so results can be revisited without pasting every sample into the conversation.
+- Every variant does the same work: same items, same look, same behavior. Drawing fewer items, skipping frames, or anything that makes the meter read high without the user seeing it, is cheating and can't win.
+- Don't change the app's own test, its clock or its frame counter.
+- Don't ask the user to approve each round. Ask only when a choice changes the scope.
+- Stay on the user's platform. Test other platforms only when they're in scope.