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 — all backed by the persistent tree index for instant load |
Storage index — full scan once, then hooks
The storage monitor is backed by a persistent SQLite directory index. It is built by a single 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. After that, the fs-watch hook is the only automatic writer: 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/ is discovered by re-walking from its nearest already-indexed ancestor. 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. An audit across every walk-and-write call site confirms the pattern holds: the hook is the sole automatic writer, the full walk runs exactly once.
update_paths is the only automatic writer; no periodic re-walk.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.