fix to more streamable node

Author: mohamedmansour

crates/webui-node/Cargo.toml

@@ -13,7 +13,6 @@ crate-type = ["cdylib"]
 [dependencies]
 napi = { workspace = true }
 napi-derive = { workspace = true }
-webui-parser = { path = "../webui-parser", default-features = false }
 webui-handler = { path = "../webui-handler" }
 webui-protocol = { path = "../webui-protocol" }
 serde_json = { workspace = true }
@@ -22,4 +21,5 @@ serde_json = { workspace = true }
 napi-build = { workspace = true }
 
 [dev-dependencies]
+webui-parser = { path = "../webui-parser", default-features = false }
 webui-test-utils = { path = "../webui-test-utils" }

crates/webui-node/src/lib.rs

@@ -3,39 +3,51 @@
 //! Provides high-performance server-side rendering by compiling the Rust
 //! WebUI handler directly into a `.node` native addon — no C ABI intermediary.
 //!
+//! The `render` function accepts pre-compiled protobuf protocol data (from
+//! `webui build`) and streams rendered HTML fragments via a callback, enabling
+//! true streaming SSR without buffering the entire response.
+//!
 //! ## Usage (from Node.js)
 //!
 //! ```js
-//! // Load the native addon from the cargo build output
+//! import fs from 'node:fs';
+//!
+//! // Load the native addon
 //! const mod = { exports: {} };
 //! process.dlopen(mod, './target/release/libwebui_node.dylib');
-//! const html = mod.exports.render('<h1>Hello, {{name}}!</h1>', '{"name": "WebUI"}');
-//! // => "<h1>Hello, WebUI!</h1>"
+//! const { render } = mod.exports;
+//!
+//! // Read pre-compiled protocol (from `webui build`)
+//! const protocol = fs.readFileSync('./dist/protocol.bin');
+//! const state = '{"name": "WebUI"}';
+//!
+//! // Stream rendered fragments
+//! render(protocol, state, (chunk) => process.stdout.write(chunk));
 //! ```
 
+use napi::bindgen_prelude::{Buffer, Function};
 use napi::Error as NapiError;
 use napi_derive::napi;
 use serde_json::Value;
 use webui_handler::{ResponseWriter, WebUIHandler};
-use webui_parser::HtmlParser;
 use webui_protocol::WebUIProtocol;
 
