FooGolf in the browser (Emscripten) - feasibility assessment

Date: 2026-09-19. Status: assessment complete, decisions taken, Stage 1 (HAL + build skeleton) started the same day. Numbers come from a read-only survey of foodoublebassesp32, esp32-device-core and foogolf-ota-cloud as of fw 0.8.590 / lib v0.2.31.

The ask

Run the device firmware - the LVGL UI, the games and drills, the Lua extensions and online play - in a browser as a WebAssembly build of the same C++ code, so browser players can join multiplayer rounds with hardware devices and with each other. Out of the web build by decision: ADC capture and every shot-generating path, OTA, BLE / Garmin R10, calibration, waveforms.

Verdict

Feasible, and not a rewrite. The UI and game layers are already portable in all but a handful of files; the platform surface is concentrated in three large files and a dozen network modules. A medium project in three stages: Stage 1 (single-player browser build with the real menus, drills, games, extensions, audio and persistence) is low-risk; Stage 2 (multiplayer through the existing cloud) needs small, already-modelled cloud changes plus one task rewrite; Stage 3 is polish plus the things a browser structurally cannot do, which stay out.

What is in our favour (measured)

The hard parts

1. The three god files. App.cpp (4 926 lines: 81 WiFi refs, 29 Preferences, 30 watchdog calls; App::tick is a while(true) that never returns and calls scanner.scan(), which blocks up to 6 s and ticks the UI from inside), UIController.cpp (6 154 lines, 55 WiFi refs, OTA install, NVS erase), Menu.cpp (4 995 lines, 52 WiFi refs, calibration / Dev / WiFi / R10 / camera menus). include/App.h (1 091 lines) holds hardware members (SpiDeviceADC, ADCAccessor, TFT_eSPI) that every game reaches for App::currentImpactRatio() and friends. The web build needs a FOOGOLF_WEB cut through these: no scan branch, no boot phase machine (highlights, OTA decision, audio-pack gate), the excluded menus compiled out. This is the largest single piece of work and must not disturb the firmware's scan-loop isolation.
2. Threads. Eight FreeRTOS tasks (simshare, cast, analytics, lm, luapf, net, wifi, xtrContInit) plus main-loop blocking waits (joinBlocking, mintCodeBlocking, five delay(5); continue; hold loops). Only simshare and luapf matter for the web.
3. Storage. 36 open-coded Preferences sites in one namespace, direct LittleFS calls in five modules (/lfs/players.bin, putt_*.bin, trend_*.bin, clips.bin, /lfs/extensions/). Shim: a Preferences class and a File class over Emscripten's IDBFS. Mechanical.
4. Audio. Replace writeI2SChunk with a PCM push into a Web Audio ring (AudioWorklet). drain() from the loop stays. The audio pack ships with the web build as a preloaded asset (the web build is always current, so the signed download path is not needed).
5. Shot injection is a product decision, not a porting problem. The narrowest door is Game::forward(SensorMessage) + Game::onShot(mps, face). The six existing remote-putt paths (StrokePlayGame::remotePutt/replayShot, MiniGolfGame::..., LuaGame::...) show the minimum shot is {mps, face, aoa, ratio}; the drills also read rotation rate and the two path/lie proportions. GSProIntegration::sendSynthesizedShot already fabricates a bare SensorMessage and calls forward().

Cloud changes needed for multiplayer (small, all modelled already)

• CORS on the OTA HttpApi (template.yaml:170 is CorsConfiguration: false). Copy the block from dashboard/template.yaml:98-103 with AllowHeaders: [content-type, x-device-id, x-timestamp, x-signature] and the web app's origin. Add the same origin to the extension store's CORS list so GET /e/<CODE> and POST /e/check work from the page.
• A web identity. /register-device is open but requires a MAC and runs _purge_reprovisioned (deletes any row with the same MAC plus its shots and S3 waveforms). A browser must NEVER use it with a fabricated MAC. Add a kind: "web" registration (no MAC, no purge), keep the UUID + secret in the browser, mark the row so check_for_update never offers firmware and the Devices page can filter. The trust model equals hardware's: a device's secret sits in NVS.
• Time. Signing refuses without SNTP; the browser clock is the shim.
• Nothing in sim_share needs to change.

What the browser build deliberately will not do

Decisions (user, 2026-09-19)

• Putt source: typed or slider values. A panel in the page chrome with club speed, face angle, attack angle, rotation rate, path/lie proportions and the player's impact ratio, building a bare SensorMessage (the sendSynthesizedShot pattern) into a trimmed beginShot (no host frame, no uploader, no scanner). Recorded-shot replay, a pace mechanic and a scatter generator are NOT in the first version.
• Roles: online play host AND guest through /sim/*, with hardware devices and other browsers. Sim-sharing guest is not asked for in v1.
• GSPro on the same PC as the browser: through a local bridge, never directly. A browser cannot open TCP to localhost:921 either. The route is a small helper program run beside GSPro that exposes ws://localhost:<port> and forwards newline-JSON to port 921 (browsers allow an https page to connect to ws://localhost). GSProIntegration's WiFiClient becomes a WebSocket-client shim in the web build. Second stage, after online play works.
• Threads: Emscripten pthreads with -sPROXY_TO_PTHREAD. The firmware's blocking style survives nearly 1:1 (a synchronous emscripten_fetch is allowed off the browser's main thread, vTaskDelay -> usleep, queues -> mutex + condvar) and RemoteKeys's atomics already fit a cross-thread key path. Cost: the hosting page carries COOP/COEP headers (one CloudFront response-headers policy) for SharedArrayBuffer, which also means the page cannot embed third-party iframes. Fallback if it bites: single-threaded Asyncify / JSPI with the task loops rewritten as fetch callbacks.

Staged path

1. HAL + build skeleton. A wasm/ build in the firmware repo driven by a Python script calling em++ (the repo already builds its native tests that way), a FOOGOLF_WEB define, one shim directory (Arduino.h, Preferences, LittleFS/File, millis/delay, esp_random, heap_caps, FreeRTOS -> pthreads, WiFi.status() -> connected). test/native_stubs/ is the seed. Get esp32-device-core/ui + LVGL + the pure modules linking first.
2. Cut the god files. FOOGOLF_WEB through App.h/App.cpp, UIController.cpp, Menu.cpp: a web tick that runs _ui.tick, the game tick, GuestMode::tick, serviceSimShareHost and skips scan / boot gate / OTA / BLE; excluded menus removed from the tables.
3. Display, keys, audio, storage. Flush -> shadow -> canvas; keypad -> RemoteKeys; writeI2SChunk -> Web Audio; IDBFS. Reuse cast-viewer.html as the page.
4. Putt panel feeding the trimmed beginShot.
5. Networking. HTTPClient / WiFiClient shim over emscripten_fetch; SimShare's rawPost long poll becomes a fetch; cloud CORS + web registration deployed review-first.
6. CI. The web build runs on every release beside the native tests so it cannot rot - and it is the browser simulator for extension authors that docs/lua/developer-guide.md promises.

Verification (when built)

• A native SDL build of the same HAL for debugging, then the Emscripten build in a local static server with COOP/COEP headers.
• Walk every grid row; play each drill and game from the putt panel; install CFZW5 from the store.
• Two browser tabs + one hardware device in one Course play round and one Mini golf round.
• Reload the page: players, trends, settings and extensions persist.