@barefootjs/rust 0.1.0

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@barefootjs/rust",
+  "version": "0.1.0",
+  "description": "minijinja (Rust) adapter for BarefootJS — compiles IR to .j2 templates and ships a Rust rendering runtime (packages/adapter-rust/runtime/); runs under any Rust web framework (axum, etc.)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./adapter": {
+      "types": "./dist/adapter/index.d.ts",
+      "import": "./dist/adapter/index.js"
+    },
+    "./test-render": {
+      "bun": "./src/test-render.ts"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "runtime",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run build:js && bun run build:types",
+    "build:js": "bun build ./src/index.ts ./src/adapter/index.ts ./src/build.ts --root ./src --outdir ./dist --format esm --external @barefootjs/jsx --external @barefootjs/shared",
+    "build:types": "tsgo --emitDeclarationOnly --outDir ./dist",
+    "test": "bun test",
+    "clean": "rm -rf dist",
+    "prepack": "node ../../scripts/swap-publish-config.mjs pack",
+    "postpack": "node ../../scripts/swap-publish-config.mjs unpack"
+  },
+  "keywords": [
+    "jinja",
+    "jinja2",
+    "minijinja",
+    "rust",
+    "axum",
+    "barefoot",
+    "ssr"
+  ],
+  "author": "kobaken <kentafly88@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/piconic-ai/barefootjs",
+    "directory": "packages/adapter-rust"
+  },
+  "dependencies": {
+    "@barefootjs/shared": "0.17.1"
+  },
+  "peerDependencies": {
+    "@barefootjs/jsx": ">=0.2.0"
+  },
+  "devDependencies": {
+    "@barefootjs/adapter-tests": "0.1.0",
+    "@barefootjs/jsx": "0.17.1",
+    "typescript": "^5.0.0"
+  }
+}

package/runtime/Cargo.lock