-/// A simple string buffer for collecting rendered output.
-struct StringWriter {
-    content: String,
+/// A writer that streams each rendered fragment to a JS callback.
+struct CallbackWriter<'a, 'env> {
+    callback: &'a Function<'env, String, ()>,
 }
 
-impl StringWriter {
-    fn with_capacity(cap: usize) -> Self {
-        Self {
-            content: String::with_capacity(cap),
-        }
+impl<'a, 'env> CallbackWriter<'a, 'env> {
+    fn new(callback: &'a Function<'env, String, ()>) -> Self {
+        Self { callback }
     }
 }
 
-impl ResponseWriter for StringWriter {
+impl ResponseWriter for CallbackWriter<'_, '_> {
     fn write(&mut self, content: &str) -> webui_handler::Result<()> {
-        self.content.push_str(content);
+        // Ignore return-value type mismatch — JS callbacks may return
+        // non-undefined values (e.g. `res.write()` returns a boolean).
+        let _ = self.callback.call(content.to_owned());
         Ok(())
     }
 
@@ -44,77 +56,98 @@ impl ResponseWriter for StringWriter {
     }
 }
 
-/// Parse an HTML template and render it with JSON state data.
+/// Render a pre-compiled WebUI protocol with JSON state, streaming each
+/// fragment to the provided callback.
+///
+/// # Arguments
 ///
-/// This is the main entry point for Node.js consumers. It parses the template,
-/// builds a protocol, and renders it with the provided state — all in one call.
+/// * `protocol_data` — Protobuf binary from `webui build` (zero-copy Buffer).
+/// * `state_json` — JSON string with the render state.
+/// * `on_chunk` — Called with each rendered HTML fragment as it is produced.
 #[napi]
-pub fn render(html: String, data_json: String) -> napi::Result<String> {
-    render_inner(&html, &data_json).map_err(|e| NapiError::from_reason(e.to_string()))
-}
-
-fn render_inner(html: &str, data_json: &str) -> Result<String, RenderError> {
-    let mut parser = HtmlParser::new();
-    parser
-        .parse("index.html", html)
-        .map_err(|e| RenderError::Parse(e.to_string()))?;
-
-    let protocol = WebUIProtocol {
-        fragments: parser.into_fragment_records(),
-    };
-
-    let state: Value =
-        serde_json::from_str(data_json).map_err(|e| RenderError::State(e.to_string()))?;
-
-    let initial_cap = html.len().max(1024);
-    let mut writer = StringWriter::with_capacity(initial_cap);
+pub fn render(
+    protocol_data: Buffer,
+    state_json: String,
+    on_chunk: Function<String, ()>,
+) -> napi::Result<()> {
+    let protocol = WebUIProtocol::from_protobuf(&protocol_data)
+        .map_err(|e| NapiError::from_reason(format!("Protocol decode error: {e}")))?;
+
+    let state: Value = serde_json::from_str(&state_json)
+        .map_err(|e| NapiError::from_reason(format!("State JSON error: {e}")))?;
+
+    let mut writer = CallbackWriter::new(&on_chunk);
     let handler = WebUIHandler::new();
     handler
         .render(&protocol, &state, &mut writer)
-        .map_err(|e| RenderError::Render(e.to_string()))?;
+        .map_err(|e| NapiError::from_reason(format!("Render error: {e}")))?;
 
-    Ok(writer.content)
-}
-
-/// Errors from the render pipeline.
-#[derive(Debug, PartialEq)]
-enum RenderError {
-    Parse(String),
-    State(String),
-    Render(String),
-}
-
-impl std::fmt::Display for RenderError {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        match self {
-            RenderError::Parse(msg) => write!(f, "HTML parse error: {msg}"),
-            RenderError::State(msg) => write!(f, "State JSON error: {msg}"),
-            RenderError::Render(msg) => write!(f, "Render error: {msg}"),
-        }
-    }
+    Ok(())
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
+    use webui_parser::HtmlParser;
+
+    /// Helper: parse HTML into protobuf bytes for testing.
+    fn build_protocol(html: &str) -> Vec<u8> {
+        let mut parser = HtmlParser::new();
+        parser.parse("index.html", html).expect("parse failed");
+        let protocol = WebUIProtocol {
+            fragments: parser.into_fragment_records(),
+        };
+        protocol.to_protobuf().expect("protobuf encode failed")
+    }
+
+    /// Helper: render protocol bytes + state, collecting output into a String.
+    fn render_to_string(protocol_bytes: &[u8], state_json: &str) -> Result<String, String> {
+        let protocol = WebUIProtocol::from_protobuf(protocol_bytes).map_err(|e| e.to_string())?;
+        let state: Value = serde_json::from_str(state_json).map_err(|e| e.to_string())?;
+
+        let mut output = String::with_capacity(1024);
+        let handler = WebUIHandler::new();
+
+        struct StringWriter<'a> {
+            output: &'a mut String,
+        }
+        impl ResponseWriter for StringWriter<'_> {
+            fn write(&mut self, content: &str) -> webui_handler::Result<()> {
+                self.output.push_str(content);
+                Ok(())
+            }
+            fn end(&mut self) -> webui_handler::Result<()> {
+                Ok(())
+            }
+        }
+
+        let mut writer = StringWriter {
+            output: &mut output,
+        };
+        handler
+            .render(&protocol, &state, &mut writer)
+            .map_err(|e| e.to_string())?;
+        Ok(output)
+    }
 
     #[test]
     fn test_simple_passthrough() {
-        let result = render_inner("<p>Hello</p>", "{}");
+        let proto = build_protocol("<p>Hello</p>");
+        let result = render_to_string(&proto, "{}");
         assert_eq!(result.as_deref(), Ok("<p>Hello</p>"));
     }
 
     #[test]
     fn test_signal_substitution() {
-        let result = render_inner("Hello, {{name}}!", r#"{"name": "WebUI"}"#);
+        let proto = build_protocol("Hello, {{name}}!");
+        let result = render_to_string(&proto, r#"{"name": "WebUI"}"#);
         assert_eq!(result.as_deref(), Ok("Hello, WebUI!"));
     }
 
     #[test]
     fn test_for_loop() {
-        let html = "<ul><for each=\"item in items\"><li>{{item}}</li></for></ul>";
-        let state = r#"{"items": ["a", "b", "c"]}"#;
-        let result = render_inner(html, state);
+        let proto = build_protocol("<ul><for each=\"item in items\"><li>{{item}}</li></for></ul>");
+        let result = render_to_string(&proto, r#"{"items": ["a", "b", "c"]}"#);
         assert_eq!(
             result.as_deref(),
             Ok("<ul><li>a</li><li>b</li><li>c</li></ul>")
@@ -123,54 +156,58 @@ mod tests {
 
     #[test]
     fn test_if_condition_true() {
-        let html = "<if condition=\"show\"><p>Visible</p></if>";
-        let result = render_inner(html, r#"{"show": true}"#);
+        let proto = build_protocol("<if condition=\"show\"><p>Visible</p></if>");
+        let result = render_to_string(&proto, r#"{"show": true}"#);
         assert_eq!(result.as_deref(), Ok("<p>Visible</p>"));
     }
 
     #[test]
     fn test_if_condition_false() {
-        let html = "<if condition=\"show\"><p>Hidden</p></if>";
-        let result = render_inner(html, r#"{"show": false}"#);
+        let proto = build_protocol("<if condition=\"show\"><p>Hidden</p></if>");
+        let result = render_to_string(&proto, r#"{"show": false}"#);
         assert_eq!(result.as_deref(), Ok(""));
     }
 
     #[test]
     fn test_html_escaping() {
-        let html = "<div>{{content}}</div>";
+        let proto = build_protocol("<div>{{content}}</div>");
         let state = r#"{"content": "<script>alert('xss')</script>"}"#;
-        let result = render_inner(html, state).expect("render should succeed");
+        let result = render_to_string(&proto, state).expect("render should succeed");
         assert!(!result.contains("<script>"));
         assert!(result.contains("&lt;script&gt;"));
     }
 
     #[test]
     fn test_raw_signal() {
-        let html = "<div>{{{content}}}</div>";
-        let state = r#"{"content": "<b>bold</b>"}"#;
-        let result = render_inner(html, state);
+        let proto = build_protocol("<div>{{{content}}}</div>");
+        let result = render_to_string(&proto, r#"{"content": "<b>bold</b>"}"#);
         assert_eq!(result.as_deref(), Ok("<div><b>bold</b></div>"));
     }
 
     #[test]
     fn test_invalid_json() {
-        let result = render_inner("<p>hi</p>", "NOT JSON");
+        let proto = build_protocol("<p>hi</p>");
+        let result = render_to_string(&proto, "NOT JSON");
         assert!(result.is_err());
-        let err = result.unwrap_err().to_string();
-        assert!(err.contains("State JSON error"), "Unexpected error: {err}");
     }
 
     #[test]
     fn test_empty_state() {
-        let result = render_inner("<p>static</p>", "{}");
+        let proto = build_protocol("<p>static</p>");
+        let result = render_to_string(&proto, "{}");
         assert_eq!(result.as_deref(), Ok("<p>static</p>"));
     }
 
     #[test]
     fn test_nested_object_signal() {
-        let html = "{{user.name}}";
-        let state = r#"{"user": {"name": "Alice"}}"#;
-        let result = render_inner(html, state);
+        let proto = build_protocol("{{user.name}}");
+        let result = render_to_string(&proto, r#"{"user": {"name": "Alice"}}"#);
         assert_eq!(result.as_deref(), Ok("Alice"));
     }
+
+    #[test]
+    fn test_invalid_protobuf() {
+        let result = render_to_string(&[0xFF, 0xFF, 0xFF], "{}");
+        assert!(result.is_err());
+    }
 }

examples/integration/node-express/src/hmr.js

@@ -5,18 +5,18 @@ import fs from "node:fs";
 /**
  * Return the HMR version string (latest mtime in ms since epoch).
  *
- * @param {string} templatePath - Path to the template file
+ * @param {string} protocolBinPath - Path to the protocol.bin file
  * @param {string} dataPath - Path to the data file
  * @returns {string} Milliseconds since epoch, or "0"
  */
-export function hmrVersion(templatePath, dataPath) {
+export function hmrVersion(protocolBinPath, dataPath) {
   let latest = 0;
 
   try {
-    const tStat = fs.statSync(templatePath);
+    const tStat = fs.statSync(protocolBinPath);
     latest = Math.max(latest, tStat.mtimeMs);
   } catch {
-    // Template file may not exist
+    // Protocol file may not exist
   }
 
   try {

examples/integration/node-express/src/index.js

@@ -12,7 +12,7 @@ import { fileURLToPath } from "node:url";
 import express from "express";
 import minimist from "minimist";
 
-import { renderToIndexHtml } from "./render.js";
+import { renderToResponse } from "./render.js";
 import { startFileWatcher } from "./watcher.js";
 import { indexRoute } from "./routes/index.js";
 import { assetsRoute } from "./routes/assets.js";
@@ -35,27 +35,27 @@ function main() {
     process.exit(1);
   }
 
+  // Protocol must be pre-built by `webui build`
+  const protocolBin = path.join(appDir, "dist", "protocol.bin");
+  if (!fs.existsSync(protocolBin)) {
+    process.stderr.write(
+      `  ✘ Protocol not found: ${protocolBin}\n` +
+        `  hint: Run 'cargo run -p webui-cli -- build ${path.join(appDir, "templates")} --out ${path.join(appDir, "dist")}' first\n`,
+    );
+    process.exit(1);
+  }
+
   const paths = {
-    template: path.join(appDir, "templates", "index.html"),
+    protocolBin,
     data: path.join(appDir, "data", "state.json"),
     assetsDir: path.join(appDir, "assets"),
-    distDir: path.resolve(__dirname, "..", "dist"),
   };
 
   // Styled console output (mirrors Rust Printer)
   process.stderr.write(`\n  ⚡ WebUI Express Server\n`);
   process.stderr.write(`  ▸ App       ${args.app}\n`);
   process.stderr.write(`  ▸ Directory ${appDir}\n`);
 
-  // Initial render
-  try {
-    renderToIndexHtml(paths);
-    process.stderr.write(`  ✔ Initial render complete\n`);
-  } catch (err) {
-    process.stderr.write(`  ✘ Initial render failed: ${err.message}\n`);
-    process.exit(1);
-  }
-
   // Start file watcher for HMR
   startFileWatcher(paths);
   process.stderr.write(`  ✔ File watcher started\n`);