Fix WebAssembly play boot

[jonathanperis]

Summary

• start the normal WebAssembly build manually after runtime initialization, matching the debug boot path
• move GameState off the native/WASM stack and onto the heap to avoid Emscripten stack overflow / WASM memory traps
• keep standalone super-mango.html bootable when INVOKE_RUN=0 is used

Test Plan

• git diff --check
• make web
• bun run build in docs/
• make smoke
• bun run lint in docs/ (Astro check completed with generated-output hints only)
• local browser smoke: Normal Play renders active gameplay with no hitboxes/FPS and no JS errors
• local browser smoke: Debug Mode renders active gameplay with hitboxes/FPS and no JS errors

Summary by CodeRabbit

• Improvements
  • Enhanced web version initialization and startup timing for better reliability
  • Improved game state management during startup sequence
  • Refined loading status messaging for the web interface

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e8f1a88-61a2-4ad2-84ab-6ade29d99487

📥 Commits

Reviewing files that changed from the base of the PR and between 4ee808c and 227f4be.

📒 Files selected for processing (4)

• Makefile
• docs/src/components/home/Dashboard.astro
• src/main.c
• web/shell.html

---

📝 Walkthrough

Walkthrough

This PR defers game startup until after the Emscripten runtime fully initializes. The Makefile disables automatic entry invocation and exports callMain, the C code refactors gameplay startup into a reusable helper, and both web entry points (Dashboard and shell.html) defer calling Module.callMain() until onRuntimeInitialized fires.

Changes

Deferred Game Initialization

Layer / File(s)	Summary
Emscripten build configuration Makefile	The web target now passes -s INVOKE_RUN=0, -s EXPORTED_FUNCTIONS='["_main"]', and -s EXPORTED_RUNTIME_METHODS='["callMain"]' to emcc to export and defer the entry point.
Game execution abstraction and entry points src/main.c	New run_game() helper heap-allocates GameState, runs the init/loop/cleanup cycle, and frees state with proper failure handling. The --level direct-play and menu "Play" paths both replaced with run_game() calls and explicit subsystem teardown on failure.
Web runtime lifecycle integration docs/src/components/home/Dashboard.astro, web/shell.html	Both web entry points now defer Module.callMain() via setTimeout(..., 0) within onRuntimeInitialized instead of invoking immediately, aligning with the build configuration that prevents auto-invocation.

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Fix WebAssembly play boot' directly describes the main objective of the PR, which involves fixing the WebAssembly startup process by deferring Module.callMain invocation and refactoring GameState allocation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/wasm-play-boot

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}