feat(example): Creates the best demo for acme commerce store (#110)

Author: mohamedmansour

Cargo.lock

@@ -4,6 +4,7 @@ members = [
     "xtask",
     "examples/integration/rust",
     "examples/integration/ssr-performance-showdown",
+    "examples/app/commerce/server",
 ]
 resolver = "2"
 

Cargo.toml

@@ -361,8 +361,7 @@ fn run(args: &ServeArgs) -> Result<()> {
                     .app_data(server_context.clone())
                     .route("/", web::get().to(handle_index))
                     .route("/index.html", web::get().to(handle_index))
-                    .route("/hmr", web::get().to(handle_hmr))
-                    .route("/.webui/routes.json", web::get().to(handle_routes_json));
+                    .route("/hmr", web::get().to(handle_hmr));
 
                 if has_api_proxy {
                     app = app.route("/api/{tail:.*}", web::route().to(handle_api_proxy));
@@ -810,46 +809,6 @@ fn collect_needed_template_names(
     )
 }
 
-/// Handle GET /.webui/routes.json — return the route registry as JSON.
-async fn handle_routes_json(context: web::Data<ServerContext>) -> HttpResponse {
-    let routes_array = match context.state.lock() {
-        Ok(s) => match &s.protocol {
-            Some(p) => {
-                let entries: Vec<Value> = p
-                    .routes
-                    .iter()
-                    .map(|(key, record): (&String, &webui_protocol::RouteRecord)| {
-                        let name_val = if record.name.is_empty() {
-                            key.as_str()
-                        } else {
-                            record.name.as_str()
-                        };
-                        let mut m = serde_json::Map::new();
-                        m.insert("name".into(), Value::String(name_val.to_string()));
-                        m.insert("path".into(), Value::String(record.path.clone()));
-                        m.insert(
-                            "fragmentId".into(),
-                            Value::String(record.fragment_id.clone()),
-                        );
-                        m.insert("exact".into(), Value::Bool(record.exact));
-                        Value::Object(m)
-                    })
-                    .collect();
-                Value::Array(entries)
-            }
-            None => Value::Array(Vec::new()),
-        },
-        Err(_) => Value::Array(Vec::new()),
-    };
-
-    let mut envelope = serde_json::Map::new();
-    envelope.insert("routes".into(), routes_array);
-
-    HttpResponse::Ok()
-        .content_type("application/json")
-        .json(Value::Object(envelope))
-}
-
 /// Forward requests under `/api/*` to the user's API server.
 async fn handle_api_proxy(
     req: HttpRequest,

crates/webui-cli/src/commands/serve.rs

@@ -152,24 +152,17 @@ fn emit_state_attributes(state: &Value, writer: &mut dyn ResponseWriter) -> Resu
     // Emit scalar values as individual attributes
     for (key, value) in map {
         let val_str = match value {
-            Value::String(s) => s.clone(),
-            Value::Number(n) => n.to_string(),
-            Value::Bool(b) => b.to_string(),
+            Value::String(s) => std::borrow::Cow::Borrowed(s.as_str()),
+            Value::Number(n) => std::borrow::Cow::Owned(n.to_string()),
+            Value::Bool(true) => std::borrow::Cow::Borrowed("true"),
+            Value::Bool(false) => std::borrow::Cow::Borrowed("false"),
             _ => continue,
         };
         let attr_name = camel_to_kebab(key);
         writer.write(" ")?;
         writer.write(&attr_name)?;
         writer.write("=\"")?;
-        for ch in val_str.chars() {
-            match ch {
-                '&' => writer.write("&")?,
-                '"' => writer.write(""")?,
-                '<' => writer.write("&lt;")?,
-                '>' => writer.write("&gt;")?,
-                _ => writer.write(&String::from(ch))?,
-            }
-        }
+        write_escaped_state_attr(writer, val_str.as_ref())?;
         writer.write("\"")?;
     }
 
@@ -178,16 +171,36 @@ fn emit_state_attributes(state: &Value, writer: &mut dyn ResponseWriter) -> Resu
     if has_complex {
         let json_str = state.to_string();
         writer.write(" data-state=\"")?;
-        for ch in json_str.chars() {
-            match ch {
-                '&' => writer.write("&amp;")?,
-                '"' => writer.write("&quot;")?,
-                '<' => writer.write("&lt;")?,
-                '>' => writer.write("&gt;")?,
-                _ => writer.write(&String::from(ch))?,
+        write_escaped_state_attr(writer, &json_str)?;
+        writer.write("\"")?;
+    }
+
+    Ok(())
+}
+
+fn write_escaped_state_attr(writer: &mut dyn ResponseWriter, value: &str) -> Result<()> {
+    let mut last = 0;
+
+    for (index, ch) in value.char_indices() {
+        let escaped = match ch {
+            '&' => Some("&amp;"),
+            '"' => Some("&quot;"),
+            '<' => Some("&lt;"),
+            '>' => Some("&gt;"),
+            _ => None,
+        };
+
+        if let Some(entity) = escaped {
+            if last < index {
+                writer.write(&value[last..index])?;
             }
+            writer.write(entity)?;
+            last = index + ch.len_utf8();
         }
-        writer.write("\"")?;
+    }
+
+    if last < value.len() {
+        writer.write(&value[last..])?;
     }
 
     Ok(())
@@ -5194,4 +5207,41 @@ mod tests {
             "component attr should be on webui-route: {html}"
         );
     }
+
+    #[test]
+    fn test_route_state_attributes_escape_scalars_and_data_state() {
+        let protocol = make_route_protocol();
+        let state = test_json!({
+            "title": "Fish & Chips <\"special\">",
+            "cartOpen": true,
+            "items": [{"name": "A&B"}]
+        });
+        let mut writer = TestWriter::new();
+
+        handle(
+            &protocol,
+            &state,
+            &RenderOptions::new("index.html", "/"),
+            &mut writer,
+        )
+        .unwrap();
+
+        let html = writer.get_content();
+        assert!(
+            html.contains(r#"title="Fish &amp; Chips &lt;&quot;special&quot;&gt;""#),
+            "escaped title should be emitted: {html}"
+        );
+        assert!(
+            html.contains(r#"cart-open="true""#),
+            "bool attrs should render: {html}"
+        );
+        assert!(
+            html.contains(r#"data-state=""#),
+            "complex state should be emitted as data-state: {html}"
+        );
+        assert!(
+            html.contains(r#"&quot;name&quot;:&quot;A&amp;B&quot;"#),
+            "complex state values should be escaped inside data-state: {html}"
+        );
+    }
 }

crates/webui-handler/src/lib.rs

@@ -0,0 +1 @@
+static/images/products

examples/app/commerce/.gitignore

@@ -0,0 +1,38 @@
+# WebUI Store — WebUI Marketplace Demo
+
+A blazing-fast, server-rendered marketplace dashboard built with **WebUI** and **actix-web**.
+
+This demo proves WebUI's SSR performance: 1,000+ products rendered server-side in sub-millisecond time, with seamless FAST-HTML client hydration for interactivity.
+
+## Architecture
+
+- **Server**: actix-web (Rust) with 3 SSR page routes + cart API
+- **Templates**: WebUI binary protocol — compiled once, rendered per-request
+- **Client**: FAST-HTML hydration for cart, search, gallery, variant selection
+- **Design**: Atomic Design (atoms → molecules → organisms → pages)
+- **Theme**: WebUI dark theme inspired by copilot.microsoft.com
+
+## Quick Start
+
+```bash
+# Install client dependencies
+pnpm install
+
+# Run the server.
+pnpm start
+
+# Open http://localhost:3100
+```
+
+## Pages
+
+| Page | URL | Description |
+|------|-----|-------------|
+| Homepage | `/` | 3-item hero grid + product carousel |
+| Search | `/search?q=&sort=` | Category sidebar + product grid + sort |
+| Category | `/search/{category}` | Filtered by category |
+| Product | `/product/{handle}` | Gallery + variants + add-to-cart |
+
+## Performance
+
+Templates are compiled to binary protocol at server startup. Per-request rendering only injects state data — no template parsing, no JavaScript execution on the server.

examples/app/commerce/README.md

@@ -0,0 +1,20 @@
+{
+  "storeName": "WebUI Store",
+  "cartItemCount": "0",
+  "navCategories": [
+    { "handle": "shirts", "title": "Shirts" },
+    { "handle": "stickers", "title": "Stickers" },
+    { "handle": "bags", "title": "Bags" }
+  ],
+  "categories": [
+    { "handle": "shirts", "title": "Shirts" },
+    { "handle": "stickers", "title": "Stickers" },
+    { "handle": "bags", "title": "Bags" }
+  ],
+  "featuredProducts": [],
+  "carouselProducts": [],
+  "cartEmpty": true,
+  "cartSubtotal": "$0.00",
+  "cartTaxes": "$0.00",
+  "cartItems": []
+}

examples/app/commerce/data/state.json

@@ -0,0 +1,25 @@
+{
+  "name": "commerce",
+  "version": "1.0.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "start:client": "esbuild src/index.ts --bundle --outfile=dist/index.js --format=esm --sourcemap --watch",
+    "start:server": "cargo run -p marketplace-api -- --port 3100",
+    "start": "cargo xtask dev commerce"
+  },
+  "imports": {
+    "#atoms/*": "./src/atoms/*",
+    "#molecules/*": "./src/molecules/*",
+    "#organisms/*": "./src/organisms/*",
+    "#pages/*": "./src/pages/*"
+  },
+  "devDependencies": {
+    "@microsoft/fast-element": "catalog:",
+    "@microsoft/fast-html": "catalog:",
+    "@microsoft/webui-router": "workspace:*",
+    "esbuild": "catalog:",
+    "typescript": "catalog:",
+    "tslib": "catalog:"
+  }
+}

examples/app/commerce/package.json

@@ -0,0 +1,20 @@
+[package]
+name = "marketplace-api"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[[bin]]
+name = "marketplace-api"
+path = "src/main.rs"
+
+[dependencies]
+actix-web = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+anyhow = { workspace = true }
+clap = { workspace = true }
+mime_guess = { workspace = true }
+thiserror = { workspace = true }
+webui = { path = "../../../../crates/webui" }
+webui-handler = { path = "../../../../crates/webui-handler" }

examples/app/commerce/server/Cargo.toml

@@ -0,0 +1,45 @@
+use anyhow::Result;
+use std::path::Path;
+
+use crate::catalog::Catalog;
+use crate::frontend::FrontendRuntime;
+
+pub(crate) struct AppState {
+    catalog: Catalog,
+    frontend: FrontendRuntime,
+}
+
+impl AppState {
+    pub(crate) fn load(app_root: &Path) -> Result<Self> {
+        let frontend = FrontendRuntime::load(app_root)?;
+        let catalog = Catalog::generate();
+        Ok(Self { catalog, frontend })
+    }
+
+    #[must_use]
+    pub(crate) fn catalog(&self) -> &Catalog {
+        &self.catalog
+    }
+
+    #[must_use]
+    pub(crate) fn frontend(&self) -> &FrontendRuntime {
+        &self.frontend
+    }
+
+    #[must_use]
+    pub(crate) fn product_count(&self) -> usize {
+        self.catalog.product_count()
+    }
+}
+
+#[cfg(test)]
+pub(crate) fn test_state() -> actix_web::web::Data<AppState> {
+    let app_root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
+        .parent()
+        .expect("server crate should live under the app directory");
+    let state = match AppState::load(app_root) {
+        Ok(state) => state,
+        Err(error) => panic!("{error}"),
+    };
+    actix_web::web::Data::new(state)
+}