git:20260921.5fea21b to git:20260924.9643cc5

14 added, 1 removed. Audit A to A.

# Vanta Architecture & Agent Guide

This document is intended for AI agents and developers working on the Vanta codebase. It outlines the architectural boundaries, rendering pipelines, and extension mechanisms.

## 1. Core Philosophy

Vanta is a highly-optimized, aesthetic terminal dashboard written in Rust using `ratatui`.

* **Performance first**: The main render loop must never block on I/O. All data fetching (monitors, feeds, filesystem operations) happens in background threads that update a shared state (`Summary`, `App` states, or `fs_tasks`).

* **Terminal limits**: UI components must gracefully handle terminal resizing and tiny viewports.

* **No bloat**: Core features should be universally useful. Niche features belong in WASM extensions.

## 2. Rendering Pipeline

* **`src/main.rs`**: The entry point. Initializes the terminal, loads the config, boots background workers, and drives the TUI event loop.

* **`src/app.rs`**: Holds the global state (`App`). Contains the navigation (`DashboardMode`) and handles all keystrokes. Keystrokes on custom pages are routed to active WASM extensions via `handle_key`.

* **`src/screens/dashboard.rs`**: The primary layout engine. It takes the `[[pages.layout]]` grid from the config and dynamically maps string IDs to their rendering functions.

## 3. Configuration (`src/config.rs`)

Vanta is driven by `config.toml`.

* **Custom Pages**: Users define `[[pages]]` with layouts representing a grid of component IDs.

* **Extensions**: The `[extensions]` table controls which compiled WASM extensions are booted.

## 4. Extension Architecture (V2 WASM Micro-Extensions)

Vanta uses Extism for sandboxed `wasm32-unknown-unknown` plugins. The core API is in `src/extension/host_api.rs`.

* **Micro-Extension Pattern**: We enforce a 1-to-1 mapping where possible. Every individual widget (e.g., `filespace_browser`, `filespace_preview`) is compiled as its own independent `.wasm` plugin.

* **State Isolation & Communication**: Extism sandboxes cannot share memory. To allow micro-extensions to communicate (e.g., a browser telling a preview pane what file is selected), Vanta provides a host-side Key-Value mailbox.

* Extensions call `vanta_query` with `{"topic": "state_set", "key": "...", "value": ...}` to broadcast state.

* Other extensions call `vanta_query` with `{"topic": "state_get", "key": "..."}` to read it.

* **Host API Boundaries**: WASM plugins cannot perform blocking I/O (no `std::fs`, no threading). They must query the host for JSON snapshots (e.g., `fs_list`, `fs_ops`, `media`). Heavy tasks must be dispatched to the host via `fs_action` so they run on background threads.

- ## 5. Ecosystem Boundaries

+ ## 5. Frame Scheduling & Idle Budget

+ Vanta is meant to run 24/7, so a static screen must idle at ~2 fps (~4% of a core on an i5-8265U).

+ * `src/anim.rs`: widgets that visibly animate call `anim::request(fps)` / `anim::request_full()` during render. The event loop redraws at the highest request (capped by `ui.fps`), else `anim::IDLE_FPS`. Input and resizes redraw immediately.

+ * Never animate on a silent/idle state at full fps. Only request frames while there's actual motion.

+ * Samplers whose data only extensions read (`services`, `connections`) use `monitors::Demand` so they run only while someone reads them.

+ * Profile with `VANTA_PROFILE=1` (writes `/tmp/vanta-profile.log`).

+ ## 6. Build & Verify

+ * Full release build (thin LTO) takes ~8 min. For iteration use a non-LTO build in a separate target dir:

+ `CARGO_TARGET_DIR=target/fast CARGO_PROFILE_RELEASE_LTO=false CARGO_PROFILE_RELEASE_CODEGEN_UNITS=16 cargo build --release`

+ * CI gates: `cargo fmt --all -- --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test`.

+ * Visual check: `tmux -L vchk new-session -d -s v -x 120 -y 34 ./target/fast/release/vanta; sleep 3; tmux -L vchk capture-pane -t v -p; tmux -L vchk kill-server` (check 200×50, 120×34, 100×30).

+ ## 7. Ecosystem Boundaries

* **Vanta Core** (`vanta`): Contains the foundational monitors, UI framework, Extism host engine, and background threadpools.

* **Vanta Integrations** (`vanta-integrations` repo): A separate cargo workspace holding community-built WASM extensions. Each widget must be its own crate.