Enhancing WebAssembly Gallery Experiences: Embedding Multiple Emscripten Builds with Modals on Astro and Cloudflare Pages

Introduction

Creating an engaging and seamless platform for showcasing WebAssembly (WASM) demos can significantly enhance user interaction and retention. Inspired by platforms like itch.io, this approach involves integrating multiple Emscripten-compiled demos into a single site, presented elegantly through modal dialogs. Achieving this requires careful handling of browser security headers, resource management, and clean session behaviors, especially when deploying over static hosts such as Cloudflare Pages.

In this article, we explore a robust methodology for embedding several Emscripten WASM demos within a modern static site built with Astro, emphasizing best practices for cross-origin policies, asset loading, and teardown strategies to ensure a smooth, leak-free experience.

Scope and Objectives

The goal was to develop a user-friendly gallery of playable WebAssembly demos, each launched within a modal overlay. Key requirements included:

• Multiple Emscripten-based demos on a singular page
• Each demo launches in a fresh canvas context
• Proper handling of security headers for features like SharedArrayBuffer
• Reliable asset resolution despite build processes
• Efficient cleanup between demo sessions without confusing Emscripten’s internal state

Challenges Encountered

1. Asset Path Resolution:
   Placing WASM, JS, and data files inside the source directory caused issues since build tools like Vite interactively hash and relocate assets, making runtime references invalid. Moving static assets to the public directory ensured stable, predictable paths accessible at runtime.

2. Enabling Threads:
   SharedArrayBuffer support necessitated strict cross-origin headers (Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy) both during development and in production. Without these headers, multi-threaded features failed to initialize.

3. Canvas State Management:
   Reusing a single <canvas> element across different demos led to conflicts within Emscripten, which maintains internal state. Creating a new <canvas> element for each demo launch solved this, providing a clean environment each time.

Effective Strategies

Asset Management
– Keep build artifacts inside public/demos/<slug>/ to prevent bundler interference.
– Implement resolvers that attempt to load assets based on expected naming conventions (<slug>.wasm, <slug>.js, etc.), with fallback options to handle version differences.

Header Configuration
– During development (Vite middleware):

“`js