fix: omit render-only tokens from client state (#351)

* Omit render-only tokens from client state

Keep design-token CSS available during SSR, but omit the render-only tokens field from the emitted webui-data client state in CLI and FFI render paths.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix: strip render-only tokens from client state

Strip top-level tokens in the handler when serializing the WebUI bootstrap state instead of exposing a generic RenderOptions omit-list or wiring special cases through CLI and FFI callers.

SSR still receives the full state so token CSS signals resolve during render, while the emitted client state drops the render-only token payload. Keep coverage at the handler boundary and the serve pipeline.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Remove serve token filtering test

Rely on handler and FFI coverage for render-only token omission and remove the webui-cli serve-specific regression test.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Mohamed Mansour <hello@mohamedmansour.com>

Author: 3 people

DESIGN.md

@@ -1257,7 +1257,7 @@ inject_token_css(state, css) → state["tokens"]["light"] = "..."
 1. **Filter**: Only tokens in `protocol.tokens` are kept.
 2. **Dependency closure**: Token values referencing other tokens via `var(--x)` trigger transitive inclusion. Uses an iterative BFS expansion followed by DFS cycle detection.
 3. **CSS generation**: Sorted `--name: value;` declarations. Output is deterministic.
-4. **State injection**: Per-theme CSS strings are set on `state.tokens.<theme>`, where `/*{{{tokens.<theme>}}}*/` signals resolve them during rendering.
+4. **State injection**: Per-theme CSS strings are set on `state.tokens.<theme>`, where `/*{{{tokens.<theme>}}}*/` signals resolve them during rendering. These render-only token strings are omitted from the emitted `webui-data` client bootstrap.
 
 #### Package Resolution (`resolve_theme_path`)
 

crates/webui-handler/src/lib.rs

@@ -28,6 +28,7 @@ use plugin::BootstrapExtensionContext;
 use plugin::HandlerPlugin;
 use plugin::WebUiTemplatePayload;
 use route_matcher::CompiledRouteCache;
+use serde::ser::SerializeMap;
 use serde::Serialize;
 use serde_json::Value;
 use std::borrow::Cow;
@@ -37,6 +38,8 @@ use webui_expressions::{evaluate_with_resolver, ExpressionError};
 use webui_protocol::{web_ui_fragment::Fragment, WebUIFragment, WebUIProtocol};
 use webui_state::find_value_by_dotted_path_ref;
 
+const CLIENT_STATE_TOKEN_KEY: &str = "tokens";
+
 /// Error types for the WebUI handler.
 #[derive(Debug, Error)]
 pub enum HandlerError {
@@ -360,6 +363,34 @@ where
     write_script_safe_json(writer, value)
 }
 
+struct ClientState<'a> {
+    value: &'a Value,
+}
+
+impl Serialize for ClientState<'_> {
+    fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+    where
+        S: serde::Serializer,
+    {
+        let Value::Object(map) = self.value else {
+            return self.value.serialize(serializer);
+        };
+
+        if !map.contains_key(CLIENT_STATE_TOKEN_KEY) {
+            return self.value.serialize(serializer);
+        }
+
+        let mut out = serializer.serialize_map(None)?;
+        for (key, value) in map {
+            if key == CLIENT_STATE_TOKEN_KEY {
+                continue;
+            }
+            out.serialize_entry(key, value)?;
+        }
+        out.end()
+    }
+}
+
 fn write_webui_bootstrap(
     writer: &mut dyn ResponseWriter,
     bootstrap: WebUiBootstrap<'_>,
@@ -377,7 +408,14 @@ fn write_webui_bootstrap(
     if let Some(nonce) = bootstrap.nonce {
         write_json_field(writer, &mut wrote_field, "nonce", nonce)?;
     }
-    write_json_field(writer, &mut wrote_field, "state", bootstrap.state)?;
+    write_json_field(
+        writer,
+        &mut wrote_field,
+        "state",
+        &ClientState {
+            value: bootstrap.state,
+        },
+    )?;
     if !bootstrap.style_specs.is_empty() {
         write_json_field(writer, &mut wrote_field, "styles", bootstrap.style_specs)?;
     }
@@ -7091,6 +7129,46 @@ mod tests {
         );
     }
 
+    #[test]
+    fn client_state_strips_tokens_after_ssr_resolution() -> Result<()> {
+        let mut fragments = HashMap::new();
+        fragments.insert(
+            "index.html".to_string(),
+            FragmentList {
+                fragments: vec![
+                    WebUIFragment::raw("<html><body><style>".to_string()),
+                    WebUIFragment::signal("tokens.light", true),
+                    WebUIFragment::raw("</style>".to_string()),
+                    WebUIFragment::signal("body_end", true),
+                    WebUIFragment::raw("</body></html>".to_string()),
+                ],
+            },
+        );
+        let protocol = WebUIProtocol::new(fragments);
+        let state = test_json!({
+            "name": "Alice",
+            "tokens": {
+                "light": "--color-brand: red;"
+            }
+        });
+        let mut writer = TestWriter::new();
+        let handler = WebUIHandler::with_plugin(|| {
+            Box::new(crate::plugin::webui::WebUIHydrationPlugin::new())
+        });
+        handler.handle(
+            &protocol,
+            &state,
+            &RenderOptions::new("index.html", "/"),
+            &mut writer,
+        )?;
+        let output = writer.get_content();
+
+        assert!(output.contains("--color-brand: red;"));
+        assert!(output.contains(r#""name":"Alice""#));
+        assert!(!output.contains(r#""tokens""#));
+        Ok(())
+    }
+
     #[test]
     fn test_component_attr_name_aria() {
         // component_attr_name correctly maps ARIA attributes via the shared table

docs/ai.md

@@ -716,7 +716,8 @@ property declarations into the render state. Only available on `webui serve`.
    including nested `var()` fallbacks)
 3. Expands transitive `var()` references and detects cycles
 4. Generates CSS declaration strings per theme
-5. Injects into state as `state.tokens.light`, `state.tokens.dark`, etc.
+5. Injects into SSR state as `state.tokens.light`, `state.tokens.dark`, etc.
+   These render-only token strings are omitted from the emitted client state.
 
 **Multi-theme format:**
 ```json