Unblock pampa wasm tests: feature-gate JS bridge, set wasm32 panic strategy

The raw_module extern blocks in quarto-system-runtime/src/wasm.rs import
absolute paths (/src/wasm-js-bridge/*.js) that hub-client serves through
Vite at runtime. wasm-bindgen generates unconditional require() calls
for these paths in the shim it produces, so any wasm32 binary that links
quarto-system-runtime — including the pampa wasm_lua tests — fails to
load under Node.js with MODULE_NOT_FOUND before any test body runs.

Add a js-bridge Cargo feature, default off. Gate the extern blocks
behind it, and provide stubs that return Err("js-bridge feature not
enabled") / false when off so the SystemRuntime impl still compiles.
wasm-quarto-hub-client opts in via features = ["js-bridge"]; pampa's
wasm test build does not, so the require()s disappear from the shim.
Native builds are unaffected (wasm.rs is #![cfg(target_arch = "wasm32")]).

That exposed a downstream panic-strategy problem: rust_lua_throw panics
propagated as wasm RuntimeError instead of being caught by
rust_lua_protected_call. Fix by mirroring wasm-quarto-hub-client's
rustflags (-C panic=unwind, +bulk-memory,+exception-handling,
-Zwasm-c-abi=spec) in the workspace-root .cargo/config.toml for wasm32
builds, and moving the LuaThrow marker type into wasm-c-shim so the
production build and the tests share it. Update design/plan docs and
dev-docs/wasm.md accordingly.

Author: gordonwoodhull

.cargo/config.toml

@@ -9,3 +9,14 @@ create-worktree = "xtask create-worktree"
 
 [target.wasm32-unknown-unknown]
 runner = "wasm-bindgen-test-runner"
+# Mirror the rustflags used by wasm-quarto-hub-client/.cargo/config.toml so any
+# wasm32 build invoked from the workspace root (e.g. the pampa wasm_lua test)
+# gets the same panic strategy and ABI. Without panic=unwind plus the
+# exception-handling target feature, wasm-c-shim's catch_unwind-based
+# replacement for Lua's setjmp/longjmp can't catch panics, and any Lua throw
+# during mlua initialization aborts the wasm module.
+rustflags = [
+    "-C", "target-feature=+bulk-memory,+exception-handling",
+    "-C", "panic=unwind",
+    "-Zwasm-c-abi=spec",
+]

claude-notes/designs/2026-04-03-wasm-testing-and-cleanup.md

@@ -413,6 +413,91 @@ extern crate wasm_c_shim;
   registers synthetic io/os, but only integration tests verify they actually work
   when called from Lua during filter execution on real wasm32.
 
+## JS bridge isolation and panic strategy (2026-04-17)
+
+After Phase 4 landed, the `wasm-tests` CI job failed at the
+`wasm-bindgen-test-runner` step (Node.js execution) before any test body
+ran, with `MODULE_NOT_FOUND` for `/src/wasm-js-bridge/cache.js`. Two
+distinct issues were uncovered, both originating in production code that
+had never previously been exercised on the wasm32 test path.
+
+### Finding 1: `raw_module` extern blocks load unconditionally
+
+`crates/quarto-system-runtime/src/wasm.rs` declares four
+`#[wasm_bindgen(raw_module = "/src/wasm-js-bridge/{template,sass,cache,fetch}.js")]`
+extern blocks. Hub-client serves these JS files at runtime through Vite,
+and `wasm-bindgen` generates `require()` calls for each one in the JS
+shim it produces. The `require()` happens at module-load time regardless
+of whether the test ever calls into JavaScript, so any wasm32 binary
+that links `quarto-system-runtime` cannot load under Node.js — the
+absolute paths don't resolve on disk.
+
+The pampa wasm tests pull in `quarto-system-runtime` transitively
+(`WasmRuntime`, `LuaShortcodeEngine`), so the failure surfaced as soon
+as Phase 3 tests reached the runner step. Production never tripped this
+because the only wasm32 consumer (`wasm-quarto-hub-client`) runs in a
+browser where Vite resolves the paths.
+
+**Fix:** add a `js-bridge` Cargo feature to `quarto-system-runtime`,
+default off. Gate the four extern blocks behind the feature, and provide
+stub modules that return `Err(JsValue::from_str("js-bridge feature not enabled"))`
+or `false` when off so the `SystemRuntime` impl still compiles.
+`wasm-quarto-hub-client/Cargo.toml` opts in via
+`features = ["js-bridge"]`. Pampa's wasm test build does not, so the
+`require()` calls disappear from the generated shim.
+
+### Finding 2: workspace wasm32 builds inherit `panic = "abort"`
+
+With Finding 1 resolved, the test runner loaded the module successfully
+and reached the test bodies — at which point all six tests failed in
+`wasm-c-shim::rust_lua_throw` with the wasm error `RuntimeError: unreachable`.
+
+The `wasm-c-shim` crate replaces Lua's `setjmp`/`longjmp` with
+`panic!()`/`catch_unwind` (since wasm32 has no native unwinding). For
+this substitution to work, the binary's panic strategy must be `unwind`,
+not the wasm32 default of `abort`. Under `panic=abort`, `panic!()`
+lowers directly to the wasm `unreachable` instruction and `catch_unwind`
+becomes a compile-time no-op that always returns `Ok` — so the first
+Lua throw during mlua's protected init aborts the module.
+
+The CI command's `-Zbuild-std=std,panic_unwind,panic_abort` only ensures
+the unwind runtime is *available* in std; it does not change the
+binary's panic strategy. Three additional flags are required:
+`-C panic=unwind`, `-C target-feature=+exception-handling`, and
+`-Zwasm-c-abi=spec`. `wasm-quarto-hub-client/.cargo/config.toml` already
+sets all three, but that config lives in an isolated workspace and never
+reaches builds invoked from the workspace root. Production never tripped
+this because hub-client builds always use the local config.
+
+**Fix:** mirror the rustflags into the workspace-root `.cargo/config.toml`
+under `[target.wasm32-unknown-unknown]`. `[unstable] build-std` is
+deliberately *not* added to the workspace config — it is not target-scoped,
+so adding it would force `build-std` for every native invocation from the
+root. The `-Zbuild-std` flag stays on the test command (and in CI).
+
+### Finding 3: `LuaThrow` marker placement (rebase artifact)
+
+While this branch was open, main landed `Suppress noisy 'lua error' panic
+stack traces in WASM console` (commit `675c22d2`), which introduced a
+`LuaThrow` marker struct in `wasm-quarto-hub-client/src/lib.rs` and
+changed `rust_lua_throw` from `panic!("lua error")` to
+`std::panic::panic_any(crate::LuaThrow)`. Hub-client's panic hook
+downcasts to `LuaThrow` to filter expected control-flow panics out of
+console.error.
+
+When this branch's "Extract C stdlib shims into shared wasm-c-shim crate"
+commit was rebased onto that change, `crate::LuaThrow` no longer
+resolved — the shim moved out of `wasm-quarto-hub-client`, so `crate::`
+points elsewhere.
+
+**Fix:** the marker belongs in `wasm-c-shim` (where the panic
+originates), not in the hub-client (where the hook lives). Moved the
+`pub struct LuaThrow;` definition into `crates/wasm-c-shim/src/lib.rs`
+and have `wasm-quarto-hub-client/src/lib.rs` import it via
+`use wasm_c_shim::LuaThrow;`. Behavior is preserved; the dependency
+direction is now consistent (hub-client depends on the shim, not
+vice-versa).
+
 ## Out of scope
 
 - Migrating wasm-pack usage (no longer needed — only stale crate used it)

claude-notes/plans/2026-04-07-wasm-testing-and-cleanup.md

@@ -1144,3 +1144,74 @@ br sync --flush-only
 git add .beads/
 git commit -m "Sync beads: close bd-itj9 WASM testing and cleanup"
 ```
+
+---
+
+## Phase 7: Post-CI follow-up findings (2026-04-17)
+
+After Phase 4's CI job started executing, two production-side issues
+surfaced in the test path that did not affect the production wasm32
+build. Both fixes landed on this branch; design rationale in the design
+spec section "JS bridge isolation and panic strategy (2026-04-17)".
+
+### Task 27: Feature-gate JS bridge in `quarto-system-runtime`
+
+- [x] Add `js-bridge` Cargo feature (default off) to
+  `crates/quarto-system-runtime/Cargo.toml`.
+- [x] Gate the four `#[wasm_bindgen(raw_module = ...)]` extern blocks in
+  `crates/quarto-system-runtime/src/wasm.rs` behind
+  `#[cfg(feature = "js-bridge")]`.
+- [x] Provide stub modules under `#[cfg(not(feature = "js-bridge"))]`
+  that return `Err(JsValue::from_str("js-bridge feature not enabled"))`
+  or `false`, matching the original signatures so the `SystemRuntime`
+  impl still compiles.
+- [x] Opt in from `crates/wasm-quarto-hub-client/Cargo.toml`:
+  `quarto-system-runtime = { ..., features = ["js-bridge"] }`.
+
+Without this gate, `wasm-bindgen-test-runner` (Node.js) fails to load
+the module with `MODULE_NOT_FOUND` for `/src/wasm-js-bridge/cache.js`,
+since the absolute paths only resolve under Vite.
+
+### Task 28: Set `panic=unwind` for workspace wasm32 builds
+
+- [x] Add to `[target.wasm32-unknown-unknown]` in workspace
+  `.cargo/config.toml`:
+  ```toml
+  rustflags = [
+      "-C", "target-feature=+bulk-memory,+exception-handling",
+      "-C", "panic=unwind",
+      "-Zwasm-c-abi=spec",
+  ]
+  ```
+- [x] Do **not** add `[unstable] build-std` to the workspace config —
+  the `[unstable]` table is not target-scoped, so it would force
+  build-std on every native invocation. `-Zbuild-std` stays on the test
+  command and in CI.
+
+Without these flags the binary inherits the wasm32 default of
+`panic=abort`, which makes `wasm-c-shim::rust_lua_protected_call`'s
+`catch_unwind` a no-op. The first Lua throw during mlua initialization
+then aborts the wasm module rather than being caught.
+
+### Task 29: Move `LuaThrow` into `wasm-c-shim` (rebase resolution)
+
+- [x] Move `pub struct LuaThrow;` from
+  `crates/wasm-quarto-hub-client/src/lib.rs` into
+  `crates/wasm-c-shim/src/lib.rs` (where the panic actually originates).
+- [x] Update `crates/wasm-quarto-hub-client/src/lib.rs` to
+  `use wasm_c_shim::LuaThrow;` for its panic-suppression hook.
+
+The marker struct was introduced on main while this branch was open
+(`Suppress noisy 'lua error' panic stack traces in WASM console`). After
+rebase, `crate::LuaThrow` in the extracted shim no longer resolved.
+
+### Task 30: Local test verification
+
+- [x] All 6 `pampa wasm_lua` tests pass on `wasm32-unknown-unknown`
+  via `wasm-bindgen-test-runner` / Node.js.
+- [x] `cargo check --workspace` clean (native).
+- [x] `cargo check --target wasm32-unknown-unknown` clean for
+  `wasm-quarto-hub-client`.
+
+Note: `cargo xtask verify` was not re-run locally — these changes
+should be exercised by the existing `wasm-tests` CI job once pushed.

crates/quarto-system-runtime/Cargo.toml

@@ -7,6 +7,17 @@ license.workspace = true
 repository.workspace = true
 description = "Runtime abstraction layer for Quarto system operations"
 
+[features]
+# Enables wasm-bindgen `raw_module` imports of the JS bridge files at
+# /src/wasm-js-bridge/{template,sass,cache,fetch}.js.
+#
+# Hub-client provides those JS modules at runtime via Vite. Off-by-default
+# because non-hub-client wasm32 binaries (e.g. wasm-bindgen-test runs of
+# pampa) have no bridge to require — Node.js fails to resolve the absolute
+# paths at module load. With the feature off, the impls return errors.
+default = []
+js-bridge = []
+
 [dependencies]
 # Async methods in traits
 async-trait.workspace = true

crates/quarto-system-runtime/src/wasm.rs

@@ -39,6 +39,7 @@ use crate::vfs::{VirtualFileSystem, not_found_error};
 // The functions are expected to be provided via a module at the path specified.
 // In hub-client, this is at: /src/wasm-js-bridge/sass.js
 
+#[cfg(feature = "js-bridge")]
 #[wasm_bindgen(raw_module = "/src/wasm-js-bridge/sass.js")]
 extern "C" {
     /// Check if SASS compilation is available.
@@ -69,6 +70,27 @@ extern "C" {
     ) -> Result<JsValue, JsValue>;
 }
 
+#[cfg(not(feature = "js-bridge"))]
+mod sass_stubs {
+    use wasm_bindgen::prelude::*;
+    pub(super) fn js_sass_available_impl() -> bool {
+        false
+    }
+    #[allow(dead_code)]
+    pub(super) fn js_sass_compiler_name_impl() -> String {
+        "unavailable (js-bridge feature not enabled)".to_string()
+    }
+    pub(super) fn js_compile_sass_impl(
+        _scss: &str,
+        _style: &str,
+        _load_paths_json: &str,
+    ) -> Result<JsValue, JsValue> {
+        Err(JsValue::from_str("js-bridge feature not enabled"))
+    }
+}
+#[cfg(not(feature = "js-bridge"))]
+use sass_stubs::{js_compile_sass_impl, js_sass_available_impl, js_sass_compiler_name_impl};
+
 // =============================================================================
 // JavaScript Interop for Cache Operations
 // =============================================================================
@@ -79,6 +101,7 @@ extern "C" {
 // The functions are expected to be provided via a module at the path specified.
 // In hub-client, this is at: /src/wasm-js-bridge/cache.js
 
+#[cfg(feature = "js-bridge")]
 #[wasm_bindgen(raw_module = "/src/wasm-js-bridge/cache.js")]
 extern "C" {
     /// Get a cached value by namespace and key.
@@ -110,6 +133,31 @@ extern "C" {
     fn js_cache_clear_namespace_impl(namespace: &str) -> Result<JsValue, JsValue>;
 }
 
+#[cfg(not(feature = "js-bridge"))]
+mod cache_stubs {
+    use wasm_bindgen::prelude::*;
+    pub(super) fn js_cache_get_impl(_namespace: &str, _key: &str) -> Result<JsValue, JsValue> {
+        Err(JsValue::from_str("js-bridge feature not enabled"))
+    }
+    pub(super) fn js_cache_set_impl(
+        _namespace: &str,
+        _key: &str,
+        _value: &js_sys::Uint8Array,
+    ) -> Result<JsValue, JsValue> {
+        Err(JsValue::from_str("js-bridge feature not enabled"))
+    }
+    pub(super) fn js_cache_delete_impl(_namespace: &str, _key: &str) -> Result<JsValue, JsValue> {
+        Err(JsValue::from_str("js-bridge feature not enabled"))
+    }
+    pub(super) fn js_cache_clear_namespace_impl(_namespace: &str) -> Result<JsValue, JsValue> {
+        Err(JsValue::from_str("js-bridge feature not enabled"))
+    }
+}
+#[cfg(not(feature = "js-bridge"))]
+use cache_stubs::{
+    js_cache_clear_namespace_impl, js_cache_delete_impl, js_cache_get_impl, js_cache_set_impl,
+};
+
 // =============================================================================
 // JavaScript Interop for Network Fetch
 // =============================================================================
@@ -121,6 +169,7 @@ extern "C" {
 // Binary content is base64-encoded by the JS side to avoid complex type
 // marshalling. The Rust side decodes it with the base64 crate.
 
+#[cfg(feature = "js-bridge")]
 #[wasm_bindgen(raw_module = "/src/wasm-js-bridge/fetch.js")]
 extern "C" {
     /// Fetch content from a URL.
@@ -133,6 +182,11 @@ extern "C" {
     fn js_fetch_url_impl(url: &str) -> Result<JsValue, JsValue>;
 }
 
+#[cfg(not(feature = "js-bridge"))]
+fn js_fetch_url_impl(_url: &str) -> Result<JsValue, JsValue> {
+    Err(JsValue::from_str("js-bridge feature not enabled"))
+}
+
 // =============================================================================
 // Monotonic clock: performance.now()
 // =============================================================================

crates/wasm-c-shim/src/lib.rs

@@ -24,3 +24,12 @@
 
 #[cfg(target_arch = "wasm32")]
 mod shim;
+
+/// Marker payload for panics raised by `rust_lua_throw` (the WASM replacement
+/// for Lua's `LUAI_THROW`). Each Lua error inside `lua_pcall` produces one
+/// such panic, which `rust_lua_protected_call` catches microseconds later.
+///
+/// Hosts that install a custom panic hook (e.g. wasm-quarto-hub-client) can
+/// downcast to this type to filter expected Lua control-flow panics out of
+/// console.error logs without suppressing real Rust panics.
+pub struct LuaThrow;

crates/wasm-quarto-hub-client/Cargo.toml

@@ -27,7 +27,7 @@ quarto-lsp-core = { path = "../quarto-lsp-core" }
 quarto-pandoc-types = { path = "../quarto-pandoc-types" }
 quarto-sass = { path = "../quarto-sass" }
 quarto-source-map = "0.1.0"
-quarto-system-runtime = { path = "../quarto-system-runtime" }
+quarto-system-runtime = { path = "../quarto-system-runtime", features = ["js-bridge"] }
 quarto-project-create = { path = "../quarto-project-create" }
 quarto-trace = { path = "../quarto-trace" }
 flate2 = "1.1"

crates/wasm-quarto-hub-client/src/lib.rs

@@ -12,15 +12,7 @@
 #[cfg(target_arch = "wasm32")]
 extern crate wasm_c_shim;
 
-/// Sentinel panic payload raised by `c_shim::rust_lua_throw`.
-///
-/// On wasm32 Lua's `LUAI_THROW` macro cannot use `setjmp`/`longjmp`, so
-/// it is rewired to raise a Rust panic that `rust_lua_protected_call`
-/// catches via `catch_unwind`. This happens on every Lua runtime error —
-/// including ones caught by `pcall` — so the panic is expected control
-/// flow. The `init()` panic hook filters panics carrying this payload
-/// so they do not spam `console.error` with stack traces.
-pub struct LuaThrow;
+use wasm_c_shim::LuaThrow;
 
 use std::cell::RefCell;
 use std::path::Path;