zthrottle is a thin Tauri v2 host binary; all benchmark logic, the monitor data harvest, the command surface and the served frontend live in the zthrottle-core engine — see the engine report for the module map and command list. This page covers what the host adds around the engine. Early-stage and in active development.
Host surface
| area | role |
|---|---|
| engine bridge | zth_invoke forwards every benchmark and monitor command to zthrottle-core; stateless data-harvest runs on the tokio blocking pool without the engine mutex |
| job manager | a background-job registry (job_start / job_list / job_result / job_partial / job_cancel / job_clear) — cancellable, streaming, unlimited-concurrency storage scans surfaced in a drawer |
| tree index | tree_load (instant cached read) + tree_forget (targeted delete) over the persistent SQLite directory map; tree.index / tree.refresh run as jobs |
| gear menu | save_screenshot (xcap window capture) and quit_app |
| Stryke Hooks (R2) | a bundled stryke --lsp sidecar + hook runner for the in-app scripting editor |
| shared embeds | the shared embedded PTY terminal (R3) and the multi-pane file browser (R10) from the zpwr component crates |
GUI feature map
| tab | surface |
|---|---|
| Benchmark | four axis gauges (Blackmagic-style sweeping needles), single-axis runs, RUN ALL, and the contention matrix + bottleneck-migration timeline |
| Processes | CPU/memory table, CPU-history graph, per-core bars, filter, and a left-/right-click signal menu (TERM · KILL · STOP · CONT · HUP · INT · QUIT · ABRT · USR1 · USR2) |
| Network | per-interface throughput with live download/upload sparkline history |
| Storage | a global macOS-Storage-style overview by auto-category, drill-down, find-biggest (the dirs Storage hides), build/cache-junk flags, SMB/NFS mount detection, and delete-to-reclaim (🗑 button or a right-click row menu: open · reveal in Finder/Explorer · open in Terminal · copy path · delete, with stale index rows verified away on every paint), plus a per-directory ↻ refresh that re-walks just that subtree — all backed by the persistent tree index for instant load |
Storage index — full scan, then hooks, with a full descent as the reconcile
The storage monitor is backed by a persistent SQLite directory index. It is built by a full filesystem walk on a cold or wiped database — streamed to the UI and committed every 20k directories, so a restart mid-walk keeps its progress. In steady state the fs-watch hook is the writer that carries the load: a notify FSEvents / inotify watch on $HOME, debounced (1.5 s quiet, ≥3 s between fires, ≤64 coalesced dirs), driving a targeted update_paths that re-sizes only the changed directories and bubbles the byte delta to their ancestors — never a whole-tree re-walk. A freshly-built target/ that the hook saw is discovered by re-walking from its nearest already-indexed ancestor.
The hook cannot cover everything, so three automatic full descents back it up. Creating repo/target/ bumps repo's mtime but no ancestor above it, and the mtime-incremental refresh skips any subtree whose ancestors did not move — so an incremental pass structurally cannot find what the hook missed. It runs on: cold start (a build that happened while the app was closed left no event to replay), burst overflow / dropped events (the lost events are exactly the ones that would have announced a new directory), and every 10th tick (~20 min) of the degraded loop when the recursive watch cannot be established at all — the other ticks stay incremental. Reads (tree_load, delete_candidates) hit the index instantly; every other write — refresh, reindex, delete, a junk-pattern edit (one SQL reflag pass, no re-walk), a size freshen — is a user action, and every automatic write lands as a visible ⚙ JOBS row.
Build
Tauri v2 over a webview; the frontend is served by the engine crate (single source of truth, shared with every embed). Build with pnpm --dir app tauri build; dev with pnpm --dir app tauri dev. The GUI harvests all monitor data through the worker pool so a minutes-long / scan never blocks the UI, and the storage map is persisted so launch is instant rather than a re-walk.