@@ -0,0 +1,124 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "barefootjs"
+version = "0.1.0"
+dependencies = [
+ "minijinja",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
+
+[[package]]
+name = "memo-map"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "38d1115007560874e373613744c6fba374c17688327a71c1476d1a5954cc857b"
+
+[[package]]
+name = "minijinja"
+version = "2.21.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb3d648e68cea56d9858d535ee28f9538404e2dd8cb08ed0bd05dca379477f39"
+dependencies = [
+ "memo-map",
+ "serde",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"

package/runtime/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "barefootjs"
+version = "0.1.0"
+edition = "2021"
+description = "Rust runtime for BarefootJS marked templates (minijinja adapter)."
+license = "MIT"
+
+[lib]
+name = "barefootjs"
+path = "src/lib.rs"
+
+[[bin]]
+name = "bf-render"
+path = "src/bin/bf-render.rs"
+
+[dependencies]
+minijinja = { version = "2", features = ["loader"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = { version = "1", features = ["float_roundtrip"] }
+
+[dev-dependencies]

package/runtime/src/backend_minijinja.rs

@@ -0,0 +1,176 @@
+//! minijinja `Environment` construction, the custom formatter, canonical
+//! JSON encoding, and named-template rendering.
+//!
+//! Port of `packages/adapter-jinja/python/barefootjs/backend_jinja.py`'s
+//! four engine-specific operations the runtime delegates to
+//! (`encode_json`, `mark_raw`, `materialize`, `render_named`) -- adjusted
+//! for the design contract's minijinja Environment shape (see the design
+//! doc's "minijinja Environment contract" section, verified against
+//! minijinja 2.21.0):
+//!
+//!   * `ChainableUndefined` equivalent: [`UndefinedBehavior::Chainable`].
+//!   * `trim_blocks` / `lstrip_blocks`: both `true` (Jinja2 parity).
+//!   * `.j2` is NOT auto-escaped by minijinja's own extension-sniffing
+//!     default, so [`Environment::set_auto_escape_callback`] forces
+//!     `AutoEscape::Html` unconditionally.
+//!   * A custom [`Environment::set_formatter`] absorbs JS/minijinja
+//!     semantic differences UNIFORMLY (no per-fixture hacks): `undefined`/
+//!     `none` print nothing, safe values pass through raw, strings escape
+//!     with MarkupSafe-compatible entities (`'` for `'`, NOT
+//!     minijinja's default `'` -- fixtures pin `'`), numbers
+//!     format via [`crate::num::format_js_number`] (a fallback: templates
+//!     normally route through `bf.string()` first), bools print
+//!     `true`/`false`.
+//!
+//! `materialize` has no Rust analogue: JSX children are captured via
+//! minijinja `{% set %}...{% endset %}` blocks, which always yield a
+//! concrete rendered `Value::from_safe_string` (never a lazy callable, no
+//! `bf-render` payload path constructs one either), so there is nothing to
+//! resolve.
+
+use crate::num::{self, JsValue};
+use crate::runtime;
+use minijinja::value::Value as MjValue;
+use minijinja::{escape_formatter, path_loader, AutoEscape, Environment, Error, Output, State, UndefinedBehavior};
+use std::collections::BTreeMap;
+use std::path::Path;
+
+/// Build the minijinja `Environment` per the design contract. `templates_dir`
+/// contains `<snake_case>.j2` files loaded by base name (no `templates/`
+/// prefix, no extension) via [`Environment::get_template`].
+pub fn build_environment(templates_dir: &Path) -> Environment<'static> {
+    let mut env = Environment::new();
+    env.set_loader(path_loader(templates_dir));
+    env.set_undefined_behavior(UndefinedBehavior::Chainable);
+    env.set_trim_blocks(true);
+    env.set_lstrip_blocks(true);
+    env.set_auto_escape_callback(|_name| AutoEscape::Html);
+    env.set_formatter(bf_formatter);
+    env
+}
+
+/// MarkupSafe-compatible escape for plain (non-safe) string interpolation:
+/// `&` `&amp;`, `<` `&lt;`, `>` `&gt;`, `"` `&quot;`, `'` `&#39;`. The ONLY
+/// divergence from minijinja's own default HTML escaper
+/// (`crate::utils::write_escaped` in the minijinja source) is the
+/// apostrophe entity (minijinja default: `&#x27;`) -- everything else
+/// matches minijinja's own table already, kept explicit here so the whole
+/// policy lives in one place next to the formatter that uses it.
+///
+/// NOT the same escaper as `runtime::html_escape` (used by `spread_attrs` /
+/// `hydration_attrs` / `data_key_attr`'s raw attribute-syntax construction),
+/// which uses `&#34;` for `"` (matching Go's `template.HTMLEscapeString`
+/// byte-for-byte so SSR output stays identical across adapters). Two
+/// call sites, two historically-pinned entity choices; unifying them is
+/// out of scope for this port.
+fn markupsafe_escape(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    for c in s.chars() {
+        match c {
+            '&' => out.push_str("&amp;"),
+            '<' => out.push_str("&lt;"),
+            '>' => out.push_str("&gt;"),
+            '"' => out.push_str("&quot;"),
+            '\'' => out.push_str("&#39;"),
+            _ => out.push(c),
+        }
+    }
+    out
+}
+
+fn bf_formatter(out: &mut Output, state: &State, value: &MjValue) -> Result<(), Error> {
+    if value.is_undefined() || value.is_none() {
+        return Ok(());
+    }
+    if value.is_safe() {
+        out.write_str(value.as_str().unwrap_or_default()).map_err(Error::from)?;
+        return Ok(());
+    }
+    match value.kind() {
+        minijinja::value::ValueKind::Bool => {
+            out.write_str(if value.is_true() { "true" } else { "false" }).map_err(Error::from)?;
+        }
+        minijinja::value::ValueKind::Number => {
+            let n = f64::try_from(value.clone()).unwrap_or(f64::NAN);
+            out.write_str(&num::format_js_number(n)).map_err(Error::from)?;
+        }
+        minijinja::value::ValueKind::String => {
+            out.write_str(&markupsafe_escape(value.as_str().unwrap_or(""))).map_err(Error::from)?;
+        }
+        // Arrays/maps/objects are never interpolated directly by generated
+        // templates (they always go through `bf.json` / `bf.string` /
+        // `bf.spread_attrs` first) -- fall back to minijinja's own default
+        // rendering for defensive completeness.
+        _ => escape_formatter(out, state, value)?,
+    }
+    Ok(())
+}
+
+/// Canonical JSON encoding for `bf.json` / `bf-p` / `bf-scope`: sorted keys
+/// (free, since [`JsValue::Object`] is a `BTreeMap`), compact separators
+/// (`serde_json::to_string`'s default), non-finite floats -> JSON `null`
+/// recursively (`JsValue::to_json`'s documented contract -- see `num.rs`).
+pub fn encode_json(v: &JsValue) -> String {
+    serde_json::to_string(&v.to_json()).expect("JsValue::to_json always produces a JSON-encodable document")
+}
+
+fn build_context(bf_value: MjValue, vars: &JsValue) -> BTreeMap<String, MjValue> {
+    let mut ctx = BTreeMap::new();
+    if let Some(map) = vars.as_object() {
+        for (k, v) in map {
+            ctx.insert(runtime::mangle_ident(k), runtime::js_to_mj(v));
+        }
+    }
+    ctx.insert("bf".to_string(), bf_value);
+    ctx
+}
+
+/// Render `<name>.j2` with `bf_value` bound as the `bf` variable, plus the
+/// supplied template vars (keyword-mangled -- the one point every props
+/// dict is turned into template variables). Used for the top-level entry
+/// render (`bf-render`'s own `env`, no template is executing yet).
+pub fn render_named(env: &Environment<'static>, template_name: &str, bf_value: MjValue, vars: &JsValue) -> Result<String, Error> {
+    let template = env.get_template(&format!("{template_name}.j2"))?;
+    template.render(build_context(bf_value, vars))
+}
+
+/// Same as [`render_named`] but sourced from a `State` -- the re-entrant
+/// path `bf.render_child` uses to render a child template from WITHIN an
+/// already-executing template, via `state.env()`.
+pub fn render_named_from_state(state: &State, template_name: &str, bf_value: MjValue, vars: &JsValue) -> Result<String, Error> {
+    let template = state.env().get_template(&format!("{template_name}.j2"))?;
+    template.render(build_context(bf_value, vars))
+}
+
+/// Like [`render_named_from_state`], but `vars` are ALREADY
+/// `minijinja::Value`s with ALREADY keyword-mangled keys (built by
+/// `render_child`), rather than a `JsValue` document to mangle-and-convert
+/// here. This is the child-render path: `render_child` must keep props as
+/// `Value` end-to-end so a safe (JSX children) value survives -- routing
+/// through `&JsValue`/[`build_context`] would strip the safe flag off any
+/// safe-string entry (see `runtime::BfInstance::render_child`'s docstring).
+pub fn render_named_from_state_values(
+    state: &State,
+    template_name: &str,
+    bf_value: MjValue,
+    mut vars: BTreeMap<String, MjValue>,
+) -> Result<String, Error> {
+    let template = state.env().get_template(&format!("{template_name}.j2"))?;
+    vars.insert("bf".to_string(), bf_value);
+    template.render(vars)
+}
+
+/// Like [`render_named`], plus extra raw `minijinja::Value` context entries
+/// (keyword-mangled like every other var) inserted after the `vars`-derived
+/// ones. Used by `bf-render`'s entry point to bind `searchParams` -- a
+/// [`crate::search_params::SearchParams`] `Object`, which has no
+/// [`JsValue`] representation (it isn't a JSON-shaped value), so it can't
+/// flow through the normal `vars: &JsValue` path.
+pub fn render_entry(env: &Environment<'static>, template_name: &str, bf_value: MjValue, vars: &JsValue, extra_vars: &[(String, MjValue)]) -> Result<String, Error> {
+    let template = env.get_template(&format!("{template_name}.j2"))?;
+    let mut ctx = build_context(bf_value, vars);
+    for (k, v) in extra_vars {
+        ctx.insert(runtime::mangle_ident(k), v.clone());
+    }
+    template.render(ctx)
+}

package/runtime/src/bin/bf-render.rs

@@ -0,0 +1,147 @@
+//! Conformance renderer binary: `bf-render <path-to-payload.json>`.
+//!
+//! Implements the bf-render payload protocol (design doc, "bf-render
+//! payload protocol" section) verbatim. HTML -> stdout on success; on
+//! error, a message -> stderr and exit 1.
+//!
+//! Non-finite numbers (JSON cannot spell NaN/Infinity) travel as
+//! `{"__bf_special": "nan" | "inf" | "-inf"}` sentinel objects, decoded
+//! recursively AFTER `serde_json` parses the document (the TS side
+//! transforms values recursively BEFORE `JSON.stringify`; this binary is
+//! the mirror-image decode step).
+
+use barefootjs::backend_minijinja;
+use barefootjs::num::JsValue;
+use barefootjs::runtime::{js_to_mj, BfInstance, ChildRendererSpec, RenderSession};
+use barefootjs::search_params::SearchParams;
+use minijinja::value::Value as MjValue;
+use serde::Deserialize;
+use serde_json::Value as JsonValue;
+use std::path::PathBuf;
+use std::process::ExitCode;
+use std::sync::Arc;
+
+#[derive(Deserialize)]
+struct ChildPayload {
+    name: String,
+    template: String,
+    #[serde(default)]
+    ssr_defaults: JsonValue,
+    #[serde(default)]
+    rest_props_name: Option<String>,
+    #[serde(default)]
+    param_names: Vec<String>,
+}
+
+#[derive(Deserialize)]
+struct Payload {
+    templates_dir: String,
+    entry: String,
+    scope_id: String,
+    #[serde(default)]
+    vars: JsonValue,
+    #[serde(default)]
+    search_params: Option<String>,
+    #[serde(default)]
+    children: Vec<ChildPayload>,
+}
+
+/// Recursively decode a parsed JSON document into the working [`JsValue`]
+/// domain, resolving `{"__bf_special": "nan" | "inf" | "-inf"}` sentinel
+/// objects into real non-finite `f64`s along the way -- these are the ONE
+/// shape `serde_json::Value` cannot carry natively (see `num.rs`'s module
+/// docstring), so decoding happens here rather than via
+/// `JsValue::from_json` (which has no sentinel to look for -- ordinary
+/// JSON documents never need one).
+fn decode_value(v: &JsonValue) -> JsValue {
+    if let JsonValue::Object(map) = v {
+        if map.len() == 1 {
+            if let Some(JsonValue::String(kind)) = map.get("__bf_special") {
+                let n = match kind.as_str() {
+                    "nan" => f64::NAN,
+                    "inf" => f64::INFINITY,
+                    "-inf" => f64::NEG_INFINITY,
+                    _ => f64::NAN,
+                };
+                return JsValue::Number(n);
+            }
+        }
+        return JsValue::Object(map.iter().map(|(k, v)| (k.clone(), decode_value(v))).collect());
+    }
+    match v {
+        JsonValue::Null => JsValue::Null,
+        JsonValue::Bool(b) => JsValue::Bool(*b),
+        JsonValue::Number(n) => JsValue::Number(n.as_f64().unwrap_or(f64::NAN)),
+        JsonValue::String(s) => JsValue::String(s.clone()),
+        JsonValue::Array(a) => JsValue::Array(a.iter().map(decode_value).collect()),
+        JsonValue::Object(_) => unreachable!("handled above"),
+    }
+}
+
+fn run(payload_path: &str) -> Result<String, String> {
+    let text = std::fs::read_to_string(payload_path).map_err(|e| format!("failed to read {payload_path}: {e}"))?;
+    let payload: Payload = serde_json::from_str(&text).map_err(|e| format!("invalid payload JSON: {e}"))?;
+
+    let templates_dir = PathBuf::from(&payload.templates_dir);
+    let env = backend_minijinja::build_environment(&templates_dir);
+
+    let session = RenderSession::new();
+    for child in &payload.children {
+        session.register_child_renderer(
+            // Keyed by the snake_case template base name -- matches the
+            // literal `bf.render_child('<snake_name>', ...)` call sites the
+            // TS emitter generates (`toTemplateName(comp.name)`), mirroring
+            // `buildChildRenderers`'s `bf.register_child_renderer(snakeName, ...)`.
+            child.template.clone(),
+            ChildRendererSpec {
+                component_name: child.name.clone(),
+                template: child.template.clone(),
+                // Converted from JSON to `Value` HERE, at registration time
+                // -- `render_child` keeps props as `Value` end-to-end from
+                // this point on (see `ChildRendererSpec::ssr_defaults`'s
+                // docstring).
+                ssr_defaults: js_to_mj(&decode_value(&child.ssr_defaults)),
+                rest_props_name: child.rest_props_name.clone(),
+                param_names: child.param_names.clone(),
+            },
+        );
+    }
+
+    let root = BfInstance::root(Arc::clone(&session), payload.scope_id.clone());
+    let vars = decode_value(&payload.vars);
+
+    let mut extra: Vec<(String, MjValue)> = Vec::new();
+    if let Some(query) = &payload.search_params {
+        extra.push(("searchParams".to_string(), SearchParams::new(query).to_value()));
+    }
+
+    backend_minijinja::render_entry(&env, &payload.entry, root.as_mj_value(), &vars, &extra).map_err(|e| {
+        let mut msg = format!("{e:#}");
+        let mut source = std::error::Error::source(&e);
+        while let Some(s) = source {
+            msg.push_str(&format!("\ncaused by: {s}"));
+            source = s.source();
+        }
+        msg
+    })
+}
+
+fn main() -> ExitCode {
+    let payload_path = match std::env::args().nth(1) {
+        Some(p) => p,
+        None => {
+            eprintln!("usage: bf-render <path-to-payload.json>");
+            return ExitCode::FAILURE;
+        }
+    };
+    match run(&payload_path) {
+        Ok(html) => {
+            print!("{html}");
+            ExitCode::SUCCESS
+        }
+        Err(msg) => {
+            eprintln!("{msg}");
+            ExitCode::FAILURE
+        }
+    }
+}