@zolomedia/bifrost-client 1.7.74

package/L2_Handling/zhooks/features/cache_live.js

@@ -0,0 +1,287 @@
+/**
+ * zHook: cache_live — live cache inspector (INTERNAL DEV TOOL)
+ *
+ * A self-contained zHook. Enable from the bootstrap with:
+ *
+ *   new BifrostClient({ zHooks: { cache_live: true } });
+ *
+ * Renders a dark-glass dev panel pinned to the bottom of the viewport that
+ * surfaces BOTH sides of the caching system so we can dogfood it:
+ *   - Frontend: the client TrailStore — the offline-browse cache of visited,
+ *     rendered pages ("rendered" tier). This is NOT a mirror of zLoader; it is
+ *     a bfcache-style freeze of pages the user has already seen.
+ *   - Backend: the server zLoader cache (system / pinned / schema / plugin),
+ *     echoed over the live socket via &zdebug.cache().
+ *
+ * It also writes a server-side zCache.log (sibling to zNav.log) so a run's cache
+ * behaviour is legible after the fact. Controls let us clear tiers AND drop /
+ * restore the WebSocket — the "drop ws" button simulates an offline / disrupted
+ * connection so we can dogfood the trail-replay + auto-retry offline experience
+ * without pulling the network in DevTools.
+ *
+ * Like crumbs_live this is a dev tool — it depends on plugins/zdebug.py and is a
+ * safe no-op where that plugin is absent. Both will later be refined for users
+ * or dropped from zHooks; for now they are dogfood instruments.
+ *
+ * @module L2_Handling/zhooks/features/cache_live
+ * @layer 2 (Handling)
+ */
+
+const STYLE_ID = 'zhook-cache-live-style';
+const EL_TAG = 'zCache_Debugging';
+
+// Dark-glass dev palette with an amber accent — aligned with crumbs_live so the
+// two dogfood panels read as one toolset, while amber keeps "cache" distinct.
+const CSS = `
+${EL_TAG} {
+  position: fixed; bottom: 0; left: 0; right: 0; z-index: 99998;
+  box-sizing: border-box; max-height: 42vh; overflow: auto;
+  font: 11px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
+  background: rgba(16,14,10,.93); -webkit-backdrop-filter: blur(8px); backdrop-filter: blur(8px);
+  color: #ffe9b0; border-top: 1px solid rgba(255,179,0,.45);
+  padding: 8px 14px 10px; box-shadow: 0 -8px 28px rgba(0,0,0,.5);
+}
+${EL_TAG} .zcl-title {
+  display: flex; align-items: center; gap: 10px; flex-wrap: wrap;
+  color: #ffd24d; font-weight: 700; letter-spacing: .03em; margin-bottom: 6px;
+}
+${EL_TAG} .zcl-tag {
+  display: inline-flex; align-items: center; gap: 6px;
+  color: #ffb300; font-weight: 800;
+}
+${EL_TAG} .zcl-sub { color: #8a7a52; font-weight: 600; }
+${EL_TAG} .zcl-spacer { flex: 1 1 auto; }
+${EL_TAG} .zcl-pill {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 2px 9px; border-radius: 999px; font-weight: 700;
+  border: 1px solid transparent;
+}
+${EL_TAG} .zcl-pill .zcl-dot { width: 7px; height: 7px; border-radius: 50%; }
+${EL_TAG} .zcl-pill.up { color: #7ee0a6; background: rgba(40,200,120,.10); border-color: rgba(40,200,120,.35); }
+${EL_TAG} .zcl-pill.up .zcl-dot { background: #34d27e; box-shadow: 0 0 6px #34d27e; }
+${EL_TAG} .zcl-pill.down { color: #ff9b9b; background: rgba(255,80,80,.10); border-color: rgba(255,80,80,.35); }
+${EL_TAG} .zcl-pill.down .zcl-dot { background: #ff5a5a; box-shadow: 0 0 6px #ff5a5a; }
+${EL_TAG} button {
+  cursor: pointer; font: inherit; font-weight: 700; line-height: 1;
+  color: #ffd24d; background: rgba(255,179,0,.10); border: 1px solid rgba(255,179,0,.30);
+  border-radius: 6px; padding: 4px 10px; transition: background .12s ease, border-color .12s ease;
+}
+${EL_TAG} button:hover { background: rgba(255,179,0,.20); border-color: rgba(255,179,0,.55); }
+${EL_TAG} button.zcl-ws-drop {
+  color: #ffd2d2; background: rgba(255,80,80,.14); border-color: rgba(255,80,80,.40);
+}
+${EL_TAG} button.zcl-ws-drop:hover { background: rgba(255,80,80,.26); border-color: rgba(255,80,80,.7); }
+${EL_TAG} button.zcl-ws-up {
+  color: #c9ffe0; background: rgba(40,200,120,.16); border-color: rgba(40,200,120,.45);
+}
+${EL_TAG} button.zcl-ws-up:hover { background: rgba(40,200,120,.28); border-color: rgba(40,200,120,.75); }
+${EL_TAG} .zcl-cols { display: flex; gap: 28px; flex-wrap: wrap; }
+${EL_TAG} .zcl-col { min-width: 220px; }
+${EL_TAG} .zcl-head { color: #ff8f00; font-weight: 700; margin-bottom: 3px; text-transform: uppercase; font-size: 10px; letter-spacing: .06em; }
+${EL_TAG} .zcl-row { color: #ffe9b0; white-space: pre; }
+${EL_TAG} .zcl-key { color: #ffd24d; }
+${EL_TAG} .zcl-empty { color: #9a8350; font-style: italic; }
+${EL_TAG} .zcl-meta { color: #9a8350; font-size: 10px; margin-top: 6px; }
+${EL_TAG}.zcl-collapsed { max-height: none; overflow: visible; }
+${EL_TAG}.zcl-collapsed .zcl-body { display: none; }
+`;
+
+function injectStyle() {
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = STYLE_ID;
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}
+
+function ensureElement() {
+  let el = document.querySelector(EL_TAG);
+  if (!el) {
+    el = document.createElement(EL_TAG);
+    document.body.appendChild(el);
+  }
+  return el;
+}
+
+// Reduce a tier's getStats() result to a short, readable count line.
+function summarize(stats) {
+  if (stats == null) return '—';
+  if (typeof stats === 'number') return String(stats);
+  if (typeof stats !== 'object') return String(stats);
+  // Prefer an explicit count-ish field; else count own keys.
+  for (const k of ['count', 'size', 'entries', 'length']) {
+    if (typeof stats[k] === 'number') return `${stats[k]}`;
+  }
+  const keys = Object.keys(stats);
+  return keys.length ? `${keys.length} keys` : 'empty';
+}
+
+function renderTiers(stats) {
+  if (!stats || typeof stats !== 'object' || !Object.keys(stats).length) {
+    return '<span class="zcl-empty">— none —</span>';
+  }
+  return Object.keys(stats).map(function (tier) {
+    return '<div class="zcl-row"><span class="zcl-key">' + tier + '</span>: ' + summarize(stats[tier]) + '</div>';
+  }).join('');
+}
+
+export function activate(client) {
+  injectStyle();
+  const el = ensureElement();
+
+  const TAG = 'zCACHE-DBG';
+  const STY = 'color:#ffb300;font-weight:700';
+  let collapsed = localStorage.getItem('zclCollapsed') === '1';
+  let feStats = null;
+  let beStats = null;
+  let lastSentFe = null; // dedupe: only echo to the server when FE stats change
+  function log(...args) { console.log('%c' + TAG, STY, ...args); }
+
+  function wsUp() {
+    return !!(client && typeof client.isConnected === 'function' && client.isConnected());
+  }
+
+  function render() {
+    el.classList.toggle('zcl-collapsed', collapsed);
+    const up = wsUp();
+    const pill = up
+      ? '<span class="zcl-pill up"><span class="zcl-dot"></span>ws online</span>'
+      : '<span class="zcl-pill down"><span class="zcl-dot"></span>ws offline</span>';
+    const wsBtn = up
+      ? '<button data-act="ws-toggle" class="zcl-ws-drop" type="button">drop ws</button>'
+      : '<button data-act="ws-toggle" class="zcl-ws-up" type="button">reconnect</button>';
+    const head = '<div class="zcl-title">'
+      + '<span class="zcl-tag">⚡ zCache</span><span class="zcl-sub">live · dev</span>'
+      + pill
+      + '<span class="zcl-spacer"></span>'
+      + '<button data-act="refresh" type="button">refresh</button>'
+      + '<button data-act="clear-blocks" type="button">clear trail</button>'
+      + '<button data-act="clear-be" type="button">clear BE</button>'
+      + wsBtn
+      + '<button data-act="toggle" type="button">' + (collapsed ? '+' : '–') + '</button>'
+      + '</div>';
+    const body = '<div class="zcl-body"><div class="zcl-cols">'
+      + '<div class="zcl-col"><div class="zcl-head">frontend · trail (visited pages)</div>' + renderTiers(feStats) + '</div>'
+      + '<div class="zcl-col"><div class="zcl-head">backend · zLoader</div>' + renderTiers(beStats) + '</div>'
+      + '</div><div class="zcl-meta">FE: client TrailStore (offline-browse) · BE: server zLoader (echoed via &zdebug.cache) · logged to zCache.log · "drop ws" simulates offline</div></div>';
+    el.innerHTML = head + body;
+  }
+
+  // ── frontend stats ────────────────────────────────────────────────────────
+  async function pollFrontend() {
+    try {
+      if (client.cache && typeof client.cache.getStats === 'function') {
+        feStats = await client.cache.getStats();
+      }
+    } catch (e) { log('FE getStats error →', e); }
+  }
+
+  // ── backend echo + log via &zdebug.cache(action, payload) ──────────────────
+  function sendBackend(action) {
+    const conn = client && client.connection;
+    if (!conn || typeof conn.send !== 'function' || !wsUp()) return;
+    installWrap();
+    try {
+      const payload = JSON.stringify(feStats || {});
+      const a = [JSON.stringify(String(action || 'report')), JSON.stringify(payload)];
+      conn.send(JSON.stringify({
+        event: 'execute_zfunc',
+        zfunc: '&zdebug.cache(' + a.join(', ') + ')',
+        requestId: 'zdebug-cache-' + Date.now()
+      }));
+    } catch (e) { /* not connected yet */ }
+  }
+
+  // Claim only our own reply prefix; pass everything else to the prior handler.
+  function installWrap() {
+    if (!client || !client.hooks || !client.hooks.hooks) return false;
+    const orig = client.hooks.hooks.onZFuncResponse;
+    if (orig && orig._zCacheWrapped) return true;
+    const wrapped = function (msg) {
+      const rid = (msg && typeof msg.requestId === 'string') ? msg.requestId : '';
+      if (rid.indexOf('zdebug-cache') === 0) {
+        if (msg.success) { beStats = msg.result; render(); }
+        else { log('backend poll error →', msg.error); }
+        return; // claimed
+      }
+      if (typeof orig === 'function') return orig(msg);
+    };
+    wrapped._zCacheWrapped = true;
+    client.hooks.hooks.onZFuncResponse = wrapped;
+    return true;
+  }
+
+  // Drop or restore the live socket to simulate an offline / disrupted
+  // connection. disconnect() is a *clean* close, so the connection's
+  // auto-reconnect stays out of the way — the socket stays down until we
+  // explicitly reconnect, which is exactly the manual offline toggle we want.
+  // Reconnect re-creates the ws and re-binds the message handler; ws.onopen
+  // fires the onConnected hook, which fulfils any pending offline navigation.
+  function toggleWs() {
+    if (wsUp()) {
+      try { client.disconnect(); log('ws dropped — simulating offline (trail-replay active)'); }
+      catch (e) { log('drop ws error →', e); }
+      render();
+      return;
+    }
+    log('reconnecting ws…');
+    const conn = client && client.connection;
+    if (!conn || typeof conn.connect !== 'function') { log('no connection to restore'); return; }
+    conn.connect().then(function () {
+      if (client.messageHandler && typeof conn.onMessage === 'function') {
+        conn.onMessage(function (event) { client.messageHandler.handleMessage(event.data); });
+      }
+      log('ws reconnected');
+      tick(true);
+    }).catch(function (e) { log('reconnect failed →', e); render(); });
+  }
+
+  // The real BE cache events stream straight to zCache.log via the server-side
+  // logging tap, so the panel no longer needs to poll on a blind timer. We only
+  // echo to the server when the FE stats actually change — that kills the 2s
+  // identical-payload spam while still refreshing BE counts on real activity.
+  async function tick(force) {
+    await pollFrontend();
+    render();
+    const sig = JSON.stringify(feStats || {});
+    if (force || sig !== lastSentFe) {
+      lastSentFe = sig;
+      sendBackend('report');
+    }
+  }
+
+  // Delegated controls — survive innerHTML rebuilds.
+  el.addEventListener('click', async function (e) {
+    const btn = e.target.closest('button');
+    if (!btn) return;
+    const act = btn.getAttribute('data-act');
+    if (act === 'toggle') {
+      collapsed = !collapsed;
+      localStorage.setItem('zclCollapsed', collapsed ? '1' : '0');
+      render();
+      return;
+    }
+    if (act === 'ws-toggle') { toggleWs(); return; }
+    if (act === 'refresh') { tick(true); return; }
+    if (act === 'clear-blocks') {
+      try { await client.cache.clear('rendered'); log('cleared FE trail (visited pages)'); } catch (err) { log('clear trail error →', err); }
+      tick();
+      return;
+    }
+    if (act === 'clear-be') { sendBackend('clear'); log('requested BE clear'); return; }
+  });
+
+  render();
+
+  // Setup loop: wait for the socket, install the reply wrap, then poll on an
+  // interval (cache state drifts over time, unlike event-driven crumbs).
+  const setup = setInterval(function () {
+    if (installWrap()) {
+      clearInterval(setup);
+      tick(true);                  // first paint always echoes once
+      setInterval(tick, 2000);     // subsequent ticks only echo on FE change
+    }
+  }, 300);
+
+  log('cache inspector armed — FE trail + BE zLoader echo → zCache.log');
+}

