npm - @ape-egg/vibe - Versions diffs - 2.0.5 → 2.1.1 - Mend

@ape-egg/vibe 2.0.5 → 2.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/CHANGELOG.md +19 -0
package/README.md +21 -0
package/llms.txt +1 -1
package/package.json +1 -1
package/runtime/component-cache.js +94 -0
package/runtime/component.js +9 -3
package/runtime/constants.js +2 -1
package/runtime/debug.js +2 -1
package/runtime/index.js +15 -0

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,24 @@
 # Changelog
+## [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 CHANGED Viewed

@@ -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/llms.txt CHANGED Viewed

@@ -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 CHANGED Viewed

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

package/runtime/component-cache.js ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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