Xcalux Browser

Xcalux Browser is a modular low-bandwidth browser stack designed for constrained networks such as 2G/3G conditions common in parts of Nigeria. It focuses on minimizing transfer size, reducing script overhead, and preserving legibility on low-end devices.

Last Documentation Update: 2026-04-04

Live Code Metrics Dashboard

Metric	Value
Files Counted	87
Total LOC (Non-Empty)	30,810
LOC Snapshot Date	2026-04-04
Total Lines (Raw)	32,389
Avg LOC / File	354
Current Users (Neon DB)	1
Last Updated	2026-04-04 17:57:12

Language Breakdown

Language	Files	LOC (Non-Empty)	Lines (Raw)	Share	Footprint
Rust	8	11,013	11,147	35.7%	█████████
C	3	8,206	8,268	26.6%	███████
Assembly	2	4,480	4,499	14.5%	████
Python	5	3,011	3,532	9.8%	██
C++	20	2,323	2,822	7.5%	██
C/C++ Header	21	544	705	1.8%	█
Go	5	498	588	1.6%	█
HTML	4	317	327	1.0%	█
SCSS	1	91	104	0.3%	█
JavaScript	1	85	105	0.3%	█
SVG	2	77	82	0.2%	█
CMake	5	65	86	0.2%	█
Shell	4	59	76	0.2%	█
TOML	6	41	48	0.1%	█

Metric Analysis

• Largest code surfaces: Rust (11,013), C (8,206), Assembly (4,480)
• Current registered users (Neon DB): 1
• This dashboard is generated from source files only (build/cache/vendor outputs are excluded).
• Run python3 scripts/update_readme_metrics.py any time to refresh this section manually.

Auto-generated by scripts/update_readme_metrics.py.

Project Snapshot

Area	Design
Core Objective	Low-bandwidth web rendering and optimization for constrained networks
Main Runtime	C++ optimization engine + embedded QtWebEngine browser
Performance Stack	Rust optimizer + WASM preprocess + C compression layer
Network Adaptation	Tuned 2g / 3g / 4g / wifi profiles
UX Direction	Tabbed, responsive browser UI with search cards and image previews
Security Layer	Download risk guard + optional ClamAV quarantine scanning
Account Layer	Neon PostgreSQL auth with email-based password reset codes

Founder

• Project starter: Chisom Life Eke
• GitHub: @chisomlifeeke
• Profile: 17-year-old Nigerian system-level development enthusiast
• Mission: reduce internet consumption on low-end PCs while enabling 4K rendering paths for high-end PCs

Aura Theme Pack

• Animated hero assets for README:
  • docs/assets/readme-aura-hero.svg
  • docs/assets/readme-signal.svg
• Advanced SCSS design system:
  • docs/assets/readme-aura-theme.scss

// quick import for docs/site pages
@use "docs/assets/readme-aura-theme" as aura;

.hero {
  @include aura.glass-card;
}

.headline {
  @include aura.aura-gradient-text;
}

Documentation Hub (Open Source)

• Architecture Reference
• Full Software Guide
• Browser Overview
• Render Pipeline
• Search System
• Security and Accounts
• Contributing Guide

Metrics Workflow

1. Metrics are generated by scripts/update_readme_metrics.py.
2. scripts/build.sh and scripts/build_rust_wasm.sh automatically refresh README.md.
3. Manual refresh is available with python3 scripts/update_readme_metrics.py.

What is implemented

• Core browser engine in C++ (engine/core)
• SIMD-ready compression layer in C (modules/compression-c)
• Adaptive render modes:
  • Low Data
  • Balanced
  • High Quality
  • Ultra Lite (text-first)
• Smart resource blocker (ads, heavy embeds, preload/prefetch stripping)
• DOM simplification pipeline + above-the-fold pre-render extraction
• JavaScript deferring and inline script throttling
• Image lazy loading and quality tagging
• Intelligent compressed cache (.xcalux_cache)
• Nigeria network profile tuning for 2g, 3g, 4g, wifi
• Optional GPU enhanced UI scaling (requires explicit --gpu)
• Optional 4K-like GPU scaling (--gpu-4k)
• Explicit ad blocker control (--adblock, --no-adblock)
• Optional WASM preprocessing toggle (--wasm)
• Embedded Qt GUI browser for internet sites with tabbed browsing, custom homepage/search UI, dev mode, and download guard (ui/python/xcalux_qt_webengine_browser.py)
• Rich search cards with extracted page summaries + thumbnail previews
• Neon-backed account system (username/email/password hash) + forgot-password email reset codes
• Background-threaded page pipeline + search enrichment to reduce UI lag
• Rust policy engine with large signature rule database and mode-aware blocking levels
• C policy scanner for tracker/heavy-media fingerprint detection and compression advice
• x86_64 assembly memops primitives (count/find/xor-copy) plus heuristic lookup tables

Architecture

