webspresso 0.0.110 → 0.0.112

package/core/client/fragments.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { defaultStorage } = require('./storage');
+const { isArray, isNumber, parseDurationMs, parseRefetchMode, uid } = require('./utils');
 
 /**
  * Webspresso Client-Side SSR Fragment Coordinator & Invalidation Engine
@@ -33,7 +34,7 @@ function parseDependsOnAttr(raw) {
   if (trimmed.startsWith('[')) {
     try {
       const parsed = JSON.parse(trimmed);
-      if (Array.isArray(parsed)) {
+      if (isArray(parsed)) {
         return parsed.map((s) => String(s).trim()).filter(Boolean);
       }
     } catch (_e) {
@@ -58,12 +59,22 @@ function parseFragmentInputAttr(raw) {
   if (!trimmed) return {};
   try {
     const parsed = JSON.parse(trimmed);
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    return parsed && typeof parsed === 'object' && !isArray(parsed) ? parsed : {};
   } catch (_e) {
     return {};
   }
 }
 
+function isStrictAncestor(parentEl, childEl) {
+  return Boolean(
+    parentEl &&
+      childEl &&
+      parentEl !== childEl &&
+      typeof parentEl.contains === 'function' &&
+      parentEl.contains(childEl)
+  );
+}
+
 /**
  * Filter a list of fragment records so that if fragment B's DOM element is inside
  * fragment A's DOM subtree, B is omitted from the batch because refreshing A will
@@ -78,7 +89,7 @@ function deduplicateParentChildFragments(candidates) {
     if (!candidate.el) return true;
     for (const other of candidates) {
       if (other === candidate || !other.el) continue;
-      if (other.el !== candidate.el && typeof other.el.contains === 'function' && other.el.contains(candidate.el)) {
+      if (isStrictAncestor(other.el, candidate.el)) {
         return false;
       }
     }
@@ -108,9 +119,24 @@ function createFragmentCoordinator(options = {}) {
   const endpoint = options.endpoint || DEFAULT_FRAGMENT_ENDPOINT;
   const datastar = options.datastar || options.adapter;
   const debug = options.debug || null;
-  const defaultTimeout = typeof options.timeout === 'number' ? options.timeout : 15000;
-
-  // Map<instanceId, { instanceId, name, pagePath, input, dependsOn: Set<string>, version: number, el: Element, abortController: AbortController|null }>
+  const defaultTimeout = isNumber(options.timeout) ? options.timeout : 15000;
+
+  // React Query-style automatic revalidation defaults
+  const defaultStaleTime = parseDurationMs(options.staleTime, 0);
+  const defaultRefetchOnWindowFocus = parseRefetchMode(
+    options.refetchOnWindowFocus !== undefined ? options.refetchOnWindowFocus : options.refetchOnFocus,
+    false
+  );
+  const defaultRefetchOnReconnect = parseRefetchMode(options.refetchOnReconnect, false);
+  const defaultRefetchOnMount = parseRefetchMode(
+    options.refetchOnMount !== undefined ? options.refetchOnMount : options.refetchOnVisit,
+    false
+  );
+  const defaultRefetchInterval = parseDurationMs(options.refetchInterval, 0);
+  const defaultRefetchIntervalInBackground =
+    parseRefetchMode(options.refetchIntervalInBackground, false) === true;
+
+  // Map<instanceId, { instanceId, name, pagePath, input, dependsOn: Set<string>, version: number, el: Element, abortController: AbortController|null, ... }>
   const instances = new Map();
 
   // Coalescing & in-flight state for tag invalidations
@@ -122,91 +148,416 @@ function createFragmentCoordinator(options = {}) {
   let lastFailedBatch = null;
   const inflightBatchWaiters = [];
 
-  /**
-   * Scan DOM and synchronize tracked `[data-w-fragment]` instances.
-   */
-  function syncDomInstances(containerEl) {
-    const root = containerEl || getRoot();
-    if (!root || typeof root.querySelectorAll !== 'function') return [];
+  // Automatic refetch (focus / reconnect / mount / interval) state
+  const pendingAutoInstanceIds = new Set();
+  const pendingAutoReasons = new Set();
+  let autoBatchScheduled = false;
+  let autoBatchTimer = null;
+  let focusDebounceTimer = null;
+  let isDisposed = false;
+  let lifecycleListenersAttached = false;
+
+  function isDocumentHidden() {
+    const root = getRoot();
+    const doc = root && root.nodeType === 9 ? root : root && root.ownerDocument ? root.ownerDocument : typeof document !== 'undefined' ? document : null;
+    return Boolean(doc && doc.visibilityState === 'hidden');
+  }
 
-    const elements = Array.from(root.querySelectorAll('[data-w-fragment]'));
-    if (root.nodeType === 1 && root.hasAttribute && root.hasAttribute('data-w-fragment')) {
-      elements.unshift(root);
-    }
-
-    const seenIds = new Set();
-
-    for (let i = 0; i < elements.length; i++) {
-      const el = elements[i];
-      const name = (el.getAttribute('data-w-fragment') || '').trim();
-      if (!name) continue;
-
-      let instanceId = (el.getAttribute('data-w-fragment-id') || '').trim();
-      if (!instanceId) {
-        instanceId = i === 0 ? `${name}:default` : `${name}:${i}`;
-        el.setAttribute('data-w-fragment-id', instanceId);
-      }
-
-      seenIds.add(instanceId);
-      const pagePath =
-        (el.getAttribute('data-w-fragment-page') || '').trim() ||
-        (typeof window !== 'undefined' && window.location ? window.location.pathname : '/');
-      const input = parseFragmentInputAttr(el.getAttribute('data-w-fragment-input'));
-      const dependsOn = new Set(parseDependsOnAttr(el.getAttribute('data-w-depends-on')));
-
-      // Fragment input persistence setup
-      const rawPersistInput =
-        el.getAttribute('data-w-persist-input') ||
-        (el.getAttribute('data-w-persist') === 'input' ? 'session' : null);
-      const isInputPersistEnabled = Boolean(rawPersistInput && rawPersistInput !== 'false');
-      const inputStorageType = rawPersistInput && rawPersistInput.toLowerCase() === 'local' ? 'local' : 'session';
-      const inputStorageKey =
-        el.getAttribute('data-w-persist-key') ||
-        el.getAttribute('data-w-input-key') ||
-        `frag_input:${name}`;
-
-      let effectiveInput = input;
-      if (isInputPersistEnabled) {
-        const store = inputStorageType === 'local' ? defaultStorage.local : defaultStorage.session;
-        if (!el.hasAttribute('data-w-fragment-input') || Object.keys(effectiveInput).length === 0) {
-          const stored = store.get(inputStorageKey, null);
-          if (stored && typeof stored === 'object' && !Array.isArray(stored)) {
-            effectiveInput = stored;
-          }
+  function isInstanceStale(inst, mode) {
+    if (!inst || !mode) return false;
+    if (mode === 'always') return true;
+    const staleMs = isNumber(inst.staleTime) ? inst.staleTime : 0;
+    if (staleMs <= 0) return true;
+    const elapsed = Date.now() - (inst.lastUpdatedAt || 0);
+    return elapsed >= staleMs;
+  }
+
+  function clearInstanceInterval(inst) {
+    if (inst && inst.intervalTimer) {
+      clearInterval(inst.intervalTimer);
+      inst.intervalTimer = null;
+      inst.activeIntervalMs = 0;
+    }
+  }
+
+  function syncInstanceInterval(inst) {
+    if (!inst || isDisposed) return;
+    const targetMs = isNumber(inst.refetchInterval) && inst.refetchInterval > 0 ? inst.refetchInterval : 0;
+    if (targetMs <= 0) {
+      clearInstanceInterval(inst);
+      return;
+    }
+    if (inst.intervalTimer && inst.activeIntervalMs === targetMs) {
+      return;
+    }
+    clearInstanceInterval(inst);
+    inst.activeIntervalMs = targetMs;
+    inst.intervalTimer = setInterval(() => {
+      if (isDisposed || !inst.el || inst.el.isConnected === false) {
+        clearInstanceInterval(inst);
+        return;
+      }
+      if (!inst.refetchIntervalInBackground && isDocumentHidden()) {
+        return;
+      }
+      scheduleAutoRefresh([inst.instanceId], 'interval');
+    }, targetMs);
+    if (inst.intervalTimer && typeof inst.intervalTimer.unref === 'function') {
+      inst.intervalTimer.unref();
+    }
+  }
+
+  async function flushAutoRefresh() {
+    autoBatchScheduled = false;
+    if (autoBatchTimer) {
+      clearTimeout(autoBatchTimer);
+      autoBatchTimer = null;
+    }
+    if (isDisposed || pendingAutoInstanceIds.size === 0) return;
+    const idsToRefresh = Array.from(pendingAutoInstanceIds);
+    const reasons = Array.from(pendingAutoReasons);
+    pendingAutoInstanceIds.clear();
+    pendingAutoReasons.clear();
+
+    // Skip background auto-refresh if a mutation invalidation batch is currently in flight
+    if (inFlightBatchCount > 0) return;
+
+    const candidates = [];
+    for (const id of idsToRefresh) {
+      const inst = instances.get(id);
+      if (
+        inst &&
+        inst.el &&
+        inst.el.isConnected !== false &&
+        !inst.abortController &&
+        !(inst.inFlightCount > 0)
+      ) {
+        candidates.push(inst);
+      }
+    }
+    if (candidates.length === 0) return;
+
+    const deduped = deduplicateParentChildFragments(candidates);
+    const targets = deduped.map((inst) => {
+      inst.version += 1;
+      return {
+        instanceId: inst.instanceId,
+        name: inst.name,
+        pagePath: inst.pagePath,
+        input: { ...inst.input },
+        reqVersion: inst.version,
+      };
+    });
+
+    if (debug && typeof debug.recordEvent === 'function') {
+      debug.recordEvent('fragment:auto-refetch', {
+        reason: reasons.length === 1 ? reasons[0] : reasons.join('+'),
+        reasons,
+        fragments: targets.map((t) => t.instanceId),
+      });
+    }
+
+    try {
+      await executeBatchRefresh(targets);
+    } catch (_err) {
+      // Background auto-refetch errors are non-fatal
+    }
+  }
+
+  function scheduleAutoRefresh(instanceIds, reason = 'auto') {
+    if (isDisposed || !isArray(instanceIds) || instanceIds.length === 0) return;
+    for (const id of instanceIds) {
+      if (id) pendingAutoInstanceIds.add(id);
+    }
+    if (reason) pendingAutoReasons.add(reason);
+    if (pendingAutoInstanceIds.size === 0) return;
+
+    if (reason === 'mount') {
+      if (!autoBatchScheduled) {
+        autoBatchScheduled = true;
+        Promise.resolve().then(flushAutoRefresh);
+      }
+      return;
+    }
+
+    if (autoBatchTimer || autoBatchScheduled) return;
+    autoBatchTimer = setTimeout(flushAutoRefresh, 5);
+  }
+
+  function triggerFocusRefetch() {
+    if (isDisposed || isDocumentHidden()) return;
+    scanDomInstances();
+    const matchedIds = [];
+    for (const inst of instances.values()) {
+      if (isInstanceStale(inst, inst.refetchOnWindowFocus)) {
+        matchedIds.push(inst.instanceId);
+      }
+    }
+    if (matchedIds.length > 0) {
+      scheduleAutoRefresh(matchedIds, 'window-focus');
+    }
+  }
+
+  function triggerReconnectRefetch() {
+    if (isDisposed) return;
+    scanDomInstances();
+    const matchedIds = [];
+    for (const inst of instances.values()) {
+      if (isInstanceStale(inst, inst.refetchOnReconnect)) {
+        matchedIds.push(inst.instanceId);
+      }
+    }
+    if (matchedIds.length > 0) {
+      scheduleAutoRefresh(matchedIds, 'reconnect');
+    }
+  }
+
+  function onVisibilityChange() {
+    if (!isDocumentHidden()) {
+      triggerFocusRefetch();
+    }
+  }
+
+  function onPageShow(event) {
+    if (isDisposed) return;
+    if (event && event.persisted) {
+      scanDomInstances();
+      const matchedIds = [];
+      for (const inst of instances.values()) {
+        const mode = inst.refetchOnMount || inst.refetchOnWindowFocus;
+        if (isInstanceStale(inst, mode)) {
+          matchedIds.push(inst.instanceId);
         }
       }
+      if (matchedIds.length > 0) {
+        scheduleAutoRefresh(matchedIds, 'pageshow');
+      }
+    }
+  }
+
+  function ensureLifecycleListeners() {
+    if (lifecycleListenersAttached || isDisposed) return;
+    const root = getRoot();
+    const doc = root && root.nodeType === 9 ? root : root && root.ownerDocument ? root.ownerDocument : typeof document !== 'undefined' ? document : null;
+    const win = (doc && doc.defaultView) || (typeof window !== 'undefined' ? window : null);
+
+    if (doc && typeof doc.addEventListener === 'function') {
+      doc.addEventListener('visibilitychange', onVisibilityChange);
+    }
+    if (win && typeof win.addEventListener === 'function') {
+      win.addEventListener('focus', triggerFocusRefetch);
+      win.addEventListener('online', triggerReconnectRefetch);
+      win.addEventListener('pageshow', onPageShow);
+    }
+    lifecycleListenersAttached = true;
+  }
+
+  function removeLifecycleListeners() {
+    if (!lifecycleListenersAttached) return;
+    const root = getRoot();
+    const doc = root && root.nodeType === 9 ? root : root && root.ownerDocument ? root.ownerDocument : typeof document !== 'undefined' ? document : null;
+    const win = (doc && doc.defaultView) || (typeof window !== 'undefined' ? window : null);
+
+    if (doc && typeof doc.removeEventListener === 'function') {
+      doc.removeEventListener('visibilitychange', onVisibilityChange);
+    }
+    if (win && typeof win.removeEventListener === 'function') {
+      win.removeEventListener('focus', triggerFocusRefetch);
+      win.removeEventListener('online', triggerReconnectRefetch);
+      win.removeEventListener('pageshow', onPageShow);
+    }
+    lifecycleListenersAttached = false;
+  }
+
+  function syncSingleElement(el, index, seenIds) {
+    const name = (el.getAttribute('data-w-fragment') || '').trim();
+    if (!name) return;
+
+    let instanceId = (el.getAttribute('data-w-fragment-id') || '').trim();
+    if (!instanceId) {
+      instanceId = index === 0 ? `${name}:default` : `${name}:${index}`;
+      el.setAttribute('data-w-fragment-id', instanceId);
+    }
+
+    if (seenIds) seenIds.add(instanceId);
+
+    const existing = instances.get(instanceId);
+    const rawInput = el.getAttribute('data-w-fragment-input');
+    const rawDepends = el.getAttribute('data-w-depends-on');
+    const rawStale = el.getAttribute('data-w-stale-time');
+    const rawInterval = el.getAttribute('data-w-refetch-interval');
+
+    // Fast-path: if the same DOM element is already registered and its reactive attributes are unchanged,
+    // skip JSON.parse, Set allocation, storage lookup, and timer reconfiguration.
+    if (
+      existing &&
+      existing.el === el &&
+      existing.name === name &&
+      existing._rawInput === rawInput &&
+      existing._rawDepends === rawDepends &&
+      existing._rawStale === rawStale &&
+      existing._rawInterval === rawInterval
+    ) {
+      return;
+    }
 
-      const existing = instances.get(instanceId);
-      if (existing) {
-        existing.name = name;
-        existing.pagePath = pagePath;
-        existing.el = el;
-        existing.dependsOn = dependsOn;
-        if (el.hasAttribute('data-w-fragment-input') || isInputPersistEnabled) {
-          existing.input = effectiveInput;
+    const pagePath =
+      (el.getAttribute('data-w-fragment-page') || '').trim() ||
+      (typeof window !== 'undefined' && window.location ? window.location.pathname : '/');
+    const input =
+      existing && existing.el === el && existing._rawInput === rawInput
+        ? existing.input
+        : parseFragmentInputAttr(rawInput);
+    const dependsOn =
+      existing && existing.el === el && existing._rawDepends === rawDepends
+        ? existing.dependsOn
+        : new Set(parseDependsOnAttr(rawDepends));
+
+    // Fragment input persistence setup
+    const rawPersistInput =
+      el.getAttribute('data-w-persist-input') ||
+      (el.getAttribute('data-w-persist') === 'input' ? 'session' : null);
+    const isInputPersistEnabled = Boolean(rawPersistInput && rawPersistInput !== 'false');
+    const inputStorageType = rawPersistInput && rawPersistInput.toLowerCase() === 'local' ? 'local' : 'session';
+    const inputStorageKey =
+      el.getAttribute('data-w-persist-key') ||
+      el.getAttribute('data-w-input-key') ||
+      `frag_input:${name}`;
+
+    let effectiveInput = input;
+    let pendingRestoredInput = null;
+    if (!existing && isInputPersistEnabled) {
+      const store = inputStorageType === 'local' ? defaultStorage.local : defaultStorage.session;
+      let stored = store.get(inputStorageKey, null);
+      if (
+        (!stored || typeof stored !== 'object' || isArray(stored)) &&
+        inputStorageKey !== `frag_input:${instanceId}`
+      ) {
+        stored = store.get(`frag_input:${instanceId}`, null);
+      }
+      if (stored && typeof stored === 'object' && !isArray(stored)) {
+        if (rawInput === null || Object.keys(effectiveInput).length === 0) {
+          effectiveInput = { ...stored };
+        } else if (JSON.stringify(stored) !== JSON.stringify(effectiveInput)) {
+          pendingRestoredInput = { ...stored };
         }
-        existing.persistInput = isInputPersistEnabled ? { type: inputStorageType, key: inputStorageKey } : null;
-      } else {
-        instances.set(instanceId, {
-          instanceId,
-          name,
-          pagePath,
-          input: effectiveInput,
-          dependsOn,
-          version: 0,
-          el,
-          abortController: null,
-          persistInput: isInputPersistEnabled ? { type: inputStorageType, key: inputStorageKey } : null,
+      }
+    }
+
+    // Parse React Query-style automatic revalidation attributes
+    const staleTime = parseDurationMs(rawStale, defaultStaleTime);
+    const rawFocusAttr =
+      el.getAttribute('data-w-refetch-on-focus') ??
+      el.getAttribute('data-w-refetch-on-window-focus');
+    const refetchOnWindowFocus = parseRefetchMode(rawFocusAttr, defaultRefetchOnWindowFocus);
+    const refetchOnReconnect = parseRefetchMode(
+      el.getAttribute('data-w-refetch-on-reconnect'),
+      defaultRefetchOnReconnect
+    );
+    const rawMountAttr =
+      el.getAttribute('data-w-refetch-on-mount') ??
+      el.getAttribute('data-w-refetch-on-visit');
+    const refetchOnMount = parseRefetchMode(rawMountAttr, defaultRefetchOnMount);
+    const refetchInterval = parseDurationMs(rawInterval, defaultRefetchInterval);
+    const refetchIntervalInBackground =
+      parseRefetchMode(
+        el.getAttribute('data-w-refetch-in-background'),
+        defaultRefetchIntervalInBackground
+      ) === true;
+
+    if (refetchOnWindowFocus || refetchOnReconnect || refetchOnMount) {
+      ensureLifecycleListeners();
+    }
+
+    if (existing) {
+      existing.name = name;
+      existing.pagePath = pagePath;
+      existing.el = el;
+      existing.dependsOn = dependsOn;
+      if (rawInput !== null && rawInput !== existing._rawInput) {
+        existing.input = input;
+      }
+      existing.persistInput = isInputPersistEnabled ? { type: inputStorageType, key: inputStorageKey } : null;
+      existing.staleTime = staleTime;
+      existing.refetchOnWindowFocus = refetchOnWindowFocus;
+      existing.refetchOnReconnect = refetchOnReconnect;
+      existing.refetchOnMount = refetchOnMount;
+      existing.refetchInterval = refetchInterval;
+      existing.refetchIntervalInBackground = refetchIntervalInBackground;
+      existing._rawInput = rawInput;
+      existing._rawDepends = rawDepends;
+      existing._rawStale = rawStale;
+      existing._rawInterval = rawInterval;
+      syncInstanceInterval(existing);
+    } else {
+      const created = {
+        instanceId,
+        name,
+        pagePath,
+        input: effectiveInput,
+        restoredInput: pendingRestoredInput,
+        dependsOn,
+        version: 0,
+        el,
+        abortController: null,
+        inFlightCount: 0,
+        persistInput: isInputPersistEnabled ? { type: inputStorageType, key: inputStorageKey } : null,
+        lastUpdatedAt: Date.now(),
+        staleTime,
+        refetchOnWindowFocus,
+        refetchOnReconnect,
+        refetchOnMount,
+        refetchInterval,
+        refetchIntervalInBackground,
+        intervalTimer: null,
+        activeIntervalMs: 0,
+        _rawInput: rawInput,
+        _rawDepends: rawDepends,
+        _rawStale: rawStale,
+        _rawInterval: rawInterval,
+      };
+      instances.set(instanceId, created);
+      syncInstanceInterval(created);
+      if (pendingRestoredInput) {
+        Promise.resolve().then(() => {
+          if (!isDisposed && created.version === 0 && instances.get(instanceId) === created) {
+            refresh(instanceId, pendingRestoredInput).catch(() => {});
+          }
         });
+      } else if (refetchOnMount === 'always' || (refetchOnMount === true && staleTime <= 0)) {
+        scheduleAutoRefresh([instanceId], 'mount');
       }
     }
+  }
+
+  /**
+   * Internal DOM scan without allocating a return array.
+   */
+  function scanDomInstances(containerEl) {
+    const defaultRoot = getRoot();
+    const root = containerEl || defaultRoot;
+    if (!root || typeof root.querySelectorAll !== 'function') return;
+
+    const isFullScan = !containerEl || containerEl === defaultRoot;
+    const seenIds = isFullScan ? new Set() : null;
+    const nodeList = root.querySelectorAll('[data-w-fragment]');
+    let idx = 0;
+
+    if (root.nodeType === 1 && root.hasAttribute && root.hasAttribute('data-w-fragment')) {
+      syncSingleElement(root, idx++, seenIds);
+    }
+
+    for (let i = 0, len = nodeList.length; i < len; i++) {
+      syncSingleElement(nodeList[i], idx++, seenIds);
+    }
 
     // Prune disconnected instances if scanning full root
-    if (!containerEl || containerEl === getRoot()) {
+    if (isFullScan) {
       for (const [id, inst] of instances.entries()) {
         const disconnected =
           !seenIds.has(id) || (inst.el && inst.el.isConnected === false);
         if (disconnected) {
+          clearInstanceInterval(inst);
           if (inst.abortController) {
             try {
               inst.abortController.abort();
@@ -218,7 +569,13 @@ function createFragmentCoordinator(options = {}) {
         }
       }
     }
+  }
 
+  /**
+   * Scan DOM and synchronize tracked `[data-w-fragment]` instances.
+   */
+  function syncDomInstances(containerEl) {
+    scanDomInstances(containerEl);
     return Array.from(instances.values());
   }
 
@@ -226,7 +583,7 @@ function createFragmentCoordinator(options = {}) {
    * Apply a single server fragment result `{ instanceId, name, html, input, loadMs, renderMs }`
    * to the DOM if and only if `reqVersion >= inst.version`.
    */
-  function applyFragmentPatch(inst, fragmentPayload, reqVersion, chainId = null) {
+  function applyFragmentPatch(inst, fragmentPayload, reqVersion, chainId = null, requestedInput = null) {
     if (!inst || !inst.el) return false;
 
     if (reqVersion < inst.version) {
@@ -248,17 +605,27 @@ function createFragmentCoordinator(options = {}) {
 
     const patchStart = Date.now();
 
+    const committedInput =
+      fragmentPayload.input && typeof fragmentPayload.input === 'object' && !isArray(fragmentPayload.input)
+        ? fragmentPayload.input
+        : requestedInput && typeof requestedInput === 'object' && !isArray(requestedInput)
+          ? requestedInput
+          : null;
+
     if (
-      fragmentPayload.input &&
-      typeof fragmentPayload.input === 'object' &&
+      committedInput &&
       !followUpNeeded &&
       pendingTags.size === 0
     ) {
-      inst.input = fragmentPayload.input;
-      inst.el.setAttribute('data-w-fragment-input', JSON.stringify(fragmentPayload.input));
+      inst.input = { ...committedInput };
+      const serializedInput = JSON.stringify(inst.input);
+      if (inst.el && typeof inst.el.setAttribute === 'function') {
+        inst.el.setAttribute('data-w-fragment-input', serializedInput);
+      }
+      inst._rawInput = serializedInput;
       if (inst.persistInput) {
         const store = inst.persistInput.type === 'local' ? defaultStorage.local : defaultStorage.session;
-        store.set(inst.persistInput.key, fragmentPayload.input);
+        store.set(inst.persistInput.key, inst.input);
       }
     }
 
@@ -272,9 +639,16 @@ function createFragmentCoordinator(options = {}) {
     }
 
     const patchMs = Math.max(0, Date.now() - patchStart);
+    const now = Date.now();
+    inst.lastUpdatedAt = now;
 
     // Re-sync nested fragment instances that may have been updated inside this parent fragment
-    syncDomInstances(inst.el);
+    scanDomInstances(inst.el);
+    for (const otherInst of instances.values()) {
+      if (otherInst !== inst && otherInst.el && isStrictAncestor(inst.el, otherInst.el)) {
+        otherInst.lastUpdatedAt = now;
+      }
+    }
 
     if (typeof options.onAfterPatch === 'function') {
       options.onAfterPatch(inst.el, inst);
@@ -321,6 +695,26 @@ function createFragmentCoordinator(options = {}) {
       targets[0].pagePath ||
       (typeof window !== 'undefined' && window.location ? window.location.pathname : '/');
 
+    // Collect active inputs of any nested descendant fragments inside the requested parent targets
+    // so server-side parent re-rendering preserves nested child filters & pagination.
+    const childInputs = {};
+    let hasChildInputs = false;
+    for (const t of targets) {
+      const parentInst = instances.get(t.instanceId);
+      if (!parentInst || !parentInst.el) continue;
+      for (const otherInst of instances.values()) {
+        if (otherInst !== parentInst && otherInst.el && isStrictAncestor(parentInst.el, otherInst.el)) {
+          if (otherInst.input && typeof otherInst.input === 'object') {
+            childInputs[otherInst.instanceId] = { ...otherInst.input };
+            if (!childInputs[otherInst.name]) {
+              childInputs[otherInst.name] = { ...otherInst.input };
+            }
+            hasChildInputs = true;
+          }
+        }
+      }
+    }
+
     const requestPayload = {
       pagePath,
       fragments: targets.map((t) => ({
@@ -329,9 +723,32 @@ function createFragmentCoordinator(options = {}) {
         input: t.input || {},
         version: t.reqVersion,
       })),
+      ...(hasChildInputs ? { childInputs } : {}),
+    };
+
+    for (const t of targets) {
+      const inst = instances.get(t.instanceId);
+      if (inst) {
+        inst.inFlightCount = (inst.inFlightCount || 0) + 1;
+        if (inst.el && typeof inst.el.setAttribute === 'function') {
+          inst.el.setAttribute('aria-busy', 'true');
+        }
+      }
+    }
+
+    const decrementTargetBusy = () => {
+      for (const t of targets) {
+        const inst = instances.get(t.instanceId);
+        if (inst) {
+          inst.inFlightCount = Math.max(0, (inst.inFlightCount || 1) - 1);
+          if (inst.inFlightCount === 0 && inst.el && typeof inst.el.removeAttribute === 'function') {
+            inst.el.removeAttribute('aria-busy');
+          }
+        }
+      }
     };
 
-    const reqId = `frag_req_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+    const reqId = uid('frag_req', 4);
     if (debug) {
       debug.trackRequestStart({
         requestId: reqId,
@@ -346,7 +763,7 @@ function createFragmentCoordinator(options = {}) {
     const batchAbortController = new AbortController();
     let timeoutTimer = null;
     let timedOut = false;
-    const timeoutMs = typeof batchTimeout === 'number' ? batchTimeout : defaultTimeout;
+    const timeoutMs = isNumber(batchTimeout) ? batchTimeout : defaultTimeout;
 
     if (timeoutMs > 0) {
       timeoutTimer = setTimeout(() => {
@@ -374,6 +791,7 @@ function createFragmentCoordinator(options = {}) {
         signal: batchAbortController.signal,
       });
     } catch (err) {
+      decrementTargetBusy();
       if (timeoutTimer) {
         clearTimeout(timeoutTimer);
         timeoutTimer = null;
@@ -454,6 +872,8 @@ function createFragmentCoordinator(options = {}) {
       }
     } catch (_e) {
       body = null;
+    } finally {
+      decrementTargetBusy();
     }
 
     if (!response.ok) {
@@ -489,8 +909,20 @@ function createFragmentCoordinator(options = {}) {
     }
 
     lastFailedBatch = null;
-    const resultsMap = (body && body.fragments) || {};
+    const rawFragments = (body && body.fragments) || {};
+    const resultsMap = {};
+    if (isArray(rawFragments)) {
+      for (const item of rawFragments) {
+        if (item && typeof item === 'object') {
+          if (item.instanceId) resultsMap[item.instanceId] = item;
+          if (item.name && !resultsMap[item.name]) resultsMap[item.name] = item;
+        }
+      }
+    } else if (rawFragments && typeof rawFragments === 'object') {
+      Object.assign(resultsMap, rawFragments);
+    }
     const refreshedIds = [];
+    let staleDiscardCount = 0;
     let totalLoadMs = 0;
     let totalRenderMs = 0;
 
@@ -498,32 +930,53 @@ function createFragmentCoordinator(options = {}) {
       const inst = instances.get(target.instanceId);
       const fragResult = resultsMap[target.instanceId] || resultsMap[target.name];
       if (!inst || !fragResult) continue;
-      if (typeof fragResult.loadMs === 'number') totalLoadMs += fragResult.loadMs;
-      if (typeof fragResult.renderMs === 'number') totalRenderMs += fragResult.renderMs;
+      if (target.reqVersion < inst.version) {
+        staleDiscardCount += 1;
+      }
+      if (isNumber(fragResult.loadMs)) totalLoadMs += fragResult.loadMs;
+      if (isNumber(fragResult.renderMs)) totalRenderMs += fragResult.renderMs;
 
       const applied = applyFragmentPatch(
         inst,
         fragResult,
         target.reqVersion,
-        chainIds[0] || null
+        chainIds[0] || null,
+        target.input
       );
       if (applied) {
         refreshedIds.push(target.instanceId);
       }
     }
 
+    const allSuperseded =
+      refreshedIds.length === 0 && staleDiscardCount > 0 && staleDiscardCount === targets.length;
+
     for (const cid of chainIds) {
       if (debug) {
         debug.recordChainRefresh(cid, {
           fragmentIds: refreshedIds,
-          status: 'ok',
+          status: allSuperseded ? 'superseded' : 'ok',
           loadMs: totalLoadMs,
           renderMs: totalRenderMs,
-          totalServerMs: body && typeof body.totalMs === 'number' ? body.totalMs : null,
+          totalServerMs: body && isNumber(body.totalMs) ? body.totalMs : null,
         });
       }
     }
 
+    if (allSuperseded) {
+      return {
+        ok: false,
+        canceled: true,
+        superseded: true,
+        refreshed: [],
+        errors: [],
+        timings: {
+          loadMs: totalLoadMs,
+          renderMs: totalRenderMs,
+        },
+      };
+    }
+
     return {
       ok: true,
       refreshed: refreshedIds,
@@ -557,7 +1010,7 @@ function createFragmentCoordinator(options = {}) {
     pendingTags.clear();
     pendingChains.length = 0;
 
-    syncDomInstances();
+    scanDomInstances();
 
     // Find all mounted fragment instances whose `dependsOn` intersects `tagsToFlush`
     const matchingInstances = [];
@@ -636,7 +1089,7 @@ function createFragmentCoordinator(options = {}) {
    * @returns {Promise<{ refreshed: string[], skipped?: boolean }>}
    */
   function invalidate(tags, meta = {}) {
-    const tagList = Array.isArray(tags) ? tags : [tags];
+    const tagList = isArray(tags) ? tags : [tags];
     for (const raw of tagList) {
       if (typeof raw === 'string' && raw.trim()) {
         pendingTags.add(raw.trim());
@@ -685,7 +1138,7 @@ function createFragmentCoordinator(options = {}) {
    * @param {object} [refreshOpts]
    */
   async function refresh(idOrName, nextInput, refreshOpts = {}) {
-    syncDomInstances();
+    scanDomInstances();
 
     const matched = [];
     if (instances.has(idOrName)) {
@@ -726,32 +1179,35 @@ function createFragmentCoordinator(options = {}) {
       inst.abortController = abortController;
       inst.version += 1;
 
-      if (nextInput && typeof nextInput === 'object') {
-        inst.input = refreshOpts.replaceInput
-          ? { ...nextInput }
-          : { ...inst.input, ...nextInput };
-        if (inst.el && typeof inst.el.setAttribute === 'function') {
-          inst.el.setAttribute('data-w-fragment-input', JSON.stringify(inst.input));
-        }
-        if (inst.persistInput) {
-          const store = inst.persistInput.type === 'local' ? defaultStorage.local : defaultStorage.session;
-          store.set(inst.persistInput.key, inst.input);
-        }
-      }
+      const candidateInput =
+        nextInput && typeof nextInput === 'object'
+          ? refreshOpts.replaceInput
+            ? { ...nextInput }
+            : { ...inst.input, ...nextInput }
+          : { ...inst.input };
 
       return {
         instanceId: inst.instanceId,
         name: inst.name,
         pagePath: inst.pagePath,
-        input: { ...inst.input },
+        input: candidateInput,
         reqVersion: inst.version,
       };
     });
 
+    const clearOwnedAbortControllers = () => {
+      for (const inst of deduped) {
+        if (inst.abortController === abortController) {
+          inst.abortController = null;
+        }
+      }
+    };
+
     try {
       const result = await executeBatchRefresh(targets, [], abortController.signal, refreshOpts.timeout);
+      clearOwnedAbortControllers();
       const enrichedResult = { ok: true, ...result };
-      if (!enrichedResult.canceled && enrichedResult.ok !== false) {
+      if (!enrichedResult.canceled && !enrichedResult.superseded && enrichedResult.ok !== false) {
         if (typeof refreshOpts.onSuccess === 'function') {
           await refreshOpts.onSuccess(enrichedResult);
         }
@@ -763,6 +1219,7 @@ function createFragmentCoordinator(options = {}) {
       }
       return enrichedResult;
     } catch (err) {
+      clearOwnedAbortControllers();
       const failHandler = refreshOpts.onFailure || refreshOpts.onError;
       if (typeof failHandler === 'function') {
         try {
@@ -807,7 +1264,7 @@ function createFragmentCoordinator(options = {}) {
         inst.version += 1;
         retryTargets.push({
           ...t,
-          input: { ...inst.input },
+          input: t.input ? { ...t.input } : { ...inst.input },
           reqVersion: inst.version,
         });
       }
@@ -825,10 +1282,10 @@ function createFragmentCoordinator(options = {}) {
     invalidate,
     refresh,
     refreshFragments(items = []) {
-      if (!Array.isArray(items) || items.length === 0) {
+      if (!isArray(items) || items.length === 0) {
         return Promise.resolve({ refreshed: [], skipped: true });
       }
-      syncDomInstances();
+      scanDomInstances();
       for (const item of items) {
         const key = item.instanceId || item.name;
         const inst = instances.get(key) || Array.from(instances.values()).find((i) => i.name === key);
@@ -836,7 +1293,9 @@ function createFragmentCoordinator(options = {}) {
           if (item.input && typeof item.input === 'object') {
             inst.input = { ...item.input };
             if (inst.el && typeof inst.el.setAttribute === 'function') {
-              inst.el.setAttribute('data-w-fragment-input', JSON.stringify(inst.input));
+              const serializedInput = JSON.stringify(inst.input);
+              inst.el.setAttribute('data-w-fragment-input', serializedInput);
+              inst._rawInput = serializedInput;
             }
           }
           pendingTags.add(inst.name);
@@ -847,8 +1306,8 @@ function createFragmentCoordinator(options = {}) {
       return flushInvalidations();
     },
     findFragmentsByTags(tags = []) {
-      syncDomInstances();
-      const tagSet = new Set((Array.isArray(tags) ? tags : [tags]).map((t) => String(t || '').trim()).filter(Boolean));
+      scanDomInstances();
+      const tagSet = new Set((isArray(tags) ? tags : [tags]).map((t) => String(t || '').trim()).filter(Boolean));
       const matching = [];
       for (const inst of instances.values()) {
         for (const t of tagSet) {
@@ -863,24 +1322,63 @@ function createFragmentCoordinator(options = {}) {
     retryFailed,
     retryLastFailed: retryFailed,
     getInstance(instanceId) {
-      syncDomInstances();
+      const hit = instances.get(instanceId);
+      if (hit && (!hit.el || hit.el.isConnected !== false)) {
+        return hit;
+      }
+      scanDomInstances();
       return instances.get(instanceId) || null;
     },
     getInstances() {
-      syncDomInstances();
+      scanDomInstances();
       return Array.from(instances.values());
     },
     getStoredInput(instanceIdOrName, storageType = 'session') {
       const store = storageType === 'local' ? defaultStorage.local : defaultStorage.session;
-      return store.get(`frag_input:${instanceIdOrName}`, null);
+      const direct = store.get(`frag_input:${instanceIdOrName}`, null);
+      if (direct !== null) return direct;
+      const inst = instances.get(instanceIdOrName) || Array.from(instances.values()).find((i) => i.name === instanceIdOrName);
+      if (inst && inst.persistInput) {
+        const instStore = inst.persistInput.type === 'local' ? defaultStorage.local : defaultStorage.session;
+        return instStore.get(inst.persistInput.key, null);
+      }
+      return null;
     },
     clearStoredInput(instanceIdOrName, storageType = 'session') {
       const store = storageType === 'local' ? defaultStorage.local : defaultStorage.session;
+      const inst = instances.get(instanceIdOrName) || Array.from(instances.values()).find((i) => i.name === instanceIdOrName);
+      if (inst && inst.persistInput) {
+        const instStore = inst.persistInput.type === 'local' ? defaultStorage.local : defaultStorage.session;
+        instStore.remove(inst.persistInput.key);
+      }
       return store.remove(`frag_input:${instanceIdOrName}`);
     },
     get hasFailedRefresh() {
       return Boolean(lastFailedBatch);
     },
+    dispose() {
+      isDisposed = true;
+      if (focusDebounceTimer) {
+        clearTimeout(focusDebounceTimer);
+        focusDebounceTimer = null;
+      }
+      if (autoBatchTimer) {
+        clearTimeout(autoBatchTimer);
+        autoBatchTimer = null;
+      }
+      pendingAutoInstanceIds.clear();
+      pendingAutoReasons.clear();
+      removeLifecycleListeners();
+      for (const inst of instances.values()) {
+        clearInstanceInterval(inst);
+        if (inst.abortController) {
+          try {
+            inst.abortController.abort();
+          } catch (_e) {}
+          inst.abortController = null;
+        }
+      }
+    },
   };
 }