🦊 Platform Proxies

Vulfram runs in multiple environments (desktop and browser) without changing its public API. Platform proxies isolate the OS/browser details so the ABI stays stable for hosts.

1. Why Proxies Exist

The host always talks to the same functions:

vulfram_send_queue
vulfram_receive_queue
vulfram_receive_events
vulfram_tick

Platform proxies handle the environment-specific pieces:

Window creation and lifecycle
Input plumbing (keyboard, pointer, touch, gamepad)
Event loop pumping
Surface creation and resize

This lets the core stay portable while adding new platforms later.

2. Desktop Proxy (Native)

Location: src/core/platforms/desktop/

Responsibilities:

Own the winit event loop
Create OS windows and surfaces
Translate native input to engine events
Use gilrs for gamepad input
Request redraws during vulfram_tick

Used when building for native targets (default).

3. Browser Proxy (WASM)

Location: src/core/platforms/browser/

Responsibilities:

Bind to a DOM canvas (canvasId)
Attach DOM event listeners
Poll Web Gamepad API each tick
Render directly during vulfram_tick

Used when compiled with the wasm feature.

4. Selection Rules

Desktop builds (ffi, napi, lua, python) → Desktop proxy
WASM builds (--features wasm) → Browser proxy

The selection is compile-time, but the ABI does not change.

5. Adding New Platforms

To extend Vulfram:

Implement a new proxy alongside desktop/browser.
Wire it into the platform selector in src/core/platforms/mod.rs.
Keep the ABI untouched; only the internal proxy changes.

Possible future targets:

Mobile (iOS/Android)
Console SDKs
Headless/server rendering