@ape-egg/vibe 2.0.5 → 2.1.3

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [2.1.3] - 2026-06-18
+
+### Added
+
+- **Compiler 1.8.2 → 1.9.0 — `skipFiles` config option** (`compiler/src/config.rs`, `compiler/src/compiler/compile.rs`, `compiler/src/compiler/watcher.rs`, `compiler/src/main.rs`) — projects can now add their own exclude patterns on top of the compiler's built-in skip list (test files, `*.config.js`, `node_modules`, dotfiles, build dirs). Like `reservedElements`, user values **append** to the built-ins rather than replacing them, so the sensible defaults always hold. `Config::load` merges the built-in `SKIP_FILES` const with the user array into one effective `config.skip_files`, which is now threaded into `should_skip_path` at every call site (compile pass + watch mode) instead of the function reading a hard-coded const. Matching: a bare name (`server`) matches any file or directory with that name; a pattern containing `*` is a glob (`**/*.bak`) matched against both filename and full path; dotfiles are always skipped. This removes the need for app-side post-build pruning of directories the deploy never serves (a backend `server/`, build `scripts/`, a stale `dist/`). Config-only (no CLI flag, like `reservedElements`); surfaced in `--verbose` output. Repro: `tests/compiler/skip-files`.
+- Docs: the compiler **Configuration** page documents `skipFiles` (example config + full section) and adds two collapsible panels revealing the built-in `reservedElements` and `skipFiles` default lists.
+
+## [2.1.2] - 2026-06-18
+
+### Fixed
+
+- **Compiler 1.8.0 → 1.8.1 — `--minify` mangled tags whose attributes span multiple lines** (`compiler/src/compiler/compile.rs`) — `minify_html` joined trimmed source lines with no separator, so a newline *inside* a tag vanished instead of collapsing to a space. A multi-line `<meta name="viewport" content="...">` became `<metaname="viewport"content="...">`, which the downstream stamping stage then re-parsed into deeper garbage (`initial-scale="1.0,"`, `&quot;`, a bogus `</metaname...>` close). The inter-line break is now collapsed to a single space like any other whitespace run; the existing `>\s+<` → `><` pass re-tightens genuine tag boundaries. Generic fix — applies to any multi-line tag or text node, not just `<meta>`. Repro: `tests/compiler/minify-meta`.
+
+## [2.1.1] - 2026-06-18
+
+### Added
+
+- **`[Fet(ca)ched]` debug event for cache hits** (`runtime/debug.js`, `runtime/constants.js`, `runtime/component.js`, `runtime/component-cache.js`) — in debug mode, a `<component src>` served from the runtime template cache now logs `[Fet(ca)ched]` instead of `[Fetched]`, so a real network fetch and a cache hit are visually distinct at a glance (both share the same purple). `component-cache.js` exposes `isComponentCached(src)`, captured before the fetch so the debug layer can tell the two apart. The phase-bracket padding widened 13 → 14 to keep `[Fet(ca)ched]` column-aligned with the other events.
+
+## [2.1.0] - 2026-06-17
+
+### Added
+
+- **Component template cache** (`runtime/component-cache.js`, new) — Vibe now caches each fetched `<component src>` template by `src` instead of refetching it per instance. A page that mounts the same component many times, or an SPA that re-mounts components on navigation, previously issued one network request per instance; it now issues **one per unique template**. Two mechanisms in one small module:
+  - **In-flight coalescing** — the fetch *promise* is cached synchronously before its first `await`, so a burst of same-tick mounts of the same `src` shares a single request instead of stampeding the network. This is something a browser HTTP cache structurally cannot do (a cold cache can't dedupe concurrent requests for the same URL).
+  - **Session-lived reuse** — later mounts, including after SPA navigation, resolve from memory with no network request at all.
+
+  The cache is content-busted, never time-based: in production component templates are immutable for the life of the page, so there is nothing to invalidate and no staleness window. Per-instance props, slots, and component-local state are unaffected — only the template text is shared; each instance hydrates independently. Verified on a real page: a view that fetched 253 component files (41 unique) now fetches 41, with zero duplicate requests.
+  - New config flag `noCache: true` (`vibe(state, { noCache })`) disables it entirely.
+  - New public method `$.clearComponentCache(path?)` invalidates one entry (query string ignored) or all. `@ape-egg/vite-plugin-vibe` calls it on hot update so edits are reflected for freshly-mounted instances; the runtime stays free of dev-server coupling.
+  - Unit coverage: `tests/unit/component-cache.test.js` (coalescing, caching, eviction, `noCache`, non-ok/rejected responses not persisted).
+
 ## [2.0.5] - 2026-06-16
 
 ### Fixed

package/README.md

@@ -45,6 +45,7 @@ window.$ = vibe(state, config?, targetSelector?);
 
 - **`config`** *(object, optional)* — runtime configuration. Currently supported keys:
   - `debug` *(boolean, default `false`)* — colored console logs for every lifecycle phase (parse, hydrate, iterate, mutate, …). Useful for debugging reactivity issues.
+  - `noCache` *(boolean, default `false`)* — disable the component template cache (see **Component Template Caching** below). When set, every `<component src>` mount refetches its template.
 
 - **`targetSelector`** *(string, optional)* — CSS selector for the root element vibe attaches to. **Defaults to `document.body`.** Vibe parses, hydrates, and observes mutations only inside this root — anything outside (e.g. `<head>`, sibling `<aside>` elements) is ignored. If the selector matches nothing, vibe silently falls back to `document.body`. Pass `'html'` to include `<head>` (e.g. for binding `<title>@[pageTitle]</title>`).
 
@@ -216,6 +217,26 @@ How it works:
 
 Multiple drop-in blocks on the same page each get their own state bucket. They can read each other's state via global `$['_c0'].count` if they need to coordinate, but in most drop-in cases they're independent.
 
+### Component Template Caching
+
+Vibe loads a `<component src="...">` by fetching its HTML template. A page often mounts the same component many times (a list of cards, a row of stat bars), and an SPA re-mounts components on every navigation. By default Vibe caches each fetched template by `src`, so:
+
+- **Concurrent mounts coalesce.** Twenty `<component src="/components/Bar.html">` in the same render share **one** in-flight request instead of stampeding the network with twenty.
+- **Repeat mounts are free.** Later mounts — including after an SPA navigation away and back — resolve the template from memory with **no network request at all**. This is the one win a browser HTTP cache can't give you: it revalidates per request and never coalesces concurrent ones.
+
+The cache is **session-lived and content-busted, never time-based**. In production a component template is immutable for the life of the page (it only changes on redeploy, which is a new session), so there is nothing to invalidate and no staleness window. Per-instance props, slots, and component-local state are unaffected — only the fetched template text is shared; each instance still hydrates independently.
+
+Turn it off with `vibe(state, { noCache: true })` — useful if you serve component HTML that genuinely changes within a session.
+
+Manual invalidation (rarely needed):
+
+```javascript
+$.clearComponentCache('/components/Card.html'); // drop one template (query string ignored)
+$.clearComponentCache();                        // drop all cached templates
+```
+
+> Dev note: `@ape-egg/vite-plugin-vibe` calls `$.clearComponentCache(path)` on hot update, so editing a component file is reflected immediately for both live and freshly-mounted instances — the runtime itself stays free of any dev-server coupling.
+
 ### Lifecycle Hooks
 
 ```javascript

package/compiler/src/Cargo.lock

@@ -1599,7 +1599,7 @@ checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 
 [[package]]
 name = "vibe-compiler"
-version = "1.8.0"
+version = "1.9.0"
 dependencies = [
  "clap",
  "colored",

package/compiler/src/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "vibe-compiler"
-version = "1.8.0"
+version = "1.9.0"
 edition = "2021"
 description = "Vibe framework compiler - compiles Vibe source files into optimized output"
 authors = ["Kim Korte"]

package/compiler/src/compiler/compile.rs

@@ -12,6 +12,32 @@ use rayon::prelude::*;
 use crate::config::Config;
 use crate::parser::HtmlParser;
 
+/// Map an output-relative HTML path to the URL path the runtime resolves a
+/// manifest from. Strips the `root` dir (served at /) and collapses dynamic
+/// `$param` segments to a `$` token, e.g. with root `pages`:
+///   pages/armory.html        -> armory.html
+///   pages/the-arena/$id.html -> the-arena/$.html
+fn manifest_url_path(relative_path: &str, root: Option<&str>) -> String {
+    let stripped = match root {
+        Some(r) if relative_path == r => "",
+        Some(r) if relative_path.starts_with(&format!("{}/", r)) => &relative_path[r.len() + 1..],
+        _ => relative_path,
+    };
+
+    stripped
+        .split('/')
+        .map(|seg| match seg.strip_prefix('$') {
+            // $id.html -> $.html ; $id -> $
+            Some(rest) => match rest.find('.') {
+                Some(dot) => format!("${}", &rest[dot..]),
+                None => "$".to_string(),
+            },
+            None => seg.to_string(),
+        })
+        .collect::<Vec<_>>()
+        .join("/")
+}
+
 // =============================================================================
 // MIRROR_MODE: Copy asset files from source to output as-is, preserving
 // directory structure. HTML files are compiled separately.
@@ -38,7 +64,10 @@ const MIRROR_EXTENSIONS: &[&str] = &[
     "json", "xml", "csv",
 ];
 
-// Files and directories to skip when walking source (supports glob patterns)
+// Built-in files and directories to skip when walking source (supports glob
+// patterns). User-supplied `skipFiles` are appended to these in Config::load,
+// so the effective list lives on `config.skip_files` and is passed into
+// should_skip_path() at every call site.
 // Note: Output directory is checked dynamically (not hardcoded here)
 // Note: Dotfiles are handled by starts_with('.') check in should_skip_path()
 pub const SKIP_FILES: &[&str] = &[
@@ -53,20 +82,21 @@ pub const SKIP_FILES: &[&str] = &[
     "**/*.config.ts",    // Config files
 ];
 
-/// Check if a path should be skipped based on SKIP_FILES patterns
-pub fn should_skip_path(path: &Path, name: &str) -> bool {
+/// Check if a path should be skipped based on the effective skip patterns
+/// (built-in SKIP_FILES + user `skipFiles`, merged in Config::load).
+pub fn should_skip_path(path: &Path, name: &str, patterns: &[String]) -> bool {
     // Check if name starts with dot (dotfiles/directories)
     if name.starts_with('.') {
         return true;
     }
 
     // Check exact name match (for directories and simple filenames)
-    if SKIP_FILES.contains(&name) {
+    if patterns.iter().any(|p| p == name) {
         return true;
     }
 
     // Check glob patterns (e.g., **/*.test.js)
-    for pattern_str in SKIP_FILES {
+    for pattern_str in patterns {
         if pattern_str.contains('*') {
             if let Ok(pattern) = Pattern::new(pattern_str) {
                 // Try matching against just the filename
@@ -794,6 +824,7 @@ impl Compiler {
                 self.config.iterations_as_is,
                 self.config.components_as_is,
                 &self.config.source,
+                self.config.root.as_deref(),
             ) {
                 Ok(()) => {
                     pages_processed += 1;
@@ -826,6 +857,7 @@ impl Compiler {
         iterations_as_is: bool,
         components_as_is: bool,
         source_root: &Path,
+        manifest_root: Option<&str>,
     ) -> Result<(), String> {
         use crate::compiler::manifest_builder::ManifestBuilder;
         use crate::compiler::component_tagger::ComponentTagger;
@@ -841,10 +873,17 @@ impl Compiler {
         let manifest_builder = ManifestBuilder::new();
         let manifest = manifest_builder.build_from_html(html, &state, iterations_as_is)?;
 
+        // Map the output-relative path to the served-URL path: drop the `root`
+        // dir (the folder served at /, e.g. `pages`) and collapse dynamic
+        // `$param` segments to a single `$` token. This lets the runtime resolve
+        // a manifest from a clean URL — `/armory` and `/the-arena/123` find
+        // `armory.html.manifest.js` and `the-arena/$.html.manifest.js`.
+        let manifest_rel = manifest_url_path(relative_path, manifest_root);
+
         // Write manifest
         let manifest_path = output_dir
             .join("vibe-hyperspeed")
-            .join(format!("{}.manifest.js", relative_path));
+            .join(format!("{}.manifest.js", manifest_rel));
 
         // Ensure directory exists
         if let Some(parent) = manifest_path.parent() {
@@ -857,7 +896,7 @@ impl Compiler {
 
         let manifest_js = format!(
             "// Pre-compiled manifest for /{}\n// Generated by Vibe compiler\n\nexport default {};\n",
-            relative_path,
+            manifest_rel,
             manifest_json
         );
 
@@ -901,6 +940,7 @@ impl Compiler {
         let verbose = self.verbose;
         let iterations_as_is = self.config.iterations_as_is;
         let components_as_is = self.config.components_as_is;
+        let manifest_root = self.config.root.clone();
 
         let results: Vec<_> = html_files
             .par_iter()
@@ -917,7 +957,7 @@ impl Compiler {
                 };
 
                 // Try to generate manifest for this file (skip on error)
-                match Self::generate_file_manifest(&html, html_path, &output_dir, relative_path, verbose, iterations_as_is, components_as_is, &source_root) {
+                match Self::generate_file_manifest(&html, html_path, &output_dir, relative_path, verbose, iterations_as_is, components_as_is, &source_root, manifest_root.as_deref()) {
                     Ok(()) => (true, None),
                     Err(e) => {
                         if verbose {
@@ -974,7 +1014,7 @@ impl Compiler {
                 }
 
                 // Skip special directories
-                if should_skip_path(&path, file_name) {
+                if should_skip_path(&path, file_name, &self.config.skip_files) {
                     continue;
                 }
 
@@ -1059,7 +1099,7 @@ impl Compiler {
                 }
 
                 // Skip special directories
-                if should_skip_path(&path, file_name) {
+                if should_skip_path(&path, file_name, &self.config.skip_files) {
                     continue;
                 }
 
@@ -1093,7 +1133,7 @@ impl Compiler {
                 self.process_directory_assets_only(&path, &new_relative, canonical_output, canonical_source, stats)?;
             } else if let Some(ext) = path.extension().and_then(|e| e.to_str()) {
                 // Skip files matching skip patterns
-                if should_skip_path(&path, file_name) {
+                if should_skip_path(&path, file_name, &self.config.skip_files) {
                     continue;
                 }
 
@@ -1546,7 +1586,7 @@ impl Compiler {
             let file_name_str = file_name.to_string_lossy();
 
             // Skip specific directories/patterns (includes dotfiles via SKIP_FILES)
-            if should_skip_path(&path, &file_name_str) {
+            if should_skip_path(&path, &file_name_str, &self.config.skip_files) {
                 continue;
             }
 
@@ -1765,7 +1805,7 @@ impl Compiler {
             let file_name = path.file_name().unwrap().to_str().unwrap();
 
             // Skip files/directories matching skip patterns
-            if should_skip_path(&path, file_name) {
+            if should_skip_path(&path, file_name, &self.config.skip_files) {
                 continue;
             }
 
@@ -1945,7 +1985,16 @@ fn minify_html(html: &str) -> String {
         if in_pre {
             result.push_str(line);
             result.push('\n');
+            last_was_space = false;
         } else {
+            // The line break preceding this line is whitespace: collapse it to a
+            // single space so attributes/text split across lines don't glue
+            // together (e.g. a multi-line <meta name=... content=...> tag).
+            // The >\s+< pass below re-tightens genuine tag boundaries.
+            if !last_was_space && !result.is_empty() {
+                result.push(' ');
+                last_was_space = true;
+            }
             for c in trimmed.chars() {
                 if c.is_whitespace() {
                     if !last_was_space {

package/compiler/src/compiler/watcher.rs

@@ -128,11 +128,11 @@ fn to_kebab_case(s: &str) -> String {
 
 /// Check if a path should be blacklisted based on SKIP_FILES patterns
 /// This checks both the filename and all path components relative to source root
-fn is_path_blacklisted(path: &Path, source_root: &Path) -> bool {
+fn is_path_blacklisted(path: &Path, source_root: &Path, skip_files: &[String]) -> bool {
     let file_name = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
 
     // Check filename against blacklist
-    if should_skip_path(path, file_name) {
+    if should_skip_path(path, file_name, skip_files) {
         return true;
     }
 
@@ -140,7 +140,7 @@ fn is_path_blacklisted(path: &Path, source_root: &Path) -> bool {
     if let Ok(relative) = path.strip_prefix(source_root) {
         for component in relative.components() {
             if let Some(component_str) = component.as_os_str().to_str() {
-                if should_skip_path(path, component_str) {
+                if should_skip_path(path, component_str, skip_files) {
                     return true;
                 }
             }
@@ -159,7 +159,7 @@ pub fn build_dependency_graph(config: &Config) -> std::result::Result<Dependency
         .unwrap_or_else(|_| config.output.clone());
 
     // Scan all HTML files in source directory
-    scan_directory(&config.source, &config.source, &config.components, &canonical_output, &mut graph)?;
+    scan_directory(&config.source, &config.source, &config.components, &canonical_output, &config.skip_files, &mut graph)?;
 
     Ok(graph)
 }
@@ -169,6 +169,7 @@ fn scan_directory(
     source_root: &Path,
     components_dir: &str,
     output_dir: &Path,
+    skip_files: &[String],
     graph: &mut DependencyGraph,
 ) -> std::result::Result<(), std::io::Error> {
     if !dir.is_dir() {
@@ -190,11 +191,11 @@ fn scan_directory(
             }
 
             // Skip directories using shared skip logic
-            if should_skip_path(&path, file_name) {
+            if should_skip_path(&path, file_name, skip_files) {
                 continue;
             }
 
-            scan_directory(&path, source_root, components_dir, output_dir, graph)?;
+            scan_directory(&path, source_root, components_dir, output_dir, skip_files, graph)?;
         } else if let Some(ext) = path.extension() {
             if ext == "html" {
                 let html = std::fs::read_to_string(&path)?;
@@ -354,7 +355,7 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                         for event in events {
                             for path in &event.paths {
                                 // Skip blacklisted files/directories (check entire path, not just filename)
-                                if is_path_blacklisted(path, &config.source) {
+                                if is_path_blacklisted(path, &config.source, &config.skip_files) {
                                     continue;
                                 }
 
@@ -381,7 +382,7 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                             }
 
                             // Skip blacklisted files/directories
-                            if is_path_blacklisted(path, &config.source) {
+                            if is_path_blacklisted(path, &config.source, &config.skip_files) {
                                 continue;
                             }
 
@@ -487,7 +488,7 @@ pub fn watch(config: Config, verbose: bool) -> std::result::Result<(), Box<dyn s
                             }
 
                             // Skip blacklisted files/directories
-                            if is_path_blacklisted(path, &config.source) {
+                            if is_path_blacklisted(path, &config.source, &config.skip_files) {
                                 continue;
                             }
 

package/compiler/src/config.rs

@@ -35,6 +35,8 @@ pub struct VibeCompilerConfig {
     #[serde(default)]
     pub reserved_elements: Vec<String>,
     #[serde(default)]
+    pub skip_files: Vec<String>,
+    #[serde(default)]
     pub node_modules_as_is: bool,
     #[serde(default)]
     pub components_as_is: bool,
@@ -96,6 +98,7 @@ impl Default for VibeCompilerConfig {
             elements_as_is: false,
             source_maps: false,
             reserved_elements: vec![],
+            skip_files: vec![],
             node_modules_as_is: false,
             components_as_is: false,
             runtime_as_is: false,
@@ -115,11 +118,12 @@ pub struct Config {
     pub components: String,
     pub pages: String,
     pub _assets: String,
-    pub _root: Option<String>,
+    pub root: Option<String>,
     pub minify: bool,
     pub elements_as_is: bool,
     pub source_maps: bool,
     pub reserved_elements: Vec<String>,
+    pub skip_files: Vec<String>,
     pub node_modules_as_is: bool,
     pub components_as_is: bool,
     pub runtime_as_is: bool,
@@ -154,6 +158,13 @@ impl Config {
         let mut reserved_elements = get_default_reserved_elements();
         reserved_elements.extend(config.reserved_elements);
 
+        // Combine built-in skip patterns with user-provided ones (append, not replace)
+        let mut skip_files: Vec<String> = crate::compiler::compile::SKIP_FILES
+            .iter()
+            .map(|s| s.to_string())
+            .collect();
+        skip_files.extend(config.skip_files);
+
         Self {
             source,
             output,
@@ -162,11 +173,12 @@ impl Config {
             components: config.components,
             pages: config.pages,
             _assets: config.assets,
-            _root: config.root,
+            root: config.root,
             minify: config.minify,
             elements_as_is: config.elements_as_is,
             source_maps: config.source_maps,
             reserved_elements,
+            skip_files,
             node_modules_as_is: config.node_modules_as_is,
             components_as_is: config.components_as_is,
             runtime_as_is: config.runtime_as_is,

package/compiler/src/main.rs

@@ -204,6 +204,14 @@ fn main() {
             }
         }
 
+        fn format_list_preview(items: &[String]) -> String {
+            if items.len() <= 2 {
+                format!("{:?}", items)
+            } else {
+                format!("[{:?}, {:?}, ... + {} more]", items[0], items[1], items.len() - 2)
+            }
+        }
+
         // Alphabetically ordered with padding (longest key is "reservedElements" = 16 chars)
         println!("  {}: {}", format!("{:<16}", "assets").cyan(), format_value_no_flag(&config._assets));
         println!("  {}: {}", format!("{:<16}", "components").cyan(), format_value_no_flag(&config.components));
@@ -215,8 +223,9 @@ fn main() {
         println!("  {}: {}", format!("{:<16}", "output").cyan(), format_value_no_flag(&config._output_str));
         println!("  {}: {}", format!("{:<16}", "pages").cyan(), format_value_no_flag(&config.pages));
         println!("  {}: {}", format!("{:<16}", "reservedElements").cyan(), format_value_no_flag(format_reserved_elements(&config.reserved_elements)));
-        println!("  {}: {}", format!("{:<16}", "root").cyan(), format_value_no_flag(config._root.as_ref().map(|s| s.as_str()).unwrap_or("null")));
+        println!("  {}: {}", format!("{:<16}", "root").cyan(), format_value_no_flag(config.root.as_ref().map(|s| s.as_str()).unwrap_or("null")));
         println!("  {}: {}", format!("{:<16}", "runtimeAsIs").cyan(), format_bool_with_flag(config.runtime_as_is, overrides.runtime_as_is, original_runtime_as_is));
+        println!("  {}: {}", format!("{:<16}", "skipFiles").cyan(), format_value_no_flag(format_list_preview(&config.skip_files)));
         println!("  {}: {}", format!("{:<16}", "source").cyan(), format_value_no_flag(&config._source_str));
         println!("  {}: {}", format!("{:<16}", "sourceMaps").cyan(), format_bool_with_flag(config.source_maps, overrides.source_maps, original_source_maps));
         println!();

package/llms.txt

@@ -289,7 +289,7 @@ window.$ = vibe(
 
 **Parameters:**
 - `initialState` — object containing initial state values
-- `config` — optional object. Currently supports `{ debug: boolean }`. A third positional argument can pass a target selector (defaults to `body`).
+- `config` — optional object. Supports `{ debug: boolean, noCache: boolean }` (`noCache` disables the component template cache — components are otherwise fetched once per `src` and reused across instances/navigation). A third positional argument can pass a target selector (defaults to `body`).
 
 **Returns:** Reactive proxy. Assign it to `window.$` so inline event handlers and bindings can find it.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ape-egg/vibe",
-  "version": "2.0.5",
+  "version": "2.1.3",
   "type": "module",
   "description": "Runtime-first reactivity with optional compiler",
   "main": "index.js",

package/runtime/component-cache.js

@@ -0,0 +1,94 @@
+// Component template cache.
+//
+// Vibe loads each `<component src="...">` by fetching its HTML template. A page
+// commonly mounts the same component many times (a list of cards, a row of
+// stat bars), and an SPA re-mounts components on every navigation. Without a
+// cache, each instance — and each revisit — refetches an identical template,
+// and a burst of same-tick mounts stampedes the network with N concurrent
+// requests for one file.
+//
+// This module dedupes those fetches by `src`:
+//   - concurrent mounts in the same tick share one in-flight request, because
+//     the PROMISE (not the resolved text) is cached synchronously before the
+//     first await — so callers coalesce onto it instead of each starting their own
+//   - later mounts (including after SPA navigation) resolve from memory, with
+//     no network request at all — the one win a browser HTTP cache cannot
+//     provide, since it revalidates per request and never coalesces concurrent ones
+//
+// The cache is session-lived and content-busted, never time-busted. In
+// production a component template is immutable for the life of the page (it
+// only changes on redeploy, which is a new session anyway), so there is nothing
+// to invalidate. In development, tooling busts entries on file change via
+// `clearComponentCache(path)` — which keeps this module free of any dev/HMR
+// coupling; it never references the dev server or its events.
+//
+// Disable entirely with `vibe(state, { noCache: true })`.
+
+let enabled = true;
+
+// src -> Promise<string> (raw template HTML). Stores the in-flight promise so
+// concurrent callers coalesce; the resolved value is held by the promise, so a
+// settled entry is an instant cache hit on every later read.
+const templates = new Map();
+
+// Configure from the runtime config (`{ noCache }`). Called once at boot. When
+// caching is turned off we also drop anything already cached, so toggling at
+// runtime (e.g. between test cases) can't serve a stale hit.
+export const configureComponentCache = (config = {}) => {
+  enabled = !config?.noCache;
+  if (!enabled) templates.clear();
+};
+
+export const isComponentCacheEnabled = () => enabled;
+
+// True when `src` will resolve without a new network request — either a settled
+// template or an in-flight request this mount coalesces onto. Callers capture
+// this BEFORE fetchComponentTemplate so the debug layer can distinguish a real
+// network fetch from a cache hit.
+export const isComponentCached = (src) => enabled && templates.has(src);
+
+// Fetch a component template, deduped by `src`. Returns a Promise<string>.
+//
+// `signal` aborts the request when the host element is removed. It is honored
+// only on the uncached path: a shared cached fetch must NOT be aborted by one
+// element unmounting while other elements still await the same template. The
+// caller already re-checks `el.parentNode` after the fetch settles, so dropping
+// the abort on the shared path costs nothing but a tiny, redundant download.
+export const fetchComponentTemplate = (src, signal) => {
+  if (!enabled) {
+    return fetch(src, { signal }).then((response) => response.text());
+  }
+
+  let entry = templates.get(src);
+  if (!entry) {
+    entry = fetch(src).then(async (response) => {
+      const text = await response.text();
+      // Never persist a failed response — the immediate caller still gets the
+      // body (parity with the uncached path), but the next mount may retry.
+      if (!response.ok) templates.delete(src);
+      return text;
+    });
+    // Cache synchronously, before the first await, so same-tick concurrent
+    // mounts find this pending entry and coalesce onto it.
+    templates.set(src, entry);
+    // Drop the entry if the fetch rejects, so a transient network error isn't
+    // sticky for the rest of the session.
+    entry.catch(() => templates.delete(src));
+  }
+  return entry;
+};
+
+// Invalidate cached templates. With a `path`, drops that one entry (the query
+// string is ignored when matching, so `/components/Foo.html` also clears a
+// versioned `/components/Foo.html?v=…`); with no argument, clears everything.
+// Exposed publicly as `$.clearComponentCache` for tooling to call on change.
+export const clearComponentCache = (path) => {
+  if (!path) {
+    templates.clear();
+    return;
+  }
+  const base = path.split('?')[0];
+  for (const key of templates.keys()) {
+    if (key.split('?')[0] === base) templates.delete(key);
+  }
+};

package/runtime/component.js

@@ -1,12 +1,14 @@
 import { debugLog } from './debug.js';
 import {
   PHASE_FETCH,
+  PHASE_FETCH_CACHED,
   DEHYDRATE_CLASS_OR_ATTR,
   BINDING_REGEX,
   THIS_PROP_REGEX,
   STATE_THIS_PROP_REGEX,
 } from './constants.js';
 import { evalInScope } from './utils.js';
+import { fetchComponentTemplate, isComponentCached } from './component-cache.js';
 
 // Deterministic component counter
 let componentCounter = 0;
@@ -432,12 +434,16 @@ const processSingle = (el, debug) => {
     }
   });
 
+  // Capture cache state before the fetch so the debug layer can tell a real
+  // network fetch from a runtime-cache hit (the call below would make them
+  // indistinguishable — both just resolve a promise).
+  const fromCache = isComponentCached(src);
+
   // Create AbortController to cancel fetch if element is removed
   const controller = new AbortController();
   pendingFetches.set(el, controller);
 
-  return fetch(src, { signal: controller.signal })
-    .then((r) => r.text())
+  return fetchComponentTemplate(src, controller.signal)
     .then((html) => {
       // Parse HTML in temporary container to process component scripts
       const temp = createDetached('div');
@@ -589,7 +595,7 @@ const processSingle = (el, debug) => {
           // each row update.
           el._vibeReplacedBy = newWrapper;
           el.replaceWith(newWrapper);
-          debugLog(PHASE_FETCH, src, debug);
+          debugLog(fromCache ? PHASE_FETCH_CACHED : PHASE_FETCH, src, debug);
 
           // MutationObserver handles parsing and hydrating the new content.
           // Branch nodes are registered in the manifest by mountBranch,

package/runtime/constants.js

@@ -15,7 +15,8 @@ export const PHASE_PARSE = 'Parsed'; // Reads DOM structure (parse.js)
 export const PHASE_HYDRATE = 'Hydrated'; // Replaces @[...] with values (hydrate.js)
 export const PHASE_ITERATE = 'Iterated'; // Renders <!-- each --> blocks (iterate.js)
 export const PHASE_CONDITION = 'Evaluated'; // Renders <!-- if --> blocks (conditionals.js)
-export const PHASE_FETCH = 'Fetched'; // Loads <component> content (component.js)
+export const PHASE_FETCH = 'Fetched'; // Loads <component> content over the network (component.js)
+export const PHASE_FETCH_CACHED = 'Fet(ca)ched'; // Loads <component> content from the runtime template cache — a Fetch served from memory (component.js)
 export const PHASE_UPDATE = 'Proxy'; // State changes trigger re-hydration (index.js)
 export const PHASE_MUTATE = 'Mutation'; // DOM mutations detected by observer (index.js)
 export const PHASE_HYPERSPEED = 'Hyperspeed'; // Restores @[...] markers from pre-compiled manifest (pre-compiled-manifest.js)

package/runtime/debug.js

@@ -12,6 +12,7 @@ const PHASE_COLORS = {
   Iterated: 'oklch(0.58 0.11 142)', // comment green (baseline)
   Evaluated: 'oklch(0.58 0.11 142)', // comment green (baseline)
   Fetched: 'oklch(0.59 0.12 307)', // muted purple
+  'Fet(ca)ched': 'oklch(0.59 0.12 307)', // same muted purple — a Fetch served from the runtime cache
   Mutation: 'oklch(0.60 0.11 240)', // muted blue
   Proxy: 'oklch(0.60 0.11 240)', // muted blue
   Hyperspeed: 'oklch(0.60 0.11 180)', // muted cyan
@@ -39,7 +40,7 @@ const COLORS = {
 export const debugLog = (phase, message, debug = false, indent = 0, element = null) => {
   if (!debug) return;
 
-  const phaseBracket = `[${phase}] `.padEnd(13, ' '); // Pad to 13 chars (longest is "[Manifested] ")
+  const phaseBracket = `[${phase}] `.padEnd(14, ' '); // Pad to 14 chars (longest is "[Fet(ca)ched] ")
   const indentStr = indent > 0 ? '  '.repeat(indent) + '├─ ' : '';
   const phaseColor = PHASE_COLORS[phase] || 'oklch(0.55 0.02 250)';
 

package/runtime/index.js

@@ -24,6 +24,7 @@ import {
   DEHYDRATE_CLASS_OR_ATTR,
 } from './constants.js';
 import { processComponent, abortComponentFetch, collectComponentIds, releaseOrphanedComponentState, renderComponentTemplate, executeCompiledComponentScripts } from './component.js';
+import { configureComponentCache, clearComponentCache } from './component-cache.js';
 import { debugLog } from './debug.js';
 import { shouldCleanup, cleanup } from './cleanup.js';
 import { reconcile } from './reconcile.js';
@@ -331,6 +332,9 @@ const main = (s, config = {}, stringSelector = '') => {
   const verbose = !!config?.verbose;
   globalThis.__vibeDebug = debug;
 
+  // Enable/disable the component template cache from config (`{ noCache }`).
+  configureComponentCache(config);
+
   // Expose the global `$scope` resolver used by loop-scoped `on*` handlers.
   installScopeResolver();
 
@@ -676,6 +680,17 @@ const main = (s, config = {}, stringSelector = '') => {
     enumerable: false,
   });
 
+  // Invalidate cached component templates. `$.clearComponentCache(path)` drops
+  // one entry, `$.clearComponentCache()` drops all. Templates are immutable in
+  // production (nothing to clear), so this exists for tooling that swaps a
+  // template under a live session — e.g. the dev server busts the changed file
+  // on hot update. Non-enumerable so it never leaks into state snapshots.
+  Object.defineProperty($, 'clearComponentCache', {
+    value: clearComponentCache,
+    enumerable: false,
+    configurable: true,
+  });
+
   // Expose the live reactive proxy to the iteration stamper so loop-scoped
   // `on*` handlers (`$scope`) resolve the SAME object identity the app sees via
   // `$`, instead of the plain diff-snapshot clones iterations render against

package/runtime/pre-compiled-manifest.js

@@ -193,6 +193,17 @@ const detectHyperspeed = async () => {
       );
     }
 
+    // Strategy 4: dynamic routes. The compiler collapses a `$param` segment to a
+    // single `$` token (the-arena/$id.html -> the-arena/$.html.manifest.js), so a
+    // concrete URL only matches once its trailing segment is tokenized. Tried
+    // after the literal strategies, so static pages still win on an exact hit.
+    const dot = fileName.indexOf(".");
+    const tokenized = dot >= 0 ? "$" + fileName.slice(dot) : "$";
+    if (tokenized !== fileName) {
+      const dirPrefix = dirSegments.length ? `/${dirSegments.join("/")}` : "";
+      possiblePaths.push(`/vibe-hyperspeed${dirPrefix}/${tokenized}.manifest.js`);
+    }
+
     if (!skipNetwork) {
       // Fully-runtime dynamic import. Hidden behind `new Function` so any
       // bundler's static-analysis can't read into it — there's nothing we