Add WebGPU/WebAssembly build infrastructure and documentation

[Copilot]

Sets up complete build infrastructure for compiling GL Playground to WebAssembly with WebGPU support. Note: This PR provides build system only—actual OpenGL→WebGPU API porting is Phase 2 work (see ROADMAP.md).

Build Infrastructure

• GitHub Actions workflows: Automated WebAssembly builds with Emscripten 3.1.51, native Linux/Windows CI, artifact uploads, and GitHub Pages deployment
• Local build tooling: build_wasm.sh for local development, check_env.sh for environment validation
• Emscripten integration: CMake configuration using function pattern to avoid target initialization ordering issues
• Web deployment: Responsive HTML shell template with loading indicators and viewport-adaptive canvas

Configuration

# CMakeLists.txt - Emscripten integration after target creation
include(cmake/emscripten.cmake)
if(EMSCRIPTEN)
    configure_emscripten_target(app)
endif()

Emscripten flags: USE_GLFW=3, USE_WEBGPU=1, ALLOW_MEMORY_GROWTH=1, resource preloading via --preload-file.

Documentation

• AGENTS.md: Project architecture, tech stack, directory structure, migration strategy
• WEBGPU_BUILD.md: Build prerequisites, local testing, browser requirements, troubleshooting
• ROADMAP.md: 7-phase migration plan with timeline estimates and known challenges (geometry shaders, tessellation)
• QUICKSTART.md: Fast-track reference for developers

Current State

The codebase still uses OpenGL—shaders are GLSL, rendering uses glad/OpenGL ES. This infrastructure enables the actual WebGPU port work outlined in ROADMAP.md phases 2-7 (estimated 12-18 weeks).

