Release v0.4.6: Flow DX, public/, PWA defaults, and SPA query navigation.

Adds loader_refresh_input, query_nav_link, public/ serving, theme→PWA,
flow-booking template, __resuma.navigate/buildUrl in core.js, and docs cookbook.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: GoldevLab

CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to this project will be documented in this file.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.4.6] - 2026-06-02
+
+Flow DX release: query navigation, `public/`, and booking scaffold.
+
+### Added
+
+- **`__resuma.navigate` / `__resuma.buildUrl`** on the default `core.js` runtime for SPA reloads when query params change (server `#[load]` re-runs).
+- **`loader_refresh_input`**, **`loader_refresh_form`**, **`query_nav_link`**, **`build_query_href`** — Rust helpers for query-driven pages.
+- **`public/` auto-serve** on `FlowApp` (defaults to `{CARGO_MANIFEST_DIR}/public`), with paths merged into PWA precache.
+- **`with_theme_pwa(Theme)`** — maps theme primary/background into auto PWA colors.
+- **PWA icons from `public/`** — `icons/icon-192.png` etc. override generated SVG manifest entries when present.
+- **`resuma new --template flow-booking`** — minimal appointments sample.
+- **`resuma dev --kill-stale`** (Linux) and `cargo watch` on `public/`.
+- Docs: [docs/FLOW_COOKBOOK.md](./docs/FLOW_COOKBOOK.md).
+
+### Fixed
+
+- **NavLink `active` after SPA navigation with query** — `/reservar` stays active on `/reservar?fecha=…` (Rust + `core.js`).
+- **PWA manifest icons from `public/`** — use the file’s real `Content-Type` (PNG/SVG).
+- **Clippy** — simplified CSP `from_env` toggle (CI `-D warnings`).
+
 ## [0.4.2] - 2026-05-31
 
 CLI onboarding patch release.

Cargo.toml

@@ -11,7 +11,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.4.5"
+version = "0.4.6"
 edition = "2021"
 rust-version = "1.91"
 authors = ["Resuma Contributors"]
@@ -25,7 +25,7 @@ categories = ["web-programming", "asynchronous"]
 readme = "README.md"
 
 [workspace.dependencies]
-resuma-macros = { path = "crates/resuma-macros", version = "0.4.5" }
+resuma-macros = { path = "crates/resuma-macros", version = "0.4.6" }
 
 # 3rd-party
 serde       = { version = "1", features = ["derive"] }

README.md

@@ -75,7 +75,7 @@ cd my-app
 resuma dev --open
 ```
 
-**Templates:** `basic` · `todo` · `flow` · `flow-fullstack`
+**Templates:** `basic` · `todo` · `flow` · `flow-booking` · `flow-fullstack`
 
 ```rust
 use resuma::prelude::*;

crates/resuma/assets/core.js

