β οΈ Work in Progress - BrowserX is in active development. Many components are experimental, incomplete, or undergoing significant changes. This project is not yet production-ready.
A browser toolkit built with TypeScript/Deno and Rust. BrowserX is a fully composable, programmable browser system with 11 standalone packages β every component from networking to rendering to GPU acceleration can be used independently or combined to create custom browser experiences.
BrowserX is not a traditional browser. It's a toolkit for building anything browser-related. Whether you need a headless scraper, a custom renderer, a programmable proxy, or a full-featured browser with AI integration, BrowserX provides the building blocks.
All packages are designed to work together as an integrated system, but each is a standalone composable unit with its own workspace, API, and test suite:
TypeScript/Deno Packages (7):
- Browser Engine (
@browserx/browser) - Complete rendering pipeline: HTML/CSS parsing, layout, JavaScript execution, DOM manipulation - Proxy Engine (
@browserx/proxy-engine) - Programmable traffic routing: middleware, load balancing, caching, request/response transformation - Query Engine (
@browserx/query-engine) - SQL-like interface: query browser state, DOM tree, network activity, and proxy metrics - Runtime (
@browserx/runtime) - Unified orchestration layer integrating all engines with plugin architecture - MCP Server (
@browserx/mcp-server) - Model Context Protocol server for AI-driven browser automation - DevTools (
@browserx/dev-tools) - Chrome DevTools Protocol (CDP) implementation with 14 debugging domains - GraphX (
@browserx/graphx) - Graph data structures, algorithms (topological sort, shortest path, cycle detection), and visualization
Rust FFI Crates (4):
- pixpane - Native windowing: cross-platform windows, GPU rendering via wgpu, immediate-mode UI with egui
- webgpu_x - GPU compute: WebGPU bindings for compute shaders, texture readback, and bind group management
- bytecodex - Bytecode optimization: constant folding, dead store elimination, peephole optimization, validation
- transportx - QUIC/HTTP/3 transport: connection management, stream multiplexing via quiche FFI
The toolkit is designed for composability at every level:
- Use the Browser Engine alone for server-side rendering or scraping
- Combine Browser + Proxy for traffic inspection and modification
- Add Pixpane for native window output with GPU acceleration
- Layer on Query Engine for AI/ML-friendly programmatic access
- Use webgpu_x for custom GPU compute alongside rendering
Every component exposes its internals through public APIs, allowing you to compose exactly what you needβnothing more, nothing less.
Testing & Automation:
- Headless browser testing with full DOM/layout introspection
- Visual regression testing with pixel-perfect rendering
- Performance testing with detailed timing breakdowns
- AI-powered test generation using query interface
AI & Machine Learning:
- AI agents that inspect render trees and layout information
- Browser automation driven by natural language queries
- Training data collection from real browser sessions
- Custom rendering for vision model inputs
Development Tools:
- Custom DevTools with deep protocol visibility
- Traffic debugging and manipulation proxies
- Performance profiling at every layer
- Browser experimentation and research
Production Services:
- Programmable CDN with edge rendering
- Screenshot and PDF generation services
- Web scraping with full JavaScript support
- API gateway with browser-level protocol handling
BrowserX reimagines the browser as a composable, queryable system where every layer can be accessed, controlled, and extended programmatically. Instead of a monolithic black box, BrowserX exposes:
- Browser Engine: Full rendering pipeline from HTML parsing to GPU compositing
- Proxy Engine: Programmable traffic routing, interception, and transformation
- Query Engine: SQL-like interface for browser and proxy operations
- Native Windowing: Cross-platform GPU-accelerated rendering via Rust FFI
This architecture enables use cases like:
- Automated testing with deep introspection
- AI agents that can inspect render trees and layout
- Traffic analysis and manipulation at any protocol layer
- Browser automation with query-based selectors
- Custom rendering pipelines and display strategies
Understanding the Layers:
βββββββββββββββββββββββββββββββββββββββ
β MCP Server β Model Context Protocol API
β - AI tool integration β for LLM-driven browser control
β - stdio/HTTP transports β Screenshot & activity persistence
βββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββ
β Query Engine β SQL-like queryable interface
β "SELECT * FROM browser β for humans and AI/ML
β WHERE url LIKE '%.example.com'" β
βββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββ
β Runtime β Unified orchestration layer
β - Integrates browser, proxy, query β Plugin architecture, lifecycle
β - Plugin system with disposables β management, composable workflows
βββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββ
β Proxy Engine β Traffic routing, middleware,
β - Request/Response interception β caching, load balancing
β - Middleware pipeline β
β - Connection pooling β
βββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββββββββββββββββββββββ
β Browser Engine β Core rendering and networking
β - HTML/CSS parsing β Full page load pipeline
β - JavaScript execution (V8) β from DNS to pixels
β - Layout & Rendering β
β - Network stack (TCP/TLS/HTTP) β
β - WebGPU rendering (Deno native) β
βββββββββββββββββββββββββββββββββββββββ
β
ββββββββββββ΄βββββββββββ
β β
ββββββββββββββββββββ ββββββββββββββββββββ
β Pixpane (Rust) β β webgpu_x (Rust) β
β - Windows/UI β β - GPU Compute β
β - GPU Rendering β β - Kernels β
β - egui (FFI) β β - Tensors (FFI) β
ββββββββββββββββββββ ββββββββββββββββββββ
ββββββββββββββββββββ ββββββββββββββββββββ
β bytecodex (Rust) β β transportx(Rust) β
β - Const folding β β - QUIC/HTTP/3 β
β - Dead store β β - Stream mux β
β - Peephole (FFI) β β - quiche (FFI) β
ββββββββββββββββββββ ββββββββββββββββββββ
Data Flow: User requests flow down through the MCP server β query engine β runtime β proxy engine β browser engine. The browser engine can then output to:
- Pixpane for visual rendering (windows, UI, display)
- webgpu_x for GPU compute workloads (ML, custom shaders, tensor operations)
Each layer can be used independently or composed together.
BrowserX/
βββ browser/ # Browser Engine (TypeScript/Deno)
β βββ src/
β β βββ engine/ # Core: network, rendering, JavaScript, storage
β β βββ types/ # Type system: HTTP, DOM, CSS, rendering types
β β βββ os/ # Platform abstractions
β βββ docs/ # 19 detailed architecture documents
β βββ examples/ # Browser usage examples
β
βββ proxy-engine/ # Proxy Engine (TypeScript/Deno)
β βββ core/ # Gateway, routing, caching, connection pooling
β β βββ network/ # Network primitives, transport protocols
β β βββ proxy_types/ # Auth, reverse, load balance, WebSocket proxies
β β βββ cache/ # Cache manager with eviction policies
β βββ gateway/ # Request/response routing and middleware
β
βββ query-engine/ # Query Engine (TypeScript/Deno)
β βββ parser/ # SQL-like query parser
β βββ executor/ # Query execution engine
β βββ adapters/ # Adapters for browser/proxy backends
β
βββ runtime/ # Runtime (TypeScript/Deno)
β βββ src/
β β βββ config/ # Runtime configuration
β β βββ plugins/ # Plugin system (manager, loader, registry)
β β βββ types.ts # Runtime type definitions
β βββ tests/ # Runtime and plugin tests
β
βββ mcp-server/ # MCP Server (TypeScript/Deno)
β βββ server/ # MCP server setup, transports (stdio/HTTP)
β βββ tools/ # Tool implementations (browser, query, proxy)
β βββ resources/ # Resource providers (page, metrics)
β βββ activity/ # Activity tracking and persistence
β βββ session/ # Browser session management
β
βββ dev-tools/ # DevTools Protocol (TypeScript/Deno)
β βββ src/domains/ # CDP domains (DOM, CSS, Network, etc.)
β βββ tests/ # 847+ tests across 24 test files
β
βββ graphx/ # Graph Library (TypeScript/Deno)
β βββ src/
β β βββ graph/ # Graph, DiGraph, DAG data structures
β β βββ algorithms/ # Topological sort, shortest path, cycle detection
β β βββ layout/ # Force-directed, hierarchical layouts
β β βββ export/ # SVG, DOT, JSON export
β βββ tests/ # 164 tests
β
βββ crates/
β βββ pixpane/ # Native windowing layer (Rust)
β β βββ src/
β β β βββ window/ # Window management (winit)
β β β βββ rendering/ # GPU rendering (wgpu, egui)
β β β βββ deno_bindings.rs # FFI exports via deno_bindgen
β β βββ bindings/ # Generated TypeScript bindings
β β
β βββ webgpu_x/ # GPU compute layer (Rust)
β β βββ src/
β β β βββ compute/ # Compute kernels and workgroups
β β β βββ tensor/ # Tensor operations and storage
β β β βββ shader/ # WGSL shader generation
β β β βββ deno_bindings.rs # FFI exports via deno_bindgen
β β βββ bindings/ # Generated TypeScript bindings
β β
β βββ bytecodex/ # Bytecode optimizer (Rust)
β β βββ src/ # Constant folding, dead store elimination, peephole
β β
β βββ transportx/ # QUIC/HTTP/3 transport (Rust)
β βββ src/ # Connection management, stream mux via quiche
β
βββ resources/ # Reference implementations and dependencies
β βββ deno_bindgen-0.8.1/ # Custom deno_bindgen for FFI generation
β βββ deno/ # Deno runtime fork (for reference)
β βββ wgpu/ # wgpu graphics library (for reference)
β βββ [other references] # Additional libraries for research
β
βββ resource/devdocs/ # Architecture documentation
βββ Browser.md # Complete browser architecture (30k+ tokens)
βββ ProxyEngine.md # Complete proxy architecture (57k+ tokens)
βββ QueryEngine.md # Query engine design
βββ WEBGPU_RENDERING.md # WebGPU rendering architecture
βββ WEBGPU_FIXES.md # Deno WebGPU workarounds
βββ 01-19*.md # 19 detailed browser subsystem documents
git clone https://github.com/LayerDynamics/BrowserX.git
cd BrowserXNote: Most components are still being implemented. See individual component READMEs for current status.
cd browser
# Type check
deno task check
# Run tests
deno task test
# Run example (when available)
deno run --allow-all examples/basic.tscd proxy-engine
# Type check
deno check core/runtime.ts
# Run tests (when available)
deno test --allow-allcd crates/pixpane
# Build Rust library
cargo build --release
# Generate TypeScript bindings
deno run --allow-all gen_bindings.ts
# Run FFI test
deno run --allow-ffi --unstable-ffi tests/test.tscd crates/webgpu_x
# Build Rust library
cargo build --release
# Generate TypeScript bindings
deno run --allow-all gen_bindings.ts
# Run FFI test
deno run --allow-ffi --unstable-ffi tests/test.ts# Start MCP server with stdio transport (for Claude Desktop)
deno task mcp:start
# Start with HTTP transport (for custom integrations)
deno task mcp:start:http
# Type check
deno task mcp:checkClaude Desktop Integration - Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"browserx": {
"command": "deno",
"args": ["task", "mcp:start"],
"cwd": "/path/to/BrowserX"
}
}
}# Type check
deno task runtime:check
# Run tests (includes plugin system tests)
deno task runtime:testBrowserX automatically saves screenshots and activity data for debugging and analysis:
.browserx/usage_data/
βββ screenshots/ # Saved screenshots organized by date
β βββ YYYY-MM-DD/
β βββ {timestamp}_{id}.png
βββ logs/ # Daily activity logs in JSONL format
β βββ YYYY-MM-DD.jsonl
βββ metadata/ # Session metadata
βββ {sessionId}.json
The browser_screenshot MCP tool returns both the image data AND the saved file path, enabling AI agents to reference previously captured screenshots.
- Browser.md - Complete browser architecture: multi-process model, page load sequence, rendering pipeline, network stack
- ProxyEngine.md - Proxy architecture: layered design, connection pooling, caching, middleware
- QueryEngine.md - Query engine design and composability model
- WEBGPU_RENDERING.md - WebGPU rendering architecture for Deno
- browser/docs/ - 19 detailed technical documents covering every browser subsystem
- browser/README.md - Browser engine API and usage
- proxy-engine/README.md - Proxy engine configuration and middleware
- query-engine/README.md - Query syntax and execution
- runtime/README.md - Runtime lifecycle, configuration, plugin system
- mcp-server/README.md - MCP server tools, resources, AI integration
- crates/pixpane/README.md - FFI bindings and window management
- crates/webgpu_x/README.md - GPU compute, kernels, and tensor operations
# Browser type checking
cd browser && deno task check
# Proxy type checking
cd proxy-engine && deno check core/runtime.ts
# Build Pixpane + generate bindings
cd crates/pixpane && cargo build --release && deno run --allow-all gen_bindings.ts
# Build webgpu_x + generate bindings
cd crates/webgpu_x && cargo build --release && deno run --allow-all gen_bindings.ts
# Run all tests
cd browser && deno test --allow-all
cd crates/pixpane && cargo test
cd crates/webgpu_x && cargo testBrowser & Proxy Engines:
- TypeScript/Deno for type-safe, modern JavaScript runtime
- Multi-process architecture inspired by Chromium
- Event-driven async I/O for high performance
Pixpane (Native Layer):
- Rust for systems-level performance and safety
- wgpu 22 for cross-platform GPU acceleration
- winit 0.30 for window management
- egui 0.29 for immediate-mode UI
- deno_bindgen 0.8.1 for FFI code generation
webgpu_x (GPU Compute Layer):
- Rust for high-performance compute kernels
- wgpu 22 for GPU compute and shader execution
- WGSL shader language support
- Tensor operations for ML workloads
- deno_bindgen 0.8.1 for FFI code generation
Browser Engine :
- Complete type system (11 type files: HTTP, DOM, CSS, rendering, network, JavaScript, storage, events, WebGPU)
- Network layer: TCP connection management, TLS 1.3 implementation with handshake and certificate validation, connection pooling, DNS resolution
- HTTP protocol: Request/response parsing, header handling, connection reuse
- HTML tokenizer: Full state machine with 80+ tokenization states
- CSS parser: Selector matching, specificity calculation, cascade resolution
- JavaScript engine: V8 isolate management, execution contexts, heap management, bytecode compilation with 11 ops, bytecodex FFI optimization (721 tests)
- CSS at-rules:
@media,@keyframes,@font-face,@importparsing with media query matching, percentage length resolution - Storage types: Interfaces for localStorage, sessionStorage, IndexedDB, cookies, quota management
- WebGPU rendering: Offscreen rendering via Deno's native WebGPU, GPU readback, WGSL compositor shaders, compositeLayer GPU compositing
- Window subsystem:
Window+WindowContextclasses with OS abstractions
Proxy Engine :
- Runtime orchestration: Lifecycle management, graceful shutdown, signal handling
- Gateway layer: Request/response routing with pattern matching, middleware chain execution
- Connection management: Pooling with configurable size limits, health checking, lifecycle tracking
- Transport protocols: HTTP/1.1, HTTP/2, HTTP/3, WebSocket, TLS termination
- Cache layer: Memory/disk storage with encryption, TTL management, LRU/LFU/FIFO eviction policies
- Middleware system: Auth, rate limiting, logging, CORS, compression, header manipulation
- Network primitives: TCP sockets, IP address handling, buffer pools
- Event system: Event loop, async handling, priority queuing
- Process/thread management: Multi-process architecture, worker pools, task scheduling
- Proxy types: Reverse proxy, load balancer, auth proxy, WebSocket proxy, SSE proxy, TLS proxy, event-driven proxy
- Load balancing: Round-robin, least connections, weighted, IP hash, least response time, random (1878 tests)
- ALPN protocol negotiation: TLS ClientHello parsing and extension building
- HTTP/2 GOAWAY: Stream draining and graceful connection shutdown
Query Engine :
- Lexer: Token generation from query strings
- Parser: Recursive descent parser building Abstract Syntax Trees (AST)
- SQL-like statements: SELECT, INSERT, UPDATE, DELETE, NAVIGATE, SET, SHOW, FOR, IF, WITH
- Query analysis: Semantic analysis, type checking, validation
- Planner: Query plan generation
- Optimizer: Query optimization strategies
- Executor: Query execution engine
- Type system: Primitive types, collections, functions
- Error handling: Comprehensive error types and recovery
- Browser wiring: DOM functions (CLICK, TYPE, TEXT, HTML, ATTR, COUNT, EXISTS) async with browser controller
- Result formatting: Multiple output formats (JSON, CSV, table)
- Dependency graph: GraphX-backed
DependencyGraphBuilderwith topological sort and cycle detection
Pixpane :
- Window management: Creation, configuration, lifecycle control (winit 0.30)
- Event loop: pump_events model with non-blocking polling, thread-safe event queue
- GPU rendering: wgpu 22 integration with surface management, texture uploads
- egui integration: Immediate-mode UI (egui 0.29) with full widget support
- FFI layer: deno_bindgen 0.8.1 with comprehensive TypeScript bindings
- Thread safety: Lazy-static window registry with parking_lot synchronization
- Pixel rendering: RGBA8 buffer uploads, fullscreen texture rendering
- Window operations: Resize, move, minimize, maximize, fullscreen, visibility control
webgpu_x :
- Compute kernels: Kernel specification, parameter binding, workgroup configuration
- WGSL generation: Automatic shader code generation from kernel specs
- Tensor types: Float32, Float16, Int32, Int8, UInt8 with size calculations
- Tensor access: ReadOnly, WriteOnly, ReadWrite, Uniform patterns
- GPU infrastructure: Device management, queue handling, buffer operations
- FFI bindings: Comprehensive Deno integration for GPU compute
- Shader support: WGSL type mapping, storage qualifiers
- GPU readback: Texture-to-CPU data transfer for screenshot capture
- Bind group creation: Resource binding for render pipelines
- Command encoding: Render pass commands and queue submission
Runtime :
- Unified orchestration: Integrates browser, proxy, and query engines
- Plugin system: PluginManager with topological sort activation, reverse deactivation
- Plugin lifecycle: All contributions return Disposable for automatic cleanup
- Plugin registry: Discovery, validation, and loading of plugins
- Configuration: RuntimeConfig with plugin enablement (opt-in by default)
- Lifecycle components: LifecycleManager, HealthChecker, UnifiedMetricsCollector, EventCoordinator
- BrowserPool: acquire/release pattern with idle timeout, max lifetime, automatic cleanup
- GraphX integration: PluginManager uses GraphX DAG + topologicalSort for activation ordering (98 plugin tests)
MCP Server :
- Model Context Protocol: Full MCP SDK integration (v1.12.0)
- Browser tools:
browser_navigate,browser_screenshot,browser_click,browser_type,browser_evaluate - Query tools:
browserx_query,browserx_query_async,browserx_query_explain - Proxy tools:
proxy_cache_get,proxy_cache_set,proxy_add_interceptor - Transports: stdio (default for Claude Desktop), HTTP on port 9847
- Activity tracking: Persistent file-based logging of screenshots and activities
- Data persistence: Screenshots saved to
.browserx/usage_data/screenshots/, activity logs in JSONL format - Lazy initialization: Fast startup (<100ms) with services initialized on first use
- Runtime integration: ServiceInitializer with BrowserPool delegation, health checks, metrics
- Session management: SessionManager delegates to Runtime BrowserPool with critical shutdown ordering
- Graph tools:
browserx_visualize_dom,browserx_dependency_graph,browserx_plugin_graph
DevTools :
- Chrome DevTools Protocol: 14 debugging domains implemented
- Domains: Runtime, Debugger, DOM, CSS, Network, Storage, Console, Page, Emulation, Overlay, Security, Rendering, Performance, Memory
- Event system: EventBus for cross-domain pub/sub communication
- Test coverage: 847+ tests across 24 test files
GraphX :
- Graph data structures: Graph (undirected), DiGraph (directed), DAG (directed acyclic)
- Algorithms: BFS, DFS, Dijkstra shortest path, topological sort, cycle detection, connected components
- Layout engines: Force-directed (Fruchterman-Reingold), hierarchical (Sugiyama), radial, grid
- SVG rendering: Headless SVG generation with themes, labels, arrowheads
- Cross-codebase integration: Runtime PluginManager, Query Engine DependencyGraphBuilder, MCP visualization tools
- Test coverage: 164 tests across graph structures, algorithms, layout, and rendering
bytecodex :
- Constant folding: Folds arithmetic on constant operands into single constants
- Dead store elimination: Removes unused register stores
- Peephole optimization: Pattern-matches small instruction windows
- Bytecode validation: Opcode validity, operand counts, constant pool bounds, jump targets
- Disassembly: Human-readable bytecode output
- V8Compiler integration:
compile(source, { optimize: true })runs bytecodex FFI pass (15 Rust tests)
transportx :
- QUIC/HTTP/3 transport: Connection management and stream multiplexing via quiche FFI
Browser Engine:
- Layout engine: Box model calculation, block/flexbox/grid layout algorithms, text measurement
- Paint engine: Display list generation, rasterization
- Compositor: Layer management, tiling, GPU texture uploads, VSync synchronization
- Full rendering pipeline: End-to-end integration from HTML to pixels
Proxy Engine:
- Metrics collection: Request tracking, latency histograms, throughput measurement
- Distributed tracing: Trace context propagation, span collection
Query Engine:
- Advanced SQL features: Subqueries, joins, aggregations, window functions
Integration:
- End-to-end data flow: MCP Server β Query Engine β Runtime β Proxy Engine β Browser Engine
- Cross-layer communication: Event propagation, state synchronization
- Performance optimization: Pipeline parallelization, caching strategies
Core Functionality:
- Complete HTML tree builder with error recovery and special element handling
- CSS layout engine: Complete flexbox and grid implementations, positioned elements
- JavaScript V8: Full DOM API bindings, Web APIs (fetch, setTimeout, Promise)
- Storage implementations: Actual localStorage, sessionStorage, IndexedDB, cookie persistence
- GPU acceleration: Hardware-accelerated compositing, canvas rendering
Developer Tools:
- CLI interface: Interactive query shell for browser/proxy inspection
- Web UI: Browser-based inspector for debugging and metrics visualization
- Performance profiler: CPU/memory/network profiling tools
Testing & Quality:
- Comprehensive test suites: Unit tests, integration tests, end-to-end tests
- Browser compatibility tests: Rendering accuracy vs Chrome/Firefox
- Performance benchmarks: Page load times, rendering speed, memory usage
- Fuzzing: Protocol fuzzing, parser fuzzing for security
Advanced Features:
- Service workers: Background processing, offline support
- WebAssembly: WASM execution in V8
- WebRTC: Peer-to-peer communication
- WebSocket server: Bidirectional communication support
- HTTP/3 optimizations: QUIC transport enhancements
BrowserX is in early development. Contributions are welcome, but please note:
- Architecture is evolving: Core designs may change significantly
- Documentation is primary: Focus on understanding and documenting the architecture
- Stubs are intentional: Many files contain stubs for planned functionality
- Used imports matter: If an import is unused, it's likely meant to be used - implement it rather than removing it
See CONTRIBUTING.md for detailed guidelines.
BrowserX is licensed under the MIT License.
- Deno - Modern JavaScript/TypeScript runtime
- Chromium - Architectural inspiration for multi-process browser
- wgpu - Cross-platform GPU API
- V8 - JavaScript engine
BrowserX is built on these principles:
- Composability: Every layer is usable independently
- Programmability: Query and control everything via code
- Transparency: Expose internal state and operations
- Extensibility: Plugin architecture at every layer
- Performance: Multi-process, async I/O, GPU acceleration
- Type Safety: Strong typing throughout TypeScript and Rust
Note: This project is experimental and educational. It is not intended to replace production browsers like Chrome, Firefox, or Safari, but rather to explore alternative architectures and enable new use cases for programmable web interaction.