feat(ui): add htmx ui foundation

Cargo.toml

@@ -14,6 +14,7 @@ default-members = [
 	"crates/serde",
 	"crates/serde-support",
 	"crates/hfs",
+	"crates/ui",
 	"crates/persistence",
 	"crates/rest",
 	"crates/sof",

crates/hfs/Cargo.toml

@@ -15,7 +15,7 @@ name = "hfs"
 path = "src/main.rs"
 
 [features]
-default = ["R4", "sqlite"]
+default = ["R4", "sqlite", "ui"]
 
 # FHIR version features
 R4 = ["helios-fhir/R4", "helios-rest/R4", "helios-audit/R4"]
@@ -25,6 +25,8 @@ R6 = ["helios-fhir/R6", "helios-rest/R6", "helios-audit/R6"]
 
 # Build options
 skip-r6-download = []
+ui = ["dep:helios-ui"]
+headless = []
 
 # Database backends
 sqlite = ["helios-rest/sqlite"]
@@ -56,6 +58,7 @@ helios-sof = { path = "../sof", version = "0.2.1", default-features = false }
 helios-auth = { path = "../auth", version = "0.2.1" }
 helios-audit = { path = "../audit", version = "0.2.1", default-features = false }
 helios-subscriptions = { path = "../subscriptions", version = "0.2.1", optional = true, default-features = false }
+helios-ui = { path = "../ui", version = "0.2.1", optional = true }
 
 # Export job controller
 dashmap = "6"

crates/hfs/src/main.rs

@@ -554,6 +554,9 @@ async fn serve(
     config: &ServerConfig,
     audit_state: Option<Arc<AuditMiddlewareState>>,
 ) -> anyhow::Result<()> {
+    #[cfg(all(feature = "ui", not(feature = "headless")))]
+    let app = helios_ui::mount(app, env!("CARGO_PKG_VERSION"));
+
     let addr = config.socket_addr();
     info!(address = %addr, "Server listening");
     let listener = tokio::net::TcpListener::bind(&addr).await?;

crates/ui/Cargo.toml

@@ -0,0 +1,29 @@
+[package]
+name = "helios-ui"
+version.workspace = true
+edition.workspace = true
+description = "Optional server-rendered HTMX web UI for the Helios FHIR Server"
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+homepage = "https://github.com/HeliosSoftware/hfs/tree/main/crates/ui"
+keywords = ["helios-software", "fhir", "ui", "htmx"]
+
+[dependencies]
+# Web framework (matches the version used by helios-hfs / helios-rest)
+axum = "0.8"
+
+# Compile-time, type-checked, auto-escaping templates (Jinja2-like).
+# Markup lives in templates/, never in Rust source.
+askama = "0.12"
+
+# Typed htmx header handling: the infallible `HxRequest` extractor for the
+# fragment-vs-full-page branch, and `AutoVaryLayer` for correct HTTP caching
+# (`Vary: HX-Request`) so an htmx fragment is never served for a hard navigation.
+axum-htmx = { version = "0.8", features = ["auto-vary"] }
+
+# Static assets (htmx, CSS) embedded into the binary at compile time so the
+# server has no runtime CDN dependency and works in air-gapped deployments.
+# `axum-embed` serves them with precompressed (br/gzip/deflate) negotiation.
+rust-embed = "8"
+axum-embed = "0.1"