Split WASM parser and handler bundles (#344)

Author: mohamedmansour

.github/actions/setup-wasm/action.yml

@@ -26,6 +26,8 @@ runs:
     - name: Verify WASM output
       shell: bash
       run: |
-        test -f docs/.webui-press/public/wasm/webui_wasm_bg.wasm
-        test -f docs/.webui-press/public/wasm/webui_wasm.js
-        ! grep -q "from 'env'" docs/.webui-press/public/wasm/webui_wasm.js
+        for variant in all handler parser; do
+          test -f "docs/.webui-press/public/wasm/${variant}/webui_wasm_${variant}_bg.wasm"
+          test -f "docs/.webui-press/public/wasm/${variant}/webui_wasm_${variant}.js"
+          ! grep -q "from 'env'" "docs/.webui-press/public/wasm/${variant}/webui_wasm_${variant}.js"
+        done

.github/workflows/publish.yml

@@ -246,6 +246,6 @@ jobs:
             publish/npm/*
             publish/nuget/*
             publish/crates/*
-            publish/wasm/*
+            publish/wasm/**/*
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Cargo.lock

@@ -35,6 +35,7 @@ prost = "0.14.3"
 napi = { version = "3.8.5", features = ["napi4"] }
 napi-derive = "3.5.4"
 wasm-bindgen = "=0.2.100"
+js-sys = "0.3.77"
 serde-wasm-bindgen = "0.6"
 actix-web = "4.11.0"
 rustls = "0.23.39"

Cargo.toml

@@ -1476,16 +1476,39 @@ webui-cli ──────► webui (library) ◄────── webui-node
                     ├── webui-protocol        └── serde_json
                     └── webui-discovery
 
-webui-ffi ──────► webui-handler ◄────── webui-wasm
-                  webui-parser              webui-parser
-                  webui-protocol            webui-protocol
+webui-ffi ──────► webui-handler ◄────── webui-wasm (handler feature)
+                  webui-parser       ┌──── webui-wasm (parser feature)
+                  webui-protocol     └──── webui-wasm (all/default feature)
 ```
 
 The `webui` library crate is the primary API surface for programmatic use.
 It re-exports `WebUIHandler`, `ResponseWriter`, and `WebUIProtocol` from their
 respective crates and provides `build()`, `build_to_disk()`, and `inspect()`
 functions with `BuildStats` (duration, fragment/component/CSS counts, protocol size).
 
+### WASM Distribution
+
+The `microsoft-webui-wasm` crate exposes feature-gated browser bindings so
+consumers only ship the parser and/or handler code they need:
+
+- `handler` builds `webui_wasm_handler.js` and exports `render`,
+  `render_partial`, `protocol_tokens`, and `render_component_templates`. It
+  accepts protobuf protocol bytes and depends on `webui-handler` and
+  `webui-protocol`, not `webui-parser`. `render(protocolBytes, stateJson,
+  onChunk, options)` uses the same `ResponseWriter` callback shape as the
+  Node binding: each handler write calls `onChunk(html)`, while callers that
+  need a full string concatenate chunks in JavaScript.
+- `parser` builds `webui_wasm_parser.js` and exports `build_protocol`. It
+  returns protobuf protocol bytes and depends on `webui-parser` and
+  `webui-protocol`, not `webui-handler`.
+- `all` is the default feature, builds `webui_wasm_all.js`, and exports the
+  parser plus handler surfaces for playground-style live preview. Callers
+  compose `build_protocol()` and callback-based `render()` explicitly.
+
+`cargo xtask build-wasm` builds all three variants into
+`docs/.webui-press/public/wasm/{all,handler,parser}/` with stable `wasm-pack`
+output names.
+
 ### npm Distribution
 
 The `@microsoft/webui` npm package follows the esbuild single-package model:

DESIGN.md

@@ -18,12 +18,19 @@ wasm-opt = false
 name = "webui_wasm"
 crate-type = ["cdylib", "rlib"]
 
+[features]
+default = ["all"]
+all = ["handler", "parser"]
+handler = ["dep:microsoft-webui-handler"]
+parser = ["dep:microsoft-webui-parser"]
+
 [dependencies]
-microsoft-webui-parser = { path = "../webui-parser", version = "0.0.15", default-features = false }
-microsoft-webui-handler = { path = "../webui-handler", version = "0.0.15" }
+microsoft-webui-parser = { path = "../webui-parser", version = "0.0.15", default-features = false, optional = true }
+microsoft-webui-handler = { path = "../webui-handler", version = "0.0.15", optional = true }
 microsoft-webui-protocol = { path = "../webui-protocol", version = "0.0.15" }
 serde_json = { workspace = true }
 wasm-bindgen = { workspace = true }
+js-sys = { workspace = true }
 serde-wasm-bindgen = { workspace = true }
 thiserror = { workspace = true }
 

crates/webui-wasm/Cargo.toml

@@ -1,15 +1,31 @@
 # microsoft-webui-wasm
 
-WebAssembly bindings for the [WebUI](https://github.com/microsoft/webui) framework, built with `wasm-bindgen`. Powers the online WebUI playground.
+WebAssembly bindings for the [WebUI](https://github.com/microsoft/webui) framework, built with `wasm-bindgen`.
 
 ## Overview
 
-`microsoft-webui-wasm` exposes WebUI's parser and handler to the browser via a WASM module, enabling live template preview without a server.
+`microsoft-webui-wasm` can be built as three browser bundles:
+
+| Feature | Bundle | Exports |
+|---------|--------|---------|
+| `handler` | `webui_wasm_handler.js` | `render`, `render_partial`, `protocol_tokens`, `render_component_templates` |
+| `parser` | `webui_wasm_parser.js` | `build_protocol` |
+| `all` | `webui_wasm_all.js` | Parser and handler exports |
+
+The default feature is `all`, which powers the online playground. Consumers that only need to render prebuilt protobuf protocol bytes should use the handler bundle to avoid shipping parser code.
+
+## Building
+
+```bash
+cargo xtask build-wasm
+```
+
+This writes the three generated bundles under `docs/.webui-press/public/wasm/`.
 
 ## Documentation
 
 See the [WebUI repository](https://github.com/microsoft/webui) for full usage guides and examples.
 
 ## License
 
-MIT — Copyright (c) Microsoft Corporation.
+MIT - Copyright (c) Microsoft Corporation.

crates/webui-wasm/README.md

@@ -0,0 +1,42 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+//! Shared WASM binding errors.
+
+/// Error type used by the WASM binding layer.
+#[derive(Debug, thiserror::Error)]
+pub(crate) enum WasmError {
+    /// Requested entry file was not present in the virtual file map.
+    #[cfg(feature = "parser")]
+    #[error("Entry file '{0}' not found")]
+    MissingEntry(String),
+
+    /// Template parsing or authoring validation failed.
+    #[cfg(feature = "parser")]
+    #[error("{0}")]
+    Parse(#[from] webui_parser::ParserError),
+
+    /// Protocol protobuf bytes could not be decoded or encoded.
+    #[error("Protocol error: {0}")]
+    Protocol(#[from] webui_protocol::ProtocolError),
+
+    /// State JSON could not be decoded.
+    #[cfg(feature = "handler")]
+    #[error("State JSON error: {0}")]
+    State(serde_json::Error),
+
+    /// Rendering failed.
+    #[cfg(feature = "handler")]
+    #[error("{0}")]
+    Render(#[from] webui_handler::HandlerError),
+
+    /// A requested handler plugin name is not supported.
+    #[cfg(feature = "handler")]
+    #[error("Unknown plugin: {0}. Use \"webui\", \"fast-v3\", \"fast-v2\", or \"fast\".")]
+    UnknownPlugin(String),
+
+    /// The JavaScript render options object was invalid.
+    #[cfg(feature = "handler")]
+    #[error("Invalid render options: {0}")]
+    InvalidOptions(String),
+}