Build artifacts will be available via GitHub Actions. Local build requires Emscripten SDK installation per WEBGPU_BUILD.md.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• gitlab.com
  • Triggering command: /usr/lib/git-core/git-remote-https /usr/lib/git-core/git-remote-https origin REDACTED (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>making it work with WebGPU / WebASM</issue_title>
<issue_description>Re-implement so it works on the web! WebGPU / WebASM</issue_description>

<agent_instructions>before doing anything, create a AGENTS.md file with basic explanation of the project and its layout. then, try to get a working build workflow script going.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes making it work with WebGPU / WebASM #1

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR establishes comprehensive WebAssembly build infrastructure for GL Playground, enabling compilation to run in browsers with WebGPU support. The implementation focuses on build tooling, CI/CD automation, and documentation, while the actual OpenGL-to-WebGPU API porting remains as planned future work (Phase 2-7 in ROADMAP.md).

Key changes:

• Complete build infrastructure: Local build scripts (build_wasm.sh, check_env.sh) and CMake integration (cmake/emscripten.cmake) for Emscripten-based WebAssembly compilation
• Automated CI/CD: GitHub Actions workflows for WebAssembly builds with artifact uploads and GitHub Pages deployment, plus native builds for Linux/Windows
• Comprehensive documentation: Five new documentation files covering project architecture (AGENTS.md), build instructions (WEBGPU_BUILD.md), migration roadmap (ROADMAP.md), and quick reference (QUICKSTART.md)

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
cmake/emscripten.cmake	Emscripten-specific CMake configuration with function-based target setup to avoid ordering issues
CMakeLists.txt	Integrates Emscripten configuration conditionally when building for WebAssembly
shell.html	Custom HTML template with responsive canvas, loading indicators, and error handling
build_wasm.sh	Local build automation script with environment checks and artifact preparation
check_env.sh	Development environment validation tool checking for required dependencies
.github/workflows/build-wasm.yml	CI/CD for WebAssembly builds with Emscripten 3.1.51 and GitHub Pages deployment
.github/workflows/build-native.yml	CI/CD for native Linux and Windows builds ensuring cross-platform compatibility
AGENTS.md	Project architecture documentation with tech stack, structure, and migration overview
WEBGPU_BUILD.md	Complete WebAssembly build guide with prerequisites, testing, and troubleshooting
ROADMAP.md	7-phase migration roadmap with timeline estimates and known technical challenges
QUICKSTART.md	Fast-track developer reference summarizing changes and next steps
PR_SUMMARY.md	Detailed PR summary (consider removing before merge - typically not tracked in repos)
README.md	Updated with WebAssembly build instructions and web testing guidance
.gitignore	Added WebAssembly build artifacts with broad wildcard patterns

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The wildcard copy cp build-wasm/app.* dist/ combined with error suppression (2>/dev/null || true) could silently fail if the expected build artifacts are missing or named differently than expected. This makes debugging build failures more difficult.

Consider being more explicit about which files are required vs. optional:

- name: Prepare artifacts
  run: |
    mkdir -p dist
    # Required files - fail if missing
    cp build-wasm/app.html dist/index.html
    cp build-wasm/app.js dist/
    cp build-wasm/app.wasm dist/
    # Optional files
    cp build-wasm/app.data dist/ 2>/dev/null || echo "No .data file (optional)"
    cp -r resources dist/ 2>/dev/null || echo "No resources directory (optional)"

This provides better visibility into what's actually being copied and what's optional.

Suggested change

	cp build-wasm/app.* dist/ 2>/dev/null || true
	cp -r resources dist/ 2>/dev/null || true
	# Required files - fail if missing
	cp build-wasm/app.html dist/index.html
	cp build-wasm/app.js dist/
	cp build-wasm/app.wasm dist/
	# Optional files
	cp build-wasm/app.data dist/ 2>/dev/null || echo "No .data file (optional)"
	cp -r resources dist/ 2>/dev/null || echo "No resources directory (optional)"

[Copilot]

[nitpick] Including a "PR_SUMMARY.md" file in the repository is unconventional. PR summaries are typically provided in the PR description or commit messages, not as tracked files in the repository. This file will become outdated and irrelevant once the PR is merged, but will remain in the repository history.

Consider:

1. Moving this content to the PR description
2. Removing this file before merging
3. If you need a summary of changes, consider updating the CHANGELOG.md or adding a "What's New" section to the main README.md instead

[Copilot]

The progressElement variable is declared but never used in the code. It's defined on line 114 but there are no subsequent references to it. Consider removing this unused variable to keep the code clean.

var progressElement = document.getElementById('progress'); // This line can be removed

Suggested change

var progressElement = document.getElementById('progress');

[Copilot]

Using innerHTML to set potentially user-controlled text (status messages) could introduce XSS vulnerabilities if the status text ever contains user input or external data. While the current implementation appears safe since status messages come from Emscripten's internal state, it's a best practice to use textContent instead of innerHTML when setting plain text.

Change:

statusElement.innerHTML = text;

To:

statusElement.textContent = text;

This ensures that any unexpected HTML characters in the status text are properly escaped.

Suggested change

	statusElement.innerHTML = text;
	statusElement.textContent = text;

[Copilot]

Using -sEXPORT_ALL=1 exports all functions from the WebAssembly module, which significantly increases the binary size and exposes internal implementation details. This flag is typically used for debugging or when the exact set of required exports is unknown.

For production builds, consider:

1. Explicitly listing required exports using -sEXPORTED_FUNCTIONS instead
2. Only exporting the main entry point and required callback functions
3. Using -sEXPORT_ALL=0 (the default) and specifying exports as needed

If EXPORT_ALL is intentional for development purposes, consider making it conditional based on build type:

if(CMAKE_BUILD_TYPE STREQUAL "Debug")
    -sEXPORT_ALL=1
endif()

Suggested change

	-sEXPORT_ALL=1
	"-sEXPORTED_RUNTIME_METHODS=[\"ccall\",\"cwrap\"]"
	--preload-file ${CMAKE_SOURCE_DIR}/resources@/resources
	--shell-file ${CMAKE_SOURCE_DIR}/shell.html
	)
	"-sEXPORTED_RUNTIME_METHODS=[\"ccall\",\"cwrap\"]"
	--preload-file ${CMAKE_SOURCE_DIR}/resources@/resources
	--shell-file ${CMAKE_SOURCE_DIR}/shell.html
	)
	# Only export all functions in Debug builds
	if(CMAKE_BUILD_TYPE STREQUAL "Debug")
	list(APPEND EMSCRIPTEN_LINK_FLAGS -sEXPORT_ALL=1)
	endif()