• Core Engine: C++
• Performance Modules: Rust (modules/perf-rust)
• Compression Layer: C + SIMD intrinsics (modules/compression-c)
• Networking Proxy: Go (proxy/go-net)
• WASM Optimization Module: Rust + wasm-bindgen (wasm/preprocess)

See docs/ARCHITECTURE.md for details.

GitHub Architecture Diagram

flowchart LR
    U[User Input URL or Search] --> UI[Python Qt Browser UI]
    UI --> S{Request Type}
    S -->|Search| IDX[DuckDuckGo Index + Instant Summary]
    S -->|Page Load| F[Fetch HTML]

    subgraph DOMP["DOM and Optimization Pipeline"]
        F --> B[Inject Base Href]
        B --> W[WASM Preprocess Optional]
        W --> R[Rust Optimizer Optional]
        R --> C[C++ Xcalux Engine]
        C --> O[Optimized Final HTML]
    end

    IDX --> SR[Custom Search Results UI]
    SR --> UI
    O --> E[QtWebEngine Renderer]
    E --> V[Rendered Page in App]

    UI --> DLG[Download Guard]
    DLG --> AV[Optional ClamAV Scan + Quarantine]
    UI --> DB[Neon Account Auth]

Loading

Build and run (C/C++ engine)

./scripts/build.sh
./build/engine/core/xcalux-browser --input samples/lagos-news.html --mode low-data --network 2g --stats --output output/page.html

Or run the full demo:

./scripts/demo.sh

CLI examples

Low data for very slow network:

./build/engine/core/xcalux-browser \
  --input samples/lagos-news.html \
  --mode low-data \
  --network 2g \
  --stats

GPU enhanced high quality (user permitted):

./build/engine/core/xcalux-browser \
  --input samples/lagos-news.html \
  --mode high-quality \
  --network 4g \
  --gpu \
  --stats

Ultra Lite text-first fallback:

./build/engine/core/xcalux-browser \
  --input samples/lagos-news.html \
  --mode ultra-lite \
  --network 2g \
  --stats

4K GPU + ad blocker:

./build/engine/core/xcalux-browser \
  --input https://example.com \
  --mode high-quality \
  --network 4g \
  --gpu \
  --gpu-4k \
  --adblock \
  --stats

GUI

python3 ui/python/xcalux_ui.py --engine build/engine/core/xcalux-browser

The GUI supports:

• Site URL/search input with internet fetching via the engine
• Data estimate prompt before full-site load
• Ad blocker toggle
• GPU Enhanced and 4K GPU rendering toggles

Embedded QtWebEngine GUI (In-App Renderer)

This runtime renders optimized pages inside the app window via QtWebEngine (no external Chromium window). Search attribution: the internal search feature uses DuckDuckGo index data under the hood, while results are rendered in Xcalux UI.

./scripts/build.sh
./scripts/build_rust_wasm.sh
./.venv/bin/python -m pip install PyQt6 PyQt6-WebEngine qtawesome psycopg[binary]
./.venv/bin/python ui/python/xcalux_qt_webengine_browser.py --engine build/engine/core/xcalux-browser

If your system shows GPU startup crashes (GpuControl.CreateCommandBuffer), run:

./.venv/bin/python ui/python/xcalux_qt_webengine_browser.py \
  --engine build/engine/core/xcalux-browser \
  --safe-render --low-memory --max-workers 3

Account setup:

• copy .env.example to .env
• set DATABASE_URL (Neon)
• set SMTP vars for forgot-password email delivery

Full setup/use guide:

• docs/FULL_SOFTWARE_GUIDE.md

Rust + WASM + Chromium Browser Runtime

For full HTML/CSS/JS animations (Google-like runtime behavior), use the Rust/WASM pipeline plus Chromium renderer:

./scripts/build.sh
./scripts/build_rust_wasm.sh
python3 ui/python/xcalux_rust_wasm_browser.py --engine build/engine/core/xcalux-browser

This runtime flow is:

1. Fetch internet page HTML
2. WebAssembly preprocess (wasm/preprocess)
3. Rust optimizer (modules/perf-rust)
4. C++ core engine pass (modes/adblock/network/GPU)
5. Open final page in Chromium (real JS/CSS animation runtime)

Go proxy and Rust modules

The Go and Rust modules are scaffolded with working source code and interfaces. Build commands:

# Go proxy
cd proxy/go-net && go run . --port 8088

# Rust performance module
cd modules/perf-rust && cargo run --bin xcalux-perf-cli -- --mode low-data < ../../samples/lagos-news.html

# WASM module
cd wasm/preprocess && cargo build --target wasm32-unknown-unknown

Status

This repository currently ships a working C/C++ engine path and production-style module stubs for Rust/Go/WASM so teams can iterate by stack ownership while preserving a lightweight, retro-modular architecture.

Validation snapshot

Measured on April 4, 2026 using samples/news_portal.html with --no-cache:

• Low Data + 2g: 1659 -> 1559 bytes
• Ultra Lite + 2g: 1659 -> 1109 bytes
• High Quality + 4g --gpu: 1659 -> 2548 bytes (intentional visual-quality tradeoff)