Architecture

AuroraView is built with a modular, backend-agnostic architecture that supports multiple window integration modes.

Design Principles

1. Modularity: Clear separation between core logic and platform-specific implementations
2. Extensibility: Easy to add new backends and platforms
3. Type Safety: Leveraging Rust's type system for reliability
4. API Consistency: Unified API across different backends
5. Performance: Zero-cost abstractions where possible

Architecture Layers

┌─────────────────────────────────────────────────────────────┐
│                     Python API Layer                        │
│  (create_webview, WebView, QtWebView, AuroraView)          │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                   PyO3 Bindings Layer                       │
│  (AuroraView - Python-facing Rust class)                   │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  Backend Abstraction Layer                  │
│  (WebViewBackend trait)                                     │
└─────────────────────────────────────────────────────────────┘
                            │
                ┌───────────┴───────────┐
                ▼                       ▼
┌───────────────────────┐   ┌───────────────────────┐
│   Native Backend      │   │    Qt Host Layer      │
│  (Standalone / HWND)  │   │  (Qt widget container)│
└───────────────────────┘   └───────────────────────┘
                │                       │
                └───────────┬───────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              System WebView Engines                         │
│   Windows: WebView2  │  macOS: WKWebView  │  Linux: WebKitGTK │
└─────────────────────────────────────────────────────────────┘

Core Components

Rust Core (src/)

The Rust core provides:

• WebView Management: Window creation, lifecycle, and events
• IPC System: Bidirectional communication between Python and JavaScript
• Plugin System: High-performance native plugins
• Custom Protocols: Secure local resource loading

src/
├── lib.rs                      # PyO3 module entry point
├── ipc/                        # IPC system for Python ↔ JavaScript
│   ├── mod.rs
│   ├── handler.rs              # IPC message handler
│   ├── message_queue.rs        # Thread-safe message queue
│   └── ...
├── utils/                      # Utilities (logging, etc.)
│   └── mod.rs
└── webview/                    # WebView implementation
    ├── mod.rs                  # Module exports
    ├── aurora_view.rs          # Python-facing class (PyO3)
    ├── config.rs               # Configuration structures
    ├── backend/                # Backend implementations
    │   ├── mod.rs              # Backend trait definition
    │   ├── native.rs           # Native backend (HWND on Windows)
    │   └── qt.rs               # Qt backend
    ├── event_loop.rs           # Event loop handling
    ├── message_pump.rs         # Windows message pump
    ├── protocol.rs             # Custom protocol handler
    ├── standalone.rs           # Standalone window mode
    └── webview_inner.rs        # Core WebView logic

Python Bindings (python/auroraview/)

Python bindings via PyO3 provide:

• WebView API: High-level Python interface
• Event System: Node.js-style EventEmitter
• Qt Integration: QtWebView for DCC applications
• Type Safety: Full type hints and runtime validation

python/auroraview/
├── __init__.py                 # Public API exports
├── webview.py                  # Base WebView class
├── qt_integration.py           # Qt backend implementation
└── event_timer.py              # Event timer for DCC integration

Backend System

Backend Trait

The WebViewBackend trait defines the common interface:

pub trait WebViewBackend {
    fn create(
        config: WebViewConfig,
        ipc_handler: Arc<IpcHandler>,
        message_queue: Arc<MessageQueue>,
    ) -> Result<Self, Box<dyn std::error::Error>>
    where
        Self: Sized;

    fn webview(&self) -> Arc<Mutex<WryWebView>>;
    fn message_queue(&self) -> Arc<MessageQueue>;
    fn window(&self) -> Option<&tao::window::Window>;
    fn process_events(&self) -> bool;
    fn run_event_loop_blocking(&mut self);
    
    // Default implementations for common operations
    fn load_url(&mut self, url: &str) -> Result<(), Box<dyn std::error::Error>>;
    fn load_html(&mut self, html: &str) -> Result<(), Box<dyn std::error::Error>>;
    fn eval_js(&mut self, script: &str) -> Result<(), Box<dyn std::error::Error>>;
    fn emit(&mut self, event_name: &str, data: serde_json::Value) -> Result<(), Box<dyn std::error::Error>>;
}

Native Backend

The NativeBackend uses platform-specific APIs for window embedding:

