core: the profiler says why each frame happened

[foxnne]

Part of plans/DASHBOARD_PLAN.md, "What performance work lacked": frame causes. Coordinated with the session doing the profiler; it takes spans.

What changes

The profiler says why each frame happened. fizzy draws only when something asks for a frame, so the frame-loop bugs are a frame that never comes (work waiting for the next unrelated event) and frames that never stop (something asking every frame). A profile showed where a frame's time went, but not who asked for the frame. Two of those bugs came up this week, the crash checkpoint (#361) and the restart handover (#356), and each cost a round of guessing.

While the profiler records, each frame is put down to one of three causes:

• its events, less the pointer position event dvui adds to every frame;
• else the dvui.refresh calls before it, by file and line;
• else something else: a timer or an animation coming due.

core.profile.report gains a .causes section with the counts and the places that asked for frames, most first. Idle under the agent's profiler, for example:

.causes = .{
    .frames = 252, .by_events = 0, .by_refresh = 251, .by_other = 1,
    .refreshed_from = .{
        .{ .place = "Host.refresh (a plugin):0", .count = 252 },
    },
},

That first reading found a bug of ours: the agent's own fizzy_profile keeps fizzy awake while it measures. The fix is in the agent plugin, next.

Where the places come from:

• fizzy and the built-in plugins: dvui already records each refresh's file and line as a debug log line while dvui.debug.logRefresh is on, which is what FIZZY_LOG_REFRESH turns on. fizzy turns it on while the profiler records. The app's log function hands those lines to core.profile.interceptLog, matched by format at compile time, so no other log call costs anything, and they're counted instead of printed.
  • For release builds, dvui's debug level is compiled in (log_scope_levels), and its other debug lines are dropped in logFn as before. A ReleaseFast run logged none of them.
• A plugin dylib: its refresh lines reach the host as text through Host.logLine and are read the same way (interceptPluginLine). Only its Debug builds produce them.
• Host.refresh, how every plugin asks for a frame: it wakes the backend directly, so it's recorded at that point as Host.refresh (a plugin). Which plugin asked, it doesn't say.

No layout change: FrameCauses is its own allocation, made the first frame the profiler records and published under its own key, as Lookback is (#353). The profiler's abi stays 4. It starts over each time the profiler starts recording, so it describes what happened while someone was looking.

SDK impact

• Core-only or additive: reaches plugins at the next SDK release (core.profile: FrameCauses, frameCauses, interceptLog, ReportOptions.causes). No fingerprint move (test-sdk-version passes).

Verified

• macOS, Debug and ReleaseFast, a sandbox profiled through the agent plugin:
  • Idle: all frames put down to Host.refresh, as above. The same in ReleaseFast, with no dvui debug lines in its log.
  • With FIZZY_LOG_REFRESH=1: the intercept fires for every refresh record dvui prints (234 in a run), and the lines still print.
• fizzy-profile-causes-tests (new, std-only): the three causes; the busiest place first; a long path keeping its tail; places past the 32 kept counted together; reset.
• zig build, zig build -Doptimize=ReleaseFast, zig build test (533/534, 1 skipped), test-integration (375/375), check-web, test-sdk-version.
• Windows, Linux: CI.
• Not covered: a test that holds dvui to the format strings it logs. The integration tests take their log function from Zig's test runner, so the intercept can't run there. If dvui changes the format, refresh places stop being recorded, and frames show up as "other".

Follow-ups

• Which plugin called Host.refresh: a source location through it, which moves the SDK boundary, so it waits for a release that moves it anyway.
• A dylib plugin's own dvui.refresh calls are counted only in its Debug builds, and only once its dvui copy has refresh records on. Syncing that flag through dvui_context is the seam.
• Agent: fizzy_profile should measure without driving frames, and a step to compare before and after.

🤖 Generated with Claude Code