aego/docs/web-capabilities.md

Web capabilities

What the browser build (GOOS=js GOARCH=wasm, platform/web + gpu/webgl2) supports compared with the native build. Decisions: D289, D290.

Platform

Feature	Web	Notes
Window	works	one canvas; size from CSS, pixels from devicePixelRatio
Resize, DPI change	works	ResizeObserver, resize, DPR check every frame
Keyboard	works	code → scancode; browser shortcuts (Ctrl/Cmd, F5, F11, F12) stay with the browser
Text input	degraded	single characters only, no IME composition
Mouse	works	pointer capture while a button is held
Wheel	works	100 px = one line; trackpads are precise
Pointer lock	degraded	granted on the next click or key press after the request
Touch	degraded	primary pointer as the left button; multi-touch in Stage 18
Gamepads	works	standard mapping; Chrome reports a pad only after a button press
Focus loss	works	held keys and buttons are released
Hidden tab	works	the platform clock excludes hidden time. Any background animation callback leaves the simulation paused. The first visible frame rebases the live clock and delivers queued input. Explicit fixed timelines retain their configured step
Frame pacing	works	VSync; the frame limit skips animation frames
Fullscreen	degraded	entered on the next click or key press
Display modes, monitors	missing	the display module has no modes to apply; the pixel ratio is capped at 1.5 by default (display.maxPixelRatio)
Clipboard write	works	navigator.clipboard.writeText (secure contexts)
Clipboard read	degraded	only what was pasted into the page or copied by the game
Cursors	works	CSS cursor names
Drag and drop of files	missing
Player profile, saves	works	localStorage, limited to a few MB; a full store reports a write error
Files outside the bundle	missing	no OS file system

GPU

Feature	Web	Notes
Buffers, instancing	works
Textures RGBA8, SRGB8_ALPHA8, R8	works
RGBA16F	degraded	EXT_color_buffer_float plus actual framebuffer/blend/readback probe; no requirement for 32-bit EXT_float_blend; honest LDR fallback
2D array textures	works	layer/mip allocation, update, framebuffer attachment and restore; shared shadow/cookie bindings
Depth24/stencil8 targets	works
sRGB output	works	offscreen backbuffer plus an encoding pass
Samplers, mipmaps	works
Scissor, viewport, blend, cull	works
ReadPixels	works	resolved RGBA8 targets keep the screenshot contract; RGBA16F diagnostics use RGBA/FLOAT
GPU timer	degraded	needs EXT_disjoint_timer_query_webgl2; unavailable/disjoint/context-canceled intervals are invalid, not zero GPU time
Debug output, object labels	missing	Options.Debug checks getError after creation calls
Context loss	works	objects are recreated from CPU copies; textures cost twice the memory
Shaders	works	GLSL ES 3.00 copies generated by make shaders

Audio

Feature	Web	Notes
Output	works	AudioWorklet at the context's rate: 48 kHz is asked, Safari may give 44.1 kHz and the mixer runs at what it gets
Start	degraded	silent until the first click, key or touch on the page; a page started by a click (the docs Try it) plays at once; audio written before that is dropped
Mute	works	web exports show a mute button; the choice is kept in localStorage for the site
Hidden tab	works	the context is suspended and resumed
Transport	works	a SharedArrayBuffer ring when the page is cross-origin isolated (COOP same-origin and COEP require-corp), otherwise blocks posted to the worklet
Latency	degraded	minimum targets of 3 blocks with SharedArrayBuffer and 6 with messages; at 48 kHz/512 frames these are ~32 and ~64 ms, plus the browser's output buffer. Reported device latency or long frames can raise the target
Device events	missing	the browser follows the default output device itself

Exported games

aego export --target web (D295) runs the same runtime as the desktop export on this platform and GPU backend. Differences from desktop: data is loaded into memory before the game starts, there are no log files or crash bundles, saves and settings share the site's localStorage quota.

Performance

make web-bench (D365) runs the exported platformer with its input recording in Chromium and Firefox: 1280×720, device pixel ratio 1, render scale 1, seed 1, 120 warmup frames, 600 measured, 5 runs. While it measures, every frame advances the game by exactly one fixed step, so each run plays the same frames. It writes .cache/web-bench.json and a table in .cache/web-bench.md.

Level	Metrics
Go	allocations and bytes per frame, bytes allocated inside the engine frame, allocations per engine zone (phases, gpu, poll), GC cycles, heap
Bridge	WebGL calls, timer query calls counted apart, draw calls, buffer and texture uploads and their size, program and render-target switches, time spent in WebGL calls
Browser	frame time p50/p95/p99 from requestAnimationFrame gaps, main-thread work per frame, frames over 33 ms, long tasks, JS heap, GPU time

Options: WEB_BENCH_BROWSERS=chromium, WEB_BENCH_ARGS="--gpu=hard --headed" for the real GPU, --gogc=100,150,200 for GC experiments, --trace for a Chrome trace of the first run. make web-bench-baseline saves the machine's baseline, one per GPU mode. Later runs fail when a count (draw calls, WebGL calls, uploads, switches per frame) differs from the baseline or between runs, when Go allocates more than 24 bytes per frame over the baseline inside the engine frame, or when frame or work time is more than 10% slower; time is compared only with at least 5 runs. make web-smoke runs Chromium once and checks the counts, not the time. On the reference machine with --gpu=hard frame p95 must stay at or under 20 ms with at most 1% of frames over 33 ms.

make ci compares its Chromium/SwiftShader run with the versioned Stage 12 baseline in tools/websmoke/bench-stage12-baseline.json. A missing, incomplete or incompatible baseline, disabled allocation profile, wrong actual renderer, or attempt to update the baseline while gating is a failure. Direct make web-bench and make web-smoke keep using .cache/web-bench.base.json by default; CI does not replace that local file.

The engine-frame probe uses runtime.ReadMemStats at each end of a frame: runtime/metrics can publish small allocations in a later frame when an allocator cache is flushed. The frame count now includes tiny allocations, unlike the per-zone runtime/metrics counts. These stop-the-world reads happen only while the probe is enabled, and benchmark timings include their overhead; do not compare frame-byte values or timing baselines made with the older probe as if the method were unchanged. The separate stack-profile allocation gate and its exemptions remain in force.

Historical Stage 12w measurements on the reference machine, hardware GPU, 1280×720, device pixel ratio 1, 600 measured frames. These values do not measure Stage 12b lighting or its updated platformer:

	Chromium before 12w	Chromium after	Firefox before 12w	Firefox after
frame p95, ms	16.7	16.8	17.2	17.2
frames over 33 ms	0	0	0	0
Go allocations per frame (runtime/metrics)	7.2	3.8	6.1	2.5
allocations in the engine frame, not exempt	—	0	—	0
GC cycles in 3600 frames	0	0	—	—
WebGL calls per frame	50.5	50.5	50.5	50.5
draw calls per frame	3.3	3.3	3.3	3.3