@@ -52,7 +52,7 @@ enum Commands {
     Doctor,
     /// Run the app with hot reload.
     Dev {
-        /// Bind address (default: 127.0.0.1:3000).
+        /// Bind address (default: 127.0.0.1:3000). If the port is taken, the next free port is used.
         #[arg(long, default_value = "127.0.0.1:3000")]
         addr: String,
         /// Open the default browser once the server starts.
@@ -61,6 +61,9 @@ enum Commands {
         /// Skip building the JS runtime (useful when prebuilt).
         #[arg(long)]
         skip_runtime: bool,
+        /// Kill any process listening on the dev port before starting (Linux).
+        #[arg(long)]
+        kill_stale: bool,
     },
     /// Build a production binary + JS bundles.
     Build {
@@ -108,7 +111,8 @@ pub fn run() -> Result<()> {
             addr,
             open,
             skip_runtime,
-        } => dev_command(&addr, open, skip_runtime),
+            kill_stale,
+        } => dev_command(&addr, open, skip_runtime, kill_stale),
         Commands::Build {
             static_export,
             out,
@@ -194,6 +198,20 @@ pub(crate) fn ensure_rust_toolchain() -> Result<()> {
     }
 }
 
+#[cfg(unix)]
+fn kill_stale_port(port: u16) {
+    let target = format!("{port}/tcp");
+    let status = Command::new("fuser").args(["-k", &target]).status();
+    if let Ok(s) = status {
+        if s.success() {
+            println!("[resuma] freed port {port}");
+        }
+    }
+}
+
+#[cfg(not(unix))]
+fn kill_stale_port(_port: u16) {}
+
 fn ensure_cargo_watch() -> Result<()> {
     let ok = Command::new("cargo")
         .args(["watch", "--version"])
@@ -217,13 +235,29 @@ fn ensure_cargo_watch() -> Result<()> {
     Ok(())
 }
 
-fn dev_command(addr: &str, open: bool, skip_runtime: bool) -> Result<()> {
+fn dev_command(addr: &str, open: bool, skip_runtime: bool, kill_stale: bool) -> Result<()> {
     ensure_rust_toolchain()?;
     ensure_cargo_watch()?;
     if !skip_runtime {
         ensure_runtime_built()?;
     }
 
+    let preferred: std::net::SocketAddr = addr
+        .parse()
+        .map_err(|_| anyhow!("invalid --addr {addr:?} (expected e.g. 127.0.0.1:3000)"))?;
+    if kill_stale {
+        kill_stale_port(preferred.port());
+    }
+    let bound = crate::server::resolve_listen_addr(preferred)
+        .map_err(|e| anyhow!("could not bind {preferred}: {e}"))?;
+    if bound != preferred {
+        println!(
+            "[resuma] port {} in use, using http://{}",
+            preferred.port(),
+            bound
+        );
+    }
+    let addr = bound.to_string();
     let url = format!("http://{}", addr);
     println!("[resuma] starting dev server at {}", url);
     if open {
@@ -233,11 +267,12 @@ fn dev_command(addr: &str, open: bool, skip_runtime: bool) -> Result<()> {
 
     let mut watch_args = vec![
         "watch".to_string(),
-        "-c".to_string(),
         "-q".to_string(),
         "-w".to_string(),
         "src".to_string(),
         "-w".to_string(),
+        "public".to_string(),
+        "-w".to_string(),
         "Cargo.toml".to_string(),
     ];
     #[cfg(windows)]

crates/resuma/assets/runtime.js

@@ -35,6 +35,7 @@ const TEMPLATE_CHOICES: &[(&str, &str)] = &[
     ("basic", "static SSR page, zero client JS"),
     ("todo", "full showcase (signals, server, islands)"),
     ("flow", "multi-page app with src/pages/"),
+    ("flow-booking", "appointments + query-driven #[load]"),
     ("flow-fullstack", "Flow + SQLx SQLite sample"),
 ];
 
@@ -49,10 +50,11 @@ pub fn prompt_template() -> Result<String> {
             "" | "1" => "basic",
             "2" => "todo",
             "3" => "flow",
-            "4" => "flow-fullstack",
+            "4" => "flow-booking",
+            "5" => "flow-fullstack",
             other if TEMPLATE_CHOICES.iter().any(|(id, _)| *id == other) => other,
             _ => {
-                eprintln!("  (pick 1–4 or type basic/todo/flow/flow-fullstack)");
+                eprintln!("  (pick 1–5 or type basic/todo/flow/flow-booking/flow-fullstack)");
                 continue;
             }
         };

crates/resuma/src/cli/mod.rs

@@ -80,6 +80,27 @@ const FLOW_ABOUT: &str = include_str!("../../templates/flow/pages/about.rs");
 const FLOW_MOD: &str = include_str!("../../templates/flow/pages/mod.rs");
 const FLOW_REGISTRY: &str = include_str!("../../templates/flow/pages/_registry.rs");
 
+const CARGO_FLOW_BOOKING: &str = r#"[package]
+name = "%NAME%"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+resuma = "%RESUMA_VERSION%"
+tokio  = { version = "1", features = ["full"] }
+serde  = { version = "1", features = ["derive"] }
+once_cell   = "1"
+parking_lot = "0.12"
+"#;
+
+const FLOW_BOOKING_MAIN: &str = include_str!("../../templates/flow-booking/main.rs");
+const FLOW_BOOKING_STORE: &str = include_str!("../../templates/flow-booking/booking_store.rs");
+const FLOW_BOOKING_MOD: &str = include_str!("../../templates/flow-booking/pages/mod.rs");
+const FLOW_BOOKING_REGISTRY: &str = include_str!("../../templates/flow-booking/pages/_registry.rs");
+const FLOW_BOOKING_INDEX: &str = include_str!("../../templates/flow-booking/pages/index.rs");
+const FLOW_BOOKING_BOOK: &str = include_str!("../../templates/flow-booking/pages/book.rs");
+const FLOW_BOOKING_GRACIAS: &str = include_str!("../../templates/flow-booking/pages/gracias.rs");
+
 const CARGO_FULLSTACK: &str = r#"[package]
 name = "%NAME%"
 version = "0.1.0"
@@ -115,6 +136,7 @@ Created with [Resuma](https://github.com/GolfredoPerezFernandez/resuma).
 - **todo** - full Resuma showcase (signals, server, island, security, js!)
 - **flow** - multi-page app with `src/pages/` and FlowApp
 - **flow-fullstack** - Flow + SQLx (SQLite) with users CRUD sample
+- **flow-booking** - appointments with query-driven `#[load]` + `loader_refresh_input`
 
 ## Develop
 
@@ -182,6 +204,30 @@ pub fn create_project(name: &str, template: &str) -> Result<()> {
             fs::write(pages.join("index.rs"), FLOW_INDEX).context("write pages/index.rs")?;
             fs::write(pages.join("about.rs"), FLOW_ABOUT).context("write pages/about.rs")?;
         }
+        "flow-booking" => {
+            fs::write(dir.join("Cargo.toml"), render_cargo(CARGO_FLOW_BOOKING, name))
+                .context("write Cargo.toml")?;
+            fs::write(
+                dir.join("src/main.rs"),
+                FLOW_BOOKING_MAIN.replace("%NAME%", name),
+            )
+            .context("write src/main.rs")?;
+            fs::write(dir.join("src/booking_store.rs"), FLOW_BOOKING_STORE)
+                .context("write src/booking_store.rs")?;
+            let pages = dir.join("src/pages");
+            fs::create_dir_all(&pages)?;
+            fs::write(pages.join("mod.rs"), FLOW_BOOKING_MOD).context("write pages/mod.rs")?;
+            fs::write(pages.join("_registry.rs"), FLOW_BOOKING_REGISTRY)
+                .context("write pages/_registry.rs")?;
+            fs::write(pages.join("index.rs"), FLOW_BOOKING_INDEX.replace("%NAME%", name))
+                .context("write pages/index.rs")?;
+            fs::write(pages.join("book.rs"), FLOW_BOOKING_BOOK).context("write pages/book.rs")?;
+            fs::write(pages.join("gracias.rs"), FLOW_BOOKING_GRACIAS)
+                .context("write pages/gracias.rs")?;
+            let public = dir.join("public");
+            fs::create_dir_all(&public)?;
+            fs::write(public.join(".gitkeep"), "").ok();
+        }
         "flow-fullstack" => {
             fs::write(dir.join("Cargo.toml"), render_cargo(CARGO_FULLSTACK, name))
                 .context("write Cargo.toml")?;
@@ -205,7 +251,7 @@ pub fn create_project(name: &str, template: &str) -> Result<()> {
         }
         other => {
             return Err(anyhow!(
-                "unknown template `{}` (try: basic, todo, flow, flow-fullstack)",
+                "unknown template `{}` (try: basic, todo, flow, flow-booking, flow-fullstack)",
                 other
             ));
         }
@@ -230,7 +276,13 @@ mod tests {
 
     #[test]
     fn cargo_templates_pin_the_cli_crate_version() {
-        for cargo_template in [CARGO_BASIC, CARGO_TODO, CARGO_FLOW, CARGO_FULLSTACK] {
+        for cargo_template in [
+            CARGO_BASIC,
+            CARGO_TODO,
+            CARGO_FLOW,
+            CARGO_FLOW_BOOKING,
+            CARGO_FULLSTACK,
+        ] {
             let rendered = render_cargo(cargo_template, "smoke-app");
             assert!(rendered.contains("name = \"smoke-app\""));
             assert!(rendered.contains(&format!("\"{}\"", env!("CARGO_PKG_VERSION"))));

crates/resuma/src/cli/prompt.rs

@@ -49,11 +49,46 @@ fn paths_match(href: &str, current: &str) -> bool {
     if href == current {
         return true;
     }
-    if href != "/" && current.starts_with(href) {
-        return current
+    let (href_path, href_query) = split_path_query(href);
+    let (cur_path, cur_query) = split_path_query(current);
+    if href_query.is_some() {
+        return href_path == cur_path && href_query == cur_query;
+    }
+    if href_path == cur_path {
+        return true;
+    }
+    if href_path != "/" && cur_path.starts_with(href_path) {
+        return cur_path
             .as_bytes()
-            .get(href.len())
+            .get(href_path.len())
             .is_none_or(|b| *b == b'/');
     }
     false
 }
+
+fn split_path_query(s: &str) -> (&str, Option<&str>) {
+    match s.split_once('?') {
+        Some((path, query)) => (path, Some(query)),
+        None => (s, None),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::paths_match;
+
+    #[test]
+    fn path_only_active_with_query_on_current() {
+        assert!(paths_match("/reservar", "/reservar?fecha=2026-06-02"));
+    }
+
+    #[test]
+    fn query_href_requires_exact_match() {
+        assert!(paths_match(
+            "/book?fecha=1",
+            "/book?fecha=1"
+        ));
+        assert!(!paths_match("/book?fecha=1", "/book?fecha=2"));
+        assert!(!paths_match("/book?fecha=1", "/book"));
+    }
+}