Platform	Technology	Status
Windows	WebView2 (HWND)	✅ Supported
macOS	WKWebView (NSView)	✅ Supported
Linux	WebKitGTK	✅ Supported

Windows Modes:

• Child: WS_CHILD style (same-thread parenting required)
• Owner: GWLP_HWNDPARENT (safe for cross-thread usage)

Qt Host Layer

The Qt integration layer embeds the system WebView as a child window inside a Qt QWidget container. Qt handles the event loop and window chrome, while the actual rendering is delegated to the platform's native WebView engine (WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux).

Integration Modes

AuroraView provides three integration modes for different scenarios:

1. Desktop Mode

Creates an independent window with its own event loop. Best for standalone applications.

from auroraview import WebView

webview = WebView(title="My App", width=800, height=600)
webview.show()  # Blocking call, owns event loop

Use Cases:

• Standalone tools
• Desktop applications
• Testing and development

2. Native Mode (HWND)

Embeds WebView via HWND into non-Qt applications. Full effect support without Qt dependency.

from auroraview import WebView

# Get parent window HWND from non-Qt app (Blender, Unreal, etc.)
parent_hwnd = get_app_window_handle()

webview = WebView.create(
    title="My Tool",
    width=650,
    height=500,
    parent=parent_hwnd,
    mode="owner",
)
webview.load_html("<h1>Hello from Native Mode!</h1>")
webview.show()

Use Cases:

• Blender integration (non-Qt)
• Unreal Engine integration
• Other non-Qt DCC applications
• Floating tool windows in any application

Key Features:

• ✅ Full window effects support (click-through, blur, mica)
• ✅ Non-blocking - host app remains responsive
• ✅ No Qt dependency

3. Qt Mode

Embeds WebView as a Qt widget child. Best for Qt-based DCC applications where docking is needed.

from auroraview import QtWebView
import hou  # or maya.OpenMayaUI, etc.

# Get DCC main window
main_window = hou.qt.mainWindow()

# Create embedded WebView
qt_webview = QtWebView(
    parent=main_window,
    width=650,
    height=500,
)
qt_webview.load_html("<h1>Hello from Qt Mode!</h1>")
qt_webview.show()

Use Cases:

• Maya, Houdini, Nuke, 3ds Max integration
• Dockable panels
• Qt-based DCC applications

Key Features:

• ✅ Seamless Qt integration
• ✅ QDockWidget support
• ✅ Uses DCC's Qt message pump
• ⚠️ Limited window effects support

3. Packed Mode

When packaged as a standalone executable:

app.exe (Rust)
    ├── Extracts resources and Python runtime
    ├── Creates WebView
    ├── Loads frontend (from overlay)
    ├── Starts Python backend process
    │       └── Runs as API server (JSON-RPC over stdin/stdout)
    └── Event loop (Rust main thread)

Key differences from development mode:

• Rust is the main process (not Python)
• Python runs as a subprocess
• Communication via JSON-RPC over stdin/stdout
• Better process isolation and error handling

Plugin Architecture

AuroraView includes built-in Rust plugins:

Plugin	Description
Process	Run external processes with streaming output
File System	Native file operations
Dialog	Native file/folder dialogs
Shell	Execute commands, open URLs
Clipboard	System clipboard access

Thread Safety

Native Backend

• WebView and EventLoop are not Send on Windows
• Designed for single-thread usage (UI thread)
• Message queue provides thread-safe communication

DCC Integration Mode

• WebView created on DCC's main UI thread
• No separate event loop (no threading issues)
• Message processing handled by internal EventTimer
• Thread-safe message queue for cross-thread communication

Performance Characteristics

Memory Footprint

Component	Memory Usage
Rust Core	~5 MB
System WebView	~20-30 MB
Total	~30 MB

Compare to:

• Electron: ~150 MB
• Qt WebEngine: ~100 MB

Startup Time

• Cold start: ~300ms
• Warm start: ~100ms

Contributing

When adding a new backend:

1. Create src/webview/backend/your_backend.rs
2. Implement the WebViewBackend trait
3. Add Python wrapper in python/auroraview/your_backend.py
4. Export from __init__.py
5. Update documentation
6. Add tests

See backend/native.rs for reference implementation.