feat: Add WebAssembly browser port + fix Ctrl+Alt+F8 fast mode on all platforms

[anomixer]

feat: Add WebAssembly browser port + fix Ctrl+Alt+F8 fast mode on all platforms

Hi @samkusin,

I've been working on a WebAssembly/Emscripten port of Clemens IIGS that lets the emulator run directly in a browser — no installation needed. Along the way, I also found and fixed the Ctrl+Alt+F8 Fast Mode shortcut, which was broken on all platforms (not just web).

WASM Demo here: https://anomixer.github.io/clemens_iigs/

---

What's included

🌐 WebAssembly / Emscripten Browser Port

• Implemented clem_host_platform_select_disk and clemens_host_import_disk to support disk image loading from the browser.
• Used EM_JS to embed a JavaScript file picker that reads a user-selected disk image into Emscripten's MEMFS and passes it back to C++ via Module.ccall.
• Implemented clemens_emscripten_mount_disk (exported via EMSCRIPTEN_KEEPALIVE) to receive the file path from JS and mount it in the emulator.
• Fixed startup crashes by making get_local_user_directory return a valid VFS path (/home/web_user).
• Updated host/CMakeLists.txt to export ccall and UTF8ToString runtime methods, preventing runtime aborts when JS calls into C++.
• Modified clem_front.cpp to conditionally trigger disk selection via the platform API when disk icons are clicked in Emscripten builds.
• Added build_emscripten.bat — a one-step build script that automatically downloads the Emscripten SDK and Ninja, then compiles the project.

⌨️ Ctrl+Alt+F8 Fast Mode Fix (affects all platforms)

The original code in clem_front.cpp hard-codes ImGuiKey_LeftAlt:

if (ImGui::IsKeyDown(ImGuiKey_LeftAlt)) {
    if (ImGui::IsKeyDown(ImGuiKey_LeftCtrl) || ...) {
        // Fast Mode, Pause, etc.
    }
}

This means Right Alt + Ctrl + F8 does nothing on Windows, Linux, and macOS — and on the web, even Left Alt detection is unreliable due to how Sokol maps modifier keys.

The fix replaces these with ImGui::GetIO().KeyAlt and ImGui::GetIO().KeyCtrl, which correctly detect either Left or Right modifier keys on all platforms. I also removed the alternative number key bindings (8, 5, 0, -) to avoid conflicts with emulated Apple IIGS software.

Final shortcut layout:

Shortcut	Action
Ctrl + Alt + F8	Toggle Fast Mode
F5	Pause / Resume
F10	Mouse Lock
F11	Debugger
Ctrl + LAlt + RAlt + F1	IIGS Control Panel (web only)

---

Files Changed

File	Description
host/clem_front.cpp	Shortcut fix + Emscripten disk selection
host/clem_front.hpp	Platform abstraction declarations
host/clem_host.hpp	Host interface updates
host/clem_host_app.cpp	Key mapping for IIGS Control Panel (web)
host/clem_host_platform.h	Platform API definition
host/platform/host_emscripten.c	Full Emscripten implementation
host/CMakeLists.txt	Build export flags
host/resources/emscripten_shell.html	Cleanup
build_emscripten.bat	New automated build script
README.md	Updated build instructions
.gitignore	Updated

---

How to Test

Web version:

1. Run .\build_emscripten.bat (Emscripten SDK downloaded automatically)
2. Run .\run_emscripten.bat
3. Open http://localhost:6931/clemens_iigs.html
4. Test disk mounting via the disk icons in the UI
5. Verify Ctrl+Alt+F8 toggles Fast Mode correctly

Desktop version:

• Verify Ctrl+Alt+F8 now works with both Left and Right Alt/Ctrl keys

---

Note: Disk images loaded in the browser are written to Emscripten's in-memory filesystem (MEMFS) and are temporary — lost on page reload. This is expected behaviour.

[samkusin]

Seeing Clemens on the browser looks great.

NOTE: I understand this was developed with AI based on the included Agent.md plus some other markers. It would be good to know to what extent this is agent-driven vs human encouraged with assistance from Claude/Gemini/etc. I'm not wholly against AI assisted PRs if they are beneficial to the project (Emscripten support is an example.)

There are a few issues with the PR though that I'll have to resolve before merging:

• It removes the existing workflows for building the other platforms (though this may have been done to avoid triggering the workflows on your environment.)
• The inclusion of the IIgs ROM - I'm not sure this is allowed though its unlikely given the hardware's age and the emulator's reach to matter. I'm wondering if the ROM needs to be in github and instead supplied by the user during the build.

[anomixer]

Seeing Clemens on the browser looks great.

NOTE: I understand this was developed with AI based on the included Agent.md plus some other markers. It would be good to know to what extent this is agent-driven vs human encouraged with assistance from Claude/Gemini/etc. I'm not wholly against AI assisted PRs if they are beneficial to the project (Emscripten support is an example.)

There are a few issues with the PR though that I'll have to resolve before merging:

• It removes the existing workflows for building the other platforms (though this may have been done to avoid triggering the workflows on your environment.)
• The inclusion of the IIgs ROM - I'm not sure this is allowed though its unlikely given the hardware's age and the emulator's reach to matter. I'm wondering if the ROM needs to be in github and instead supplied by the user during the build.

Hi Sam, thanks for the detailed feedback and for taking time to review!
Here's a summary of what I've addressed:

---

1. AI Usage Transparency

This PR was developed with substantial AI assistance (Antigravity / Gemini Pro + Claude),
acting as a "super-IDE" pair programmer. The overall direction, architecture decisions, and
testing were human-guided — I specified what to build and validated the results at each step.
The AI handled boilerplate, C/JS interop details, and iterative bug-fixing. I think this is
roughly equivalent to "heavy use of GitHub Copilot + Stack Overflow", just more interactive.
I'm happy to be transparent about this in the Agent.md file (already included), which
documents what was built and how.

---

2. Restored Original CI Workflows

The existing build-linux.yml, build-macos.yml, and build-windows.yml workflows have
been fully restored to match your upstream versions exactly. The new Emscripten
deployment lives in a separate deploy-emscripten.yml and does not interfere with your
existing CI pipelines.

---

3. ROM Copyright — Now Fully Runtime-Loaded

The rom/rom.v3 file has been removed from the repository entirely (git rm --cached),
and rom/ is now in .gitignore.
Instead, the ROM is loaded at runtime in the browser, with no build-time dependency:

• On first visit, a full-screen dialog prompts the user to select their own rom.v3 from
  their local machine. The file is validated (must be exactly 262,144 bytes / 256 KB).
• The ROM is then written to Emscripten's in-memory filesystem (MEMFS) and simultaneously
  saved to the browser's IndexedDB for persistence.
• On all subsequent visits the ROM loads silently from IndexedDB — the user never has to
  select it again.
• The CI/CD build (deploy-emscripten.yml) requires no ROM file and no secrets at
  build time.
  The live demo is at: https://anomixer.github.io/clemens_iigs/

---

Now the merge is ok to go!
Let me know if there's anything else you'd like me to change before merging.

Thanks again!

[anomixer]

One more note on the CI checks — all workflows on your end are showing
"Action required" status. This is GitHub's security gate for first-time
contributor PRs; no actual build errors.

To run them, go to your Actions tab
and click "Approve and run" on the pending workflow runs (Linux All Build,
Windows All Build, Deploy Emscripten).

Once approved they should all pass. 🙂