wasm_rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e88c3bdb062ebc82a44f218f48d8e93614dda54d89a584f873a0715dbd130f82
+  data.tar.gz: 103d7130d41648dcee8e9a527ec02fe8aab8f7e281a7b52ef194c6a4c33b86b8
+SHA512:
+  metadata.gz: ddc70640c5a8b8dc0ec733b0f89b8b2cd507bdd27ab187336b8cea2169f9828d7aa243ba93494896a1f9660b30e1c68d331d306691dde73809523316a76a6896
+  data.tar.gz: 678917372a8eb43a1dfde066ed849d5597f26607f5637275f244c1f162cab4282b19be6e08620f17112d6092402ecf1e5ab80e475b3b29fbb4fe8998a7cd38d0

data/MIT-LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2026 Emerson Argueta
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# wasm_rails
+
+Run Rails apps entirely in the browser via WebAssembly.
+
+The entire Rails runtime — ActiveRecord, ActionController, ActionView — executes inside a Service Worker. SQLite is persisted to OPFS (with IndexedDB fallback). No server required after first load.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "wasm_rails"
+```
+
+Run the installer:
+
+```bash
+bundle install
+rails g wasm_rails:install
+npm install
+```
+
+## What the generator installs
+
+| File | Purpose |
+|------|---------|
+| `app/javascript/wasm/service_worker.js` | Boots Rails in SW, handles SQLite, intercepts fetches, export/import DB |
+| `app/javascript/wasm/boot.js` | Page-side SW registration and progress display |
+| `bin/build_app_bundle.mjs` | Bundles Ruby source + gems → `public/wasm/app_bundle.json` |
+| `bin/esbuild_wasm.mjs` | esbuild config for WASM JS entry points |
+| `bin/serve_wasm.mjs` | Local dev server with COOP/COEP headers |
+| `lib/active_record/connection_adapters/wasm_sqlite3_adapter.rb` | AR adapter bridging Ruby to JS sqlite |
+| `wasm_stubs/` | Stubs for C extensions unavailable in WASM |
+| `public/wasm_shell.html` | Entry point HTML — registers SW, shows boot progress |
+
+## `config/application.rb` setup
+
+After installing, add these requires at the top of `config/application.rb`, **before** `Bundler.require`:
+
+```ruby
+require "wasm_rails"
+require "turbo-rails"
+require "stimulus-rails"
+# Add any other gems that need explicit requires for Propshaft asset discovery:
+# require "chartkick"
+# require "groupdate"
+```
+
+Also add the WASM SQLite adapter inside your `Application` class:
+
+```ruby
+module YourApp
+  class Application < Rails::Application
+    require_relative "../../lib/active_record/connection_adapters/wasm_sqlite3_adapter" if RUBY_PLATFORM == "wasm32-wasi"
+  end
+end
+```
+
+## `config/boot.rb` setup
+
+Wrap Bundler setup so it's skipped inside the Service Worker:
+
+```ruby
+unless RUBY_PLATFORM == "wasm32-wasi"
+  ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+  require "bundler/setup"
+end
+```
+
+## `config/initializers/assets.rb` setup
+
+Add `app/javascript` to Propshaft's asset paths so `application.js` and controller files are found:
+
+```ruby
+Rails.application.config.assets.paths << Rails.root.join("app/javascript")
+```
+
+## Gems with `app/` directories
+
+Some gems (like `turbo-rails`) ship controllers, helpers, and views in their `app/` directory. Zeitwerk normally autoloads these, but WASM has no lazy autoloading from gem `app/` dirs. The `wasm_rails` Railtie handles `turbo-rails` automatically.
+
+For other gems that use `app/` dirs, add them to `GEM_EXTRA_PATHS` in `bin/build_app_bundle.mjs`:
+
+```js
+const GEM_EXTRA_PATHS = {
+  'turbo-rails': ['app/controllers', 'app/controllers/concerns', 'app/helpers', 'app/models', 'app/models/concerns', 'app/views'],
+  'your-gem':    ['app/helpers'],
+};
+```
+
+## Usage
+
+### Build
+
+```bash
+# Precompile Rails assets (Propshaft reads the manifest at runtime)
+SECRET_KEY_BASE=dummy RAILS_ENV=production bin/rails assets:precompile
+
+# Bundle Ruby source + gems (~39MB)
+npm run build:app
+
+# Bundle service worker JS
+npm run build:wasm
+```
+
+### Serve locally
+
+```bash
+node bin/serve_wasm.mjs   # http://localhost:3100
+```
+
+Requires Chrome or Edge — Firefox/Safari lack full OPFS SAH Pool + module Service Worker support.
+
+### Deploy
+
+`ruby+stdlib.wasm` (~34MB) and `app_bundle.json` (~39MB) exceed Cloudflare Pages' 25MB file size limit. Upload them to R2 or any CDN. Deploy the rest to Cloudflare Pages or any static host.
+
+Set `WASM_BASE_URL` at build time to point to your CDN:
+
+```bash
+WASM_BASE_URL=https://your-cdn.example.com npm run build:wasm
+```
+
+The built JS files in `public/wasm/` (`service_worker.js`, `boot.js`, etc.) must be committed — they're served directly by the static host.
+
+## `WasmRails.wasm?`
+
+The gem provides a clean predicate you can use anywhere:
+
+```ruby
+WasmRails.wasm?  # => true when running inside ruby.wasm
+```
+
+## How it works
+
+1. `wasm_shell.html` is served statically and registers the Service Worker
+2. The SW downloads `ruby+stdlib.wasm` (~34MB, cached after first load)
+3. The SW downloads `app_bundle.json` (all gem + app `.rb` files, base64-encoded)
+4. Ruby boots, Rails initializes, SQLite opens (OPFS SAH Pool or IndexedDB fallback)
+5. On first boot: runs `db/schema.rb`. On subsequent boots: runs pending migrations
+6. Every page request is intercepted by the SW, dispatched to the Rails Rack app, returned as HTML
+
+## C extension stubs
+
+Native gems that can't run in WASM are stubbed in `wasm_stubs/`:
+
+- `sqlite3` → replaced by the JS sqlite4rails interface
+- `openssl`, `nokogiri`, `loofah`, `rails-html-sanitizer` → empty stubs
+- `resolv`, `socket`, `io/wait`, `io/console/size` → empty stubs
+- `thread` → mapped to `Fiber` (WASM is single-threaded)
+
+## Requirements
+
+- Ruby 3.3+
+- Rails 7.1+
+- Node.js 20+
+- Chrome or Edge (for OPFS SAH Pool)

data/lib/generators/wasm_rails/install/install_generator.rb

@@ -0,0 +1,109 @@
+require "rails/generators"
+require "json"
+
+module WasmRails
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Sets up a Rails app to run as a WASM app in the browser."
+
+      def copy_wasm_adapter
+        copy_file "wasm_sqlite3_adapter.rb",
+                  "lib/active_record/connection_adapters/wasm_sqlite3_adapter.rb"
+      end
+
+      def copy_wasm_stubs
+        stubs_src = File.expand_path("../../../../../wasm_stubs", __dir__)
+        Dir.glob("#{stubs_src}/**/*").each do |src|
+          next if File.directory?(src)
+          rel = Pathname.new(src).relative_path_from(Pathname.new(stubs_src))
+          copy_file src, "wasm_stubs/#{rel}"
+        end
+      end
+
+      def copy_js_files
+        copy_file "service_worker.js", "app/javascript/wasm/service_worker.js"
+        copy_file "boot.js",           "app/javascript/wasm/boot.js"
+      end
+
+      def copy_bin_scripts
+        copy_file "build_app_bundle.mjs", "bin/build_app_bundle.mjs"
+        copy_file "esbuild_wasm.mjs",     "bin/esbuild_wasm.mjs"
+        copy_file "serve_wasm.mjs",       "bin/serve_wasm.mjs"
+        chmod "bin/build_app_bundle.mjs", 0o755
+        chmod "bin/esbuild_wasm.mjs",     0o755
+        chmod "bin/serve_wasm.mjs",       0o755
+      end
+
+      def copy_public_files
+        copy_file "wasm_shell.html", "public/wasm_shell.html"
+      end
+
+      def patch_boot_rb
+        boot = "config/boot.rb"
+        return unless File.exist?(boot)
+        return if File.read(boot).include?("wasm32-wasi")
+        gsub_file boot,
+          /^(ENV\["BUNDLE_GEMFILE"\].+\nrequire "bundler\/setup"\nrequire "bootsnap\/setup")$/m,
+          "unless RUBY_PLATFORM == \"wasm32-wasi\"\n  \\1\nend"
+      end
+
+      def patch_application_rb
+        application_rb = "config/application.rb"
+        return if File.read(application_rb).include?("wasm_sqlite3_adapter")
+        inject_into_class application_rb, "Application" do
+          <<~RUBY.indent(4)
+            if RUBY_PLATFORM == "wasm32-wasi"
+              require_relative "../../lib/active_record/connection_adapters/wasm_sqlite3_adapter"
+            end
+          RUBY
+        end
+      end
+
+      def patch_assets_initializer
+        initializer = "config/initializers/assets.rb"
+        create_file initializer unless File.exist?(initializer)
+        return if File.read(initializer).include?("app/javascript")
+        append_to_file initializer,
+          "\nRails.application.config.assets.paths << Rails.root.join(\"app/javascript\")\n"
+      end
+
+      def update_package_json
+        return unless File.exist?("package.json")
+        pkg = JSON.parse(File.read("package.json"))
+
+        (pkg["dependencies"] ||= {}).merge!(
+          "@ruby/3.3-wasm-wasi"     => "^3.3.0",
+          "@ruby/wasm-wasi"         => "^3.3.0",
+          "@sqlite.org/sqlite-wasm" => "^3.0.0",
+          "esbuild"                 => "^0.25.0"
+        ) { |_k, old, _new| old }
+
+        (pkg["scripts"] ||= {}).merge!(
+          "build:wasm" => "node bin/esbuild_wasm.mjs",
+          "watch:wasm" => "node bin/esbuild_wasm.mjs --watch",
+          "build:app"  => "node bin/build_app_bundle.mjs"
+        ) { |_k, old, _new| old }
+
+        File.write("package.json", JSON.pretty_generate(pkg))
+        say_status :update, "package.json"
+      end
+
+      def show_post_install_message
+        say "\n"
+        say "  ✓ wasm_rails installed!", :green
+        say "\n"
+        say "  Next steps:"
+        say "    1. npm install"
+        say "    2. In config/application.rb, require these before Bundler.require:"
+        say "         require 'wasm_rails'"
+        say "         require 'turbo-rails'"
+        say "         require 'stimulus-rails'"
+        say "    3. npm run build:app && npm run build:wasm"
+        say "    4. node bin/serve_wasm.mjs  →  http://localhost:3100"
+        say "\n"
+      end
+    end
+  end
+end

data/lib/generators/wasm_rails/install/templates/boot.js

@@ -0,0 +1,31 @@
+// boot.js — Main thread glue.
+// Registers the Service Worker and relays progress messages to the shell page.
+
+export async function bootWasm() {
+  if (!('serviceWorker' in navigator)) {
+    throw new Error('Service Workers not supported in this browser.');
+  }
+
+  const reg = await navigator.serviceWorker.register('/wasm/service_worker.js', { scope: '/', type: 'module' });
+  console.log('[wasm/boot] Service Worker registered', reg.scope);
+
+  // If a SW is already active with no pending update, boot completed in a previous session.
+  if (reg.active && !reg.installing && !reg.waiting) {
+    console.log('[wasm/boot] SW already active');
+    return;
+  }
+
+  return new Promise((resolve, reject) => {
+    navigator.serviceWorker.addEventListener('message', function handler({ data }) {
+      if (data.type === 'progress') {
+        window.dispatchEvent(new CustomEvent('wasm-progress', { detail: data }));
+      } else if (data.type === 'ready') {
+        navigator.serviceWorker.removeEventListener('message', handler);
+        resolve();
+      } else if (data.type === 'error') {
+        navigator.serviceWorker.removeEventListener('message', handler);
+        reject(new Error(data.message));
+      }
+    });
+  });
+}

data/lib/generators/wasm_rails/install/templates/build_app_bundle.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// Bundles Ruby source files + gem lib files into public/wasm/app_bundle.json.
+// Also generates public/wasm/wasm_setup.rb which sets up $LOAD_PATH inside WASM.
+
+import { readdirSync, statSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { resolve, relative, extname, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+const outdir = resolve(root, 'public', 'wasm');
+
+mkdirSync(outdir, { recursive: true });
+
+// ── App source files ──────────────────────────────────────────────────────────
+
+const APP_DIRS = [
+  'app/models', 'app/controllers', 'app/helpers', 'app/views',
+  'app/mailers', 'app/jobs', 'app/services', 'config', 'db/migrate', 'lib',
+];
+const APP_FILES = [
+  'db/schema.rb', 'db/seeds.rb',
+  'public/assets/.manifest.json',
+];
+const EXCLUDE = [/node_modules/, /\.git/, /tmp\//, /log\//, /public\//, /storage\//, /\.DS_Store/];
+const SOURCE_EXTS = new Set(['.rb', '.erb', '.yml', '.yaml', '.json', '.ru']);
+
+function shouldExclude(p) { return EXCLUDE.some(r => r.test(p)); }
+
+function collectDir(dir, mountPath, bundle) {
+  const abs = resolve(root, dir);
+  try {
+    const walk = (cur) => {
+      if (shouldExclude(cur)) return;
+      const stat = statSync(cur);
+      if (stat.isDirectory()) {
+        readdirSync(cur).forEach(f => walk(resolve(cur, f)));
+      } else if (SOURCE_EXTS.has(extname(cur).toLowerCase())) {
+        const rel = mountPath + '/' + relative(abs, cur);
+        bundle[rel] = Buffer.from(readFileSync(cur)).toString('base64');
+      }
+    };
+    walk(abs);
+  } catch { /* skip missing dirs */ }
+}
+
+// ── Gem source files ──────────────────────────────────────────────────────────
+
+const NATIVE_GEMS = new Set([
+  'sqlite3', 'puma', 'bootsnap', 'nio4r', 'ffi', 'nokogiri',
+  'msgpack', 'bcrypt', 'ed25519', 'bcrypt_pbkdf', 'bindex',
+  'websocket-driver', 'websocket-extensions', 'image_processing',
+  'mini_magick', 'ruby-vips', 'selenium-webdriver', 'capybara',
+  'debug', 'web-console', 'kamal', 'thruster',
+  // loofah and rails-html-sanitizer depend on nokogiri — stub them instead
+  'loofah', 'rails-html-sanitizer', 'crass',
+  // dev/build tools
+  'rubocop', 'rubocop-rails-omakase', 'brakeman', 'bundler-audit',
+  'tailwindcss-rails', 'tailwindcss-ruby',
+]);
+
+// Extra non-lib paths to bundle for specific gems (e.g. Rails engines with app/ dirs)
+const GEM_EXTRA_PATHS = {
+  'turbo-rails': [
+    'app/controllers',
+    'app/controllers/concerns',
+    'app/helpers',
+    'app/models',
+    'app/models/concerns',
+    'app/views',
+  ],
+};
+
+const STDLIB_GEMS = new Set([
+  'json', 'psych', 'stringio', 'date', 'bigdecimal', 'racc',
+  'strscan', 'io-console', 'timeout', 'logger', 'ostruct',
+  'prism', 'rbs',
+  'bundler',
+]);
+
+function getGemSpecs() {
+  try {
+    const json = execSync(
+      'bundle exec ruby -e \'' +
+      'require "json"; ' +
+      'puts Gem.loaded_specs.values.map { |s| ' +
+      '  { name: s.name, version: s.version.to_s, gem_dir: s.gem_dir, ' +
+      '    require_paths: s.require_paths } ' +
+      '}.to_json\'',
+      { cwd: root, encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }
+    );
+    return JSON.parse(json);
+  } catch (e) {
+    console.warn('[build_app_bundle] Could not enumerate gems:', e.message);
+    return [];
+  }
+}
+
+function collectGems(bundle) {
+  const specs = getGemSpecs();
+  const loadPaths = [];
+  let gemFileCount = 0;
+
+  for (const spec of specs) {
+    if (NATIVE_GEMS.has(spec.name) || STDLIB_GEMS.has(spec.name)) continue;
+
+    const allPaths = [
+      ...spec.require_paths,
+      ...(GEM_EXTRA_PATHS[spec.name] || []),
+    ];
+
+    for (const rp of allPaths) {
+      const libDir = join(spec.gem_dir, rp);
+      const mountAt = `/gems/${spec.name}-${spec.version}/${rp}`;
+
+      try {
+        statSync(libDir);
+      } catch { continue; }
+
+      loadPaths.push(mountAt);
+
+      const walk = (cur) => {
+        try { statSync(cur); } catch { return; }
+        if (statSync(cur).isDirectory()) {
+          readdirSync(cur).forEach(f => walk(join(cur, f)));
+        } else if (['.rb', '.erb', '.yml', '.yaml'].includes(extname(cur))) {
+          const rel = mountAt + '/' + relative(libDir, cur);
+          bundle[rel] = Buffer.from(readFileSync(cur)).toString('base64');
+          gemFileCount++;
+        }
+      };
+      walk(libDir);
+    }
+  }
+
+  console.log(`[build_app_bundle] Bundled ${gemFileCount} gem .rb files from ${loadPaths.length} load paths`);
+  return loadPaths;
+}
+
+// ── Build ─────────────────────────────────────────────────────────────────────
+
+// 1. App source — mounted at /app/... in the WASM virtual FS
+const cleanBundle = {};
+for (const dir of APP_DIRS) {
+  const abs = resolve(root, dir);
+  try {
+    const walk = (cur) => {
+      if (shouldExclude(cur)) return;
+      if (statSync(cur).isDirectory()) {
+        readdirSync(cur).forEach(f => walk(resolve(cur, f)));
+      } else if (SOURCE_EXTS.has(extname(cur).toLowerCase())) {
+        const rel = '/app/' + relative(root, cur);
+        cleanBundle[rel] = Buffer.from(readFileSync(cur)).toString('base64');
+      }
+    };
+    walk(abs);
+  } catch { /* skip */ }
+}
+for (const file of APP_FILES) {
+  try {
+    const abs = resolve(root, file);
+    cleanBundle['/app/' + file] = Buffer.from(readFileSync(abs)).toString('base64');
+  } catch { /* skip */ }
+}
+
+// 2. WASM stubs — C extensions not available in ruby+stdlib.wasm
+const stubsDir = resolve(root, 'wasm_stubs');
+try {
+  const walkStubs = (cur) => {
+    if (statSync(cur).isDirectory()) {
+      readdirSync(cur).forEach(f => walkStubs(resolve(cur, f)));
+    } else if (extname(cur) === '.rb') {
+      cleanBundle['/stubs/' + relative(stubsDir, cur)] = Buffer.from(readFileSync(cur)).toString('base64');
+    }
+  };
+  walkStubs(stubsDir);
+  console.log(`[build_app_bundle] Bundled ${Object.keys(cleanBundle).filter(k => k.startsWith('/stubs/')).length} WASM stubs`);
+} catch { /* wasm_stubs dir missing — skip */ }
+
+// 3. Gem source files + collect load paths
+const gemLoadPaths = collectGems(cleanBundle);
+
+// 4. Generate wasm_setup.rb
+const setupRb = [
+  '# Auto-generated by bin/build_app_bundle.mjs — do not edit',
+  '$LOAD_PATH.unshift("/stubs")',
+  '$LOAD_PATH.unshift("/app")',
+  ...gemLoadPaths.map(p => `$LOAD_PATH.unshift("${p}")`),
+].join("\n") + "\n";
+
+writeFileSync(resolve(outdir, 'wasm_setup.rb'), setupRb);
+cleanBundle['/wasm_setup.rb'] = Buffer.from(setupRb).toString('base64');
+
+// 5. Write bundle
+const outPath = resolve(outdir, 'app_bundle.json');
+writeFileSync(outPath, JSON.stringify(cleanBundle));
+
+const count = Object.keys(cleanBundle).length;
+const size  = (Buffer.byteLength(JSON.stringify(cleanBundle)) / 1024 / 1024).toFixed(1);
+console.log(`[build_app_bundle] Total: ${count} files → ${size} MB → public/wasm/app_bundle.json`);

data/lib/generators/wasm_rails/install/templates/esbuild_wasm.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Bundles the WASM service worker and boot helper into public/wasm/.
+// Add your own app entry points to the entryPoints array below.
+
+import * as esbuild from 'esbuild';
+import { cpSync, mkdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, '..');
+const outdir = resolve(root, 'public', 'wasm');
+
+mkdirSync(outdir, { recursive: true });
+
+const watching = process.argv.includes('--watch');
+
+const ctx = await esbuild.context({
+  entryPoints: [
+    resolve(root, 'app/javascript/wasm/service_worker.js'),
+    resolve(root, 'app/javascript/wasm/boot.js'),
+    // Add your app-specific WASM entry points here:
+    // resolve(root, 'app/javascript/wasm/auth.js'),
+    // resolve(root, 'app/javascript/wasm/proxy_client.js'),
+  ],
+  bundle:    true,
+  format:    'esm',
+  splitting: false,
+  outdir,
+  sourcemap: true,
+  define: {
+    'process.env.NODE_ENV':  '"production"',
+    '__BUILD_ID__':          JSON.stringify(Date.now().toString()),
+    '__RUBY_WASM_URL__':     JSON.stringify(process.env.WASM_BASE_URL ? `${process.env.WASM_BASE_URL}/ruby+stdlib.wasm` : '/wasm/ruby+stdlib.wasm'),
+    '__APP_BUNDLE_URL__':    JSON.stringify(process.env.WASM_BASE_URL ? `${process.env.WASM_BASE_URL}/app_bundle.json` : '/wasm/app_bundle.json'),
+  },
+  loader: { '.wasm': 'file' },
+  assetNames: '[name]',
+});
+
+cpSync(
+  resolve(root, 'node_modules/@ruby/3.3-wasm-wasi/dist/ruby+stdlib.wasm'),
+  resolve(outdir, 'ruby+stdlib.wasm')
+);
+
+cpSync(
+  resolve(root, 'node_modules/@sqlite.org/sqlite-wasm/dist/sqlite3.wasm'),
+  resolve(outdir, 'sqlite3.wasm')
+);
+
+if (watching) {
+  await ctx.watch();
+  console.log('[esbuild_wasm] Watching…');
+} else {
+  await ctx.rebuild();
+  await ctx.dispose();
+  console.log('[esbuild_wasm] Built → public/wasm/');
+}

data/lib/generators/wasm_rails/install/templates/serve_wasm.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// Static file server for local WASM testing.
+// Sets the COOP/COEP headers required for SharedArrayBuffer (and therefore Atomics).
+
+import { createServer } from 'http';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { resolve, extname, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const PORT = process.env.PORT || 3100;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PUBLIC = resolve(__dirname, '../public');
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js':   'application/javascript',
+  '.mjs':  'application/javascript',
+  '.wasm': 'application/wasm',
+  '.json': 'application/json',
+  '.css':  'text/css',
+  '.png':  'image/png',
+  '.svg':  'image/svg+xml',
+  '.ico':  'image/x-icon',
+  '.txt':  'text/plain',
+  '.map':  'application/json',
+};
+
+const SAB_HEADERS = {
+  'Cross-Origin-Opener-Policy':   'same-origin',
+  'Cross-Origin-Embedder-Policy': 'credentialless',
+  'Cross-Origin-Resource-Policy': 'cross-origin',
+};
+
+const server = createServer((req, res) => {
+  const urlPath = req.url.split('?')[0];
+  let filePath = resolve(PUBLIC, '.' + urlPath);
+
+  if (urlPath === '/' || urlPath === '') {
+    filePath = resolve(PUBLIC, 'wasm_shell.html');
+  }
+
+  if (!existsSync(filePath) || statSync(filePath).isDirectory()) {
+    if (!extname(urlPath)) {
+      filePath = resolve(PUBLIC, 'wasm_shell.html');
+    }
+  }
+
+  if (!existsSync(filePath)) {
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end(`404 Not Found: ${urlPath}`);
+    return;
+  }
+
+  const ext = extname(filePath).toLowerCase();
+  const contentType = MIME[ext] || 'application/octet-stream';
+
+  Object.entries(SAB_HEADERS).forEach(([k, v]) => res.setHeader(k, v));
+  res.setHeader('Content-Type', contentType);
+  res.setHeader('Cache-Control', 'no-store');
+
+  if (urlPath === '/wasm/service_worker.js') {
+    res.setHeader('Service-Worker-Allowed', '/');
+  }
+
+  try {
+    const body = readFileSync(filePath);
+    res.writeHead(200);
+    res.end(body);
+  } catch (e) {
+    res.writeHead(500, { 'Content-Type': 'text/plain' });
+    res.end(e.message);
+  }
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log('');
+  console.log('  Budget Clear WASM test server');
+  console.log(`  http://localhost:${PORT}`);
+  console.log('');
+  console.log('  SharedArrayBuffer headers: ✓');
+  console.log('  Serving from: client/public/');
+  console.log('');
+  console.log('  Open http://localhost:3100 — first boot downloads ruby+stdlib.wasm (34MB)');
+  console.log('  Subsequent loads are instant (cached by Service Worker).');
+  console.log('');
+});