Chrome Trace

Chrome Trace

Core Workflow

Use Playwright with Chromium and the Chrome DevTools Protocol Tracing domain to capture the exact interaction under investigation.

1. Start from a reproducible page and action.
2. Warm up the page until app-specific readiness is true.
3. Start Chrome tracing and a requestAnimationFrame sampler immediately before the action.
4. Mark the action window with performance.mark() and console.timeStamp().
5. Perform the action with real Playwright input when the user is asking about input-driven behavior.
6. Stop tracing after a short settle window.
7. Align trace event timestamps to performance.now() using the start/end marks.
8. Report where time went: Scripting, Style, Layout, PrePaint, Paint, compositor main-thread work, compositor impl-thread work, raster, GPU/viz events, and the slowest frame windows.

Do not draw conclusions from FPS alone. Use FPS/frame-time summaries only as the symptom; use trace groups and top events as the explanation.

PolyCSS Trace Runners

Use scripts/trace.mjs as the front door:

pnpm bench:build
node .agents/skills/chrome-trace/scripts/trace.mjs motion --page nonvoxel --mesh glb:Elephant.glb --variant baseline --dom-samples --label elephant-baseline
node .agents/skills/chrome-trace/scripts/trace.mjs motion --page nonvoxel --mesh teapot --variant baseline --dom-samples --frame-details --layer-details --gpu-details --trace-out bench/results/teapot.trace.json --label teapot-enriched --report
node .agents/skills/chrome-trace/scripts/trace.mjs motion --page nonvoxel --mesh teapot --variant baseline --gpu-details full --trace-out bench/results/teapot-full-gpu.trace.json --label teapot-full-gpu
node .agents/skills/chrome-trace/scripts/trace.mjs drag --mesh teapot --mode baked --frame-details --label teapot-drag
node .agents/skills/chrome-trace/scripts/trace.mjs motion --mesh garden --report --markdown-out bench/results/garden-trace.md
node .agents/skills/chrome-trace/scripts/trace.mjs compare bench/results/before.json bench/results/after.json --markdown-out bench/results/trace-compare.md

Use trace.mjs motion for steady bench motion across perf and nonvoxel pages, cadence buckets, DOM samples, render stats, and tag counts.

Add --frame-details to motion traces when you need slowest/fastest frame attribution instead of only bucket averages. On nonvoxel pages this also enables page-work samples for camera.update, scene.applyCamera, and input/control callbacks when available. Add --layer-details when compositor/layer shape is part of the question; it records LayerTree counts, layer aggregates by DOM tag/class (leaf:b, leaf:u, polycss-camera, etc.), largest layers, and compositing reasons. Add --trace-out when the raw Chrome trace should be preserved for DevTools.

Add --gpu-details when render pass timing is the current question and the trace still needs to stay reasonably sized. Light mode keeps the normal GPU/viz timeline categories and adds only disabled-by-default-viz.gpu_composite_time; render-pass attribution still comes from base events such as DirectRenderer::DrawFrame and DirectRenderer::DrawRenderPass. It intentionally avoids per-quad, Skia command, and GPU service spam.

Use --deep-gpu or --gpu-details full only for rare forensic runs that truly need per-quad/Skia/overdraw detail. Full mode also enables disabled-by-default-viz.quads, disabled-by-default-viz.triangles, disabled-by-default-viz.overdraw, disabled-by-default-gpu.debug, and disabled-by-default-skia.gpu; raw traces can become hundreds of MB and timing can be heavily perturbed.

Use trace.mjs drag for real PolyOrbitControls pointer-drag traces on nonvoxel-vanilla.html. This runner knows the non-voxel readiness hooks, camera state, interaction stats, and per-frame page-work samples.

Use trace.mjs generic for arbitrary pages and interactions that are not covered by a polycss bench page.

When interpreting PolyCSS traces, map the result back to the render model:

• FunctionCall, EventDispatch, FireAnimationFrame: JS/input work. Unexpected sustained per-frame work is suspicious outside imported skeletal animation.
• UpdateLayoutTree, RecalculateStyles: style recalculation, often CSS variable or selector invalidation cost.
• Layout: layout; should stay low for transform/CSS-var-driven motion.
• PrePaint, Paint, PaintArtifactCompositor::Update, Layerize: paint/compositing setup.
• LayerTreeImpl::UpdateDrawProperties, draw_property_utils::ComputeDrawPropertiesOfVisibleLayers, LayerTreeHostImpl::PrepareToDraw, MainFrame.Draw, SubmitCompositorFrame: compositor-side cost.
• Graphics.Pipeline, DisplayScheduler::DrawAndSwap, DirectRenderer::DrawFrame, DirectRenderer::DrawRenderPass: GPU/viz drawing pipeline. Treat these as browser output work, and compare them against layer details before changing app JS.
• gpuVizRenderPass, gpuVizTiles, gpuVizGpuService: opt-in --gpu-details attribution buckets for render pass, coarse tile/raster playback, and GPU service events.
• gpuVizQuads and gpuVizSkia: usually require --gpu-details full / --deep-gpu; treat them as high-overhead forensic signals.
• RasterTask, image decode events: raster/bitmap work, usually atlas or tile work.