Engineering Details

System architecture &
technical blueprint

Study the core architecture that powers Vastra. From native WebContentsView sandboxing to advanced Windows 11 registry handlers, learn what makes Vastra lightweight and secure.

Core Architecture

React Renderer ↔ Electron WebContentsView Flow

Traditional Electron browsers force web pages into insecure and slow <iframe> tags or legacy webview elements that limit performance.

Vastra separates concerns perfectly: The React Renderer keeps the absolute source of truth about browsing states inside global Zustand stores. The Electron Main Process maintains a dedicated, lightweight TabManager that creates native, isolated WebContentsView instances.

When resizing or rendering occurs, the React window host measures bounds via a ResizeObserver and pushes dimensions to Electron, matching coordinates perfectly.

System Thread Separation

Main Process (Electron Node.js)

Manages TabManager, creates OS windows, handles will-download hooks, hooks shortcuts, edits registries.

Renderer Process (React, Vite)

Renders dashboard UI, settings sheets, active workspaces, and monitors dimensions.

Secure Context Preload Bridge

IPC bridge exposing limited hooks (window.vastra) to prevent raw Node access in the browser views.

Interactive Tab Navigation Loop

1. React Store Dispatch

User clicks tab/types URL. Zustand modifies active state.

2. Preload IPC Signal

Preload bridge passes tabID & payload over secure channel.

3. WebContentsView load

Main process maps view coordinates, mounts layout, and streams the URL.

Windows 11 Integration

Win11 Default Apps Registry Architecture

Windows 11 enforces strict policies on default browser takeovers to block silent browser hijacking. Apps failing to declare Capabilities are filtered out of OS prompts.

Vastra implements an advanced registry writing model on startup (running safely in User space without admin requests):

  • Configures capability declarations in HKCU\Software\Vastra\Capabilities.
  • Hooks protocol declarations (http/https/mailto) to VastraHTML pointers.
  • Checks active OS default precisely by executing reg query UserChoice\ProgId instead of relying on Electron's false-positive hooks, checking defaults instantly on window refocus.
Registry declaration schema 
// HKCU Registry structure declared by Vastra:
Software\RegisteredApplications\Vastra
  └─ Pointer: Software\Vastra\Capabilities

Software\Vastra\Capabilities
  ├─ URLAssociations: http, https → VastraHTML
  └─ FileAssociations: .html, .svg → VastraHTML

Software\Classes\VastraHTML\shell\open\command
  └─ Default: "path\to\Vastra.exe" "%1"
Data Layer

The Dynamic Favicon Discovery Matrix

To ensure beautiful visuals across your workspaces and widgets, Vastra utilizes a dynamic favicon discovery mechanism, completely bypassing hardcoded bookmarks.

When any site loads, Vastra routes lookup requests through a prioritized five-tier probe tree:

  1. Requests Google s2 128px domain database.
  2. Falls back to DuckDuckGo dynamic icon service.
  3. Checks site's host root /favicon.ico address directly.
  4. Inspects Apple iOS web app touch anchors.
  5. Builds a localized gradient letter-tile canvas render as a last resort.

All discovery results are stored inside an active in-memory cache and persisted locally!

App-wide Integration Points

Workspaces Tab Lists: Displays matching icons per active session.
New-Tab Quick Links: Dynamic logo display with validator hints.
History Logs: Visual indicators for active domains.
Command Search Results: Fast fuzzy matches displaying icons.

Built on modern bricks

Vastra leverages optimized open-source web frameworks to achieve high reliability and speed.

Electron
v33.0
React
v18.2
Vite
v5.0
Zustand
v4.4
Tailwind CSS
v3.3