Ventus: Instructions file for Claude Code

Ventus — Claude Context File

Read RULES.md before writing any code. It defines naming, comments, wording, structure, and IPC conventions for this project. All code must match that style.

Rust desktop browser. Frameless window, Zen Browser-inspired UI, AI sidebar. Stack: WRY 0.38.2, TAO 0.28, WebView2 (Windows), SQLite (rusqlite), Tokio.

---

Architecture: Two-Layer WebView System

The most critical architectural concept. Two types of WebViews co-exist as Win32 child HWNDs:

Chrome WebView — full-window overlay (0,0,win_w,win_h), always on top via SetWindowPos(HWND_TOP).

• Contains all UI: toolbar, sidebar, AI sidebar, settings modal, new-tab page, overlays.
• SetWindowRgn clips it to only the UI regions (toolbar strip + sidebar column + optional AI panel).
• Outside the clip region: mouse events and painting fall through to the content WebViews below.

Content WebViews — one per tab, positioned below chrome in Z-order.

• Rect is (content_x, toolbar_h, content_w, content_h).
• In auto-hide-pinned mode: content_x = sidebar_w. In all other modes: content_x = 0.
• Managed by build_content_webview() in src/runtime/webviews.rs.

Key constraint: WM_MOUSELEAVE never fires when cursor moves from chrome clip region into content area (content is a sibling HWND, not the chrome's client). The content WebView's mousemove IPC is used instead to signal Rust to close the sidebar.

Single WebView2 environment (critical): The chrome WebView and all normal content tabs (+ popups) share ONE WebContext (content_web_context, profile webview_data). The context is created BEFORE the chrome builder, and chrome attaches via .with_web_context(...). WRY caches the ICoreWebView2Environment on the context and reuses it for every later WebView, so there is a SINGLE msedgewebview2.exe browser process tree (one GPU/network/storage utility set) under ventus.exe. Never build a WebView without a shared WebContext — a context-less WebViewBuilder makes WRY create a second environment (default <exe>.WebView2 dir) = a duplicate process tree in Task Manager. Incognito tabs intentionally use a separate incognito_web_context (ephemeral profile) → their own environment, only while incognito tabs exist. Because chrome shares the env, browser args (DoH, 3p-cookie block) can't be swapped at runtime — TabAction::ApplyWebSecurity relaunches the app (relaunch_self → --wait-for-pid + --restore-session). On exit, close_chrome_controller() runs before shutdown_webview2() so the shared browser process flushes its cookie DB before process::exit().