package/L2_Handling/zhooks/features/crumbs_live.js

@@ -0,0 +1,292 @@
+/**
+ * zHook: crumbs_live — live zCrumbs session overlay (INTERNAL DEV TOOL)
+ *
+ * A first-class, self-contained zHook. Enable from the bootstrap with:
+ *
+ *   new BifrostClient({ zHooks: { crumbs_live: true } });
+ *
+ * When active it injects its own CSS + <zCrumbs_Debugging> element, taps the
+ * live client WebSocket, and paints session['zCrumbs'] in real time. It polls
+ * the server via &zdebug.crumbs() and records lifecycle events via &zdebug.nav()
+ * — both server-side zfuncs that only exist where the developer installed them
+ * (plugins/zdebug.py). On a deployment without those zfuncs the polls fail
+ * silently and the overlay simply shows "no trails".
+ *
+ * This is the proof case for the zHook abstraction: a shipped, opt-in feature
+ * toggled by a data flag — never bespoke page script. Disable by omitting the
+ * flag; nothing is created.
+ *
+ * @module L2_Handling/zhooks/features/crumbs_live
+ * @layer 2 (Handling)
+ */
+
+const STYLE_ID = 'zhook-crumbs-live-style';
+const EL_TAG = 'zCrumbs_Debugging';
+
+const CSS = `
+${EL_TAG} {
+  position: fixed; left: 10px; bottom: 10px; z-index: 99999;
+  max-width: 380px; max-height: 45vh; overflow: auto;
+  font: 11px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace;
+  background: rgba(12,14,20,.92); color: #d7e0ee;
+  border: 1px solid #2c3340; border-radius: 8px;
+  padding: 8px 10px; box-shadow: 0 6px 24px rgba(0,0,0,.45);
+  white-space: pre; pointer-events: auto;
+}
+${EL_TAG} .zdbg-title {
+  display: flex; align-items: center; justify-content: space-between;
+  gap: 10px; color: #7fd1ff; font-weight: 700;
+  letter-spacing: .04em; margin-bottom: 4px;
+}
+${EL_TAG} .zdbg-toggle {
+  flex: none; cursor: pointer; pointer-events: auto;
+  border: 1px solid #2c3340; background: rgba(255,255,255,.04);
+  color: #7fd1ff; border-radius: 5px; font: inherit; font-weight: 700;
+  line-height: 1; padding: 2px 8px;
+}
+${EL_TAG} .zdbg-toggle:hover { background: rgba(127,209,255,.15); }
+${EL_TAG} .zdbg-scope { color: #ffd479; }
+${EL_TAG} .zdbg-empty { color: #6b7585; font-style: italic; }
+${EL_TAG} .zdbg-meta { color: #6b7585; font-size: 10px; }
+${EL_TAG}.zdbg-collapsed {
+  max-height: none; overflow: visible; white-space: nowrap;
+}
+${EL_TAG}.zdbg-collapsed .zdbg-body { display: none; }
+`;
+
+function injectStyle() {
+  if (document.getElementById(STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = STYLE_ID;
+  style.textContent = CSS;
+  document.head.appendChild(style);
+}
+
+function ensureElement() {
+  let el = document.querySelector(EL_TAG);
+  if (!el) {
+    el = document.createElement(EL_TAG);
+    document.body.appendChild(el);
+  }
+  return el;
+}
+
+/**
+ * Activate the live-crumbs overlay against a connected BifrostCore.
+ * @param {Object} client - the BifrostCore instance (window.bifrostClient)
+ */
+export function activate(client) {
+  injectStyle();
+  const el = ensureElement();
+
+  // Single filterable console tag — type "zCRUMBS-DBG" into the browser
+  // console filter to watch only the live crumbs trail + status.
+  const TAG = 'zCRUMBS-DBG';
+  const STY = 'color:#7fd1ff;font-weight:700';
+  let lastJson = null;
+  let lastPayload = null;
+  let collapsed = localStorage.getItem('zdbgCollapsed') === '1';
+  function log(...args) {
+    console.log('%c' + TAG, STY, ...args);
+  }
+
+  // Per-tab id: sessionStorage is scoped to THIS tab and survives a reload, so
+  // two tabs of the same app get distinct ids while an incognito window gets
+  // its own (and its own cookie/zS session). This is the discriminator for the
+  // multi-tab / guest-vs-logged-in drift hunt in zNav.log.
+  let TAB = sessionStorage.getItem('zdbgTab');
+  if (!TAB) {
+    TAB = Math.random().toString(36).slice(2, 8);
+    sessionStorage.setItem('zdbgTab', TAB);
+  }
+  log('overlay armed — tab=' + TAB + ' — logs nav lifecycle to zNav.log');
+
+  function shortScope(s) {
+    // Drop the @.UI. prefix and the .zUI. file marker for readability.
+    return String(s).replace(/^@\.UI\./, '').replace(/\.zUI\./, ' · ');
+  }
+
+  function render(payload) {
+    lastPayload = payload;
+    el.classList.toggle('zdbg-collapsed', collapsed);
+    const head = '<span class="zdbg-title">zCrumbs · live session'
+      + '<button class="zdbg-toggle" type="button" '
+      + 'aria-label="' + (collapsed ? 'Expand' : 'Minimize') + '">'
+      + (collapsed ? '+' : '–') + '</button></span>';
+    // Real session shape: { trails: {scope:[keys]}, _context, _depth_map, _navbar_navigation }
+    const trails = (payload && typeof payload === 'object' && payload.trails)
+      ? payload.trails : (payload || {});
+    const scopes = Object.keys(trails || {});
+    if (!scopes.length) {
+      el.innerHTML = head + '<div class="zdbg-body">'
+        + '<span class="zdbg-empty">— no trails —</span></div>';
+    } else {
+      const body = scopes.map(function (scope, i) {
+        const trail = trails[scope];
+        const hasKeys = Array.isArray(trail) && trail.length;
+        const t = hasKeys ? trail.join('  ›  ')
+          : '<span class="zdbg-empty">(empty)</span>';
+        const here = (i === scopes.length - 1) ? ' ◂ here' : '';
+        return '<span class="zdbg-scope">' + shortScope(scope) + here + '</span>\n  ' + t;
+      }).join('\n');
+      const meta = [];
+      if (payload && payload._navbar_navigation) meta.push('navbar');
+      meta.push(scopes.length + ' scope' + (scopes.length === 1 ? '' : 's'));
+      el.innerHTML = head + '<div class="zdbg-body">' + body
+        + '\n\n<span class="zdbg-meta">' + meta.join(' · ') + '</span></div>';
+    }
+    // Log only on change so the filtered console reads as a clean event log.
+    const json = JSON.stringify(payload || {});
+    if (json !== lastJson) {
+      log('trail changed →', payload);
+      lastJson = json;
+    }
+  }
+
+  // Delegated toggle — survives the full innerHTML rebuild on each render.
+  el.addEventListener('click', function (e) {
+    if (!e.target.closest('.zdbg-toggle')) return;
+    collapsed = !collapsed;
+    localStorage.setItem('zdbgCollapsed', collapsed ? '1' : '0');
+    render(lastPayload);
+  });
+  render(null);
+
+  // Wrap onZFuncResponse so our poll replies render (and are swallowed, avoiding
+  // the orchestrator's "no resolver" warn) while real zFuncs still reach their
+  // handler.
+  function installWrap() {
+    if (!client || !client.hooks || !client.hooks.hooks) return false;
+    const orig = client.hooks.hooks.onZFuncResponse;
+    if (orig && orig._zCrumbsWrapped) return true;
+    // Claim ONLY our own requestId prefixes and pass everything else to `orig`.
+    // This makes the wrap composable: other zHooks (e.g. cache_live) chain their
+    // own wrap and each claims its own replies — no single feature swallows
+    // another's. Distinct flag (_zCrumbsWrapped) so chained wraps don't mistake
+    // each other for "already installed".
+    const wrapped = function (msg) {
+      const rid = (msg && typeof msg.requestId === 'string') ? msg.requestId : '';
+      if (rid.indexOf('zdebug-crumbs') === 0) {
+        if (msg.success) { render(msg.result); }
+        else { log('poll error →', msg.error); }
+        return; // claimed: crumbs poll reply repaints the overlay
+      }
+      if (rid.indexOf('zdebug-nav') === 0) {
+        return; // claimed: nav() is fire-and-forget — swallow our own reply
+      }
+      if (typeof orig === 'function') return orig(msg);
+    };
+    wrapped._zCrumbsWrapped = true;
+    client.hooks.hooks.onZFuncResponse = wrapped;
+    return true;
+  }
+
+  // Fire a single crumbs fetch over the live socket (initial paint + after each
+  // navigation — never on a timer).
+  function fetchCrumbs() {
+    const conn = client && client.connection;
+    // Re-assert the reply wrap before every poll. The display orchestrator
+    // registers its own onZFuncResponse during init (after our first install)
+    // and `register` overwrites the single hook slot — clobbering our wrap, so
+    // later crumbs replies fall through to the orchestrator ("No resolver" warn)
+    // and the overlay freezes. installWrap is idempotent and re-captures the
+    // orchestrator handler as `orig`, so real zFuncs still pass through.
+    installWrap();
+    if (conn && typeof conn.send === 'function') {
+      try {
+        conn.send(JSON.stringify({
+          event: 'execute_zfunc',
+          zfunc: '&zdebug.crumbs()',
+          requestId: 'zdebug-crumbs-' + Date.now()
+        }));
+      } catch (e) { /* not connected yet */ }
+    }
+  }
+
+  // Record a client-observed lifecycle event into zNav.log via the server-side
+  // &zdebug.nav() zfunc. Positional args only (the zfunc invoker has no kwargs);
+  // JSON.stringify keeps quoting/escaping safe and lets the comma-aware arg
+  // splitter keep values intact.
+  function sendNav(tag, url, detail) {
+    const conn = client && client.connection;
+    if (!conn || typeof conn.send !== 'function') return;
+    try {
+      const a = [
+        JSON.stringify(String(tag || '')),
+        JSON.stringify(String(url || '')),
+        JSON.stringify(String(TAB)),
+        JSON.stringify(String(detail || ''))
+      ];
+      conn.send(JSON.stringify({
+        event: 'execute_zfunc',
+        zfunc: '&zdebug.nav(' + a.join(', ') + ')',
+        requestId: 'zdebug-nav-' + Date.now()
+      }));
+    } catch (e) { /* not connected yet */ }
+  }
+
+  // Browser-history + tab lifecycle taps. popstate fires on Back/Fwd (and on
+  // server-driven history.back()); beforeunload fires when the tab/window is
+  // closed or reloaded — the "browser closed but zApp still running" signal.
+  window.addEventListener('popstate', function () {
+    sendNav('popstate', location.pathname);
+  });
+  window.addEventListener('beforeunload', function () {
+    sendNav('unload', location.pathname);
+  });
+
+  // WebSocket open/close — logged on TRANSITION only (no per-tick noise). A
+  // close→open gap in the log = the socket broke and reconnected; a lone close
+  // with no reopen = zApp lost this tab.
+  let wsUp = null;
+  setInterval(function () {
+    const up = !!(client && typeof client.isConnected === 'function' && client.isConnected());
+    if (up === wsUp) return;
+    wsUp = up;
+    sendNav(up ? 'ws_open' : 'ws_close', location.pathname);
+  }, 1000);
+
+  // Refresh on NAVIGATION ONLY: wrap connection.send so every outgoing
+  // execute_walker (forward nav, menu/brand pick, browser Back/popstate — all
+  // route through execute_walker in Bifrost) schedules one crumbs fetch after
+  // the server has updated the trail. No interval polling.
+  function installSendWrap() {
+    const conn = client && client.connection;
+    if (!conn || typeof conn.send !== 'function') return false;
+    if (conn.send._zdebugWrapped) return true;
+    const origSend = conn.send.bind(conn);
+    const wrapped = function (data) {
+      const r = origSend(data);
+      try {
+        if (typeof data === 'string' &&
+            data.indexOf('"event":"execute_walker"') !== -1) {
+          setTimeout(fetchCrumbs, 200);
+        }
+      } catch (e) { /* ignore */ }
+      return r;
+    };
+    wrapped._zdebugWrapped = true;
+    conn.send = wrapped;
+    return true;
+  }
+
+  // One-time bootstrap: install BOTH wraps once the socket exists, paint the
+  // initial trail, then stop. This is setup — NOT a state poll. Both must
+  // succeed before we stop: installWrap is the reply→repaint wrap (renders each
+  // crumbs() poll) and installSendWrap is the nav→fetch wrap (schedules the
+  // poll). Clearing the loop on installSendWrap alone could strand the overlay
+  // with fetches firing but nothing repainting — the "live crumbs never update"
+  // symptom.
+  const setup = setInterval(function () {
+    const responseWrapped = installWrap();
+    const sendWrapped = installSendWrap();
+    if (responseWrapped && sendWrapped) {
+      // 'load' first: it clears the server-side CRUMBS dedupe so the
+      // fetchCrumbs() right after always paints a fresh trail snapshot for this
+      // (re)load.
+      sendNav('load', location.pathname);
+      fetchCrumbs();
+      clearInterval(setup);
+    }
+  }, 300);
+}

package/L2_Handling/zhooks/zhooks_manager.js

@@ -0,0 +1,65 @@
+/**
+ * zHooks Manager — declarative, opt-in client features (SSOT registry)
+ *
+ * A zHook is NOT a callback (that is `registerHook(fn)`). A zHook is a *data
+ * flag* that toggles a feature the client already ships — closer to WordPress
+ * `add_theme_support()` than to a WooCommerce action hook. The bootstrap script
+ * declares them:
+ *
+ *   new BifrostClient({ zHooks: { crumbs_live: true } });
+ *
+ * Trust: zHooks are data (booleans), never code, so they cannot inject behavior
+ * into the page — they only switch on capabilities the audited client owns. A
+ * deployment (or the server) can therefore reason about exactly what is enabled.
+ *
+ * Adding a feature: register its module path below and ship a module that
+ * exports `activate(client)`. Nothing else in the core needs to change.
+ *
+ * @module L2_Handling/zhooks/zhooks_manager
+ * @layer 2 (Handling)
+ */
+
+// name → module path (resolved against the client BASE_URL at load time).
+// SSOT for the set of module zHooks (opt-in, dynamically imported features).
+const ZHOOK_REGISTRY = {
+  crumbs_live: 'L2_Handling/zhooks/features/crumbs_live.js',
+  cache_live: 'L2_Handling/zhooks/features/cache_live.js',
+};
+
+// Core zHooks are gated where they live in the client (not imported as modules)
+// — typically default-ON chrome with opt-out, e.g. the connection badge handled
+// in zvaf_manager. Listed here only so explicit toggles aren't flagged unknown.
+const CORE_ZHOOKS = new Set(['badge']);
+
+/**
+ * Activate every enabled zHook declared in the config.
+ * @param {Object} client - the BifrostCore instance
+ * @param {Object} config - { <featureName>: true|false }
+ * @param {string} baseUrl - client BASE_URL for dynamic feature import
+ */
+export async function activateZHooks(client, config, baseUrl) {
+  if (!config || typeof config !== 'object') return;
+  const logger = client.logger || console;
+
+  for (const [name, enabled] of Object.entries(config)) {
+    if (!enabled) continue;
+    // Core zHooks are gated in-core (e.g. badge in zvaf_manager) — not imported.
+    if (CORE_ZHOOKS.has(name)) continue;
+    const path = ZHOOK_REGISTRY[name];
+    if (!path) {
+      logger.warn(`[zHooks] Unknown zHook "${name}" — ignored. Known: ${[...Object.keys(ZHOOK_REGISTRY), ...CORE_ZHOOKS].join(', ')}`);
+      continue;
+    }
+    try {
+      const mod = await import(`${baseUrl}${path}`);
+      if (typeof mod.activate !== 'function') {
+        logger.error(`[zHooks] Feature "${name}" has no activate(client) export`);
+        continue;
+      }
+      mod.activate(client);
+      logger.debug(`[zHooks] Activated: ${name}`);
+    } catch (err) {
+      logger.error(`[zHooks] Failed to activate "${name}":`, err);
+    }
+  }
+}

package/L2_Handling/zvaf/zvaf.js

@@ -0,0 +1,8 @@
+/**
+ * L2_Handling/zvaf - zVaF Element Management
+ * 
+ * zVaF element initialization, connection badge, NavBar population.
+ * Depends on: L1_Foundation (Logger)
+ */
+
+export { ZVaFManager } from './zvaf_manager.js';